@aragon-agent/cli 0.5.9 → 0.5.11

package/README.md

@@ -117,6 +117,7 @@ Exit codes: `0` success · `1` agent/runtime error · `2` config/usage error ·
 | `/todo [on\|off\|panel on\|off\|follow <mode>\|clear\|continue]` | Todo planning: status, the on/off switch, the rail, follow-through, and picking an unfinished plan back up |
 | `/retry [show\|on\|off\|max <n>]` | API retry: the effective ladder, the on/off switch, the retry count. Takes effect **in the running session**, children included |
 | `/fast [on\|off\|model <id>\|provider <id>\|same\|review <n\|off>\|delegate on\|off]` | Fast model tier: status and this session's totals, the on/off switch, which model, the review cadence |
+| `/update [status\|now\|skip\|off]` | Auto-update: what is running, what is available, where it came from, when it looks again. `now` forces a check past the throttle; `skip` declines the offered version until a newer one appears |
 | `/theme <auto\|warm\|cool\|light>` | Switch the color theme live (persisted) |
 | `/expand [n]` | Expand / collapse the n-th-from-last (default last) tool card |
 | `/copy` | Copy the last answer to the clipboard |
@@ -1095,6 +1096,8 @@ env / `.env` → CLI flags**.
   `ARAGON_TODO_FOLLOW` (`notify` / `auto` / `off`),
   `ARAGON_RETRY` (`0` disables API retry), `ARAGON_RETRY_MAX` (retry count; `0`
   also disables),
+  `ARAGON_UPDATE` (`0` / `off` disables auto-update, `notify` reports without
+  installing), `ARAGON_UPDATE_REGISTRY` (registry base URL for the update check),
   `ARAGON_SKILLS` (`0` disables), `ARAGON_SKILLS_PATH`,
   `ARAGON_SKILLS_DISABLED` (comma-separated names), `ARAGON_LOG_LEVEL`,
   `ARAGON_LOG_FILE` (`0` disables), `ARAGON_LOG_DIR`,
@@ -1227,6 +1230,124 @@ greater than it, and the two are resolved together rather than left to collide.
 These are additive: a config file written by an earlier version loads
 unchanged, with no migration and no version bump.
 
