@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/update/state.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `<home>/update-state.json` (cli-auto-update section 5.2).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * WHY NOT `state.json` (D-14 / C-6). That file is documented as UI bookkeeping
+ * SCALARS ONLY, and its header names itself "the most inviting drawer in the
+ * codebase". What lives here is CROSS-PROCESS COORDINATION state with a
+ * completely different lifetime and failure policy: ten terminals read it to
+ * decide whether anyone has already asked the registry today. The rule exists
+ * precisely to stop the merge that looks convenient today.
+ *
+ * FAILURE POLICY: copies `ui-state.ts` verbatim - per-field tolerance, whole
+ * object fallback on a wrong `schema`, atomic temp-file + rename + `chmod 0600`,
+ * and NEVER THROWS. Losing the file costs one extra registry request.
+ *
+ * NO PROCESS-LIFETIME CACHE, unlike `ui-state.ts`. The whole point of
+ * `lastCheckAt` is that a SECOND aragon process wrote it (section 3.7), so a
+ * value memoized at first read would defeat the throttle it exists to implement.
+ *
+ * ==========================================================================
+ * C-17 - THIS FILE IS A CROSS-VERSION CHANNEL, AND `readUpdateState` ERASES
+ * WHAT IT DOES NOT KNOW.
+ *
+ * The reader below rebuilds the object FIELD BY FIELD from a fixed list, so an
+ * OLDER `aragon` reading and writing this file destroys every field added after
+ * it shipped. Two consequences, and both have already been reasoned through
+ * (cli-auto-update-hardening section 7.1 / D-27 / D-28):
+ *
+ *  1. DO NOT BUMP `UPDATE_STATE_SCHEMA` TO ADD A FIELD. A bump makes the reader
+ *     fall back to the WHOLE default object on the first read after an upgrade
+ *     (see the `parsed.schema !== ...` line), which discards `skippedVersion` -
+ *     the field that stops an `install-ineffective` loop (R-12) and a
+ *     bad-release loop (H1) - on every machine at once. Per-field tolerance
+ *     already handles absence: a missing field reads as its default.
+ *  2. A ROLLBACK MUST LATCH THROUGH `skippedVersion`, which is a schema-1 field
+ *     every shipped version honours. Latching only in one of the four fields
+ *     below would be invisible to a CLI that predates them, which would decide
+ *     `install` on its next check and reinstall the release that just bricked
+ *     the machine - once per interval, forever.
+ * ==========================================================================
+ */
+export declare const UPDATE_STATE_FILENAME = "update-state.json";
+export declare const UPDATE_STATE_SCHEMA = 1;
+export interface UpdateState {
+    schema: number;
+    /** Epoch ms of the last registry request by ANY process; `0` = never. */
+    lastCheckAt: number;
+    /** `''` = unknown. */
+    lastKnownVersion: string;
+    /** Installed and awaiting a relaunch; `''` = none. */
+    pendingRestartVersion: string;
+    /** `''` = none. Set by `/update skip` and by an ineffective install (U-6). */
+    skippedVersion: string;
+    consecutiveFailures: number;
+    lastFailureAt: number;
+    /**
+     * The version THIS UPDATER installed and has not yet seen boot healthy.
+     * `''` = the boot guard is disarmed, which is every launch on every machine
+     * except the first one after an auto-update.
+     */
+    autoInstalledVersion: string;
+    /**
+     * The version that was running when the last auto-install ran, or the last
+     * version seen to boot healthy. THE ROLLBACK TARGET.
+     */
+    lastGoodVersion: string;
+    /**
+     * Launches of `autoInstalledVersion` that EXITED NON-ZERO. Reset by
+     * `markBootHealthy`, by a rollback, and by each new arming.
+     *
+     * NAMED FOR FAILURES AND NOT FOR ATTEMPTS, and the name is the specification
+     * (P1-5). A counter named for attempts invites an increment at boot, and an
+     * increment at boot has no per-process identity: three terminals starting
+     * inside the window between the first one's increment and its
+     * `markBootHealthy` walk it to the threshold, and the third rolls back a
+     * release running fine in the other two. A counter named for failures can only
+     * be incremented where a failure is observable, which is the exit hook.
+     */
+    bootFailures: number;
+    /**
+     * The version the last rollback moved away from. Written by `performRollback`
+     * and consumed EXACTLY ONCE by `UpdateService.start()`. `''` = nothing to
+     * report.
+     */
+    rolledBackFrom: string;
+}
+export declare const DEFAULT_UPDATE_STATE: UpdateState;
+/**
+ * Per-field tolerance: one nonsense value must not take the others with it, and
+ * a field this version has never heard of reads as its default rather than
+ * failing the parse. A wrong SCHEMA is different - the shape is no longer known,
+ * so the whole object falls back (the rule `ui-state.ts` and `skills/usage.ts`
+ * follow). See C-17 in the header before adding a field OR touching the schema.
+ */
+export declare function readUpdateState(): UpdateState;
+/**
+ * Read-modify-write. READ-MODIFY-WRITE AND NOT WRITE, deliberately: another
+ * `aragon` may have recorded a check or an install between our read and this
+ * call, and clobbering its `lastCheckAt` is how ten terminals turn back into ten
+ * registry requests.
+ */
+export declare function updateUpdateState(patch: Partial<Omit<UpdateState, 'schema'>>): UpdateState;

