@xhulz/nina 0.31.0 → 0.33.0

package/src/commands/status.mjs

@@ -0,0 +1,150 @@
+/**
+ * `nina status` — one screen for one project: what it pins and what is installed, whether a newer release
+ * is out, whether its hooks are wired and its gate holds, what `check` says, how fresh its measured
+ * history is and what the last week cost, and where its learning stands.
+ *
+ * Each of these had its own command, and the question a person brings — is this project's harness in order,
+ * and is it current — needed six of them. Every line here reads what those commands read, or asks them, so
+ * the screen cannot disagree with them.
+ *
+ *   nina status [--project <dir>] [--offline]
+ */
+
+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 { costOf } from '../prices.mjs';
+import { runOf } from '../transcripts.mjs';
+import { missingWiring, shippedScripts } from '../wiring.mjs';
+import { amber, bold, dim, green, pink } from '../look.mjs';
+import { byVersion, layerRootFor } from './compose.mjs';
+import { filedRequests } from './learn.mjs';
+import { frontmatter, pillFiles } from './pills.mjs';
+import { storedRecords } from './snapshot.mjs';
+
+/** How long the registry gets to say which version is newest; a status is not worth waiting on. */
+const REGISTRY_MS = 3000;
+
+/**
+ * The version of NINA the project has installed, or null.
+ *
+ * @param {string} target
+ * @returns {string|null}
+ */
+function installedVersion(target) {
+  try {
+    const path = createRequire(join(target, 'package.json')).resolve('@xhulz/nina/package.json');
+    return JSON.parse(readFileSync(path, 'utf8')).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The newest version on the registry, or null when it cannot be asked.
+ *
+ * @returns {Promise<string|null>}
+ */
+async function latestVersion() {
+  try {
+    const answer = await fetch('https://registry.npmjs.org/@xhulz%2Fnina/latest', { signal: AbortSignal.timeout(REGISTRY_MS) });
+    return answer.ok ? ((await answer.json()).version ?? null) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The last line a command printed, and whether it passed: what `check` and `gate --selftest` conclude.
+ *
+ * @param {string} bin - This install's entry point.
+ * @param {string[]} args
+ * @returns {{ok: boolean, line: string}}
+ */
+function verdictOf(bin, args) {
+  const run = spawnSync(process.execPath, [bin, ...args, '--quiet'], { encoding: 'utf8', timeout: 120_000 });
+  const lines = `${run.stdout ?? ''}`.split('\n').map((l) => l.trim()).filter(Boolean);
+  return { ok: run.status === 0, line: lines.at(-1) ?? `exit ${run.status}` };
+}
+
+/** How long ago a moment was, in words. */
+function ago(iso, now) {
+  const ms = now - Date.parse(iso);
+  if (!Number.isFinite(ms)) return 'at an unknown time';
+  const h = ms / 3_600_000;
+  return h < 1 ? `${Math.max(1, Math.round(ms / 60_000))} min ago` : h < 48 ? `${Math.round(h)}h ago` : `${Math.round(h / 24)} days ago`;
+}
+
+/**
+ * Runs the command.
+ *
+ * @param {string[]} argv
+ * @param {{root: string}} ctx
+ * @returns {Promise<number>}
+ */
+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`);
+    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}`);
+  let attention = 0;
+  const warn = (text) => {
+    attention += 1;
+    return amber(text);
+  };
+
+  const installed = installedVersion(target);
+  const latest = argv.includes('--offline') ? null : await latestVersion();
+  const pinned = profile.core;
+  const behind = latest && pinned !== 'dev' && byVersion(pinned, latest) < 0;
+  row(
+    'version',
+    `pins ${bold(pinned)} · installed ${installed ? bold(installed) : warn('none — pnpm add -D -E @xhulz/nina')}` +
+      (latest ? ` · newest ${bold(latest)}${behind ? warn(` — \`nina upgrade --to ${latest}\` says what the move costs`) : green(' — current')}` : dim(' · newest unknown (offline)')),
+  );
+
+  const layers = layerRootFor(ctx.root, pinned);
+  if (!layers.error) {
+    const unwired = await missingWiring(target, await shippedScripts(layers.dir, profile.surfaces ?? []));
+    row('hooks', unwired.length === 0 ? green('every hook its release needs is wired') : warn(`${unwired.length} missing — \`nina wire --apply\` merges them`));
+  } else {
+    row('hooks', warn(layers.error));
+  }
+  const gate = verdictOf(bin, ['gate', '--selftest', '--project', target]);
+  row('gate', gate.ok ? green(gate.line) : warn(`${gate.line} — \`nina gate --selftest\` says what`));
+  const check = verdictOf(bin, ['check', '--project', target]);
+  row('check', check.ok ? green(check.line) : warn(`${check.line} — \`nina check\` lists them`));
+
+  const records = storedRecords(target) ?? [];
+  if (records.length === 0) {
+    row('measured', dim('nothing yet — `nina snapshot` captures it'));
+  } else {
+    const latestAt = records.map((r) => String(r.result_ts ?? r.ts)).sort().at(-1);
+    const week = new Date(now - 7 * 86_400_000).toISOString();
+    const recent = records.filter((r) => String(r.ts) >= week);
+    const cost = recent.reduce((a, r) => a + ((r.tokens && costOf(r.tokens, r.usage_model)) || 0), 0);
+    row(
+      'measured',
+      `${new Set(records.map(runOf)).size} runs in ${records.length} rounds, the latest ${ago(latestAt, now)} · last 7 days: ` +
+        `${new Set(recent.map(runOf)).size} runs, ${bold(`$${cost.toFixed(cost >= 100 ? 0 : 2)}`)} at API list prices — \`nina runs\` itemizes it`,
+    );
+  }
+
+  const pillsDir = join(target, '.claude', 'pills');
+  const pills = existsSync(pillsDir) ? await pillFiles(pillsDir) : [];
+  let active = 0;
+  for (const p of pills) if (frontmatter(readFileSync(p.path, 'utf8'))?.status !== 'retired') active += 1;
+  const open = (await filedRequests(target)).filter((r) => r.status === 'open').length;
+  row('learning', `${pills.length} pill(s), ${active} active · ${open} request(s) open with the harness${open ? dim(' — `nina upgrade` to the release that answers one closes it') : ''}`);
+
+  console.log(attention === 0 ? `\n  status: ${green('in order')}\n` : `\n  status: ${attention} thing(s) to look at\n`);
+  return attention === 0 ? 0 : 1;
+}

