failproofai 1.0.10 → 1.0.11-beta.1

package/src/hooks/daemon-service.ts

@@ -1617,14 +1617,24 @@ export async function refreshDaemonToCliVersion(
 
   const result = await install();
   if (!result.installed) {
+    // Root is the usual reason, and the install's own `reason` for it is written
+    // for the wizard and the log: it says to re-run `failproofai config` and
+    // carries a full unit file to paste. From `update` the answer is shorter,
+    // and names this command: get sudo, then run it again. Never "run the CLI
+    // under sudo" — that would configure root's account instead of this one.
+    const needsRoot = /root privileges are required/.test(result.reason ?? "");
     return {
       ok: false,
-      lines: [
-        `failproofaid ${version} could not be installed: ${result.reason ?? "unknown reason"}`,
-        `The previous daemon is untouched. On a machine configured to require it,`,
-        `enforcement continues; collection and cloud policy may be stale until this`,
-        `succeeds. \`${daemonStatusCommand() ?? "systemctl status"}\` will say more.`,
-      ],
+      lines: needsRoot
+        ? [
+            `✕ failproofaid ${version} was not installed: root privileges are required. The previous daemon is untouched.`,
+            "  Run `sudo -v` and then `failproofai update` again.",
+          ]
+        : [
+            `✕ failproofaid ${version} could not be installed: ${(result.reason ?? "unknown reason").replace(/\.$/, "")}. ` +
+              "The previous daemon is untouched.",
+            `  See why with \`${daemonStatusCommand() ?? "systemctl status"}\`.`,
+          ],
     };
   }
   // RECORD THE VERSION, or the refresh is invisible to everything that asks.

package/src/hooks/did-you-mean.ts

@@ -0,0 +1,185 @@
+/**
+ * "Did you mean …?" for a command or a top-level flag the CLI does not know.
+ *
+ * Two sources, asked in this order:
+ *
+ *   1. Words people type that are not commands here, each mapped to the real
+ *      command that does what they meant: `status` is `config --status`, not
+ *      `flush`. The nearest-spelling guess used to answer `status` with
+ *      `flush` and `install` with `uninstall` — the opposite of the request.
+ *   2. The nearest real subcommand by spelling, for a typo of one. A word
+ *      that is a candidate with `un`/`de`/`dis` added or removed is never its
+ *      match: `unpause` is two edits from `pause` and means the opposite.
+ *
+ * Both are matched within a distance cut-off, so a typo of a table word still
+ * finds it (`statsu` → `config --status`), and a word that is close to nothing
+ * gets NO suggestion. A guess at something unrelated sends a person to the
+ * wrong command with confidence; saying nothing sends them to `help`.
+ *
+ * Every suggestion is a whole command, runnable exactly as printed.
+ */
+
+/** Words that are not commands here, and what to run instead. Lower case. */
+const WORD_INTENTS: Readonly<Record<string, string>> = {
+  status: "failproofai config --status",
+  doctor: "failproofai config --status",
+  whoami: "failproofai config --status",
+  pause: "failproofai config --pause",
+  resume: "failproofai config --resume",
+  // Docker's word for it. Two edits from `pause`, which is the opposite.
+  unpause: "failproofai config --resume",
+  login: "failproofai config",
+  signin: "failproofai config",
+  "sign-in": "failproofai config",
+  connect: "failproofai config",
+  logout: "failproofai config --disconnect",
+  disconnect: "failproofai config --disconnect",
+  // `setup`, `configure`, `policy` and `pack` already RUN as their command;
+  // they are here so a typo of one finds it too.
+  setup: "failproofai config",
+  configure: "failproofai config",
+  policy: "failproofai policies",
+  pack: "failproofai policies",
+  install: "failproofai policies --install",
+  enable: "failproofai policies add",
+  disable: "failproofai policies remove",
+  add: "failproofai policies add",
+  list: "failproofai policies",
+  ls: "failproofai policies",
+  upgrade: "failproofai update",
+  version: "failproofai --version",
+  hook: "failproofai help hook",
+  hooks: "failproofai help hook",
+  dashboard: "failproofai",
+  start: "failproofai",
+  open: "failproofai",
+  // `auth login` was the audit reminder's sign-in until it was removed; that
+  // sign-in lives with the audit now.
+  auth: "failproofai audit",
+};
+
+/** Top-level flags that belong to a command, and that command. */
+const FLAG_INTENTS: Readonly<Record<string, string>> = {
+  "--status": "failproofai config --status",
+  "--pause": "failproofai config --pause",
+  "--resume": "failproofai config --resume",
+  "--unpause": "failproofai config --resume",
+  "--token": "failproofai config",
+  "--connect": "failproofai config",
+  "--disconnect": "failproofai config --disconnect",
+  "--install": "failproofai policies --install",
+  "-i": "failproofai policies --install",
+  // Two edits from `--install`: without these the nearest spelling answers a
+  // request to take hooks out with the command that puts them in.
+  "--uninstall": "failproofai policies --uninstall",
+  "-u": "failproofai policies --uninstall",
+  "--list": "failproofai policies",
+  "--all": "failproofai policies --all",
+};
+
+/** The flags that are top-level in their own right, and are typo targets. */
+const TOP_LEVEL_FLAGS = ["--version", "--help"] as const;
+
+/**
+ * Edit distance with a swap of two neighbouring letters counted as ONE edit
+ * (optimal string alignment) — `cofnig` is one slip from `config`, not two.
+ */
+function typoDistance(a: string, b: string): number {
+  const d: number[][] = Array.from({ length: a.length + 1 }, (_, i) =>
+    Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)),
+  );
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+      }
+    }
+  }
+  return d[a.length][b.length];
+}
+
+/**
+ * How far a typo may be from what it meant. Two letters or fewer must match
+ * exactly — almost anything is one edit from `ls`. Up to four letters, one
+ * edit; longer, two. `install` is two edits from `uninstall`, which is why the
+ * word table is asked first.
+ */
+function typoReach(word: string): number {
+  if (word.length <= 2) return 0;
+  return word.length <= 4 ? 1 : 2;
+}
+
+/** Prefixes that turn a word into its opposite: `unpause`, `deinstall`, `disable`. */
+const NEGATING_PREFIXES = ["un", "de", "dis"] as const;
+
+/**
+ * Whether `a` is `b` with a negating prefix, either way round. Such a pair is
+ * a short edit apart and means the opposite, so it is never a typo match.
+ */
+function isNegationOf(a: string, b: string): boolean {
+  return NEGATING_PREFIXES.some((prefix) => a === prefix + b || b === prefix + a);
+}
+
+/**
+ * What `word` most likely meant among `candidates` (spelling → command), or
+ * null. A word of three letters or more that starts exactly one command's
+ * spelling is that command — `back` is `backfill`, though `pack` is nearer by
+ * spelling. Otherwise the closest spelling within reach, the earliest one
+ * winning a tie. A word that is a candidate with a negating prefix added or
+ * taken away is never matched to it.
+ */
+function nearestOf(word: string, candidates: ReadonlyArray<readonly [string, string]>): string | null {
+  if (word.length >= 3) {
+    const prefixed = new Set(candidates.filter(([spelling]) => spelling.startsWith(word)).map(([, to]) => to));
+    if (prefixed.size === 1) return [...prefixed][0];
+  }
+  const reach = typoReach(word);
+  let best: { to: string; distance: number } | null = null;
+  for (const [spelling, to] of candidates) {
+    if (isNegationOf(word, spelling)) continue;
+    const distance = typoDistance(word, spelling);
+    if (distance <= reach && (best === null || distance < best.distance)) best = { to, distance };
+  }
+  return best?.to ?? null;
+}
+
+/**
+ * The command to suggest for an unknown word, or null when nothing is close.
+ * `subcommands` is the CLI's own list, passed in so there is one copy of it.
+ */
+export function suggestCommand(word: string, subcommands: readonly string[]): string | null {
+  const typed = word.trim().toLowerCase();
+  if (!typed) return null;
+  const intent = WORD_INTENTS[typed];
+  if (intent) return intent;
+  return nearestOf(typed, [
+    ...subcommands.map((name) => [name, `failproofai ${name}`] as const),
+    ...Object.entries(WORD_INTENTS),
+  ]);
+}
+
+/** The one of `names` that `word` is a typo of, or null when none is close. */
+export function nearestName(word: string, names: readonly string[]): string | null {
+  const typed = word.trim().toLowerCase();
+  if (!typed) return null;
+  return nearestOf(typed, names.map((name) => [name, name] as const));
+}
+
+/** The command to suggest for an unknown top-level flag, or null when nothing is close. */
+export function suggestFlag(flag: string): string | null {
+  const typed = flag.trim().toLowerCase();
+  // `-V` and `-H` reach here only because of their case.
+  if (typed === "-v") return "failproofai --version";
+  if (typed === "-h") return "failproofai --help";
+  const intent = FLAG_INTENTS[typed];
+  if (intent) return intent;
+  // Compared without the dashes, so `-verison` and `--verison` read alike.
+  const bare = (spelling: string) => spelling.replace(/^-+/, "");
+  if (!bare(typed)) return null;
+  return nearestOf(bare(typed), [
+    ...TOP_LEVEL_FLAGS.map((name) => [bare(name), `failproofai ${name}`] as const),
+    ...Object.entries(FLAG_INTENTS).map(([spelling, to]) => [bare(spelling), to] as const),
+  ]);
+}

