@zenera/cli 1.1.24 → 1.1.25

package/dist/meta/window.d.ts

@@ -0,0 +1,61 @@
+export interface Sink {
+    answer(text: string): void;
+    narrate(line: string): void;
+    warn(line: string): void;
+    /** Kept by the log, never shown: the step-by-step nobody reads while it runs. */
+    detail?(line: string): void;
+    /** A transient last row, replaced each time and never kept. '' removes it. */
+    status?(line: string): void;
+    /** Called once when the run ends, so a repainting sink can clear itself. */
+    close?(): void;
+}
+export declare const terminalSink: Sink;
+/** Rows of narration the window keeps on screen. */
+export declare const WINDOW_ROWS = 8;
+/** How often the border is redrawn — the wave's frame, not the clock's. */
+export declare const FRAME_MS = 80;
+/** Cells the crest travels per frame — a lap of a wide window in a few seconds. */
+export declare const WAVE_STEP = 3;
+/**
+ * How brightly one cell of the border is lit, given where the crest has got to.
+ *
+ * `position` counts clockwise from the top left corner, so one index walks the
+ * whole ring and the wave rounds the corners without a seam. Everything the
+ * tail has passed sits at the dimmest tone, which is the border's resting
+ * colour: the ring is always drawn, only the crest moves.
+ */
+export declare function toneAt(position: number, head: number, span: number): number;
+/**
+ * The bottom rule as cells, with the status label set into it near the left.
+ *
+ * Waiting belongs to the frame rather than to the narration: a row of its own
+ * costs a step of what the agent is doing every time, and it settles just
+ * under the last line, which is where the eye already is. Near the left, where
+ * reading starts, and not so near that it displaces the corner.
+ */
+export declare function footerCells(label: string, width: number): string[];
+/**
+ * Narration held to a fixed number of rows that rewrite themselves in place.
+ *
+ * A long run is hundreds of tool calls, and printing each as its own line
+ * scrolls the question, the model line and every warning off the top of the
+ * screen — by the end the terminal holds a transcript nobody asked for and the
+ * answer is somewhere in the middle of it. Only the last few steps say what it
+ * is doing now, which is the only thing narration is for; the rest is in the
+ * session copilot recorded.
+ *
+ * Warnings are not narration: they leave the window and stay on the screen.
+ *
+ * Without a terminal there is nothing to rewrite over, so every line is its
+ * own — which is what a CI log wants anyway.
+ */
+export declare function windowSink(rows?: number): Sink;
+/**
+ * The answer in the same box `zen run` draws it in: bounded width, rounded
+ * rule, formatted with full markdown styling (bold, italics, code, lists, quotes, tables).
+ *
+ * Redirected output gets the text and nothing else — `zen meta run ... > out.md`
+ * is meant to produce a file you can read, not one with a border down its side.
+ */
+export declare function answerBox(text: string, columns?: number): string[];
+//# sourceMappingURL=window.d.ts.map

package/dist/meta/window.js

