failproofai 1.0.0-beta.5 → 1.0.0-beta.7

package/src/hooks/onboarding-attempt.ts

@@ -0,0 +1,179 @@
+/**
+ * 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
+ *
+ * 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 "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",
+    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";
+  return [
+    ``,
+    `[failproofai] Setup is not finished — ${detail}.`,
+    `              Run \`failproofai config\` when you are ready.`,
+    ``,
+  ];
+}

package/src/hooks/onboarding-lock.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+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

@@ -126,13 +126,6 @@ export interface HooksConfig {
    * Only ever written explicitly as `false`.
    */
   customPoliciesEnabled?: boolean;
-  /**
-   * Upper bound, in ms, on how long `failproofai config --pause` may suspend
-   * enforcement. Only ever LOWERS the built-in 8h ceiling — a value above it is
-   * clamped back down, because a ceiling a project can raise is not a ceiling.
-   * Absent means the built-in ceiling applies.
-   */
-  maxPauseMs?: number;
   /**
    * Record of the convention policies (`.failproofai/policies/*policies.mjs`)
    * discovered at this scope the last time a failproofai command ran.

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

@@ -17,7 +17,6 @@ import {
   writePause,
   type ActivePause,
 } from "./session-pause";
-import { readMergedHooksConfig } from "./hooks-config";
 
 export interface PauseCommandOptions {
   action: "pause" | "resume" | "status";
@@ -39,18 +38,21 @@ export interface PauseCommandResult {
 }
 
 /**
- * The ceiling, after any config lowering. A project may tighten this; nothing
- * may loosen it, so a config asking for 24h still gets 8h.
+ * 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(cwd?: string): number {
-  try {
-    const configured = readMergedHooksConfig(cwd).maxPauseMs;
-    if (typeof configured === "number" && Number.isFinite(configured) && configured > 0) {
-      return Math.min(configured, PAUSE_CEILING_MS);
-    }
-  } catch {
-    // An unreadable config must not remove the ceiling.
-  }
+export function effectiveCeilingMs(): number {
   return PAUSE_CEILING_MS;
 }
 
@@ -109,7 +111,7 @@ export function runPauseCommand(opts: PauseCommandOptions): PauseCommandResult {
   // pause
   let durationMs: number;
   try {
-    durationMs = parsePauseDuration(opts.duration, effectiveCeilingMs(cwd));
+    durationMs = parsePauseDuration(opts.duration, effectiveCeilingMs());
   } catch (err) {
     return { exitCode: 1, lines: [err instanceof Error ? err.message : String(err)], affected: 0 };
   }

package/src/hooks/session-pause.ts

@@ -27,6 +27,7 @@ import { createHash } from "node:crypto";
 import { join, resolve } from "node:path";
 import { writeJsonAtomically } from "../../lib/atomic-write";
 import { getAllHookActivityEntries } from "./hook-activity-store";
+import { sessionPauseDir } from "./fp-home";
 
 const SCHEMA_VERSION = 1;
 
@@ -44,6 +45,19 @@ export interface ActivePause {
   sessionId: string;
   /** Epoch ms. */
   pausedAt: number;
+  /**
+   * Epoch ms of the FIRST pause in this unbroken run, which the ceiling is
+   * measured from.
+   *
+   * `pausedAt` moves to now on every renewal, so a ceiling measured from it is
+   * not a ceiling at all: `--pause 8h` every seven hours suspends enforcement
+   * indefinitely, one legal command at a time, and each individual pause passes
+   * every check. This field is what makes 8h mean 8h. Carried forward by
+   * `writePause` while a pause is still live, and reset once one has expired —
+   * the limit is on how long enforcement can stay off in one stretch, not a
+   * daily quota.
+   */
+  firstPausedAt: number;
   /** Epoch ms. Always finite — there is no unbounded pause. */
   expiresAt: number;
   /** Free-form provenance, e.g. "cli". Recorded so the activity log can say who. */
@@ -59,7 +73,7 @@ interface StoredPause extends ActivePause {
 export function pauseStateDir(): string {
   const override = process.env.FAILPROOFAI_STATE_DIR;
   if (override) return resolve(override, "sessions");
-  return join(homedir(), ".failproofai", "state", "sessions");
+  return sessionPauseDir();
 }
 
 /**
@@ -119,11 +133,22 @@ function parseStored(raw: unknown): StoredPause | null {
   if (p.schemaVersion !== SCHEMA_VERSION) return null;
   if (typeof p.sessionId !== "string" || p.sessionId.length === 0) return null;
   if (!Number.isFinite(p.pausedAt) || !Number.isFinite(p.expiresAt)) return null;
+  const pausedAt = p.pausedAt as number;
+  // A file written before this field existed measures its ceiling from the
+  // only start it recorded. Same meaning for a pause that was never renewed.
+  const firstPausedAt = Number.isFinite(p.firstPausedAt) ? (p.firstPausedAt as number) : pausedAt;
   return {
     schemaVersion: SCHEMA_VERSION,
     sessionId: p.sessionId,
-    pausedAt: p.pausedAt as number,
-    expiresAt: p.expiresAt as number,
+    pausedAt,
+    firstPausedAt,
+    // Clamped at READ time, not only at write. The ceiling has to hold against
+    // a file this process did not write: `~/.failproofai/state/sessions/` is
+    // owner-writable by design, and an `expiresAt` a year out would otherwise
+    // be honoured on every subsequent tool call forever. Enforcing it here
+    // means the bound is a property of the pause, not of the path that created
+    // it.
+    expiresAt: Math.min(p.expiresAt as number, firstPausedAt + PAUSE_CEILING_MS),
     setBy: typeof p.setBy === "string" ? p.setBy : "unknown",
     ...(typeof p.cwd === "string" ? { cwd: p.cwd } : {}),
   };
@@ -159,10 +184,17 @@ export function writePause(opts: {
   now?: number;
 }): ActivePause {
   const now = opts.now ?? Date.now();
+  // Carry the run's original start forward while a pause is still live, so a
+  // renewal extends the same stretch rather than starting a fresh ceiling.
+  const existing = readActivePause(opts.sessionId, now);
+  const firstPausedAt = existing?.firstPausedAt ?? now;
   const pause: ActivePause = {
     sessionId: opts.sessionId,
     pausedAt: now,
-    expiresAt: now + opts.durationMs,
+    firstPausedAt,
+    // The requested duration, but never past the ceiling measured from the
+    // start of the run. A renewal can shorten a pause; it cannot outrun 8h.
+    expiresAt: Math.min(now + opts.durationMs, firstPausedAt + PAUSE_CEILING_MS),
     setBy: opts.setBy ?? "cli",
     ...(opts.cwd ? { cwd: opts.cwd } : {}),
   };