failproofai 1.0.0-beta.2 → 1.0.0-beta.21

package/src/hooks/onboarding-attempt.ts

@@ -0,0 +1,195 @@
+/**
+ * Why the last first-run setup stopped, and whether it is worth offering again.
+ *
+ * # The problem this exists for
+ *
+ * Setup is deliberately all-or-nothing: every abort path writes NOTHING, so a
+ * machine that could not be configured is left exactly as it was found rather
+ * than carrying half a configuration (a `daemonConfigured` flag with no daemon
+ * behind it denies every tool call across all twelve CLIs). That invariant is
+ * right and is not changed here.
+ *
+ * But it left onboarding with no memory. `isConfigured()` reads three signals —
+ * a global policy config, live user-scope hooks, the legacy marker — and an
+ * abort sets none of them, so "never tried" and "tried twenty times and could
+ * not finish" are indistinguishable. On a machine without passwordless sudo,
+ * every single command relaunched the whole wizard, forever.
+ *
+ * # What this is NOT
+ *
+ * Not a fourth "configured" signal. Nothing here may make `isConfigured()` true.
+ * A machine that failed setup is unconfigured and must keep saying so — to the
+ * hook path, to `--status`, and to the wizard when it is asked for by name.
+ * This only changes whether the wizard is *offered unprompted*.
+ *
+ * # Re-offering
+ *
+ * A hint that never becomes an offer again is its own failure: the common case
+ * is someone who hits the sudo prompt, gives up, and comes back later able to
+ * elevate. So each reason carries a cheap local check for whether its blocker
+ * is gone, and the wizard offers itself again the moment one is:
+ *
+ *   needs_root          -> elevation is now possible without a prompt
+ *   daemon_failed       -> the service manager now reports something different
+ *   cancelled           -> the CLI version changed; an upgrade is a fair moment to
+ *                          ask again, and nothing else about a deliberate cancel
+ *                          should re-nag
+ *   unsupported_platform -> the CLI version changed (a future release might
+ *                          support this platform)
+ *
+ * Every probe is local and takes milliseconds. None of them runs on the hook
+ * path — `--hook` never reaches the first-run gate at all.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { onboardingAttemptFile } from "./fp-home";
+import type { WizardAbort } from "./configure-wizard";
+
+/** Bumped only for a deliberate shape change; an unreadable record is ignored. */
+const SCHEMA_VERSION = 1;
+
+export interface OnboardingAttempt {
+  schemaVersion: number;
+  /** Why the wizard stopped. */
+  reason: WizardAbort;
+  /** The CLI that made the attempt, so an upgrade can re-offer. */
+  cliVersion: string;
+  /**
+   * What the service manager said at the time. Compared, never trusted — the
+   * point is only whether it has CHANGED since.
+   */
+  daemonStatus: string;
+  /** Epoch ms, for support and for nothing else. */
+  at: number;
+}
+
+export function readOnboardingAttempt(): OnboardingAttempt | null {
+  const path = onboardingAttemptFile();
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<OnboardingAttempt>;
+    if (raw.schemaVersion !== SCHEMA_VERSION) return null;
+    if (typeof raw.reason !== "string" || typeof raw.cliVersion !== "string") return null;
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      reason: raw.reason as WizardAbort,
+      cliVersion: raw.cliVersion,
+      daemonStatus: typeof raw.daemonStatus === "string" ? raw.daemonStatus : "",
+      at: typeof raw.at === "number" ? raw.at : 0,
+    };
+  } catch {
+    // A corrupt record reads as "no record", which degrades to today's
+    // behaviour — offering the wizard. Never to "configured".
+    return null;
+  }
+}
+
+/** Best-effort: a machine that cannot record this simply keeps being offered. */
+export function recordOnboardingAttempt(
+  reason: WizardAbort,
+  cliVersion: string,
+  daemonStatus: string,
+  now: number = Date.now(),
+): void {
+  try {
+    const path = onboardingAttemptFile();
+    mkdirSync(dirname(path), { recursive: true });
+    const record: OnboardingAttempt = {
+      schemaVersion: SCHEMA_VERSION,
+      reason,
+      cliVersion,
+      daemonStatus,
+      at: now,
+    };
+    writeFileSync(path, JSON.stringify(record, null, 2), "utf8");
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Called on a completed apply. A stale record would keep suppressing the offer
+ * on a machine that has since been reconfigured by hand and un-configured again.
+ */
+export function clearOnboardingAttempt(): void {
+  try {
+    rmSync(onboardingAttemptFile(), { force: true });
+  } catch {
+    // best-effort
+  }
+}
+
+export interface RetryProbe {
+  /** Elevation is possible without prompting. */
+  canElevate: () => boolean;
+  /** What the service manager says right now. */
+  daemonStatus: () => string;
+  /** This CLI's version. */
+  cliVersion: string;
+}
+
+/**
+ * Whether the thing that stopped setup last time has since changed.
+ *
+ * `true` means offer the wizard again; `false` means a one-line hint. An
+ * unrecognised reason returns `true` — an unknown blocker is one we cannot
+ * prove is still present, and the safe direction is offering setup rather than
+ * silently withholding it.
+ */
+export function blockerCleared(attempt: OnboardingAttempt, probe: RetryProbe): boolean {
+  switch (attempt.reason) {
+    case "needs_root":
+      return probe.canElevate();
+    case "daemon_failed":
+      // Any movement at all: not-installed -> stopped, stopped -> running, or a
+      // platform that has gained a service manager. Comparing rather than
+      // demanding "running" is what lets a partially-repaired machine be
+      // offered setup again instead of waiting for a state it cannot reach on
+      // its own.
+      return probe.daemonStatus() !== attempt.daemonStatus || probe.canElevate();
+    case "cancelled":
+      // A deliberate stop. Re-asking on the next command is exactly the nagging
+      // this module removes — but an upgrade is a new thing to say, so it is
+      // allowed to ask once more.
+      return probe.cliVersion !== attempt.cliVersion;
+    case "unsupported_platform":
+      // A permanent property of the machine, not the invocation — nagging every
+      // command would just repeat the hard-fail. Only a new release is a reason
+      // to ask again (it might add support for this platform).
+      return probe.cliVersion !== attempt.cliVersion;
+    case "not_a_tty":
+    case "running_as_sudo":
+      // Both are properties of the invocation, not of the machine, so the next
+      // one may well be fine.
+      return true;
+    default:
+      return true;
+  }
+}
+
+/** The one line shown instead of relaunching the wizard. */
+export function attemptHintLines(attempt: OnboardingAttempt): string[] {
+  const why: Record<string, string> = {
+    needs_root: "it needs root to install the failproofaid service",
+    daemon_failed: "the failproofaid service could not be started",
+    cancelled: "it was cancelled",
+    unsupported_platform: "failproofaid does not run on this platform",
+    not_a_tty: "there was no terminal to ask in",
+    running_as_sudo: "it was run under sudo",
+  };
+  const detail = why[attempt.reason] ?? "it did not finish";
+  // Every other reason is fixable by the user right now, so the generic
+  // retry is correct. unsupported_platform is not — blockerCleared only
+  // re-offers it on a CLI version change, and `failproofai config` would
+  // hit the exact same hard-fail in the meantime.
+  const action =
+    attempt.reason === "unsupported_platform"
+      ? "Check for a failproofai update — this platform may be supported by a newer release."
+      : "Run `failproofai config` when you are ready.";
+  return [
+    ``,
+    `[failproofai] Setup is not finished — ${detail}.`,
+    `              ${action}`,
+    ``,
+  ];
+}

package/src/hooks/onboarding-lock.ts

@@ -0,0 +1,118 @@
+/**
+ * A single-holder guard around first-run onboarding.
+ *
+ * Onboarding used to fire only on a bare `failproofai`. It now fires on any
+ * command an unconfigured machine runs, which makes concurrent runs a real
+ * shape rather than a theoretical one: two terminals, `failproofai audit` in
+ * each, and both draw a wizard. They would then race on the same settings
+ * files and, worse, both try to install the system service — two `sudo`
+ * prompts and two `systemctl enable` calls against one unit.
+ *
+ * ## Why liveness, not a timeout
+ *
+ * The obvious lock carries a timestamp and is treated as stale after N
+ * seconds. That cannot work here: the holder is a human answering questions,
+ * so any N short enough to recover promptly from a crash is also short enough
+ * to evict someone who walked away mid-setup. So the lock records a PID and is
+ * considered held only while that process is actually alive — which recovers
+ * instantly from a crash or a Ctrl-C, and never evicts a live wizard no matter
+ * how long it sits.
+ *
+ * ## Failure direction
+ *
+ * Every failure here resolves to "do not onboard". A lock we cannot take is
+ * indistinguishable from one already held, and skipping onboarding costs a
+ * user one printed hint, where wrongly proceeding costs a duplicated install.
+ * The command the user typed always runs either way.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { onboardingLockFile, stateDir } from "./fp-home";
+
+interface LockBody {
+  pid: number;
+  startedAt: number;
+}
+
+export function onboardingLockPath(home: string = homedir()): string {
+  return onboardingLockFile(home);
+}
+
+/**
+ * Whether `pid` is a live process this user can signal.
+ *
+ * `kill(pid, 0)` performs the permission and existence checks without
+ * delivering a signal. `EPERM` means the process exists but belongs to another
+ * user — still alive, so still holding the lock.
+ */
+function processAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException)?.code === "EPERM";
+  }
+}
+
+function readLock(path: string): LockBody | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<LockBody>;
+    if (typeof parsed.pid !== "number") return null;
+    return { pid: parsed.pid, startedAt: Number(parsed.startedAt) || 0 };
+  } catch {
+    // Absent, unreadable, or truncated by a crash mid-write. All three mean
+    // "no live holder we can prove", and the liveness check below is what
+    // actually decides.
+    return null;
+  }
+}
+
+export interface OnboardingLock {
+  /** Release the lock. Safe to call more than once. */
+  release(): void;
+}
+
+/**
+ * Take the onboarding lock, or return `null` if another live process holds it.
+ *
+ * There is a small window between the liveness check and the write in which
+ * two processes could both decide the lock is free. That is accepted
+ * deliberately: closing it needs `O_EXCL` plus stale-file recovery, which
+ * reintroduces exactly the timeout problem this design avoids — and the
+ * consequence of losing that race is two wizards, which is the situation
+ * before this existed, not something worse.
+ */
+export function acquireOnboardingLock(home: string = homedir()): OnboardingLock | null {
+  const path = onboardingLockPath(home);
+  try {
+    const held = readLock(path);
+    // Our own PID appearing here means a previous run in this same process
+    // already holds it — re-entering is fine and must not deadlock.
+    if (held && held.pid !== process.pid && processAlive(held.pid)) return null;
+
+    mkdirSync(stateDir(home), { recursive: true });
+    const body: LockBody = { pid: process.pid, startedAt: Date.now() };
+    writeFileSync(path, JSON.stringify(body), "utf8");
+
+    let released = false;
+    return {
+      release() {
+        if (released) return;
+        released = true;
+        try {
+          // Only remove a lock still recorded as ours: if this process was
+          // evicted as dead and another wizard took over, deleting the file
+          // would release someone else's lock.
+          const current = readLock(path);
+          if (!current || current.pid === process.pid) rmSync(path, { force: true });
+        } catch {
+          /* best effort — a stray lock is reclaimed by the liveness check */
+        }
+      },
+    };
+  } catch {
+    // Unwritable home, read-only filesystem, whatever it is: treat as held.
+    return null;
+  }
+}

