@zenera/cli 1.1.24 → 1.1.25

package/dist/projects.d.ts

@@ -87,10 +87,5 @@ export declare function lastUsedAt(projectDir: string): string | undefined;
 export declare function dirSize(dir: string): number;
 /** True when a session's lock names a process that is still alive. */
 export declare function isBusy(sessionDir: string): boolean;
-/**
- * `kill(pid, 0)` sends no signal and only asks whether the process exists.
- * EPERM means it exists and belongs to someone else, which still counts.
- */
-export declare function alive(pid: number): boolean;
 export declare function projectName(dir: string): string;
 //# sourceMappingURL=projects.d.ts.map

package/dist/projects.js

@@ -1,4 +1,4 @@
-import { ASSETS_MOUNT, assetsDir, FILES_DIR, MEMORY_MOUNT, memoryDir, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
+import { ASSETS_MOUNT, assetsDir, FILES_DIR, MEMORY_MOUNT, memoryDir, pidAlive, skillDirs, skillMounts, SKILLS_MOUNT, } from '@zenera/neo';
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { paths, readJson, writeJson } from "./home.js";
@@ -290,26 +290,13 @@ export function isBusy(sessionDir) {
     const path = join(sessionDir, '.lock');
     try {
         const { pid } = JSON.parse(readFileSync(path, 'utf8'));
-        return typeof pid === 'number' && alive(pid);
+        return typeof pid === 'number' && pidAlive(pid);
     }
     catch {
         // Absent, unreadable or malformed: nothing is holding it.
         return false;
     }
 }
-/**
- * `kill(pid, 0)` sends no signal and only asks whether the process exists.
- * EPERM means it exists and belongs to someone else, which still counts.
- */
-export function alive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === 'EPERM';
-    }
-}
 export function projectName(dir) {
     return basename(resolve(dir));
 }

package/dist/sandbox.d.ts

@@ -39,6 +39,8 @@ export interface SandboxInputs {
      * promise it does not keep.
      */
     env?: readonly string[];
+    /** `false` overrides every `persist:` in the config, the agents' included */
+    persist?: boolean;
 }
 export declare function buildSandbox(opts: SandboxInputs): SandboxSetup;
 /**

package/dist/sandbox.js

@@ -3,7 +3,7 @@ import { mkdirSync } from 'node:fs';
 import { basename, join } from 'node:path';
 import { resolveBuild } from "./image.js";
 import { credentials } from "./keys.js";
-import { ensurePodmanReady } from "./podman.js";
+import { assertLocks, ensurePodmanReady } from "./podman.js";
 import { warn } from "./term.js";
 // ---------------------------------------------------------------------------
 // The sandbox, as this CLI wires it
@@ -71,6 +71,7 @@ export function buildSandbox(opts) {
         ...(opts.config.sandbox ?? {}),
         ...((opts.image ?? build?.tag) ? { image: opts.image ?? build?.tag } : {}),
         ...(opts.keys === false ? { keys: false } : {}),
+        ...(opts.persist === false ? { persist: false } : {}),
     };
     const home = join(opts.session.data, 'sandbox', 'home');
     const mounts = [{ host: home, at: HOME }, ...(opts.mounts ?? [])];
@@ -81,18 +82,22 @@ export function buildSandbox(opts) {
     // Skills and assets are mounted read-only, and a python script run from a
     // read-only directory fails on writing its own `__pycache__` — a confusing
     // error about a file nobody asked for.
-    const extra = { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(keys?.env ?? {}) };
+    // `ZENERA_AGENT` tells a `zen` run by `run_command` that no person is there.
+    const extra = { HOME, PYTHONDONTWRITEBYTECODE: '1', ZENERA_AGENT: '1', ...(keys?.env ?? {}) };
     const spec = toSpec(base, extra, secretsOf(keys?.secrets, opts.env));
     const agents = {};
     for (const agent of opts.config.agents) {
         if (agent.sandbox) {
             const merged = merge(base, agent.sandbox);
+            if (opts.persist === false) {
+                merged.persist = false;
+            }
             // An agent that opts out gets neither the variables nor the mount,
             // but the mount is on the pool and cannot be taken back per agent —
             // so the variable is what actually decides, and without it the file
             // sitting there is not a credential anything will look for.
             const own = merged.keys === false ? undefined : keys;
-            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ...(own?.env ?? {}) }, own && secretsOf(own.secrets, opts.env));
+            agents[agent.name] = toSpec(merged, { HOME, PYTHONDONTWRITEBYTECODE: '1', ZENERA_AGENT: '1', ...(own?.env ?? {}) }, own && secretsOf(own.secrets, opts.env));
         }
     }
     const pool = new SandboxPool({
@@ -201,6 +206,8 @@ export async function preflight(setup, yes) {
         memory: setup.spec.memory,
         yes,
     });
+    // A resumed session restarts its own stopped container, which needs no lock.
+    await assertLocks(1, { reuses: setup.pool.for().name });
     READY.add(setup.image);
 }
 /** Best-effort teardown: losing a container must never lose a run. */