@@ -0,0 +1,198 @@
+import { boxWidth, cut, cyan, dim, formatMarkdown, note, pad, red, styled, write } from "./host.js";
+export const terminalSink = {
+    answer: (text) => write(text),
+    narrate: (line) => note(line),
+    warn: (line) => note(red(line)),
+};
+/** Rows of narration the window keeps on screen. */
+export const WINDOW_ROWS = 8;
+const BOX = { tl: '╭', tr: '╮', bl: '╰', br: '╯', h: '─', v: '│' };
+/** How often the border is redrawn — the wave's frame, not the clock's. */
+export const FRAME_MS = 80;
+// Dimmest first, crest last. Written as escapes rather than `styleText` because
+// a named colour has no ramp, which is also why `styled()` has to be asked.
+const WAVE = [
+    '\u001b[0;38;5;24m',
+    '\u001b[0;38;5;31m',
+    '\u001b[0;38;5;38m',
+    '\u001b[0;38;5;45m',
+    '\u001b[0;38;5;51m',
+    '\u001b[1;38;5;159m',
+    '\u001b[1;38;5;231m',
+];
+const RESET = '\u001b[0m';
+/** Cells each tone of the tail covers, so the crest reads as a band, not a dot. */
+const WAVE_TAIL = 2;
+/** Cells the crest travels per frame — a lap of a wide window in a few seconds. */
+export const WAVE_STEP = 3;
+/**
+ * How brightly one cell of the border is lit, given where the crest has got to.
+ *
+ * `position` counts clockwise from the top left corner, so one index walks the
+ * whole ring and the wave rounds the corners without a seam. Everything the
+ * tail has passed sits at the dimmest tone, which is the border's resting
+ * colour: the ring is always drawn, only the crest moves.
+ */
+export function toneAt(position, head, span) {
+    const behind = (((head - position) % span) + span) % span;
+    const step = Math.floor(behind / WAVE_TAIL);
+    return step < WAVE.length ? WAVE.length - 1 - step : 0;
+}
+/**
+ * A run of border cells, coloured by the wave and emitting an escape only where
+ * the tone changes — a frame of the whole ring is a handful of them.
+ *
+ * `from` is the ring position of the first cell and `step` which way round the
+ * ring the cells run, because the bottom rule is printed left to right while
+ * the ring travels it right to left.
+ */
+function lit(cells, from, step, head, span) {
+    let out = '';
+    let tone = -1;
+    for (let i = 0; i < cells.length; i++) {
+        const next = toneAt(from + i * step, head, span);
+        if (next !== tone) {
+            out += WAVE[next];
+            tone = next;
+        }
+        out += cells[i];
+    }
+    return `${out}${RESET}`;
+}
+/**
+ * The bottom rule as cells, with the status label set into it near the left.
+ *
+ * Waiting belongs to the frame rather than to the narration: a row of its own
+ * costs a step of what the agent is doing every time, and it settles just
+ * under the last line, which is where the eye already is. Near the left, where
+ * reading starts, and not so near that it displaces the corner.
+ */
+export function footerCells(label, width) {
+    const room = width - 6;
+    const text = label && room > 0 ? [...label].slice(0, room) : [];
+    const cells = text.length > 0 ? [BOX.bl, BOX.h, ' ', ...text, ' '] : [BOX.bl];
+    while (cells.length < width - 1) {
+        cells.push(BOX.h);
+    }
+    return [...cells, BOX.br];
+}
+/**
+ * Narration held to a fixed number of rows that rewrite themselves in place.
+ *
+ * A long run is hundreds of tool calls, and printing each as its own line
+ * scrolls the question, the model line and every warning off the top of the
+ * screen — by the end the terminal holds a transcript nobody asked for and the
+ * answer is somewhere in the middle of it. Only the last few steps say what it
+ * is doing now, which is the only thing narration is for; the rest is in the
+ * session copilot recorded.
+ *
+ * Warnings are not narration: they leave the window and stay on the screen.
+ *
+ * Without a terminal there is nothing to rewrite over, so every line is its
+ * own — which is what a CI log wants anyway.
+ */
+export function windowSink(rows = WINDOW_ROWS) {
+    if (!process.stderr.isTTY) {
+        return terminalSink;
+    }
+    const kept = [];
+    const colour = styled();
+    let label = '';
+    let head = 0;
+    let painted = 0;
+    // The frame must stay under the viewport: a block taller than the screen
+    // scrolls its own top away, and then the cursor-up erase falls short and
+    // strands a copy of every repaint. The two border rows count towards it.
+    const height = () => Math.max(1, Math.min(rows, (process.stderr.rows ?? 24) - 4));
+    const columns = () => Math.max(20, (process.stderr.columns ?? 80) - 1);
+    const innerOf = () => columns() - 4;
+    const erase = () => {
+        if (painted > 0) {
+            process.stderr.write(`\u001b[${painted}A\u001b[0J`);
+            painted = 0;
+        }
+    };
+    /** The whole frame, border lit by the wave, every row exactly one row. */
+    const frameOf = (show, inner) => {
+        const width = inner + 4;
+        // Clockwise from the top left: across the top, down the right, back
+        // along the bottom, up the left. One ring, so one index addresses it.
+        const span = 2 * width + 2 * show.length;
+        const top = [BOX.tl, ...Array(width - 2).fill(BOX.h), BOX.tr];
+        const bottom = footerCells(label, width);
+        const edge = (position) => colour ? lit([BOX.v], position, 1, head, span) : cyan(BOX.v);
+        return [
+            colour ? lit(top, 0, 1, head, span) : cyan(top.join('')),
+            ...show.map((line, r) => `${edge(span - 1 - r)} ${pad(cut(line, inner), inner)} ${edge(width + r)}`),
+            colour
+                ? lit(bottom, 2 * width + show.length - 1, -1, head, span)
+                : cyan(bottom.join('')),
+        ];
+    };
+    const paint = () => {
+        const show = kept.slice(-height());
+        if (show.length === 0 && label === '') {
+            erase();
+            return;
+        }
+        // The wave wants a frame to run round before there is anything to say.
+        const lines = frameOf(show.length > 0 ? show : [''], innerOf());
+        if (painted === lines.length) {
+            // Erasing before a repaint is what flickers; overwriting in place
+            // does not, and at frame rate the whole border has to be redrawn.
+            process.stderr.write(`\u001b[${painted}A${lines.map((l) => `\r${l}\u001b[0K\n`).join('')}`);
+            return;
+        }
+        erase();
+        process.stderr.write(lines.map((l) => `${l}\n`).join(''));
+        painted = lines.length;
+    };
+    return {
+        answer: (text) => {
+            erase();
+            write(text);
+        },
+        narrate: (line) => {
+            kept.push(...line.split('\n'));
+            if (kept.length > height() * 4) {
+                kept.splice(0, kept.length - height());
+            }
+            paint();
+        },
+        warn: (line) => {
+            erase();
+            note(red(line));
+            paint();
+        },
+        status: (line) => {
+            label = line;
+            head += WAVE_STEP;
+            paint();
+        },
+        close: erase,
+    };
+}
+/**
+ * The answer in the same box `zen run` draws it in: bounded width, rounded
+ * rule, formatted with full markdown styling (bold, italics, code, lists, quotes, tables).
+ *
+ * Redirected output gets the text and nothing else — `zen meta run ... > out.md`
+ * is meant to produce a file you can read, not one with a border down its side.
+ */
+export function answerBox(text, columns = process.stdout.columns ?? 80) {
+    if (!process.stdout.isTTY) {
+        return text.split('\n');
+    }
+    const outer = boxWidth(text, columns);
+    const inner = outer - 4;
+    const body = formatMarkdown(text, inner);
+    const rule = BOX.h.repeat(outer - 2);
+    return [
+        '',
+        dim(`${BOX.tl}${rule}${BOX.tr}`),
+        ...body.map((l) => `${dim(BOX.v)} ${pad(l, inner)} ${dim(BOX.v)}`),
+        dim(`${BOX.bl}${rule}${BOX.br}`),
+        '',
+    ];
+}
+//# sourceMappingURL=window.js.map

package/dist/meta/wire.d.ts

@@ -0,0 +1,42 @@
+import { type KeyEntry, type KeyStore, type Provider } from './host.ts';
+/**
+ * Copilot offers its tools as OpenAI *custom* tools, which the completions API
+ * rejects outright — `400 Invalid value: 'custom'`. Only the responses API
+ * takes them, and only the reasoning models serve it, so the wire API follows
+ * the model rather than being a flag nobody would know to set. Older models are
+ * listed rather than newer ones, so each new generation works without a release.
+ */
+export declare function wireApi(provider: Provider, id: string): string | undefined;
+export interface Wiring {
+    provider: Provider;
+    /** what the model is called on the wire */
+    model: string;
+    /** every `COPILOT_*` name and value, ready to hand to the child */
+    env: Record<string, string>;
+    /** names whose values are secret, for `--secret-env-vars` and for masking */
+    secret: string[];
+    /** anything true but unwelcome: a location that will be slow, a stale default */
+    warnings: string[];
+    /** Claude on Vertex: a loopback relay to start, whose url becomes the base url */
+    relay?: {
+        key: string;
+        project: string;
+        location: string;
+        keyFile: string;
+    };
+}
+/** Where the relay's url goes once it is listening. */
+export declare const RELAY_URL = "http://127.0.0.1:<relay>";
+/**
+ * Turns a zen key entry and a model id into copilot's environment.
+ *
+ * `COPILOT_PROVIDER_BASE_URL` is what activates BYOK at all, so every provider
+ * gets one — including OpenAI, whose url copilot would otherwise have reached
+ * through a GitHub account we are deliberately not using.
+ */
+export declare function wire(store: KeyStore, entry: KeyEntry, id: string): Wiring;
+/** Values a `--dry-run` may print. A key is four characters and an apology. */
+export declare function masked(env: Record<string, string>, secret: readonly string[]): string[];
+/** Non-fatal, said once, because a competing file is a silent override. */
+export declare function providersWarning(): string | undefined;
+//# sourceMappingURL=wire.d.ts.map

package/dist/meta/wire.js

@@ -0,0 +1,129 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { credentialError, envOf, invokedAs, yellow, } from "./host.js";
+const TYPES = {
+    openai: 'openai',
+    anthropic: 'anthropic',
+    google: 'openai',
+    vertex: 'openai',
+    openrouter: 'openai',
+};
+const BASE_URLS = {
+    openai: 'https://api.openai.com/v1',
+    anthropic: 'https://api.anthropic.com',
+    google: 'https://generativelanguage.googleapis.com/v1beta/openai/',
+    openrouter: 'https://openrouter.ai/api/v1',
+};
+/**
+ * Copilot offers its tools as OpenAI *custom* tools, which the completions API
+ * rejects outright — `400 Invalid value: 'custom'`. Only the responses API
+ * takes them, and only the reasoning models serve it, so the wire API follows
+ * the model rather than being a flag nobody would know to set. Older models are
+ * listed rather than newer ones, so each new generation works without a release.
+ */
+export function wireApi(provider, id) {
+    return provider === 'openai' && !/^(gpt-4|gpt-3\.5|chatgpt-)/.test(id)
+        ? 'responses'
+        : undefined;
+}
+/** Where the relay's url goes once it is listening. */
+export const RELAY_URL = 'http://127.0.0.1:<relay>';
+const vertexClaude = (id) => /^(anthropic\/)?claude-/.test(id);
+/**
+ * Turns a zen key entry and a model id into copilot's environment.
+ *
+ * `COPILOT_PROVIDER_BASE_URL` is what activates BYOK at all, so every provider
+ * gets one — including OpenAI, whose url copilot would otherwise have reached
+ * through a GitHub account we are deliberately not using.
+ */
+export function wire(store, entry, id) {
+    const provider = entry.provider;
+    const env = {};
+    const secret = [];
+    const warnings = [];
+    env.COPILOT_PROVIDER_TYPE = TYPES[provider];
+    env.COPILOT_MODEL = id;
+    if (provider === 'vertex' && vertexClaude(id)) {
+        const project = store.projectOf(entry)?.id;
+        if (entry.holds !== 'file' || !project) {
+            throw credentialError(`Claude on vertex needs a service account and a GCP project, not ${entry.provider}/${entry.name}`, 'add one: zen key add vertex --project <id>');
+        }
+        const model = id.replace(/^anthropic\//, '');
+        const key = randomBytes(24).toString('hex');
+        env.COPILOT_PROVIDER_TYPE = 'anthropic';
+        env.COPILOT_MODEL = model;
+        env.COPILOT_PROVIDER_BASE_URL = RELAY_URL;
+        env.COPILOT_PROVIDER_API_KEY = key;
+        return {
+            provider,
+            model,
+            env,
+            secret: ['COPILOT_PROVIDER_API_KEY'],
+            warnings,
+            relay: {
+                key,
+                project,
+                location: entry.location?.trim() || 'global',
+                keyFile: store.fileOf(entry),
+            },
+        };
+    }
+    if (provider === 'vertex') {
+        const project = store.projectOf(entry)?.id;
+        if (!project) {
+            throw credentialError(`no GCP project on ${entry.provider}/${entry.name}`, 'set one: zen key add vertex --project <id>');
+        }
+        const named = entry.location?.trim() || 'global';
+        const partner = id.includes('/') && !id.startsWith('google/');
+        // Gemini serves the `us`/`eu` multi-regions; partner models answer them with a 404 or 429.
+        const location = partner && (named === 'us' || named === 'eu') ? 'global' : named;
+        if (location === 'global' && !partner) {
+            warnings.push('location `global` adds about ten seconds of cold start');
+        }
+        env.COPILOT_PROVIDER_BASE_URL = `https://aiplatform.googleapis.com/v1/projects/${project}/locations/${location}/endpoints/openapi`;
+        // Vertex speaks publisher names on the wire and knows nothing of zen's
+        // provider prefix; the bare id stays as the model *id* so copilot can
+        // still match its catalogue for token limits and tool support.
+        env.COPILOT_PROVIDER_WIRE_MODEL = id.includes('/') ? id : `google/${id}`;
+        // Only Google's own ids are bare: `gpt-oss-…` would get GPT's custom `apply_patch`, which this endpoint rejects.
+        env.COPILOT_PROVIDER_MODEL_ID = id.startsWith('google/') ? id.slice('google/'.length) : id;
+    }
+    else {
+        const url = BASE_URLS[provider];
+        if (!url) {
+            throw credentialError(`no BYOK endpoint known for ${provider}`);
+        }
+        env.COPILOT_PROVIDER_BASE_URL = url;
+    }
+    const api = wireApi(provider, id);
+    if (api) {
+        env.COPILOT_PROVIDER_WIRE_API = api;
+    }
+    if (entry.holds === 'file') {
+        // A Google access token is good for an hour and a session is not, so
+        // copilot is told how to mint one rather than handed one that will be
+        // stale by the time it matters.
+        env.COPILOT_PROVIDER_API_KEY_COMMAND = `${invokedAs('zen')} key token ${entry.provider}`;
+        env[envOf(entry)] = store.fileOf(entry);
+    }
+    else {
+        env.COPILOT_PROVIDER_API_KEY = store.reveal(entry);
+        secret.push('COPILOT_PROVIDER_API_KEY');
+    }
+    return { provider, model: env.COPILOT_PROVIDER_WIRE_MODEL ?? id, env, secret, warnings };
+}
+/** Values a `--dry-run` may print. A key is four characters and an apology. */
+export function masked(env, secret) {
+    return Object.entries(env)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, value]) => `${name}=${secret.includes(name) ? '••••' : value}`);
+}
+/** Non-fatal, said once, because a competing file is a silent override. */
+export function providersWarning() {
+    const configured = process.env.COPILOT_PROVIDERS_CONFIG;
+    const path = configured ?? `${process.env.HOME ?? ''}/.copilot/providers.json`;
+    return existsSync(path)
+        ? yellow(`${path} may override the provider zen just wired`)
+        : undefined;
+}
+//# sourceMappingURL=wire.js.map