package/src/hooks/policy-types.ts

@@ -80,8 +80,36 @@ export interface LlmConfig {
   model?: string;
 }
 
+/**
+ * The collector's non-secret settings. The ingest credential deliberately does
+ * NOT live here: this file is written with a bare `writeFileSync`, so it
+ * inherits the umask and lands at 0664 inside a 0775 `~/.failproofai/` — an API
+ * key here would be readable by every local user. It lives in
+ * `~/.failproofai/ingest.json` at 0600 instead.
+ *
+ * Read by the Rust daemon (`crates/fpai-collect/src/config.rs`); the field
+ * names must stay in step with the `Settings` struct there.
+ */
+export interface CollectorConfig {
+  /**
+   * Ship agent session transcripts. Defaults to false and is a SEPARATE opt-in
+   * from configuring a key, because transcripts carry prompts, file contents
+   * and whatever was pasted into a terminal.
+   */
+  sessions?: boolean;
+  /** Ship hook activity. Carries decisions and tool names, never file contents. */
+  hooks?: boolean;
+  /** `decisions` keeps every deny/instruct exact and aggregates the ~99% allows. */
+  hooksVerbosity?: "all" | "decisions" | "off";
+  redact?: "minimal" | "off";
+  /** Label stamped on every event. Must not contain a comma — ingest skips those lines. */
+  environment?: string;
+}
+
 export interface HooksConfig {
   enabledPolicies: string[];
+  /** Collector settings; see {@link CollectorConfig}. Absent means unconfigured. */
+  collector?: CollectorConfig;
   llm?: LlmConfig;
   policyParams?: Record<string, Record<string, unknown>>;
   /** Explicit custom policy files, loaded in array order. */

package/src/hooks/session-pause-cli.ts

@@ -0,0 +1,159 @@
+/**
+ * `failproofai config --pause | --resume | --status`.
+ *
+ * Lives on `config` rather than as its own verb because `config` is the single
+ * place this product configures anything. The state it writes is NOT config
+ * though — see session-pause.ts for why a pause must never reach a file that
+ * gets committed.
+ */
+import {
+  PAUSE_CEILING_MS,
+  clearPause,
+  formatDuration,
+  listActivePauses,
+  parsePauseDuration,
+  readActivePause,
+  resolveSessionForCwd,
+  writePause,
+  type ActivePause,
+} from "./session-pause";
+
+export interface PauseCommandOptions {
+  action: "pause" | "resume" | "status";
+  /** Raw `--pause <duration>` argument, if any. */
+  duration?: string;
+  /** Explicit `--session <id>`. */
+  sessionId?: string;
+  /** `--all`. */
+  all?: boolean;
+  cwd?: string;
+  now?: number;
+}
+
+export interface PauseCommandResult {
+  exitCode: number;
+  lines: string[];
+  /** For telemetry; never the session id itself. */
+  affected: number;
+}
+
+/**
+ * The ceiling on a single `--pause`.
+ *
+ * Took a `cwd` and consulted `readMergedHooksConfig(cwd).maxPauseMs` to let a
+ * project LOWER it. That path was dead: the merge in `hooks-config.ts` builds
+ * its result field by field and never emits `maxPauseMs`, so the lookup could
+ * only ever read `undefined` — and the two tests that claimed to cover it
+ * `vi.mock`ed `readMergedHooksConfig` to return a field the real function
+ * cannot produce, which is why the gap survived. The knob is removed rather
+ * than wired up: nothing documented it, nothing could have used it, and the
+ * hard ceiling was doing all the work already.
+ *
+ * Kept as a function, and still the only thing `--pause` measures against, so
+ * reinstating a config lowering later is a change in one place.
+ */
+export function effectiveCeilingMs(): number {
+  return PAUSE_CEILING_MS;
+}
+
+function describe(pause: ActivePause, now: number): string {
+  const remaining = formatDuration(Math.max(0, pause.expiresAt - now));
+  const at = new Date(pause.expiresAt).toLocaleTimeString();
+  const where = pause.cwd ? ` · ${pause.cwd}` : "";
+  return `  ${pause.sessionId}  ${remaining} left (until ${at})${where}`;
+}
+
+export function runPauseCommand(opts: PauseCommandOptions): PauseCommandResult {
+  const now = opts.now ?? Date.now();
+  const cwd = opts.cwd ?? process.cwd();
+
+  if (opts.action === "status") {
+    const active = listActivePauses(now);
+    if (active.length === 0) {
+      return { exitCode: 0, lines: ["Enforcement is active — nothing is paused."], affected: 0 };
+    }
+    return {
+      exitCode: 0,
+      lines: [
+        `Enforcement paused for ${active.length} session${active.length === 1 ? "" : "s"}:`,
+        ...active.map((p) => describe(p, now)),
+        "",
+        "Cloud-managed policies keep enforcing regardless.",
+        "Resume early with: failproofai config --resume",
+      ],
+      affected: active.length,
+    };
+  }
+
+  if (opts.action === "resume") {
+    if (opts.all) {
+      const active = listActivePauses(now);
+      let cleared = 0;
+      for (const pause of active) if (clearPause(pause.sessionId)) cleared++;
+      return {
+        exitCode: 0,
+        lines: [cleared === 0 ? "Nothing was paused." : `Resumed enforcement for ${cleared} session(s).`],
+        affected: cleared,
+      };
+    }
+    const sessionId = opts.sessionId ?? resolveSessionForCwd(cwd, undefined, now);
+    if (!sessionId) {
+      return { exitCode: 0, lines: ["Nothing was paused for this directory."], affected: 0 };
+    }
+    const cleared = clearPause(sessionId);
+    return {
+      exitCode: 0,
+      lines: [cleared ? "Enforcement resumed." : "Nothing was paused for that session."],
+      affected: cleared ? 1 : 0,
+    };
+  }
+
+  // pause
+  let durationMs: number;
+  try {
+    durationMs = parsePauseDuration(opts.duration, effectiveCeilingMs());
+  } catch (err) {
+    return { exitCode: 1, lines: [err instanceof Error ? err.message : String(err)], affected: 0 };
+  }
+
+  const sessionId = opts.sessionId ?? resolveSessionForCwd(cwd, undefined, now);
+  if (!sessionId) {
+    // Deliberately an error, not a guess. Pausing the wrong session would leave
+    // the user believing enforcement is off while it is on, or vice versa.
+    return {
+      exitCode: 1,
+      lines: [
+        "No recent agent session found for this directory.",
+        "",
+        "A pause applies to one agent session, and the session id only appears once",
+        "an agent has run at least one tool call here. Either run your agent first,",
+        "or name the session explicitly:",
+        "",
+        "  failproofai config --pause --session <id>",
+        "",
+        "Session ids are listed in the dashboard's activity view.",
+      ],
+      affected: 0,
+    };
+  }
+
+  const existing = readActivePause(sessionId, now);
+  const pause = writePause({ sessionId, durationMs, cwd, setBy: "cli", now });
+  const until = new Date(pause.expiresAt).toLocaleTimeString();
+
+  return {
+    exitCode: 0,
+    lines: [
+      existing
+        ? `Enforcement pause extended · ${formatDuration(durationMs)} · resumes at ${until}`
+        : `Enforcement paused · ${formatDuration(durationMs)} · resumes at ${until}`,
+      "",
+      "  Builtin, custom and convention policies are suspended for this session.",
+      "  Cloud-managed policies keep enforcing.",
+      "",
+      "It lifts on its own — no action needed. To end it early:",
+      "  failproofai config --resume",
+    ],
+    affected: 1,
+  };
+}