@zenera/cli 1.1.10 → 1.1.12

package/dist/commands/run.js

@@ -104,13 +104,14 @@ export const run = {
                 await start(engine, {
                     readOnly: Boolean(values['read-only']),
                     theme: values.theme,
+                    started: { created: where.created, freshWorkspace: where.freshWorkspace },
                 });
                 return;
             }
             if (!prompt) {
                 throw usageError('nothing to ask', 'give a prompt, or pipe one in');
             }
-            await once(engine, prompt, values, ctx.json, ctx.cwd);
+            await once(engine, prompt, values, ctx.json, ctx.cwd, where);
         }
         finally {
             await engine.close();
@@ -120,7 +121,7 @@ export const run = {
 // ---------------------------------------------------------------------------
 // One shot
 // ---------------------------------------------------------------------------
-async function once(engine, prompt, values, asJson, cwd) {
+async function once(engine, prompt, values, asJson, cwd, where) {
     const narrator = new Narrator({
         quiet: Boolean(values.quiet) || asJson,
         live: Boolean(process.stderr.isTTY),
@@ -131,7 +132,14 @@ async function once(engine, prompt, values, asJson, cwd) {
     const onInterrupt = () => stopping.abort();
     process.once('SIGINT', onInterrupt);
     if (!values.quiet && !asJson) {
-        note(`${bold(engine.name)} ${dim(engine.session.id)} ` + dim(display(engine.workspace, cwd)));
+        // Two questions were just answered, possibly without being asked. Say
+        // which way they went: a run that quietly resumed the wrong session, or
+        // wrote into the directory you were standing in, is only explainable
+        // afterwards, and this is the one line where it is cheap to say.
+        note(`${bold(engine.name)} ${dim(where.created ? 'new session' : 'continuing')} ` +
+            `${dim(engine.session.id)}`);
+        note(dim(`${where.freshWorkspace ? 'new directory' : 'workspace'} ` +
+            `${display(engine.workspace, cwd)}`));
     }
     let outcome;
     try {

package/dist/commands/sandbox.js

@@ -2,8 +2,7 @@ import { readProjectConfig } from '@zenera/neo';
 import { parse } from "../args.js";
 import { resolveBuild } from "../image.js";
 import { engineDisk, ensurePodmanReady, ownedContainers, podmanStatus, removeContainers, } from "../podman.js";
-import { dirSize, isProjectDir, Registry, sessionIds } from "../projects.js";
-import { project as findProject } from "../resolve.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]';
 /** Enough to see the pattern; the rest are a number. */
@@ -29,9 +28,13 @@ export const sandbox = {
         '  clean                  Remove every container this CLI created.',
         '  disk                   What the engine and every known project occupy.',
         '',
-        '  --project <name|dir>   Which project the image comes from.',
+        '  --project <name|dir>   Which project the image and containers belong to.',
         '  --image <ref>          Use this image instead of the project\u2019s.',
         '',
+        'Without --project this is the project you are standing in, and standing',
+        'nowhere is an answer: `status` then reports the engine and every container',
+        'on the machine, since that is all there is to say.',
+        '',
         'None of this is required. A run does all of it on its own, the first',
         'time an agent that can reach a shell is about to start one.',
     ],
@@ -47,18 +50,21 @@ export const sandbox = {
         if (positionals.length > 1) {
             throw usageError('one subcommand at a time', USAGE);
         }
-        // `clean` and `disk` are machine-wide questions, so asking which
-        // project they mean would be asking something they do not use.
+        // `clean` and `disk` are machine-wide questions, so looking for a
+        // project they do not use would be reading something for nothing.
         const scoped = what === 'status' || what === 'up' || what === 'pull';
-        const found = values.image || !scoped ? undefined : await projectSandbox(ctx.cwd, values);
+        const found = scoped ? await projectSandbox(ctx.cwd, values) : undefined;
         const image = values.image ?? found?.image;
-        const build = found?.build;
+        const build = values.image ? undefined : found?.build;
         switch (what) {
             case 'status':
-                return status(image, build, ctx.json);
+                return status(found, image, ctx.json);
             case 'up':
                 return up(image, build, ctx.json, ctx.json);
             case 'pull':
+                if (!image) {
+                    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 'clean':
                 return clean(ctx.json);
@@ -68,27 +74,51 @@ export const sandbox = {
     },
 };
 /**
- * The project's image, when there is a project to ask. `zen sandbox status`
- * run from anywhere at all is still a useful thing, so failing to find one is
- * not a failure — it just means there is no image to report on. Notably this
- * does *not* go through `target`: reading a setting must not create a session.
+ * Which project this is about: the flag, or the directory the command was run
+ * in. It deliberately never asks. `zen sandbox status` run from anywhere at
+ * all is a useful thing, so standing outside every project is an answer — the
+ * engine is still there to report on — and a question with a list of every
+ * project on the machine is not one a *reading* has any business asking.
+ *
+ * Notably it also does not go through `target`: reading a setting must not
+ * create a session.
  */
 async function projectSandbox(cwd, values) {
+    const found = values.project ? await openProject(values.project) : await currentProject(cwd);
+    if (!found) {
+        return undefined;
+    }
     try {
-        const found = await findProject({ cwd, project: values.project, yes: true });
         const { root, config } = readProjectConfig(found.dir);
         const build = resolveBuild(root, config.sandbox);
-        return { image: build?.tag ?? config.sandbox?.image, build };
+        return {
+            dir: found.dir,
+            name: found.name,
+            image: build?.tag ?? config.sandbox?.image,
+            build,
+        };
     }
     catch {
-        return undefined;
+        // A project whose configuration does not read is `zen check`'s to
+        // report; here it only means there is no image to name.
+        return { dir: found.dir, name: found.name };
     }
 }
-async function status(image, build, asJson) {
+async function status(project, image, asJson) {
+    const build = project?.build;
     const found = await podmanStatus({ image });
-    const containers = found.ready ? await ownedContainers(found.engine) : [];
+    const all = found.ready ? await ownedContainers(found.engine) : [];
+    // A container belongs to a session, and a session belongs to a project, so
+    // 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;
     if (asJson) {
-        json({ ...found, dockerfile: build?.dockerfile ?? null, containers });
+        json({
+            ...found,
+            project: project?.name ?? null,
+            dockerfile: build?.dockerfile ?? null,
+            containers,
+        });
         return;
     }
     const mark = (ok) => (ok ? green('ok') : red('no'));
@@ -98,18 +128,31 @@ async function status(image, build, asJson) {
         write(`${bold('machine')}    ${found.machine.name} ${state}`);
     }
     write(`${bold('responds')}   ${mark(found.ready)}`);
+    if (project) {
+        write(`${bold('project')}    ${project.name} ${dim(project.dir)}`);
+    }
     if (found.image) {
         write(`${bold('image')}      ${found.image} ${mark(Boolean(found.imagePresent))}`);
     }
     if (build) {
         write(`${bold('dockerfile')} ${dim(build.dockerfile)}`);
     }
-    writeAll(containerLines(containers));
+    writeAll(containerLines(containers, project?.name));
     if (!found.installed || !found.ready) {
         note('');
         note(dim('run `zen sandbox up` to fix what can be fixed.'));
     }
 }
+/**
+ * The containers this project's sessions made. A container carries the session
+ * id that made it in a label, and a session id is a directory name under the
+ * project — the same attribution `disk` does for every project at once, so the
+ * two cannot disagree.
+ */
+function ofProject(dir, containers) {
+    const sessions = new Set(sessionIds(dir));
+    return containers.filter((c) => c.key !== undefined && sessions.has(c.key));
+}
 /**
  * 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 —
@@ -117,11 +160,15 @@ async function status(image, build, asJson) {
  *
  * The trailing note is there because the count surprises people: a container
  * is per *session*, not per project, and `persist: true` is what leaves the
- * stopped ones behind.
+ * 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) {
+function containerLines(containers, scope) {
+    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';
     if (containers.length === 0) {
-        return [`${bold('containers')} ${dim('none')}`];
+        return [`${bold('containers')} ${dim(scope ? `none in ${scope}` : 'none')}`];
     }
     const running = containers.filter((c) => c.state === 'running').length;
     const head = `${bold('containers')} ${containers.length} ${dim(running ? `· ${running} running` : '· none running')}`;
@@ -138,7 +185,7 @@ function containerLines(containers) {
         head,
         ...table(rows),
         ...(rest > 0 ? [`${INDENT}${dim(`+${rest} more`)}`] : []),
-        `${INDENT}${dim('one per session, kept by `persist: true` — see: zen sandbox disk')}`,
+        `${INDENT}${dim(tail)}`,
     ];
 }
 async function up(image, build, yes, asJson, rebuild = false) {

package/dist/engine.js

@@ -1,4 +1,4 @@
-import { AgentRunner, FileMemoryStore, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, assertState, buildRunReport, exaTools, lastText, loadProject, readProjectConfig, renderReportHtml, sandboxTools, turns, workspaceTools, } from '@zenera/neo';
+import { AgentRunner, FilePayloadStore, SANDBOX_MOUNT, SKILLS_MOUNT, Workspace, assertState, buildRunReport, exaTools, lastText, loadProject, readProjectConfig, renderReportHtml, sandboxTools, turns, workspaceTools, } from '@zenera/neo';
 import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
@@ -27,7 +27,6 @@ export async function open(opts) {
     const meta = await readSessionMeta(opts.session);
     const workspace = resolve(meta.workspace);
     const payloads = new FilePayloadStore({ dir: opts.session.blobs, id: 'file' });
-    const memory = [new FileMemoryStore({ dir: opts.session.memory, id: 'file' })];
     // The config is read before the project is loaded because the sandbox is
     // configured by it and the tools have to exist before selectors can be
     // resolved against them. They are always registered, whether or not anyone
@@ -35,6 +34,7 @@ export async function open(opts) {
     // fails to load with "unknown tool", which would be a lie.
     let sandbox;
     let project;
+    let files;
     try {
         const { root, config } = readProjectConfig(opts.project.dir);
         // Assets and the skill catalog are mounted for both, under one name.
@@ -49,17 +49,21 @@ export async function open(opts) {
             keys: opts.keys,
             mounts,
         });
+        const workspaceOptions = {
+            root: workspace,
+            readOnly: opts.readOnly,
+            mount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
+            mounts,
+        };
+        // The same view the file tools have, so a path the agent just wrote
+        // resolves the same way when it asks memory to keep a copy.
+        files = new Workspace(workspaceOptions);
         project = await loadProject(opts.project.dir, {
             tools: [
                 // Both groups are pointed at one directory, so both are told the
                 // one name for it: whatever `run_command` prints a path as,
                 // `read_file` accepts.
-                ...workspaceTools({
-                    root: workspace,
-                    readOnly: opts.readOnly,
-                    mount: sandbox.spec.workdir ?? SANDBOX_MOUNT,
-                    mounts,
-                }),
+                ...workspaceTools(workspaceOptions),
                 ...sandboxTools(sandbox.pool),
                 // Registered whether or not a key exists: the credential is
                 // read when a tool is called, so a project that names `exa:*`
@@ -69,7 +73,7 @@ export async function open(opts) {
             ],
             skillsAt: SKILLS_MOUNT,
             payloads,
-            memory,
+            resolveFile: (path) => files.within(path),
         });
     }
     catch (err) {
@@ -105,6 +109,7 @@ export async function open(opts) {
         lock,
         close: async () => {
             await teardown(sandbox.pool);
+            project.close();
             lock.release();
         },
     };

package/dist/home.d.ts

@@ -5,8 +5,8 @@ export declare const paths: {
     keys: () => string;
     keyDir: () => string;
     faker: () => string;
-    /** cached model listings, one file per provider — public data, not secrets */
-    catalog: () => string;
+    /** work already done and worth keeping: vectors, parses, model listings */
+    cache: () => string;
 };
 /** Creates a directory owner-only, and leaves an existing one's mode alone. */
 export declare function ensureDir(dir: string, mode?: number): string;

package/dist/home.js

@@ -26,8 +26,8 @@ export const paths = {
     keys: () => join(home(), 'keys.json'),
     keyDir: () => join(home(), 'keys'),
     faker: () => join(home(), 'faker'),
-    /** cached model listings, one file per provider — public data, not secrets */
-    catalog: () => join(home(), 'catalog'),
+    /** work already done and worth keeping: vectors, parses, model listings */
+    cache: () => join(home(), 'cache'),
 };
 /** Creates a directory owner-only, and leaves an existing one's mode alone. */
 export function ensureDir(dir, mode = DIR_MODE) {

package/dist/keys.d.ts

@@ -103,6 +103,17 @@ export declare function parseRef(ref: string): {
     provider: KeyOwner;
     name?: string;
 };
+/** Which of a provider's forms a raw value is, decided by the value itself. */
+export declare function formOf(provider: KeyOwner, raw: string): CredentialForm;
+/**
+ * Throws on a name that is neither an endpoint nor shaped like a region — `usa`,
+ * or `us-central` with its digit missing — because those are 404s at the first
+ * call, a long way from the command that caused them. Returns false for a
+ * well-formed name that is merely unrecognised, which the caller reports and
+ * stores anyway: Google adds regions, and a list compiled here would be wrong
+ * before it was old.
+ */
+export declare function checkRegion(region: string): boolean;
 /** What a credential cannot say about itself. */
 export interface KeyMeta {
     /** GCP project id, for a Vertex service account */
@@ -144,6 +155,17 @@ export declare class KeyStore {
     fileOf(entry: KeyEntry): string;
     /** The plaintext an entry stands for — the only way out of the store. */
     reveal(entry: KeyEntry): string;
+    /**
+     * Which GCP project a Vertex entry addresses, and how that was decided —
+     * the same order the library resolves it in, so what is shown is what will
+     * be called. A service-account file states its own project, and nothing was
+     * ever stored for it, so an entry with no `project` is not an entry with no
+     * project: it is one whose project is only knowable by reading the file.
+     */
+    projectOf(entry: KeyEntry): {
+        id: string;
+        from: 'env' | 'stored' | 'file';
+    } | undefined;
     /**
      * What the library would see. Real environment variables win, so CI,
      * `docker run -e` and a one-off `OPENAI_API_KEY=… zen run` all behave

package/dist/keys.js

@@ -1,5 +1,5 @@
 import { EXA_API_KEY_ENV } from '@zenera/neo';
-import { chmodSync, copyFileSync, existsSync, statSync } from 'node:fs';
+import { chmodSync, copyFileSync, existsSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { assertPrivate, ensureDir, paths, readJson, writeJson } from "./home.js";
@@ -169,7 +169,7 @@ export function parseRef(ref) {
     return { provider, name };
 }
 /** Which of a provider's forms a raw value is, decided by the value itself. */
-function formOf(provider, raw) {
+export function formOf(provider, raw) {
     const { forms } = SHAPES[provider];
     if (forms.length === 1) {
         return forms[0];
@@ -177,6 +177,71 @@ function formOf(provider, raw) {
     const wanted = raw.length < 4096 && existsSync(resolve(raw)) ? 'file' : 'secret';
     return forms.find((f) => f.holds === wanted) ?? forms[0];
 }
+const REGION = /^[a-z]+-[a-z]+[0-9]+$/;
+const REGIONS = new Set([
+    'africa-south1',
+    'asia-east1',
+    'asia-east2',
+    'asia-northeast1',
+    'asia-northeast2',
+    'asia-northeast3',
+    'asia-south1',
+    'asia-south2',
+    'asia-southeast1',
+    'asia-southeast2',
+    'asia-southeast3',
+    'australia-southeast1',
+    'australia-southeast2',
+    'europe-central2',
+    'europe-north1',
+    'europe-southwest1',
+    'europe-west1',
+    'europe-west2',
+    'europe-west3',
+    'europe-west4',
+    'europe-west6',
+    'europe-west8',
+    'europe-west9',
+    'europe-west10',
+    'europe-west12',
+    'me-central1',
+    'me-central2',
+    'me-west1',
+    'northamerica-northeast1',
+    'northamerica-northeast2',
+    'northamerica-south1',
+    'southamerica-east1',
+    'southamerica-west1',
+    'us-central1',
+    'us-east1',
+    'us-east4',
+    'us-east5',
+    'us-south1',
+    'us-west1',
+    'us-west2',
+    'us-west3',
+    'us-west4',
+]);
+/**
+ * Endpoints that route across regions rather than naming one. `us` and `eu` keep
+ * processing inside their territory; `global` does not promise that, and takes
+ * whatever capacity is free.
+ */
+const ENDPOINTS = new Set(['global', 'us', 'eu']);
+/**
+ * Throws on a name that is neither an endpoint nor shaped like a region — `usa`,
+ * or `us-central` with its digit missing — because those are 404s at the first
+ * call, a long way from the command that caused them. Returns false for a
+ * well-formed name that is merely unrecognised, which the caller reports and
+ * stores anyway: Google adds regions, and a list compiled here would be wrong
+ * before it was old.
+ */
+export function checkRegion(region) {
+    if (!ENDPOINTS.has(region) && !REGION.test(region)) {
+        throw usageError(`"${region}" is not a region`, 'give a region such as us-central1, or the endpoints global, us or eu');
+    }
+    return ENDPOINTS.has(region) || REGIONS.has(region);
+}
 // ---------------------------------------------------------------------------
 // Store
 // ---------------------------------------------------------------------------
@@ -300,6 +365,30 @@ export class KeyStore {
     reveal(entry) {
         return entry.holds === 'file' ? this.fileOf(entry) : entry.value;
     }
+    /**
+     * Which GCP project a Vertex entry addresses, and how that was decided —
+     * the same order the library resolves it in, so what is shown is what will
+     * be called. A service-account file states its own project, and nothing was
+     * ever stored for it, so an entry with no `project` is not an entry with no
+     * project: it is one whose project is only knowable by reading the file.
+     */
+    projectOf(entry) {
+        if (entry.provider !== 'vertex') {
+            return undefined;
+        }
+        const fromEnv = process.env.GOOGLE_CLOUD_PROJECT;
+        if (fromEnv) {
+            return { id: fromEnv, from: 'env' };
+        }
+        if (entry.project) {
+            return { id: entry.project, from: 'stored' };
+        }
+        if (entry.holds !== 'file') {
+            return undefined;
+        }
+        const id = projectIdOf(this.fileOf(entry));
+        return id ? { id, from: 'file' } : undefined;
+    }
     /**
      * What the library would see. Real environment variables win, so CI,
      * `docker run -e` and a one-off `OPENAI_API_KEY=… zen run` all behave
@@ -350,6 +439,20 @@ export class KeyStore {
         return target;
     }
 }
+/**
+ * `project_id` out of a service-account file. Express-mode keys, gcloud user
+ * ADC and metadata credentials carry none, so finding nothing is an answer.
+ */
+function projectIdOf(path) {
+    try {
+        const key = JSON.parse(readFileSync(path, 'utf8'));
+        const id = key.project_id;
+        return typeof id === 'string' && id.trim() ? id.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 // ---------------------------------------------------------------------------
 // Display
 // ---------------------------------------------------------------------------

package/dist/lib.d.ts

@@ -1,5 +1,6 @@
 export { extract, invokedAs, one, parse, split, type Parsed, type Split } from './args.ts';
 export { printBanner, type BannerText } from './banner.ts';
+export { Cache, items as cacheItems, cacheKey, kinds as cacheKinds, clear as clearCache, NO_CACHE, sweep as sweepCache, type CacheEntry, type CacheItem, type CacheKind, type CacheOptions, type CacheStore, type Swept, } from './cache.ts';
 export { CATALOG_TTL_MS, CURATED, fetchCatalog, loadCatalog, loadCatalogs, matches, PREFERRED, type Catalog, type CatalogEntry, type CatalogOptions, type Filters, type Role, } from './catalog.ts';
 export type { Command, Context } from './command.ts';
 export { assertPrivate, ensureDir, ensureHome, home, paths, readJson, writeJson } from './home.ts';

package/dist/lib.js

@@ -23,6 +23,7 @@
 // ---------------------------------------------------------------------------
 export { extract, invokedAs, one, parse, split } from "./args.js";
 export { printBanner } from "./banner.js";
+export { Cache, items as cacheItems, cacheKey, kinds as cacheKinds, clear as clearCache, NO_CACHE, sweep as sweepCache, } from "./cache.js";
 export { CATALOG_TTL_MS, CURATED, fetchCatalog, loadCatalog, loadCatalogs, matches, PREFERRED, } from "./catalog.js";
 export { assertPrivate, ensureDir, ensureHome, home, paths, readJson, writeJson } from "./home.js";
 export { assertNotEmpty, assertOwner, assertUsable, describe, envNames, envOf, form, isOwner, isProvider, keyId, KeyStore, mask, OWNERS, parseRef, PROVIDERS, SERVICES, SHAPES, } from "./keys.js";

package/dist/liveness.js

@@ -107,6 +107,17 @@ export function classify(err) {
     if (UNREACHED.some((needle) => haystack.includes(needle))) {
         return { state: 'unknown', at, detail: 'could not reach the provider' };
     }
+    // A json api that answers in html was never reached: the hostname was
+    // wrong. Vertex builds its hostname out of the location, so a misspelt
+    // region lands here — as `<!DOCTYPE html>`, which explains nothing.
+    if (haystack.includes('<!doctype html') || haystack.includes('<html')) {
+        return {
+            state: 'unknown',
+            at,
+            detail: 'a web page came back, not the api — the endpoint does not exist',
+            fix: 'check the location: vertex builds its hostname from it',
+        };
+    }
     // 429 means the credential authenticated and then got rate limited, which
     // is a live key having a bad day.
     if (status === 429) {

package/dist/main.js

@@ -151,5 +151,14 @@ async function usage(name) {
     write(`  -C, --directory <d> ${dim('Act as if run in <d>.')}`);
     write(`\n${dim(`Start with ${cyan(`${NAME} init`)}, then ${cyan(`${NAME} run`)}.`)}`);
 }
+// `zen memory ls | head` closes the pipe while we are still writing to it, and
+// an unhandled EPIPE turns that ordinary shell idiom into a stack trace. The
+// reader having left is not our error, so we stop quietly.
+process.stdout.on('error', (err) => {
+    if (err.code !== 'EPIPE') {
+        throw err;
+    }
+    process.exit(0);
+});
 process.exitCode = await main(process.argv.slice(2));
 //# sourceMappingURL=main.js.map

package/dist/podman.js

@@ -2,7 +2,7 @@ import { runProcess, SandboxError } from '@zenera/neo';
 import { readdirSync, statSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
-import { CliError, confirm, dim, EXIT, isInteractive, note } from "./term.js";
+import { CliError, confirm, dim, EXIT, isInteractive, note, progress } from "./term.js";
 const DEFAULT_MACHINE_CPUS = 2;
 const DEFAULT_MACHINE_MEMORY = 2048;
 /** Starting a virtual machine and pulling an image are both slow on purpose. */
@@ -73,7 +73,7 @@ async function preflight(opts) {
         const present = await call(['image', 'exists', opts.image], 30_000);
         if (present.code !== 0) {
             note(dim(`pulling ${opts.image} — this happens once`));
-            const pulled = await stream(engine, ['pull', opts.image], run);
+            const pulled = await stream(engine, ['pull', opts.image], run, 'pulling');
             if (pulled.code !== 0) {
                 throw sandboxError(`could not pull ${opts.image}`, first(pulled) || 'check the image name and your network');
             }
@@ -99,7 +99,7 @@ async function install(engine, opts, run) {
         throw sandboxError('podman is not installed', how);
     }
     note(dim('installing podman — this takes a few minutes'));
-    const done = await stream('brew', ['install', 'podman'], run);
+    const done = await stream('brew', ['install', 'podman'], run, 'installing podman');
     if (done.code !== 0) {
         throw sandboxError('could not install podman', first(done) || how);
     }
@@ -127,7 +127,7 @@ async function machine(engine, call, opts, run) {
         const cpus = String(opts.cpus ?? DEFAULT_MACHINE_CPUS);
         const memory = String(opts.memory ?? DEFAULT_MACHINE_MEMORY);
         note(dim(`initialising the podman machine (${cpus} cpus, ${memory} MiB) — once per host`));
-        const created = await stream(engine, ['machine', 'init', '--cpus', cpus, '--memory', memory], run);
+        const created = await stream(engine, ['machine', 'init', '--cpus', cpus, '--memory', memory], run, 'initialising the machine');
         if (created.code !== 0) {
             throw sandboxError('could not create the podman machine', first(created));
         }
@@ -143,7 +143,7 @@ async function machine(engine, call, opts, run) {
         args.push(chosen.Name);
     }
     note(dim('starting the podman machine'));
-    const started = await stream(engine, args, run, SLOW_MS);
+    const started = await stream(engine, args, run, 'starting the machine', SLOW_MS);
     if (started.code !== 0 && !/already running/i.test(started.stderr)) {
         throw sandboxError('could not start the podman machine', first(started));
     }
@@ -197,8 +197,8 @@ async function build(engine, spec, run, force = false) {
     }
     note(dim(`${force ? 'rebuilding' : 'building'} the sandbox image from ${spec.dockerfile}`));
     note(dim('  the agent runs its commands inside a container, so the image is needed first'));
-    note(dim('  this takes a few minutes; later runs reuse it until the Dockerfile changes'));
-    const built = await stream(engine, ['build', '--tag', spec.tag, '--file', spec.dockerfile, spec.context], run, BUILD_MS);
+    note(dim('  this takes a few minutes; later runs reuse it'));
+    const built = await stream(engine, ['build', '--tag', spec.tag, '--file', spec.dockerfile, spec.context], run, 'building the sandbox image', BUILD_MS);
     if (built.code !== 0) {
         throw new BuildError(`could not build ${spec.dockerfile}`, EXIT.sandbox, last(built) || 'run the build by hand to see what the engine says');
     }
@@ -384,13 +384,20 @@ function children(dir) {
     }
 }
 // ---------------------------------------------------------------------------
+const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const FRAME_MS = 100;
 /**
  * Long steps print as they go. A five-minute pull with no output is
  * indistinguishable from a hang, and the one thing worse than waiting is not
  * knowing whether you are waiting.
+ *
+ * The engine's own output is buffered until it exits, so while the step runs
+ * the only honest thing to show is that it is still running: a spinner and a
+ * clock, both of which have to move without any event to move them. Off
+ * without a terminal — a CI log wants one line per fact, not ten a second.
  */
-async function stream(bin, args, run, timeoutMs = SLOW_MS) {
-    const res = await run(bin, args, { timeoutMs });
+async function stream(bin, args, run, label, timeoutMs = SLOW_MS) {
+    const res = await ticking(label, run(bin, args, { timeoutMs }));
     for (const line of res.stderr.split('\n').slice(-3)) {
         if (line.trim()) {
             note(dim(`  ${line.trim()}`));
@@ -398,6 +405,33 @@ async function stream(bin, args, run, timeoutMs = SLOW_MS) {
     }
     return res;
 }
+async function ticking(label, work) {
+    if (!process.stderr.isTTY) {
+        return work;
+    }
+    const bar = progress();
+    const startedAt = Date.now();
+    let frame = 0;
+    const timer = setInterval(() => {
+        const spin = SPINNER[frame++ % SPINNER.length];
+        bar.update(dim(`  ${spin} ${label}  ${elapsed(Date.now() - startedAt)}`));
+    }, FRAME_MS);
+    timer.unref();
+    try {
+        return await work;
+    }
+    finally {
+        clearInterval(timer);
+        bar.done();
+    }
+}
+function elapsed(ms) {
+    const total = Math.floor(ms / 1000);
+    const seconds = total % 60;
+    return total < 60
+        ? `${seconds}s`
+        : `${Math.floor(total / 60)}m ${String(seconds).padStart(2, '0')}s`;
+}
 function first(res) {
     return (res.stderr.trim() || res.stdout.trim()).split('\n')[0] ?? '';
 }