@aragon-agent/cli 0.5.9 → 0.5.11

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;
 /**
@@ -434,6 +451,44 @@ export declare const DEFAULT_FAST_CONFIG: FastConfig;
  * user really did configure a dead vendor as the MAIN one.
  */
 export declare function clampFastConfig(raw: unknown): FastConfig;
+/** `auto` installs; `notify` only reports; `off` disables the subsystem. */
+export declare const UPDATE_MODES: readonly ["auto", "notify", "off"];
+export type UpdateMode = (typeof UPDATE_MODES)[number];
+export declare function isUpdateMode(v: unknown): v is UpdateMode;
+export interface UpdateConfig {
+    /**
+     * Whether the updater installs, merely reports, or does nothing at all.
+     *
+     * DEFAULTS TO `'auto'`, and that is a PRODUCT decision rather than a technical
+     * one: this CLI's users are overwhelmingly on a stale version they did not
+     * choose. The trade it makes — a wider supply-chain window in exchange for
+     * users who are actually on the current release — is stated plainly in the
+     * README (R-1), and `'off'` plus `ARAGON_UPDATE=0` are the documented kill
+     * switches.
+     */
+    mode: UpdateMode;
+    /** Minimum wall-clock between registry checks, MACHINE-WIDE (§3.7). */
+    checkIntervalMs: number;
+    /** `''` = derive: `ARAGON_UPDATE_REGISTRY` › `npm_config_registry` › npmjs. */
+    registry: string;
+    /** The dist-tag to track. */
+    distTag: string;
+}
+export declare const DEFAULT_UPDATE_CONFIG: UpdateConfig;
+/**
+ * THE single gate for every update-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * / `clampRetryConfig` / `clampFastConfig` for the reason all six record:
+ * hardening only the read path leaves a bad value on disk that reverts to the
+ * default on every launch, which presents to the user as "my setting won't
+ * stick".
+ *
+ * `registry` is CLAMPED TO `''` rather than rejected when it is not an
+ * `http(s):` URL. `''` means "derive it" (§3.3), which is the safe reading of a
+ * typo — the alternative is a background timer that throws on a value the user
+ * cannot see it reading.
+ */
+export declare function clampUpdateConfig(raw: unknown): UpdateConfig;
 export interface PersistedConfig {
     version: number;
     provider: string;
@@ -492,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;
@@ -537,6 +596,8 @@ export interface PersistedConfig {
     retry: RetryConfig;
     /** Fast model tier. The SEVENTH nested object; scalars only (see FastConfig). */
     fast: FastConfig;
+    /** Auto-update. The EIGHTH nested object; scalars only (see UpdateConfig). */
+    update: UpdateConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -631,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;
@@ -709,6 +784,22 @@ export interface CliConfig {
      * `/provider`, `/reload` and the settings screen.
      */
     fast: FastConfig;
+    /**
+     * Resolved auto-update settings (cli-auto-update §4.1).
+     *
+     * `mode` here decides whether `runInteractive` CONSTRUCTS the service at all
+     * (§3.8), which is what makes `'off'` byte-identical to a pre-feature build:
+     * no timer, no file read, no socket. The other three keys are read by the
+     * service on every check, so a `/update off` mid-session stops the next one.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `showThinking` and `liveToolOutput` each record above: the gate reads
+     * `cfg.update`, where `cfg` 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 gate. `--no-update` and `ARAGON_UPDATE=0` would parse
+     * and be discarded, with no compile error and no runtime error.
+     */
+    update: UpdateConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *

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
@@ -570,6 +594,81 @@ export function clampFastConfig(raw) {
         reviewMaxPerSession: clampInt(src.reviewMaxPerSession, DEFAULT_FAST_CONFIG.reviewMaxPerSession, REVIEW_SESSION_RANGE),
     };
 }
+// ---------------------------------------------------------------------------
+// Auto-update (cli-auto-update §4.1)
+//
+// The EIGHTH nested section in the persisted config, after `apiKeys`, `skills`,
+// `log`, `team`, `todo`, `retry` and `fast` — and, like all of them, SCALARS
+// ONLY, exactly one level deep. `store.ts` merges these sections BY HAND and
+// that merge is only correct while nesting stays flat (C-5).
+//
+// BOTH OF `store.ts`'s MERGES MUST LEARN ABOUT THIS SECTION, AND THE OMISSION IS
+// SILENT (C-4 / R-10). `config set update.mode notify` sends
+// `{ update: { mode: 'notify' } }`; without the write merge the shallow
+// top-level spread REPLACES the whole section and `checkIntervalMs`, `registry`
+// and `distTag` silently revert on disk. This package has paid for that twice
+// already — `todo` P0-1 and `fast` R-10 — which is why it is written down a
+// third time rather than assumed to be common knowledge.
+//
+// FOUR KEYS AND NO MORE (D-16). `mode` covers on / notify / off; a fifth key
+// (`autoInstall`) would be a second way to say the same thing, and two ways to
+// express one setting is how they end up disagreeing.
+// ---------------------------------------------------------------------------
+/** `auto` installs; `notify` only reports; `off` disables the subsystem. */
+export const UPDATE_MODES = ['auto', 'notify', 'off'];
+export function isUpdateMode(v) {
+    return typeof v === 'string' && UPDATE_MODES.includes(v);
+}
+export const DEFAULT_UPDATE_CONFIG = {
+    mode: 'auto',
+    // FOUR HOURS, in ms. `checkIntervalMs` and not `checkIntervalHours` (D-17):
+    // every other duration in this config is in ms (`toolTimeoutMs`,
+    // `idleTimeoutMs`, `team.dispatchTimeoutMs`, `retry.initialDelayMs`), and one
+    // unit per file is worth more than one shorter number.
+    checkIntervalMs: 14_400_000,
+    registry: '',
+    distTag: 'latest',
+};
+/** 15 minutes to 7 days. The floor is a politeness bound on the registry. */
+const UPDATE_INTERVAL_RANGE = { min: 900_000, max: 604_800_000 };
+/** npm's own dist-tag grammar, loosely: no slashes, no spaces, no `@`. */
+const DIST_TAG_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+/**
+ * THE single gate for every update-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * / `clampRetryConfig` / `clampFastConfig` for the reason all six record:
+ * hardening only the read path leaves a bad value on disk that reverts to the
+ * default on every launch, which presents to the user as "my setting won't
+ * stick".
+ *
+ * `registry` is CLAMPED TO `''` rather than rejected when it is not an
+ * `http(s):` URL. `''` means "derive it" (§3.3), which is the safe reading of a
+ * typo — the alternative is a background timer that throws on a value the user
+ * cannot see it reading.
+ */
+export function clampUpdateConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    const registry = text(src.registry, DEFAULT_UPDATE_CONFIG.registry);
+    const distTag = text(src.distTag, DEFAULT_UPDATE_CONFIG.distTag);
+    return {
+        mode: isUpdateMode(src.mode) ? src.mode : DEFAULT_UPDATE_CONFIG.mode,
+        checkIntervalMs: clampInt(src.checkIntervalMs, DEFAULT_UPDATE_CONFIG.checkIntervalMs, UPDATE_INTERVAL_RANGE),
+        registry: isRegistryUrl(registry) ? registry : DEFAULT_UPDATE_CONFIG.registry,
+        distTag: DIST_TAG_RE.test(distTag) ? distTag : DEFAULT_UPDATE_CONFIG.distTag,
+    };
+}
+function isRegistryUrl(raw) {
+    if (raw.length === 0)
+        return false;
+    try {
+        const url = new URL(raw);
+        // `http:` is accepted for a LAN mirror; nothing else is a registry.
+        return url.protocol === 'https:' || url.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
 export const DEFAULT_CONFIG = {
     version: CONFIG_VERSION,
     provider: 'anthropic',
@@ -594,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,
@@ -621,6 +722,12 @@ export const DEFAULT_CONFIG = {
     // falsy and so LOOKS correct — right up until `/fast on` writes a section that
     // has no other keys in it (P0-1's shape, one feature later).
     fast: DEFAULT_FAST_CONFIG,
+    // And one section later again, for the third time. Without this line a user
+    // whose `config.json` predates auto-update resolves `config.update.mode` to
+    // `undefined`, which is neither `'auto'` nor `'off'` — so the §3.8 gate
+    // (`cfg.update.mode !== 'off'`) would read TRUE and the feature would be on
+    // for a reason nobody could point at.
+    update: DEFAULT_UPDATE_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake

package/dist/config/store.js

@@ -14,7 +14,7 @@ import { dirname } from 'node:path';
 import process from 'node:process';
 import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
-import { CONFIG_VERSION, DEFAULT_CONFIG, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+import { CONFIG_VERSION, DEFAULT_CONFIG, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -134,6 +134,11 @@ export function loadPersistedConfig() {
         // READ half of the pair that keeps `/fast review 8` from silently switching
         // the whole tier off on the next launch (C-3 / R-10).
         fast: clampFastConfig({ ...DEFAULT_CONFIG.fast, ...(partial.fast ?? {}) }),
+        // `update` is the eighth. Same one-level rule, same merge — and the READ
+        // half is what supplies a whole section to every user whose `config.json`
+        // predates auto-update, which is all of them. Without it `config.update.mode`
+        // reads `undefined`, and the §3.8 gate tests `!== 'off'`.
+        update: clampUpdateConfig({ ...DEFAULT_CONFIG.update, ...(partial.update ?? {}) }),
     };
 }
 /**
@@ -196,6 +201,13 @@ export function updatePersistedConfig(patch) {
         // tomorrow with no error anywhere. This package has paid for that once
         // already, in `todo` (P0-1).
         fast: clampFastConfig({ ...current.fast, ...(patch.fast ?? {}) }),
+        // The eighth section, and the third time this file records the same trap.
+        // `config set update.mode notify` sends `{ update: { mode: 'notify' } }`;
+        // without this line the shallow top-level spread REPLACES the section,
+        // `checkIntervalMs` / `registry` / `distTag` are written absent, and an
+        // enterprise mirror the user configured last month is gone with no error
+        // anywhere. AC-20 is the assertion that proves both halves exist.
+        update: clampUpdateConfig({ ...current.update, ...(patch.update ?? {}) }),
     };
     writeConfigFile(merged);
     return merged;

package/dist/launcher.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The bin entry (cli-auto-update-hardening section 5.1.1).
+ *
+ * ASCII ONLY - this file is inside the glyph scanner's scope (C-19).
+ *
+ * KEEP IT THIS SMALL. Every import here is a module that can crash before the
+ * guard that exists to survive crashes. `node:process` is the only static one,
+ * and `__tests__/update-wiring.test.ts` asserts that on the source text.
+ *
+ * `dist/cli.js` IS UNCHANGED AND KEEPS ITS SHEBANG (R-17 / AC-50). Only the
+ * `bin` mapping moves; `npm start` (`node dist/cli.js`) and any user script that
+ * invokes `dist/cli.js` directly keep working byte for byte.
+ */
+export {};

package/dist/launcher.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * The bin entry (cli-auto-update-hardening section 5.1.1).
+ *
+ * ASCII ONLY - this file is inside the glyph scanner's scope (C-19).
+ *
+ * KEEP IT THIS SMALL. Every import here is a module that can crash before the
+ * guard that exists to survive crashes. `node:process` is the only static one,
+ * and `__tests__/update-wiring.test.ts` asserts that on the source text.
+ *
+ * `dist/cli.js` IS UNCHANGED AND KEEPS ITS SHEBANG (R-17 / AC-50). Only the
+ * `bin` mapping moves; `npm start` (`node dist/cli.js`) and any user script that
+ * invokes `dist/cli.js` directly keep working byte for byte.
+ */
+import process from 'node:process';
+try {
+    // DYNAMIC, AND THAT IS THE WHOLE POINT (P1-2 / R-22). A STATIC import of the
+    // guard would put `boot/guard -> update/state -> config/app-paths ->
+    // env-paths` in the bin entry's OWN module graph, and a resolution failure
+    // anywhere in that chain throws during THIS module's evaluation - outside the
+    // `try`, before any line of it runs. "An undeclared dependency" is the first
+    // way section 1.1 says a release bricks itself; a guard whose own import fails
+    // in that exact case has to degrade to "no guard", never to "no CLI".
+    const { runBootGuard } = await import('./boot/guard.js');
+    runBootGuard();
+}
+catch {
+    // A guard that throws must never be the reason the CLI will not start. This is
+    // the one catch in the package that is allowed to be empty: there is no logger
+    // yet, and there is nothing the user could do with the message.
+}
+// The `.catch` is for the IMPORT rejecting, which is precisely the import-time
+// crash H1 exists for and which today produces an unhandled rejection with a
+// stack the user cannot act on. `cli.js` runs `main()` at module scope and
+// installs its own `.catch` for everything after that point.
+//
+// EXITING NON-ZERO HERE IS WHAT FEEDS THE GUARD'S COUNTER (D-30a): the exit hook
+// the guard installed counts non-zero exits, and a module that will not import
+// raises, so it arrives here.
+await import('./cli.js').catch((err) => {
+    process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/logging/logger.d.ts

@@ -23,7 +23,7 @@
 import type { LogConfig } from '../config/schema.js';
 import { type LogLevelName } from './levels.js';
 /** Closed set, not free text: a typo'd scope is a record nobody can filter on. */
-export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history';
+export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update';
 export interface LogRecord {
     ts: string;
     lv: LogLevelName;

package/dist/ui/App.d.ts

@@ -8,6 +8,7 @@ import React from 'react';
 import type { AgentController } from '../agent/controller.js';
 import type { ConfirmRequest } from '../tools/index.js';
 import { type Overlay, type ToastLevel } from '../agent/reducer.js';
+import type { UpdateBridge } from '../update/types.js';
 import { type RenderMode } from './layout/frame.js';
 import type { MouseSource } from '../input/stdin-mouse-filter.js';
 import type { HumanInputBridge } from '../tools/human-input.js';
@@ -49,5 +50,14 @@ export interface AppProps {
      *  is off: inline mode, `--no-mouse`, a non-TTY, or a filter that failed to
      *  build (mouse-wheel-region-routing §4.2). */
     mouseSource?: MouseSource;
+    /**
+     * The auto-updater's late-arrival channel (cli-auto-update §3.8).
+     *
+     * A BRIDGE AND NOT THE SERVICE ITSELF, for the reason `confirmBridge` above is
+     * one: the service is built by a DYNAMIC `import()` fired after `render()`, so
+     * it does not exist when this component mounts. Absent under `update.mode:
+     * 'off'`, on a non-TTY, in CI, and in every test that does not exercise it.
+     */
+    updateBridge?: UpdateBridge;
 }
-export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, updateBridge, }: AppProps): React.ReactElement;

package/dist/ui/App.js

@@ -34,6 +34,15 @@ import { TodoPanel } from './TodoPanel.js';
 import { TodoStrip } from './TodoStrip.js';
 import { ActivityLine } from './ActivityLine.js';
 import { BottomStatusRow } from './BottomStatusRow.js';
+import { UpdateLine } from './UpdateLine.js';
+// The updater's two PURE modules. `shouldRenderUpdateLine` decides the row's
+// presence AT THE CALL SITE (C-15), and `UPDATE_LIMITS` owns the width
+// threshold - both are values, and both are resolved here rather than inside
+// `UpdateLine` so that component's only edge into `update/` stays erasable by
+// tsc (cli-auto-update section 3.1 rule 1 / IF-1). Neither module opens a
+// socket, spawns a process or creates a timer.
+import { shouldRenderUpdateLine } from '../update/types.js';
+import { UPDATE_LIMITS } from '../update/limits.js';
 import { AppShell } from './layout/AppShell.js';
 import { ScrollViewport } from './layout/ScrollViewport.js';
 import { todoRailRows, todoRailWidth } from './layout/rail.js';
@@ -101,7 +110,7 @@ export function resolveSettingsMaxTokens(raw, previous) {
 function seedViewState(thinkingVisible) {
     return initialViewState({ thinkingVisible });
 }
-export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, }) {
+export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, updateBridge, }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
     const fullscreen = mode === 'fullscreen';
@@ -125,6 +134,14 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     const [state, dispatch] = useReducer(viewReducer, cfg.showThinking, seedViewState);
     const [elapsedMs, setElapsedMs] = useState(0);
     const [confirmState, setConfirmState] = useState(null);
+    /**
+     * The updater's latest snapshot, or `null` while there is no service
+     * (cli-auto-update section 6.1).
+     *
+     * `UpdateSnapshot` is a VALUE OBJECT the service replaces wholesale on every
+     * transition, so this state can use referential equality and never diff fields.
+     */
+    const [updateSnapshot, setUpdateSnapshot] = useState(null);
     /** The request the question / plan overlay is currently rendering. */
     const [humanRequest, setHumanRequest] = useState(null);
     // Seeded from the history file, not from `CliConfig`: the list is no longer
@@ -200,6 +217,15 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // `ViewState` is a field `restoreEntries`, `/clear`, `/reset` and the session
     // round-trip each have to have an opinion about, and none of them has an
     // opinion about a 3-second timer.
+    /**
+     * Whether the one `installing -> ready` toast has already been pushed
+     * (cli-auto-update section 6.3).
+     *
+     * A REF AND NOT STATE: this must survive every re-render without causing one,
+     * and it is the whole of AC-19 - ten re-renders while the phase sits at
+     * `ready` must still produce exactly one toast.
+     */
+    const updateToastPushed = useRef(false);
     const budgetRef = useRef(emptyBudget());
     const followTimer = useRef(null);
     /** True while the run in flight was started by the grace timer, not the user. */
@@ -801,6 +827,48 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // --- Helpers -----------------------------------------------------------
     const notify = (level, text) => dispatch({ type: 'notice', level, text });
     const toast = (level, text) => dispatch({ type: 'pushToast', level, text });
+    // --- Auto-update bridge (cli-auto-update section 3.8 / 6.3). ------------
+    //
+    // TWO ARRIVAL ORDERS, AND BOTH HAPPEN. The service is built by a dynamic
+    // `import()` fired after `render()`, so on a warm module cache it can be
+    // attached BEFORE this effect runs, and on a cold one long after. Reading
+    // `bridge.service` first and installing `onAttach` second covers both without
+    // a race - the same shape `confirmBridge` uses one screen up.
+    useEffect(() => {
+        if (!updateBridge)
+            return undefined;
+        const bridge = updateBridge;
+        let unsubscribe = null;
+        const attach = (service) => {
+            setUpdateSnapshot(service.snapshot());
+            unsubscribe = service.subscribe(setUpdateSnapshot);
+        };
+        if (bridge.service)
+            attach(bridge.service);
+        else
+            bridge.onAttach = attach;
+        return () => {
+            bridge.onAttach = null;
+            unsubscribe?.();
+        };
+    }, [updateBridge]);
+    // ONE TOAST, ON THE `installing -> ready` EDGE ONLY (section 6.3 / AC-19).
+    //
+    // It exists because the moment of completion may arrive while the user is
+    // reading the transcript with the row occupied by a run: the toast wins the row
+    // for its TTL and then hands it back to the persistent line. The ref is what
+    // makes ten re-renders at `ready` push exactly one.
+    useEffect(() => {
+        if (updateSnapshot?.phase !== 'ready')
+            return;
+        if (updateToastPushed.current)
+            return;
+        updateToastPushed.current = true;
+        toast('info', `${updateSnapshot.latestVersion ?? 'Update'} installed - restart aragon to apply.`);
+        // `toast` is a stable dispatch wrapper; depending on it would re-run this on
+        // every render and defeat the ref guard's purpose rather than its mechanism.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [updateSnapshot?.phase, updateSnapshot?.latestVersion]);
     const persistConfig = (patch) => {
         try {
             updatePersistedConfig(patch);
@@ -858,6 +926,12 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         // Read at command time, so `/todo status` reports the live count rather than
         // whatever it was when this context was built.
         followBudget: budgetRef.current,
+        // Read at command time for the same reason, and additionally because the
+        // service ATTACHES LATE (section 3.8): a value captured when this closure was
+        // first created would be `undefined` for the whole session on a cold module
+        // cache, and `/update` would report "disabled" on a session where it is on.
+        // `?? undefined` because the bridge holds `null` and the port is optional.
+        update: updateBridge?.service ?? undefined,
     });
     /**
      * Submitting a prompt no longer touches `config.json` at all — it appends one
@@ -1379,7 +1453,19 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             // surface the run is not visible on. (Inline overlays are part of the
             // document flow, so there the suppression is conservative rather than
             // necessary — P2-5.)
-            activity: running && !overlayNode ? (_jsx(ActivityLine, { startedAt: runStartedAt.current, elapsedMs: elapsedMs, reducedMotion: reducedMotion, runningTool: runningTool, theme: theme, caps: caps })) : null, theme: theme }), composer: composer, status: _jsx(StatusBar, { model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, contextTokens: state.contextTokens, contextWindow: modelInfo.contextWindow, contextWindowKnown: modelKnown, status: state.status, elapsedMs: elapsedMs, thinkingLevel: cfg.thinkingLevel, tokPerSec: tokPerSec, theme: theme, caps: caps, scrolledLines: scrolledLines, redrawNonce: redrawNonce, agentMode: state.agentMode, pendingAgentMode: state.pendingAgentMode, ecoRung: governor.rung, ...(state.team
+            activity: running && !overlayNode ? (_jsx(ActivityLine, { startedAt: runStartedAt.current, elapsedMs: elapsedMs, reducedMotion: reducedMotion, runningTool: runningTool, theme: theme, caps: caps })) : null, 
+            // PRESENCE IS DECIDED HERE, NOT BY `UpdateLine` RETURNING `null`
+            // (C-15 / cli-auto-update P0-1 / D-19). `BottomStatusRow` tests this
+            // prop for truthiness, and a React element is truthy however it
+            // renders - so a component that rendered nothing would give the row
+            // ZERO rows and silently unbalance the frame budget. Same rule the
+            // activity line above follows with `running && !overlayNode`.
+            //
+            // `!overlayNode` for the same reason it appears there: the full-screen
+            // branch replaces the whole viewport with the overlay, and an update
+            // notice under a settings screen is noise attached to a surface it is
+            // not visible on.
+            update: updateSnapshot && !overlayNode && shouldRenderUpdateLine(updateSnapshot) ? (_jsx(UpdateLine, { snapshot: updateSnapshot, compact: cols < UPDATE_LIMITS.statusCompactCols, theme: theme, caps: caps })) : null, theme: theme }), composer: composer, status: _jsx(StatusBar, { model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, contextTokens: state.contextTokens, contextWindow: modelInfo.contextWindow, contextWindowKnown: modelKnown, status: state.status, elapsedMs: elapsedMs, thinkingLevel: cfg.thinkingLevel, tokPerSec: tokPerSec, theme: theme, caps: caps, scrolledLines: scrolledLines, redrawNonce: redrawNonce, agentMode: state.agentMode, pendingAgentMode: state.pendingAgentMode, ecoRung: governor.rung, ...(state.team
                 ? {
                     teamActive: {
                         running: state.team.runs.filter((r) => r.phase !== 'queued' && r.phase !== 'done' &&

package/dist/ui/BottomStatusRow.d.ts

@@ -26,8 +26,13 @@
  * Sharing the row means `budget.ts` and `AppShell.tsx` come out of this round
  * UNMODIFIED — and `budget.test.ts` asserts that they did (AC-8a, DoD #8).
  *
- * PRECEDENCE: a toast wins. A transient ack is a RESPONSE TO THE USER, and the
- * row nearest the input belongs to it.
+ * PRECEDENCE: toast > activity > update > blank. A toast wins because a
+ * transient ack is a RESPONSE TO THE USER, and the row nearest the input belongs
+ * to it. The update line is LAST because it is the only one of the three that is
+ * PERSISTENT (cli-auto-update D-2): it loses nothing by waiting for the run to
+ * end, whereas an activity line deferred is an activity line that never renders.
+ * That also means a user who is actively working never sees the updater at all
+ * until they stop, which is the whole of the silence requirement.
  */
 import React from 'react';
 import type { Theme } from './theme.js';
@@ -38,6 +43,23 @@ export interface BottomStatusRowProps {
     toasts: Toast[];
     /** `<ActivityLine>` while a run owns the screen, else `null`. */
     activity: React.ReactNode;
+    /**
+     * `<UpdateLine>` when the updater has something to say, else `null` — AND THE
+     * CALLER DECIDES WHICH (C-15 / cli-auto-update P0-1).
+     *
+     * `if (update)` below tests a REACT ELEMENT, and an element whose own render
+     * returns `null` is still truthy: that branch would emit a box of ZERO rows,
+     * the frame would keep its fixed height, Yoga would hand the row to the
+     * transcript, and `viewportRows()` would go on reporting the old number to
+     * five consumers. So `UpdateLine` is typed `React.ReactElement` and `App`
+     * gates it with `shouldRenderUpdateLine(snapshot)`.
+     *
+     * OPTIONAL, because `bottom-status-row.test.tsx` and the `App.tsx` fixtures
+     * construct this component without it and the test tree is inside
+     * `tsconfig.test.json` (`typecheck-scope.test.ts`); a required prop turns
+     * `npm run typecheck` red for a reason unrelated to this feature (P2-1).
+     */
+    update?: React.ReactNode;
     theme: Theme;
 }
-export declare function BottomStatusRow({ mode, toasts, activity, theme, }: BottomStatusRowProps): React.ReactElement | null;
+export declare function BottomStatusRow({ mode, toasts, activity, update, theme, }: BottomStatusRowProps): React.ReactElement | null;

package/dist/ui/BottomStatusRow.js

@@ -1,14 +1,17 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Box } from 'ink';
 import { ToastStack } from './ToastStack.js';
-export function BottomStatusRow({ mode, toasts, activity, theme, }) {
-    // A toast wins the row; so does an empty toast stack in full-screen, whose
-    // blank `<Text> </Text>` IS the budgeted row and must keep being emitted.
-    if (toasts.length > 0 || !activity) {
+export function BottomStatusRow({ mode, toasts, activity, update, theme, }) {
+    // A toast wins the row outright.
+    if (toasts.length > 0)
         return _jsx(ToastStack, { toasts: toasts, theme: theme, mode: mode });
-    }
     // Inline has no frame and therefore nothing to protect: `ToastStack`'s inline
-    // branch is already a conditional 0-3 row stack, and this is simply one more
+    // branch is already a conditional 0-3 row stack, and these are simply one more
     // conditional row above it.
-    return _jsx(Box, { flexShrink: 0, children: activity });
+    if (activity)
+        return _jsx(Box, { flexShrink: 0, children: activity });
+    if (update)
+        return _jsx(Box, { flexShrink: 0, children: update });
+    // The blank full-screen row that IS the budget must keep being emitted.
+    return _jsx(ToastStack, { toasts: toasts, theme: theme, mode: mode });
 }

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';