package/src/commands/upgrade.mjs

@@ -20,6 +20,7 @@ import { NEEDS, detected } from '../surfaces.mjs';
 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 { runSteps } from '../steps.mjs';
 import { defaultVocabulary } from '../vocabulary.mjs';
@@ -36,7 +37,8 @@ const BANNER = /^[\s█╗╔╝║═╚▄▀]*$|harness orchestration ·/;
  * fault — everything else it finds still rolls the move back.
  *
  * @param {string} target - The project.
- * @param {string[]} newSlots - Project slots this move introduces, as `<file> <slot id>`.
+ * @param {string[]} newSlots - Project slots this move introduces, as `<file> <slot id>`, and the
+ *   vocabulary names it introduces, as `{{NAME}}`.
  * @returns {{label: string, args: string[]}[]}
  */
 function validationsFor(target, newSlots = []) {
@@ -235,11 +237,16 @@ export async function upgrade(argv, ctx) {
   const declared = profile.vocabulary ?? {};
   // A name the new release supplies a default for is not owed: it composes as the default until declared.
   const defaultsAfter = defaultVocabulary(onto.dir);
-  const needed = [...vocabAfter].filter((v) => (!(v in declared) && !(v in defaultsAfter)) || declared[v] === null).sort();
+  const waits = (key) => typeof profile.deferred?.[key] === 'string' && profile.deferred[key].trim() !== '';
+  const needed = [...vocabAfter].filter((v) => ((!(v in declared) && !(v in defaultsAfter)) || declared[v] === null) && !waits(v)).sort();
   const unused = Object.keys(declared).filter((v) => !vocabAfter.has(v)).sort();
   // A slot the new release fills itself is not asked of the project: it composes as the release wrote it.
   const defaultedAfter = await defaultedSlots(onto.dir);
   const newSlots = [...slotsAfter].filter((s) => !slotsBefore.has(s) && !filled.has(s) && !defaultedAfter.has(s)).sort();
+  // A name only the new release uses is owed the way a new slot is: it cannot be filled with meaning
+  // before the core that asks for it is pinned, and rolling back for it left no order the move completes in.
+  const newVocab = needed.filter((v) => !vocabBefore.has(v));
+  const awaited = [...newSlots, ...newVocab.map((v) => `{{${v}}}`)];
   const stranded = [...filled].filter((s) => !slotsAfter.has(s)).sort();
 
   console.log(`  ${profile.core} → ${to}\n`);
@@ -355,7 +362,7 @@ export async function upgrade(argv, ctx) {
   // What was already failing is not this upgrade's doing, and rolling back for it would blame
   // the move for a problem the project brought with it. Measured before anything is written,
   // so the only rollback is for something that WAS passing and now is not.
-  const VALIDATIONS = validationsFor(target, newSlots);
+  const VALIDATIONS = validationsFor(target, awaited);
   const DETECTORS = "running the project's own detectors";
   const hasDetectors = await declares(target, 'harness:check');
 
@@ -414,7 +421,7 @@ export async function upgrade(argv, ctx) {
   // `harness:check` — an npm script whose detector list this command does not own and cannot
   // pass an argument to. The environment is what crosses that boundary, and setting it once
   // means a reporter added to the chain later is told without anyone remembering to tell it.
-  if (newSlots.length > 0) process.env[EXPECT_ENV] = newSlots.join(',');
+  if (awaited.length > 0) process.env[EXPECT_ENV] = awaited.join(',');
 
   // Compose writes and never deletes. So the files the new version stops composing are removed right
   // after it composes — before anything is verified, so what is verified is what stays — unless they
@@ -499,6 +506,9 @@ export async function upgrade(argv, ctx) {
         }
       }
     }
+    // Retired pills still where agents open them, from before they had a place of their own.
+    const shelved = await tidyRetired(target).catch(() => []);
+    if (shelved.length > 0) console.log(`\n  moved ${shelved.length} retired pill(s) to .claude/pills/retired/, where no agent opens them: ${shelved.join(', ')}`);
     const lessons = nina(ctx, target, ['learn', '--project', target, '--check']);
     if (!lessons.ok && lessons.out.trim()) {
       console.log('\n  the learning cycle has something to act on — not caused by this move, now visible:');
@@ -511,6 +521,10 @@ export async function upgrade(argv, ctx) {
       console.log(`\n  ${newSlots.length} project slot(s) still to fill — only this project can write them:`);
       for (const s of newSlots) console.log(`      ${s}`);
     }
+    if (newVocab.length > 0) {
+      console.log(`\n  ${newVocab.length} vocabulary name(s) ${to} asks for and this profile does not answer — fill each, or defer it with why:`);
+      console.log(`      ${newVocab.join(', ')}`);
+    }
     console.log('');
     return 0;
   }

package/src/cost.mjs

@@ -0,0 +1,141 @@
+/**
+ * The cost watch: tells a subagent, while it runs, what its own context has come to cost.
+ *
+ * What a run spends is mostly its context read again: every turn re-reads everything the run has built,
+ * so its cost grows faster than its work. Over the first new project's first days, three quarters of the
+ * implementer's spend was cache read, a median 36M tokens a round and 159M at most, and nothing said so
+ * until `stats` read the transcripts afterwards. This runs on every tool call a subagent makes — Claude Code
+ * hands a PostToolUse hook's `additionalContext` to the subagent that made the call — and, each time the
+ * tokens its run has re-read cross a threshold and then each doubling of it, tells the run what each turn
+ * now costs and what to do about it, and tells the person in one line.
+ *
+ * It reads only what the run's transcript gained since its last call, keeps counts per message and
+ * nothing else, under the project's gate directory, and lets every call through if anything goes wrong.
+ */
+
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { projectGateDir } from './gate.mjs';
+
+/** Where a run's counts are kept between calls, one file per agent. */
+const stateDir = (root) => join(projectGateDir(root), 'cost');
+
+/** Runs' counts are dropped this long after their last call: a run does not come back after a week. */
+const KEEP_MS = 7 * 86_400_000;
+
+/**
+ * Reads what a file gained after an offset, up to its last complete line.
+ *
+ * @param {string} path - The transcript.
+ * @param {number} from - The offset already read.
+ * @returns {{text: string, to: number}}
+ */
+function gained(path, from) {
+  const size = statSync(path).size;
+  if (size <= from) return { text: '', to: size < from ? 0 : from };
+  const buffer = Buffer.alloc(size - from);
+  const fd = openSync(path, 'r');
+  try {
+    readSync(fd, buffer, 0, buffer.length, from);
+  } finally {
+    closeSync(fd);
+  }
+  const end = buffer.lastIndexOf(0x0a);
+  if (end === -1) return { text: '', to: from };
+  return { text: buffer.subarray(0, end + 1).toString('utf8'), to: from + end + 1 };
+}
+
+/**
+ * What one call of the watch says, or null: the counts are brought up to date from the run's transcript,
+ * and a warning is due each time the total re-read crosses `warnAt`, then twice it, four times it, and on.
+ *
+ * @param {object} input - The PostToolUse hook's input.
+ * @param {{root: string, warnAt: number, now?: number}} options
+ * @returns {object|null} The hook's answer.
+ */
+export function watch(input, { root, warnAt, now = Date.now() }) {
+  // Only inside a subagent, which is where `agent_id` is set; and an id that could not be a file name is not one.
+  if (input?.hook_event_name !== 'PostToolUse' || !/^[A-Za-z0-9_-]{1,64}$/.test(String(input.agent_id ?? ''))) return null;
+  if (typeof input.transcript_path !== 'string' || typeof input.session_id !== 'string' || !(warnAt > 0)) return null;
+  const transcript = join(dirname(input.transcript_path), input.session_id, 'subagents', `agent-${input.agent_id}.jsonl`);
+  if (!existsSync(transcript)) return null;
+  const dir = stateDir(root);
+  const file = join(dir, `${input.agent_id}.json`);
+  let state = { offset: 0, read: {}, warned: 0 };
+  try {
+    state = { ...state, ...JSON.parse(readFileSync(file, 'utf8')) };
+  } catch {
+    // A run's first call, or its counts lost: read its transcript from the start.
+  }
+  const { text, to } = gained(transcript, state.offset);
+  let last = null;
+  for (const line of text.split('\n')) {
+    if (!line.includes('"cache_read_input_tokens"')) continue;
+    try {
+      const message = JSON.parse(line)?.message;
+      const read = message?.usage?.cache_read_input_tokens;
+      // A streamed message is written once per content block under one id: its last copy counts.
+      if (message?.id && typeof read === 'number') {
+        state.read[message.id] = read;
+        last = read;
+      }
+    } catch {
+      // A torn line loses one message's count.
+    }
+  }
+  state.offset = to;
+  state.at = now;
+  const total = Object.values(state.read).reduce((a, b) => a + b, 0);
+  let crossed = state.warned;
+  while (total >= warnAt * 2 ** crossed) crossed += 1;
+  const due = crossed > state.warned;
+  state.warned = crossed;
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, JSON.stringify(state));
+  if (!due) return null;
+  const m = (n) => `${Math.round(n / 1e6)}M`;
+  const size = (n) => (n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : `${Math.round(n / 1000)}k`);
+  const turn = last === null ? '' : `, and each turn now re-reads about ${size(last)} tokens more`;
+  return {
+    systemMessage: `NINA: ${input.agent_type ?? 'a subagent'} ${input.agent_id.slice(0, 8)} has re-read ${m(total)} tokens of its own context${turn}.`,
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext:
+        `NINA cost watch: this run has re-read ${m(total)} tokens of its own context${turn}; every further turn costs more than the last. ` +
+        'If what is left is more than one run should carry, stop where your work is whole, hand back what you have, and name what is left, so the orchestrator can send it as its own step. Otherwise finish without widening the work.',
+    },
+  };
+}
+
+/** Drops the counts of runs not heard from in a week. */
+function prune(root, now) {
+  const dir = stateDir(root);
+  for (const name of existsSync(dir) ? readdirSync(dir) : []) {
+    try {
+      if (now - statSync(join(dir, name)).mtimeMs > KEEP_MS) rmSync(join(dir, name), { force: true });
+    } catch {
+      // Another call's, going as this one looks.
+    }
+  }
+}
+
+/**
+ * The hook: reads the event from stdin, answers on stdout when a warning is due, and exits 0 whatever
+ * happens — a hook that fails must not stop the run it watches.
+ *
+ * @param {{root: string, warnAt: number, stdin?: NodeJS.ReadableStream, stdout?: NodeJS.WritableStream}} options
+ * @returns {Promise<number>}
+ */
+export async function runCostWatch({ root, warnAt, stdin = process.stdin, stdout = process.stdout }) {
+  try {
+    const chunks = [];
+    for await (const chunk of stdin) chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    const now = Date.now();
+    const answer = watch(JSON.parse(Buffer.concat(chunks).toString('utf8')), { root, warnAt, now });
+    if (answer) stdout.write(`${JSON.stringify(answer)}\n`);
+    if (Math.random() < 0.01) prune(root, now);
+  } catch {
+    // Fails open: the run goes on unwatched.
+  }
+  return 0;
+}

