@aragon-agent/cli 0.5.10 → 0.5.11

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/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/ui/PromptInput.d.ts

@@ -7,6 +7,16 @@
  * The buffer/cursor transforms (`applyEdit`, `moveVertical`) and the suggestion
  * computations (`slashSuggestions`, `fileTokenAt`) are pure module functions,
  * exported for `input.test.ts`, so the component itself stays thin.
+ *
+ * THE EDITOR'S FIVE PIECES OF STATE LIVE IN ONE REDUCER, and every branch of the
+ * input handler performs AT MOST ONE `dispatch` (tui-input-flicker-fix §3.4).
+ * Ink mounts a LEGACY React root, where `setState` outside a React event handler
+ * is not batched — and `useInput` runs from a stdin `'data'` listener, which is
+ * outside React entirely. The five `setState` calls one keystroke used to make
+ * were five commits, five whole-tree Yoga layouts and, through Ink's 32 ms
+ * leading+trailing throttle, two full-frame repaints per character. `fileMatches`
+ * stays a plain `useState` because it is written from the debounced glob effect
+ * rather than from a key.
  */
 import React from 'react';
 import type { Theme } from './theme.js';

package/dist/ui/PromptInput.js

@@ -8,13 +8,24 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
  * The buffer/cursor transforms (`applyEdit`, `moveVertical`) and the suggestion
  * computations (`slashSuggestions`, `fileTokenAt`) are pure module functions,
  * exported for `input.test.ts`, so the component itself stays thin.
+ *
+ * THE EDITOR'S FIVE PIECES OF STATE LIVE IN ONE REDUCER, and every branch of the
+ * input handler performs AT MOST ONE `dispatch` (tui-input-flicker-fix §3.4).
+ * Ink mounts a LEGACY React root, where `setState` outside a React event handler
+ * is not batched — and `useInput` runs from a stdin `'data'` listener, which is
+ * outside React entirely. The five `setState` calls one keystroke used to make
+ * were five commits, five whole-tree Yoga layouts and, through Ink's 32 ms
+ * leading+trailing throttle, two full-frame repaints per character. `fileMatches`
+ * stays a plain `useState` because it is written from the debounced glob effect
+ * rather than from a key.
  */
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useReducer, useRef, useState } from 'react';
 import { Box, Text, useInput } from 'ink';
 import { glob as tinyGlob } from 'tinyglobby';
 import { pickGlyphs } from './glyphs.js';
 import { recognize } from '../input/keymap.js';
 import { AutocompletePopup } from './AutocompletePopup.js';
+import { editorReducer, INITIAL_EDITOR_STATE } from './editor-reducer.js';
 // ---------------------------------------------------------------------------
 // Pure editing helpers (unit-tested in input.test.ts)
 // ---------------------------------------------------------------------------
@@ -128,11 +139,8 @@ function isControlSeq(input) {
 // Component
 // ---------------------------------------------------------------------------
 export function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, agentMode, onSubmit, onHelp, bordered, onDraftChange, }) {
-    const [buffer, setBuffer] = useState('');
-    const [cursor, setCursor] = useState(0);
-    const [historyIndex, setHistoryIndex] = useState(null);
-    const [dismissed, setDismissed] = useState(false);
-    const [sel, setSel] = useState(0);
+    const [editor, dispatch] = useReducer(editorReducer, INITIAL_EDITOR_STATE);
+    const { buffer, cursor, historyIndex, dismissed, sel } = editor;
     const [fileMatches, setFileMatches] = useState([]);
     // --- Derived suggestion state (shared by render + input handler). --------
     const slashSug = dismissed ? null : slashSuggestions(buffer, commands);
@@ -189,46 +197,36 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
         onDraftChange(hasDraft);
     }, [hasDraft, onDraftChange]);
     // --- Mutators. -----------------------------------------------------------
