@aragon-agent/cli 0.5.4 → 0.5.8

package/dist/commands/builtins.js

@@ -9,10 +9,13 @@ import { isAbsolute, resolve } from 'node:path';
 import process from 'node:process';
 import { resolveOutputTokens } from '@aragon-agent/core';
 import { clampThinkingLevel, clampTheme, isThemeName, parseMaxTokensInput, DEFAULT_MAX_TOKENS, LEGACY_DARK_THEME, THEME_NAMES, THINKING_LEVELS, } from '../config/schema.js';
+import { TODO_FOLLOW_LIMITS } from '../todo/limits.js';
+import { buildContinuationMessage } from '../todo/follow-through.js';
 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',
@@ -220,6 +223,160 @@ const COMMANDS = [
             ctx.notify('warn', `Unknown argument "${verb}" - use /team [status|on|off|max <n>].`);
         },
     },
+    {
+        name: 'todo',
+        description: 'Todo planning: status | on | off | panel on|off | follow <mode> | clear | continue',
+        /**
+         * `/todo on` CANNOT turn planning on in a session that started with
+         * `--no-todo`, for the reason `/team on` above records at length: the tool
+         * array is built ONCE and rebuilding it is forbidden (C-1), while
+         * `rebuildSystemPrompt()` IS a live path — so the naive reading produces a
+         * session where the model is told about a `todo_write` that was never
+         * registered.
+         *
+         * TWO CALLS, IN THIS ORDER, FOR BOTH `on|off` AND `panel on|off`, and
+         * neither pair is optional:
+         *
+         *   `setTodoEnabled`  re-splices `<todo_planning>` (P1-1). Without it the
+         *                     block survives `/todo off` and every call comes back
+         *                     refused while the instructions to keep calling are
+         *                     still in the model's context.
+         *   `setTodoConfig`   updates the object `App` reads at RENDER time (P1-2).
+         *                     `persistConfig` only writes the file, so without it
+         *                     `/todo panel off` reports success and changes nothing
+         *                     until the next launch.
+         *   `persistConfig`   is what survives the session, in both cases.
+         */
+        run: (ctx) => {
+            const arg = ctx.args.trim().toLowerCase();
+            const [verb, value] = arg.split(/\s+/, 2);
+            const controller = ctx.controller;
+            if (!verb || verb === 'status') {
+                const snapshot = controller.getTodoSnapshot();
+                const state = !controller.isTodoRegistered()
+                    ? 'off for this session (started with --no-todo)'
+                    : controller.isTodoEnabled()
+                        ? 'on'
+                        : 'off';
+                const todoCfg = controller.getTodoConfig();
+                const panel = todoCfg.panel ? 'on' : 'off';
+                // THE COUNTERS APPEAR ONLY IN `auto` MODE (§4.3): printing `0/25` under
+                // `notify` would advertise a budget nothing is spending.
+                const follow = todoCfg.followThrough === 'auto'
+                    ? `auto (${ctx.followBudget?.used ?? 0}/` +
+                        `${TODO_FOLLOW_LIMITS.maxAutoContinuesPerList} used)`
+                    : todoCfg.followThrough;
+                if (!snapshot) {
+                    ctx.notify('info', `No todo list. Todo planning: ${state}. Panel: ${panel}. ` +
+                        `Follow-through: ${follow}.`);
+                    return;
+                }
+                const active = snapshot.activeIndex >= 0
+                    ? ` In progress: "${snapshot.items[snapshot.activeIndex]?.content ?? ''}".`
+                    : '';
+                ctx.notify('info', `Todos: ${snapshot.doneCount}/${snapshot.total} done.${active} Panel: ${panel}. ` +
+                    `Follow-through: ${follow}.`);
+                return;
+            }
+            if (verb === 'on' || verb === 'off') {
+                const enabled = verb === 'on';
+                // A PARTIAL `todo` section, safe only because `updatePersistedConfig`
+                // deep-merges it — the contract §4.2 spells out in full.
+                ctx.persistConfig({ todo: { enabled } });
+                if (!controller.isTodoRegistered()) {
+                    ctx.notify('info', enabled
+                        ? 'Todo planning is off for this session (started with --no-todo). Saved for next launch.'
+                        : 'Todo planning is already off for this session. Saved for next launch.');
+                    return;
+                }
+                controller.setTodoEnabled(enabled);
+                ctx.toast('success', `Todo planning ${enabled ? 'on' : 'off'}.`);
+                return;
+            }
+            if (verb === 'panel') {
+                if (value !== 'on' && value !== 'off') {
+                    ctx.notify('warn', 'Usage: /todo panel <on|off>');
+                    return;
+                }
+                const panel = value === 'on';
+                controller.setTodoConfig({ panel });
+                ctx.persistConfig({ todo: { panel } });
+                ctx.toast('success', `Todo panel ${panel ? 'on' : 'off'}.`);
+                return;
+            }
+            if (verb === 'follow') {
+                if (value !== 'notify' && value !== 'auto' && value !== 'off') {
+                    ctx.notify('warn', 'Usage: /todo follow <notify|auto|off>');
+                    return;
+                }
+                const followThrough = value;
+                // THE SAME TWO-CALL RULE AS `panel` ABOVE, minus `setTodoEnabled`:
+                // nothing in `<todo_planning>` mentions follow-through (D-3), so
+                // `todoEnabled` has no bearing here.
+                //
+                // `setTodoConfig` REBUILDS THE SYSTEM PROMPT UNCONDITIONALLY
+                // (`controller.ts`), and that is fine and must be left alone: the
+                // rebuild is idempotent for this key (the block does not mention
+                // follow-through, so the output is byte-identical), it costs one string
+                // composition PER COMMAND INVOCATION rather than per turn, and
+                // `setTodoConfig` is the ONLY method that updates the object `App` reads
+                // at decision time. A branch that bypassed it to avoid the rebuild would
+                // trade a free string concatenation for the exact "reports success,
+                // changes nothing" bug the method exists to prevent (P1-1 / P2-10).
+                controller.setTodoConfig({ followThrough });
+                ctx.persistConfig({ todo: { followThrough } });
+                ctx.toast('success', followThrough === 'auto'
+                    ? `Follow-through: auto (up to ${TODO_FOLLOW_LIMITS.maxAutoContinuesPerList} ` +
+                        'continuations per plan).'
+                    : `Follow-through: ${followThrough}.`);
+                return;
+            }
+            if (verb === 'clear') {
+                // REFUSED MID-RUN, which bounds the model/panel disagreement window to
+                // zero (§1.2): between turns the model's next `todo_write` is a full
+                // replacement anyway.
+                if (controller.isRunning()) {
+                    ctx.notify('warn', 'Cannot clear the todo list while a run is in progress.');
+                    return;
+                }
+                if (!controller.getTodoSnapshot()) {
+                    ctx.notify('info', 'No todo list.');
+                    return;
+                }
+                controller.clearTodos();
+                ctx.toast('info', 'Todo list cleared.');
+                return;
+            }
+            if (verb === 'continue') {
+                // REFUSED WHILE RUNNING TOO (P2-7). `ctx.submit` is the App's
+                // `submitMessage`, which routes to `controller.steer()` when the status
+                // is `running` — so the un-refused form would inject "continue the
+                // remaining items" into the run that is already doing exactly that.
+                if (controller.isRunning()) {
+                    ctx.notify('warn', 'Already running.');
+                    return;
+                }
+                const snapshot = controller.getTodoSnapshot();
+                if (!snapshot || snapshot.doneCount >= snapshot.total) {
+                    ctx.notify('info', 'Nothing left to continue.');
+                    return;
+                }
+                // THE SAME FUNCTION THE AUTO PATH USES, which is what keeps the two from
+                // drifting (D-11 / D-12). Round 1's fixed string "Continue with the
+                // remaining todo items." was a REFERENCE to a `todo_write` call that a
+                // long session may have scrolled out of view.
+                //
+                // `{ userInitiated: false }`: the user typed `/todo continue`, which the
+                // slash history already has. Putting this canned paragraph under the
+                // composer's up-arrow as well would be the same event recorded twice, in
+                // the more verbose of the two forms (AC-17).
+                ctx.submit(buildContinuationMessage(snapshot), { userInitiated: false });
+                return;
+            }
+            ctx.notify('warn', `Unknown argument "${verb}" - use ` +
+                '/todo [status|on|off|panel on|off|follow <mode>|clear|continue].');
+        },
+    },
     {
         name: 'expand',
         description: 'Expand / collapse a recent tool card (default: last)',
@@ -296,6 +453,9 @@ const COMMANDS = [
                     },
                     messages: ctx.controller.getMessages(),
                     entries: ctx.state.entries,
+                    // `/resume` restores `messages`, so the belief that justifies the
+                    // panel comes back — and the panel has to come back with it (§3.13).
+                    todos: ctx.controller.getTodoSnapshot()?.items ?? [],
                 });
                 ctx.notify('info', `Saved session to ${path}`);
             }
