@aragon-agent/tui 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,89 @@
+/**
+ * Semver comparison and the update decision (cli-auto-update section 3.4).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * HAND-WRITTEN AND NOT `semver`. The package has no such dependency
+ * (`package.json`), and this feature needs three questions answered - "is B
+ * newer than A", "is B a prerelease", "does this Node satisfy that range" - on a
+ * document the registry writes and npm itself only warns about. Adding a
+ * transitive dependency to an auto-updater, of all things, is the one place the
+ * supply-chain argument in R-1 cuts hardest.
+ *
+ * PURE: no I/O, no clock, no process. Every function here is total and none of
+ * them throws.
+ */
+import type { LatestManifest } from './types.js';
+/**
+ * The form a version must have before it is interpolated into `npm install`'s
+ * argv (section 3.5 / AC-24).
+ *
+ * ANCHORED AND WITHOUT `v`: a registry that answered `"1.0.0; rm -rf /"` must
+ * never reach `execFile`. With `shell: false` this is not an injection surface
+ * to begin with, but the rejection is what makes that claim checkable rather
+ * than reasoned, and it also satisfies `fetch-source.ts` rule 3 (no leading `-`)
+ * by construction.
+ */
+export declare const STRICT_VERSION_RE: RegExp;
+export interface Semver {
+    major: number;
+    minor: number;
+    patch: number;
+    /** Dot-separated prerelease identifiers, or `[]` for a release. */
+    prerelease: string[];
+}
+/** Parse a semver string, or `null` when it is not one. Never throws. */
+export declare function parseSemver(raw: unknown): Semver | null;
+export declare function isPrerelease(raw: string): boolean;
+/**
+ * `-1 | 0 | 1`. An UNPARSEABLE version sorts BELOW a parseable one and equal to
+ * another unparseable one, so a garbage registry answer can never read as newer
+ * than what is installed.
+ */
+export declare function compareSemver(a: string, b: string): number;
+/**
+ * Does `nodeVersion` satisfy `engines.node`?
+ *
+ * FAILS OPEN, and that is a decision rather than an oversight (D-15). Handled
+ * forms are `>=X`, `>=X.Y.Z`, `>X`, `<X`, `<=X`, `=X`, `^X`, `~X`, `X.x`, and
+ * `||`-joined unions of those, with space-separated clauses inside a union
+ * ANDed together. Anything this cannot parse returns `true`, matching npm's own
+ * default of warning rather than refusing.
+ *
+ * Failing CLOSED here would mean a syntax we did not anticipate silently freezes
+ * every user's updates forever, with no message and no way to find out - the
+ * worse of the two errors by a wide margin. A range we DID understand and that
+ * genuinely excludes this Node yields `false`, and the caller turns that into a
+ * `node-too-old` notice so the user is told to upgrade Node rather than left
+ * wondering.
+ */
+export declare function satisfiesNodeRange(range: string | undefined, nodeVersion: string): boolean;
+export type UpdateAction = 'install' | 'notify' | 'none';
+export interface UpdateDecision {
+    action: UpdateAction;
+    reason: 'up-to-date' | 'prerelease' | 'deprecated' | 'node-too-old' | 'skipped' | 'newer-available';
+}
+export interface DecideUpdateInput {
+    /** The version this process is running. */
+    local: string;
+    manifest: Pick<LatestManifest, 'version' | 'engines' | 'deprecated'>;
+    /** `process.versions.node`, injected so the decision is testable offline. */
+    nodeVersion: string;
+    /** `state.skippedVersion`; `''` when the user has skipped nothing. */
+    skippedVersion: string;
+}
+/**
+ * Should we install, merely report, or say nothing? (section 3.4)
+ *
+ * ORDER IS SEMANTIC. `up-to-date` is answered first because it is the
+ * overwhelmingly common case and the cheapest; `skipped` comes before the
+ * quality gates so a user who typed `/update skip` is not told about a
+ * prerelease they already declined. Only a range we UNDERSTOOD and that excludes
+ * this Node produces `notify`; every other rejection is silent (`none`).
+ *
+ * The SOURCE and the MODE are deliberately NOT inputs here. This function
+ * answers "is that version worth having"; whether this machine may install it is
+ * the service's question, and folding the two would make a pure decision depend
+ * on the filesystem.
+ */
+export declare function decideUpdate(input: DecideUpdateInput): UpdateDecision;

