@xhulz/nina 0.38.0 → 0.40.0

package/src/guard.mjs

@@ -21,7 +21,7 @@ import { closeSync, existsSync, openSync, readFileSync, readSync, realpathSync }
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { NOTICE_HEAD, composedPaths, noticeOf } from './commands/compose.mjs';
-import { HARNESS } from './paths.mjs';
+import { HARNESS, layerRootFor, readProfile } from './paths.mjs';
 
 // Read here and by the suites from here; the test itself lives beside the compiler that writes the notice.
 export { NOTICE_HEAD, noticeOf };
@@ -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[][]}
+ */
+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;
 
@@ -43,13 +227,12 @@ const HEAD_BYTES = 16 * 1024;
  * @param {string} [pkg] - The NINA install to look in.
  * @returns {{layers: string, surfaces: string[]}|null}
  */
-export function pinnedLayers(root, pkg = PACKAGE) {
+function pinnedLayers(root, pkg = PACKAGE) {
   try {
-    const profile = JSON.parse(readFileSync(join(root, HARNESS, 'profile.json'), 'utf8'));
-    if (typeof profile.core !== 'string' || !/^[A-Za-z0-9._-]+$/.test(profile.core)) return null;
-    const layers = profile.core === 'dev' ? pkg : join(pkg, 'releases', profile.core);
-    if (!existsSync(join(layers, 'core', 'tree', 'scripts', 'edit-guard.mjs'))) return null;
-    return { layers, surfaces: Array.isArray(profile.surfaces) ? profile.surfaces : [] };
+    const { profile } = readProfile(root);
+    const layers = profile ? layerRootFor(pkg, profile.core) : { error: 'no profile' };
+    if (layers.error || !existsSync(join(layers.dir, 'core', 'tree', 'scripts', 'edit-guard.mjs'))) return null;
+    return { layers: layers.dir, surfaces: Array.isArray(profile.surfaces) ? profile.surfaces : [] };
   } catch {
     return null;
   }
@@ -83,6 +266,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/langfuse.mjs

@@ -13,10 +13,11 @@
  *
  * Observations go over OpenTelemetry (`/api/public/otel/v1/traces`, OTLP/HTTP as JSON), the path
  * Langfuse's v4 data model takes, with the session and trace attributes on every span, as its guide asks.
- * Verdicts go to `/api/public/scores` as categorical scores. Langfuse keeps what it was first sent: the
+ * Verdicts go as categorical scores, in batches to `/api/public/ingestion`, or one at a time to
+ * `/api/public/scores` where the batch endpoint is gone. Langfuse keeps what it was first sent: the
  * same span id sent again is a second observation, not an update, and every sum counts both; a score is
- * replaced only when its id, name and date all match, and that endpoint takes no date — it stamps the
- * day it is called. So each is sent once, and only for a run that has settled. No dependency: `fetch`
+ * replaced only when its id, name and date all match, and the scores endpoint takes no date — it stamps
+ * the day it is called. So each is sent once, and only for a run that has settled. No dependency: `fetch`
  * is enough.
  */
 
@@ -40,13 +41,13 @@ export const BATCH = 100;
 export const SETTLE_MINUTES = 15;
 
 /** How long a run that never returned is waited for before it is sent as it is. */
-export const UNRETURNED_HOURS = 24;
+const UNRETURNED_HOURS = 24;
 
 /** A stable hex id of a given length, from what it identifies. */
 const hexId = (text, length) => createHash('sha256').update(String(text)).digest('hex').slice(0, length);
 
 /** The trace a dispatch becomes, and the observation at its root. */
-export const traceIdOf = (record) => hexId(`trace|${record.dispatch_id}`, 32);
+const traceIdOf = (record) => hexId(`trace|${record.dispatch_id}`, 32);
 export const spanIdOf = (record) => hexId(record.dispatch_id, 16);
 
 /** An ISO time, as OTLP's nanoseconds since the epoch — a string, since it outgrows a double. */
@@ -230,7 +231,7 @@ export function scoreOf(record) {
 }
 
 /** The OTLP request body for a batch of spans. */
-export function otlpBody(spans) {
+function otlpBody(spans) {
   return {
     resourceSpans: [
       {
@@ -247,8 +248,8 @@ export function otlpBody(spans) {
  * request cut off after Langfuse took it is the one way a span goes twice, so a batch of spans, the one
  * request that carries real weight, gets the longer wait.
  */
-export const REQUEST_MS = 30_000;
-export const SPANS_MS = 120_000;
+const REQUEST_MS = 30_000;
+const SPANS_MS = 120_000;
 
 /** The headers every request carries. */
 const headersFor = ({ publicKey, secretKey }) => ({

package/src/lock.mjs

@@ -0,0 +1,82 @@
+/**
+ * A lock file that names the process holding it, for the commands that must not run twice at once on one
+ * project: two snapshots would leave one's cursors beside the other's records, two exports would send the same
+ * runs twice.
+ *
+ * The file appears with the pid already in it — written aside, then linked into place, which fails when a lock
+ * is there — so it is never read empty and taken for a dead one's. A lock whose process died is removed only by
+ * the taker holding its takeover, and only once it has read the holder again under it: each taker removed it
+ * outright before, after its own read, and the second removed the lock the first had just taken, so both held it.
+ */
+
+import { link, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+/** Whether a process is running. One this user may not signal is running too. */
+function alive(pid) {
+  if (!(pid > 0)) return false;
+  try {
+    return process.kill(pid, 0);
+  } catch (error) {
+    return error.code === 'EPERM';
+  }
+}
+
+/** The pid a lock file names — 0 when it names none — or undefined when there is no file. */
+async function holder(path) {
+  try {
+    return Number(await readFile(path, 'utf8')) || 0;
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+/** A name beside the lock no other taker uses, in this process or another. */
+const aside = (path) => `${path}.${process.pid}.${Math.random().toString(36).slice(2)}`;
+
+/** Puts a file naming this process at `path`, unless one is there. */
+async function place(path) {
+  const mine = aside(path);
+  await writeFile(mine, String(process.pid));
+  try {
+    await link(mine, path);
+    return true;
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    return false;
+  } finally {
+    await rm(mine, { force: true });
+  }
+}
+
+/**
+ * Takes a lock, or says it is held.
+ *
+ * @param {string} path - The lock file.
+ * @returns {Promise<(() => Promise<void>)|null>} Its release, or null when a running process holds it.
+ */
+export async function takeLock(path) {
+  await mkdir(dirname(path), { recursive: true });
+  const takeover = `${path}.takeover`;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    if (await place(path)) return () => rm(path, { force: true });
+    if (alive(await holder(path))) return null;
+    if (!(await place(takeover))) {
+      const taker = await holder(takeover);
+      if (alive(taker)) return null;
+      // A taker that died mid-takeover. One that finished is simply gone: try again.
+      if (taker !== undefined) await rm(takeover, { force: true });
+      continue;
+    }
+    try {
+      // Under the takeover nobody else removes the lock, and nobody can link over it: a lock read now stays what
+      // it is. A missing one does not — a taker may link it in the next instant — so there is nothing to remove.
+      const pid = await holder(path);
+      if (pid !== undefined && !alive(pid)) await rm(path, { force: true });
+    } finally {
+      await rm(takeover, { force: true });
+    }
+  }
+  return null;
+}

package/src/paths.mjs

@@ -9,6 +9,7 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 
@@ -101,6 +102,70 @@ export function legacyHint(target) {
     : '';
 }
 
+/**
+ * A project's profile, read the one way every command reads it: `{profile, path}`, or `{path, error}` — one
+ * line saying what is wrong, with `missing` when there is no profile at all. Commands that parsed it on
+ * their own answered a stray comma with a stack trace, and each that did not said so differently.
+ *
+ * @param {string} target - The project.
+ * @returns {{path: string, profile?: object, error?: string, missing?: boolean}}
+ */
+export function readProfile(target) {
+  const path = join(target, HARNESS, 'profile.json');
+  if (!existsSync(path)) {
+    const hint = legacyHint(target) || ' — run `nina init` first, or name the project with --project';
+    return { path, missing: true, error: `no ${HARNESS}/profile.json under ${target}${hint}` };
+  }
+  try {
+    const profile = JSON.parse(readFileSync(path, 'utf8'));
+    if (profile === null || typeof profile !== 'object' || Array.isArray(profile)) return { path, error: `${path} is not a JSON object` };
+    return { path, profile };
+  } catch (error) {
+    return { path, error: `${path} cannot be read — ${error.message}` };
+  }
+}
+
+/**
+ * Where a project's layers are read from.
+ *
+ * A project pins a frozen release, or tracks the working tree with "dev". A pinned release
+ * that is missing is an error, never a silent fall back to whatever the harness happens to
+ * look like right now: that would compose an unreviewed core into a project that asked for
+ * a reviewed one, and nothing downstream would say so. Every reader asks this one: the commands,
+ * and the hooks that ask whether the pin ships them.
+ *
+ * @param {string} root - The NINA install directory.
+ * @param {string|undefined} core - The profile's `core` field.
+ * @returns {{dir: string}|{error: string}}
+ */
+export function layerRootFor(root, core) {
+  if (!core || core === 'dev') {
+    // `dev` means "track the layers as they are being worked on", which only exists in a
+    // checkout of this repo. An installed package ships frozen releases and nothing else,
+    // so say that rather than composing an empty tree and reporting nothing wrong.
+    if (!existsSync(join(root, 'core'))) {
+      return { error: `profile pins core "dev", which tracks the NINA working tree — ${root} is an installed package and has only releases` };
+    }
+    return { dir: root };
+  }
+  // A name, never a path: `../x` would read layers from outside the releases.
+  if (typeof core !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(core)) return { error: `profile pins core ${JSON.stringify(core)}, which is not a release name` };
+  const dir = join(root, 'releases', core);
+  if (!existsSync(dir)) return { error: `profile pins core ${core}, which is not in ${join(root, 'releases')}` };
+  return { dir };
+}
+
+/**
+ * The surfaces a layer root offers, by name, in order. Seven commands listed the directory each on its own.
+ *
+ * @param {string} layerRoot - From {@link layerRootFor}.
+ * @returns {Promise<string[]>}
+ */
+export async function surfacesIn(layerRoot) {
+  const entries = await readdir(join(layerRoot, 'surfaces'), { withFileTypes: true }).catch(() => []);
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+}
+
 /**
  * Where `nina upgrade --apply` writes down a move while it is in flight: the versions it moves between, the
  * files it composes for the first time, and — under {@link movedFrom} — every file it can touch, as it was.

package/src/shell.mjs

@@ -13,8 +13,9 @@ import { spawnSync } from 'node:child_process';
 import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
-import { PINK, printBanner, useColor } from './banner.mjs';
+import { printBanner } from './banner.mjs';
 import { shellHistoryFile } from './paths.mjs';
+import { dim, pink } from './look.mjs';
 
 /** Words the session answers itself rather than handing to a command. */
 const LEAVE = new Set(['exit', 'quit', 'q']);
@@ -87,8 +88,7 @@ function keep(line) {
  */
 export function shell({ bin, version, commands }) {
   const terminal = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-  const dim = (s) => (useColor() ? `\x1b[2m${s}\x1b[0m` : s);
-  const prompt = useColor() ? `\x1b[38;2;${PINK.join(';')}mnina ›\x1b[0m ` : 'nina › ';
+  const prompt = `${pink('nina ›')} `;
 
   printBanner(version);
   console.log(dim('  type a command — stats, check, upgrade --to <version> — `help` lists them, `clear` starts the screen over, `exit` leaves\n'));

package/src/steps.mjs

@@ -6,16 +6,13 @@
  * project forward was six commands in a fixed order, where getting the order wrong quietly
  * overwrote the project's own file — so the order belongs in the tool, not in a message.
  *
- * The animation is a convenience, not the contract: a step reports the same text either way,
- * so a log, a CI run and a pipe all read like the terminal does minus the dots.
+ * On a terminal the step running shows as `...` until its line replaces it. Not animated: a step runs
+ * synchronously, so a timer would never fire while it works. A log, a CI run and a pipe read like the
+ * terminal does, minus that line.
  */
 
-/** Frames of the ellipsis, slow enough to read and fast enough to look alive. */
-const FRAMES = ['.  ', '.. ', '...'];
-const TICK = 220;
-
 /**
- * Whether to animate — a pipe, a CI log and a test all get plain lines instead.
+ * Whether to show the step running — a pipe, a CI log and a test all get plain lines instead.
  *
  * @param {NodeJS.WriteStream} stream
  * @returns {boolean}
@@ -46,24 +43,13 @@ export function runSteps(steps, options = {}) {
       continue;
     }
 
-    let frame = 0;
-    let timer = null;
-    if (live) {
-      stream.write(`  ${FRAMES[0]} ${step.label}`);
-      timer = setInterval(() => {
-        frame = (frame + 1) % FRAMES.length;
-        stream.write(`\r  ${FRAMES[frame]} ${step.label}`);
-      }, TICK);
-      timer.unref?.();
-    }
-
+    if (live) stream.write(`  ... ${step.label}`);
     let result;
     try {
       result = step.run();
     } catch (error) {
       result = { ok: false, log: String(error?.stack ?? error) };
     } finally {
-      if (timer) clearInterval(timer);
       // `\r` alone leaves the tail of the longest line behind when the next one is shorter.
       if (live) stream.write('\r\u001b[K');
     }

package/src/store.mjs

@@ -21,7 +21,7 @@ const UNREAD = new Set(['UNCLEAR', 'NONE', null, undefined]);
  * @param {string} text - The file.
  * @returns {object[]}
  */
-export function parseStore(text) {
+function parseStore(text) {
   return String(text)
     .split('\n')
     .filter((l) => l.trim())
@@ -74,7 +74,7 @@ export function readStoreFile(file, { raw = false } = {}) {
  * @param {string} dir - The project.
  * @returns {string[]}
  */
-export function storeNamesOf(dir) {
+function storeNamesOf(dir) {
   const names = new Set([slugFor(dir)]);
   try {
     names.add(slugFor(realpathSync(dir)));

package/src/wiring.mjs

@@ -22,11 +22,11 @@ import { join } from 'node:path';
 /** The composed scripts the hooks run. */
 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';
+const GUARD = 'scripts/edit-guard.mjs';
+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 = {
+const SCRIPTS = {
   'harness:check': 'node scripts/harness-check.mjs',
   'harness:compose:check': 'nina compose --check --quiet',
 };
@@ -73,7 +73,7 @@ export function packageInstalled(target) {
  * @param {string} module - `gate`, `guard`, …
  * @returns {boolean}
  */
-export function packageExports(target, module) {
+function packageExports(target, module) {
   try {
     createRequire(join(target, 'package.json')).resolve(`@xhulz/nina/${module}`);
     return true;
@@ -111,7 +111,7 @@ const previousCommands = (h) => [command(h.script, h.mode), ...EARLIER_CANNOT_ST
  * loop gate has four, one per fact it keeps: a verdict, a dispatch, the owner speaking, and the
  * decision itself; and a fifth, as each stage starts, that hands the stage its lessons (`src/lessons.mjs`).
  */
-export const HOOKS = [
+const HOOKS = [
   {
     event: 'Stop', script: CHECK, mode: '--hook', timeout: 30, statusMessage: 'Checking the harness...', why: 'nobody is told what a turn left behind',
     crash: (cannot) => ({ systemMessage: `NINA: the harness check could not start — ${cannot}` }),
@@ -133,8 +133,10 @@ 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.
@@ -306,6 +308,17 @@ function settingsHooks(hooks) {
   return out;
 }
 
+/** How {@link missingWiring} opens the sentence that says the package is missing. */
+const NOT_INSTALLED = '@xhulz/nina is not installed in this project';
+
+/**
+ * Whether what {@link missingWiring} found includes the package itself: the one thing `wire` cannot do.
+ *
+ * @param {string[]} unwired - Its sentences.
+ * @returns {boolean}
+ */
+export const lacksPackage = (unwired) => unwired.some((w) => w.startsWith(NOT_INSTALLED));
+
 /**
  * Whatever of the wiring a project lacks, one sentence each.
  *
@@ -318,7 +331,7 @@ export async function missingWiring(target, shipped) {
   // First, because nothing below matters without it: the composed scripts import the package.
   if ((shipped.has(CHECK) || shipped.has(GATE) || shipped.has(GUARD)) && !packageInstalled(target)) {
     out.push(
-      '@xhulz/nina is not installed in this project, so the composed scripts cannot load and every hook fails — ' +
+      `${NOT_INSTALLED}, so the composed scripts cannot load and every hook fails — ` +
         'pnpm add -D -E @xhulz/nina',
     );
   } else {