package/dist/modelref.d.ts

@@ -0,0 +1,16 @@
+import type { Provider } from './keys.ts';
+export declare const PROVIDER_NAMES: ReadonlySet<string>;
+/**
+ * `vertex/gemini-3.8-flash` splits; `gpt-5.6-sol` does not. Only a known provider
+ * counts as a prefix, because `google/gemini-3.8-flash` is also a perfectly good
+ * bare id on an endpoint that speaks publisher names.
+ *
+ * The colon form is the library's own — `openai:gpt-5.6-sol`, and with an api
+ * selector `openai/responses:gpt-5.6-sol` — which is what arrives when the ref
+ * came from `agents.yaml`.
+ */
+export declare function splitRef(ref: string): {
+    provider?: Provider;
+    id: string;
+};
+//# sourceMappingURL=modelref.d.ts.map

package/dist/modelref.js

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// Model refs as people type them
+//
+// `vertex/gemini-3.8-flash` from a person, `openai:gpt-5.6-sol` from
+// `agents.yaml`. Read by `zen inspect ask` and by `zen meta`, so it lives with
+// neither.
+// ---------------------------------------------------------------------------
+export const PROVIDER_NAMES = new Set([
+    'openai',
+    'anthropic',
+    'google',
+    'vertex',
+    'openrouter',
+]);
+/**
+ * `vertex/gemini-3.8-flash` splits; `gpt-5.6-sol` does not. Only a known provider
+ * counts as a prefix, because `google/gemini-3.8-flash` is also a perfectly good
+ * bare id on an endpoint that speaks publisher names.
+ *
+ * The colon form is the library's own — `openai:gpt-5.6-sol`, and with an api
+ * selector `openai/responses:gpt-5.6-sol` — which is what arrives when the ref
+ * came from `agents.yaml`.
+ */
+export function splitRef(ref) {
+    const colon = ref.indexOf(':');
+    if (colon > 0) {
+        const head = ref.slice(0, colon).split('/')[0];
+        if (PROVIDER_NAMES.has(head)) {
+            return { provider: head, id: ref.slice(colon + 1) };
+        }
+    }
+    const slash = ref.indexOf('/');
+    if (slash < 0) {
+        return { id: ref };
+    }
+    const head = ref.slice(0, slash);
+    return PROVIDER_NAMES.has(head)
+        ? { provider: head, id: ref.slice(slash + 1) }
+        : { id: ref };
+}
+//# sourceMappingURL=modelref.js.map

