@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/model/tools/terminal-output.js

@@ -0,0 +1,201 @@
+/**
+ * Raw child-process output to terminal-safe rows (agent-activity-presentation-live
+ * L2 / §3.2).
+ *
+ * NOTHING ELSE IN THIS TREE STRIPS ANSI (E-13). `renderBash` hands each line to
+ * `<Text>` unmodified (`ui/entries/ToolPreview.tsx:180`), and that survives only
+ * because the settled preview is printed ONCE, after the command has stopped
+ * writing. Redraw the same text every frame while the child is still emitting
+ * `\r`-rewritten progress bars and `\x1b[A` cursor moves and it stops being
+ * survivable: the terminal honours cursor motion Ink does not know it emitted,
+ * and `wrappedRows` measures escape bytes as if they were columns.
+ *
+ * So this module is the boundary. It runs ONCE, inside the store's `append`
+ * (§3.1.1), and every reader downstream is already safe.
+ *
+ * Pure, ASCII-only, React-free, Ink-free, and TOTAL: `sanitizeChunk` never
+ * throws, for any input including lone surrogates, NUL bytes, a chunk consisting
+ * solely of `\x1b`, and a 4 MB chunk containing no `\n` at all.
+ *
+ * D-27 — IT STRIPS, IT DOES NOT INTERPRET. Keeping colour would mean validating
+ * it (an unterminated SGR leaks its attribute into the rest of the frame), and
+ * interpreting cursor motion would mean owning a screen buffer. Neither is a
+ * presentation round's job.
+ */
+import { stripControlSequences } from '../../input/control-sequences.js';
+/** Columns a live row may occupy before it is clipped. */
+export const LIVE_ROW_MAX_CHARS = 200;
+/** Tab stop width, matching every terminal's default. */
+export const TAB_WIDTH = 8;
+/**
+ * The in-progress line's ceiling before it is flushed as a row (§3.2 step 7).
+ *
+ * AFTER STEP 4 THIS IS A RARE PATH RATHER THAN THE PROGRESS-BAR PATH (D-33). A
+ * `\r`-rewritten bar collapses to one row however many times it is redrawn, so
+ * reaching 400 characters with no `\n` requires a line that is genuinely that
+ * long -- `cat` on a minified bundle. Without the bound the carry is an
+ * unbounded accumulator.
+ */
+export const CARRY_MAX_CHARS = LIVE_ROW_MAX_CHARS * 2;
+/**
+ * Appended to a row clipped at `LIVE_ROW_MAX_CHARS`.
+ *
+ * SPELLED HERE RATHER THAN IMPORTED from `agent/reducer.ts`, the rule
+ * `patch.ts:95-103` already states for the identical string: `tools/` keeps no
+ * runtime dependency on the view model for three characters, and
+ * `terminal-output.test.ts` asserts the spellings are equal so the pair cannot
+ * drift silently.
+ */
+export const TRUNCATION_MARK = '...';
+/**
+ * How far back a trailing incomplete escape may start.
+ *
+ * A chunk can split mid-escape, and the next chunk completes it -- so the tail
+ * of an unfinished sequence must survive in the carry rather than being stripped
+ * down to its visible remainder (`\x1b[` would otherwise render as a bare `[`).
+ * The lookback is bounded because an "escape" that has run for 64 characters
+ * without a final byte is not an escape, it is a byte that happened to be 0x1b,
+ * and holding it forever would pin the carry.
+ */
+const MAX_PARTIAL_ESCAPE = 64;
+/** C1, plus every C0 control except `\t` `\n` `\r`. */
+const CONTROLS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
+/**
+ * Remove every escape sequence and control byte except `\t` `\n` `\r`.
+ *
+ * SEQUENCE SYNTAX HAS ONE OWNER (`input/control-sequences.ts`); this function
+ * adds only the control-byte sweep a DISPLAY row wants. Both call sites in this
+ * module already cut an unfinished escape off into the carry before calling it
+ * (`partialEscapeStart`), so the shared one-shot rule for a truncated sequence
+ * is exactly what they need -- and it fixes AC-24's failure in place: the old
+ * two-byte rule consumed the `\x1b[` of an unfinished CSI and left the
+ * PARAMETERS behind, so `\x1b[31m` split across chunks rendered as `red 3`.
+ *
+ * Exported for the tests, and used by `toDisplayRow` as the second line of
+ * defence over a carry that ends mid-escape.
+ */
+export function stripAnsi(text) {
+    return stripControlSequences(text).replace(CONTROLS, '');
+}
+/**
+ * Index at which a trailing INCOMPLETE escape begins, or `-1`.
+ *
+ * Only the last `\x1b` can be incomplete: anything before it is either a
+ * complete sequence (the regexes above consume it) or a stray byte the control
+ * strip removes.
+ */
+function partialEscapeStart(text) {
+    const at = text.lastIndexOf('\x1b');
+    if (at === -1 || text.length - at > MAX_PARTIAL_ESCAPE)
+        return -1;
+    const rest = text.slice(at);
+    // A lone ESC at the very end: the next chunk decides what it is.
+    if (rest.length === 1)
+        return at;
+    // An opened CSI/OSC is incomplete exactly when its own regex does not match
+    // from here -- `\x1b[1;3` has no final byte yet, `\x1b]0;title` no terminator.
+    if (rest[1] === '[')
+        return /^\x1b\[[0-?]*[ -/]*[@-~]/.test(rest) ? -1 : at;
+    if (rest[1] === ']')
+        return /^\x1b\][\s\S]*?(?:\x07|\x1b\\)/.test(rest) ? -1 : at;
+    // Any other two-byte form is already complete.
+    return -1;
+}
+/**
+ * Apply `\r` as the LINE REWRITE it is (§3.2 step 4 / D-33).
+ *
+ * A piece containing `\r` is a sequence of overwrites, so the later segment
+ * replaces the earlier one's PREFIX and anything the earlier one had beyond it
+ * survives -- which is what a real terminal shows, and what keeps R-6's classic
+ * `\r`-only tooling from losing content. A thousand progress-bar rewrites
+ * collapse to one row holding the final state.
+ */
+export function applyCarriageReturns(piece) {
+    if (piece.indexOf('\r') === -1)
+        return piece;
+    return piece.split('\r').reduce((acc, s) => s + acc.slice(s.length), '');
+}
+/** Expand tabs to the next multiple of `TAB_WIDTH`. */
+export function expandTabs(row) {
+    if (row.indexOf('\t') === -1)
+        return row;
+    let out = '';
+    for (let i = 0; i < row.length; i += 1) {
+        const ch = row[i];
+        if (ch === '\t')
+            out += ' '.repeat(TAB_WIDTH - (out.length % TAB_WIDTH));
+        else
+            out += ch;
+    }
+    return out;
+}
+/** Clip a row at `LIVE_ROW_MAX_CHARS`, marking the cut. */
+export function clipRow(row) {
+    return row.length <= LIVE_ROW_MAX_CHARS
+        ? row
+        : `${row.slice(0, LIVE_ROW_MAX_CHARS)}${TRUNCATION_MARK}`;
+}
+/**
+ * The carry as a RENDERED row: the held-back incomplete escape removed, then
+ * stripped and clipped.
+ *
+ * THE PARTIAL MUST BE CUT OFF, NOT STRIPPED (AC-24). `stripAnsi` alone is not
+ * enough and fails in the visible direction: its two-byte rule consumes the
+ * `\x1b[` of an unfinished CSI and leaves the PARAMETERS behind, so a chunk that
+ * split inside `\x1b[31m` renders as `red 3`. The bytes are held for the next
+ * chunk to complete; until then they are not text.
+ */
+export function toDisplayRow(carry) {
+    const at = partialEscapeStart(carry);
+    return clipRow(stripAnsi(at === -1 ? carry : carry.slice(0, at)));
+}
+/**
+ * Tab expansion is column arithmetic, so it cannot be done after the clip -- but
+ * it also need not run over four megabytes to decide the first 200 columns.
+ * Every character occupies at least one column, so a `CARRY_MAX_CHARS` prefix
+ * covers every column the clip can keep.
+ */
+function expandTabsForDisplay(piece) {
+    return piece.length <= CARRY_MAX_CHARS
+        ? expandTabs(piece)
+        : expandTabs(piece.slice(0, CARRY_MAX_CHARS));
+}
+/**
+ * Turn a raw chunk into complete rows plus the in-progress line.
+ *
+ * The order of the steps IS the specification (§3.2), and step 4's "every piece,
+ * THE INCOMPLETE TAIL INCLUDED" is the whole of P0-1: a progress bar emits no
+ * `\n` for its entire run, so a rule that collapsed only completed lines would
+ * never run for npm, pip, curl, docker or any other `\r` writer -- the tail
+ * would stay empty, `showLive` false, and the card the single `running` row this
+ * round exists to replace.
+ */
+export function sanitizeChunk(carry, chunk) {
+    const text = (typeof carry === 'string' ? carry : '') + (typeof chunk === 'string' ? chunk : '');
+    if (text.length === 0)
+        return { rows: [], carry: '' };
+    // 1-2. Concatenate and strip, holding back an escape the next chunk finishes.
+    const partialAt = partialEscapeStart(text);
+    const held = partialAt === -1 ? '' : text.slice(partialAt);
+    const clean = stripAnsi(partialAt === -1 ? text : text.slice(0, partialAt));
+    // 3. Split: the first n-1 pieces are complete rows, the last is the tail.
+    const pieces = clean.split('\n');
+    const rows = [];
+    for (let i = 0; i < pieces.length - 1; i += 1) {
+        // 4-6. Collapse, expand, clip.
+        rows.push(clipRow(expandTabsForDisplay(applyCarriageReturns(pieces[i]))));
+    }
+    const rawTail = applyCarriageReturns(pieces[pieces.length - 1]);
+    const tail = expandTabsForDisplay(rawTail);
+    // 7. Bound the carry. The held escape survives the flush: it belongs to the
+    // NEXT row, and dropping it here would corrupt the sequence it opened.
+    //
+    // BOTH LENGTHS ARE TESTED, and testing only the expanded one is the bug:
+    // `expandTabsForDisplay` truncates its input at `CARRY_MAX_CHARS`, so a
+    // megabyte-long line would sit at exactly the bound forever and never flush.
+    if (rawTail.length > CARRY_MAX_CHARS || tail.length > CARRY_MAX_CHARS) {
+        rows.push(clipRow(tail));
+        return { rows, carry: held };
+    }
+    return { rows, carry: tail + held };
+}

