@xhulz/nina 0.34.0 → 0.35.0

package/src/commands/upgrade.mjs

@@ -6,16 +6,15 @@
  * already wrote that the new harness has nowhere to put. A slot that was renamed or dropped
  * takes the project's own text out of the composition with it, silently, because a fragment
  * nothing references composes to nothing and no check notices. So this reports first and
- * writes only when told to, and what it writes is one field: the version. Reconciling the
- * fragments is work, and work does not get done by a flag.
+ * writes only when told to. Reconciling the fragments is work, and work does not get done by a flag.
  */
 
-import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { readFile, readdir } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
-import { HARNESS, legacyHint } from '../paths.mjs';
-import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { HARNESS, describeMove, interruptedMove, legacyHint, moveJournal, movedFrom } from '../paths.mjs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { composeProject, composedPaths, defaultedSlots, layerRootFor, walk } from './compose.mjs';
+import { REMOVED, composeProject, composedPaths, defaultedSlots, layerRootFor, walk } from './compose.mjs';
 import { NEEDS, detected } from '../surfaces.mjs';
 import { filledSlots, projectSlots, referencedVocabulary } from './check.mjs';
 import { EXPECT_ENV } from '../expected.mjs';
@@ -25,6 +24,9 @@ import { missingFragment, missingWiring, shippedScripts } from '../wiring.mjs';
 import { runSteps } from '../steps.mjs';
 import { defaultVocabulary } from '../vocabulary.mjs';
 
+/** What stops a move from outside it: Ctrl-C, a `kill`, the terminal closing. */
+const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
 /** Banner lines, which are for a person watching and only noise inside a captured log. */
 const BANNER = /^[\s█╗╔╝║═╚▄▀]*$|harness orchestration ·/;
 
@@ -75,7 +77,7 @@ function nina(ctx, target, args) {
     cwd: target,
     encoding: 'utf8',
   });
-  const out = [result.stdout ?? '', result.stderr ?? '']
+  const out = [result.stdout ?? '', result.stderr ?? '', result.signal ? `stopped by ${result.signal}` : '']
     .join('\n')
     .split('\n')
     .filter((line) => line.trim() && !BANNER.test(line))
@@ -121,7 +123,7 @@ function shell(target, script) {
     encoding: 'utf8',
     env: { ...process.env, PATH: `${join(target, 'node_modules', '.bin')}:${process.env.PATH ?? ''}` },
   });
-  const out = [result.stdout ?? '', result.stderr ?? ''].join('\n').split('\n').filter((l) => l.trim()).join('\n');
+  const out = [result.stdout ?? '', result.stderr ?? '', result.signal ? `stopped by ${result.signal}` : ''].join('\n').split('\n').filter((l) => l.trim()).join('\n');
   return { ok: result.status === 0, out, summary: summarise(out) };
 }
 
@@ -157,6 +159,74 @@ function summarise(out) {
   return [...lines].reverse().find((l) => /^\w[\w ]*:/.test(l))?.trim();
 }
 
