@xhulz/nina 0.34.0 → 0.35.0

package/src/agentrun.mjs

@@ -30,18 +30,74 @@ export function clip(text, chars) {
 }
 
 /** Names whose value is a credential when they are assigned one. */
-const SECRET_NAME = /(?:secret|token|passw(?:or)?d|api_?key|private_?key|access_?key|credential)/i;
+const SECRET_NAME = /(?:secret|token(?![a-z])|passw(?:or)?d|(?:^|[_-])pass$|api[_-]?key|private[_-]?key|access[_-]?key|signing[_-]?key|credential|dsn$)/i;
+
+/** Names that say where a secret is, or what kind, rather than holding one: `--password-file`, `TOKEN_TYPE`. */
+const ABOUT_A_SECRET = /[_-](?:file|path|dir|type|count|length|size|limit|url|endpoint)$/i;
 
 /** Token formats that are credentials on sight. */
-const SECRET_TOKEN = /\b(?:sk-(?:ant-|lf-|proj-)?[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{30,}|xox[abprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{35})/g;
+const SECRET_TOKEN = new RegExp(
+  [
+    'sk-(?:ant-|lf-|proj-)?[A-Za-z0-9_-]{16,}',
+    'gh[pousr]_[A-Za-z0-9]{30,}',
+    'github_pat_[A-Za-z0-9_]{30,}',
+    'glpat-[A-Za-z0-9_-]{20,}',
+    'xox[abprs]-[A-Za-z0-9-]{10,}',
+    '(?:AKIA|ASIA)[0-9A-Z]{16}',
+    'AIza[0-9A-Za-z_-]{35}',
+    '(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}',
+    'whsec_[A-Za-z0-9+/=]{16,}',
+    'npm_[A-Za-z0-9]{30,}',
+    'hf_[A-Za-z0-9]{30,}',
+    'SG\\.[A-Za-z0-9_-]{16,}\\.[A-Za-z0-9_-]{16,}',
+    'eyJ[A-Za-z0-9_-]{8,}\\.eyJ[A-Za-z0-9_-]{8,}\\.[A-Za-z0-9_-]{8,}',
+  ]
+    .map((p) => `\\b${p}`)
+    .join('|'),
+  'g',
+);
+
+/** `scheme://user:password@host` — the password, however the URL is named. */
+const URL_CREDENTIAL = /\b([a-z][a-z0-9+.-]{1,20}:\/\/[^\s:/@]{0,64}):[^\s@/]{1,256}@/gi;
+
+/**
+ * `NAME=value`, `NAME: value`, `"name": "value"` — the name and what joins it to a value of six characters or
+ * more, and not the value: {@link redact} takes that only for a secret's name. Every part is bounded, so no
+ * position costs more than a few dozen steps, whatever follows it.
+ */
+const ASSIGNMENT = /\b([A-Za-z0-9_-]{0,40})(["']?\s{0,3}[:=]\s{0,3}["']?)(?=[^\s"'`,;]{6})/g;
+
+/** The value that follows an assignment, read from where {@link ASSIGNMENT} stopped. */
+const VALUE = /[^\s"'`,;]+/y;
 
-/** `NAME=value`, `NAME: value`, `"name": "value"` — the name bounded, so the match cannot run away. */
-const ASSIGNMENT = /\b([A-Za-z0-9_]{0,40})(["']?\s{0,3}[:=]\s{0,3}["']?)([^\s"'`,;]{6,})/g;
+/** The same with the value in quotes, which may hold spaces: `password: "correct horse battery"`. */
+const QUOTED = /\b([A-Za-z0-9_-]{1,40})(["']?\s{0,3}[:=]\s{0,3})(["'])([^"'\n]{1,256})\3/g;
+
+/** A command-line option with its value after a space — `--password hunter2`, `--api-key "a b"`. */
+const FLAG = /(--?[A-Za-z0-9][A-Za-z0-9_-]{0,40})\s{1,3}(?:(["'])([^"'\n]{1,256})\2|([^\s"'`]{3,}))/g;
+
+/**
+ * curl's and friends' `-u user:password`, quoted or not. The user has to look like one — `date -u +%H:%M`
+ * is a format — and a password of digits alone is a group: `docker run -u 1000:1000`.
+ */
+const USER_FLAG = /((?:^|\s)(?:-u|--user)\s{1,3}[A-Za-z0-9_][A-Za-z0-9._@-]{0,63}):([^\s"']{1,256})/g;
+
+/** The same in quotes, where the password may hold spaces. */
+const USER_QUOTED = /((?:^|\s)(?:-u|--user)\s{1,3}(["'])[A-Za-z0-9_][A-Za-z0-9._@-]{0,63}):[^"'\n]{1,256}\2/g;
+
+/** A cookie header's whole value: every cookie in it may be a session. */
+const COOKIE = /\b((?:Set-)?Cookie["']?\s{0,3}:\s{0,3})[^\n"]{1,2000}/gi;
+
+/** An `Authorization` value under any scheme, or none — `ApiKey …` and a bare token as much as `Bearer …`. */
+const AUTHORIZATION = /\b((?:Proxy-)?Authorization["']?\s{0,3}[:=]\s{0,3}["']?)(?:([A-Za-z][A-Za-z0-9_-]{0,20})\s+)?[^\s"',;]{8,}/gi;
+
+/** Whether a name and the value assigned to it make a credential. A count is not one: `max_tokens: 100000`. */
+const secretPair = (name, value) => SECRET_NAME.test(name) && !ABOUT_A_SECRET.test(name) && !/^\d+$/.test(value) && value !== '[redacted]';
 
 /**
  * Text with the secrets it obviously carries masked: private keys, the token formats of the common
- * providers, an `Authorization` value, and anything assigned to a name that says it is a secret. A value
- * of digits only is left: `max_tokens: 100000` is not a credential.
+ * providers, the password in a URL, an `Authorization` value, and anything assigned to a name that says it
+ * is a secret. A value of digits only is left: `max_tokens: 100000` is not a credential.
  *
  * @param {string} text
  * @returns {string}
@@ -57,10 +113,34 @@ export function redact(text) {
     out = `${out.slice(0, start)}[redacted private key]${close === -1 ? '' : out.slice(close + 5)}`;
   }
   out = out.replace(SECRET_TOKEN, '[redacted]');
-  out = out.replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{16,}/g, '$1 [redacted]');
-  return out.replace(ASSIGNMENT, (whole, name, sep, value) =>
-    SECRET_NAME.test(name) && !/^\d+$/.test(value) && value !== '[redacted]' ? `${name}${sep}[redacted]` : whole,
+  out = out.replace(URL_CREDENTIAL, '$1:[redacted]@');
+  out = out.replace(/\b(Bearer|Basic|Token|Bot)\s+[A-Za-z0-9._~+/=-]{16,}/g, '$1 [redacted]');
+  out = out.replace(AUTHORIZATION, (whole, head, scheme) => `${head}${scheme ? `${scheme} ` : ''}[redacted]`);
+  out = out.replace(COOKIE, '$1[redacted]');
+  out = out.replace(USER_QUOTED, (whole, head, quote) => `${head}:[redacted]${quote}`);
+  out = out.replace(USER_FLAG, (whole, head, password) => (/^\d+$/.test(password) || password === '[redacted]' ? whole : `${head}:[redacted]`));
+  // The shell is where most of a stage's input is written, and it passes a secret after a space.
+  out = out.replace(FLAG, (whole, flag, quote, quoted, bare) =>
+    secretPair(flag.replace(/^-+/, ''), quoted ?? bare) ? `${flag} ${quote ?? ''}[redacted]${quote ?? ''}` : whole,
   );
+  out = out.replace(QUOTED, (whole, name, sep, quote, value) => (secretPair(name, value) ? `${name}${sep}${quote}[redacted]${quote}` : whole));
+  // By hand rather than by `replace`: an assignment to a name that is not a secret's leaves its value to be
+  // read, so one inside it still is. Replaced whole, `{"content":"API_KEY=…"}` took the key's value with it.
+  // The value is taken once, and only for a secret's name, which keeps the whole pass linear.
+  let masked = '';
+  let last = 0;
+  ASSIGNMENT.lastIndex = 0;
+  for (let m = ASSIGNMENT.exec(out); m !== null; m = ASSIGNMENT.exec(out)) {
+    const [head, name, sep] = m;
+    if (!SECRET_NAME.test(name)) continue;
+    VALUE.lastIndex = m.index + head.length;
+    const value = VALUE.exec(out)?.[0] ?? '';
+    if (!secretPair(name, value)) continue;
+    masked += `${out.slice(last, m.index)}${name}${sep}[redacted]`;
+    last = VALUE.lastIndex;
+    ASSIGNMENT.lastIndex = last;
+  }
+  return masked + out.slice(last);
 }
 
 /** A tool result's text: a string, or the text blocks of a list, with images named rather than sent. */

package/src/commands/check.mjs

@@ -9,15 +9,15 @@
  */
 
 import { readFile, readdir } from 'node:fs/promises';
-import { HARNESS, legacyHint } from '../paths.mjs';
+import { HARNESS, describeMove, interruptedMove, legacyHint } from '../paths.mjs';
 import { expectedUnfilled } from '../expected.mjs';
 import { parseGraph, validateGraph } from '../graph.mjs';
 import { frontmatterFindings, installedSkills, modelFindings, toolFindings } from '../tools.mjs';
 import { HOOK_SCRIPTS, missingWiring, shippedScripts } from '../wiring.mjs';
 import { existsSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
-import { REQUIRES, SLOT, defaultedSlots, layerRootFor, stripWhy, walk } from './compose.mjs';
-import { defaultVocabulary } from '../vocabulary.mjs';
+import { REQUIRES, SLOT, defaultedSlots, layerRootFor, noticeOf, readLayerText, stripWhy, walk } from './compose.mjs';
+import { PLACEHOLDER, defaultVocabulary } from '../vocabulary.mjs';
 import { NEEDS } from '../surfaces.mjs';
 
 /** Fields every declared integration must carry, and why each one matters. */
@@ -56,13 +56,13 @@ export async function referencedVocabulary(layerRoot, surfaces, target) {
       const t = await readFile(join(layerRoot, 'surfaces', s, 'tree', rel), 'utf8').catch(() => null);
       if (t !== null) texts.push(t);
     }
-    for (const [, name] of stripWhy(texts.join('\n')).matchAll(/\{\{([A-Z_]+)\}\}/g)) found.add(name);
+    for (const [, name] of stripWhy(texts.join('\n')).matchAll(PLACEHOLDER)) found.add(name);
   }
   if (target) {
     const projectTree = join(target, HARNESS, 'project', 'tree');
     for (const rel of await walk(projectTree)) {
-      const text = stripWhy(await readFile(join(projectTree, rel), 'utf8'));
-      for (const [, name] of text.matchAll(/\{\{([A-Z_]+)\}\}/g)) found.add(name);
+      const text = stripWhy((await readLayerText(join(projectTree, rel))) ?? '');
+      for (const [, name] of text.matchAll(PLACEHOLDER)) found.add(name);
     }
   }
   return found;
@@ -100,7 +100,7 @@ export async function filledSlots(target) {
   const tree = join(target, HARNESS, 'project', 'tree');
   const filled = new Set();
   for (const rel of await walk(tree)) {
-    for (const line of (await readFile(join(tree, rel), 'utf8')).split('\n')) {
+    for (const line of ((await readLayerText(join(tree, rel))) ?? '').split('\n')) {
       const marker = SLOT.exec(line);
       if (marker) filled.add(`${rel} ${marker[1]}`);
     }
@@ -230,6 +230,10 @@ export async function check(argv, ctx) {
     return 1;
   }
 
+  // The move measures this check itself while its journal is written, and that journal is not a problem then.
+  const stopped = process.env.NINA_UPGRADE ? null : interruptedMove(target);
+  if (stopped) problems.push(`${describeMove(stopped)} \`nina upgrade --abort\` undoes it`);
+
   const surfaces = profile.surfaces ?? [];
   const available = (await readdir(join(resolved.dir, 'surfaces'), { withFileTypes: true }))
     .filter((e) => e.isDirectory())
@@ -350,7 +354,7 @@ export async function check(argv, ctx) {
       // them; they are outside the pipeline graph, not a stage the graph forgot.
       for (const file of (await readdir(agentsDir).catch(() => [])).filter((f) => f.endsWith('.md'))) {
         const text = await readFile(join(agentsDir, file), 'utf8');
-        if (text.includes('nina:generated')) specs.set(file.replace(/\.md$/, ''), text);
+        if (noticeOf(text) !== null) specs.set(file.replace(/\.md$/, ''), text);
       }
       // A core with a graph and no agent specs has no roles to name — an empty set, not a crash that
       // `upgrade` would read as a new failure and roll a move back for.

package/src/commands/compose.mjs

@@ -16,12 +16,12 @@
  * sit unenforceable for three months here.
  */
 
-import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { HARNESS, legacyHint } from '../paths.mjs';
 import { expectedUnfilled } from '../expected.mjs';
 import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
-import { defaultVocabulary } from '../vocabulary.mjs';
+import { NAME, defaultVocabulary } from '../vocabulary.mjs';
 
 /**
  * Matches a slot marker on its own line, with an optional label.
@@ -139,6 +139,48 @@ export function generatedNotice(rel, slots, script = false) {
   return script ? lines.map((line) => `// ${line}`).join('\n') : `<!-- ${lines.join('\n     ')} -->`;
 }
 
+/** Where compose keeps a copy of each file it stops composing when a surface leaves the profile. */
+export const REMOVED = join(HARNESS, 'removed');
+
+/**
+ * How far into a file the notice is looked for: below a frontmatter block, or a shebang. The compose
+ * suite holds every composed file's notice inside it.
+ */
+export const NOTICE_HEAD = 60;
+
+/**
+ * A composed file's notice, as one sentence without its comment syntax, or null when it has none.
+ *
+ * This is the one test of whether a file was composed. A file that only mentions the notice — a CLAUDE.md
+ * written by hand that explains the harness, say — is not composed: read as "contains the words", compose
+ * took such a file for its own and wrote over it with no copy kept.
+ *
+ * @param {string} text - The file.
+ * @returns {string|null}
+ */
+export function noticeOf(text) {
+  const lines = String(text).split('\n').slice(0, NOTICE_HEAD);
+  const at = lines.findIndex((l) => /^(<!--|\/\/) nina:generated/.test(l));
+  if (at < 0) return null;
+  const block = [];
+  if (lines[at].startsWith('//')) {
+    for (const line of lines.slice(at)) {
+      if (!line.startsWith('//')) break;
+      block.push(line.replace(/^\/\/ ?/, ''));
+    }
+  } else {
+    // The notice's own delimiters, taken off by position: this reads text the compiler wrote, it filters
+    // nothing, and a pattern for it read to a scanner as an HTML sanitizer that misses `--!>`.
+    for (const line of lines.slice(at)) {
+      const open = line.startsWith('<!-- ') ? line.slice('<!-- '.length) : line;
+      const end = open.lastIndexOf('-->');
+      block.push(end >= 0 ? open.slice(0, end) : open);
+      if (end >= 0) break;
+    }
+  }
+  return block.map((l) => l.trim()).join(' ');
+}
+
 /**
  * Puts the notice at the top of a composed file, below its frontmatter where it has any.
  *
@@ -241,6 +283,20 @@ export async function walk(dir) {
   return out;
 }
 
+/**
+ * A layer file's text, read the way every reader of the layers must read it: with a byte-order mark taken
+ * off and Windows line ends made `\n`. A fragment saved with CRLF matched no slot marker — the marker's
+ * pattern ends at `-->` and the line ended in a `\r` — so the whole file composed to nothing, and the only
+ * sign was the count of unfilled slots. A BOM did the same to the first slot.
+ *
+ * @param {string} path - A file in a layer's tree.
+ * @returns {Promise<string|null>} Null when there is no such file.
+ */
+export async function readLayerText(path) {
+  const text = await readFile(path, 'utf8').catch(() => null);
+  return text === null ? null : text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+}
+
 /**
  * Reads the fragments one layer declares for one file.
  *
@@ -254,7 +310,7 @@ export async function walk(dir) {
  */
 async function readFragments(path) {
   const bySlot = new Map();
-  const text = await readFile(path, 'utf8').catch(() => null);
+  const text = await readLayerText(path);
   if (text === null) return bySlot;
   let current = null;
   const buffer = [];
@@ -350,7 +406,7 @@ export function projectOwned(target, paths) {
     }
     const stamped = p.endsWith('.md') || SCRIPT.test(p);
     // Read without following links, a link is not a file: it is the project's, whatever it points at.
-    if (!entry.isFile() || (stamped && !readFileSync(join(target, p), 'utf8').includes('nina:generated'))) out.push(p);
+    if (!entry.isFile() || (stamped && noticeOf(readFileSync(join(target, p), 'utf8')) === null)) out.push(p);
   }
   return out.sort();
 }
@@ -366,13 +422,15 @@ export function projectOwned(target, paths) {
  * @param {string} target - The project directory.
  * @param {{root: string}} ctx - CLI context; `root` is the NINA install directory.
  * @param {{check?: boolean}} [options] - `check` compares without writing.
- * @returns {Promise<{error?: string, written: string[], differ: string[], unfilled: string[], skipped: string[]}>}
+ * @returns {Promise<{error?: string, written: string[], differ: string[], unfilled: string[], skipped: string[], removed?: string[]}>}
  */
 export async function composeProject(target, ctx, options = {}) {
   const check = options.check === true;
   const written = [];
   const differ = [];
   const skipped = [];
+  /** Files composed for a surface this profile no longer declares, moved to {@link REMOVED}. */
+  const removed = [];
 
   const profilePath = join(target, HARNESS, 'profile.json');
   if (!existsSync(profilePath)) {
@@ -425,9 +483,23 @@ export async function composeProject(target, ctx, options = {}) {
     if (requires) {
       core = core.slice(requires[0].length);
       if (!surfaces.includes(requires[1])) {
-        // The project has no such surface, so the file does not exist for it.
+        // The project has no such surface, so the file does not exist for it. One composed for it before the
+        // surface left the profile is still dispatched as a stage the graph no longer has, and was reported as
+        // drift that no compose cleared: it goes, with a copy kept. A file there with no notice is the project's.
         skipped.push(rel);
-        if (check && existsSync(dest)) differ.push(`${rel} (present, but no '${requires[1]}' surface)`);
+        let stale = false;
+        try {
+          stale = lstatSync(dest).isFile() && noticeOf(await readFile(dest, 'utf8')) !== null;
+        } catch {
+          // Not there.
+        }
+        if (stale && check) differ.push(`${rel} (present, but no '${requires[1]}' surface)`);
+        if (stale && !check) {
+          await mkdir(dirname(join(target, REMOVED, rel)), { recursive: true });
+          await writeFile(join(target, REMOVED, rel), await readFile(dest));
+          await rm(dest);
+          removed.push(rel);
+        }
         continue;
       }
     }
@@ -500,7 +572,7 @@ export async function composeProject(target, ctx, options = {}) {
     // A name the project deferred, with its reason, reads as not decided: a stage that meets it asks
     // instead of guessing, and the raw placeholder it would otherwise read looks like an editing slip.
     for (const [name, why] of Object.entries(profile.deferred ?? {})) {
-      if (typeof why === 'string' && why.trim() && /^[A-Z][A-Z0-9_]*$/.test(name)) text = text.split(`{{${name}}}`).join(`[${name}: not decided yet]`);
+      if (typeof why === 'string' && why.trim() && NAME.test(name)) text = text.split(`{{${name}}}`).join(`[${name}: not decided yet]`);
     }
 
     // Only what has a comment syntax the notice knows. A layer that one day composes JSON
@@ -518,7 +590,7 @@ export async function composeProject(target, ctx, options = {}) {
     if (previous !== null && previous !== text) differ.push(rel);
   }
 
-  return { written, differ, unfilled, skipped, malformed };
+  return { written, differ, unfilled, skipped, malformed, removed };
 }
 
 /**
@@ -577,6 +649,10 @@ export async function compose(argv, ctx) {
     return bad === 0 ? 0 : 1;
   }
   console.log(`composed ${result.written.length} file(s) → ${relative(process.cwd(), target) || '.'}`);
+  if (result.removed.length > 0) {
+    console.log(`  removed ${result.removed.length} file(s) composed for a surface this profile no longer declares — a copy of each is in ${REMOVED}/:`);
+    for (const rel of result.removed) console.log(`    ${rel}`);
+  }
   // The one place a pointer to `nina where` costs nothing. Put it in the notice instead and
   // every composed file in every project differs until it recomposes — for a pointer, not a
   // fix. This line is written to no file, so it can say what it likes, and it reaches whoever

package/src/commands/init.mjs

@@ -20,7 +20,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { REQUIRES, SLOT, byVersion, composeProject, composedPaths, defaultedSlots, layerRootFor, projectOwned, walk } from './compose.mjs';
 import { owedDocuments } from './check.mjs';
-import { defaultVocabulary } from '../vocabulary.mjs';
+import { PLACEHOLDER, defaultVocabulary } from '../vocabulary.mjs';
 import { PINK, useColor } from '../banner.mjs';
 import { DETECTABLE, NEEDS } from '../surfaces.mjs';
 
@@ -273,8 +273,17 @@ export async function init(argv, ctx) {
   let previous = null;
   try {
     previous = JSON.parse(readFileSync(join(harness, 'profile.json'), 'utf8'));
-  } catch {
-    // None, or unreadable: there is nothing to keep.
+  } catch (error) {
+    // None: there is nothing to keep. One that is there but cannot be read still holds the pin and every
+    // value the project declared — read as "none", a trailing comma moved the pin to the newest release and
+    // wrote every vocabulary value away.
+    if (error.code !== 'ENOENT') {
+      console.error(
+        `  ${HARNESS}/profile.json cannot be read (${error.message}). Starting over would write a new one over it and keep ` +
+          'nothing it declares — fix it and run this again, or move it aside to start from nothing.\n',
+      );
+      return 1;
+    }
   }
   if (previous?.core && arg('--core') && arg('--core') !== previous.core) {
     console.error(`  ${target} pins ${previous.core}. A pin moves with \`nina upgrade --to ${arg('--core')}\`, which says what the move costs and rolls it back when it fails.\n`);
@@ -341,7 +350,7 @@ export async function init(argv, ctx) {
   const released = await defaultedSlots(resolved.dir);
   for (const { rel, core, fragments } of files) {
     const lines = core.split('\n');
-    for (const [, name] of [core, ...fragments].join('\n').matchAll(/\{\{([A-Z_]+)\}\}/g)) {
+    for (const [, name] of [core, ...fragments].join('\n').matchAll(PLACEHOLDER)) {
       vocabulary.add(name);
     }
     /** The nearest non-empty neighbour, naming it when it is another slot. */

package/src/commands/learn.mjs

@@ -305,11 +305,20 @@ async function answerRequest(target, file, answer) {
  */
 async function close(target, which) {
   const dir = join(target, HARNESS, 'requests');
-  const file = (await readdir(dir).catch(() => [])).find((f) => f === which || join(dir, f) === resolve(target, which) || f.startsWith(which));
-  if (!file) {
-    console.error(`  no request matching ${which} under ${HARNESS}/requests/\n`);
+  const files = (await readdir(dir).catch(() => [])).filter((f) => f.endsWith('.md'));
+  // The name exactly, else a prefix of one — and exactly one, as `requests --answer` asks. A prefix alone let
+  // an empty name match every file: a bare `--close` closed whichever request sorted first and retired its pill.
+  const exact = files.filter((f) => f === which || join(dir, f) === resolve(target, which));
+  const matches = exact.length > 0 ? exact : files.filter((f) => which && f.startsWith(which));
+  if (matches.length !== 1) {
+    console.error(
+      matches.length === 0
+        ? `  no request matching "${which}" under ${HARNESS}/requests/ — \`nina learn\` lists them\n`
+        : `  "${which}" matches ${matches.length} requests — name one:\n${matches.map((f) => `    ${f}`).join('\n')}\n`,
+    );
     return 1;
   }
+  const [file] = matches;
   const fields = frontmatter(await readFile(join(dir, file), 'utf8')) ?? {};
   const { pill } = await answerRequest(target, file, { status: 'closed', retire: true });
   console.log(`  closed ${HARNESS}/requests/${file}`);

package/src/commands/release.mjs

@@ -9,9 +9,10 @@
  * Releases are never rewritten. Fixing a release means cutting the next one.
  */
 
-import { cp, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { cp, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { byVersion } from './compose.mjs';
 
 /** A release name: dotted numbers, so the directory sorts and reads like a version. */
 const VERSION = /^\d+\.\d+\.\d+$/;
@@ -80,11 +81,28 @@ export async function release(argv, ctx) {
     console.error(`  ${version} already exists — a release is immutable; cut the next one.\n`);
     return 1;
   }
+  // Above the newest, or `init` pins something older than what the package says it is, and the package's
+  // version moves backwards with the cut.
+  const newest = (await readdir(join(ctx.root, 'releases'), { withFileTypes: true }).catch(() => []))
+    .filter((e) => e.isDirectory() && VERSION.test(e.name))
+    .map((e) => e.name)
+    .sort(byVersion)
+    .at(-1);
+  if (newest && byVersion(version, newest) < 0) {
+    console.error(`  ${newest} is the newest release — a release is cut above it, not below.\n`);
+    return 1;
+  }
 
-  await mkdir(dest, { recursive: true });
+  // Frozen beside the releases and moved in whole: a cut stopped half-way used to leave a partial release,
+  // immutable by name, which `init` then pinned as the newest.
+  const partial = join(ctx.root, `.release-${version}.partial`);
+  await rm(partial, { recursive: true, force: true });
+  await mkdir(partial, { recursive: true });
   for (const layer of ['core', 'surfaces']) {
-    await cp(join(ctx.root, layer), join(dest, layer), { recursive: true });
+    await cp(join(ctx.root, layer), join(partial, layer), { recursive: true });
   }
+  await mkdir(join(ctx.root, 'releases'), { recursive: true });
+  await rename(partial, dest);
 
   const surfaces = (await readdir(join(dest, 'surfaces'), { withFileTypes: true }))
     .filter((e) => e.isDirectory())

package/src/commands/stats.mjs

@@ -14,13 +14,13 @@
 import { amber, bar, bold, dim, heading, note, pink, stacked } from '../look.mjs';
 import { readFile, readdir } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
-import { createReadStream, existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { closeSync, createReadStream, existsSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
-import { ROLE_TOKENS, isLoopBack, runOf } from '../transcripts.mjs';
+import { ROLE_TOKENS, isLoopBack, runOf, transcriptsOf } from '../transcripts.mjs';
 import { frontmatter, pillFiles } from './pills.mjs';
-import { HARNESS, snapshotsDir } from '../paths.mjs';
+import { HARNESS, slugFor, snapshotsDir } from '../paths.mjs';
 import { defaultVocabulary } from '../vocabulary.mjs';
 import { layerRootFor } from './compose.mjs';
 import { PRICES_AS_OF, costOf } from '../prices.mjs';
@@ -80,17 +80,64 @@ async function load(dir, opts) {
 }
 
 
+/** Directories already found for an encoded name: `stats` asks for the same project many times over. */
+const decoded = new Map();
+
+/**
+ * The directory a project's sessions ran in, as its own transcripts record it: every line carries the
+ * session's `cwd`. Taken only when it encodes back to the same name and is still there.
+ *
+ * @param {string} encoded - A snapshot's project name, which is also its transcript directory's.
+ * @returns {string|null}
+ */
+function recordedDir(encoded) {
+  const dir = transcriptsOf(encoded);
+  let files = [];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+  } catch {
+    return null;
+  }
+  for (const file of files.slice(0, 5)) {
+    let head = '';
+    try {
+      const fd = openSync(join(dir, file), 'r');
+      try {
+        const buffer = Buffer.alloc(64 * 1024);
+        head = buffer.toString('utf8', 0, readSync(fd, buffer, 0, buffer.length, 0));
+      } finally {
+        closeSync(fd);
+      }
+    } catch {
+      continue;
+    }
+    for (const line of head.split('\n')) {
+      let cwd;
+      try {
+        cwd = JSON.parse(line)?.cwd;
+      } catch {
+        continue;
+      }
+      if (typeof cwd === 'string' && slugFor(cwd) === encoded && existsSync(cwd)) return cwd;
+    }
+  }
+  return null;
+}
+
 /**
  * Turns a snapshot's encoded project name back into a directory.
  *
- * The encoding replaces every separator with a dash, so `Code-IA-harness` could be
- * `Code/IA/harness` or `Code/IA-harness` and the string alone cannot say which. The
- * filesystem can, so the split is resolved against it rather than guessed.
+ * The encoding makes every character that is not a letter or a digit a dash, so the name alone cannot say
+ * what it was. The project's transcripts can: each line records the directory its session ran in. Failing
+ * that, the split is resolved against the file system — which can only rebuild `/` from a dash, so a
+ * project whose path held a `.`, a space or an `_` was never found, and its pills, models and requests went
+ * missing from every report without a word.
  *
  * @param {string} encoded - The `project` field of a snapshot record.
  * @returns {string | null} The directory, or `null` when no split of the name exists.
  */
 export function decodeProjectDir(encoded) {
+  if (decoded.has(encoded)) return decoded.get(encoded);
   const parts = encoded.replace(/^-/, '').split('-');
   const walk = (base, i) => {
     if (i === parts.length) return base;
@@ -102,7 +149,10 @@ export function decodeProjectDir(encoded) {
     }
     return null;
   };
-  return walk('/', 0);
+  const found = recordedDir(encoded) ?? walk('/', 0);
+  // Only what was found: a directory made after a miss is found the next time it is asked for.
+  if (found) decoded.set(encoded, found);
+  return found;
 }
 
 /**