@takodotid/circuit 0.37.0 → 0.39.0

package/dist/types/helpers/cables.d.ts

@@ -0,0 +1,66 @@
+/** The far end of a port, for a description of your own: the device and its port by Circuit's name. */
+export type FarEnd = {
+    device: string;
+    port: string;
+};
+/** What every cable of one entry shares. */
+type Shared = {
+    /** What is between the two ends, such as a carrier's local loop. Both ends get it on their `link`. */
+    through?: string;
+    /** A port's description from its far end. When absent, Circuit writes the far device and the far port as printed on it, such as `firewall-1 port6`, from the far device's own file. */
+    describe?: (far: FarEnd) => string;
+};
+/** A port a cable builds: the other end, the LAG it is in, and a description when `describe` gives one. */
+type CablePort<L extends string> = {
+    link: {
+        device: string;
+        port: string;
+        through?: string;
+    };
+    lag?: L;
+    description?: string;
+};
+/** Ports for both ends of the cables between two of our devices, each cable written once. */
+export declare class Cables {
+    /**
+     * One cable, both ends. Spread each end into its device's `ports`:
+     *
+     * ```ts
+     * const uplink = Cables.link({ a: { device: "router-1", port: "25g-1" }, b: { device: "switch-1", port: "10g-48" } });
+     * // router-1: ports: { ...uplink.a }
+     * ```
+     */
+    static link<const NA extends string, const NB extends string>(spec: Shared & {
+        a: {
+            device: string;
+            port: NA;
+        };
+        b: {
+            device: string;
+            port: NB;
+        };
+    }): {
+        a: Record<NA, CablePort<never>>;
+        b: Record<NB, CablePort<never>>;
+    };
+    /**
+     * The cables of a LAG, both ends, from one list read from end A: `{ "25g-1": "10g-2" }` is a cable from A's 25g-1 to B's 10g-2. Each port is a member of its end's LAG. Spread each end into its device's `ports`; the LAG itself stays on each device.
+     */
+    static lag<const LA extends string, const LB extends string, const C extends Readonly<Record<string, string>>>(spec: Shared & {
+        a: {
+            device: string;
+            lag: LA;
+        };
+        b: {
+            device: string;
+            lag: LB;
+        };
+        cables: C;
+    }): {
+        a: Record<keyof C & string, CablePort<LA>>;
+        b: Record<C[keyof C], CablePort<LB>>;
+    };
+    /** A port facing `port` on the far device. */
+    private static end;
+}
+export {};

package/dist/types/helpers/index.d.ts

@@ -1,10 +1,14 @@
 export { Bgp } from "./bgp.js";
-export type { CommunityScheme, SanityLengths } from "./bgp.js";
+export type { Announced, CommunityScheme, DefaultOnlyOptions, LearnOptions, SanityLengths } from "./bgp.js";
+export { Cables } from "./cables.js";
+export type { FarEnd } from "./cables.js";
 export { Checks } from "./checks.js";
 export type { TrustBoundary } from "./checks.js";
 export { Exchange } from "./exchange.js";
 export type { ExchangeMember, InternetExchange } from "./exchange.js";
 export { Filters } from "./filters.js";
 export { RouteServerConfig } from "./route-server.js";
+export { Upstreams } from "./upstreams.js";
+export type { Upstream, UpstreamCatalog, UpstreamPolicies } from "./upstreams.js";
 export type { RouteServer } from "./route-server.js";
 export type { AntiAmplificationOptions } from "./filters.js";

package/dist/types/helpers/upstreams.d.ts