package/src/detectors.mjs

@@ -24,7 +24,7 @@ import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { hookStateDir, slugFor } from './paths.mjs';
 import { CHECK } from './wiring.mjs';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 /**
@@ -157,20 +157,82 @@ const stopState = (root) => join(hookStateDir(), `${slugFor(root)}.stop.json`);
 /** Sessions remembered per project; the oldest is forgotten past this. */
 const SESSIONS_KEPT = 20;
 
+/** What Claude Code wrote to the hook's stdin, read once: stdin can be read only once. */
+let input;
+
+/**
+ * The payload Claude Code writes to a hook's stdin, or an empty object run by hand.
+ *
+ * @returns {{session_id?: string, prompt?: string, transcript_path?: string}}
+ */
+function hookInput() {
+  if (input === undefined) {
+    try {
+      input = process.stdin.isTTY ? {} : (JSON.parse(readFileSync(0, 'utf8')) ?? {});
+    } catch {
+      input = {};
+    }
+  }
+  return input;
+}
+
 /**
- * The session a Stop hook runs in, from the payload Claude Code writes to its stdin. What was said is
- * kept per session: kept per project, a second session open on the same project found the finding
- * already told — to the first session's person — and told its own nothing.
+ * The session a hook runs in. What was said is kept per session: kept per project, a second session open
+ * on the same project found the finding already told — to the first session's person — and told its own
+ * nothing.
  *
  * @returns {string}
  */
