@zenera/cli 1.1.25 → 1.1.27

package/README.md

@@ -494,6 +494,8 @@ you want to validate a project's execution environment before a run.
 
 ```sh
 zen sandbox status                    # engine, project image and active containers
+zen sandbox top                       # memory and cpu, live: this computer, the machine, each container
+zen sandbox top --once                # the same, printed once (also with --json or when piped)
 zen sandbox up                        # prepare the execution environment for this project
 zen sandbox pull                      # pull or build this project's image only
 zen sandbox status --project my-app   # inspect a named project from anywhere
@@ -507,6 +509,13 @@ zen sandbox clean --idle              # only what no live run is using
 `disk` are machine-wide operations, so use them when you mean to inspect or
 remove resources beyond the current project.
 
+`top` is machine-wide too. Next to every figure it says in a few words what the
+figure means; `--brief` leaves those notes out, `--interval <seconds>` sets how
+often the live screen refreshes. On macOS it answers the usual question - why
+Activity Monitor shows "Virtual Machine Service for vfkit" holding many
+gigabytes - by setting what macOS counts for the machine against what is in use
+inside it, and naming the command that gives the difference back.
+
 ## Sharing a project
 
 A project is a directory, so sending one somewhere else is a zip - except that
@@ -554,6 +563,7 @@ The commands to run next are printed for you to read and type.
 | `run`     | Runs the project - the TUI on a terminal, a single answer otherwise. |
 | `meta`    | Runs the meta agent over the project - the one that edits it.        |
 | `inspect` | Opens or rebuilds a run's `report.html`.                             |
+| `view`    | Shows a folder in the browser, redrawn live as its files change.     |
 | `memory`  | What the agents remember - size, listing, one node, or a whole page. |
 | `check`   | Validates the project and every file it names, and asks the models.  |
 | `export`  | Writes the project to a shareable zip archive.                       |
@@ -734,6 +744,7 @@ See the `zen-dataset` skill a project carries in `.github/skills/`.
 zen meta finetune start -N 4                 # 4 cases at a time; resumes if stopped
 zen meta finetune                            # where it stands
 zen meta finetune stop                       # finish the steps in flight, then stop
+zen meta finetune serve                      # the pages live in a browser, while it is stopped
 zen meta finetune session plan-day           # resume that case's analyze session
 ```
 
@@ -743,7 +754,8 @@ applied in batches between runs, and every apply is a new, diffable version of
 the prose. Follow it in `finetune/STATUS.md`, whose summary shows whether the
 fixes and the memory are making runs cheaper; each case has its own
 `finetune/cases/<id>/FEEDBACK.md` with its latest analysis and the metrics of
-every try.
+every try. `start` prints a local address that shows those pages in a browser,
+with their diagrams drawn, updated in place as the tuning writes them.
 
 ## Credentials
 

package/dist/catalog.d.ts