package/src/hooks/flush-cli.ts

@@ -19,7 +19,7 @@
  * before returning success. A CLI that prints "requested" while the daemon is
  * stopped has told the user the opposite of what happened.
  */
-import { existsSync, mkdirSync, writeFileSync, readdirSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { customAgentsEventsDir, failedDir, failproofaiHome, spoolDir } from "./fp-home";
 import { readConfig } from "./fp-config";
@@ -86,15 +86,39 @@ function parkedLine(n: number, home?: string): string {
 
 /** Batches awaiting delivery. `.tmp` files are half-written and not counted. */
 export function pendingBatches(home?: string): number {
-  let n = 0;
+  return spoolBacklog(home).count;
+}
+
+/**
+ * {@link pendingBatches}, plus how long the oldest of them has waited.
+ *
+ * The age is what tells a backlog that is draining from one that is stuck: the
+ * collector sweeps a batch only once it is two minutes old, so a few young
+ * batches are normal, while one that has sat for a quarter of an hour has not
+ * been delivered by several passes. `config --status` reads it for that.
+ */
+export function spoolBacklog(home?: string, now: number = Date.now()): { count: number; oldestAgeMs?: number } {
+  let count = 0;
+  let oldest: number | undefined;
   for (const dir of spoolDirs(home)) {
+    let names: string[];
     try {
-      n += readdirSync(dir).filter((f) => f.endsWith(".jsonl")).length;
+      names = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
     } catch {
       // A directory that vanished mid-scan is one the collector just drained.
+      continue;
+    }
+    count += names.length;
+    for (const name of names) {
+      try {
+        const mtime = statSync(join(dir, name)).mtimeMs;
+        if (oldest === undefined || mtime < oldest) oldest = mtime;
+      } catch {
+        // Delivered between the listing and the stat.
+      }
     }
   }
-  return n;
+  return oldest === undefined ? { count } : { count, oldestAgeMs: Math.max(0, now - oldest) };
 }
 
 export async function runFlushCommand(opts: FlushOptions = {}): Promise<FlushResult> {
@@ -198,10 +222,12 @@ export async function runFlushCommand(opts: FlushOptions = {}): Promise<FlushRes
 
   // A timeout is not necessarily a failure — a large backlog legitimately takes
   // longer than the budget — so say what is still outstanding rather than
-  // calling it broken.
+  // calling it broken. Marked ▲ on its own line: the report opens on the
+  // "Requested delivery." line, and an unmarked failed report puts its ✕ on
+  // whichever line comes first.
   lines.push(
-    `Still ${pending} batch${pending === 1 ? "" : "es"} spooled after ${timeoutSecs}s.`,
-    "Delivery continues in the background; re-run with a longer --timeout to keep watching.",
+    `▲ Still ${pending} batch${pending === 1 ? "" : "es"} spooled after ${timeoutSecs}s.`,
+    "  Delivery continues in the background; re-run with a longer --timeout to keep watching.",
   );
   return { exitCode: 1, pending, lines };
 }

package/src/hooks/fp-config.ts

@@ -281,6 +281,14 @@ export interface FpConfig {
   };
   collector: {
     sessions: boolean;
+    /**
+     * Per-agent transcript transport overrides. Orthogonal to `agents.selected`,
+     * which gates collection: a traced agent using OTEL keeps its hooks, but
+     * must not also send transcripts. Retain the original OTEL key layout so
+     * upgrades and recovery snapshots can restore the previous preference.
+     */
+    agents?: Record<string, { sessions?: boolean }>;
+    otlp?: { enabled: boolean; port?: number };
     hooks: boolean;
     hooksVerbosity: "all" | "decisions" | "off";
     redact: "minimal" | "off";
@@ -368,6 +376,23 @@ export interface FpConfig {
     /** Days between scheduled runs. Wall clock, so it survives suspend. */
     intervalDays: number;
   };
+  /**
+   * Which agents failproofai traces: the remembered answer to `failproofai
+   * config`'s "which agents should failproofai trace?".
+   *
+   * `selected` drives every per-agent thing at once — which CLIs get hooks,
+   * which harnesses the daemon's collector reads, and which `backfill` re-sends.
+   * `seen` is every agent that was detected at the last setup, which is how a
+   * newly installed agent is recognised and offered as "new on this machine".
+   * Ids are the integration ids (`claude`, `codex`, …).
+   *
+   * ABSENT means today's behaviour, everything, and that is what every machine
+   * set up before this existed has. So `writeConfig` emits nothing in that case,
+   * and the daemon — which reads `agents.selected` from this same file — keeps
+   * collecting every harness. The direction matters: an unreadable or missing
+   * selection must never quietly switch tracing OFF.
+   */
+  agents?: { selected: string[]; seen: string[] };
 }
 
 /**
@@ -443,6 +468,45 @@ function readSources(raw: unknown): FpConfig["collector"]["sources"] {
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
+function readAgentSessions(raw: unknown): FpConfig["collector"]["agents"] {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const agents = Object.fromEntries(Object.entries(raw).flatMap(([agent, settings]) => {
+    if (!settings || typeof settings !== "object" || Array.isArray(settings)) return [];
+    const sessions = (settings as Record<string, unknown>).sessions;
+    return typeof sessions === "boolean" ? [[agent, { sessions }]] : [];
+  }));
+  return Object.keys(agents).length ? agents : undefined;
+}
+
+function readOtlpSettings(raw: unknown): FpConfig["collector"]["otlp"] {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const settings = raw as Record<string, unknown>;
+  return {
+    enabled: settings.enabled === true,
+    ...(typeof settings.port === "number" && Number.isInteger(settings.port) ? { port: settings.port } : {}),
+  };
+}
+
+/**
+ * `agents` → the in-memory shape. Kept as written (strings only, de-duplicated
+ * in order): the daemon owns the list of real agent ids and warns about an
+ * unknown one, so dropping it here would hide that warning behind a value the
+ * CLI had already rewritten — the same reasoning as {@link readSources}.
+ *
+ * `undefined` unless `selected` is an array, because absent means everything
+ * and a garbage value must fail in that direction too.
+ */
+function readAgents(raw: unknown): FpConfig["agents"] {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const ids = (v: unknown): string[] =>
+    Array.isArray(v)
+      ? [...new Set(v.filter((e): e is string => typeof e === "string" && e.trim() !== ""))]
+      : [];
+  const table = raw as Record<string, unknown>;
+  if (!Array.isArray(table.selected)) return undefined;
+  return { selected: ids(table.selected), seen: ids(table.seen) };
+}
+
 /**
  * {@link readConfig}, plus the raw object it was projected from.
  *
@@ -532,6 +596,8 @@ export function projectConfig(parsed: Record<string, unknown>): FpConfig {
           typeof collector.environment === "string" ? collector.environment : "local",
         machineId: typeof collector.machine_id === "string" ? collector.machine_id : undefined,
         sources: readSources(collector.sources),
+        agents: readAgentSessions(collector.agents),
+        otlp: readOtlpSettings(collector.otlp),
       },
       // Only an explicit `false` switches it off. Absent, or any other value,
       // reads as on — the shipped default, and what a config with no
@@ -552,6 +618,7 @@ export function projectConfig(parsed: Record<string, unknown>): FpConfig {
             ? audit.reports_consented_at
             : undefined,
       },
+      agents: readAgents(parsed.agents),
       // Same shape as `audit.auto` above and for the same reason: only an
       // explicit `true` opts in. Anything else — absent, misspelled, `"yes"` —
       // reads as off, because the failure direction is a machine that starts
@@ -594,10 +661,15 @@ const OWNED_CONFIG_KEYS: readonly (readonly string[])[] = [
   ["collector", "environment"],
   ["collector", "machine_id"],
   ["collector", "sources", "*", "extra_paths"],
+  ["collector", "agents", "*", "sessions"],
+  ["collector", "otlp", "enabled"],
+  ["collector", "otlp", "port"],
   ["telemetry", "enabled"],
   ["audit", "auto"],
   ["audit", "interval_days"],
   ["audit", "reports_consented_at"],
+  ["agents", "selected"],
+  ["agents", "seen"],
 ];
 
 const isPlainObject = (v: unknown): v is Record<string, unknown> =>
@@ -669,6 +741,8 @@ export function writeConfig(config: FpConfig, raw?: Record<string, unknown>): vo
       // Omitted when unset rather than written null: the Rust side treats an
       // absent machine_id as "derive one", and an explicit null is not that.
       ...(c.machineId ? { machine_id: c.machineId } : {}),
+      ...(c.agents ? { agents: c.agents } : {}),
+      ...(c.otlp ? { otlp: c.otlp } : {}),
       // Extra capture paths per harness. Emitted ONLY when non-empty, so a
       // machine that never configured one gets a file byte-identical to what
       // this function produced before the field existed — the same reasoning as
@@ -708,6 +782,12 @@ export function writeConfig(config: FpConfig, raw?: Record<string, unknown>): vo
         ? {}
         : { reports_consented_at: config.audit.reportsConsentedAt }),
     },
+    // Written ONLY when a selection exists — absent means "every agent", and a
+    // machine that never chose keeps a file byte-identical to what this
+    // function wrote before the field existed.
+    ...(config.agents
+      ? { agents: { selected: config.agents.selected, seen: config.agents.seen } }
+      : {}),
   };
   // Start from the previous bytes, strip the keys this build owns — so an
   // omission above really removes — then lay the projection on top. What is left
@@ -726,6 +806,8 @@ export function updateConfig(patch: {
   collector?: Partial<FpConfig["collector"]>;
   telemetry?: Partial<FpConfig["telemetry"]>;
   audit?: Partial<FpConfig["audit"]>;
+  /** Replace the agent selection; `null` removes it (back to "every agent"). */
+  agents?: FpConfig["agents"] | null;
 }): FpConfig {
   // `readConfigRaw`, not `readConfig` — this is the function EVERY mutation path
   // goes through (the wizard, `harness add-path`, `healDaemonFlag`, the telemetry
@@ -738,11 +820,25 @@ export function updateConfig(patch: {
     collector: { ...current.collector, ...patch.collector },
     telemetry: { ...current.telemetry, ...patch.telemetry },
     audit: { ...current.audit, ...patch.audit },
+    // Carried forward when the patch does not name it. Every other mutation
+    // path goes through here — the wizard's own connect step among them — and
+    // a selection dropped by an unrelated write would silently turn tracing
+    // back on for every agent the user switched off.
+    agents: patch.agents === undefined ? current.agents : (patch.agents ?? undefined),
   };
   writeConfig(next, raw);
   return next;
 }
 
+/**
+ * Whether failproofai traces this agent: hooked, collected and backfilled.
+ * True for every agent when no selection has been saved, which is today's
+ * behaviour and what every machine set up before the selection existed has.
+ */
+export function isAgentTraced(id: string, config: FpConfig = readConfig()): boolean {
+  return !config.agents || config.agents.selected.includes(id);
+}
+
 // ── credentials.json ─────────────────────────────────────────────────────────
 
 export interface FpCredentials {

package/src/hooks/fp-home.ts

@@ -139,6 +139,14 @@ export const versionFile = (home?: string) => atHome(home, "VERSION");
 /** Non-secret configuration. World-readable by design; never holds a token. */
 export const configFile = (home?: string) => atHome(home, "config.json");
 
+export const otelAgentStateDir = (home?: string) => atHome(home, "state", "otel-agents");
+export const otelAgentStateFile = (agent: string) => {
+  if (!["claude", "codex", "gemini", "copilot"].includes(agent)) throw new Error("Unknown OTEL agent.");
+  return resolve(otelAgentStateDir(), `${agent}.json`);
+};
+export const otlpSpoolDir = (home?: string) => atHome(home, "state", "spool-otlp");
+export const otlpHealthFile = (home?: string) => atHome(home, "state", "otlp-health.json");
+
 /**
  * Every credential, owner-only.
  *
@@ -576,6 +584,7 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   // the collector preferences, `[audit] auto`, the telemetry opt-out, and
   // `collector.sources.*.extra_paths` — the entire output of `harness add-path`.
   { path: configFile, class: "user-typed" },
+  { path: otelAgentStateDir, class: "user-typed" },
   // The builtin enable/disable set and per-policy params. `resetHome` used to
   // clear this and carry eight named keys back over; it is simply kept now.
   { path: globalPolicyConfigFile, class: "user-typed" },
@@ -602,6 +611,7 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   // these is PERMANENT and not merely slow is `cursorsDir` below: the watermark
   // has already advanced past them, so nothing will ever read that range again.
   { path: spoolDir, class: "undelivered" },
+  { path: otlpSpoolDir, class: "undelivered" },
   { path: failedDir, class: "undelivered" },
   // The SDK spool (`events/` + `failed/`), same argument.
   { path: customAgentsDir, class: "undelivered" },
@@ -657,6 +667,7 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   { path: auditCacheDir, class: "derived" },
   { path: auditScheduleFile, class: "derived" },
   { path: collectorHealthFile, class: "derived" },
+  { path: otlpHealthFile, class: "derived" },
   { path: codexSessionPathsFile, class: "derived" },
   { path: shimsDir, class: "derived" },
   { path: sessionPauseDir, class: "derived" },