@aragon-agent/cli 0.5.9 → 0.5.10

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

@@ -7,6 +7,7 @@ import type { AgentMode } from '../agent/agent-mode.js';
 import type { NoticeLevel, Overlay, ToastLevel, ViewAction, ViewState } from '../agent/reducer.js';
 import type { PersistedConfig } from '../config/schema.js';
 import type { FollowThroughBudget } from '../todo/follow-through.js';
+import type { UpdateCommandPort } from '../update/types.js';
 export interface CommandContext {
     /** Raw argument string after the command word (may be empty). */
     args: string;
@@ -52,6 +53,22 @@ export interface CommandContext {
      * change; absent means the clause degrades to naming the ceiling alone.
      */
     followBudget?: FollowThroughBudget;
+    /**
+     * The updater, when this session has one (cli-auto-update §4.4 / C-14 / P0-2).
+     *
+     * `/fast`, `/team` and `/todo` reach their subsystems through `controller`,
+     * because those subsystems live on `AgentController`. This one does not, and
+     * by §3.1 it MUST NOT — `update/` may not import `agent/` — so it needs its
+     * own field, and this is the only seam a slash command has.
+     *
+     * OPTIONAL, for two independent reasons. The service is legitimately absent
+     * under `update.mode: 'off'`, on a non-TTY and in CI (§3.8), so `/update` has
+     * to have something honest to say when it is missing; and a REQUIRED field
+     * would break every existing `CommandContext` fixture in this package at
+     * compile time, for a feature none of them are about. `followBudget` above is
+     * the precedent for an optional, read-at-command-time member.
+     */
+    update?: UpdateCommandPort;
     /** Rebuild the system prompt and the dynamic command list after a skill change. */
     refreshSkills: () => void;
     /**

package/dist/config/app-paths.d.ts

@@ -14,6 +14,9 @@
  *   ├── config.json.bak        `aragon config edit` pre-edit backup
  *   ├── prompt-history.jsonl   submitted prompts, append-only (0600 on POSIX)
  *   ├── state.json             UI bookkeeping scalars (0600 on POSIX)
+ *   ├── update-state.json      auto-update coordination (0600 on POSIX)
+ *   ├── update-install.lock    held by the running `npm i -g` child
+ *   ├── update-install.log     that child's stdout+stderr; unlinked on exit
  *   ├── logs/                  JSONL logs (0700 on POSIX)
  *   ├── sessions/              /save · /resume
  *   ├── skills/                `aragon skills install` target
@@ -79,6 +82,34 @@ export declare function getConfigBackupPath(): string;
 export declare function getPromptHistoryPath(): string;
 /** `<home>/state.json` — UI bookkeeping scalars only; see `ui-state.ts`. */
 export declare function getUiStatePath(): string;
+/**
+ * `<home>/update-state.json` — cross-process auto-update coordination
+ * (cli-auto-update §5.2).
+ *
+ * Deliberately NOT inside `state.json`: that file is documented as UI
+ * bookkeeping scalars only (C-6), and this is coordination state that a SECOND
+ * aragon process reads to decide whether anyone has already asked the registry.
+ * Different lifetime, different failure policy, different reader.
+ */
+export declare function getUpdateStatePath(): string;
+/**
+ * `<home>/update-install.lock` — the `wx` lock the running installer child holds
+ * (cli-auto-update §3.7).
+ *
+ * A FILE, and a direct child of the root, for the reason the two files above
+ * are: `logs/`, `sessions/` and `skills/` are all scan roots, and every extra
+ * file inside one is another thing each walk has to recognise and skip.
+ */
+export declare function getUpdateLockPath(): string;
+/**
+ * `<home>/update-install.log` — the installer child's stdout+stderr
+ * (cli-auto-update §3.5 / U-5).
+ *
+ * A REAL FILE and not a pipe: the child is detached and outlives the parent
+ * (D-10), and a pipe whose parent has exited takes EPIPE on the next write. The
+ * parent tails it on the child's exit, redacts, logs, and unlinks.
+ */
+export declare function getUpdateInstallLogPath(): string;
 export declare function getLogsDir(): string;
 export declare function getSessionsDir(): string;
 /** `<home>` — parent of `skills/`, and where sidecar state such as usage lives. */

package/dist/config/app-paths.js

@@ -14,6 +14,9 @@
  *   ├── config.json.bak        `aragon config edit` pre-edit backup
  *   ├── prompt-history.jsonl   submitted prompts, append-only (0600 on POSIX)
  *   ├── state.json             UI bookkeeping scalars (0600 on POSIX)
+ *   ├── update-state.json      auto-update coordination (0600 on POSIX)
+ *   ├── update-install.lock    held by the running `npm i -g` child
+ *   ├── update-install.log     that child's stdout+stderr; unlinked on exit
  *   ├── logs/                  JSONL logs (0700 on POSIX)
  *   ├── sessions/              /save · /resume
  *   ├── skills/                `aragon skills install` target
@@ -140,6 +143,40 @@ export function getPromptHistoryPath() {
 export function getUiStatePath() {
     return join(resolution.root, 'state.json');
 }
+/**
+ * `<home>/update-state.json` — cross-process auto-update coordination
+ * (cli-auto-update §5.2).
+ *
+ * Deliberately NOT inside `state.json`: that file is documented as UI
+ * bookkeeping scalars only (C-6), and this is coordination state that a SECOND
+ * aragon process reads to decide whether anyone has already asked the registry.
+ * Different lifetime, different failure policy, different reader.
+ */
+export function getUpdateStatePath() {
+    return join(resolution.root, 'update-state.json');
+}
+/**
+ * `<home>/update-install.lock` — the `wx` lock the running installer child holds
+ * (cli-auto-update §3.7).
+ *
+ * A FILE, and a direct child of the root, for the reason the two files above
+ * are: `logs/`, `sessions/` and `skills/` are all scan roots, and every extra
+ * file inside one is another thing each walk has to recognise and skip.
+ */
+export function getUpdateLockPath() {
+    return join(resolution.root, 'update-install.lock');
+}
+/**
+ * `<home>/update-install.log` — the installer child's stdout+stderr
+ * (cli-auto-update §3.5 / U-5).
+ *
+ * A REAL FILE and not a pipe: the child is detached and outlives the parent
+ * (D-10), and a pipe whose parent has exited takes EPIPE on the next write. The
+ * parent tails it on the child's exit, redacts, logs, and unlinks.
+ */
+export function getUpdateInstallLogPath() {
+    return join(resolution.root, 'update-install.log');
+}
 export function getLogsDir() {
     return join(resolution.root, 'logs');
 }

package/dist/config/cli-commands.d.ts

@@ -1,6 +1,6 @@
 /**
  * `aragon config get | list | edit | home`, plus the `log.*`, `team.*`,
- * `retry.*` and `fast.*` branches of `config set`.
+ * `retry.*`, `fast.*` and `update.*` branches of `config set`.
  *
  * These live here rather than in `cli.tsx` because `runConfigSet` is already a
  * 21-case switch — well past the complexity ceiling this package writes down —
@@ -43,6 +43,17 @@ export declare const RETRY_CONFIG_SET_KEYS: readonly ["retry.enabled", "retry.ma
  * `Set fast.model = haiku`.
  */
 export declare const FAST_CONFIG_SET_KEYS: readonly ["fast.enabled", "fast.provider", "fast.model", "fast.baseUrl", "fast.thinkingLevel", "fast.delegate", "fast.review", "fast.reviewEveryTurns", "fast.reviewContextTurns", "fast.reviewMaxChars", "fast.reviewMaxPerSession"];
+/**
+ * Config keys under `update.` that `aragon config set` accepts (cli-auto-update
+ * §4.1).
+ *
+ * A DEDICATED SETTER RATHER THAN A GENERIC DOTTED WRITER, for the reason the
+ * four sets above each record: a generic setter would write `update` as a FLAT
+ * string key (`"update.mode": "notify"` at the top level of the file), the
+ * section would silently never take effect, and `config set` would still print
+ * `Set update.mode = notify`.
+ */
+export declare const UPDATE_CONFIG_SET_KEYS: readonly ["update.mode", "update.checkIntervalMs", "update.registry", "update.distTag"];
 /**
  * Translate a `log.*` dotted key into a patch, or `null` for anything else.
  *
@@ -94,6 +105,21 @@ export declare function applyRetryConfigSet(key: string, value: string): Partial
  * the clamped 50 while the caller echoes the STORED value (AC-13).
  */
 export declare function applyFastConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
+/**
+ * Translate an `update.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `update` section, safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge,
+ * setting the mode would silently reset the interval, the registry mirror and
+ * the dist-tag (C-4 / R-10).
+ *
+ * EVERY KEY ROUTES THROUGH `clampUpdateConfig`, not through a local parse, for
+ * the reason `applyRetryConfigSet` and `applyFastConfigSet` both record: one
+ * gate for both directions means no key here can pick up a different coercion
+ * later, and `config set update.checkIntervalMs 5` writes the clamped 900000
+ * while the caller echoes the STORED value (AC-20).
+ */
+export declare function applyUpdateConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
 /**
  * `log.redactSecrets false` is the one setting that lets credentials reach the
  * disk. It is command-line-only (there is no settings-screen entry) and it says

package/dist/config/cli-commands.js

@@ -1,6 +1,6 @@
 /**
  * `aragon config get | list | edit | home`, plus the `log.*`, `team.*`,
- * `retry.*` and `fast.*` branches of `config set`.
+ * `retry.*`, `fast.*` and `update.*` branches of `config set`.
  *
  * These live here rather than in `cli.tsx` because `runConfigSet` is already a
  * 21-case switch — well past the complexity ceiling this package writes down —
@@ -13,7 +13,7 @@ import process from 'node:process';
 import { getConfigBackupPath, getConfigPath, getHomeRoot, getLogsDir, getPromptHistoryPath, getUiStatePath, isHomeOverridden, } from './app-paths.js';
 import { getHomeMigrationBreadcrumbPath } from './migrate-home.js';
 import { loadPersistedConfig, updatePersistedConfig } from './store.js';
-import { clampFastConfig, clampRetryConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, } from './schema.js';
+import { clampFastConfig, clampRetryConfig, clampUpdateConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, DEFAULT_UPDATE_CONFIG, } from './schema.js';
 import { clampLogLevel } from '../logging/levels.js';
 /** Config keys under `log.` that `aragon config set` accepts. */
 export const LOG_CONFIG_SET_KEYS = [
@@ -87,6 +87,22 @@ export const FAST_CONFIG_SET_KEYS = [
     'fast.reviewMaxChars',
     'fast.reviewMaxPerSession',
 ];
+/**
+ * Config keys under `update.` that `aragon config set` accepts (cli-auto-update
+ * §4.1).
+ *
+ * A DEDICATED SETTER RATHER THAN A GENERIC DOTTED WRITER, for the reason the
+ * four sets above each record: a generic setter would write `update` as a FLAT
+ * string key (`"update.mode": "notify"` at the top level of the file), the
+ * section would silently never take effect, and `config set` would still print
+ * `Set update.mode = notify`.
+ */
+export const UPDATE_CONFIG_SET_KEYS = [
+    'update.mode',
+    'update.checkIntervalMs',
+    'update.registry',
+    'update.distTag',
+];
 function isTrue(value) {
     return value === 'true' || value === '1';
 }
@@ -245,6 +261,39 @@ export function applyFastConfigSet(key, value) {
             return null;
     }
 }
+/**
+ * Translate an `update.*` dotted key into a patch, or `null` for anything else.
+ *
+ * The patch is a PARTIAL `update` section, safe only because
+ * `updatePersistedConfig` deep-merges that section — with a shallow merge,
+ * setting the mode would silently reset the interval, the registry mirror and
+ * the dist-tag (C-4 / R-10).
+ *
+ * EVERY KEY ROUTES THROUGH `clampUpdateConfig`, not through a local parse, for
+ * the reason `applyRetryConfigSet` and `applyFastConfigSet` both record: one
+ * gate for both directions means no key here can pick up a different coercion
+ * later, and `config set update.checkIntervalMs 5` writes the clamped 900000
+ * while the caller echoes the STORED value (AC-20).
+ */
+export function applyUpdateConfigSet(key, value) {
+    const patch = (update) => ({ update });
+    const clampOne = (field) => {
+        const merged = clampUpdateConfig({ ...DEFAULT_UPDATE_CONFIG, [field]: value });
+        return { [field]: merged[field] };
+    };
+    switch (key) {
+        case 'update.mode':
+            return patch(clampOne('mode'));
+        case 'update.checkIntervalMs':
+            return patch(clampOne('checkIntervalMs'));
+        case 'update.registry':
+            return patch(clampOne('registry'));
+        case 'update.distTag':
+            return patch(clampOne('distTag'));
+        default:
+            return null;
+    }
+}
 /**
  * `log.redactSecrets false` is the one setting that lets credentials reach the
  * disk. It is command-line-only (there is no settings-screen entry) and it says

package/dist/config/env.d.ts

@@ -12,7 +12,16 @@
  *     ARAGON_FAST_PROVIDER, ARAGON_FAST_MODEL, ARAGON_FAST_BASE_URL,
  *     ARAGON_LOG_LEVEL,
  *     ARAGON_LOG_FILE, ARAGON_LOG_DIR, ARAGON_TRANSCRIPT_RETAIN,
- *     ARAGON_RENDER_GOVERNOR, ARAGON_MAX_RENDER_INTERVAL_MS.
+ *     ARAGON_RENDER_GOVERNOR, ARAGON_MAX_RENDER_INTERVAL_MS,
+ *     ARAGON_UPDATE.
+ *
+ * READ ELSEWHERE, ON PURPOSE: `ARAGON_UPDATE_REGISTRY` and `npm_config_registry`
+ * are resolved by `update/registry.ts::resolveRegistryUrl`, NOT here, because
+ * §3.3 puts them BELOW `config.update.registry` in precedence — the opposite of
+ * the env-beats-file rule this file implements. Writing them into `partial`
+ * would silently invert that order and make a config-file mirror unreachable on
+ * any machine where npm exports its own registry (which is every machine npm
+ * runs a script on).
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never

package/dist/config/env.js

@@ -12,7 +12,16 @@
  *     ARAGON_FAST_PROVIDER, ARAGON_FAST_MODEL, ARAGON_FAST_BASE_URL,
  *     ARAGON_LOG_LEVEL,
  *     ARAGON_LOG_FILE, ARAGON_LOG_DIR, ARAGON_TRANSCRIPT_RETAIN,
- *     ARAGON_RENDER_GOVERNOR, ARAGON_MAX_RENDER_INTERVAL_MS.
+ *     ARAGON_RENDER_GOVERNOR, ARAGON_MAX_RENDER_INTERVAL_MS,
+ *     ARAGON_UPDATE.
+ *
+ * READ ELSEWHERE, ON PURPOSE: `ARAGON_UPDATE_REGISTRY` and `npm_config_registry`
+ * are resolved by `update/registry.ts::resolveRegistryUrl`, NOT here, because
+ * §3.3 puts them BELOW `config.update.registry` in precedence — the opposite of
+ * the env-beats-file rule this file implements. Writing them into `partial`
+ * would silently invert that order and make a config-file mirror unreachable on
+ * any machine where npm exports its own registry (which is every machine npm
+ * runs a script on).
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
  * evaluated, which is long before `loadDotenv()` runs, so a `.env` can never
@@ -279,6 +288,37 @@ export function readEnvConfig() {
         if (Object.keys(section).length > 0)
             partial.fast = section;
     }
+    // ARAGON_UPDATE=0|off|false turns auto-update off; `notify` reports without
+    // installing; 1|on|true|yes turns it on (cli-auto-update §4.2).
+    //
+    // A TRI-STATE, so it is parsed by an EXPLICIT POSITIVE LIST PER OUTCOME rather
+    // than by the boolean positive list its neighbours use — and emphatically not
+    // by `envBool` below, whose NEGATIVE list would resolve `ARAGON_UPDATE=disable`
+    // to `true`.
+    //
+    // ANYTHING UNRECOGNISED IS LEFT ABSENT, which is the invariant this file
+    // states three times over (`ARAGON_TEAM_MAX`, `ARAGON_RETRY_MAX`,
+    // `ARAGON_MAX_TOKENS`): a value that resolves to a default looks PERMANENTLY
+    // SUPPLIED, and the config file underneath can then never win again. For a
+    // kill switch that is the worst possible failure — `ARAGON_UPDATE=disabled`
+    // would read as "on" while the user believes they turned it off.
+    //
+    // `ARAGON_TODO_FOLLOW` is the tri-state precedent: the recognised string is
+    // written through and `clampUpdateConfig` stays the single gate, so there is
+    // never a second validator that can disagree with the first.
+    const update = process.env.ARAGON_UPDATE?.trim().toLowerCase();
+    if (update !== undefined && update.length > 0) {
+        const mode = update === '0' || update === 'false' || update === 'off' || update === 'no'
+            ? 'off'
+            : update === 'notify'
+                ? 'notify'
+                : update === '1' || update === 'true' || update === 'on' || update === 'yes'
+                    ? 'auto'
+                    : undefined;
+        if (mode !== undefined) {
+            partial.update = { mode };
+        }
+    }
     // Render bounds (tui-render-performance §5.3). Same channel story as
     // ARAGON_FULLSCREEN: a container or a wrapper that owns argv can reach neither
     // a flag nor a config file, and a session that freezes is exactly the case

package/dist/config/load.d.ts

@@ -148,6 +148,23 @@ export interface CliFlags {
      * to keep in step with `toFlags`.
      */
     fastReview?: string;
+    /**
+     * `--update` ⇒ true, `--no-update` ⇒ false, absent ⇒ undefined
+     * (cli-auto-update §4.2).
+     *
+     * DECLARED AS A PAIR — MANDATORY (C-11), for the reason `--team`,
+     * `--todo-panel`, `--render-governor`, `--retry` and `--fast` each record in
+     * turn. `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 —
+     * i.e. the kill switch would un-set itself.
+     *
+     * A BOOLEAN FOR A TRI-STATE KEY, deliberately: the flag is a SESSION override
+     * and `notify` is a preference, not something a user reaches for once. `true`
+     * maps to `'auto'`, `false` to `'off'`; `notify` is reachable through the
+     * config file and `ARAGON_UPDATE=notify`.
+     */
+    update?: boolean;
 }
 /**
  * Resolve the effective config by merging all layers, then derive the runtime

package/dist/config/load.js

@@ -6,7 +6,7 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampMaxRenderInterval, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampFastConfig, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampUpdateConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampMaxRenderInterval, clampTranscriptRetain, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile } from './store.js';
 import { getConfigPath } from './app-paths.js';
@@ -185,6 +185,29 @@ function resolveFastConfig(flags, env, file) {
         ...reviewPatch,
     });
 }
+/**
+ * Merge the `update` section across all four layers (defaults › file › env ›
+ * flags), cli-auto-update §4.2.
+ *
+ * `!== undefined` ON `flags.update`, which is the rule `resolveTeamConfig`,
+ * `resolveTodoConfig`, `resolveRetryConfig` and `resolveFastConfig` each state
+ * once (C-11): commander materialises a lone `--no-update` as
+ * `opts.update = true` when the flag is absent, so a truthiness check cannot
+ * tell `--no-update` from "not passed" — and here that would silently re-enable
+ * a subsystem the user turned off, which is the one direction this feature must
+ * never fail in.
+ *
+ * The flag maps onto `mode` rather than carrying its own key, so there is
+ * exactly one place that says whether the updater runs.
+ */
+function resolveUpdateConfig(flags, env, file) {
+    return clampUpdateConfig({
+        ...DEFAULT_CONFIG.update,
+        ...(file.update ?? {}),
+        ...(env.update ?? {}),
+        ...(flags.update !== undefined ? { mode: flags.update ? 'auto' : 'off' } : {}),
+    });
+}
 /**
  * Resolve the adaptive render governor: flag › env › file › default `true`
  * (tui-render-performance L4).
@@ -428,6 +451,7 @@ export function loadConfig(flags = {}) {
         todo: resolveTodoConfig(flags, env.partial, file),
         retry: resolveRetryConfig(flags, env.partial, file),
         fast: resolveFastConfig(flags, env.partial, file),
+        update: resolveUpdateConfig(flags, env.partial, file),
         cwd,
         color,
         colorLevel,

package/dist/config/schema.d.ts

@@ -434,6 +434,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;
@@ -537,6 +575,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;
 /**
@@ -709,6 +749,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`).
      *