@@ -103,6 +103,26 @@ export interface CatalogOptions {
  * model list to four rows.
  */
 export declare function loadCatalog(provider: Provider, opts?: CatalogOptions): Promise<Catalog>;
+/** A per-token USD price as dollars per million tokens, the unit price lists use. */
+export declare function perMillion(price: string | undefined): string;
+/** What an OpenRouter account has left to spend, as far as its key may see. */
+export interface Balance {
+    /** credits bought minus credits used; absent when the key may not read the account */
+    credits?: number;
+    /** the key's own spending cap, when one is set */
+    cap?: {
+        limit: number;
+        remaining: number;
+        reset?: string;
+    };
+    /** requests to `:free` models left today */
+    free?: {
+        used: number;
+        limit: number;
+        remaining: number;
+    };
+}
+export declare function routerBalance(): Promise<Balance>;
 /** Every provider asked at once — they are independent and mostly latency. */
 export declare function loadCatalogs(providers: readonly Provider[], opts?: CatalogOptions): Promise<Catalog[]>;
 export interface Filters {

package/dist/catalog.js

@@ -477,6 +477,66 @@ export async function loadCatalog(provider, opts = {}) {
         fetchedAt: new Date(0).toISOString(),
     };
 }
+// ---------------------------------------------------------------------------
+// Prices and balance
+// ---------------------------------------------------------------------------
+/** A per-token USD price as dollars per million tokens, the unit price lists use. */
+export function perMillion(price) {
+    if (price === undefined || price === '') {
+        return '';
+    }
+    const n = Number(price) * 1_000_000;
+    if (!Number.isFinite(n)) {
+        return '';
+    }
+    // OpenRouter prices its routers (`openrouter/auto`) as "-1": it depends on the pick.
+    if (n < 0) {
+        return 'varies';
+    }
+    if (n === 0) {
+        return 'free';
+    }
+    if (n >= 1) {
+        return `$${n.toFixed(2)}`;
+    }
+    // Two significant digits for fractions of a dollar, but never fewer than cents.
+    const short = String(Number(n.toPrecision(2)));
+    return `$${(short.split('.')[1]?.length ?? 0) < 2 ? n.toFixed(2) : short}`;
+}
+export async function routerBalance() {
+    const base = (process.env.OPENROUTER_BASE_URL ?? 'https://openrouter.ai/api/v1').replace(/\/+$/, '');
+    const get = async (path) => {
+        const res = await fetch(`${base}${path}`, {
+            headers: { Authorization: `Bearer ${process.env.OPENROUTER_API_KEY ?? ''}` },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok) {
+            throw Object.assign(new Error(`${path} answered ${res.status}`), {
+                status: res.status,
+            });
+        }
+        return (await res.json()).data;
+    };
+    // Raw rather than the SDK: its schema drops `free_model_daily_requests`.
+    const [key, credits] = await Promise.all([
+        get('/key'),
+        // Documented as management-key only, though ordinary keys are answered too.
+        get('/credits').catch(() => undefined),
+    ]);
+    return {
+        ...(credits ? { credits: credits.total_credits - credits.total_usage } : {}),
+        ...(key.limit !== null && key.limit_remaining !== null
+            ? {
+                cap: {
+                    limit: key.limit,
+                    remaining: key.limit_remaining,
+                    ...(key.limit_reset ? { reset: key.limit_reset } : {}),
+                },
+            }
+            : {}),
+        ...(key.free_model_daily_requests ? { free: key.free_model_daily_requests } : {}),
+    };
+}
 /** Every provider asked at once — they are independent and mostly latency. */
 export async function loadCatalogs(providers, opts = {}) {
     return Promise.all(providers.map((p) => loadCatalog(p, opts)));

package/dist/commands/index.js

@@ -13,6 +13,7 @@ import { open } from "./open.js";
 import { run } from "./run.js";
 import { sandbox } from "./sandbox.js";
 import { version } from "./version.js";
+import { view } from "./view.js";
 /**
  * Insertion order is the order help prints in, and it is deliberate: the four
  * a new user needs first, then the credentials-and-models pair, then the two
@@ -32,6 +33,7 @@ export const COMMANDS = {
     models,
     check,
     inspect,
+    view,
     export: pack,
     import: unpack,
     memory,

package/dist/commands/inspect.d.ts

@@ -11,15 +11,19 @@ interface Flags {
     part?: string[];
     'question-file'?: string;
     full?: boolean;
+    raw?: boolean;
     open?: boolean;
     rebuild?: boolean;
     'no-timing'?: boolean;
     'no-style'?: boolean;
 }
 export declare const inspect: Command;
+/** The `--part` names that match no part of any of these nodes. */
+export declare function missingParts(found: readonly NodeDetail[], want: readonly string[]): string[];
 /**
  * Which parts print in full: everything `--part` names, or everything but
- * `request`. A prefix matches, so `--part call` catches `call run_command (…)`.
+ * the bulky ones. A prefix matches, so `--part call` catches `call run_command (…)`.
+ * A name that matches nothing is an error only when no name matches at all.
  */
 export declare function wholeParts(found: readonly NodeDetail[], values: {
     part?: string[];

package/dist/commands/inspect.js

@@ -1,8 +1,9 @@
-import { assertState, buildRunReport, FilePayloadStore, memoryDir, MemoryStore, PayloadResolver, projectRegistry, readProjectConfig, renderReportHtml, text, } from '@zenera/neo';
+import { assertState, buildRunReport, FilePayloadStore, memoryDir, MemoryStore, PayloadResolver, projectRegistry, readProjectConfig, renderReportHtml, SANDBOX_MOUNT, text, } from '@zenera/neo';
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { parse } from "../args.js";
 import { buildDiagnostic, parseRecordedRequest, pickModel } from "../ask.js";
 import { loadProjectEnv } from "../env.js";
@@ -59,6 +60,7 @@ export const inspect = {
         '  --question-file <path> Read the `ask` question from a file; `-` is stdin.',
         '  --part <name>          Print this part of a node in full. Repeatable.',
         '  --full                 Print every part, the recorded `request` included.',
+        '  --raw                  With one node and one --part: that part alone, unframed.',
         '  --rebuild              Build report.html again from the run state.',
         '  --open                 Open the report in a browser.',
         '  --no-timing            Leave the clock off the graph.',
@@ -84,6 +86,14 @@ export const inspect = {
         '',
         '  zen inspect node n11 --part thinking --part text --dir <run dir>',
         '',
+        'An `llm_call` also carries two parts read out of its request, printed',
+        'only when named: `tools`, the tool names that call was offered, and',
+        '`messages`, the conversation it saw, one clipped line per message.',
+        '`--raw` prints one part with nothing around it, for a pipe:',
+        '',
+        '  zen inspect node n11 --part tools --dir <run dir>',
+        "  zen inspect node n11 --part request --raw --dir <run dir> | jq '.messages'",
+        '',
         '`ask` replays one `llm_call` — its system prompt, its messages, its tool',
         'schemas — to a model, with your question on the end and tool calling off.',
         'It is told the run is over and that it may quote its own instructions, so',
@@ -122,6 +132,7 @@ export const inspect = {
             part: { type: 'string', multiple: true },
             'question-file': { type: 'string' },
             full: { type: 'boolean' },
+            raw: { type: 'boolean' },
             open: { type: 'boolean' },
             rebuild: { type: 'boolean' },
             'no-timing': { type: 'boolean' },
@@ -238,18 +249,42 @@ async function nodes(at, values, ids, asJson) {
         return;
     }
     const whole = wholeParts(found, values);
-    writeAll(preamble(run.id, found, whole, trace.entries.length));
+    if (values.raw) {
+        const [node] = found;
+        const hits = node?.parts.filter((p) => whole(p.name)) ?? [];
+        if (found.length !== 1 || values.part?.length !== 1 || hits.length !== 1) {
+            throw usageError('--raw prints one part of one node', hits.length > 1
+                ? `name one: ${hits.map((p) => `--part ${flag(p.name)}`).join(', ')}`
+                : 'zen inspect node n11 --part request --raw --dir <run dir>');
+        }
+        const { text } = hits[0];
+        process.stdout.write(text.endsWith('\n') ? text : `${text}\n`);
+        return;
+    }
+    writeAll([
+        ...preamble(run.id, found, whole, trace.entries.length),
+        ...missingParts(found, values.part ?? []).map((name) => `# no part starts with "${name}" in these nodes`),
+    ]);
     for (const node of found) {
         write(renderNode(node, whole));
     }
-    note(dim(`the rest of the run: ${cyan(`zen inspect graph --dir ${run.dir}`)}`));
-    note(dim(`why it did this: ${cyan(`zen inspect ask ${found[0]?.id ?? 'n1'} "…" --dir ${run.dir}`)}`));
+    // A model reading this already has the commands; only a person needs reminding.
+    if (process.stderr.isTTY) {
+        note(dim(`the rest of the run: ${cyan(`zen inspect graph --dir ${run.dir}`)}`));
+        note(dim(`why it did this: ${cyan(`zen inspect ask ${found[0]?.id ?? 'n1'} "…" --dir ${run.dir}`)}`));
+    }
+}
+/** Parts `node` names with their size instead of printing, unless asked for. */
+const BULKY = new Set(['request', 'messages', 'tools']);
+/** The `--part` names that match no part of any of these nodes. */
+export function missingParts(found, want) {
+    const names = found.flatMap((n) => n.parts.map((p) => p.name));
+    return want.filter((asked) => !names.some((name) => name.startsWith(asked)));
 }
-/** The part `--part` leaves out unless it is asked for by name. */
-const BULKY = 'request';
 /**
  * Which parts print in full: everything `--part` names, or everything but
- * `request`. A prefix matches, so `--part call` catches `call run_command (…)`.
+ * the bulky ones. A prefix matches, so `--part call` catches `call run_command (…)`.
+ * A name that matches nothing is an error only when no name matches at all.
  */
 export function wholeParts(found, values) {
     if (values.full) {
@@ -257,13 +292,12 @@ export function wholeParts(found, values) {
     }
     const want = values.part ?? [];
     if (!want.length) {
-        return (name) => name !== BULKY;
+        return (name) => !BULKY.has(name);
     }
-    const names = [...new Set(found.flatMap((n) => n.parts.map((p) => p.name)))];
-    for (const asked of want) {
-        if (!names.some((name) => name.startsWith(asked))) {
-            throw usageError(`no part starts with "${asked}" in ${found.length === 1 ? found[0]?.id : 'these nodes'}`, names.length ? `they carry: ${names.join(', ')}` : 'they carry no payloads');
-        }
+    const missing = missingParts(found, want);
+    if (missing.length === want.length) {
+        const names = [...new Set(found.flatMap((n) => n.parts.map((p) => p.name)))];
+        throw usageError(`no part starts with "${want[0]}" in ${found.length === 1 ? found[0]?.id : 'these nodes'}`, names.length ? `they carry: ${names.join(', ')}` : 'they carry no payloads');
     }
     return (name) => want.some((asked) => name.startsWith(asked));
 }
@@ -618,7 +652,13 @@ async function pickRun(session, asked, asking) {
 async function rebuild(session, run, store) {
     const state = await readState(run);
     const payloads = new PayloadResolver(new FilePayloadStore({ dir: session.blobs, id: 'file' }));
-    const report = await buildRunReport(state, payloads, { title: run.id, memory: store });
+    const { workspace } = await readRunMeta(run);
+    const report = await buildRunReport(state, payloads, {
+        title: run.id,
+        memory: store,
+        // The run never recorded a `workdir:`, so the default name is the guess.
+        mounts: workspace ? [{ at: SANDBOX_MOUNT, href: pathToFileURL(workspace).href }] : [],
+    });
     await writeFile(run.report, renderReportHtml(report), 'utf8');
 }
 /**

package/dist/commands/memory.js

@@ -1,6 +1,6 @@
 import { ALL_AGENTS, buildMemoryReport, createEmbedder, diffMemories, GREP_FIELDS, grepMemory, hostPath, memoryDir, MemoryError, MemoryIndex, MemoryStore, MergeConflicts, mergeMemories, readProjectConfig, renderMemoryHtml, renderRecollection, } from '@zenera/neo';
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { basename, isAbsolute, join, resolve } from 'node:path';
 import { parse } from "../args.js";
@@ -49,6 +49,7 @@ export const memory = {
         '',
         '  --project <name|dir>   Which project. Defaults to the one you are in.',
         '  --dir <dir>            Read this memory directory instead of the project’s.',
+        '                         Run from inside a memory directory, that one is the default.',
         '  --kind <name>          Only this kind of node.',
         '  --audience <name>      Only nodes committed under this label.',
         '  --files                Only nodes that remember a file.',
@@ -198,6 +199,11 @@ export const memory = {
  */
 async function open(cwd, want, at, opts = {}) {
     const { create = false, lock = true } = opts;
+    // Standing inside a memory (a merged or batch copy) means that memory, not
+    // the project's own one a few directories up.
+    if (!at && !want && isMemoryDir(cwd)) {
+        at = cwd;
+    }
     if (at) {
         const dir = resolve(cwd, at);
         if (!create && !existsSync(join(dir, 'manifest.json'))) {
@@ -221,6 +227,19 @@ async function open(cwd, want, at, opts = {}) {
         at: { root: project.dir, config },
     };
 }
+/** A rag index also has a manifest and a graph.json; only a memory's manifest counts nodes and edges. */
+function isMemoryDir(dir) {
+    if (!existsSync(join(dir, 'graph.json'))) {
+        return false;
+    }
+    try {
+        const m = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8'));
+        return typeof m?.nodes === 'number' && typeof m?.edges === 'number';
+    }
+    catch {
+        return false;
+    }
+}
 // ---------------------------------------------------------------------------
 // stats
 // ---------------------------------------------------------------------------
@@ -753,10 +772,16 @@ async function write_(o, rest, flags, cwd, asJson) {
     const report = { ...built, nodes: built.nodes.map((n) => onHost(o, n)) };
     await writeFile(target, renderMemoryHtml(report), 'utf8');
     if (asJson) {
-        json({ path: target, nodes: report.nodes.length, edges: report.edges.length });
+        json({
+            path: target,
+            from: o.dir,
+            nodes: report.nodes.length,
+            edges: report.edges.length,
+        });
     }
     else {
-        note(`${green('wrote')} ${target} ${dim(`· ${count(report.nodes.length, 'node')}, ${count(report.edges.length, 'edge')}`)}`);
+        note(`${green('wrote')} ${target} ${dim(`· ${count(report.nodes.length, 'node')}, ${count(report.edges.length, 'edge')}` +
+            ` · from ${o.dir}`)}`);
     }
     if (flags.open) {
         reveal(target);

package/dist/commands/meta.js

@@ -1,7 +1,7 @@
 import { readProjectConfig } from '@zenera/neo';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { parse } from "../args.js";
@@ -83,6 +83,7 @@ export const meta = {
         '  --project <name|dir>   Which project to work in. The agent is rooted there.',
         '  --model <ref>          Model for this run, e.g. vertex/gemini-3.8-flash.',
         '  --provider <name>      Force the key to use. Default: the model ref says.',
+        '  --prompt-file <file>   Append this file to the prompt, after any words.',
         '  --agent <name>         A .github/agents/<name>.agent.md.',
         '  --effort <level>       none, minimal, low, medium, high, xhigh or max.',
         '  --allow-tool <list>    Only these: read, shell(git:*), write(README.md).',
@@ -164,6 +165,7 @@ export const meta = {
             provider: { type: 'string' },
             model: { type: 'string' },
             prompt: { type: 'string', short: 'p' },
+            'prompt-file': { type: 'string' },
             agent: { type: 'string' },
             effort: { type: 'string' },
             share: { type: 'string' },
@@ -243,7 +245,9 @@ async function where(ctx, flag, positionals) {
 function refresh(project) {
     try {
         const written = editorFiles(project.dir);
-        note(dim(`refreshed ${written.length} editor files in ${project.name}`));
+        if (written.length) {
+            note(dim(`refreshed ${written.length} editor files in ${project.name}`));
+        }
     }
     catch (err) {
         warn(`could not refresh the editor files — ${err.message}`);
@@ -282,7 +286,7 @@ async function stored(ctx, values, args) {
     if (name) {
         return await runPrompt(ctx, values, project, name, rest);
     }
-    const question = (values.prompt ?? rest.join(' ')).trim() || (await readStdin());
+    const question = withFile(values, (values.prompt ?? rest.join(' ')).trim()) || (await readStdin());
     if (question) {
         return await go(ctx, values, project, question);
     }
@@ -294,9 +298,24 @@ async function runPrompt(ctx, values, project, name, extra) {
     if (found.description) {
         note(dim(found.description));
     }
-    const prompt = extra.length > 0 ? `${found.body}\n\n${extra.join(' ')}` : found.body;
+    const prompt = withFile(values, extra.length > 0 ? `${found.body}\n\n${extra.join(' ')}` : found.body);
     await go(ctx, values, project, prompt, name.replace(/^\//, ''));
 }
+/** The prompt with `--prompt-file` after it: text too long, or too awkward to quote, for a word. */
+function withFile(values, prompt) {
+    const file = values['prompt-file'];
+    if (!file) {
+        return prompt;
+    }
+    let text;
+    try {
+        text = readFileSync(resolve(file), 'utf8').trim();
+    }
+    catch {
+        throw usageError(`no prompt file at ${file}`, 'name a file that exists');
+    }
+    return [prompt, text].filter(Boolean).join('\n\n');
+}
 async function pickPrompt(ctx, project) {
     const names = await listPrompts(project.dir);
     if (names.length === 0) {
@@ -348,7 +367,7 @@ async function resumeRun(ctx, values, args) {
     if (!values['no-refresh']) {
         refresh(project);
     }
-    const message = (values.prompt ?? words.join(' ')).trim() || RESUME_PROMPT;
+    const message = withFile(values, (values.prompt ?? words.join(' ')).trim()) || RESUME_PROMPT;
     await go(ctx, { ...values, resume: session, continue: false }, project, message);
 }
 // ---------------------------------------------------------------------------

package/dist/commands/models.js

@@ -13,7 +13,7 @@
 // ---------------------------------------------------------------------------
 import { createEmbedder, ModelRegistry } from '@zenera/neo';
 import { parse } from "../args.js";
-import { byGroup, groupOf, isPartner, 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 { probeChat, probeModel } from "../liveness.js";
@@ -589,6 +589,7 @@ const browse = async (ctx, args) => {
         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'

package/dist/commands/sandbox.js

@@ -3,8 +3,14 @@ import { parse } from "../args.js";
 import { resolveBuild } from "../image.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, count, 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. */
@@ -28,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.',
@@ -37,6 +45,10 @@ export const sandbox = {
         '  --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',
@@ -51,9 +63,13 @@ export const sandbox = {
             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) {
@@ -75,6 +91,8 @@ 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, Boolean(values.idle || values.stopped));
             case 'disk':
@@ -167,6 +185,58 @@ async function status(project, image, asJson) {
         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

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