-    const resetDraftFlags = () => {
-        setHistoryIndex(null);
-        setDismissed(false);
-        setSel(0);
-    };
+    // ONE DISPATCH EACH, and that is the rule §3.4 asks a reviewer to check line
+    // by line. Two dispatches from one key would put the legacy root back to two
+    // commits and undo the whole of F3 for that branch.
     const insert = (text) => {
-        setBuffer(buffer.slice(0, cursor) + text + buffer.slice(cursor));
-        setCursor(cursor + text.length);
-        resetDraftFlags();
+        dispatch({ type: 'insert', text });
     };
     const submit = (text) => {
         onSubmit(text);
-        setBuffer('');
-        setCursor(0);
-        resetDraftFlags();
+        dispatch({ type: 'clear' });
     };
     const recallUp = () => {
         if (history.length === 0)
             return;
         const idx = historyIndex === null ? history.length - 1 : Math.max(0, historyIndex - 1);
         const value = history[idx] ?? '';
-        setHistoryIndex(idx);
-        setBuffer(value);
-        setCursor(value.length);
+        dispatch({ type: 'recall', buffer: value, cursor: value.length, historyIndex: idx });
     };
     const recallDown = () => {
         if (historyIndex === null)
             return;
         const idx = historyIndex + 1;
+        // Past the newest entry the walk ends and the draft goes back to empty —
+        // `historyIndex: null` is what tells `verticalOrHistory` the user is editing
+        // again rather than still stepping.
         if (idx >= history.length) {
-            setHistoryIndex(null);
-            setBuffer('');
-            setCursor(0);
-        }
-        else {
-            const value = history[idx] ?? '';
-            setHistoryIndex(idx);
-            setBuffer(value);
-            setCursor(value.length);
+            dispatch({ type: 'recall', buffer: '', cursor: 0, historyIndex: null });
+            return;
         }
+        const value = history[idx] ?? '';
+        dispatch({ type: 'recall', buffer: value, cursor: value.length, historyIndex: idx });
     };
     const completeSelection = () => {
         const chosen = popupItems[clampedSel];
@@ -236,20 +234,17 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
             return;
         if (popupKind === 'slash') {
             const next = `${chosen.label} `;
-            setBuffer(next);
-            setCursor(next.length);
+            dispatch({ type: 'replace', buffer: next, cursor: next.length });
         }
         else if (popupKind === 'file' && fileTok) {
             const next = buffer.slice(0, fileTok.start) + chosen.label + buffer.slice(fileTok.end);
-            setBuffer(next);
-            setCursor(fileTok.start + chosen.label.length);
+            dispatch({ type: 'replace', buffer: next, cursor: fileTok.start + chosen.label.length });
         }
-        resetDraftFlags();
     };
     const verticalOrHistory = (dir) => {
         const moved = moveVertical(buffer, cursor, dir);
         if (moved) {
-            setCursor(moved.cursor);
+            dispatch({ type: 'moveCursor', cursor: moved.cursor });
             return;
         }
         // At an edge: recall history only from an empty buffer or while already
@@ -274,11 +269,11 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
         // Popup navigation owns Up/Down/Tab/→/Enter/Esc while it is open.
         if (popupItems.length > 0) {
             if (key.upArrow) {
-                setSel(Math.max(0, clampedSel - 1));
+                dispatch({ type: 'select', sel: Math.max(0, clampedSel - 1) });
                 return;
             }
             if (key.downArrow) {
-                setSel(Math.min(popupItems.length - 1, clampedSel + 1));
+                dispatch({ type: 'select', sel: Math.min(popupItems.length - 1, clampedSel + 1) });
                 return;
             }
             if (key.tab || (key.rightArrow && cursor >= buffer.length)) {
@@ -292,7 +287,7 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
                 return;
             }
             if (key.escape) {
-                setDismissed(true);
+                dispatch({ type: 'dismiss' });
                 return;
             }
             // Any other key falls through so typing keeps filtering the popup.
@@ -303,9 +298,7 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
         const intent = recognize(input, key);
         if (intent) {
             const next = applyEdit(buffer, cursor, intent);
-            setBuffer(next.buffer);
-            setCursor(next.cursor);
-            resetDraftFlags();
+            dispatch({ type: 'replace', buffer: next.buffer, cursor: next.cursor });
             return;
         }
         if (key.ctrl)
@@ -321,19 +314,19 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
             return;
         }
         if (key.backspace || key.delete) {
-            if (cursor > 0) {
-                setBuffer(buffer.slice(0, cursor - 1) + buffer.slice(cursor));
-                setCursor(cursor - 1);
-                resetDraftFlags();
-            }
+            // The `cursor > 0` guard lives in the reducer now, so this branch is one
+            // unconditional dispatch and a no-op at the left edge returns the same
+            // state object — which React bails out on, exactly as the old
+            // `if (cursor > 0)` skipped the `setState`s.
+            dispatch({ type: 'backspace' });
             return;
         }
         if (key.leftArrow) {
-            setCursor(Math.max(0, cursor - 1));
+            dispatch({ type: 'moveCursor', cursor: Math.max(0, cursor - 1) });
             return;
         }
         if (key.rightArrow) {
-            setCursor(Math.min(buffer.length, cursor + 1));
+            dispatch({ type: 'moveCursor', cursor: Math.min(buffer.length, cursor + 1) });
             return;
         }
         // `!key.shift` is load-bearing: Shift+↑/↓ is the viewport's line-scroll

package/dist/ui/editor-reducer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Composer editor state — F3 of tui-input-flicker-fix (§3.4).
+ *
+ * Ink creates its container with tag `0` — a LEGACY React root
+ * (`ink/build/ink.js:59-61`). In a legacy root, `setState` called outside a
+ * React event handler is NOT batched: each call schedules and immediately
+ * flushes a synchronous render. `useInput`'s callback runs from a stdin
+ * `'data'` listener, which is outside React entirely, so `PromptInput.insert`'s
+ * five `setState` calls became five commits, five whole-tree Yoga layouts, and
+ * — through Ink's 32 ms leading+trailing throttle — TWO full-frame repaints per
+ * printable character (§2 R3). The flicker got worse the faster the user typed,
+ * which is exactly what the report described.
+ *
+ * Collapsing the five always-together pieces of state into one reducer makes a
+ * keystroke cost one commit. `fileMatches` deliberately stays a separate
+ * `useState` in the component: it is written from the debounced async glob
+ * effect, not from the key handler, so folding it in here would couple two
+ * unrelated update sources.
+ *
+ * THE RULE A REVIEWER SHOULD CHECK LINE BY LINE: every branch of the `useInput`
+ * callback performs at most ONE `dispatch` and then returns.
+ *
+ * Extracted from the component so it is unit-testable without mounting Ink.
+ */
+export interface EditorState {
+    buffer: string;
+    cursor: number;
+    historyIndex: number | null;
+    dismissed: boolean;
+    sel: number;
+}
+/**
+ * A `type` and not an `interface` because it is a discriminated union — the one
+ * documented exception to this package's interface-first convention.
+ */
+export type EditorAction = {
+    type: 'insert';
+    text: string;
+} | {
+    type: 'replace';
+    buffer: string;
+    cursor: number;
+} | {
+    type: 'backspace';
+} | {
+    type: 'moveCursor';
+    cursor: number;
+} | {
+    type: 'recall';
+    buffer: string;
+    cursor: number;
+    historyIndex: number | null;
+} | {
+    type: 'select';
+    sel: number;
+} | {
+    type: 'dismiss';
+} | {
+    type: 'clear';
+};
+export declare const INITIAL_EDITOR_STATE: EditorState;
+export declare function editorReducer(state: EditorState, action: EditorAction): EditorState;

package/dist/ui/editor-reducer.js

@@ -0,0 +1,90 @@
+/**
+ * Composer editor state — F3 of tui-input-flicker-fix (§3.4).
+ *
+ * Ink creates its container with tag `0` — a LEGACY React root
+ * (`ink/build/ink.js:59-61`). In a legacy root, `setState` called outside a
+ * React event handler is NOT batched: each call schedules and immediately
+ * flushes a synchronous render. `useInput`'s callback runs from a stdin
+ * `'data'` listener, which is outside React entirely, so `PromptInput.insert`'s
+ * five `setState` calls became five commits, five whole-tree Yoga layouts, and
+ * — through Ink's 32 ms leading+trailing throttle — TWO full-frame repaints per
+ * printable character (§2 R3). The flicker got worse the faster the user typed,
+ * which is exactly what the report described.
+ *
+ * Collapsing the five always-together pieces of state into one reducer makes a
+ * keystroke cost one commit. `fileMatches` deliberately stays a separate
+ * `useState` in the component: it is written from the debounced async glob
+ * effect, not from the key handler, so folding it in here would couple two
+ * unrelated update sources.
+ *
+ * THE RULE A REVIEWER SHOULD CHECK LINE BY LINE: every branch of the `useInput`
+ * callback performs at most ONE `dispatch` and then returns.
+ *
+ * Extracted from the component so it is unit-testable without mounting Ink.
+ */
+export const INITIAL_EDITOR_STATE = {
+    buffer: '',
+    cursor: 0,
+    historyIndex: null,
+    dismissed: false,
+    sel: 0,
+};
+/**
+ * The three flags `resetDraftFlags()` used to clear with three separate
+ * `setState` calls.
+ *
+ * Every action that CHANGES THE BUFFER resets them, and that is the pre-existing
+ * semantics rather than a new rule: an edit invalidates the history cursor (the
+ * draft is no longer the recalled entry), un-dismisses the popup (the user is
+ * typing again, so suggestions should come back), and re-homes the selection
+ * (the candidate list is about to be recomputed).
+ */
+const DRAFT_FLAGS = { historyIndex: null, dismissed: false, sel: 0 };
+export function editorReducer(state, action) {
+    switch (action.type) {
+        case 'insert':
+            return {
+                ...state,
+                ...DRAFT_FLAGS,
+                buffer: state.buffer.slice(0, state.cursor) + action.text + state.buffer.slice(state.cursor),
+                cursor: state.cursor + action.text.length,
+            };
+        case 'replace':
+            return { ...state, ...DRAFT_FLAGS, buffer: action.buffer, cursor: action.cursor };
+        case 'backspace': {
+            if (state.cursor <= 0)
+                return state;
+            return {
+                ...state,
+                ...DRAFT_FLAGS,
+                buffer: state.buffer.slice(0, state.cursor - 1) + state.buffer.slice(state.cursor),
+                cursor: state.cursor - 1,
+            };
+        }
+        case 'moveCursor':
+            // NO DRAFT-FLAG RESET. Moving the caret is not an edit: clearing
+            // `historyIndex` here would end a history walk the moment the user pressed
+            // ← to look at what they recalled.
+            return state.cursor === action.cursor ? state : { ...state, cursor: action.cursor };
+        case 'recall':
+            // `historyIndex` is SET, not reset, which is why recall cannot reuse
+            // `replace` — the two differ in exactly the field that keeps the walk
+            // alive. `dismissed` and `sel` are LEFT ALONE, which is not an oversight:
+            // the three `setState` calls this replaces did not touch them either, and
+            // an Esc-dismissed popup that reopened when the user stepped through their
+            // history would be a behaviour change smuggled in by a refactor whose whole
+            // claim is that input semantics are identical (K-7).
+            return {
+                ...state,
+                buffer: action.buffer,
+                cursor: action.cursor,
+                historyIndex: action.historyIndex,
+            };
+        case 'select':
+            return state.sel === action.sel ? state : { ...state, sel: action.sel };
+        case 'dismiss':
+            return state.dismissed ? state : { ...state, dismissed: true };
+        case 'clear':
+            return INITIAL_EDITOR_STATE;
+    }
+}

package/dist/ui/frame-differ.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Frame differ — F1 of tui-input-flicker-fix (§3.2).
+ *
+ * Ink 5.2.1 has exactly one repaint strategy: on every commit it serialises the
+ * WHOLE frame and hands it to `log-update`, which writes
+ * `eraseLines(previousLineCount) + frame` in a single `stdout.write`
+ * (`ink/build/log-update.js:17`). `ansiEscapes.eraseLines` walks BOTTOM-UP, so
+ * the composer — the last row of the frame — is erased near the start of every
+ * repaint and rewritten at the very end of it. During a run that happens 15–30
+ * times a second with the composer's bytes unchanged, and the user sees the
+ * bottom of their screen flicker while they type (§2 R1/R2).
+ *
+ * This module recognises that write shape, diffs the new frame against the
+ * previous one line by line, and emits only the rows that actually changed, each
+ * addressed absolutely. It is PURE: no I/O, no Node globals, no event emitter —
+ * `stdout-frame-writer.ts` is what binds it to a real stream. That is what keeps
+ * it unit-testable with plain string literals and no TTY.
+ *
+ * THREE INVARIANTS LIVE HERE AND EACH ONE FAILS SILENTLY IF DROPPED:
+ *
+ *  - I-4 · An emitted line is `CUP · SGR0 · text · SGR0 · CSI K`, IN THAT ORDER,
+ *    and it never contains `CSI 2K`. Erasing first would blank the row and refill
+ *    it, which is R1's defect at 1/H the scale but on the one row the user is
+ *    watching. Overwriting in place means no cell is ever presentably empty; the
+ *    trailing `CSI K` removes only the residue a longer previous line left, and
+ *    the trailing SGR reset before it stops a BCE terminal painting that residue
+ *    in whatever background colour the line ended inside.
+ *  - I-5 · Every emitted batch ends parked on row `H+1`. Ink's own
+ *    `previousLineCount` is computed from the string IT produced and is
+ *    unaffected by what we actually wrote, so a later pass-through's
+ *    `eraseLines(H+1)` must find the cursor exactly where log-update left it last
+ *    time. Drop this and one fallback shifts the frame up a row for the rest of
+ *    the session.
+ *  - I-6 · Any unrecognised write invalidates the cache. Absolute addressing is
+ *    valid only while nothing else writes to stdout. Full-screen mode already
+ *    forbids that, but "forbidden" is not "impossible", and the failure mode of
+ *    the guard being absent is a permanently misaligned screen while the failure
+ *    mode of it firing spuriously is one extra full repaint.
+ */
+/**
+ * Rebuild `ansiEscapes.eraseLines(count)` byte for byte.
+ *
+ * Exported for the upgrade tripwire (`frame-differ-ink-shape.test.ts`), which
+ * drives the real `ink/build/log-update.js` and asserts this reconstruction is
+ * byte-equal to what it produced. If a future Ink changes the shape, that test
+ * fails loudly instead of this module silently degrading to pass-through for the
+ * rest of the package's life (K-2).
+ */
+export declare function eraseLinesPrefix(count: number): string;
+export interface FrameDifferOptions {
+    /** Emit the DEC 2026 envelope around each batch. */
+    sync: boolean;
+    /**
+     * Live terminal height. Read on every `transform`, NEVER cached: it is the
+     * only input to the I-9 geometry guard and it changes under the differ's feet
+     * on resize. `undefined` ⇒ stand down and pass through.
+     */
+    rows: () => number | undefined;
+    /** Raised once, on the 0→1 edge of `fallbacks` (§5.6). */
+    onFirstFallback?: () => void;
+}
+export interface FrameWriterStats {
+    /** Frames the differ EMITTED — `framesDiffed + framesFull`, never pass-throughs. */
+    framesTotal: number;
+    framesDiffed: number;
+    framesFull: number;
+    linesWritten: number;
+    bytesWritten: number;
+    /**
+     * Pass-throughs caused by a write the differ did not understand.
+     *
+     * NOT INVALIDATIONS (AC-11 / K-14). A resize legitimately invalidates and shows
+     * up as `framesFull`; counting invalidations here would put AC-7 and AC-11 in
+     * direct contradiction and one of them would end up quietly relaxed. It also
+     * excludes the two pass-throughs this module inflicts on ITSELF and already
+     * knows are benign — the session's seed write and the degenerate-geometry
+     * stand-down — because `fallbacks > 0` is documented to mean "something wrote
+     * to stdout behind Ink's back" and is what raises the §5.6 notice.
+     */
+    fallbacks: number;
+}
+export interface FrameDiffer {
+    /**
+     * Bytes to write instead of `chunk`; `''` = write nothing; `null` = write
+     * `chunk`. The parameter is `string` and only `string` (P1-4): decoding, and
+     * the decision about what is even diffable, belong to the writer — the only
+     * place untyped input arrives.
+     */
+    transform(chunk: string): string | null;
+    /** Force the next frame to be a full repaint. */
+    invalidate(): void;
+    /** Single owner of the counters (P2-2); the writer re-exports this. */
+    stats(): FrameWriterStats;
+}
+export declare function createFrameDiffer(options: FrameDifferOptions): FrameDiffer;

package/dist/ui/frame-differ.js

@@ -0,0 +1,230 @@
+/**
+ * Frame differ — F1 of tui-input-flicker-fix (§3.2).
+ *
+ * Ink 5.2.1 has exactly one repaint strategy: on every commit it serialises the
+ * WHOLE frame and hands it to `log-update`, which writes
+ * `eraseLines(previousLineCount) + frame` in a single `stdout.write`
+ * (`ink/build/log-update.js:17`). `ansiEscapes.eraseLines` walks BOTTOM-UP, so
+ * the composer — the last row of the frame — is erased near the start of every
+ * repaint and rewritten at the very end of it. During a run that happens 15–30
+ * times a second with the composer's bytes unchanged, and the user sees the
+ * bottom of their screen flicker while they type (§2 R1/R2).
+ *
+ * This module recognises that write shape, diffs the new frame against the
+ * previous one line by line, and emits only the rows that actually changed, each
+ * addressed absolutely. It is PURE: no I/O, no Node globals, no event emitter —
+ * `stdout-frame-writer.ts` is what binds it to a real stream. That is what keeps
+ * it unit-testable with plain string literals and no TTY.
+ *
+ * THREE INVARIANTS LIVE HERE AND EACH ONE FAILS SILENTLY IF DROPPED:
+ *
+ *  - I-4 · An emitted line is `CUP · SGR0 · text · SGR0 · CSI K`, IN THAT ORDER,
+ *    and it never contains `CSI 2K`. Erasing first would blank the row and refill
+ *    it, which is R1's defect at 1/H the scale but on the one row the user is
+ *    watching. Overwriting in place means no cell is ever presentably empty; the
+ *    trailing `CSI K` removes only the residue a longer previous line left, and
+ *    the trailing SGR reset before it stops a BCE terminal painting that residue
+ *    in whatever background colour the line ended inside.
+ *  - I-5 · Every emitted batch ends parked on row `H+1`. Ink's own
+ *    `previousLineCount` is computed from the string IT produced and is
+ *    unaffected by what we actually wrote, so a later pass-through's
+ *    `eraseLines(H+1)` must find the cursor exactly where log-update left it last
+ *    time. Drop this and one fallback shifts the frame up a row for the rest of
+ *    the session.
+ *  - I-6 · Any unrecognised write invalidates the cache. Absolute addressing is
+ *    valid only while nothing else writes to stdout. Full-screen mode already
+ *    forbids that, but "forbidden" is not "impossible", and the failure mode of
+ *    the guard being absent is a permanently misaligned screen while the failure
+ *    mode of it firing spuriously is one extra full repaint.
+ */
+import { MIN_FULLSCREEN_ROWS } from './layout/frame.js';
+// ---------------------------------------------------------------------------
+// Constants — exact, so no call site ever re-derives an escape sequence.
+// ---------------------------------------------------------------------------
+/** Control Sequence Introducer. Spelled out once; nothing below re-escapes it. */
+const CSI = '\x1b[';
+/** Erase the WHOLE line. Ink uses it on every repaint; this module never emits it (I-4). */
+const ERASE_LINE = `${CSI}2K`;
+/** Erase cursor → end of line. This is what an emitted line ends with. */
+const ERASE_TO_EOL = `${CSI}K`;
+const CURSOR_UP_1 = `${CSI}1A`;
+const CURSOR_LEFT = `${CSI}G`;
+const SGR_RESET = `${CSI}0m`;
+/** Erase cursor → end of screen. One sequence instead of H+1 line erases. */
+const ERASE_DOWN = `${CSI}J`;
+/** DEC private mode 2026 — begin/end synchronized update (F2, §3.3). */
+const SYNC_BEGIN = `${CSI}?2026h`;
+const SYNC_END = `${CSI}?2026l`;
+/**
+ * `eraseLines(n)` for any n ≥ 1, anchored at the start of the chunk.
+ *
+ * FALLBACK ONLY (P2-3). Whenever `prev !== null` the differ already knows the
+ * exact prefix it expects — `eraseLinesPrefix(prev.length + 1)` is a
+ * deterministic string — so the hot path is `chunk.startsWith(expected)`:
+ * linear, unambiguous, and it collapses step 7's `erased !== prev.length + 1`
+ * test into the same comparison. This regex is reached only on the first
+ * diffable chunk after a session start or an `invalidate()`, where no
+ * expectation exists yet.
+ */
+const ERASE_PREFIX_RE = /^(?:\x1b\[2K(?:\x1b\[1A)?)+\x1b\[G/;
+function cursorTo(row) {
+    return `${CSI}${row};1H`;
+}
+/**
+ * Rebuild `ansiEscapes.eraseLines(count)` byte for byte.
+ *
+ * Exported for the upgrade tripwire (`frame-differ-ink-shape.test.ts`), which
+ * drives the real `ink/build/log-update.js` and asserts this reconstruction is
+ * byte-equal to what it produced. If a future Ink changes the shape, that test
+ * fails loudly instead of this module silently degrading to pass-through for the
+ * rest of the package's life (K-2).
+ */
+export function eraseLinesPrefix(count) {
+    if (count <= 0)
+        return '';
+    let out = '';
+    for (let i = 0; i < count; i += 1) {
+        out += ERASE_LINE + (i < count - 1 ? CURSOR_UP_1 : '');
+    }
+    return out + CURSOR_LEFT;
+}
+function countErases(prefix) {
+    return prefix.split(ERASE_LINE).length - 1;
+}
+export function createFrameDiffer(options) {
+    /** Last frame, one entry per row. `null` = no cache, next frame is a full repaint. */
+    let prev = null;
+    /**
+     * Whether any chunk has been seen at all.
+     *
+     * The session's FIRST write has `previousLineCount === 0`, so `eraseLines(0)`
+     * is the empty string and the chunk carries no erase prefix (§3.2.1). That is
+     * expected, not a desync, so it must not raise the §5.6 notice on every launch.
+     * After it, every chunk Ink produces carries a prefix, so a prefix-less chunk
+     * from then on really is foreign.
+     */
+    let seenAnyChunk = false;
+    const counters = {
+        framesTotal: 0,
+        framesDiffed: 0,
+        framesFull: 0,
+        linesWritten: 0,
+        bytesWritten: 0,
+        fallbacks: 0,
+    };
+    const invalidate = () => {
+        prev = null;
+    };
+    /**
+     * Write `chunk` verbatim — today's behaviour, and the only failure mode.
+     *
+     * `counted` is false for the two cases the differ inflicts on itself and knows
+     * are harmless (the seed write, degenerate geometry); true means a foreign
+     * write desynced absolute addressing, which is what `fallbacks` reports.
+     */
+    const passThrough = (counted) => {
+        invalidate();
+        if (counted) {
+            counters.fallbacks += 1;
+            if (counters.fallbacks === 1)
+                options.onFirstFallback?.();
+        }
+        return null;
+    };
+    const wrapSync = (payload) => options.sync ? SYNC_BEGIN + payload + SYNC_END : payload;
+    const emit = (payload, lines, addressed, full) => {
+        prev = lines;
+        counters.framesTotal += 1;
+        if (full)
+            counters.framesFull += 1;
+        else
+            counters.framesDiffed += 1;
+        counters.linesWritten += addressed;
+        counters.bytesWritten += payload.length;
+        return payload;
+    };
+    /** `undefined` ⇒ the I-9 stand-down: a viewport too small to address safely. */
+    const usableRows = () => {
+        const rows = options.rows();
+        if (rows === undefined || !Number.isFinite(rows))
+            return undefined;
+        return rows < MIN_FULLSCREEN_ROWS ? undefined : rows;
+    };
+    const matchErasePrefix = (chunk) => {
+        if (prev !== null) {
+            const expected = eraseLinesPrefix(prev.length + 1);
+            if (chunk.startsWith(expected))
+                return { prefix: expected, erased: prev.length + 1 };
+        }
+        const m = ERASE_PREFIX_RE.exec(chunk);
+        if (m === null)
+            return null;
+        return { prefix: m[0], erased: countErases(m[0]) };
+    };
+    /**
+     * Full repaint — the first diffable frame of a session, every invalidation
+     * (including the resize invalidation of I-8), and any line-count change.
+     *
+     * `CSI J` replaces the H+1 individual line erases with one sequence, and the
+     * alternate screen is exactly the region being erased. `\r\n` rather than `\n`
+     * is deliberate: Ink relies on the tty's `ONLCR` post-processing to turn `\n`
+     * into CRLF, and that dependency is invisible until it is not there.
+     *
+     * P0-1's blank-then-paint objection does not apply here and the asymmetry with
+     * the per-line path is deliberate: a full repaint rewrites every row, so there
+     * is no unchanged content that has to survive, and full repaints are rare by
+     * construction — one per session, one per resize, one per invalidation.
+     */
+    const fullRepaint = (lines) => {
+        const payload = cursorTo(1) +
+            SGR_RESET +
+            ERASE_DOWN +
+            lines.join('\r\n') +
+            '\r\n' +
+            cursorTo(lines.length + 1);
+        return emit(wrapSync(payload), lines, lines.length, true);
+    };
+    const diffRepaint = (lines, previous) => {
+        const out = [];
+        for (let i = 0; i < lines.length; i += 1) {
+            // I-4: paint, THEN clear the tail. Never `ERASE_LINE` first.
+            if (lines[i] !== previous[i]) {
+                out.push(cursorTo(i + 1) + SGR_RESET + lines[i] + SGR_RESET + ERASE_TO_EOL);
+            }
+        }
+        // DEFENSIVE ONLY, not a live path (P2-4). `log-update.js:13-15` returns early
+        // on an identical frame, so a chunk that reaches here differs by at least one
+        // line; the only way to observe zero is a cache that disagrees with the
+        // screen, which is the state `invalidate()` exists to prevent.
+        if (out.length === 0)
+            return emit('', lines, 0, false);
+        out.push(cursorTo(lines.length + 1)); // I-5
+        return emit(wrapSync(out.join('')), lines, out.length - 1, false);
+    };
+    const transform = (chunk) => {
+        const firstChunk = !seenAnyChunk;
+        seenAnyChunk = true;
+        const rows = usableRows();
+        if (rows === undefined)
+            return passThrough(false); // I-9
+        const matched = matchErasePrefix(chunk);
+        // A prefix-less chunk is the session's seed write (P1-1) or a foreign one.
+        if (matched === null)
+            return passThrough(!firstChunk);
+        const body = chunk.slice(matched.prefix.length);
+        if (!body.endsWith('\n'))
+            return passThrough(true); // `log.clear()` and friends
+        const lines = body.slice(0, -1).split('\n');
+        if (lines.length + 1 > rows)
+            return passThrough(false); // I-9
+        if (prev === null || prev.length !== lines.length || matched.erased !== prev.length + 1) {
+            return fullRepaint(lines);
+        }
+        return diffRepaint(lines, prev);
+    };
+    return {
+        transform,
+        invalidate,
+        stats: () => ({ ...counters }),
+    };
+}

package/dist/ui/stdout-frame-writer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Stdout frame writer — the `Proxy` that binds `frame-differ.ts` to a real
+ * stream (tui-input-flicker-fix §3.2 / §5.5).
+ *
+ * Ink offers no hook for "how to write a frame": `Ink#log` is constructed
+ * internally and `log-update` is a private module. It DOES accept a `stdout` in
+ * `render()`'s options, so the whole interposition is one `Proxy` whose only
+ * trapped behaviour is `write` — everything else is the real stream.
+ *
+ * THREE THINGS IN HERE ARE LOAD-BEARING:
+ *
+ *  - The `get` trap MUST bind non-`write` function members to the REAL stream.
+ *    Without the bind, `stdout.on('resize', …)` executes with `this === proxy`,
+ *    and `useTerminalSize` registers and removes its listener against a
+ *    different `_events` object than the one Node emits on — the frame stops
+ *    resizing and nothing reports why.
+ *  - The UNTYPED BOUNDARY LIVES HERE, not in the differ (P1-4). A `Uint8Array`
+ *    chunk, and any `write` whose `encoding` is present and is not UTF-8, is
+ *    passed straight through after `invalidate()`: in both cases the bytes on
+ *    the wire are not the string a differ could reason about, and diffing one
+ *    encoding while writing another is the kind of bug that only shows up on
+ *    someone else's machine.
+ *  - The `'resize'` SUBSCRIPTION (I-8 / P0-2). Ink renders SYNCHRONOUSLY from its
+ *    own `'resize'` handler while the frame's height is still the pre-resize one
+ *    — `useTerminalSize` debounces by 50 ms — so the line count is unchanged
+ *    across that window and the differ's line-count guard cannot see the resize.
+ *    Meanwhile the emulator has re-flowed the alternate screen, so every row the
+ *    differ believes unchanged is a row it will not repaint, for the rest of the
+ *    drag. It goes on the REAL stream, not the `Proxy`, and `dispose()` removes
+ *    it.
+ */
+import type { FrameDiffer, FrameWriterStats } from './frame-differ.js';
+export interface FrameWriterHandle {
+    /** Hand this to `render(…, { stdout })`. */
+    stdout: NodeJS.WriteStream;
+    /** Hand this to `setFrameStatsProvider`. */
+    stats(): FrameWriterStats;
+    /** Removes the `'resize'` subscription of I-8. Idempotent. */
+    dispose(): void;
+}
+export declare function wrapStdoutForFrames(stdout: NodeJS.WriteStream, differ: FrameDiffer): FrameWriterHandle;

package/dist/ui/stdout-frame-writer.js

@@ -0,0 +1,102 @@
+/**
+ * Stdout frame writer — the `Proxy` that binds `frame-differ.ts` to a real
+ * stream (tui-input-flicker-fix §3.2 / §5.5).
+ *
+ * Ink offers no hook for "how to write a frame": `Ink#log` is constructed
+ * internally and `log-update` is a private module. It DOES accept a `stdout` in
+ * `render()`'s options, so the whole interposition is one `Proxy` whose only
+ * trapped behaviour is `write` — everything else is the real stream.
+ *
+ * THREE THINGS IN HERE ARE LOAD-BEARING:
+ *
+ *  - The `get` trap MUST bind non-`write` function members to the REAL stream.
+ *    Without the bind, `stdout.on('resize', …)` executes with `this === proxy`,
+ *    and `useTerminalSize` registers and removes its listener against a
+ *    different `_events` object than the one Node emits on — the frame stops
+ *    resizing and nothing reports why.
+ *  - The UNTYPED BOUNDARY LIVES HERE, not in the differ (P1-4). A `Uint8Array`
+ *    chunk, and any `write` whose `encoding` is present and is not UTF-8, is
+ *    passed straight through after `invalidate()`: in both cases the bytes on
+ *    the wire are not the string a differ could reason about, and diffing one
+ *    encoding while writing another is the kind of bug that only shows up on
+ *    someone else's machine.
+ *  - The `'resize'` SUBSCRIPTION (I-8 / P0-2). Ink renders SYNCHRONOUSLY from its
+ *    own `'resize'` handler while the frame's height is still the pre-resize one
+ *    — `useTerminalSize` debounces by 50 ms — so the line count is unchanged
+ *    across that window and the differ's line-count guard cannot see the resize.
+ *    Meanwhile the emulator has re-flowed the alternate screen, so every row the
+ *    differ believes unchanged is a row it will not repaint, for the rest of the
+ *    drag. It goes on the REAL stream, not the `Proxy`, and `dispose()` removes
+ *    it.
+ */
+/** The only encodings for which the chunk string IS the bytes on the wire. */
+function isUtf8Encoding(encoding) {
+    const e = encoding.toLowerCase();
+    return e === 'utf8' || e === 'utf-8';
+}
+export function wrapStdoutForFrames(stdout, differ) {
+    const bound = new Map();
+    const writeReal = (chunk, encoding, cb) => {
+        if (encoding !== undefined)
+            return stdout.write(chunk, encoding, cb);
+        return stdout.write(chunk, cb);
+    };
+    /**
+     * All three Node overloads: `write(chunk)`, `write(chunk, cb)`,
+     * `write(chunk, encoding, cb)`.
+     */
+    const write = (chunk, encodingOrCb, maybeCb) => {
+        const encoding = typeof encodingOrCb === 'string' ? encodingOrCb : undefined;
+        const cb = typeof encodingOrCb === 'function'
+            ? encodingOrCb
+            : typeof maybeCb === 'function'
+                ? maybeCb
+                : undefined;
+        // Foreign by construction: Ink never writes Buffers, and a non-UTF-8
+        // encoding means the string is not the bytes (P1-4).
+        if (typeof chunk !== 'string' || (encoding !== undefined && !isUtf8Encoding(encoding))) {
+            differ.invalidate();
+            return writeReal(chunk, encoding, cb);
+        }
+        const out = differ.transform(chunk);
+        if (out === null)
+            return writeReal(chunk, encoding, cb);
+        // Nothing to write, but the callback is still part of the contract — a
+        // skipped `cb` strands whatever was waiting on the drain.
+        if (out.length === 0) {
+            cb?.();
+            return true;
+        }
+        return writeReal(out, encoding, cb);
+    };
+    const onResize = () => differ.invalidate();
+    stdout.on('resize', onResize);
+    let disposed = false;
+    const proxy = new Proxy(stdout, {
+        get(target, prop) {
+            if (prop === 'write')
+                return write;
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== 'function')
+                return value;
+            // Cached so repeated property access does not allocate a new bound
+            // function on a hot path (K-9).
+            let fn = bound.get(prop);
+            if (fn === undefined) {
+                fn = value.bind(target);
+                bound.set(prop, fn);
+            }
+            return fn;
+        },
+    });
+    return {
+        stdout: proxy,
+        stats: () => differ.stats(),
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            stdout.off('resize', onResize);
+        },
+    };
+}

package/package.json

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