@@ -0,0 +1,239 @@
+import type { Exchange as ExchangeLan, Family, FilterRule, Gre, InterfaceAddress, IP, LargeCommunity, Neighbor, NeighborSettings, PolicyRule, Port, Secret, StandardCommunity, Vlan, VlanInterface } from "../schema/index.js";
+import { type Announced } from "./bgp.js";
+/** One network we exchange routes with: a transit we buy, an exchange's route servers, or a peer. */
+export type Upstream = {
+    /** Its name as people write it, for descriptions: `Transit A`. The key when absent. */
+    name?: string;
+    asn: number;
+    /** What it is to us: `provider` for a transit, `rs` for an exchange's route servers, `peer` for a direct session. */
+    role: "provider" | "rs" | "peer";
+    /** Where it lands on our side: a VLAN, our addresses on it, and the switch port it arrives on. A peer over a tunnel, or over an exchange's VLAN, has none. */
+    handoff?: {
+        /** The VLAN's ID. */
+        vlan: number;
+        /** It sends its VLAN tagged: its port gets a native VLAN of its own with this ID, which nothing else is in. Untagged when absent. */
+        native?: number;
+        /** Its number in names with `{number}`, such as `core-ipt01-transita`. Written here, so removing another upstream renumbers nothing. */
+        number?: number;
+        /** Our addresses on it. `{ address, peer }` for a point-to-point address whose far end is outside its own prefix. */
+        addresses: readonly (InterfaceAddress | {
+            address: InterfaceAddress;
+            peer: IP;
+        })[];
+        /** The switch port it arrives on. */
+        port?: {
+            device: string;
+            port: string;
+            storm_control?: Port<string, string, string, string>["storm_control"];
+        };
+        /** An exchange's LAN, for `circuit peeringdb`. */
+        exchange?: ExchangeLan;
+    };
+    /** A GRE tunnel to it. `number` is its number in names with `{number}`. */
+    tunnel?: {
+        local: IP;
+        remote: IP;
+        addresses: readonly InterfaceAddress[];
+        mtu?: number;
+        number?: number;
+    };
+    /** Our BGP sessions with it, by name: its address, and ours when it is not the interface's. */
+    sessions: Readonly<Record<string, {
+        address: IP;
+        local_address?: IP;
+    }>>;
+    /** The sessions are more than one hop away, from this address of ours. They share a group. */
+    multihop?: {
+        local_address: IP;
+        families?: readonly Family[];
+        password?: Secret;
+    };
+    /** The most prefixes a session may send, by its family: about twice what it sends. Over it, the session closes until it is cleared. */
+    limits?: {
+        ipv4?: number;
+        ipv6?: number;
+    };
+    /** What we take. Nothing when absent. */
+    import?: {
+        /** Its default route, at this preference. */
+        default?: {
+            local_pref?: number;
+            description?: string;
+        };
+        /** Its routes, through `Bgp.learn`: the `before` rules, sanity, this preference, the tag. Only the default when absent. */
+        learn?: {
+            local_pref?: number;
+            before?: readonly PolicyRule<never, never>[];
+        };
+    };
+    /** Rules of yours in its export, between the community actions and what we announce, such as a prepend. */
+    export?: readonly PolicyRule<never, never>[];
+    /** What we announce to it. Everything else is rejected. */
+    announce: readonly Announced[];
+    /** Drop RFC 1918 sources arriving from it. `privateDrops()` lists the VLANs. */
+    drop_private?: true;
+};
+/** Upstreams by key. The key names everything built from it. */
+export type UpstreamCatalog = Readonly<Record<string, Upstream>>;
+/** A name made from an upstream: `{key}` is its key, `{KEY}` the key in capitals, `{number}` its `handoff.number` or `tunnel.number`. */
+type Pattern = string;
+/** A pattern for every upstream, or one per role. A role left out takes the default. */
+type ByRole = Pattern | {
+    readonly provider?: Pattern;
+    readonly rs?: Pattern;
+    readonly peer?: Pattern;
+};
+/** How the names built from each upstream are made. Each one left out takes its default. */
+export type UpstreamNames = {
+    /** The VLAN a handoff is on. `{key}` when absent. */
+    vlan?: ByRole;
+    /** The native VLAN of a handoff sent tagged. `{key}-native` when absent. */
+    native?: Pattern;
+    /** The router's interface: per role, and `tunnel` for one reached over a tunnel. `{key}` when absent. */
+    interface?: Pattern | {
+        readonly provider?: Pattern;
+        readonly rs?: Pattern;
+        readonly peer?: Pattern;
+        readonly tunnel?: Pattern;
+    };
+    /** The import policy. `{KEY}-IN` when absent. */
+    import?: Pattern;
+    /** The export policy. `{KEY}-OUT` when absent. */
+    export?: Pattern;
+    /** The BGP group of an exchange's route servers or of multihop sessions. `{key}` when absent. */
+    group?: Pattern;
+    /** The description of a handoff's switch port. Its `name` when absent. No device names it, so it may be any function. */
+    port?: (key: string, upstream: Upstream) => string;
+};
+/** How each upstream's policies are written: shared by every upstream of a catalog. */
+export type UpstreamPolicies<P extends string> = {
+    /** A policy holding `Bgp.sanity()` that each import calls. The sanity rules are written in each import when absent. */
+    sanity?: P;
+    /** Where a route came from, by upstream: a community or a rule, such as `communityScheme(...).tag(...)`. Nothing is tagged when absent. */
+    tag?: (key: string, upstream: Upstream) => StandardCommunity | LargeCommunity | PolicyRule<never, never>;
+    /** Rules first in each export, such as `communityScheme(...).actions(upstream.asn)`. */
+    actions?: (key: string, upstream: Upstream) => readonly PolicyRule<never, never>[];
+    /** The source address for routes of its family, one per family. */
+    sources?: readonly IP[];
+};
+/** The names a device can refer to, and their patterns when the project gives none. */
+declare const DEFAULTS: {
+    readonly vlan: "{key}";
+    readonly native: "{key}-native";
+    readonly interface: "{key}";
+    readonly import: "{KEY}-IN";
+    readonly export: "{KEY}-OUT";
+    readonly group: "{key}";
+};
+type Defaults = typeof DEFAULTS;
+type Field = keyof Defaults;
+type Key<C> = keyof C & string;
+/** The upstreams that land on a VLAN of ours. */
+type Landed<C> = {
+    [K in Key<C>]: C[K] extends {
+        handoff: object;
+    } ? K : never;
+}[Key<C>];
+/** The upstreams that send their VLAN tagged. */
+type Tagged<C> = {
+    [K in Key<C>]: C[K] extends {
+        handoff: {
+            native: number;
+        };
+    } ? K : never;
+}[Key<C>];
+/** The upstreams reached over a tunnel. */
+type Tunneled<C> = {
+    [K in Key<C>]: C[K] extends {
+        tunnel: object;
+    } ? K : never;
+}[Key<C>];
+/** The upstreams whose sessions share a group: an exchange's route servers, or multihop sessions. */
+type Grouped<C> = {
+    [K in Key<C>]: C[K] extends {
+        role: "rs";
+    } | {
+        multihop: object;
+    } ? K : never;
+}[Key<C>];
+/** The upstreams we take routes from. */
+type Importing<C> = {
+    [K in Key<C>]: C[K] extends {
+        import: object;
+    } ? K : never;
+}[Key<C>];
+/** The project's pattern for a name, or the default. */
+type PatternOf<N, F extends Field> = N extends {
+    [X in F]: infer P;
+} ? P : Defaults[F];
+/** The pattern an upstream takes: the only one, its tunnel's, its role's, or the default. */
+type Chosen<P, U, F extends Field> = P extends string ? P : U extends {
+    tunnel: object;
+} ? P extends {
+    tunnel: infer T extends string;
+} ? T : Defaults[F] : U extends {
+    role: infer R extends string;
+} ? P extends {
+    [X in R]: infer T extends string;
+} ? T : Defaults[F] : Defaults[F];
+/** Every `From` in `S` replaced. */
+type Replace<S extends string, From extends string, To extends string> = S extends `${infer A}${From}${infer B}` ? `${A}${To}${Replace<B, From, To>}` : S;
+/** An upstream's `handoff.number` or `tunnel.number`. */
+type NumberOf<U> = U extends {
+    handoff: {
+        number: infer N extends number;
+    };
+} ? N : U extends {
+    tunnel: {
+        number: infer N extends number;
+    };
+} ? N : number;
+/** The name built for upstream `K`: its pattern with the key, the key in capitals and its number filled in. */
+type Named<C, N, F extends Field, K extends Key<C>> = Replace<Replace<Replace<Chosen<PatternOf<N, F>, C[K], F>, "{key}", K>, "{KEY}", Uppercase<K>>, "{number}", `${NumberOf<C[K]>}`>;
+/** Each of these upstreams' names. */
+type Names<C, N, F extends Field, Ks extends Key<C>> = {
+    [K in Ks]: Named<C, N, F, K>;
+}[Ks];
+/** The catalog as written, with any key the shape does not have refused, at every level. */
+type Exact<S, T> = T extends readonly unknown[] | string | number | boolean | Secret | ((...args: never[]) => unknown) ? T : {
+    [K in keyof T]: K extends keyof S ? Exact<NonNullable<S[K]>, T[K]> : never;
+};
+/** The names as written, with a name or a role Upstreams does not make refused. */
+type ExactNames<N> = {
+    [F in keyof N]: F extends keyof UpstreamNames ? N[F] extends string | ((...args: never[]) => unknown) ? N[F] : {
+        [R in keyof N[F]]: R extends "provider" | "rs" | "peer" | "tunnel" ? N[F][R] : never;
+    } : never;
+};
+/** A network's upstreams written once, and each device's part built from them. */
+export declare class Upstreams {
+    /**
+     * Each upstream written once: its AS, where it lands, its sessions, limits and policy. Everything a device needs is built from it, under names made from each key, so a device that names one is checked. By default:
+     *
+     * - VLAN `<key>`, and `<key>-native` for one that sends its VLAN tagged. The router's interface is `<key>` too, a VLAN interface or a GRE tunnel.
+     * - Policies `<KEY>-IN` and `<KEY>-OUT`; a BGP group `<key>` for an exchange's route servers or multihop sessions.
+     *
+     * `names` gives patterns of your own, such as `{ interface: { provider: "core-ipt0{number}-{key}" } }`; see `UpstreamNames`.
+     *
+     * On the router: `vlans()`, `interfaces()`, `uplinks()`, `groups()`, `neighbors()`, `policies({ ... })`, `tunnelRules()`, `addresses()`. On a switch: `vlans(device)`, `ports(device)`, `vlansOn(device)`. For checks and ACLs: `untrusted()`, `natives()`, `privateDrops()`. Lists follow the catalog's order, where order counts on a device.
+     */
+    static define<const C extends UpstreamCatalog, const N extends UpstreamNames = {}>(catalog: C & {
+        [K in keyof C]: Exact<Upstream, C[K]>;
+    }, options?: {
+        names?: N & ExactNames<N>;
+    }): {
+        vlans: <const D extends string | undefined = undefined>(device?: D) => D extends string ? { [K in Names<C, N, "vlan", Landed<C>>]: Vlan; } & { [K in Names<C, N, "native", Tagged<C>>]: Vlan; } : { [K in Names<C, N, "vlan", Landed<C>>]: Vlan; };
+        vlansOn: (device: string) => Names<C, N, "vlan", Landed<C>>[];
+        ports: (device: string) => Record<string, Port<Names<C, N, "native", Tagged<C>> | Names<C, N, "vlan", Landed<C>>, never, never, never>>;
+        interfaces: () => { [K in Names<C, N, "interface", Landed<C>>]: VlanInterface<Names<C, N, "vlan", Landed<C>>, never>; } & { [K in Names<C, N, "interface", Tunneled<C>>]: Gre<never>; };
+        uplinks: () => Names<C, N, "interface", Landed<C>>[];
+        groups: () => Record<Names<C, N, "group", Grouped<C>>, NeighborSettings<Names<C, N, "export", Key<C>> | Names<C, N, "import", Importing<C>>>>;
+        neighbors: () => Record<string, Neighbor<Names<C, N, "export", Key<C>> | Names<C, N, "import", Importing<C>>, Names<C, N, "group", Grouped<C>>>>;
+        policies: <const P extends string = never>(options?: UpstreamPolicies<P>) => Record<Names<C, N, "export", Key<C>> | Names<C, N, "import", Importing<C>>, PolicyRule<P, never>[]>;
+        untrusted: () => (Names<C, N, "native", Tagged<C>> | Names<C, N, "vlan", Landed<C>>)[];
+        natives: () => Names<C, N, "native", Tagged<C>>[];
+        privateDrops: () => Names<C, N, "vlan", Landed<C>>[];
+        tunnelRules: () => FilterRule<never, never>[];
+        addresses: () => IP[];
+    };
+}
+export {};