package/dist/model/update/semver.js

@@ -0,0 +1,295 @@
+/**
+ * Semver comparison and the update decision (cli-auto-update section 3.4).
+ *
+ * ASCII ONLY - this tree is inside the glyph scanner's scope (C-2 / C-3).
+ *
+ * HAND-WRITTEN AND NOT `semver`. The package has no such dependency
+ * (`package.json`), and this feature needs three questions answered - "is B
+ * newer than A", "is B a prerelease", "does this Node satisfy that range" - on a
+ * document the registry writes and npm itself only warns about. Adding a
+ * transitive dependency to an auto-updater, of all things, is the one place the
+ * supply-chain argument in R-1 cuts hardest.
+ *
+ * PURE: no I/O, no clock, no process. Every function here is total and none of
+ * them throws.
+ */
+/**
+ * The form a version must have before it is interpolated into `npm install`'s
+ * argv (section 3.5 / AC-24).
+ *
+ * ANCHORED AND WITHOUT `v`: a registry that answered `"1.0.0; rm -rf /"` must
+ * never reach `execFile`. With `shell: false` this is not an injection surface
+ * to begin with, but the rejection is what makes that claim checkable rather
+ * than reasoned, and it also satisfies `fetch-source.ts` rule 3 (no leading `-`)
+ * by construction.
+ */
+export const STRICT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+/** Parse a semver string, or `null` when it is not one. Never throws. */
+export function parseSemver(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const match = SEMVER_RE.exec(raw.trim());
+    if (!match)
+        return null;
+    const [, major, minor, patch, pre] = match;
+    return {
+        major: Number.parseInt(major, 10),
+        minor: Number.parseInt(minor, 10),
+        patch: Number.parseInt(patch, 10),
+        prerelease: pre ? pre.split('.') : [],
+    };
+}
+export function isPrerelease(raw) {
+    return (parseSemver(raw)?.prerelease.length ?? 0) > 0;
+}
+/**
+ * Compare prerelease identifier lists per semver section 11.
+ *
+ * THE EMPTY LIST SORTS HIGHEST, which is the rule that keeps `1.0.0-rc.1` below
+ * `1.0.0`. Getting this backwards would let a `latest` tag pointing at a release
+ * candidate read as newer than the release it precedes.
+ */
+function comparePrerelease(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1;
+    if (b.length === 0)
+        return -1;
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i += 1) {
+        const x = a[i];
+        const y = b[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xNum = /^\d+$/.test(x);
+        const yNum = /^\d+$/.test(y);
+        if (xNum && yNum) {
+            const diff = Number.parseInt(x, 10) - Number.parseInt(y, 10);
+            if (diff !== 0)
+                return diff < 0 ? -1 : 1;
+            continue;
+        }
+        // Numeric identifiers always sort below alphanumeric ones.
+        if (xNum !== yNum)
+            return xNum ? -1 : 1;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * `-1 | 0 | 1`. An UNPARSEABLE version sorts BELOW a parseable one and equal to
+ * another unparseable one, so a garbage registry answer can never read as newer
+ * than what is installed.
+ */
+export function compareSemver(a, b) {
+    const left = parseSemver(a);
+    const right = parseSemver(b);
+    if (!left && !right)
+        return 0;
+    if (!left)
+        return -1;
+    if (!right)
+        return 1;
+    if (left.major !== right.major)
+        return left.major < right.major ? -1 : 1;
+    if (left.minor !== right.minor)
+        return left.minor < right.minor ? -1 : 1;
+    if (left.patch !== right.patch)
+        return left.patch < right.patch ? -1 : 1;
+    return comparePrerelease(left.prerelease, right.prerelease);
+}
+function parseClause(raw) {
+    const text = raw.trim();
+    if (text.length === 0)
+        return null;
+    const ops = [
+        ['>=', '>='],
+        ['<=', '<='],
+        ['>', '>'],
+        ['<', '<'],
+        ['^', '^'],
+        ['~', '~'],
+        ['=', '='],
+    ];
+    for (const [prefix, op] of ops) {
+        if (text.startsWith(prefix)) {
+            const rest = text.slice(prefix.length).trim();
+            const parsed = parsePartial(rest);
+            return parsed ? { op, ...parsed } : null;
+        }
+    }
+    const parsed = parsePartial(text);
+    return parsed ? { op: '=', ...parsed } : null;
+}
+/**
+ * `18`, `18.x`, `18.19`, `18.19.0` - the partial forms `engines.node` uses in
+ * practice. Missing components read as `0`, which is what makes `>=18` mean
+ * `>=18.0.0`, and `specified` records how many were really named.
+ */
+function parsePartial(raw) {
+    const text = raw.trim().replace(/^v/, '');
+    if (text.length === 0)
+        return null;
+    const parts = text.split('.');
+    if (parts.length > 3)
+        return null;
+    const nums = [];
+    let specified = 0;
+    let sawWildcard = false;
+    for (const part of parts) {
+        if (part === 'x' || part === 'X' || part === '*') {
+            sawWildcard = true;
+            nums.push(0);
+            continue;
+        }
+        if (!/^\d+$/.test(part))
+            return null;
+        nums.push(Number.parseInt(part, 10));
+        // A concrete component AFTER a wildcard (`18.x.3`) names nothing further:
+        // the wildcard has already made everything below it free.
+        if (!sawWildcard)
+            specified += 1;
+    }
+    return {
+        version: {
+            major: nums[0] ?? 0,
+            minor: nums[1] ?? 0,
+            patch: nums[2] ?? 0,
+            prerelease: [],
+        },
+        specified,
+    };
+}
+function compareParsed(a, b) {
+    if (a.major !== b.major)
+        return a.major < b.major ? -1 : 1;
+    if (a.minor !== b.minor)
+        return a.minor < b.minor ? -1 : 1;
+    if (a.patch !== b.patch)
+        return a.patch < b.patch ? -1 : 1;
+    return comparePrerelease(a.prerelease, b.prerelease);
+}
+function satisfiesClause(actual, clause) {
+    const cmp = compareParsed(actual, clause.version);
+    switch (clause.op) {
+        case '>=':
+            return cmp >= 0;
+        case '>':
+            return cmp > 0;
+        case '<=':
+            return cmp <= 0;
+        case '<':
+            return cmp < 0;
+        case '=':
+            // A BARE PARTIAL IS A RANGE, NOT AN EQUALITY. `18` and `18.x` mean "any
+            // 18.y.z"; only a fully-specified `18.19.0` means that exact version.
+            if (clause.specified === 0)
+                return true;
+            if (actual.major !== clause.version.major)
+                return false;
+            if (clause.specified === 1)
+                return true;
+            if (actual.minor !== clause.version.minor)
+                return false;
+            if (clause.specified === 2)
+                return true;
+            return actual.patch === clause.version.patch;
+        case '^':
+            return cmp >= 0 && actual.major === clause.version.major;
+        case '~':
+            return (cmp >= 0 &&
+                actual.major === clause.version.major &&
+                actual.minor === clause.version.minor);
+        default:
+            return true;
+    }
+}
+/**
+ * Does `nodeVersion` satisfy `engines.node`?
+ *
+ * FAILS OPEN, and that is a decision rather than an oversight (D-15). Handled
+ * forms are `>=X`, `>=X.Y.Z`, `>X`, `<X`, `<=X`, `=X`, `^X`, `~X`, `X.x`, and
+ * `||`-joined unions of those, with space-separated clauses inside a union
+ * ANDed together. Anything this cannot parse returns `true`, matching npm's own
+ * default of warning rather than refusing.
+ *
+ * Failing CLOSED here would mean a syntax we did not anticipate silently freezes
+ * every user's updates forever, with no message and no way to find out - the
+ * worse of the two errors by a wide margin. A range we DID understand and that
+ * genuinely excludes this Node yields `false`, and the caller turns that into a
+ * `node-too-old` notice so the user is told to upgrade Node rather than left
+ * wondering.
+ */
+export function satisfiesNodeRange(range, nodeVersion) {
+    if (range === undefined)
+        return true;
+    const text = range.trim();
+    if (text.length === 0 || text === '*')
+        return true;
+    const actual = parseSemver(nodeVersion);
+    if (!actual)
+        return true;
+    for (const union of text.split('||')) {
+        const clauses = union.trim().split(/\s+/).filter((c) => c.length > 0);
+        if (clauses.length === 0)
+            continue;
+        let allParsed = true;
+        let allSatisfied = true;
+        for (const raw of clauses) {
+            const clause = parseClause(raw);
+            if (!clause) {
+                allParsed = false;
+                break;
+            }
+            if (!satisfiesClause(actual, clause))
+                allSatisfied = false;
+        }
+        // An unparseable clause makes the WHOLE range unknown, not just this union:
+        // a partially-understood range is exactly the input that would make a
+        // fail-open guard silently strict.
+        if (!allParsed)
+            return true;
+        if (allSatisfied)
+            return true;
+    }
+    return false;
+}
+/**
+ * Should we install, merely report, or say nothing? (section 3.4)
+ *
+ * ORDER IS SEMANTIC. `up-to-date` is answered first because it is the
+ * overwhelmingly common case and the cheapest; `skipped` comes before the
+ * quality gates so a user who typed `/update skip` is not told about a
+ * prerelease they already declined. Only a range we UNDERSTOOD and that excludes
+ * this Node produces `notify`; every other rejection is silent (`none`).
+ *
+ * The SOURCE and the MODE are deliberately NOT inputs here. This function
+ * answers "is that version worth having"; whether this machine may install it is
+ * the service's question, and folding the two would make a pure decision depend
+ * on the filesystem.
+ */
+export function decideUpdate(input) {
+    const { local, manifest, nodeVersion, skippedVersion } = input;
+    const remote = manifest.version;
+    if (compareSemver(remote, local) <= 0)
+        return { action: 'none', reason: 'up-to-date' };
+    if (skippedVersion.length > 0 && remote === skippedVersion) {
+        return { action: 'none', reason: 'skipped' };
+    }
+    // A stable install is never moved onto a prerelease, even if someone points
+    // `latest` at one. A local prerelease is already opted in, so it may move.
+    if (isPrerelease(remote) && !isPrerelease(local)) {
+        return { action: 'none', reason: 'prerelease' };
+    }
+    if (manifest.deprecated !== undefined)
+        return { action: 'none', reason: 'deprecated' };
+    if (!satisfiesNodeRange(manifest.engines?.node, nodeVersion)) {
+        return { action: 'notify', reason: 'node-too-old' };
+    }
+    return { action: 'install', reason: 'newer-available' };
+}

package/dist/model/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/model/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/dist/testing/governance-fixtures.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Snapshot / card fixtures for the governance TUI tests. The engine is built by another
+ * agent, so every UI test runs against these hand-built shapes.
+ */
+import type { GovernanceCardData, GovernanceSnapshot, PipelineStep, RosterRow } from '../model/governance/types.js';
+export declare const NOW = 1000000;
+export declare function rosterRow(over?: Partial<RosterRow>): RosterRow;
+export declare function pipeline(active?: PipelineStep['key']): PipelineStep[];
+/** The six-member roster of the spec's 10.3 sketch. */
+export declare function sketchRoster(): RosterRow[];
+export declare function snapshot(over?: Partial<GovernanceSnapshot>): GovernanceSnapshot;
+export declare function manyAgents(count: number): RosterRow[];
+export declare function card(over?: Partial<GovernanceCardData>): GovernanceCardData;