@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/agent/retry-view.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Retry presentation — pure, React-free, unit-tested (llm-api-retry-backoff
+ * §6.5 / §6.6).
+ *
+ * ASCII ONLY: `src/agent/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`). Every non-ASCII character in the rendered line comes from
+ * the `Glyphs` set the caller passes in, never from a literal here.
+ *
+ * The COUNTDOWN is derived from `resumeAt`, an absolute instant, and never from
+ * `delayMs`. Core deliberately sends the instant rather than a tick stream, so
+ * the clock belongs to whoever renders — and a card that recomputed from
+ * `delayMs` would freeze at the announced number the moment a frame was skipped.
+ */
+import type { Glyphs } from '../ui/glyphs.js';
+/**
+ * Presentation bounds. NAMED `RETRY_UI`, NOT `RETRY_LIMITS_UI`: core's
+ * `RETRY_LIMITS` bounds what the mechanism can physically do, this is a column
+ * breakpoint, and a name that read as its sibling would invite the next reader to
+ * look here for the missing keys.
+ */
+export declare const RETRY_UI: {
+    /** Below this many columns the status-bar chip degrades to `[r3]`. */
+    readonly statusCompactCols: 100;
+};
+/** The five phases of the one card a turn gets. */
+export type RetryPhase = 'waiting' | 'retrying' | 'recovered' | 'exhausted' | 'interrupted';
+/** The shape `formatRetryLine` reads — the `kind: 'retry'` entry, structurally. */
+export interface RetryLineInput {
+    attempt: number;
+    maxRetries: number;
+    errorType: string;
+    phase: RetryPhase;
+    resumeAt?: number;
+    totalRetries?: number;
+    elapsedMs?: number;
+}
+/**
+ * Whole seconds until `resumeAt`, floored at 0.
+ *
+ * `Math.ceil` rather than `round`: a countdown that shows `0s` for half a second
+ * before firing reads as a stall, and showing `1s` for slightly too long does
+ * not.
+ */
+export declare function secondsLeft(resumeAt: number | undefined, now: number): number;
+/**
+ * A short headline for a provider failure.
+ *
+ * Deliberately shorter than `formatStreamError`'s: that one is a standalone
+ * notice and has to explain what to do, while this shares one line with a
+ * counter and a countdown. Derived from `errorType` ONLY — nothing here parses
+ * the provider's message, because a human-facing sentence must never become a
+ * machine-readable contract (the rule `SubagentRun.retryable` records).
+ */
+export declare function retryHeadline(errorType: string): string;
+/**
+ * The card's single line, WITHOUT the rail glyph — `EntryView` supplies that, the
+ * same way it does for every other entry kind.
+ *
+ * `now` is a parameter rather than a `Date.now()` call so the function stays pure
+ * and the render can be asserted without a clock.
+ */
+export declare function formatRetryLine(entry: RetryLineInput, glyphs: Glyphs, now: number): string;
+/** The status-bar chip text: full at width, `[r3]` when the row is tight. */
+export declare function formatRetryChip(active: {
+    attempt: number;
+    max: number;
+    secondsLeft: number;
+}, cols: number): string;

package/dist/agent/retry-view.js