package/dist/types/platforms/bgp-wait.d.ts

@@ -15,4 +15,10 @@ export declare class BgpWait {
     static until(read: () => Promise<BgpSession[]>, enough: (sessions: BgpSession[]) => boolean, limits: WaitLimits, waiting?: (sessions: BgpSession[]) => void): Promise<BgpSession[]>;
     /** How many of these sessions are established. */
     static upCount(sessions: readonly BgpSession[]): number;
+    /** Sessions closed on their limit within this many minutes of each other are one burst. */
+    static readonly BURST_MINUTES = 5;
+    /**
+     * Groups of two or more sessions closed on their limit within `BURST_MINUTES` of each other, earliest first. Several limits at once is usually a leak upstream, not growth, so raising them is the wrong fix.
+     */
+    static limitBursts(sessions: readonly BgpSession[]): BgpSession[][];
 }

package/dist/types/platforms/platform.d.ts

@@ -57,6 +57,16 @@ export type BgpSession = {
     prefixes: string;
     /** How long it has been up, as the device prints it, or `no session`. */
     uptime: string;
+    /** Why it is down, when the device says: `limit exceeded`, `admin down`, `connecting`. */
+    reason?: string;
+    /** It closed because the neighbor sent more prefixes than its limit, and stays closed until cleared. */
+    limit?: BgpLimit;
+};
+/** A session closed on its prefix limit: the limit, and when it closed, as the device prints it and in milliseconds, to compare. */
+export type BgpLimit = {
+    max?: number;
+    stopped?: string;
+    stoppedAt?: number;
 };
 /** One BGP log line: when, as the device printed it, such as `2026-10-24 03:12:44`, and the rest of the line. */
 export type BgpLogLine = {
@@ -113,6 +123,8 @@ export declare abstract class Platform {
     bgpSessions?(device: Device, session: ReadSession): Promise<BgpSession[]>;
     /** The device's BGP log lines from the last `minutes`, by the device's own clock, read over a `session()`. */
     bgpLog?(session: ReadSession, minutes: number): Promise<BgpLogLine[]>;
+    /** Open again these sessions, each closed on its prefix limit, read by `bgpSessions`. Only a session still closed on its limit is touched. */
+    bgpClearLimit?(session: ReadSession, sessions: readonly BgpSession[]): Promise<void>;
     /**
      * Checks that the device is healthy after an apply, not only that it took the commands. Called before the plan is sent, to read what the checks compare against; the CLI runs them after the apply and the snapshot. Absent on a platform with no checks yet.
      */

package/dist/types/platforms/routeros/index.d.ts

@@ -13,8 +13,12 @@ export declare class RouterOs extends Platform {
     private static readonly EXPORT_TIMESTAMP;
     /** Lists certificates in the form the renderer writes them, since an export does not include them. One line, because a script sent over exec runs as one. */
     private static readonly LIST_CERTIFICATES;
-    /** Every BGP session, one line each: name, remote address, established, prefixes received, uptime. One line, because a script sent over exec runs as one. */
+    /**
+     * Every BGP session, one line each: name, remote address, established, prefixes received, uptime, closed on its limit, the limit, when it last closed. Then each disabled connection, `disabled|<name>|<address>`. One line, because a script sent over exec runs as one.
+     */
     private static readonly LIST_BGP_SESSIONS;
+    /** Open again the session from one address, only while it is closed on its limit. */
+    private static clearLimit;
     /**
      * Every LLDP neighbor, one line each: our interfaces, the port first and then the LAG and bridge it is in, the far system name, and the far port as LLDP reports it. `:tostr` keeps the interface list one value; joined to a string as it is, a list repeats the whole line for each of its items. One line, because a script sent over exec runs as one.
      */
@@ -51,8 +55,11 @@ export declare class RouterOs extends Platform {
     session(device: Device, options?: ReadOptions): Promise<ReadSession>;
     /**
      * A session is named `<connection>-<n>`, but a renamed connection keeps its session's old name until the session restarts. So a neighbor is matched by its address first, then by name.
+     *
+     * A session that is down says why: closed on its limit, or still connecting. A neighbor with no session and a disabled connection is admin down.
      */
     bgpSessions(device: Device, session: ReadSession): Promise<BgpSession[]>;
+    bgpClearLimit(session: ReadSession, sessions: readonly BgpSession[]): Promise<void>;
     /** A `time>` filter in `/log print` does not filter, so the lines are kept here by comparing each one's time with the device's clock. */
     bgpLog(session: ReadSession, minutes: number): Promise<BgpLogLine[]>;
     /**

package/dist/types/schema/interfaces.d.ts

@@ -109,7 +109,7 @@ export type Port<V extends string, A extends string, L extends string, F extends
     acl?: A;
     /** The LAG this port is in. Every other setting goes on the LAG. */
     lag?: L;
-    /** Another of our devices at the other end of the cable. */
+    /** Another of our devices at the other end of the cable. Without a `description`, the port is described from it: the far device and the far port as printed on it, such as `firewall-1 port6`. */
     link?: Link;
 };
 /** Settings every interface that is not a physical port shares. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.37.0",
+    "version": "0.39.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/cli/index.ts

@@ -103,12 +103,20 @@ class Cli {
         return new Cli(configPath, network, options);
     }
 
-    /** The config, a TypeScript file. Bun imports it as it is; Node needs jiti, which also resolves imports written without an extension. */
+    /**
+     * The config, a TypeScript file. Bun imports it as it is; Node needs jiti, which also resolves imports written without an extension. A linked port without a description is given one from its far end.
+     */
     private static async load(path: string): Promise<Network> {
-        if (process.versions.bun) return (await import(path)).default;
+        let network: Network;
+
+        if (process.versions.bun) {
+            network = (await import(path)).default;
+        } else {
+            const { createJiti } = await import("jiti");
+            network = await createJiti(import.meta.url).import<Network>(path, { default: true });
+        }
 
-        const { createJiti } = await import("jiti");
-        return createJiti(import.meta.url).import(path, { default: true });
+        return { ...network, devices: Cabling.describeLinks(network.devices) };
     }
 
     private static fail(message: string): never {
@@ -228,7 +236,7 @@ class Cli {
 
         program
             .command("bgp")
-            .description("each BGP neighbor in the config next to its live session: up or down, prefixes, uptime")
+            .description("each BGP neighbor in the config next to its live session: up or down and why, prefixes, uptime")
             .argument("[device]", "may be left out when only one device has BGP neighbors")
             .argument("[name-regex]", "only the neighbors whose name matches")
             .option(
@@ -238,6 +246,7 @@ class Cli {
             )
             .option("--max <seconds>", "how long --wait waits at most", Cli.seconds, BgpWait.COMMAND.seconds)
             .option("--log [minutes]", "also print the device's BGP log lines from the last minutes, 5 by default", Cli.minutes)
+            .option("--clear-limit", "open again the neighbors shown that closed on their prefix limit; any other is left alone")
             .option(Cli.CONFIG_FLAGS, Cli.CONFIG_HELP)
             .action(async (first, second, flags) => (await Cli.open(flags.config)).bgp(first, second, flags));
 
@@ -604,12 +613,12 @@ class Cli {
     }
 
     /**
-     * Each BGP neighbor in the config next to its live session. `first` is the device, or, when it names none and only one device has BGP neighbors, the name pattern. With `wait`, reads again until every neighbor shown, or that many, is up, and fails when time runs out.
+     * Each BGP neighbor in the config next to its live session. `first` is the device, or, when it names none and only one device has BGP neighbors, the name pattern. With `wait`, reads again until every neighbor shown, or that many, is up, and fails when time runs out. With `clearLimit`, opens again the neighbors shown that closed on their prefix limit, and fails when none did.
      */
     private async bgp(
         first: string | undefined,
         second: string | undefined,
-        flags: { wait?: true | number; max: number; log?: true | number }
+        flags: { wait?: true | number; max: number; log?: true | number; clearLimit?: true }
     ): Promise<void> {
         const { device, pattern } = this.bgpTarget(first, second);
         const adapter = this.adapterOf(device);
@@ -620,6 +629,8 @@ class Cli {
             .join(", ");
         if (!adapter.bgpSessions) Cli.fail(`circuit bgp does not support ${device.platform} yet, only ${supported}`);
         if (flags.log && !adapter.bgpLog) Cli.fail(`circuit bgp --log does not support ${device.platform} yet`);
+        if (flags.clearLimit && !adapter.bgpClearLimit) Cli.fail(`circuit bgp --clear-limit does not support ${device.platform} yet`);
+        if (flags.clearLimit && flags.wait !== undefined) Cli.fail("--clear-limit and --wait go in two runs: clear first, then wait");
 
         let matcher: RegExp;
         try {
@@ -640,6 +651,11 @@ class Cli {
         try {
             const read = async () => (await adapter.bgpSessions!(device, session)).filter((neighbor) => shown.includes(neighbor.neighbor));
 
+            if (flags.clearLimit) {
+                await Cli.clearLimits(adapter, session, read);
+                return;
+            }
+
             const limits = { seconds: flags.max, every: BgpWait.COMMAND.every };
             const sessions = await BgpWait.until(
                 read,
@@ -660,6 +676,27 @@ class Cli {
         }
     }
 
+    /** Open again the sessions closed on their limit, say which others were left alone, and show them all after. */
+    private static async clearLimits(adapter: Platform, session: ReadSession, read: () => Promise<BgpSession[]>): Promise<void> {
+        const sessions = await read();
+        const closed = sessions.filter((bgp) => bgp.limit);
+
+        if (!closed.length) {
+            Cli.printBgp(sessions);
+            console.error("\nno neighbor shown is closed on its prefix limit, so nothing was cleared");
+            process.exitCode = 1;
+            return;
+        }
+
+        for (const bgp of sessions) if (!bgp.limit) console.log(`${bgp.neighbor}: left alone, not closed on its limit`);
+        await adapter.bgpClearLimit!(session, closed);
+        console.log(
+            `cleared ${closed.map((bgp) => bgp.neighbor).join(", ")}: each connects again, and closes again if it still sends too much\n`
+        );
+
+        Cli.printBgp(await read());
+    }
+
     /** The device `circuit bgp` reads, and the name pattern, from its two optional arguments. */
     private bgpTarget(first: string | undefined, second: string | undefined): { device: Device; pattern: string | undefined } {
         if (second !== undefined || (first && this.network.devices.some((device) => device.name === first))) {
@@ -681,12 +718,34 @@ class Cli {
 
         for (const session of sessions) {
             const state = session.established ? "up  " : "DOWN";
+            const why = session.reason ? `  ${Cli.downReason(session)}` : "";
             console.log(
-                `${session.neighbor.padEnd(width)}  ${state}  ${session.prefixes.padStart(7)}  ${session.uptime.padEnd(12)}  ${session.remote}`
+                `${session.neighbor.padEnd(width)}  ${state}  ${session.prefixes.padStart(7)}  ${session.uptime.padEnd(12)}  ${session.remote}${why}`
             );
         }
 
         console.log(`${BgpWait.upCount(sessions)}/${sessions.length} up`);
+
+        for (const burst of BgpWait.limitBursts(sessions)) {
+            const names = burst.map((session) => session.neighbor);
+            const listed = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
+            const seconds = Math.round((burst.at(-1)!.limit!.stoppedAt! - burst[0]!.limit!.stoppedAt!) / 1000);
+
+            console.log(
+                `
+${listed} closed on their prefix limit within ${seconds} s of each other, from ${burst[0]!.limit!.stopped}. Several limits at once is usually a leak upstream, not growth: find the leak before raising a limit, then clear them with --clear-limit.`
+            );
+        }
+    }
+
+    /** Why a session is down, with its limit and when it closed when that is why. */
+    private static downReason(session: BgpSession): string {
+        const { limit } = session;
+        if (!limit) return session.reason ?? "";
+
+        const over = limit.max !== undefined ? `: over ${limit.max} prefixes` : "";
+        const when = limit.stopped ? `, closed ${limit.stopped}` : "";
+        return `${session.reason}${over}${when}`;
     }
 
     /** The device's BGP log lines from the last `minutes`, a message repeated folded into one line, secrets hidden. */

package/src/core/cabling.ts

@@ -121,6 +121,36 @@ export class Cabling {
         return findings;
     }
 
+    /**
+     * Each linked port without a description gets one from its far end: the far device and the far port as printed on it, such as `firewall-1 port6`. The far device's own file has its platform and model, so the label is never written twice. A port whose far device is not in the network keeps none.
+     */
+    static describeLinks(devices: readonly Device[]): Device[] {
+        const byName = new Map(devices.map((device) => [device.name, device]));
+
+        return devices.map((device) => {
+            const ports = Object.entries(device.ports ?? {});
+            if (!ports.some(([, port]) => port?.link && port.description === undefined)) return device;
+
+            const described = ports.map(([name, port]) => {
+                const far = port?.link ? byName.get(port.link.device) : undefined;
+                if (!port?.link || port.description !== undefined || !far) return [name, port];
+
+                return [name, { ...port, description: `${far.name} ${Cabling.labelOf(far, port.link.port)}` }];
+            });
+
+            return { ...device, ports: Object.fromEntries(described) } as Device;
+        });
+    }
+
+    /** A port as printed on the device, or Circuit's name for it when the model has no spelling for it. */
+    private static labelOf(device: Device, port: string): string {
+        try {
+            return Catalog.spell(device.platform, device.model, port);
+        } catch {
+            return port;
+        }
+    }
+
     /** A system name is the device's name, alone or with a domain after it. */
     private static isDevice(system: string, name: string): boolean {
         return system === name || system.startsWith(`${name}.`);