@zenera/cli 1.1.10 → 1.1.12

package/dist/cache.js

@@ -0,0 +1,301 @@
+import { createHash } from 'node:crypto';
+import { readdirSync, readFileSync, rmdirSync, rmSync, statSync, utimesSync } from 'node:fs';
+import { join } from 'node:path';
+import { paths, writeJson } from "./home.js";
+// ---------------------------------------------------------------------------
+// One place for work already done
+//
+// Embedding a paragraph, parsing a document, asking a provider what models it
+// serves: all expensive, all perfectly repeatable, and all previously cached by
+// a different hand-rolled file format sitting in a different directory. This is
+// the one store they share, at `~/.zenera/neo/cache/<kind>/<ab>/<sha>.json`,
+// one file per object.
+//
+// Three rules hold the whole thing up.
+//
+// **Nothing here throws.** A corrupt file, a full disk, an unreadable
+// directory, a key that does not match: every one of them is a miss. A cache
+// that cannot work costs time and must never cost correctness, so there is no
+// error path for a caller to get wrong.
+//
+// **The key carries every input.** Not the text alone but the model, the
+// dimensions, the version of whatever produced the value — all of it. That is
+// why there is no invalidation step anywhere: change any input and you are
+// asking a different question, which has no answer yet. Vectors from another
+// model are not evicted, they are simply never found.
+//
+// **The key is written into the entry and checked on the way out.** The path is
+// only a hash of it. Reading proves the file is the one that was asked for
+// rather than trusting sha256 to be injective, and — much more likely to
+// actually happen — it catches a key derivation that changed shape without
+// anyone bumping a version.
+// ---------------------------------------------------------------------------
+/** Characters of the digest that name the subdirectory, so no one directory grows huge. */
+const SHARD = 2;
+/**
+ * How stale a mtime has to be before reading an entry rewrites it.
+ *
+ * `commit` is what makes "older than 30 days" mean *unused* for 30 days rather
+ * than *unwritten* for 30 days. Doing it on every read would be a write per
+ * read; a day's granularity costs nothing and is far finer than any retention
+ * anyone will ask for.
+ */
+const TOUCH_AFTER_MS = 24 * 60 * 60 * 1000;
+/** Joins the parts of a composite key. NUL cannot occur in any of them. */
+export function cacheKey(...parts) {
+    return parts.map((part) => part ?? '').join('\u0000');
+}
+export class Cache {
+    kind;
+    #dir;
+    #mode;
+    /** entries read this run, so `commit` can say they are still wanted */
+    #used = new Set();
+    #hits = 0;
+    #misses = 0;
+    constructor(kind, options = {}) {
+        this.kind = kind;
+        this.#dir = join(options.dir ?? paths.cache(), kind);
+        this.#mode = options.mode;
+    }
+    get hits() {
+        return this.#hits;
+    }
+    get misses() {
+        return this.#misses;
+    }
+    #path(key) {
+        const sha = createHash('sha256')
+            .update(this.kind, 'utf8')
+            .update('\u0000', 'utf8')
+            .update(key, 'utf8')
+            .digest('hex');
+        return join(this.#dir, sha.slice(0, SHARD), `${sha}.json`);
+    }
+    entry(key) {
+        const path = this.#path(key);
+        let found;
+        try {
+            found = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            this.#misses++;
+            return undefined;
+        }
+        if (found?.kind !== this.kind || found.key !== key) {
+            this.#misses++;
+            return undefined;
+        }
+        this.#hits++;
+        this.#used.add(path);
+        return { value: found.value, storedAt: found.storedAt };
+    }
+    get(key) {
+        return this.entry(key)?.value;
+    }
+    put(key, value) {
+        const stored = {
+            kind: this.kind,
+            key,
+            storedAt: new Date().toISOString(),
+            value,
+        };
+        try {
+            writeJson(this.#path(key), stored, this.#mode);
+        }
+        catch {
+            // Out of disk, or the directory went away. Nothing depends on this.
+        }
+    }
+    delete(key) {
+        try {
+            rmSync(this.#path(key), { force: true });
+        }
+        catch {
+            // Still cached, then. It will be pruned by age eventually.
+        }
+    }
+    commit() {
+        const now = new Date();
+        for (const path of this.#used) {
+            try {
+                if (now.getTime() - statSync(path).mtimeMs > TOUCH_AFTER_MS) {
+                    utimesSync(path, now, now);
+                }
+            }
+            catch {
+                // Gone, or read-only. Neither is worth a word.
+            }
+        }
+        this.#used.clear();
+    }
+}
+/** Remembers nothing, for `--no-cache` and for anywhere a store cannot be opened. */
+export const NO_CACHE = {
+    kind: 'none',
+    hits: 0,
+    misses: 0,
+    entry: () => undefined,
+    get: () => undefined,
+    put: () => { },
+    delete: () => { },
+    commit: () => { },
+};
+const dirents = (dir) => {
+    try {
+        return readdirSync(dir, { withFileTypes: true }).map((e) => ({
+            name: e.name,
+            dir: e.isDirectory(),
+            file: e.isFile(),
+        }));
+    }
+    catch {
+        return [];
+    }
+};
+/** Every entry file, kind by kind. Half-written `.tmp` siblings are not entries. */
+function* walk(dir, only) {
+    for (const kind of dirents(dir)) {
+        if (!kind.dir || (only !== undefined && kind.name !== only)) {
+            continue;
+        }
+        const kindDir = join(dir, kind.name);
+        for (const shard of dirents(kindDir)) {
+            if (!shard.dir) {
+                continue;
+            }
+            const shardDir = join(kindDir, shard.name);
+            for (const file of dirents(shardDir)) {
+                if (!file.file || !file.name.endsWith('.json')) {
+                    continue;
+                }
+                const path = join(shardDir, file.name);
+                try {
+                    const info = statSync(path);
+                    yield { kind: kind.name, path, bytes: info.size, usedAt: info.mtimeMs };
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+    }
+}
+/** A row per kind, for `zen cache ls`. One stat walk; nothing is parsed. */
+export function kinds(dir = paths.cache()) {
+    const rows = new Map();
+    for (const found of walk(dir)) {
+        const row = rows.get(found.kind) ?? { kind: found.kind, entries: 0, bytes: 0 };
+        row.entries++;
+        row.bytes += found.bytes;
+        row.oldest = Math.min(row.oldest ?? found.usedAt, found.usedAt);
+        row.newest = Math.max(row.newest ?? found.usedAt, found.usedAt);
+        rows.set(found.kind, row);
+    }
+    return [...rows.values()].sort((a, b) => a.kind.localeCompare(b.kind));
+}
+/**
+ * The entries of one kind, most recently used first. Reading a key means
+ * parsing the file, so the sort happens on stat data and only what will be
+ * shown is opened.
+ */
+export function items(kind, options = {}) {
+    const all = [...walk(options.dir ?? paths.cache(), kind)].sort((a, b) => b.usedAt - a.usedAt);
+    const take = options.limit === undefined ? all : all.slice(0, options.limit);
+    const rows = take.map((found) => {
+        const row = {
+            kind: found.kind,
+            key: '',
+            bytes: found.bytes,
+            usedAt: found.usedAt,
+        };
+        try {
+            const stored = JSON.parse(readFileSync(found.path, 'utf8'));
+            row.key = stored.key ?? '';
+            row.storedAt = stored.storedAt;
+            row.value = stored.value;
+        }
+        catch {
+            // An unreadable entry is still an entry taking up room.
+        }
+        return row;
+    });
+    return { rows, found: all.length };
+}
+/**
+ * Removes what the options describe and reports what went, by kind.
+ *
+ * `maxBytes` applies to the whole selection rather than to each kind
+ * separately: the disk is one thing, and least-recently-used across the store
+ * is the only ordering that means anything on it.
+ */
+export function sweep(options = {}) {
+    const dir = options.dir ?? paths.cache();
+    const cutoff = options.olderThanMs === undefined ? undefined : Date.now() - options.olderThanMs;
+    const kept = [];
+    const doomed = [];
+    for (const found of walk(dir, options.kind)) {
+        (cutoff !== undefined && found.usedAt < cutoff ? doomed : kept).push(found);
+    }
+    if (options.maxBytes !== undefined) {
+        kept.sort((a, b) => a.usedAt - b.usedAt);
+        let total = kept.reduce((n, f) => n + f.bytes, 0);
+        while (total > options.maxBytes && kept.length > 0) {
+            const found = kept.shift();
+            total -= found.bytes;
+            doomed.push(found);
+        }
+    }
+    const swept = new Map();
+    for (const found of doomed) {
+        try {
+            rmSync(found.path, { force: true });
+        }
+        catch {
+            continue;
+        }
+        const row = swept.get(found.kind) ?? { kind: found.kind, removed: 0, bytes: 0 };
+        row.removed++;
+        row.bytes += found.bytes;
+        swept.set(found.kind, row);
+    }
+    tidy(dir);
+    return [...swept.values()].sort((a, b) => a.kind.localeCompare(b.kind));
+}
+/** Everything, or one kind of everything. */
+export function clear(options = {}) {
+    const dir = options.dir ?? paths.cache();
+    try {
+        rmSync(options.kind === undefined ? dir : join(dir, options.kind), {
+            recursive: true,
+            force: true,
+        });
+    }
+    catch {
+        // Whatever survived will be reported by the next `ls`.
+    }
+}
+/** Drops the shard and kind directories a sweep emptied. */
+function tidy(dir) {
+    for (const kind of dirents(dir)) {
+        if (!kind.dir) {
+            continue;
+        }
+        const kindDir = join(dir, kind.name);
+        for (const shard of dirents(kindDir)) {
+            if (shard.dir) {
+                rmdir(join(kindDir, shard.name));
+            }
+        }
+        rmdir(kindDir);
+    }
+}
+function rmdir(dir) {
+    try {
+        rmdirSync(dir);
+    }
+    catch {
+        // Not empty, which is the usual answer.
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/catalog.d.ts

@@ -51,6 +51,7 @@ export interface Catalog {
 }
 /** A day. Model lists change on the scale of weeks; a stale row costs a retry. */
 export declare const CATALOG_TTL_MS: number;
+export declare const CATALOG_KIND = "catalog";
 /**
  * Enough to work with when the provider cannot be asked — offline, no
  * credential, or a listing endpoint that is down. Deliberately short: this is
@@ -80,6 +81,8 @@ export declare const PREFERRED: Record<Provider, {
  * `ProviderSpec.client`, which exists in the library for the same reason.
  */
 export declare function fetchCatalog(provider: Provider, client?: unknown): Promise<CatalogEntry[]>;
+/** The key one provider's listing is filed under, version and all. */
+export declare const catalogKey: (provider: Provider) => string;
 export interface CatalogOptions {
     /** ignore a fresh cache and ask the provider again */
     refresh?: boolean;

package/dist/catalog.js

@@ -16,14 +16,15 @@
 // `source` for exactly that reason: a curated guess must never be mistaken for
 // the vendor's own word.
 // ---------------------------------------------------------------------------
-import { join } from 'node:path';
 import { ModelRegistry } from '@zenera/neo';
-import { paths, readJson, writeJson } from "./home.js";
+import { Cache, cacheKey } from "./cache.js";
 import { PROVIDERS } from "./keys.js";
 import { classify } from "./liveness.js";
 /** A day. Model lists change on the scale of weeks; a stale row costs a retry. */
 export const CATALOG_TTL_MS = 24 * 60 * 60 * 1000;
-const CACHE_VERSION = 1;
+export const CATALOG_KIND = 'catalog';
+/** Bumped when the stored shape changes, which makes every old entry a miss. */
+const CATALOG_VERSION = 1;
 // ---------------------------------------------------------------------------
 // The fallback table
 // ---------------------------------------------------------------------------
@@ -341,10 +342,35 @@ function enrich(provider, live) {
         };
     });
 }
-const cachePath = (provider) => join(paths.catalog(), `${provider}.json`);
-async function readCache(provider) {
-    const file = await readJson(cachePath(provider), undefined);
-    return file?.version === CACHE_VERSION && Array.isArray(file.entries) ? file : undefined;
+/**
+ * Listings are public data, so the file is left readable — someone wondering
+ * where a model row came from can go and look at it. Opened per call rather
+ * than once, because the home directory is an environment variable and a test
+ * is allowed to move it.
+ */
+const store = () => new Cache(CATALOG_KIND, { mode: 0o644 });
+/**
+ * What else decides a listing's contents. Vertex answers per project and per
+ * location — one account was offered eight models at `us` and forty at
+ * `us-central1` — so a key naming only the provider serves one of those lists
+ * to both. A project left to the service-account file is not seen here.
+ */
+function scope(provider) {
+    if (provider !== 'vertex') {
+        return undefined;
+    }
+    return cacheKey(process.env.GOOGLE_CLOUD_PROJECT, process.env.GOOGLE_CLOUD_LOCATION ?? 'global');
+}
+/** The key one provider's listing is filed under, version and all. */
+export const catalogKey = (provider) => {
+    const extra = scope(provider);
+    return extra ? cacheKey(CATALOG_VERSION, provider, extra) : cacheKey(CATALOG_VERSION, provider);
+};
+function readCache(provider) {
+    const file = store().get(catalogKey(provider));
+    return file && Array.isArray(file.entries) && typeof file.fetchedAt === 'string'
+        ? file
+        : undefined;
 }
 /**
  * The listing for one provider, from the cheapest source that can answer.
@@ -356,7 +382,7 @@ async function readCache(provider) {
  * model list to four rows.
  */
 export async function loadCatalog(provider, opts = {}) {
-    const cached = await readCache(provider);
+    const cached = readCache(provider);
     const fresh = cached && Date.now() - new Date(cached.fetchedAt).getTime() < CATALOG_TTL_MS
         ? cached
         : undefined;
@@ -367,9 +393,7 @@ export async function loadCatalog(provider, opts = {}) {
         try {
             const entries = await fetchCatalog(provider);
             const fetchedAt = new Date().toISOString();
-            writeJson(cachePath(provider), { version: CACHE_VERSION, provider, fetchedAt, entries }, 
-            // Public data, and readable so a human can look at what was cached.
-            0o644);
+            store().put(catalogKey(provider), { provider, fetchedAt, entries });
             return { provider, entries, origin: 'live', fetchedAt };
         }
         catch (err) {

package/dist/commands/cache.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from '../command.ts';
+export declare const cache: Command;
+/** `30d`, `12h`, `2w`. A bare number is days: nobody means milliseconds. */
+export declare function duration(text: string | undefined): number | undefined;
+/** `500MB`, `2GB`. Powers of 1000, the way `bytes()` prints them back. */
+export declare function size(text: string | undefined): number | undefined;
+//# sourceMappingURL=cache.d.ts.map

package/dist/commands/cache.js

@@ -0,0 +1,245 @@
+import { parse } from "../args.js";
+import { clear, items, kinds, sweep } from "../cache.js";
+import { paths } from "../home.js";
+import { ago, bold, bytes, confirm, count, cyan, dim, green, isInteractive, json, note, table, usageError, writeAll, } from "../term.js";
+const USAGE = 'zen cache [ls|prune|clear] [options]';
+/** Enough to see what is in there; the rest is a number. */
+const LISTED = 20;
+// ---------------------------------------------------------------------------
+// The cache, from outside
+//
+// Everything expensive and repeatable this machine has done is kept in one
+// place, and the reason it needs a command at all is that nothing evicts from
+// it on its own. That is deliberate: a store that quietly deletes things is
+// only ever noticed when it has deleted the wrong one. So retention is a
+// decision someone makes out loud, here.
+//
+// Nothing in it is precious. Every entry can be recomputed, which is why
+// `clear` is safe to reach for and why the only cost of being wrong is time.
+// ---------------------------------------------------------------------------
+export const cache = {
+    summary: 'What work has been kept, and getting rid of it.',
+    usage: USAGE,
+    details: [
+        '  ls                     What is stored, by kind. Changes nothing.',
+        '  prune                  Remove what the filters name.',
+        '  clear                  Remove everything, or one kind of everything.',
+        '',
+        '  --kind <name>          Just this kind. With `ls`, list its entries.',
+        '  --older-than <age>     Unused for longer than e.g. 30d, 12h, 2w.',
+        '  --max-size <size>      Ceiling on what is left, e.g. 500MB, 2GB.',
+        '  --limit <n>            Entries to list. Default 20.',
+        '  --yes                  Do not ask before removing.',
+        '',
+        'Age is when an entry was last *used*, not when it was written, so a',
+        'vector a rebuild reads every week is never old.',
+        '',
+        '`prune` with no filter is a usage error: deleting everything is what',
+        '`clear` is for, and it should have to be typed.',
+        '',
+        'Nothing here is precious. Every entry is work that can be done again,',
+        'so the only cost of removing one is paying for it a second time.',
+    ],
+    run: async (ctx) => {
+        const { values, positionals } = parse(ctx.args, {
+            kind: { type: 'string' },
+            'older-than': { type: 'string' },
+            'max-size': { type: 'string' },
+            limit: { type: 'string' },
+            yes: { type: 'boolean' },
+        }, USAGE);
+        const what = positionals[0] ?? 'ls';
+        if (!['ls', 'prune', 'clear'].includes(what)) {
+            throw usageError(`unknown subcommand: ${what}`, USAGE);
+        }
+        if (positionals.length > 1) {
+            throw usageError('one subcommand at a time', USAGE);
+        }
+        switch (what) {
+            case 'ls':
+                return list(values, ctx.json);
+            case 'prune':
+                return prune(values, ctx.json);
+            default:
+                return wipe(values, ctx.json);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// ls
+// ---------------------------------------------------------------------------
+function list(values, asJson) {
+    if (values.kind) {
+        return listOne(values, asJson);
+    }
+    const rows = kinds();
+    if (asJson) {
+        json({ dir: paths.cache(), kinds: rows, ...totals(rows) });
+        return;
+    }
+    if (rows.length === 0) {
+        note(`nothing cached yet ${dim(paths.cache())}`);
+        return;
+    }
+    writeAll(table([
+        [bold('KIND'), bold('ENTRIES'), bold('SIZE'), bold('OLDEST'), bold('NEWEST')],
+        ...rows.map((row) => [
+            cyan(row.kind),
+            String(row.entries),
+            bytes(row.bytes),
+            dim(since(row.oldest)),
+            dim(since(row.newest)),
+        ]),
+    ]));
+    const all = totals(rows);
+    note('');
+    note(dim(`${count(all.entries, 'entry', 'entries')}, ${bytes(all.bytes)} in ${paths.cache()}`));
+}
+function listOne(values, asJson) {
+    const kind = values.kind;
+    const limit = number(values.limit, '--limit') ?? LISTED;
+    const { rows, found } = items(kind, { limit });
+    if (asJson) {
+        json({ kind, found, entries: rows });
+        return;
+    }
+    if (found === 0) {
+        note(`nothing cached under ${cyan(kind)}`);
+        return;
+    }
+    writeAll(table([
+        [bold('KEY'), bold('SIZE'), bold('USED')],
+        ...rows.map((row) => [shorten(row.key), bytes(row.bytes), dim(since(row.usedAt))]),
+    ]));
+    if (found > rows.length) {
+        note('');
+        note(dim(`${found - rows.length} more — raise --limit to see them`));
+    }
+}
+// ---------------------------------------------------------------------------
+// prune and clear
+// ---------------------------------------------------------------------------
+function prune(values, asJson) {
+    const olderThanMs = duration(values['older-than']);
+    const maxBytes = size(values['max-size']);
+    if (olderThanMs === undefined && maxBytes === undefined) {
+        throw usageError('prune needs something to go on', 'pass --older-than <age> or --max-size <size>, or run: zen cache clear');
+    }
+    report(sweep({ kind: values.kind, olderThanMs, maxBytes }), asJson);
+}
+async function wipe(values, asJson) {
+    const before = kinds().filter((row) => !values.kind || row.kind === values.kind);
+    const all = totals(before);
+    if (all.entries === 0) {
+        if (asJson) {
+            json({ removed: [], entries: 0, bytes: 0 });
+            return;
+        }
+        note(values.kind ? `nothing cached under ${cyan(values.kind)}` : 'nothing cached yet');
+        return;
+    }
+    if (!values.yes && !asJson && isInteractive()) {
+        const what = values.kind
+            ? `${count(all.entries, 'entry', 'entries')} under ${values.kind}`
+            : count(all.entries, 'entry', 'entries');
+        if (!(await confirm(`Remove ${what} (${bytes(all.bytes)})?`))) {
+            note('left alone');
+            return;
+        }
+    }
+    clear({ kind: values.kind });
+    report(before.map((row) => ({ kind: row.kind, removed: row.entries, bytes: row.bytes })), asJson);
+}
+function report(swept, asJson) {
+    const entries = swept.reduce((n, row) => n + row.removed, 0);
+    const freed = swept.reduce((n, row) => n + row.bytes, 0);
+    if (asJson) {
+        json({ removed: swept, entries, bytes: freed });
+        return;
+    }
+    if (entries === 0) {
+        note('nothing to remove');
+        return;
+    }
+    for (const row of swept) {
+        note(`${green('removed')} ${count(row.removed, 'entry', 'entries')} ${dim(`${row.kind} · ${bytes(row.bytes)}`)}`);
+    }
+    if (swept.length > 1) {
+        note('');
+        note(dim(`${count(entries, 'entry', 'entries')}, ${bytes(freed)} freed`));
+    }
+}
+// ---------------------------------------------------------------------------
+// Reading the filters
+// ---------------------------------------------------------------------------
+const DURATIONS = {
+    s: 1000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+/** `30d`, `12h`, `2w`. A bare number is days: nobody means milliseconds. */
+export function duration(text) {
+    if (text === undefined) {
+        return undefined;
+    }
+    const match = /^(\d+(?:\.\d+)?)\s*([a-z]*)$/i.exec(text.trim());
+    const unit = match ? (match[2] || 'd').toLowerCase() : '';
+    const scale = DURATIONS[unit];
+    if (!match || scale === undefined) {
+        throw usageError(`"${text}" is not an age`, 'try: 30d, 12h, 2w');
+    }
+    return Number(match[1]) * scale;
+}
+const SIZES = {
+    b: 1,
+    kb: 1000,
+    mb: 1000 ** 2,
+    gb: 1000 ** 3,
+    tb: 1000 ** 4,
+};
+/** `500MB`, `2GB`. Powers of 1000, the way `bytes()` prints them back. */
+export function size(text) {
+    if (text === undefined) {
+        return undefined;
+    }
+    const match = /^(\d+(?:\.\d+)?)\s*([a-z]*)$/i.exec(text.trim());
+    const unit = match ? (match[2] || 'mb').toLowerCase() : '';
+    const scale = SIZES[unit];
+    if (!match || scale === undefined) {
+        throw usageError(`"${text}" is not a size`, 'try: 500MB, 2GB');
+    }
+    return Number(match[1]) * scale;
+}
+function number(text, flag) {
+    if (text === undefined) {
+        return undefined;
+    }
+    const value = Number(text);
+    if (!Number.isInteger(value) || value < 1) {
+        throw usageError(`${flag} takes a whole number of at least 1`, `got "${text}"`);
+    }
+    return value;
+}
+// ---------------------------------------------------------------------------
+// Small formatting
+// ---------------------------------------------------------------------------
+const totals = (rows) => ({
+    entries: rows.reduce((n, row) => n + row.entries, 0),
+    bytes: rows.reduce((n, row) => n + row.bytes, 0),
+});
+const since = (at) => at === undefined ? 'never' : ago(new Date(at).toISOString());
+/**
+ * A key holds every input that produced the value, so an embedding's key is a
+ * whole paragraph. One line of it says which entry this is; the rest is noise
+ * in a table.
+ */
+function shorten(key) {
+    const flat = key
+        .replace(/\u0000/g, ' · ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return flat.length > 72 ? `${flat.slice(0, 71)}…` : flat || dim('(unreadable)');
+}
+//# sourceMappingURL=cache.js.map

package/dist/commands/check.js

@@ -35,9 +35,9 @@ export const check = {
     details: [
         'Checks the whole project: the configuration parses and satisfies the',
         'schema, every prompt, skill and catalog it names is on disk, hand-offs',
-        'and forks name agents that exist, tool selectors resolve, skills bind to',
-        'a catalog that holds them, and the models it declares have a credential',
-        'on this machine.',
+        'and forks name agents that exist, every hand-off has a way back, tool',
+        'selectors resolve, skills bind to a catalog that holds them, and the',
+        'models it declares have a credential on this machine.',
         '',
         'It also builds the sandbox image and runs one command in it, against a',
         'temporary directory rather than your workspace, and --no-sandbox skips',
@@ -199,6 +199,9 @@ function render(report) {
     if (report.models.length) {
         push(...table(report.models.map((m) => [
             `  ${m.name}`,
+            // An alias names nothing the provider knows, so what it
+            // stands for is printed next to it.
+            dim(m.ref ?? ''),
             dim(m.provider ? `${m.provider} (${m.kind})` : red('unresolved')),
             dim(m.env ?? ''),
             credential(m.credential),