package/dist/model/tools/tool-output-store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The CLI-local side channel a running tool's output travels on
+ * (agent-activity-presentation-live L1 / §3.1.1).
+ *
+ * It mirrors `file-change-store.ts` in shape and in its documented reasoning,
+ * with ONE deliberate difference: it is PEEK-AND-CLEAR, not take-once, because a
+ * running command is read many times and consumed once.
+ *
+ * Four properties, each load-bearing, each with the failure it prevents:
+ *
+ *  - **Owner-scoped.** The key is `${owner}:${toolCallId}`, for D-13's reason
+ *    unchanged: only `'lead'` is written this round, but subagents build their
+ *    tools from the same factory, and a child's tool-call id must never be able
+ *    to paint a lead's card.
+ *  - **Sanitised on write.** `append` calls `sanitizeChunk` BEFORE storing, so
+ *    the store's contract is "terminal-safe rows" and no consumer can forget.
+ *  - **Bounded twice.** `LIVE_TAIL_ROWS` per call and `TOOL_OUTPUT_STORE_CAP`
+ *    calls. A command emitting 400 MB to stdout costs a fixed number of retained
+ *    rows: the per-call bound is what makes the DISPLAY bounded, the cap is what
+ *    makes a session that never settles a call bounded.
+ *  - **Cleared at settle, not at read.** The authoritative result arrives with
+ *    `tool_execution_end`; from that instant the tail is superseded and must be
+ *    released. Clearing there keeps the store's size a function of CONCURRENT
+ *    calls rather than of total calls.
+ */
+/**
+ * ROWS retained per tool call.
+ *
+ * THIS AND THE CAP BELOW ARE DELIBERATELY DIFFERENT NUMBERS (P2-8). They bound
+ * unrelated things -- rows inside one call, and calls inside one session -- and
+ * a shared literal is how a later edit collapses two bounds into one.
+ */
+export declare const LIVE_TAIL_ROWS = 8;
+/** CONCURRENT CALLS retained before the oldest is evicted. */
+export declare const TOOL_OUTPUT_STORE_CAP = 16;
+/**
+ * Silence after which the card stops claiming progress and says so (§3.3.4).
+ *
+ * It lives here rather than in `ToolCard` because it is the STORE's notion of
+ * "quiet": the card reads it so there is no second copy to drift.
+ */
+export declare const STALL_AFTER_MS = 10000;
+export interface ToolOutputStore {
+    /**
+     * Append a raw chunk. Sanitises (§3.2), then returns the display tail: the
+     * last `LIVE_TAIL_ROWS` of `[...completedRows, carry]`, `carry` last and
+     * included only when non-empty.
+     */
+    append(owner: string, toolCallId: string, chunk: string): readonly string[];
+    /** Current tail, or `undefined`. Does NOT remove. Test-facing (P2-2). */
+    peek(owner: string, toolCallId: string): readonly string[] | undefined;
+    /** Drop the entry -- called at `tool_execution_end`. */
+    clear(owner: string, toolCallId: string): void;
+    size(): number;
+}
+/**
+ * What the controller's fourth CLI-local emitter carries (§3.1.3).
+ *
+ * `rows` IS THE WHOLE TAIL, not an increment, and that is what lets
+ * `mergeDeltas` keep only the last one per `toolCallId` (D-30). It is frozen, so
+ * a listener cannot mutate the array a later listener will see.
+ */
+export interface ToolOutputEvent {
+    toolCallId: string;
+    rows: readonly string[];
+}
+export type ToolOutputListener = (event: ToolOutputEvent) => void;
+export declare function createToolOutputStore(cap?: number): ToolOutputStore;

