@xhulz/nina 0.31.0 → 0.33.0

package/src/commands/compose.mjs

@@ -497,6 +497,11 @@ export async function composeProject(target, ctx, options = {}) {
       if (name in (profile.vocabulary ?? {})) continue;
       text = text.split(`{{${name}}}`).join(value);
     }
+    // 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]`);
+    }
 
     // Only what has a comment syntax the notice knows. A layer that one day composes JSON
     // would be corrupted by it rather than marked, so it gets nothing and says nothing.

package/src/commands/learn.mjs

@@ -28,7 +28,7 @@ import { join, relative, resolve } from 'node:path';
 import { HARNESS, legacyHint, slugFor, snapshotsDir } from '../paths.mjs';
 import { isLoopBack, runOf } from '../transcripts.mjs';
 import { REQUIRES, byVersion, layerRootFor } from './compose.mjs';
-import { GRADUATION_AT, frontmatter, graduationTarget, list, pillFiles, roleGates } from './pills.mjs';
+import { GRADUATION_AT, frontmatter, graduationTarget, list, pillFiles, roleGates, tidyRetired } from './pills.mjs';
 import { decodeProjectDir } from './stats.mjs';
 import { snapshot } from './snapshot.mjs';
 import { loadProject, projectGateDir, readLedger, replay } from '../gate.mjs';