package/dist/narrate.js

@@ -117,8 +117,11 @@ export function duration(ms) {
     if (ms < 60_000) {
         return `${(ms / 1000).toFixed(1)}s`;
     }
-    const minutes = Math.floor(ms / 60_000);
-    return `${minutes}m ${Math.round((ms % 60_000) / 1000)}s`;
+    const totalSeconds = Math.round(ms / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    return hours > 0 ? `${hours}h ${minutes}m ${seconds}s` : `${minutes}m ${seconds}s`;
 }
 export const stopMark = (reason) => reason === 'final' ? green('done') : reason === 'aborted' ? yellow('aborted') : red('failed');
 //# sourceMappingURL=narrate.js.map

package/dist/podman.d.ts

@@ -41,6 +41,8 @@ export interface PodmanStatus {
         swap: number;
         cpus: number;
     };
+    /** containers the engine can still create; a stopped one holds a lock too */
+    freeLocks?: number;
     image?: string;
     imagePresent?: boolean;
 }
@@ -62,6 +64,30 @@ export declare class BuildError extends CliError {
 }
 /** What `zn sandbox status` prints. Changes nothing, and never throws. */
 export declare function podmanStatus(opts?: PodmanOptions): Promise<PodmanStatus>;
+/** Containers the engine can still create; undefined when it will not say. */
+export declare function freeLocks(engine?: string, exec?: import("@zenera/neo").Runner): Promise<number | undefined>;
+export interface LockOptions {
+    engine?: string;
+    exec?: typeof runProcess;
+    /** a container that may already exist, and so needs no new lock */
+    reuses?: string;
+    /** session id -> its directory; read from the registry when absent */
+    owners?: ReadonlyMap<string, string>;
+}
+/**
+ * Refuses a run the engine cannot hold before anything is spent on it. Every
+ * container takes a lock, stopped ones included, and at zero the failure would
+ * otherwise land on the first shell command — mid-turn, or once per item.
+ */
+export declare function assertLocks(need: number, opts?: LockOptions): Promise<void>;
+/** Every session on this machine, by id, from the projects the registry knows. */
+export declare function sessionOwners(): Promise<Map<string, string>>;
+/**
+ * Containers no live process is using: every stopped one, and a running one
+ * whose run exited without tearing it down (a kill, a crash, a closed lid).
+ * A running container that cannot be traced to its owner is left alone.
+ */
+export declare function idleContainers(containers: readonly OwnedContainer[], owners: ReadonlyMap<string, string>): OwnedContainer[];
 export interface OwnedContainer {
     name: string;
     /** podman's own word: `running`, `exited`, `created`, `paused` */

package/dist/podman.js

@@ -1,7 +1,8 @@
-import { runProcess, SandboxError } from '@zenera/neo';
+import { pidAlive, runProcess, SandboxError } from '@zenera/neo';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
+import { isBusy, isProjectDir, Registry, sessionIds, sessionsDir } from "./projects.js";
 import { CliError, confirm, dim, EXIT, isInteractive, note, progress } from "./term.js";
 const DEFAULT_MACHINE_CPUS = 2;
 const DEFAULT_MACHINE_MEMORY = 2048;
@@ -409,6 +410,9 @@ export async function podmanStatus(opts = {}) {
                 cpus: Number.isFinite(cpus) ? cpus : 0,
             };
         }