+/**
+ * Puts a project back on the version a move started from: the pin, then the files the move composed for the
+ * first time removed, a recompose, and every file it could touch written back as it was — the recompose alone
+ * would write the old composition over the owner's own edits and call it restored.
+ *
+ * @param {{root: string}} ctx - CLI context.
+ * @param {string} target - The project.
+ * @param {string} profilePath - Its profile.
+ * @param {object} profile - The profile as read, whose pin is set back.
+ * @param {string} version - The version the move started from.
+ * @param {string[]} created - Paths the move composed where nothing was.
+ * @param {Map<string, Buffer>} saved - Every file the move could touch, as it was.
+ * @returns {boolean} Whether the recompose passed.
+ */
+function restore(ctx, target, profilePath, profile, version, created, saved) {
+  profile.core = version;
+  writeFileSync(profilePath, `${JSON.stringify(profile, null, 2)}\n`);
+  for (const p of created) rmSync(join(target, p), { force: true });
+  const recomposed = nina(ctx, target, ['compose', '--project', target]);
+  for (const [p, bytes] of saved) {
+    mkdirSync(dirname(join(target, p)), { recursive: true });
+    writeFileSync(join(target, p), bytes);
+  }
+  return recomposed.ok;
+}
+
+/**
+ * `nina upgrade --abort`: undoes a move that was stopped before it finished, from what it wrote down first.
+ *
+ * @param {{root: string}} ctx - CLI context.
+ * @param {string} target - The project.
+ * @param {string} profilePath - Its profile.
+ * @param {object} profile - The profile as read.
+ * @param {ReturnType<typeof interruptedMove>} stopped - The move it was left in.
+ * @returns {number} Process exit code.
+ */
+function abort(ctx, target, profilePath, profile, stopped) {
+  if (!stopped) {
+    console.log('  no upgrade was stopped half-way here — there is nothing to undo.\n');
+    return 0;
+  }
+  if (stopped.unreadable) {
+    console.error(
+      `  ${describeMove(stopped)} Nothing can be undone from it: set "core" in ${HARNESS}/profile.json back by hand, run \`nina compose\`, ` +
+        `and delete ${HARNESS}/upgrade.json.\n`,
+    );
+    return 1;
+  }
+  const saved = new Map();
+  for (const p of stopped.saved ?? []) {
+    const copy = join(movedFrom(target), p);
+    if (existsSync(copy)) saved.set(p, readFileSync(copy));
+  }
+  const lost = (stopped.saved ?? []).filter((p) => !saved.has(p));
+  if (lost.length > 0) {
+    console.error(`  ${lost.length} of the files the move kept are missing from ${HARNESS}/upgrade-saved/, so it cannot be undone exactly: ${lost.slice(0, 5).join(', ')}${lost.length > 5 ? ', …' : ''}\n`);
+    return 1;
+  }
+  const recomposed = restore(ctx, target, profilePath, profile, stopped.from, stopped.created ?? [], saved);
+  rmSync(moveJournal(target), { force: true });
+  rmSync(movedFrom(target), { recursive: true, force: true });
+  console.log(
+    `  undid the move to ${stopped.to}: pinned ${stopped.from} again and put ${saved.size} file(s) back as they were.` +
+      `${recomposed ? '' : ' Recomposing failed along the way — run `nina compose` yourself.'} Run the move again when ready.\n`,
+  );
+  return recomposed ? 0 : 1;
+}
+
 /**
  * `nina upgrade`.
  *
@@ -176,6 +246,15 @@ export async function upgrade(argv, ctx) {
   }
   const profile = JSON.parse(await readFile(profilePath, 'utf8'));
 
+  // A move stopped half-way comes before anything else asked of this command: its pin may already name the
+  // version it was moving to, and "already pins" left the tree half-moved for good.
+  const stopped = interruptedMove(target);
+  if (argv.includes('--abort')) return abort(ctx, target, profilePath, profile, stopped);
+  if (stopped) {
+    console.error(`  ${describeMove(stopped)} \`nina upgrade --abort --project ${target}\` undoes it; then run the move again.\n`);
+    return 1;
+  }
+
   const to = arg('--to');
   if (!to) {
     console.error('  usage: nina upgrade --to <version> [--project <dir>] [--apply]\n');
@@ -354,10 +433,6 @@ export async function upgrade(argv, ctx) {
   }
 
   const previous = profile.core;
-  const pin = async (version) => {
-    profile.core = version;
-    await writeFile(profilePath, `${JSON.stringify(profile, null, 2)}\n`);
-  };
 
   // What was already failing is not this upgrade's doing, and rolling back for it would blame
   // the move for a problem the project brought with it. Measured before anything is written,
@@ -437,8 +512,12 @@ export async function upgrade(argv, ctx) {
   const keptEdited = dropped.filter((p) => edited.has(p));
   // Every file the move can touch, as it is now, so a rollback puts the tree back exactly — the
   // recompose alone would write the old composition over the owner's own edits and call it restored.
+  // That is every path either version composes for any surface, not only the declared ones: compose moves
+  // a file gated on an undeclared surface to .nina/removed/, and one left out of here stayed there after a
+  // rollback that said the tree was as it was.
+  const reachable = [...(await composedPaths(from.dir, offeredBefore)), ...(await composedPaths(onto.dir, available))];
   const saved = new Map();
-  for (const p of new Set([...pathsBefore, ...pathsAfter])) {
+  for (const p of new Set([...pathsBefore, ...pathsAfter, ...reachable])) {
     const entry = entryAt(p);
     if (entry?.isFile()) saved.set(p, readFileSync(join(target, p)));
   }
@@ -449,7 +528,31 @@ export async function upgrade(argv, ctx) {
     writeFileSync(copy, saved.get(p) ?? readFileSync(join(target, p)));
   }
 
-  await pin(to);
+  // All of it written down before the pin moves, copies first and the journal last, so a journal always has
+  // its copies. A move stopped from here on — Ctrl-C, a closed terminal, a crash — left the pin moved, the tree
+  // half-composed, and the owner's own edits, held only in this process's memory, gone; now the next run says
+  // so, and `--abort` undoes it.
+  rmSync(movedFrom(target), { recursive: true, force: true });
+  for (const [p, bytes] of saved) {
+    mkdirSync(dirname(join(movedFrom(target), p)), { recursive: true });
+    writeFileSync(join(movedFrom(target), p), bytes);
+  }
+  const journal = { from: previous, to, started: new Date().toISOString(), created, saved: [...saved.keys()] };
+  writeFileSync(`${moveJournal(target)}.tmp`, `${JSON.stringify(journal, null, 2)}\n`);
+  renameSync(`${moveJournal(target)}.tmp`, moveJournal(target));
+  // Ctrl-C reaches the step running in a child too, which dies of it, and its step fails: with this process
+  // still alive, that is an ordinary failed step, and the move rolls back. Without a listener this process died
+  // first, half-way through, with nothing left to roll anything back.
+  const hold = () => {};
+  for (const s of SIGNALS) process.on(s, hold);
+  const settle = () => {
+    for (const s of SIGNALS) process.off(s, hold);
+    rmSync(moveJournal(target), { force: true });
+    rmSync(movedFrom(target), { recursive: true, force: true });
+  };
+
+  profile.core = to;
+  writeFileSync(profilePath, `${JSON.stringify(profile, null, 2)}\n`);
   console.log(`  pinned ${to}\n`);
 
   const steps = [
@@ -473,12 +576,20 @@ export async function upgrade(argv, ctx) {
   const { failed } = runSteps(steps);
 
   if (!failed) {
+    settle();
     delete process.env.NINA_UPGRADE;
     console.log(`\n  upgrade: ${previous} → ${to} applied and verified.`);
     if (removable.length > 0) console.log(`\n  removed ${removable.length} file(s) ${to} no longer composes: ${removable.join(', ')}`);
-    if (keptEdited.length > 0) {
-      console.log(`\n  kept ${keptEdited.length} file(s) ${to} no longer composes, because they carry edits of yours — delete them once nothing in them is needed:`);
-      for (const p of keptEdited) console.log(`      ${p}`);
+    // A file gated on a surface the project does not declare is moved aside by compose itself, edited or not.
+    const stillKept = keptEdited.filter((p) => entryAt(p));
+    const setAside = keptEdited.filter((p) => !entryAt(p));
+    if (stillKept.length > 0) {
+      console.log(`\n  kept ${stillKept.length} file(s) ${to} no longer composes, because they carry edits of yours — delete them once nothing in them is needed:`);
+      for (const p of stillKept) console.log(`      ${p}`);
+    }
+    if (setAside.length > 0) {
+      console.log(`\n  moved ${setAside.length} file(s) with edits of yours to ${REMOVED}/, since ${to} composes them only for a surface this project does not declare:`);
+      for (const p of setAside) console.log(`      ${p}`);
     }
     if (occupied.length > 0) {
       console.log(`\n  replaced ${occupied.length} file(s) of yours with what ${to} composes there — the originals are in ${HARNESS}/replaced/:`);
@@ -530,15 +641,10 @@ export async function upgrade(argv, ctx) {
   }
 
   console.log(`\n  ✗ ${failed.label} failed — rolling back to ${previous}.\n`);
-  await pin(previous);
-  for (const p of created) rmSync(join(target, p), { force: true });
-  const recomposed = nina(ctx, target, ['compose', '--project', target]);
-  for (const [p, bytes] of saved) {
-    mkdirSync(dirname(join(target, p)), { recursive: true });
-    writeFileSync(join(target, p), bytes);
-  }
+  const recomposed = restore(ctx, target, profilePath, profile, previous, created, saved);
+  settle();
   console.log(
-    recomposed.ok
+    recomposed
       ? `  rolled back: pinned ${previous} and recomposed. The tree is as it was.\n`
       : `  rolled back the pin to ${previous}, but recomposing failed — run \`nina compose\` yourself.\n`,
   );

package/src/guard.mjs

@@ -20,21 +20,18 @@
 import { closeSync, existsSync, openSync, readFileSync, readSync, realpathSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { composedPaths } from './commands/compose.mjs';
+import { NOTICE_HEAD, composedPaths, noticeOf } from './commands/compose.mjs';
 import { HARNESS } 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 };
+
 /** The package this runs from: its releases say whether a pinned version ships the guard. */
 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' };
 