package/dist/update/state.js

@@ -0,0 +1,142 @@
+/**
+ * `<home>/update-state.json` (cli-auto-update section 5.2).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * WHY NOT `state.json` (D-14 / C-6). That file is documented as UI bookkeeping
+ * SCALARS ONLY, and its header names itself "the most inviting drawer in the
+ * codebase". What lives here is CROSS-PROCESS COORDINATION state with a
+ * completely different lifetime and failure policy: ten terminals read it to
+ * decide whether anyone has already asked the registry today. The rule exists
+ * precisely to stop the merge that looks convenient today.
+ *
+ * FAILURE POLICY: copies `ui-state.ts` verbatim - per-field tolerance, whole
+ * object fallback on a wrong `schema`, atomic temp-file + rename + `chmod 0600`,
+ * and NEVER THROWS. Losing the file costs one extra registry request.
+ *
+ * NO PROCESS-LIFETIME CACHE, unlike `ui-state.ts`. The whole point of
+ * `lastCheckAt` is that a SECOND aragon process wrote it (section 3.7), so a
+ * value memoized at first read would defeat the throttle it exists to implement.
+ *
+ * ==========================================================================
+ * C-17 - THIS FILE IS A CROSS-VERSION CHANNEL, AND `readUpdateState` ERASES
+ * WHAT IT DOES NOT KNOW.
+ *
+ * The reader below rebuilds the object FIELD BY FIELD from a fixed list, so an
+ * OLDER `aragon` reading and writing this file destroys every field added after
+ * it shipped. Two consequences, and both have already been reasoned through
+ * (cli-auto-update-hardening section 7.1 / D-27 / D-28):
+ *
+ *  1. DO NOT BUMP `UPDATE_STATE_SCHEMA` TO ADD A FIELD. A bump makes the reader
+ *     fall back to the WHOLE default object on the first read after an upgrade
+ *     (see the `parsed.schema !== ...` line), which discards `skippedVersion` -
+ *     the field that stops an `install-ineffective` loop (R-12) and a
+ *     bad-release loop (H1) - on every machine at once. Per-field tolerance
+ *     already handles absence: a missing field reads as its default.
+ *  2. A ROLLBACK MUST LATCH THROUGH `skippedVersion`, which is a schema-1 field
+ *     every shipped version honours. Latching only in one of the four fields
+ *     below would be invisible to a CLI that predates them, which would decide
+ *     `install` on its next check and reinstall the release that just bricked
+ *     the machine - once per interval, forever.
+ * ==========================================================================
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import process from 'node:process';
+import { getHomeRoot, getUpdateStatePath } from '../config/app-paths.js';
+export const UPDATE_STATE_FILENAME = 'update-state.json';
+export const UPDATE_STATE_SCHEMA = 1;
+export const DEFAULT_UPDATE_STATE = {
+    schema: UPDATE_STATE_SCHEMA,
+    lastCheckAt: 0,
+    lastKnownVersion: '',
+    pendingRestartVersion: '',
+    skippedVersion: '',
+    consecutiveFailures: 0,
+    lastFailureAt: 0,
+    autoInstalledVersion: '',
+    lastGoodVersion: '',
+    bootFailures: 0,
+    rolledBackFrom: '',
+};
+function count(value, fallback) {
+    const n = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10);
+    if (!Number.isFinite(n) || n < 0)
+        return fallback;
+    return Math.floor(n);
+}
+function text(value, fallback) {
+    return typeof value === 'string' ? value : fallback;
+}
+/**
+ * Per-field tolerance: one nonsense value must not take the others with it, and
+ * a field this version has never heard of reads as its default rather than
+ * failing the parse. A wrong SCHEMA is different - the shape is no longer known,
+ * so the whole object falls back (the rule `ui-state.ts` and `skills/usage.ts`
+ * follow). See C-17 in the header before adding a field OR touching the schema.
+ */
+export function readUpdateState() {
+    const path = getUpdateStatePath();
+    if (!existsSync(path))
+        return { ...DEFAULT_UPDATE_STATE };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return { ...DEFAULT_UPDATE_STATE };
+        if (parsed.schema !== UPDATE_STATE_SCHEMA)
+            return { ...DEFAULT_UPDATE_STATE };
+        return {
+            schema: UPDATE_STATE_SCHEMA,
+            lastCheckAt: count(parsed.lastCheckAt, DEFAULT_UPDATE_STATE.lastCheckAt),
+            lastKnownVersion: text(parsed.lastKnownVersion, DEFAULT_UPDATE_STATE.lastKnownVersion),
+            pendingRestartVersion: text(parsed.pendingRestartVersion, DEFAULT_UPDATE_STATE.pendingRestartVersion),
+            skippedVersion: text(parsed.skippedVersion, DEFAULT_UPDATE_STATE.skippedVersion),
+            consecutiveFailures: count(parsed.consecutiveFailures, DEFAULT_UPDATE_STATE.consecutiveFailures),
+            lastFailureAt: count(parsed.lastFailureAt, DEFAULT_UPDATE_STATE.lastFailureAt),
+            autoInstalledVersion: text(parsed.autoInstalledVersion, DEFAULT_UPDATE_STATE.autoInstalledVersion),
+            lastGoodVersion: text(parsed.lastGoodVersion, DEFAULT_UPDATE_STATE.lastGoodVersion),
+            bootFailures: count(parsed.bootFailures, DEFAULT_UPDATE_STATE.bootFailures),
+            rolledBackFrom: text(parsed.rolledBackFrom, DEFAULT_UPDATE_STATE.rolledBackFrom),
+        };
+    }
+    catch {
+        return { ...DEFAULT_UPDATE_STATE };
+    }
+}
+/**
+ * Atomic write: temp file, rename, re-chmod. Never throws.
+ *
+ * `mkdirSync` first for the reason `prompt-history.ts` and `ui-state.ts` both
+ * record: `<home>` is not guaranteed to exist, and without it the throttle would
+ * silently never persist on a fresh install - which presents as one registry
+ * request per launch forever.
+ */
+function writeUpdateState(state) {
+    const path = getUpdateStatePath();
+    const tmp = `${path}.tmp-${process.pid}`;
+    try {
+        mkdirSync(getHomeRoot(), { recursive: true });
+        writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+        renameSync(tmp, path);
+        if (process.platform !== 'win32')
+            chmodSync(path, 0o600);
+    }
+    catch {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // Nothing further to try; the value simply stays in memory.
+        }
+    }
+}
+/**
+ * Read-modify-write. READ-MODIFY-WRITE AND NOT WRITE, deliberately: another
+ * `aragon` may have recorded a check or an install between our read and this
+ * call, and clobbering its `lastCheckAt` is how ten terminals turn back into ten
+ * registry requests.
+ */
+export function updateUpdateState(patch) {
+    const next = { ...readUpdateState(), ...patch, schema: UPDATE_STATE_SCHEMA };
+    writeUpdateState(next);
+    return next;
+}

