@xhulz/nina 0.28.21 → 0.29.0

package/src/commands/compose.mjs

@@ -19,7 +19,7 @@
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { HARNESS, legacyHint } from '../paths.mjs';
 import { expectedUnfilled } from '../expected.mjs';
-import { existsSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { defaultVocabulary } from '../vocabulary.mjs';
 
@@ -327,6 +327,34 @@ export async function composedPaths(layerRoot, surfaces = []) {
   return out;
 }
 
+/**
+ * The files of the project's own that sit where the harness composes one: a CLAUDE.md or an agent spec
+ * written by hand before the harness arrived, or a symlink, which a compose would write through. A file
+ * that carries a notice can say it was composed; one with no notice where every composed file of its kind
+ * has one is the project's, and composing over it would destroy it. `init` refused to compose over one and
+ * told the owner to move it aside and run `compose` — which then wrote over whatever was still there, with
+ * no copy kept; so did every compose after a surface was added to a profile by hand.
+ *
+ * @param {string} target - The project.
+ * @param {Iterable<string>} paths - Paths the harness composes, relative to it.
+ * @returns {string[]} The ones in the way, sorted.
+ */
+export function projectOwned(target, paths) {
+  const out = [];
+  for (const p of paths) {
+    let entry;
+    try {
+      entry = lstatSync(join(target, p));
+    } catch {
+      continue;
+    }
+    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);
+  }
+  return out.sort();
+}
+
 /**
  * Composes one project, and reports what it did.
  *
@@ -368,6 +396,22 @@ export async function composeProject(target, ctx, options = {}) {
   /** Layers whose fragments are expected to exist: the declared surfaces, plus the project's own. */
   const declared = new Set([...surfaces, 'project']);
 
+  // Nothing is written while a file of the project's own sits where one would go, so a compose that
+  // refuses leaves the project as it found it.
+  const owned = check ? [] : projectOwned(target, await composedPaths(layerRoot, surfaces));
+  if (owned.length > 0) {
+    return {
+      error:
+        `${owned.length} file(s) of this project's own sit where the harness composes one, and composing would destroy them — ` +
+        `nothing was written:\n${owned.map((p) => `  ${p}`).join('\n')}\n` +
+        `Move each aside, or put its text in ${HARNESS}/project/tree/<the same path> as the fragment that fills its slot, then compose again.`,
+      written,
+      differ,
+      unfilled: [],
+      skipped,
+    };
+  }
+
   /** Slots the core expects a declared layer to fill, and no layer did. */
   const unfilled = [];
   /** Files a `nina:why` marker composed into, unclosed. */

package/src/commands/export.mjs

@@ -26,10 +26,11 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readRun, runFile } from '../agentrun.mjs';
 import { BATCH, SETTLE_MINUTES, postScore, postScores, postSpans, scoreOf, settled, spanOf, spansOf } from '../langfuse.mjs';
-import { transcriptsOf } from '../transcripts.mjs';
+import { runOf, transcriptsOf } from '../transcripts.mjs';
 import { exportsDir, snapshotsDir } from '../paths.mjs';
 import { readConfig, statusPath, targetOf } from './langfuse.mjs';
 import { projectName } from './stats.mjs';
+import { handsToModel } from '../detectors.mjs';
 
 /** The CLI, for the export the detector starts in the background. */
 const BIN = fileURLToPath(new URL('../../bin/nina.mjs', import.meta.url));
