@aragon-agent/cli 0.5.9 → 0.5.11

package/dist/cli.js

@@ -23,7 +23,7 @@ import { formatMigrationNotice, migrateLegacyState } from './config/migrate-lega
 import { formatHomeMigrationNotice, migrateToHome } from './config/migrate-home.js';
 import { migrateStateOutOfConfig } from './config/migrate-state-out-of-config.js';
 import { runHistoryCommand } from './config/history-commands.js';
-import { FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
+import { FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, UPDATE_CONFIG_SET_KEYS, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, applyUpdateConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.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';
@@ -41,6 +44,15 @@ import { renderTranscriptText } from './ui/transcript-text.js';
 import { detectCapabilities } from './ui/capabilities.js';
 import { pickGlyphs } from './ui/glyphs.js';
 import { DENY_ALL_HUMAN_INPUT } from './tools/human-input.js';
+// A VALUE import, and the one deliberate exception to the paragraph above
+// (cli-auto-update-hardening P2-7). `boot/guard.js` statically pulls
+// `update/state.js`, so `aragon -p` now EVALUATES that module - it is pure at
+// module scope, calls nothing, and `update-wiring.test.ts` walks the transitive
+// graph against an allow-list so it cannot quietly grow. The alternative, a
+// dynamic import for a two-line disarm on the hottest path in the file, buys
+// nothing: the guard has already loaded and read the same module milliseconds
+// earlier, in the launcher.
+import { markBootHealthy } from './boot/guard.js';
 // ---------------------------------------------------------------------------
 // Version (read from the shipped package.json next to dist/)
 // ---------------------------------------------------------------------------
@@ -131,6 +143,25 @@ 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
+        // `CliFlags`, AND a line here; miss this one and the flag is inert with no
+        // compile error and no runtime error. It bites hardest here of all: this is
+        // the KILL SWITCH for a feature that installs software, so a missing line
+        // means `--no-update` reports nothing, does nothing, and leaves the updater
+        // running.
+        update: opts.update,
     };
 }
 // ---------------------------------------------------------------------------
@@ -206,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.
  *
@@ -254,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;
@@ -302,7 +381,26 @@ function runInteractive(flags, extras = {}) {
             process.exit(128 + signo);
         });
     }
