@xhulz/nina 0.38.0 → 0.40.0

package/src/commands/pipeline.mjs

@@ -13,7 +13,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { dim, pink } from '../look.mjs';
-import { HARNESS } from '../paths.mjs';
+import { readProfile } from '../paths.mjs';
 import { TERMINALS, parseGraph } from '../graph.mjs';
 import { required } from '../tools.mjs';
 import { isLoopBack, runOf } from '../transcripts.mjs';
@@ -33,7 +33,7 @@ const HISTORY_DAYS = 30;
  * @param {string} text - The composed `.claude/graph.md`.
  * @returns {Map<string, string>}
  */
-export function stageWords(text) {
+function stageWords(text) {
   const out = new Map();
   let inStages = false;
   for (const line of text.split('\n')) {
@@ -210,12 +210,8 @@ export async function pipeline(argv) {
   const shownStage = (s) => `${name(s)}${many.has(s) ? ' ×n' : ''}`;
   const padName = (s, n) => `${name(s)}${' '.repeat(Math.max(n - s.length, 1))}`;
 
-  let profile = {};
-  try {
-    profile = JSON.parse(readFileSync(join(dir, HARNESS, 'profile.json'), 'utf8'));
-  } catch {
-    // A pipeline composed by hand draws all the same; only the header has less to say.
-  }
+  // A pipeline composed by hand draws all the same; only the header has less to say.
+  const profile = readProfile(dir).profile ?? {};
   const surfaces = (profile.surfaces ?? []).slice().sort();
   console.log(`  pipeline · ${basename(dir)}${profile.core ? ` · core ${profile.core}` : ''}${surfaces.length ? ` · surfaces ${surfaces.join(', ')}` : ''}`);
 

package/src/commands/release.mjs

@@ -13,6 +13,7 @@ import { cp, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/pro
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { byVersion } from './compose.mjs';
+import { surfacesIn } from '../paths.mjs';
 
 /** A release name: dotted numbers, so the directory sorts and reads like a version. */
 const VERSION = /^\d+\.\d+\.\d+$/;
@@ -104,9 +105,7 @@ export async function release(argv, ctx) {
   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())
-    .map((e) => e.name);
+  const surfaces = (await surfacesIn(dest));
   const bumped = await bumpPackage(ctx.root, version);
 
   console.log(`  released ${version} — core + ${surfaces.length} surfaces (${surfaces.join(', ')})`);

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

@@ -54,11 +54,12 @@
  * gate that could block work on its own crash would be worse than the loops it exists to stop.
  */
 
+import { spawnSync } from 'node:child_process';
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 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';
 
@@ -134,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;
   }
@@ -432,7 +432,18 @@ export function replay(entries, loops, forward = new Map()) {
       }
     }
   });
-  return { effect: (to) => effect(to, entries.length), rounds: made };
+  // What is open when the replay ends: each loop with its rounds, the rounds the owner's replies gave it and the
+  // issues it counted by, and each loop-back no fix has acted on yet — what a compaction takes from the orchestrator.
+  const open = [...streak.entries()]
+    .filter(([key]) => key.split('|').length === 2)
+    .map(([key, s]) => {
+      const [source, token] = key.split('|');
+      const cap = Math.max(0, ...(loops.get(source)?.get(token)?.values() ?? []));
+      const issues = [...streak.keys()].filter((k) => k.startsWith(`${key}|`)).map((k) => k.slice(key.length + 1));
+      return { source, token, rounds: s.n, cap, given: grace.get(key) ?? 0, issues };
+    });
+  const waiting = [...pending.entries()].flatMap(([source, batch]) => batch.filter((v) => isLoopBack(v.verdict)).map((v) => ({ source, verdict: v.verdict, issues: v.issues ?? [] })));
+  return { effect: (to) => effect(to, entries.length), rounds: made, open, waiting };
 }
 
 /**
@@ -660,6 +671,40 @@ function onPre(input, project, path, at) {
   return confirmation(worst);
 }
 
+/**
+ * What the gate hands the orchestrator after its conversation was compacted: the loops still open and the
+ * loop-backs waiting on a fix, the latest dispatches, where the checkout stands, and the two documents to read
+ * again. The graph and the router are read once, at a session's start, and a compaction drops them with every
+ * report; the router told the orchestrator to write "round 2 of max 2" in a dispatch so "you after a
+ * compaction" could see it, and after a compaction it sees only a summary.
+ *
+ * @param {object} project - `loadProject`'s.
+ * @param {string} path - The session's ledger.
+ * @param {string} root - The project.
+ * @returns {object}
+ */
+function afterCompaction(project, path, root) {
+  const entries = readLedger(path);
+  const { open, waiting } = replay(entries, project.loops, project.forward);
+  const lines = ['The conversation was compacted. What the NINA loop gate kept of this session:'];
+  for (const l of open) {
+    lines.push(
+      `- open loop: ${l.source} ${l.token} — ${l.rounds} round(s), capped at ${l.cap}${l.given ? ` and ${l.given} more from the owner's replies` : ''}` +
+        (l.issues.length ? `, issues ${l.issues.join(', ')}` : ''),
+    );
+  }
+  for (const w of waiting) lines.push(`- waiting on a fix: ${w.source} ${w.verdict}${w.issues.length ? `, issues ${w.issues.join(', ')}` : ''}`);
+  if (open.length === 0 && waiting.length === 0) lines.push('- no loop is open');
+  const dispatched = entries.filter((e) => e.k === 'dispatch' && e.role).slice(-4);
+  if (dispatched.length) lines.push(`- the latest dispatches: ${dispatched.map((e) => e.role).join(', ')}, the newest at ${String(dispatched.at(-1).at ?? '').slice(11, 16)} UTC`);
+  const git = (...args) => spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', timeout: 2000 }).stdout?.trim() ?? '';
+  const branch = git('rev-parse', '--abbrev-ref', 'HEAD');
+  const last = git('log', '-1', '--format=%h %s');
+  if (branch) lines.push(`- the checkout: branch ${branch}${last ? `, last commit ${last.slice(0, 100)}` : ''}`);
+  lines.push('Before the next dispatch, read .claude/graph.md and .claude/router.md again: they were read at the start of the session, and are no longer in your context.');
+  return { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: lines.join('\n') } };
+}
+
 /** Drops a project's ledgers nobody has written to in a month, and error lines older than a week. */
 function prune(root, now) {
   const dir = projectGateDir(root);
@@ -719,6 +764,8 @@ export function handle(input, { root, now = new Date(), pkg = PACKAGE }) {
         return null;
       case 'SubagentStop':
         return onStop(input, project, path, at);
+      case 'SessionStart':
+        return input.source === 'compact' ? afterCompaction(project, path, root) : null;
       case 'SubagentStart': {
         // Not the loop's business, but the one hook every stage passes through as it begins: its lessons. Claude
         // Code reads `additionalContext` from this event's `hookSpecificOutput` into the subagent's context as it

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();