@aragon-agent/cli 0.5.9 → 0.5.10

package/dist/config/schema.js

@@ -570,6 +570,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',
@@ -621,6 +696,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/UpdateLine.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The update line (cli-auto-update section 6.2) - the THIRD occupant of the
+ * already-budgeted bottom row, after the toast stack and the activity line.
+ *
+ * ONE ROW, ALWAYS, AND NEVER `null` (C-15 / P0-1 / D-19). The return type is
+ * `React.ReactElement` rather than `React.ReactElement | null`, so the compiler
+ * refuses the shortcut: `BottomStatusRow` decides presence with `if (update)`,
+ * which tests a REACT ELEMENT, and an element whose render returns `null` is
+ * still truthy. Taking that branch would emit a box of ZERO rows - the frame
+ * keeps its fixed height, Yoga hands the row to the transcript, and
+ * `viewportRows()` goes on reporting the old number to `ScrollViewport`,
+ * `selectWindow`, `overlayMaxRows`, `popupMaxRows` and `todoRailRows`. The
+ * transcript would gain a row while the updater is idle and lose it the moment
+ * it has news. Presence is the CALLER's decision, through
+ * `shouldRenderUpdateLine`, exactly as `App.tsx` already decides the activity
+ * line's with `running && !overlayNode`.
+ *
+ * PURE: a function of `snapshot + compact + theme + caps`. No state, no timer,
+ * no clock. `<Text wrap="truncate">` so a narrow terminal degrades by truncation
+ * rather than by wrapping into a second row the fixed frame cannot afford.
+ *
+ * ASCII ONLY, and every user-visible character comes from `pickGlyphs(caps)`
+ * (C-3). No literal `...`, `+` or `~` may be spelled inline - `ActivityLine`'s
+ * routing of even the ellipsis through `pickGlyphs` is the precedent.
+ *
+ * `compact` RATHER THAN `cols` (IF-1). Section 6.2 describes the width tiers in
+ * terms of `cols`, but resolving them here would mean importing
+ * `UPDATE_LIMITS.statusCompactCols` - a VALUE - from `update/`, and section 3.1
+ * rule 1 requires this module's only edge into that tree to be erasable by tsc.
+ * The caller owns `UPDATE_LIMITS` already (it computes presence from it), so it
+ * resolves the threshold too. Same rule as presence: the call site decides.
+ */
+import React from 'react';
+import type { Theme } from './theme.js';
+import type { TermCapabilities } from './capabilities.js';
+import type { UpdateSnapshot } from '../update/types.js';
+export interface UpdateLineProps {
+    snapshot: UpdateSnapshot;
+    /** `cols < UPDATE_LIMITS.statusCompactCols`, resolved by the caller. */
+    compact: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export declare function UpdateLine({ snapshot, compact, theme, caps }: UpdateLineProps): React.ReactElement;

package/dist/ui/UpdateLine.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { pickGlyphs } from './glyphs.js';
+export function UpdateLine({ snapshot, compact, theme, caps }) {
+    const glyphs = pickGlyphs(caps);
+    const version = snapshot.latestVersion ?? snapshot.currentVersion;
+    const advice = snapshot.advice ?? '';
+    const dot = glyphs.midDot;
+    const line = (() => {
+        if (snapshot.phase === 'installing') {
+            return {
+                glyph: glyphs.arrowUp,
+                text: compact
+                    ? `${version}${glyphs.ellipsis}`
+                    : `updating to ${version}${glyphs.ellipsis}`,
+                color: theme.muted,
+            };
+        }
+        if (snapshot.phase === 'ready') {
+            return {
+                glyph: glyphs.check,
+                text: compact ? `${version} ready` : `${version} installed ${dot} restart aragon to apply`,
+                color: theme.toast.success,
+            };
+        }
+        if (snapshot.phase === 'failed') {
+            // H2's three classified failures (cli-auto-update-hardening section 8).
+            // Each names the REAL obstacle rather than the generic one, because each
+            // is allowed to break the three-strike silence and a notice that breaks
+            // silence must be worth the interruption.
+            if (snapshot.reason === 'blocked-by-os') {
+                // `npm i -g` FROM THE SAME SHELL HITS THE SAME HANDLE. On Windows the
+                // shim that launched us is being read by the `cmd.exe` running it for
+                // as long as our process lives, and npm's install rewrites that shim -
+                // so the generic advice is not merely unhelpful here, it is a wrong
+                // instruction (R-3 / section 5.3.1).
+                return {
+                    glyph: glyphs.warn,
+                    text: compact || !advice
+                        ? 'update blocked'
+                        : `update blocked ${dot} close other aragon windows, then: ${advice}`,
+                    color: theme.noticeWarn,
+                };
+            }
+            if (snapshot.reason === 'no-space') {
+                return {
+                    glyph: glyphs.warn,
+                    text: compact ? 'no disk space' : `update failed ${dot} no disk space`,
+                    color: theme.noticeWarn,
+                };
+            }
+            if (snapshot.reason === 'not-writable') {
+                return {
+                    glyph: glyphs.warn,
+                    text: compact || !advice
+                        ? 'update blocked'
+                        : `update needs write access ${dot} ${advice}`,
+                    color: theme.noticeWarn,
+                };
+            }
+            return {
+                glyph: glyphs.warn,
+                text: compact || !advice ? 'update failed' : `update failed ${dot} ${advice}`,
+                color: theme.noticeWarn,
+            };
+        }
+        if (snapshot.phase === 'available') {
+            if (snapshot.reason === 'node-too-old') {
+                // Both numbers or neither: "needs a newer Node" without saying which is
+                // a notice the user cannot act on.
+                const detail = snapshot.requiredNode && snapshot.runningNode
+                    ? `${version} needs Node ${snapshot.requiredNode} (running ${snapshot.runningNode})`
+                    : `${version} needs a newer Node`;
+                return {
+                    glyph: glyphs.warn,
+                    text: compact ? 'needs newer Node' : detail,
+                    color: theme.noticeWarn,
+                };
+            }
+            if (snapshot.reason === 'install-ineffective') {
+                return {
+                    glyph: glyphs.warn,
+                    text: compact
+                        ? 'check npm prefix'
+                        : `${version} installed elsewhere${advice ? ` ${dot} ${advice}` : ''}`,
+                    color: theme.noticeWarn,
+                };
+            }
+            return {
+                glyph: glyphs.arrowUp,
+                text: compact
+                    ? version
+                    : `${version} available${advice ? ` ${dot} ${advice}` : ''}`,
+                color: theme.muted,
+            };
+        }
+        // H1's rollback notice, and it goes HERE rather than in a phase branch
+        // (cli-auto-update-hardening section 8 / P0-1). It is true for a whole
+        // SESSION rather than for a phase, so `shouldRenderUpdateLine` decides its
+        // presence from `snapshot.rolledBackFrom` outside `phase` entirely - and the
+        // phases that leaves are exactly `idle` / `checking`, which is this
+        // fallthrough. An earlier draft put it in the `failed` / `available`
+        // branches and keyed it on phase `idle`, a phase neither branch handles;
+        // three independent suppressions, so the one line telling a user their CLI
+        // had been silently downgraded could never have appeared.
+        //
+        // NOT `version` ABOVE: that is `latestVersion ?? currentVersion`, and after
+        // a rollback `latestVersion` may well be the BAD release we just escaped.
+        if (snapshot.rolledBackFrom) {
+            const to = snapshot.rolledBackTo ?? snapshot.currentVersion;
+            return {
+                glyph: glyphs.warn,
+                text: compact
+                    ? 'rolled back'
+                    : `rolled back to ${to} after ${snapshot.rolledBackFrom} failed to start`,
+                color: theme.noticeWarn,
+            };
+        }
+        // `idle` / `checking`, and a `failed` below the notice threshold. The CALLER
+        // never mounts us here (`shouldRenderUpdateLine` is false), but the row must
+        // still be exactly one row if it ever is - the same blank-row discipline
+        // `ToastStack` applies to its own budgeted row.
+        return null;
+    })();
+    if (!line) {
+        return (_jsx(Box, { flexShrink: 0, children: _jsx(Text, { children: " " }) }));
+    }
+    return (_jsx(Box, { flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: line.color, children: [' ', line.glyph, " ", line.text] }) }));
+}

