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

package/src/hooks/handler.ts

@@ -41,6 +41,9 @@ import { resolveTranscriptPath } from "./resolve-transcript-path";
 import { getInstanceId } from "../../lib/telemetry-id";
 import { hookLogInfo, hookLogWarn } from "./hook-logger";
 import { readStdinPayload } from "./read-stdin";
+import { readActiveCloudManagedPolicies, type CloudManagedPolicyArtifact } from "./cloud-managed-policies";
+import { readActivePause, type ActivePause } from "./session-pause";
+import { layoutWarningForHook } from "./fp-reset";
 
 /**
  * Canonicalize an event name to PascalCase. Codex sends snake_case event names
@@ -134,6 +137,37 @@ export interface EvaluateHookEventOptions {
   fallbackCwd?: string;
 }
 
+/**
+ * Runs an observe-mode policy under the same timeout and error handling as an
+ * enforcing one, so what gets measured is what would actually have happened —
+ * including a policy that times out, which in enforce mode is an allow and must
+ * be recorded as one rather than as a would-deny.
+ */
+async function runObserved(
+  hook: CustomHook,
+  ctx: Parameters<CustomHook["fn"]>[0],
+  hookName: string,
+  eventType: string,
+  cli: IntegrationType,
+): Promise<PolicyResult> {
+  try {
+    return await Promise.race([
+      hook.fn(ctx),
+      new Promise<PolicyResult>((_, reject) => setTimeout(() => reject(new Error("timeout")), 10_000)),
+    ]);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    void trackHookEvent(getInstanceId(), "custom_hook_error", {
+      hook_name: hookName,
+      error_type: msg === "timeout" ? "timeout" : "exception",
+      event_type: eventType,
+      cli,
+      is_observe_mode: true,
+    });
+    return { decision: "allow" };
+  }
+}
+
 /**
  * The core hook-evaluation logic, decoupled from process stdin/stdout so it
  * can be called repeatedly inside a long-lived process (the daemon's warm
@@ -149,6 +183,13 @@ export async function evaluateHookEvent(
   opts?: EvaluateHookEventOptions,
 ): Promise<HookEventOutcome> {
   const startTime = performance.now();
+  // A home from another layout resolves to no global config, so every builtin
+  // silently stops firing — the machine looks protected and is not. Say so on
+  // every call rather than deleting anything (a hook is unattended) or denying
+  // (a blanket deny takes UserPromptSubmit with it and locks the user out of
+  // their agent entirely — demonstrated on a real machine during this work).
+  const layoutWarning = layoutWarningForHook();
+  if (layoutWarning) hookLogWarn(layoutWarning);
   try {
     let parsed: Record<string, unknown> = {};
     if (stdinPayload) {
@@ -209,6 +250,20 @@ export async function evaluateHookEvent(
     let config: HooksConfig;
     let customHooksList: CustomHook[] = [];
     let conventionHookNames = new Set<string>();
+    let activePause: ActivePause | null = null;
+    /** Registered policy name → where it came from. See the set() below. */
+    const policyAttribution = new Map<
+      string,
+      { source: "custom" | "convention" | "cloud"; cloudPolicyId?: string; cloudVersion?: number }
+    >();
+    let cloudDeployment: number | undefined;
+    /** What observe-mode policies WOULD have done, had they been enforcing. */
+    const observedResults: Array<{
+      policyId: string;
+      version: number;
+      decision: "deny" | "instruct";
+      reason: string | null;
+    }> = [];
 
     if (opts?.forceDecision) {
       // Fail-closed: no config/custom-hook loading at all — a daemon that
@@ -228,25 +283,113 @@ export async function evaluateHookEvent(
       // Load enabled policies (merge across project/local/global scopes)
       config = readMergedHooksConfig(session.cwd);
       clearPolicies();
-      registerBuiltinPolicies(config.enabledPolicies);
+
+      // A session pause suspends LOCAL policy only, for a bounded time. Cloud
+      // assignments are exempt below for the same reason `disabledCustomPolicies`
+      // already exempts them: a locally-issued command that could switch off a
+      // centrally assigned policy would make cloud enforcement decorative.
+      activePause = readActivePause(session.sessionId);
+      registerBuiltinPolicies(activePause ? [] : config.enabledPolicies);
+
+      // Cloud-managed policies are daemon-reconciled artifacts, but they use
+      // the same public JS policy API as local custom policies. Verify and add
+      // only the paths referenced by the atomically active deployment.
+      //
+      // Wrapped, like `readConfigAt` and `readActivePause` above it. This call
+      // has fourteen throw sites — a malformed manifest, an unsafe id, an
+      // integrity mismatch, an unknown effect — and it sat bare inside a `try`
+      // whose only handler is a `finally`, so any of them aborted the entire
+      // evaluation. What that cost depended on where the hook ran, and none of
+      // the outcomes were the intended one: on a daemon machine the client
+      // fail-closed denies every tool call, and off the daemon path the throw
+      // reaches `bin/failproofai.mjs`'s outer catch, which exits 2 with nothing
+      // on stdout — a deny on Claude and Factory, but a logged warning followed
+      // by an ALLOW on Copilot, Cursor, Goose, Pi and Hermes, which read a
+      // decision off stdout and ignore the exit code. One corrupt byte was
+      // either a permanent machine-wide lockout or silent non-enforcement,
+      // depending on the CLI.
+      //
+      // Failing open here degrades ONE layer: builtins and local custom
+      // policies were already registered above and keep enforcing. That is the
+      // same trade `2ad735e5` made on the Rust side, and it is strictly better
+      // than the status quo, which already failed open on five of the twelve —
+      // just accidentally, and without saying so.
+      let cloudManagedPolicies: CloudManagedPolicyArtifact[] = [];
+      try {
+        cloudManagedPolicies = readActiveCloudManagedPolicies();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        hookLogWarn(
+          `[failproofai] cloud-managed policies could NOT be loaded and are not being enforced: ${msg}. ` +
+            `Local policies are unaffected. Run \`failproofai config --status\` to check this machine's enrolment.`,
+        );
+        void trackHookEvent(getInstanceId(), "cloud_managed_load_error", {
+          event_type: eventType,
+          cli,
+        });
+      }
+      // Recorded on every row once a machine is managed, whether or not a cloud
+      // policy decided this event: "what was deployed here at the time" is a
+      // separate question from "what decided", and only the former can tell a
+      // rollout that changed nothing from one that never reached the machine.
+      cloudDeployment = cloudManagedPolicies[0]?.deployment;
+      const configuredCustomPaths = config.customPoliciesPaths ?? config.customPoliciesPath;
+      const allExplicitPaths =
+        cloudManagedPolicies.length === 0
+          ? configuredCustomPaths
+          : [
+              ...(typeof configuredCustomPaths === "string" ? [configuredCustomPaths] : configuredCustomPaths ?? []),
+              ...cloudManagedPolicies.map((policy) => policy.path),
+            ];
 
       // Load and register custom hooks (layer 2, after builtins)
-      const loadResult = await loadAllCustomHooks(config.customPoliciesPaths ?? config.customPoliciesPath, {
+      const loadResult = await loadAllCustomHooks(allExplicitPaths, {
         sessionCwd: session.cwd,
         customPoliciesEnabled: config.customPoliciesEnabled,
+        ...(cloudManagedPolicies.length > 0 ? { cloudManagedPolicies } : {}),
       });
       customHooksList = loadResult.hooks;
       const disabledCustomPolicies = new Set(config.disabledCustomPolicies ?? []);
       conventionHookNames = new Set(loadResult.conventionSources.flatMap((s) => s.hookNames));
 
       for (const hook of customHooksList) {
-        const policyId = (hook as CustomHook & { __policyId?: string }).__policyId;
-        if (policyId && disabledCustomPolicies.has(policyId)) continue;
+        const taggedHook = hook as CustomHook & {
+          __policyId?: string;
+          __cloudManaged?: CloudManagedPolicyArtifact;
+        };
+        const policyId = taggedHook.__policyId;
+        const cloudManaged = taggedHook.__cloudManaged;
+        // Local config cannot disable a centrally assigned policy merely by
+        // copying its generated ID into disabledCustomPolicies.
+        if (!cloudManaged && policyId && disabledCustomPolicies.has(policyId)) continue;
+        // Same rule for a session pause — it suspends local policy, never cloud.
+        if (!cloudManaged && activePause) continue;
         const hookName = hook.name;
         const conventionScope = (hook as CustomHook & { __conventionScope?: string }).__conventionScope;
         const isConvention = !!conventionScope;
-        const prefix = isConvention ? `.failproofai-${conventionScope}` : "custom";
+        const prefix = cloudManaged
+          ? `cloud/${cloudManaged.id}@${cloudManaged.version}`
+          : isConvention
+            ? `.failproofai-${conventionScope}`
+            : "custom";
+        // Observe mode: run it for real, record what it decided, then hand back
+        // an allow. Evaluating and discarding is the whole point — a rollout is
+        // measured against real traffic before it can break anyone's work, and
+        // a policy that did not actually run would measure nothing.
+        const observeOnly = cloudManaged?.effect === "observe";
         const fn: PolicyFunction = async (ctx): Promise<PolicyResult> => {
+          if (observeOnly) {
+            const shadow = await runObserved(hook, ctx, hookName, eventType, cli);
+            if (shadow.decision !== "allow") {
+              observedResults.push({
+                policyId: cloudManaged!.id,
+                version: cloudManaged!.version,
+                decision: shadow.decision,
+                reason: shadow.reason ?? null,
+              });
+            }
+            return { decision: "allow" };
+          }
           try {
             const result = await Promise.race([
               hook.fn(ctx),
@@ -268,8 +411,18 @@ export async function evaluateHookEvent(
             return { decision: "allow" };
           }
         };
+        const registeredName = `${prefix}/${hookName}`;
+        // Record where this policy came from as structured data, keyed by the
+        // exact name the evaluator will report back. The display name already
+        // encodes it ("cloud/org-guard@7/…"), but only as a string — so the one
+        // question cloud attribution has to answer, "which rollout produced
+        // this decision", could only be answered by re-parsing our own label.
+        policyAttribution.set(registeredName, {
+          source: cloudManaged ? "cloud" : isConvention ? "convention" : "custom",
+          ...(cloudManaged ? { cloudPolicyId: cloudManaged.id, cloudVersion: cloudManaged.version } : {}),
+        });
         registerPolicy(
-          `${prefix}/${hookName}`,
+          registeredName,
           hook.description ?? "",
           fn,
           hook.match ?? {},
@@ -335,6 +488,32 @@ export async function evaluateHookEvent(
       cwd: session.cwd,
       permissionMode: session.permissionMode,
       hookEventName: session.hookEventName,
+      // Attribution. A builtin is anything registered that is not in the map,
+      // so its absence is meaningful rather than missing — but only when a
+      // policy actually decided; a plain allow names nobody.
+      ...(result.policyName
+        ? (() => {
+            const attribution = policyAttribution.get(result.policyName);
+            return {
+              policySource: attribution?.source ?? ("builtin" as const),
+              ...(attribution?.cloudPolicyId ? { cloudPolicyId: attribution.cloudPolicyId } : {}),
+              ...(attribution?.cloudVersion !== undefined
+                ? { cloudVersion: attribution.cloudVersion }
+                : {}),
+            };
+          })()
+        : {}),
+      ...(cloudDeployment !== undefined ? { cloudDeployment } : {}),
+      // The point of observe mode is this record. Without it the rollout is
+      // unmeasurable and the row is indistinguishable from one where the policy
+      // never matched at all.
+      ...(observedResults.length > 0 ? { observed: observedResults } : {}),
+      // Without these, a row logged during a pause is indistinguishable from
+      // one where every policy ran and allowed — the log would assert a clean
+      // window over exactly the window that was not enforced.
+      ...(activePause
+        ? { pausedBy: activePause.setBy, pauseExpiresAt: activePause.expiresAt }
+        : {}),
     };
     try {
       persistHookActivity(activityEntry);

package/src/hooks/harness-cli.ts

@@ -0,0 +1,386 @@
+/**
+ * `failproofai harness` — manage extra capture paths per harness.
+ *
+ * Each supported agent CLI has one location its own installer put it in, and
+ * the collector watches that. This command adds others: a second profile, a
+ * bind-mounted team share, a container's home mapped in beside the host's, an
+ * agent an operator relocated. Those hold real sessions and nothing collected
+ * them.
+ *
+ * # This file edits config; the daemon decides what the config means
+ *
+ * Entries are stored as written. The grammar (`label=path`, folder-name
+ * fallback), `~` expansion, overlap rejection and the `<label>-<agentId>`
+ * namespacing all live in `crates/fpai-collect/src/extra_paths.rs`, and the
+ * daemon reports what it rejected at startup. Re-implementing any of that here
+ * would give one product two parsers, and the way that fails is the CLI
+ * accepting a path the daemon then silently drops — which is indistinguishable
+ * from the feature working.
+ *
+ * The one thing validated here is the HARNESS NAME, because that failure has no
+ * other detector: `collector.sources.claud` is valid JSON, parses cleanly,
+ * captures nothing, and is mentioned nowhere else a user would look.
+ *
+ * # No restart, and no sudo
+ *
+ * This writes one file in the user's own home and nothing else. The daemon's
+ * collector manager re-reads `config.json` on an interval and cycles the
+ * collector whenever the resolved `CollectorConfig` changes — the same path
+ * that already picks up `--connect`, a stream being switched off, and a
+ * verbosity change. `extra_paths` rides it for free by living inside
+ * `Settings`, which is part of the value being compared. That is load-bearing
+ * rather than incidental, and `collector_config_change_cycles_the_collector`
+ * in `crates/fpai-collect/src/config.rs` pins it: move `sources` out of
+ * `CollectorConfig` and the CLI would keep reporting success for paths the
+ * running daemon never picks up.
+ */
+
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { readConfig, updateConfig } from "./fp-config";
+import { configFile } from "./fp-home";
+
+/**
+ * Harness keys `collector.sources.<key>` accepts.
+ *
+ * MUST stay in step with `HARNESS_KEYS` in `crates/failproofaid/src/main.rs`,
+ * which is the side that actually registers the tasks. A name here that the
+ * daemon does not know configures a table nothing reads; a name the daemon
+ * knows and this list omits is a path the user cannot add. `__tests__` asserts
+ * the two lists are identical by reading the Rust source, because nothing else
+ * connects them.
+ *
+ * Twelve keys, thirteen sources: `claude` covers both the main and the subagent
+ * transcript formats, which share a root — an extra path holding Claude
+ * transcripts holds their subagents too.
+ */
+export const HARNESS_KEYS = [
+  "claude",
+  "codex",
+  "copilot",
+  "openclaw",
+  "pi",
+  "factory",
+  "antigravity",
+  "cursor",
+  "goose",
+  "opencode",
+  "devin",
+  "hermes",
+] as const;
+
+export type HarnessKey = (typeof HARNESS_KEYS)[number];
+
+export interface HarnessResult {
+  lines: string[];
+  exitCode: number;
+}
+
+const ok = (lines: string[]): HarnessResult => ({ lines, exitCode: 0 });
+const fail = (lines: string[]): HarnessResult => ({ lines, exitCode: 1 });
+
+function unknownHarness(name: string): HarnessResult {
+  return fail([
+    `Unknown harness: ${name}`,
+    "",
+    `Known harnesses: ${HARNESS_KEYS.join(", ")}`,
+  ]);
+}
+
+/** The path half of an entry, for comparing against what a user typed. */
+function pathOf(entry: string): string {
+  const eq = entry.indexOf("=");
+  if (eq <= 0) return entry.trim();
+  const label = entry.slice(0, eq).trim();
+  return label === "" ? entry.trim() : entry.slice(eq + 1).trim();
+}
+
+/** The label half, or `null` when the entry did not name one. */
+function labelOf(entry: string): string | null {
+  const eq = entry.indexOf("=");
+  if (eq <= 0) return null;
+  const label = entry.slice(0, eq).trim();
+  return label === "" ? null : label;
+}
+
+function currentPaths(harness: string): string[] {
+  return readConfig().collector.sources?.[harness]?.extraPaths ?? [];
+}
+
+function writePaths(harness: string, paths: string[]): void {
+  const cfg = readConfig();
+  const sources = { ...(cfg.collector.sources ?? {}) };
+  if (paths.length > 0) sources[harness] = { extraPaths: paths };
+  else delete sources[harness];
+  updateConfig({
+    collector: {
+      ...cfg.collector,
+      // `undefined` rather than `{}` when the last entry goes, so removing what
+      // you added leaves the file as it was rather than carrying an empty table
+      // forever.
+      sources: Object.keys(sources).length > 0 ? sources : undefined,
+    },
+  });
+}
+
+/**
+ * No restart, and deliberately no instruction to perform one.
+ *
+ * The daemon's collector manager re-reads `config.json` on an interval and
+ * cycles the collector whenever the resolved `CollectorConfig` changes — the
+ * same path that already picks up `--connect`, a stream being switched off and
+ * a verbosity change. `extra_paths` rides that for free because it lives inside
+ * `Settings`, which lives inside the value being compared.
+ *
+ * Verified live: adding a path to a running daemon logged "collector
+ * configuration changed; cycling the collector", took the task count from 21 to
+ * 23, and the first transcript written under the new path reached the server.
+ *
+ * This said "run `sudo systemctl restart failproofaid@$USER`" first. That was
+ * wrong twice over: the restart is unnecessary, and it asks for root from a
+ * command that writes one file in the user's own home and needs none.
+ */
+const TAKES_EFFECT_HINT = [
+  "",
+  "The daemon picks this up on its own within a few seconds — no restart, no sudo.",
+];
+
+/**
+ * The daemon's label rule, FOR COMPARISON ONLY.
+ *
+ * Mirrors `sanitize_label()` in `crates/fpai-collect/src/extra_paths.rs`:
+ * lowercase, every non-alphanumeric run collapsed to one `-`, leading and
+ * trailing dashes trimmed.
+ *
+ * Deliberately NOT used to rewrite what is stored. The daemon is the authority on
+ * the grammar, and this file's header is explicit that it must not re-implement
+ * the parser — "two parsers is how the CLI comes to accept a path the daemon then
+ * silently drops". Normalising for a duplicate CHECK is the narrow opposite of
+ * that: it makes the CLI's own pre-flight agree with the rule it exists to
+ * pre-empt, while the stored string stays exactly what the user typed and the
+ * daemon still derives the real label.
+ */
+function comparableLabel(raw: string): string {
+  return raw
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * The daemon's path rule, for comparison only. Mirrors `clean()`: `~/` expanded,
+ * trailing slashes trimmed.
+ */
+function comparablePath(raw: string): string {
+  const home = homedir();
+  const expanded = raw === "~" ? home : raw.startsWith("~/") ? resolve(home, raw.slice(2)) : raw;
+  return expanded.replace(/\/+$/, "");
+}
+
+/**
+ * What the daemon will call this entry, label given or derived.
+ *
+ * Mirrors `derive_label()` for the unlabelled case: the folder name with a leading
+ * dot stripped, then sanitised. Without this an unlabelled
+ * `/mnt/team-a/.claude/projects` and `/mnt/team-b/.claude/projects` both derive
+ * "projects" — the CLI's label check was skipped entirely for unlabelled entries,
+ * so both were written and the daemon silently dropped the second.
+ */
+function effectiveLabel(entry: string): string {
+  const given = labelOf(entry);
+  if (given) return comparableLabel(given);
+  const path = comparablePath(pathOf(entry));
+  const base = path.split("/").filter(Boolean).pop() ?? "";
+  return comparableLabel(base.replace(/^\.+/, ""));
+}
+
+export function addPath(harness: string, entry: string): HarnessResult {
+  if (!(HARNESS_KEYS as readonly string[]).includes(harness)) return unknownHarness(harness);
+  const trimmed = entry.trim();
+  if (trimmed === "") return fail(["A path is required."]);
+  if (pathOf(trimmed) === "") {
+    return fail([`Could not read a path out of ${JSON.stringify(entry)}.`, "", "Use `<path>` or `<label>=<path>`."]);
+  }
+
+  const existing = currentPaths(harness);
+
+  // Exact duplicate: succeed rather than error. `add-path` run twice from a
+  // provisioning script must not fail the second time.
+  if (existing.includes(trimmed)) {
+    return ok([`${harness}: ${trimmed} is already configured.`]);
+  }
+
+  // Same path under a different label, or the same label on a different path.
+  // Both are rejected HERE rather than left to the daemon, because the daemon
+  // resolves them at startup and drops one — so the CLI would report success
+  // for a path that is never captured.
+  // Compared NORMALISED, not raw. `add-path claude a=/srv/x/` then
+  // `add-path claude b=/srv/x` differ as strings and are the same path to the
+  // daemon, which resolves them at startup and drops one — so the CLI reported
+  // success for a path that is never captured.
+  const samePath = existing.find((e) => comparablePath(pathOf(e)) === comparablePath(pathOf(trimmed)));
+  if (samePath) {
+    return fail([
+      `${harness} already captures ${pathOf(trimmed)} as ${JSON.stringify(samePath)}.`,
+      "",
+      "Remove it first if you meant to relabel it:",
+      `  failproofai harness remove-path ${harness} ${pathOf(trimmed)}`,
+    ]);
+  }
+  const wanted = labelOf(trimmed);
+  // The EFFECTIVE label, normalised, and computed for unlabelled entries too.
+  // Three inputs slipped past the old exact-string check on the given label:
+  // `"Team Share"` vs `team-share` (the daemon lowercases and substitutes), and two
+  // unlabelled paths whose folder name derives the same label — for which the check
+  // did not run at all. In every case both entries were written, `harness list`
+  // showed both, and only one was captured.
+  const effective = effectiveLabel(trimmed);
+  const sameLabel = effective
+    ? existing.find((e) => effectiveLabel(e) === effective)
+    : undefined;
+  if (sameLabel) {
+    return fail([
+      `${harness} already uses the label ${JSON.stringify(effective)} for ${pathOf(sameLabel)}.`,
+      "",
+      "Labels namespace agent ids, so two paths cannot share one — and the daemon",
+      "lowercases them and collapses punctuation to `-`, so labels that differ only",
+      "in case or spacing collide. An unlabelled path takes its folder name.",
+      "",
+      "Give this one an explicit label:",
+      `  failproofai harness add-path ${harness} <label>=${pathOf(trimmed)}`,
+    ]);
+  }
+
+  writePaths(harness, [...existing, trimmed]);
+  return ok([
+    // "configured", NOT "now capturing". The checks above cover what this side can
+    // know — the entries already in the file — and there is one rejection it
+    // cannot: a path overlapping the harness's own DEFAULT capture root, which the
+    // daemon owns and refuses. Claiming capture there was a promise this command
+    // is not in a position to make, so it says what it did and where the answer
+    // is. Teaching the CLI all thirteen sources' default roots would be the second
+    // parser this file exists to avoid.
+    `${harness}: configured to also capture ${pathOf(trimmed)}`,
+    wanted
+      ? `  agent ids will be namespaced ${wanted}-*`
+      : "  a label will be derived from the folder name; `failproofai harness list` shows it",
+    `  written to ${configFile()}`,
+    "",
+    "  The daemon validates it on the next read and reports what it rejected —",
+    "  `failproofai harness list` shows what is actually being captured.",
+    ...TAKES_EFFECT_HINT,
+  ]);
+}
+
+export function removePath(harness: string, target: string): HarnessResult {
+  if (!(HARNESS_KEYS as readonly string[]).includes(harness)) return unknownHarness(harness);
+  const existing = currentPaths(harness);
+  const t = target.trim();
+  // Match on the whole entry, on its path, or on its label — a user removing
+  // something is working from what `list` printed, which shows all three.
+  const kept = existing.filter((e) => e !== t && pathOf(e) !== t && labelOf(e) !== t);
+  if (kept.length === existing.length) {
+    return fail([
+      `${harness} has no extra path matching ${JSON.stringify(t)}.`,
+      "",
+      existing.length > 0
+        ? `Configured: ${existing.join(", ")}`
+        : `${harness} has no extra paths configured.`,
+    ]);
+  }
+  writePaths(harness, kept);
+  return ok([
+    `${harness}: no longer capturing ${t}`,
+    "",
+    "Already-collected sessions from that path are NOT removed — they are on the",
+    "server. This only stops new ones.",
+    ...TAKES_EFFECT_HINT,
+  ]);
+}
+
+export function listPaths(harness?: string): HarnessResult {
+  if (harness && !(HARNESS_KEYS as readonly string[]).includes(harness)) return unknownHarness(harness);
+  const sources = readConfig().collector.sources ?? {};
+  const names: string[] = harness
+    ? [harness]
+    : HARNESS_KEYS.filter((k) => sources[k]?.extraPaths?.length);
+
+  // Computed BEFORE the empty-state return, not after. A config whose only
+  // tables are typos has no known harness configured, so the early return fired
+  // and the warning below was unreachable in precisely the case it exists for —
+  // the user sees "No extra capture paths configured" while their file plainly
+  // contains one, which is the most confusing possible answer.
+  const unknown = Object.keys(sources).filter(
+    (k) => !(HARNESS_KEYS as readonly string[]).includes(k),
+  );
+
+  if (names.length === 0 && unknown.length === 0) {
+    return ok([
+      "No extra capture paths configured.",
+      "",
+      "Every harness is watching only its default location. Add one with:",
+      "  failproofai harness add-path <harness> [<label>=]<path>",
+      "",
+      `Harnesses: ${HARNESS_KEYS.join(", ")}`,
+    ]);
+  }
+
+  const lines: string[] = [];
+  for (const name of names) {
+    const entries = sources[name]?.extraPaths ?? [];
+    if (entries.length === 0) {
+      if (harness) lines.push(`${name}: no extra paths configured (default location only)`);
+      continue;
+    }
+    lines.push(`${name}:`);
+    for (const e of entries) {
+      const label = labelOf(e);
+      lines.push(
+        label
+          ? `  ${pathOf(e)}   → agent ids ${label}-*`
+          : `  ${pathOf(e)}   → label derived from the folder name`,
+      );
+    }
+  }
+  // Unknown tables are surfaced here as well as by the daemon: a user who
+  // hand-edited config.json runs `list` to check it, and that is the moment the
+  // typo is cheapest to find.
+  if (unknown.length > 0) {
+    if (lines.length === 0) lines.push("No extra capture paths configured for any known harness.");
+    lines.push(
+      "",
+      `⚠ config.json configures ${unknown.length} unknown harness(es): ${unknown.join(", ")}`,
+      "  Nothing is captured from them.",
+      `  Known: ${HARNESS_KEYS.join(", ")}`,
+    );
+  }
+  return ok(lines);
+}
+
+/** Dispatch for `failproofai harness <sub> ...`. */
+export function runHarnessCommand(argv: string[]): HarnessResult {
+  const [sub, ...rest] = argv;
+  switch (sub) {
+    case "add-path":
+      if (rest.length < 2) {
+        return fail(["Usage: failproofai harness add-path <harness> [<label>=]<path>"]);
+      }
+      return addPath(rest[0], rest.slice(1).join(" "));
+    case "remove-path":
+      if (rest.length < 2) {
+        return fail(["Usage: failproofai harness remove-path <harness> <path|label>"]);
+      }
+      return removePath(rest[0], rest.slice(1).join(" "));
+    case "list":
+      return listPaths(rest[0]);
+    default:
+      return fail([
+        sub ? `Unknown subcommand: ${sub}` : "A subcommand is required.",
+        "",
+        "Usage:",
+        "  failproofai harness list [<harness>]",
+        "  failproofai harness add-path <harness> [<label>=]<path>",
+        "  failproofai harness remove-path <harness> <path|label>",
+      ]);
+  }
+}