+        // Asked apart from the line above: an engine without the field fails
+        // the whole template, and that must not cost the report its memory.
+        status.freeLocks = await freeLocks(engine, run);
     }
     if (opts.image) {
         status.image = opts.image;
@@ -425,6 +429,76 @@ function safeMachines(stdout) {
         return [];
     }
 }
+/** Containers the engine can still create; undefined when it will not say. */
+export async function freeLocks(engine = 'podman', exec = runProcess) {
+    const res = await exec(engine, ['info', '--format', '{{.Host.FreeLocks}}'], {
+        timeoutMs: 30_000,
+    }).catch(() => undefined);
+    const free = res?.code === 0 ? res.stdout.trim() : '';
+    return /^\d+$/.test(free) ? Number(free) : undefined;
+}
+/**
+ * Refuses a run the engine cannot hold before anything is spent on it. Every
+ * container takes a lock, stopped ones included, and at zero the failure would
+ * otherwise land on the first shell command — mid-turn, or once per item.
+ */
+export async function assertLocks(need, opts = {}) {
+    const engine = opts.engine ?? 'podman';
+    const exec = opts.exec ?? runProcess;
+    const free = await freeLocks(engine, exec);
+    if (free === undefined || free >= need) {
+        return;
+    }
+    if (opts.reuses) {
+        const there = await exec(engine, ['container', 'exists', opts.reuses], {
+            timeoutMs: 30_000,
+        }).catch(() => undefined);
+        if (there?.code === 0) {
+            return;
+        }
+    }
+    const idle = idleContainers(await ownedContainers(engine, exec), opts.owners ?? (await sessionOwners())).length;
+    throw new CliError(`the container engine has ${free} locks free and this run needs ${need} — ` +
+        'every container holds one, stopped ones included', EXIT.sandbox, idle > 0
+        ? `zen sandbox clean --idle frees ${idle}`
+        : `every container zen made is in use — \`${engine} ps --all\` shows what holds them`);
+}
+/** Every session on this machine, by id, from the projects the registry knows. */
+export async function sessionOwners() {
+    const owners = new Map();
+    for (const entry of (await Registry.open()).entries) {
+        if (isProjectDir(entry.path)) {
+            for (const id of sessionIds(entry.path)) {
+                owners.set(id, join(sessionsDir(entry.path), id));
+            }
+        }
+    }
+    return owners;
+}
+/**
+ * Containers no live process is using: every stopped one, and a running one
+ * whose run exited without tearing it down (a kill, a crash, a closed lid).
+ * A running container that cannot be traced to its owner is left alone.
+ */
+export function idleContainers(containers, owners) {
+    return containers.filter((c) => {
+        if (c.state !== 'running') {
+            return true;
+        }
+        const faker = /^faker-(\d+)$/.exec(c.key ?? '');
+        if (faker) {
+            return !pidAlive(Number(faker[1]));
+        }
+        const dir = c.key === undefined ? undefined : owners.get(c.key);
+        return dir !== undefined && !isBusy(dir);
+    });
+}
+/**
+ * `ps --format json` is ~1 kB a container, so the runner's default 64 kB cap cut
+ * the listing at about sixty, the JSON stopped parsing, and every report said
+ * "none" while two thousand sat on the machine.
+ */
+const LISTING_BYTES = 64 * 1024 * 1024;
 /**
  * Containers this CLI created, whatever session they belong to, and whether
  * each is up. `--all` is the point: with `persist: true` a session leaves a
@@ -438,7 +512,7 @@ export async function ownedContainers(engine = 'podman', exec = runProcess, opts
     if (opts.sizes) {
         args.push('--size');
     }
-    const res = await exec(engine, args, { timeoutMs: 120_000 }).catch(() => undefined);
+    const res = await exec(engine, args, { timeoutMs: 120_000, maxBytes: LISTING_BYTES }).catch(() => undefined);
     if (!res || res.code !== 0) {
         return [];
     }
@@ -471,8 +545,14 @@ export async function removeContainers(names, engine = 'podman', exec = runProce
     if (names.length === 0) {
         return;
     }
-    await exec(engine, ['rm', '--force', '--volumes', ...names], { timeoutMs: 120_000 });
+    // In slices, so two thousand of them get a timeout each slice can meet.
+    for (let i = 0; i < names.length; i += REMOVE_SLICE) {
+        await exec(engine, ['rm', '--force', '--volumes', ...names.slice(i, i + REMOVE_SLICE)], {
+            timeoutMs: 120_000,
+        });
+    }
 }
+const REMOVE_SLICE = 100;
 /** What the engine is using. Never throws: a disk report is not worth a crash. */
 export async function engineDisk(engine = 'podman', exec = runProcess) {
     const call = (args) => exec(engine, args, { timeoutMs: 120_000 }).catch(() => undefined);