-    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, mouseSource: mouseFilter?.source }), 
+    // --- Auto-update (cli-auto-update section 3.8). --------------------------
+    //
+    // THE ONLY CONSTRUCTION SITE. `runOneShot` / `runHeadless` never reach this
+    // function, so `aragon -p` executes zero update code and its stdout is
+    // byte-identical to a pre-feature build (AC-1); `aragon config <subcommand>`,
+    // `aragon logs`, `aragon skills` and `aragon --version` likewise. Bare
+    // `aragon config` DOES construct it, because it is a full interactive session
+    // with a settings overlay on top - which is correct, and is why AC-1's claim
+    // names the SUBCOMMAND form.
+    //
+    // `CI` is excluded on top of the two TTY tests because a CI runner with a pty
+    // allocated is otherwise a machine that silently mutates its own global
+    // toolchain mid-pipeline (D-11).
+    const updateBridge = { service: null, onAttach: null };
+    let updateService = null;
+    const updateEligible = !!process.stdout.isTTY &&
+        !!process.stdin.isTTY &&
+        !process.env.CI &&
+        config.update.mode !== 'off';
+    const instance = render(_jsx(App, { controller: controller, version: VERSION, mode: mode, confirmBridge: confirmBridge, humanInputBridge: humanInputBridge, initialPrompt: extras.initialPrompt, initialOverlay: extras.initialOverlay, mouseSource: mouseFilter?.source, updateBridge: updateEligible ? updateBridge : undefined }), 
     // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
     // straight to stdout and permanently shifts the fixed frame's accounting.
     {
@@ -311,7 +409,50 @@ 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
+    // (cli-auto-update-hardening section 5.1.4). It is what makes a long session
+    // that is later `SIGKILL`ed - terminal window closed, machine slept badly, OOM
+    // killer - still count as healthy.
+    //
+    // UNGATED BY `updateEligible` ON PURPOSE. The guard is armed only by an
+    // auto-install, which `mode: 'off'` already prevents, so on a machine that
+    // never armed it this is one read and one string compare. Gating it would mean
+    // a user who switches `mode` to `off` between the install and the next launch
+    // leaves the guard armed with nothing able to disarm it.
+    markBootHealthy(VERSION);
+    if (updateEligible) {
+        // DYNAMIC, and fire-and-forget AFTER `render()` (D-25). Dynamic because a
+        // static import would make AC-1 false for `aragon -p`, which shares this
+        // module and has no bundler to shake the subsystem out; after `render()`
+        // because the service must never be able to delay or fail the first frame.
+        // The `.catch` is not decoration: a subsystem that cannot even be imported
+        // must degrade to "no updater", never to a crashed TUI.
+        void import('./update/service.js')
+            .then(({ UpdateService }) => {
+            const service = new UpdateService({ config: config.update, currentVersion: VERSION });
+            updateService = service;
+            updateBridge.service = service;
+            // `App` may have mounted first and parked its listener here; it may also
+            // not have mounted yet, in which case its own effect reads
+            // `bridge.service` directly. Both orders happen (IF-4).
+            updateBridge.onAttach?.(service);
+            service.start();
+        })
+            .catch((err) => {
+            logger.warn('update', 'update_service_unavailable', {
+                reason: err instanceof Error ? err.message : String(err),
+            });
+        });
+    }
     // The return value MUST be captured — `waitUntilExit()` is the normal-exit
     // restore path and it cannot be registered otherwise. `dispose()` runs on
     // BOTH branches (I-7): a live `'data'` listener on stdin keeps the event loop
@@ -329,16 +470,33 @@ 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.
         controller.dispose();
+        // BOTH BRANCHES, exactly as `controller.dispose()` is (section 3.6 / P2-6),
+        // and idempotent for the same reason. It clears the timers and drops the
+        // listeners; it NEVER signals the installer child (U-3), because killing a
+        // running `npm install -g` is the one action here that can leave the
+        // user's global installation broken - and it would be triggered by the
+        // most ordinary event there is, the user pressing Ctrl+C. The signal path
+        // above calls `process.exit()` and reaches neither branch, which is
+        // correct and is precisely WHY U-3 matters: the detached child survives
+        // that exit and completes.
+        updateService?.dispose();
         replayTranscript();
     })
         .catch(() => {
         screen?.restore();
         disposeMouse();
+        disposeFrameWriter();
         controller.dispose();
+        updateService?.dispose();
     });
 }
 async function runOneShot(flags, prompt, quiet) {
@@ -432,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',
@@ -471,6 +633,8 @@ const CONFIG_SET_KEYS = new Set([
     ...RETRY_CONFIG_SET_KEYS,
     // `fast.*` keys are handled by `applyFastConfigSet`, same reasoning again.
     ...FAST_CONFIG_SET_KEYS,
+    // `update.*` keys are handled by `applyUpdateConfigSet`, same reasoning again.
+    ...UPDATE_CONFIG_SET_KEYS,
 ]);
 /**
  * `aragon config set maxTokens <n|auto|default>`.
@@ -546,6 +710,17 @@ function runConfigSet(key, value) {
         process.stdout.write(`Set ${key} = ${String(merged.fast[field])}\n`);
         return;
     }
+    const updatePatch = applyUpdateConfigSet(key, value);
+    if (updatePatch) {
+        // Echoed from the STORED value, so `config set update.checkIntervalMs 5`
+        // prints the clamped 900000 rather than reporting a number that was never
+        // written (AC-20) — the rule `team.*`, `retry.*` and `fast.*` each state
+        // above.
+        const merged = updatePersistedConfig(updatePatch);
+        const field = key.slice('update.'.length);
+        process.stdout.write(`Set ${key} = ${String(merged.update[field])}\n`);
+        return;
+    }
     const patch = {};
     switch (key) {
         case 'provider':
@@ -590,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;
@@ -662,6 +843,166 @@ function runConfigSet(key, value) {
     updatePersistedConfig(patch);
     process.stdout.write(`Set ${key} = ${value}\n`);
 }
+/**
+ * Exit codes (cli-auto-update section 4.3): `0` = up to date, or installed;
+ * `1` = the check or the install failed; `2` = an install source we will not
+ * install for (the advice line is printed); `4` = `--rollback` had nothing to
+ * roll back to (cli-auto-update-hardening section 6.2 / P2-8).
+ *
+ * A SOURCE WE DECLINE IS `2` AND NOT `1`, and the difference matters to the only
+ * consumer that reads an exit code - a script. `1` says "try again later"; `2`
+ * says "this machine will never auto-update, run the command we printed".
+ */
+function updateExitCode(snapshot) {
+    // REASON BEFORE PHASE, and the order is the whole change (P1-1). The three
+    // classified failures all arrive with `phase: 'failed'` - they come from
+    // `recordFailure` - so leaving the phase test first, as it was, means these
+    // two lines can never be reached and the mapping is a silent no-op.
+    //
+    // THIS IS A BEHAVIOUR CHANGE FOR SCRIPTS AND IS CALLED ONE (R-23). A
+    // `blocked-by-os` install used to exit `1` ("try again later") and now exits
+    // `2` ("this machine will never auto-update, run the command we printed").
+    // That is the honest answer - on Windows the same `npm i -g` from the same
+    // shell fails the same way until the user closes something - and it is
+    // recorded in the CHANGELOG under the version that ships it.
+    if (snapshot.reason === 'blocked-by-os' || snapshot.reason === 'no-space')
+        return 2;
+    if (snapshot.reason === 'source-ineligible' || snapshot.reason === 'not-writable')
+        return 2;
+    if (snapshot.phase === 'failed')
+        return 1;
+    if (snapshot.reason === 'install-ineffective')
+        return 1;
+    return 0;
+}
+/** Human output: three lines at most (section 4.3). */
+function formatUpdateResult(snapshot) {
+    const lines = [];
+    switch (snapshot.phase) {
+        case 'ready':
+            lines.push(`Installed ${snapshot.latestVersion ?? ''}. Restart aragon to apply.`);
+            break;
+        case 'available':
+            lines.push(snapshot.reason === 'install-ineffective'
+                ? `${snapshot.latestVersion ?? 'The new version'} installed somewhere else - ` +
+                    'check your npm prefix.'
+                : `${snapshot.latestVersion ?? 'A new version'} is available ` +
+                    `(running ${snapshot.currentVersion}).`);
+            if (snapshot.advice)
+                lines.push(`  ${snapshot.advice}`);
+            break;
+        case 'failed':
+            lines.push('Update failed. See the log for details.');
+            if (snapshot.advice)
+                lines.push(`  ${snapshot.advice}`);
+            break;
+        default:
+            lines.push(`aragon ${snapshot.currentVersion} is up to date.`);
+            break;
+    }
+    if (snapshot.reason && snapshot.phase !== 'ready')
+        lines.push(`  (${snapshot.reason})`);
+    return lines.slice(0, 3).join('\n');
+}
+/**
+ * `aragon update --rollback` - the MANUAL form of the boot guard's rollback
+ * (cli-auto-update-hardening section 6.2).
+ *
+ * It exists because a release can be BAD WITHOUT FAILING TO START, which is the
+ * case non-goal 2 declines to detect automatically precisely because a human
+ * detects it in one second. It shares `performRollback` verbatim, so the latch,
+ * the re-classification, the lock and the post-install verification are the same
+ * code the automatic path uses.
+ *
+ * Exit `4` for "nothing to roll back to" is a fourth code on a documented
+ * contract, so the contract's own comment above moves with it (P2-8). A rollback
+ * that RAN and failed is an ordinary failed install and keeps exit `1`.
+ */
+async function runRollbackCommand() {
+    const { readUpdateState, updateUpdateState } = await import('./update/state.js');
+    const good = readUpdateState().lastGoodVersion;
+    if (!good) {
+        process.stderr.write('Nothing to roll back to: no previous version was recorded by an auto-update.\n');
+        return 4;
+    }
+    if (good === VERSION) {
+        process.stdout.write(`aragon ${VERSION} is already the last known-good version.\n`);
+        return 0;
+    }
+    const { performRollback } = await import('./boot/rollback.js');
+    const result = await performRollback(VERSION, good);
+    if (!result.ok) {
+        process.stderr.write(`Rollback to ${good} did not complete (${result.failure}).\n`);
+        return 1;
+    }
+    // THE NOTICE IS FOR A DOWNGRADE THE USER DID NOT ASK FOR, AND THIS ONE WAS
+    // TYPED. `performRollback` sets `rolledBackFrom` because it cannot tell which
+    // caller it has, and the field has exactly one rendering: `rolled back to <to>
+    // after <bad> FAILED TO START` (section 8). On this path that sentence is
+    // false - the version started fine, the user simply did not want it - and a
+    // bottom row asserting a crash that never happened is worse than no row.
+    //
+    // Clearing it here rather than teaching `performRollback` a mode keeps the
+    // "verbatim shared mechanism" of section 6.2 intact and adds no fifth state
+    // field under C-17. D-38's purpose survives: the notice exists so a SILENT
+    // downgrade cannot go unnoticed, and the line below is this one's notice.
+    // `/update status` still shows `lastgood`, and `update_rolled_back` is in the
+    // log either way.
+    updateUpdateState({ rolledBackFrom: '' });
+    process.stdout.write(`Rolled back to ${good}. Restart aragon to apply.\n`);
+    return 0;
+}
+/**
+ * `aragon update` - a deliberate, foreground check.
+ *
+ * PRINTS TO STDOUT, unlike every other update surface in this package: here the
+ * update IS the command's output, so C-10's "the TUI is the only legal visible
+ * channel" does not apply - there is no TUI.
+ *
+ * Reached through the SAME dynamic `import()` the interactive gate uses, so
+ * `dist/cli.js` still carries no static specifier under `update/` (AC-1).
+ */
+async function runUpdateCommand(flags, opts) {
+    const config = loadConfig(flags);
+    getLogger().reconfigure(config.log);
+    const { UpdateService } = await import('./update/service.js');
+    const service = new UpdateService({
+        // `--check` is exactly `mode: 'notify'` FOR THIS RUN, and expressing it that
+        // way rather than with a second flag through the service means there is one
+        // code path deciding whether to install, not two.
+        config: opts.check ? { ...config.update, mode: 'notify' } : config.update,
+        currentVersion: VERSION,
+    });
+    try {
+        if (opts.rollback)
+            return await runRollbackCommand();
+        const target = opts.to?.trim();
+        if (target) {
+            // REPORTED, not silently ignored. `installNow` also refuses a malformed
+            // version (it is the one entry point whose target comes straight from
+            // argv), but there the refusal is a no-op snapshot that would exit 0 and
+            // tell the user they are up to date — which is a lie about the command
+            // they actually typed.
+            const { STRICT_VERSION_RE } = await import('./update/semver.js');
+            if (!STRICT_VERSION_RE.test(target)) {
+                process.stderr.write(`Not a version: "${target}". Use e.g. --to 0.6.0\n`);
+                return 1;
+            }
+        }
+        const snapshot = target
+            ? await service.installNow(target)
+            : await service.checkNow({ force: true });
+        process.stdout.write(opts.json ? `${JSON.stringify(snapshot)}\n` : `${formatUpdateResult(snapshot)}\n`);
+        return updateExitCode(snapshot);
+    }
+    catch (err) {
+        process.stderr.write(`update failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    finally {
+        service.dispose();
+    }
+}
 // ---------------------------------------------------------------------------
 // CLI definition
 // ---------------------------------------------------------------------------
@@ -751,6 +1092,14 @@ function buildProgram() {
         .option('--fast-model <id>', 'The fast model id (implies nothing about --fast)')
         .option('--fast-provider <id>', 'Provider for the fast model (default: the main provider)')
         .option('--fast-review <n|off>', 'Turns between automatic fast reviews, or "off"')
+        // BOTH FORMS, positive first, for the reason recorded seven times above —
+        // and this is the pair whose omission would be worst. `update.mode` is
+        // PERSISTED and defaults to `'auto'`, so a lone `--no-update` would make
+        // commander default `opts.update` to `true` and silently overwrite a stored
+        // `off` on EVERY run that passed no flag at all: the kill switch for a
+        // feature that installs software would quietly un-set itself (C-11).
+        .option('--update', 'Check for and install updates in the background (the default)')
+        .option('--no-update', 'Disable auto-update for this session')
         .option('--no-skills', 'Disable the skill system entirely (no catalog, no skill tools)')
         .option('--skill <name>', 'Force-load a skill at Level 2 for this run (repeatable)', (value, previous = []) => [...previous, value])
         .option('--skills-yes', 'Approve skill installs for this run (CI / headless)')
@@ -772,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) => {
@@ -881,6 +1239,22 @@ function buildProgram() {
         const code = await runSkillsCommand(subcommand ?? 'list', argument, opts, toFlags(program.opts()), VERSION);
         process.exitCode = code;
     });
+    // aragon update [--check] [--to <version>] [--json]
+    //
+    // THE GUARANTEED REPORTING SURFACE (C-12 / D-18), and the only update path
+    // available to a headless user at all - `runInteractive` is the sole place the
+    // background service is constructed, so without this command `aragon -p` users
+    // could never update deliberately.
+    program
+        .command('update')
+        .description('Check for a new release and install it')
+        .option('--check', 'Report only; never install')
+        .option('--to <version>', 'Install an exact version (an explicit escape hatch)')
+        .option('--rollback', 'Reinstall the version that ran before the last auto-update')
+        .option('--json', 'Machine-readable result on stdout')
+        .action(async (opts) => {
+        process.exitCode = await runUpdateCommand(toFlags(program.opts()), opts);
+    });
     // aragon models [--provider p]
     program
         .command('models')

package/dist/commands/builtins.js

@@ -31,6 +31,62 @@ import { perfCommand } from './perf.js';
  * feature that is spending money is the same class of lie as pricing a Haiku
  * child at Sonnet rates.
  */
+/**
+ * `/update status` - the human-readable readout (cli-auto-update §4.4).
+ *
+ * ASCII ONLY and NO GLYPHS: this string goes into a transcript `notice`, which
+ * `Transcript.tsx` renders with its own marker; the glyph tier belongs to the
+ * bottom-row line, not here. Everything a user could want to act on is named:
+ * what is running, what is available, how it got installed, and when we look
+ * again.
+ */
+function formatUpdateStatus(port, override) {
+    const snapshot = override ?? port.snapshot();
+    const lines = [
+        `Auto-update: ${snapshot.phase}`,
+        `  running   ${snapshot.currentVersion}`,
+        `  latest    ${snapshot.latestVersion ?? 'unknown'}`,
+        `  source    ${snapshot.source}`,
+    ];
+    if (snapshot.reason)
+        lines.push(`  reason    ${snapshot.reason}`);
+    if (snapshot.advice)
+        lines.push(`  install   ${snapshot.advice}`);
+    // The three hardening lines, each only when it has something to say
+    // (cli-auto-update-hardening section 6.3).
+    //
+    // THE KEY COLUMN IS TEN WIDE, WHICH IS WHY THE FIRST KEY IS `rollback` AND NOT
+    // `rolledback`. Section 6.3 asks for "a padded key, matching the six lines
+    // `formatUpdateStatus` already emits", and every one of those pads the key to
+    // ten so the values start in the same column - the entire reason a readout is
+    // padded at all. `rolledback` is ten characters on its own, so it cannot take
+    // a separating space without pushing its value one column past the other six,
+    // which is the misalignment the padding exists to prevent. The spec's sample
+    // block is internally consistent (all three new lines at eleven) and
+    // inconsistent with the six it says it matches; the prose is the requirement.
+    //
+    // THE ROLLBACK LINE CARRIES NO FAILURE COUNT on purpose: `bootFailures` is
+    // zeroed by the rollback itself, so any number printed here would be `0`. The
+    // count that mattered is in the `update_rolled_back` log record.
+    if (snapshot.rolledBackFrom) {
+        const to = snapshot.rolledBackTo ?? snapshot.currentVersion;
+        lines.push(`  rollback  ${snapshot.rolledBackFrom} -> ${to}`);
+    }
+    // What `aragon update --rollback` would reinstall. This is the only place a
+    // user can find that out BEFORE running the command.
+    if (snapshot.lastGoodVersion)
+        lines.push(`  lastgood  ${snapshot.lastGoodVersion}`);
+    // The only place a user can learn their machine updates through the fallback.
+    if (snapshot.probe) {
+        lines.push(`  probe     ${snapshot.probe === 'npm' ? 'npm (proxy fallback)' : 'http'}`);
+    }
+    if (snapshot.consecutiveFailures > 0) {
+        lines.push(`  failures  ${snapshot.consecutiveFailures} in a row`);
+    }
+    const next = override ? port.nextCheckAt() : snapshot.nextCheckAt;
+    lines.push(`  next      ${next ? new Date(next).toLocaleTimeString() : 'not scheduled'}`);
+    return lines.join('\n');
+}
 function formatFastStatus(controller) {
     const status = controller.getFastStatus();
     const cfg = controller.getFastConfig();
@@ -458,6 +514,68 @@ const COMMANDS = [
                 'delegate on|off].');
         },
     },
+    {
+        name: 'update',
+        description: 'Auto-update: status | now | skip | off',
+        /**
+         * THE GUARANTEED REPORTING SURFACE for the updater (C-12 / D-18).
+         *
+         * The bottom row can be preempted by a toast or by the activity line, and it
+         * is deliberately last in that precedence (D-2), so a user who is actually
+         * working may never see it. This command always answers "is it on, what did
+         * it find, and when does it look again".
+         *
+         * REACHES THE SERVICE THROUGH `ctx.update`, NOT THROUGH `ctx.controller`
+         * (C-14 / P0-2). `/fast`, `/team` and `/todo` ride on the controller because
+         * their subsystems live there; `update/` may not import `agent/` at all, so
+         * it carries its own optional port. `undefined` is a legitimate state - `off`,
+         * a non-TTY, or CI - and says so rather than pretending to have failed.
+         */
+        run: (ctx) => {
+            const arg = ctx.args.trim();
+            const [rawVerb] = arg.split(/\s+/, 1);
+            const verb = (rawVerb ?? '').toLowerCase();
+            const port = ctx.update;
+            // `/update off` is the one branch that works WITHOUT a service: turning
+            // something off must not require it to be running, or a user who launched
+            // with `--no-update` can never make that stick.
+            if (verb === 'off') {
+                ctx.persistConfig({ update: { mode: 'off' } });
+                ctx.toast('success', 'Auto-update off. Takes effect on the next launch.');
+                return;
+            }
+            if (!port) {
+                ctx.notify('info', 'Updates are disabled for this session (update.mode: off, a non-TTY, or CI). ' +
+                    'Enable with: aragon config set update.mode auto');
+                return;
+            }
+            if (!verb || verb === 'status') {
+                ctx.notify('info', formatUpdateStatus(port));
+                return;
+            }
+            if (verb === 'now') {
+                // `force: true` bypasses the machine-wide throttle - a human typing this
+                // is the one caller entitled to ignore `lastCheckAt`.
+                void port
+                    .checkNow({ force: true })
+                    .then((snapshot) => ctx.notify('info', formatUpdateStatus(port, snapshot)))
+                    .catch(() => ctx.notify('warn', 'Update check failed. See the log for details.'));
+                ctx.toast('info', 'Checking for updates...');
+                return;
+            }
+            if (verb === 'skip') {
+                const version = port.snapshot().latestVersion;
+                if (!version) {
+                    ctx.notify('info', 'No update is being offered, so there is nothing to skip.');
+                    return;
+                }
+                port.skip(version);
+                ctx.toast('success', `Skipped ${version}. You will hear about the next release.`);
+                return;
+            }
+            ctx.notify('warn', `Unknown argument "${verb}" - use /update [status|now|skip|off].`);
+        },
+    },
     {
         name: 'todo',
         description: 'Todo planning: status | on | off | panel on|off | follow <mode> | clear | continue',

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;