@xhulz/nina 0.69.0 → 0.71.0

package/src/commands/sizes.mjs

@@ -75,6 +75,23 @@ export function forecastIn(text) {
   return { lines: Number(m[1].replace(/,/g, '')), files: files ? Number(files[1]) : null };
 }
 
+/**
+ * What a step file's `Size:` line says when {@link forecastIn} reads no forecast from it, or null when it reads one or
+ * the file has no such line. A step whose line was rewritten into prose — "round 1 landed +498/−95 against ~272" — was
+ * left out of every rate without a word. The label opens its line, as `Kind:` does: `font-size:` in a step's CSS and a
+ * sentence that names the `Size:` line are no line of their own.
+ *
+ * @param {string} text - A step file.
+ * @returns {string|null} The line after `Size:`, shortened.
+ */
+export function unreadSize(text) {
+  if (forecastIn(text)) return null;
+  const m = /^[\s>*_-]*Size:[*_ \t]*([^\n]*)/im.exec(text);
+  if (!m) return null;
+  const said = m[1].trim();
+  return said.length > 72 ? `${said.slice(0, 71)}…` : said;
+}
+
 /** Runs git in the project, or says it could not. */
 function git(dir, args) {
   const r = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
@@ -178,7 +195,8 @@ const median = (xs) => {
  * Every step with a forecast, landed or not: what it was forecast before it was built, and what its commits added.
  *
  * @param {string} dir - The project.
- * @returns {{steps: object[], limit: number}|null} Null outside a git repository.
+ * @returns {{steps: object[], limit: number, unread: object[]}|null} Null outside a git repository. `unread` is each step
+ *   file whose `Size:` line reads as no forecast, with what it says (`said`).
  */
 export function measure(dir) {
   const profile = (() => {
@@ -191,7 +209,7 @@ export function measure(dir) {
   const limit = Number(profile?.vocabulary?.STEP_LINES) || Number(defaultVocabulary(PACKAGE).STEP_LINES) || 400;
   // It runs every turn: a project with no step file does not pay for its history.
   const files = stepFiles(dir);
-  if (files.length === 0) return git(dir, ['rev-parse', '--verify', '--quiet', 'HEAD']) === null ? null : { steps: [], limit };
+  if (files.length === 0) return git(dir, ['rev-parse', '--verify', '--quiet', 'HEAD']) === null ? null : { steps: [], limit, unread: [] };
   const log = git(dir, ['log', '--format=%H%x09%ct%x09%cI%x09%s', 'HEAD']);
   if (log === null) return null;
   // Times as instants: an ISO time carries its zone, and two zones compared as text order wrongly.
@@ -227,23 +245,36 @@ export function measure(dir) {
     return when;
   };
   const steps = [];
+  // Step files whose `Size:` line reads as no forecast: left out of every rate, so said rather than skipped.
+  const unread = [];
   for (const file of files) {
     const current = readFileSync(join(dir, file.path), 'utf8');
     const now = forecastIn(current);
     const kind = kindIn(current);
     const landings = named.get(file.path).filter((c) => code.get(c.hash)?.size > 0);
     if (landings.length === 0) {
-      if (!now) continue;
+      if (!now) {
+        const said = unreadSize(current);
+        if (said !== null) unread.push({ ...file, landed: false, said });
+        continue;
+      }
       // Forecast again in the working tree, it is newer than every commit.
       const since = at('HEAD', file.path)?.lines === now.lines ? writtenAt(file.path, Infinity, now.lines) : Infinity;
-      steps.push({ ...file, kind, landed: false, forecast: now, since });
+      // What it was first forecast at: a forecast restated at a rate carries that rate over it, and rates multiplied
+      // onto one another — another kind's among them — put one project's steps at ×2.54 of their count.
+      const original = changes.get(file.path).map((c) => at(c.hash, file.path)).filter(Boolean).at(-1) ?? null;
+      steps.push({ ...file, kind, landed: false, forecast: now, since, original: original && original.lines !== now.lines ? original : null });
       continue;
     }
     // The forecast the step was built to: its file before its first commit, or as that commit wrote it.
     const first = landings[0];
     const before = at(`${first.hash}^`, file.path);
     const forecast = before ?? at(first.hash, file.path);
-    if (!forecast) continue;
+    if (!forecast) {
+      const said = unreadSize(text.get(`${first.hash}^:${file.path}`) ?? '') ?? unreadSize(text.get(`${first.hash}:${file.path}`) ?? '');
+      if (said !== null) unread.push({ ...file, landed: true, said, hash: first.hash });
+      continue;
+    }
     const since = (before ? writtenAt(file.path, order.get(first.hash), forecast.lines) : null) ?? first.t;
     const lines = new Map();
     for (const c of landings) for (const [path, added] of code.get(c.hash)) lines.set(path, (lines.get(path) ?? 0) + added);
@@ -272,7 +303,7 @@ export function measure(dir) {
       hash: last.hash,
     });
   }
-  return { steps, limit };
+  return { steps, limit, unread };
 }
 
 /**
@@ -294,6 +325,20 @@ export function rateOf(steps, { spec, since, kind = null }) {
   return over.length ? { rate: median(over.map((s) => s.measured ?? s.ratio)), over: over.length, kind: mine.length ? kind : null } : null;
 }
 
+/**
+ * What a spec's newest landed steps of one kind missed by, whenever they were forecast: set beside a step to land that
+ * carries more over its first forecast than its kind ever missed by, which reads as rates carried from elsewhere.
+ *
+ * @param {object[]} steps
+ * @param {{spec: string, kind?: string|null}} step - Its spec and kind.
+ * @returns {number|null}
+ */
+export function kindRate(steps, { spec, kind = null }) {
+  if (!kind) return null;
+  const over = steps.filter((s) => s.landed && s.spec === spec && s.kind === kind).sort((a, b) => a.t - b.t).slice(-RATE_OVER);
+  return over.length ? median(over.map((s) => s.measured ?? s.ratio)) : null;
+}
+
 /**
  * What the detector says: the newest landed step, when it overran, and the steps of its spec still forecast as they
  * were when it landed — until one of them is forecast again. The next step to go out is forecast again at its turn, and
@@ -336,7 +381,7 @@ export async function sizes(argv) {
     else console.error('  not a git repository, or one with no commit yet: a step is measured by its commits\n');
     return check ? 0 : 1;
   }
-  const { steps, limit } = measured;
+  const { steps, limit, unread } = measured;
   if (check) {
     // During `nina upgrade --apply`: a step that overran is the project's history, not the move — and the release that
     // first shipped this detector rolled itself back in the project that asked for it. The move says it after.
@@ -344,30 +389,50 @@ export async function sizes(argv) {
       console.log('sizes: current');
       return 0;
     }
+    const said = [];
     const found = overrun(measured);
-    if (!found) {
+    if (found) {
+      const { step, stale } = found;
+      const again = stale.slice(0, 4).map((s) => {
+        const rate = rateOf(steps, s);
+        const next = Math.round(s.forecast.lines * (rate?.rate ?? 1));
+        return `${s.step} ~${s.forecast.lines} → ~${next}${rate?.kind ? ` (${rate.kind})` : ''}${next > limit ? ` past ${limit}` : ''}`;
+      });
+      const first = step.first === null ? '' : `, ${step.first} in its first round (${times(step.measured)})`;
+      said.push(
+        `step ${step.step} of ${step.spec} landed ${step.lines} lines against ~${step.forecast.lines} (${times(step.ratio)}${first}); ` +
+          `before the next of its ${stale.length} step(s) forecast when it was goes out, forecast that one again — a \`Size:\` line at the rate \`nina sizes\` gives it — ` +
+          `and split it if that puts it past ${limit}; the rest at their turn: ${again.join(', ')}${stale.length > again.length ? ', …' : ''}`,
+      );
+    }
+    // Only a step still to land: its line can be written again now, and once it lands, the line it carried is history.
+    for (const u of unread.filter((x) => !x.landed)) {
+      // "~215 raw lines" opens with a number too: what reads is the forecast it is measured by, followed by `lines`.
+      said.push(`step ${u.step} of ${u.spec}: no forecast it can read in its \`Size:\` line ("${u.said}") — write it as \`Size: ~N lines in M files\`, the forecast the step is measured by followed by \`lines\`, before the step lands, or no rate counts it`);
+    }
+    if (said.length === 0) {
       console.log('sizes: current');
       return 0;
     }
-    const { step, stale } = found;
-    const again = stale.slice(0, 4).map((s) => {
-      const rate = rateOf(steps, s);
-      const next = Math.round(s.forecast.lines * (rate?.rate ?? 1));
-      return `${s.step} ~${s.forecast.lines} → ~${next}${rate?.kind ? ` (${rate.kind})` : ''}${next > limit ? ` past ${limit}` : ''}`;
-    });
-    const first = step.first === null ? '' : `, ${step.first} in its first round (${times(step.measured)})`;
-    console.log(
-      `step ${step.step} of ${step.spec} landed ${step.lines} lines against ~${step.forecast.lines} (${times(step.ratio)}${first}); ` +
-        `before the next of its ${stale.length} step(s) forecast when it was goes out, forecast that one again — a \`Size:\` line at the rate \`nina sizes\` gives it — ` +
-        `and split it if that puts it past ${limit}; the rest at their turn: ${again.join(', ')}${stale.length > again.length ? ', …' : ''}`,
-    );
+    for (const line of said) console.log(line);
     return 1;
   }
-  if (steps.length === 0) {
+  if (steps.length === 0 && unread.length === 0) {
     console.log(`  no step file under ${SPECS} states a \`Size:\` line yet\n`);
     return 0;
   }
-  for (const spec of [...new Set(steps.map((s) => s.spec))]) {
+  // What a step to land carries over its first forecast, beside what its kind's landed steps missed by: rates multiplied
+  // onto one another, another kind's among them, read as one step's own.
+  const carried = (s) => {
+    if (!s.original) return '';
+    const factor = s.forecast.lines / s.original.lines;
+    const own = kindRate(steps, s);
+    const note = ` · first forecast ~${s.original.lines}, ${times(factor)} since`;
+    if (own === null) return dim(note);
+    const beside = `${note}; its ${s.kind} steps missed by ${times(own)}`;
+    return factor > own * OVERRUN ? amber(beside) : dim(beside);
+  };
+  for (const spec of [...new Set([...steps, ...unread].map((s) => s.spec))]) {
     const mine = steps.filter((s) => s.spec === spec);
     console.log(`\n  ${bold(pink(spec))}${dim(`  landed against the forecast it was built to; limit ${limit} lines`)}`);
     for (const s of mine.filter((x) => x.landed).sort((a, b) => a.t - b.t)) {
@@ -382,16 +447,21 @@ export async function sizes(argv) {
     for (const s of mine.filter((x) => !x.landed)) {
       const rate = rateOf(steps, s);
       if (!rate) {
-        console.log(`    ${s.step.padEnd(10)} ~${String(s.forecast.lines).padEnd(5)} ${dim('to land — forecast after every step that landed, so none measures it yet')}`);
+        console.log(`    ${s.step.padEnd(10)} ~${String(s.forecast.lines).padEnd(5)} ${dim('to land — forecast after every step that landed, so none measures it yet')}${carried(s)}`);
         continue;
       }
       const next = Math.round(s.forecast.lines * rate.rate);
       console.log(
         `    ${s.step.padEnd(10)} ~${String(s.forecast.lines).padEnd(5)} → ~${String(next).padEnd(5)} ` +
           dim(`to land, at ${times(rate.rate)} over ${rate.over} ${rate.kind ? `${rate.kind} ` : ''}step(s) forecast as it was`) +
-          (next > limit ? amber(`  past ${limit}: split`) : ''),
+          (next > limit ? amber(`  past ${limit}: split`) : '') +
+          carried(s),
       );
     }
+    for (const u of unread.filter((x) => x.spec === spec)) {
+      const where = u.landed ? `before ${u.hash.slice(0, 7)}, the commit that landed it,` : 'to land,';
+      console.log(`    ${u.step.padEnd(10)} ${amber('no forecast it can read')} ${dim(`— its \`Size:\` line ${where} says "${u.said}", so no rate counts it`)}`);
+    }
   }
   console.log('');
   return 0;

package/src/commands/stats.mjs

@@ -299,6 +299,17 @@ function contextReport(records) {
         `${(row.prompt === null ? '—' : row.prompt.toLocaleString('en-US')).padStart(9)}`,
     );
   }
+  if (d.reread.length === 0) return;
+  const pct = (x) => (x === null ? '—' : `${Math.round(x * 100)}%`);
+  console.log('');
+  console.log(dim('    what the turns re-read: the context each round opened with, the expired cache written again, the outputs clipped to a file'));
+  console.log(dim(`    ${'stage'.padEnd(20)}${'rounds'.padStart(6)}${'opened with'.padStart(13)}${'rewrites'.padStart(10)}${'of spend'.padStart(10)}${'clipped'.padStart(9)}`));
+  for (const row of d.reread) {
+    console.log(
+      `    ${pink(row.role)}${' '.repeat(Math.max(20 - row.role.length, 1))}${String(row.n).padStart(6)}${pct(row.fixed).padStart(13)}` +
+        `${String(row.rewrites).padStart(10)}${pct(row.rewriteShare).padStart(10)}${String(row.clipped).padStart(9)}`,
+    );
+  }
 }
 
 /**
@@ -334,7 +345,52 @@ export function contextData(records) {
       });
     }
   }
-  return { rows };
+  return { rows, reread: rereadData(shaped) };
+}
+
+/**
+ * Where each stage's re-read went, as data: the share of the context its turns re-read that was what each
+ * round opened with — the system prompt, CLAUDE.md, the spec, the dispatch — the share of what it spent that
+ * went on writing an expired cache again, and the outputs the cost watch clipped to a file. Rounds measured
+ * before the fields existed are left out of the shares rather than counted as none; a stage with no
+ * measured round has no row.
+ *
+ * @param {object[]} shaped - The rounds that recorded their turns.
+ * @returns {{role: string, n: number, fixed: number|null, rewrites: number, rewriteShare: number|null, clipped: number}[]}
+ */
+export function rereadData(shaped) {
+  const measured = shaped.filter((r) => typeof r.cache_rewrites === 'number');
+  const byRole = new Map();
+  for (const r of measured) byRole.set(r.role, [...(byRole.get(r.role) ?? []), r]);
+  const t = (n) => (typeof n === 'number' ? n : 0);
+  const rows = [];
+  for (const [role, rounds] of byRole) {
+    let opened = 0;
+    let reread = 0;
+    let rewriteCost = 0;
+    let spent = 0;
+    for (const r of rounds) {
+      const total = t(r.tokens?.input) + t(r.tokens?.read) + t(r.tokens?.write_5m) + t(r.tokens?.write_1h);
+      if (total > 0 && typeof r.context_start === 'number') {
+        opened += Math.min(r.context_start * r.turns, total);
+        reread += total;
+      }
+      const cost = costOf(r.tokens, r.usage_model);
+      if (cost !== null && cost > 0) {
+        spent += cost;
+        rewriteCost += costOf({ write_5m: t(r.cache_rewritten) }, r.usage_model);
+      }
+    }
+    rows.push({
+      role,
+      n: rounds.length,
+      fixed: reread > 0 ? opened / reread : null,
+      rewrites: rounds.reduce((a, r) => a + t(r.cache_rewrites), 0),
+      rewriteShare: spent > 0 ? rewriteCost / spent : null,
+      clipped: rounds.reduce((a, r) => a + t(r.clipped), 0),
+    });
+  }
+  return rows.sort((a, b) => b.n - a.n);
 }
 
 /**

package/src/commands/upgrade.mjs

@@ -366,9 +366,9 @@ export async function upgrade(argv, ctx) {
   const newScripts = new Set([...(await shippedScripts(onto.dir, kept))].filter((s) => !scriptsBefore.has(s)));
   const unwired = newScripts.size > 0 ? await missingWiring(target, newScripts) : [];
   // A script already run whose hooks this NINA needs more of — a matcher that grew — holds what it held, so it does
-  // not stop the move; it is said, with what fixes it.
+  // not stop the move; it is said, with what fixes it. So is a setting it now ships beside them.
   const stillRun = new Set([...(await shippedScripts(onto.dir, kept))].filter((s) => scriptsBefore.has(s)));
-  const widened = stillRun.size > 0 ? (await missingWiring(target, stillRun)).filter((w) => / hook running `[^`]+` does not match /.test(w)) : [];
+  const widened = stillRun.size > 0 ? (await missingWiring(target, stillRun)).filter((w) => / hook running `[^`]+` does not match /.test(w) || /^\.claude\/settings\.json has no "/.test(w)) : [];
   if (widened.length > 0) {
     for (const w of widened) console.log(`  · ${w}`);
     console.log('');
@@ -633,7 +633,7 @@ export async function upgrade(argv, ctx) {
     }
     const forecasts = nina(ctx, target, ['sizes', '--project', target, '--check']);
     if (!forecasts.ok && forecasts.out.trim()) {
-      console.log('\n  a step landed past its forecast — not caused by this move, now visible:');
+      console.log('\n  the step forecasts have something to act on — not caused by this move, now visible:');
       for (const line of forecasts.out.trim().split('\n')) console.log(`    ${line}`);
     }
     // The move is done and the tree is sound, but it is not finished: until these are written

package/src/cost.mjs

@@ -11,11 +11,19 @@
  *
  * 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.
+ *
+ * Two things a run pays for on every turn after are settled at the call itself. A shell command's long
+ * output stays in the context and is re-read on every turn — outputs longer than a screen were a fifth of
+ * what two projects' stages re-read — so past `clipAt` characters it goes to a file beside the ones Claude
+ * Code keeps for the session, and the run sees its first and last lines and where the rest is. And a call
+ * that ran past the five minutes a subagent's cache lives makes the next turn write the whole context again,
+ * at twelve times a read's price — a quarter of what one project's stages spent — so the run is told then.
  */
 
 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';
+import { CLIP_MARK } from './transcripts.mjs';
 
 /** Where a run's counts are kept between calls, one file per agent. */
 const stateDir = (root) => join(projectGateDir(root), 'cost');
@@ -45,18 +53,168 @@ function gained(path, from) {
   return { text: buffer.subarray(0, end + 1).toString('utf8'), to: from + end + 1 };
 }
 
+/** How long a subagent's prompt cache lives without a turn: a call that runs past it is paid for again in full. */
+const CACHE_MS = 5 * 60_000;
+
+/**
+ * Whether a shell command reads a file or a diff rather than producing output: what it prints is what the
+ * run asked to read, so clipping it would only send the run to read the file it was cut to. What a command
+ * line prints last is its last command's, and of a pipe its last stage's, so that is the one judged:
+ * `sed -i … && node run` produces output, and `cd p && cat f` or `node run && tail -n 50 log` reads.
+ *
+ * @param {unknown} command - The Bash call's command.
+ * @returns {boolean}
+ */
+export function readsByShell(command) {
+  if (typeof command !== 'string') return false;
+  // Read as words, never by a pattern that backtracks: the command is the model's, of any length.
+  const assignment = (word) => /^\w+=/.test(word);
+  // A subshell's parentheses are not part of the words they hold.
+  const unwrap = (word) => {
+    let from = 0;
+    let to = word.length;
+    while (from < to && word[from] === '(') from += 1;
+    while (to > from && word[to - 1] === ')') to -= 1;
+    return word.slice(from, to);
+  };
+  const segments = command
+    .split(/&&|\|\||;|\n/)
+    .map((segment) => segment.split(/\s+/).map(unwrap).filter(Boolean))
+    // A segment of assignments alone prints nothing.
+    .filter((words) => words.length && !words.every(assignment));
+  const piped = (segments.at(-1) ?? []).join(' ').split('|').at(-1);
+  const words = piped.split(/\s+/).filter(Boolean);
+  // Less what runs a command rather than being it: assignments, `export NAME=…`, `timeout N`, `nice`, `command`.
+  let i = 0;
+  while (i < words.length) {
+    if (assignment(words[i]) || words[i] === 'nice' || words[i] === 'command') i += 1;
+    else if ((words[i] === 'export' && assignment(words[i + 1] ?? '')) || (words[i] === 'timeout' && words[i + 1])) i += 2;
+    else break;
+  }
+  if (['cat', 'sed', 'head', 'tail', 'nl', 'awk', 'less', 'more'].includes(words[i])) return true;
+  if (words[i] !== 'git') return false;
+  // `git diff` and `git show`, past the options that come before a subcommand.
+  i += 1;
+  while (words[i] === '--no-pager' || words[i] === '-C' || words[i] === '-c') i += words[i] === '--no-pager' ? 1 : 2;
+  return words[i] === 'diff' || words[i] === 'show';
+}
+
+/**
+ * The first lines of a text up to a size, or its last ones; a single line longer than the size is cut.
+ *
+ * @param {string} text - The output.
+ * @param {number} size - Characters at most.
+ * @param {boolean} fromEnd - The last lines rather than the first.
+ * @returns {string}
+ */
+function lines(text, size, fromEnd) {
+  const all = text.split('\n');
+  const kept = [];
+  let length = 0;
+  for (const line of fromEnd ? all.reverse() : all) {
+    if (length + line.length + 1 > size) break;
+    kept.push(line);
+    length += line.length + 1;
+  }
+  if (kept.length === 0) return fromEnd ? text.slice(-size) : text.slice(0, size);
+  return (fromEnd ? kept.reverse() : kept).join('\n');
+}
+
+/**
+ * A long Bash output clipped: the whole of it written to a file in the session's `tool-results` directory,
+ * where Claude Code keeps the outputs it moves out itself and a stage may read, and in its place the first
+ * lines, the last ones — where a test runner or a battery prints its summary — and where the rest is.
+ * Null when the output is short, the command reads a file, or the file cannot be written: the run then sees
+ * the output as it was.
+ *
+ * @param {object} input - The PostToolUse hook's input.
+ * @param {number} clipAt - The characters past which an output is clipped; 0 clips nothing.
+ * @returns {{updatedToolOutput: object, chars: number}|null}
+ */
+export function clipOutput(input, clipAt) {
+  const response = input?.tool_response;
+  if (input?.tool_name !== 'Bash' || !(clipAt > 0) || response === null || typeof response !== 'object' || typeof response.stdout !== 'string') return null;
+  const stderr = typeof response.stderr === 'string' ? response.stderr : '';
+  const chars = response.stdout.length + stderr.length;
+  if (chars <= clipAt || response.isImage || readsByShell(input.tool_input?.command)) return null;
+  const id = /^[A-Za-z0-9_-]{1,80}$/.test(String(input.tool_use_id ?? '')) ? input.tool_use_id : `${Date.now()}`;
+  const file = join(dirname(input.transcript_path), input.session_id, 'tool-results', `nina-${id}.txt`);
+  const whole = stderr ? `${response.stdout}\n--- stderr ---\n${stderr}` : response.stdout;
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, whole);
+  } catch {
+    return null;
+  }
+  const said =
+    `${CLIP_MARK}: ${whole.split('\n').length.toLocaleString('en-US')} lines and ${chars.toLocaleString('en-US')} characters, of which the first and last lines are shown. ` +
+    `The whole of it${stderr ? ', stderr after stdout,' : ''} is in ${file} — grep it, or read the range you need: read whole, it all comes back into your context and is re-read on every turn after.]`;
+  // A stdout short enough to show whole is shown once, the notice after it: only what is long is cut.
+  const head = Math.round(clipAt / 8);
+  const tail = Math.round((clipAt * 3) / 8);
+  const stdout = response.stdout.length > head + tail ? `${lines(response.stdout, head, false)}\n…\n${said}\n…\n${lines(response.stdout, tail, true)}` : `${response.stdout}\n${said}`;
+  return {
+    chars,
+    updatedToolOutput: { ...response, stdout, stderr: stderr ? lines(stderr, head, true) : stderr },
+  };
+}
+
 /**
  * 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.
+ * A long Bash output is clipped to a file ({@link clipOutput}), and a call that outlived the cache is named.
  *
  * @param {object} input - The PostToolUse hook's input.
- * @param {{root: string, warnAt: number, now?: number}} options
+ * @param {{root: string, warnAt: number, clipAt?: number, now?: number}} options
  * @returns {object|null} The hook's answer.
  */
-export function watch(input, { root, warnAt, now = Date.now() }) {
+export function watch(input, { root, warnAt, clipAt = 0, 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;
+  // The session's id becomes a directory name below, in the clip's path and the transcript's.
+  if (typeof input.transcript_path !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(String(input.session_id ?? ''))) return null;
+  const clipped = clipOutput(input, clipAt);
+  const counted = warnAt > 0 ? count(input, { root, warnAt, now }) : null;
+  const ran = typeof input.duration_ms === 'number' && input.duration_ms > CACHE_MS ? input.duration_ms : null;
+  if (!clipped && !counted?.due && ran === null) return null;
+  const size = (n) => (n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : `${Math.round(n / 1000)}k`);
+  const context = [];
+  const person = [];
+  if (counted?.due) {
+    context.push(
+      `NINA cost watch: this run has re-read ${counted.total} tokens of its own context${counted.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.',
+    );
+    person.push(`${input.agent_type ?? 'a subagent'} ${input.agent_id.slice(0, 8)} has re-read ${counted.total} tokens of its own context${counted.turn}.`);
+  }
+  if (ran !== null) {
+    const minutes = Math.round(ran / 60_000);
+    const whole = counted?.context ? `, about ${size(counted.context)} tokens,` : '';
+    context.push(
+      `NINA cost watch: that call ran ${minutes} minutes, past the five your context stays cached between turns, so your next turn writes all of it${whole} again — at twelve times what re-reading it costs. ` +
+        'Wait in calls that each end within three minutes: run the rest in shares, or start it in the background and check on it no more often than every three minutes (Hard Rule #19).',
+    );
+    person.push(`${input.agent_type ?? 'a subagent'} ${input.agent_id.slice(0, 8)} waited ${minutes} min in one call; its next turn writes its whole context again.`);
+  }
+  return {
+    ...(person.length ? { systemMessage: `NINA: ${person.join(' ')}` } : {}),
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      ...(context.length ? { additionalContext: context.join('\n\n') } : {}),
+      ...(clipped ? { updatedToolOutput: clipped.updatedToolOutput } : {}),
+    },
+  };
+}
+
+/**
+ * The run's re-read brought up to date from its transcript, and whether a warning is due; null when the
+ * transcript is not there.
+ *
+ * @param {object} input - The PostToolUse hook's input.
+ * @param {{root: string, warnAt: number, now: number}} options
+ * @returns {{due: boolean, total: string, turn: string, context: number|null}|null}
+ */
+function count(input, { root, warnAt, now }) {
   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);
@@ -69,6 +227,7 @@ export function watch(input, { root, warnAt, now = Date.now() }) {
   }
   const { text, to } = gained(transcript, state.offset);
   let last = null;
+  const n = (v) => (typeof v === 'number' ? v : 0);
   for (const line of text.split('\n')) {
     if (!line.includes('"cache_read_input_tokens"')) continue;
     try {
@@ -78,6 +237,8 @@ export function watch(input, { root, warnAt, now = Date.now() }) {
       if (message?.id && typeof read === 'number') {
         state.read[message.id] = read;
         last = read;
+        // The whole context that turn held, which a turn after an expired cache writes again.
+        state.context = read + n(message.usage.cache_creation_input_tokens) + n(message.usage.input_tokens);
       }
     } catch {
       // A torn line loses one message's count.
@@ -92,18 +253,12 @@ export function watch(input, { root, warnAt, now = Date.now() }) {
   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`;
+  const size = (v) => (v >= 1e6 ? `${(v / 1e6).toFixed(1)}M` : `${Math.round(v / 1000)}k`);
   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.',
-    },
+    due,
+    total: `${Math.round(total / 1e6)}M`,
+    turn: last === null ? '' : `, and each turn now re-reads about ${size(last)} tokens more`,
+    context: typeof state.context === 'number' ? state.context : null,
   };
 }
 
@@ -120,18 +275,18 @@ function prune(root, now) {
 }
 
 /**
- * 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.
+ * The hook: reads the event from stdin, answers on stdout when a warning is due or an output is clipped,
+ * 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
+ * @param {{root: string, warnAt: number, clipAt?: number, stdin?: NodeJS.ReadableStream, stdout?: NodeJS.WritableStream}} options
  * @returns {Promise<number>}
  */
-export async function runCostWatch({ root, warnAt, stdin = process.stdin, stdout = process.stdout }) {
+export async function runCostWatch({ root, warnAt, clipAt = 0, 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 });
+    const answer = watch(JSON.parse(Buffer.concat(chunks).toString('utf8')), { root, warnAt, clipAt, now });
     if (answer) stdout.write(`${JSON.stringify(answer)}\n`);
     if (Math.random() < 0.01) prune(root, now);
   } catch {

package/src/dashboard.html

@@ -362,7 +362,9 @@ const RENDER = {
         table(['stage', 'runs', 'median', 'total', 'share', ''], d.cost.rows.map((r) => [el('span', { class: 'role' }, r.role), String(r.runs), money(r.median), money(r.total), pct(r.total, d.cost.total), bar([[r.total / d.cost.total, 'var(--pink)']])]), [1, 2, 3, 4]),
         d.cost.unpriced ? el('p', { class: 'note faint' }, `${d.cost.unpriced} run(s) on a model the price table does not know.`) : null] : null,
       d.context ? [el('h3', {}, 'context · every turn re-reads it all'),
-        table(['stage', 'rounds', 'n', 'turns', 'calls/turn', 'starts at', 'peak', 'prompt'], d.context.rows.map((r, i, all) => [i > 0 && all[i - 1].role === r.role ? '' : el('span', { class: 'role' }, r.role), el('span', { class: 'faint' }, r.label), String(r.n), String(r.turns), r.callsPerTurn.toFixed(2), kTokens(r.start), kTokens(r.peak), r.prompt === null ? '—' : r.prompt.toLocaleString('en-US')]), [2, 3, 4, 5, 6, 7])] : null,
+        table(['stage', 'rounds', 'n', 'turns', 'calls/turn', 'starts at', 'peak', 'prompt'], d.context.rows.map((r, i, all) => [i > 0 && all[i - 1].role === r.role ? '' : el('span', { class: 'role' }, r.role), el('span', { class: 'faint' }, r.label), String(r.n), String(r.turns), r.callsPerTurn.toFixed(2), kTokens(r.start), kTokens(r.peak), r.prompt === null ? '—' : r.prompt.toLocaleString('en-US')]), [2, 3, 4, 5, 6, 7]),
+        d.context.reread?.length ? el('h3', {}, 'what the turns re-read') : null,
+        d.context.reread?.length ? table(['stage', 'rounds', 'opened with', 'rewrites', 'of spend', 'clipped'], d.context.reread.map((r) => [el('span', { class: 'role' }, r.role), String(r.n), r.fixed === null ? '—' : `${Math.round(r.fixed * 100)}%`, String(r.rewrites), r.rewriteShare === null ? '—' : `${Math.round(r.rewriteShare * 100)}%`, String(r.clipped)]), [1, 2, 3, 4, 5]) : null] : null,
       d.proportion ? [el('h3', {}, 'proportion · the size of a change against its chain'),
         table(['largest write', 'cycles', 'with a planner or architect', ''], d.proportion.rows.map((r) => [r.label, String(r.cycles), r.cycles ? `${r.designed} (${pct(r.designed, r.cycles)})` : '—', bar([[r.cycles ? r.designed / r.cycles : 0, 'var(--pink)']])]), [1, 2]),
         d.proportion.over ? el('p', { class: 'note warn' }, `${d.proportion.over.count} implementer round(s) wrote more files than one step may (${d.proportion.over.limit}); the largest wrote ${d.proportion.over.largest}.`) : null,

package/src/gate.mjs

@@ -268,6 +268,8 @@ function append(path, entry) {
  *
  * - a rejection is cancelled by a pass launched after a fix went out for it: that review saw the fix. A
  *   sibling launched with it, or a reviewer launched after it that saw no fix, cancels nothing;
+ * - a rejection is withdrawn by a later completion of the agent that made it, passing with no fix sent between:
+ *   the same review judged again, which nothing else would settle;
  * - a rejection from a review that was already running when the edge's last round went out belongs to
  *   that round, and makes no new one;
  * - the rest make this dispatch a round on the edge: one more than the rounds since the loop last
@@ -335,12 +337,15 @@ export function replay(entries, loops, forward = new Map()) {
   };
 
   /**
-   * A source's waiting verdicts, settled: the rejections no later review of a fix cancelled, and whether a pass
-   * closes its loops — one that began after the latest fix, with no rejection running beside it.
+   * A source's waiting verdicts, settled: the rejections no later review of a fix cancelled and no later completion of
+   * their own agent withdrew, and whether a pass closes its loops — one that began after the latest fix, with no
+   * rejection running beside it.
    */
   const settle = (source, batch) => {
     const passes = batch.filter((v) => !isLoopBack(v.verdict));
-    const live = batch.filter((v) => isLoopBack(v.verdict) && !passes.some((p) => p.launch > v.at && fixBetween(source, v.at, p.launch)));
+    const live = batch.filter(
+      (v) => isLoopBack(v.verdict) && !passes.some((p) => p.launch > v.at && (p.agent === v.agent || fixBetween(source, v.at, p.launch))),
+    );
     return { live, closes: passes.some((p) => p.launch > (lastFix.get(source) ?? -1) && !live.some((v) => v.launch < p.at)) };
   };
 
@@ -461,7 +466,8 @@ export function replay(entries, loops, forward = new Map()) {
       const onward = [...forward].filter(([, sources]) => sources.has(source)).map(([stage]) => stage);
       return { source, token, rounds: s.n, cap, given: grace.get(key) ?? 0, issues, closing, targets: [...targetsOf(source)], onward };
     });
-  const waiting = [...pending.entries()].flatMap(([source, batch]) => batch.filter((v) => isLoopBack(v.verdict)).map((v) => ({ source, verdict: v.verdict, issues: v.issues ?? [], index: v.at })));
+  // A rejection its own agent withdrew waits on no fix: counted as waiting, the next session inherited it.
+  const waiting = [...pending.entries()].flatMap(([source, batch]) => settle(source, batch).live.map((v) => ({ source, verdict: v.verdict, issues: v.issues ?? [], index: v.at })));
   return { effect: (to) => effect(to, entries.length), rounds: made, open, waiting };
 }
 

package/src/langfuse.mjs

@@ -112,8 +112,11 @@ export function contextMode(setting) {
   return setting?.content === 'prompts' ? 'prompts' : setting?.content ? 'full' : null;
 }
 
-/** A round's shape, as metadata on its root: how many turns and calls it took, and how large its context and prompt were. */
-const SHAPE = ['turns', 'tool_calls', 'context_start', 'context_peak', 'prompt_chars'];
+/**
+ * A round's shape, as metadata on its root: how many turns and calls it took, how large its context and prompt
+ * were, how often it wrote an expired cache again and how much, and how many outputs the cost watch clipped.
+ */
+const SHAPE = ['turns', 'tool_calls', 'context_start', 'context_peak', 'prompt_chars', 'cache_rewrites', 'cache_rewritten', 'clipped'];
 
 /**
  * The OTLP span at the root of a dispatch's trace. Without its context, a run that spent tokens is a