package/dist/update/classify-failure.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Turning a tail of npm output into a reason (cli-auto-update-hardening H2 /
+ * section 5.3).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * PURE, AND THE ONLY IMPORT IS A TYPE. The interesting half of H2 is not this
+ * table, it is the REPORTING rule that decides which of the resulting reasons
+ * may break the three-strike silence - and that lives in `types.ts` beside
+ * `shouldRenderUpdateLine`, as `IMMEDIATE_NOTICE_REASONS`.
+ *
+ * WHY THIS EXISTS AT ALL. The one line a user is ever allowed to see on the
+ * failure path reads `update failed <dot> npm i -g @aragon-agent/cli` for EVERY
+ * cause. For `EPERM` / `EBUSY` - the Windows self-replacement case, R-3 - that
+ * advice hits the same held handle and fails identically, so the single visible
+ * failure is also a wrong instruction.
+ */
+import type { UpdateReason } from './types.js';
+/**
+ * Classify an install failure from the bounded stderr tail `runNpmInstall`
+ * already returns.
+ *
+ * ONE PARAMETER, NOT TWO. An earlier draft took `exitCode` and never read it:
+ * npm exits `1` for every one of these, so the code carries no information the
+ * tail does not, and a parameter that no branch and no test consumes is a
+ * maintenance liability that reads like a promise (P2-2).
+ *
+ * An absent or unrecognised tail is `install-failed` - the pre-H2 behaviour, so
+ * a machine whose npm says something we have never seen degrades to exactly what
+ * it did before rather than to a confident wrong answer.
+ */
+export declare function classifyInstallFailure(tail: string | undefined): UpdateReason;