@@ -200,7 +200,7 @@ export function applied(records, known) {
  * rate moves with the work. The control does not remove either, but it shows whether the lesson's
  * roles moved differently from everything else, which the lesson's own numbers cannot.
  *
- * @returns {{rel: string, date: string, before: {n: number, loops: number}, after: {n: number, loops: number}, control: {before: {n: number, loops: number}, after: {n: number, loops: number}}}[]}
+ * @returns {{rel: string, date: string, on: string|null, comparable: boolean, was?: string, before?: {n: number, loops: number}, after?: {n: number, loops: number}, control?: {before: {n: number, loops: number}, after: {n: number, loops: number}}}[]}
  */
 export function verified(records, known) {
   const out = [];
@@ -209,15 +209,28 @@ export function verified(records, known) {
       const s = rs.filter(pick);
       return { n: s.length, loops: s.filter((r) => isLoopBack(r.verdict)).length };
     };
-    const mine = records.filter((r) => lesson.roles.includes(r.role) && readable(r.verdict));
+    const all = records.filter((r) => lesson.roles.includes(r.role) && readable(r.verdict));
     const others = records.filter((r) => r.role && !lesson.roles.includes(r.role) && readable(r.verdict));
     const pre = (r) => day(r.ts) < lesson.date;
     const post = (r) => day(r.ts) > lesson.date;
+    if (rate(all, pre).n < VERIFY_MIN || rate(all, post).n < VERIFY_MIN) continue;
+    // Read on one model and effort level: the one the roles ran on most after the lesson. A lesson written
+    // the week a role moved to a stricter model read as making it worse — one project's reviewer went from
+    // 2% to 29% "after" a lesson, and from Sonnet to Opus in the same days. Where the roles ran on it too
+    // little before the lesson, the two sides are not comparable, and that is said rather than a number.
+    const ranOn = (r) => (r.usage_model ? `${r.usage_model}${r.effort ? ` · ${r.effort}` : ''}` : null);
+    const tally = new Map();
+    for (const r of all.filter(post)) if (ranOn(r)) tally.set(ranOn(r), (tally.get(ranOn(r)) ?? 0) + 1);
+    const on = [...tally].sort((x, y) => y[1] - x[1])[0]?.[0] ?? null;
+    const mine = on ? all.filter((r) => ranOn(r) === on) : all;
     const before = rate(mine, pre);
     const after = rate(mine, post);
-    if (before.n >= VERIFY_MIN && after.n >= VERIFY_MIN) {
-      out.push({ rel: lesson.rel, date: lesson.date, before, after, control: { before: rate(others, pre), after: rate(others, post) } });
+    if (before.n < VERIFY_MIN || after.n < VERIFY_MIN) {
+      const was = [...new Set(all.filter(pre).map(ranOn).filter(Boolean))].join(', ') || 'no recorded model';
+      out.push({ rel: lesson.rel, date: lesson.date, on, was, comparable: false });
+      continue;
     }
+    out.push({ rel: lesson.rel, date: lesson.date, on, comparable: true, before, after, control: { before: rate(others, pre), after: rate(others, post) } });
   }
   return out;
 }
@@ -242,7 +255,7 @@ export function unfiled(known, filed) {
  * @param {string} target - The project directory.
  * @returns {Promise<{file: string, status: string, pill: string, target: string, date: string}[]>}
  */
-async function filedRequests(target) {
+export async function filedRequests(target) {
   const dir = join(target, HARNESS, 'requests');
   const out = [];
   for (const f of (await readdir(dir).catch(() => [])).filter((f) => f.endsWith('.md'))) {
@@ -279,6 +292,8 @@ async function answerRequest(target, file, answer) {
   const pill = await readFile(join(target, fields.pill), 'utf8');
   const retired = /^status: .*$/m.test(pill) ? pill.replace(/^status: .*$/m, 'status: retired') : pill.replace(/^---\n/, '---\nstatus: retired\n');
   await writeFile(join(target, fields.pill), retired);
+  // And out of the way of the agents that open every pill to see which apply.
+  await tidyRetired(target);
   return { pill: fields.pill };
 }
 
@@ -691,8 +706,13 @@ export async function learn(argv, ctx) {
   for (const r of open) console.log(`            open since ${r.date}: ${r.pill} → ${r.target}. \`nina upgrade\` to the release that answers it closes it`);
   if (checks.length === 0) console.log(`  verify    no lesson has ${VERIFY_MIN}+ readable verdicts on both sides of its date yet`);
   checks.forEach((c, i) => {
+    const head = `  ${i === 0 ? 'verify  ' : '        '}  ${c.rel.replace(/^\.claude\/pills\//, '')} (${c.date})`;
+    if (!c.comparable) {
+      console.log(`${head}: not comparable — the role ran on ${c.on} after it, and before it on ${c.was}`);
+      return;
+    }
     console.log(
-      `  ${i === 0 ? 'verify  ' : '        '}  ${c.rel.replace(/^\.claude\/pills\//, '')} (${c.date}): ` +
+      `${head}${c.on ? `, on ${c.on}` : ''}: ` +
         `${pct(c.before.loops, c.before.n)} → ${pct(c.after.loops, c.after.n)} loop-back (n ${c.before.n} → ${c.after.n}); ` +
         `every other role ${pct(c.control.before.loops, c.control.before.n)} → ${pct(c.control.after.loops, c.control.after.n)}`,
     );

package/src/commands/pills.mjs

@@ -10,11 +10,11 @@
  * This reads the project, never the layers — pills are written at runtime, not composed.
  */
 
-import { readFile, readdir } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rename } from 'node:fs/promises';
 import { HARNESS } from '../paths.mjs';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { REQUIRES, layerRootFor } from './compose.mjs';
 
 /** Fields every pill must carry, and what breaks without each one. */
@@ -33,6 +33,34 @@ const SEVERITIES = ['low', 'medium', 'high'];
 /** The statuses a pill may declare. */
 const STATUSES = ['active', 'retired'];
 
+/**
+ * Where a retired pill goes, beside the directories agents read: every agent opens every pill in its own
+ * directory and in `shared/` to learn which apply, and in the first new project 16 KB of the 33 KB it opened
+ * on every dispatch was retired.
+ */
+export const RETIRED = 'retired';
+
+/**
+ * Moves every retired pill still where agents read it into `retired/<the directory it was read from>/`.
+ *
+ * @param {string} target - The project.
+ * @returns {Promise<string[]>} The pills moved, as paths relative to `.claude/pills/`.
+ */
+export async function tidyRetired(target) {
+  const pillsDir = join(target, '.claude', 'pills');
+  if (!existsSync(pillsDir)) return [];
+  const moved = [];
+  for (const pill of await pillFiles(pillsDir)) {
+    if (!pill.dir || pill.dir === RETIRED || pill.dir.startsWith(`${RETIRED}/`)) continue;
+    if (frontmatter(await readFile(pill.path, 'utf8'))?.status !== 'retired') continue;
+    const to = join(pillsDir, RETIRED, pill.dir, pill.file);
+    await mkdir(dirname(to), { recursive: true });
+    await rename(pill.path, to);
+    moved.push(`${pill.dir}/${pill.file}`);
+  }
+  return moved;
+}
+
 /**
  * How often the same lesson must be learned before it stops being an anecdote.
  *
@@ -184,6 +212,15 @@ export function graduationTarget(applies, gates) {
 export async function pillFiles(pillsDir) {
   const found = [];
   for (const entry of await readdir(pillsDir, { withFileTypes: true })) {
+    // Retired pills keep the directory they were read from, one level down, where no agent globs.
+    if (entry.isDirectory() && entry.name === RETIRED) {
+      for (const inner of await readdir(join(pillsDir, RETIRED), { withFileTypes: true })) {
+        const dir = inner.isDirectory() ? `${RETIRED}/${inner.name}` : RETIRED;
+        const files = inner.isDirectory() ? await readdir(join(pillsDir, dir)) : [inner.name];
+        for (const file of files) if (file.endsWith('.md')) found.push({ dir, file, path: join(pillsDir, dir, file) });
+      }
+      continue;
+    }
     if (entry.isDirectory()) {
       for (const file of await readdir(join(pillsDir, entry.name))) {
         if (file.endsWith('.md')) found.push({ dir: entry.name, file, path: join(pillsDir, entry.name, file) });
@@ -208,6 +245,7 @@ export function validate(pill, text, roles, today) {
   const label = `${pill.dir ? `${pill.dir}/` : ''}${pill.file}`;
   const problems = [];
   const notes = [];
+  const shelved = pill.dir === RETIRED || pill.dir.startsWith(`${RETIRED}/`);
 
   if (pill.dir === '') {
     problems.push(`${label} sits at the top level of pills/ — no agent globs there, so nobody reads it`);
@@ -224,6 +262,14 @@ export function validate(pill, text, roles, today) {
   }
 
   const applies = list(fields.applies_to);
+  // Where a retired pill sits says only where it was read from, and nobody reads it there now.
+  if (shelved) {
+    if (fields.status !== 'retired') problems.push(`${label} is ${fields.status || 'active'} but sits in ${RETIRED}/, where no agent reads it — move it back, or retire it`);
+    return { problems, notes, fields, label, citations: [], uncited: false };
+  }
+  if (fields.status === 'retired') {
+    notes.push(`${label} is retired but still where agents open it — \`nina pills --tidy\` moves it to ${RETIRED}/${pill.dir}/`);
+  }
   for (const role of applies) {
     if (!roles.includes(role)) {
       problems.push(`${label} applies_to "${role}", which this project does not compose — available: ${roles.join(', ')}`);
@@ -306,6 +352,12 @@ export async function pills(argv, ctx) {
     .sort();
 
   const today = new Date().toISOString().slice(0, 10);
+  if (argv.includes('--tidy')) {
+    const moved = await tidyRetired(target);
+    for (const m of moved) console.log(`  moved ${m} → ${RETIRED}/${m}`);
+    console.log(moved.length ? `\npills: ${moved.length} retired pill(s) moved where no agent opens them\n` : 'pills: no retired pill where agents read\n');
+    return 0;
+  }
   const files = existsSync(pillsDir) ? await pillFiles(pillsDir) : [];
 
   // The directory itself is composed, so its presence says nothing. An empty corpus is the

package/src/commands/runs.mjs

@@ -0,0 +1,129 @@
+/**
+ * `nina runs` — what each piece of work cost: the pipeline's cycles in one project, newest first, each with
+ * the stages it went through, their rounds, what was sent back, how long it took and what it cost.
+ *
+ * `stats` answers per stage and over a window, which is the right question for a gate and the wrong one for
+ * the owner, whose question is what a feature, a spike or a fix came to. A cycle is the unit `stats` already
+ * sizes (`cyclesOf`): a session's rounds up to the verdict that closes one. It is named by the description
+ * the orchestrator gave its first dispatch, which is the one name the record keeps.
+ *
+ *   nina runs [--project <dir>] [--last N] [--since YYYY-MM-DD]
+ */
+
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { HARNESS } from '../paths.mjs';
+import { costOf } from '../prices.mjs';
+import { isLoopBack, runOf } from '../transcripts.mjs';
+import { amber, bold, dim, pink } from '../look.mjs';
+import { storedRecords } from './snapshot.mjs';
+import { cyclesOf, projectName } from './stats.mjs';
+
+/** What ended a cycle, in words. */
+const ENDS = {
+  closed: (last) => `ended at ${last.role} ${last.verdict}`,
+  unreadable: (last) => `ended at a ${last.role} whose verdict could not be read`,
+  next: () => 'ended where the next design began',
+  open: () => 'still open where the record ends',
+};
+
+/**
+ * One cycle, summed: when, how long, what it cost, and each stage's rounds and loop-backs in the order the
+ * stages first ran.
+ *
+ * @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) {
+  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);
+  const minutes = Number.isFinite(Date.parse(end) - Date.parse(start)) ? Math.round((Date.parse(end) - Date.parse(start)) / 60_000) : null;
+  let cost = 0;
+  let unpriced = 0;
+  for (const r of rounds) {
+    if (!r.tokens || typeof r.tokens !== 'object') continue;
+    const c = costOf(r.tokens, r.usage_model);
+    if (c === null) unpriced += 1;
+    else cost += c;
+  }
+  const stages = new Map();
+  for (const r of rounds) {
+    const s = stages.get(r.role) ?? { role: r.role, runs: new Set(), rounds: 0, back: 0 };
+    s.runs.add(runOf(r));
+    s.rounds += 1;
+    if (isLoopBack(r.verdict)) s.back += 1;
+    stages.set(r.role, s);
+  }
+  const files = rounds.filter((r) => typeof r.files_touched === 'number').map((r) => r.files_touched);
+  const peaks = rounds.filter((r) => typeof r.context_peak === 'number').map((r) => r.context_peak);
+  return {
+    start,
+    end,
+    minutes,
+    cost,
+    unpriced,
+    name: String(rounds[0]?.desc ?? '').trim() || '(no description)',
+    how: ENDS[cycle.end](rounds.at(-1)),
+    stages: [...stages.values()].map((s) => ({ ...s, runs: s.runs.size })),
+    files: files.length ? Math.max(...files) : null,
+    peak: peaks.length ? Math.max(...peaks) : null,
+  };
+}
+
+/** A duration in minutes, as hours and minutes. */
+const span = (m) => (m === null ? '—' : m >= 60 ? `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}` : `${m}m`);
+
+/** A cost in dollars. */
+const money = (n) => `$${n >= 100 ? n.toFixed(0) : n.toFixed(2)}`;
+
+/**
+ * Runs the command.
+ *
+ * @param {string[]} argv
+ * @returns {Promise<number>}
+ */
+export async function runs(argv) {
+  const arg = (name) => (argv.includes(name) ? argv[argv.indexOf(name) + 1] : null);
+  const dir = resolve(arg('--project') ?? '.');
+  if (!existsSync(join(dir, HARNESS, 'profile.json'))) {
+    console.error(`  no ${HARNESS}/profile.json under ${dir} — run it inside a project, or name one with --project\n`);
+    return 1;
+  }
+  const since = arg('--since');
+  const last = Math.max(1, Number(arg('--last') ?? 10) || 10);
+  const records = (storedRecords(dir) ?? []).filter((r) => r.status !== 'denied' && (!since || String(r.ts).slice(0, 10) >= since));
+  if (records.length === 0) {
+    console.error('  no measured history for this project yet — `nina snapshot` captures it\n');
+    return 1;
+  }
+  const cycles = cyclesOf(records)
+    .map(summarize)
+    .sort((a, b) => b.start.localeCompare(a.start));
+  const shown = cycles.slice(0, last);
+  console.log(
+    `  ${bold(pink(projectName(records[0].project)))} · ${cycles.length} cycle(s)` +
+      dim(`  newest first${cycles.length > shown.length ? `, the last ${shown.length} — --last N for more` : ''}; a cycle runs up to the verdict that closes it`),
+  );
+  for (const c of shown) {
+    const when = `${c.start.slice(0, 10)} ${c.start.slice(11, 16)}`;
+    console.log(`\n  ${pink('▌')} ${bold(when)} · ${span(c.minutes)} · ${bold(money(c.cost))}${c.unpriced ? dim(` + ${c.unpriced} unpriced`) : ''} · ${dim(c.how)}`);
+    console.log(`    ${c.name.length > 96 ? `${c.name.slice(0, 95)}…` : c.name}`);
+    const chain = c.stages.map((s) => {
+      const count = s.rounds > s.runs ? `${s.rounds} rounds` : `${s.rounds}`;
+      return `${pink(s.role)} ${count}${s.back ? amber(`, ${s.back} sent back`) : ''}`;
+    });
+    console.log(
+      `    ${chain.join(dim(' · '))}${c.files === null ? '' : dim(` · largest write ${c.files} file(s)`)}` +
+        (c.peak === null ? '' : dim(` · context up to ${Math.round(c.peak / 1000)}k`)),
+    );
+  }
+  const total = shown.reduce((a, c) => a + c.cost, 0);
+  const costliest = shown.reduce((a, c) => (c.cost > a.cost ? c : a), shown[0]);
+  console.log(
+    `\n  ${shown.length} cycle(s): ${bold(money(total))} in all` +
+      (shown.length > 1 ? `; the costliest, ${money(costliest.cost)}, ${costliest.start.slice(0, 10)} — ${costliest.name.slice(0, 60)}` : '') +
+      '\n',
+  );
+  return 0;
+}

package/src/commands/snapshot.mjs

@@ -8,7 +8,7 @@
  * the transcripts are hundreds of megabytes and growing.
  */
 
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { slugFor, snapshotsDir } from '../paths.mjs';
 import { createReadStream, existsSync, readFileSync, realpathSync } from 'node:fs';
 import { createInterface } from 'node:readline';
@@ -117,6 +117,40 @@ export function storedRecords(dir) {
   return null;
 }
 
+/**
+ * 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.
  *
@@ -155,40 +189,56 @@ export async function snapshot(argv, ctx) {
 
   let totalNew = 0;
   for (const project of targets) {
-    const file = join(outDir, `${project.slug}.jsonl`);
-    const prior = rebuild ? [] : await readRecords(file);
-    const own = rebuild ? {} : await readJson(join(outDir, `${project.slug}.state.json`));
-    const cursors = rebuild ? {} : (own.cursors ?? legacy[project.slug]?.cursors ?? {});
-
-    const scanned = await scanProject(project.dir, { cursors, records: prior });
-    const records = scanned.records.map((r) => ({ project: project.slug, ...r }));
-    if (records.length === 0) continue;
-
-    const fresh = records.length - prior.length;
-    // A prior record can change without the count changing — a field learned after it was
-    // captured, filled in from its transcript — and a write gated on the count alone would
-    // compute the backfill and throw it away.
-    const changed =
-      fresh !== 0 ||
-      prior.length === 0 ||
-      rebuild ||
-      records.some((r, i) => JSON.stringify(r) !== JSON.stringify({ project: project.slug, ...prior[i] }));
-    if (changed) await writeAtomic(file, records);
-    await writeAtomicText(join(outDir, `${project.slug}.state.json`), `${JSON.stringify({ cursors: scanned.cursors, captured: records.length }, null, 2)}\n`);
-    totalNew += Math.max(0, fresh);
-
-    if (!quiet) {
-      const span = `${String(records[0].ts).slice(0, 10)} → ${String(records.at(-1).ts).slice(0, 10)}`;
-      console.log(
-        `  ${project.slug.padEnd(48)} ${String(records.length).padStart(5)} rounds  ` +
-          `${String(fresh).padStart(5)} new  ${span}`,
-      );
+    const release = await lock(join(outDir, `${project.slug}.lock`));
+    if (!release) continue;
+    try {
+      totalNew += await snapshotProject(project, { outDir, rebuild, quiet, legacy });
+    } finally {
+      await release();
     }
   }
 
-
   if (!quiet) {
     console.log(`\n  ${totalNew} new round${totalNew === 1 ? '' : 's'} captured → ${outDir}`);
   }
   return 0;
 }
+
+/**
+ * Snapshots one project, under its lock.
+ *
+ * @returns {Promise<number>} How many rounds it captured that were not on record.
+ */
+async function snapshotProject(project, { outDir, rebuild, quiet, legacy }) {
+  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 prior = rebuild ? [] : await readRecords(file);
+  const own = rebuild ? {} : await readJson(join(outDir, `${project.slug}.state.json`));
+  const cursors = rebuild ? {} : (own.cursors ?? legacy[project.slug]?.cursors ?? {});
+
+  const scanned = await scanProject(project.dir, { cursors, records: prior });
+  const records = scanned.records.map((r) => ({ project: project.slug, ...r }));
+  if (records.length === 0) return 0;
+
+  const fresh = records.length - prior.length;
+  // A prior record can change without the count changing — a field learned after it was
+  // captured, filled in from its transcript — and a write gated on the count alone would
+  // compute the backfill and throw it away.
+  const changed =
+    fresh !== 0 ||
+    prior.length === 0 ||
+    rebuild ||
+    records.some((r, i) => JSON.stringify(r) !== JSON.stringify({ project: project.slug, ...prior[i] }));
+  if (changed) await writeAtomic(file, records);
+  await writeAtomicText(join(outDir, `${project.slug}.state.json`), `${JSON.stringify({ cursors: scanned.cursors, captured: records.length }, null, 2)}\n`);
+  if (!quiet) {
+    const span = `${String(records[0].ts).slice(0, 10)} → ${String(records.at(-1).ts).slice(0, 10)}`;
+    console.log(
+      `  ${project.slug.padEnd(48)} ${String(records.length).padStart(5)} rounds  ` +
+        `${String(fresh).padStart(5)} new  ${span}`,
+    );
+  }
+  return Math.max(0, fresh);
+}

package/src/commands/stats.mjs

@@ -223,6 +223,40 @@ function costReport(records) {
   console.log(bold(`    ${'all stages'.padEnd(20)}${String([...byRole.values()].flat().length).padStart(6)}${''.padStart(10)}${money(total).padStart(10)}`));
 }
 
+/**
+ * How each stage's rounds spent their context: turns, tool calls sent per turn, and the context a turn
+ * re-read when the round began and at its largest. Every turn is billed the whole context again, so the
+ * cost of a round is its turns times its context, and a round that starts where a long one ended pays for
+ * all of it on every turn. The first rounds of a run are set beside the later ones, which are resumes.
+ *
+ * @param {object[]} records - The rounds in the window.
+ */
+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` : '—');
+  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'));
+  console.log(dim(`    ${'stage'.padEnd(20)}${'rounds'.padEnd(8)}${'n'.padStart(4)}${'turns'.padStart(7)}${'calls/turn'.padStart(12)}${'starts at'.padStart(11)}${'peak'.padStart(8)}`));
+  const byRole = new Map();
+  for (const r of shaped) byRole.set(r.role, [...(byRole.get(r.role) ?? []), r]);
+  for (const [role, rounds] of [...byRole].sort((a, b) => b[1].reduce((x, r) => x + r.turns, 0) - a[1].reduce((x, r) => x + r.turns, 0))) {
+    [
+      ['first', rounds.filter((r) => (r.round ?? 1) === 1)],
+      ['resumed', rounds.filter((r) => (r.round ?? 1) > 1)],
+    ].forEach(([label, group], i) => {
+      if (group.length === 0) return;
+      const turns = group.reduce((a, r) => a + r.turns, 0);
+      const calls = group.reduce((a, r) => a + (r.tool_calls ?? 0), 0);
+      const name = i === 0 || !rounds.some((r) => (r.round ?? 1) === 1) ? pink(role) + ' '.repeat(Math.max(20 - role.length, 1)) : ' '.repeat(20);
+      console.log(
+        `    ${name}${dim(label.padEnd(8))}${String(group.length).padStart(4)}${String(median(group.map((r) => r.turns))).padStart(7)}` +
+          `${(calls / turns).toFixed(2).padStart(12)}${k(median(group.map((r) => r.context_start ?? 0))).padStart(11)}${k(median(group.map((r) => r.context_peak ?? 0))).padStart(8)}`,
+      );
+    });
+  }
+}
+
 /**
  * Whether a model a run used is the one a spec declares: an alias (`opus`) names a family — a whole
  * segment of the id, wherever it sits, so `claude-3-sonnet` is a sonnet — anything else names a model
@@ -348,29 +382,15 @@ const WRITERS = new Set(['implementer', 'solidity-dev']);
 const DESIGNERS = new Set(['planner', 'architect']);
 
 /**
- * How the size of a change sat against the weight of the chain it went through: the core's first hard
- * rule, which nothing had measured. A cycle is a session's dispatches up to the verdict that closes one
- * (`CYCLE_ENDS`), so a loop-back's fix rounds stay with the design that preceded them — the owner's own
- * prompts were tried as the boundary first, and every "pode seguir" after a spec cut a pipeline in two.
- * Two more things end a cycle, both found in real sessions: a design stage dispatched after code was
- * written starts the next change — the light chain has no qa to close it, and it was absorbed into the
- * design that followed — unless the verdict before it sent work back, which the graph routes into both
- * designers; and a closing stage whose verdict cannot be read still closes it, counted as unreadable,
- * because a qa run with no verdict line otherwise let one cycle swallow a dozen pipelines. A cycle is
- * sized by the most files any one of its writers wrote, not their sum, so three fix rounds on two files
- * stay two files; and only edits through the edit tools count, so a file written from a shell is missed
- * and the size is a floor.
+ * A session's records cut into cycles: each up to the verdict that closes one, or to the next design stage
+ * after code was written unless a loop-back sent the work there, or to a closing stage whose verdict cannot
+ * be read (see `proportionReport`). What `stats` sizes and `nina runs` prices.
  *
- * It reports a distribution, not verdicts. A critical path is gated in full at any size and cannot be
- * seen from a file count, and one spec legitimately covers sibling steps (`ONE-SPEC`), so a cycle with
- * no architect of its own is not by itself a skipped gate. What the table can show is the shape: how
- * often a design stage ran for a change of one or two files, and how the large changes were carried.
- *
- * @param {object[]} records - The runs in the window.
+ * @param {object[]} records - Records of any number of sessions and projects.
+ * @returns {{runs: object[], end: 'closed'|'unreadable'|'next'|'open'}[]} In the order they happened within
+ *   each session.
  */
-function proportionReport(records, stepLimit = () => null) {
-  const measured = records.filter((r) => WRITERS.has(r.role) && typeof r.files_touched === 'number');
-  if (measured.length === 0) return;
+export function cyclesOf(records) {
   /** @type {Map<string, object[]>} */
   const bySession = new Map();
   for (const r of [...records].sort((a, b) => String(a.ts).localeCompare(String(b.ts)))) {
@@ -398,6 +418,34 @@ function proportionReport(records, stepLimit = () => null) {
     }
     end('open');
   }
+  return cycles;
+}
+
+/**
+ * How the size of a change sat against the weight of the chain it went through: the core's first hard
+ * rule, which nothing had measured. A cycle is a session's dispatches up to the verdict that closes one
+ * (`CYCLE_ENDS`), so a loop-back's fix rounds stay with the design that preceded them — the owner's own
+ * prompts were tried as the boundary first, and every "pode seguir" after a spec cut a pipeline in two.
+ * Two more things end a cycle, both found in real sessions: a design stage dispatched after code was
+ * written starts the next change — the light chain has no qa to close it, and it was absorbed into the
+ * design that followed — unless the verdict before it sent work back, which the graph routes into both
+ * designers; and a closing stage whose verdict cannot be read still closes it, counted as unreadable,
+ * because a qa run with no verdict line otherwise let one cycle swallow a dozen pipelines. A cycle is
+ * sized by the most files any one of its writers wrote, not their sum, so three fix rounds on two files
+ * stay two files; and only edits through the edit tools count, so a file written from a shell is missed
+ * and the size is a floor.
+ *
+ * It reports a distribution, not verdicts. A critical path is gated in full at any size and cannot be
+ * seen from a file count, and one spec legitimately covers sibling steps (`ONE-SPEC`), so a cycle with
+ * no architect of its own is not by itself a skipped gate. What the table can show is the shape: how
+ * often a design stage ran for a change of one or two files, and how the large changes were carried.
+ *
+ * @param {object[]} records - The runs in the window.
+ */
+function proportionReport(records, stepLimit = () => null) {
+  const measured = records.filter((r) => WRITERS.has(r.role) && typeof r.files_touched === 'number');
+  if (measured.length === 0) return;
+  const cycles = cyclesOf(records);
   const rows = [
     { label: '1–2 files', from: 1, to: 2 },
     { label: '3–9 files', from: 3, to: 9 },
@@ -708,6 +756,7 @@ export async function stats(argv, ctx) {
   }
 
   costReport(records.filter((r) => r.status !== 'denied'));
+  contextReport(records.filter((r) => r.status !== 'denied'));
   modelReport(records.filter((r) => r.status !== 'denied'));
   proportionReport(records.filter((r) => r.status !== 'denied'), stepLimitOf(ctx));