package/dist/update/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The updater's runtime shapes, plus the ONE pure predicate the renderer needs
+ * (cli-auto-update sections 5.3 / 5.3a).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * THE ONLY VALUE EXPORTED HERE IS `shouldRenderUpdateLine`. Everything else is a
+ * type, so `ui/UpdateLine.tsx` and `commands/registry.ts` can import from this
+ * module with `import type` and tsc erases the specifier entirely - no runtime
+ * edge from the renderer or the command registry into `update/` (section 3.1
+ * rule 1 / P1-7). This module and `limits.ts` import nothing but each other, are
+ * side-effect-free, and open no socket, spawn no process and create no timer.
+ */
+export type UpdatePhase = 'idle' | 'checking' | 'available' | 'installing' | 'ready' | 'failed';
+/**
+ * How the running copy of `aragon` got onto this machine (section 3.2).
+ *
+ * `npm-global` is the ONLY value that may be auto-installed, because it is the
+ * only one whose install target is unambiguous and verifiable from this machine
+ * (D-5). Everything else is advice, not execution.
+ */
+export type InstallSource = 'dev-monorepo' | 'npx' | 'pnpm' | 'yarn' | 'bun' | 'volta' | 'npm-local' | 'npm-global' | 'unknown';
+/** Why we are not installing, when we are not. Drives the advice line. */
+export type UpdateReason = 'up-to-date' | 'prerelease' | 'deprecated' | 'node-too-old' | 'skipped' | 'not-writable' | 'source-ineligible' | 'network' | 'install-failed' | 'locked'
+/** npm exited 0 but THIS root did not move - see U-6. */
+ | 'install-ineffective'
+/** EPERM / EBUSY / ETXTBSY - something holds the file we must replace. */
+ | 'blocked-by-os'
+/** ENOSPC. */
+ | 'no-space';
+/** The slice of the registry's dist-tag document this feature reads. */
+export interface LatestManifest {
+    name: string;
+    version: string;
+    engines?: {
+        node?: string;
+    };
+    /** Present ONLY when the version is deprecated; the string is the reason. */
+    deprecated?: string;
+}
+export interface UpdateSnapshot {
+    phase: UpdatePhase;
+    currentVersion: string;
+    latestVersion: string | null;
+    source: InstallSource;
+    reason?: UpdateReason;
+    /** Copy-pasteable command for an ineligible source. */
+    advice?: string;
+    /**
+     * The `engines.node` range the offered version demands, and the Node actually
+     * running - set ONLY on the `node-too-old` path.
+     *
+     * They exist because section 6.2 specifies that row as
+     * `<warn> 0.6.0 needs Node >=20 (running 18.19.0)`, and neither number is
+     * derivable from anything else on this object. "Needs a newer Node" without
+     * saying WHICH is the kind of notice a user cannot act on, which is exactly
+     * what D-7 spends the rest of this feature avoiding (IF-2).
+     */
+    requiredNode?: string;
+    runningNode?: string;
+    /**
+     * Set for the WHOLE session after a rollback, and deliberately NOT a `reason`
+     * (cli-auto-update-hardening section 5.2a / D-39).
+     *
+     * `reason` is rewritten by `setPhase` on EVERY transition, so the first
+     * scheduled check three seconds into the session would erase it before anyone
+     * read it. A fact that is true for a whole session needs a carrier the state
+     * machine does not own.
+     *
+     * BOTH, OR NEITHER, on the `requiredNode` / `runningNode` precedent above -
+     * half the pair is a notice nobody can read. Here it holds BY CONSTRUCTION
+     * rather than by discipline: `rolledBackTo` is the running version, assigned
+     * in the same two lines that read `rolledBackFrom` out of the state file.
+     */
+    rolledBackFrom?: string;
+    rolledBackTo?: string;
+    /**
+     * What `aragon update --rollback` would reinstall, read from the state file.
+     *
+     * On the snapshot rather than derived because `/update status` is the only
+     * place a user can find out what that command would DO before running it
+     * (section 6.3). See IF-1 in the hardening spec.
+     */
+    lastGoodVersion?: string;
+    /** Which probe answered the last successful check (H3). */
+    probe?: 'http' | 'npm';
+    nextCheckAt: number | null;
+    consecutiveFailures: number;
+}
+export type UpdateEvent = {
+    type: 'phase';
+    snapshot: UpdateSnapshot;
+} | {
+    type: 'log';
+    level: 'info' | 'warn';
+    msg: string;
+};
+/**
+ * The narrow surface `/update` sees (section 4.4 / C-14 / P0-2).
+ *
+ * `CommandContext` carries this rather than the service itself, and carries it
+ * as an OPTIONAL member: the service is legitimately absent under
+ * `update.mode: 'off'`, on a non-TTY and in CI, and a required field would break
+ * every existing `CommandContext` fixture at compile time.
+ *
+ * `UpdateService` satisfies it STRUCTURALLY, so nothing implements it explicitly
+ * and there is no adapter to keep in sync.
+ */
+export interface UpdateCommandPort {
+    snapshot(): UpdateSnapshot;
+    checkNow(opts?: {
+        force?: boolean;
+    }): Promise<UpdateSnapshot>;
+    skip(version: string): void;
+    nextCheckAt(): number | null;
+}
+/** What the renderer needs on top of the command port: a subscription. */
+export interface UpdateServiceHandle extends UpdateCommandPort {
+    subscribe(fn: (snapshot: UpdateSnapshot) => void): () => void;
+}
+/**
+ * The late-arrival channel between `cli.tsx` and `App` (IF-4).
+ *
+ * The service is constructed through a DYNAMIC `import()` fired AFTER
+ * `render()` (section 3.8 / D-25), so it does not exist when `App` mounts and
+ * cannot be an ordinary prop. This is the same shape `ConfirmBridge` and
+ * `HumanInputBridge` already use for exactly the same reason: a mutable object
+ * created before `render()`, populated by whichever side arrives second.
+ *
+ * A PLAIN INTERFACE AND NOT A CLASS, so `cli.tsx` builds one with an object
+ * literal and needs no runtime import from `update/` (AC-1).
+ */
+export interface UpdateBridge {
+    /** Set once the dynamically-imported service exists; `null` until then. */
+    service: UpdateServiceHandle | null;
+    /** Set by `App` on mount, so a service that arrives later can wake it. */
+    onAttach: ((service: UpdateServiceHandle) => void) | null;
+}
+/**
+ * The reasons allowed to break the three-strike silence rule (D-7 / D-33),
+ * because each is both ACTIONABLE BY THE USER and NOT SELF-HEALING.
+ *
+ * THE MEMBERSHIP RULE IS THE WHOLE MECHANISM, not the list. `network` fails both
+ * halves - the user cannot fix the registry and the next check may well succeed -
+ * so it stays silent and backs off, which is the entire reason a background
+ * updater is tolerable at all. The three below will otherwise repeat identically
+ * until the user does something, which is the definition of a notice worth
+ * showing once. Anything added here without passing both halves is the first
+ * step of the notification fatigue the rest of this feature is built to avoid
+ * (R-20).
+ */
+export declare const IMMEDIATE_NOTICE_REASONS: ReadonlySet<UpdateReason>;
+/**
+ * Whether the bottom row has anything to say. PURE, and deliberately NOT
+ * expressed as `UpdateLine` returning `null` (C-15 / P0-1 / D-19).
+ *
+ * A component that returns `null` still satisfies `if (update)` at the call site
+ * - the prop is a React ELEMENT, and an element is truthy however it renders.
+ * The row would become `<Box flexShrink={0}>{nothing}</Box>`, which in
+ * full-screen is ZERO rows, and the transcript silently gains a row for as long
+ * as the updater is idle and loses it again the moment it has news. That is
+ * precisely the layout shift `BottomStatusRow` exists to prevent, and
+ * `bottom-status-row.test.tsx`'s "holds one row in all four states" is the
+ * assertion it would defeat.
+ *
+ * `ActivityLine` already settles the pattern: it ALWAYS returns an element, and
+ * `App.tsx` decides presence at the call site with `running && !overlayNode`.
+ */
+export declare function shouldRenderUpdateLine(snapshot: UpdateSnapshot): boolean;

