@xhulz/nina 0.39.0 → 0.40.0

package/src/commands/runs.mjs

@@ -34,7 +34,7 @@ const ENDS = {
  * @param {{runs: object[], end: string}} cycle
  * @returns {{start: string, end: string, minutes: number|null, cost: number, unpriced: number, name: string, how: string, stages: {role: string, runs: number, rounds: number, back: number}[], files: number|null, peak: number|null}}
  */
-export function summarize(cycle) {
+function summarize(cycle) {
   const rounds = cycle.runs;
   const start = rounds.map((r) => String(r.ts)).sort()[0];
   const end = rounds.map((r) => String(r.result_ts ?? r.ts)).sort().at(-1);

package/src/commands/snapshot.mjs

@@ -8,16 +8,14 @@
  * the transcripts are hundreds of megabytes and growing.
  */
 
-import { copyFile, mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { HARNESS, snapshotsDir } from '../paths.mjs';
 import { decodeProjectDir } from './stats.mjs';
 import { readStoreFile } from '../store.mjs';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { listProjects, scanProject } from '../transcripts.mjs';
-
-/** Where per-project read cursors live, beside the snapshots they describe. */
-const STATE_FILE = '.state.json';
+import { takeLock } from '../lock.mjs';
 
 /**
  * Reads a JSON file, or an empty object when it is missing or unreadable. A state file cut short
@@ -64,40 +62,6 @@ async function writeAtomic(file, records) {
   await rename(tmp, file);
 }
 
-/**
- * Takes a project's lock, or says it is taken. The records and the cursors are written one after the other,
- * and two snapshots of one project at once — a project's own detector and a global hook, both on every
- * Stop — could leave the cursors of the scan that read further beside the records of the one that read less,
- * and whatever lay between was never captured. One that finds the lock taken skips the project: the next
- * snapshot reads from where this one leaves it. A lock names its process, so one left by a snapshot that
- * died is taken over.
- *
- * @param {string} path - The lock file.
- * @returns {Promise<(() => Promise<void>)|null>} Its release, or null when another snapshot holds it.
- */
-async function lock(path) {
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try {
-      const handle = await open(path, 'wx');
-      await handle.writeFile(String(process.pid));
-      await handle.close();
-      return () => rm(path, { force: true });
-    } catch (error) {
-      if (error.code !== 'EEXIST') throw error;
-      const pid = Number(await readFile(path, 'utf8').catch(() => ''));
-      let alive = false;
-      try {
-        alive = pid > 0 && process.kill(pid, 0);
-      } catch (e) {
-        alive = e.code === 'EPERM';
-      }
-      if (alive) return null;
-      await rm(path, { force: true });
-    }
-  }
-  return null;
-}
-
 /**
  * Runs the snapshot.
  *
@@ -115,14 +79,6 @@ export async function snapshot(argv, ctx) {
   const quiet = argv.includes('--quiet');
 
   await mkdir(outDir, { recursive: true });
-  // The cursors used to live in one file shared by every project, rewritten whole and in place.
-  // Two snapshots at once — the global hook and a project's own detector, or two sessions ending
-  // together — each read all of it, updated their own project, and wrote all of it back: the later
-  // writer silently put every other project's cursor back where it had been, and a cursor that
-  // goes back re-reads history. Each project now has its own, beside its records, written by
-  // rename. The shared file is still read, once, so a project's cursor is not lost in the move.
-  const legacy = rebuild ? {} : await readJson(join(outDir, STATE_FILE));
-
   const projects = await listProjects();
   // `--exact` for a caller that knows the slug — a project's own detector. A substring also
   // matched every project nested under it, and snapshotted them all on every turn.
@@ -136,10 +92,13 @@ export async function snapshot(argv, ctx) {
 
   let totalNew = 0;
   for (const project of targets) {
-    const release = await lock(join(outDir, `${project.slug}.lock`));
+    // One at a time per project: the records and the cursors are written one after the other, and two at once could
+    // leave the cursors of the scan that read further beside the records of the one that read less. One that finds
+    // the lock held skips the project, and the next reads from where this one leaves it.
+    const release = await takeLock(join(outDir, `${project.slug}.lock`));
     if (!release) continue;
     try {
-      totalNew += await snapshotProject(project, { outDir, rebuild, quiet, legacy });
+      totalNew += await snapshotProject(project, { outDir, rebuild, quiet });
     } finally {
       await release();
     }
@@ -192,15 +151,18 @@ function pinOf(slug) {
  *
  * @returns {Promise<number>} How many rounds it captured that were not on record.
  */
-async function snapshotProject(project, { outDir, rebuild, quiet, legacy }) {
+async function snapshotProject(project, { outDir, rebuild, quiet }) {
   const file = join(outDir, `${project.slug}.jsonl`);
   // The store is the only copy of history older than the transcripts, and a rebuild re-reads only what is
   // still on disk: the record it replaces is kept beside it first.
   if (rebuild && existsSync(file)) await copyFile(file, `${file}.before-rebuild-${new Date().toISOString().replace(/[:.]/g, '-')}`);
   const stored = readStoreFile(file, { raw: true });
   const prior = rebuild ? [] : stored;
+  // Each project's read cursors live beside its records, written by rename. They once shared one file, rewritten
+  // whole: two snapshots at once each wrote every other project's cursor back where it had been, and a cursor
+  // that goes back re-reads history.
   const own = rebuild ? {} : await readJson(join(outDir, `${project.slug}.state.json`));
-  const cursors = rebuild ? {} : (own.cursors ?? legacy[project.slug]?.cursors ?? {});
+  const cursors = rebuild ? {} : (own.cursors ?? {});
 
   const scanned = await scanProject(project.dir, { cursors, records: prior });
   // With its cursors gone — a state file deleted, or cut short — the transcripts are read again from the start

package/src/commands/stats.mjs

@@ -164,7 +164,7 @@ export function projectName(encoded) {
  * @param {string[]} projects - The encoded project names in the report.
  * @returns {Promise<{total:number, retired:number, undated:number, dates:string[], unresolved:string[]}>}
  */
-export async function harvest(projects) {
+async function harvest(projects) {
   const out = { total: 0, retired: 0, undated: 0, dates: [], unresolved: [] };
   for (const name of projects) {
     const dir = decodeProjectDir(name);
@@ -243,7 +243,6 @@ function costReport(records) {
   if (total === 0) return;
   const money = (n) => `$${n >= 100 ? n.toFixed(0) : n.toFixed(2)}`;
   // The same convention as the duration column beside it: the upper middle of an even count.
-  const median = (xs) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)];
   console.log(
     heading(
       'cost',
@@ -273,7 +272,6 @@ function costReport(records) {
 function contextReport(records) {
   const shaped = records.filter((r) => typeof r.turns === 'number' && r.turns > 0);
   if (shaped.length === 0) return;
-  const median = (xs) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)];
   const k = (n) => (typeof n === 'number' ? `${Math.round(n / 1000)}k` : '—');
   const chars = (xs) => (xs.length ? median(xs).toLocaleString('en-US') : '—');
   console.log(heading('context', 'every turn re-reads the whole context: a round costs its turns times its size, and a resumed one starts where it ended; the prompt it was handed is in characters'));
@@ -362,7 +360,6 @@ function modelReport(records) {
   const changed = [...byRole].filter(([, models]) => models.size > 1).sort(([a], [b]) => a.localeCompare(b));
 
   const money = (n) => `$${n.toFixed(2)}`;
-  const median = (xs) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)];
   const lines = [];
   for (const [role, models] of changed) {
     const ordered = [...models].sort(([, a], [, b]) => String(a[0].ts).localeCompare(String(b[0].ts)));
@@ -431,7 +428,7 @@ const RULE_SINCE = { issues: '0.22.0', stepFiles: '0.28.8' };
  * @param {keyof RULE_SINCE} rule - The rule.
  * @returns {boolean}
  */
-export const ranUnder = (record, rule) => typeof record.core === 'string' && (record.core === 'dev' || byVersion(record.core, RULE_SINCE[rule]) >= 0);
+const ranUnder = (record, rule) => typeof record.core === 'string' && (record.core === 'dev' || byVersion(record.core, RULE_SINCE[rule]) >= 0);
 
 /** The stages that write code, whose runs' file counts size a cycle. */
 export const WRITERS = new Set(['implementer', 'solidity-dev']);
@@ -590,11 +587,13 @@ function stepLimitOf(ctx) {
   };
 }
 
+/** The middle of a list of numbers — the upper one of two — or undefined for none. */
+const median = (xs) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)];
+
 /** Formats a median duration in minutes from a list of seconds. */
 function medianMin(values) {
-  const xs = values.filter((v) => typeof v === 'number' && v >= 0).sort((a, b) => a - b);
-  if (xs.length === 0) return '—';
-  return `${(xs[Math.floor(xs.length / 2)] / 60).toFixed(1)}m`;
+  const xs = values.filter((v) => typeof v === 'number' && v >= 0);
+  return xs.length ? `${(median(xs) / 60).toFixed(1)}m` : '—';
 }
 
 /**

package/src/commands/status.mjs

@@ -14,7 +14,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, resolve } from 'node:path';
-import { HARNESS } from '../paths.mjs';
+import { readProfile } from '../paths.mjs';
 import { costOf } from '../prices.mjs';
 import { runOf } from '../transcripts.mjs';
 import { missingWiring, shippedScripts } from '../wiring.mjs';
@@ -86,12 +86,11 @@ function ago(iso, now) {
  */
 export async function status(argv, ctx) {
   const target = resolve(argv.includes('--project') ? argv[argv.indexOf('--project') + 1] : '.');
-  const profilePath = join(target, HARNESS, 'profile.json');
-  if (!existsSync(profilePath)) {
-    console.error(`  no ${HARNESS}/profile.json under ${target} — run it inside a project, or name one with --project\n`);
+  const { profile, error } = readProfile(target);
+  if (error) {
+    console.error(`  ${error}\n`);
     return 1;
   }
-  const profile = JSON.parse(readFileSync(profilePath, 'utf8'));
   const bin = join(ctx.root, 'bin', 'nina.mjs');
   const now = Date.now();
   const row = (label, text) => console.log(`  ${pink(label.padEnd(10))} ${text}`);

package/src/commands/upgrade.mjs

@@ -9,9 +9,9 @@
  * writes only when told to. Reconciling the fragments is work, and work does not get done by a flag.
  */
 
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
-import { HARNESS, describeMove, interruptedMove, legacyHint, moveJournal, movedFrom } from '../paths.mjs';
+import { describeMove, HARNESS, interruptedMove, movedFrom, moveJournal, readProfile, surfacesIn } from '../paths.mjs';
 import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { REMOVED, composeProject, composedPaths, defaultedSlots, layerRootFor, walk } from './compose.mjs';
@@ -20,7 +20,7 @@ import { filledSlots, projectSlots, referencedVocabulary } from './check.mjs';
 import { EXPECT_ENV } from '../expected.mjs';
 import { closeAnswered } from './learn.mjs';
 import { tidyRetired } from './pills.mjs';
-import { missingFragment, missingWiring, shippedScripts } from '../wiring.mjs';
+import { lacksPackage, missingFragment, missingWiring, shippedScripts } from '../wiring.mjs';
 import { runSteps } from '../steps.mjs';
 import { defaultVocabulary } from '../vocabulary.mjs';
 
@@ -239,12 +239,11 @@ export async function upgrade(argv, ctx) {
   const target = resolve(arg('--project') ?? '.');
   const apply = argv.includes('--apply');
 
-  const profilePath = join(target, HARNESS, 'profile.json');
-  if (!existsSync(profilePath)) {
-    console.error(`  no .nina/profile.json under ${target}${legacyHint(target)}\n`);
+  const { profile, path: profilePath, error } = readProfile(target);
+  if (error) {
+    console.error(`  ${error}\n`);
     return 1;
   }
-  const profile = JSON.parse(await readFile(profilePath, 'utf8'));
 
   // A move stopped half-way comes before anything else asked of this command: its pin may already name the
   // version it was moving to, and "already pins" left the tree half-moved for good.
@@ -290,15 +289,13 @@ export async function upgrade(argv, ctx) {
   }
 
   const surfaces = profile.surfaces ?? [];
-  const available = (await readdir(join(onto.dir, 'surfaces'), { withFileTypes: true }))
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name);
+  const available = (await surfacesIn(onto.dir));
   const gone = surfaces.filter((s) => !available.includes(s));
   const kept = surfaces.filter((s) => available.includes(s));
   // A surface the target release adds that this project's own files show it has. When a stack is split out
   // of a concern — `prisma` out of `db` — its rules go with it, and a project that does not declare it loses
   // them in silence: the rules that were in its specs yesterday are not there after the move.
-  const offeredBefore = (await readdir(join(from.dir, 'surfaces'), { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+  const offeredBefore = (await surfacesIn(from.dir));
   const offered = detected(await walk(target)).filter(
     (d) => available.includes(d.surface) && !offeredBefore.includes(d.surface) && !surfaces.includes(d.surface) && (!NEEDS[d.surface] || kept.includes(NEEDS[d.surface])),
   );
@@ -376,7 +373,7 @@ export async function upgrade(argv, ctx) {
       for (const line of fragment.split('\n')) console.log(`        ${line}`);
     }
     console.log(`      \`nina wire --to ${to} --apply\` merges them. They stay inert until ${to} is pinned, so wiring first is safe.`);
-    if (unwired.some((w) => w.startsWith('@xhulz/nina is not installed'))) {
+    if (lacksPackage(unwired)) {
       console.log('      The package is the one thing `wire` cannot do: `pnpm add -D -E @xhulz/nina`.');
     }
     console.log('');

package/src/commands/where.mjs

@@ -19,10 +19,10 @@
  */
 
 import { existsSync } from 'node:fs';
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { HARNESS, legacyHint } from '../paths.mjs';
-import { REQUIRES, SLOT, defaultedSlots, generatedNotice, layerRootFor } from './compose.mjs';
+import { HARNESS, readProfile, surfacesIn } from '../paths.mjs';
+import { SLOT, closedGate, defaultedSlots, generatedNotice, layerRootFor } from './compose.mjs';
 import { filledSlots, owedDocuments } from './check.mjs';
 import { roleGates } from './pills.mjs';
 
@@ -71,16 +71,9 @@ export async function where(argv, ctx) {
     return 1;
   }
 
-  const profilePath = join(target, HARNESS, 'profile.json');
-  if (!existsSync(profilePath)) {
-    console.error(`  no ${HARNESS}/profile.json under ${target}${legacyHint(target)}\n`);
-    return 1;
-  }
-  let profile;
-  try {
-    profile = JSON.parse(await readFile(profilePath, 'utf8'));
-  } catch (error) {
-    console.error(`  ${profilePath} is not valid JSON — ${error.message}\n`);
+  const { profile, error } = readProfile(target);
+  if (error) {
+    console.error(`  ${error}\n`);
     return 1;
   }
 
@@ -89,9 +82,7 @@ export async function where(argv, ctx) {
     console.error(`  ${resolved.error}\n`);
     return 1;
   }
-  const available = (await readdir(join(resolved.dir, 'surfaces'), { withFileTypes: true }))
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name);
+  const available = (await surfacesIn(resolved.dir));
   const surfaces = (profile.surfaces ?? []).filter((s) => available.includes(s));
 
   console.log(`  ${posix(rel)}\n`);
@@ -99,8 +90,8 @@ export async function where(argv, ctx) {
   const corePath = join(resolved.dir, 'core', 'tree', rel);
   if (existsSync(corePath)) {
     const core = await readFile(corePath, 'utf8');
-    const gate = REQUIRES.exec(core)?.[1] ?? null;
-    if (gate && !surfaces.includes(gate)) {
+    const gate = closedGate(core, surfaces);
+    if (gate) {
       block(`defined in core ${profile.core}, but gated on the "${gate}" surface, which this project
 does not declare — so it is never composed here and is not on disk.
 to get it: add "${gate}" to ${HARNESS}/profile.json and run \`nina compose\`.`);

package/src/commands/wire.mjs

@@ -12,11 +12,9 @@
  *                              hook runs its script only once that script is composed
  */
 
-import { existsSync } from 'node:fs';
-import { readFile, readdir } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
-import { HARNESS, legacyHint } from '../paths.mjs';
-import { applyWiring, missingFragment, missingWiring, shippedScripts, staleHooks } from '../wiring.mjs';
+import { resolve } from 'node:path';
+import { readProfile, surfacesIn } from '../paths.mjs';
+import { applyWiring, lacksPackage, missingFragment, missingWiring, shippedScripts, staleHooks } from '../wiring.mjs';
 import { layerRootFor } from './compose.mjs';
 
 /**
@@ -27,16 +25,9 @@ import { layerRootFor } from './compose.mjs';
 export async function wire(argv, ctx) {
   const arg = (name) => (argv.includes(name) ? argv[argv.indexOf(name) + 1] : null);
   const target = resolve(arg('--project') ?? '.');
-  const profilePath = join(target, HARNESS, 'profile.json');
-  if (!existsSync(profilePath)) {
-    console.error(`  no ${HARNESS}/profile.json under ${target}${legacyHint(target)}\n`);
-    return 2;
-  }
-  let profile;
-  try {
-    profile = JSON.parse(await readFile(profilePath, 'utf8'));
-  } catch (error) {
-    console.error(`  ${profilePath} is not valid JSON — ${error.message}\n`);
+  const { profile, error } = readProfile(target);
+  if (error) {
+    console.error(`  ${error}\n`);
     return 2;
   }
   const version = arg('--to') ?? profile.core;
@@ -45,9 +36,7 @@ export async function wire(argv, ctx) {
     console.error(`  ${resolved.error}\n`);
     return 2;
   }
-  const available = (await readdir(join(resolved.dir, 'surfaces'), { withFileTypes: true }).catch(() => []))
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name);
+  const available = (await surfacesIn(resolved.dir));
   const shipped = await shippedScripts(resolved.dir, (profile.surfaces ?? []).filter((s) => available.includes(s)));
 
   const missing = await missingWiring(target, shipped);
@@ -71,7 +60,7 @@ export async function wire(argv, ctx) {
       for (const line of fragment.split('\n')) console.log(`    ${line}`);
     }
     console.log(`\n  \`nina wire${arg('--to') ? ` --to ${version}` : ''} --apply\` merges them, changing nothing else — a customised command is never touched.`);
-    if (missing.some((m) => m.startsWith('@xhulz/nina is not installed'))) {
+    if (lacksPackage(missing)) {
       console.log('  The package it cannot install: that one is `pnpm add -D -E @xhulz/nina`.');
     }
     console.log(`wire: ${missing.length} missing${stale.length ? `, ${stale.length} to update` : ''}`);

package/src/deep.mjs

@@ -30,7 +30,7 @@ const REPORT_CHARS = 1500;
 /** The default model: grouping sentences, not reviewing code. */
 const MODEL = 'haiku';
 
-export const MAP_SCHEMA = {
+const MAP_SCHEMA = {
   type: 'object',
   properties: {
     causes: {
@@ -45,7 +45,7 @@ export const MAP_SCHEMA = {
   required: ['causes'],
 };
 
-export const REDUCE_SCHEMA = {
+const REDUCE_SCHEMA = {
   type: 'object',
   properties: {
     clusters: {
@@ -134,7 +134,7 @@ export function mapPrompt(batch) {
 }
 
 /** The reduce prompt: the causes grouped, set against the pills already written. */
-export function reducePrompt(causes, known) {
+function reducePrompt(causes, known) {
   return [
     'Below are root causes of work a software pipeline sent back, one per report, and the lessons ("pills") already',
     'written for it. Group the causes that are the same mistake. For each group give the refs, the pill that already',

package/src/gate.mjs

@@ -59,7 +59,7 @@ import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSyn
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { TERMINALS, declaredTokens, parseGraph } from './graph.mjs';
-import { gateDir, slugFor } from './paths.mjs';
+import { gateDir, layerRootFor, readProfile, slugFor } from './paths.mjs';
 import { declaredIssues, isLoopBack, saidToAgent } from './transcripts.mjs';
 import { lessonIndex } from './lessons.mjs';
 
@@ -135,12 +135,11 @@ export function ledgerPath(root, session) {
  * @param {string} [pkg] - The NINA install to look in.
  * @returns {boolean}
  */
-export function pinnedShipsGate(root, pkg = PACKAGE) {
+function pinnedShipsGate(root, pkg = PACKAGE) {
   try {
-    const core = JSON.parse(readFileSync(join(root, '.nina', 'profile.json'), 'utf8')).core;
-    if (typeof core !== 'string' || !/^[A-Za-z0-9._-]+$/.test(core)) return false;
-    const layers = core === 'dev' ? pkg : join(pkg, 'releases', core);
-    return existsSync(join(layers, 'core', 'tree', 'scripts', 'loop-gate.mjs'));
+    const { profile } = readProfile(root);
+    const layers = profile ? layerRootFor(pkg, profile.core) : { error: 'no profile' };
+    return !layers.error && existsSync(join(layers.dir, 'core', 'tree', 'scripts', 'loop-gate.mjs'));
   } catch {
     return false;
   }

package/src/graph.mjs

@@ -102,7 +102,7 @@ export function declaredTokens(spec) {
  * @param {Set<string>} known - Every stage name that could be meant.
  * @returns {Set<string>}
  */
-export function proseRoutes(spec, known) {
+function proseRoutes(spec, known) {
   const routes = new Set();
   for (const m of spec.matchAll(/(?:back to|→)\s+\*\*([A-Za-z-]+)\*\*/g)) {
     const name = m[1].toLowerCase();

package/src/guard.mjs

@@ -21,7 +21,7 @@ import { closeSync, existsSync, openSync, readFileSync, readSync, realpathSync }
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { NOTICE_HEAD, composedPaths, noticeOf } from './commands/compose.mjs';
-import { HARNESS } from './paths.mjs';
+import { HARNESS, layerRootFor, readProfile } from './paths.mjs';
 
 // Read here and by the suites from here; the test itself lives beside the compiler that writes the notice.
 export { NOTICE_HEAD, noticeOf };
@@ -57,7 +57,7 @@ const SPECIAL = new Set(["'", '"', '\\', '#', '\n', '<', '&', ';', '|', '(', ')'
  * @param {string} command
  * @returns {string[][]}
  */
-export function simpleCommands(command) {
+function simpleCommands(command) {
   const text = String(command);
   const commands = [[]];
   const heredocs = [];
@@ -227,13 +227,12 @@ const HEAD_BYTES = 16 * 1024;
  * @param {string} [pkg] - The NINA install to look in.
  * @returns {{layers: string, surfaces: string[]}|null}
  */
-export function pinnedLayers(root, pkg = PACKAGE) {
+function pinnedLayers(root, pkg = PACKAGE) {
   try {
-    const profile = JSON.parse(readFileSync(join(root, HARNESS, 'profile.json'), 'utf8'));
-    if (typeof profile.core !== 'string' || !/^[A-Za-z0-9._-]+$/.test(profile.core)) return null;
-    const layers = profile.core === 'dev' ? pkg : join(pkg, 'releases', profile.core);
-    if (!existsSync(join(layers, 'core', 'tree', 'scripts', 'edit-guard.mjs'))) return null;
-    return { layers, surfaces: Array.isArray(profile.surfaces) ? profile.surfaces : [] };
+    const { profile } = readProfile(root);
+    const layers = profile ? layerRootFor(pkg, profile.core) : { error: 'no profile' };
+    if (layers.error || !existsSync(join(layers.dir, 'core', 'tree', 'scripts', 'edit-guard.mjs'))) return null;
+    return { layers: layers.dir, surfaces: Array.isArray(profile.surfaces) ? profile.surfaces : [] };
   } catch {
     return null;
   }

package/src/langfuse.mjs

@@ -13,10 +13,11 @@
  *
  * Observations go over OpenTelemetry (`/api/public/otel/v1/traces`, OTLP/HTTP as JSON), the path
  * Langfuse's v4 data model takes, with the session and trace attributes on every span, as its guide asks.
- * Verdicts go to `/api/public/scores` as categorical scores. Langfuse keeps what it was first sent: the
+ * Verdicts go as categorical scores, in batches to `/api/public/ingestion`, or one at a time to
+ * `/api/public/scores` where the batch endpoint is gone. Langfuse keeps what it was first sent: the
  * same span id sent again is a second observation, not an update, and every sum counts both; a score is
- * replaced only when its id, name and date all match, and that endpoint takes no date — it stamps the
- * day it is called. So each is sent once, and only for a run that has settled. No dependency: `fetch`
+ * replaced only when its id, name and date all match, and the scores endpoint takes no date — it stamps
+ * the day it is called. So each is sent once, and only for a run that has settled. No dependency: `fetch`
  * is enough.
  */
 
@@ -40,13 +41,13 @@ export const BATCH = 100;
 export const SETTLE_MINUTES = 15;
 
 /** How long a run that never returned is waited for before it is sent as it is. */
-export const UNRETURNED_HOURS = 24;
+const UNRETURNED_HOURS = 24;
 
 /** A stable hex id of a given length, from what it identifies. */
 const hexId = (text, length) => createHash('sha256').update(String(text)).digest('hex').slice(0, length);
 
 /** The trace a dispatch becomes, and the observation at its root. */
-export const traceIdOf = (record) => hexId(`trace|${record.dispatch_id}`, 32);
+const traceIdOf = (record) => hexId(`trace|${record.dispatch_id}`, 32);
 export const spanIdOf = (record) => hexId(record.dispatch_id, 16);
 
 /** An ISO time, as OTLP's nanoseconds since the epoch — a string, since it outgrows a double. */
@@ -230,7 +231,7 @@ export function scoreOf(record) {
 }
 
 /** The OTLP request body for a batch of spans. */
-export function otlpBody(spans) {
+function otlpBody(spans) {
   return {
     resourceSpans: [
       {
@@ -247,8 +248,8 @@ export function otlpBody(spans) {
  * request cut off after Langfuse took it is the one way a span goes twice, so a batch of spans, the one
  * request that carries real weight, gets the longer wait.
  */
-export const REQUEST_MS = 30_000;
-export const SPANS_MS = 120_000;
+const REQUEST_MS = 30_000;
+const SPANS_MS = 120_000;
 
 /** The headers every request carries. */
 const headersFor = ({ publicKey, secretKey }) => ({

package/src/lock.mjs

@@ -0,0 +1,82 @@
+/**
+ * A lock file that names the process holding it, for the commands that must not run twice at once on one
+ * project: two snapshots would leave one's cursors beside the other's records, two exports would send the same
+ * runs twice.
+ *
+ * The file appears with the pid already in it — written aside, then linked into place, which fails when a lock
+ * is there — so it is never read empty and taken for a dead one's. A lock whose process died is removed only by
+ * the taker holding its takeover, and only once it has read the holder again under it: each taker removed it
+ * outright before, after its own read, and the second removed the lock the first had just taken, so both held it.
+ */
+
+import { link, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+/** Whether a process is running. One this user may not signal is running too. */
+function alive(pid) {
+  if (!(pid > 0)) return false;
+  try {
+    return process.kill(pid, 0);
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+/** The pid a lock file names — 0 when it names none — or undefined when there is no file. */
+async function holder(path) {
+  try {
+    return Number(await readFile(path, 'utf8')) || 0;
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+/** A name beside the lock no other taker uses, in this process or another. */
+const aside = (path) => `${path}.${process.pid}.${Math.random().toString(36).slice(2)}`;
+
+/** Puts a file naming this process at `path`, unless one is there. */
+async function place(path) {
+  const mine = aside(path);
+  await writeFile(mine, String(process.pid));
+  try {
+    await link(mine, path);
+    return true;
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    return false;
+  } finally {
+    await rm(mine, { force: true });
+  }
+}
+
+/**
+ * Takes a lock, or says it is held.
+ *
+ * @param {string} path - The lock file.
+ * @returns {Promise<(() => Promise<void>)|null>} Its release, or null when a running process holds it.
+ */
+export async function takeLock(path) {
+  await mkdir(dirname(path), { recursive: true });
+  const takeover = `${path}.takeover`;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    if (await place(path)) return () => rm(path, { force: true });
+    if (alive(await holder(path))) return null;
+    if (!(await place(takeover))) {
+      const taker = await holder(takeover);
+      if (alive(taker)) return null;
+      // A taker that died mid-takeover. One that finished is simply gone: try again.
+      if (taker !== undefined) await rm(takeover, { force: true });
+      continue;
+    }
+    try {
+      // Under the takeover nobody else removes the lock, and nobody can link over it: a lock read now stays what
+      // it is. A missing one does not — a taker may link it in the next instant — so there is nothing to remove.
+      const pid = await holder(path);
+      if (pid !== undefined && !alive(pid)) await rm(path, { force: true });
+    } finally {
+      await rm(takeover, { force: true });
+    }
+  }
+  return null;
+}