+## Auto-update
+
+`aragon` checks npm for a newer release in the background, installs it silently
+into the same global installation you already have, and tells you on one line
+above the composer:
+
+```
+  * 0.6.0 installed - restart aragon to apply
+```
+
+**The running session is never touched.** The new version lands on disk and
+takes effect the next time you start `aragon`. A restart in the middle of a turn
+would destroy a live run, a subagent dispatch and an open plan review, so the
+line waits and you decide when. Nothing else about the check is visible: it
+happens at most once every four hours, at most once per machine per interval,
+and every failure is silent. Only after three consecutive failures does the line
+say anything, and then it says something you can act on.
+
+**It only ever installs for one kind of installation**: a global `npm i -g`,
+where nothing else claims to own the version. If `aragon` came from pnpm, yarn,
+bun or volta it will not run a command on your behalf — it prints the right one
+for your manager and stops. If it came from `npx`, from a project's
+`node_modules`, or from a clone of this repo it says **nothing at all**: an
+`npx` run resolved `latest` seconds ago, a project's manifest deliberately pins
+the version, and a checkout is not out of date. A global directory it cannot
+write to (the usual Linux case) is detected before anything is spawned.
+
+### The four keys
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `update.mode` | `auto` | `auto` installs · `notify` only reports · `off` disables the subsystem entirely |
+| `update.checkIntervalMs` | `14400000` (4 h) | Minimum time between registry checks, across every `aragon` on this machine |
+| `update.registry` | `''` | Registry base URL. Empty derives it: `ARAGON_UPDATE_REGISTRY`, then `npm_config_registry`, then npmjs |
+| `update.distTag` | `latest` | The dist-tag to track |
+
+```bash
+aragon config set update.mode notify     # tell me, do not install
+aragon config set update.mode off        # never check at all
+ARAGON_UPDATE=0 aragon                   # off for this run
+aragon --no-update                       # the same, as a flag
+aragon update --check                    # ask right now, install nothing
+aragon update                            # ask right now, install if eligible
+aragon update --to 0.5.8                 # go back to a specific version
+aragon update --rollback                 # undo the last auto-update
+```
+
+`aragon update` is also the answer for headless users: the background updater is
+only ever constructed for an interactive session, so `aragon -p "…"`,
+`aragon config set`, CI (any truthy `CI`) and any non-TTY execute **zero** lines
+of update code.
+
+### If an update breaks the CLI
+
+The failure an auto-updater has to answer for is the one where the version it
+installed will not start — an undeclared dependency, a Node API that moved, a
+syntax error past the transpile target. None of those reach any line inside
+`main()`, so no amount of care there helps.
+
+So the `aragon` command is a small launcher that runs **before** the CLI itself.
+It reads one file, and on almost every launch that is all it does. But if the
+version it is about to start is one **this updater installed**, and that version
+has already exited non-zero twice, it reinstalls the version you were running
+before the update and marks the bad one so nothing puts it back:
+
+```
+aragon 0.6.0 failed to start twice; rolling back to 0.5.9.
+```
+
+It boots anyway — if the crash was transient, refusing to start would lock you
+out on a guess. The next session tells you once what happened, and then stops
+mentioning it. A **newer** release clears the mark and installs normally: you
+were never opted out of updates, only out of the loop.
+
+Three things this deliberately does not do. It never touches a version **you**
+installed yourself — `npm i -g @aragon-agent/cli@something` is your decision, and
+an updater that silently reverts it is a worse actor than one that does nothing.
+It does not roll back a release that starts and is merely *wrong*; that is not
+detectable from inside, and a heuristic that guessed would eventually revert a
+working version on a bad day. Use `aragon update --rollback` for that — it is the
+same mechanism, run deliberately. And **`update.mode: off` disables this too**:
+the guard is armed only by an auto-install, so a machine that never auto-installs
+never arms it. That is the honest reading of the kill switch — it turns off the
+whole subsystem, recovery included.
+
+### Behind a proxy
+
+Node's own `fetch` ignores `HTTP_PROXY`, so on a proxied machine the direct check
+simply fails. When it does, `aragon` asks **the npm you already have** instead,
+which honours `proxy`, `https-proxy` and your `.npmrc`. It runs only after the
+direct request has already failed, so on an ordinary machine it never runs at
+all. `/update status` shows `probe: npm` when this is what answered.
+
+No credentials are read or forwarded by either path — we run the command you
+could have typed and read one version string out of its JSON.
+
+### The trade this makes
+
+Auto-update widens the window in which a compromised release could reach you
+without a human deciding to fetch it. That is a real cost, and it is worth
+stating plainly rather than burying:
+
+- npm verifies each package against the registry's `dist.integrity` SRI hash, so
+  what is installed is what was published. That protects the transport, not the
+  publisher.
+- Only the `latest` dist-tag is tracked, prereleases are never installed onto a
+  stable version, and a release its own author has `npm deprecate`d is skipped.
+- `update.mode: off` and `ARAGON_UPDATE=0` are kill switches, and they are
+  documented rather than incidental.
+- Organisations that want a review gate point `update.registry` at a mirror they
+  control.
+
+No credentials are ever sent with the check. The updater does not read
+`_authToken` out of your `.npmrc` — an updater that attached a token to a
+user-configurable URL would be a credential-exfiltration primitive the moment
+that URL was mis-set. Private-registry users should point `update.registry` at a
+mirror they can read anonymously, or turn the feature off.
+
 ## Files & logs
 
 Everything AragonAgent keeps for you lives under one directory in your home:
@@ -1237,6 +1358,8 @@ Everything AragonAgent keeps for you lives under one directory in your home:
 ├── config.json.bak                 written by `aragon config edit` before it opens
 ├── prompt-history.jsonl            prompts you submitted, for ↑ recall (0600 on POSIX)
 ├── state.json                      UI bookkeeping: submit count, one-shot notices
