@aragon-agent/cli 0.5.4 → 0.5.8

package/dist/agent/reducer.d.ts

@@ -13,6 +13,7 @@
 import type { AgentEvent, ModelCost, ToolResult, TokenUsage } from '@aragon-agent/core';
 import type { AgentMode } from './agent-mode.js';
 import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '../team/types.js';
+import type { TodoItem, TodoSnapshot } from '../todo/types.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
 export type ToastLevel = NoticeLevel | 'success';
 export type Overlay = null | 'settings' | 'model' | 'help' | 'confirm' | 'question' | 'plan';
@@ -78,6 +79,34 @@ export type Entry = {
     aborted: boolean;
     durationMs?: number;
     active: boolean;
+}
+/**
+ * The turn's todo checklist (todo-plan-execution §3.8). ONE per user turn,
+ * rewritten in place — a 7-item list updated twice per item would otherwise be
+ * 14 near-identical tool cards in the one surface the user reads most.
+ *
+ * JSON-SERIALIZABLE by construction, so `/save` needs no format change.
+ *
+ * `live: true` is normalized away ON LOAD, in `session/persist.ts`, for the
+ * same reason the team entry's `active` is (C-5): `Transcript`'s settled
+ * boundary is MONOTONIC, so an entry that never settles never reaches
+ * `<Static>` and is re-rendered on every frame for the rest of the session.
+ */
+ | {
+    id: string;
+    kind: 'todo';
+    items: TodoItem[];
+    doneCount: number;
+    total: number;
+    /** The turn that owns this card is still running, so it may be rewritten. */
+    live: boolean;
+    /**
+     * Set by `normalizeLoadedEntries` on a card saved while its run was live
+     * (P2-6). The todo analogue of the team entry's `aborted`, and true for the
+     * same reason: the run behind it died with the process. Absent on every
+     * card this session produced.
+     */
+    interrupted?: boolean;
 };
 export interface UsageTotal {
     inputTokens: number;
@@ -112,14 +141,33 @@ export interface ViewState {
      * live dispatch to show (§6.4).
      */
     team: TeamSnapshot | null;
+    /**
+     * The live todo list, or `null` when there is none.
+     *
+     * NEVER PERSISTED HERE — `entries` is the history and `SavedSession.todos` is
+     * the list (§3.13). `null` is what leaves the rail unmounted entirely, which
+     * is why a session that never plans has byte-identical layout to a pre-feature
+     * build (AC-24).
+     */
+    todos: TodoSnapshot | null;
     seq: number;
     /** The `kind: 'team'` entry the live dispatch is writing into. */
     teamEntryId?: string;
+    /** The `kind: 'todo'` entry this turn is writing into. */
+    todoEntryId?: string;
     streamingId?: string;
     turnProduced: boolean;
     errorNoticed: boolean;
     /** The current run was aborted by the user (suppresses the failure guard). */
     aborted: boolean;
+    /**
+     * Entries removed by `transcriptRetain` (tui-render-performance L1).
+     *
+     * Rendered by `transcript-text` and reported by `/perf`; NEVER PERSISTED —
+     * `SavedSession` keeps `{ model, messages, entries, todos }` exactly as it is,
+     * so `/save` and `/resume` need no format change and old files load unchanged.
+     */
+    droppedEntries: number;
 }
 export declare function initialViewState(): ViewState;
 export type ViewAction = {
@@ -213,6 +261,11 @@ export type ViewAction = {
 } | {
     type: 'teamEnd';
     outcome: DispatchOutcome;
+} | {
+    type: 'todoUpdate';
+    snapshot: TodoSnapshot;
+} | {
+    type: 'todoCleared';
 };
 export declare const STORED_PREVIEW_CHARS = 8000;
 export declare const STORED_PREVIEW_LINES = 200;

package/dist/agent/reducer.js

@@ -10,7 +10,9 @@
  *   - `agent_end` after a turn that produced no `turn_end` and no error notice
  *     synthesizes a generic error notice (a swallowed throw is never a no-op).
  */
+import process from 'node:process';
 import { computeCost } from './usage.js';
+import { ENTRY_LIMITS, appendBounded, entryRetain, trimEntries } from './entry-limits.js';
 /** Default auto-dismiss window for a toast. */
 export const DEFAULT_TOAST_TTL_MS = 2500;
 export function initialViewState() {
@@ -28,12 +30,15 @@ export function initialViewState() {
         agentMode: 'build',
         pendingAgentMode: null,
         team: null,
+        todos: null,
         seq: 0,
         teamEntryId: undefined,
+        todoEntryId: undefined,
         streamingId: undefined,
         turnProduced: false,
         errorNoticed: false,
         aborted: false,
+        droppedEntries: 0,
     };
 }
 // ---------------------------------------------------------------------------
@@ -118,6 +123,20 @@ export function reduceEvent(event, cost) {
             return [];
     }
 }
+/**
+ * Tools that render their own transcript entry, so the generic tool card would
+ * be a duplicate. EXACTLY ONE MEMBER; read todo-plan-execution §3.8 before
+ * adding a second.
+ *
+ * SUPPRESSING ONLY `tool_call_start` IS SUFFICIENT, AND THAT IS THE WHOLE REASON
+ * THIS IS SAFE (D-10). Every later handler — `toolCallDelta` / `toolCallEnd` /
+ * `toolExecStart` / `toolExecEnd` — resolves its target through
+ * `findToolEntryId`, which returns `undefined` when no entry was created, and
+ * every one of them already early-returns on that. There is no fifth handler. A
+ * second suppression rule would be four more places to get the id matching
+ * wrong, for nothing.
+ */
+const SELF_RENDERING_TOOLS = new Set(['todo_write']);
 function reduceStreamEvent(se) {
     switch (se.type) {
         case 'thinking_start':
@@ -127,6 +146,8 @@ function reduceStreamEvent(se) {
         case 'text_delta':
             return [{ type: 'textDelta', delta: se.delta }];
         case 'tool_call_start':
+            if (SELF_RENDERING_TOOLS.has(se.toolName))
+                return [];
             return [
                 { type: 'toolCallStart', toolCallId: se.toolCallId, toolName: se.toolName },
             ];
@@ -183,6 +204,35 @@ function nextId(state) {
 function mapEntry(entries, id, fn) {
     return entries.map((e) => (e.id === id ? fn(e) : e));
 }
+/**
+ * Append one entry and ring-trim the result (tui-render-performance L1).
+ *
+ * TRIMMING HAPPENS ONLY AT APPEND POINTS, and that is the whole reason this is a
+ * helper rather than a line in `viewReducer`. A mid-turn trim triggered by an
+ * UPDATE action could drop the entry `streamingId` / `teamEntryId` /
+ * `todoEntryId` points at while it is still being written to; appending is the
+ * only moment at which the tail is by definition the newest thing.
+ *
+ * I-L1-1 — the trim must never drop a live target. With `retain >= 200` and a
+ * trim that only ever removes from the head this is structurally true, but a
+ * future clamp change would break it SILENTLY (the `mapEntry` calls would simply
+ * stop matching), so development builds assert it.
+ */
+function appendEntry(state, entries, entry) {
+    const trimmed = trimEntries([...entries, entry], entryRetain());
+    if (trimmed.dropped > 0 && process.env.NODE_ENV !== 'production') {
+        const live = [state.streamingId, state.teamEntryId, state.todoEntryId].filter((id) => typeof id === 'string');
+        for (const id of live) {
+            if (!trimmed.entries.some((e) => e.id === id)) {
+                throw new Error(`trimEntries dropped a live entry (${id}) - see I-L1-1`);
+            }
+        }
+    }
+    return {
+        entries: trimmed.entries,
+        droppedEntries: state.droppedEntries + trimmed.dropped,
+    };
+}
 function findToolEntryId(state, toolCallId) {
     for (let i = state.entries.length - 1; i >= 0; i -= 1) {
         const e = state.entries[i];
@@ -199,8 +249,12 @@ export function viewReducer(state, action) {
             return {
                 ...state,
                 seq,
-                entries: [...state.entries, entry],
+                ...appendEntry(state, state.entries, entry),
                 streamingId: undefined,
+                // A new turn gets its own card, in that turn's position in the
+                // transcript. The PREVIOUS card stays exactly where it is — it is
+                // history, and history is not retracted.
+                todoEntryId: undefined,
                 turnProduced: false,
                 errorNoticed: false,
                 aborted: false,
@@ -224,7 +278,7 @@ export function viewReducer(state, action) {
                 thinkingOpen: false,
                 streaming: true,
             };
-            return { ...state, seq, entries: [...state.entries, entry], streamingId: id };
+            return { ...state, seq, ...appendEntry(state, state.entries, entry), streamingId: id };
         }
         case 'thinkingStart': {
             if (!state.streamingId)
@@ -240,7 +294,7 @@ export function viewReducer(state, action) {
             return {
                 ...state,
                 entries: mapEntry(state.entries, state.streamingId, (e) => e.kind === 'assistant'
-                    ? { ...e, thinking: (e.thinking ?? '') + action.delta }
+                    ? { ...e, thinking: appendBounded(e.thinking ?? '', action.delta, ENTRY_LIMITS.thinking) }
                     : e),
             };
         }
@@ -249,7 +303,9 @@ export function viewReducer(state, action) {
                 return state;
             return {
                 ...state,
-                entries: mapEntry(state.entries, state.streamingId, (e) => e.kind === 'assistant' ? { ...e, text: e.text + action.delta } : e),
+                entries: mapEntry(state.entries, state.streamingId, (e) => e.kind === 'assistant'
+                    ? { ...e, text: appendBounded(e.text, action.delta, ENTRY_LIMITS.text) }
+                    : e),
             };
         }
         case 'toolCallStart': {
@@ -263,7 +319,7 @@ export function viewReducer(state, action) {
                 argsRaw: '',
                 status: 'pending',
             };
-            return { ...state, seq, entries: [...state.entries, entry] };
+            return { ...state, seq, ...appendEntry(state, state.entries, entry) };
         }
         case 'toolCallDelta': {
             const id = findToolEntryId(state, action.toolCallId);
@@ -271,7 +327,9 @@ export function viewReducer(state, action) {
                 return state;
             return {
                 ...state,
-                entries: mapEntry(state.entries, id, (e) => e.kind === 'tool' ? { ...e, argsRaw: e.argsRaw + action.argsDelta } : e),
+                entries: mapEntry(state.entries, id, (e) => e.kind === 'tool'
+                    ? { ...e, argsRaw: appendBounded(e.argsRaw, action.argsDelta, ENTRY_LIMITS.argsRaw) }
+                    : e),
             };
         }
         case 'toolCallEnd': {
@@ -336,17 +394,27 @@ export function viewReducer(state, action) {
                 ? mapEntry(state.entries, state.streamingId, (e) => e.kind === 'assistant' ? { ...e, streaming: false } : e)
                 : state.entries;
             let seq = state.seq;
+            let droppedEntries = state.droppedEntries;
             // Silent-failure guard (R2): a swallowed throw shows nothing otherwise.
             // A user abort is an expected empty run, not a failure — skip the guard.
             if (!state.turnProduced && !state.errorNoticed && !state.aborted) {
                 const next = nextId({ ...state, seq });
                 seq = next.seq;
-                entries = [
-                    ...entries,
-                    { id: next.id, kind: 'notice', level: 'error', text: GENERIC_RUN_FAILURE },
-                ];
+                const appended = appendEntry(state, entries, {
+                    id: next.id,
+                    kind: 'notice',
+                    level: 'error',
+                    text: GENERIC_RUN_FAILURE,
+                });
+                entries = appended.entries;
+                droppedEntries = appended.droppedEntries;
             }
-            return { ...state, entries, seq, status: 'idle', streamingId: undefined };
+            // The card may now reach `<Static>` (C-5 / I-6): the turn that owns it is
+            // over, so nothing will rewrite it.
+            if (state.todoEntryId) {
+                entries = mapEntry(entries, state.todoEntryId, (e) => e.kind === 'todo' ? { ...e, live: false } : e);
+            }
+            return { ...state, entries, seq, droppedEntries, status: 'idle', streamingId: undefined };
         }
         case 'notice': {
             const { id, seq } = nextId(state);
@@ -354,7 +422,7 @@ export function viewReducer(state, action) {
             return {
                 ...state,
                 seq,
-                entries: [...state.entries, entry],
+                ...appendEntry(state, state.entries, entry),
                 errorNoticed: action.level === 'error' ? true : state.errorNoticed,
             };
         }
@@ -376,19 +444,35 @@ export function viewReducer(state, action) {
             return {
                 ...state,
                 entries: [],
+                // The count describes what the RETAIN RING removed from the visible
+                // transcript. `/clear` empties it by intent, so carrying the number
+                // over would make the exported transcript claim a loss that did not
+                // happen.
+                droppedEntries: 0,
                 streamingId: undefined,
                 expandedToolIds: {},
                 teamEntryId: undefined,
+                // The entry it pointed at is gone, so the id goes with it. `todos` is
+                // DELIBERATELY UNTOUCHED (I-2): `/clear` wipes the transcript and not
+                // the conversation, so the model still believes in the plan, and a panel
+                // that disagrees with the model is worse than no panel.
+                todoEntryId: undefined,
             };
         case 'resetConversation':
             return {
                 ...state,
                 entries: [],
+                droppedEntries: 0,
                 streamingId: undefined,
                 expandedToolIds: {},
                 contextTokens: 0,
                 usageTotal: { inputTokens: 0, outputTokens: 0, costUsd: 0 },
                 teamEntryId: undefined,
+                // `/reset` clears `messages`, so the belief is gone and the list goes
+                // with it — the other half of I-2. `controller.clearMessages()` clears
+                // the STORE; this clears the mirror.
+                todos: null,
+                todoEntryId: undefined,
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };
@@ -444,7 +528,7 @@ export function viewReducer(state, action) {
             return {
                 ...state,
                 seq,
-                entries: [...state.entries, entry],
+                ...appendEntry(state, state.entries, entry),
                 teamEntryId: id,
                 team: {
                     dispatchId: action.dispatchId,
@@ -496,13 +580,60 @@ export function viewReducer(state, action) {
             // "(dang you de shi hou)": it renders only while a dispatch is running.
             return { ...state, entries, team: null, teamEntryId: undefined };
         }
+        // --- Todo planning (todo-plan-execution §5.2) -------------------------
+        case 'todoUpdate': {
+            const entry = (id) => ({
+                id,
+                kind: 'todo',
+                items: action.snapshot.items,
+                doneCount: action.snapshot.doneCount,
+                total: action.snapshot.total,
+                live: true,
+            });
+            // Rewrite the turn's card when there is one; otherwise append and record
+            // its id. One `mapEntry` on the KNOWN id, never a scan.
+            if (state.todoEntryId) {
+                const known = state.todoEntryId;
+                return {
+                    ...state,
+                    todos: action.snapshot,
+                    entries: mapEntry(state.entries, known, (e) => e.kind === 'todo' ? { ...entry(known), live: e.live } : e),
+                };
+            }
+            const { id, seq } = nextId(state);
+            return {
+                ...state,
+                seq,
+                todos: action.snapshot,
+                ...appendEntry(state, state.entries, entry(id)),
+                todoEntryId: id,
+            };
+        }
+        // THE ENTRY STAYS. It is history, and history is not retracted — only the
+        // live projection goes away, which is what unmounts the rail.
+        case 'todoCleared':
+            return { ...state, todos: null, todoEntryId: undefined };
         case 'restoreEntries': {
             // Adopt a seq beyond any restored id to keep future ids unique.
             const maxSeq = action.entries.reduce((acc, e) => {
                 const n = Number.parseInt(e.id.replace(/^e/, ''), 10);
                 return Number.isFinite(n) ? Math.max(acc, n) : acc;
             }, state.seq);
-            return { ...state, entries: [...action.entries], seq: maxSeq, teamEntryId: undefined };
+            // A session file can be longer than the retain ring; trimming it here is
+            // the one append-free place the bound still has to hold, and the count
+            // starts from this restore rather than inheriting the previous session's.
+            const restored = trimEntries([...action.entries], entryRetain());
+            return {
+                ...state,
+                entries: restored.entries,
+                droppedEntries: restored.dropped,
+                seq: maxSeq,
+                teamEntryId: undefined,
+                // As for `team`: the restored cards are history and no turn owns them.
+                // The LIST itself arrives separately, through `controller.restoreTodos`
+                // and the store's own event (§3.13).
+                todoEntryId: undefined,
+            };
         }
         default:
             return state;

package/dist/agent/system-prompt.d.ts

@@ -53,6 +53,14 @@ export interface SystemPromptParams {
      * mixing them a one-character mistake.
      */
     subagentBlock?: string;
+    /**
+     * The rendered `<todo_planning>` block, or `''` (todo-plan-execution §3.7).
+     *
+     * Spliced conditionally exactly as `skillsBlock`, the plan block and
+     * `teamBlock` are, which is what keeps C-10 / I-5 true: `todo.enabled: false`
+     * (and `--no-todo`) produce the pre-todo prompt BYTE FOR BYTE.
+     */
+    todoBlock?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -39,6 +39,7 @@ export function buildSystemPrompt(params) {
         : '';
     const teamBlock = params.teamBlock ?? '';
     const subagentBlock = params.subagentBlock ?? '';
+    const todoBlock = params.todoBlock ?? '';
     return [
         'You are AragonAgent, an autonomous coding assistant operating inside a terminal (TUI).',
         'You help the user accomplish software-engineering tasks by reasoning step by step and using the provided tools.',
@@ -54,6 +55,7 @@ export function buildSystemPrompt(params) {
         ...(planBlock ? ['', planBlock] : []),
         ...(teamBlock ? ['', teamBlock] : []),
         ...(subagentBlock ? ['', subagentBlock] : []),
+        ...(todoBlock ? ['', todoBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',

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';
@@ -86,11 +86,29 @@ function toFlags(opts) {
         // reach `CliFlags` and are inert, with no compile error and no runtime error.
         team: opts.team,
         teamMax: opts.teamMax,
+        // Site three of three for `--todo` / `--todo-panel`, and the one this
+        // package has now paid for twice (`mouse` P1-2, `team` P1-4): a flag needs
+        // the `.option()` declaration below, a field on `CliFlags`, AND a line here.
+        // Miss this one and the flag is inert with no compile error and no runtime
+        // error.
+        todo: opts.todo,
+        todoPanel: opts.todoPanel,
+        // Site three of three for `--todo-follow` as well (todo-plan-followthrough
+        // C-9). A value flag is no less inert than a boolean one when this line is
+        // missing.
+        todoFollow: opts.todoFollow,
         // `--verbose` is just a shorthand for `--log-level debug`; an explicit
         // `--log-level` still wins, so the two can be combined without surprise.
         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,
     };
 }
 // ---------------------------------------------------------------------------
@@ -120,12 +138,21 @@ function makeController(flags, opts = { interactive: true }) {
     // resolved a bootstrap level — it ran before commander and before `.env` were
     // readable — and without this hand-off the fully resolved one never applies.
     getLogger().reconfigure(config.log);
+    // Whether this session could EVER show the todo rail (todo-plan-execution
+    // §3.7 / P1-6). It varies ONE sentence of `<todo_planning>`; `decideRenderMode`
+    // is pure and `runInteractive` calls it again with the same inputs, so
+    // computing it here rather than threading it back costs nothing and keeps the
+    // controller's construction self-contained.
+    const todoPanelCapable = opts.interactive &&
+        decideRenderMode({ fullscreen: config.fullscreen }, process.env, process.stdout) ===
+            'fullscreen';
     const confirmBridge = { handler: null };
     // `cancelPending` is replaced by the App's own implementation on mount; this
     // no-op keeps the object total so nothing has to null-check it.
     const humanInputBridge = { handler: null, cancelPending: () => { } };
     const controller = new AgentController(config, {
         version: VERSION,
+        todoPanelCapable,
         confirm: (req) => confirmBridge.handler ? confirmBridge.handler(req) : Promise.resolve(true),
         approval: opts.interactive
             ? {
@@ -219,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') {
@@ -308,7 +339,13 @@ async function runOneShot(flags, prompt, quiet) {
     for (const dir of untrusted) {
         process.stderr.write(`[skills] project skills in ${dir} skipped (untrusted). Run: aragon skills trust ${dir}\n`);
     }
-    const code = await runHeadless(controller, prompt, { quiet });
+    // `followThrough` is read off the REAL controller here rather than through
+    // `HeadlessController`, which is deliberately the minimal surface a test can
+    // satisfy with an object literal (todo-plan-followthrough §3.6).
+    const code = await runHeadless(controller, prompt, {
+        quiet,
+        followThrough: controller.getTodoConfig().followThrough,
+    });
     // Flushed HERE and not inside `runHeadless`: that module is deliberately
     // injectable (its own controller interface, its own stdout/stderr) and has an
     // early `return 2`, so a singleton dependency in there would be both a new
@@ -367,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',
@@ -483,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');
@@ -602,6 +654,19 @@ function buildProgram() {
         .option('--team', 'Enable team subagents for this session (the default)')
         .option('--no-team', 'Disable team subagents (the task tool is not registered at all)')
         .option('--team-max <n>', 'Max subagents per dispatch for this run (1-10)')
+        // BOTH PAIRS, positive first (todo-plan-execution §4.3 / P1-8). `--todo` is
+        // the `--team` story verbatim; `--todo-panel` needs the pair for a second
+        // reason on top of it — `panel` is PERSISTED, so a lone `--no-todo-panel`
+        // would make commander default `opts.todoPanel` to `true` and silently
+        // overwrite a stored `panel: false` on every run that passed no flag.
+        .option('--todo', 'Enable todo planning for this session (the default)')
+        .option('--no-todo', 'Disable todo planning (the todo_write tool is not registered at all)')
+        .option('--todo-panel', 'Show the todo plan in a right-hand rail (the default)')
+        .option('--no-todo-panel', 'Keep todo planning but do not render the rail')
+        // NOT A PAIR, and it does not need to be: a value flag is absent unless
+        // passed, so `!== undefined` in `resolveTodoConfig` already distinguishes it
+        // from silence. An unrecognized mode is clamped to `notify`, not rejected.
+        .option('--todo-follow <mode>', 'What to do when a run ends with unfinished steps: notify (default) | auto | off')
         .option('--no-skills', 'Disable the skill system entirely (no catalog, no skill tools)')
         .option('--skill <name>', 'Force-load a skill at Level 2 for this run (repeatable)', (value, previous = []) => [...previous, value])
         .option('--skills-yes', 'Approve skill installs for this run (CI / headless)')
@@ -615,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) => {