@zenera/cli 1.1.24 → 1.1.26

package/dist/commands/models.js

@@ -11,14 +11,14 @@
 // instead", and prints a ref on stdout that can be pasted straight back into
 // agents.yaml — or read by an agent doing the pasting.
 // ---------------------------------------------------------------------------
-import { createEmbedder, createModel, ModelRegistry } from '@zenera/neo';
+import { createEmbedder, ModelRegistry } from '@zenera/neo';
 import { parse } from "../args.js";
-import { loadCatalog, loadCatalogs, matches, PREFERRED, } from "../catalog.js";
+import { byGroup, groupOf, isPartner, loadCatalog, loadCatalogs, matches, PREFERRED, routerBalance, } from "../catalog.js";
 import { ensureHome } from "../home.js";
 import { envNames, form, isProvider, KeyStore, PROVIDERS } from "../keys.js";
-import { probeModel } from "../liveness.js";
-import { ago, bold, credentialError, cyan, dim, green, json, note, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
-const USAGE = 'zen models <providers|ls|search|show|test|pick> [ref] [options]';
+import { probeChat, probeModel } from "../liveness.js";
+import { ago, bold, CliError, credentialError, cyan, dim, EXIT, green, isInteractive, json, note, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen models <providers|ls|search|show|test|pick|browse> [ref] [options]';
 /**
  * The keyring is materialised here, and only here.
  *
@@ -112,15 +112,32 @@ function freshness(cat) {
     return cat.origin === 'live' ? green('fetched now') : dim(`cached ${ago(cat.fetchedAt)}`);
 }
 const roleMark = (row) => row.roles.join('+');
+const maker = (row) => !row.publisher ? '' : isPartner(row) ? yellow(row.publisher) : green(row.publisher);
 function row(entry) {
     return [
         cyan(entry.ref),
+        maker(entry),
         dim(roleMark(entry)),
         dim(tokens(entry.contextLength)),
         dim(entry.pricing?.free ? 'free' : ''),
         dim(entry.name ?? ''),
     ];
 }
+/** The table, with a heading wherever a reseller's rows change maker. */
+function grouped(entries) {
+    const lines = table(entries.map(row));
+    const out = [];
+    let last;
+    entries.forEach((e, i) => {
+        const group = groupOf(e);
+        if (group && group !== last) {
+            out.push(...(out.length > 0 ? [''] : []), bold(group));
+        }
+        last = group;
+        out.push(lines[i]);
+    });
+    return out;
+}
 /**
  * Says how a listing was obtained whenever it was not the vendor's own word —
  * on stderr, because it is narration about the answer rather than the answer.
@@ -175,6 +192,7 @@ const providers = async (ctx, args) => {
     })));
     note('');
     note(dim('zen models ls <provider>   what one of them serves'));
+    note(dim('zen models browse          walk them with the arrow keys'));
     note(dim('zen models pick --chat     the first one that answers'));
 };
 // ---------------------------------------------------------------------------
@@ -198,7 +216,7 @@ const ls = async (ctx, args) => {
     const all = cats
         .flatMap((c) => c.entries)
         .filter((e) => matches(e, '', { roles }))
-        .sort((a, b) => a.ref.localeCompare(b.ref));
+        .sort(byGroup);
     if (ctx.json) {
         json({
             models: all,
@@ -215,10 +233,13 @@ const ls = async (ctx, args) => {
         note(dim('nothing matched — try: zen models ls --refresh'));
         return;
     }
-    writeAll(table(all.slice(0, limit).map(row)));
+    writeAll(grouped(all.slice(0, limit)));
     if (all.length > limit) {
         note(dim(`${all.length - limit} more — narrow with \`zen models search\`, or pass --all`));
     }
+    if (all.some(isPartner)) {
+        note(dim('partner models are billed through Vertex and must be enabled in Model Garden first: https://console.cloud.google.com/vertex-ai/model-garden'));
+    }
 };
 // ---------------------------------------------------------------------------
 // search
@@ -255,7 +276,7 @@ const search = async (ctx, args) => {
         // Cheapest first when price is known: search is usually the step before
         // picking one, and the free ones are what most people are looking for.
         .sort((a, b) => Number(b.pricing?.free ?? false) - Number(a.pricing?.free ?? false) ||
-        a.ref.localeCompare(b.ref));
+        byGroup(a, b));
     if (ctx.json) {
         json({ query, matched: hits.length, models: hits.slice(0, limit) });
         return;
@@ -377,9 +398,7 @@ function target(ref, provider, id, role) {
     if (role !== 'chat') {
         throw usageError(`${ref} is ${role}-only, and there is no way to ask it a question from here`, 'zen models test only exercises chat and embedding models');
     }
-    // 16 tokens is enough for "ok" and not enough to matter. Anthropic requires
-    // a cap at all, so this is not merely thrift.
-    return { ref, kind: 'model', model: createModel({ provider, model: id, maxTokens: 16 }) };
+    return { ref, kind: 'model', model: probeChat(provider, id) };
 }
 function verdict(probe) {
     switch (probe.check.state) {
@@ -536,6 +555,68 @@ const pick = async (ctx, args) => {
     throw credentialError(`no ${role} model answered on this machine`, 'add a credential: zen key add openai');
 };
 // ---------------------------------------------------------------------------
+// browse
+// ---------------------------------------------------------------------------
+/**
+ * The same catalog, walked with the arrow keys: providers, what one serves,
+ * one model in full, with a key to ask it a question and a key to take it.
+ *
+ * The interface is drawn on stderr, so a pick reaches stdout alone and
+ * `$(zen models browse)` is the ref, the same contract `pick` keeps.
+ */
+const browse = async (ctx, args) => {
+    const { values, positionals } = parse(args, { refresh: { type: 'boolean' }, theme: { type: 'string' } }, 'zen models browse [provider] [--refresh] [--theme dark|light|auto]');
+    const initial = positionals[0];
+    if (initial !== undefined && !isProvider(initial)) {
+        throw usageError(`unknown provider "${initial}"`, `known: ${PROVIDERS.join(', ')}`);
+    }
+    if (ctx.json || !isInteractive()) {
+        throw usageError('browsing needs a person at a terminal', 'from a script: zen models ls --json, or zen models pick --chat');
+    }
+    const where = await credentials();
+    // Offline, like `providers`: the overview should not cost five listings.
+    // A provider is fetched when it is opened.
+    const cats = await loadCatalogs(PROVIDERS, { offline: true });
+    const { browse: draw } = await import("../tui/models.js");
+    const chosen = await draw({
+        providers: cats.map((c) => ({
+            provider: c.provider,
+            credential: source(where, c.provider),
+            models: c.entries.length,
+            origin: c.origin,
+            fetchedAt: c.fetchedAt,
+        })),
+        initial,
+        theme: values.theme,
+        load: (provider, refresh) => loadCatalog(provider, { refresh: refresh || values.refresh }),
+        balance: async (provider) => provider === 'openrouter' && source(where, provider) ? routerBalance() : undefined,
+        test: async (entry) => {
+            const role = entry.roles.includes('chat')
+                ? 'chat'
+                : entry.roles.includes('embedding')
+                    ? 'embedding'
+                    : (entry.roles[0] ?? 'chat');
+            const probe = await probeModel(target(entry.ref, entry.provider, entry.id, role));
+            return {
+                state: probe.check.state,
+                ms: probe.ms,
+                detail: probe.check.detail,
+                fix: probe.check.fix,
+                dimensions: probe.dimensions,
+            };
+        },
+    });
+    if (!chosen) {
+        // Leaving is a fine way to end a browse, but not an answer to a
+        // substitution that was waiting for one.
+        if (!process.stdout.isTTY) {
+            throw new CliError('nothing picked', EXIT.failed);
+        }
+        return;
+    }
+    write(chosen.ref);
+};
+// ---------------------------------------------------------------------------
 // Dispatch
 // ---------------------------------------------------------------------------
 const SUBS = {
@@ -548,6 +629,8 @@ const SUBS = {
     test,
     check: test,
     pick,
+    browse,
+    ui: browse,
 };
 export const models = {
     summary: 'What this machine can use: list, search, test and pick models.',
@@ -570,6 +653,8 @@ export const models = {
         '  zen models show <ref>            One model, in full.',
         '  zen models test <ref> …          Ask it one real question.',
         '  zen models pick --embedding      The first ref that answers, on stdout.',
+        '  zen models browse [provider]     Walk providers and models with the',
+        '                                   arrow keys; t asks one, p prints its ref.',
     ],
     run: async (ctx) => {
         const [name, ...rest] = ctx.args;
@@ -588,7 +673,7 @@ export const models = {
             await ls(ctx, ctx.args);
             return;
         }
-        throw usageError(`unknown: zen models ${name}`, `try: ${cyan('providers, ls, search, show, test, pick')} — or a provider: ${dim(PROVIDERS.join(', '))}`);
+        throw usageError(`unknown: zen models ${name}`, `try: ${cyan('providers, ls, search, show, test, pick, browse')} — or a provider: ${dim(PROVIDERS.join(', '))}`);
     },
 };
 //# sourceMappingURL=models.js.map

package/dist/commands/open.js

@@ -3,9 +3,9 @@ import { accessSync, constants, existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { delimiter, join, resolve, sep } from 'node:path';
 import { one, parse } from "../args.js";
+import { editorFiles } from "../meta/editor.js";
 import { project as resolveProject } from "../resolve.js";
-import { editorFiles } from "../scaffold.js";
-import { CliError, cyan, dim, EXIT, json, note, usageError } from "../term.js";
+import { CliError, cyan, dim, EXIT, isInteractive, json, note, usageError } from "../term.js";
 const USAGE = 'zen open [project] [--editor <cmd>] [--wait]';
 /**
  * A project is resolved by name or from the cwd, and the path is handed to an
@@ -247,8 +247,8 @@ function verify(editor) {
             ? 'name one with --editor, or set $ZENERA_EDITOR'
             : `${editor.from} names a command that is not on PATH`);
     }
-    if ((editor.from === '$VISUAL' || editor.from === '$EDITOR') && !process.stdin.isTTY) {
-        throw usageError(`${editor.from} names a terminal editor and there is no terminal here`, 'name a windowed one with --editor, or set $ZENERA_EDITOR');
+    if ((editor.from === '$VISUAL' || editor.from === '$EDITOR') && !isInteractive()) {
+        throw usageError(`${editor.from} names a terminal editor and there is no one at a terminal here`, 'name a windowed one with --editor, or set $ZENERA_EDITOR');
     }
 }
 async function launch(editor, dir) {

package/dist/commands/run.js

@@ -1,15 +1,18 @@
+import { usageByModel } from '@zenera/neo';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { parse } from "../args.js";
 import { concurrency, runBatch } from "../batch.js";
 import * as Engine from "../engine.js";
+import { agentEventLog } from "../eventlog.js";
 import { duration, Narrator, stopMark, summary } from "../narrate.js";
 import * as Projects from "../projects.js";
 import { readBatch, readRequest } from "../request.js";
 import { target } from "../resolve.js";
 import { display } from "../session.js";
-import { bold, cyan, dim, json, jsonText, note, readStdin, usageError, write } from "../term.js";
+import { bold, cyan, dim, drivenByAgent, json, jsonText, note, readStdin, usageError, write, } from "../term.js";
 import { parseChoice } from "../tui/theme.js";
+import { appendUsage } from "../usage.js";
 const USAGE = 'zen run [project] [prompt] [options]';
 export const run = {
     summary: 'Run the project — the TUI on a terminal, one shot otherwise.',
@@ -40,6 +43,10 @@ export const run = {
         '  --theme <dark|light>   Colours for the TUI. Default: auto.',
         '  --out <file>           Put the answer in this file instead of on screen.',
         '                         With --json, the file gets the whole JSON envelope.',
+        '  --events <file>        Append what the agent does to this file as it does it:',
+        '                         one JSON line per model call, tool call and message.',
+        '  --disposable           Remove its containers when it ends, whatever `persist:`',
+        '                         says: for a session that will never be continued.',
         '  --yes                  Answer yes to every question.',
         '  --json                 Print machine-readable JSON (session, run, mounts, output, etc...).',
         '',
@@ -121,6 +128,8 @@ export const run = {
             plain: { type: 'boolean' },
             theme: { type: 'string' },
             out: { type: 'string' },
+            events: { type: 'string' },
+            disposable: { type: 'boolean' },
             'batch-dir': { type: 'string' },
             concurrency: { type: 'string' },
         }, USAGE);
@@ -158,6 +167,9 @@ export const run = {
         // TUI, where there is someone to ask, still asks.
         const input = request ? request.input : prompt;
         const shot = Boolean(prompt) || Boolean(request);
+        if (values.events && !shot) {
+            throw usageError('--events records a one-shot run', 'give a prompt or --input');
+        }
         const where = await target({
             cwd: ctx.cwd,
             project: request?.project ?? values.project ?? (named ? head : undefined),
@@ -179,6 +191,7 @@ export const run = {
             memoryReadOnly: values['memory-read-only'],
             keys: values['no-keys'] ? false : undefined,
             yes: values.yes || ctx.json,
+            disposable: values.disposable,
         });
         try {
             // The TUI is for the case it is actually good at: a person at a
@@ -188,7 +201,8 @@ export const run = {
             const drawing = !shot &&
                 !values.plain &&
                 !ctx.json &&
-                Boolean(process.stdout.isTTY && process.stdin.isTTY);
+                Boolean(process.stdout.isTTY && process.stdin.isTTY) &&
+                !drivenByAgent();
             if (drawing) {
                 const { start } = await import("../tui/app.js");
                 await start(engine, {
@@ -222,6 +236,8 @@ const NOT_IN_A_BATCH = [
     ['workspace', 'they cannot share one; each item gets its own, or names one in the file'],
     ['plain', 'a batch never draws the TUI'],
     ['theme', 'a batch never draws the TUI'],
+    ['events', 'each item already has its own output.json'],
+    ['disposable', 'a batch removes its containers already'],
 ];
 async function batch(ctx, values, rest, piped) {
     if (rest.length > 0) {
@@ -261,11 +277,18 @@ async function once(engine, input, values, asJson, cwd, where) {
         quiet: asJson,
         live: Boolean(process.stderr.isTTY),
     });
+    const record = values.events ? agentEventLog(resolve(cwd, values.events)) : undefined;
+    const onEvent = (event) => {
+        narrator.handle(event);
+        record?.(event);
+    };
     // Ctrl-C asks the run to stop rather than killing the process, so the turn
-    // still lands on disk and the session stays resumable.
+    // still lands on disk and the session stays resumable. SIGTERM too: it is
+    // how a tuning stops a run it left behind, and its containers go with it.
     const stopping = new AbortController();
     const onInterrupt = () => stopping.abort();
     process.once('SIGINT', onInterrupt);
+    process.once('SIGTERM', onInterrupt);
     if (!asJson) {
         // Two questions were just answered, possibly without being asked. Say
         // which way they went: a run that quietly resumed the wrong session, or
@@ -278,12 +301,23 @@ async function once(engine, input, values, asJson, cwd, where) {
     }
     let outcome;
     try {
-        outcome = await Engine.run(engine, input, narrator.handle, stopping.signal);
+        outcome = await Engine.run(engine, input, onEvent, stopping.signal);
     }
     finally {
         narrator.done();
         process.off('SIGINT', onInterrupt);
+        process.off('SIGTERM', onInterrupt);
     }
+    appendUsage(where.project.dir, {
+        kind: 'run',
+        ts: new Date().toISOString(),
+        runDir: outcome.run.dir,
+        session: engine.session.id,
+        ok: true,
+        stopReason: outcome.result.stopReason,
+        durationMs: outcome.durationMs,
+        models: usageByModel(outcome.result.state.trajectory),
+    });
     if (asJson) {
         // --out is a destination, not a copy, and with --json the answer *is*
         // the envelope — so that is what lands in the file, not the prose.

package/dist/commands/sandbox.js

@@ -1,16 +1,24 @@
 import { readProjectConfig, sandboxLimits, } from '@zenera/neo';
 import { parse } from "../args.js";
 import { resolveBuild } from "../image.js";
-import { engineDisk, ensurePodmanReady, ownedContainers, podmanStatus, removeContainers, } from "../podman.js";
+import { engineDisk, ensurePodmanReady, idleContainers, ownedContainers, podmanStatus, removeContainers, sessionOwners, } from "../podman.js";
 import { current as currentProject, dirSize, isProjectDir, open as openProject, Registry, sessionIds, } from "../projects.js";
-import { ago, bold, bytes, dim, green, json, note, red, table, usageError, write, writeAll, yellow, } from "../term.js";
-const USAGE = 'zen sandbox [status|up|pull|clean|disk] [options]';
+import { layout, ResourceSampler } from "../resources.js";
+import { ago, bold, bytes, count, cyan, dim, green, json, note, red, table, usageError, write, writeAll, yellow, } from "../term.js";
+const USAGE = 'zen sandbox [status|top|up|pull|clean|disk] [options]';
+const SUBCOMMANDS = ['status', 'top', 'up', 'pull', 'clean', 'disk'];
+/** `top` refreshes this often unless told otherwise. */
+const DEFAULT_INTERVAL_S = 2;
+/** A one-shot report still needs two readings for a cpu figure. */
+const ONCE_INTERVAL_MS = 1000;
 /** Enough to see the pattern; the rest are a number. */
 const LISTED = 6;
 /** Under the labels, which is where the eye already is. */
 const INDENT = ' '.repeat(11);
 /** `agents.yaml` states memory in MiB; `bytes` prints bytes. */
 const MIB = 1024 * 1024;
+/** Below this many free locks, `status` says so: a batch can spend that in minutes. */
+const FEW_LOCKS = 256;
 // ---------------------------------------------------------------------------
 // The container engine, on its own
 //
@@ -26,6 +34,8 @@ export const sandbox = {
     banner: { head: 'Zenera', accent: 'Sandbox', subtitle: 'Container Isolation', hue: 'azure' },
     details: [
         '  status                 What is installed, running and pulled. Changes nothing.',
+        '  top                    Memory and cpu, live: this computer, the machine, each',
+        '                         container — with a note on what every figure means.',
         '  up                     Install if asked, start the machine, pull or build the image.',
         '  pull                   Just the image: pulled, or built from the project\u2019s Dockerfile.',
         '  clean                  Remove every container this CLI created.',
@@ -33,6 +43,12 @@ export const sandbox = {
         '',
         '  --project <name|dir>   Which project the image and containers belong to.',
         '  --image <ref>          Use this image instead of the project\u2019s.',
+        '  --idle                 With clean: only what no live run is using — stopped ones,',
+        '                         and running ones whose run was killed before it cleaned up.',
+        '  --once                 With top: measure once and print, no live screen. Also',
+        '                         what happens with --json or when output is not a terminal.',
+        '  --interval <seconds>   With top: how often the live screen refreshes (default 2).',
+        '  --brief                With top: the figures without the notes explaining them.',
         '',
         'Without --project this is the project you are standing in, and standing',
         'nowhere is an answer: `status` then reports the engine and every container',
@@ -45,9 +61,15 @@ export const sandbox = {
         const { values, positionals } = parse(ctx.args, {
             project: { type: 'string' },
             image: { type: 'string' },
+            stopped: { type: 'boolean' },
+            idle: { type: 'boolean' },
+            once: { type: 'boolean' },
+            interval: { type: 'string' },
+            brief: { type: 'boolean' },
+            theme: { type: 'string' },
         }, USAGE);
         const what = positionals[0] ?? 'status';
-        if (!['status', 'up', 'pull', 'clean', 'disk'].includes(what)) {
+        if (!SUBCOMMANDS.includes(what)) {
             throw usageError(`unknown subcommand: ${what}`, USAGE);
         }
         if (positionals.length > 1) {
@@ -69,8 +91,10 @@ export const sandbox = {
                     throw usageError('no project here, so there is no image to pull', 'name one with --project, or an image with --image');
                 }
                 return up(image, build, true, ctx.json, true);
+            case 'top':
+                return top(values, ctx.json);
             case 'clean':
-                return clean(ctx.json);
+                return clean(ctx.json, Boolean(values.idle || values.stopped));
             case 'disk':
                 return disk(ctx.json);
         }
@@ -116,6 +140,7 @@ async function status(project, image, asJson) {
     // a report about one project must not list another's — or the faker's,
     // which wears the same label and belongs to no project at all.
     const containers = project ? ofProject(project.dir, all) : all;
+    const idle = all.length > 0 ? idleContainers(all, await sessionOwners()) : [];
     if (asJson) {
         json({
             ...found,
@@ -124,6 +149,7 @@ async function status(project, image, asJson) {
             limits: project?.limits ?? null,
             fits: fits(found.capacity?.memory, project?.limits?.memory) ?? null,
             containers,
+            idle: idle.map((c) => c.name),
         });
         return;
     }
@@ -153,11 +179,64 @@ async function status(project, image, asJson) {
     if (build) {
         write(`${bold('dockerfile')} ${dim(build.dockerfile)}`);
     }
-    writeAll(containerLines(containers, project?.name));
+    writeAll(lockLines(found.freeLocks, idle.length));
+    writeAll(containerLines(containers, idle, project?.name, all.length));
     if (!found.installed || !found.ready) {
         note('');
         note(dim('run `zen sandbox up` to fix what can be fixed.'));
     }
+    else {
+        note('');
+        note(dim('memory and cpu, live: zen sandbox top'));
+    }
+}
+// ---------------------------------------------------------------------------
+// Memory and cpu
+//
+// A live screen when a person is watching, one report when not: the same
+// layout either way, so what a script reads is what the screen showed.
+// ---------------------------------------------------------------------------
+async function top(values, asJson) {
+    const interval = values.interval === undefined ? DEFAULT_INTERVAL_S : Number(values.interval);
+    if (!Number.isFinite(interval) || interval < 0.5 || interval > 3600) {
+        throw usageError(`--interval must be a number of seconds from 0.5 to 3600, not ${values.interval}`, USAGE);
+    }
+    const sampler = new ResourceSampler();
+    const live = !asJson && !values.once && Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY);
+    if (live) {
+        const { watch } = await import("../tui/sandbox.js");
+        await watch({
+            sampler,
+            intervalMs: interval * 1000,
+            explain: !values.brief,
+            theme: values.theme,
+        });
+        return;
+    }
+    // The first reading has nothing to compare against, so its cpu figures are
+    // lifetime averages; the second one is over a second of real time.
+    await sampler.next();
+    await new Promise((done) => setTimeout(done, ONCE_INTERVAL_MS));
+    const view = await sampler.next();
+    if (asJson) {
+        json(view);
+        return;
+    }
+    const width = process.stdout.columns || Number(process.env.COLUMNS) || 100;
+    writeAll(layout(view, { width, explain: !values.brief, sort: 'memory', wrapNotes: true }).map(ansi));
+}
+const PAINT = {
+    plain: (s) => s,
+    strong: bold,
+    heading: (s) => bold(cyan(s)),
+    dim,
+    good: green,
+    warn: yellow,
+    bad: red,
+    accent: cyan,
+};
+function ansi(line) {
+    return line.map((s) => PAINT[s.tone ?? 'plain'](s.text)).join('');
 }
 /**
  * The hungriest container this project can start. An agent may override the
@@ -225,6 +304,22 @@ function ofProject(dir, containers) {
     const sessions = new Set(sessionIds(dir));
     return containers.filter((c) => c.key !== undefined && sessions.has(c.key));
 }
+/**
+ * Every container the engine holds takes one of its locks, stopped or not, and
+ * at zero nothing can be created — for any project. Said only when it is close.
+ */
+function lockLines(free, idle) {
+    if (free === undefined || free >= FEW_LOCKS) {
+        return [];
+    }
+    const left = free === 0 ? red('none free') : yellow(`${free} free`);
+    return [
+        `${bold('locks')}      ${left} ${dim('· one per container, stopped ones included')}`,
+        ...(idle > 0
+            ? [`${INDENT}${dim(`${idle} no live run is using — zen sandbox clean --idle`)}`]
+            : []),
+    ];
+}
 /**
  * One per line rather than one long line, because there is normally more than
  * one and the interesting part — how old, and whether anything is still up —
@@ -235,21 +330,31 @@ function ofProject(dir, containers) {
  * stopped ones behind. `scope` names the project these belong to, and saying
  * so is half the answer — the other half is that there are more elsewhere.
  */
-function containerLines(containers, scope) {
+function containerLines(containers, idle, scope, total = containers.length) {
     const tail = scope
         ? `one per session in ${scope}, kept by \`persist: true\` — all of them: zen sandbox disk`
         : 'one per session, kept by `persist: true` — see: zen sandbox disk';
+    const elsewhere = total > containers.length ? ` · ${total} on the machine` : '';
     if (containers.length === 0) {
-        return [`${bold('containers')} ${dim(scope ? `none in ${scope}` : 'none')}`];
+        return [`${bold('containers')} ${dim(scope ? `none in ${scope}${elsewhere}` : 'none')}`];
     }
+    // Running, but the run that started it is gone: nothing will ever stop it.
+    const orphans = new Set(idle.filter((c) => c.state === 'running').map((c) => c.name));
     const running = containers.filter((c) => c.state === 'running').length;
-    const head = `${bold('containers')} ${containers.length} ${dim(running ? `· ${running} running` : '· none running')}`;
+    const lost = containers.filter((c) => orphans.has(c.name)).length;
+    const head = `${bold('containers')} ${containers.length} ${dim((running ? `· ${running} running` : '· none running') +
+        (lost ? `, ${lost} of them orphaned` : '') +
+        elsewhere)}`;
     const rows = containers
         .slice(0, LISTED)
         .map((c) => [
         INDENT.slice(2),
         c.name,
-        c.state === 'running' ? green('running') : dim(c.state),
+        orphans.has(c.name)
+            ? yellow('orphaned')
+            : c.state === 'running'
+                ? green('running')
+                : dim(c.state),
         dim(ago(c.createdAt)),
     ]);
     const rest = containers.length - LISTED;
@@ -258,6 +363,9 @@ function containerLines(containers, scope) {
         ...table(rows),
         ...(rest > 0 ? [`${INDENT}${dim(`+${rest} more`)}`] : []),
         `${INDENT}${dim(tail)}`,
+        ...(lost
+            ? [`${INDENT}${dim('orphaned: its run was killed — zen sandbox clean --idle')}`]
+            : []),
     ];
 }
 async function up(image, build, yes, asJson, rebuild = false) {
@@ -268,8 +376,9 @@ async function up(image, build, yes, asJson, rebuild = false) {
     }
     write(`${green('ready')}${image ? ` ${dim(image)}` : ''}`);
 }
-async function clean(asJson) {
-    const containers = await ownedContainers(undefined, undefined, { sizes: true });
+async function clean(asJson, idle) {
+    const owned = await ownedContainers(undefined, undefined, { sizes: true });
+    const containers = idle ? idleContainers(owned, await sessionOwners()) : owned;
     const names = containers.map((c) => c.name);
     const freed = containers.reduce((n, c) => n + (c.size ?? 0), 0);
     await removeContainers(names);
@@ -307,10 +416,30 @@ async function disk(asJson) {
         write('');
     }
     writeAll(projectRows(projects, loose));
-    if (usage && usage.images.reclaimable > 0) {
+    const idle = idleContainers(containers, await sessionOwners());
+    const live = containers.length - idle.length;
+    const sessions = projects.reduce((n, p) => n + p.files, 0);
+    const hints = [
+        ...(idle.length > 0
+            ? [`zen sandbox clean --idle  ${count(idle.length, 'container')} no live run is using`]
+            : []),
+        ...(live > 0
+            ? [`zen sandbox clean         also the ${live} in use, cutting off whatever runs there`]
+            : []),
+        ...(usage && usage.images.reclaimable > 0
+            ? [`podman image prune -a     ${bytes(usage.images.reclaimable)} of unused images`]
+            : []),
+        // The ON DISK column is the bulk of the report and no command above touches it.
+        ...(sessions > 0
+            ? [
+                `${bytes(sessions)} ON DISK is project directories on this host, not the engine: ` +
+                    'removing containers frees none of it',
+            ]
+            : []),
+    ];
+    if (hints.length > 0) {
         write('');
-        write(dim(`zen sandbox clean       every container above`));
-        write(dim(`podman image prune -a   ${bytes(usage.images.reclaimable)} of unused images`));
+        writeAll(hints.map((h) => dim(h)));
     }
 }
 function engineRows(usage) {
@@ -382,13 +511,16 @@ function projectRows(projects, loose) {
         // Containers whose session directory is gone, and faker's, which are
         // labelled the same way and belong to no project at all.
         const size = loose.reduce((n, c) => n + (c.size ?? 0), 0);
+        const fakers = loose.filter((c) => c.key?.startsWith('faker-')).length;
         rows.push([
             dim('(unclaimed)'),
             dim('—'),
             dim('—'),
             dim(String(loose.length)),
             dim(bytes(size)),
-            dim('no session owns these'),
+            dim(fakers === loose.length
+                ? `zen faker ${fakers === 1 ? 'server' : 'servers'}, no project`
+                : 'no session owns these'),
         ]);
     }
     const total = (pick) => projects.reduce((n, p) => n + pick(p), 0);

package/dist/commands/view.d.ts

@@ -0,0 +1,8 @@
+import type { Command } from '../command.ts';
+/** A file inside the cwd is served from the cwd, so its links up the tree still resolve. */
+export declare function placeOf(cwd: string, target: string): {
+    root: string;
+    start: string;
+};
+export declare const view: Command;
+//# sourceMappingURL=view.d.ts.map