+├── update-state.json               auto-update: last check, pending restart, skipped version,
+│                                   and the boot guard's rollback bookkeeping
 ├── logs/
 │   ├── aragon-2026-07-27.log       today, JSON Lines
 │   └── aragon-2026-07-27.1.log     rotated at log.maxFileBytes

package/dist/boot/guard.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The boot guard (cli-auto-update-hardening H1 / section 5.1).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-19).
+ *
+ * WHY THIS LIVES BELOW `cli.tsx` AND NOT INSIDE `main()` (D-26). The instinct is
+ * to put crash recovery in `cli.tsx::main()`. That covers a crash AFTER the
+ * module graph loads and misses the class of failure that actually bricks npm
+ * CLIs: `dist/cli.js` statically imports ~60 modules, and a release that fails to
+ * IMPORT never reaches any line anyone wrote inside `main()`. An undeclared
+ * dependency, a Node API that moved, a syntax error past the transpile target -
+ * all of them raise before `main` exists.
+ *
+ * ==========================================================================
+ * THE IMPORT LIST HERE IS A CONSTRAINT, NOT A COINCIDENCE (section 4 rule 2).
+ *
+ * This module may import `node:*`, `../update/state.js` and its own sibling in
+ * `boot/` - AND NOTHING ELSE. Every module it pulls in is a module that can
+ * crash before the guard that exists to survive crashes has run.
+ *
+ * IN PARTICULAR IT MUST NOT IMPORT `logging/logger.js`. `getLogger()` resolves
+ * config on its way to a sink, so wiring it in here would drag the whole config
+ * graph into the one module that has to survive a broken build - which is
+ * exactly the failure this guard is for. So the guard is SILENT BY CONSTRUCTION
+ * (D-42); the two facts worth having after the event are recorded by
+ * `rollback.ts` and by `UpdateService`, both of which already have a logger.
+ *
+ * THE CHAIN IS NOT `node:*`-ONLY AND THE LIST MUST NOT BE READ AS CLAIMING SO
+ * (P1-2). `../update/state.js` imports `../config/app-paths.js`, which imports
+ * and CALLS `env-paths` at module scope. That third-party module is in this
+ * graph, which is why `launcher.ts` imports this file DYNAMICALLY and inside a
+ * `try` - so a release whose `node_modules` lost `env-paths` degrades to "no
+ * guard, and the CLI reports its own crash normally" rather than to an
+ * `ERR_MODULE_NOT_FOUND` from the bin entry. The residual hole is real and is
+ * stated in section 5.1.5 rather than argued away; this list is what keeps it
+ * from growing.
+ * ==========================================================================
+ */
+import { type UpdateState } from '../update/state.js';
+/**
+ * `<root>/package.json`'s `version`, or `''`.
+ *
+ * Resolves the root the way `install-source.ts` does - `dirname(fileURLToPath(
+ * import.meta.url))` then up two - which from `dist/boot/` lands on the package
+ * root exactly as it does from `dist/update/`. DUPLICATED RATHER THAN IMPORTED
+ * because the import list above keeps `install-source.js` out of this graph; it
+ * is four lines of `node:*` with no path NAME in it (P2-4).
+ *
+ * The level count is load-bearing for the same reason it is there: this package
+ * is compiled by plain `tsc` with `rootDir: ./src` and NO BUNDLER (C-16), so
+ * `src/boot/guard.ts` really does land at `dist/boot/guard.js`.
+ */
+export declare function readOwnVersion(): string;
+/** Injected wholesale by the tests; `runBootGuard()` uses the real ones. */
+export interface BootGuardDeps {
+    readState?: () => UpdateState;
+    writeState?: (patch: Partial<Omit<UpdateState, 'schema'>>) => unknown;
+    version?: string;
+    /** Called instead of `performRollback`, so no test spawns npm. */
+    rollback?: (bad: string, good: string) => void;
+    onExit?: (listener: (code: number) => void) => void;
+    writeStderr?: (text: string) => void;
+}
+/**
+ * Arm, count, disarm, or decide a rollback. Called once, from `launcher.ts`,
+ * before `dist/cli.js` is imported.
+ *
+ * READ THE ORDER AGAINST THE FAILURE IT DEFENDS:
+ *
+ *  - `autoInstalledVersion !== version` IS THE ARMING CONDITION AND IT IS FIRST.
+ *    That field is written by `performInstall` on success and cleared by
+ *    `markBootHealthy`, so the guard is armed for exactly the window between "we
+ *    installed X" and "X has been seen to start", and for no other launch of any
+ *    version. Steady state - every launch on every machine except the first one
+ *    after an auto-update - is ONE `readFileSync` of ~300 bytes and one string
+ *    compare, with NO WRITE AT ALL. Reordering this check after anything else
+ *    costs a write on every `aragon --version`.
+ *
+ *  - THE GUARD ONLY CLEANS UP DAMAGE WE CAUSED (D-29). If a user's own
+ *    `npm i -g @aragon-agent/cli@broken` crashes, that is their install and
+ *    their decision; an updater that silently reverts it is a worse actor than
+ *    one that does nothing. It also bounds the blast radius of a bug in the
+ *    guard itself to one unnecessary reinstall of a version the user was running
+ *    an hour ago.
+ *
+ *  - THE THRESHOLD IS TESTED BEFORE THIS LAUNCH CAN CONTRIBUTE, so `2` means
+ *    "two PREVIOUS launches of X exited non-zero" and the rollback happens on the
+ *    third (D-30).
+ *
+ *  - THE ROLLBACK DOES NOT ABORT THE BOOT (D-31). Refusing to start would be the
+ *    wrong trade: if the crash was transient the user is now locked out of a
+ *    working CLI by our guess. The detached child completes regardless, so the
+ *    worst case is one more crash followed by a good launch.
+ *
+ *  - THE COUNTER MOVES IN THE EXIT HOOK AND ONLY ON A NON-ZERO CODE (D-30a /
+ *    P1-5). See `UpdateState.bootFailures`. The cost is stated rather than
+ *    hidden: a release that dies WITHOUT running exit handlers (`SIGKILL`, a
+ *    native segfault, `process.abort()`) is never counted and never rolled back.
+ *    For a pure-JS CLI whose target failure is a module that will not import -
+ *    which raises, and therefore exits `1` through the launcher's `.catch` -
+ *    that is the right side of the trade.
+ *
+ * NEVER THROWS. `launcher.ts` wraps the call anyway, because a guard that throws
+ * must never be the reason the CLI will not start.
+ */
+export declare function runBootGuard(deps?: BootGuardDeps): void;
+/**
+ * Disarm the guard and record this version as the one to roll back TO.
+ *
+ * Called from two places, and both matter:
+ *
+ *  - `cli.tsx::runInteractive`, immediately after `render()` returns - the
+ *    earliest moment at which "this build starts" is PROVEN: the module graph
+ *    loaded, config resolved, Ink mounted. This is the primary, and it is what
+ *    makes a long session that is later `SIGKILL`ed (terminal window closed,
+ *    machine slept badly, OOM killer) still count as healthy.
+ *  - the exit hook installed by `runBootGuard`, when the code is `0` - the
+ *    backstop for `aragon -p`, `aragon config set`, `aragon --version` and every
+ *    other path that never mounts Ink.
+ *
+ * IDEMPOTENT through the first-line guard, which is also the fast path: on every
+ * ordinary launch this is one read and one string compare.
+ *
+ * `lastGoodVersion` is set here as well as at install time, deliberately: a
+ * machine whose state file was deleted between the install and the next launch
+ * converges to a correct rollback target after one healthy run.
+ *
+ * IT DOES NOT TOUCH `rolledBackFrom`, AND IT MUST NOT (P0-1e). An earlier draft
+ * had this function clear the rollback notice; it could never have done so,
+ * because in the session AFTER a rollback `autoInstalledVersion` is `''` and this
+ * function returns on its first line before touching anything. The notice is
+ * consumed by `UpdateService.start()` instead, which is also the only place that
+ * can decide it has actually been shown (D-40).
+ */
+export declare function markBootHealthy(version: string, deps?: BootGuardDeps): void;

