@massu/core 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -10,6 +10,71 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 > redistributed under the **Apache License 2.0**. Full license + NOTICE:
 > `packages/core/assets/embedder/MODEL-LICENSE`.
 
+## [2.5.0] - 2026-08-01
+
+### Fixed
+
+- **`install-hooks` ADDED a hook registration instead of REPLACING it, so every version bump
+  doubled the hooks — and that defect BLOCKED ITS OWN REMEDY.** `mergeHookEntries` deduped by
+  EXACT COMMAND STRING, and the emitted command embeds the version, so
+  `npx -y @massu/core@1.16.2 hook-runner user-prompt` and the `@2.4.0` form were two different
+  strings, two different hooks, BOTH kept. The command was simultaneously the payload and the
+  identity, so any payload change forged a new identity.
+
+  Measured, not theoretical: one workspace carried `1.15.5` x16 **and** `1.15.2` x15 at once,
+  with 15 hook names firing TWICE per event and writing double telemetry indefinitely. Worse,
+  because upgrading duplicated, nobody upgraded — 9 of 10 workspaces on this machine sat on a
+  pre-2.0.0 version whose `better-sqlite3` ABI did not match the running Node, and one had
+  **26,119 `NODE_MODULE_VERSION` hook failures**: a total massu outage. It stayed invisible
+  because a crashing hook still **exits 0**.
+
+  Registration identity is now the `hook-runner` subcommand — a stable CLI contract (`cli.ts`
+  dispatches on exactly that token), invariant under both a version bump and a launch-mechanism
+  change. Non-massu entries keep the historical exact-command semantics, so a customer's own
+  hooks are never touched or collapsed.
+
+  Proof it can fail (CR-72, planted in the real tree, restored byte-identical by sha256):
+  reverting the identity branch to exact-command dedup turns
+  `installer-registration-identity-drift-guard.test.ts` RED — that guard drives the REAL
+  `installHooks()` over a real temp project seeded with an older-version block, a node-direct
+  block and a customer hook.
+
+### Added
+
+- **A version-stable launcher shim, cutting ~0.86s of npm bootstrap off each hook fire.**
+  `npx -y @massu/core@<v> …` spends ~0.86s starting npm before any massu code runs. Measured
+  interleaved, min-of-5: `npx` 0.97s, `npx --offline` 0.88s, `node <cli.js>` 0.11s — so the
+  cost is npm's own startup, NOT the registry, and no npx flag addresses it.
+
+  `install-hooks` now writes `~/.massu/bin/massu-hook` and emits
+  `"~/.massu/bin/massu-hook" <version> hook-runner <name>`. That path is VERSION-STABLE, and
+  the shim re-resolves the runtime AT FIRE TIME, exec'ing npx when it is absent.
+
+  This deliberately does NOT bake a versioned absolute path, which would reintroduce the class
+  P-003 (v1.9.4) eliminated: such a path is "invalidated by cache clears, global-install
+  relocations, or npx upgrades — silently 404-ing the hooks". Probing at emit time says nothing
+  about invalidation after emit. Three fail-safe layers instead — shim missing at emit emits
+  npx; runtime missing at fire execs npx; both present takes the fast path — so no single
+  missing artifact is fatal and a stale registration self-heals.
+
+  Measured after: fast path **0.11s vs npx 1.07s (9.7x)**. The fallback is mutation-proven — a
+  shim with its npx branch removed FAILS the same no-runtime case (exit 27), so the test is not
+  vacuous. `exec` in both branches preserves stdin, stdout and the exit code.
+
+  Semver MINOR: `massuHookIdentity`, `massuShimPath`, `massuShimBody`, `installMassuShim`,
+  `resolveMassuShim`, `massuRuntimeDir`, `massuRuntimeCliPath`, `resolveMassuRuntimeCli` and
+  `materializeMassuRuntime` are new exports. `MASSU_NO_NODE_DIRECT=1` forces the npx form.
+
+### Changed
+
+- **CR-70 Layer 3 amended: installer symmetry is no longer npx-specific.** Both emitters read
+  one resolver and agree on mechanism AND pinned version. The drift-guard previously asserted
+  the literal `'npx'`, which pinned an implementation detail rather than the property — it
+  would go RED on a correct mechanism change and GREEN on a wrong one that used npx on both
+  sides. Three assertions were amended on the same grounds
+  (`init-hook-paths-no-absolute`, `init-mcp-json-pin`, `cli.test.ts`); each keeps its original
+  protection of a visible pinned version and a known launch mechanism.
+
 ## [2.4.0] - 2026-07-31
 
 ### Fixed

package/dist/cli.js

