@cruxy/cli 1.4.0 → 1.6.0

package/dist/tui/limits-panel.js

@@ -0,0 +1,247 @@
+import { compactTokens } from "../render/units.js";
+import { bindingWindow, usedFraction } from "../limits/index.js";
+/**
+ * The limits panel (P9): what this credential may spend, and how much is left.
+ *
+ * THE PANEL IS DRIVEN BY THE BUCKET, NEVER BY THE LOGIN. Which numbers exist —
+ * and whether a fraction exists at all — is decided by the billing bucket the
+ * gateway reports, because that is the only thing that actually decides it. The
+ * inference this replaces (a CLI login is an apikey, so it is metered and
+ * ungated) was true when it was written and silently stopped being true when the
+ * gateway changed what a login mints (cruxy-ai/api#174), with nothing locally
+ * observable changing. So there are four bodies here, one per shape, and the
+ * type system hands each of them only the numbers that shape may state.
+ *
+ * AND THIS ONE GETS A BAR. The context panel refuses one under a locking test,
+ * for reasons that are exactly right there: its numerator is a chars/4 estimate
+ * and its denominator a local config default, so a filled bar would render a
+ * guess as a measurement. Every number here is the opposite — server-authored,
+ * in the meter's own unit, peeked from the same buckets the gate enforces on, so
+ * the fraction the bar fills IS the fraction the next request is judged against.
+ * A bar is the right claim for a real measurement, and only for one.
+ *
+ * The corollary is the rule the rest of this file exists to keep: NO CAP, NO
+ * FRACTION. An enterprise pool reports `{enforced: false}` and a developer key
+ * reports `metered: true`; neither has an allowance, so neither gets a bar, a
+ * percentage, or an X-of-Y — not even a reassuring full one. Spend caps are not
+ * a substitute, because they appear only when someone set one.
+ */
+/** Cells in the bar. Sized so `bar + " " + "100%"` clears {@link RAIL_COLS}. */
+const BAR_CELLS = 12;
+/**
+ * A proportion bar. Empty under the screen-reader glyph table (both cells are
+ * ""), which is deliberate — a run of blocks announces as nothing, and the
+ * percentage that follows it carries the entire meaning.
+ */
+export function bar(theme, fraction, cells = BAR_CELLS) {
+    const filled = Math.round(Math.min(1, Math.max(0, fraction)) * cells);
+    return (theme.glyph.barFilled.repeat(filled) +
+        theme.glyph.barEmpty.repeat(cells - filled));
+}
+/**
+ * The styler for a window's state. `low` and `blocked` are the two the user can
+ * act on, and they are different acts — one is "wrap up", the other is "you are
+ * already being refused" — so they are not merged into one warning.
+ */
+function stateStyle(theme, state) {
+    if (state === "blocked")
+        return theme.danger;
+    if (state === "low")
+        return theme.warning;
+    return theme.strong;
+}
+/**
+ * Re-exported, not defined here any more (P10 track 3): `/budget` states the
+ * same windows in the same unit, so the two share one formatter.
+ */
+export { compactTokens };
+/** 27.77 → "$27.77", 29 → "$29", 0.5 → "$0.50". */
+export function usd(n) {
+    return Number.isInteger(n) ? `$${n}` : `$${n.toFixed(2)}`;
+}
+/**
+ * How long until an ISO instant, compactly: "18d", "4h", "12m", "now".
+ * `undefined` for an absent or unparseable one — a reset we cannot state is
+ * simply not stated, never guessed at.
+ */
+export function untilLabel(iso, now) {
+    if (!iso)
+        return undefined;
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return undefined;
+    const ms = at - now;
+    if (ms <= 0)
+        return "now";
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 60)
+        return `${Math.max(1, minutes)}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+/** A percentage for display: 0.618 → "62%". */
+function pct(fraction) {
+    return `${Math.round(fraction * 100)}%`;
+}
+/**
+ * Beyond this, the reading is called out as old rather than presented as
+ * current. The pool is shared with every other surface on the account, so an
+ * idle CLI's figures can go stale without this process doing anything at all —
+ * which is precisely the case a timestamp has to cover.
+ */
+const STALE_AFTER_MS = 5 * 60_000;
+/**
+ * The subscription pool: a bar on the BINDING window, the same one the gate
+ * decides against.
+ *
+ * Drawing the month instead — the bigger, friendlier number — would routinely
+ * show a comfortable 6% while the trailing-12h burst, a quarter of the month's
+ * cap on every self-serve tier, is the window actually about to refuse the next
+ * request. The bar is the thing that stops you, and the line under it names
+ * which window that is so the figure is never ambiguous.
+ */
+function poolLines(theme, pool, now) {
+    const binding = bindingWindow(pool.monthly, pool.burst);
+    // Unreachable via `reduceLimits` (a pool with no readable window reduces to
+    // `unknown`), but the type permits it and inventing a bar is the one thing
+    // this panel must never do on the way to being defensive.
+    if (!binding)
+        return [theme.muted("figures not reported")];
+    const { window: w, name } = binding;
+    const fraction = usedFraction(w) ?? 0;
+    const style = stateStyle(theme, w.state ?? pool.state);
+    const lines = [
+        `${style(bar(theme, fraction))} ${style(pct(fraction))}`,
+        `${compactTokens(w.used)} / ${compactTokens(w.cap)} ${name}`,
+    ];
+    // The window that is NOT binding, so both dimensions are visible — a user
+    // whose burst is tight still needs to know the month is nearly gone too.
+    const other = name === "burst" ? pool.monthly : pool.burst;
+    const otherName = name === "burst" ? "month" : "burst";
+    const until = untilLabel(w.resetsAt, now);
+    if (other) {
+        const otherPct = pct(usedFraction(other) ?? 0);
+        lines.push(theme.muted(until
+            ? `${otherName} ${otherPct} ${theme.sep}${until}`
+            : `${otherName} ${otherPct}`));
+    }
+    else if (until) {
+        lines.push(theme.muted(`resets ${until}`));
+    }
+    // Only when it is actionable. A blocked model list is the answer to "why did
+    // that request fail"; mira's remaining requests are the answer to "what can I
+    // still run" — and neither question is being asked while the pool is healthy.
+    if (pool.blockedModels.length > 0) {
+        lines.push(theme.danger(`no ${pool.blockedModels.join(" ")}`));
+    }
+    else if (pool.state === "low" && pool.mira) {
+        lines.push(theme.muted(`mira ${compactTokens(pool.mira.remaining)} left`));
+    }
+    return lines;
+}
+/** A spend cap line. Text, never a bar: the bar belongs to the allowance. */
+function spendCapLine(theme, label, cap) {
+    return theme.muted(`${label} ${usd(cap.remaining)} of ${usd(cap.cap)}`);
+}
+/** How long ago, compactly: the mirror of {@link untilLabel}. */
+function agoLabel(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 60)
+        return `${Math.max(1, minutes)}m`;
+    const hours = Math.floor(minutes / 60);
+    return hours < 24 ? `${hours}h` : `${Math.floor(hours / 24)}d`;
+}
+/** The body for a ready reading, chosen by the budget shape. */
+function readingLines(theme, reading, now) {
+    const lines = [];
+    const budget = reading.budget;
+    switch (budget.kind) {
+        case "pool":
+            lines.push(...poolLines(theme, budget, now));
+            break;
+        // Enterprise. NO fraction, and no consolation bar drawn at 0% either: a full
+        // green bar and "no limit" are read the same way at a glance, and only one
+        // of them is true.
+        case "unenforced":
+            lines.push(theme.strong(reading.tier));
+            lines.push(theme.muted("pool not enforced"));
+            break;
+        // A developer key: billed per token, gated by nothing it draws down. Saying
+        // "no pool" explicitly matters here — an empty budget section would read as
+        // a figure that failed to load rather than as a figure that does not exist.
+        case "metered":
+            lines.push(`${theme.strong(reading.tier)}${theme.muted(" metered")}`);
+            lines.push(theme.muted("no pool cap"));
+            break;
+        case "credits": {
+            const fraction = budget.granted > 0
+                ? Math.min(1, Math.max(0, budget.used / budget.granted))
+                : undefined;
+            if (fraction !== undefined) {
+                const style = fraction >= 0.9 ? theme.warning : theme.strong;
+                lines.push(`${style(bar(theme, fraction))} ${style(pct(fraction))}`);
+            }
+            lines.push(`${usd(budget.remaining)} of ${usd(budget.granted)}`);
+            const until = untilLabel(budget.resetsAt, now);
+            if (until)
+                lines.push(theme.muted(`resets ${until}`));
+            break;
+        }
+        // The bucket, or the pool inside it, is one this build cannot read. Both
+        // facts it DOES have are real and server-resolved, so both are shown; what
+        // it does not have, it declines to imply.
+        case "unknown":
+            lines.push(`${theme.strong(reading.tier)}${theme.muted(` ${theme.glyph.sep} ${reading.bucket}`)}`);
+            lines.push(theme.muted("budget not reported"));
+            break;
+    }
+    // Rate and spend caps hang off every bucket, so they are appended once here
+    // rather than repeated per branch. They are the ONLY ceilings a metered key
+    // has — and they appear only when they exist, which is why they can never
+    // stand in for the pool a metered key does not have.
+    if (budget.kind === "metered" && reading.chat) {
+        const { remaining, limit } = reading.chat.perKey;
+        lines.push(theme.muted(`${remaining} / ${limit} rpm`));
+    }
+    if (reading.keySpendCap) {
+        lines.push(spendCapLine(theme, "key", reading.keySpendCap));
+    }
+    if (reading.workspaceSpendCap) {
+        lines.push(spendCapLine(theme, "ws", reading.workspaceSpendCap));
+    }
+    // The cache keeps the last good reading through a failed refresh, so the panel
+    // owes the user the age of what it is showing rather than the impression that
+    // it is live.
+    const age = now - reading.readAt;
+    if (age > STALE_AFTER_MS) {
+        lines.push(theme.muted(`as of ${agoLabel(age)} ago`));
+    }
+    return lines;
+}
+/**
+ * The limits panel's body.
+ *
+ * `pending` and each error reason are said differently, on the tri-state
+ * discipline the git panel established: "still asking" must not read as "no
+ * limits", and neither may read as "your key is bad".
+ */
+export function limitsPanelLines(theme, state, now = Date.now()) {
+    if (state === undefined || state.status === "pending") {
+        return [theme.muted(`checking${theme.glyph.ellipsis}`)];
+    }
+    if (state.status === "error") {
+        switch (state.reason) {
+            case "unauthenticated":
+                return [theme.muted("not signed in"), theme.muted("run cruxy login")];
+            case "unsupported":
+                // The gateway answered — it simply has no limits to report. Sending this
+                // user to debug their network would be the wrong errand entirely.
+                return [theme.muted("gateway reports"), theme.muted("no limits")];
+            case "unreachable":
+                return [theme.muted("gateway unreachable")];
+        }
+    }
+    return readingLines(theme, state.reading, now);
+}

package/dist/tui/overview.js

@@ -20,7 +20,8 @@ import { sessionStatusLines } from "../render/status-view.js";
  *    cost two subprocesses each, ~45ms warm and worse on Windows, and the pane
  *    repaints on every frame and every resize. {@link WorkspaceGitCache} does
  *    the probing after a turn; {@link lines} only ever reads the last settled
- *    value.
+ *    value. Free space joins them: microseconds on a local disk, and an
+ *    unbounded kernel block on a network mount that has stopped answering.
  *
  * The rule the split enforces: nothing in `lines` may spawn, block, or touch
  * the disk. Anything that needs to is a cache read here and a `refresh` there.
@@ -31,19 +32,30 @@ export function createOverviewView(session, git,
  * because it changes per turn and the view is registered once. Supplied by
  * the renderer, the only object that sees the stream's routing frame.
  */
-servedTier = () => undefined) {
+servedTier = () => undefined, 
+/**
+ * Free space where cruxy writes. Optional so a caller that has no disk cache
+ * gets a status screen without disk rows rather than a probe it didn't ask
+ * for — the same shape `servedTier` uses for a fact only some callers have.
+ */
+disk) {
     return {
         id: "overview",
         label: "overview",
-        lines: (theme, cols) => sessionStatusLines(buildSessionStatus(session, (absPath) => git.current(absPath), servedTier()), theme, cols),
+        lines: (theme, cols) => sessionStatusLines(buildSessionStatus(session, (absPath) => git.current(absPath), servedTier(), disk ? (path) => disk.current(path) : undefined), theme, cols),
         /**
          * Re-probe every root after a turn. Invalidate-then-refresh because a turn
          * is exactly when the tree may have moved; the cache coalesces, so the ten
          * writes a turn makes still cost one probe per root.
+         *
+         * Disk refreshes alongside, and unconditionally — it has no invalidate,
+         * because free space moves for reasons that have nothing to do with this
+         * session (see `disk-status.ts`). Concurrently, not in sequence: they are
+         * independent reads and neither should wait on the other's slowest mount.
          */
         refresh: async () => {
             git.invalidate();
-            await git.refresh();
+            await Promise.all([git.refresh(), disk?.refresh()]);
         },
     };
 }

package/dist/tui/palette.js

@@ -1,29 +1,21 @@
 import { fuzzyFind } from "../components/fuzzy.js";
-import { COMMAND_CATALOG } from "../cli/session-commands.js";
+import { COMMAND_CATALOG, TUI_ONLY_COMMANDS } from "../cli/command-catalog.js";
 import { canOverlay, createOverlayIO } from "./overlay.js";
-/** The TUI's own commands, which the shared catalogue deliberately excludes. */
-const PANEL_COMMANDS = [
-    {
-        name: "/close",
-        summary: "hide a panel or the whole rail",
-        args: "<sidebar | context | model | git | tools | rail>",
-    },
-    {
-        name: "/open",
-        summary: "show a hidden panel",
-        args: "<sidebar | context | model | git | tools | rail>",
-    },
-];
 /**
- * Everything the palette offers: the shared catalogue, this shell's panel
+ * Everything the palette offers: the shared catalogue, this shell's own
  * commands, and the project's own slash commands.
  *
- * Custom commands come LAST and are labelled. `resolveSlash` consults builtins
- * first, so a custom command named `clear` can never shadow `/clear` — listing
- * it above the builtin would show an order the dispatcher does not honour.
+ * The TUI's own three are {@link TUI_ONLY_COMMANDS} rather than a copy kept
+ * here. The copy had drifted — it listed `/close` and `/open` and had never
+ * gained `/view`, so the one shell with a palette was also the one place `/view`
+ * could not be discovered.
+ *
+ * Custom commands come LAST and are labelled. A custom command can no longer be
+ * named after a reserved one at all (the loader refuses the file), so this list
+ * cannot contain two rows for one name.
  */
 export function paletteItems(slashCommands = []) {
-    const builtins = [...COMMAND_CATALOG, ...PANEL_COMMANDS].map((c) => ({
+    const builtins = [...COMMAND_CATALOG, ...TUI_ONLY_COMMANDS].map((c) => ({
         name: c.name,
         summary: c.summary,
         ...(c.args === undefined ? {} : { args: c.args }),

package/dist/tui/panels.js

@@ -17,6 +17,7 @@ import { RAIL_PANELS, } from "./layout.js";
 export const PANEL_LABELS = {
     sidebar: "sidebar",
     context: "context",
+    limits: "limits",
     model: "model",
     git: "git",
     tools: "tools",
@@ -30,6 +31,7 @@ export const COLUMN_LABELS = {
 /** Titles drawn at the top of each rail panel. */
 const RAIL_TITLES = {
     context: "context",
+    limits: "limits",
     model: "model",
     git: "git",
     tools: "tools",

package/dist/tui/renderer.js

@@ -11,6 +11,7 @@ import { ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, phaseIdentity, } from "
 import { budgetColumns, bodyRows, composeScreen, droppedForWidth, fitOverlay, overlayRows, scrollNotice, scrollWindow, stackPanels, CLOSABLE_PANELS, } from "./layout.js";
 import { CONVERSATION_VIEW, cycleView, navLines, } from "./views.js";
 import { contextPanelLines, gitPanelLines, headerModel, mainWelcome, modelPanelLines, railBlocks, sidebarLines, toolsPanelLines, } from "./panels.js";
+import { limitsPanelLines } from "./limits-panel.js";
 /**
  * The full-viewport renderer (P1) — the fourth {@link StreamRenderer}, and the
  * only one that owns the whole screen rather than a single managed line.
@@ -93,6 +94,10 @@ export class TuiRenderer {
     git;
     /** Context-budget reading for the context panel (P4 track 3); absent → unwired. */
     context;
+    /** The account's headroom for the limits panel (P9); absent → panel unwired. */
+    limits;
+    /** Whether the first limits read has been kicked off (see {@link startLimits}). */
+    limitsStarted = false;
     /**
      * The configured model/tier as known at construction — the renderer is built
      * before the session exists, so this covers the window before {@link attachModel}
@@ -196,6 +201,20 @@ export class TuiRenderer {
         gauge.sample();
         this.schedulePaint();
     }
+    /**
+     * Attach the limits cache (P9). Set after construction like the context gauge,
+     * because the credential it reads with is resolved alongside the session.
+     *
+     * NO PROBE HAPPENS HERE. The first read is deferred to the first paint that
+     * actually shows the panel — the rule the tool probes already follow — so a
+     * user who keeps `limits` closed, or who runs a one-shot that never paints a
+     * rail, never makes the request at all. The panel is a status surface; it does
+     * not get to spend a round trip on someone who is not looking at it.
+     */
+    attachLimits(limits) {
+        this.limits = limits;
+        this.schedulePaint();
+    }
     /**
      * Adopt the session's live model choice (P6 track 1). Set after construction
      * for the same reason the context gauge is: the choice belongs to the session,
@@ -233,6 +252,24 @@ export class TuiRenderer {
      * nothing after the first; the repaint callback is what lets each row appear
      * as its own probe lands rather than all at once at the end.
      */
+    /**
+     * Kick off the first limits read, at the first paint that actually SHOWS the
+     * panel. Returns the cache so the paint path can read it in one expression.
+     *
+     * Guarded by its own flag rather than by the cache's interval floor: the floor
+     * exists to coalesce refreshes AFTER a reading exists, and would not stop the
+     * paint path from firing a request on every frame before the first one lands.
+     */
+    startLimits(limits) {
+        if (!this.limitsStarted) {
+            this.limitsStarted = true;
+            void limits.refresh().then(() => {
+                if (!this.closed)
+                    this.schedulePaint();
+            });
+        }
+        return limits;
+    }
     startTools(tools) {
         tools.start(() => {
             if (!this.closed)
@@ -639,8 +676,29 @@ export class TuiRenderer {
         this.context?.sample();
         this.paintNow();
         this.refreshGit();
+        this.refreshLimits();
         this.refreshViews();
     }
+    /**
+     * Re-read the account's headroom after a turn (P9) — the one moment it is
+     * KNOWN to have moved, because this process just spent some of it.
+     *
+     * Same rules as the git probe: never awaited, a failure leaves the last good
+     * reading standing, and the cache coalesces. Unlike git it is also floored by
+     * a minimum interval, because this one crosses the network — and unlike git it
+     * is skipped entirely while the panel is closed, since a user who has hidden
+     * the figures has no use for the request that fetches them.
+     */
+    refreshLimits() {
+        const limits = this.limits;
+        if (limits === undefined || this.closed || !this.open.has("limits"))
+            return;
+        void limits.refresh().then(() => {
+            if (this.closed)
+                return;
+            this.schedulePaint();
+        });
+    }
     /**
      * Re-probe the working tree, off the paint path, and repaint when it lands.
      *
@@ -1043,6 +1101,14 @@ export class TuiRenderer {
             ...(this.context === undefined
                 ? {}
                 : { context: contextPanelLines(this.theme, this.context.current()) }),
+            // Like the tool probes: the first network read starts at the first paint
+            // that SHOWS this panel, never at startup and never at all while it is
+            // closed. `startLimits` is idempotent, so painting it costs one request.
+            ...(this.limits === undefined || !this.open.has("limits")
+                ? {}
+                : {
+                    limits: limitsPanelLines(this.theme, this.startLimits(this.limits).current()),
+                }),
             ...(this.git === undefined
                 ? {}
                 : { git: gitPanelLines(this.theme, this.git.current()) }),

package/dist/usage/weighted.js

@@ -41,6 +41,20 @@ export const TIER_MULTIPLIERS = {
 export function multiplierForTier(tier) {
     return TIER_MULTIPLIERS[tier];
 }
+/**
+ * The heaviest multiplier any chat tier carries.
+ *
+ * FOR ADMISSION ONLY, never for accounting. A request routed `auto` has no tier
+ * until the gateway answers, so an admission check that must decide BEFORE the
+ * request has to assume something — and the only safe assumption is the most
+ * expensive one. Assuming the cheapest (or skipping the check) admits a batch
+ * that then trips a sliding window which refills by trickle over twelve hours.
+ *
+ * {@link weightedFor} deliberately does NOT use this: after the fact the tier is
+ * known, and substituting a guess there would be exactly the confidently-wrong
+ * number that function's doc comment refuses to produce.
+ */
+export const MAX_TIER_MULTIPLIER = Math.max(...Object.values(TIER_MULTIPLIERS));
 /**
  * Weighted tokens for one request's figures, or `undefined` when the request
  * cannot be weighed honestly.

package/dist/utils/disk.js

@@ -0,0 +1,103 @@
+import { statfsSync } from "node:fs";
+import { statfs } from "node:fs/promises";
+const GIB = 1024 ** 3;
+/** Below this, a run that shadow-copies a repo can plausibly fail. */
+const LOW_FREE_BYTES = 5 * GIB;
+/** Below this, assume the next sizeable write fails. */
+const CRITICAL_FREE_BYTES = 1 * GIB;
+export function capacityLevel(capacity) {
+    if (capacity.freeBytes < CRITICAL_FREE_BYTES)
+        return "critical";
+    if (capacity.freeBytes < LOW_FREE_BYTES)
+        return "low";
+    return "ok";
+}
+/**
+ * Turn a `statfs` result into a capacity, or `undefined` when it cannot say
+ * anything true.
+ *
+ * `blocks === 0` is the guard that matters: some pseudo-filesystems report a
+ * zero total, and a percentage derived from it is `NaN` or `Infinity` — a
+ * "0% free" that means "we have no idea" is the single worst thing this could
+ * render, because it is indistinguishable from a genuinely full disk.
+ *
+ * Exported for the test that pins that guard: it is the one branch here that
+ * cannot be reached through a real `statfs` on any machine CI runs on.
+ */
+export function capacityFromStats(stats) {
+    const blockSize = Number(stats.bsize);
+    const blocks = Number(stats.blocks);
+    const available = Number(stats.bavail);
+    if (!(blockSize > 0) || !(blocks > 0) || !(available >= 0))
+        return undefined;
+    const totalBytes = blocks * blockSize;
+    const freeBytes = available * blockSize;
+    return {
+        freeBytes,
+        totalBytes,
+        freePercent: Math.floor((freeBytes / totalBytes) * 100),
+    };
+}
+/**
+ * Capacity of the filesystem holding `path`, or `undefined` if it can't be
+ * read (a path that doesn't exist, a platform or mount that won't answer).
+ *
+ * ASYNC because a `statfs` is only microseconds on a local disk — the whole
+ * reason this is affordable — but can block for SECONDS on an unresponsive
+ * network mount, and someone will eventually run cruxy in a repo on NFS. The
+ * cost model that justifies the feature holds for the common case; the API is
+ * shaped for the uncommon one.
+ */
+export async function readDiskCapacity(path) {
+    try {
+        return capacityFromStats(await statfs(path));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The synchronous read, for the one caller that is allowed one: a command the
+ * user just typed, which has no frame to lose and every reason to print a real
+ * answer instead of "checking…". Never call this from a paint path.
+ */
+export function readDiskCapacitySync(path) {
+    try {
+        return capacityFromStats(statfsSync(path));
+    }
+    catch {
+        return undefined;
+    }
+}
+const UNITS = ["B", "KiB", "MiB", "GiB", "TiB", "PiB"];
+/**
+ * `8.1 GiB`, `465 GiB`, `912 MiB`.
+ *
+ * Binary units with binary labels. `GB` for 2^30 is the ambiguity that makes
+ * people distrust a number they were about to act on; if the unit is 1024-based
+ * the label says so.
+ */
+export function formatBytes(bytes) {
+    let value = Math.max(0, bytes);
+    let unit = 0;
+    while (value >= 1024 && unit < UNITS.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    // One decimal only while it carries information: "8.1 GiB" is a different
+    // amount from "8 GiB", "465.3 GiB" is not meaningfully different from "465".
+    const digits = unit > 0 && value < 10 ? 1 : 0;
+    return `${value.toFixed(digits)} ${UNITS[unit]}`;
+}
+/**
+ * `2% free · 8.1 GiB of 465 GiB` — the percentage first, since that's the read.
+ *
+ * The joiner is a PARAMETER rather than a literal: this module has no theme (it
+ * is a `statfs` reader, not a renderer), and a hardcoded `·` would survive
+ * `CRUXY_ASCII` and `TERM=dumb` on a terminal that renders it as mojibake, and
+ * announce as noise to a screen reader. Callers pass `theme.glyph.sep`; the
+ * default keeps every existing caller and every log line unchanged.
+ */
+export function formatCapacity(capacity, sep = "·") {
+    return `${capacity.freePercent}% free ${sep} ${formatBytes(capacity.freeBytes)} of ${formatBytes(capacity.totalBytes)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
     "undici": "^6.21.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5",
-    "@cruxy/sdk": "0.4.1"
+    "@cruxy/sdk": "0.5.0"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.11.1"
@@ -52,7 +52,7 @@
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
     "clean": "rm -rf dist",
     "test": "vitest run"
   }