@@ -312,6 +472,13 @@ const COMMANDS = [
                 const path = resolveSessionPath(ctx.args, ctx.controller.getCwd());
                 const session = loadSession(path);
                 ctx.controller.replaceMessages(session.messages);
+                // IN THE SAME `try`, IMMEDIATELY AFTER `replaceMessages`, so a malformed
+                // file fails the whole resume rather than half of it — and AN ABSENT
+                // `todos` CLEARS RATHER THAN SKIPPING (P0-2 / D-22). `replaceMessages`
+                // has just discarded the conversation the current list belonged to, so
+                // leaving the rail up produces a panel that disagrees with the model,
+                // which §1.2 ranks below having no panel at all.
+                ctx.controller.restoreTodos(session.todos ?? []);
                 ctx.dispatch({ type: 'restoreEntries', entries: session.entries });
                 if (session.model?.providerId && session.model?.modelId) {
                     ctx.controller.setModel(session.model.providerId, session.model.modelId, session.model.baseUrl);
@@ -369,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/commands/registry.d.ts

@@ -6,6 +6,7 @@ import type { AgentController } from '../agent/controller.js';
 import type { AgentMode } from '../agent/agent-mode.js';
 import type { NoticeLevel, Overlay, ToastLevel, ViewAction, ViewState } from '../agent/reducer.js';
 import type { PersistedConfig } from '../config/schema.js';
+import type { FollowThroughBudget } from '../todo/follow-through.js';
 export interface CommandContext {
     /** Raw argument string after the command word (may be empty). */
     args: string;
@@ -24,8 +25,33 @@ export interface CommandContext {
      * idle). Dynamic skill commands need this: they turn `/pdf-forms a.pdf` into a
      * real user message. It is a separate entry point from `handleSubmit` on
      * purpose — routing back through that would re-enter slash-command parsing.
+     *
+     * `userInitiated: false` suppresses `recordPrompt` (todo-plan-followthrough
+     * C-12 / AC-17), which skips TWO things and both are wanted: the prompt-history
+     * append, and the `submitCount` bump that drives the composer's hint fade. A
+     * canned string the user did not type belongs in neither. The parameter is
+     * named for the CAUSE rather than for one of its effects, because a flag
+     * called `recordHistory` would have made the second one look like a bug.
+     *
+     * WIDENING THIS SIGNATURE IS THE WHOLE REASON THIS FILE IS IN THE CHANGE PLAN
+     * (P1-5): `builtins.ts` reaches `submitMessage` only through here, so
+     * `/todo continue` cannot opt out of prompt history without it.
+     */
+    submit: (text: string, opts?: {
+        userInitiated?: boolean;
+    }) => void;
+    /**
+     * The live auto-continue budget, for `/todo status`'s `(2/25 used)` clause
+     * (todo-plan-followthrough §4.3).
+     *
+     * READ-ONLY AND OPTIONAL. It lives in an `App` ref rather than on the
+     * controller or in `ViewState` (§4.4 / §5.2) because it counts a SESSION'S
+     * INTERACTION WITH THE USER, not the model's plan — so this is the only way a
+     * command can see it, and `makeCtx` is the only place that supplies it.
+     * Optional so the many test contexts that build this object by literal need no
+     * change; absent means the clause degrades to naming the ceiling alone.
      */
-    submit: (text: string) => void;
+    followBudget?: FollowThroughBudget;
     /** Rebuild the system prompt and the dynamic command list after a skill change. */
     refreshSkills: () => void;
     /**

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
@@ -134,6 +136,77 @@ export function readEnvConfig() {
         if (Object.keys(section).length > 0)
             partial.team = section;
     }
+    // ARAGON_TODO=0 turns todo planning off entirely (no tool, no rail). Parsed by
+    // the POSITIVE list, exactly as ARAGON_FULLSCREEN / ARAGON_MOUSE / ARAGON_PLAN
+    // / ARAGON_TEAM are — NOT by `envBool` below, which uses a negative list. The
+    // two readers disagree on values like `ARAGON_TODO=disable`, and this file
+    // already records that once for team mode.
+    //
+    // There is no `ARAGON_TODO_PANEL`: the panel is a per-machine display
+    // preference, which is what `config.json` is for, and every env var here
+    // exists because a flag and a config file are BOTH unreachable in the channel
+    // it serves (containers, SSH, being spawned by another tool).
+    //
+    // ARAGON_TODO_FOLLOW=notify|auto|off PASSES THAT SAME TEST (D-18), which is
+    // why it exists where `ARAGON_TODO_PANEL` does not: follow-through is exactly
+    // the knob an unattended `-p` run in a container with a fixed entrypoint needs
+    // and can reach no other way.
+    //
+    // ONE ACCUMULATED SECTION, ASSIGNED ONCE — the shape the `team` branch above
+    // already uses, and NOT two `if` blocks each assigning `partial.todo` (P1-4).
+    // THE CAST IS WHAT WOULD MAKE THAT MISTAKE SILENT: a second assignment
+    // compiles clean and drops `enabled`, so `ARAGON_TODO=0 ARAGON_TODO_FOLLOW=auto`
+    // would quietly re-enable the tool the user turned off.
+    const todo = process.env.ARAGON_TODO?.trim().toLowerCase();
+    const todoFollow = process.env.ARAGON_TODO_FOLLOW?.trim().toLowerCase();
+    if ((todo !== undefined && todo.length > 0) ||
+        (todoFollow !== undefined && todoFollow.length > 0)) {
+        // Keyed by `TodoConfig` but VALUED `unknown`, which is what lets the mode be
+        // written through unvalidated (below) while still failing to compile if a
+        // future key is misspelled.
+        const section = {};
+        if (todo !== undefined && todo.length > 0) {
+            section.enabled = todo === '1' || todo === 'true' || todo === 'on' || todo === 'yes';
+        }
+        // Written through unvalidated: `clampTodoConfig` clamps an unrecognized mode
+        // to the default rather than rejecting it, so validating here would be a
+        // second gate that can disagree with the first.
+        if (todoFollow !== undefined && todoFollow.length > 0) {
+            section.followThrough = todoFollow;
+        }
+        // A PARTIAL section, safe only because every consumer deep-merges it — the
+        // same contract `partial.skills`, `partial.log` and `partial.team` rely on.
+        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

@@ -52,12 +52,53 @@ export interface CliFlags {
     team?: boolean;
     /** `--team-max <n>` — override `team.maxSubagents` for this run (still clamped). */
     teamMax?: string | number;
+    /**
+     * `--todo` ⇒ true, `--no-todo` ⇒ false, absent ⇒ undefined
+     * (todo-plan-execution §4.3).
+     */
+    todo?: boolean;
+    /**
+     * `--todo-panel` ⇒ true, `--no-todo-panel` ⇒ false, absent ⇒ undefined.
+     *
+     * DECLARED AS A PAIR, like `--todo` above, and unlike `--no-skills` (P1-8).
+     * `panel` is a PERSISTED setting, so "not passed" has to stay distinguishable
+     * from `true` — otherwise commander's lone-`--no-x` default silently
+     * overwrites a config-file `panel: false` on every run that passes no flag at
+     * all. `--no-skills` escapes the rule only because nothing needs to
+     * distinguish `--skills` from silence.
+     */
+    todoPanel?: boolean;
+    /**
+     * `--todo-follow <mode>` — `notify` | `auto` | `off`
+     * (todo-plan-followthrough §4.2).
+     *
+     * A VALUE FLAG, NOT A PAIR, so commander materializes it only when passed and
+     * the `!== undefined` rule above applies to its presence rather than to a
+     * synthesized `true`. Typed `string` and not `FollowThroughMode`: an
+     * unrecognized value is CLAMPED to the default by `clampTodoConfig`, never
+     * rejected, which is what every other key in this file does.
+     */
+    todoFollow?: string;
     /** `--log-level <lv>` — this run only, never persisted. */
     logLevel?: string;
     /** `--log-file` ⇒ true, `--no-log-file` ⇒ false, absent ⇒ undefined. */
     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, 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';
@@ -97,6 +98,48 @@ function resolveTeamConfig(flags, env, file) {
             : {}),
     });
 }