-function hookSession() {
-  if (process.stdin.isTTY) return '-';
+const hookSession = () => String(hookInput().session_id ?? '-');
+
+/**
+ * Whether the prompt the hook runs before is a subagent's completion notification rather than something a
+ * person said. Claude Code submits each as a prompt, and every one ran the detectors — a second or more
+ * before the model read it — and put their findings beside it: one session of the first new project did so
+ * 181 times over 23 of its owner's messages.
+ *
+ * @returns {boolean}
+ */
+const notification = () => String(hookInput().prompt ?? '').trimStart().startsWith('<task-notification>');
+
+/** How much of a transcript's end is read for a compaction since the last hand-over: it is the latest line. */
+const TAIL = 1024 * 1024;
+
+/**
+ * Whether the session was compacted after a moment: a compaction drops what the model was handed, so what it
+ * was handed is handed again.
+ *
+ * @param {unknown} path - The session's transcript.
+ * @param {unknown} since - An ISO time.
+ * @returns {boolean}
+ */
+function compactedSince(path, since) {
+  if (typeof path !== 'string' || typeof since !== 'string' || !existsSync(path)) return false;
+  let text;
   try {
-    return String(JSON.parse(readFileSync(0, 'utf8'))?.session_id ?? '-');
+    const size = statSync(path).size;
+    const length = Math.min(size, TAIL);
+    const buffer = Buffer.alloc(length);
+    const fd = openSync(path, 'r');
+    try {
+      readSync(fd, buffer, 0, length, size - length);
+    } finally {
+      closeSync(fd);
+    }
+    text = buffer.toString('utf8');
   } catch {
-    return '-';
+    return false;
   }
+  for (const line of text.split('\n')) {
+    if (!line.includes('"compact_boundary"')) continue;
+    try {
+      const row = JSON.parse(line);
+      if (row?.subtype === 'compact_boundary' && String(row.timestamp) > since) return true;
+    } catch {
+      // A torn line at the head of the tail.
+    }
+  }
+  return false;
 }
 
 /** What was said, per session, for a project. */
@@ -237,8 +299,9 @@ function reportOf(drift, errored, missing, detectors) {
 /**
  * What the prompt hook hands the model, or null for nothing. A finding not handed over at the last
  * message goes in full, with the instruction to act on it or say it is pending. One that was, and has
- * not changed, goes as its summary, with the instruction not to say it again: told before every message
- * to say it was pending, the model closed every answer with the same line.
+ * not changed, goes as its summary beside a new one, with the instruction not to say it again — told
+ * before every message to say it was pending, the model closed every answer with the same line — and on
+ * its own not at all: the model has it from the first time, until a compaction drops it.
  *
  * @returns {string|null}
  */
@@ -317,6 +380,7 @@ function remember(root, session, change) {
  */
 export function runDetectors(detectors, options) {
   const { root, hook = false, context = false } = options;
+  if (context && notification()) return 0;
   const declared = declaredIn(root);
   const results = detectors.map((d) => runOne(d, root, declared, context ? 'context' : hook ? 'stop' : ''));
   const applicable = results.filter((r) => r.state !== 'n/a');
@@ -358,11 +422,17 @@ export function runDetectors(detectors, options) {
   // again: it has it already, and every copy stays in the conversation.
   if (context) {
     const session = hookSession();
-    const before = readStops(root)[session]?.given;
-    const handed = new Set(Array.isArray(before) ? before : []);
-    remember(root, session, { given: drift.flatMap(findingKeys) });
+    const state = readStops(root)[session] ?? {};
+    // A compaction since the last hand-over dropped it from the model's context: everything goes again.
+    const compacted = compactedSince(hookInput().transcript_path, state.handed_at);
+    const handed = new Set(!compacted && Array.isArray(state.given) ? state.given : []);
     const known = drift.filter((r) => findingKeys(r).every((k) => handed.has(k)));
-    const said = contextOf(drift.filter((r) => !known.includes(r)), known, errored, missing, detectors);
+    const fresh = drift.filter((r) => !known.includes(r));
+    remember(root, session, { given: drift.flatMap(findingKeys), ...(fresh.length > 0 ? { handed_at: new Date().toISOString() } : {}) });
+    // What the model was handed and has not changed is said only beside something new. Said on its own
+    // before every message, it went into the conversation on every prompt the session had.
+    const speaking = fresh.length > 0 || errored.length > 0 || missing.length > 0;
+    const said = contextOf(fresh, speaking ? known : [], errored, missing, detectors);
     if (said) {
       process.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: said } })}\n`);
     }

package/src/expected.mjs

@@ -1,8 +1,9 @@
 /**
- * The project slots a caller has declared it already knows are open.
+ * The project slots, and vocabulary names, a caller has declared it already knows are open.
  *
  * `nina upgrade --apply` creates slots: a new core can introduce one, and it cannot be filled
- * before the core that introduces it is pinned. Every reporter that fails on an unfilled slot
+ * before the core that introduces it is pinned. A name only the new core uses is the same case,
+ * named as `{{NAME}}`: `check` rolled a move back for one the preview had just listed as needed. Every reporter that fails on an unfilled slot
  * therefore has to be told, or the move deadlocks — there is no order in which it completes.
  *
  * Two reporters say this same thing, and the first fix taught only one: `check` counts a slot
@@ -21,7 +22,7 @@ export const EXPECT_ENV = 'NINA_EXPECT_UNFILLED';
 /**
  * @param {string[]} argv - The command's arguments; `--expect-unfilled <a,b>` names slots.
  * @param {NodeJS.ProcessEnv} [env] - Where to read `NINA_EXPECT_UNFILLED` from.
- * @returns {Set<string>} Slot ids as `<relative path> <slot id>`.
+ * @returns {Set<string>} Slot ids as `<relative path> <slot id>`, names as `{{NAME}}`.
  */
 export function expectedUnfilled(argv = [], env = process.env) {
   const fromArgv = argv.includes('--expect-unfilled') ? argv[argv.indexOf('--expect-unfilled') + 1] ?? '' : '';

package/src/transcripts.mjs

@@ -626,9 +626,13 @@ async function attachAgentDetail(projectDir, dispatches) {
       // 744 of one project's 826 in full on every turn, two seconds before the person saw an answer.
       const size = (await stat(join(dir, file)).catch(() => null))?.size ?? null;
       const settled = (r) => r.handed_back === false || String(r.verdict_source ?? '').startsWith('handback');
+      // `resumes` is written only by a reader from before rounds, which bills the whole run to its first
+      // record. A store both versions wrote to — one project on the old pin, a hook elsewhere on the new —
+      // had its runs marked read by the old one and skipped here, their first round billed twice.
       if (
         run.agent_read_bytes === size &&
-        [...records, ...later].every((r) => settled(r) && 'round' in r && 'lessons_read' in r && 'tokens' in r && 'files_touched' in r && 'effort' in r)
+        !('resumes' in run) &&
+        [...records, ...later].every((r) => settled(r) && 'round' in r && 'lessons_read' in r && 'tokens' in r && 'files_touched' in r && 'effort' in r && 'turns' in r)
       ) {
         continue;
       }
@@ -656,6 +660,8 @@ async function attachAgentDetail(projectDir, dispatches) {
         usage: new Map(),
         /** The files the round wrote through the edit tools. Only their number is kept. */
         written: new Set(),
+        /** The tool calls the round made, by id: over its turns, how many calls each turn sent at once. */
+        calls: new Set(),
       });
       const rounds = [fresh()];
       const roundOf = roundsOf();
@@ -677,6 +683,7 @@ async function attachAgentDetail(projectDir, dispatches) {
         const round = rounds[n - 1];
         const hasSkill = line.includes('"Skill"');
         const hasHandback = line.includes('SubagentHandback');
+        for (const m of line.matchAll(/"type":"tool_use","id":"([^"]+)"/g)) round.calls.add(m[1]);
         if (/"name":"(Edit|Write|MultiEdit|NotebookEdit)"/.test(line)) {
           try {
             for (const block of JSON.parse(line)?.message?.content ?? []) {
@@ -755,9 +762,14 @@ async function attachAgentDetail(projectDir, dispatches) {
           targets = [dispatches.get(id)];
         }
         const spent = tokensOf(round.usage);
+        const shape = contextOf(round.usage);
         targets.forEach((record, j) => {
           // One transcript, one bill: were two records ever to share an agent, the second would count it again.
           record.tokens = j === 0 ? spent.tokens : null;
+          record.turns = shape.turns;
+          record.tool_calls = round.calls.size;
+          record.context_start = shape.start;
+          record.context_peak = shape.peak;
           record.usage_model = spent.model;
           record.effort = spent.effort;
           record.files_touched = round.written.size;
@@ -790,6 +802,20 @@ async function attachAgentDetail(projectDir, dispatches) {
   }
 }
 
+/**
+ * How a round spent its context: how many turns it took, and how large the context each turn re-read was
+ * when the round began and at its largest. Every turn is billed the whole context again, so a round that
+ * begins where a long one ended — a run resumed for a fix — pays for everything before it on each turn.
+ *
+ * @param {Map<string, {usage: object}>} usage - Message id → its final usage, in the order the round sent them.
+ * @returns {{turns: number, start: number|null, peak: number|null}} Context sizes in tokens.
+ */
+export function contextOf(usage) {
+  const n = (v) => (typeof v === 'number' ? v : 0);
+  const sizes = [...usage.values()].map(({ usage: u }) => n(u.input_tokens) + n(u.cache_read_input_tokens) + n(u.cache_creation_input_tokens));
+  return { turns: sizes.length, start: sizes[0] ?? null, peak: sizes.length > 0 ? Math.max(...sizes) : null };
+}
+
 /**
  * What a run spent, from each of its messages' final usage: tokens by kind, and the model and effort
  * level that most of its messages ran at. Metadata — counts, a model id and a level, never a message.

package/src/wiring.mjs

@@ -23,6 +23,7 @@ import { join } from 'node:path';
 export const CHECK = 'scripts/harness-check.mjs';
 export const GATE = 'scripts/loop-gate.mjs';
 export const GUARD = 'scripts/edit-guard.mjs';
+export const COST = 'scripts/cost-watch.mjs';
 
 /** The npm scripts the detectors hang off: the reviewer runs one, the other is a detector itself. */
 export const SCRIPTS = {
@@ -135,6 +136,8 @@ export const HOOKS = [
     event: 'PreToolUse', matcher: 'Edit|Write|MultiEdit|NotebookEdit', script: GUARD, timeout: 10, why: 'a hand edit to a composed file is found only after the turn, as drift, and the next compose overwrites it',
     crash: (cannot) => ({ systemMessage: `NINA: the edit guard could not start, so composed files can be edited in place — ${cannot}` }),
   },
+  // Every tool, since what it watches is a subagent's every turn; a call outside a subagent returns at once.
+  { event: 'PostToolUse', script: COST, timeout: 10, why: 'a run that keeps re-reading its own context is told what it cost only afterwards, by `stats`' },
 ];
 
 /** Where a project's hooks can live: Claude Code reads both, so a hook kept in the local file counts. */