-/**
- * How far into a file the notice is looked for: below a frontmatter block, or a shebang. The compose
- * suite holds every composed file's notice inside it.
- */
-export const NOTICE_HEAD = 60;
-
 /** 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;
 
@@ -69,35 +66,6 @@ function head(path) {
   }
 }
 
-/**
- * A composed file's notice, as one sentence without its comment syntax, or null when it has none.
- *
- * @param {string} text - The file.
- * @returns {string|null}
- */
-export function noticeOf(text) {
-  const lines = String(text).split('\n').slice(0, NOTICE_HEAD);
-  const at = lines.findIndex((l) => /^(<!--|\/\/) nina:generated/.test(l));
-  if (at < 0) return null;
-  const block = [];
-  if (lines[at].startsWith('//')) {
-    for (const line of lines.slice(at)) {
-      if (!line.startsWith('//')) break;
-      block.push(line.replace(/^\/\/ ?/, ''));
-    }
-  } else {
-    // The notice's own delimiters, taken off by position: this reads text the compiler wrote, it filters
-    // nothing, and a pattern for it read to a scanner as an HTML sanitizer that misses `--!>`.
-    for (const line of lines.slice(at)) {
-      const open = line.startsWith('<!-- ') ? line.slice('<!-- '.length) : line;
-      const end = open.lastIndexOf('-->');
-      block.push(end >= 0 ? open.slice(0, end) : open);
-      if (end >= 0) break;
-    }
-  }
-  return block.map((l) => l.trim()).join(' ');
-}
-
 /**
  * Handles one hook event: the JSON to print, or null to let the call through. Never throws.
  *
@@ -121,7 +89,9 @@ export async function handleEdit(input, { root, pkg = PACKAGE }) {
     if (!pinned) return null;
     const target = isAbsolute(path) ? path : resolve(input.cwd ?? root, path);
     if (!existsSync(target)) return null;
-    const rel = relative(realpathSync(root), realpathSync(target)).split(sep).join('/');
+    // The native call returns the name as it is on disk: where case is ignored, `claude.md` is CLAUDE.md, and
+    // read as spelled it reached no composed path and let the edit through.
+    const rel = relative(realpathSync.native(root), realpathSync.native(target)).split(sep).join('/');
     // Outside the project, or in its own layer — where a change to a composed file belongs.
     if (rel.startsWith('..') || isAbsolute(rel) || rel.split('/')[0] === HARNESS) return null;
     const notice = noticeOf(head(target));

package/src/paths.mjs

@@ -8,7 +8,7 @@
  * project, and losing it is irreversible — so it lives in the user's own directory.
  */
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 
@@ -100,3 +100,52 @@ export function legacyHint(target) {
     ? ` — this project still has .harness/, which is what ${HARNESS}/ used to be called. Rename it; do not start over.`
     : '';
 }