package/dist/model/tools/tool-output-store.js

@@ -0,0 +1,102 @@
+/**
+ * The CLI-local side channel a running tool's output travels on
+ * (agent-activity-presentation-live L1 / §3.1.1).
+ *
+ * It mirrors `file-change-store.ts` in shape and in its documented reasoning,
+ * with ONE deliberate difference: it is PEEK-AND-CLEAR, not take-once, because a
+ * running command is read many times and consumed once.
+ *
+ * Four properties, each load-bearing, each with the failure it prevents:
+ *
+ *  - **Owner-scoped.** The key is `${owner}:${toolCallId}`, for D-13's reason
+ *    unchanged: only `'lead'` is written this round, but subagents build their
+ *    tools from the same factory, and a child's tool-call id must never be able
+ *    to paint a lead's card.
+ *  - **Sanitised on write.** `append` calls `sanitizeChunk` BEFORE storing, so
+ *    the store's contract is "terminal-safe rows" and no consumer can forget.
+ *  - **Bounded twice.** `LIVE_TAIL_ROWS` per call and `TOOL_OUTPUT_STORE_CAP`
+ *    calls. A command emitting 400 MB to stdout costs a fixed number of retained
+ *    rows: the per-call bound is what makes the DISPLAY bounded, the cap is what
+ *    makes a session that never settles a call bounded.
+ *  - **Cleared at settle, not at read.** The authoritative result arrives with
+ *    `tool_execution_end`; from that instant the tail is superseded and must be
+ *    released. Clearing there keeps the store's size a function of CONCURRENT
+ *    calls rather than of total calls.
+ */
+import { sanitizeChunk, toDisplayRow } from './terminal-output.js';
+/**
+ * ROWS retained per tool call.
+ *
+ * THIS AND THE CAP BELOW ARE DELIBERATELY DIFFERENT NUMBERS (P2-8). They bound
+ * unrelated things -- rows inside one call, and calls inside one session -- and
+ * a shared literal is how a later edit collapses two bounds into one.
+ */
+export const LIVE_TAIL_ROWS = 8;
+/** CONCURRENT CALLS retained before the oldest is evicted. */
+export const TOOL_OUTPUT_STORE_CAP = 16;
+/**
+ * Silence after which the card stops claiming progress and says so (§3.3.4).
+ *
+ * It lives here rather than in `ToolCard` because it is the STORE's notion of
+ * "quiet": the card reads it so there is no second copy to drift.
+ */
+export const STALL_AFTER_MS = 10_000;
+const EMPTY = Object.freeze([]);
+export function createToolOutputStore(cap = TOOL_OUTPUT_STORE_CAP) {
+    // A `Map` iterates in insertion order, so the first key IS the oldest.
+    const entries = new Map();
+    const limit = Math.max(1, Math.floor(cap));
+    const keyOf = (owner, toolCallId) => `${owner}:${toolCallId}`;
+    /**
+     * The tail a consumer sees.
+     *
+     * THE IN-PROGRESS LINE IS PART OF IT, and that is the display half of P0-1: a
+     * command whose output is one continuously-rewritten line -- every progress
+     * bar there is -- has NO completed rows until it exits, and a tail built from
+     * completed rows alone would be empty for its entire run.
+     */
+    const tailOf = (slot) => {
+        const live = toDisplayRow(slot.carry);
+        const rows = live.length > 0 ? [...slot.rows, live] : [...slot.rows];
+        return Object.freeze(rows.length > LIVE_TAIL_ROWS ? rows.slice(-LIVE_TAIL_ROWS) : rows);
+    };
+    return {
+        append(owner, toolCallId, chunk) {
+            const key = keyOf(owner, toolCallId);
+            const slot = entries.get(key) ?? { rows: [], carry: '' };
+            // Delete first so an append moves the key to the END of the ring rather
+            // than leaving it at its original age: the cap must evict the least
+            // recently WRITTEN call, not the one that started first.
+            entries.delete(key);
+            entries.set(key, slot);
+            const { rows, carry } = sanitizeChunk(slot.carry, chunk);
+            if (rows.length > 0) {
+                slot.rows.push(...rows);
+                if (slot.rows.length > LIVE_TAIL_ROWS) {
+                    slot.rows.splice(0, slot.rows.length - LIVE_TAIL_ROWS);
+                }
+            }
+            slot.carry = carry;
+            while (entries.size > limit) {
+                const oldest = entries.keys().next();
+                if (oldest.done)
+                    break;
+                entries.delete(oldest.value);
+            }
+            return tailOf(slot);
+        },
+        peek(owner, toolCallId) {
+            const slot = entries.get(keyOf(owner, toolCallId));
+            if (!slot)
+                return undefined;
+            const tail = tailOf(slot);
+            return tail.length > 0 ? tail : EMPTY;
+        },
+        clear(owner, toolCallId) {
+            entries.delete(keyOf(owner, toolCallId));
+        },
+        size() {
+            return entries.size;
+        },
+    };
+}

