failproofai 0.0.10-beta.0 → 0.0.10-beta.2

package/dist/cli.mjs

@@ -16,7 +16,7 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // src/hooks/types.ts
-var HOOK_SCOPES, INTEGRATION_TYPES, CODEX_HOOK_SCOPES, CODEX_HOOK_EVENT_TYPES, CODEX_EVENT_MAP, COPILOT_HOOK_SCOPES, COPILOT_HOOK_EVENT_TYPES, CURSOR_HOOK_SCOPES, CURSOR_HOOK_EVENT_TYPES, CURSOR_EVENT_MAP, OPENCODE_HOOK_SCOPES, OPENCODE_HOOK_EVENT_TYPES, PI_HOOK_SCOPES, PI_HOOK_EVENT_TYPES, PI_EVENT_MAP, GEMINI_HOOK_SCOPES, GEMINI_HOOK_EVENT_TYPES, GEMINI_EVENT_MAP, GEMINI_TOOL_MAP, HOOK_EVENT_TYPES, FAILPROOFAI_HOOK_MARKER = "__failproofai_hook__";
+var HOOK_SCOPES, INTEGRATION_TYPES, CODEX_HOOK_SCOPES, CODEX_HOOK_EVENT_TYPES, CODEX_EVENT_MAP, COPILOT_HOOK_SCOPES, COPILOT_HOOK_EVENT_TYPES, COPILOT_TOOL_MAP, CURSOR_HOOK_SCOPES, CURSOR_HOOK_EVENT_TYPES, CURSOR_EVENT_MAP, OPENCODE_HOOK_SCOPES, OPENCODE_HOOK_EVENT_TYPES, PI_HOOK_SCOPES, PI_HOOK_EVENT_TYPES, PI_EVENT_MAP, GEMINI_HOOK_SCOPES, GEMINI_HOOK_EVENT_TYPES, GEMINI_EVENT_MAP, GEMINI_TOOL_MAP, HOOK_EVENT_TYPES, FAILPROOFAI_HOOK_MARKER = "__failproofai_hook__";
 var init_types = __esm(() => {
   HOOK_SCOPES = ["user", "project", "local"];
   INTEGRATION_TYPES = ["claude", "codex", "copilot", "cursor", "opencode", "pi", "gemini"];
@@ -46,6 +46,16 @@ var init_types = __esm(() => {
     "PostToolUse",
     "Stop"
   ];
+  COPILOT_TOOL_MAP = {
+    bash: "Bash",
+    read: "Read",
+    write: "Write",
+    edit: "Edit",
+    str_replace_editor: "Edit",
+    glob: "Glob",
+    grep: "Grep",
+    ls: "LS"
+  };
   CURSOR_HOOK_SCOPES = ["user", "project"];
   CURSOR_HOOK_EVENT_TYPES = [
     "sessionStart",
@@ -2760,7 +2770,7 @@ var init_hook_activity_store = __esm(() => {
 });
 
 // package.json
-var version2 = "0.0.10-beta.0";
+var version2 = "0.0.10-beta.2";
 var init_package = () => {};
 
 // src/posthog-key.ts
@@ -5347,6 +5357,9 @@ function canonicalizeEventType(raw, cli) {
 function canonicalizeToolName(raw, cli) {
   if (!raw)
     return raw;
+  if (cli === "copilot") {
+    return COPILOT_TOOL_MAP[raw] ?? raw;
+  }
   if (cli === "gemini") {
     return GEMINI_TOOL_MAP[raw] ?? raw;
   }
@@ -5881,6 +5894,30 @@ const BUS_EVENT_MAP = {
   // message.updated is handled separately (filter to role:user); see below.
 };
 
+// Map opencode lowercase tool IDs (\`input.tool\`) → Claude PascalCase canonical
+// names. Builtin failproofai policies match on PascalCase via case-sensitive
+// \`Array.includes\`, so without this every Bash/Read/Write/Edit builtin
+// silently no-ops under opencode. Keep in sync with OPENCODE_TOOL_MAP in
+// failproofai/src/hooks/types.ts (this shim is loaded in-process by opencode
+// and must be self-contained — no imports from the failproofai package).
+// Unknown tools pass through unchanged via \`?? raw\`.
+const TOOL_NAME_MAP = {
+  bash: "Bash",
+  read: "Read",
+  write: "Write",
+  edit: "Edit",
+  glob: "Glob",
+  grep: "Grep",
+  list: "LS",
+  webfetch: "WebFetch",
+  todowrite: "TodoWrite",
+  todoread: "TodoRead",
+};
+function canonicalizeTool(raw) {
+  if (!raw) return raw;
+  return TOOL_NAME_MAP[raw] != null ? TOOL_NAME_MAP[raw] : raw;
+}
+
 const FAILPROOFAI_BIN = ${escapedBin};
 const USE_NPX = ${useNpx};
 
@@ -5974,7 +6011,7 @@ export default async function failproofaiPlugin({ client, directory }) {
       const r = runFailproofai("PreToolUse", {
         session_id: input.sessionID,
         cwd: directory,
-        tool_name: input.tool,
+        tool_name: canonicalizeTool(input.tool),
         tool_input: output.args,
         hook_event_name: "PreToolUse",
       }, directory);
@@ -5986,7 +6023,7 @@ export default async function failproofaiPlugin({ client, directory }) {
       const r = runFailproofai("PostToolUse", {
         session_id: input.sessionID,
         cwd: directory,
-        tool_name: input.tool,
+        tool_name: canonicalizeTool(input.tool),
         tool_input: input.args,
         tool_response: { title: output.title, output: output.output, metadata: output.metadata },
         hook_event_name: "PostToolUse",
@@ -5999,7 +6036,7 @@ export default async function failproofaiPlugin({ client, directory }) {
       const r = runFailproofai("PermissionRequest", {
         session_id: input.sessionID,
         cwd: directory,
-        tool_name: input.tool || input.command || "permission",
+        tool_name: canonicalizeTool(input.tool) || input.command || "permission",
         tool_input: input,
         hook_event_name: "PermissionRequest",
       }, directory);
@@ -8194,14 +8231,146 @@ function parseScriptArgs(argv) {
 }
 var init_parse_script_args = () => {};
 
+// scripts/install-diagnosis.mjs
+import { existsSync as existsSync14, readFileSync as readFileSync10, realpathSync } from "node:fs";
+import { dirname as dirname7, resolve as resolve9 } from "node:path";
+import { homedir as homedir21, platform as platform3 } from "node:os";
+import { spawnSync } from "node:child_process";
+function findPackageRoot(start) {
+  try {
+    let dir = realpathSync(start);
+    if (existsSync14(dir) && !existsSync14(resolve9(dir, "package.json"))) {
+      dir = dirname7(dir);
+    }
+    while (true) {
+      const pkgPath = resolve9(dir, "package.json");
+      if (existsSync14(pkgPath)) {
+        try {
+          const pkg = JSON.parse(readFileSync10(pkgPath, "utf8"));
+          if (pkg.name === PKG_NAME)
+            return dir;
+        } catch {}
+      }
+      const parent = dirname7(dir);
+      if (parent === dir)
+        return null;
+      dir = parent;
+    }
+  } catch {
+    return null;
+  }
+}
+function readPackageVersion(packageRoot) {
+  if (!packageRoot)
+    return null;
+  try {
+    const pkg = JSON.parse(readFileSync10(resolve9(packageRoot, "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+function resolvePathFirstBinary() {
+  try {
+    const isWin = platform3() === "win32";
+    const res = isWin ? spawnSync("where", [PKG_NAME], { encoding: "utf8" }) : spawnSync("sh", ["-c", `command -v ${PKG_NAME}`], { encoding: "utf8" });
+    if (res.status !== 0)
+      return null;
+    const first = (res.stdout || "").split(/\r?\n/).find((l) => l.trim().length > 0);
+    return first ? first.trim() : null;
+  } catch {
+    return null;
+  }
+}
+function locateNpmGlobal() {
+  try {
+    const res = spawnSync("npm", ["root", "-g"], { encoding: "utf8" });
+    if (res.status !== 0)
+      return null;
+    const root = (res.stdout || "").trim();
+    if (!root)
+      return null;
+    const candidate = resolve9(root, PKG_NAME);
+    return existsSync14(resolve9(candidate, "package.json")) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+function locateBunGlobal() {
+  try {
+    const candidate = resolve9(homedir21(), ".bun", "install", "global", "node_modules", PKG_NAME);
+    return existsSync14(resolve9(candidate, "package.json")) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+function buildRecommendation(pathFirstBin) {
+  if (!pathFirstBin)
+    return null;
+  const bunBinPrefix = resolve9(homedir21(), ".bun", "bin") + "/";
+  const bunGlobalPrefix = resolve9(homedir21(), ".bun", "install", "global") + "/";
+  const isBun = pathFirstBin.startsWith(bunBinPrefix) || pathFirstBin.startsWith(bunGlobalPrefix);
+  if (isBun) {
+    return `rm -f ~/.bun/bin/${PKG_NAME} && rm -rf ~/.bun/install/global/node_modules/${PKG_NAME}`;
+  }
+  return `npm rm -g ${PKG_NAME}`;
+}
+function diagnoseShadow(self) {
+  const selfPackageRoot = (() => {
+    try {
+      return self?.selfPackageRoot ? realpathSync(self.selfPackageRoot) : null;
+    } catch {
+      return self?.selfPackageRoot ?? null;
+    }
+  })();
+  const selfVersion = self?.selfVersion ?? null;
+  const pathFirstBin = resolvePathFirstBinary();
+  const pathFirstPackageRoot = pathFirstBin ? findPackageRoot(pathFirstBin) : null;
+  const pathFirstVersion = readPackageVersion(pathFirstPackageRoot);
+  const npmGlobalPath = locateNpmGlobal();
+  const npmGlobalVersion = readPackageVersion(npmGlobalPath);
+  const bunGlobalPath = locateBunGlobal();
+  const bunGlobalVersion = readPackageVersion(bunGlobalPath);
+  let shadowed = false;
+  if (selfPackageRoot && pathFirstPackageRoot && pathFirstPackageRoot !== selfPackageRoot) {
+    shadowed = true;
+  } else if (pathFirstPackageRoot) {
+    if (npmGlobalPath && npmGlobalPath !== pathFirstPackageRoot)
+      shadowed = true;
+    else if (bunGlobalPath && bunGlobalPath !== pathFirstPackageRoot)
+      shadowed = true;
+  }
+  const recommendation = shadowed ? buildRecommendation(pathFirstBin) : null;
+  let shadowDescription = null;
+  if (shadowed) {
+    shadowDescription = `PATH resolves to ${pathFirstPackageRoot}` + (pathFirstVersion ? ` (v${pathFirstVersion})` : "") + `, but you just installed ${selfPackageRoot}` + (selfVersion ? ` (v${selfVersion})` : "") + ".";
+  }
+  return {
+    selfPackageRoot,
+    selfVersion,
+    pathFirstBin,
+    pathFirstPath: pathFirstPackageRoot,
+    pathFirstVersion,
+    npmGlobalPath,
+    npmGlobalVersion,
+    bunGlobalPath,
+    bunGlobalVersion,
+    shadowed,
+    shadowDescription,
+    recommendation
+  };
+}
+var PKG_NAME = "failproofai";
+var init_install_diagnosis = () => {};
+
 // scripts/launch.ts
 var exports_launch = {};
 __export(exports_launch, {
   launch: () => launch
 });
 import { spawn as spawn4 } from "child_process";
-import { realpathSync, existsSync as existsSync14 } from "node:fs";
-import { resolve as resolve9, dirname as dirname7 } from "node:path";
+import { realpathSync as realpathSync2, existsSync as existsSync15 } from "node:fs";
+import { resolve as resolve10, dirname as dirname8 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function launch(mode) {
   const { claudeProjectsPath: parsedPath, loggingLevel, disableTelemetry, allowedDevOrigins, remainingArgs } = parseScriptArgs(process.argv.slice(2));
@@ -8233,10 +8402,27 @@ function launch(mode) {
     process.env.PORT = port;
     process.env.HOSTNAME = "0.0.0.0";
     cmd = "node";
-    const packageRoot = process.env.FAILPROOFAI_PACKAGE_ROOT ?? resolve9(dirname7(realpathSync(fileURLToPath2(import.meta.url))), "..");
-    const serverJsPath = resolve9(packageRoot, ".next/standalone/server.js");
-    if (!existsSync14(serverJsPath)) {
-      console.error(`
+    const packageRoot = process.env.FAILPROOFAI_PACKAGE_ROOT ?? resolve10(dirname8(realpathSync2(fileURLToPath2(import.meta.url))), "..");
+    const serverJsPath = resolve10(packageRoot, ".next/standalone/server.js");
+    if (!existsSync15(serverJsPath)) {
+      let shadowMessage = null;
+      try {
+        const diag = diagnoseShadow({ selfPackageRoot: packageRoot, selfVersion: version2 });
+        if (diag.shadowed) {
+          const alt = (diag.npmGlobalPath && diag.npmGlobalPath !== diag.pathFirstPath ? { path: diag.npmGlobalPath, version: diag.npmGlobalVersion } : null) ?? (diag.bunGlobalPath && diag.bunGlobalPath !== diag.pathFirstPath ? { path: diag.bunGlobalPath, version: diag.bunGlobalVersion } : null);
+          const newer = alt?.path ?? "(unknown)";
+          const newerVer = alt?.version ?? "?";
+          shadowMessage = `
+Error: failproofai on your PATH is a stale install that no longer has its build output.
+` + `  Running:    ${diag.pathFirstPath}` + (diag.pathFirstVersion ? `  (v${diag.pathFirstVersion})` : "") + `
+` + `  Newer copy: ${newer}  (v${newerVer})
+
+` + `Remove the shadow with:
+  ${diag.recommendation}
+`;
+        }
+      } catch {}
+      console.error(shadowMessage ?? `
 Error: Cannot find server.js at:
   ${serverJsPath}
 
@@ -8272,6 +8458,7 @@ Error: Cannot find server.js at:
 var init_launch = __esm(() => {
   init_paths();
   init_parse_script_args();
+  init_install_diagnosis();
   init_package();
 });
 
@@ -8293,18 +8480,18 @@ var init_cli_error2 = __esm(() => {
 });
 
 // bin/failproofai.mjs
-import { realpathSync as realpathSync2 } from "fs";
-import { dirname as dirname8, resolve as resolve10 } from "path";
+import { realpathSync as realpathSync3 } from "fs";
+import { dirname as dirname9, resolve as resolve11 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
-var version = "0.0.10-beta.0";
+var version = "0.0.10-beta.2";
 
 // bin/failproofai.mjs
 if (!process.env.FAILPROOFAI_PACKAGE_ROOT) {
-  process.env.FAILPROOFAI_PACKAGE_ROOT = resolve10(dirname8(realpathSync2(fileURLToPath3(import.meta.url))), "..");
+  process.env.FAILPROOFAI_PACKAGE_ROOT = resolve11(dirname9(realpathSync3(fileURLToPath3(import.meta.url))), "..");
 }
 if (!process.env.FAILPROOFAI_DIST_PATH) {
-  process.env.FAILPROOFAI_DIST_PATH = resolve10(dirname8(realpathSync2(fileURLToPath3(import.meta.url))), "..", "dist");
+  process.env.FAILPROOFAI_DIST_PATH = resolve11(dirname9(realpathSync3(fileURLToPath3(import.meta.url))), "..", "dist");
 }
 var args = process.argv.slice(2);
 if (args[0] === "p")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.10-beta.0",
+  "version": "0.0.10-beta.2",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs"
@@ -91,7 +91,7 @@
     "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.1.18",
     "typescript": "^6.0.2",
-    "@anthropic-ai/sdk": "^0.91.1",
+    "@anthropic-ai/sdk": "^0.93.0",
     "vitest": "^4.0.18"
   },
   "dependencies": {

package/pi-extension/index.ts

@@ -102,14 +102,31 @@ interface PiToolCallEvent {
 }
 
 /**
- * Pi emits tool names in lowercase (`bash`, `read`, `edit`, `write`).
- * failproofai's builtin policies match on Claude-shaped capitalized names
- * (`Bash`, `Read`, `Edit`, `Write`). Map between the two so existing
+ * Pi emits tool names in lowercase (`bash`, `read`, `edit`, `write`, `glob`,
+ * `grep`). failproofai's builtin policies match on Claude PascalCase
+ * (`Bash`, `Read`, `Edit`, `Write`, `Glob`, `Grep`) via case-sensitive
+ * `Array.includes` in policy-registry.ts. Map between the two so existing
  * tool-name match clauses fire on Pi sessions.
+ *
+ * Keys must stay in sync with PI_TOOL_MAP in src/hooks/types.ts (this shim is
+ * loaded in-process by Pi and must be self-contained — no imports from the
+ * failproofai package). Update both whenever Pi adds a tool ID we care about.
+ *
+ * Unknown tools (anything not in this map) pass through unchanged so custom
+ * policies that match on raw Pi tool IDs still work.
  */
+const PI_TOOL_MAP: Record<string, string> = {
+  bash: "Bash",
+  read: "Read",
+  write: "Write",
+  edit: "Edit",
+  glob: "Glob",
+  grep: "Grep",
+};
+
 function canonicalizeToolName(piToolName: string | undefined): string | undefined {
   if (!piToolName) return undefined;
-  return piToolName.charAt(0).toUpperCase() + piToolName.slice(1);
+  return PI_TOOL_MAP[piToolName] ?? piToolName;
 }
 
 /** Resolve the cwd for the policy payload. Pi events don't include cwd, so

package/scripts/install-diagnosis.mjs

@@ -0,0 +1,190 @@
+/**
+ * Detects when `failproofai` on the user's PATH is shadowed by a different,
+ * older install — typically a leftover `bun link` from a prior dev session, or
+ * a `bun install -g failproofai` whose prefix sorts ahead of npm's on PATH.
+ *
+ * Used by:
+ *   - scripts/postinstall.mjs — warn at install time so the customer never sees
+ *     the misleading "missing build output" runtime error.
+ *   - scripts/launch.ts        — when .next/standalone/server.js is missing,
+ *     produce a shadow-shaped error if the cause is a shadow rather than a
+ *     genuinely broken build.
+ *
+ * Pure Node.js built-ins, no external dependencies. Every probe is wrapped in
+ * try/catch — diagnoseShadow() is guaranteed not to throw.
+ */
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { homedir, platform } from "node:os";
+import { spawnSync } from "node:child_process";
+
+const PKG_NAME = "failproofai";
+
+/**
+ * Walk up from `start` looking for a package.json whose name === "failproofai".
+ * Returns its directory, or null when no such package.json is reachable.
+ */
+function findPackageRoot(start) {
+  try {
+    let dir = realpathSync(start);
+    // If `start` was a file (e.g. /usr/local/bin/failproofai), step up to its dir.
+    if (existsSync(dir) && !existsSync(resolve(dir, "package.json"))) {
+      dir = dirname(dir);
+    }
+    while (true) {
+      const pkgPath = resolve(dir, "package.json");
+      if (existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+          if (pkg.name === PKG_NAME) return dir;
+        } catch {
+          // unreadable or non-JSON — fall through to parent
+        }
+      }
+      const parent = dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+    }
+  } catch {
+    return null;
+  }
+}
+
+/** Read `version` from a package.json; null on any error. */
+function readPackageVersion(packageRoot) {
+  if (!packageRoot) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Find which `failproofai` PATH would resolve. POSIX: `command -v`; Win32: `where`. */
+function resolvePathFirstBinary() {
+  try {
+    const isWin = platform() === "win32";
+    const res = isWin
+      ? spawnSync("where", [PKG_NAME], { encoding: "utf8" })
+      : spawnSync("sh", ["-c", `command -v ${PKG_NAME}`], { encoding: "utf8" });
+    if (res.status !== 0) return null;
+    const first = (res.stdout || "").split(/\r?\n/).find((l) => l.trim().length > 0);
+    return first ? first.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Locate the npm global install of failproofai, if any. */
+function locateNpmGlobal() {
+  try {
+    const res = spawnSync("npm", ["root", "-g"], { encoding: "utf8" });
+    if (res.status !== 0) return null;
+    const root = (res.stdout || "").trim();
+    if (!root) return null;
+    const candidate = resolve(root, PKG_NAME);
+    return existsSync(resolve(candidate, "package.json")) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Locate the bun global install of failproofai, if any. */
+function locateBunGlobal() {
+  try {
+    const candidate = resolve(homedir(), ".bun", "install", "global", "node_modules", PKG_NAME);
+    return existsSync(resolve(candidate, "package.json")) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build a copy-pasteable cleanup command for the offending install.
+ *
+ * The signal we trust is `pathFirstBin` — the un-resolved binary location PATH
+ * pointed to. For bun-link shadows the realpath'd package root is the dev tree
+ * (not under ~/.bun/), so checking the package root would mis-classify those
+ * shadows as npm and recommend the wrong cleanup.
+ */
+function buildRecommendation(pathFirstBin) {
+  if (!pathFirstBin) return null;
+  const bunBinPrefix = resolve(homedir(), ".bun", "bin") + "/";
+  const bunGlobalPrefix = resolve(homedir(), ".bun", "install", "global") + "/";
+  const isBun = pathFirstBin.startsWith(bunBinPrefix) || pathFirstBin.startsWith(bunGlobalPrefix);
+  if (isBun) {
+    return `rm -f ~/.bun/bin/${PKG_NAME} && rm -rf ~/.bun/install/global/node_modules/${PKG_NAME}`;
+  }
+  return `npm rm -g ${PKG_NAME}`;
+}
+
+/**
+ * Diagnose whether the running binary is being shadowed on PATH by a different
+ * failproofai install.
+ *
+ * @param {{ selfPackageRoot: string, selfVersion: string | null }} self
+ *   The package root and version of the binary calling diagnoseShadow().
+ *   Callers (bin/failproofai.mjs, scripts/postinstall.mjs) already have these
+ *   values; passing them in keeps the helper deterministic and free of
+ *   import.meta.url assumptions.
+ */
+export function diagnoseShadow(self) {
+  const selfPackageRoot = (() => {
+    try { return self?.selfPackageRoot ? realpathSync(self.selfPackageRoot) : null; }
+    catch { return self?.selfPackageRoot ?? null; }
+  })();
+  const selfVersion = self?.selfVersion ?? null;
+
+  const pathFirstBin = resolvePathFirstBinary();
+  const pathFirstPackageRoot = pathFirstBin ? findPackageRoot(pathFirstBin) : null;
+  const pathFirstVersion = readPackageVersion(pathFirstPackageRoot);
+
+  const npmGlobalPath = locateNpmGlobal();
+  const npmGlobalVersion = readPackageVersion(npmGlobalPath);
+
+  const bunGlobalPath = locateBunGlobal();
+  const bunGlobalVersion = readPackageVersion(bunGlobalPath);
+
+  // "Shadow" covers two scenarios:
+  //   1. Postinstall case — `selfPackageRoot` is the just-installed copy and
+  //      PATH resolves elsewhere. Flag when the two roots differ.
+  //   2. Runtime case — the running binary IS the shadow (so selfPackageRoot
+  //      === pathFirstPackageRoot), but a *different* failproofai install
+  //      exists at the npm or bun global. Flag when one of those differs from
+  //      pathFirstPackageRoot.
+  let shadowed = false;
+  if (selfPackageRoot && pathFirstPackageRoot && pathFirstPackageRoot !== selfPackageRoot) {
+    shadowed = true;
+  } else if (pathFirstPackageRoot) {
+    if (npmGlobalPath && npmGlobalPath !== pathFirstPackageRoot) shadowed = true;
+    else if (bunGlobalPath && bunGlobalPath !== pathFirstPackageRoot) shadowed = true;
+  }
+
+  const recommendation = shadowed ? buildRecommendation(pathFirstBin) : null;
+
+  // A short human-readable summary used by callers that want a one-liner.
+  let shadowDescription = null;
+  if (shadowed) {
+    shadowDescription =
+      `PATH resolves to ${pathFirstPackageRoot}` +
+      (pathFirstVersion ? ` (v${pathFirstVersion})` : "") +
+      `, but you just installed ${selfPackageRoot}` +
+      (selfVersion ? ` (v${selfVersion})` : "") + ".";
+  }
+
+  return {
+    selfPackageRoot,
+    selfVersion,
+    pathFirstBin,
+    pathFirstPath: pathFirstPackageRoot,
+    pathFirstVersion,
+    npmGlobalPath,
+    npmGlobalVersion,
+    bunGlobalPath,
+    bunGlobalVersion,
+    shadowed,
+    shadowDescription,
+    recommendation,
+  };
+}

package/scripts/launch.ts

@@ -7,6 +7,7 @@ import { realpathSync, existsSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseScriptArgs } from "./parse-script-args";
+import { diagnoseShadow } from "./install-diagnosis.mjs";
 import { version } from "../package.json";
 
 export function launch(mode: "dev" | "start"): void {
@@ -49,7 +50,38 @@ export function launch(mode: "dev" | "start"): void {
       ?? resolve(dirname(realpathSync(fileURLToPath(import.meta.url))), "..");
     const serverJsPath = resolve(packageRoot, ".next/standalone/server.js");
     if (!existsSync(serverJsPath)) {
+      // Most "missing server.js" reports come from a PATH shadow (an older
+      // `bun link` or a `bun install -g` whose prefix wins over npm), not from
+      // a genuinely broken build. Diagnose first so the error message names
+      // the actual cause when that's what's going on.
+      let shadowMessage: string | null = null;
+      try {
+        const diag = diagnoseShadow({ selfPackageRoot: packageRoot, selfVersion: version });
+        if (diag.shadowed) {
+          // Pick whichever alternate install exists at npm/bun globals AND
+          // differs from PATH-first. In the runtime stale-binary scenario the
+          // running install IS the PATH-first one, so we'd otherwise point the
+          // user back at themselves.
+          const alt =
+            (diag.npmGlobalPath && diag.npmGlobalPath !== diag.pathFirstPath
+              ? { path: diag.npmGlobalPath, version: diag.npmGlobalVersion }
+              : null)
+            ?? (diag.bunGlobalPath && diag.bunGlobalPath !== diag.pathFirstPath
+              ? { path: diag.bunGlobalPath, version: diag.bunGlobalVersion }
+              : null);
+          const newer = alt?.path ?? "(unknown)";
+          const newerVer = alt?.version ?? "?";
+          shadowMessage =
+            `\nError: failproofai on your PATH is a stale install that no longer has its build output.\n` +
+            `  Running:    ${diag.pathFirstPath}` + (diag.pathFirstVersion ? `  (v${diag.pathFirstVersion})` : "") + `\n` +
+            `  Newer copy: ${newer}  (v${newerVer})\n\n` +
+            `Remove the shadow with:\n  ${diag.recommendation}\n`;
+        }
+      } catch {
+        // Diagnosis is best-effort; fall back to the original message.
+      }
       console.error(
+        shadowMessage ??
         `\nError: Cannot find server.js at:\n  ${serverJsPath}\n\n` +
         `The package may be missing its build output.\n` +
         `Try reinstalling:\n  npm install -g failproofai@latest\n`

package/scripts/postinstall.mjs

@@ -12,6 +12,7 @@ import { resolve } from "node:path";
 import { platform, arch, release, homedir, hostname } from "node:os";
 import { createHmac } from "node:crypto";
 import { trackInstallEvent } from "./install-telemetry.mjs";
+import { diagnoseShadow } from "./install-diagnosis.mjs";
 
 // Skip when running in development context (e.g. `bun install` in the source repo).
 // INIT_CWD is set by npm/bun to the directory where install was invoked; it differs
@@ -29,6 +30,30 @@ if (!existsSync(serverJsPath)) {
   process.exit(1);
 }
 
+// Detect when an older `failproofai` is shadowing this fresh install on PATH —
+// classic case is a leftover `bun link` from a prior dev session, or a
+// `bun install -g` whose ~/.bun/bin sorts ahead of npm's prefix. Without this
+// warning the user only finds out later via a confusing runtime error from
+// scripts/launch.ts pointing at the *old* install's missing build output.
+try {
+  let selfVersion = null;
+  try {
+    selfVersion = JSON.parse(readFileSync(resolve(process.cwd(), "package.json"), "utf8")).version ?? null;
+  } catch {}
+  const diag = diagnoseShadow({ selfPackageRoot: process.cwd(), selfVersion });
+  if (diag.shadowed) {
+    console.warn(
+      `\n[failproofai] Warning: another failproofai install is earlier on your PATH.\n` +
+      `  Just installed: ${diag.selfPackageRoot}` + (diag.selfVersion ? `  (v${diag.selfVersion})` : "") + `\n` +
+      `  PATH resolves : ${diag.pathFirstPath}` + (diag.pathFirstVersion ? `  (v${diag.pathFirstVersion})` : "") + `\n\n` +
+      `  Your shell will run the older copy. Remove the shadow with:\n` +
+      `    ${diag.recommendation}\n`
+    );
+  }
+} catch {
+  // Diagnosis is best-effort — never fail the install over a warning.
+}
+
 const FAILPROOFAI_HOOK_MARKER = "__failproofai_hook__";
 const NAMESPACE = "failproofai-telemetry-v1";