package/dist/scaffold.d.ts

@@ -1,3 +1,6 @@
+export declare const TEMPLATES: string;
+/** How to use the memory graph: a house rules file, landing under `agents/`. */
+export declare const MEMORY_RULES: string;
 /**
  * The project files that are ours rather than the project's.
  *
@@ -19,14 +22,19 @@ export declare const SHARED_RULES: readonly string[];
  * scaffold wrote, rather than a second definition of "this version".
  */
 export declare function ownVersion(): string;
+type Vars = Record<string, string>;
+export interface CopyOptions {
+    /** values for the `{{...}}` in any template under this tree */
+    vars?: Vars;
+    /** leave a file that is already there alone rather than replacing it */
+    keep?: boolean;
+}
 /**
- * Writes the editor's files under `dir`, replacing what is there. They are
- * ours: they say how the editor is to treat a directory the agents write into,
- * and they describe the file formats of the version of `zen` in hand, so the
- * current answer is the only one worth having and a stale one is worse than
- * none. Returns the relative paths written.
+ * Copies one template directory into `dir` at `rel`, depth first, sorted so the
+ * list it returns is the same on every machine. Only a `.tmpl` is read as text;
+ * everything else is copied byte for byte.
  */
-export declare function editorFiles(dir: string): string[];
+export declare function copyTree(from: string, dir: string, rel: string, opts: CopyOptions): string[];
 /**
  * Replaces every file in a project that nobody is meant to be maintaining:
  * `SHARED_RULES` in the project tree, and the editor tree whole. Returns the
@@ -83,4 +91,5 @@ export interface Scaffolded {
  * the first set under twice as many lines about the second.
  */
 export declare function scaffold(opts: ScaffoldOptions): Scaffolded;
+export {};
 //# sourceMappingURL=scaffold.d.ts.map

package/dist/scaffold.js

@@ -1,6 +1,7 @@
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { editorFiles } from "./meta/editor.js";
 // ---------------------------------------------------------------------------
 // Scaffolding
 //
@@ -30,13 +31,13 @@ import { fileURLToPath } from 'node:url';
 // standing next to the files that implement it, which is the shape every
 // change to the project is then made in.
 // ---------------------------------------------------------------------------
-const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
+export const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
 /** The suffix on a file with `{{...}}` in it, dropped when the file lands. */
 const TEMPLATE = '.tmpl';
 /** How to use file tools: a house rules file, landing under `agents/`. */
 const FILE_RULES = join('agents', 'files-instructions.md');
 /** How to use the memory graph: a house rules file, landing under `agents/`. */
-const MEMORY_RULES = join('agents', 'memory-instructions.md');
+export const MEMORY_RULES = join('agents', 'memory-instructions.md');
 /** How tools are called: the same, and equally not the project's to maintain. */
 const TOOL_RULES = join('agents', 'tools-instructions.md');
 /** How forking behaves: the same again, reaching only agents that declare `fork:`. */
@@ -54,8 +55,6 @@ const FORK_RULES = join('agents', 'fork-instructions.md');
  * own beside them.
  */
 export const SHARED_RULES = [FILE_RULES, FORK_RULES, MEMORY_RULES, TOOL_RULES];
-/** The same bytes, kept in the `zen-memory` skill to restore or diff against. */
-const MEMORY_REFERENCE = join('.github', 'skills', 'zen-memory', 'references', 'memory-instructions.md');
 /**
  * This `zen`'s own version, which the scaffold pins the sandbox's tools to.
  * The publishable packages move in lockstep, so one number covers them all.
@@ -149,7 +148,7 @@ function target(name) {
  * list it returns is the same on every machine. Only a `.tmpl` is read as text;
  * everything else is copied byte for byte.
  */
