failproofai 0.0.14-beta.0 → 0.0.14-beta.1

package/lib/error-origin.ts

@@ -0,0 +1,67 @@
+/**
+ * Works out whether a browser error actually came from the dashboard.
+ *
+ * `window`'s "error" and "unhandledrejection" events are page-global: browser
+ * extensions inject content scripts into the same page and share the same
+ * window, so their failures reach our listeners and get reported as ours. The
+ * observed case was MetaMask's "Failed to connect to MetaMask" arriving as a
+ * failproofai `unhandled_rejection`. Extensions are user-installed and
+ * open-ended, so the noise is unbounded and unrelated to our code.
+ *
+ * We therefore attribute positively — report an error only when it can be
+ * traced to our own origin — rather than maintaining a denylist of extensions
+ * we happen to know about. React render errors don't depend on this: the error
+ * boundaries (`app/global-error.tsx`, `app/components/error-fallback.tsx`)
+ * report `client_error` directly, and React only invokes those for errors thrown
+ * inside our own tree.
+ */
+
+/**
+ * Any `<vendor>-extension://` URL — `chrome-extension://`, `moz-extension://`,
+ * `safari-web-extension://`, `ms-browser-extension://`. Matching the shared
+ * suffix rather than an explicit vendor list means a new browser's scheme is
+ * filtered the day it ships.
+ */
+const EXTENSION_URL = /\b[\w-]+-extension:\/\//i;
+
+export type ErrorOrigin =
+  /** Traceable to our own origin — a real dashboard failure. */
+  | "app"
+  /** Came from a browser extension sharing the page. */
+  | "extension"
+  /** Not attributable: no stack, or a cross-origin "Script error.". */
+  | "unknown";
+
+export interface ErrorOriginInput {
+  /** `error.stack` / `reason.stack`, when the thrown value was an Error. */
+  stack?: string | null;
+  /** `ErrorEvent.filename` — the script URL. Absent on rejections. */
+  filename?: string | null;
+  /** Typically `window.location.origin`. */
+  appOrigin: string;
+}
+
+/**
+ * Classify where an error came from, using whatever location information the
+ * browser gave us.
+ *
+ * Extension frames are checked first: an error whose stack passes through an
+ * extension is that extension's problem even if one of our frames appears
+ * further down.
+ */
+export function classifyErrorOrigin({ stack, filename, appOrigin }: ErrorOriginInput): ErrorOrigin {
+  const text = [filename, stack].filter(Boolean).join("\n");
+  if (!text.trim()) return "unknown";
+  if (EXTENSION_URL.test(text)) return "extension";
+  if (appOrigin && text.includes(appOrigin)) return "app";
+  return "unknown";
+}
+
+/**
+ * Whether an error is ours to report. Only positively-attributed errors qualify:
+ * `unknown` covers cross-origin "Script error." and stack-less rejections, which
+ * are unactionable anyway — there's nothing in them to debug.
+ */
+export function isAppError(input: ErrorOriginInput): boolean {
+  return classifyErrorOrigin(input) === "app";
+}

package/lib/install-check.ts

