@zenera/cli 1.1.18 → 1.1.20

package/README.md

@@ -377,6 +377,12 @@ clones it types `zen init repo-notes` once - a directory that is already a
 project is registered, not rebuilt, and nothing in it is touched - and the name
 is a command on their machine too.
 
+When a newer `zen` is installed, `zen check --fix` brings a project's copies of
+_our_ files up to date: the memory and tool house rules under `agents/`, and the
+`.vscode/` and `.github/` trees. They restate how the version in hand behaves,
+so a copy left behind by an upgrade is worse than none. Nothing that describes
+_your_ project is touched.
+
 ## A project is a folder
 
 Prompts, agent wiring, skills and tool selections are all files - Markdown and

package/dist/banner.d.ts

@@ -4,6 +4,10 @@ declare const ACCENTS: {
         readonly face: "\u001B[1;38;5;208m";
         readonly shade: "\u001B[0;38;5;130m";
     };
+    readonly green: {
+        readonly face: "\u001B[1;38;5;41m";
+        readonly shade: "\u001B[0;38;5;29m";
+    };
     readonly cyan: {
         readonly face: "\u001B[1;38;5;51m";
         readonly shade: "\u001B[0;38;5;37m";
@@ -12,6 +16,10 @@ declare const ACCENTS: {
         readonly face: "\u001B[1;38;5;121m";
         readonly shade: "\u001B[0;38;5;78m";
     };
+    readonly gold: {
+        readonly face: "\u001B[1;38;5;220m";
+        readonly shade: "\u001B[0;38;5;178m";
+    };
 };
 export type Hue = keyof typeof ACCENTS;
 export interface BannerText {

package/dist/banner.js

@@ -1,4 +1,4 @@
-import { dim, note, styled } from "./term.js";
+import { appearance, dim, note, styled } from "./term.js";
 // ---------------------------------------------------------------------------
 // The banner
 //
@@ -65,12 +65,17 @@ function big(word) {
 /** A wordmark rather than a sentence, so the letters are set apart. */
 const spaced = (s) => [...s.toUpperCase()].join(' ');
 const RESET = '\u001b[0m';
-const HEAD = { face: '\u001b[1;38;5;231m', shade: '\u001b[0;38;5;244m' };
+const HEADS = {
+    dark: { face: '\u001b[1;38;5;231m', shade: '\u001b[0;38;5;244m' },
+    light: { face: '\u001b[1;38;5;235m', shade: '\u001b[0;38;5;245m' },
+};
 /** One per sub-brand, so two of them are told apart before the word is read. */
 const ACCENTS = {
     orange: { face: '\u001b[1;38;5;208m', shade: '\u001b[0;38;5;130m' },
+    green: { face: '\u001b[1;38;5;41m', shade: '\u001b[0;38;5;29m' },
     cyan: { face: '\u001b[1;38;5;51m', shade: '\u001b[0;38;5;37m' },
     mint: { face: '\u001b[1;38;5;121m', shade: '\u001b[0;38;5;78m' },
+    gold: { face: '\u001b[1;38;5;220m', shade: '\u001b[0;38;5;178m' },
 };
 /** Runs of stroke and runs of bevel, alternating; spaces stay unstyled. */
 const RUNS = /[█▀▄]+|[^█▀▄ ]+/g;
@@ -95,17 +100,18 @@ export function bannerLines(text, columns = process.stderr.columns || 80) {
     // inside a styled string cannot be trimmed away later.
     const accent = big(text.accent).map((row) => row.trimEnd());
     const tone = ACCENTS[text.hue ?? 'orange'];
+    const ink = HEADS[appearance()];
     const margin = ' '.repeat(INDENT);
     const width = INDENT + head[0].length + GAP + Math.max(...accent.map((row) => row.length));
     if (width > columns) {
         return [
-            `${margin}${flat(text.head.toUpperCase(), HEAD)} ${flat(text.accent.toUpperCase(), tone)}`,
+            `${margin}${flat(text.head.toUpperCase(), ink)} ${flat(text.accent.toUpperCase(), tone)}`,
             `${margin}${dim(spaced(text.subtitle))}`,
         ];
     }
     const lines = [];
     for (let r = 0; r < HEIGHT; r++) {
-        lines.push(`${margin}${paint(head[r], HEAD)}${' '.repeat(GAP)}${paint(accent[r], tone)}`);
+        lines.push(`${margin}${paint(head[r], ink)}${' '.repeat(GAP)}${paint(accent[r], tone)}`);
     }
     // Rules on both sides, centred under the art: the subtitle is a caption,
     // and without them a short line of spaced capitals floats.

package/dist/commands/cache.js

@@ -20,6 +20,7 @@ const LISTED = 20;
 export const cache = {
     summary: 'What work has been kept, and getting rid of it.',
     usage: USAGE,
+    banner: { head: 'Zenera', accent: 'Cache', subtitle: 'Stored Work', hue: 'gold' },
     details: [
         '  ls                     What is stored, by kind. Changes nothing.',
         '  prune                  Remove what the filters name.',

package/dist/commands/check.js

@@ -6,9 +6,10 @@ import { KeyStore } from "../keys.js";
 import { duration } from "../narrate.js";
 import { Registry } from "../projects.js";
 import { project as resolveProject } from "../resolve.js";
+import { refreshShared } from "../scaffold.js";
 import { bold, count, cyan, dim, green, invalidError, json, progress, red, table, usageError, write, writeAll, yellow, } from "../term.js";
 import { validateProject, } from "../validate.js";
-const USAGE = 'zen check [name|dir] [--project <name|dir>] [--no-sandbox] [--no-models] [--strict] [--quiet]';
+const USAGE = 'zen check [name|dir] [--project <name|dir>] [--fix] [--no-sandbox] [--no-models] [--strict] [--quiet]';
 // ---------------------------------------------------------------------------
 // zen check
 //
@@ -52,6 +53,14 @@ export const check = {
         'Unlike a run, it does not stop at the first problem — the report lists',
         'everything it found, each with a code and the fix for it.',
         '',
+        '--fix rewrites the files that are ours rather than the project\u2019s: the',
+        'memory and tool house rules under agents/, and the editor tree',
+        '(.vscode/ and .github/). They restate how this version of zen behaves,',
+        'so a copy left behind by an upgrade is worse than none — they are',
+        'replaced whether or not they were edited, and the report that follows is',
+        'of the project as repaired. Nothing else is touched: agents.yaml, the',
+        'prompts, the specification and agents/instructions.md are yours.',
+        '',
         'The argument is a directory if one is there and a registered project',
         'name otherwise; with neither, the project you are standing in.',
         '',
@@ -61,6 +70,7 @@ export const check = {
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, {
             project: { type: 'string' },
+            fix: { type: 'boolean' },
             'no-sandbox': { type: 'boolean' },
             'no-models': { type: 'boolean' },
             strict: { type: 'boolean' },
@@ -74,6 +84,11 @@ export const check = {
         // read here and handed to the check rather than looked up inside it.
         const entry = (await Registry.open()).findPath(dir);
         const name = entry?.name ?? basename(dir);
+        // Before the report rather than after it, so what it says is true of
+        // the files that are there now and the exit code answers the repaired
+        // project. A fix that left an error behind in the output would be read
+        // as a fix that failed.
+        const fixed = values.fix ? refreshShared(dir) : [];
         // Materialised first, so the credential verdicts are the ones a run
         // would reach: a key in the environment and a key in the keyring are
         // the same key by the time the library asks. The project's own `.env`
@@ -99,13 +114,15 @@ export const check = {
         });
         bar.done();
         if (ctx.json) {
-            json(report);
+            json({ ...report, fixed });
         }
         else if (values.quiet) {
+            writeAll(fixedLines(fixed));
             writeAll(findingLines(report.findings));
             write(verdict(report, Boolean(values.strict)));
         }
         else {
+            writeAll(fixedLines(fixed));
             writeAll(render(report));
         }
         const failed = report.counts.errors > 0 || (Boolean(values.strict) && report.counts.warnings > 0);
@@ -303,6 +320,21 @@ function agentBlock(agent) {
     }
     return [head, ...table(rows)];
 }
+/**
+ * What `--fix` replaced, said before the report so the two read in the order
+ * they happened. Silent when nothing was asked for, so the only difference
+ * between `zen check` and `zen check --fix` on a healthy project is these lines.
+ */
+function fixedLines(fixed) {
+    if (fixed.length === 0) {
+        return [];
+    }
+    return [
+        `${bold('Replaced')} ${dim(`${count(fixed.length, 'file')} \u2014 ours, not the project's`)}`,
+        ...fixed.map((f) => `  ${green('wrote')} ${f}`),
+        '',
+    ];
+}
 /**
  * One finding, three lines at most: what and where, then why, then the fix.
  * The code is printed because it is the part a script — or a model asked to

package/dist/commands/index.js

@@ -59,7 +59,7 @@ export const EXTERNAL = {
         summary: 'Retrieval over a corpus: index it, then ask it something.',
         usage: 'zen rag <subject> <command> [args...]',
         install: 'npm i -g @zenera/rag',
-        banner: { head: 'Zenera', accent: 'Rag', subtitle: 'Corpus Retrieval' },
+        banner: { head: 'Zenera', accent: 'Rag', subtitle: 'Corpus Retrieval', hue: 'green' },
     },
 };
 //# sourceMappingURL=index.js.map

package/dist/commands/init.js

@@ -130,7 +130,7 @@ export const init = {
         'Writes SPECIFICATION.md, agents.yaml, agents/ (house rules, the memory',
         'rules and one role prompt) and scripts/, then records the directory so',
         '`zen list` and `zen open` can find it by name. Editor files',
-        '(.vscode/settings.json and the .github/ tree) are written alongside,',
+        '(.vscode/ and the .github/ tree) are written alongside,',
         'replacing any already there.',
         '',
         'A directory that is already a project is adopted rather than rebuilt:',

package/dist/commands/meta.js

@@ -56,7 +56,7 @@ export const meta = {
         'Nothing it needs is put on a command line: every credential reaches it',
         'through the environment, where other processes cannot read it.',
         '',
-        'The editor files `zen init` writes (.vscode/settings.json and the .github/',
+        'The editor files `zen init` writes (.vscode/ and the .github/',
         'tree) are refreshed in the project first, the way `zen open` refreshes',
         'them: the agent is about to read that brief, and it describes this version',
         'of zen. Edits to them do not survive.',

package/dist/commands/open.js

@@ -20,7 +20,7 @@ export const open = {
         'Editor: --editor, then $ZENERA_EDITOR, then the editor this terminal',
         'belongs to, then $VISUAL or $EDITOR, then a known editor on PATH or',
         'installed, then the platform opener.',
-        'The editor files `zen init` writes (.vscode/settings.json and the',
+        'The editor files `zen init` writes (.vscode/ and the',
         '.github/ tree) are refreshed in the directory being opened; edits to',
         'them do not survive.',
         'VS Code and its forks are launched with --disable-workspace-trust so',

package/dist/main.js

@@ -6,7 +6,7 @@ import { NEO_BANNER, printBanner } from "./banner.js";
 import { ALIASES, COMMANDS, EXTERNAL } from "./commands/index.js";
 import { cliManifest, versionOf } from "./commands/version.js";
 import { hasExternal, loadExternal } from "./external.js";
-import { CliError, EXIT, bold, cyan, dim, fail, note, pad, write } from "./term.js";
+import { CliError, EXIT, bold, cyan, dim, fail, note, pad, title, write } from "./term.js";
 /** What the user typed: `zen`, `zn` or `zenera` all arrive here. */
 const NAME = invokedAs('zen');
 /** Usage lines are written against `zen`. Say them back in the reader's word. */
@@ -22,6 +22,8 @@ const spell = (usage) => (NAME === 'zen' ? usage : usage.replace(/^zen\b/, NAME)
 // inside `run`. Everything on this path is Node's own, which is why `zen --help`
 // starts instantly and why the CLI adds no weight to the library.
 // ---------------------------------------------------------------------------
+/** Commands whose name is not simply its first letter capitalised. */
+const TITLES = { rag: 'RAG' };
 const GLOBAL = {
     help: { type: 'boolean', short: 'h' },
     version: { type: 'boolean', short: 'v' },
@@ -54,6 +56,11 @@ async function main(argv) {
     const name = parts.name ? (ALIASES[parts.name] ?? parts.name) : undefined;
     const command = name ? COMMANDS[name] : undefined;
     const external = name && !command ? EXTERNAL[name] : undefined;
+    // Named before anything is printed, so a run that takes an hour is
+    // identifiable in `ps` and on its own tab for the whole of it.
+    if (name && (command || external)) {
+        title(`Zen ${TITLES[name] ?? name.replace(/^./, (c) => c.toUpperCase())}`);
+    }
     // Narration, so `--json` and every pipe are untouched by it. A command
     // living in another package brings its own brand, but only once it is
     // actually there — a banner over "not installed" is a claim about nothing.

package/dist/meta.js

@@ -6,7 +6,7 @@ import { invokedAs } from "./args.js";
 import { paths, readJson, writeJson } from "./home.js";
 import { envOf } from "./keys.js";
 import { credentialError, cut, cyan, dim, note, pad, plain, red, styled, usageError, write, yellow, } from "./term.js";
-import { answerWidth, segmentsOf, wrap } from "./tui/wrap.js";
+import { blocksOf, boxWidth, textOf, wrap } from "./tui/wrap.js";
 export const PROMPT_DIR = '.github/prompts';
 const PROMPT_SUFFIX = '.prompt.md';
 // ---------------------------------------------------------------------------
@@ -492,19 +492,31 @@ export function answerBox(text, columns = process.stdout.columns ?? 80) {
     if (!process.stdout.isTTY) {
         return text.split('\n');
     }
-    const outer = answerWidth(columns);
+    const outer = boxWidth(text, columns);
     const inner = outer - 4;
     const body = [];
-    for (const segment of segmentsOf(text)) {
-        if (segment.code) {
+    let previous;
+    for (const block of blocksOf(text)) {
+        if (previous && !(block.kind === 'item' && previous.kind === 'item')) {
+            body.push('');
+        }
+        previous = block;
+        if (block.kind === 'code') {
             // Indentation is the meaning of a fenced block, so it is cut rather
             // than reflowed.
-            body.push(dim(`\u250c\u2500${segment.title ? ` ${segment.title}` : ''}`));
-            body.push(...segment.lines.map((l) => `${dim('\u2502')} ${cut(l, inner - 2)}`));
+            body.push(dim(`\u250c\u2500${block.title ? ` ${block.title}` : ''}`));
+            body.push(...(block.lines ?? []).map((l) => `${dim('\u2502')} ${cut(l, inner - 2)}`));
             body.push(dim('\u2514\u2500'));
         }
+        else if (block.lines || block.kind === 'table') {
+            body.push(...textOf(block)
+                .split('\n')
+                .map((l) => cut(l, inner)));
+        }
         else {
-            body.push(...wrap(segment.lines.join('\n'), inner));
+            // Plain, not styled: `wrap` counts characters, and a bold run
+            // measured with its escape codes in it folds the line early.
+            body.push(...wrap(textOf(block, inner), inner));
         }
     }
     const rule = BOX.h.repeat(outer - 2);

package/dist/scaffold.d.ts

@@ -1,3 +1,16 @@
+/**
+ * The project files that are ours rather than the project's.
+ *
+ * Everything else under `templates/project/` describes *this project* and is
+ * written once. These describe *this version of `zen`* — how the memory graph
+ * works, how its tools are called, what survives a join — and land under
+ * `agents/` only because that is where house rules have to be to reach a
+ * prompt. A copy that has fallen behind the runtime is worse than none, so
+ * `zen check --fix` replaces them, and nothing in them is worth editing in
+ * place: project policy on any of those subjects goes in a topic file of its
+ * own beside them.
+ */
+export declare const SHARED_RULES: readonly string[];
 /**
  * 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,
@@ -6,6 +19,30 @@
  * none. Returns the relative paths written.
  */
 export declare function editorFiles(dir: string): 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
+ * relative paths written, project files first.
+ *
+ * This is the other half of `keep: true`. A scaffold never overwrites, which is
+ * right for the files a project goes on to make its own and wrong for the ones
+ * that only ever restate how this version of `zen` behaves — those a project
+ * upgrades into, and before this there was no way to get them except by hand.
+ */
+export declare function refreshShared(dir: string): string[];
+/**
+ * Which of a project's `SHARED_RULES` are not the bytes this `zen` ships.
+ *
+ * The comparison is the whole file rather than anything read out of it,
+ * because there is no reading that would have caught the copies that went
+ * stale in practice: prose describing a tool that was renamed, a section about
+ * behaviour that changed, frontmatter added after the copy was written. All of
+ * it parses, all of it loads, and all of it is wrong. A file that is not there
+ * is not stale — what must exist is checked where it is required, not here.
+ *
+ * Paths come back with forward slashes, the way a report names a file.
+ */
+export declare function staleShared(dir: string): string[];
 export interface ScaffoldOptions {
     /** the project directory */
     dir: string;

package/dist/scaffold.js

@@ -1,5 +1,5 @@
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 // ---------------------------------------------------------------------------
 // Scaffolding
@@ -11,7 +11,7 @@ import { fileURLToPath } from 'node:url';
 //
 //   templates/project/   the project's own files. Written once and edited from
 //                        then on, so anything already there is left alone.
-//   templates/editor/    ours: `.vscode/settings.json` and the `.github/` tree,
+//   templates/editor/    ours: the `.vscode/` and `.github/` trees,
 //                        which describe this version of `zen` to the editor and
 //                        are replaced every time.
 //   templates/parts/     fragments spliced into a template above.
@@ -35,6 +35,23 @@ const TEMPLATES = fileURLToPath(new URL('../templates', import.meta.url));
 const TEMPLATE = '.tmpl';
 /** How to use the memory graph: a house rules file, landing under `agents/`. */
 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:`. */
+const FORK_RULES = join('agents', 'fork-instructions.md');
+/**
+ * The project files that are ours rather than the project's.
+ *
+ * Everything else under `templates/project/` describes *this project* and is
+ * written once. These describe *this version of `zen`* — how the memory graph
+ * works, how its tools are called, what survives a join — and land under
+ * `agents/` only because that is where house rules have to be to reach a
+ * prompt. A copy that has fallen behind the runtime is worse than none, so
+ * `zen check --fix` replaces them, and nothing in them is worth editing in
+ * place: project policy on any of those subjects goes in a topic file of its
+ * own beside them.
+ */
+export const SHARED_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');
 /**
@@ -194,7 +211,7 @@ function copyTree(from, dir, rel, opts) {
 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 prepended to every agent that can see the graph — and it is
+    // 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
@@ -208,6 +225,53 @@ export function editorFiles(dir) {
     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
+ * relative paths written, project files first.
+ *
+ * This is the other half of `keep: true`. A scaffold never overwrites, which is
+ * right for the files a project goes on to make its own and wrong for the ones
+ * that only ever restate how this version of `zen` behaves — those a project
+ * upgrades into, and before this there was no way to get them except by hand.
+ */
+export function refreshShared(dir) {
+    const written = [];
+    for (const rel of SHARED_RULES) {
+        const path = join(dir, rel);
+        mkdirSync(dirname(path), { recursive: true });
+        copyFileSync(join(TEMPLATES, 'project', rel), path);
+        written.push(rel);
+    }
+    written.push(...editorFiles(dir));
+    return written;
+}
+/**
+ * Which of a project's `SHARED_RULES` are not the bytes this `zen` ships.
+ *
+ * The comparison is the whole file rather than anything read out of it,
+ * because there is no reading that would have caught the copies that went
+ * stale in practice: prose describing a tool that was renamed, a section about
+ * behaviour that changed, frontmatter added after the copy was written. All of
+ * it parses, all of it loads, and all of it is wrong. A file that is not there
+ * is not stale — what must exist is checked where it is required, not here.
+ *
+ * Paths come back with forward slashes, the way a report names a file.
+ */
+export function staleShared(dir) {
+    const stale = [];
+    for (const rel of SHARED_RULES) {
+        const path = join(dir, rel);
+        if (!existsSync(path)) {
+            continue;
+        }
+        const ours = readFileSync(join(TEMPLATES, 'project', rel), 'utf8');
+        if (readFileSync(path, 'utf8') !== ours) {
+            stale.push(rel.split(sep).join('/'));
+        }
+    }
+    return stale;
+}
 /**
  * Writes a project. Never overwrites the project's own files — a second `init`
  * over a directory fills in what is missing and leaves the rest alone — but the

package/dist/term.d.ts

@@ -20,7 +20,21 @@ export declare class CliError extends Error {
 export declare const usageError: (m: string, hint?: string) => CliError;
 export declare const invalidError: (m: string, hint?: string) => CliError;
 export declare const credentialError: (m: string, hint?: string) => CliError;
+export type Appearance = 'dark' | 'light';
+/** One grey per background. The only 256-colour indices in the CLI. */
+export declare const CHROME: Record<Appearance, number>;
+/** What the terminal looks like, as far as can be known without asking it. */
+export declare function appearance(): Appearance;
 export declare const bold: (s: string) => string;
+/**
+ * One step quieter, which is half of everything this tool prints: paths,
+ * counts, hints, the second column of every table.
+ *
+ * A stated grey rather than SGR 2. `dim` is not a colour, it is a request, and
+ * how far it is honoured is the terminal's own business — iTerm2 takes a step,
+ * Apple Terminal goes most of the way to the background and takes the quiet
+ * half of the output with it.
+ */
 export declare const dim: (s: string) => string;
 export declare const red: (s: string) => string;
 export declare const green: (s: string) => string;
@@ -52,6 +66,8 @@ export declare function progress(): {
     done: () => void;
 };
 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;
 export declare function isInteractive(): boolean;
 export declare function ask(question: string, fallback?: string): Promise<string>;

package/dist/term.js

@@ -1,3 +1,4 @@
+import { execFileSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { styleText } from 'node:util';
 // ---------------------------------------------------------------------------
@@ -36,11 +37,75 @@ export class CliError extends Error {
 export const usageError = (m, hint) => new CliError(m, EXIT.usage, hint);
 export const invalidError = (m, hint) => new CliError(m, EXIT.invalid, hint);
 export const credentialError = (m, hint) => new CliError(m, EXIT.credentials, hint);
+/** One grey per background. The only 256-colour indices in the CLI. */
+export const CHROME = { dark: 245, light: 242 };
+let sniffed;
+/** What the terminal looks like, as far as can be known without asking it. */
+export function appearance() {
+    sniffed ??= fromEnv() ?? fromColorFgBg() ?? fromAppleTerminal() ?? 'dark';
+    return sniffed;
+}
+function fromEnv() {
+    const v = process.env['ZENERA_THEME']?.trim().toLowerCase();
+    return v === 'dark' || v === 'light' ? v : undefined;
+}
+/**
+ * `COLORFGBG` is `fg;bg` or `fg;<something>;bg`; the background is the last
+ * field. Anything non-numeric (notably `default`) tells us nothing.
+ */
+function fromColorFgBg() {
+    const parts = process.env['COLORFGBG']?.split(';');
+    const bg = parts?.[parts.length - 1];
+    if (bg === undefined || !/^\d+$/.test(bg)) {
+        return undefined;
+    }
+    const n = Number(bg);
+    return n === 7 || n >= 9 ? 'light' : 'dark';
+}
+/** The shipped Apple Terminal profiles that are paper rather than ink. */
+const APPLE_LIGHT = new Set(['basic', 'man page', 'novel', 'silver aerogel']);
+/**
+ * Ask `defaults` which profile Terminal.app opens with. A subprocess during
+ * startup is a real cost, so it is paid last, once per process, and only on
+ * the one terminal that leaves us nothing else to go on. A custom profile is
+ * not in the table and falls through to the guess.
+ */
+function fromAppleTerminal() {
+    if (process.env['TERM_PROGRAM'] !== 'Apple_Terminal') {
+        return undefined;
+    }
+    try {
+        const name = execFileSync('defaults', ['read', 'com.apple.Terminal', 'Default Window Settings'], { encoding: 'utf8', timeout: 300, stdio: ['ignore', 'pipe', 'ignore'] })
+            .trim()
+            .toLowerCase();
+        return APPLE_LIGHT.has(name) ? 'light' : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 // ---------------------------------------------------------------------------
 // Styling
 // ---------------------------------------------------------------------------
 export const bold = (s) => styleText('bold', s);
-export const dim = (s) => styleText('dim', s);
+/**
+ * One step quieter, which is half of everything this tool prints: paths,
+ * counts, hints, the second column of every table.
+ *
+ * A stated grey rather than SGR 2. `dim` is not a colour, it is a request, and
+ * how far it is honoured is the terminal's own business — iTerm2 takes a step,
+ * Apple Terminal goes most of the way to the background and takes the quiet
+ * half of the output with it.
+ */
+export const dim = (s) => {
+    if (!styled()) {
+        return s;
+    }
+    const open = `\u001b[38;5;${CHROME[appearance()]}m`;
+    // A colour nested inside closes with `39m`, which would drop the grey for
+    // whatever follows it.
+    return `${open}${s.replaceAll('\u001b[39m', `\u001b[39m${open}`)}\u001b[39m`;
+};
 export const red = (s) => styleText('red', s);
 export const green = (s) => styleText('green', s);
 export const yellow = (s) => styleText('yellow', s);
@@ -121,6 +186,31 @@ export function progress() {
 export function warn(message) {
     note(`${yellow('warning')} ${message}`);
 }
+// ---------------------------------------------------------------------------
+// Naming the run
+//
+// Two different things answer to the word "title", and a long run wants both.
+// `process.title` is what the process table says, which is how `ps` and
+// Activity Monitor tell one `zen` from another. The tab is the terminal's own,
+// and nothing a process does to itself reaches it — macOS reads the tab name
+// from the executable — so it takes an OSC sequence, written to stderr with the
+// rest of the narration and only when there is a terminal to read it.
+// ---------------------------------------------------------------------------
+let restores = false;
+/** What this run calls itself, in the process table and on the terminal's tab. */
+export function title(text) {
+    process.title = text;
+    if (!process.stderr.isTTY) {
+        return;
+    }
+    // Push what the shell had there first, so leaving puts it back.
+    if (!restores) {
+        restores = true;
+        process.stderr.write('\u001b[22;0t');
+        process.on('exit', () => process.stderr.write('\u001b[23;0t'));
+    }
+    process.stderr.write(`\u001b]0;${text}\u0007`);
+}
 export function fail(message, hint) {
     note(`${red('error')} ${message}`);
     if (hint) {