package/dist/boot/guard.js

@@ -0,0 +1,218 @@
+/**
+ * The boot guard (cli-auto-update-hardening H1 / section 5.1).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-19).
+ *
+ * WHY THIS LIVES BELOW `cli.tsx` AND NOT INSIDE `main()` (D-26). The instinct is
+ * to put crash recovery in `cli.tsx::main()`. That covers a crash AFTER the
+ * module graph loads and misses the class of failure that actually bricks npm
+ * CLIs: `dist/cli.js` statically imports ~60 modules, and a release that fails to
+ * IMPORT never reaches any line anyone wrote inside `main()`. An undeclared
+ * dependency, a Node API that moved, a syntax error past the transpile target -
+ * all of them raise before `main` exists.
+ *
+ * ==========================================================================
+ * THE IMPORT LIST HERE IS A CONSTRAINT, NOT A COINCIDENCE (section 4 rule 2).
+ *
+ * This module may import `node:*`, `../update/state.js` and its own sibling in
+ * `boot/` - AND NOTHING ELSE. Every module it pulls in is a module that can
+ * crash before the guard that exists to survive crashes has run.
+ *
+ * IN PARTICULAR IT MUST NOT IMPORT `logging/logger.js`. `getLogger()` resolves
+ * config on its way to a sink, so wiring it in here would drag the whole config
+ * graph into the one module that has to survive a broken build - which is
+ * exactly the failure this guard is for. So the guard is SILENT BY CONSTRUCTION
+ * (D-42); the two facts worth having after the event are recorded by
+ * `rollback.ts` and by `UpdateService`, both of which already have a logger.
+ *
+ * THE CHAIN IS NOT `node:*`-ONLY AND THE LIST MUST NOT BE READ AS CLAIMING SO
+ * (P1-2). `../update/state.js` imports `../config/app-paths.js`, which imports
+ * and CALLS `env-paths` at module scope. That third-party module is in this
+ * graph, which is why `launcher.ts` imports this file DYNAMICALLY and inside a
+ * `try` - so a release whose `node_modules` lost `env-paths` degrades to "no
+ * guard, and the CLI reports its own crash normally" rather than to an
+ * `ERR_MODULE_NOT_FOUND` from the bin entry. The residual hole is real and is
+ * stated in section 5.1.5 rather than argued away; this list is what keeps it
+ * from growing.
+ * ==========================================================================
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { readUpdateState, updateUpdateState } from '../update/state.js';
+import { performRollback } from './rollback.js';
+/**
+ * Non-zero exits of a version we installed before it is rolled back.
+ *
+ * DUPLICATED FROM `UPDATE_LIMITS.crashesBeforeRollback` RATHER THAN IMPORTED,
+ * and the duplication is the point: `update/limits.ts` is pure and dependency-
+ * free today, but it is a shared table that anyone may add an import to, and the
+ * import list above is worth more than one deduplicated integer. It is a bare
+ * number with no path and no name in it, so it is not the duplication
+ * `config/app-paths.ts`'s header forbids.
+ */
+const CRASHES_BEFORE_ROLLBACK = 2;
+let cachedVersion = null;
+/**
+ * `<root>/package.json`'s `version`, or `''`.
+ *
+ * Resolves the root the way `install-source.ts` does - `dirname(fileURLToPath(
+ * import.meta.url))` then up two - which from `dist/boot/` lands on the package
+ * root exactly as it does from `dist/update/`. DUPLICATED RATHER THAN IMPORTED
+ * because the import list above keeps `install-source.js` out of this graph; it
+ * is four lines of `node:*` with no path NAME in it (P2-4).
+ *
+ * The level count is load-bearing for the same reason it is there: this package
+ * is compiled by plain `tsc` with `rootDir: ./src` and NO BUNDLER (C-16), so
+ * `src/boot/guard.ts` really does land at `dist/boot/guard.js`.
+ */
+export function readOwnVersion() {
+    if (cachedVersion !== null)
+        return cachedVersion;
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const parsed = JSON.parse(readFileSync(resolve(here, '..', '..', 'package.json'), 'utf-8'));
+        cachedVersion = typeof parsed.version === 'string' ? parsed.version : '';
+    }
+    catch {
+        cachedVersion = '';
+    }
+    return cachedVersion;
+}
+/**
+ * Arm, count, disarm, or decide a rollback. Called once, from `launcher.ts`,
+ * before `dist/cli.js` is imported.
+ *
+ * READ THE ORDER AGAINST THE FAILURE IT DEFENDS:
+ *
+ *  - `autoInstalledVersion !== version` IS THE ARMING CONDITION AND IT IS FIRST.
+ *    That field is written by `performInstall` on success and cleared by
+ *    `markBootHealthy`, so the guard is armed for exactly the window between "we
+ *    installed X" and "X has been seen to start", and for no other launch of any
+ *    version. Steady state - every launch on every machine except the first one
+ *    after an auto-update - is ONE `readFileSync` of ~300 bytes and one string
+ *    compare, with NO WRITE AT ALL. Reordering this check after anything else
+ *    costs a write on every `aragon --version`.
+ *
+ *  - THE GUARD ONLY CLEANS UP DAMAGE WE CAUSED (D-29). If a user's own
+ *    `npm i -g @aragon-agent/cli@broken` crashes, that is their install and
+ *    their decision; an updater that silently reverts it is a worse actor than
+ *    one that does nothing. It also bounds the blast radius of a bug in the
+ *    guard itself to one unnecessary reinstall of a version the user was running
+ *    an hour ago.
+ *
+ *  - THE THRESHOLD IS TESTED BEFORE THIS LAUNCH CAN CONTRIBUTE, so `2` means
+ *    "two PREVIOUS launches of X exited non-zero" and the rollback happens on the
+ *    third (D-30).
+ *
+ *  - THE ROLLBACK DOES NOT ABORT THE BOOT (D-31). Refusing to start would be the
+ *    wrong trade: if the crash was transient the user is now locked out of a
+ *    working CLI by our guess. The detached child completes regardless, so the
+ *    worst case is one more crash followed by a good launch.
+ *
+ *  - THE COUNTER MOVES IN THE EXIT HOOK AND ONLY ON A NON-ZERO CODE (D-30a /
+ *    P1-5). See `UpdateState.bootFailures`. The cost is stated rather than
+ *    hidden: a release that dies WITHOUT running exit handlers (`SIGKILL`, a
+ *    native segfault, `process.abort()`) is never counted and never rolled back.
+ *    For a pure-JS CLI whose target failure is a module that will not import -
+ *    which raises, and therefore exits `1` through the launcher's `.catch` -
+ *    that is the right side of the trade.
+ *
+ * NEVER THROWS. `launcher.ts` wraps the call anyway, because a guard that throws
+ * must never be the reason the CLI will not start.
+ */
+export function runBootGuard(deps = {}) {
+    try {
+        const read = deps.readState ?? readUpdateState;
+        const write = deps.writeState ?? updateUpdateState;
+        const version = deps.version ?? readOwnVersion();
+        if (!version)
+            return;
+        const state = read();
+        // FAST PATH: not our install, or already seen healthy. No write, no hook.
+        if (state.autoInstalledVersion !== version)
+            return;
+        if (state.bootFailures >= CRASHES_BEFORE_ROLLBACK &&
+            state.lastGoodVersion &&
+            state.lastGoodVersion !== version) {
+            // WRITTEN HERE, SYNCHRONOUSLY, AND NOT INSIDE `performRollback` (P2-9).
+            // That function is `async` and its first statement is a dynamic `import`,
+            // which yields - so a line written in there would race the
+            // `await import('./cli.js')` that follows and could land below whatever
+            // the CLI prints. Written before the call, the ordering is a property of
+            // the code rather than of the module loader's timing. C-10 permits this
+            // one visible message because the TUI is not mounted yet: there is no
+            // fixed frame to shift.
+            const stderr = deps.writeStderr ?? ((text) => process.stderr.write(text));
+            stderr(`aragon ${version} failed to start twice; rolling back to ${state.lastGoodVersion}.\n`);
+            const roll = deps.rollback ??
+                ((bad, good) => {
+                    void performRollback(bad, good);
+                });
+            roll(version, state.lastGoodVersion);
+            // No exit hook: the rollback has already disarmed the guard, and this
+            // launch's own crash must not be counted against a cycle that is over.
+            return;
+        }
+        const on = deps.onExit ?? ((listener) => process.on('exit', listener));
+        on((code) => {
+            try {
+                if (code === 0)
+                    markBootHealthy(version, { readState: read, writeState: write });
+                else
+                    write({ bootFailures: state.bootFailures + 1 });
+            }
+            catch {
+                // An exit hook that throws prints an unactionable stack over whatever
+                // the CLI last said. The bookkeeping is not worth that.
+            }
+        });
+    }
+    catch {
+        // See the contract above: never throws.
+    }
+}
+/**
+ * Disarm the guard and record this version as the one to roll back TO.
+ *
+ * Called from two places, and both matter:
+ *
+ *  - `cli.tsx::runInteractive`, immediately after `render()` returns - the
+ *    earliest moment at which "this build starts" is PROVEN: the module graph
+ *    loaded, config resolved, Ink mounted. This is the primary, and it is what
+ *    makes a long session that is later `SIGKILL`ed (terminal window closed,
+ *    machine slept badly, OOM killer) still count as healthy.
+ *  - the exit hook installed by `runBootGuard`, when the code is `0` - the
+ *    backstop for `aragon -p`, `aragon config set`, `aragon --version` and every
+ *    other path that never mounts Ink.
+ *
+ * IDEMPOTENT through the first-line guard, which is also the fast path: on every
+ * ordinary launch this is one read and one string compare.
+ *
+ * `lastGoodVersion` is set here as well as at install time, deliberately: a
+ * machine whose state file was deleted between the install and the next launch
+ * converges to a correct rollback target after one healthy run.
+ *
+ * IT DOES NOT TOUCH `rolledBackFrom`, AND IT MUST NOT (P0-1e). An earlier draft
+ * had this function clear the rollback notice; it could never have done so,
+ * because in the session AFTER a rollback `autoInstalledVersion` is `''` and this
+ * function returns on its first line before touching anything. The notice is
+ * consumed by `UpdateService.start()` instead, which is also the only place that
+ * can decide it has actually been shown (D-40).
+ */
+export function markBootHealthy(version, deps = {}) {
+    try {
+        if (!version)
+            return;
+        const read = deps.readState ?? readUpdateState;
+        const write = deps.writeState ?? updateUpdateState;
+        const state = read();
+        if (state.autoInstalledVersion !== version)
+            return;
+        write({ autoInstalledVersion: '', bootFailures: 0, lastGoodVersion: version });
+    }
+    catch {
+        // Bookkeeping. Never a reason to fail a session that is otherwise healthy.
+    }
+}