+
+/**
+ * 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.
+ * It is written before the pin moves and removed once the move is verified or rolled back, so one that is
+ * still there is a move that was stopped half-way.
+ *
+ * @param {string} target - The project.
+ * @returns {string}
+ */
+export const moveJournal = (target) => join(target, HARNESS, 'upgrade.json');
+
+/**
+ * Where an in-flight move keeps the files it can touch, as they were before it — at their own paths below.
+ *
+ * @param {string} target - The project.
+ * @returns {string}
+ */
+export const movedFrom = (target) => join(target, HARNESS, 'upgrade-saved');
+
+/**
+ * The move a project was left in when `upgrade --apply` was stopped before it finished, or null when none is.
+ *
+ * A pin that moved with the composed files half-written looks like hand edits to every check, and the
+ * owner's own edits it was about to put back lived only in the stopped process's memory. This is what says
+ * so instead, and what `nina upgrade --abort` undoes it from.
+ *
+ * @param {string} target - The project.
+ * @returns {{from: string, to: string, started: string, created: string[], saved: string[]}|{unreadable: string}|null}
+ */
+export function interruptedMove(target) {
+  try {
+    return JSON.parse(readFileSync(moveJournal(target), 'utf8'));
+  } catch (error) {
+    return error.code === 'ENOENT' ? null : { unreadable: error.message };
+  }
+}
+
+/**
+ * A stopped move, said once for every command that finds one.
+ *
+ * @param {NonNullable<ReturnType<typeof interruptedMove>>} stopped - The move.
+ * @returns {string}
+ */
+export function describeMove(stopped) {
+  return stopped.unreadable
+    ? `An upgrade was stopped before it finished, and its journal ${HARNESS}/upgrade.json cannot be read (${stopped.unreadable}).`
+    : `An upgrade from ${stopped.from} to ${stopped.to}, started ${stopped.started}, was stopped before it finished — the pin and the composed files may be half-moved.`;
+}

