@xhulz/nina 0.37.0 → 0.39.0

package/src/gate.mjs

@@ -54,12 +54,14 @@
  * gate that could block work on its own crash would be worse than the loops it exists to stop.
  */
 
+import { spawnSync } from 'node:child_process';
 import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { TERMINALS, declaredTokens, parseGraph } from './graph.mjs';
 import { gateDir, slugFor } from './paths.mjs';
 import { declaredIssues, isLoopBack, saidToAgent } from './transcripts.mjs';
+import { lessonIndex } from './lessons.mjs';
 
 /** The package this runs from: its releases say whether a pinned version ships the gate at all. */
 const PACKAGE = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -431,7 +433,18 @@ export function replay(entries, loops, forward = new Map()) {
       }
     }
   });
-  return { effect: (to) => effect(to, entries.length), rounds: made };
+  // What is open when the replay ends: each loop with its rounds, the rounds the owner's replies gave it and the
+  // issues it counted by, and each loop-back no fix has acted on yet — what a compaction takes from the orchestrator.
+  const open = [...streak.entries()]
+    .filter(([key]) => key.split('|').length === 2)
+    .map(([key, s]) => {
+      const [source, token] = key.split('|');
+      const cap = Math.max(0, ...(loops.get(source)?.get(token)?.values() ?? []));
+      const issues = [...streak.keys()].filter((k) => k.startsWith(`${key}|`)).map((k) => k.slice(key.length + 1));
+      return { source, token, rounds: s.n, cap, given: grace.get(key) ?? 0, issues };
+    });
+  const waiting = [...pending.entries()].flatMap(([source, batch]) => batch.filter((v) => isLoopBack(v.verdict)).map((v) => ({ source, verdict: v.verdict, issues: v.issues ?? [] })));
+  return { effect: (to) => effect(to, entries.length), rounds: made, open, waiting };
 }
 
 /**
@@ -659,6 +672,40 @@ function onPre(input, project, path, at) {
   return confirmation(worst);
 }
 
+/**
+ * What the gate hands the orchestrator after its conversation was compacted: the loops still open and the
+ * loop-backs waiting on a fix, the latest dispatches, where the checkout stands, and the two documents to read
+ * again. The graph and the router are read once, at a session's start, and a compaction drops them with every
+ * report; the router told the orchestrator to write "round 2 of max 2" in a dispatch so "you after a
+ * compaction" could see it, and after a compaction it sees only a summary.
+ *
+ * @param {object} project - `loadProject`'s.
+ * @param {string} path - The session's ledger.
+ * @param {string} root - The project.
+ * @returns {object}
+ */
+function afterCompaction(project, path, root) {
+  const entries = readLedger(path);
+  const { open, waiting } = replay(entries, project.loops, project.forward);
+  const lines = ['The conversation was compacted. What the NINA loop gate kept of this session:'];
+  for (const l of open) {
+    lines.push(
+      `- open loop: ${l.source} ${l.token} — ${l.rounds} round(s), capped at ${l.cap}${l.given ? ` and ${l.given} more from the owner's replies` : ''}` +
+        (l.issues.length ? `, issues ${l.issues.join(', ')}` : ''),
+    );
+  }
+  for (const w of waiting) lines.push(`- waiting on a fix: ${w.source} ${w.verdict}${w.issues.length ? `, issues ${w.issues.join(', ')}` : ''}`);
+  if (open.length === 0 && waiting.length === 0) lines.push('- no loop is open');
+  const dispatched = entries.filter((e) => e.k === 'dispatch' && e.role).slice(-4);
+  if (dispatched.length) lines.push(`- the latest dispatches: ${dispatched.map((e) => e.role).join(', ')}, the newest at ${String(dispatched.at(-1).at ?? '').slice(11, 16)} UTC`);
+  const git = (...args) => spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', timeout: 2000 }).stdout?.trim() ?? '';
+  const branch = git('rev-parse', '--abbrev-ref', 'HEAD');
+  const last = git('log', '-1', '--format=%h %s');
+  if (branch) lines.push(`- the checkout: branch ${branch}${last ? `, last commit ${last.slice(0, 100)}` : ''}`);
+  lines.push('Before the next dispatch, read .claude/graph.md and .claude/router.md again: they were read at the start of the session, and are no longer in your context.');
+  return { hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: lines.join('\n') } };
+}
+
 /** Drops a project's ledgers nobody has written to in a month, and error lines older than a week. */
 function prune(root, now) {
   const dir = projectGateDir(root);
@@ -718,6 +765,17 @@ export function handle(input, { root, now = new Date(), pkg = PACKAGE }) {
         return null;
       case 'SubagentStop':
         return onStop(input, project, path, at);
+      case 'SessionStart':
+        return input.source === 'compact' ? afterCompaction(project, path, root) : null;
+      case 'SubagentStart': {
+        // Not the loop's business, but the one hook every stage passes through as it begins: its lessons. Claude
+        // Code reads `additionalContext` from this event's `hookSpecificOutput` into the subagent's context as it
+        // starts — its hook schema and handler say so in 2.1.283, and the handler in 2.1.158 — though the help text
+        // it prints for a malformed hook output does not list the event.
+        const role = input.agent_type;
+        const text = role && project.graph.stages.has(role) ? lessonIndex(root, role) : null;
+        return text ? { hookSpecificOutput: { hookEventName: 'SubagentStart', additionalContext: text } } : null;
+      }
       case 'PostToolUse':
         return onPost(input, project, path, at);
       case 'PreToolUse':

package/src/guard.mjs

@@ -32,6 +32,190 @@ const PACKAGE = dirname(dirname(fileURLToPath(import.meta.url)));
 /** The tools that change a file, and where each names it. */
 const EDITS = { Edit: 'file_path', Write: 'file_path', MultiEdit: 'file_path', NotebookEdit: 'notebook_path' };
 
+/** The git subcommands that move the checkout or write its history — Hard Rule #18's. */
+const MOVES = new Set(['stash', 'checkout', 'switch', 'reset', 'restore', 'clean', 'commit', 'merge', 'rebase', 'cherry-pick', 'revert', 'am', 'apply', 'pull', 'push']);
+
+/** Words before the command word that leave it the command: `env X=1 git …`, `command git …`, `{ git …; }`. */
+const RUNNERS = new Set(['env', 'command', 'exec', 'time', 'nohup', 'nice', '{', '}', '!']);
+
+/** A `-C` or a `cd` to one of these is still the tree the stage was dispatched into. */
+const HERE = new Set(['.', './']);
+
+/** Where a heredoc's delimiter word ends. */
+const DELIMITER_ENDS = new Set([' ', '\t', '\r', '\n', ';', '&', '|', '(', ')', '`', '<', '>']);
+
+/** The characters that can end a run of plain word characters. */
+const SPECIAL = new Set(["'", '"', '\\', '#', '\n', '<', '&', ';', '|', '(', ')', '`', ' ', '\t', '\r']);
+
+/**
+ * A shell command as the shell reads it: its simple commands, in order, each as its words with the quotes removed.
+ * `&&`, `||`, `;`, `|`, `&`, a newline, a parenthesis and a backquote end one; a quoted string is part of a word — `"git" stash`
+ * is git — and never a separator or a command of its own, across lines too; a comment and a heredoc's body are not
+ * read. One pass, no pattern: the command is a model's, and a pattern that backtracks on it is one a stage could
+ * stall the guard with.
+ *
+ * @param {string} command
+ * @returns {string[][]}
+ */
+export function simpleCommands(command) {
+  const text = String(command);
+  const commands = [[]];
+  const heredocs = [];
+  let word = null;
+  const end = () => {
+    if (word !== null) commands.at(-1).push(word);
+    word = null;
+  };
+  const next = () => {
+    end();
+    if (commands.at(-1).length) commands.push([]);
+  };
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === "'") {
+      const close = text.indexOf("'", i + 1);
+      const stop = close === -1 ? text.length : close;
+      word = (word ?? '') + text.slice(i + 1, stop);
+      i = stop + 1;
+    } else if (c === '"') {
+      const parts = [];
+      i += 1;
+      let from = i;
+      while (i < text.length && text[i] !== '"') {
+        if (text[i] === '\\' && i + 1 < text.length) {
+          parts.push(text.slice(from, i));
+          from = i + 1;
+          i += 2;
+        } else i += 1;
+      }
+      parts.push(text.slice(from, i));
+      word = (word ?? '') + parts.join('');
+      i += 1;
+    } else if (c === '\\') {
+      if (text[i + 1] !== '\n') word = (word ?? '') + (text[i + 1] ?? '');
+      i += 2;
+    } else if (c === '#' && word === null) {
+      const line = text.indexOf('\n', i);
+      i = line === -1 ? text.length : line;
+    } else if (c === '\n') {
+      next();
+      i += 1;
+      for (const delimiter of heredocs.splice(0)) {
+        while (i < text.length) {
+          const line = text.indexOf('\n', i);
+          const stop = line === -1 ? text.length : line;
+          const body = text.slice(i, stop);
+          i = stop + 1;
+          if (body.trim() === delimiter) break;
+        }
+      }
+    } else if (c === '<' && text.startsWith('<<<', i)) {
+      word = (word ?? '') + '<<<';
+      i += 3;
+    } else if (c === '<' && text[i + 1] === '<') {
+      end();
+      i += text[i + 2] === '-' ? 3 : 2;
+      while (text[i] === ' ' || text[i] === '\t') i += 1;
+      const from = i;
+      while (i < text.length && !DELIMITER_ENDS.has(text[i])) i += 1;
+      const delimiter = text.slice(from, i).replaceAll("'", '').replaceAll('"', '').replaceAll('\\', '');
+      if (delimiter) heredocs.push(delimiter);
+    } else if (c === '&' && (text[i + 1] === '>' || word?.endsWith('>') || word?.endsWith('<'))) {
+      word = (word ?? '') + c;
+      i += 1;
+    } else if (c === ';' || c === '&' || c === '|' || c === '(' || c === ')' || c === '`') {
+      next();
+      i += (c === '&' || c === '|') && text[i + 1] === c ? 2 : 1;
+    } else if (c === ' ' || c === '\t' || c === '\r') {
+      end();
+      i += 1;
+    } else {
+      const from = i;
+      i += 1;
+      while (i < text.length && !SPECIAL.has(text[i])) i += 1;
+      word = (word ?? '') + text.slice(from, i);
+    }
+  }
+  end();
+  return commands.filter((words) => words.length);
+}
+
+/**
+ * The git subcommand in a shell command that would move the checkout the command runs in, or null. Read command
+ * by command, in order, as the shell runs it: a `cd` exempts only what comes after it — `git stash && cd /tmp`
+ * stashed the tree all the same, and a test of the whole string for a `cd` let it through — and `-C .` is not
+ * another directory. A git command is one whose command word is `git`, not a phrase in a quoted string or a
+ * heredoc's body; its subcommand is the word after its global options, so `merge-base` is not `merge`; and a
+ * stash's `list` or `show`, and an `apply` that only checks, read.
+ *
+ * @param {string} command - A Bash tool call's command.
+ * @returns {string|null}
+ */
+export function checkoutMove(command) {
+  let moved = false;
+  for (const words of simpleCommands(command)) {
+    while (words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]) || RUNNERS.has(words[0]))) words.shift();
+    if (words[0] === 'cd' || words[0] === 'pushd') {
+      moved ||= !HERE.has(words[1] ?? '');
+      continue;
+    }
+    if (words[0] !== 'git') continue;
+    let i = 1;
+    let elsewhere = false;
+    while (words[i]?.startsWith('-')) {
+      if (words[i] === '-C') {
+        elsewhere ||= !HERE.has(words[i + 1] ?? '.');
+        i += 2;
+      } else if (words[i] === '-c') {
+        i += 2;
+      } else {
+        if (/^--(git-dir|work-tree)\b/.test(words[i])) elsewhere = true;
+        i += 1;
+      }
+    }
+    const sub = words[i];
+    if (!MOVES.has(sub) || moved || elsewhere) continue;
+    const rest = words.slice(i + 1);
+    if (sub === 'stash' && ['list', 'show'].includes(rest[0])) continue;
+    if (sub === 'apply' && rest.some((w) => ['--check', '--stat', '--numstat', '--summary'].includes(w)) && !rest.includes('--apply')) continue;
+    return sub;
+  }
+  return null;
+}
+
+/**
+ * A stage's shell command that would move the checkout it was dispatched into, refused. Only the orchestrator
+ * commits, and the work in flight lives in that tree, uncommitted: one reviewer, told not to edit, stashed it to
+ * compare with the baseline, and its pop failed on a conflict.
+ *
+ * @param {object} input - The hook's stdin, parsed.
+ * @param {{layers: string}} pinned - The pinned layers, whose hard rules say whether this one is the project's.
+ * @returns {object|null}
+ */
+function handleShell(input, pinned) {
+  if (!input.agent_id) return null;
+  const moves = checkoutMove(input.tool_input?.command ?? '');
+  if (!moves) return null;
+  let rules = '';
+  try {
+    rules = readFileSync(join(pinned.layers, 'core', 'tree', 'CLAUDE.md'), 'utf8');
+  } catch {
+    return null;
+  }
+  if (!rules.includes('Only the orchestrator commits')) return null;
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        `NINA: \`git ${moves}\` would move the checkout the pipeline's work in flight lives in — Hard Rule #18: only the orchestrator ` +
+        'commits, and no stage moves the checkout. Read history with git diff, log, show, status or blame, and build or test another ' +
+        'revision in a `git worktree` you remove afterwards.',
+    },
+  };
+}
+
 /** How much of a file is read to find it: the head, not the whole of a large file on every edit. */
 const HEAD_BYTES = 16 * 1024;
 