@@ -0,0 +1,231 @@
+/**
+ * Install reporting, driven from the CLI instead of an npm lifecycle script.
+ *
+ * This used to live in `scripts/postinstall.mjs`. Every package manager now
+ * blocks dependency install scripts by default — npm 12 (`allowScripts`), pnpm,
+ * bun, and Yarn ≥4.14 — and a publisher cannot opt its own package in, so a
+ * postinstall hook is no longer a channel that reaches users. The first non-hook
+ * CLI invocation is.
+ *
+ * Two constraints shape this module:
+ *
+ *   1. It must never run on the `--hook` fast path in bin/failproofai.mjs. That
+ *      path fires on every tool call of every agent session; the check belongs
+ *      in runCli() only.
+ *   2. It must be free on the steady-state path. When the recorded version
+ *      matches, this returns before touching anything else.
+ *
+ * Everything here is best-effort: telemetry must never break, delay, or fail a
+ * real command.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { platform, arch, release, homedir, hostname } from "node:os";
+import { createHmac } from "node:crypto";
+import { trackInstallEvent } from "../scripts/install-telemetry.mjs";
+
+const FAILPROOFAI_HOOK_MARKER = "__failproofai_hook__";
+const NAMESPACE = "failproofai-telemetry-v1";
+
+/**
+ * Cap on the once-per-version report so a hanging network never stalls a command.
+ *
+ * A ceiling, not a cost: delivery resolves as soon as PostHog answers, measured
+ * at ~1.1s from a cold process (these events are the first thing a fresh process
+ * sends, so they always pay the DNS + TLS handshake). Raising this only matters
+ * when the network is slow — precisely when a tight budget would silently drop
+ * the report instead.
+ *
+ * 5s matches hook-telemetry and the postinstall script this replaces. An earlier
+ * 2s left barely any headroom over a 1.85s worst case seen in testing, for a
+ * saving nobody experiences on a healthy network.
+ */
+const REPORT_TIMEOUT_MS = 5000;
+
+function hashToId(raw: string): string {
+  return createHmac("sha256", NAMESPACE).update(raw).digest("hex");
+}
+
+function lastVersionPath(): string {
+  return resolve(homedir(), ".failproofai", "last-version");
+}
+
+/**
+ * Semver ordering. A release outranks the same version carrying a prerelease
+ * tag (semver §11); within a prerelease, numeric identifiers rank below
+ * non-numeric ones.
+ *
+ * Prerelease identifiers are separated by dots only (semver §9). A hyphen is a
+ * legal character *inside* an identifier, so `beta-2` is one non-numeric
+ * identifier compared lexically — not `beta` and `2`.
+ */
+export function compareSemver(a: string, b: string): number {
+  const parse = (v: string) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(v);
+    if (!m) return null;
+    return { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return a < b ? -1 : a > b ? 1 : 0;
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] < pb.nums[i] ? -1 : 1;
+  }
+  if (pa.pre === null && pb.pre === null) return 0;
+  if (pa.pre === null) return 1;
+  if (pb.pre === null) return -1;
+  const ax = pa.pre.split(".");
+  const bx = pb.pre.split(".");
+  for (let i = 0; i < Math.max(ax.length, bx.length); i++) {
+    const ai = ax[i], bi = bx[i];
+    if (ai === undefined) return -1;
+    if (bi === undefined) return 1;
+    const aNum = /^\d+$/.test(ai), bNum = /^\d+$/.test(bi);
+    if (aNum && bNum) {
+      const d = Number(ai) - Number(bi);
+      if (d !== 0) return d < 0 ? -1 : 1;
+    } else if (aNum) {
+      return -1;
+    } else if (bNum) {
+      return 1;
+    } else if (ai !== bi) {
+      return ai < bi ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+export interface HooksState {
+  configured: boolean;
+  registered: boolean;
+  policyCount: number;
+}
+
+/**
+ * Snapshot of the user's hook configuration, carried as properties on
+ * package_installed.
+ *
+ * Only inspects Claude's settings, which understates `registered` for someone
+ * running failproofai against another CLI. Preserved as-is from the postinstall
+ * script so the event keeps its historical meaning.
+ */
+export function checkHooks(): HooksState {
+  const hooksConfigPath = resolve(homedir(), ".failproofai", "policies-config.json");
+  if (!existsSync(hooksConfigPath)) {
+    return { configured: false, registered: false, policyCount: 0 };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(hooksConfigPath, "utf8"));
+  } catch {
+    return { configured: false, registered: false, policyCount: 0 };
+  }
+
+  if (!Array.isArray(config.enabledPolicies) || config.enabledPolicies.length === 0) {
+    return { configured: false, registered: false, policyCount: 0 };
+  }
+
+  const policyCount = config.enabledPolicies.length;
+  const settingsPath = resolve(homedir(), ".claude", "settings.json");
+  if (!existsSync(settingsPath)) return { configured: true, registered: false, policyCount };
+
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+  } catch {
+    return { configured: true, registered: false, policyCount };
+  }
+
+  if (!settings?.hooks) return { configured: true, registered: false, policyCount };
+
+  for (const matchers of Object.values(settings.hooks)) {
+    if (!Array.isArray(matchers)) continue;
+    for (const matcher of matchers) {
+      if (!matcher?.hooks) continue;
+      if (matcher.hooks.some((h: Record<string, unknown>) => h[FAILPROOFAI_HOOK_MARKER] === true)) {
+        return { configured: true, registered: true, policyCount };
+      }
+    }
+  }
+
+  return { configured: true, registered: false, policyCount };
+}
+
+/**
+ * Report an install or upgrade, at most once per version.
+ *
+ * Fires first_install (nothing recorded yet) or version_changed (recorded
+ * version differs), then package_installed, then records `version`. A same-version
+ * run is a no-op — unlike the postinstall script this replaces, the CLI has no
+ * signal that would distinguish a reinstall from an ordinary invocation, so
+ * `direction: "reinstall"` is no longer reported.
+ */
+export async function maybeReportInstall(version: string): Promise<void> {
+  try {
+    const versionFile = lastVersionPath();
+
+    let previousVersion: string | null = null;
+    try {
+      if (existsSync(versionFile)) {
+        previousVersion = readFileSync(versionFile, "utf8").trim() || null;
+      }
+    } catch {
+      // Unreadable marker — treat as first run rather than give up.
+    }
+
+    // Steady state: same version already reported. Costs one stat() per command.
+    if (previousVersion === version) return;
+
+    const hooks = checkHooks();
+
+    const events: Promise<void>[] = [];
+    if (previousVersion === null) {
+      events.push(
+        trackInstallEvent("first_install", {
+          platform: platform(),
+          arch: arch(),
+          os_release: release(),
+          node_version: process.versions.node,
+        }, { version, timeoutMs: REPORT_TIMEOUT_MS }),
+      );
+    } else {
+      const cmp = compareSemver(previousVersion, version);
+      events.push(
+        trackInstallEvent("version_changed", {
+          from_version: previousVersion,
+          to_version: version,
+          direction: cmp < 0 ? "upgrade" : "downgrade",
+          platform: platform(),
+          arch: arch(),
+        }, { version, timeoutMs: REPORT_TIMEOUT_MS }),
+      );
+    }
+
+    events.push(
+      trackInstallEvent("package_installed", {
+        platform: platform(),
+        arch: arch(),
+        os_release: release(),
+        node_version: process.versions.node,
+        hostname_hash: hashToId(hostname()),
+        hooks_configured: hooks.configured,
+        hooks_registered: hooks.registered,
+        enabled_policy_count: hooks.policyCount,
+      }, { version, timeoutMs: REPORT_TIMEOUT_MS }),
+    );
+
+    // Record before awaiting: a dropped event is cheaper than re-reporting the
+    // same version on every command because delivery kept failing.
+    try {
+      mkdirSync(resolve(homedir(), ".failproofai"), { recursive: true });
+      writeFileSync(versionFile, version, "utf8");
+    } catch {
+      // best-effort
+    }
+
+    await Promise.all(events.map((p) => p.catch(() => {})));
+  } catch {
+    // Reporting must never break a command.
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.14-beta.0",
+  "version": "0.0.14-beta.1",
   "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"
@@ -30,8 +30,6 @@
     "test": "vitest",
     "test:run": "vitest run",
     "lint": "eslint . --config eslint.config.mjs",
-    "postinstall": "node scripts/postinstall.mjs",
-    "preuninstall": "node scripts/preuninstall.mjs",
     "prepare": "bun run build",
     "test:e2e": "vitest run --config vitest.config.e2e.mts",
     "test:e2e:watch": "vitest --config vitest.config.e2e.mts",

package/scripts/dev-hook.mjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+/**
+ * failproofai DEV-ONLY hook launcher — for THIS repo's dogfood configs only.
+ *
+ * End users never run this. They install `npx -y failproofai --hook <Event>`
+ * (see `src/hooks/integrations.ts`), which resolves the published package.
+ * This file exists because this repo dogfoods itself from source, and doing so
+ * has two prerequisites that silently rot:
+ *
+ *   1. `bun` on the hook's PATH. `bin/failproofai.mjs` cannot run under node —
+ *      it does a bare `import { version } from "../package.json"` (node needs
+ *      `with { type: "json" }`) and `await import("../src/hooks/handler")`,
+ *      an extensionless TypeScript specifier node cannot resolve. But bun is
+ *      routinely absent from a hook's PATH even when it's on yours: `npm i -g
+ *      bun` installs into ONE nvm version's bin dir, so `nvm use <other>` drops
+ *      it; a macOS GUI launch gets a launchd PATH built without ~/.zshrc.
+ *      When that happens every hook exits 127 and the session runs with ZERO
+ *      policy enforcement — silently.
+ *
+ *   2. `dist/index.js`. The committed policies in `.failproofai/policies/`
+ *      `import from 'failproofai'`, which `findDistIndex()` resolves to that
+ *      bundle. Without it all three fail-open and only builtins enforce.
+ *
+ * So: locate bun (installing it via npm if we must), make sure the bundle
+ * exists, then hand off to the real binary. If we cannot enforce, say so in
+ * one line rather than failing silently.
+ *
+ * INVARIANT — never write to stdout. Most CLIs' deny contracts are JSON on
+ * stdout (Copilot `{decision:"block"}`, Cursor `{followup_message}`, Devin,
+ * Factory-on-Stop, Antigravity). A single stray byte corrupts the parse and
+ * turns a denial into an allow. Diagnostics go to stderr; subprocesses we run
+ * for our own purposes get their stdout discarded, never inherited.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
+import { constants, homedir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, "..");
+const SRC_BIN = resolve(REPO_ROOT, "bin", "failproofai.mjs");
+const BUNDLE = resolve(REPO_ROOT, "dist", "index.js");
+const CACHE_DIR = resolve(REPO_ROOT, "node_modules", ".cache", "failproofai-dev");
+const LOCK_DIR = join(CACHE_DIR, ".lock");
+
+/** A lock older than this belonged to a process that died mid-install. */
+const LOCK_STALE_MS = 5 * 60_000;
+/** 120 × 250ms = 30s, under the tightest hook timeout (Factory/Antigravity). */
+const LOCK_WAIT_TRIES = 120;
+const LOCK_WAIT_MS = 250;
+
+/**
+ * @typedef {object} Deps
+ * @property {Record<string, string | undefined>} [env]
+ * @property {string} [platform]
+ * @property {string} [execPath]
+ * @property {string} [home]
+ * @property {(p: string) => boolean} [exists]
+ * @property {(p: string) => string[]} [readdir]
+ */
+
+function warn(msg) {
+  process.stderr.write(`[failproofai-dev] ${msg}\n`);
+}
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function readdirSafe(p) {
+  try {
+    return readdirSync(p);
+  } catch {
+    return [];
+  }
+}
+
+/** Executable basenames to probe, most specific first. */
+function exeNames(base, platform) {
+  return platform === "win32" ? [`${base}.exe`, `${base}.cmd`, base] : [base];
+}
+
+/** First existing `<dir>/<name>` across dirs × names, or null. */
+function probe(dirs, names, exists) {
+  for (const dir of dirs) {
+    for (const name of names) {
+      const candidate = join(dir, name);
+      if (exists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Absolute path to a bun executable, or null. NEVER spawns a subprocess —
+ * this runs on every hook, so it is an existsSync walk and nothing more.
+ * @param {Deps} deps
+ */
+export function findBun(deps = {}) {
+  const env = deps.env ?? process.env;
+  const platform = deps.platform ?? process.platform;
+  const execPath = deps.execPath ?? process.execPath;
+  const home = deps.home ?? homedir();
+  const exists = deps.exists ?? existsSync;
+  const readdir = deps.readdir ?? readdirSafe;
+
+  const dirs = [];
+  const push = (d) => {
+    if (d && !dirs.includes(d)) dirs.push(d);
+  };
+
+  // 1. PATH — the common case, and the only one that costs nothing.
+  for (const p of (env.PATH ?? "").split(delimiter)) push(p);
+  // 2. An explicit bun install root.
+  if (env.BUN_INSTALL) push(join(env.BUN_INSTALL, "bin"));
+  // 3. Where bun.sh's installer puts it. The macOS GUI-launch case: launchd's
+  //    PATH has /usr/local/bin but never ~/.bun/bin.
+  push(join(home, ".bun", "bin"));
+  // 4. Package-manager prefixes.
+  if (platform !== "win32") {
+    push("/opt/homebrew/bin");
+    push("/usr/local/bin");
+  }
+  // 5. Every nvm-managed node version's bin dir. Load-bearing: `npm i -g bun`
+  //    lands bun in exactly ONE version's bin, so `nvm use <another>` makes it
+  //    vanish from PATH entirely while it's still perfectly usable on disk.
+  //    Descending so the newest version wins deterministically.
+  const nvmRoot = join(home, ".nvm", "versions", "node");
+  for (const v of readdir(nvmRoot).sort().reverse()) push(join(nvmRoot, v, "bin"));
+  // 6. Next to the running node. For our own `node scripts/dev-hook.mjs` form
+  //    this is a strict subset of (1) — node was resolved from PATH — so it is
+  //    a no-op. Kept only for a caller that spawns node by absolute path.
+  push(dirname(execPath));
+
+  // Cache from a previous npm-install (see installBun). Last, so a real bun
+  // that reappears on PATH always wins over our vendored copy.
+  push(join(CACHE_DIR, "node_modules", ".bin"));
+
+  return probe(dirs, exeNames("bun", platform), exists);
+}
+
+/** Absolute path to npm, or null. PATH only — npm ships beside node. */
+export function findNpm(deps = {}) {
+  const env = deps.env ?? process.env;
+  const platform = deps.platform ?? process.platform;
+  const exists = deps.exists ?? existsSync;
+  const dirs = (env.PATH ?? "").split(delimiter).filter(Boolean);
+  return probe(dirs, exeNames("npm", platform), exists);
+}
+
+/**
+ * `{ cmd, args }` to run the real binary, or null when bun is unfindable.
+ * Shared with `.opencode/plugins/failproofai.mjs`, which spawns bun itself.
+ * @param {Deps} deps
+ */
+export function resolveDevSpawn(deps = {}) {
+  const bun = findBun(deps);
+  return bun ? { cmd: bun, args: [SRC_BIN] } : null;
+}
+
+/** One actionable line. Keep it to one — this can fire on 26 events. */
+export function bunMissingMessage() {
+  return (
+    "bun not found and npm unavailable to install it — this repo's dogfood hooks are NOT " +
+    "enforcing. Install bun: curl -fsSL https://bun.sh/install | bash"
+  );
+}
+
+/**
+ * Run `doWork` at most once across concurrently-firing hooks. `mkdirSync` is
+ * atomic, so it doubles as the lock: EEXIST means another process got there.
+ * Losers wait for the artifact rather than duplicating the work.
+ */
+function ensureOnce(isDone, doWork) {
+  if (isDone()) return true;
+  mkdirSync(CACHE_DIR, { recursive: true });
+
+  for (let i = 0; i < LOCK_WAIT_TRIES; i++) {
+    if (isDone()) return true;
+    try {
+      mkdirSync(LOCK_DIR);
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err;
+      try {
+        if (Date.now() - statSync(LOCK_DIR).mtimeMs > LOCK_STALE_MS) {
+          rmSync(LOCK_DIR, { recursive: true, force: true });
+        } else {
+          sleepSync(LOCK_WAIT_MS);
+        }
+      } catch {
+        /* lock vanished under us — retry immediately */
+      }
+      continue;
+    }
+    try {
+      doWork();
+    } finally {
+      try {
+        rmSync(LOCK_DIR, { recursive: true, force: true });
+      } catch {
+        /* best effort; a leaked lock goes stale in LOCK_STALE_MS */
+      }
+    }
+    return isDone();
+  }
+  return isDone();
+}
+
+/**
+ * Vendor bun into node_modules/.cache via npm. bun ships as an npm package, so
+ * npm is the one bootstrap that works when bun is genuinely absent — building
+ * `dist/cli.mjs` to run under node can't, because `build:cli` is itself
+ * `bun build`.
+ */
+function installBun(deps = {}) {
+  const npm = findNpm(deps);
+  if (!npm) return null;
+  ensureOnce(
+    () => findBun(deps) !== null,
+    () => {
+      warn("bun not found — installing it into node_modules/.cache (one time, ~15s)");
+      const r = spawnSync(
+        npm,
+        ["install", "bun", "--prefix", CACHE_DIR, "--no-save", "--no-audit", "--no-fund", "--loglevel=error"],
+        // NOT "inherit" on stdout: npm prints there, and our stdout is a deny
+        // channel. stderr passes through so a failed install is visible.
+        { stdio: ["ignore", "ignore", "inherit"], cwd: REPO_ROOT },
+      );
+      if (r.status !== 0) warn("npm install bun failed — see the error above");
+    },
+  );
+  return findBun(deps);
+}
+
+/**
+ * Build dist/index.js if absent, so `.failproofai/policies/*.mjs` can resolve
+ * `import ... from 'failproofai'`. Non-fatal: builtins enforce without it.
+ */
+export function ensureBundle(bunPath) {
+  return ensureOnce(
+    () => existsSync(BUNDLE),
+    () => {
+      warn("dist/index.js missing — building it so .failproofai/policies/ can load (one time)");
+      const r = spawnSync(
+        bunPath,
+        ["build", "--target=node", "--format=cjs", "--outfile=dist/index.js", "src/index.ts"],
+        { stdio: ["ignore", "ignore", "inherit"], cwd: REPO_ROOT },
+      );
+      if (r.status !== 0) warn("build failed — policies in .failproofai/policies/ will NOT load");
+    },
+  );
+}
+
+function main() {
+  const bun = findBun() ?? installBun();
+  if (!bun) {
+    warn(bunMissingMessage());
+    process.exit(1);
+  }
+  ensureBundle(bun);
+
+  // stdio:"inherit" hands the child our actual fds: the payload on stdin and
+  // any decision JSON on stdout flow byte-exact, unbuffered, unparsed by us.
+  // No cwd override — the child must see whatever cwd the agent CLI chose,
+  // exactly as it did when the config spawned bun directly.
+  const r = spawnSync(bun, [SRC_BIN, ...process.argv.slice(2)], { stdio: "inherit" });
+
+  // Exit codes are a contract, not a status: 2 means DENY on Claude/Factory/
+  // Goose. Propagate verbatim. Never synthesize 2 (would deny) or 0 (would
+  // silently allow).
+  if (r.error) {
+    warn(`could not run bun (${r.error.code ?? r.error.message}) — hooks are NOT enforcing`);
+    process.exit(1);
+  }
+  if (r.status === null && r.signal) {
+    // Mirror what `sh` reports for a signalled child, which is what the agent
+    // CLI saw before this launcher sat in between.
+    process.exit(128 + (constants.signals[r.signal] ?? 15));
+  }
+  process.exit(r.status ?? 1);
+}
+
+// Only run when executed, not when `.opencode/plugins/failproofai.mjs` imports
+// the resolver. realpath so a symlinked or relative argv[1] still matches.
+let invokedDirectly = false;
+try {
+  invokedDirectly = realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+} catch {
+  invokedDirectly = false;
+}
+if (invokedDirectly) main();

package/scripts/install-diagnosis.mjs

@@ -4,11 +4,9 @@
  * 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.
+ *   - 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.
@@ -125,9 +123,8 @@ function buildRecommendation(pathFirstBin) {
  *
  * @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.
+ *   Callers (scripts/launch.ts) already have these values; passing them in keeps
+ *   the helper deterministic and free of import.meta.url assumptions.
  */
 export function diagnoseShadow(self) {
   const selfPackageRoot = (() => {

package/scripts/install-telemetry.mjs

@@ -80,12 +80,20 @@ function getInstanceId() {
 
 /**
  * Track a named event to PostHog. No-op when telemetry is disabled.
- * Uses process.env.npm_package_version (set automatically by npm in lifecycle scripts).
+ *
+ * `opts.version` must be supplied by callers outside an npm lifecycle script:
+ * npm only sets npm_package_version while running one, and these events now
+ * fire from the CLI (see lib/install-check.ts) because package managers block
+ * install scripts by default.
+ *
+ * @param {string} event
+ * @param {Record<string, unknown>} [properties]
+ * @param {{ version?: string, timeoutMs?: number }} [opts]
  */
-export async function trackInstallEvent(event, properties = {}) {
+export async function trackInstallEvent(event, properties = {}, opts = {}) {
   if (process.env.FAILPROOFAI_TELEMETRY_DISABLED === "1") return;
 
-  const version = process.env.npm_package_version ?? "unknown";
+  const version = opts.version ?? process.env.npm_package_version ?? "unknown";
   const body = JSON.stringify({
     api_key: process.env.FAILPROOFAI_POSTHOG_KEY ?? API_KEY,
     event,
@@ -106,7 +114,7 @@ export async function trackInstallEvent(event, properties = {}) {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body,
-      signal: AbortSignal.timeout(5000),
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
     }
   );
 }