@zenera/cli 1.1.9 → 1.1.11

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/history.d.ts

@@ -0,0 +1,18 @@
+/** Entries kept in memory and after a trim. */
+export declare const MAX_ENTRIES = 500;
+/** Beside the sessions, so it outlives any one of them and is already ignored by git. */
+export declare const historyPath: (projectDir: string) => string;
+export declare class History {
+    #private;
+    constructor(path: string);
+    static open(projectDir: string): History;
+    /** Oldest first, which is the order the arrow keys walk. */
+    get entries(): readonly string[];
+    /**
+     * Records one line. Blanks and a repeat of the line just before it are
+     * dropped — holding the arrow key down to get past six identical retries
+     * is the thing that makes a history annoying rather than useful.
+     */
+    add(text: string): void;
+}
+//# sourceMappingURL=history.d.ts.map

package/dist/history.js

@@ -0,0 +1,93 @@
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { sessionsDir } from "./projects.js";
+// ---------------------------------------------------------------------------
+// The prompt's history
+//
+// The same contract a shell offers: what you asked before is one arrow key
+// away, and it is still there tomorrow. It belongs to the **project**, not to
+// a session — the question you want back is usually the one you asked in the
+// session you just finished, while starting the next one.
+//
+// The file is what `.bash_history` is: one line per entry, oldest last,
+// appended to. A prompt line cannot contain a newline, so nothing has to be
+// escaped and the file stays greppable and hand-editable.
+//
+// Nothing here may ever stop someone typing. Every filesystem call is guarded
+// and a failure degrades to an in-memory history for the rest of the run.
+// ---------------------------------------------------------------------------
+/** Entries kept in memory and after a trim. */
+export const MAX_ENTRIES = 500;
+/** Lines tolerated in the file before it is rewritten, so appending stays the common case. */
+const TRIM_AT = MAX_ENTRIES * 2;
+const FILE_MODE = 0o600;
+/** Beside the sessions, so it outlives any one of them and is already ignored by git. */
+export const historyPath = (projectDir) => join(sessionsDir(projectDir), '.history');
+export class History {
+    #path;
+    #entries;
+    constructor(path) {
+        this.#path = path;
+        this.#entries = read(path);
+    }
+    static open(projectDir) {
+        return new History(historyPath(projectDir));
+    }
+    /** Oldest first, which is the order the arrow keys walk. */
+    get entries() {
+        return this.#entries;
+    }
+    /**
+     * Records one line. Blanks and a repeat of the line just before it are
+     * dropped — holding the arrow key down to get past six identical retries
+     * is the thing that makes a history annoying rather than useful.
+     */
+    add(text) {
+        const line = text.trim();
+        if (!line || line.includes('\n') || this.#entries.at(-1) === line) {
+            return;
+        }
+        this.#entries.push(line);
+        if (this.#entries.length > MAX_ENTRIES) {
+            this.#entries.shift();
+        }
+        try {
+            mkdirSync(dirname(this.#path), { recursive: true });
+            appendFileSync(this.#path, `${line}\n`, { mode: FILE_MODE });
+        }
+        catch {
+            // A prompt that cannot remember is still a prompt.
+        }
+    }
+}
+function read(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const lines = text
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0);
+    const kept = lines.slice(-MAX_ENTRIES);
+    if (lines.length > TRIM_AT) {
+        rewrite(path, kept);
+    }
+    return kept;
+}
+/** Through a sibling and a rename: a crash leaves the old history, never half of one. */
+function rewrite(path, lines) {
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tmp, lines.map((line) => `${line}\n`).join(''), { mode: FILE_MODE });
+        renameSync(tmp, path);
+    }
+    catch {
+        rmSync(tmp, { force: true });
+    }
+}
+//# sourceMappingURL=history.js.map

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/resolve.d.ts

@@ -13,6 +13,10 @@ export interface Target {
     session: SessionPaths;
     /** true when this call created the session */
     created: boolean;
+    /** absolute path the agent's file tools are rooted at */
+    workspace: string;
+    /** true when that directory is the session's own, made by this call */
+    freshWorkspace: boolean;
 }
 export declare function project(want: Wanted): Promise<Projects.Project>;
 export declare function target(want: Wanted): Promise<Target>;

