failproofai 0.0.13 → 0.0.14-beta.1

package/openclaw-plugin/index.js

@@ -0,0 +1,223 @@
+/**
+ * failproofai policy bridge for OpenClaw (openclaw gateway).
+ *
+ * Loaded in-process by the gateway (registered via `plugins.load.paths` +
+ * `plugins.entries.failproofai` in ~/.openclaw/openclaw.json). It subscribes to
+ * OpenClaw's typed PLUGIN hooks — the only surface that can block; OpenClaw's
+ * file-based "internal hooks" are observation-only — and forwards each to the
+ * failproofai binary as `failproofai --hook <event> --cli openclaw`. failproofai
+ * prints a flat `{permission, reason}` verdict on stdout; this shim maps it to
+ * each hook's native return shape.
+ *
+ * Marker comment for failproofai's installer detection (do not remove):
+ *   __failproofai_hook__: true
+ *
+ * Design notes (verified live against openclaw v2026.7.1):
+ *  • ASYNC spawn, never spawnSync — the gateway is a long-running multi-channel
+ *    process; a synchronous spawn on every hook would stall every channel.
+ *    30s guard timer; fail-open on any error (never block on infra failure).
+ *  • Raw forwarding — we send the raw tool name / params and a Claude-shaped
+ *    stdin (params→tool_input, toolName→tool_name, transcriptPath→
+ *    transcript_path, stopHookActive→stop_hook_active, sessionKey→session_id).
+ *    The binary canonicalizes via OPENCLAW_* maps (single source of truth); the
+ *    shim ships NO inline maps (unlike the OpenCode/Pi shims).
+ *  • No top-level `await` — OpenClaw's plugin loader rejects it; all async work
+ *    happens inside register()'s handlers.
+ *
+ * Binary resolution mirrors pi-extension/index.ts: prefer the bundled
+ * dist/cli.mjs (node-compatible), fall back to bin/failproofai.mjs with bun for
+ * dev; honor FAILPROOFAI_BINARY_OVERRIDE. Paths resolve relative to this file
+ * via import.meta.url (the gateway spawns plugins with an undefined cwd).
+ */
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DIST_BIN = resolve(HERE, "..", "dist", "cli.mjs");
+const SRC_BIN = resolve(HERE, "..", "bin", "failproofai.mjs");
+
+function resolveSpawn() {
+  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] };
+}
+
+function debug(msg) {
+  if (process.env.FAILPROOFAI_OPENCLAW_DEBUG === "1") {
+    process.stderr.write(`[failproofai-openclaw-shim] ${msg}\n`);
+  }
+}
+
+/**
+ * Spawn `failproofai --hook <rawEvent> --cli openclaw`, write the JSON payload
+ * to stdin, and resolve the parsed flat `{permission, reason}` verdict. Async +
+ * fail-open: any spawn/parse error or timeout resolves to `{permission:"allow"}`
+ * so a failproofai fault never blocks the gateway.
+ */
+function callPolicy(rawEvent, payload) {
+  return new Promise((done) => {
+    const { cmd, args } = resolveSpawn();
+    let child;
+    try {
+      child = spawn(cmd, [...args, "--hook", rawEvent, "--cli", "openclaw"], {
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch (err) {
+      debug(`spawn threw: ${err && err.message ? err.message : String(err)}`);
+      done({ permission: "allow" });
+      return;
+    }
+    let out = "";
+    let settled = false;
+    const finish = (verdict) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      done(verdict);
+    };
+    const timer = setTimeout(() => {
+      debug(`timeout on ${rawEvent}; killing child`);
+      try { child.kill(); } catch { /* ignore */ }
+      finish({ permission: "allow" });
+    }, 30_000);
+    child.stdout.on("data", (d) => { out += d; });
+    child.on("error", (err) => {
+      debug(`child error: ${err && err.message ? err.message : String(err)}`);
+      finish({ permission: "allow" });
+    });
+    child.on("close", () => {
+      const stdout = out.trim();
+      if (!stdout) { finish({ permission: "allow" }); return; }
+      try {
+        finish(JSON.parse(stdout));
+      } catch (err) {
+        debug(`parse error: ${err && err.message ? err.message : String(err)}`);
+        finish({ permission: "allow" });
+      }
+    });
+    try {
+      child.stdin.end(JSON.stringify(payload));
+    } catch (err) {
+      debug(`stdin write failed: ${err && err.message ? err.message : String(err)}`);
+      finish({ permission: "allow" });
+    }
+  });
+}
+
+/** Claude-shaped stdin base. Extra keys are ignored by the binary's payload
+ *  parser; they're forwarded for future use / activity attribution. */
+function baseMeta(payload, ctx) {
+  const p = payload || {};
+  const c = ctx || {};
+  return {
+    session_id: c.sessionId ?? p.sessionId ?? c.sessionKey ?? p.sessionKey,
+    cwd: p.cwd ?? c.workspaceDir ?? process.cwd(),
+    transcript_path: p.transcriptPath,
+    stop_hook_active: p.stopHookActive === true,
+    openclaw: {
+      agentId: c.agentId,
+      sessionKey: c.sessionKey ?? p.sessionKey,
+      runId: c.runId ?? p.runId,
+      provider: p.provider,
+      model: p.model,
+    },
+  };
+}
+
+export default definePluginEntry({
+  id: "failproofai",
+  name: "failproofai",
+  description: "Real-time policy enforcement for OpenClaw by failproofai",
+  register(api) {
+    // before_tool_call → PreToolUse. Full deny: return {block:true, blockReason}.
+    api.on(
+      "before_tool_call",
+      async (payload, ctx) => {
+        const p = payload || {};
+        const verdict = await callPolicy("before_tool_call", {
+          ...baseMeta(payload, ctx),
+          tool_name: p.toolName,
+          tool_input: p.params,
+          hook_event_name: "before_tool_call",
+        });
+        if (verdict.permission === "deny") {
+          return { block: true, blockReason: verdict.reason || "Blocked by failproofai" };
+        }
+        return undefined;
+      },
+      { priority: 100, timeoutMs: 60_000 },
+    );
+
+    // before_agent_run → UserPromptSubmit. Deny: return {outcome:"block", reason}.
+    api.on(
+      "before_agent_run",
+      async (payload, ctx) => {
+        const p = payload || {};
+        const verdict = await callPolicy("before_agent_run", {
+          ...baseMeta(payload, ctx),
+          prompt: p.prompt,
+          hook_event_name: "before_agent_run",
+        });
+        if (verdict.permission === "deny") {
+          return { outcome: "block", reason: verdict.reason || "Blocked by failproofai" };
+        }
+        return undefined;
+      },
+      { priority: 100, timeoutMs: 60_000 },
+    );
+
+    // before_agent_finalize → Stop. The real turn-end gate: a deny becomes a
+    // revise so the agent runs another pass. The evaluator supplies the
+    // MANDATORY ACTION wording; the payload's stop_hook_active guards the
+    // require-*-before-stop builtins against infinite loops.
+    api.on(
+      "before_agent_finalize",
+      async (payload, ctx) => {
+        const verdict = await callPolicy("before_agent_finalize", {
+          ...baseMeta(payload, ctx),
+          hook_event_name: "before_agent_finalize",
+        });
+        if (verdict.permission === "deny") {
+          return { action: "revise", reason: verdict.reason || "Action required by failproofai" };
+        }
+        return undefined;
+      },
+      { priority: 100, timeoutMs: 60_000 },
+    );
+
+    // Observation hooks — await so activity ordering is stable, ignore verdict.
+    // after_tool_call → PostToolUse; session_start/end → SessionStart/End;
+    // subagent_ended → SubagentStop (obs only); before_compaction → PreCompact.
+    for (const ev of [
+      "after_tool_call",
+      "session_start",
+      "session_end",
+      "subagent_ended",
+      "before_compaction",
+    ]) {
+      api.on(
+        ev,
+        async (payload, ctx) => {
+          const p = payload || {};
+          await callPolicy(ev, {
+            ...baseMeta(payload, ctx),
+            tool_name: p.toolName,
+            tool_input: p.params,
+            tool_response: p.result,
+            reason: p.reason,
+            hook_event_name: ev,
+          });
+          return undefined;
+        },
+        { priority: 100, timeoutMs: 60_000 },
+      );
+    }
+  },
+});

package/openclaw-plugin/openclaw.plugin.json

@@ -0,0 +1,6 @@
+{
+  "id": "failproofai",
+  "name": "failproofai",
+  "description": "Real-time policy enforcement for OpenClaw by failproofai",
+  "configSchema": {}
+}

package/openclaw-plugin/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@failproofai/openclaw-plugin",
+  "version": "0.0.1",
+  "description": "failproofai policy bridge for OpenClaw (openclaw gateway)",
+  "type": "module",
+  "main": "./index.js",
+  "private": true,
+  "keywords": [
+    "openclaw-plugin",
+    "failproofai"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "0.0.13",
+  "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"
@@ -11,6 +11,7 @@
     "scripts/",
     "lib/",
     "pi-extension/",
+    "openclaw-plugin/",
     ".next/standalone/",
     "dist/",
     "README.md"
@@ -29,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),
     }
   );
 }