package/dist/model/update/limits.d.ts

@@ -0,0 +1,111 @@
+/**
+ * UPDATE_LIMITS - the single authority on every structural bound the updater
+ * enforces (cli-auto-update section 5.4).
+ *
+ * ASCII ONLY: `src/update/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte. The
+ * regex there is a hardcoded directory list, which is why adding this tree and
+ * adding `update` to that list are the SAME change (C-2 / AC-18) - a scanner
+ * that silently stops scanning is worse than no scanner.
+ *
+ * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE - the distinction
+ * `TEAM_LIMITS`, `TODO_LIMITS` and `FAST_LIMITS` all state:
+ *
+ *  - The entries below are STRUCTURAL. They describe what a background check, a
+ *    detached install and a one-row readout can physically carry. A user has no
+ *    business tuning them.
+ *  - The four `update.*` keys in `config/schema.ts` are POLICY: whether to
+ *    install at all, how often to ask, which registry, which dist-tag. Those are
+ *    clamped, persisted and user-facing.
+ *
+ * NOTHING HERE IS IMPORTED AT RUNTIME BY `cli.tsx` (AC-1). This module and
+ * `types.ts` are pure, dependency-free and side-effect-free; every other module
+ * in this tree is reached only through the dynamic `import()` in section 3.8.
+ */
+export declare const UPDATE_LIMITS: {
+    /** Never contend with first paint. */
+    readonly startupDelayMs: 3000;
+    /**
+     * A background check has nobody waiting on it.
+     *
+     * Below `fetch-source.ts`'s `HTTP_TIMEOUT_MS` (15 s) ON PURPOSE: that one
+     * bounds a download a human typed a command for, this one bounds a request the
+     * user never asked for and must never notice.
+     */
+    readonly checkTimeoutMs: 8000;
+    /**
+     * Wall-clock budget for the `installing` PHASE and the lock's staleness
+     * refresh - NEVER FOR THE CHILD (U-5 / P1-5).
+     *
+     * It decides when the UI stops saying "updating" and when a lock is treated as
+     * abandoned. It is deliberately NOT `execFile`'s `timeout`, which stays `0`:
+     * wiring it there makes Node `SIGTERM` npm mid-write - the broken global
+     * installation U-3 and D-10 exist to prevent - and it would fire on exactly
+     * the slow links where a five-minute install is the correct outcome.
+     */
+    readonly installTimeoutMs: 300000;
+    /** The `/latest` document is ~2 KB; this is the C-8 ceiling, not a target. */
+    readonly manifestMaxBytes: number;
+    /** Matches `fetch-source.ts`'s `MAX_REDIRECTS`. */
+    readonly maxRedirects: 3;
+    /**
+     * Longer than `skills`' 60 s, and the difference is the point: the holder here
+     * is an npm install on a cold cache, not a file rename.
+     */
+    readonly lockTtlMs: 600000;
+    /** First retry after a failed check or install. */
+    readonly backoffBaseMs: 1800000;
+    /** Ceiling of the exponential. */
+    readonly backoffMaxMs: 86400000;
+    /**
+     * Consecutive failures before the row says anything at all (D-7).
+     *
+     * Below this the failure is silent, because silence is the requirement and an
+     * unactionable recurring warning is the standard way updaters become hated.
+     */
+    readonly failuresBeforeNotice: 3;
+    /** Thundering-herd spread on the check interval (D-12). */
+    readonly jitterRatio: 0.15;
+    /**
+     * Bounded, redacted npm error tail, read from the install LOG FILE (U-5).
+     *
+     * There is a tail to read at all only because the child writes to a real file
+     * descriptor rather than to `'ignore'`; a pipe would have died with the parent
+     * and broken D-10.
+     */
+    readonly stderrTailChars: 500;
+    /**
+     * Below this many columns the update line renders its short form (section 6.2).
+     *
+     * DELIBERATELY NOT `FAST_LIMITS.statusCompactCols`' 100 (`fast/limits.ts`).
+     * That number governs a multi-part status chip competing with the context
+     * gauge for the same row; this one governs a single short clause that owns its
+     * row outright. Two numbers about two different things - do not unify them.
+     */
+    readonly statusCompactCols: 60;
+    /**
+     * Non-zero exits of a version WE installed before it is rolled back
+     * (cli-auto-update-hardening section 7.2 / D-30).
+     *
+     * Tested against the count of PREVIOUS launches, so `2` means "the third
+     * launch rolls back". One crash can be transient - a machine that ran out of
+     * memory once, or whose session file was corrupt, gets a second chance at the
+     * release it just installed. Two is a pattern.
+     *
+     * NOTHING ELSE IN THIS TABLE BOUNDS THE ROLLBACK. There is deliberately no
+     * `bootGuardMaxAgeMs`: the guard is armed only while `autoInstalledVersion`
+     * equals the RUNNING version, so "a machine offline for a year" is a machine
+     * still running the version we installed, and rolling it back to
+     * `lastGoodVersion` is exactly as correct on day 400 as on day 1 (P1-3).
+     */
+    readonly crashesBeforeRollback: 2;
+    /**
+     * Bound on the `npm view` fallback probe (H3).
+     *
+     * SAFE HERE AND FORBIDDEN FOR THE INSTALLER (C-20). A killed `npm view` has
+     * written nothing; a killed `npm install -g` leaves a broken global
+     * installation, which is why `installTimeoutMs` above bounds the PHASE and
+     * never the child.
+     */
+    readonly npmViewTimeoutMs: 10000;
+};