@@ -83,6 +267,10 @@ function head(path) {
 export async function handleEdit(input, { root, pkg = PACKAGE }) {
   try {
     if (input?.hook_event_name !== 'PreToolUse') return null;
+    if (input.tool_name === 'Bash') {
+      const pinnedShell = input.agent_id ? pinnedLayers(root, pkg) : null;
+      return pinnedShell ? handleShell(input, pinnedShell) : null;
+    }
     const key = EDITS[input.tool_name];
     const path = key ? input.tool_input?.[key] : null;
     const pinned = typeof path === 'string' ? pinnedLayers(root, pkg) : null;

package/src/lessons.mjs

@@ -0,0 +1,55 @@
+/**
+ * The lessons a stage is handed as it starts: the list of its active pills, each with the trigger that says
+ * when it applies, given to the subagent by the `SubagentStart` hook.
+ *
+ * Every spec told its stage to read its pills, and a stage found them by opening files: every pill in its own
+ * directory, and every shared one to see whether its `applies_to` named it. So a reviewer read one in only
+ * seven of fifteen runs while twelve applied to it, and a stage no pill named opened them in two runs of three.
+ * Handed the list, a stage opens the ones whose trigger matches its task, and nothing else.
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { frontmatter, list } from './commands/pills.mjs';
+
+/** How much of a trigger goes in the list: enough to say when, not the lesson. */
+const TRIGGER_CHARS = 160;
+
+/**
+ * A stage's lessons as the text handed to it, or null when it has none.
+ *
+ * @param {string} root - The project directory.
+ * @param {string} role - The stage.
+ * @returns {string|null}
+ */
+export function lessonIndex(root, role) {
+  const found = [];
+  for (const sub of [role, 'shared']) {
+    let files = [];
+    try {
+      files = readdirSync(join(root, '.claude', 'pills', sub)).filter((f) => f.endsWith('.md')).sort();
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      let fields = null;
+      try {
+        fields = frontmatter(readFileSync(join(root, '.claude', 'pills', sub, file), 'utf8'));
+      } catch {
+        continue;
+      }
+      if (!fields || fields.status === 'retired') continue;
+      const applies = list(fields.applies_to);
+      // A shared pill is this stage's when it names it; one in the stage's own directory, unless it names others.
+      if (sub === 'shared' ? !applies.includes(role) : applies.length > 0 && !applies.includes(role)) continue;
+      const trigger = String(fields.trigger ?? '').replace(/\s+/g, ' ').trim();
+      const when = trigger ? `when ${trigger.length > TRIGGER_CHARS ? `${trigger.slice(0, TRIGGER_CHARS - 1)}…` : trigger}` : 'on every task';
+      found.push(`- \`.claude/pills/${sub}/${file}\` — ${when}`);
+    }
+  }
+  if (found.length === 0) return null;
+  return [
+    `Your lessons in this project, ${found.length}: before acting, open each one whose trigger matches this task, and only those.`,
+    ...found,
+  ].join('\n');
+}

package/src/wiring.mjs

@@ -109,7 +109,7 @@ const previousCommands = (h) => [command(h.script, h.mode), ...EARLIER_CANNOT_ST
  * The harness check has two: `Stop` tells the person what a turn left behind, `UserPromptSubmit` puts
  * the same findings in the model's context before it answers — the only one of the two it reads. The
  * loop gate has four, one per fact it keeps: a verdict, a dispatch, the owner speaking, and the
- * decision itself.
+ * decision itself; and a fifth, as each stage starts, that hands the stage its lessons (`src/lessons.mjs`).
  */
 export const HOOKS = [
   {
@@ -132,8 +132,11 @@ export const HOOKS = [
   },
   { event: 'PostToolUse', matcher: 'Agent|Task|SendMessage|AskUserQuestion|SubagentHandback', script: GATE, timeout: 10, why: 'the gate never learns which rounds went out, or that the owner answered' },
   { event: 'SubagentStop', script: GATE, timeout: 10, why: 'the gate misses the verdict of a stage that wrote its report as its last message' },
+  { event: 'SubagentStart', script: GATE, timeout: 10, why: 'a stage is not handed its lessons, and opens every shared pill to find them, or none' },
+  { event: 'SessionStart', matcher: 'compact', script: GATE, timeout: 10, why: 'after a compaction the orchestrator has lost the graph, the router and its open loops, and nothing gives them back' },
   {
-    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',
+    event: 'PreToolUse', matcher: 'Edit|Write|MultiEdit|NotebookEdit|Bash', script: GUARD, timeout: 10,
+    why: "a hand edit to a composed file is found only after the turn, as drift, and a stage's git stash or checkout takes the work in flight",
     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.