package/scripts/launch.ts

@@ -9,19 +9,15 @@ import { createInterface } from "node:readline";
 import { parseScriptArgs } from "./parse-script-args";
 import { diagnoseShadow } from "./install-diagnosis.mjs";
 import { makeSkewLogFilter } from "./skew-log-filter";
+import { renderLaunchBanner } from "../src/hooks/tui";
 import { version } from "../package.json";
 
 export function launch(mode: "dev" | "start"): void {
   const { loggingLevel, disableTelemetry, allowedDevOrigins, remainingArgs } = parseScriptArgs(process.argv.slice(2));
 
-  // Plain-text title + a labeled `Version` line that lines up with the
-  // `Star us` / `Docs` / `Discord` lines below (all four labels pad to the
-  // same column so the values form a clean right-hand column).
-  console.log(`\n  failproof ai\n`);
-  console.log(`  📦 Version:      ${version}`);
-  console.log(`  ⭐ Star us:      https://github.com/failproofai/failproofai`);
-  console.log(`  📖 Docs:         https://docs.befailproof.ai/introduction`);
-  console.log(`  💬 Discord:      https://discord.gg/2zjBZP7yQJ\n`);
+  // Branded splash — the same logomark + palette as the `configure` wizard, then
+  // a tidy version/links column. Falls back to plain text off a TTY.
+  for (const line of renderLaunchBanner(version)) console.log(line);
 
   let cmd: string;
   let cmdArgs: string[];