package/dist/model/update/limits.js

@@ -0,0 +1,111 @@
+/**
+ * UPDATE_LIMITS - the single authority on every structural bound the updater
+ * enforces (cli-auto-update section 5.4).
+ *
+ * ASCII ONLY: `src/update/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte. The
+ * regex there is a hardcoded directory list, which is why adding this tree and
+ * adding `update` to that list are the SAME change (C-2 / AC-18) - a scanner
+ * that silently stops scanning is worse than no scanner.
+ *
+ * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE - the distinction
+ * `TEAM_LIMITS`, `TODO_LIMITS` and `FAST_LIMITS` all state:
+ *
+ *  - The entries below are STRUCTURAL. They describe what a background check, a
+ *    detached install and a one-row readout can physically carry. A user has no
+ *    business tuning them.
+ *  - The four `update.*` keys in `config/schema.ts` are POLICY: whether to
+ *    install at all, how often to ask, which registry, which dist-tag. Those are
+ *    clamped, persisted and user-facing.
+ *
+ * NOTHING HERE IS IMPORTED AT RUNTIME BY `cli.tsx` (AC-1). This module and
+ * `types.ts` are pure, dependency-free and side-effect-free; every other module
+ * in this tree is reached only through the dynamic `import()` in section 3.8.
+ */
+export const UPDATE_LIMITS = {
+    /** Never contend with first paint. */
+    startupDelayMs: 3_000,
+    /**
+     * A background check has nobody waiting on it.
+     *
+     * Below `fetch-source.ts`'s `HTTP_TIMEOUT_MS` (15 s) ON PURPOSE: that one
+     * bounds a download a human typed a command for, this one bounds a request the
+     * user never asked for and must never notice.
+     */
+    checkTimeoutMs: 8_000,
+    /**
+     * Wall-clock budget for the `installing` PHASE and the lock's staleness
+     * refresh - NEVER FOR THE CHILD (U-5 / P1-5).
+     *
+     * It decides when the UI stops saying "updating" and when a lock is treated as
+     * abandoned. It is deliberately NOT `execFile`'s `timeout`, which stays `0`:
+     * wiring it there makes Node `SIGTERM` npm mid-write - the broken global
+     * installation U-3 and D-10 exist to prevent - and it would fire on exactly
+     * the slow links where a five-minute install is the correct outcome.
+     */
+    installTimeoutMs: 300_000,
+    /** The `/latest` document is ~2 KB; this is the C-8 ceiling, not a target. */
+    manifestMaxBytes: 256 * 1024,
+    /** Matches `fetch-source.ts`'s `MAX_REDIRECTS`. */
+    maxRedirects: 3,
+    /**
+     * Longer than `skills`' 60 s, and the difference is the point: the holder here
+     * is an npm install on a cold cache, not a file rename.
+     */
+    lockTtlMs: 600_000,
+    /** First retry after a failed check or install. */
+    backoffBaseMs: 1_800_000,
+    /** Ceiling of the exponential. */
+    backoffMaxMs: 86_400_000,
+    /**
+     * Consecutive failures before the row says anything at all (D-7).
+     *
+     * Below this the failure is silent, because silence is the requirement and an
+     * unactionable recurring warning is the standard way updaters become hated.
+     */
+    failuresBeforeNotice: 3,
+    /** Thundering-herd spread on the check interval (D-12). */
+    jitterRatio: 0.15,
+    /**
+     * Bounded, redacted npm error tail, read from the install LOG FILE (U-5).
+     *
+     * There is a tail to read at all only because the child writes to a real file
+     * descriptor rather than to `'ignore'`; a pipe would have died with the parent
+     * and broken D-10.
+     */
+    stderrTailChars: 500,
+    /**
+     * Below this many columns the update line renders its short form (section 6.2).
+     *
+     * DELIBERATELY NOT `FAST_LIMITS.statusCompactCols`' 100 (`fast/limits.ts`).
+     * That number governs a multi-part status chip competing with the context
+     * gauge for the same row; this one governs a single short clause that owns its
+     * row outright. Two numbers about two different things - do not unify them.
+     */
+    statusCompactCols: 60,
+    /**
+     * Non-zero exits of a version WE installed before it is rolled back
+     * (cli-auto-update-hardening section 7.2 / D-30).
+     *
+     * Tested against the count of PREVIOUS launches, so `2` means "the third
+     * launch rolls back". One crash can be transient - a machine that ran out of
+     * memory once, or whose session file was corrupt, gets a second chance at the
+     * release it just installed. Two is a pattern.
+     *
+     * NOTHING ELSE IN THIS TABLE BOUNDS THE ROLLBACK. There is deliberately no
+     * `bootGuardMaxAgeMs`: the guard is armed only while `autoInstalledVersion`
+     * equals the RUNNING version, so "a machine offline for a year" is a machine
+     * still running the version we installed, and rolling it back to
+     * `lastGoodVersion` is exactly as correct on day 400 as on day 1 (P1-3).
+     */
+    crashesBeforeRollback: 2,
+    /**
+     * Bound on the `npm view` fallback probe (H3).
+     *
+     * SAFE HERE AND FORBIDDEN FOR THE INSTALLER (C-20). A killed `npm view` has
+     * written nothing; a killed `npm install -g` leaves a broken global
+     * installation, which is why `installTimeoutMs` above bounds the PHASE and
+     * never the child.
+     */
+    npmViewTimeoutMs: 10_000,
+};