-function copyTree(from, dir, rel, opts) {
+export function copyTree(from, dir, rel, opts) {
     const written = [];
     mkdirSync(join(dir, rel), { recursive: true });
     const entries = readdirSync(from, { withFileTypes: true });
@@ -169,67 +168,13 @@ function copyTree(from, dir, rel, opts) {
             : readFileSync(source);
         writeFileSync(join(dir, child), body);
         // The bytes are copied, not the file, so a script arrives unrunnable.
-        if (child.endsWith('.sh')) {
+        if (child.endsWith('.sh') || child.endsWith('.mjs')) {
             chmodSync(join(dir, child), 0o755);
         }
         written.push(child);
     }
     return written;
 }
-// ---------------------------------------------------------------------------
-// Telling the editor which instructions are not for it
-//
-// The project's house rules are `agents/instructions.md`, deliberately not
-// `AGENTS.md`: every coding assistant now reads that name out of an open
-// folder and feeds it to itself as always-on instructions, and `zen open`
-// opens exactly this directory. A name nobody else claims means the two are
-// never confused, and `chat.useAgentsMdFile` no longer has to be switched off
-// to keep them apart.
-//
-// They sit under `agents/` because there is rarely only one of them. Anything
-// named `agents/<topic>-instructions.md` is read too, in filename order, so a
-// subject that is true for every agent but is about one capability — memory,
-// say — gets its own document instead of another section in a file that keeps
-// growing.
-//
-// `chat.useNestedAgentsMdFiles` is still written. It is already false by
-// default, but it is opt-in globally, and this is a directory the agent itself
-// writes into — someone who turned it on would otherwise have the editor pick
-// up whatever `AGENTS.md` a run happened to leave behind. It is a *restricted*
-// setting, so it applies only in a trusted workspace; that is the right way
-// round, since an untrusted folder is not one to run agents in either.
-//
-// `agents/instructions.md` addresses the *project's* agents. The editor's
-// assistant still needs a brief of its own, and what it needs to know is how
-// this kind of project is put together — the file formats, how a prompt is
-// written, when to add a skill rather than an agent. That is what the
-// `.github/` tree is: the standing brief, plus the prompt files and skills the
-// editor picks up from the same place.
-// ---------------------------------------------------------------------------
-/**
- * Writes the editor's files under `dir`, replacing what is there. They are
- * ours: they say how the editor is to treat a directory the agents write into,
- * and they describe the file formats of the version of `zen` in hand, so the
- * current answer is the only one worth having and a stale one is worse than
- * none. Returns the relative paths written.
- */
-export function editorFiles(dir) {
-    const written = copyTree(join(TEMPLATES, 'editor'), dir, '', {});
-    // The one file that belongs to both trees. It is a project file first —
-    // house rules reaching every agent that can see the graph — and it is
-    // written once and edited from then on, like every other project file. But
-    // a project whose copy drifted, or that deleted it and turned memory back
-    // on later, needs somewhere to get the current text from, and the editor
-    // tree is replaced on every `init` and `open`. Copying the same bytes into
-    // the skill's references is what makes `diff` between the two mean
-    // something, and what stops a second copy of these rules existing in the
-    // repository to fall out of step with the first.
-    const reference = join(dir, MEMORY_REFERENCE);
-    mkdirSync(dirname(reference), { recursive: true });
-    copyFileSync(join(TEMPLATES, 'project', MEMORY_RULES), reference);
-    written.push(MEMORY_REFERENCE);
-    return written;
-}
 /**
  * Replaces every file in a project that nobody is meant to be maintaining:
  * `SHARED_RULES` in the project tree, and the editor tree whole. Returns the

package/dist/session.js

@@ -1,9 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { hostname } from 'node:os';
+import { claimLock, ownLock } from '@zenera/neo';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { readJson, writeJson } from "./home.js";
 import { isStamp, stamp, stampInstant } from "./ids.js";
-import { alive, isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
+import { isBusy, runIds, sessionIds, sessionsDir } from "./projects.js";
 import { CliError, EXIT, invalidError, usageError } from "./term.js";
 export function sessionPaths(projectDir, id) {
     if (!isStamp(id)) {
@@ -85,24 +85,7 @@ export function requireSession(projectDir, id) {
     return p;
 }
 export function acquire(p) {
-    const lock = { pid: process.pid, host: hostname(), startedAt: new Date().toISOString() };
-    const body = `${JSON.stringify(lock, null, 2)}\n`;
-    try {
-        // 'wx' fails when the file exists — the create and the check are one
-        // operation, so two `zen run`s racing cannot both win.
-        writeFileSync(p.lock, body, { flag: 'wx' });
-    }
-    catch (err) {
-        if (err.code !== 'EEXIST') {
-            throw err;
-        }
-        const held = current(p);
-        if (held && alive(held.pid) && held.host === hostname()) {
-            throw new CliError(`session ${p.id} is already running (pid ${held.pid})`, EXIT.failed, 'wait for it, or start another with --new');
-        }
-        // Stale, or from another machine's run that cannot be verified here.
-        writeFileSync(p.lock, body);
-    }
+    claimLock(p.lock, ownLock(), (held) => new CliError(`session ${p.id} is already running (pid ${held.pid})`, EXIT.failed, 'wait for it, or start another with --new'), 2);
     let released = false;
     const release = () => {
         if (released) {
@@ -113,14 +96,6 @@ export function acquire(p) {
     };
     return { release };
 }
-function current(p) {
-    try {
-        return JSON.parse(readFileSync(p.lock, 'utf8'));
-    }
-    catch {
-        return undefined;
-    }
-}
 export function runPaths(session, id) {
     if (!isStamp(id)) {
         throw usageError(`"${id}" is not a run id`);

package/dist/term.d.ts

@@ -73,6 +73,8 @@ export declare function warn(message: string): void;
 /** What this run calls itself, in the process table and on the terminal's tab. */
 export declare function title(text: string): void;
 export declare function fail(message: string, hint?: string): void;
+/** An agent's terminal can be a real pty (VS Code Copilot's is), so TTY checks alone miss it. */
+export declare function drivenByAgent(): boolean;
 export declare function isInteractive(): boolean;
 export declare function deferBanner(print: () => void): void;
 export declare function ask(question: string, fallback?: string): Promise<string>;

package/dist/term.js

@@ -230,8 +230,16 @@ export function fail(message, hint) {
 // a stdin that will never answer. A CLI that hangs in CI is worse than one that
 // fails in CI, because only one of the two tells you which flag you forgot.
 // ---------------------------------------------------------------------------
+/** An agent's terminal can be a real pty (VS Code Copilot's is), so TTY checks alone miss it. */
+export function drivenByAgent() {
+    const own = process.env['ZENERA_AGENT'];
+    if (own !== undefined) {
+        return own !== '' && own !== '0';
+    }
+    return Boolean(process.env['AI_AGENT'] || process.env['COPILOT_AGENT']);
+}
 export function isInteractive() {
-    return Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY) && !drivenByAgent();
 }
 // A banner is for whoever is sitting there, and the only proof that anyone is
 // sitting there is that we are about to ask them something. Commands whose
@@ -244,7 +252,8 @@ export function deferBanner(print) {
 }
 function requireTty(what, flag) {
     if (!isInteractive()) {
-        throw usageError(`cannot ask for ${what} without a terminal`, `pass ${flag} instead`);
+        const why = drivenByAgent() ? 'when an agent is running zen' : 'without a terminal';
+        throw usageError(`cannot ask for ${what} ${why}`, `pass ${flag} instead`);
     }
     const banner = pending;
     pending = undefined;

package/dist/trace.js

@@ -387,6 +387,53 @@ function tally(entries) {
         .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
         .map(([name, n]) => `${safe(name, 40)} x${n}`);
 }
+const WRITES = new Set(['write_file', 'apply_patch', 'copy_file', 'move_file']);
+/**
+ * What the run did with memory, zeros included. The `tools` row only lists
+ * calls that happened, and a commit that never happened is the commonest
+ * memory finding there is: absent from a list, a reader does not see it.
+ */
+function memoryRows(entries, bound) {
+    let recalls = 0;
+    let recalled = 0;
+    let commits = 0;
+    let committed = 0;
+    let files = 0;
+    let written = 0;
+    const calls = new Map();
+    for (const { node: n } of entries) {
+        if (n.type === 'memory_recall') {
+            recalls++;
+            recalled += n.nodes.length;
+        }
+        else if (n.type === 'memory_op' && n.op === 'commit') {
+            commits++;
+            committed += n.nodes.length;
+            files += n.files;
+        }
+        else if (n.type === 'tool_call') {
+            calls.set(n.name, (calls.get(n.name) ?? 0) + 1);
+            if (WRITES.has(n.name)) {
+                written++;
+            }
+        }
+    }
+    const used = (name) => calls.get(name) ?? 0;
+    const reads = used('memory_search') + used('memory_grep') + used('memory_load');
+    if (!bound && !recalls && !reads && !commits) {
+        return [];
+    }
+    const label = bound ? '' : 'memory';
+    const lines = [
+        row(label, `recall ${recalls} (${recalled} nodes) · search ${used('memory_search')} · ` +
+            `grep ${used('memory_grep')} · load ${used('memory_load')} · ` +
+            `commit ${commits} (${committed} nodes, ${files} files)`),
+    ];
+    if (!commits && written) {
+        lines.push(row('', `nothing committed after ${written} workspace file writes`));
+    }
+    return lines;
+}
 function elapsed(entries) {
     const stamps = entries.map((e) => e.endMs).filter((t) => t !== null);
     return stamps.length < 2 ? '' : span(Math.max(...stamps) - Math.min(...stamps));
@@ -441,6 +488,7 @@ function header(state, trace, opts) {
         ...(opts.dir ? [row('dir', safe(opts.dir, 200))] : []),
         ...(opts.workspace ? [row('workspace', safe(opts.workspace, 200))] : []),
         ...(opts.memory ? [row('memory', safe(opts.memory, 200))] : []),
+        ...memoryRows(entries, Boolean(opts.memory)),
         row('agent', `${safe(state.agentName, 40)} · started as ${safe(state.spec.startAgent, 40)}`),
         row('phase', state.error ? `${state.phase} — ${safe(state.error, 200)}` : state.phase),
         row('nodes', `${entries.length} · ${kinds.get('llm_call') ?? 0} llm · ` +
@@ -473,10 +521,13 @@ function header(state, trace, opts) {
     if (hidden) {
         lines.push(row('compacted', `${hidden} nodes are marked "hidden by" a later summary`), row('', 'they still ran; the model simply stopped seeing them'));
     }
-    lines.push('%%', row('reading', 'nN is a node id · t+ counts from the start of the turn'), row('', 'dotted edges are fork/join and calls answered out of order'), row('', 'nodes are declared in run order; every edge is in one block below'), row('detail', `zen inspect node n1 n2 n5..n9${where}`), 
+    lines.push(
+    // Never a bare `%%`: Mermaid only strips a comment line with something
+    // after the marker, and leaves the rest to the parser, which rejects it.
+    '%% ---', row('reading', 'nN is a node id · t+ counts from the start of the turn'), row('', 'dotted edges are fork/join and calls answered out of order'), row('', 'nodes are declared in run order; every edge is in one block below'), row('detail', `zen inspect node n1 n2 n5..n9${where}`), 
     // Named here because this is where the question forms. A reader who has
     // just found the node they distrust will not go looking for a verb.
-    row('why', `zen inspect ask n5 "why did you do that?"${where}`), '%%');
+    row('why', `zen inspect ask n5 "why did you do that?"${where}`), '%% ---');
     return lines;
 }
 export function traceMermaid(state, opts = {}) {

package/dist/tui/models.d.ts

@@ -0,0 +1,33 @@
+import { type Catalog, type CatalogEntry } from '../catalog.ts';
+import type { Provider } from '../keys.ts';
+export interface ProviderRow {
+    provider: Provider;
+    /** where its credential came from — `environment`, `keyring` — or '' for none */
+    credential: string;
+    /** what the cached listing holds, read without asking anyone */
+    models: number;
+    origin: Catalog['origin'];
+    fetchedAt: string;
+}
+/** What asking a model one question found out. */
+export interface Verdict {
+    state: 'live' | 'dead' | 'blocked' | 'unknown';
+    ms?: number;
+    detail?: string;
+    fix?: string;
+    dimensions?: number;
+}
+export interface BrowseOptions {
+    providers: readonly ProviderRow[];
+    /** opens straight into this provider's listing */
+    initial?: Provider;
+    theme?: string;
+    load(provider: Provider, refresh: boolean): Promise<Catalog>;
+    test(entry: CatalogEntry): Promise<Verdict>;
+}
+/**
+ * Runs the browser until the person picks a model or leaves. Resolves to the
+ * picked entry, or undefined when nothing was picked.
+ */
+export declare function browse(options: BrowseOptions): Promise<CatalogEntry | undefined>;
+//# sourceMappingURL=models.d.ts.map