@aragon-agent/cli 0.5.9 → 0.5.10

package/dist/boot/rollback.js

@@ -0,0 +1,185 @@
+/**
+ * The rollback (cli-auto-update-hardening H1 / section 5.1.3).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-19).
+ *
+ * EVERY IMPORT THAT DOES REAL WORK IS DYNAMIC, AND FOR A REASON THAT IS NOT THE
+ * USUAL ONE. This function runs inside a build we have CONCRETE EVIDENCE is
+ * broken - it was reached because that build failed to start twice - so every
+ * one of `install-lock`, `installer` and `install-source` can reject on import.
+ * The whole body is inside one `try`, and the `catch` records one line and
+ * returns. Static `import type` specifiers below are erased by tsc and are not
+ * runtime edges, which is what keeps `guard.ts`'s own graph inside the list its
+ * header pins down.
+ *
+ * `../update/state.js` IS THE ONE EXCEPTION and is imported statically: the
+ * guard has already loaded and read it before it can possibly call us, so a
+ * static edge here adds no failure mode that has not already been survived.
+ */
+import process from 'node:process';
+import { readUpdateState, updateUpdateState } from '../update/state.js';
+/** Best-effort, and deliberately so: a logger that fails must not stop a
+ *  rollback that is the user's only way back to a working CLI. */
+async function record(deps, level, msg, data) {
+    try {
+        if (deps.log) {
+            deps.log(level, msg, data);
+            return;
+        }
+        const { getLogger } = await import('../logging/logger.js');
+        getLogger().child('update')[level](msg, data);
+    }
+    catch {
+        // No logger, or a broken one. The stderr line the guard already wrote is
+        // the part the user needs.
+    }
+}
+async function defaultResolveTarget() {
+    const { classifyInstallSource, isAutoInstallable, probeWritable, readSelfManifest, selfPackageRoot } = await import('../update/install-source.js');
+    const root = selfPackageRoot();
+    if (!root)
+        return { root: null, packageName: '', autoInstallable: false, writable: false };
+    return {
+        root,
+        packageName: readSelfManifest(root)?.name ?? '',
+        autoInstallable: isAutoInstallable(classifyInstallSource(root)),
+        writable: probeWritable(root),
+    };
+}
+/**
+ * Reinstall `good` and latch `bad` so nothing puts it back.
+ *
+ * THE ORDER OF OPERATIONS IS LOAD-BEARING.
+ *
+ * 1. LATCH FIRST, INSTALL SECOND. If the process dies between the latch and the
+ *    spawn, the machine is left running a broken version that WILL NOT BE
+ *    REINSTALLED - recoverable by hand. In the other order, a death between the
+ *    spawn and the latch leaves a good version installed with no latch, and the
+ *    next check reinstalls the bad one.
+ *
+ *    `skippedVersion` is part of that write and is the reason it works across
+ *    versions (C-17 / D-28): `readUpdateState` rebuilds from a fixed field list,
+ *    so an OLDER `aragon` writing this file erases every field it does not know.
+ *    `skippedVersion` is schema-1 and every shipped version honours it through
+ *    `decideUpdate`. Per section 1.2 the ordinary rollback target is itself an H1
+ *    build and preserves all four new fields; this covers the cases that
+ *    argument does not reach - a hand-edited state file, a user who manually
+ *    installs a pre-H1 version, and any future field that matters across the
+ *    boundary.
+ *
+ *    `rolledBackFrom` IS WRITTEN HERE AND NOWHERE ELSE (P0-1d). It is consumed
+ *    exactly once, by `UpdateService.start()`, which is the only thing that can
+ *    decide the notice has actually been shown.
+ *
+ * 2. RE-CLASSIFY BEFORE SPAWNING. The machine may have changed since the
+ *    install; we do not run `npm i -g` on a tree we would not have installed
+ *    into.
+ *
+ * 3. ONE NON-BLOCKING LOCK ATTEMPT (U-5b). If another process holds it, return:
+ *    it is either installing or already rolling back, and two concurrent
+ *    `npm i -g` on one prefix is the one thing the lock exists to stop.
+ *
+ * 4. `runNpmInstall` VERBATIM. It already validates the version against
+ *    `STRICT_VERSION_RE`, spawns detached through `process.execPath`, writes to
+ *    a real fd and verifies the classified root afterwards (U-6). A rollback is
+ *    an install; it does not deserve a second code path.
+ *
+ * The stderr line belongs to `runBootGuard` and is written before this is called
+ * (P2-9). NEVER THROWS: the guard invokes it without `await` and cannot handle a
+ * rejection.
+ */
+export async function performRollback(bad, good, deps = {}) {
+    const write = deps.writeState ?? updateUpdateState;
+    const read = deps.readState ?? readUpdateState;
+    try {
+        // Read BEFORE the latch: the write below zeroes `bootFailures`, and the
+        // count is the one number worth keeping in the log record.
+        const failures = read().bootFailures;
+        // Step 1 - the latch, in ONE write.
+        write({
+            skippedVersion: bad,
+            pendingRestartVersion: '',
+            bootFailures: 0,
+            autoInstalledVersion: '',
+            rolledBackFrom: bad,
+        });
+        // Step 2 - re-classify.
+        const target = await (deps.resolveTarget ?? defaultResolveTarget)();
+        if (!target.root || target.packageName.length === 0) {
+            await record(deps, 'warn', 'update_rollback_failed', {
+                from: bad,
+                to: good,
+                reason: 'no-package-root',
+            });
+            return { ok: false, failure: 'no-package-root' };
+        }
+        if (!target.autoInstallable) {
+            await record(deps, 'warn', 'update_rollback_failed', {
+                from: bad,
+                to: good,
+                reason: 'source-ineligible',
+            });
+            return { ok: false, failure: 'source-ineligible' };
+        }
+        if (!target.writable) {
+            await record(deps, 'warn', 'update_rollback_failed', {
+                from: bad,
+                to: good,
+                reason: 'not-writable',
+            });
+            return { ok: false, failure: 'not-writable' };
+        }
+        // Step 3 - the ordinary install lock.
+        const acquire = deps.acquireLock ??
+            (await import('../update/install-lock.js')).tryAcquireInstallLock;
+        const lock = acquire();
+        if (!lock) {
+            await record(deps, 'warn', 'update_rollback_failed', {
+                from: bad,
+                to: good,
+                reason: 'locked',
+            });
+            return { ok: false, failure: 'locked' };
+        }
+        // Step 4 - the install, reused.
+        const install = deps.install ?? (await import('../update/installer.js')).runNpmInstall;
+        let result;
+        try {
+            result = await install({
+                packageName: target.packageName,
+                version: good,
+                root: target.root,
+                // Phase two of U-4, exactly as `performInstall` does it: the lock had to
+                // precede the spawn, and it is rewritten to the child's pid the instant
+                // the child exists. `adoptChild` closes over its own state and may be
+                // passed unbound.
+                onSpawn: lock.adoptChild,
+            });
+        }
+        finally {
+            lock.release();
+        }
+        if (!result.ok) {
+            await record(deps, 'warn', 'update_rollback_failed', {
+                from: bad,
+                to: good,
+                reason: result.failure ?? 'install-failed',
+            });
+            return { ok: false, failure: 'install-failed' };
+        }
+        await record(deps, 'warn', 'update_rolled_back', { from: bad, to: good, failures });
+        return { ok: true };
+    }
+    catch (err) {
+        // The one place this module writes to the terminal itself, and only because
+        // the alternative is a silent no-op on the path the user is already stuck on.
+        try {
+            process.stderr.write(`aragon: rollback to ${good} could not run (${err instanceof Error ? err.message : String(err)}).\n`);
+        }
+        catch {
+            // stderr is gone too. Nothing further is available to us.
+        }
+        await record(deps, 'warn', 'update_rollback_failed', { from: bad, to: good, reason: 'error' });
+        return { ok: false, failure: 'error' };
+    }
+}

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';
@@ -41,6 +41,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 +140,15 @@ function toFlags(opts) {
         transcriptRetain: opts.transcriptRetain,
         renderGovernor: opts.renderGovernor,
         maxRenderInterval: opts.maxRenderInterval,
+        // 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,
     };
 }
 // ---------------------------------------------------------------------------
@@ -302,7 +320,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.
     {
@@ -312,6 +349,42 @@ function runInteractive(flags, extras = {}) {
         // every existing path is provably unchanged.
         stdin: mouseFilter?.stdin ?? process.stdin,
     });
+    // 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
@@ -333,12 +406,23 @@ function runInteractive(flags, extras = {}) {
         // 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();
         controller.dispose();
+        updateService?.dispose();
     });
 }
 async function runOneShot(flags, prompt, quiet) {
@@ -471,6 +555,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 +632,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':
@@ -662,6 +759,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 +1008,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)')
@@ -881,6 +1146,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')