package/src/prices.mjs

@@ -15,7 +15,7 @@
 /** The date the table was read, printed beside every estimate made from it. */
 export const PRICES_AS_OF = '2026-06-24';
 
-/** model id prefix → $/MTok. Longest prefix wins, so `claude-opus-5-5` is not read as `claude-opus-5`. */
+/** model id → $/MTok. */
 const PRICES = {
   'claude-fable-5-1': { input: 10, output: 50, read: 0.25 },
   'claude-mythos-5-1': { input: 10, output: 50 },
@@ -39,12 +39,12 @@ const PRICES = {
  * @returns {{input: number, output: number, read: number, write5m: number, write1h: number}|null}
  */
 export function priceOf(model) {
-  const id = String(model ?? '');
-  const key = Object.keys(PRICES)
-    .filter((k) => id === k || id.startsWith(`${k}-`) || id.startsWith(`${k}[`))
-    .sort((a, b) => b.length - a.length)[0];
-  if (!key) return null;
-  const p = PRICES[key];
+  // The id itself, less the two suffixes a transcript adds to one: a context window (`[1m]`) and a snapshot
+  // date (`-20251001`). Matched by prefix, a model newer than the table was priced as the one before it —
+  // `claude-opus-5-6` as Opus 5, at five times its cache reads.
+  const id = String(model ?? '').replace(/\[[^\]]*\]$/, '').replace(/-\d{8}$/, '');
+  const p = Object.hasOwn(PRICES, id) ? PRICES[id] : null;
+  if (!p) return null;
   return { input: p.input, output: p.output, read: p.read ?? p.input * 0.1, write5m: p.input * 1.25, write1h: p.input * 2 };
 }
 

package/src/vocabulary.mjs

@@ -16,6 +16,17 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+/**
+ * A vocabulary name: capitals, digits and `_`, from a letter — `{{S3_BUCKET}}` as much as `{{OWNER}}`. Every
+ * reader of a placeholder reads it with this one grammar. Compose took any name the profile declared while
+ * `check`, `init` and `upgrade` looked only for capitals and `_`, so `{{S3_BUCKET}}` was reported as declared
+ * and referenced by nothing, and deleting it on that advice composed the placeholder raw, with nobody saying so.
+ */
+export const NAME = /^[A-Z][A-Z0-9_]*$/;
+
+/** A placeholder in a text, its name captured. */
+export const PLACEHOLDER = /\{\{([A-Z][A-Z0-9_]*)\}\}/g;
+
 /**
  * The defaults a layer root supplies, name → value. Anything that is not a string under an
  * upper-case name is ignored rather than trusted: a default reaches every project that pins it.
@@ -26,7 +37,7 @@ import { join } from 'node:path';
 export function defaultVocabulary(layerRoot) {
   try {
     const parsed = JSON.parse(readFileSync(join(layerRoot, 'core', 'vocabulary.json'), 'utf8'));
-    return Object.fromEntries(Object.entries(parsed).filter(([name, value]) => /^[A-Z_]+$/.test(name) && typeof value === 'string'));
+    return Object.fromEntries(Object.entries(parsed).filter(([name, value]) => NAME.test(name) && typeof value === 'string'));
   } catch {
     return {};
   }

package/src/wiring.mjs

@@ -205,21 +205,77 @@ function groupsFor(hooks, event) {
   return Array.isArray(hooks[event]) ? hooks[event] : null;
 }
 
+/** Whether one hook command runs a hook's script, recognised by what it runs, not by its exact text. */
+function runsCommand(x, h) {
+  const cmd = String(x?.command ?? '');
+  return cmd.includes(h.script) && (!h.mode || cmd.includes(h.mode));
+}
+
+/** Whether a settings group runs a hook's script. */
+function runs(g, h) {
+  return Boolean(g) && typeof g === 'object' && Array.isArray(g.hooks) && g.hooks.some((x) => runsCommand(x, h));
+}
+
+/** A matcher that reaches every tool: none, empty, or `*`. */
+const everyTool = (m) => m === undefined || m === null || m === '' || m === '*';
+
+/** A matcher this can read and rewrite: every tool, or a list of exact names. A regular expression is its owner's. */
+const plainMatcher = (m) => everyTool(m) || (typeof m === 'string' && /^[A-Za-z0-9_|]+$/.test(m));
+
+/** Whether two matchers reach a tool in common — unknown for a regular expression, taken as no. */
+function overlaps(a, b) {
+  if (everyTool(a) || everyTool(b)) return true;
+  if (!plainMatcher(a) || !plainMatcher(b)) return false;
+  const names = new Set(a.split('|'));
+  return b.split('|').some((n) => names.has(n));
+}
+
+/** Whether two of these groups run on a tool they share, so the hook runs once per group there. */
+const doubled = (groups) => groups.some((g, i) => groups.slice(i + 1).some((other) => overlaps(g.matcher, other.matcher)));
+
 /**
  * Whether settings already run a hook. Recognised by what the command runs, not by its exact text —
  * a project may have written its own — and by a matcher that reaches every tool the hook needs.
  */
 function covered(hooks, h) {
-  const groups = groupsFor(hooks, h.event) ?? [];
   const need = h.matcher ? h.matcher.split('|') : [];
-  return groups.some((g) => {
-    if (!g || typeof g !== 'object') return false;
-    if (!need.every((tool) => matcherReaches(g.matcher, tool))) return false;
-    return Array.isArray(g.hooks) && g.hooks.some((x) => {
-      const cmd = String(x?.command ?? '');
-      return cmd.includes(h.script) && (!h.mode || cmd.includes(h.mode));
-    });
-  });
+  return (groupsFor(hooks, h.event) ?? []).some((g) => runs(g, h) && need.every((tool) => matcherReaches(g.matcher, tool)));
+}
+
+/**
+ * The hooks a project runs, from both settings files merged by event — Claude Code runs both, so a hook
+ * kept in the local file counts. Every reader asks this one: `wire` used to read the shared file alone,
+ * and appended a second copy of each hook a project kept in its local file, which then ran twice.
+ *
+ * @param {string} target - The project directory.
+ * @param {(event: string) => boolean} [wanted] - Events whose malformed lists are worth a problem.
+ * @returns {Promise<{merged: Record<string, object[]>, problems: string[]}>} Each merged group says `from` which file.
+ */
+async function projectHooks(target, wanted = () => false) {
+  const merged = {};
+  const problems = [];
+  for (const rel of SETTINGS_FILES) {
+    const path = join(target, rel);
+    if (!existsSync(path)) continue;
+    let settings;
+    try {
+      settings = JSON.parse(await readFile(path, 'utf8'));
+    } catch (error) {
+      problems.push(`${rel} is not valid JSON — ${error.message}`);
+      continue;
+    }
+    const shape = settings?.hooks;
+    if (shape === undefined || shape === null) continue;
+    if (typeof shape !== 'object' || Array.isArray(shape)) {
+      problems.push(`${rel} has a "hooks" that is not an object of event lists — no hook in it can run`);
+      continue;
+    }
+    for (const [event, groups] of Object.entries(shape)) {
+      if (Array.isArray(groups)) (merged[event] ??= []).push(...groups.map((g) => (g && typeof g === 'object' ? { ...g, from: rel } : g)));
+      else if (wanted(event)) problems.push(`${rel}'s hooks.${event} is not a list — no hook in it can run`);
+    }
+  }
+  return { merged, problems };
 }
 
 /** The command settings run for a hook, when they run one — the selftest runs it the same way. */
@@ -299,29 +355,16 @@ export async function missingWiring(target, shipped) {
   }
   const wanted = HOOKS.filter((h) => shipped.has(h.script));
   if (wanted.length === 0) return out;
-  const merged = {};
-  for (const rel of SETTINGS_FILES) {
-    const path = join(target, rel);
-    if (!existsSync(path)) continue;
-    let settings;
-    try {
-      settings = JSON.parse(await readFile(path, 'utf8'));
-    } catch (error) {
-      out.push(`${rel} is not valid JSON — ${error.message}`);
-      continue;
-    }
-    const shape = settings?.hooks;
-    if (shape === undefined || shape === null) continue;
-    if (typeof shape !== 'object' || Array.isArray(shape)) {
-      out.push(`${rel} has a "hooks" that is not an object of event lists — no hook in it can run`);
-      continue;
-    }
-    for (const [event, groups] of Object.entries(shape)) {
-      if (Array.isArray(groups)) (merged[event] ??= []).push(...groups);
-      else if (wanted.some((h) => h.event === event)) out.push(`${rel}'s hooks.${event} is not a list — no hook in it can run`);
-    }
-  }
+  const { merged, problems } = await projectHooks(target, (event) => wanted.some((h) => h.event === event));
+  out.push(...problems);
   for (const h of wanted) {
+    const running = (merged[h.event] ?? []).filter((g) => runs(g, h));
+    if (doubled(running)) {
+      out.push(
+        `${running.length} ${h.event} groups run \`${h.script}${h.mode ? ` ${h.mode}` : ''}\` for tools they share, so it runs once per group there — ` +
+          '`nina wire --apply` makes them one',
+      );
+    }
     if (covered(merged, h)) continue;
     out.push(
       `.claude/settings.json has no ${h.event} hook${h.matcher ? ` for ${h.matcher}` : ''} running \`${h.script}${h.mode ? ` ${h.mode}` : ''}\` — without it ${h.why}`,
@@ -359,13 +402,9 @@ export async function staleHooks(target, shipped) {
  * @returns {Promise<string|null>} Null when nothing is missing.
  */
 export async function missingFragment(target, shipped) {
-  let settings = null;
-  try {
-    settings = JSON.parse(await readFile(join(target, '.claude', 'settings.json'), 'utf8'));
-  } catch {
-    // Absent or unreadable: everything is missing, and `missingWiring` says which.
-  }
-  const lacking = HOOKS.filter((h) => shipped.has(h.script) && !covered(settings?.hooks, h));
+  // Absent or unreadable files hold nothing: everything they would have held is missing, and `missingWiring` says why.
+  const { merged } = await projectHooks(target);
+  const lacking = HOOKS.filter((h) => shipped.has(h.script) && !covered(merged, h));
   return lacking.length === 0 ? null : JSON.stringify({ hooks: settingsHooks(lacking) }, null, 2);
 }
 
@@ -405,10 +444,36 @@ export async function applyWiring(target, shipped, { settings: editSettings = tr
     if (readable) {
       const hooks = settings.hooks ?? {};
       const added = [];
+      const { merged } = await projectHooks(target);
       for (const h of HOOKS.filter((h) => shipped.has(h.script))) {
-        if (covered(hooks, h)) continue;
-        (hooks[h.event] ??= []).push(group(h));
-        added.push(`${h.event}${h.matcher ? ` (${h.matcher})` : ''} → ${h.script}${h.mode ? ` ${h.mode}` : ''}`);
+        const running = (merged[h.event] ?? []).filter((g) => runs(g, h));
+        if (covered(merged, h) && !doubled(running)) continue;
+        const named = `${h.event}${h.matcher ? ` (${h.matcher})` : ''} → ${h.script}${h.mode ? ` ${h.mode}` : ''}`;
+        if (running.length === 0) {
+          (hooks[h.event] ??= []).push(group(h));
+          added.push(named);
+          continue;
+        }
+        // The groups that already run the script become one that reaches every tool it needs. A second group
+        // beside a narrower one — or two left as they were — runs it on the tools they share once per group, and
+        // the gate counts each of those events twice. A group in the local file, or one matched by a regular
+        // expression, is its owner's to change: said, and not doubled.
+        const foreign = running.find((g) => g.from !== '.claude/settings.json' || !plainMatcher(g.matcher));
+        if (foreign) {
+          problems.push(
+            `${foreign.from} runs ${h.script} for "${foreign.matcher ?? ''}" — make every group that runs it there one, reaching ${h.matcher ?? 'every tool'}; ` +
+              'another group beside it would run it twice',
+          );
+          continue;
+        }
+        const mine = (hooks[h.event] ?? []).filter((g) => runs(g, h));
+        const keep = mine.find((g) => everyTool(g.matcher)) ?? mine[0];
+        if (!everyTool(keep.matcher)) {
+          keep.matcher = [...new Set([...mine.flatMap((g) => g.matcher.split('|')), ...(h.matcher ? h.matcher.split('|') : [])])].join('|');
+        }
+        for (const g of mine) if (g !== keep) g.hooks = g.hooks.filter((x) => !runsCommand(x, h));
+        hooks[h.event] = hooks[h.event].filter((g) => !Array.isArray(g?.hooks) || g.hooks.length > 0);
+        added.push(`${named} (${mine.length > 1 ? `${mine.length} groups made one, ` : ''}reaching ${everyTool(keep.matcher) ? 'every tool' : keep.matcher})`);
       }
       // An old command, exactly as it was written, learns to say when its script cannot start, and how to
       // install NINA as it is installed now.