@@ -0,0 +1,95 @@
+/**
+ * Retry presentation — pure, React-free, unit-tested (llm-api-retry-backoff
+ * §6.5 / §6.6).
+ *
+ * ASCII ONLY: `src/agent/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`). Every non-ASCII character in the rendered line comes from
+ * the `Glyphs` set the caller passes in, never from a literal here.
+ *
+ * The COUNTDOWN is derived from `resumeAt`, an absolute instant, and never from
+ * `delayMs`. Core deliberately sends the instant rather than a tick stream, so
+ * the clock belongs to whoever renders — and a card that recomputed from
+ * `delayMs` would freeze at the announced number the moment a frame was skipped.
+ */
+import { formatDuration } from './usage.js';
+/**
+ * Presentation bounds. NAMED `RETRY_UI`, NOT `RETRY_LIMITS_UI`: core's
+ * `RETRY_LIMITS` bounds what the mechanism can physically do, this is a column
+ * breakpoint, and a name that read as its sibling would invite the next reader to
+ * look here for the missing keys.
+ */
+export const RETRY_UI = {
+    /** Below this many columns the status-bar chip degrades to `[r3]`. */
+    statusCompactCols: 100,
+};
+/**
+ * Whole seconds until `resumeAt`, floored at 0.
+ *
+ * `Math.ceil` rather than `round`: a countdown that shows `0s` for half a second
+ * before firing reads as a stall, and showing `1s` for slightly too long does
+ * not.
+ */
+export function secondsLeft(resumeAt, now) {
+    if (resumeAt === undefined)
+        return 0;
+    return Math.max(0, Math.ceil((resumeAt - now) / 1000));
+}
+/**
+ * A short headline for a provider failure.
+ *
+ * Deliberately shorter than `formatStreamError`'s: that one is a standalone
+ * notice and has to explain what to do, while this shares one line with a
+ * counter and a countdown. Derived from `errorType` ONLY — nothing here parses
+ * the provider's message, because a human-facing sentence must never become a
+ * machine-readable contract (the rule `SubagentRun.retryable` records).
+ */
+export function retryHeadline(errorType) {
+    switch (errorType) {
+        case 'rate_limit':
+            return 'Rate limited by the provider';
+        case 'overloaded':
+            return 'Provider overloaded';
+        case 'server_error':
+            return 'Provider error';
+        case 'network_error':
+            return 'Network error reaching the provider';
+        case 'timeout':
+            return 'The request timed out';
+        default:
+            return 'Provider call failed';
+    }
+}
+function plural(n) {
+    return n === 1 ? 'retry' : 'retries';
+}
+/**
+ * The card's single line, WITHOUT the rail glyph — `EntryView` supplies that, the
+ * same way it does for every other entry kind.
+ *
+ * `now` is a parameter rather than a `Date.now()` call so the function stays pure
+ * and the render can be asserted without a clock.
+ */
+export function formatRetryLine(entry, glyphs, now) {
+    const dot = ` ${glyphs.midDot} `;
+    const counter = `retry ${entry.attempt}/${entry.maxRetries}`;
+    const settled = entry.totalRetries ?? entry.attempt;
+    switch (entry.phase) {
+        case 'waiting':
+            return `${retryHeadline(entry.errorType)}${dot}${counter} in ${secondsLeft(entry.resumeAt, now)}s`;
+        case 'retrying':
+            return `${retryHeadline(entry.errorType)}${dot}${counter} ${glyphs.ellipsis}`;
+        case 'recovered':
+            return `recovered after ${settled} ${plural(settled)}${entry.elapsedMs === undefined ? '' : `${dot}${formatDuration(entry.elapsedMs)}`}`;
+        case 'exhausted':
+            return `${retryHeadline(entry.errorType)}${dot}gave up after ${settled} ${plural(settled)}${entry.elapsedMs === undefined ? '' : `${dot}${formatDuration(entry.elapsedMs)}`}`;
+        case 'interrupted':
+            return `interrupted after ${settled} ${plural(settled)}`;
+    }
+}
+/** The status-bar chip text: full at width, `[r3]` when the row is tight. */
+export function formatRetryChip(active, cols) {
+    if (cols >= RETRY_UI.statusCompactCols) {
+        return `retry ${active.attempt}/${active.max} ${active.secondsLeft}s`;
+    }
+    return `[r${active.attempt}]`;
+}

package/dist/agent/system-prompt.d.ts

@@ -61,6 +61,17 @@ export interface SystemPromptParams {
      * (and `--no-todo`) produce the pre-todo prompt BYTE FOR BYTE.
      */
     todoBlock?: string;
+    /**
+     * The rendered `<fast_tier>` block, or `''` (fast-model-tier §3.8).
+     *
+     * Spliced conditionally exactly as `skillsBlock`, the plan block, `teamBlock`
+     * and `todoBlock` are, which is what keeps I-2 true: `fast.enabled: false`
+     * (and `--no-fast`) produce the pre-feature prompt BYTE FOR BYTE.
+     *
+     * A CHILD'S PROMPT NEVER CARRIES IT: children cannot delegate and are not
+     * reviewed, so `buildSubagentBlock`'s caller leaves this unset.
+     */
+    fastBlock?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -40,6 +40,7 @@ export function buildSystemPrompt(params) {
     const teamBlock = params.teamBlock ?? '';
     const subagentBlock = params.subagentBlock ?? '';
     const todoBlock = params.todoBlock ?? '';
+    const fastBlock = params.fastBlock ?? '';
     return [
         'You are AragonAgent, an autonomous coding assistant operating inside a terminal (TUI).',
         'You help the user accomplish software-engineering tasks by reasoning step by step and using the provided tools.',
@@ -56,6 +57,7 @@ export function buildSystemPrompt(params) {
         ...(teamBlock ? ['', teamBlock] : []),
         ...(subagentBlock ? ['', subagentBlock] : []),
         ...(todoBlock ? ['', todoBlock] : []),
+        ...(fastBlock ? ['', fastBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',

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>;