failproofai 1.0.0-beta.1 → 1.0.0-beta.3

package/src/hooks/configure-wizard.ts

@@ -13,12 +13,13 @@
  * install/uninstall manager and the existing searchable policy picker.
  */
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { resolve, sep } from "node:path";
 
 import {
   selectOne,
   multiSelect,
+  promptText,
   intro,
   outro,
   summarize,
@@ -26,6 +27,12 @@ import {
   type TTYIn,
   type TTYOut,
 } from "./tui";
+import {
+  DEFAULT_INGEST_URL,
+  validateIngestKey,
+  writeIngestCredential,
+  writeCollectorSettings,
+} from "./collector-config";
 import {
   detectInstalledClis,
   getIntegration,
@@ -43,9 +50,16 @@ import {
   isDaemonSupportedPlatform,
   installDaemonService,
   daemonServiceFilePath,
+  primeElevation,
   setDaemonConfigured,
 } from "./daemon-service";
 import { hookLogWarn } from "./hook-logger";
+import {
+  readCloudCredentials,
+  verifyCloudCredentials,
+  writeCloudCredentials,
+} from "./cloud-enrollment";
+import { cloudBaseFor, ingestUrlFor } from "./cloud-connection";
 
 export interface WizardIO {
   stdin?: TTYIn;
@@ -350,18 +364,31 @@ export function reviewLines(state: {
   cwd: string;
   /** The Custom checkbox. `undefined` = nothing to toggle, leave as-is. */
   customEnabled?: boolean;
+  /**
+   * Step 0's answer. The daemon is machine-level, so this is a decision the
+   * user made explicitly rather than something inferred from the scope —
+   * showing it any other way would promise a service the apply won't install.
+   */
+  installDaemon?: boolean;
 }): string[] {
-  const { scope, clis, policies, cwd, customEnabled } = state;
+  const { scope, clis, policies, cwd, customEnabled, installDaemon } = state;
   const where =
     scope === "project" ? `This project (${homeify(cwd)})` : "Everywhere (global)";
   const lines: string[] = [];
   const assistantNames = clis.map((c) => getIntegration(c).displayName);
   lines.push(`  Where      : ${where}`);
   lines.push(`  Assistants : ${assistantNames.length ? summarize(assistantNames, "assistants") : "(none)"}`);
-  lines.push(`  Policies   : ${policies.length} enabled`);
-  if (scope === "user" && isDaemonSupportedPlatform()) {
+  // Zero is a deliberate answer, not a failed step — say so, and say where to
+  // change it, so the review screen doesn't read like the wizard lost the
+  // selection. Hooks still install; only the builtin set is empty.
+  lines.push(
+    policies.length === 0
+      ? "  Policies   : none enabled (add later: failproofai policies --install)"
+      : `  Policies   : ${policies.length} enabled`,
+  );
+  if (installDaemon && isDaemonSupportedPlatform()) {
     lines.push(
-      `  Daemon     : failproofaid will be installed/started as a background service`,
+      `  Daemon     : failproofaid, installed as a system service running as you`,
     );
   }
 
@@ -389,9 +416,9 @@ export function reviewLines(state: {
     }
   }
   lines.push(`    ${homeify(getConfigPathForScope(scope, cwd))}   ${policies.length} policies`);
-  if (scope === "user" && isDaemonSupportedPlatform()) {
+  if (installDaemon && isDaemonSupportedPlatform()) {
     const servicePath = daemonServiceFilePath();
-    if (servicePath) lines.push(`    ${homeify(servicePath)}   failproofaid service`);
+    if (servicePath) lines.push(`    ${homeify(servicePath)}   failproofaid service (needs root)`);
   }
   return lines;
 }
@@ -500,6 +527,24 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
     return { applied: false };
   }
 
+  // Running the wizard itself under sudo configures the WRONG ACCOUNT, and
+  // does it silently: homedir() becomes /root, so the hooks land in root's
+  // settings, `daemonConfigured` is set for root, the daemon binary downloads
+  // to /root/.failproofai/bin, and the unit is generated with User=root —
+  // exactly the elevation the design exists to avoid. SUDO_USER is set only
+  // when a real user sudo'd here, which distinguishes this mistake from a
+  // legitimately root-only environment (a container that has no other user).
+  if (typeof process.getuid === "function" && process.getuid() === 0 && process.env.SUDO_USER) {
+    stdout.write(
+      `Run failproofai config as ${process.env.SUDO_USER}, not under sudo.\n` +
+        "Everything it configures is per-user — hooks, policies and the daemon's own\n" +
+        "account — so under sudo it would set all of that up for root instead of you.\n" +
+        "The one step that needs root (installing the service) asks for your password\n" +
+        "on its own.\n",
+    );
+    return { applied: false };
+  }
+
   // Fire-and-forget: never block the wizard's first paint on telemetry.
   void emit("configure_started", {});
   intro("let's set up your safety net", stdout);
@@ -509,6 +554,55 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
     return { applied: false };
   };
 
+  // 0 — The background daemon, before anything else.
+  //
+  // First because it is the only step that needs a password: asking here
+  // means sudo prompts on a clean terminal, before any question has drawn a
+  // screen, instead of firing from underneath a rendered TUI where the prompt
+  // is invisible and the typed password lands in a redrawn frame. `sudo -v`
+  // caches the credential for the rest of the run, so the actual install at
+  // apply time stays non-interactive.
+  //
+  // Machine-level, so it is deliberately NOT gated on the scope chosen in the
+  // next step: one daemon serves every project on this machine.
+  let daemonWanted = false;
+  let elevated = false;
+  if (isDaemonSupportedPlatform()) {
+    const choice = await selectOne<"install" | "skip">({
+      message: "Install the failproofaid background daemon?",
+      choices: [
+        {
+          label: "Yes — keep policy evaluation warm",
+          value: "install",
+          hint: "a system service, started at boot, running as you · needs your password once",
+        },
+        {
+          label: "Not now",
+          value: "skip",
+          hint: "policies still enforce, evaluated per hook call",
+        },
+      ],
+      stdin,
+      stdout,
+    });
+    if (choice === null) return cancel();
+    daemonWanted = choice === "install";
+
+    if (daemonWanted) {
+      stdout.write("\nInstalling the failproofaid service needs root. Your password stays with sudo.\n");
+      elevated = primeElevation();
+      if (!elevated) {
+        // Never fatal: the rest of setup is worth applying, and a machine with
+        // no daemon is exactly the machine every release before this one had.
+        stdout.write(
+          "Could not get sudo — carrying on without the daemon.\n" +
+            "Everything else still applies, and policies still enforce in-process.\n\n",
+        );
+        daemonWanted = false;
+      }
+    }
+  }
+
   // 1 — Where?
   const scope = await selectOne<HookScope>({
     message: "Where should this apply?",
@@ -561,12 +655,23 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
   const presetChoices = buildPresetChoices(cwd, customEnabledBefore);
   const hasCustomFiles = describeCustomPolicies(cwd).fileCount > 0;
 
+  // No minimum. Ticking nothing is a real answer — someone who only wants their
+  // own custom policies, or who intends to pick bundles later from the
+  // dashboard, was previously stuck on this step with no way forward and no
+  // explanation beyond "Select at least 1". An empty set is already supported
+  // end to end: `installHooksImpl` documents its explicit-array path as "may be
+  // empty", `replace: true` makes it the full enabled set, and `summarize([])`
+  // renders "none". Hooks still install, so enforcement can be switched on
+  // later without re-running setup.
+  //
+  // The assistants step above keeps its minimum deliberately: an empty CLI list
+  // does NOT mean "no assistants" there — `installHooksImpl` falls back to
+  // ["claude"], so letting it through would silently install for Claude.
   const presets = await multiSelect<string>({
     message: "What should we guard against?",
     choices: presetChoices,
-    minSelected: 1,
     summaryNoun: "bundles",
-    hint: "space toggles · combine presets · ↵ confirm",
+    hint: "space toggles · combine presets · ↵ confirm · none is fine",
     stdin,
     stdout,
   });
@@ -576,10 +681,169 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
   // locked-unchecked and must not write a disabling flag.
   const customEnabled = hasCustomFiles ? presets.includes(CUSTOM) : undefined;
 
-  // 4 — Review & apply
+  // 4 — Send data to AgentEye? Last, and only when a daemon was asked for,
+  // since the daemon is what runs the collector.
+  //
+  // Deliberately AFTER the enforcement questions rather than beside the daemon
+  // one: by this point the user has decided what to protect, so "and would you
+  // like to see it in a dashboard?" follows naturally, where asking up front
+  // interrupts setup with a question about a product they may not have.
+  //
+  // Defaults to NO, and the transcript choice is a SEPARATE question from the
+  // key, because a transcript carries prompts, file contents and whatever was
+  // pasted into a terminal. Configuring ingest must never silently send those.
+  let collector: { cred: { url: string; key: string }; sessions: boolean } | null = null;
+  if (daemonWanted) {
+    const send = await selectOne<"yes" | "no">({
+      message: "Send session and hook data to AgentEye?",
+      choices: [
+        {
+          label: "Not now",
+          value: "no",
+          hint: "nothing leaves this machine",
+        },
+        {
+          label: "Yes — connect to a dashboard",
+          value: "yes",
+          hint: "needs an events:add API key",
+        },
+      ],
+      stdin,
+      stdout,
+    });
+    if (send === null) return cancel();
+
+    if (send === "yes") {
+      // If this machine is ALREADY enrolled with Failproof Cloud, it has a URL
+      // and a token that usually work for both capabilities. Asking for them
+      // again is the seam that made connecting feel like two products: someone
+      // runs `--connect`, sees an empty dashboard, and has no reason to think a
+      // second credential exists. Offer what we already know, and let it be
+      // overridden.
+      const existing = readCloudCredentials();
+      let url: string | null = null;
+      let key: string | null = null;
+
+      if (existing) {
+        const reuse = await selectOne<"reuse" | "other">({
+          message: `Use this machine's existing connection to ${existing.url}?`,
+          choices: [
+            {
+              label: `Yes — reuse it`,
+              value: "reuse",
+              hint: `as ${existing.machineId}, same token`,
+            },
+            { label: "No — use a different endpoint and key", value: "other", hint: "" },
+          ],
+          stdin,
+          stdout,
+        });
+        if (reuse === null) return cancel();
+        if (reuse === "reuse") {
+          url = ingestUrlFor(existing.url);
+          key = existing.token;
+        }
+      }
+
+      if (url === null) {
+        const entered = await promptText({
+          message: "Failproof Cloud URL",
+          defaultValue: cloudBaseFor(DEFAULT_INGEST_URL),
+          hint: "Enter for the hosted endpoint",
+          validate: (v) => (/^https?:\/\//.test(v) ? null : "must be an http(s) URL"),
+          stdin,
+          stdout,
+        });
+        if (entered === null) return cancel();
+        // Asked for as a base and derived, so this and `--connect` take the
+        // same thing. Someone pasting the older `/events` endpoint still works.
+        url = ingestUrlFor(cloudBaseFor(entered));
+      }
+
+      if (key === null) {
+        key = await promptText({
+          message: "API key",
+          hint: "needs events:add",
+          // Masked: setup is routinely run while screen-sharing, and a pasted key
+          // would otherwise sit in the scrollback of every recording.
+          mask: true,
+          validate: (v) => (v.length >= 8 ? null : "that looks too short to be a key"),
+          stdin,
+          stdout,
+        });
+        if (key === null) return cancel();
+      }
+
+      // Check BEFORE writing anything. A typo'd key is otherwise only
+      // discovered later as a silent pile of 401s parked in failed/, which
+      // reads like a server problem rather than a typo.
+      stdout.write("\nChecking the key… ");
+      const check = await validateIngestKey({ url, key });
+      if (!check.ok) {
+        stdout.write(`\nThat did not work: ${check.reason}\n`);
+        const retry = await selectOne<"skip" | "anyway">({
+          message: "Carry on without sending data?",
+          choices: [
+            { label: "Yes, skip it", value: "skip", hint: "re-run failproofai config later" },
+            { label: "Save it anyway", value: "anyway", hint: "if you know the server is just down" },
+          ],
+          stdin,
+          stdout,
+        });
+        if (retry === null) return cancel();
+        if (retry === "skip") {
+          stdout.write("Skipping data collection. Everything else still applies.\n\n");
+        } else {
+          collector = { cred: { url, key }, sessions: false };
+        }
+      } else {
+        stdout.write("looks good.\n");
+        const sessions = await selectOne<"hooks" | "both">({
+          message: "What should it send?",
+          choices: [
+            {
+              label: "Policy decisions only",
+              value: "hooks",
+              hint: "which hooks fired and what they decided \u00b7 no file contents",
+            },
+            {
+              label: "Decisions and full session transcripts",
+              value: "both",
+              hint: "includes prompts, file contents and command output",
+            },
+          ],
+          stdin,
+          stdout,
+        });
+        if (sessions === null) return cancel();
+        collector = { cred: { url, key }, sessions: sessions === "both" };
+
+        // The other half of the same connection. If this machine is not
+        // enrolled for policy and the key turns out to carry `policies:pull`,
+        // enrol it here rather than making the user discover a second command.
+        // Silent when the key lacks the permission — an events-only key is a
+        // perfectly reasonable thing to have, and a warning about a capability
+        // nobody asked for is noise.
+        if (!readCloudCredentials()) {
+          const base = cloudBaseFor(url);
+          const machineId = hostname();
+          const enrol = await verifyCloudCredentials({ url: base, machineId, token: key });
+          if (enrol.ok) {
+            writeCloudCredentials({ url: base, machineId, token: key });
+            stdout.write(
+              `Also connected for cloud-managed policy (${enrol.policyCount} assigned, generation ${enrol.generation}).\n`,
+            );
+          }
+        }
+      }
+    }
+  }
+
+
+  // 5 — Review & apply
   const decision = await selectOne<"apply" | "cancel">({
     message: "Ready to apply?",
-    body: reviewLines({ scope, clis, policies, cwd, customEnabled }),
+    body: reviewLines({ scope, clis, policies, cwd, customEnabled, installDaemon: daemonWanted }),
     choices: [
       { label: "Yes, apply now", value: "apply", hint: "write the config" },
       { label: "Cancel", value: "cancel", hint: "quit, no changes" },
@@ -615,14 +879,14 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
   );
   setCustomPoliciesEnabled(scope, cwd, customEnabled);
 
-  // Daemon setup — unconditional on Linux/macOS whenever the global scope
-  // was chosen (a daemon is per-machine, not per-project), no separate
-  // opt-in step or command. A failure here (binary not found, no service
-  // manager, ...) never fails the wizard — the rest of setup already
-  // applied, and this machine simply stays on the in-process path exactly
-  // as before, since `daemonConfigured` is only set on success.
+  // Daemon setup — driven by step 0's answer, with the sudo credential it
+  // already primed, so nothing here can stop to ask a question. A failure
+  // (binary download blocked, no service manager, a daemon that won't stay
+  // up) never fails the wizard: the rest of setup already applied, and this
+  // machine simply stays on the in-process path, since `daemonConfigured` is
+  // only set on success.
   let daemonInstalled = false;
-  if (scope === "user" && isDaemonSupportedPlatform()) {
+  if (daemonWanted) {
     const daemonResult = await installDaemonService();
     if (daemonResult.installed) {
       setDaemonConfigured(true);
@@ -643,6 +907,32 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
     });
   }
 
+  // Collector config, written only when the daemon actually came up: the
+  // daemon is what runs the collector, so writing a credential for a service
+  // that failed to install would leave a key on disk doing nothing.
+  if (collector && daemonInstalled) {
+    try {
+      writeIngestCredential(collector.cred);
+      writeCollectorSettings({
+        sessions: collector.sessions,
+        hooks: true,
+        hooksVerbosity: "decisions",
+        redact: "minimal",
+      });
+      // Never the key, the URL, or the count — only that it happened and what
+      // shape of data the user agreed to send.
+      void emit("configure_collector", { sessions: collector.sessions });
+    } catch (err) {
+      // Non-fatal, like the daemon: the rest of setup is worth keeping, and a
+      // machine with no collector behaves exactly as every release before this.
+      hookLogWarn(
+        `collector configuration was not written: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  } else if (collector && !daemonInstalled) {
+    hookLogWarn("skipped collector configuration because the daemon was not installed");
+  }
+
   await applied;
   // Only now — a completed apply — is the launcher considered "seen", so the
   // first-run bare invocation stops redirecting here and opens the dashboard.

package/src/hooks/custom-hooks-loader.ts

@@ -12,29 +12,40 @@
  */
 import { resolve, isAbsolute, basename } from "node:path";
 import { existsSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 import { hookLogWarn, hookLogError, hookLogInfo } from "./hook-logger";
-import { getCustomHooks, clearCustomHooks } from "./custom-hooks-registry";
+import { customPolicies, getCustomHooks, clearCustomHooks } from "./custom-hooks-registry";
 import { findDistIndex, rewriteFileTree, TMP_SUFFIX, cleanupTmpFiles } from "./loader-utils";
 import { findProjectConfigDir } from "./hooks-config";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
 import type { CustomHook } from "./policy-types";
+import type { CloudManagedPolicyArtifact } from "./cloud-managed-policies";
 
 const LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__";
 
 /** Regex matching convention policy filenames: *policies.{js,mjs,ts} */
 const CONVENTION_FILE_RE = /policies\.(js|mjs|ts)$/;
 
-/**
- * Monotonic counter used to cache-bust each dynamic import. Loading N files
- * creates N module instances rather than reusing one; every caller here is
- * either a one-shot CLI command or a short-lived hook process, so the
- * lifetime cost is bounded by the process, not by uptime.
- */
+/** Monotonic suffix for physically distinct temporary module trees. Bun
+ * ignores URL query strings when caching imports, so a query-only cache
+ * buster silently drops custom policies after the first request in the warm
+ * daemon worker. A unique filename is honored by both Bun and Node. */
 let loadSequence = 0;
 
+interface CachedPolicyModule {
+  fingerprint: string;
+  hooks: CustomHook[];
+}
+
+/** One retained module instance per source entry. Reusing its registered hook
+ * functions prevents an unbounded ESM module-cache leak in the resident worker.
+ * A source-tree change replaces this entry and imports one new module. */
+const policyModuleCache = new Map<string, CachedPolicyModule>();
+
 /** Script extensions we could load, used to spot near-miss filenames. */
 const LOADABLE_EXT_RE = /\.(js|mjs|ts)$/;
 
@@ -101,23 +112,27 @@ async function loadSingleFile(
     const distIndex = await findDistIndex();
     const distUrl = distIndex ? pathToFileURL(distIndex).href : null;
 
-    tmpFiles = await rewriteFileTree(absPath, distUrl, distIndex);
-
-    const entryTmp = absPath + TMP_SUFFIX;
-    // Cache-bust the specifier. NOTE this works under Node but NOT under Bun,
-    // which caches by resolved path and ignores the query — and the shipped
-    // binary runs under Bun. It is kept because it makes repeat loads behave
-    // the same on both runtimes where it can, but nothing may DEPEND on a
-    // repeat load re-executing; callers dedupe paths instead (see above).
-    // The temp path is deterministic, so a second
-    // load of the same file inside one process hit the ESM module cache, the
-    // module body never re-ran, no `customPolicies.add` fired, and the caller
-    // saw zero hooks — indistinguishable from a broken policy file. That is
-    // exactly what `failproofai policies` rendered as "failed to load" for
-    // every file when it walked a shared project/user directory twice.
-    // A distinct query string makes it a distinct module to the loader.
-    const fileUrl = `${pathToFileURL(entryTmp).href}?v=${++loadSequence}`;
+    const sequence = ++loadSequence;
+    const tmpSuffix = `${TMP_SUFFIX}.${process.pid}.${sequence}.mjs`;
+    tmpFiles = await rewriteFileTree(absPath, distUrl, distIndex, tmpSuffix);
+
+    const fingerprint = await fingerprintTemporaryTree(tmpFiles, tmpSuffix);
+    const cached = policyModuleCache.get(absPath);
+    if (cached?.fingerprint === fingerprint) {
+      for (const hook of cached.hooks) customPolicies.add({ ...hook });
+      return;
+    }
+
+    const entryTmp = absPath + tmpSuffix;
+    const fileUrl = pathToFileURL(entryTmp).href;
+    const hooksBefore = getCustomHooks().length;
     await import(/* webpackIgnore: true */ fileUrl);
+    policyModuleCache.set(absPath, {
+      fingerprint,
+      hooks: getCustomHooks()
+        .slice(hooksBefore)
+        .map((hook) => ({ ...hook })),
+    });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     const errorType = /Cannot find module|MODULE_NOT_FOUND|ENOENT/i.test(msg)
@@ -139,6 +154,18 @@ async function loadSingleFile(
   }
 }
 
+async function fingerprintTemporaryTree(tmpFiles: string[], tmpSuffix: string): Promise<string> {
+  const hash = createHash("sha256");
+  for (const tmpFile of [...tmpFiles].sort()) {
+    // The generated filenames change per load. Normalize both the logical path
+    // and rewritten import specifiers so identical source graphs hash equally.
+    hash.update(tmpFile.replaceAll(tmpSuffix, TMP_SUFFIX));
+    const contents = await readFile(tmpFile, "utf8");
+    hash.update(contents.replaceAll(tmpSuffix, TMP_SUFFIX));
+  }
+  return hash.digest("hex");
+}
+
 /**
  * Load a single explicit custom hooks file (legacy API).
  * Clears the registry, loads the file, returns registered hooks.
@@ -214,7 +241,11 @@ function warnSkippedPolicyFiles(dir: string, scope: "project" | "user"): void {
 
 export async function loadAllCustomHooks(
   customPoliciesPaths: string | string[] | undefined,
-  opts?: { sessionCwd?: string; customPoliciesEnabled?: boolean },
+  opts?: {
+    sessionCwd?: string;
+    customPoliciesEnabled?: boolean;
+    cloudManagedPolicies?: CloudManagedPolicyArtifact[];
+  },
 ): Promise<LoadAllResult> {
   clearCustomHooks();
 
@@ -235,6 +266,9 @@ export async function loadAllCustomHooks(
   // twice per event. Seeded by the explicit path below and consulted by both
   // convention passes.
   const loadedPaths = new Set<string>();
+  const cloudManagedByPath = new Map(
+    (opts?.cloudManagedPolicies ?? []).map((policy) => [resolve(policy.path), policy]),
+  );
 
   // 1. Explicit custom policy paths. Accept a string for callers/configs using
   // the legacy singular form.
@@ -250,7 +284,17 @@ export async function loadAllCustomHooks(
         const hooksBefore = getCustomHooks().length;
         await loadSingleFile(absPath);
         for (const hook of getCustomHooks().slice(hooksBefore)) {
-          (hook as CustomHook & { __policyId?: string }).__policyId = customPolicyId(absPath, hook.name);
+          const cloudManaged = cloudManagedByPath.get(absPath);
+          const tagged = hook as CustomHook & {
+            __policyId?: string;
+            __cloudManaged?: CloudManagedPolicyArtifact;
+          };
+          if (cloudManaged) {
+            tagged.__cloudManaged = cloudManaged;
+            tagged.__policyId = `cloud:${cloudManaged.id}@${cloudManaged.revision}:${hook.name}`;
+          } else {
+            tagged.__policyId = customPolicyId(absPath, hook.name);
+          }
         }
       }
     } else {

package/src/hooks/daemon-client.ts

@@ -17,6 +17,7 @@ import { resolve } from "node:path";
 import { homedir } from "node:os";
 import type { IntegrationType } from "./types";
 import { readHooksConfig } from "./hooks-config";
+import { existsSync } from "node:fs";
 
 const PROTOCOL_VERSION = 1;
 
@@ -66,6 +67,23 @@ export interface DaemonHookResponse {
   stderr: string;
 }
 
+/**
+ * Whether a daemon is listening, regardless of how it was started.
+ *
+ * Distinct from `daemonServiceStatus()`, which asks the service manager. A
+ * daemon run by hand — during development, or from a container — is invisible
+ * to that check but is very much running and pulling policy, so reporting "not
+ * installed, so nothing will be pulled" at someone whose machine is actively
+ * enforcing is simply false.
+ */
+export function daemonSocketPresent(): boolean {
+  try {
+    return existsSync(socketPath());
+  } catch {
+    return false;
+  }
+}
+
 function socketPath(): string {
   if (process.env.FAILPROOFAI_DAEMON_SOCKET) return process.env.FAILPROOFAI_DAEMON_SOCKET;
   return resolve(homedir(), ".failproofai", "run", "failproofaid.sock");