package/dist/boot/rollback.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 { type UpdateState } from '../update/state.js';
+import type { InstallLockHandle } from '../update/install-lock.js';
+import type { InstallResult, RunNpmInstallInput } from '../update/installer.js';
+/** What stopped us, when something did. `undefined` on the happy path. */
+export type RollbackFailure = 'no-package-root' | 'source-ineligible' | 'not-writable' | 'locked' | 'install-failed' | 'error';
+export interface RollbackResult {
+    ok: boolean;
+    failure?: RollbackFailure;
+}
+/** What this module resolved about the machine, injected wholesale by tests. */
+export interface RollbackTarget {
+    root: string | null;
+    packageName: string;
+    autoInstallable: boolean;
+    writable: boolean;
+}
+export interface RollbackDeps {
+    readState?: () => UpdateState;
+    writeState?: (patch: Partial<Omit<UpdateState, 'schema'>>) => unknown;
+    /** Injected together; when all four are present nothing is imported at all. */
+    resolveTarget?: () => Promise<RollbackTarget>;
+    acquireLock?: () => InstallLockHandle | null;
+    install?: (input: RunNpmInstallInput) => Promise<InstallResult>;
+    log?: (level: 'info' | 'warn', msg: string, data: Record<string, unknown>) => void;
+}
+/**
+ * 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 declare function performRollback(bad: string, good: string, deps?: RollbackDeps): Promise<RollbackResult>;