package/dist/resolve.js

@@ -2,8 +2,8 @@ import { existsSync } from 'node:fs';
 import { relative, resolve, sep } from 'node:path';
 import { stamp } from "./ids.js";
 import * as Projects from "./projects.js";
-import { createSession, listSessions, requireSession, sessionPaths, } from "./session.js";
-import { ago, choose, confirm, dim, isInteractive, usageError, warn, yellow } from "./term.js";
+import { createSession, listSessions, readSessionMeta, requireSession, sessionPaths, } from "./session.js";
+import { ago, bold, choose, confirm, cyan, dim, isInteractive, usageError, warn, yellow, } from "./term.js";
 // ---------------------------------------------------------------------------
 // Project
 // ---------------------------------------------------------------------------
@@ -36,44 +36,70 @@ export async function target(want) {
         throw usageError('--session and --new contradict each other');
     }
     if (want.session) {
-        return {
-            project: found,
-            session: requireSession(dir, want.session),
-            created: false,
-        };
+        return await resumed(found, requireSession(dir, want.session));
     }
     if (!want.fresh) {
         const existing = await pickExisting(dir);
         if (existing) {
-            return { project: found, session: existing, created: false };
+            return await resumed(found, existing);
         }
     }
-    return { project: found, session: await create(dir, want), created: true };
+    const made = await create(dir, want);
+    return {
+        project: found,
+        session: made.session,
+        created: true,
+        workspace: made.workspace,
+        freshWorkspace: contains(made.session.dir, made.workspace),
+    };
 }
+/** A session that already exists brings its own workspace; it is never re-asked. */
+async function resumed(project, session) {
+    const meta = await readSessionMeta(session);
+    return {
+        project,
+        session,
+        created: false,
+        workspace: resolve(meta.workspace),
+        freshWorkspace: false,
+    };
+}
+/**
+ * Past this many, you are looking for a session by name rather than scrolling
+ * to it — and `--session <id>` is how you say a name.
+ */
+const MAX_SESSIONS = 25;
 /**
- * Resuming is the default: the common case is continuing what you were doing.
- * With one session it is taken without asking; with several, the others are
- * offered, because "the most recent" is only usually what you meant.
+ * Starting fresh is first, and it is the default: `zen run` followed by Enter
+ * should be a new conversation in a new directory, because that is what the
+ * command is asked for most often and the only answer that cannot go wrong.
+ * Everything already here is offered under it, newest first.
  *
  * A session that has never run has nothing to continue — it is indistinguishable
  * from a fresh one, so it is left out rather than offered as a choice.
  */
 async function pickExisting(projectDir) {
-    const sessions = (await listSessions(projectDir)).filter((s) => s.runs > 0 || s.busy);
-    if (sessions.length === 0) {
+    const all = (await listSessions(projectDir)).filter((s) => s.runs > 0 || s.busy);
+    if (all.length === 0) {
         return undefined;
     }
     if (!isInteractive()) {
-        return sessionPaths(projectDir, sessions[0].id);
+        return sessionPaths(projectDir, all[0].id);
     }
+    const sessions = all.slice(0, MAX_SESSIONS);
     const choice = await choose('Session', [
+        {
+            key: '0',
+            label: bold(cyan('New session…')),
+            detail: dim('a fresh conversation, in a directory of its own'),
+            value: undefined,
+        },
         ...sessions.map((s) => ({
             label: s.title ?? s.id,
             detail: `${s.id}  ${ago(s.lastRunAt ?? s.createdAt)}  ` +
                 `${s.runs} run${s.runs === 1 ? '' : 's'}${s.busy ? yellow('  running') : ''}`,
             value: s.id,
         })),
-        { label: dim('New session…'), value: undefined },
     ]);
     return choice ? sessionPaths(projectDir, choice) : undefined;
 }
@@ -86,7 +112,7 @@ async function create(projectDir, want) {
     const id = stamp();
     const planned = sessionPaths(projectDir, id);
     const workspace = await chooseWorkspace(planned, want);
-    return createSession(projectDir, id, workspace);
+    return { session: createSession(projectDir, id, workspace), workspace };
 }
 // ---------------------------------------------------------------------------
 // Workspace