@aragon-agent/cli 0.5.10 → 0.5.12

package/CHANGELOG.md

@@ -7,6 +7,30 @@ were written.
 
 ## Unreleased
 
+### Fixed
+
+- **`/clear` now takes the todo panel with it.** Finish a plan, type `/clear`,
+  and the transcript emptied while the `7/7 done` rail stayed exactly where it
+  was — on a screen you had just asked to be cleared. It stayed until your next
+  real message, which is precisely the pause you take after clearing to decide
+  what to ask next, so essentially everyone met it.
+
+  This was deliberate once. The list is a projection of what the model believes,
+  and `/clear` wipes the transcript rather than the conversation, so the model
+  still believed in the plan and a panel contradicting the model was judged worse
+  than no panel. That reasoning holds for everything the CLI does on its own; it
+  does not hold against you typing the command. An explicit instruction was
+  always this rule's exception — `/todo clear` has used the same door from the
+  start — and `/clear` now goes through it.
+
+  The list itself is cleared, not just the pixels, so `/save`, `/todo status`,
+  `/todo continue` and auto follow-through all agree with the screen: no plan is
+  written into a saved session, nothing offers to continue one, and nothing spends
+  a follow-through on it. `/reset` is unchanged and still the only command that
+  clears the conversation. Nothing is stranded either way — the model's next
+  `todo_write` is a full replacement, so the panel comes back the moment there is
+  a plan to show.
+
 ### Added
 
 - **An update that will not start is undone automatically.** The updater shipped

package/README.md

@@ -107,7 +107,7 @@ Exit codes: `0` success · `1` agent/runtime error · `2` config/usage error ·
 | `/thinking <level>` | Set the thinking level |
 | `/max-tokens [<n>\|auto\|default]` | Output token cap; with no argument, reports the setting **and** the effective cap for the live model |
 | `/tools` | List active tools |
-| `/clear` | Clear the visible transcript |
+| `/clear` | Clear the visible transcript and the todo panel |
 | `/reset` | New conversation |
 | `/cwd [dir]` | Show / change the tool working directory |
 | `/save [file]` | Save the session to JSON |
@@ -498,9 +498,11 @@ against an empty plan is refused outright. A session that never plans has
 byte-identical layout to a build without this feature.
 
 **The list is a projection of what the model believes**, so nothing that does
-not also tell the model may change it:
+not also tell the model may change it — except you, saying so:
 
-- `/clear` wipes the transcript but not the conversation, so the plan stays.
+- `/clear` and `/todo clear` take the plan off the screen. Neither touches the
+  conversation, so the model still knows what it was doing and its next update
+  brings the panel straight back.
 - `/reset` clears the conversation, so the plan goes with it.
 - `/save` writes the list and `/resume` restores it. Resuming a session that has
   no list clears the current one, rather than leaving a plan on screen whose

package/dist/agent/controller.d.ts