@@ -140,7 +141,16 @@ async function keep(slug, sent) {
  *   sends what it does from then on, and its history only when asked.
  */
 export function due(records, sent, now = new Date(), since = '') {
-  const spans = records.filter((r) => r.dispatch_id && !sent.spans[r.dispatch_id] && String(r.ts) >= since && settled(r, now) && spanOf(r, ''));
+  // A round split from a run captured before rounds were, whose first round went while it still held the
+  // whole run's spend: sent now, its tokens would be counted twice. Its first round's record has changed
+  // since it went, which is how it is told.
+  const byId = new Map(records.map((r) => [r.dispatch_id, r]));
+  const sentWhole = (r) => {
+    if (!r.backfilled) return false;
+    const first = byId.get(runOf(r));
+    return Boolean(first && sent.spans[first.dispatch_id] && sent.spans[first.dispatch_id] !== digest(first));
+  };
+  const spans = records.filter((r) => r.dispatch_id && !sent.spans[r.dispatch_id] && String(r.ts) >= since && settled(r, now) && !sentWhole(r) && spanOf(r, ''));
   const going = new Set(spans.map((r) => r.dispatch_id));
   const scores = records.filter((r) => (sent.spans[r.dispatch_id] || going.has(r.dispatch_id)) && !sent.scores[r.dispatch_id] && scoreOf(r));
   const changed = records.filter((r) => sent.spans[r.dispatch_id] && sent.spans[r.dispatch_id] !== digest(r)).length;
@@ -168,7 +178,8 @@ export async function autoExport(slug, records, now = new Date()) {
   const last = JSON.parse(await readFile(statusPath(slug), 'utf8').catch(() => 'null'));
   if (last?.error && !last.reported) {
     finding = `the export to Langfuse failed (${last.at}) — ${last.error}; \`nina langfuse status\` says where it stands`;
-    await writeFile(statusPath(slug), JSON.stringify({ ...last, reported: true }));
+    // Said on every run until the prompt hook hands it to the model, and not after (`handsToModel`).
+    if (handsToModel()) await writeFile(statusPath(slug), JSON.stringify({ ...last, reported: true }));
   }
   const sent = await sentOf(slug);
   if (typeof sent === 'string') return finding ?? sent;
@@ -306,7 +317,7 @@ async function exportProject({ slug, name, file, target, dry, now, since = '', q
   let bytes = 0;
   for (const record of todo.spans) {
     if (error) break;
-    const run = content ? await readRun(runFile(transcriptsOf(slug), record)) : null;
+    const run = content ? await readRun(runFile(transcriptsOf(slug), record), record.round ?? 1) : null;
     if (content && !run) bare += 1;
     let built = spansOf(record, name, run);
     let size = JSON.stringify(built).length;

package/src/commands/gate.mjs

@@ -15,18 +15,22 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { HARNESS, legacyHint, slugFor } from '../paths.mjs';
 import { GATE, hookCommand, missingWiring, shippedScripts } from '../wiring.mjs';
-import { loadProject, projectGateDir, readLedger, runGate } from '../gate.mjs';
+import { LEDGER_TAIL, ledgerPath, loadProject, projectGateDir, readLedger, runGate } from '../gate.mjs';
+import { storedRecords } from './snapshot.mjs';
 import { layerRootFor } from './compose.mjs';
+import { handsToModel } from '../detectors.mjs';
 
 /**
- * The gate's failures a person has not been told about yet, as one sentence, or null. Each failure is
- * reported once: a detector that repeats one transient error on every turn for a day is the noise the
- * detectors exist to remove, and the gate's own log keeps the history.
+ * The gate's failures the model has not been told about yet, as one sentence, or null. Each failure is
+ * reported until the prompt hook hands it over, and not after: a detector that repeats one transient
+ * error on every turn for a day is the noise the detectors exist to remove, and the gate's own log keeps
+ * the history. Spent by the first run that saw it, it was usually spent by the Stop hook, whose line the
+ * model never reads, or by a check run by hand.
  *
  * @param {string} target - The project directory.
  * @returns {string|null}
@@ -50,7 +54,7 @@ function newErrors(target) {
   if (fresh.length === 0) return null;
   const last = fresh.at(-1);
   try {
-    writeFileSync(seenFile, `${last.at}\n`);
+    if (handsToModel()) writeFileSync(seenFile, `${last.at}\n`);
   } catch {
     // Unwritable: it is said again next time, which is better than never.
   }
@@ -60,6 +64,12 @@ function newErrors(target) {
   );
 }
 
+/**
+ * When this check first ran in the project, kept beside its ledgers: what the pipeline did before then
+ * was never the gate's to see, so the live check asks only about what came after.
+ */
+const SINCE = 'checked-since';
+
 /** Whether the gate can write its ledger here. It lets every call through when it cannot. */
 function writable(target) {
   const dir = projectGateDir(target);
@@ -68,12 +78,70 @@ function writable(target) {
     const probe = join(dir, `.selftest-${process.pid}`);
     writeFileSync(probe, '');
     rmSync(probe);
+    if (!existsSync(join(dir, SINCE))) writeFileSync(join(dir, SINCE), `${new Date().toISOString()}\n`);
     return null;
   } catch (error) {
     return `the gate cannot write its ledger in ${dir} — ${error.message}. It lets every call through when it cannot, so no cap is held`;
   }
 }
 
+/** How long after a report the gate is asked whether it saw it: the two are written moments apart. */
+const SETTLE_MS = 120_000;
+
+/** Fewer reports than this in a session, and a miss is not yet a pattern. */
+const LIVE_SAMPLE = 3;
+
+/**
+ * Whether the gate saw what the pipeline actually did — what the dry run cannot answer, since it feeds the
+ * gate events written here, in the shape Claude Code sent when they were written. The gate reads fields
+ * of what Claude Code sends each hook, and the transcripts it writes have changed shape twice under this
+ * harness; were the hooks' payloads to change, the gate would record nothing and let everything through,
+ * and the dry run would still pass. So the reports of the last session with enough of them — each round
+ * whose first line declares a verdict, as the snapshot read it from the transcripts — are set against the
+ * verdicts that session's ledger holds. The gate recording fewer than half of them is a finding.
+ *
+ * @param {string} target - The project directory.
+ * @param {{graph: {stages: Set<string>}, tokens: Map<string, Set<string>>}} project - Its composed graph.
+ * @returns {string|null}
+ */
+function liveness(target, project) {
+  const dir = projectGateDir(target);
+  let since;
+  try {
+    since = readFileSync(join(dir, SINCE), 'utf8').trim();
+  } catch {
+    return null;
+  }
+  const now = Date.now();
+  const reports = (storedRecords(target) ?? []).filter(
+    (r) =>
+      r.verdict_source === 'handback' &&
+      r.session &&
+      project.graph.stages.has(r.role) &&
+      project.tokens.get(r.role)?.has(r.verdict) &&
+      String(r.result_ts) >= since &&
+      now - Date.parse(r.result_ts) > SETTLE_MS,
+  );
+  const bySession = new Map();
+  for (const r of reports) bySession.set(r.session, [...(bySession.get(r.session) ?? []), r]);
+  const last = [...bySession.values()]
+    .filter((rs) => rs.length >= LIVE_SAMPLE)
+    .sort((a, b) => String(a.map((r) => r.result_ts).sort().at(-1)).localeCompare(String(b.map((r) => r.result_ts).sort().at(-1))))
+    .at(-1);
+  if (!last) return null;
+  const path = ledgerPath(target, last[0].session);
+  const entries = readLedger(path);
+  // A ledger too large to read whole is read from its tail; what came before the tail is not asked about.
+  const from = entries.length > 0 && statSync(path).size > LEDGER_TAIL ? String(entries[0].at) : '';
+  const shown = last.filter((r) => String(r.result_ts) >= from).length;
+  const recorded = entries.filter((e) => e.k === 'verdict').length;
+  if (shown < LIVE_SAMPLE || recorded * 2 >= shown) return null;
+  return (
+    `in session ${last[0].session.slice(0, 8)}, the transcripts show ${shown} report(s) with a verdict line and the gate recorded ${recorded}: ` +
+    `Claude Code may have changed what it sends to the hooks, and a loop the gate does not see is not capped (${path})`
+  );
+}
+
 /**
  * Runs the gate the way Claude Code runs it — the command in this project's own settings, through
  * `sh` and whatever `node` is on the PATH — over a whole loop in the shapes Claude Code sends: each
@@ -135,6 +203,15 @@ function dryRun(target) {
     // Reported by the wiring check; the script is run directly instead.
   }
   const command = hookCommand(settings, 'PreToolUse', GATE) ?? `node "${join(target, GATE)}"`;
+  // A hook that runs past its timeout is killed before `finally` can remove its directory; one left by a
+  // run an hour gone is such a one, and goes now.
+  for (const left of readdirSync(tmpdir()).filter((f) => f.startsWith('nina-gate-'))) {
+    try {
+      if (Date.now() - statSync(join(tmpdir(), left)).mtimeMs > 3_600_000) rmSync(join(tmpdir(), left), { recursive: true, force: true });
+    } catch {
+      // Another run's, going as this one looks.
+    }
+  }
   const data = mkdtempSync(join(tmpdir(), 'nina-gate-'));
   try {
     const run = spawnSync('sh', ['-c', command], {
@@ -209,7 +286,8 @@ export async function gate(argv, ctx) {
   const problems = [];
   const composed = existsSync(join(target, GATE));
   if (!composed) problems.push(`${GATE} is not composed — run \`nina compose\``);
-  problems.push(...(await missingWiring(target, new Set([GATE]))));
+  const unwired = await missingWiring(target, new Set([GATE]));
+  problems.push(...unwired);
   const cannotWrite = writable(target);
   if (cannotWrite) problems.push(cannotWrite);
   const failing = newErrors(target);
@@ -218,9 +296,14 @@ export async function gate(argv, ctx) {
     const dry = dryRun(target);
     if (dry) problems.push(dry);
   }
+  // A gate that is not wired sees nothing, and says so above; asked whether it saw the pipeline, it would
+  // say the same thing twice.
+  const project = composed && unwired.length === 0 ? loadProject(target) : null;
+  const blind = project ? liveness(target, project) : null;
+  if (blind) problems.push(blind);
 
   if (problems.length === 0) {
-    console.log(`  wired, writable, no new failure, and a dry run through the hook command sent the round past a cap to the owner — ledgers in ${projectGateDir(target)}`);
+    console.log(`  wired, writable, no new failure, a dry run through the hook command sent the round past a cap to the owner, and it recorded the reports the transcripts show — ledgers in ${projectGateDir(target)}`);
     console.log('gate: current');
     return 0;
   }

package/src/commands/init.mjs

@@ -16,9 +16,9 @@ import { createInterface } from 'node:readline/promises';
 import { HARNESS } from '../paths.mjs';
 import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { applyWiring, missingWiring, shippedScripts } from '../wiring.mjs';
-import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { REQUIRES, SLOT, byVersion, composeProject, composedPaths, defaultedSlots, layerRootFor, walk } from './compose.mjs';
+import { REQUIRES, SLOT, byVersion, composeProject, composedPaths, defaultedSlots, layerRootFor, projectOwned, walk } from './compose.mjs';
 import { owedDocuments } from './check.mjs';
 import { defaultVocabulary } from '../vocabulary.mjs';
 import { PINK, useColor } from '../banner.mjs';
@@ -269,6 +269,20 @@ export async function init(argv, ctx) {
     console.error(`  ${target} already has a .nina/profile.json — pass --force to start over.\n`);
     return 1;
   }
+  // Started over, a project keeps what it had declared and asks again only about its surfaces: `init`
+  // itself says to re-run with --force to add one, and doing so used to write a profile from nothing —
+  // every vocabulary value and integration gone, and the pin moved to the newest release past every
+  // check `upgrade` makes.
+  let previous = null;
+  try {
+    previous = JSON.parse(readFileSync(join(harness, 'profile.json'), 'utf8'));
+  } catch {
+    // None, or unreadable: there is nothing to keep.
+  }
+  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`);
+    return 1;
+  }
 
   const tree = await walk(target);
   // Kept as the matched entries, not just their names: the summary prints WHY each surface was
@@ -284,7 +298,7 @@ export async function init(argv, ctx) {
     .filter((e) => e.isDirectory())
     .map((e) => e.name)
     .sort(byVersion);
-  const core = arg('--core') ?? releases.at(-1) ?? 'dev';
+  const core = arg('--core') ?? previous?.core ?? releases.at(-1) ?? 'dev';
   const resolved = layerRootFor(ctx.root, core);
   if (resolved.error) {
     console.error(`  ${resolved.error}\n`);
@@ -357,12 +371,19 @@ export async function init(argv, ctx) {
   const defaults = defaultVocabulary(resolved.dir);
   const defaulted = [...vocabulary].filter((name) => name in defaults).sort();
   for (const name of defaulted) vocabulary.delete(name);
+  // What the profile being replaced had filled in, for a name these layers still use or one the release
+  // defaults and the project had chosen its own value for.
+  const kept = Object.entries(previous?.vocabulary ?? {}).filter(([name, value]) => value !== null && value !== undefined && (vocabulary.has(name) || name in defaults));
+  for (const [name] of kept) vocabulary.delete(name);
+  const keptIntegrations = surfaces.includes('integrations') && Array.isArray(previous?.integrations) ? previous.integrations : [];
 
   const profile = {
     core,
     surfaces,
-    ...(surfaces.includes('integrations') ? { integrations: [] } : {}),
-    vocabulary: Object.fromEntries([...vocabulary].sort().map((name) => [name, null])),
+    ...(surfaces.includes('integrations') ? { integrations: keptIntegrations } : {}),
+    vocabulary: Object.fromEntries([...[...vocabulary].map((name) => [name, null]), ...kept].sort(([a], [b]) => a.localeCompare(b))),
+    // Anything else the profile said is the project's, and stays.
+    ...Object.fromEntries(Object.entries(previous ?? {}).filter(([key]) => !['core', 'surfaces', 'integrations', 'vocabulary'].includes(key))),
   };
 
   await mkdir(join(harness, 'project', 'tree'), { recursive: true });
@@ -379,16 +400,7 @@ export async function init(argv, ctx) {
   // Files of the project's own where the harness composes one: a CLAUDE.md or an agent spec written by
   // hand before the harness arrived — the adoption case — or a symlink, which compose would write
   // through. Composing over them would destroy them, so they hold the compose back and are named.
-  const inTheWay = [];
-  for (const p of await composedPaths(resolved.dir, surfaces)) {
-    let entry = null;
-    try {
-      entry = lstatSync(join(target, p));
-    } catch {
-      continue;
-    }
-    if (entry.isSymbolicLink() || !entry.isFile() || !readFileSync(join(target, p), 'utf8').includes('nina:generated')) inTheWay.push(p);
-  }
+  const inTheWay = projectOwned(target, await composedPaths(resolved.dir, surfaces));
 
   const cut = (s) => (s.length > 96 ? `${s.slice(0, 96)}…` : s);
   const owed = await owedDocuments(resolved.dir, surfaces);
@@ -532,6 +544,13 @@ export async function init(argv, ctx) {
   }
 
   console.log(`  initialised ${target}\n`);
+  if (previous) {
+    console.log(
+      `    kept from the profile it replaced: the pin ${core}, ${kept.length} vocabulary value(s)` +
+        (surfaces.includes('integrations') ? `, ${keptIntegrations.length} integration(s)` : '') +
+        '\n',
+    );
+  }
   if (!asked && !canAsk) {
     const greenfield = tree.filter((f) => !f.startsWith('.git') && !f.startsWith(HARNESS)).length === 0;
     if (greenfield) {

package/src/commands/learn.mjs

@@ -26,7 +26,7 @@ import { existsSync, readdirSync } from 'node:fs';
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { join, relative, resolve } from 'node:path';
 import { HARNESS, legacyHint, slugFor, snapshotsDir } from '../paths.mjs';
-import { isLoopBack } from '../transcripts.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 { decodeProjectDir } from './stats.mjs';
@@ -35,6 +35,7 @@ import { loadProject, projectGateDir, readLedger, replay } from '../gate.mjs';
 import { GATE, shippedScripts } from '../wiring.mjs';
 import { deepLearn, transcriptsOf } from '../deep.mjs';
 import { autoExport } from './export.mjs';
+import { beforeModel } from '../detectors.mjs';
 
 /** Loop-backs from one role, since its newest lesson, that make a lesson overdue. */
 export const CAPTURE_AT = 3;
@@ -172,13 +173,17 @@ export function overdue(records, known, now = new Date(), days = CAPTURE_DAYS) {
  */
 export function applied(records, known) {
   const taught = new Set(known.filter((l) => !l.retired).flatMap((l) => l.roles));
-  // Only records captured after the field existed can answer; the rest are unknown, not "no".
-  const measured = records.filter((r) => taught.has(r.role) && 'lessons_read' in r);
+  // Only records captured after the field existed can answer; the rest are unknown, not "no". Asked of
+  // runs, not rounds: a lesson a run read in its first round is in front of it in every round after.
+  const runs = new Map();
+  for (const r of records.filter((r) => taught.has(r.role) && 'lessons_read' in r)) runs.set(runOf(r), [...(runs.get(runOf(r)) ?? []), r]);
+  const measured = [...runs.values()];
+  const read = (rounds) => rounds.some((r) => r.lessons_read > 0);
   return {
     measured: measured.length,
-    read: measured.filter((r) => r.lessons_read > 0).length,
-    listed: measured.filter((r) => !(r.lessons_read > 0) && r.lessons_listed).length,
-    from: measured.map((r) => day(r.ts)).sort()[0] ?? null,
+    read: measured.filter(read).length,
+    listed: measured.filter((rounds) => !read(rounds) && rounds.some((r) => r.lessons_listed)).length,
+    from: measured.map((rounds) => day(rounds[0].ts)).sort()[0] ?? null,
   };
 }
 
@@ -598,7 +603,11 @@ export async function learn(argv, ctx) {
     const stuck = owed
       .filter((l) => l.roles.length === 0)
       .map((lesson) => ({ lesson, why: 'names no role in applies_to, so no layer can take it', fix: 'fix its frontmatter — `nina pills` says what is wrong' }));
-    for (const lesson of owed.filter((l) => l.roles.length > 0)) {
+    // Sent from the Stop hook, a request was news only the person heard: its one line said the model would
+    // be told, and by the next message the lesson was no longer owed, so nothing told it. It is sent by the
+    // run that hands its findings to the model, or by hand; the Stop hook says it is about to go.
+    const due = beforeModel() ? owed.filter((l) => l.roles.length > 0) : [];
+    for (const lesson of beforeModel() ? [] : owed.filter((l) => l.roles.length > 0)) {
       // A detector that throws is reported as one that could not run, every turn, and takes the
       // rest of its findings with it — so a request that cannot be written is a finding instead.
       try {
@@ -607,7 +616,7 @@ export async function learn(argv, ctx) {
         stuck.push({ lesson, why: `could not be written to ${HARNESS}/requests/ — ${error.message}`, fix: `make it writable, or send it by hand: \`nina learn --graduate ${lesson.rel}\`` });
       }
     }
-    if (late.length === 0 && sent.length === 0 && stuck.length === 0 && !exported) {
+    if (late.length === 0 && sent.length === 0 && due.length === 0 && stuck.length === 0 && !exported) {
       console.log('learn: current');
       return 0;
     }
@@ -624,6 +633,9 @@ export async function learn(argv, ctx) {
       console.log(`  ${s.lesson.rel} has recurred ${s.lesson.occurrences} times — sent to the harness as ${HARNESS}/requests/${s.file}, proposing a rule in ${s.layer}`);
       console.log('    → commit it with the pill; nothing else is owed here. `nina upgrade` to the release that answers it closes it and retires the pill');
     }
+    for (const lesson of due) {
+      console.log(`  ${lesson.rel} has recurred ${lesson.occurrences} times — it goes to the harness as a request before your next message`);
+    }
     for (const s of stuck) {
       console.log(`  ${s.lesson.rel} has recurred ${s.lesson.occurrences} times and ${s.why}`);
       console.log(`    → ${s.fix}`);
@@ -633,6 +645,7 @@ export async function learn(argv, ctx) {
       `learn: ${[
         late.length && `${late.length} role(s) keep being sent back with nothing written down`,
         sent.length && `${sent.length} lesson(s) sent to the harness`,
+        due.length && `${due.length} lesson(s) to send to the harness`,
         stuck.length && `${stuck.length} lesson(s) cannot be sent`,
         exported && 'the Langfuse export needs a look',
       ]
@@ -652,7 +665,7 @@ export async function learn(argv, ctx) {
   console.log(`\n  learning — core ${profile.core}\n`);
   console.log(
     records.length
-      ? `  observe   ${records.length} dispatch(es) recorded, ${span}`
+      ? `  observe   ${new Set(records.map(runOf)).size} run(s) in ${records.length} round(s) recorded, ${span}`
       : '  observe   ✗ nothing recorded — no transcripts found for this project, so no link below can be measured',
   );
   if (late.length === 0) console.log(`  capture   ✓ no role has looped back ${CAPTURE_AT}+ times without a lesson in the last ${days} days`);

package/src/commands/pipeline.mjs

@@ -10,14 +10,15 @@
  * back and draws it.
  */
 
-import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { dim, pink } from '../look.mjs';
-import { HARNESS, slugFor, snapshotsDir } from '../paths.mjs';
+import { HARNESS } from '../paths.mjs';
 import { TERMINALS, parseGraph } from '../graph.mjs';
 import { required } from '../tools.mjs';
-import { isLoopBack } from '../transcripts.mjs';
+import { isLoopBack, runOf } from '../transcripts.mjs';
 import { frontmatter } from './pills.mjs';
+import { storedRecords } from './snapshot.mjs';
 
 /** A stage line under "## Stages": "- `name` — what it does". */
 const STAGE_LINE = /^- `([a-z][a-z-]*)` — (.*)$/;
@@ -133,19 +134,24 @@ export function pickShape(shapes, query) {
 }
 
 /**
- * What each stage did since a date, from the measurement store: its runs, the verdicts that could be read,
- * and how many of those sent work back. A run a hook denied never ran, and is not counted.
+ * What each stage did since a date, from the measurement store: its runs, their rounds, the verdicts that
+ * could be read, and how many of those sent work back. A run a hook denied never ran, and is not counted.
  *
- * @param {object[]} records - The project's records.
+ * @param {object[]} records - The project's records, one per round.
  * @param {string} since - An ISO date.
- * @returns {Map<string, {runs: number, read: number, back: number}>}
+ * @returns {Map<string, {runs: number, rounds: number, read: number, back: number}>}
  */
 export function historyOf(records, since) {
   const byRole = new Map();
+  const seen = new Map();
   for (const r of records) {
     if (!r.role || r.status === 'denied' || String(r.ts ?? '') < since) continue;
-    const s = byRole.get(r.role) ?? { runs: 0, read: 0, back: 0 };
-    s.runs += 1;
+    const s = byRole.get(r.role) ?? { runs: 0, rounds: 0, read: 0, back: 0 };
+    const runs = seen.get(r.role) ?? new Set();
+    runs.add(runOf(r));
+    seen.set(r.role, runs);
+    s.runs = runs.size;
+    s.rounds += 1;
     if (r.verdict && r.verdict !== 'UNCLEAR' && r.verdict !== 'NONE') {
       s.read += 1;
       if (isLoopBack(r.verdict)) s.back += 1;
@@ -155,37 +161,6 @@ export function historyOf(records, since) {
   return byRole;
 }
 
-/**
- * The project's records in the measurement store, under the name Claude Code gives its directory — as
- * given, or with its links resolved, since either may be the one the sessions ran in.
- *
- * @param {string} dir - The project.
- * @returns {object[]|null} Null when the store has nothing for it.
- */
-function storedRuns(dir) {
-  const names = new Set([slugFor(dir)]);
-  try {
-    names.add(slugFor(realpathSync(dir)));
-  } catch {
-    // A directory that cannot be resolved is looked up as given.
-  }
-  for (const name of names) {
-    const file = join(snapshotsDir(), `${name}.jsonl`);
-    if (!existsSync(file)) continue;
-    return readFileSync(file, 'utf8')
-      .split('\n')
-      .filter(Boolean)
-      .flatMap((l) => {
-        try {
-          return [JSON.parse(l)];
-        } catch {
-          return [];
-        }
-      });
-  }
-  return null;
-}
-
 /**
  * Runs the command.
  *
@@ -309,7 +284,7 @@ export async function pipeline(argv) {
     specs.set(file.replace(/\.md$/, ''), readFileSync(join(agentsDir, file), 'utf8'));
   }
   const since = arg('--since') || new Date(Date.now() - HISTORY_DAYS * 86_400_000).toISOString().slice(0, 10);
-  const runs = storedRuns(dir);
+  const runs = storedRecords(dir);
   const history = runs ? historyOf(runs, since) : null;
   const stages = [...graph.stages].filter((s) => covered.has(s));
   const col = Math.max(...stages.map((s) => s.length), 10) + 2;
@@ -323,7 +298,7 @@ export async function pipeline(argv) {
       const h = history.get(stage);
       const said = !h
         ? 'no run'
-        : `${h.runs} run(s)${h.read === 0 ? ', no verdict read' : `, sent back ${h.back} of ${h.read} (${Math.round((100 * h.back) / h.read)}%)`}`;
+        : `${h.runs} run(s)${h.rounds > h.runs ? ` in ${h.rounds} rounds` : ''}${h.read === 0 ? ', no verdict read' : `, sent back ${h.back} of ${h.read} (${Math.round((100 * h.back) / h.read)}%)`}`;
       console.log(`    ${' '.repeat(col)}${dim('ran     ')}${said}`);
     }
     const skills = [...required(spec).skills].sort();

package/src/commands/snapshot.mjs

@@ -9,8 +9,8 @@
  */
 
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import { snapshotsDir } from '../paths.mjs';
-import { createReadStream } from 'node:fs';
+import { slugFor, snapshotsDir } from '../paths.mjs';
+import { createReadStream, existsSync, readFileSync, realpathSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { join, resolve } from 'node:path';
 import { listProjects, scanProject } from '../transcripts.mjs';
@@ -86,6 +86,37 @@ async function writeAtomic(file, records) {
   await rename(tmp, file);
 }
 
+/**
+ * A project's records in the measurement store, under the name Claude Code gives its directory — as
+ * given, or with its links resolved, since either may be the one the sessions ran in.
+ *
+ * @param {string} dir - The project.
+ * @returns {object[]|null} Null when the store has nothing for it.
+ */
+export function storedRecords(dir) {
+  const names = new Set([slugFor(dir)]);
+  try {
+    names.add(slugFor(realpathSync(dir)));
+  } catch {
+    // A directory that cannot be resolved is looked up as given.
+  }
+  for (const name of names) {
+    const file = join(snapshotsDir(), `${name}.jsonl`);
+    if (!existsSync(file)) continue;
+    return readFileSync(file, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .flatMap((l) => {
+        try {
+          return [JSON.parse(l)];
+        } catch {
+          return [];
+        }
+      });
+  }
+  return null;
+}
+
 /**
  * Runs the snapshot.
  *
@@ -149,7 +180,7 @@ export async function snapshot(argv, ctx) {
     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)} dispatches  ` +
+        `  ${project.slug.padEnd(48)} ${String(records.length).padStart(5)} rounds  ` +
           `${String(fresh).padStart(5)} new  ${span}`,
       );
     }
@@ -157,7 +188,7 @@ export async function snapshot(argv, ctx) {
 
 
   if (!quiet) {
-    console.log(`\n  ${totalNew} new dispatch${totalNew === 1 ? '' : 'es'} captured → ${outDir}`);
+    console.log(`\n  ${totalNew} new round${totalNew === 1 ? '' : 's'} captured → ${outDir}`);
   }
   return 0;
 }