package/dist/update/types.js

@@ -0,0 +1,68 @@
+/**
+ * The updater's runtime shapes, plus the ONE pure predicate the renderer needs
+ * (cli-auto-update sections 5.3 / 5.3a).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * THE ONLY VALUE EXPORTED HERE IS `shouldRenderUpdateLine`. Everything else is a
+ * type, so `ui/UpdateLine.tsx` and `commands/registry.ts` can import from this
+ * module with `import type` and tsc erases the specifier entirely - no runtime
+ * edge from the renderer or the command registry into `update/` (section 3.1
+ * rule 1 / P1-7). This module and `limits.ts` import nothing but each other, are
+ * side-effect-free, and open no socket, spawn no process and create no timer.
+ */
+import { UPDATE_LIMITS } from './limits.js';
+/**
+ * The reasons allowed to break the three-strike silence rule (D-7 / D-33),
+ * because each is both ACTIONABLE BY THE USER and NOT SELF-HEALING.
+ *
+ * THE MEMBERSHIP RULE IS THE WHOLE MECHANISM, not the list. `network` fails both
+ * halves - the user cannot fix the registry and the next check may well succeed -
+ * so it stays silent and backs off, which is the entire reason a background
+ * updater is tolerable at all. The three below will otherwise repeat identically
+ * until the user does something, which is the definition of a notice worth
+ * showing once. Anything added here without passing both halves is the first
+ * step of the notification fatigue the rest of this feature is built to avoid
+ * (R-20).
+ */
+export const IMMEDIATE_NOTICE_REASONS = new Set([
+    'blocked-by-os',
+    'no-space',
+    'not-writable',
+]);
+/**
+ * Whether the bottom row has anything to say. PURE, and deliberately NOT
+ * expressed as `UpdateLine` returning `null` (C-15 / P0-1 / D-19).
+ *
+ * A component that returns `null` still satisfies `if (update)` at the call site
+ * - the prop is a React ELEMENT, and an element is truthy however it renders.
+ * The row would become `<Box flexShrink={0}>{nothing}</Box>`, which in
+ * full-screen is ZERO rows, and the transcript silently gains a row for as long
+ * as the updater is idle and loses it again the moment it has news. That is
+ * precisely the layout shift `BottomStatusRow` exists to prevent, and
+ * `bottom-status-row.test.tsx`'s "holds one row in all four states" is the
+ * assertion it would defeat.
+ *
+ * `ActivityLine` already settles the pattern: it ALWAYS returns an element, and
+ * `App.tsx` decides presence at the call site with `running && !overlayNode`.
+ */
+export function shouldRenderUpdateLine(snapshot) {
+    if (snapshot.phase === 'available' ||
+        snapshot.phase === 'installing' ||
+        snapshot.phase === 'ready') {
+        return true;
+    }
+    if (snapshot.phase === 'failed') {
+        if (snapshot.reason && IMMEDIATE_NOTICE_REASONS.has(snapshot.reason))
+            return true;
+        return snapshot.consecutiveFailures >= UPDATE_LIMITS.failuresBeforeNotice;
+    }
+    // `idle` / `checking` - the two phases the user must never be told about,
+    // EXCEPT for a rollback this session has not yet reported. Placed LAST on
+    // purpose: any real news above owns the row first, and the budget is one row
+    // (C-15). It is therefore possible for the notice never to appear on a machine
+    // that has an update waiting on the very next launch, which is the correct
+    // trade - the newer fact is the more actionable one, and the rollback is still
+    // in `/update status` and in the log.
+    return Boolean(snapshot.rolledBackFrom);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -28,7 +28,7 @@
   },
   "type": "module",
   "bin": {
-    "aragon": "./dist/cli.js"
+    "aragon": "./dist/launcher.js"
   },
   "files": [
     "dist",
@@ -52,7 +52,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.8",
+    "@aragon-agent/core": "^0.2.10",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",

package/dist/ui/layout/regions.d.ts

@@ -1,55 +0,0 @@
-/**
- * Wheel band hit-testing (mouse-wheel-region-routing §4.5) — pure, React-free.
- *
- * The requirement is stated in terms of REGIONS ("scrolling over the agent area
- * scrolls the transcript; scrolling over the input box steps prompt history"),
- * so the router needs to turn a reported terminal row into one of two bands.
- *
- * The boundary is MEASURED, never computed from `budget.ts`. That arithmetic
- * describes the PLANNED chrome, but the real bottom chrome grows and shrinks at
- * run time: the toast row comes and goes, the hint row is dropped below
- * `HINT_MIN_ROWS`, and the autocomplete popup adds up to nine rows. Routing off
- * the plan would put the boundary in the wrong place exactly when the popup is
- * open — the moment precision matters most (D-5 / D-16).
- */
-export type WheelBand = 'content' | 'composer';
-export interface FrameGeometry {
-    /**
-     * 1-based row of the frame's first row. 1 in the alternate screen.
-     *
-     * This is DERIVED, not assumed, and it has a named dependency: it holds
-     * because the full-screen transcript renders no `<Static>`
-     * (`Transcript.tsx`), so Ink's `log-update` writes `frameHeight(rows) = rows-1`
-     * lines plus a newline into a `rows`-row buffer — nothing scrolls, and the
-     * frame sits at rows `1 … rows-1` with the cursor parked on the undrawn last
-     * row. Reintroducing `<Static>` into the full-screen path pushes the frame
-     * down the screen and silently biases every hit test; whoever does that has
-     * to change `top` here at the same time.
-     */
-    top: number;
-    /** Rows the frame occupies — `frameHeight(rows)`. */
-    height: number;
-    /** Measured rows of the bottom chrome (toast + composer + status). */
-    bottom: number;
-}
-/**
- * The "I do not know where the frame is" value.
- *
- * `App` writes it into the geometry ref on every render path that does NOT
- * render the full-screen `AppShell` — the terminal-too-small placeholder and
- * inline mode — so a stale measurement can never outlive the frame it
- * described. There is deliberately no arithmetic fallback: an unmeasured frame
- * routes to `'content'`, which is the band that cannot destroy anything, and
- * one invisible frame after a resize is a better failure than a wrong band
- * (§4.5, P1-5 / D-16).
- */
-export declare const UNMEASURED_GEOMETRY: FrameGeometry;
-/**
- * Which band does terminal row `y` belong to?
- *
- * Fails toward `'content'`: the whole point of this feature is that a wheel
- * notch must never edit the user's draft (I-3), so every degenerate input —
- * nothing measured yet, a row outside the frame, a chrome measurement that
- * swallowed the screen — resolves to the harmless direction.
- */
-export declare function hitTestWheel(y: number, geometry: FrameGeometry): WheelBand;

package/dist/ui/layout/regions.js

@@ -1,52 +0,0 @@
-/**
- * Wheel band hit-testing (mouse-wheel-region-routing §4.5) — pure, React-free.
- *
- * The requirement is stated in terms of REGIONS ("scrolling over the agent area
- * scrolls the transcript; scrolling over the input box steps prompt history"),
- * so the router needs to turn a reported terminal row into one of two bands.
- *
- * The boundary is MEASURED, never computed from `budget.ts`. That arithmetic
- * describes the PLANNED chrome, but the real bottom chrome grows and shrinks at
- * run time: the toast row comes and goes, the hint row is dropped below
- * `HINT_MIN_ROWS`, and the autocomplete popup adds up to nine rows. Routing off
- * the plan would put the boundary in the wrong place exactly when the popup is
- * open — the moment precision matters most (D-5 / D-16).
- */
-/**
- * The "I do not know where the frame is" value.
- *
- * `App` writes it into the geometry ref on every render path that does NOT
- * render the full-screen `AppShell` — the terminal-too-small placeholder and
- * inline mode — so a stale measurement can never outlive the frame it
- * described. There is deliberately no arithmetic fallback: an unmeasured frame
- * routes to `'content'`, which is the band that cannot destroy anything, and
- * one invisible frame after a resize is a better failure than a wrong band
- * (§4.5, P1-5 / D-16).
- */
-export const UNMEASURED_GEOMETRY = { top: 1, height: 0, bottom: 0 };
-/**
- * Which band does terminal row `y` belong to?
- *
- * Fails toward `'content'`: the whole point of this feature is that a wheel
- * notch must never edit the user's draft (I-3), so every degenerate input —
- * nothing measured yet, a row outside the frame, a chrome measurement that
- * swallowed the screen — resolves to the harmless direction.
- */
-export function hitTestWheel(y, geometry) {
-    const { top, height } = geometry;
-    if (!Number.isFinite(height) || height <= 0)
-        return 'content';
-    if (!Number.isFinite(y))
-        return 'content';
-    // Clamp into the frame so the one undrawn bottom row — and any off-by-one
-    // from a terminal that reports 0-based rows — lands on a real band instead of
-    // being dropped.
-    const row = Math.min(Math.max(Math.floor(y), top), top + height - 1);
-    // I-6: at least one content row always survives. This clamp is a backstop
-    // that should never fire, and that is checkable rather than hopeful: the
-    // completion popup is capped at `viewportRows(rows) - 4`, so the measured
-    // chrome tops out at `rows - 6` against a frame of `rows - 1` — five content
-    // rows survive the worst case the layout can produce.
-    const bottom = Math.min(Math.max(Math.floor(geometry.bottom) || 0, 0), height - 1);
-    return row >= top + height - bottom ? 'composer' : 'content';
-}