@@ -339,7 +339,11 @@ export declare class AgentController {
     subscribeTodos(listener: TodoEventListener): () => void;
     /** `/resume`. An absent or empty list CLEARS — see `TodoStore.restore` (P0-2). */
     restoreTodos(items: unknown): void;
-    /** `/todo clear`. A user override of a projection; refused mid-run by `/todo`. */
+    /**
+     * `/todo clear` and `/clear`. A user override of a projection (I-2's standing
+     * exception). `/todo` refuses mid-run before it gets here; `/clear` does not,
+     * on purpose — refusing there would leave it unable to clear the transcript.
+     */
     clearTodos(): void;
     getRetryConfig(): RetryConfig;
     /**

package/dist/agent/controller.js

@@ -916,7 +916,11 @@ export class AgentController {
     restoreTodos(items) {
         this.todos?.restore(items);
     }
-    /** `/todo clear`. A user override of a projection; refused mid-run by `/todo`. */
+    /**
+     * `/todo clear` and `/clear`. A user override of a projection (I-2's standing
+     * exception). `/todo` refuses mid-run before it gets here; `/clear` does not,
+     * on purpose — refusing there would leave it unable to clear the transcript.
+     */
     clearTodos() {
         this.todos?.clear('user');
     }
@@ -1057,9 +1061,10 @@ export class AgentController {
         // in this conversation" hint would otherwise start lying (P2-9).
         this.skills.getRegistry().clearActive();
         // `/reset` clears `messages`, so the belief that justifies the panel is gone
-        // with them and the list must go too (I-2). `/clear` reaches the transcript
-        // and NOT this method, which is the whole distinction: it tells the model
-        // nothing, so it may not change the list.
+        // with them and the list must go too (I-2). `/clear` also drops the list, but
+        // through `clearTodos()` and reason `'user'`, which is the distinction that
+        // remains: this path is a belief that no longer exists, that one is a user
+        // overriding a projection of a belief the model still holds.
         this.todos?.clear('reset');
     }
     /** Read-only view of the live system prompt (regression tests, /debug). */

package/dist/agent/reducer.js

@@ -692,10 +692,20 @@ export function viewReducer(state, action) {
                 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.
+                // The list goes with the screen it was on. `/clear` is an explicit user
+                // instruction, which is I-2's standing exception (`TodoClearReason`
+                // `'user'`, the same door `/todo clear` uses) — so the command clears the
+                // STORE via `controller.clearTodos()` and this clears the MIRROR, exactly
+                // the pairing `resetConversation` below has always had.
+                //
+                // The mirror write is same-valued with the store's own `todoCleared`
+                // dispatch rather than redundant with it: it is what makes this action
+                // stand on its own. `builtins.ts` is the only dispatcher of it TODAY, and
+                // a second one — a real clear-screen key, a session-restore path — would
+                // otherwise bring the bug back in identical form and in silence.
+                //
+                // The entry id is dropped because the entry it pointed at is gone.
+                todos: null,
                 todoEntryId: undefined,
                 // Same reasoning for the retry card: the entry is gone, so the id must go
                 // with it or `retryScheduled` would `mapEntry` an id that no longer

package/dist/cli.js

@@ -34,6 +34,9 @@ import { runSkillsCommand } from './skills/cli-commands.js';
 import { runHeadless } from './agent/headless.js';
 import { App } from './ui/App.js';
 import { decideRenderMode } from './ui/layout/frame.js';
+import { createFrameDiffer } from './ui/frame-differ.js';
+import { wrapStdoutForFrames } from './ui/stdout-frame-writer.js';
+import { setFrameStatsProvider } from './commands/perf.js';
 import { tryCreateMouseFilter } from './input/stdin-mouse-filter.js';
 import { enterAltScreen, writeExitTranscript } from './ui/screen.js';
 import { readExitSnapshot } from './ui/exit-snapshot.js';
@@ -140,6 +143,16 @@ function toFlags(opts) {
         transcriptRetain: opts.transcriptRetain,
         renderGovernor: opts.renderGovernor,
         maxRenderInterval: opts.maxRenderInterval,
+        // Site three of three for `--diff-render` / `--sync-output` — EIGHT
+        // features, one trap (`mouse` P1-2, `team` P1-4, `todo` C-9, render L4,
+        // retry, fast, update, now frame diffing). 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. It bites
+        // hardest for `--no-diff-render`: that is the documented escape hatch for a
+        // user whose terminal renders the diffed frame wrongly, and a user who has
+        // been told to pass it and sees no change has no next move.
+        diffRender: opts.diffRender,
+        syncOutput: opts.syncOutput,
         // Site three of three for `--update` / `--no-update` — SEVEN features, one
         // trap (`mouse` P1-2, `team` P1-4, `todo` C-9, render L4, retry, fast, now
         // update). A flag needs the `.option()` declaration below, a field on
@@ -224,6 +237,20 @@ function makeController(flags, opts = { interactive: true }) {
     });
     return { controller, confirmBridge, humanInputBridge };
 }
+/**
+ * Raised once per session, on the 0->1 edge of the writer's `fallbacks` counter
+ * (tui-input-flicker-fix §5.6 / AC-15).
+ *
+ * The characteristic failure of frame diffing is SILENT — absolute addressing
+ * loses its origin and the user sees a subtly wrong screen — so leaving its only
+ * signal behind a slash command the affected user has no reason to run is not an
+ * acceptable end state for a fix whose whole premise is "the user should not have
+ * to notice the renderer". `warn`, not `error`: a single fallback is self-healing
+ * by construction (I-6), and it is worth reporting only because the PATTERN is
+ * not.
+ */
+const FRAME_FALLBACK_NOTICE = 'Frame diffing lost sync with the terminal and fell back to a full repaint. ' +
+    'If the display looks wrong, restart with `--no-diff-render`.';
 /**
  * The interactive TUI — and the ONLY place that may touch the screen.
  *
@@ -272,6 +299,40 @@ function runInteractive(flags, extras = {}) {
         ? tryCreateMouseFilter(process.stdin, (reason) => logger.warn('cli', 'mouse_filter_failed', { reason }))
         : null;
     const disposeMouse = () => mouseFilter?.dispose();
+    // --- Frame differ (tui-input-flicker-fix §3.2 / §4.2). -------------------
+    //
+    // FULL-SCREEN ONLY, and that is invariant I-3 rather than caution: inline mode
+    // prints settled entries through Ink's `<Static>`, starts wherever the shell's
+    // cursor happened to be and scrolls, so row k of a frame is not absolute row k
+    // there and never will be. `--no-diff-render` skips construction entirely,
+    // which is what makes rung 2 of the fail-safe ladder byte-identical to a
+    // pre-fix build rather than merely equivalent.
+    //
+    // `rows` is a THUNK, not a snapshot: it is the only input to the I-9 geometry
+    // guard and it changes under the differ's feet on every resize.
+    const frameWriter = mode === 'fullscreen' && config.diffRender
+        ? wrapStdoutForFrames(process.stdout, createFrameDiffer({
+            sync: config.syncOutput && process.env.TERM !== 'dumb',
+            rows: () => process.stdout.rows,
+            // The console bridge (`App.tsx`, full-screen only) turns this into
+            // `dispatch({type:'notice', level:'warn'})`, which is the only legal
+            // user-visible channel with the TUI mounted — a direct write would
+            // itself be the foreign write being reported. Latched on the 0->1
+            // edge inside the differ: a notice per fallback would be a repaint
+            // storm triggered by a repaint problem (§5.6).
+            onFirstFallback: () => console.warn(FRAME_FALLBACK_NOTICE),
+        }))
+        : null;
+    // `null` when no writer was built, so `/perf` can say "diff render off" rather
+    // than printing zeroes that read like a writer doing nothing (§5.4).
+    if (frameWriter)
+        setFrameStatsProvider(frameWriter.stats);
+    const disposeFrameWriter = () => {
+        if (!frameWriter)
+            return;
+        setFrameStatsProvider(null);
+        frameWriter.dispose();
+    };
     const replayTranscript = () => {
         if (replayed || mode !== 'fullscreen' || !config.exitTranscript)
             return;
@@ -348,6 +409,13 @@ function runInteractive(flags, extras = {}) {
         // I-5: with mouse support off the REAL stdin is handed over unwrapped, so
         // every existing path is provably unchanged.
         stdin: mouseFilter?.stdin ?? process.stdin,
+        // SPREAD, not `frameWriter?.stdout ?? process.stdout`. This call passed no
+        // `stdout` at all before, and Ink defaults it to `process.stdout`; omitting
+        // the key entirely when the writer is off keeps the options object the same
+        // SHAPE it has always had, which is what makes AC-5 / AC-6 ("byte-identical
+        // with --no-diff-render, inline mode and `aragon -p`") a statement about
+        // the code rather than about Ink's defaulting.
+        ...(frameWriter ? { stdout: frameWriter.stdout } : {}),
     });
     // H1's primary disarm, and this is the earliest moment at which "this build
     // STARTS" is proven: the module graph loaded, config resolved, Ink mounted
@@ -402,6 +470,11 @@ function runInteractive(flags, extras = {}) {
         .then(() => {
         screen?.restore();
         disposeMouse();
+        // BOTH BRANCHES, the same discipline `controller.dispose()` and
+        // `updateService?.dispose()` already follow. It drops the `'resize'`
+        // listener of I-8 and detaches the `/perf` provider so a later `/perf` in a
+        // torn-down tree reports honestly instead of reading a dead closure.
+        disposeFrameWriter();
         // Orphaned subagents survive `Ctrl+C` otherwise, and a live child holds
         // the event loop open so `aragon` never returns to the shell (R-15). The
         // App's unmount cleanup also calls this; `dispose()` is idempotent.
@@ -421,6 +494,7 @@ function runInteractive(flags, extras = {}) {
         .catch(() => {
         screen?.restore();
         disposeMouse();
+        disposeFrameWriter();
         controller.dispose();
         updateService?.dispose();
     });
@@ -516,6 +590,10 @@ const CONFIG_SET_KEYS = new Set([
     'transcriptRetain',
     'renderGovernor',
     'maxRenderIntervalMs',
+    // tui-input-flicker-fix §5.1. Listed here AND cased in the switch below, for
+    // the reason `transcriptRetain` records three lines up.
+    'diffRender',
+    'syncOutput',
     // Without these two, `density` and `hints` would be settable only as one-shot
     // flags and never persist -- inconsistent with every other config field.
     'density',
@@ -687,6 +765,12 @@ function runConfigSet(key, value) {
         case 'maxRenderIntervalMs':
             patch.maxRenderIntervalMs = clampMaxRenderInterval(value, DEFAULT_MAX_RENDER_INTERVAL_MS);
             break;
+        case 'diffRender':
+            patch.diffRender = value === 'true' || value === '1';
+            break;
+        case 'syncOutput':
+            patch.syncOutput = value === 'true' || value === '1';
+            break;
         case 'density':
             patch.density = clampDensity(value, 'comfortable');
             break;
@@ -1037,6 +1121,15 @@ function buildProgram() {
         .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)')
+        // Composer flicker (tui-input-flicker-fix §5.2). Positive form FIRST for the
+        // tri-state reason recorded five times above: both keys are persisted and
+        // default to `true`, so a negative-only declaration would let commander
+        // synthesize `true` and overwrite a stored `false` on every run — turning the
+        // one documented escape hatch for a mis-rendering terminal into a no-op.
+        .option('--diff-render', 'Repaint only changed rows (default, full-screen only)')
+        .option('--no-diff-render', 'Repaint the whole frame every time (pre-fix behavior)')
+        .option('--sync-output', 'Ask the terminal to present each repaint atomically (the default)')
+        .option('--no-sync-output', 'Do not emit DEC 2026 begin/end synchronized update')
         .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

@@ -831,8 +831,27 @@ const COMMANDS = [
     },
     {
         name: 'clear',
-        description: 'Clear the visible transcript',
-        run: (ctx) => ctx.dispatch({ type: 'clearTranscript' }),
+        description: 'Clear the visible transcript and the todo panel',
+        run: (ctx) => {
+            // A USER OVERRIDE OF A PROJECTION, the same class as `/todo clear`, so it
+            // reuses reason `'user'`; I-2 and its standing exception are stated on
+            // `TodoStore`. Clearing the STORE and not merely the view mirror is what
+            // keeps `/save`, `/todo status|continue` and follow-through agreeing with
+            // the screen — they read the store directly. `messages` is untouched:
+            // clearing the conversation is still `/reset` alone.
+            //
+            // DELIBERATELY WITHOUT `/todo clear`'s two guards: an `isRunning()` refusal
+            // would leave `/clear` unable to clear even the transcript mid-run, and an
+            // early return on an empty list would skip the dispatch below entirely.
+            // Clearing an empty store is already silent — it emits into a reducer
+            // branch that writes two fields that are both already at their defaults.
+            //
+            // Bounded side effect: the emptied store re-arms `todo_write`'s "a fresh
+            // plan has at least two items" gate, so a model that shrinks a plan to one
+            // item right after a mid-run `/clear` gets the refusal text and retries.
+            ctx.controller.clearTodos();
+            ctx.dispatch({ type: 'clearTranscript' });
+        },
     },
     {
         name: 'reset',

package/dist/commands/perf.d.ts

@@ -15,6 +15,7 @@
  * live panel, because a performance readout that costs a repaint per second to
  * display would be self-defeating.
  */
+import type { FrameWriterStats } from '../ui/frame-differ.js';
 import type { SlashCommand } from './registry.js';
 export interface PerfSnapshot {
     /** Governor rung, its resolved interval, and the last measured commit cost. */
@@ -40,6 +41,9 @@ export interface PerfSnapshot {
 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. */
+/** Called by `cli.tsx` after building the writer. Passing `null` detaches. */
+export declare function setFrameStatsProvider(fn: (() => FrameWriterStats) | null): void;
+export declare function readFrameStats(): FrameWriterStats | null;
+/** Format a snapshot as the six-line block documented in §5.4. */
 export declare function formatPerfReport(snap: PerfSnapshot): string;
 export declare const perfCommand: SlashCommand;

package/dist/commands/perf.js

@@ -30,10 +30,51 @@ let resetGovernor = null;
 export function setPerfResetHook(fn) {
     resetGovernor = fn;
 }
+/**
+ * Frame-writer counters (tui-input-flicker-fix §5.4).
+ *
+ * A SECOND MODULE-LEVEL SLOT rather than a prop on `App`, and that is this
+ * file's own documented convention rather than a shortcut: the writer is built
+ * in `runInteractive`, lives entirely outside React, and its counters never
+ * render — so routing them through a 1900-line component's props would buy
+ * nothing and cost `App.tsx` plus `app.test.tsx` churn (P1-2).
+ *
+ * `null` means the writer was never built — `--no-diff-render`, inline mode, or
+ * a non-interactive path. `/perf` says so in words, so "the flag is off" and
+ * "the writer crashed" never look alike.
+ */
+let frameStats = null;
+/** Called by `cli.tsx` after building the writer. Passing `null` detaches. */
+export function setFrameStatsProvider(fn) {
+    frameStats = fn;
+}
+export function readFrameStats() {
+    return frameStats ? frameStats() : null;
+}
 function mb(bytes) {
     return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
 }
-/** Format a snapshot as the five-line block documented in §5.4. */
+function ratio(total, frames) {
+    return frames > 0 ? (total / frames).toFixed(1) : '0.0';
+}
+/**
+ * The writer line (§5.4), in this function's existing ASCII separator shape.
+ *
+ * `fallbacks > 0` on a healthy session is the single most useful diagnostic this
+ * feature can emit: it means something wrote to stdout behind Ink's back and
+ * absolute addressing lost its origin.
+ */
+function formatWriterLine() {
+    const stats = readFrameStats();
+    if (!stats)
+        return 'writer     full  -  diff render off';
+    const bytesPerFrame = stats.framesTotal > 0 ? Math.round(stats.bytesWritten / stats.framesTotal) : 0;
+    return (`writer     diff  -  frames ${stats.framesTotal} ` +
+        `(diffed ${stats.framesDiffed}, full ${stats.framesFull})  -  ` +
+        `lines/frame ${ratio(stats.linesWritten, stats.framesTotal)}  -  ` +
+        `bytes/frame ${bytesPerFrame}  -  fallbacks ${stats.fallbacks}`);
+}
+/** Format a snapshot as the six-line block documented in §5.4. */
 export function formatPerfReport(snap) {
     const caches = renderCacheStats();
     const eco = snap.rung > 0 ? '  -  eco' : '';
@@ -49,6 +90,7 @@ export function formatPerfReport(snap) {
             `hl ${caches.highlightEntries} (${mb(caches.highlightBytes)})  -  ` +
             `lines ${caches.lineEntries}`,
         `mode       ${snap.mode}  -  viewport ${snap.viewportRows} rows  -  offset ${snap.offset}`,
+        formatWriterLine(),
     ].join('\n');
 }
 export const perfCommand = {

package/dist/config/env.d.ts

@@ -13,6 +13,7 @@
  *     ARAGON_LOG_LEVEL,
  *     ARAGON_LOG_FILE, ARAGON_LOG_DIR, ARAGON_TRANSCRIPT_RETAIN,
  *     ARAGON_RENDER_GOVERNOR, ARAGON_MAX_RENDER_INTERVAL_MS,
+ *     ARAGON_DIFF_RENDER, ARAGON_SYNC_OUTPUT,
  *     ARAGON_UPDATE.
  *
  * READ ELSEWHERE, ON PURPOSE: `ARAGON_UPDATE_REGISTRY` and `npm_config_registry`

package/dist/config/env.js

@@ -13,6 +13,7 @@
  *     ARAGON_LOG_LEVEL,
  *     ARAGON_LOG_FILE, ARAGON_LOG_DIR, ARAGON_TRANSCRIPT_RETAIN,
  *     ARAGON_RENDER_GOVERNOR, ARAGON_MAX_RENDER_INTERVAL_MS,
+ *     ARAGON_DIFF_RENDER, ARAGON_SYNC_OUTPUT,
  *     ARAGON_UPDATE.
  *
  * READ ELSEWHERE, ON PURPOSE: `ARAGON_UPDATE_REGISTRY` and `npm_config_registry`
@@ -347,6 +348,22 @@ export function readEnvConfig() {
         if (Number.isFinite(parsed) && parsed > 0)
             partial.maxRenderIntervalMs = parsed;
     }
+    // ARAGON_DIFF_RENDER=0 restores the pre-fix full-frame repaint;
+    // ARAGON_SYNC_OUTPUT=0 drops the DEC 2026 envelope (tui-input-flicker-fix
+    // §5.3). Parsed by the POSITIVE list, exactly as ARAGON_FULLSCREEN /
+    // ARAGON_MOUSE / ARAGON_PLAN / ARAGON_TEAM / ARAGON_TODO / ARAGON_RENDER_GOVERNOR
+    // are — NOT by `envBool` below, whose NEGATIVE list disagrees with it on values
+    // like `ARAGON_DIFF_RENDER=disable`.
+    const diffRender = process.env.ARAGON_DIFF_RENDER?.trim().toLowerCase();
+    if (diffRender !== undefined && diffRender.length > 0) {
+        partial.diffRender =
+            diffRender === '1' || diffRender === 'true' || diffRender === 'on' || diffRender === 'yes';
+    }
+    const syncOutput = process.env.ARAGON_SYNC_OUTPUT?.trim().toLowerCase();
+    if (syncOutput !== undefined && syncOutput.length > 0) {
+        partial.syncOutput =
+            syncOutput === '1' || syncOutput === 'true' || syncOutput === 'on' || syncOutput === 'yes';
+    }
     const log = readEnvLogConfig();
     if (log)
         partial.log = log;

package/dist/config/load.d.ts

@@ -106,6 +106,19 @@ export interface CliFlags {
     renderGovernor?: boolean;
     /** `--max-render-interval <ms>` — the governor ceiling for this run (L4). */
     maxRenderInterval?: string | number;
+    /**
+     * `--diff-render` ⇒ true, `--no-diff-render` ⇒ false, absent ⇒ undefined
+     * (tui-input-flicker-fix §5.2).
+     *
+     * DECLARED AS A PAIR for the reason `--render-governor` records one field up:
+     * `diffRender` is PERSISTED and defaults to `true`, so a lone
+     * `--no-diff-render` would make commander default `opts.diffRender` to `true`
+     * and silently overwrite a stored `false` on every run that passed no flag at
+     * all — i.e. the documented escape hatch would quietly un-set itself.
+     */
+    diffRender?: boolean;
+    /** `--sync-output` ⇒ true, `--no-sync-output` ⇒ false, absent ⇒ undefined (§5.2). */
+    syncOutput?: boolean;
     /**
      * `--retry` ⇒ true, `--no-retry` ⇒ false, absent ⇒ undefined
      * (llm-api-retry-backoff §6.2).

package/dist/config/load.js

@@ -227,6 +227,35 @@ function resolveRenderGovernor(flags, env, file) {
         return file.renderGovernor;
     return DEFAULT_CONFIG.renderGovernor;
 }
+/**
+ * Resolve per-line frame diffing: flag › env › file › default `true`
+ * (tui-input-flicker-fix §5.1).
+ *
+ * Shaped exactly like `resolveRenderGovernor` above, and for the same reason:
+ * there are no heuristics for an explicit `true` to override, so a persisted
+ * `true` is a value rather than an opinion that has to be told apart from
+ * silence. `!== undefined` on the flag is what makes `--no-diff-render` beat a
+ * config file that left the key at its default.
+ */
+function resolveDiffRender(flags, env, file) {
+    if (flags.diffRender !== undefined)
+        return flags.diffRender;
+    if (env.diffRender !== undefined)
+        return env.diffRender;
+    if (file.diffRender !== undefined)
+        return file.diffRender;
+    return DEFAULT_CONFIG.diffRender;
+}
+/** Same ladder for the DEC 2026 envelope (§5.1). */
+function resolveSyncOutput(flags, env, file) {
+    if (flags.syncOutput !== undefined)
+        return flags.syncOutput;
+    if (env.syncOutput !== undefined)
+        return env.syncOutput;
+    if (file.syncOutput !== undefined)
+        return file.syncOutput;
+    return DEFAULT_CONFIG.syncOutput;
+}
 /** Merge the `log` section across all four layers (defaults › file › env › flags). */
 function resolveLogConfig(flags, env, file) {
     const merged = clampLogConfig({
@@ -421,6 +450,8 @@ export function loadConfig(flags = {}) {
         ...(requestedRetain < transcriptRetain ? { transcriptRetainRequested: requestedRetain } : {}),
         renderGovernor: resolveRenderGovernor(flags, env.partial, file),
         maxRenderIntervalMs: clampMaxRenderInterval(pick(flags.maxRenderInterval, env.partial.maxRenderIntervalMs, file.maxRenderIntervalMs), DEFAULT_CONFIG.maxRenderIntervalMs),
+        diffRender: resolveDiffRender(flags, env.partial, file),
+        syncOutput: resolveSyncOutput(flags, env.partial, file),
         confirmTools,
         toolTimeoutMs,
         idleTimeoutMs,

package/dist/config/schema.d.ts

@@ -98,6 +98,23 @@ export declare const DEFAULT_RENDER_GOVERNOR = true;
  */
 export declare const DEFAULT_MAX_RENDER_INTERVAL_MS = 320;
 export declare function clampMaxRenderInterval(v: unknown, fallback: number): number;
+/**
+ * Repaint only the frame lines that changed (full-screen only).
+ *
+ * ON by default, and `--no-diff-render` restores today's byte stream EXACTLY —
+ * the interposer is not constructed at all, so a regression on an exotic
+ * terminal is one flag away from being neutralised (§3.5 rung 2).
+ */
+export declare const DEFAULT_DIFF_RENDER = true;
+/**
+ * Wrap each repaint batch in DEC 2026 begin/end synchronized update.
+ *
+ * ON by default with NO capability probe (§3.3): terminals that do not implement
+ * mode 2026 parse the CSI sequence, find an unknown private mode and discard it,
+ * so a false positive costs nothing — and a false negative costs nothing either,
+ * because the frame differ already removes the flicker on its own.
+ */
+export declare const DEFAULT_SYNC_OUTPUT = true;
 /** `ask_user` calls allowed per user turn. */
 export declare const DEFAULT_PLAN_MAX_ASK_ROUNDS = 4;
 /**
@@ -530,6 +547,10 @@ export interface PersistedConfig {
     renderGovernor: boolean;
     /** Ceiling of the governor ladder in ms; `33` flattens it (L4). */
     maxRenderIntervalMs: number;
+    /** Repaint only the frame rows that changed (tui-input-flicker-fix §5.1). */
+    diffRender: boolean;
+    /** Wrap each repaint batch in DEC 2026 synchronized update (§5.1). */
+    syncOutput: boolean;
     confirmTools: boolean;
     toolTimeoutMs: number;
     idleTimeoutMs: number;
@@ -671,6 +692,20 @@ export interface CliConfig {
     renderGovernor: boolean;
     /** Ceiling of the governor ladder in ms; `33` flattens it (L4). */
     maxRenderIntervalMs: number;
+    /**
+     * Repaint only the frame rows that changed (tui-input-flicker-fix §5.1).
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `showThinking` / `liveToolOutput` / `update` each record: `runInteractive`
+     * reads `config.diffRender`, where `config` is a `CliConfig`, so a key added to
+     * the persisted shape alone would round-trip through `config set`, appear in
+     * `config list` — and never reach the one gate that constructs the writer.
+     * `--no-diff-render` and `ARAGON_DIFF_RENDER=0` would parse and be discarded,
+     * with no compile error and no runtime error.
+     */
+    diffRender: boolean;
+    /** Wrap each repaint batch in DEC 2026 synchronized update (§5.1). */
+    syncOutput: boolean;
     confirmTools: boolean;
     toolTimeoutMs: number;
     idleTimeoutMs: number;

package/dist/config/schema.js

@@ -145,6 +145,30 @@ export function clampMaxRenderInterval(v, fallback) {
     return clampInt(v, fallback, RENDER_INTERVAL_RANGE);
 }
 // ---------------------------------------------------------------------------
+// Frame diffing (tui-input-flicker-fix §5.1)
+//
+// TWO TROUBLESHOOTING SWITCHES, in the same class as `historyEnabled`: neither
+// appears on the settings overlay, because a user who needs them is debugging a
+// terminal, not adjusting a preference.
+// ---------------------------------------------------------------------------
+/**
+ * Repaint only the frame lines that changed (full-screen only).
+ *
+ * ON by default, and `--no-diff-render` restores today's byte stream EXACTLY —
+ * the interposer is not constructed at all, so a regression on an exotic
+ * terminal is one flag away from being neutralised (§3.5 rung 2).
+ */
+export const DEFAULT_DIFF_RENDER = true;
+/**
+ * Wrap each repaint batch in DEC 2026 begin/end synchronized update.
+ *
+ * ON by default with NO capability probe (§3.3): terminals that do not implement
+ * mode 2026 parse the CSI sequence, find an unknown private mode and discard it,
+ * so a false positive costs nothing — and a false negative costs nothing either,
+ * because the frame differ already removes the flicker on its own.
+ */
+export const DEFAULT_SYNC_OUTPUT = true;
+// ---------------------------------------------------------------------------
 // Plan mode (plan-mode §4.4)
 //
 // THREE FLAT KEYS, not a nested `planMode` object. `store.ts` documents that its
@@ -669,6 +693,8 @@ export const DEFAULT_CONFIG = {
     transcriptRetain: DEFAULT_TRANSCRIPT_RETAIN,
     renderGovernor: DEFAULT_RENDER_GOVERNOR,
     maxRenderIntervalMs: DEFAULT_MAX_RENDER_INTERVAL_MS,
+    diffRender: DEFAULT_DIFF_RENDER,
+    syncOutput: DEFAULT_SYNC_OUTPUT,
     confirmTools: false,
     toolTimeoutMs: DEFAULT_TOOL_TIMEOUT_MS,
     idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,

package/dist/todo/store.d.ts

@@ -10,12 +10,18 @@
  * `TeamRuntime`.
  *
  * INVARIANT I-2 — the list is a PROJECTION OF WHAT THE MODEL BELIEVES, and
- * nothing that does not tell the model may change it. `/clear` wipes the
- * transcript but not the conversation, so it must NOT reach this class;
- * `/reset` clears `messages`, so it must. Every write is a FULL REPLACEMENT and
- * every clear is a FULL REMOVAL - there is no partial update anywhere, which is
- * what makes I-9 ("the panel is never a contradiction of the model") provable
- * rather than argued.
+ * nothing that does not tell the model may change it — EXCEPT AN EXPLICIT USER
+ * INSTRUCTION, which is the rule's standing exception and is marked
+ * `TodoClearReason = 'user'`. Two commands come through that door: `/todo clear`
+ * and `/clear`. Neither tells the model anything, and that is fine, because what
+ * they leave behind is "panel absent, model still remembers" - the direction I-9
+ * below calls safe, and one the model's next full-replacement write heals on its
+ * own. `/reset` (reason `'reset'`) remains the only clear caused by the belief
+ * itself being destroyed, because it clears `messages`.
+ *
+ * Every write is a FULL REPLACEMENT and every clear is a FULL REMOVAL - there is
+ * no partial update anywhere, which is what makes I-9 ("the panel is never a
+ * contradiction of the model") provable rather than argued.
  */
 import { type NormalizeResult } from './normalize.js';
 import type { TodoClearReason, TodoEventListener, TodoSnapshot } from './types.js';