@@ -15980,14 +15980,23 @@ __export(init_exports, {
   getInstallerVersion: () => getInstallerVersion,
   initMemoryDir: () => initMemoryDir,
   installHooks: () => installHooks,
+  installMassuShim: () => installMassuShim,
   isTemplateName: () => isTemplateName,
   listTemplates: () => listTemplates,
+  massuHookIdentity: () => massuHookIdentity,
+  massuRuntimeCliPath: () => massuRuntimeCliPath,
+  massuRuntimeDir: () => massuRuntimeDir,
+  massuShimBody: () => massuShimBody,
+  massuShimPath: () => massuShimPath,
+  materializeMassuRuntime: () => materializeMassuRuntime,
   mergeHooksConfig: () => mergeHooksConfig,
   parseInitArgs: () => parseInitArgs,
   printInitHelp: () => printInitHelp,
   registerMcpServer: () => registerMcpServer,
   renderConfigYaml: () => renderConfigYaml,
   resolveHooksDir: () => resolveHooksDir,
+  resolveMassuRuntimeCli: () => resolveMassuRuntimeCli,
+  resolveMassuShim: () => resolveMassuShim,
   resolveTemplatesDir: () => resolveTemplatesDir,
   runInit: () => runInit,
   validateWrittenConfig: () => validateWrittenConfig,
@@ -15997,6 +16006,7 @@ import { closeSync as closeSync4, existsSync as existsSync19, fsyncSync as fsync
 import { resolve as resolve9, basename as basename6, dirname as dirname12 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { homedir as homedir7 } from "os";
+import { execFileSync as execFileSync2 } from "child_process";
 import { stringify as yamlStringify, parse as yamlParse } from "yaml";
 function detectFramework(projectRoot) {
   const result = {
@@ -16570,11 +16580,8 @@ function registerMcpServer(projectRoot) {
     return false;
   }
   const version = getInstallerVersion();
-  servers.massu = {
-    type: "stdio",
-    command: "npx",
-    args: ["-y", `@massu/core@${version}`]
-  };
+  const shim = resolveMassuShim();
+  servers.massu = shim !== null ? { type: "stdio", command: shim, args: [version] } : { type: "stdio", command: "npx", args: ["-y", `@massu/core@${version}`] };
   existing.mcpServers = servers;
   writeFileSync5(mcpPath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
   return true;
@@ -16591,7 +16598,98 @@ function resolveHooksDir() {
   }
   return "node_modules/@massu/core/dist/hooks";
 }
-function hookCmd(version, hookName) {
+function massuRuntimeDir(version) {
+  return resolve9(homedir7(), ".massu", "runtime", version);
+}
+function massuRuntimeCliPath(version) {
+  return resolve9(massuRuntimeDir(version), "node_modules", "@massu", "core", "dist", "cli.js");
+}
+function resolveMassuRuntimeCli(version) {
+  if (process.env.MASSU_NO_NODE_DIRECT === "1") return null;
+  const cli = massuRuntimeCliPath(version);
+  if (!existsSync19(cli)) return null;
+  try {
+    execFileSync2(process.execPath, [cli, "--version"], { stdio: "ignore", timeout: 2e4 });
+    return cli;
+  } catch {
+    return null;
+  }
+}
+function materializeMassuRuntime(version) {
+  if (process.env.MASSU_NO_NODE_DIRECT === "1") return false;
+  if (resolveMassuRuntimeCli(version) !== null) return true;
+  const dir = massuRuntimeDir(version);
+  try {
+    mkdirSync10(dir, { recursive: true });
+    execFileSync2(
+      "npm",
+      ["install", "--prefix", dir, `@massu/core@${version}`, "--no-audit", "--no-fund", "--loglevel=error"],
+      { stdio: "ignore", timeout: 3e5 }
+    );
+  } catch {
+    return false;
+  }
+  return resolveMassuRuntimeCli(version) !== null;
+}
+function massuShimPath() {
+  return resolve9(homedir7(), ".massu", "bin", "massu-hook");
+}
+function massuShimBody() {
+  return `#!/bin/sh
+# massu launcher shim \u2014 GENERATED, do not edit. Recreated by \`massu install-hooks\`.
+#
+# usage: massu-hook <version> <subcommand...>
+#
+# Resolves the massu runtime AT FIRE TIME so a deleted/moved runtime degrades to npx
+# instead of silently 404-ing the hook (the P-003 failure class). exec preserves stdin,
+# stdout, stderr and the exit code.
+set -u
+if [ "$#" -lt 1 ]; then
+  echo "massu-hook: missing <version> argument" >&2
+  exit 2
+fi
+MASSU_VERSION="$1"
+shift
+MASSU_CLI="\${HOME}/.massu/runtime/\${MASSU_VERSION}/node_modules/@massu/core/dist/cli.js"
+if [ -f "$MASSU_CLI" ]; then
+  exec node "$MASSU_CLI" "$@"
+fi
+exec npx -y "@massu/core@\${MASSU_VERSION}" "$@"
+`;
+}
+function installMassuShim() {
+  if (process.env.MASSU_NO_NODE_DIRECT === "1") return false;
+  if (process.platform === "win32") return false;
+  const shim = massuShimPath();
+  try {
+    mkdirSync10(dirname12(shim), { recursive: true });
+    writeFileSync5(shim, massuShimBody(), "utf-8");
+    chmodSync5(shim, 493);
+  } catch {
+    return false;
+  }
+  try {
+    execFileSync2(shim, [], { stdio: "ignore", timeout: 1e4 });
+    return false;
+  } catch (e2) {
+    const status = e2.status;
+    return status === 2;
+  }
+}
+function resolveMassuShim() {
+  if (process.env.MASSU_NO_NODE_DIRECT === "1") return null;
+  if (process.platform === "win32") return null;
+  const shim = massuShimPath();
+  if (!existsSync19(shim)) return null;
+  try {
+    execFileSync2(shim, [], { stdio: "ignore", timeout: 1e4 });
+    return null;
+  } catch (e2) {
+    return e2.status === 2 ? shim : null;
+  }
+}
+function hookCmd(version, hookName, shim) {
+  if (shim !== null) return `"${shim}" ${version} hook-runner ${hookName}`;
   return `npx -y @massu/core@${version} hook-runner ${hookName}`;
 }
 function getHookTimeout(name) {
@@ -16599,11 +16697,12 @@ function getHookTimeout(name) {
 }
 function buildHooksConfig(_hooksDir) {
   const version = getInstallerVersion();
+  const shim = resolveMassuShim();
   return {
     SessionStart: [
       {
         hooks: [
-          { type: "command", command: hookCmd(version, "session-start"), timeout: getHookTimeout("session-start") }
+          { type: "command", command: hookCmd(version, "session-start", shim), timeout: getHookTimeout("session-start") }
         ]
       }
     ],
@@ -16618,26 +16717,26 @@ function buildHooksConfig(_hooksDir) {
       {
         matcher: "Bash|Write|Edit",
         hooks: [
-          { type: "command", command: hookCmd(version, "pre-tool-use-gate"), timeout: getHookTimeout("pre-tool-use-gate") }
+          { type: "command", command: hookCmd(version, "pre-tool-use-gate", shim), timeout: getHookTimeout("pre-tool-use-gate") }
         ]
       }
     ],
     PostToolUse: [
       {
         hooks: [
-          { type: "command", command: hookCmd(version, "post-tool-use"), timeout: getHookTimeout("post-tool-use") },
-          { type: "command", command: hookCmd(version, "quality-event"), timeout: getHookTimeout("quality-event") },
-          { type: "command", command: hookCmd(version, "cost-tracker"), timeout: getHookTimeout("cost-tracker") }
+          { type: "command", command: hookCmd(version, "post-tool-use", shim), timeout: getHookTimeout("post-tool-use") },
+          { type: "command", command: hookCmd(version, "quality-event", shim), timeout: getHookTimeout("quality-event") },
+          { type: "command", command: hookCmd(version, "cost-tracker", shim), timeout: getHookTimeout("cost-tracker") }
         ]
       },
       {
         matcher: "Edit|Write",
         hooks: [
-          { type: "command", command: hookCmd(version, "post-edit-context"), timeout: getHookTimeout("post-edit-context") },
+          { type: "command", command: hookCmd(version, "post-edit-context", shim), timeout: getHookTimeout("post-edit-context") },
           // Auto-learning pipeline — classifies failures and detects fixes on
           // file changes. See Phase 5-6 of the autodetect plan.
-          { type: "command", command: hookCmd(version, "fix-detector"), timeout: getHookTimeout("fix-detector") },
-          { type: "command", command: hookCmd(version, "classify-failure"), timeout: getHookTimeout("classify-failure") }
+          { type: "command", command: hookCmd(version, "fix-detector", shim), timeout: getHookTimeout("fix-detector") },
+          { type: "command", command: hookCmd(version, "classify-failure", shim), timeout: getHookTimeout("classify-failure") }
         ]
       },
       {
@@ -16645,35 +16744,35 @@ function buildHooksConfig(_hooksDir) {
         hooks: [
           // Incident + rule enforcement pipelines fire on Write-only (incidents
           // are authored as .md files; rules are enforced after new-file drops).
-          { type: "command", command: hookCmd(version, "incident-pipeline"), timeout: getHookTimeout("incident-pipeline") },
-          { type: "command", command: hookCmd(version, "rule-enforcement-pipeline"), timeout: getHookTimeout("rule-enforcement-pipeline") }
+          { type: "command", command: hookCmd(version, "incident-pipeline", shim), timeout: getHookTimeout("incident-pipeline") },
+          { type: "command", command: hookCmd(version, "rule-enforcement-pipeline", shim), timeout: getHookTimeout("rule-enforcement-pipeline") }
         ]
       }
     ],
     Stop: [
       {
         hooks: [
-          { type: "command", command: hookCmd(version, "session-end"), timeout: getHookTimeout("session-end") },
+          { type: "command", command: hookCmd(version, "session-end", shim), timeout: getHookTimeout("session-end") },
           // Session-end auto-learning aggregation (failure-class roll-up).
-          { type: "command", command: hookCmd(version, "auto-learning-pipeline"), timeout: getHookTimeout("auto-learning-pipeline") }
+          { type: "command", command: hookCmd(version, "auto-learning-pipeline", shim), timeout: getHookTimeout("auto-learning-pipeline") }
         ]
       }
     ],
     PreCompact: [
       {
         hooks: [
-          { type: "command", command: hookCmd(version, "pre-compact"), timeout: getHookTimeout("pre-compact") }
+          { type: "command", command: hookCmd(version, "pre-compact", shim), timeout: getHookTimeout("pre-compact") }
         ]
       }
     ],
     UserPromptSubmit: [
       {
         hooks: [
-          { type: "command", command: hookCmd(version, "user-prompt"), timeout: getHookTimeout("user-prompt") },
-          { type: "command", command: hookCmd(version, "intent-suggester"), timeout: getHookTimeout("intent-suggester") },
+          { type: "command", command: hookCmd(version, "user-prompt", shim), timeout: getHookTimeout("user-prompt") },
+          { type: "command", command: hookCmd(version, "intent-suggester", shim), timeout: getHookTimeout("intent-suggester") },
           // plan-living-memory-slice-1 P3-002: automatic relevant-recall.
           // Injects a compact "🧠 Relevant memory" block; fails open (empty).
-          { type: "command", command: hookCmd(version, "memory-recall"), timeout: getHookTimeout("memory-recall") }
+          { type: "command", command: hookCmd(version, "memory-recall", shim), timeout: getHookTimeout("memory-recall") }
         ]
       }
     ]
@@ -16711,21 +16810,31 @@ function mergeHooksConfig(existing, additions) {
   }
   return merged;
 }
+function massuHookIdentity(command) {
+  if (!/@massu\/core|[/\\]\.?massu[/\\]/.test(command)) return null;
+  const m3 = /\bhook-runner\s+([A-Za-z0-9._-]+)/.exec(command);
+  return m3 ? m3[1] : null;
+}
 function mergeHookEntries(existing, additions) {
-  const seen = /* @__PURE__ */ new Set();
+  const seenCommands = /* @__PURE__ */ new Set();
+  const seenIdentities = /* @__PURE__ */ new Set();
   const result = [];
-  for (const entry of additions ?? []) {
-    if (!entry || typeof entry.command !== "string") continue;
-    if (seen.has(entry.command)) continue;
-    seen.add(entry.command);
-    result.push(entry);
-  }
-  for (const entry of existing ?? []) {
-    if (!entry || typeof entry.command !== "string") continue;
-    if (seen.has(entry.command)) continue;
-    seen.add(entry.command);
+  const take = (entry) => {
+    if (!entry || typeof entry.command !== "string") return;
+    const identity = massuHookIdentity(entry.command);
+    if (identity !== null) {
+      if (seenIdentities.has(identity)) return;
+      seenIdentities.add(identity);
+      seenCommands.add(entry.command);
+      result.push(entry);
+      return;
+    }
+    if (seenCommands.has(entry.command)) return;
+    seenCommands.add(entry.command);
     result.push(entry);
-  }
+  };
+  for (const entry of additions ?? []) take(entry);
+  for (const entry of existing ?? []) take(entry);
   return result;
 }
 function installHooks(projectRoot) {
@@ -18716,6 +18825,16 @@ async function runInstallHooks() {
   console.log("Massu AI - Hook Installation");
   console.log("============================");
   console.log("");
+  const version = getInstallerVersion();
+  const shimOk = installMassuShim();
+  const runtimeOk = materializeMassuRuntime(version);
+  if (shimOk && runtimeOk) {
+    console.log("  Launcher: shim + runtime ready (fast path, ~9x cheaper per hook)");
+  } else if (shimOk) {
+    console.log("  Launcher: shim ready, runtime unavailable \u2014 shim will fall back to npx at fire time");
+  } else {
+    console.log("  Launcher: npx (shim unavailable \u2014 works, ~0.9s slower per hook)");
+  }
   const { count } = installHooks(projectRoot);
   console.log(`  Installed ${count} hooks in .claude/settings.local.json`);
   console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massu/core",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "AI Engineering Governance MCP Server - Session memory, knowledge system, feature registry, code intelligence, rule enforcement, tiered tooling (12 free / 73 total), 56 workflow commands, 11 agents, 20+ patterns",
   "main": "./dist/cli.js",