failproofai 0.0.9 → 0.0.10-beta.1

package/pi-extension/index.ts

@@ -0,0 +1,373 @@
+/**
+ * failproofai policy bridge for Pi (pi-coding-agent).
+ *
+ * This extension is loaded by Pi at startup and registered via
+ * `pi install <abs-path-to-this-dir> [-l]` (or by hand-authoring an entry in
+ * `<scope>/.pi/settings.json`). It subscribes to Pi's `tool_call`, `user_bash`,
+ * `input`, and `session_start` events and forwards them to the failproofai
+ * binary as `failproofai --hook <Event> --cli pi`. failproofai prints a
+ * decision JSON to stdout; this shim parses it and translates into Pi's
+ * `{ block: true, reason }` return shape so policy `deny` decisions cancel
+ * tool execution.
+ *
+ * Marker comment for failproofai's installer detection (do not remove):
+ *   __failproofai_hook__: true
+ *
+ * Binary resolution. failproofai ships two entrypoints:
+ *   • dist/cli.mjs — bundled, node-compatible (production npm install)
+ *   • bin/failproofai.mjs — source, requires `bun` (dev / monorepo)
+ *
+ * dist/cli.mjs is preferred because spawning `node bin/failproofai.mjs`
+ * fails with ERR_IMPORT_ATTRIBUTE_MISSING (the source `import package.json`
+ * needs `with { type: "json" }` under node, which bun handles transparently
+ * but the build:cli step transpiles away in dist/cli.mjs). When dist/cli.mjs
+ * isn't present, fall back to running bin/failproofai.mjs with `bun`. Pi
+ * spawns extensions with an undefined cwd contract, so paths are resolved
+ * relative to this file via `import.meta.url`, NOT process.cwd().
+ */
+import { spawnSync } from "node:child_process";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DIST_BIN = resolve(HERE, "..", "dist", "cli.mjs");
+const SRC_BIN = resolve(HERE, "..", "bin", "failproofai.mjs");
+// Prefer the bundled dist/cli.mjs (node-compatible); fall back to source +
+// bun for dev workflows where dist/ hasn't been built yet.
+function resolveSpawn(): { cmd: string; args: string[] } {
+  if (process.env.FAILPROOFAI_BINARY_OVERRIDE) {
+    return { cmd: "node", args: [process.env.FAILPROOFAI_BINARY_OVERRIDE] };
+  }
+  if (existsSync(DIST_BIN)) {
+    return { cmd: "node", args: [DIST_BIN] };
+  }
+  return { cmd: "bun", args: [SRC_BIN] };
+}
+
+interface PolicyDecision {
+  permission?: "allow" | "deny";
+  reason?: string;
+}
+
+/**
+ * Spawn `failproofai --hook <eventName> --cli pi`, write the JSON payload to
+ * stdin, and parse the flat `{permission, reason}` JSON we expect failproofai
+ * to print on stdout. Fail-open on any subprocess / parse error.
+ */
+/** Optional stderr trace for debugging the shim. Enabled with
+ *  FAILPROOFAI_PI_DEBUG=1; silent otherwise. */
+function debug(msg: string): void {
+  if (process.env.FAILPROOFAI_PI_DEBUG === "1") {
+    process.stderr.write(`[failproofai-pi-shim] ${msg}\n`);
+  }
+}
+
+function callPolicy(eventName: string, payload: unknown): { block: boolean; reason: string } {
+  const { cmd, args } = resolveSpawn();
+  debug(`callPolicy event=${eventName} cmd=${cmd}`);
+  try {
+    const result = spawnSync(
+      cmd,
+      [...args, "--hook", eventName, "--cli", "pi"],
+      {
+        input: JSON.stringify(payload),
+        encoding: "utf8",
+        timeout: 60_000,
+      },
+    );
+    if (result.status !== 0) return { block: false, reason: "" };
+    const stdout = (result.stdout || "").trim();
+    if (!stdout) return { block: false, reason: "" };
+    const parsed = JSON.parse(stdout) as PolicyDecision;
+    if (parsed.permission === "deny") {
+      debug(`DENY reason=${parsed.reason}`);
+      return { block: true, reason: parsed.reason ?? "Blocked by failproofai" };
+    }
+  } catch (err) {
+    debug(`EXCEPTION ${err instanceof Error ? err.message : String(err)}`);
+    // Fail-open: never block tool execution because of an infra failure.
+  }
+  return { block: false, reason: "" };
+}
+
+interface PiToolCallEvent {
+  type?: string;
+  toolName?: string;
+  toolCallId?: string;
+  input?: Record<string, unknown>;
+  cwd?: string;
+  sessionId?: string;
+}
+
+/**
+ * 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
+ * tool-name match clauses fire on Pi sessions.
+ */
+function canonicalizeToolName(piToolName: string | undefined): string | undefined {
+  if (!piToolName) return undefined;
+  return piToolName.charAt(0).toUpperCase() + piToolName.slice(1);
+}
+
+/** Resolve the cwd for the policy payload. Pi events don't include cwd, so
+ *  fall back to the extension's process.cwd() — which is where Pi was
+ *  launched and where `.failproofai/` config lives. */
+function resolveCwd(eventCwd: string | undefined): string {
+  return eventCwd ?? process.cwd();
+}
+
+/**
+ * Pi (verified empirically against pi-coding-agent v0.71.1) does NOT
+ * populate `event.sessionId` on any of its events — `session_start`,
+ * `tool_call`, `user_bash`, `input`, `tool_result`, `agent_end`,
+ * `session_shutdown` all leave it undefined. Without help the shim can't
+ * tag activity records with a session id, so the dashboard renders
+ * `Session ID: —` for every Pi row.
+ *
+ * What Pi DOES do: at session start it creates a JSONL transcript at
+ * `~/.pi/agent/sessions/<encodedCwd>/<isoTimestamp>_<uuid>.jsonl` where
+ * the filename encodes the sessionId. We discover ours by scanning the
+ * encoded-cwd directory for the most-recently-modified matching file.
+ *
+ * Strategy: scan once and cache. Pi runs one session per process so the
+ * cache is per-process and lives for the session's lifetime. If Pi ever
+ * multiplexes, we'd need a keyed map.
+ */
+const PI_FILE_RE = /^[\d-]+T[\d-]+Z_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+
+/** Encode a cwd into Pi's on-disk session-dir name. Pi strips the leading
+ *  `/` before replacing remaining slashes with `-`, e.g.
+ *  `/home/u/repo` → `--home-u-repo--`. */
+function piEncodeCwd(cwd: string): string {
+  const inner = cwd.replace(/^\/+/, "").replace(/\//g, "-");
+  return `--${inner}--`;
+}
+
+/** Process start boundary — files older than this aren't from the current
+ *  Pi session. Captured at module load so cold-start in a cwd with stale
+ *  transcripts doesn't pin a previous session's UUID. We allow a small
+ *  tolerance below `processStartMs` because mtime resolution and clock
+ *  skew can put a "current" file's mtime a few hundred ms before module
+ *  load on slow startup. */
+const PROCESS_START_MS = Date.now();
+const STALE_TOLERANCE_MS = 2_000;
+
+/** Find the newest `<ts>_<uuid>.jsonl` file under `~/.pi/agent/sessions/<encodedCwd>/`
+ *  whose mtime indicates it belongs to the CURRENT Pi process (≥ process
+ *  start, with a small tolerance). Files older than that are stale
+ *  transcripts from prior sessions in the same cwd — caching their UUID
+ *  would cross-attribute every event of the new session.
+ *  Returns undefined when the dir doesn't exist, has no matching file, or
+ *  every matching file is stale. */
+function discoverPiSessionId(cwd: string): string | undefined {
+  const root = process.env.PI_SESSIONS_DIR || join(homedir(), ".pi", "agent", "sessions");
+  const dir = join(root, piEncodeCwd(cwd));
+  let entries: string[];
+  try { entries = readdirSync(dir); } catch { return undefined; }
+  const boundary = PROCESS_START_MS - STALE_TOLERANCE_MS;
+  let best: { sessionId: string; mtime: number } | undefined;
+  for (const name of entries) {
+    const m = PI_FILE_RE.exec(name);
+    if (!m) continue;
+    let mtime: number;
+    try { mtime = statSync(join(dir, name)).mtimeMs; } catch { continue; }
+    if (mtime < boundary) continue;
+    if (!best || mtime > best.mtime) best = { sessionId: m[1], mtime };
+  }
+  return best?.sessionId;
+}
+
+/** sessionId cache, keyed by cwd. Per-cwd so a multi-cwd Pi (extension running
+ *  across multiple workspace roots) can't cross-attribute. Cleared on
+ *  session_shutdown reasons `new`/`resume`/`fork` (Pi reuses the process). */
+const cachedSessionIdByCwd = new Map<string, string>();
+function resolveSessionId(eventSessionId: string | undefined, cwd: string): string | undefined {
+  if (eventSessionId) {
+    cachedSessionIdByCwd.set(cwd, eventSessionId);
+    return eventSessionId;
+  }
+  const cached = cachedSessionIdByCwd.get(cwd);
+  if (cached) return cached;
+  // Pi v0.71.1 never sets sessionId — discover from disk.
+  const discovered = discoverPiSessionId(cwd);
+  if (discovered) cachedSessionIdByCwd.set(cwd, discovered);
+  return discovered;
+}
+/** Clear the cached sessionId for a cwd. Called on session_shutdown reasons
+ *  that indicate a new session is starting in the same process (`new`,
+ *  `resume`, `fork`). Without this, the next session would inherit the prior
+ *  sessionId until disk discovery refreshed it. */
+function resetSessionIdCache(cwd: string): void {
+  cachedSessionIdByCwd.delete(cwd);
+}
+
+interface PiUserBashEvent {
+  type?: string;
+  command?: string;
+  cwd?: string;
+  sessionId?: string;
+}
+
+interface PiInputEvent {
+  type?: string;
+  text?: string;
+  source?: string;
+  cwd?: string;
+  sessionId?: string;
+}
+
+interface PiSessionStartEvent {
+  type?: string;
+  reason?: string;
+  cwd?: string;
+  sessionId?: string;
+}
+
+interface PiSessionShutdownEvent {
+  type?: string;
+  /** "quit" | "reload" | "new" | "resume" | "fork" per pi-coding-agent v0.72.1 */
+  reason?: string;
+  targetSessionFile?: string;
+  cwd?: string;
+  sessionId?: string;
+}
+
+interface PiToolResultEvent {
+  type?: string;
+  toolCallId?: string;
+  toolName?: string;
+  input?: Record<string, unknown>;
+  /** TextContent | ImageContent — opaque to us; forwarded as-is. */
+  content?: unknown[];
+  isError?: boolean;
+  cwd?: string;
+  sessionId?: string;
+}
+
+interface PiAgentEndEvent {
+  type?: string;
+  /** AgentMessage[] — opaque; not forwarded (Stop policies don't need it). */
+  messages?: unknown[];
+  cwd?: string;
+  sessionId?: string;
+}
+
+interface PiExtensionApi {
+  on(event: string, handler: (event: unknown) => unknown): void;
+}
+
+export default function failproofaiBridge(pi: PiExtensionApi) {
+  // tool_call → PreToolUse. Block tool execution when failproofai denies.
+  pi.on("tool_call", (event: unknown): unknown => {
+    const e = event as PiToolCallEvent;
+    const decision = callPolicy("tool_call", {
+      tool_name: canonicalizeToolName(e.toolName),
+      tool_input: e.input,
+      session_id: resolveSessionId(e.sessionId, resolveCwd(e.cwd)),
+      cwd: resolveCwd(e.cwd),
+      hook_event_name: "PreToolUse",
+    });
+    if (decision.block) return { block: true, reason: decision.reason };
+    return undefined;
+  });
+
+  // user_bash → PreToolUse with synthesized toolName=Bash.
+  pi.on("user_bash", (event: unknown): unknown => {
+    const e = event as PiUserBashEvent;
+    const decision = callPolicy("user_bash", {
+      tool_name: "Bash",
+      tool_input: { command: e.command },
+      session_id: resolveSessionId(e.sessionId, resolveCwd(e.cwd)),
+      cwd: resolveCwd(e.cwd),
+      hook_event_name: "PreToolUse",
+    });
+    if (decision.block) return { block: true, reason: decision.reason };
+    return undefined;
+  });
+
+  // input → UserPromptSubmit. Honor block decisions if Pi accepts them
+  // (Pi's docs describe block on input but it's not exhaustively tested).
+  pi.on("input", (event: unknown): unknown => {
+    const e = event as PiInputEvent;
+    const decision = callPolicy("input", {
+      prompt: e.text,
+      session_id: resolveSessionId(e.sessionId, resolveCwd(e.cwd)),
+      cwd: resolveCwd(e.cwd),
+      hook_event_name: "UserPromptSubmit",
+    });
+    if (decision.block) return { block: true, reason: decision.reason };
+    return undefined;
+  });
+
+  // session_start → SessionStart. Observe-only; we still forward so the
+  // activity feed records the session and any UserPromptSubmit policies that
+  // need session_id continuity see the metadata.
+  pi.on("session_start", (event: unknown): unknown => {
+    const e = event as PiSessionStartEvent;
+    callPolicy("session_start", {
+      session_id: resolveSessionId(e.sessionId, resolveCwd(e.cwd)),
+      cwd: resolveCwd(e.cwd),
+      reason: e.reason,
+      hook_event_name: "SessionStart",
+    });
+    return undefined;
+  });
+
+  // tool_result → PostToolUse. Observation-only on Pi: ToolResultEventResult
+  // exposes {content, details, isError} for mutation but no `block`. We
+  // forward to the failproofai binary so PostToolUse builtins (sanitize-jwt,
+  // sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-
+  // content, sanitize-bearer-tokens) run and get their decisions logged to
+  // the activity store + stderr — but Pi keeps the original tool result.
+  pi.on("tool_result", (event: unknown): unknown => {
+    const e = event as PiToolResultEvent;
+    callPolicy("tool_result", {
+      tool_name: canonicalizeToolName(e.toolName),
+      tool_input: e.input ?? {},
+      tool_response: { content: e.content, isError: e.isError },
+      session_id: resolveSessionId(e.sessionId, resolveCwd(e.cwd)),
+      cwd: resolveCwd(e.cwd),
+      hook_event_name: "PostToolUse",
+    });
+    return undefined;
+  });
+
+  // agent_end → Stop. Observation-only on Pi: the agent loop has already
+  // exited when this fires, so a deny decision cannot keep Pi running the
+  // way Claude's exit-2-from-Stop can. We still forward so the 5
+  // require-*-before-stop builtins run and log their findings (visible in
+  // the dashboard's activity feed and stderr) — best-effort visibility.
+  pi.on("agent_end", (event: unknown): unknown => {
+    const e = event as PiAgentEndEvent;
+    callPolicy("agent_end", {
+      session_id: resolveSessionId(e.sessionId, resolveCwd(e.cwd)),
+      cwd: resolveCwd(e.cwd),
+      hook_event_name: "Stop",
+    });
+    return undefined;
+  });
+
+  // session_shutdown → SessionEnd. Observation-only; emits a SessionEnd
+  // record so per-session telemetry has a clean close. Reset the per-cwd
+  // sessionId cache for shutdown reasons that mean "Pi is starting a new
+  // session in the same process" — without the reset, the next session's
+  // events would inherit the prior session's id until disk discovery
+  // refreshed it.
+  pi.on("session_shutdown", (event: unknown): unknown => {
+    const e = event as PiSessionShutdownEvent;
+    const cwd = resolveCwd(e.cwd);
+    callPolicy("session_shutdown", {
+      session_id: resolveSessionId(e.sessionId, cwd),
+      cwd,
+      reason: e.reason,
+      hook_event_name: "SessionEnd",
+    });
+    if (e.reason === "new" || e.reason === "resume" || e.reason === "fork") {
+      resetSessionIdCache(cwd);
+    }
+    return undefined;
+  });
+}

package/pi-extension/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@failproofai/pi-extension",
+  "version": "0.0.1",
+  "description": "failproofai policy bridge for Pi (pi-coding-agent)",
+  "type": "module",
+  "main": "./index.ts",
+  "private": true,
+  "keywords": [
+    "pi-extension",
+    "failproofai"
+  ]
+}

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";