+/**
+ * Merge the `todo` section across all four layers (defaults › file › env ›
+ * flags), todo-plan-execution §4.3.
+ *
+ * `!== undefined` ON BOTH FLAGS, and that is the whole point (P1-8). `commander`
+ * materializes a lone `--no-x` as `opts.x = true` when the flag is absent, so a
+ * truthiness check cannot tell `--no-todo-panel` from "not passed" — and both
+ * keys here are persisted, so both need the distinction. This is the same rule
+ * `resolveTeamConfig` above states, one feature later.
+ */
+function resolveTodoConfig(flags, env, file) {
+    return clampTodoConfig({
+        ...DEFAULT_CONFIG.todo,
+        ...(file.todo ?? {}),
+        ...(env.todo ?? {}),
+        ...(flags.todo !== undefined ? { enabled: flags.todo } : {}),
+        ...(flags.todoPanel !== undefined ? { panel: flags.todoPanel } : {}),
+        // `!== undefined` for the third time, though for a value flag the risk is
+        // milder: commander leaves `opts.todoFollow` absent unless it was passed.
+        // Written this way anyway so the three lines read as one rule.
+        ...(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({
@@ -245,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,
@@ -257,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,
@@ -285,6 +349,7 @@ export function loadConfig(flags = {}) {
         },
         log: resolveLogConfig(flags, env.partial, file),
         team: resolveTeamConfig(flags, env.partial, file),
+        todo: resolveTodoConfig(flags, env.partial, file),
         cwd,
         color,
         colorLevel,