@xhulz/nina 0.31.0 → 0.32.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';
@@ -235,7 +236,8 @@ 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);
@@ -499,6 +501,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:');

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/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. */