From 3767489522164bb4fbda644a0ad03522086c131c Mon Sep 17 00:00:00 2001
From: SiddarthAA <siddartha_ay@protonmail.com>
Date: Fri, 7 Aug 2026 19:37:09 +0530
Subject: [PATCH 1/3] Capture sessions from more than one location per agent
 CLI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every source watched exactly the place its own installer puts it —
~/.claude/projects, ~/.hermes/state.db. That is right for one machine and
wrong for every other arrangement: a second profile, a mounted team share, a
container's home beside the host's, an agent an operator relocated. Those
hold real sessions and nothing collected them.

`failproofai harness add-path <harness> [<label>=]<path>` (plus list /
remove-path) writes [collector.sources.<harness>] extra_paths in config.toml;
FAILPROOFAI_<HARNESS>_EXTRA_PATHS overrides it for containers. All twelve
harnesses — thirteen sources, since `claude` carries its subagent
transcripts, which share a root and would otherwise be silently dropped under
an added path.

Grammar, folder-name label fallback and <label>-<agentId> namespacing match
AgentEye's collector (--openclaw-extra-path, --hermes-extra-path) rather than
inventing a second answer to what an extra path is.

Three things are structural rather than incidental:

* Each labelled path is its OWN task. `roots` is walked by one task with one
  Params, and the label lives in Params — so a second root added there would
  be captured under the same agent id as the default. Two copies of one
  project derive the SAME id (from the cwd inside the transcript, identical in
  both), which is precisely what the label exists to separate.
* Each gets its own cursor directory. The store writes its whole map
  atomically, so two instances sharing one clobber each other's watermark and
  both re-read from zero after every restart.
* Each gets its own health key, or they overwrite each other's record and
  root_present alternates — destroying the "absent root versus idle source"
  distinction that file exists to draw. Hermes hit exactly this with its
  per-profile databases; that is the shape every source now takes.

The label is applied in SpoolWriter::push — the one point every event from
every source passes through, where machine_id and user are already stamped
for the same reason — and NOT in either engine. A SQLite format is handed
params.agent_id only as a fallback and derives the real id from the row:
devin::agent_id returns devin-<project> and never consults the fallback for a
session that has a working directory, which is all of them. Prefixing there
would namespace only the sessions that failed to derive an id.

A path overlapping one already captured is refused at startup rather than
collected twice under two ids, and an unrecognised [collector.sources.*]
table is reported instead of silently capturing nothing.

A machine with nothing configured is unchanged, byte for byte, including its
config.toml.

Tests: 8 engine tests through the real filetail and sqlitepoll loops
(multi-path steady state, backfill from a newly added path, cursor resume,
and a default-only regression); 16 grammar unit tests; a cross-language
contract test parsing the exact config.toml bytes the TypeScript CLI emits,
because that seam has nothing else holding it together; and a test that reads
HARNESS_KEYS out of main.rs so the two hand-maintained copies of that list
cannot drift.

Found and fixed while testing: `harness list` returned "No extra capture
paths configured" before it checked for unknown tables, so the typo warning
was unreachable in exactly the case it exists for.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CCSFM55BcUEAHECabpeSr4
---
 CHANGELOG.md                                  |   3 +-
 CLAUDE.md                                     |  30 +
 __tests__/hooks/harness-extra-paths.test.ts   | 273 +++++++++
 bin/failproofai.mjs                           |  84 ++-
 crates/failproofaid/src/main.rs               | 333 +++++++++-
 crates/fpai-collect/src/config.rs             | 240 ++++++++
 crates/fpai-collect/src/extra_paths.rs        | 370 ++++++++++++
 crates/fpai-collect/src/filetail.rs           |  28 +-
 crates/fpai-collect/src/lib.rs                |   6 +-
 crates/fpai-collect/src/spool.rs              |  43 ++
 crates/fpai-collect/src/sqlitepoll.rs         |  20 +-
 crates/fpai-collect/src/supervisor.rs         |  18 +-
 .../fpai-collect/tests/antigravity_source.rs  |   2 +
 crates/fpai-collect/tests/claude_source.rs    |   2 +
 crates/fpai-collect/tests/claude_subagents.rs |   2 +
 crates/fpai-collect/tests/codex_source.rs     |   2 +
 crates/fpai-collect/tests/copilot_source.rs   |   2 +
 crates/fpai-collect/tests/cursor_source.rs    |   2 +
 crates/fpai-collect/tests/devin_source.rs     |   1 +
 .../fpai-collect/tests/extra_paths_engine.rs  | 570 ++++++++++++++++++
 crates/fpai-collect/tests/factory_source.rs   |   2 +
 crates/fpai-collect/tests/goose_source.rs     |   1 +
 crates/fpai-collect/tests/hermes_source.rs    |   1 +
 crates/fpai-collect/tests/openclaw_source.rs  |   2 +
 crates/fpai-collect/tests/pi_source.rs        |   2 +
 src/hooks/fp-config.ts                        |  62 ++
 src/hooks/harness-cli.ts                      | 291 +++++++++
 27 files changed, 2349 insertions(+), 43 deletions(-)
 create mode 100644 __tests__/hooks/harness-extra-paths.test.ts
 create mode 100644 crates/fpai-collect/src/extra_paths.rs
 create mode 100644 crates/fpai-collect/tests/extra_paths_engine.rs
 create mode 100644 src/hooks/harness-cli.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d2905244..f64b293e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,9 +4,8 @@
 
 ### Features
 - Add `failproofai flush` — deliver what is already spooled, now. The collector is unhurried on purpose (a batch is swept once it is older than two minutes, at most 64 per pass, on a 60-second cadence), which is right for a backlog and exactly wrong for somebody standing at a dashboard waiting to see their own events: from there "not delivered yet" and "not working" look identical. The command asks the daemon for a pass with no minimum age and no cap, and `--wait` blocks until the spool drains so a script can flush and then assert. It re-sends nothing — for history the collector already read past, that is still `backfill`. (#PR)
-
-### Features
 - Rename the cloud-policy vocabulary: a **generation** is now a **deployment**, and a policy **revision** is a **version**. Both were words the product used nowhere else — a customer reads "deployment 7" and "version 3" without a glossary. The rename goes through the wire format and the on-disk manifest, not just the labels, and lands with the matching AgentEye change: a server and a daemon that disagree on these names means the fleet stops reconciling, silently. (#PR)
+- Capture sessions from more than one location per agent CLI. Every source watched exactly the place its own installer puts it — `~/.claude/projects`, `~/.hermes/state.db` — which is right for one machine and wrong for every other arrangement: a second profile, a mounted team share, a container's home beside the host's, an agent an operator relocated. Those hold real sessions and nothing collected them. `failproofai harness add-path <harness> [<label>=]<path>` (plus `list` / `remove-path`) writes `[collector.sources.<harness>] extra_paths` in `config.toml`; `FAILPROOFAI_<HARNESS>_EXTRA_PATHS` overrides it for containers. Covers all twelve harnesses — thirteen sources, since `claude` carries its subagent transcripts, which share a root and would otherwise be silently dropped under an added path. Grammar, folder-name label fallback and `<label>-<agentId>` namespacing match AgentEye's collector (`--openclaw-extra-path`, `--hermes-extra-path`) rather than inventing a second answer to what an extra path is. Three things are structural rather than incidental: **each labelled path is its own task**, because `roots` is walked by one task with one `Params` and the label lives there — sharing would capture both under one id; each gets **its own cursor directory**, because the store writes its whole map atomically and two instances sharing one clobber each other's watermark and both re-read from zero after every restart; and each gets **its own health key**, or they overwrite each other's record and `root_present` alternates, destroying the "absent root versus idle source" distinction that file exists to draw — the exact failure Hermes hit with its per-profile databases. The label is applied in `SpoolWriter::push`, the one point every event from every source passes through (where `machine_id` and `user` are already stamped for the same reason), and **not** in either engine: a SQLite format is handed `params.agent_id` only as a fallback and derives the real id from the row (`devin::agent_id` returns `devin-<project>` and never consults the fallback for a session that has a working directory, which is all of them), so prefixing there would namespace only the sessions that failed to derive an id. A path overlapping one already captured is refused at startup rather than collected twice under two ids, and an unrecognised `[collector.sources.*]` table is reported instead of silently capturing nothing. A machine with nothing configured is unchanged, byte for byte, including its `config.toml`. (#PR)
 
 ### Fixes
 - Make `failproofai config` refuse setup on an unsupported platform (Windows, today) instead of completing it unenforced. The wizard used to skip the daemon requirement and finish anyway, leaving the machine reading as configured while enforcing in-process with no fail-closed guarantee — now it prints why and exits 1 before drawing a single prompt, writing nothing. (#664)
diff --git a/CLAUDE.md b/CLAUDE.md
index 7c030f32..140b3a2a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1152,6 +1152,18 @@ src/hooks/
                               all 11 CLIs, recoverable only by hand-editing
                               ~/.failproofai/policies-config.json
   manager.ts                 policies --install / --uninstall / list
+  harness-cli.ts             `failproofai harness add-path/remove-path/list` —
+                              edits [collector.sources.<harness>] extra_paths in
+                              config.toml and NOTHING else. The grammar, `~`
+                              expansion, overlap rejection and <label>-<agentId>
+                              namespacing all live in the daemon
+                              (crates/fpai-collect/src/extra_paths.rs); this side
+                              validates only the HARNESS NAME, because that is
+                              the one failure with no other detector — a typo'd
+                              table is valid TOML that captures nothing.
+                              HARNESS_KEYS here and in main.rs are two
+                              hand-maintained copies of one list; a test reads
+                              the Rust source to keep them identical
 src/index.ts                 Public API entry point → compiled to dist/index.js
 dist/index.js                CJS bundle (built by `bun run build`; shipped in npm pkg)
 dist/cli.mjs                 Bundled bin/failproofai.mjs (bun run build:cli)
@@ -1159,6 +1171,24 @@ dist/worker.mjs              Bundled bin/failproofai-worker.mjs (bun run build:w
                               plain Node can't resolve raw .ts specifiers, so the warm
                               worker needs this bundle just like the CLI does
 Cargo.toml                   Rust workspace root (resolver "3", shared [workspace.package])
+crates/fpai-collect/src/extra_paths.rs
+                              Per-source extra capture paths: `label=path`
+                              grammar, folder-name label fallback, and the
+                              rejections that each prevent a SILENT failure — a
+                              path overlapping a default root is collected twice
+                              under two agent ids, and two entries sharing a
+                              label share a cursor directory whose whole map is
+                              written atomically, so both re-read from zero after
+                              every restart. Each accepted path becomes its OWN
+                              task (file_source / sqlite_harness in main.rs) with
+                              its own cursor dir and health key — Hermes reached
+                              this shape first, via per-profile databases. The
+                              <label>-<agentId> prefix is applied in
+                              SpoolWriter::push, never in an engine: a SQLite
+                              format derives its real id from the row and takes
+                              params.agent_id only as a fallback, so prefixing
+                              there namespaces just the sessions that failed to
+                              derive one
 crates/fpai-ipc/              Wire protocol shared by the daemon and its tests: length-
                               prefixed JSON framing, protocolVersion envelope, peer-
                               credential checks (see crates/PROTOCOL.md)
diff --git a/__tests__/hooks/harness-extra-paths.test.ts b/__tests__/hooks/harness-extra-paths.test.ts
new file mode 100644
index 00000000..fcf9ffc5
--- /dev/null
+++ b/__tests__/hooks/harness-extra-paths.test.ts
@@ -0,0 +1,273 @@
+// @vitest-environment node
+//
+// `failproofai harness` and the `[collector.sources.*]` config it writes.
+//
+// The round trip through a real config.toml is the point of most of these:
+// `writeConfig` regenerates the file wholesale, so the failure mode worth
+// testing is not "did it write the key" but "did writing it drop something
+// else", and "does what it wrote parse back to what it meant".
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+import { readConfig, writeConfig, DEFAULT_CONFIG } from "@/src/hooks/fp-config";
+import { configFile } from "@/src/hooks/fp-home";
+import { HARNESS_KEYS, addPath, removePath, listPaths, runHarnessCommand } from "@/src/hooks/harness-cli";
+
+describe("harness extra paths", () => {
+  let home: string;
+  let prevHome: string | undefined;
+
+  beforeEach(() => {
+    prevHome = process.env.FAILPROOFAI_HOME;
+    home = mkdtempSync(join(tmpdir(), "fpai-hx-"));
+    process.env.FAILPROOFAI_HOME = home;
+  });
+
+  afterEach(() => {
+    if (prevHome === undefined) delete process.env.FAILPROOFAI_HOME;
+    else process.env.FAILPROOFAI_HOME = prevHome;
+    rmSync(home, { recursive: true, force: true });
+  });
+
+  // ── the list that cannot be allowed to drift ───────────────────────────
+
+  // Two hand-maintained copies of one list, in two languages, with nothing
+  // generating either. A name here the daemon does not know writes a table
+  // nothing reads; a name the daemon knows and this omits is a path the user
+  // cannot add. Both parse cleanly and neither is mentioned anywhere else.
+  it("matches HARNESS_KEYS in the daemon, which is the side that registers tasks", () => {
+    const rust = readFileSync(
+      resolve(__dirname, "../../crates/failproofaid/src/main.rs"),
+      "utf8",
+    );
+    const block = /const HARNESS_KEYS: &\[&str\] = &\[([\s\S]*?)\];/.exec(rust);
+    expect(block, "HARNESS_KEYS not found in main.rs — did it move or get renamed?").toBeTruthy();
+    const rustKeys = [...block![1].matchAll(/"([a-z-]+)"/g)].map((m) => m[1]);
+    expect(rustKeys.length).toBeGreaterThan(0);
+    expect([...rustKeys].sort()).toEqual([...HARNESS_KEYS].sort());
+  });
+
+  // ── the default-path-only regression ───────────────────────────────────
+
+  it("writes no [collector.sources] table when nothing is configured", () => {
+    writeConfig(DEFAULT_CONFIG);
+    const text = readFileSync(configFile(), "utf8");
+    expect(text).not.toContain("[collector.sources");
+    expect(readConfig().collector.sources).toBeUndefined();
+  });
+
+  it("adding then removing the last path leaves no empty table behind", () => {
+    writeConfig(DEFAULT_CONFIG);
+    const before = readFileSync(configFile(), "utf8");
+
+    addPath("claude", "work=/srv/team/projects");
+    expect(readFileSync(configFile(), "utf8")).toContain("[collector.sources.claude]");
+
+    removePath("claude", "work");
+    expect(readFileSync(configFile(), "utf8")).not.toContain("[collector.sources");
+    // Byte-identical to before: a user who adds and removes gets their file back.
+    expect(readFileSync(configFile(), "utf8")).toBe(before);
+  });
+
+  // ── round trips ────────────────────────────────────────────────────────
+
+  it("round-trips a labelled path through real TOML", () => {
+    addPath("claude", "work=/srv/team/.claude/projects");
+    expect(readConfig().collector.sources).toEqual({
+      claude: { extraPaths: ["work=/srv/team/.claude/projects"] },
+    });
+  });
+
+  it("keeps several paths for one harness, in the order they were added", () => {
+    addPath("claude", "a=/srv/a");
+    addPath("claude", "b=/srv/b");
+    addPath("claude", "/srv/c");
+    expect(readConfig().collector.sources?.claude.extraPaths).toEqual([
+      "a=/srv/a",
+      "b=/srv/b",
+      "/srv/c",
+    ]);
+  });
+
+  it("keeps paths for several harnesses independently", () => {
+    addPath("claude", "w=/srv/claude");
+    addPath("hermes", "p=/srv/hermes/state.db");
+    const s = readConfig().collector.sources!;
+    expect(s.claude.extraPaths).toEqual(["w=/srv/claude"]);
+    expect(s.hermes.extraPaths).toEqual(["p=/srv/hermes/state.db"]);
+  });
+
+  // The regression that motivates writing sub-tables AFTER every scalar of
+  // `[collector]`: get the order wrong and TOML reads `[telemetry]`/`[audit]`,
+  // or worse a later `[collector]` scalar, as belonging to the sub-table.
+  it("does not corrupt the rest of the config", () => {
+    writeConfig({
+      ...DEFAULT_CONFIG,
+      mode: "cloud",
+      daemon: { configured: true },
+      collector: {
+        ...DEFAULT_CONFIG.collector,
+        sessions: true,
+        environment: "prod",
+        machineId: "m-123",
+        redact: "off",
+      },
+      telemetry: { enabled: false },
+      audit: { auto: true, intervalDays: 14 },
+    });
+    addPath("codex", "alt=/mnt/other/.codex/sessions");
+
+    const cfg = readConfig();
+    expect(cfg.mode).toBe("cloud");
+    expect(cfg.daemon.configured).toBe(true);
+    expect(cfg.collector.sessions).toBe(true);
+    expect(cfg.collector.environment).toBe("prod");
+    expect(cfg.collector.machineId).toBe("m-123");
+    expect(cfg.collector.redact).toBe("off");
+    expect(cfg.telemetry.enabled).toBe(false);
+    expect(cfg.audit).toEqual({ auto: true, intervalDays: 14 });
+    expect(cfg.collector.sources?.codex.extraPaths).toEqual(["alt=/mnt/other/.codex/sessions"]);
+  });
+
+  it("a path containing an equals sign survives the round trip", () => {
+    addPath("claude", "k=/srv/a=b/projects");
+    expect(readConfig().collector.sources?.claude.extraPaths).toEqual(["k=/srv/a=b/projects"]);
+  });
+
+  // ── rejections ─────────────────────────────────────────────────────────
+
+  it("refuses an unknown harness and names the real ones", () => {
+    const r = addPath("claud", "/srv/x");
+    expect(r.exitCode).toBe(1);
+    expect(r.lines.join("\n")).toContain("Unknown harness: claud");
+    expect(r.lines.join("\n")).toContain("claude");
+    expect(existsSync(configFile())).toBe(false);
+  });
+
+  // Adding twice from a provisioning script must not fail the second time.
+  it("is idempotent for an exact duplicate", () => {
+    expect(addPath("claude", "w=/srv/x").exitCode).toBe(0);
+    const r = addPath("claude", "w=/srv/x");
+    expect(r.exitCode).toBe(0);
+    expect(readConfig().collector.sources?.claude.extraPaths).toEqual(["w=/srv/x"]);
+  });
+
+  // Both of these are dropped by the daemon at startup. Caught here so the CLI
+  // does not report success for a path that is never captured.
+  it("refuses the same path under a second label", () => {
+    addPath("claude", "a=/srv/x");
+    const r = addPath("claude", "b=/srv/x");
+    expect(r.exitCode).toBe(1);
+    expect(r.lines.join("\n")).toContain("already captures /srv/x");
+    expect(readConfig().collector.sources?.claude.extraPaths).toEqual(["a=/srv/x"]);
+  });
+
+  it("refuses a second path under the same label", () => {
+    addPath("claude", "a=/srv/x");
+    const r = addPath("claude", "a=/srv/y");
+    expect(r.exitCode).toBe(1);
+    expect(r.lines.join("\n")).toContain('already uses the label "a"');
+    expect(readConfig().collector.sources?.claude.extraPaths).toEqual(["a=/srv/x"]);
+  });
+
+  it("refuses an entry with no path", () => {
+    expect(addPath("claude", "").exitCode).toBe(1);
+    expect(addPath("claude", "label=").exitCode).toBe(1);
+  });
+
+  // ── removal ────────────────────────────────────────────────────────────
+
+  it("removes by label, by path, or by the whole entry", () => {
+    for (const target of ["w", "/srv/x", "w=/srv/x"]) {
+      addPath("claude", "w=/srv/x");
+      const r = removePath("claude", target);
+      expect(r.exitCode, `removing by ${target}`).toBe(0);
+      expect(readConfig().collector.sources).toBeUndefined();
+    }
+  });
+
+  it("removing something absent fails rather than silently succeeding", () => {
+    addPath("claude", "w=/srv/x");
+    const r = removePath("claude", "nope");
+    expect(r.exitCode).toBe(1);
+    expect(readConfig().collector.sources?.claude.extraPaths).toEqual(["w=/srv/x"]);
+  });
+
+  it("removing one of several keeps the rest", () => {
+    addPath("claude", "a=/srv/a");
+    addPath("claude", "b=/srv/b");
+    removePath("claude", "a");
+    expect(readConfig().collector.sources?.claude.extraPaths).toEqual(["b=/srv/b"]);
+  });
+
+  // ── list ───────────────────────────────────────────────────────────────
+
+  it("says so plainly when nothing is configured", () => {
+    const r = listPaths();
+    expect(r.exitCode).toBe(0);
+    expect(r.lines.join("\n")).toContain("No extra capture paths configured");
+  });
+
+  it("shows the namespace each path will produce", () => {
+    addPath("claude", "work=/srv/team");
+    addPath("hermes", "/srv/hermes-prod/state.db");
+    const out = listPaths().lines.join("\n");
+    expect(out).toContain("claude:");
+    expect(out).toContain("/srv/team");
+    expect(out).toContain("work-*");
+    expect(out).toContain("hermes:");
+    expect(out).toContain("derived from the folder name");
+  });
+
+  // A user who hand-edits config.toml runs `list` to check it, which is the
+  // cheapest moment to find the typo. The daemon also reports this at startup.
+  it("warns about an unknown harness table written by hand", () => {
+    writeConfig({
+      ...DEFAULT_CONFIG,
+      collector: {
+        ...DEFAULT_CONFIG.collector,
+        sources: { claud: { extraPaths: ["/srv/x"] } },
+      },
+    });
+    const out = listPaths().lines.join("\n");
+    expect(out).toContain("unknown harness");
+    expect(out).toContain("claud");
+  });
+
+  // ── dispatch ───────────────────────────────────────────────────────────
+
+  it("rejects an unknown subcommand and prints usage", () => {
+    const r = runHarnessCommand(["frobnicate"]);
+    expect(r.exitCode).toBe(1);
+    expect(r.lines.join("\n")).toContain("add-path");
+  });
+
+  it("requires both arguments for add-path", () => {
+    expect(runHarnessCommand(["add-path"]).exitCode).toBe(1);
+    expect(runHarnessCommand(["add-path", "claude"]).exitCode).toBe(1);
+  });
+
+  it("dispatches add-path, list and remove-path", () => {
+    expect(runHarnessCommand(["add-path", "claude", "w=/srv/x"]).exitCode).toBe(0);
+    expect(runHarnessCommand(["list"]).lines.join("\n")).toContain("/srv/x");
+    expect(runHarnessCommand(["remove-path", "claude", "w"]).exitCode).toBe(0);
+  });
+
+  // ── malformed config on disk ───────────────────────────────────────────
+
+  it("ignores a sources table that is not shaped like one", () => {
+    writeConfig(DEFAULT_CONFIG);
+    const path = configFile();
+    const text = readFileSync(path, "utf8");
+    require("node:fs").writeFileSync(
+      path,
+      text +
+        '\n[collector.sources.claude]\nextra_paths = "not-an-array"\n' +
+        "\n[collector.sources.codex]\nextra_paths = [1, 2]\n",
+    );
+    // Neither becomes a phantom entry, and reading does not throw.
+    expect(readConfig().collector.sources).toBeUndefined();
+  });
+});
diff --git a/bin/failproofai.mjs b/bin/failproofai.mjs
index c5a603c9..c88eb6f9 100755
--- a/bin/failproofai.mjs
+++ b/bin/failproofai.mjs
@@ -271,7 +271,7 @@ if (hookIdx >= 0) {
  */
 async function runCli() {
   // --help / -h  (only when not inside a subcommand that handles its own --help)
-  const SUBCOMMANDS = ["policies", "policy", "audit", "config", "uninstall", "backfill", "flush"];
+  const SUBCOMMANDS = ["policies", "policy", "audit", "config", "uninstall", "backfill", "flush", "harness"];
   if ((args.includes("--help") || args.includes("-h")) && !SUBCOMMANDS.includes(args[0])) {
     const extraArgs = args.filter((a) => a !== "--help" && a !== "-h");
     if (extraArgs.length > 0) {
@@ -319,6 +319,14 @@ COMMANDS
 
   policies --help, -h            Show this help for the policies command
 
+  harness list                   Show extra capture paths per agent CLI
+  harness add-path <h> <path>    Also capture sessions from <path> for harness
+                                 <h>. Accepts \`<label>=<path>\`; the label
+                                 namespaces agent ids so two copies of one
+                                 project stay distinct.
+  harness remove-path <h> <p>    Stop capturing that path
+  harness --help, -h             Show this help for the harness command
+
   audit                          Audit your agent's behavior, then open the
                                  dashboard at http://localhost:8020/audit
   audit --help, -h               Show this help for the audit command
@@ -646,6 +654,80 @@ OPTIONS
     return;
   }
 
+  // harness list | add-path | remove-path
+  //
+  // Extra capture paths per harness. Writes ~/.failproofai/config.toml and
+  // nothing else — no root, no daemon call — so it works on a machine whose
+  // daemon is stopped, which is when someone is most likely to be fixing what
+  // it captures.
+  if (args[0] === "harness") {
+    const subArgs = args.slice(1);
+    if (subArgs.length === 0 || subArgs.includes("--help") || subArgs.includes("-h")) {
+      console.log(`
+failproofai harness — capture sessions from more than one location per agent CLI
+
+USAGE
+  failproofai harness list [<harness>]
+  failproofai harness add-path <harness> [<label>=]<path>
+  failproofai harness remove-path <harness> <path|label>
+
+WHY
+  Each agent CLI is watched wherever its own installer put it — ~/.claude/projects,
+  ~/.hermes/state.db, and so on. That misses every other arrangement: a second
+  profile, a mounted team share, a container's home beside the host's, an agent
+  an operator moved. Those hold real sessions and nothing collects them.
+
+THE LABEL
+  An entry is \`<path>\` or \`<label>=<path>\`. The label namespaces agent ids as
+  <label>-<agentId>, and it matters: two locations holding the same project
+  derive the SAME id (it comes from the cwd inside the transcript, identical in
+  both copies), so without a label they merge into one agent whose sessions
+  interleave from two machines' worth of history. Omit it and one is derived
+  from the folder name.
+
+HARNESSES
+  claude, codex, copilot, openclaw, pi, factory, antigravity, cursor,
+  goose, opencode, devin, hermes
+
+  \`claude\` covers subagent transcripts too — they live under the same root.
+
+NOTES
+  • Session collection must be on for any of this to be read; extra paths follow
+    [collector] in ~/.failproofai/config.toml like the default ones do.
+  • A path overlapping one already captured is REFUSED by the daemon at startup
+    rather than collected twice under two ids. It says so in the journal.
+  • Takes effect at the next daemon restart — the collector builds its task list
+    once, at startup.
+
+EXAMPLES
+  failproofai harness add-path claude work=/srv/team/.claude/projects
+  failproofai harness add-path hermes prod=/srv/hermes-prod/state.db
+  failproofai harness add-path codex /mnt/other-home/.codex/sessions
+  failproofai harness list
+  failproofai harness remove-path claude work
+`.trimStart());
+      process.exit(0);
+    }
+
+    lastSubcommand = "harness";
+    const { runHarnessCommand } = await import("../src/hooks/harness-cli");
+    const result = runHarnessCommand(subArgs);
+    for (const line of result.lines) {
+      if (result.exitCode === 0) console.log(line);
+      else console.error(line);
+    }
+    await track("cli_harness", {
+      ok: result.exitCode === 0,
+      // The subcommand only — never the harness name, the label or the path.
+      // A path is a value the user typed, and `enterprise-docs/product-analytics.md`
+      // promises we send shape, never value.
+      sub: ["list", "add-path", "remove-path"].includes(subArgs[0]) ? subArgs[0] : "unknown",
+    });
+    lastSubcommand = null;
+    await exitAfterFlush(result.exitCode);
+    return;
+  }
+
   // uninstall [--purge] [--dry-run] [--yes|-y]
   //
   // Top-level, and deliberately NOT a flag on `policies`. `policies --uninstall`
diff --git a/crates/failproofaid/src/main.rs b/crates/failproofaid/src/main.rs
index dc9fe689..af793381 100644
--- a/crates/failproofaid/src/main.rs
+++ b/crates/failproofaid/src/main.rs
@@ -613,6 +613,32 @@ fn collector_config_poll_interval() -> Duration {
     Duration::from_millis(ms.max(MINIMUM_MS))
 }
 
+/// Harness keys accepted under `[collector.sources.<key>]` in `config.toml`.
+///
+/// Twelve keys for thirteen sources: `claude` covers both the main and the
+/// subagent format, which share a root. Anything else configured is reported at
+/// startup rather than ignored — a typo'd table parses cleanly, captures
+/// nothing, and is mentioned nowhere else in the pipeline.
+///
+/// Kept beside the registrations below rather than derived from them because
+/// `claude-subagent` is a source and not a harness, so the two lists are
+/// genuinely different and deriving one from the other would reintroduce the
+/// key nobody should configure.
+const HARNESS_KEYS: &[&str] = &[
+    "claude",
+    "codex",
+    "copilot",
+    "openclaw",
+    "pi",
+    "factory",
+    "antigravity",
+    "cursor",
+    "goose",
+    "opencode",
+    "devin",
+    "hermes",
+];
+
 fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
     let home = match paths::failproofai_home() {
         Ok(home) => home,
@@ -739,14 +765,69 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
         let machine = cfg.settings.machine_id.clone();
         let cursors = cursors_root.clone();
 
+        // `~` in a configured path expands against this, not against whatever
+        // HOME the service unit happened to inherit at spawn time — a
+        // system-scope unit's environment carries essentially nothing (see
+        // `resolveWorkerCommand` in daemon-service.ts for the same hazard).
+        let home_dir = std::env::var_os("HOME").map(std::path::PathBuf::from);
+        let settings = &cfg.settings;
+
+        // A configured table naming no real source captures nothing and is
+        // mentioned nowhere else in the pipeline, so say so once at startup.
+        for unknown in settings.unknown_sources(HARNESS_KEYS) {
+            eprintln!(
+                "[failproofaid] config.toml has [collector.sources.{unknown}], which is not a \
+                 known harness; nothing will be captured from it. Known: {}",
+                HARNESS_KEYS.join(", ")
+            );
+        }
+
+        // Resolve one harness's configured extra paths against the roots it
+        // already watches, logging every rejection — each one is a path the
+        // operator asked for and is not getting.
+        let extras = |harness: &str,
+                      defaults: &[std::path::PathBuf]|
+         -> Vec<fpai_collect::ExtraPath> {
+            let entries = settings.extra_paths_for(harness);
+            if entries.is_empty() {
+                return Vec::new();
+            }
+            let resolved =
+                fpai_collect::extra_paths::resolve(&entries, defaults, home_dir.as_deref());
+            for bad in &resolved.rejected {
+                eprintln!(
+                    "[failproofaid] ignoring extra path {:?} for {harness}: {}",
+                    bad.entry, bad.reason
+                );
+            }
+            for ok in &resolved.accepted {
+                eprintln!(
+                    "[failproofaid] {harness}: also capturing {} as {:?} (agent ids namespaced {}-*)",
+                    ok.path.display(),
+                    ok.label,
+                    ok.label
+                );
+            }
+            resolved.accepted
+        };
+
         use fpai_collect::sources::{
             antigravity, claude, codex, copilot, cursor, factory, openclaw, pi,
         };
+
+        // Claude's two formats share one root and therefore one harness key:
+        // an extra path holding Claude transcripts holds their subagents too,
+        // and asking the operator to configure `claude` and `claude-subagent`
+        // separately would mean a natural-looking config that silently drops
+        // every subagent under the added path.
+        let claude_roots = vec![claude_projects_root()];
+        let claude_extra = extras("claude", &claude_roots);
         file_source(
             &mut tasks,
             "claude",
             claude::FORMAT,
-            vec![claude_projects_root()],
+            claude_roots.clone(),
+            &claude_extra,
             claude::DEFAULT_AGENT_ID,
             &spool,
             &cursors,
@@ -764,7 +845,8 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
             &mut tasks,
             "claude-subagent",
             claude::SUBAGENT_FORMAT,
-            vec![claude_projects_root()],
+            claude_roots,
+            &claude_extra,
             claude::SUBAGENT_DEFAULT_AGENT_ID,
             &spool,
             &cursors,
@@ -773,11 +855,14 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
             os_user.as_deref(),
             redact,
         );
+
+        let codex_roots = vec![codex_sessions_root()];
         file_source(
             &mut tasks,
             "codex",
             codex::FORMAT,
-            vec![codex_sessions_root()],
+            codex_roots.clone(),
+            &extras("codex", &codex_roots),
             codex::DEFAULT_AGENT_ID,
             &spool,
             &cursors,
@@ -786,11 +871,14 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
             os_user.as_deref(),
             redact,
         );
+
+        let copilot_roots = vec![copilot::session_state_root()];
         file_source(
             &mut tasks,
             "copilot",
             copilot::FORMAT,
-            vec![copilot::session_state_root()],
+            copilot_roots.clone(),
+            &extras("copilot", &copilot_roots),
             copilot::DEFAULT_AGENT_ID,
             &spool,
             &cursors,
@@ -799,11 +887,14 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
             os_user.as_deref(),
             redact,
         );
+
+        let openclaw_roots = openclaw::default_roots();
         file_source(
             &mut tasks,
             "openclaw",
             openclaw::FORMAT,
-            openclaw::default_roots(),
+            openclaw_roots.clone(),
+            &extras("openclaw", &openclaw_roots),
             openclaw::DEFAULT_AGENT_ID,
             &spool,
             &cursors,
@@ -812,11 +903,14 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
             os_user.as_deref(),
             redact,
         );
+
+        let pi_roots = vec![pi::sessions_root()];
         file_source(
             &mut tasks,
             "pi",
             pi::FORMAT,
-            vec![pi::sessions_root()],
+            pi_roots.clone(),
+            &extras("pi", &pi_roots),
             pi::DEFAULT_AGENT_ID,
             &spool,
             &cursors,
@@ -825,11 +919,14 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
             os_user.as_deref(),
             redact,
         );
+
+        let factory_roots = vec![factory_sessions_root()];
         file_source(
             &mut tasks,
             "factory",
             factory::FORMAT,
-            vec![factory_sessions_root()],
+            factory_roots.clone(),
+            &extras("factory", &factory_roots),
             factory::DEFAULT_AGENT_ID,
             &spool,
             &cursors,
@@ -838,11 +935,14 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
             os_user.as_deref(),
             redact,
         );
+
+        let antigravity_roots = vec![antigravity_brain_root()];
         file_source(
             &mut tasks,
             "antigravity",
             antigravity::FORMAT,
-            vec![antigravity_brain_root()],
+            antigravity_roots.clone(),
+            &extras("antigravity", &antigravity_roots),
             antigravity::DEFAULT_AGENT_ID,
             &spool,
             &cursors,
@@ -851,11 +951,14 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
             os_user.as_deref(),
             redact,
         );
+
+        let cursor_roots = vec![cursor_projects_root()];
         file_source(
             &mut tasks,
             "cursor",
             cursor::FORMAT,
-            vec![cursor_projects_root()],
+            cursor_roots.clone(),
+            &extras("cursor", &cursor_roots),
             cursor::DEFAULT_AGENT_ID,
             &spool,
             &cursors,
@@ -866,55 +969,60 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
         );
 
         use fpai_collect::sources::{devin, goose, hermes, opencode};
-        sqlite_source(
+        sqlite_harness(
             &mut tasks,
             "goose",
             goose::FORMAT,
             goose::db_path(),
+            &extras("goose", &[goose::db_path()]),
             goose::DEFAULT_AGENT_ID,
             &spool,
-            cursors.join("goose"),
+            &cursors,
             &env,
             machine.as_deref(),
             os_user.as_deref(),
             redact,
-            None,
         );
-        sqlite_source(
+        sqlite_harness(
             &mut tasks,
             "opencode",
             opencode::FORMAT,
             opencode::default_db_path(),
+            &extras("opencode", &[opencode::default_db_path()]),
             opencode::DEFAULT_AGENT_ID,
             &spool,
-            cursors.join("opencode"),
+            &cursors,
             &env,
             machine.as_deref(),
             os_user.as_deref(),
             redact,
-            None,
         );
-        sqlite_source(
+        sqlite_harness(
             &mut tasks,
             "devin",
             devin::FORMAT,
             devin::db_path(),
+            &extras("devin", &[devin::db_path()]),
             devin::DEFAULT_AGENT_ID,
             &spool,
-            cursors.join("devin"),
+            &cursors,
             &env,
             machine.as_deref(),
             os_user.as_deref(),
             redact,
-            None,
         );
 
         // Hermes profiles are SEPARATE databases, and the SQLite poller keys its
         // cursor on a fixed synthetic id — so two profiles sharing one state
         // directory would clobber each other's watermark and each would re-read
         // from zero after every restart. Each database gets its own.
-        for (i, db) in hermes::default_db_paths().into_iter().enumerate() {
-            let profile = profile_dir_name(&db, i);
+        //
+        // This is the shape every other source now takes for its extra paths;
+        // Hermes reached it first, by having several default databases rather
+        // than several configured ones.
+        let hermes_dbs = hermes::default_db_paths();
+        for (i, db) in hermes_dbs.iter().enumerate() {
+            let profile = profile_dir_name(db, i);
             let state = cursors.join("hermes").join(&profile);
             // ...and its own health key, for the same reason it gets its own
             // cursor directory. Every profile reporting under the bare string
@@ -926,7 +1034,7 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
                 &mut tasks,
                 "hermes",
                 hermes::FORMAT,
-                db,
+                db.clone(),
                 hermes::DEFAULT_AGENT_ID,
                 &spool,
                 state,
@@ -935,6 +1043,30 @@ fn collector_tasks() -> Vec<fpai_collect::TaskSpec> {
                 os_user.as_deref(),
                 redact,
                 Some(format!("hermes:{profile}")),
+                // No label: a default profile is not an extra path, and
+                // namespacing it would rename every agent id on every machine
+                // that already has one.
+                None,
+            );
+        }
+        // Configured extras are resolved against EVERY default profile database,
+        // so pointing one at a profile Hermes already exposes is rejected rather
+        // than collected twice under two ids.
+        for ep in extras("hermes", &hermes_dbs) {
+            sqlite_source(
+                &mut tasks,
+                "hermes",
+                hermes::FORMAT,
+                ep.path.clone(),
+                hermes::DEFAULT_AGENT_ID,
+                &spool,
+                cursors.join("hermes").join(&ep.label),
+                &env,
+                machine.as_deref(),
+                os_user.as_deref(),
+                redact,
+                Some(format!("hermes:{}", ep.label)),
+                Some(ep.label.clone()),
             );
         }
     }
@@ -976,13 +1108,24 @@ fn claude_projects_root() -> std::path::PathBuf {
     home.join(".claude").join("projects")
 }
 
-/// Register one file-tailing source.
+/// Register one file-tailing source: its default roots, plus one further
+/// instance per configured extra path.
+///
+/// Each extra path is a SEPARATE task rather than another entry in `roots`, and
+/// that is the whole design. `roots` is walked by one task with one cursor store
+/// and one `Params`, so a second root added there would be captured under the
+/// same agent id as the default — and two copies of one project derive the same
+/// id (from the `cwd` inside the transcript, identical in both copies). The
+/// label that separates them lives in `Params`, so a distinct label demands a
+/// distinct task, which then also needs its own cursor directory and its own
+/// health key for the reasons documented on each.
 #[allow(clippy::too_many_arguments)]
 fn file_source(
     tasks: &mut Vec<fpai_collect::TaskSpec>,
     name: &'static str,
     format: fpai_collect::filetail::Format,
     roots: Vec<std::path::PathBuf>,
+    extra: &[fpai_collect::ExtraPath],
     default_agent_id: &'static str,
     spool_dir: &std::path::Path,
     cursor_root: &std::path::Path,
@@ -990,16 +1133,77 @@ fn file_source(
     machine_id: Option<&str>,
     user: Option<&str>,
     redact: fpai_collect::Redact,
+) {
+    // The default instance: every root the source ships with, no label.
+    file_source_instance(
+        tasks,
+        name,
+        format,
+        roots,
+        None,
+        cursor_root.join(name),
+        None,
+        default_agent_id,
+        spool_dir,
+        environment,
+        machine_id,
+        user,
+        redact,
+    );
+
+    for ep in extra {
+        file_source_instance(
+            tasks,
+            name,
+            format,
+            vec![ep.path.clone()],
+            Some(ep.label.clone()),
+            // Its own cursor store. The store writes its whole map atomically,
+            // so sharing one with the default instance would have them clobber
+            // each other's watermarks and both re-read from zero after every
+            // restart.
+            cursor_root.join(name).join(&ep.label),
+            // ...and its own health key, or the instances overwrite each other's
+            // record and `root_present` alternates as they take turns.
+            Some(format!("{name}:{}", ep.label)),
+            default_agent_id,
+            spool_dir,
+            environment,
+            machine_id,
+            user,
+            redact,
+        );
+    }
+}
+
+/// One live instance of a file-tailing source.
+#[allow(clippy::too_many_arguments)]
+fn file_source_instance(
+    tasks: &mut Vec<fpai_collect::TaskSpec>,
+    name: &'static str,
+    format: fpai_collect::filetail::Format,
+    roots: Vec<std::path::PathBuf>,
+    label: Option<String>,
+    state_dir: std::path::PathBuf,
+    health_key: Option<String>,
+    default_agent_id: &'static str,
+    spool_dir: &std::path::Path,
+    environment: &str,
+    machine_id: Option<&str>,
+    user: Option<&str>,
+    redact: fpai_collect::Redact,
 ) {
     let spool_dir = spool_dir.to_path_buf();
-    // One cursor store per source, never shared: the store writes its whole map
-    // atomically, so two sources sharing a file would clobber each other and the
-    // loser would re-read from zero after every restart.
-    let state_dir = cursor_root.join(name);
     let environment = environment.to_string();
     let machine_id = machine_id.map(str::to_string);
     let user = user.map(str::to_string);
-    tasks.push(fpai_collect::TaskSpec::new(name, move |sd| {
+    // The task name carries the label so `/workflows`-style task listings and
+    // the supervisor's own logs name the instance, not just the source.
+    let task_name: String = match &label {
+        Some(l) => format!("{name}:{l}"),
+        None => name.to_string(),
+    };
+    tasks.push(fpai_collect::TaskSpec::new(task_name, move |sd| {
         fpai_collect::filetail::run(
             fpai_collect::filetail::Spec {
                 format,
@@ -1007,11 +1211,13 @@ fn file_source(
                 spool_dir: spool_dir.clone(),
                 state_dir: state_dir.clone(),
                 poll_interval: std::time::Duration::from_secs(2),
+                health_key: health_key.clone(),
                 params: fpai_collect::filetail::Params {
                     agent_id: default_agent_id.to_string(),
                     environment: environment.clone(),
                     machine_id: machine_id.clone(),
                     user: user.clone(),
+                    label: label.clone(),
                     end_idle_mins: 10,
                     redact,
                     max_read_bytes: 32 * 1024 * 1024,
@@ -1022,6 +1228,10 @@ fn file_source(
                     // widens this for its own rebuild — see BACKFILL_SINCE_DAYS,
                     // without which rewinding cursors delivers only 7 days no
                     // matter what was asked for.
+                    //
+                    // A newly added extra path needs no special case: it has no
+                    // cursor, so every file under it is a first discovery and is
+                    // read from the start of this same window.
                     since_days: file_source_since_days(),
                 },
             },
@@ -1030,6 +1240,63 @@ fn file_source(
     }));
 }
 
+/// Register one SQLite-polling source: its default database, plus one further
+/// instance per configured extra path.
+///
+/// The file-tailing counterpart of this is `file_source`; both expand a harness
+/// into `1 + N` tasks for the same reason, and give each instance its own
+/// cursor directory and health key. Hermes does not use this wrapper because it
+/// already has several DEFAULT databases (one per profile) and so drives the
+/// per-instance registration itself.
+#[allow(clippy::too_many_arguments)]
+fn sqlite_harness(
+    tasks: &mut Vec<fpai_collect::TaskSpec>,
+    name: &'static str,
+    format: fpai_collect::sqlitepoll::SqliteFormat,
+    db_path: std::path::PathBuf,
+    extra: &[fpai_collect::ExtraPath],
+    default_agent_id: &'static str,
+    spool_dir: &std::path::Path,
+    cursor_root: &std::path::Path,
+    environment: &str,
+    machine_id: Option<&str>,
+    user: Option<&str>,
+    redact: fpai_collect::Redact,
+) {
+    sqlite_source(
+        tasks,
+        name,
+        format,
+        db_path,
+        default_agent_id,
+        spool_dir,
+        cursor_root.join(name),
+        environment,
+        machine_id,
+        user,
+        redact,
+        None,
+        None,
+    );
+    for ep in extra {
+        sqlite_source(
+            tasks,
+            name,
+            format,
+            ep.path.clone(),
+            default_agent_id,
+            spool_dir,
+            cursor_root.join(name).join(&ep.label),
+            environment,
+            machine_id,
+            user,
+            redact,
+            Some(format!("{name}:{}", ep.label)),
+            Some(ep.label.clone()),
+        );
+    }
+}
+
 /// Register one SQLite-polling source.
 #[allow(clippy::too_many_arguments)]
 fn sqlite_source(
@@ -1045,14 +1312,21 @@ fn sqlite_source(
     user: Option<&str>,
     redact: fpai_collect::Redact,
     // Distinct health key when one format has several live instances (Hermes,
-    // one database per profile). `None` reports under the format's own kind.
+    // one database per profile; and now any source with an extra path
+    // configured). `None` reports under the format's own kind.
     health_key: Option<String>,
+    // Agent-id namespace for an extra database. `None` for the default one.
+    label: Option<String>,
 ) {
     let spool_dir = spool_dir.to_path_buf();
     let environment = environment.to_string();
     let machine_id = machine_id.map(str::to_string);
     let user = user.map(str::to_string);
-    tasks.push(fpai_collect::TaskSpec::new(name, move |sd| {
+    let task_name: String = match &label {
+        Some(l) => format!("{name}:{l}"),
+        None => name.to_string(),
+    };
+    tasks.push(fpai_collect::TaskSpec::new(task_name, move |sd| {
         fpai_collect::sqlitepoll::run(
             fpai_collect::sqlitepoll::Spec {
                 format,
@@ -1065,6 +1339,7 @@ fn sqlite_source(
                     environment: environment.clone(),
                     machine_id: machine_id.clone(),
                     user: user.clone(),
+                    label: label.clone(),
                     redact,
                     max_rows_per_poll: 2000,
                     max_batch_bytes: fpai_collect::spool::DEFAULT_MAX_BATCH_BYTES,
diff --git a/crates/fpai-collect/src/config.rs b/crates/fpai-collect/src/config.rs
index 311ae113..297f7a67 100644
--- a/crates/fpai-collect/src/config.rs
+++ b/crates/fpai-collect/src/config.rs
@@ -23,6 +23,7 @@
 //! transcripts carry prompts, file contents and whatever the user pasted into
 //! a terminal — configuring a key must not silently start shipping those.
 
+use std::collections::BTreeMap;
 use std::fs;
 use std::io;
 use std::path::{Path, PathBuf};
@@ -150,6 +151,28 @@ pub struct Settings {
     /// this field existed; such events carry no machine.
     #[serde(default)]
     pub machine_id: Option<String>,
+    /// Per-source extra capture paths, keyed by source name (`claude`,
+    /// `hermes`, …) — `[collector.sources.<name>]` in `config.toml`.
+    ///
+    /// A map rather than a struct with 13 fields: the source list is data, not
+    /// schema, and a struct would mean a newly added source silently ignoring
+    /// its own config key until somebody remembered to add the field. An
+    /// unrecognised key here is caught by the caller, which knows the real
+    /// source list, and reported rather than dropped — a typo'd `[collector.
+    /// sources.claud]` that parsed cleanly and captured nothing is exactly the
+    /// silent failure this project exists to remove.
+    #[serde(default)]
+    pub sources: BTreeMap<String, SourceSettings>,
+}
+
+/// The `[collector.sources.<name>]` table.
+#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, Serialize)]
+pub struct SourceSettings {
+    /// Extra locations to capture, each `label=path` or bare `path`. Resolved
+    /// by [`crate::extra_paths::resolve`]; see that module for the grammar and
+    /// for what each rejection prevents.
+    #[serde(default)]
+    pub extra_paths: Vec<String>,
 }
 
 fn default_true() -> bool {
@@ -169,10 +192,58 @@ impl Default for Settings {
             redact: Redact::default(),
             environment: default_environment(),
             machine_id: None,
+            sources: BTreeMap::new(),
         }
     }
 }
 
+impl Settings {
+    /// Raw `extra_paths` entries for one source, env override winning whole.
+    ///
+    /// `FAILPROOFAI_<SOURCE>_EXTRA_PATHS`, comma-separated — the same
+    /// env → file → default precedence as every other knob here, and the same
+    /// env name shape AgentEye's collector uses (`AGENTEYE_HERMES_EXTRA_PATHS`).
+    /// It REPLACES the file's list rather than appending to it: a container that
+    /// sets the variable is describing that container's whole layout, and
+    /// silently inheriting a host path from a mounted config would capture a
+    /// directory the operator never asked for.
+    ///
+    /// The source name is upper-cased with `-` mapped to `_`, so
+    /// `claude-subagent` reads `FAILPROOFAI_CLAUDE_SUBAGENT_EXTRA_PATHS`.
+    pub fn extra_paths_for(&self, source: &str) -> Vec<String> {
+        let var = format!(
+            "FAILPROOFAI_{}_EXTRA_PATHS",
+            source.to_ascii_uppercase().replace('-', "_")
+        );
+        if let Some(raw) = env_nonempty(&var) {
+            return raw
+                .split(',')
+                .map(str::trim)
+                .filter(|s| !s.is_empty())
+                .map(str::to_string)
+                .collect();
+        }
+        self.sources
+            .get(source)
+            .map(|s| s.extra_paths.clone())
+            .unwrap_or_default()
+    }
+
+    /// Configured source names that are not in `known`.
+    ///
+    /// Returned rather than warned about here so the caller — which owns the
+    /// real source list — decides how loud to be. A typo'd table parses fine
+    /// and captures nothing, and nothing else in the pipeline would ever
+    /// mention it.
+    pub fn unknown_sources(&self, known: &[&str]) -> Vec<String> {
+        self.sources
+            .keys()
+            .filter(|k| !known.contains(&k.as_str()))
+            .cloned()
+            .collect()
+    }
+}
+
 /// Everything the collector needs, resolved.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CollectorConfig {
@@ -492,3 +563,172 @@ fn tighten_home(home: &Path) {
 
 #[cfg(not(unix))]
 fn tighten_home(_home: &Path) {}
+
+#[cfg(test)]
+mod extra_path_settings_tests {
+    use super::*;
+
+    /// The exact bytes `writeConfig` in `src/hooks/fp-config.ts` produces after
+    /// two `failproofai harness add-path` runs, captured from a live CLI
+    /// invocation rather than hand-written.
+    ///
+    /// This is the seam with nothing holding it together: the TypeScript CLI
+    /// writes this file and the Rust daemon reads it, and neither is generated
+    /// from the other. Both halves parse cleanly on their own while disagreeing
+    /// — which is how `[collector]` came to be snake_case at all (it was
+    /// camelCase under `policies-config.json`, and carrying that over would have
+    /// meant every field silently falling back to its default).
+    ///
+    /// The sub-table placement is load-bearing and is the other reason this is
+    /// verbatim: TOML requires `[collector.sources.*]` AFTER every scalar of
+    /// `[collector]`, and a writer that emitted them earlier would produce a
+    /// file where `environment` and `redact` silently belong to a sub-table.
+    const WRITTEN_BY_THE_CLI: &str = r#"# failproofai configuration. Safe to edit by hand.
+# Credentials are NOT here — see credentials.toml (owner-only).
+
+[mode]
+kind = "oss"
+
+[daemon]
+configured = false
+
+[collector]
+# Session transcripts carry prompts, file contents and command output.
+sessions = true
+# Hook decisions: which policy fired and what it decided. No file contents.
+hooks = true
+hooks_verbosity = "decisions"
+redact = "minimal"
+environment = "local"
+machine_id = "m-123"
+
+[collector.sources.claude]
+# Extra locations to capture for this harness, beyond its default one.
+extra_paths = ["work=/srv/team/.claude/projects"]
+
+[collector.sources.hermes]
+extra_paths = ["/srv/hermes-prod/state.db", "b=/srv/other.db"]
+
+[audit]
+auto = false
+interval_days = 7
+"#;
+
+    fn home_with(text: &str) -> tempdir::Dir {
+        let d = tempdir::Dir::new();
+        fs::write(d.path().join(CONFIG_FILE), text).unwrap();
+        d
+    }
+
+    /// A minimal scratch directory; the crate has no dev-dep on `tempfile`.
+    mod tempdir {
+        use std::path::{Path, PathBuf};
+        pub struct Dir(PathBuf);
+        impl Dir {
+            pub fn new() -> Self {
+                let p = std::env::temp_dir().join(format!(
+                    "fpai-cfg-{}-{}",
+                    std::process::id(),
+                    std::time::SystemTime::now()
+                        .duration_since(std::time::UNIX_EPOCH)
+                        .unwrap()
+                        .as_nanos()
+                ));
+                std::fs::create_dir_all(&p).unwrap();
+                Dir(p)
+            }
+            pub fn path(&self) -> &Path {
+                &self.0
+            }
+        }
+        impl Drop for Dir {
+            fn drop(&mut self) {
+                let _ = std::fs::remove_dir_all(&self.0);
+            }
+        }
+    }
+
+    #[test]
+    fn reads_the_sources_tables_the_typescript_cli_writes() {
+        let d = home_with(WRITTEN_BY_THE_CLI);
+        let s = load_settings(d.path()).unwrap();
+
+        // The scalars after which the sub-tables appear must NOT have been
+        // swallowed into one.
+        assert!(s.sessions, "sessions was lost to a sub-table");
+        assert_eq!(s.environment, "local");
+        assert_eq!(s.machine_id.as_deref(), Some("m-123"));
+
+        assert_eq!(
+            s.extra_paths_for("claude"),
+            vec!["work=/srv/team/.claude/projects".to_string()]
+        );
+        assert_eq!(
+            s.extra_paths_for("hermes"),
+            vec![
+                "/srv/hermes-prod/state.db".to_string(),
+                "b=/srv/other.db".to_string()
+            ]
+        );
+        assert!(s.extra_paths_for("codex").is_empty());
+        assert!(s.unknown_sources(&["claude", "hermes"]).is_empty());
+    }
+
+    #[test]
+    fn a_config_with_no_sources_table_reads_as_none_configured() {
+        let d = home_with("[collector]\nsessions = true\n");
+        let s = load_settings(d.path()).unwrap();
+        assert!(s.sources.is_empty());
+        for h in ["claude", "hermes", "codex"] {
+            assert!(s.extra_paths_for(h).is_empty());
+        }
+    }
+
+    #[test]
+    fn an_unrecognised_source_table_is_reported_rather_than_ignored() {
+        let d = home_with("[collector]\n[collector.sources.claud]\nextra_paths = [\"/srv/x\"]\n");
+        let s = load_settings(d.path()).unwrap();
+        assert_eq!(s.unknown_sources(&["claude"]), vec!["claud".to_string()]);
+    }
+
+    /// The env override REPLACES the file's list. A container setting it is
+    /// describing that container's whole layout; inheriting a host path from a
+    /// mounted config would capture a directory nobody asked for.
+    #[test]
+    fn the_env_override_replaces_the_file_and_splits_on_commas() {
+        let d = home_with(WRITTEN_BY_THE_CLI);
+        let s = load_settings(d.path()).unwrap();
+        // SAFETY: single-threaded test; restored before returning.
+        unsafe {
+            std::env::set_var("FAILPROOFAI_CLAUDE_EXTRA_PATHS", " a=/one , b=/two ,, ");
+        }
+        assert_eq!(
+            s.extra_paths_for("claude"),
+            vec!["a=/one".to_string(), "b=/two".to_string()]
+        );
+        unsafe {
+            std::env::remove_var("FAILPROOFAI_CLAUDE_EXTRA_PATHS");
+        }
+        // ...and falls back to the file once it is gone.
+        assert_eq!(
+            s.extra_paths_for("claude"),
+            vec!["work=/srv/team/.claude/projects".to_string()]
+        );
+    }
+
+    /// A source whose name contains `-` must map to a legal env var name.
+    #[test]
+    fn a_hyphenated_source_name_maps_to_an_underscored_env_var() {
+        let s = Settings::default();
+        unsafe {
+            std::env::set_var("FAILPROOFAI_CLAUDE_SUBAGENT_EXTRA_PATHS", "/srv/sub");
+        }
+        assert_eq!(
+            s.extra_paths_for("claude-subagent"),
+            vec!["/srv/sub".to_string()]
+        );
+        unsafe {
+            std::env::remove_var("FAILPROOFAI_CLAUDE_SUBAGENT_EXTRA_PATHS");
+        }
+    }
+}
diff --git a/crates/fpai-collect/src/extra_paths.rs b/crates/fpai-collect/src/extra_paths.rs
new file mode 100644
index 00000000..04ba8046
--- /dev/null
+++ b/crates/fpai-collect/src/extra_paths.rs
@@ -0,0 +1,370 @@
+//! User-supplied extra capture paths, one set per source.
+//!
+//! Every source watches one default location — `~/.claude/projects`,
+//! `~/.hermes/state.db`, and so on. That is right for the machine the agent was
+//! installed on by its own installer, and wrong for every arrangement that puts
+//! a second copy somewhere else: a second profile, a bind-mounted team share, a
+//! container's home mapped in beside the host's, an agent relocated by an
+//! operator. Those paths hold real sessions and nothing collected them.
+//!
+//! # A labelled path, not just a path
+//!
+//! Each entry is `label=path` or bare `path`, and the label becomes an agent-id
+//! namespace — `<label>-<agentId>`. Without it two paths holding the same
+//! project produce the same derived agent id (`claude-myrepo` from the `cwd`
+//! inside the transcript, which is identical in both copies) and the product
+//! shows one agent whose sessions interleave from two machines' worth of
+//! history. The label is the only thing that keeps them apart, so it is part of
+//! the grammar rather than an option.
+//!
+//! This matches the shape AgentEye's collector already ships for its own two
+//! multi-path sources (`--openclaw-extra-path`, `--hermes-extra-path`): same
+//! `label=path` grammar, same folder-name fallback, same `<label>-<agentId>`
+//! namespacing. Diverging would have meant one product with two answers for
+//! what an extra path is.
+//!
+//! # What is rejected, and why each one is silent otherwise
+//!
+//! Validation is deliberately loud, because every failure here is invisible at
+//! runtime:
+//!
+//! * **A path that overlaps a default root** would be walked by two tasks with
+//!   two cursor stores. Both ship every line, under two different agent ids,
+//!   forever — and it looks like the feature working.
+//! * **Two entries with the same label** collapse into one cursor directory,
+//!   whose whole map is written atomically, so the two tasks clobber each
+//!   other's watermark and each re-reads from zero after every restart.
+//! * **An empty label** produces `-<agentId>`, which reads as a typo in the
+//!   product and groups nothing.
+
+use std::collections::BTreeSet;
+use std::path::{Path, PathBuf};
+
+/// One resolved extra path.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExtraPath {
+    /// Agent-id namespace. Non-empty, `[a-z0-9-]`, unique within its source.
+    pub label: String,
+    /// Where to capture from. A directory for file-tailing sources, a database
+    /// file for SQLite ones — this module does not know or care which, and
+    /// deliberately does NOT require it to exist: an entry for a share that is
+    /// mounted later must survive a daemon start, exactly like the default
+    /// roots, which are also allowed to be absent.
+    pub path: PathBuf,
+}
+
+/// A rejected entry, kept rather than dropped so the caller can log it.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Rejected {
+    pub entry: String,
+    pub reason: String,
+}
+
+/// Everything one source's `extra_paths` resolved to.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Resolved {
+    pub accepted: Vec<ExtraPath>,
+    pub rejected: Vec<Rejected>,
+}
+
+/// Reduce a raw label to the alphabet agent ids use.
+///
+/// Mirrors the sanitising the transforms already apply to derived id parts, so
+/// a label cannot introduce a character the rest of the pipeline would have
+/// stripped anyway — which would make the configured label and the label in the
+/// product differ.
+fn sanitize_label(raw: &str) -> String {
+    let mut out = String::with_capacity(raw.len());
+    let mut last_dash = true; // leading dashes are trimmed by starting true
+    for ch in raw.chars() {
+        let c = ch.to_ascii_lowercase();
+        if c.is_ascii_alphanumeric() {
+            out.push(c);
+            last_dash = false;
+        } else if !last_dash {
+            out.push('-');
+            last_dash = true;
+        }
+    }
+    while out.ends_with('-') {
+        out.pop();
+    }
+    out
+}
+
+/// Label for an entry that did not name one: the final path component.
+///
+/// Leading dots are stripped first so `/srv/.hermes-1` derives `hermes-1`
+/// rather than `-hermes-1`. A path whose last component sanitises to nothing
+/// (`/`, `/...`) yields `None` and the entry is rejected — guessing a label for
+/// it would silently group unrelated captures together.
+fn derive_label(path: &Path) -> Option<String> {
+    let name = path.file_name()?.to_str()?;
+    let label = sanitize_label(name.trim_start_matches('.'));
+    (!label.is_empty()).then_some(label)
+}
+
+/// Split one entry into its label and path halves.
+///
+/// Splits on the FIRST `=`, so a path containing `=` still works when a label
+/// is given. A bare path containing `=` is ambiguous and resolves as
+/// `label=path`; that is the documented grammar and the reason `list` prints
+/// the resolved pair back.
+fn split_entry(entry: &str) -> (Option<&str>, &str) {
+    match entry.split_once('=') {
+        Some((label, path)) if !label.trim().is_empty() => (Some(label.trim()), path.trim()),
+        _ => (None, entry.trim()),
+    }
+}
+
+/// True when `a` and `b` are the same path or one contains the other.
+///
+/// Both are compared after `clean`, which is lexical — no symlink resolution
+/// and no `canonicalize`, because a path is allowed to be absent and
+/// `canonicalize` fails on those. So a symlinked duplicate is NOT caught here;
+/// it is caught at runtime by the cursor store, which keys on `(dev, inode)`.
+fn overlaps(a: &Path, b: &Path) -> bool {
+    a.starts_with(b) || b.starts_with(a)
+}
+
+/// Expand `~` and drop a trailing separator so comparisons are stable.
+fn clean(raw: &str, home: Option<&Path>) -> PathBuf {
+    let expanded = match (raw.strip_prefix("~/"), home) {
+        (Some(rest), Some(home)) => home.join(rest),
+        _ if raw == "~" => home
+            .map(Path::to_path_buf)
+            .unwrap_or_else(|| PathBuf::from(raw)),
+        _ => PathBuf::from(raw),
+    };
+    // `PathBuf::from("/a/b/")` keeps the trailing slash in its OsString, which
+    // `starts_with` handles but `==` does not.
+    PathBuf::from(expanded.to_string_lossy().trim_end_matches('/').to_string())
+}
+
+/// Resolve one source's configured entries against its default roots.
+///
+/// `defaults` are the roots the source already watches. An entry overlapping
+/// any of them is rejected rather than silently double-collected.
+pub fn resolve(entries: &[String], defaults: &[PathBuf], home: Option<&Path>) -> Resolved {
+    let mut out = Resolved::default();
+    let mut seen_labels: BTreeSet<String> = BTreeSet::new();
+    let mut seen_paths: Vec<PathBuf> = Vec::new();
+
+    let defaults: Vec<PathBuf> = defaults
+        .iter()
+        .map(|d| clean(&d.to_string_lossy(), home))
+        .collect();
+
+    for entry in entries {
+        let raw = entry.trim();
+        if raw.is_empty() {
+            continue;
+        }
+        let (label_raw, path_raw) = split_entry(raw);
+        if path_raw.is_empty() {
+            out.rejected.push(Rejected {
+                entry: raw.to_string(),
+                reason: "no path".into(),
+            });
+            continue;
+        }
+        let path = clean(path_raw, home);
+
+        let label = match label_raw {
+            Some(l) => {
+                let s = sanitize_label(l);
+                if s.is_empty() {
+                    out.rejected.push(Rejected {
+                        entry: raw.to_string(),
+                        reason: format!("label {l:?} contains no usable characters"),
+                    });
+                    continue;
+                }
+                s
+            }
+            None => match derive_label(&path) {
+                Some(l) => l,
+                None => {
+                    out.rejected.push(Rejected {
+                        entry: raw.to_string(),
+                        reason: "no label given and none could be derived from the path".into(),
+                    });
+                    continue;
+                }
+            },
+        };
+
+        if let Some(clash) = defaults.iter().find(|d| overlaps(&path, d)) {
+            out.rejected.push(Rejected {
+                entry: raw.to_string(),
+                reason: format!(
+                    "overlaps the default root {}; it is already captured, and capturing it \
+                     twice ships every session under two agent ids",
+                    clash.display()
+                ),
+            });
+            continue;
+        }
+
+        if !seen_labels.insert(label.clone()) {
+            out.rejected.push(Rejected {
+                entry: raw.to_string(),
+                reason: format!(
+                    "label {label:?} is already used by another extra path for this source"
+                ),
+            });
+            continue;
+        }
+
+        if let Some(clash) = seen_paths.iter().find(|p| overlaps(&path, p)) {
+            out.rejected.push(Rejected {
+                entry: raw.to_string(),
+                reason: format!("overlaps another extra path, {}", clash.display()),
+            });
+            continue;
+        }
+
+        seen_paths.push(path.clone());
+        out.accepted.push(ExtraPath { label, path });
+    }
+
+    out
+}
+
+/// Prefix an agent id with a label. The one place the `<label>-<agentId>`
+/// convention is spelled out.
+pub fn namespaced(label: &str, agent_id: &str) -> String {
+    format!("{label}-{agent_id}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn e(items: &[&str]) -> Vec<String> {
+        items.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn bare_path_derives_its_label_from_the_final_component() {
+        let r = resolve(&e(["/srv/claude-work"].as_slice()), &[], None);
+        assert!(r.rejected.is_empty(), "{:?}", r.rejected);
+        assert_eq!(r.accepted[0].label, "claude-work");
+        assert_eq!(r.accepted[0].path, PathBuf::from("/srv/claude-work"));
+    }
+
+    #[test]
+    fn leading_dots_are_stripped_before_deriving() {
+        let r = resolve(&e(["/srv/.hermes-1"].as_slice()), &[], None);
+        assert_eq!(r.accepted[0].label, "hermes-1");
+    }
+
+    #[test]
+    fn explicit_label_wins_and_is_sanitized() {
+        let r = resolve(&e(["Team Share=/mnt/x"].as_slice()), &[], None);
+        assert_eq!(r.accepted[0].label, "team-share");
+        assert_eq!(r.accepted[0].path, PathBuf::from("/mnt/x"));
+    }
+
+    #[test]
+    fn a_path_containing_equals_still_works_with_an_explicit_label() {
+        let r = resolve(&e(["a=/mnt/k=v/x"].as_slice()), &[], None);
+        assert_eq!(r.accepted[0].path, PathBuf::from("/mnt/k=v/x"));
+    }
+
+    #[test]
+    fn tilde_expands_against_the_supplied_home() {
+        let home = PathBuf::from("/home/u");
+        let r = resolve(&e(["x=~/alt/projects"].as_slice()), &[], Some(&home));
+        assert_eq!(r.accepted[0].path, PathBuf::from("/home/u/alt/projects"));
+    }
+
+    #[test]
+    fn trailing_slash_does_not_defeat_the_overlap_check() {
+        let defaults = vec![PathBuf::from("/home/u/.claude/projects")];
+        let r = resolve(
+            &e(["a=/home/u/.claude/projects/"].as_slice()),
+            &defaults,
+            None,
+        );
+        assert!(r.accepted.is_empty());
+        assert!(r.rejected[0].reason.contains("overlaps the default root"));
+    }
+
+    /// The bug this exists to prevent: a path inside a default root is walked
+    /// by both tasks, so every line ships twice under two agent ids.
+    #[test]
+    fn a_path_nested_under_a_default_root_is_rejected() {
+        let defaults = vec![PathBuf::from("/home/u/.claude/projects")];
+        let r = resolve(
+            &e(["a=/home/u/.claude/projects/sub"].as_slice()),
+            &defaults,
+            None,
+        );
+        assert!(r.accepted.is_empty());
+        assert!(r.rejected[0].reason.contains("overlaps the default root"));
+    }
+
+    /// ...and the reverse: a default root nested under the extra path.
+    #[test]
+    fn a_path_containing_a_default_root_is_rejected() {
+        let defaults = vec![PathBuf::from("/home/u/.claude/projects")];
+        let r = resolve(&e(["a=/home/u/.claude"].as_slice()), &defaults, None);
+        assert!(r.accepted.is_empty());
+        assert!(r.rejected[0].reason.contains("overlaps the default root"));
+    }
+
+    #[test]
+    fn duplicate_labels_are_rejected_not_merged() {
+        let r = resolve(&e(["a=/srv/one", "a=/srv/two"].as_slice()), &[], None);
+        assert_eq!(r.accepted.len(), 1);
+        assert_eq!(r.accepted[0].path, PathBuf::from("/srv/one"));
+        assert!(r.rejected[0].reason.contains("already used"));
+    }
+
+    #[test]
+    fn two_extra_paths_that_overlap_each_other_are_rejected() {
+        let r = resolve(&e(["a=/srv/one", "b=/srv/one/two"].as_slice()), &[], None);
+        assert_eq!(r.accepted.len(), 1);
+        assert!(r.rejected[0].reason.contains("overlaps another extra path"));
+    }
+
+    #[test]
+    fn an_unusable_label_is_rejected_rather_than_emptied() {
+        let r = resolve(&e(["===/srv/x", "!!!=/srv/y"].as_slice()), &[], None);
+        // `===/srv/x` splits into label "" (falsy) -> bare path "==/srv/x".
+        // `!!!=/srv/y` has a label that sanitizes away.
+        assert!(
+            r.rejected
+                .iter()
+                .any(|x| x.reason.contains("no usable characters"))
+        );
+    }
+
+    #[test]
+    fn a_path_with_no_derivable_label_is_rejected() {
+        let r = resolve(&e(["/"].as_slice()), &[], None);
+        assert!(r.accepted.is_empty());
+        assert!(r.rejected[0].reason.contains("none could be derived"));
+    }
+
+    #[test]
+    fn blank_entries_are_skipped_silently() {
+        let r = resolve(&e(["", "   "].as_slice()), &[], None);
+        assert!(r.accepted.is_empty());
+        assert!(r.rejected.is_empty());
+    }
+
+    #[test]
+    fn a_missing_path_is_still_accepted() {
+        // Deliberate: a share mounted after the daemon starts must not be
+        // dropped at config-resolution time.
+        let r = resolve(&e(["a=/definitely/not/here"].as_slice()), &[], None);
+        assert_eq!(r.accepted.len(), 1);
+    }
+
+    #[test]
+    fn namespacing_is_label_dash_agent() {
+        assert_eq!(namespaced("work", "claude-myrepo"), "work-claude-myrepo");
+    }
+}
diff --git a/crates/fpai-collect/src/filetail.rs b/crates/fpai-collect/src/filetail.rs
index 2276c5e9..cf82fcbe 100644
--- a/crates/fpai-collect/src/filetail.rs
+++ b/crates/fpai-collect/src/filetail.rs
@@ -158,6 +158,13 @@ pub struct Params {
     /// Skip files older than this many days on first discovery. `None` reads
     /// everything, which on a normal machine is gigabytes of history.
     pub since_days: Option<u64>,
+    /// Agent-id namespace when this instance watches an EXTRA path rather than
+    /// the source's default root. `None` for the default instance.
+    ///
+    /// Threaded to `SpoolWriter::with_label`; see the field there for why the
+    /// prefix is applied at that choke point rather than where this engine
+    /// resolves the id.
+    pub label: Option<String>,
 }
 
 pub struct Spec {
@@ -167,10 +174,24 @@ pub struct Spec {
     pub state_dir: PathBuf,
     pub poll_interval: std::time::Duration,
     pub params: Params,
+    /// Key this instance reports health under. `None` uses `format.kind`.
+    ///
+    /// The same field `sqlitepoll::Spec` carries, added for the same reason and
+    /// with the same failure behind it: one format can now have several live
+    /// instances (a default root plus one per extra path), and every one of them
+    /// reporting under the bare kind makes `collector-health.json` alternate
+    /// `root_present` true/false as they overwrite each other — destroying the
+    /// "absent root versus idle source" distinction the record exists to draw.
+    /// Hermes hit exactly this with its per-profile databases.
+    pub health_key: Option<String>,
 }
 
 /// Tail every discovered file until shutdown.
 pub async fn run(spec: Spec, sd: Shutdown) -> Result<(), TaskError> {
+    let health_key = spec
+        .health_key
+        .clone()
+        .unwrap_or_else(|| spec.format.kind.to_string());
     let mut cursors = CursorStore::load(spec.state_dir.clone());
 
     // Log which roots actually exist. Without this an absent root is
@@ -194,7 +215,7 @@ pub async fn run(spec: Spec, sd: Shutdown) -> Result<(), TaskError> {
         match poll_once(&spec, &mut cursors).await {
             Ok(outcome) => {
                 crate::health::report_poll(
-                    spec.format.kind,
+                    &health_key,
                     spec.roots.iter().any(|r| r.exists()),
                     outcome.events,
                     cursors.len() as u64,
@@ -203,7 +224,7 @@ pub async fn run(spec: Spec, sd: Shutdown) -> Result<(), TaskError> {
                 // every file failed must not read as a clean one.
                 if let Some(err) = outcome.first_error {
                     crate::health::report_error(
-                        spec.format.kind,
+                        &health_key,
                         &format!(
                             "{} file(s) could not be processed; first: {err}",
                             outcome.failed
@@ -213,7 +234,7 @@ pub async fn run(spec: Spec, sd: Shutdown) -> Result<(), TaskError> {
             }
             Err(err) => {
                 tracing::warn!(source = spec.format.kind, %err, "poll failed; retrying next tick");
-                crate::health::report_error(spec.format.kind, &err.to_string());
+                crate::health::report_error(&health_key, &err.to_string());
             }
         }
         if !sd.sleep(spec.poll_interval).await {
@@ -366,6 +387,7 @@ async fn process_file(
         spec.format.kind,
         &ctx.session_id,
     )
+    .with_label(spec.params.label.clone())
     .with_machine_id(spec.params.machine_id.clone())
     .with_user(spec.params.user.clone())
     .with_redact(spec.params.redact);
diff --git a/crates/fpai-collect/src/lib.rs b/crates/fpai-collect/src/lib.rs
index 47347016..019cdd94 100644
--- a/crates/fpai-collect/src/lib.rs
+++ b/crates/fpai-collect/src/lib.rs
@@ -14,6 +14,7 @@
 pub mod config;
 pub mod cursor;
 pub mod delivery;
+pub mod extra_paths;
 pub mod filetail;
 pub mod health;
 pub mod redact;
@@ -23,8 +24,11 @@ pub mod sqlitepoll;
 pub mod supervisor;
 pub mod uploader;
 
-pub use config::{CollectorConfig, DEFAULT_INGEST_URL, HooksVerbosity, Ingest, Redact, Settings};
+pub use config::{
+    CollectorConfig, DEFAULT_INGEST_URL, HooksVerbosity, Ingest, Redact, Settings, SourceSettings,
+};
 pub use delivery::Delivery;
+pub use extra_paths::{ExtraPath, Resolved as ResolvedExtraPaths};
 pub use health::{Health, HealthFile, SourceHealth, health_path};
 pub use spool::SpoolWriter;
 pub use supervisor::{
diff --git a/crates/fpai-collect/src/spool.rs b/crates/fpai-collect/src/spool.rs
index 4a854d61..562774ac 100644
--- a/crates/fpai-collect/src/spool.rs
+++ b/crates/fpai-collect/src/spool.rs
@@ -70,6 +70,18 @@ pub struct SpoolWriter {
     /// same name on two machines never merges. `None` when it could not be
     /// resolved; such events simply carry no user.
     user: Option<String>,
+    /// Agent-id namespace for an extra capture path. `None` for a source
+    /// watching its default location, which is the overwhelming majority.
+    ///
+    /// Applied HERE rather than in each engine because the two engines resolve
+    /// agent ids in different places — `filetail` per discovered file, from the
+    /// path and header; `sqlitepoll` by handing `params.agent_id` to the
+    /// format, which may derive its own from a row (Hermes does). Prefixing
+    /// either one alone would namespace some events and not others from the
+    /// same path, which reads as two unrelated agents. This is the one point
+    /// every event from every source passes through, which is why `machine_id`
+    /// and `user` are stamped here too.
+    label: Option<String>,
 }
 
 impl SpoolWriter {
@@ -100,6 +112,7 @@ impl SpoolWriter {
             redacted: 0,
             machine_id: None,
             user: None,
+            label: None,
         }
     }
 
@@ -126,6 +139,16 @@ impl SpoolWriter {
         self
     }
 
+    /// Namespace every event's `agent_id` as `<label>-<agentId>`.
+    ///
+    /// An empty string is treated as absent, like the machine id and user
+    /// above: a blank label would produce `-claude-myrepo`, which groups
+    /// nothing and reads as a typo in the product.
+    pub fn with_label(mut self, label: Option<String>) -> Self {
+        self.label = label.filter(|s| !s.is_empty());
+        self
+    }
+
     /// How many string leaves have been scrubbed. Reported without ever
     /// logging what was removed.
     pub fn redacted_count(&self) -> u64 {
@@ -169,6 +192,26 @@ impl SpoolWriter {
                 .or_insert_with(|| Value::String(user.clone()));
         }
 
+        // Namespace the agent id for an extra capture path, at the same choke
+        // point and for the same reason. Unlike `machine_id` and `user` this
+        // REWRITES rather than filling a gap: the id is already present, set by
+        // the format from the path or the row, and two copies of one project in
+        // two locations derive the SAME id — which is precisely what the label
+        // exists to separate.
+        //
+        // Idempotent by construction is not available here (a project legitimately
+        // named `work-claude` would be indistinguishable from an already-prefixed
+        // id), so this must run exactly once per event. It does: every event
+        // reaches `push` once, and a re-shipped batch is re-read from the spool
+        // file rather than pushed again.
+        if let Some(label) = &self.label
+            && let Some(obj) = event.as_object_mut()
+            && let Some(id) = obj.get("agent_id").and_then(|v| v.as_str())
+        {
+            let namespaced = crate::extra_paths::namespaced(label, id);
+            obj.insert("agent_id".into(), Value::String(namespaced));
+        }
+
         let mut line = serialize(&event)?;
 
         if line.len() as u64 > self.max_batch_bytes {
diff --git a/crates/fpai-collect/src/sqlitepoll.rs b/crates/fpai-collect/src/sqlitepoll.rs
index cdff3fcb..782edc83 100644
--- a/crates/fpai-collect/src/sqlitepoll.rs
+++ b/crates/fpai-collect/src/sqlitepoll.rs
@@ -126,6 +126,14 @@ pub struct Params {
     /// Poll passes before yielding to the shutdown check. Bounds how long a
     /// backlog drain can ignore a stop request.
     pub max_drain_passes: u32,
+    /// Agent-id namespace when this instance polls an EXTRA database rather
+    /// than the source's default one. `None` for the default instance.
+    ///
+    /// Threaded to `SpoolWriter::with_label`. It must be applied there and not
+    /// by rewriting `agent_id` above, because a format's `poll` may derive its
+    /// own per-row ids from that value (Hermes does, via `SessionMeta`) — so a
+    /// prefix here would reach the fallback and miss every derived one.
+    pub label: Option<String>,
 }
 
 pub struct Spec {
@@ -238,12 +246,22 @@ async fn poll_once(spec: &Spec, cursors: &mut CursorStore) -> Result<(u64, bool)
         return Ok((0, outcome.more));
     }
 
+    // The tag carries the label so batches from a source's several instances
+    // are told apart in the shared spool directory, which is what the tag is
+    // for. Two instances would otherwise write `hermes-hermes-*` alike and only
+    // `run_id` would separate them — enough for correctness, useless for anyone
+    // reading the directory.
+    let tag = match &spec.params.label {
+        Some(label) => format!("{}-{label}", spec.format.kind),
+        None => spec.format.kind.to_string(),
+    };
     let mut writer = SpoolWriter::new(
         spec.spool_dir.clone(),
         spec.params.max_batch_bytes,
         spec.format.kind,
-        spec.format.kind,
+        &tag,
     )
+    .with_label(spec.params.label.clone())
     .with_machine_id(spec.params.machine_id.clone())
     .with_user(spec.params.user.clone())
     .with_redact(spec.params.redact);
diff --git a/crates/fpai-collect/src/supervisor.rs b/crates/fpai-collect/src/supervisor.rs
index c099ce4e..20314868 100644
--- a/crates/fpai-collect/src/supervisor.rs
+++ b/crates/fpai-collect/src/supervisor.rs
@@ -155,18 +155,24 @@ impl From<&str> for TaskError {
 /// future that already failed cannot be polled again, and reusing one would
 /// silently make "restart" mean "give up".
 pub struct TaskSpec {
-    pub name: &'static str,
+    /// Owned rather than `&'static str` because one source can now have several
+    /// live instances — a default root plus one task per configured extra path —
+    /// and their names are built at runtime (`claude:work`). Only ever used for
+    /// logging, never as a key, so duplicates would not have been a correctness
+    /// bug; they would just have made two instances indistinguishable in the
+    /// journal, which is where a multi-path problem is diagnosed.
+    pub name: String,
     factory: TaskFactory,
 }
 
 impl TaskSpec {
-    pub fn new<F, Fut>(name: &'static str, factory: F) -> Self
+    pub fn new<F, Fut>(name: impl Into<String>, factory: F) -> Self
     where
         F: Fn(Shutdown) -> Fut + Send + Sync + 'static,
         Fut: Future<Output = Result<(), TaskError>> + Send + 'static,
     {
         TaskSpec {
-            name,
+            name: name.into(),
             factory: Box::new(move |sd| Box::pin(factory(sd))),
         }
     }
@@ -348,13 +354,13 @@ async fn supervise_one(
             Ok(Ok(())) => {
                 // Finished its work. Not a failure, so no backoff — but also
                 // nothing to restart, so stop supervising it.
-                tracing::debug!(task = spec.name, "collector task completed");
+                tracing::debug!(task = %spec.name, "collector task completed");
                 return;
             }
             Ok(Err(err)) => {
                 metrics.failures.fetch_add(1, Ordering::Relaxed);
                 tracing::warn!(
-                    task = spec.name,
+                    task = %spec.name,
                     %err,
                     retry_in_ms = backoff.as_millis() as u64,
                     "collector task failed; restarting"
@@ -365,7 +371,7 @@ async fn supervise_one(
                 // Logged at error, not warn: an Err is usually the
                 // environment, a panic is always a bug worth chasing.
                 tracing::error!(
-                    task = spec.name,
+                    task = %spec.name,
                     panic = %panic_msg,
                     retry_in_ms = backoff.as_millis() as u64,
                     "collector task PANICKED; contained and restarting. Enforcement is unaffected"
diff --git a/crates/fpai-collect/tests/antigravity_source.rs b/crates/fpai-collect/tests/antigravity_source.rs
index bf0c9bc3..5defe58c 100644
--- a/crates/fpai-collect/tests/antigravity_source.rs
+++ b/crates/fpai-collect/tests/antigravity_source.rs
@@ -296,6 +296,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
         spool_dir: spool,
         state_dir: state,
         poll_interval: Duration::from_millis(200),
+        health_key: None,
         params: Params {
             redact: fpai_collect::Redact::Minimal,
             agent_id: antigravity::DEFAULT_AGENT_ID.into(),
@@ -306,6 +307,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
             max_read_bytes: 8 * 1024 * 1024,
             max_batch_bytes: 8 * 1024 * 1024,
             since_days: None,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/claude_source.rs b/crates/fpai-collect/tests/claude_source.rs
index e496bd1e..fbaa8d75 100644
--- a/crates/fpai-collect/tests/claude_source.rs
+++ b/crates/fpai-collect/tests/claude_source.rs
@@ -504,6 +504,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
         spool_dir: spool,
         state_dir: state,
         poll_interval: Duration::from_millis(200),
+        health_key: None,
         params: Params {
             redact: fpai_collect::Redact::Minimal,
             agent_id: claude::DEFAULT_AGENT_ID.into(),
@@ -514,6 +515,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
             max_read_bytes: 8 * 1024 * 1024,
             max_batch_bytes: 8 * 1024 * 1024,
             since_days: None,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/claude_subagents.rs b/crates/fpai-collect/tests/claude_subagents.rs
index 5449999a..d9357276 100644
--- a/crates/fpai-collect/tests/claude_subagents.rs
+++ b/crates/fpai-collect/tests/claude_subagents.rs
@@ -269,6 +269,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
         spool_dir: spool,
         state_dir: state,
         poll_interval: Duration::from_millis(200),
+        health_key: None,
         params: Params {
             redact: fpai_collect::Redact::Minimal,
             agent_id: claude::SUBAGENT_DEFAULT_AGENT_ID.into(),
@@ -279,6 +280,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
             max_read_bytes: 8 * 1024 * 1024,
             max_batch_bytes: 8 * 1024 * 1024,
             since_days: None,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/codex_source.rs b/crates/fpai-collect/tests/codex_source.rs
index 189bb16d..ffa78db1 100644
--- a/crates/fpai-collect/tests/codex_source.rs
+++ b/crates/fpai-collect/tests/codex_source.rs
@@ -724,6 +724,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
         spool_dir: spool,
         state_dir: state,
         poll_interval: Duration::from_millis(200),
+        health_key: None,
         params: Params {
             redact: fpai_collect::Redact::Minimal,
             agent_id: codex::DEFAULT_AGENT_ID.into(),
@@ -734,6 +735,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
             max_read_bytes: 8 * 1024 * 1024,
             max_batch_bytes: 8 * 1024 * 1024,
             since_days: None,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/copilot_source.rs b/crates/fpai-collect/tests/copilot_source.rs
index d88f2f73..e584bc61 100644
--- a/crates/fpai-collect/tests/copilot_source.rs
+++ b/crates/fpai-collect/tests/copilot_source.rs
@@ -770,6 +770,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
         spool_dir: spool,
         state_dir: state,
         poll_interval: Duration::from_millis(200),
+        health_key: None,
         params: Params {
             redact: fpai_collect::Redact::Minimal,
             agent_id: copilot::DEFAULT_AGENT_ID.into(),
@@ -780,6 +781,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
             max_read_bytes: 8 * 1024 * 1024,
             max_batch_bytes: 8 * 1024 * 1024,
             since_days: None,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/cursor_source.rs b/crates/fpai-collect/tests/cursor_source.rs
index 3ccef45f..e57b1770 100644
--- a/crates/fpai-collect/tests/cursor_source.rs
+++ b/crates/fpai-collect/tests/cursor_source.rs
@@ -173,6 +173,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
         spool_dir: spool,
         state_dir: state,
         poll_interval: Duration::from_millis(200),
+        health_key: None,
         params: Params {
             redact: fpai_collect::Redact::Minimal,
             agent_id: cursor::DEFAULT_AGENT_ID.into(),
@@ -183,6 +184,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
             max_read_bytes: 8 * 1024 * 1024,
             max_batch_bytes: 8 * 1024 * 1024,
             since_days: None,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/devin_source.rs b/crates/fpai-collect/tests/devin_source.rs
index ee7ccc46..1d5ff7b0 100644
--- a/crates/fpai-collect/tests/devin_source.rs
+++ b/crates/fpai-collect/tests/devin_source.rs
@@ -678,6 +678,7 @@ fn spec(db: &Path, spool: PathBuf, state: PathBuf) -> Spec {
             max_rows_per_poll: 500,
             max_batch_bytes: 8 * 1024 * 1024,
             max_drain_passes: 8,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/extra_paths_engine.rs b/crates/fpai-collect/tests/extra_paths_engine.rs
new file mode 100644
index 00000000..72892fc8
--- /dev/null
+++ b/crates/fpai-collect/tests/extra_paths_engine.rs
@@ -0,0 +1,570 @@
+//! Extra capture paths, end to end through the real engines.
+//!
+//! The unit tests in `extra_paths.rs` cover the grammar. These cover the thing
+//! the grammar exists for: that a second location is captured with the same
+//! fidelity as the default one, that the two do not contaminate each other, and
+//! that a machine with no extra path configured behaves exactly as it did
+//! before this feature existed.
+//!
+//! Every assertion here failed before the feature landed, and the interesting
+//! ones fail for a DIFFERENT reason than "the field does not exist": with the
+//! label threaded only into `filetail`'s own agent-id resolution rather than
+//! into `SpoolWriter`, `two_paths_holding_the_same_project_do_not_merge` still
+//! passes for the file engine and `a_sqlite_extra_path_namespaces_derived_ids`
+//! silently does not — which is exactly the split the choke-point placement
+//! exists to prevent.
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+use std::sync::atomic::AtomicBool;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use fpai_collect::filetail::{self, Params, Spec};
+use fpai_collect::sources::claude;
+use fpai_collect::supervisor::Shutdown;
+use serde_json::Value;
+
+const UUID_A: &str = "fb9f0d4f-f739-4069-ac16-9add45fd2506";
+const UUID_B: &str = "aa9f0d4f-f739-4069-ac16-9add45fd2507";
+
+fn tmpdir(name: &str) -> PathBuf {
+    let d = std::env::temp_dir().join(format!(
+        "fpai-xp-{}-{}-{}",
+        name,
+        std::process::id(),
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_nanos()
+    ));
+    fs::create_dir_all(&d).unwrap();
+    d
+}
+
+fn spec(roots: Vec<PathBuf>, spool: PathBuf, state: PathBuf, label: Option<&str>) -> Spec {
+    Spec {
+        format: claude::FORMAT,
+        roots,
+        spool_dir: spool,
+        state_dir: state,
+        poll_interval: Duration::from_millis(150),
+        health_key: label.map(|l| format!("claude:{l}")),
+        params: Params {
+            redact: fpai_collect::Redact::Minimal,
+            agent_id: claude::DEFAULT_AGENT_ID.into(),
+            environment: "local".into(),
+            machine_id: None,
+            user: None,
+            end_idle_mins: 0,
+            max_read_bytes: 8 * 1024 * 1024,
+            max_batch_bytes: 8 * 1024 * 1024,
+            since_days: None,
+            label: label.map(str::to_string),
+        },
+    }
+}
+
+async fn run_briefly(s: Spec, ms: u64) {
+    let sd = Shutdown::for_test(Arc::new(AtomicBool::new(false)));
+    let _ = tokio::time::timeout(Duration::from_millis(ms), filetail::run(s, sd)).await;
+}
+
+fn spooled(dir: &Path) -> Vec<Value> {
+    let mut out = Vec::new();
+    let Ok(rd) = fs::read_dir(dir) else {
+        return out;
+    };
+    for e in rd.filter_map(|e| e.ok()) {
+        let p = e.path();
+        if p.extension().and_then(|x| x.to_str()) != Some("jsonl") {
+            continue;
+        }
+        for l in fs::read_to_string(&p).unwrap().lines() {
+            if !l.trim().is_empty() {
+                out.push(serde_json::from_str(l).unwrap());
+            }
+        }
+    }
+    out
+}
+
+/// A real Claude transcript, with `cwd` controlling the derived agent id.
+fn write_session(root: &Path, project_cwd: &str, uuid: &str, prompts: &[&str]) -> PathBuf {
+    let slug = project_cwd.replace('/', "-");
+    let proj = root.join(slug);
+    fs::create_dir_all(&proj).unwrap();
+    let mut lines = Vec::new();
+    for (i, p) in prompts.iter().enumerate() {
+        lines.push(
+            serde_json::json!({
+                "type": "user",
+                "timestamp": format!("2026-07-18T09:4{}:04.058Z", i.min(9)),
+                "cwd": project_cwd,
+                "message": {"role": "user", "content": p},
+            })
+            .to_string(),
+        );
+    }
+    let f = proj.join(format!("{uuid}.jsonl"));
+    fs::write(&f, lines.join("\n") + "\n").unwrap();
+    f
+}
+
+fn agent_ids(events: &[Value]) -> Vec<String> {
+    let mut v: Vec<String> = events
+        .iter()
+        .filter_map(|e| e["agent_id"].as_str().map(str::to_string))
+        .collect();
+    v.sort();
+    v.dedup();
+    v
+}
+
+// ── the regression that matters most ─────────────────────────────────────
+
+/// A machine with nothing configured must be byte-for-byte what it was.
+///
+/// `label: None` is the overwhelmingly common case, and the whole feature is
+/// worthless if it costs anything there.
+#[tokio::test(flavor = "multi_thread")]
+async fn default_path_only_is_unchanged_by_the_feature_existing() {
+    let root = tmpdir("def-root");
+    let spool = tmpdir("def-spool");
+    let state = tmpdir("def-state");
+    write_session(&root, "/home/u/myrepo", UUID_A, &["hello"]);
+
+    run_briefly(
+        spec(vec![root.clone()], spool.clone(), state.clone(), None),
+        900,
+    )
+    .await;
+
+    let ev = spooled(&spool);
+    assert!(!ev.is_empty(), "default root produced nothing");
+    assert_eq!(
+        agent_ids(&ev),
+        vec!["claude-myrepo".to_string()],
+        "an unlabelled instance must not namespace anything"
+    );
+    for e in &ev {
+        assert_eq!(e["session_id"], UUID_A);
+    }
+
+    fs::remove_dir_all(&root).ok();
+    fs::remove_dir_all(&spool).ok();
+    fs::remove_dir_all(&state).ok();
+}
+
+// ── the feature ──────────────────────────────────────────────────────────
+
+/// The core claim: an extra path is captured, and its ids are namespaced.
+#[tokio::test(flavor = "multi_thread")]
+async fn an_extra_path_is_captured_and_namespaced() {
+    let extra = tmpdir("x1-root");
+    let spool = tmpdir("x1-spool");
+    let state = tmpdir("x1-state");
+    write_session(&extra, "/srv/team/myrepo", UUID_A, &["from the share"]);
+
+    run_briefly(
+        spec(
+            vec![extra.clone()],
+            spool.clone(),
+            state.clone(),
+            Some("work"),
+        ),
+        900,
+    )
+    .await;
+
+    let ev = spooled(&spool);
+    assert!(!ev.is_empty(), "extra path produced nothing");
+    assert_eq!(agent_ids(&ev), vec!["work-claude-myrepo".to_string()]);
+
+    // Namespacing must not corrupt anything else on the event.
+    let types: Vec<&str> = ev.iter().filter_map(|e| e["type"].as_str()).collect();
+    assert!(types.contains(&"agent_start"), "got {types:?}");
+    for e in &ev {
+        assert_eq!(e["session_id"], UUID_A);
+    }
+
+    fs::remove_dir_all(&extra).ok();
+    fs::remove_dir_all(&spool).ok();
+    fs::remove_dir_all(&state).ok();
+}
+
+/// The reason the label is part of the grammar rather than optional.
+///
+/// Two locations holding the same project derive the SAME agent id, because it
+/// comes from the `cwd` recorded inside the transcript and both copies say the
+/// same thing. Without the label they merge into one agent whose sessions
+/// interleave from two unrelated machines' worth of history.
+#[tokio::test(flavor = "multi_thread")]
+async fn two_paths_holding_the_same_project_do_not_merge() {
+    let default_root = tmpdir("m-default");
+    let extra_root = tmpdir("m-extra");
+    let spool = tmpdir("m-spool");
+    let state_a = tmpdir("m-state-a");
+    let state_b = tmpdir("m-state-b");
+
+    // Same cwd in both, different session ids — exactly a laptop and a share
+    // holding checkouts of one repo.
+    write_session(&default_root, "/home/u/myrepo", UUID_A, &["local work"]);
+    write_session(&extra_root, "/home/u/myrepo", UUID_B, &["share work"]);
+
+    run_briefly(
+        spec(
+            vec![default_root.clone()],
+            spool.clone(),
+            state_a.clone(),
+            None,
+        ),
+        900,
+    )
+    .await;
+    run_briefly(
+        spec(
+            vec![extra_root.clone()],
+            spool.clone(),
+            state_b.clone(),
+            Some("share"),
+        ),
+        900,
+    )
+    .await;
+
+    let ev = spooled(&spool);
+    let ids = agent_ids(&ev);
+    assert_eq!(
+        ids,
+        vec![
+            "claude-myrepo".to_string(),
+            "share-claude-myrepo".to_string()
+        ],
+        "the two locations must stay distinct agents; got {ids:?}"
+    );
+
+    // And each id carries only its own session.
+    for e in &ev {
+        let id = e["agent_id"].as_str().unwrap();
+        let sid = e["session_id"].as_str().unwrap();
+        if id.starts_with("share-") {
+            assert_eq!(sid, UUID_B, "share events carried the local session");
+        } else {
+            assert_eq!(sid, UUID_A, "local events carried the share session");
+        }
+    }
+
+    for d in [&default_root, &extra_root, &spool, &state_a, &state_b] {
+        fs::remove_dir_all(d).ok();
+    }
+}
+
+/// Steady-state: several paths for one harness, tailed at the same time, with
+/// content appended while both are live.
+#[tokio::test(flavor = "multi_thread")]
+async fn three_simultaneous_paths_for_one_harness_all_tail() {
+    let a = tmpdir("s-a");
+    let b = tmpdir("s-b");
+    let c = tmpdir("s-c");
+    let spool = tmpdir("s-spool");
+    let (sa, sb, sc) = (tmpdir("s-st-a"), tmpdir("s-st-b"), tmpdir("s-st-c"));
+
+    write_session(&a, "/home/u/alpha", UUID_A, &["one"]);
+    write_session(&b, "/home/u/beta", UUID_B, &["two"]);
+    write_session(&c, "/home/u/gamma", UUID_A, &["three"]);
+
+    let sd = Shutdown::for_test(Arc::new(AtomicBool::new(false)));
+    let h1 = tokio::spawn(filetail::run(
+        spec(vec![a.clone()], spool.clone(), sa.clone(), None),
+        sd.clone(),
+    ));
+    let h2 = tokio::spawn(filetail::run(
+        spec(vec![b.clone()], spool.clone(), sb.clone(), Some("two")),
+        sd.clone(),
+    ));
+    let h3 = tokio::spawn(filetail::run(
+        spec(vec![c.clone()], spool.clone(), sc.clone(), Some("three")),
+        sd.clone(),
+    ));
+
+    tokio::time::sleep(Duration::from_millis(1100)).await;
+    for h in [h1, h2, h3] {
+        h.abort();
+    }
+
+    let ev = spooled(&spool);
+    let ids = agent_ids(&ev);
+    assert!(ids.contains(&"claude-alpha".to_string()), "got {ids:?}");
+    assert!(ids.contains(&"two-claude-beta".to_string()), "got {ids:?}");
+    assert!(
+        ids.contains(&"three-claude-gamma".to_string()),
+        "got {ids:?}"
+    );
+
+    // Each instance kept its own cursor store, so none is empty and none was
+    // clobbered by another. This is the failure the per-instance state dir
+    // exists to prevent: a shared store writes its whole map atomically, so the
+    // loser re-reads from zero after every restart.
+    for (d, who) in [(&sa, "default"), (&sb, "two"), (&sc, "three")] {
+        let has = fs::read_dir(d).map(|r| r.count() > 0).unwrap_or(false);
+        assert!(has, "{who} instance persisted no cursor of its own");
+    }
+
+    for d in [&a, &b, &c, &spool, &sa, &sb, &sc] {
+        fs::remove_dir_all(d).ok();
+    }
+}
+
+/// A path added to an ALREADY-RUNNING configuration backfills its history.
+///
+/// The mechanism is that the new instance has no cursor, so every file under it
+/// is a first discovery and is read from the start of the backfill window. This
+/// asserts the outcome rather than the mechanism: history written long before
+/// the path was registered still arrives.
+#[tokio::test(flavor = "multi_thread")]
+async fn a_newly_added_path_backfills_history_written_before_it_was_added() {
+    let default_root = tmpdir("bf-default");
+    let extra_root = tmpdir("bf-extra");
+    let spool = tmpdir("bf-spool");
+    let state_a = tmpdir("bf-state-a");
+    let state_b = tmpdir("bf-state-b");
+
+    // History that already existed on the share, with several turns so a
+    // partial read would be visible.
+    write_session(
+        &extra_root,
+        "/srv/archive/oldrepo",
+        UUID_B,
+        &["turn one", "turn two", "turn three"],
+    );
+    write_session(&default_root, "/home/u/myrepo", UUID_A, &["current"]);
+
+    // The machine as it was: default path only. The share is not captured.
+    run_briefly(
+        spec(
+            vec![default_root.clone()],
+            spool.clone(),
+            state_a.clone(),
+            None,
+        ),
+        900,
+    )
+    .await;
+    let before = agent_ids(&spooled(&spool));
+    assert_eq!(
+        before,
+        vec!["claude-myrepo".to_string()],
+        "the share must not be captured before it is registered"
+    );
+
+    // ...and now the operator registers it. A fresh instance, fresh cursor.
+    run_briefly(
+        spec(
+            vec![extra_root.clone()],
+            spool.clone(),
+            state_b.clone(),
+            Some("archive"),
+        ),
+        900,
+    )
+    .await;
+
+    let ev = spooled(&spool);
+    let after = agent_ids(&ev);
+    assert!(
+        after.contains(&"archive-claude-oldrepo".to_string()),
+        "history under the newly added path was not backfilled; got {after:?}"
+    );
+
+    // The pre-existing turns, not just an agent_start.
+    let prompts = ev
+        .iter()
+        .filter(|e| e["agent_id"] == "archive-claude-oldrepo")
+        .filter(|e| e["type"] == "model_request")
+        .count();
+    assert!(
+        prompts >= 3,
+        "only {prompts} of 3 historical turns backfilled"
+    );
+
+    for d in [&default_root, &extra_root, &spool, &state_a, &state_b] {
+        fs::remove_dir_all(d).ok();
+    }
+}
+
+/// Re-running an instance ships nothing new — the label must not defeat the
+/// cursor, which would re-ship the whole path on every poll forever.
+#[tokio::test(flavor = "multi_thread")]
+async fn a_labelled_instance_resumes_from_its_cursor() {
+    let extra = tmpdir("r-root");
+    let spool = tmpdir("r-spool");
+    let state = tmpdir("r-state");
+    write_session(&extra, "/srv/x/repo", UUID_A, &["hi"]);
+
+    run_briefly(
+        spec(vec![extra.clone()], spool.clone(), state.clone(), Some("w")),
+        900,
+    )
+    .await;
+    let first = spooled(&spool).len();
+    assert!(first > 0);
+
+    let spool2 = tmpdir("r-spool2");
+    run_briefly(
+        spec(
+            vec![extra.clone()],
+            spool2.clone(),
+            state.clone(),
+            Some("w"),
+        ),
+        900,
+    )
+    .await;
+    let second = spooled(&spool2);
+    let non_end: Vec<&Value> = second.iter().filter(|e| e["type"] != "agent_end").collect();
+    assert!(
+        non_end.is_empty(),
+        "a resumed labelled instance re-shipped {} events",
+        non_end.len()
+    );
+
+    for d in [&extra, &spool, &spool2, &state] {
+        fs::remove_dir_all(d).ok();
+    }
+}
+
+// ── the SQLite half ──────────────────────────────────────────────────────
+//
+// This is why the label is applied in `SpoolWriter::push` and not in either
+// engine. A SQLite format is handed `params.agent_id` as a FALLBACK and derives
+// the real id from the row — `devin::agent_id(working_directory, fallback)`
+// returns `devin-<project>` and never looks at the fallback for a session that
+// has a working directory, which is all of them. So prefixing `params.agent_id`
+// would namespace only the sessions that failed to derive an id: the rare ones,
+// and none of the ones anybody looks at.
+
+mod sqlite_half {
+    use super::{spooled, tmpdir};
+    use fpai_collect::sources::devin;
+    use fpai_collect::sqlitepoll::{self, Params, Spec};
+    use fpai_collect::supervisor::Shutdown;
+    use rusqlite::{Connection, params};
+    use std::path::{Path, PathBuf};
+    use std::sync::Arc;
+    use std::sync::atomic::AtomicBool;
+    use std::time::Duration;
+
+    const SCHEMA: &str = r#"
+CREATE TABLE sessions (
+    id TEXT PRIMARY KEY, working_directory TEXT NOT NULL, backend_type TEXT NOT NULL,
+    model TEXT NOT NULL, agent_mode TEXT NOT NULL, created_at INTEGER NOT NULL,
+    last_activity_at INTEGER NOT NULL, title TEXT, main_chain_id INTEGER,
+    shell_last_seen_index INTEGER DEFAULT 0, cogs_json TEXT, workspace_dirs TEXT,
+    hidden INTEGER NOT NULL DEFAULT 0, metadata TEXT);
+CREATE TABLE message_nodes (
+    row_id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL,
+    node_id INTEGER NOT NULL, parent_node_id INTEGER, chat_message TEXT NOT NULL,
+    created_at INTEGER NOT NULL, metadata TEXT,
+    FOREIGN KEY (session_id) REFERENCES sessions(id), UNIQUE(session_id, node_id));
+"#;
+
+    const T0: i64 = 1_785_396_633;
+    const ISO0: &str = "2026-07-30T07:30:33.500577515Z";
+
+    /// A Devin database holding one session in `working_dir`.
+    fn db_with(name: &str, working_dir: &str) -> (PathBuf, PathBuf) {
+        let dir = tmpdir(name);
+        let path = dir.join("sessions.db");
+        let conn = Connection::open(&path).unwrap();
+        conn.pragma_update(None, "journal_mode", "WAL").unwrap();
+        conn.execute_batch(SCHEMA).unwrap();
+        conn.execute(
+            "INSERT INTO sessions(id, working_directory, backend_type, model, agent_mode,
+                                  created_at, last_activity_at, hidden)
+             VALUES ('s1', ?1, 'anthropic', 'claude-sonnet-4-6', 'auto', ?2, ?2, 0)",
+            params![working_dir, T0],
+        )
+        .unwrap();
+        let msg = serde_json::json!({"role": "user", "content": "hello"}).to_string();
+        let meta = serde_json::json!({"created_at": ISO0}).to_string();
+        conn.execute(
+            "INSERT INTO message_nodes(session_id, node_id, chat_message, created_at, metadata)
+             VALUES ('s1', 1, ?1, ?2, ?3)",
+            params![msg, T0, meta],
+        )
+        .unwrap();
+        (dir, path)
+    }
+
+    fn spec(db: &Path, spool: PathBuf, state: PathBuf, label: Option<&str>) -> Spec {
+        Spec {
+            format: devin::FORMAT,
+            db_path: db.to_path_buf(),
+            spool_dir: spool,
+            state_dir: state,
+            poll_interval: Duration::from_millis(150),
+            health_key: label.map(|l| format!("devin:{l}")),
+            params: Params {
+                redact: fpai_collect::Redact::Minimal,
+                agent_id: devin::DEFAULT_AGENT_ID.into(),
+                environment: "local".into(),
+                machine_id: None,
+                user: None,
+                max_rows_per_poll: 500,
+                max_batch_bytes: 8 * 1024 * 1024,
+                max_drain_passes: 8,
+                label: label.map(str::to_string),
+            },
+        }
+    }
+
+    async fn run_briefly(s: Spec, ms: u64) {
+        let sd = Shutdown::for_test(Arc::new(AtomicBool::new(false)));
+        let _ = tokio::time::timeout(Duration::from_millis(ms), sqlitepoll::run(s, sd)).await;
+    }
+
+    /// The id the format DERIVES from the row is namespaced, not just the
+    /// fallback. Prefixing `params.agent_id` passes nothing here.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn a_sqlite_extra_path_namespaces_derived_ids() {
+        let (dir, db) = db_with("sq-x", "/srv/team/checkout");
+        let spool = tmpdir("sq-x-spool");
+        let state = tmpdir("sq-x-state");
+
+        run_briefly(spec(&db, spool.clone(), state.clone(), Some("team")), 900).await;
+
+        let ev = spooled(&spool);
+        assert!(!ev.is_empty(), "sqlite extra path produced nothing");
+        for e in &ev {
+            assert_eq!(
+                e["agent_id"], "team-devin-checkout",
+                "the DERIVED id must be namespaced, not just the fallback"
+            );
+        }
+
+        std::fs::remove_dir_all(&dir).ok();
+        std::fs::remove_dir_all(&spool).ok();
+        std::fs::remove_dir_all(&state).ok();
+    }
+
+    /// ...and an unlabelled SQLite instance is untouched.
+    #[tokio::test(flavor = "multi_thread")]
+    async fn a_default_sqlite_instance_is_not_namespaced() {
+        let (dir, db) = db_with("sq-d", "/home/u/checkout");
+        let spool = tmpdir("sq-d-spool");
+        let state = tmpdir("sq-d-state");
+
+        run_briefly(spec(&db, spool.clone(), state.clone(), None), 900).await;
+
+        let ev = spooled(&spool);
+        assert!(!ev.is_empty());
+        for e in &ev {
+            assert_eq!(e["agent_id"], "devin-checkout");
+        }
+
+        std::fs::remove_dir_all(&dir).ok();
+        std::fs::remove_dir_all(&spool).ok();
+        std::fs::remove_dir_all(&state).ok();
+    }
+}
diff --git a/crates/fpai-collect/tests/factory_source.rs b/crates/fpai-collect/tests/factory_source.rs
index dd1b1914..a20351b0 100644
--- a/crates/fpai-collect/tests/factory_source.rs
+++ b/crates/fpai-collect/tests/factory_source.rs
@@ -201,6 +201,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
         spool_dir: spool,
         state_dir: state,
         poll_interval: Duration::from_millis(200),
+        health_key: None,
         params: Params {
             redact: fpai_collect::Redact::Minimal,
             agent_id: factory::DEFAULT_AGENT_ID.into(),
@@ -211,6 +212,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
             max_read_bytes: 8 * 1024 * 1024,
             max_batch_bytes: 8 * 1024 * 1024,
             since_days: None,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/goose_source.rs b/crates/fpai-collect/tests/goose_source.rs
index ff2db33f..0a6e089a 100644
--- a/crates/fpai-collect/tests/goose_source.rs
+++ b/crates/fpai-collect/tests/goose_source.rs
@@ -878,6 +878,7 @@ fn spec(db: &Path, spool: PathBuf, state: PathBuf) -> Spec {
             max_rows_per_poll: 500,
             max_batch_bytes: 8 * 1024 * 1024,
             max_drain_passes: 8,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/hermes_source.rs b/crates/fpai-collect/tests/hermes_source.rs
index 0e987e4f..e76b3293 100644
--- a/crates/fpai-collect/tests/hermes_source.rs
+++ b/crates/fpai-collect/tests/hermes_source.rs
@@ -1000,6 +1000,7 @@ fn spec(db: PathBuf, spool: PathBuf, state: PathBuf) -> sqlitepoll::Spec {
             max_rows_per_poll: 500,
             max_batch_bytes: 8 * 1024 * 1024,
             max_drain_passes: 8,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/openclaw_source.rs b/crates/fpai-collect/tests/openclaw_source.rs
index 23c337b6..39f51ec0 100644
--- a/crates/fpai-collect/tests/openclaw_source.rs
+++ b/crates/fpai-collect/tests/openclaw_source.rs
@@ -572,6 +572,7 @@ fn spec(base: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
         spool_dir: spool,
         state_dir: state,
         poll_interval: Duration::from_millis(200),
+        health_key: None,
         params: Params {
             redact: fpai_collect::Redact::Minimal,
             agent_id: openclaw::DEFAULT_AGENT_ID.into(),
@@ -582,6 +583,7 @@ fn spec(base: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
             max_read_bytes: 8 * 1024 * 1024,
             max_batch_bytes: 8 * 1024 * 1024,
             since_days: None,
+            label: None,
         },
     }
 }
diff --git a/crates/fpai-collect/tests/pi_source.rs b/crates/fpai-collect/tests/pi_source.rs
index 45d3c6b7..b7bda69d 100644
--- a/crates/fpai-collect/tests/pi_source.rs
+++ b/crates/fpai-collect/tests/pi_source.rs
@@ -779,6 +779,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
         spool_dir: spool,
         state_dir: state,
         poll_interval: Duration::from_millis(200),
+        health_key: None,
         params: Params {
             redact: fpai_collect::Redact::Minimal,
             agent_id: pi::DEFAULT_AGENT_ID.into(),
@@ -789,6 +790,7 @@ fn spec(root: PathBuf, spool: PathBuf, state: PathBuf) -> Spec {
             max_read_bytes: 8 * 1024 * 1024,
             max_batch_bytes: 8 * 1024 * 1024,
             since_days: None,
+            label: None,
         },
     }
 }
diff --git a/src/hooks/fp-config.ts b/src/hooks/fp-config.ts
index d220002f..504e5778 100644
--- a/src/hooks/fp-config.ts
+++ b/src/hooks/fp-config.ts
@@ -159,6 +159,25 @@ export interface FpConfig {
     redact: "minimal" | "off";
     environment: string;
     machineId?: string;
+    /**
+     * Extra locations to capture per harness, beyond the one each source ships
+     * with — `[collector.sources.<harness>] extra_paths` in `config.toml`.
+     *
+     * Each entry is `label=path` or a bare `path`; the label becomes an agent-id
+     * namespace (`<label>-<agentId>`), which is what keeps two copies of one
+     * project from merging into a single agent. The daemon is the authority on
+     * the grammar and on which harness names are real — see
+     * `crates/fpai-collect/src/extra_paths.rs` and `HARNESS_KEYS` in
+     * `crates/failproofaid/src/main.rs`. This side stores and edits the strings;
+     * it deliberately does not re-implement the parser, because two parsers is
+     * how the CLI comes to accept a path the daemon then silently drops.
+     *
+     * Absent for every machine that has not configured one, which is almost all
+     * of them — so `writeConfig` emits nothing at all in that case and a config
+     * file is byte-identical to what this version wrote before the field
+     * existed.
+     */
+    sources?: Record<string, { extraPaths: string[] }>;
   };
   telemetry: {
     /**
@@ -234,6 +253,32 @@ export const DEFAULT_CONFIG: FpConfig = {
   audit: { auto: false, intervalDays: DEFAULT_AUDIT_INTERVAL_DAYS },
 };
 
+/**
+ * `[collector.sources.*]` → the in-memory shape, dropping anything unusable.
+ *
+ * Entries are kept as written rather than normalised. The daemon parses them
+ * (label derivation, overlap rejection, `~` expansion) and reports what it
+ * rejected at startup; normalising here would give the two sides two answers
+ * and hide the daemon's rejection behind a value the CLI had already rewritten.
+ * The only things dropped are shapes that could not survive a round trip at
+ * all — a non-array, or a non-string element.
+ *
+ * `undefined` rather than `{}` when nothing is configured, so `writeConfig`
+ * emits no table and an untouched config file keeps its exact previous bytes.
+ */
+function readSources(raw: unknown): FpConfig["collector"]["sources"] {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const out: Record<string, { extraPaths: string[] }> = {};
+  for (const [name, table] of Object.entries(raw as Record<string, unknown>)) {
+    if (!table || typeof table !== "object" || Array.isArray(table)) continue;
+    const entries = (table as Record<string, unknown>).extra_paths;
+    if (!Array.isArray(entries)) continue;
+    const paths = entries.filter((e): e is string => typeof e === "string" && e.trim() !== "");
+    if (paths.length > 0) out[name] = { extraPaths: paths };
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 export function readConfig(): FpConfig {
   try {
     const parsed = parseToml(readFileSync(configFile(), "utf8")) as Record<string, unknown>;
@@ -258,6 +303,7 @@ export function readConfig(): FpConfig {
         environment:
           typeof collector.environment === "string" ? collector.environment : "local",
         machineId: typeof collector.machine_id === "string" ? collector.machine_id : undefined,
+        sources: readSources(collector.sources),
       },
       // Only an explicit `false` switches it off. Absent, or any other value,
       // reads as on — the shipped default, and what a config with no
@@ -308,6 +354,22 @@ export function writeConfig(config: FpConfig): void {
     `environment = ${JSON.stringify(c.environment)}`,
   );
   if (c.machineId) lines.push(`machine_id = ${JSON.stringify(c.machineId)}`);
+  // Sub-tables MUST come after every scalar of `[collector]`, or TOML reads the
+  // scalars that follow as belonging to the last sub-table opened. They are also
+  // 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 `[telemetry]` below.
+  for (const [name, src] of Object.entries(c.sources ?? {})) {
+    if (!src.extraPaths?.length) continue;
+    lines.push(
+      "",
+      `[collector.sources.${name}]`,
+      "# Extra locations to capture for this harness, beyond its default one.",
+      "# Each entry is \"label=path\" or a bare \"path\"; the label namespaces agent",
+      "# ids as <label>-<agentId> so two copies of one project stay distinct.",
+      `extra_paths = [${src.extraPaths.map((p) => JSON.stringify(p)).join(", ")}]`,
+    );
+  }
   // Written ONLY when switched off. A default install therefore carries no
   // [telemetry] block at all, but an operator who added one by hand keeps it:
   // writeConfig regenerates this file wholesale, so emitting the key only when
diff --git a/src/hooks/harness-cli.ts b/src/hooks/harness-cli.ts
new file mode 100644
index 00000000..3d5a6f48
--- /dev/null
+++ b/src/hooks/harness-cli.ts
@@ -0,0 +1,291 @@
+/**
+ * `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 TOML, parses cleanly,
+ * captures nothing, and is mentioned nowhere else a user would look.
+ *
+ * # Why a restart is mentioned and not performed
+ *
+ * The collector builds its task list once, when collection becomes enabled. A
+ * path added now is captured after the daemon next starts. Restarting it is
+ * `sudo systemctl restart` against a system-scope unit — this command writes a
+ * file without root and says what to run, rather than prompting for a password
+ * from under a command that had no other reason to need one.
+ */
+
+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,
+    },
+  });
+}
+
+const RESTART_HINT = [
+  "",
+  "The collector builds its task list at startup, so this takes effect when the",
+  "daemon next restarts:",
+  "",
+  "  sudo systemctl restart failproofaid@$USER    # linux",
+  "  sudo launchctl kickstart -k system/ai.befailproof.failproofaid   # macos",
+];
+
+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.
+  const samePath = existing.find((e) => pathOf(e) === 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);
+  if (wanted) {
+    const sameLabel = existing.find((e) => labelOf(e) === wanted);
+    if (sameLabel) {
+      return fail([
+        `${harness} already uses the label ${JSON.stringify(wanted)} for ${pathOf(sameLabel)}.`,
+        "",
+        "Labels namespace agent ids, so two paths cannot share one.",
+      ]);
+    }
+  }
+
+  writePaths(harness, [...existing, trimmed]);
+  return ok([
+    `${harness}: now also capturing ${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()}`,
+    ...RESTART_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.",
+    ...RESTART_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.toml 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.toml 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>",
+      ]);
+  }
+}

From 753343fc21828bb32f0596e883094872ed5a49d0 Mon Sep 17 00:00:00 2001
From: SiddarthAA <siddartha_ay@protonmail.com>
Date: Fri, 7 Aug 2026 20:00:05 +0530
Subject: [PATCH 2/3] Carry the user's policy selection across the layout-1
 upgrade
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Layout 1 kept it at ~/.failproofai/policies-config.json; layout 2 keeps it
at policies/local-policies/policies-config.json — and BOTH were on the reset
list. So moving between layouts discarded every builtin the user had
enabled, every explicit customPoliciesPaths entry and every policyParams
value.

The reset runs unattended from checkLayoutForCli on the first command after
an upgrade, and the machine still read as configured afterwards
(isConfigured() is a union that sees the agent CLIs' untouched settings
files) — so the wizard never re-asked and hooks kept firing against a policy
set that had quietly become the default one. Same silent enforcement gap
migrateConventionPolicies() and migrateHookActivity() already close, by a
third route.

Deliberately narrow, and inside the standing wipe-and-re-setup decision:
everything derived (cursors, spool, health, audit cache) still goes and is
rebuilt. What moves is only what a person typed and nothing regenerates —
the same test migrateHookActivity() applies to the decision log.

An ALLOWLIST rather than a copy. Layout 1's file also carried a `collector`
block in camelCase; layout 2 moved those settings to [collector] in
config.toml in snake_case, where fpai-collect's Settings deserializes them.
Carrying it would put a key into the new file that nothing reads — looking
preserved and behaving absent, which is the exact bug that Settings' own doc
comment records.

Two phases, because the source AND the destination's parent are both on the
reset list: read before the deletions, write after. Writing first would have
the reset delete the carry moments after it happened — what the note on
hookActivityDir() in resettablePaths() records happening once already.

A reset FROM the current layout no longer clears local-policies/. That is
not a layout migration, and there it would discard a current, valid
selection, including one just carried. The single production caller always
passes a DETECTED stale layout, so this only changes the forced same-layout
case.

An existing layout-2 config is never overwritten by the layout-1 file beside
it — a stale file winning would undo configuration rather than preserve it.
The reset still clears a stale layout-2 config on a layout migration, which
the pre-existing "still clears the machine-owned children of policies/" test
pins and which this change leaves intact.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CCSFM55BcUEAHECabpeSr4
---
 CHANGELOG.md                     |   1 +
 __tests__/hooks/fp-reset.test.ts | 129 ++++++++++++++++++++++++++++
 src/hooks/fp-home.ts             |   6 ++
 src/hooks/fp-reset.ts            | 141 ++++++++++++++++++++++++++++++-
 4 files changed, 274 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f64b293e..ca831c71 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@
 - Capture sessions from more than one location per agent CLI. Every source watched exactly the place its own installer puts it — `~/.claude/projects`, `~/.hermes/state.db` — which is right for one machine and wrong for every other arrangement: a second profile, a mounted team share, a container's home beside the host's, an agent an operator relocated. Those hold real sessions and nothing collected them. `failproofai harness add-path <harness> [<label>=]<path>` (plus `list` / `remove-path`) writes `[collector.sources.<harness>] extra_paths` in `config.toml`; `FAILPROOFAI_<HARNESS>_EXTRA_PATHS` overrides it for containers. Covers all twelve harnesses — thirteen sources, since `claude` carries its subagent transcripts, which share a root and would otherwise be silently dropped under an added path. Grammar, folder-name label fallback and `<label>-<agentId>` namespacing match AgentEye's collector (`--openclaw-extra-path`, `--hermes-extra-path`) rather than inventing a second answer to what an extra path is. Three things are structural rather than incidental: **each labelled path is its own task**, because `roots` is walked by one task with one `Params` and the label lives there — sharing would capture both under one id; each gets **its own cursor directory**, because the store writes its whole map atomically and two instances sharing one clobber each other's watermark and both re-read from zero after every restart; and each gets **its own health key**, or they overwrite each other's record and `root_present` alternates, destroying the "absent root versus idle source" distinction that file exists to draw — the exact failure Hermes hit with its per-profile databases. The label is applied in `SpoolWriter::push`, the one point every event from every source passes through (where `machine_id` and `user` are already stamped for the same reason), and **not** in either engine: a SQLite format is handed `params.agent_id` only as a fallback and derives the real id from the row (`devin::agent_id` returns `devin-<project>` and never consults the fallback for a session that has a working directory, which is all of them), so prefixing there would namespace only the sessions that failed to derive an id. A path overlapping one already captured is refused at startup rather than collected twice under two ids, and an unrecognised `[collector.sources.*]` table is reported instead of silently capturing nothing. A machine with nothing configured is unchanged, byte for byte, including its `config.toml`. (#PR)
 
 ### Fixes
+- Stop an upgrade from layout 1 silently emptying the user's policy selection. Layout 1 kept it at `~/.failproofai/policies-config.json` and layout 2 keeps it at `policies/local-policies/policies-config.json` — and BOTH were on the reset list, so moving between them discarded every builtin the user had enabled, every explicit `customPoliciesPaths` entry and every `policyParams` value. The reset runs unattended from `checkLayoutForCli` on the first command after an upgrade, and the machine still read as configured afterwards (`isConfigured()` is a union that sees the agent CLIs' untouched settings files) — so the wizard never re-asked, and hooks kept firing against a policy set that had quietly become the default one. That is the same silent enforcement gap `migrateConventionPolicies()` and `migrateHookActivity()` already exist to close, by a third route. The carry is deliberately narrow, and stays inside the standing wipe-and-re-setup decision: everything derived (cursors, spool, health, audit cache) still goes and is rebuilt, and what moves is only what a person typed and nothing regenerates. It is an ALLOWLIST rather than a copy, because layout 1's file also carried a `collector` block in camelCase and layout 2 moved those settings to `[collector]` in `config.toml` in snake_case — carrying it would put a key into the new file that nothing reads, looking preserved and behaving absent, which is the exact bug `fpai-collect`'s `Settings` documents. It runs in two phases (read before the deletions, write after) because its source AND its destination's parent are both on the reset list; writing first would have the reset delete the carry moments after it happened, which the note on `hookActivityDir()` records happening once already. A reset FROM the current layout no longer clears `local-policies/` at all — that is not a layout migration, and there it would discard a current, valid selection. An existing layout-2 config is never overwritten by the layout-1 file beside it. (#PR)
 - Make `failproofai config` refuse setup on an unsupported platform (Windows, today) instead of completing it unenforced. The wizard used to skip the daemon requirement and finish anyway, leaving the machine reading as configured while enforcing in-process with no fail-closed guarantee — now it prints why and exits 1 before drawing a single prompt, writing nothing. (#664)
 - Cut roughly a second of dead wait out of installing the daemon. `waitForDaemonRunning` slept a flat 750ms and then read the service status once, which was wrong in both directions: the socket is up in ~13ms and answers a real hook in ~125ms, so a healthy machine sat there with the answer already in hand — twice, because the repair path uninstalls and reinstalls — while a daemon that died at 100ms went unnoticed until the sleep was over. The window is now polled: leaving `running` fails immediately, and the wait ends as soon as the daemon accepts a connection, which is stronger evidence it did not die at startup than "still active after an arbitrary sleep". (#PR)
 - Let the setup wizard go back a step. Cancelling and going back were both `null`, so the only way to change an earlier answer was to abandon setup and start over; `←` on the harness step now re-asks the policy step with the previous selection still ticked. The policy step itself offers no `←` — the step before it is frequently not asked at all (a single scope choice is stated, not prompted), so it would sometimes go nowhere. (#PR)
diff --git a/__tests__/hooks/fp-reset.test.ts b/__tests__/hooks/fp-reset.test.ts
index 7ed9efd4..44004134 100644
--- a/__tests__/hooks/fp-reset.test.ts
+++ b/__tests__/hooks/fp-reset.test.ts
@@ -313,3 +313,132 @@ describe("daemon flag self-heal", () => {
     spyStat.mockRestore();
   });
 });
+
+// ── the policy selection a person typed ──────────────────────────────────
+//
+// Layout 1 kept the user policy config at `~/.failproofai/policies-config.json`;
+// layout 2 keeps it at `policies/local-policies/policies-config.json`. BOTH were
+// on the reset list, so an upgrade silently emptied `enabledPolicies` — and the
+// machine still read as configured afterwards (`isConfigured()` is a union that
+// sees the agent CLIs' untouched settings files), so hooks kept firing against a
+// policy set that had quietly become the default one.
+describe("resetHome carries the layout-1 policy selection", () => {
+  const layoutOneConfig = {
+    enabledPolicies: ["block-sudo", "block-env-files", "require-tests-before-stop"],
+    customPoliciesPaths: ["/home/u/team/policies.mjs"],
+    disabledCustomPolicies: ["team/noisy-rule"],
+    policyParams: { "block-sudo": { allowlist: ["sudo -n true"] } },
+    llm: { baseUrl: "https://llm.internal/v1", model: "gpt-4o-mini" },
+    // Layout 1 also kept collector settings HERE, in camelCase. Layout 2 moved
+    // them to config.toml in snake_case, where `fpai-collect`'s `Settings`
+    // deserializes them — so carrying this block forward would put a key into
+    // the new file that nothing reads, looking preserved and behaving absent.
+    collector: { hooksVerbosity: "all", machineId: "m-legacy" },
+  };
+
+  function seedLayoutOnePolicyConfig() {
+    writeFileSync(legacy.policyConfig(), JSON.stringify(layoutOneConfig, null, 2));
+  }
+
+  it("carries the fields layout 2 still means", () => {
+    seedLayoutOne();
+    seedLayoutOnePolicyConfig();
+
+    const out = resetHome(1);
+
+    const carried = JSON.parse(
+      readFileSync(resolve(localPoliciesDir(), "policies-config.json"), "utf8"),
+    );
+    expect(carried.enabledPolicies).toEqual([
+      "block-sudo",
+      "block-env-files",
+      "require-tests-before-stop",
+    ]);
+    expect(carried.customPoliciesPaths).toEqual(["/home/u/team/policies.mjs"]);
+    expect(carried.disabledCustomPolicies).toEqual(["team/noisy-rule"]);
+    expect(carried.policyParams).toEqual({ "block-sudo": { allowlist: ["sudo -n true"] } });
+    expect(carried.llm).toEqual({ baseUrl: "https://llm.internal/v1", model: "gpt-4o-mini" });
+    expect(out.policyConfig).toContain("enabledPolicies");
+  });
+
+  // The one exclusion, and the reason the carry is an allowlist rather than a
+  // copy. A camelCase `collector` block in the new file reads as a preserved
+  // setting and does nothing.
+  it("does NOT carry the collector block, which moved to config.toml", () => {
+    seedLayoutOne();
+    seedLayoutOnePolicyConfig();
+
+    const out = resetHome(1);
+
+    const carried = JSON.parse(
+      readFileSync(resolve(localPoliciesDir(), "policies-config.json"), "utf8"),
+    );
+    expect(carried.collector).toBeUndefined();
+    expect(out.policyConfig).not.toContain("collector");
+  });
+
+  // A home already set up on layout 2 has a NEWER answer than the layout-1 file
+  // beside it, and a stale file winning would UNDO configuration rather than
+  // preserve it. The reset still CLEARS that layout-2 config on a layout
+  // migration (see "still clears the machine-owned children of policies/") —
+  // what must never happen is layout 1's values taking its place.
+  it("never lets the layout-1 file overwrite an existing layout-2 config", () => {
+    seedLayoutOne();
+    seedLayoutOnePolicyConfig();
+    mkdirSync(localPoliciesDir(), { recursive: true });
+    writeFileSync(
+      resolve(localPoliciesDir(), "policies-config.json"),
+      JSON.stringify({ enabledPolicies: ["current-choice"] }),
+    );
+
+    const out = resetHome(1);
+
+    expect(out.policyConfig).toEqual([]);
+    const path = resolve(localPoliciesDir(), "policies-config.json");
+    if (existsSync(path)) {
+      const after = JSON.parse(readFileSync(path, "utf8"));
+      expect(after.enabledPolicies).not.toContain("block-sudo");
+    }
+  });
+
+  it("is a no-op when there is no layout-1 config", () => {
+    seedLayoutOne();
+    // `seedLayoutOne()` writes one; this case is the home that never had it.
+    rmSync(legacy.policyConfig(), { force: true });
+    const out = resetHome(1);
+    expect(out.policyConfig).toEqual([]);
+    expect(existsSync(resolve(localPoliciesDir(), "policies-config.json"))).toBe(false);
+  });
+
+  // Unparseable is not worth aborting a reset over, and there is nothing to
+  // carry — which is exactly what happened before this function existed.
+  it("survives an unparseable layout-1 config without aborting the reset", () => {
+    seedLayoutOne();
+    writeFileSync(legacy.policyConfig(), "{ this is not json");
+    const out = resetHome(1);
+    expect(out.policyConfig).toEqual([]);
+    expect(readVersionFile()?.layout).toBe(LAYOUT_VERSION);
+  });
+
+  // A file carrying only a collector block has nothing to carry, and must not
+  // produce an empty layout-2 file that looks like a real one.
+  it("writes nothing when only excluded fields are present", () => {
+    seedLayoutOne();
+    writeFileSync(legacy.policyConfig(), JSON.stringify({ collector: { hooksVerbosity: "all" } }));
+    const out = resetHome(1);
+    expect(out.policyConfig).toEqual([]);
+    expect(existsSync(resolve(localPoliciesDir(), "policies-config.json"))).toBe(false);
+  });
+
+  // The whole point: after the reset, the carried file is what the loader reads.
+  it("leaves the carried config where the layout-2 reader looks", () => {
+    seedLayoutOne();
+    seedLayoutOnePolicyConfig();
+    resetHome(1);
+    // The layout-1 original is gone...
+    expect(existsSync(legacy.policyConfig())).toBe(false);
+    // ...and the layout-2 path, which `globalPolicyConfigFile()` resolves to,
+    // holds the selection.
+    expect(existsSync(resolve(localPoliciesDir(), "policies-config.json"))).toBe(true);
+  });
+});
diff --git a/src/hooks/fp-home.ts b/src/hooks/fp-home.ts
index b64139d4..6ccb5fe9 100644
--- a/src/hooks/fp-home.ts
+++ b/src/hooks/fp-home.ts
@@ -341,6 +341,12 @@ export function resettablePaths(): string[] {
     // `custom-policies/` is deliberately absent from this list for the same
     // reason. Both directories below are re-derived: `local-policies/` by
     // setup, `cloud-policies/` by the next daemon poll.
+    //
+    // `local-policies/` holds ONE file — the user's enabled-policy selection —
+    // and clearing it on a layout migration is deliberate and tested. But it is
+    // also the destination `migratePolicyConfig()` carries layout 1's selection
+    // into, so the carry is written AFTER this list runs, and `resetHome` skips
+    // this entry when the reset is not a layout migration at all. See both.
     localPoliciesDir(),
     cloudPoliciesDir(),
     // `at("cursors")` is deliberately NOT here, and it is load-bearing for the
diff --git a/src/hooks/fp-reset.ts b/src/hooks/fp-reset.ts
index 57652826..c12ad567 100644
--- a/src/hooks/fp-reset.ts
+++ b/src/hooks/fp-reset.ts
@@ -29,14 +29,25 @@
  * user out of their agent entirely, with no way back except hand-editing JSON.
  * A loud warning that survives until setup runs is the proportionate answer.
  */
-import { copyFileSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
-import { resolve } from "node:path";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, resolve } from "node:path";
 import {
   LAYOUT_VERSION,
   customPoliciesDir,
   failproofaiHome,
+  globalPolicyConfigFile,
   hookActivityDir,
   legacy,
+  localPoliciesDir,
   policiesDir,
   resettablePaths,
 } from "./fp-home";
@@ -56,6 +67,8 @@ export interface ResetOutcome {
   migrated: string[];
   /** Basenames of decision-log pages carried into layout 2's `hook-activity/`. */
   activity: string[];
+  /** Keys of the layout-1 policy config carried into layout 2's. */
+  policyConfig: string[];
   /** The layout that was found before the reset. */
   from: number;
 }
@@ -202,6 +215,118 @@ export function migrateHookActivity(): string[] {
   return moved.sort((a, b) => a.localeCompare(b));
 }
 
+/**
+ * Fields of layout 1's `policies-config.json` that layout 2's still means.
+ *
+ * An allowlist, not a copy, and the exclusion is the point: layout 1's file
+ * ALSO carried a `collector` block, and layout 2 moved collector settings to
+ * `[collector]` in `config.toml` — in snake_case, deliberately, because
+ * `fpai-collect`'s `Settings` deserializes them and camelCase keys would make
+ * every field silently fall back to its default (see the note on `Settings` in
+ * `crates/fpai-collect/src/config.rs`, which records that exact bug). Carrying
+ * `collector` forward would put a block into the new file that nothing reads,
+ * where it would look like a preserved setting and behave like an absent one.
+ *
+ * The `llm` block moves because the loader still reads it from here, and its
+ * value is an endpoint and a model name a person configured by hand.
+ */
+const CARRIED_POLICY_CONFIG_KEYS = [
+  "enabledPolicies",
+  "customPoliciesPaths",
+  "customPoliciesPath",
+  "disabledCustomPolicies",
+  "conventionPolicies",
+  "disabledConventionPolicies",
+  "policyParams",
+  "llm",
+] as const;
+
+/**
+ * Carry the user's policy SELECTION across the layout-1 → layout-2 move.
+ *
+ * Layout 1 kept it at `~/.failproofai/policies-config.json`; layout 2 keeps it
+ * at `policies/local-policies/policies-config.json`, and both were on the reset
+ * list. So an upgrade silently emptied `enabledPolicies` — every builtin the
+ * user had turned on, every explicit `customPoliciesPaths` entry, and every
+ * per-policy parameter. The machine still read as configured afterwards
+ * (`isConfigured()` is a union that sees the agent CLIs' untouched settings
+ * files), so hooks kept firing against a policy set that had quietly become
+ * the default one. That is the same silent enforcement gap
+ * `migrateConventionPolicies()` exists to close, by a different route.
+ *
+ * This is deliberately NARROW. The standing decision for layout 1 is
+ * wipe-and-re-setup rather than migrate, because a half-migrated home that
+ * reads "no data" is worse than one that says so — see `legacy` in
+ * `fp-home.ts`. Everything derived (cursors, spool, health, audit cache) still
+ * goes and is rebuilt. What is carried is only what a person typed and nothing
+ * regenerates, which is the same test `migrateHookActivity()` applies to the
+ * decision log.
+ *
+ * # Two phases, because the source and the destination are BOTH on the list
+ *
+ * Unlike the two migrations above, this one cannot run entirely before the
+ * deletions. Its source (`legacy.policyConfig()`) is removed by them, and so is
+ * its destination's parent (`localPoliciesDir()`) — rightly, since clearing a
+ * stale selection on a layout migration is the documented behaviour. Writing
+ * first would have the reset delete the carry moments after it happened, which
+ * is exactly what the note on `hookActivityDir()` in `resettablePaths()` records
+ * happening once already.
+ *
+ * So: READ before, WRITE after.
+ */
+export function readCarriedPolicyConfig(): Record<string, unknown> | null {
+  const from = legacy.policyConfig();
+  // Checked HERE rather than at write time: by then the destination has been
+  // deleted along with its parent, so every home would look empty. A home
+  // already set up on layout 2 has a newer answer than the layout-1 file beside
+  // it, and a stale file winning would UNDO configuration, not preserve it.
+  if (!existsSync(from) || existsSync(globalPolicyConfigFile())) return null;
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(readFileSync(from, "utf8")) as Record<string, unknown>;
+  } catch {
+    // Unparseable is not worth aborting a reset over, and there is nothing to
+    // carry. The file is removed with the rest of layout 1, which is also what
+    // would have happened before this function existed.
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+
+  const carried: Record<string, unknown> = {};
+  let found = false;
+  for (const key of CARRIED_POLICY_CONFIG_KEYS) {
+    if (parsed[key] !== undefined) {
+      carried[key] = parsed[key];
+      found = true;
+    }
+  }
+  // Nothing worth carrying — a file holding only excluded fields must not
+  // produce an empty layout-2 config that looks like a real one.
+  if (!found) return null;
+
+  // `enabledPolicies` is required by the type and by every reader. A layout-1
+  // file that somehow lacked it would otherwise produce a layout-2 file that
+  // throws on read — worse than the empty default it replaces.
+  if (carried.enabledPolicies === undefined) carried.enabledPolicies = [];
+  return carried;
+}
+
+/** Second phase of {@link readCarriedPolicyConfig}; runs AFTER the deletions. */
+export function writeCarriedPolicyConfig(carried: Record<string, unknown> | null): string[] {
+  if (!carried) return [];
+  const to = globalPolicyConfigFile();
+  try {
+    mkdirSync(dirname(to), { recursive: true });
+    writeFileSync(to, JSON.stringify(carried, null, 2) + "\n", "utf8");
+  } catch {
+    // A destination we cannot write is not worth aborting the reset over; the
+    // user re-runs setup, which is the pre-existing behaviour.
+    return [];
+  }
+  return Object.keys(carried).sort((a, b) => a.localeCompare(b));
+}
+
 /**
  * Delete every path layout 1 or layout 2 could have written, then stamp
  * VERSION so the next run reads as current.
@@ -217,8 +342,17 @@ export function resetHome(from: number): ResetOutcome {
   // then walks over.
   const migrated = migrateConventionPolicies();
   const activity = migrateHookActivity();
+  const pendingPolicyConfig = readCarriedPolicyConfig();
   const removed: string[] = [];
   for (const path of resettablePaths()) {
+    // A reset FROM the current layout is not a layout migration, and the only
+    // thing under `local-policies/` is the user's enabled-policy selection.
+    // Clearing it is right when moving off an old layout (setup re-asks) and
+    // wrong when nothing is being migrated — there it would silently discard a
+    // current, valid selection, including one this function had just carried.
+    // The single production caller always passes a DETECTED stale layout, so
+    // this only ever changes the forced same-layout case.
+    if (from === LAYOUT_VERSION && path === localPoliciesDir()) continue;
     if (!existsSync(path)) continue;
     try {
       rmSync(path, { recursive: true, force: true });
@@ -229,8 +363,9 @@ export function resetHome(from: number): ResetOutcome {
       // directory from an old layout is inert once nothing reads it.
     }
   }
+  const policyConfig = writeCarriedPolicyConfig(pendingPolicyConfig);
   writeVersionFile();
-  return { removed, migrated, activity, from };
+  return { removed, migrated, activity, policyConfig, from };
 }
 
 export interface LayoutCheck {

From 4df92b5258c7dcc669206d1972a7359ece593deb Mon Sep 17 00:00:00 2001
From: SiddarthAA <siddartha_ay@protonmail.com>
Date: Fri, 7 Aug 2026 21:05:51 +0530
Subject: [PATCH 3/3] Correct the harness hint: no restart and no sudo are
 needed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`harness add-path` told the user to run
`sudo systemctl restart failproofaid@$USER`. That was wrong twice over.

The daemon's collector manager already re-reads config.toml on an interval
and cycles the collector whenever the resolved CollectorConfig differs from
the one the live generation was built from — the same path that picks up
`--connect`, a stream being switched off and a verbosity change. `sources`
lives inside `Settings`, which is part of that compared value, so extra
paths ride it for free.

Verified live against a running daemon: adding a path logged "collector
configuration changed; cycling the collector", took the task count 21 -> 23
(claude's extra path adds two, since the main and subagent formats share a
root), and the first transcript written under the new path reached the
server.

So the restart was unnecessary — and asking for root from a command that
writes one file in the user's own home and needs none is the worse half of
the mistake.

Two tests, because nothing registers `sources` with the reload machinery
explicitly and moving it anywhere resolved later breaks the promise
SILENTLY: the CLI keeps reporting success, the config keeps parsing, and the
daemon just never captures the path until an unrelated restart.

  - collector_config_change_cycles_the_collector (unit) pins that adding an
    extra path changes the compared value at all.
  - an_extra_capture_path_added_by_hand_is_registered_without_a_restart
    (e2e) drives the REAL binary against a hand-edited config, alongside the
    credential-rotation cases already there and for the same stated reason —
    the property is "an edit somebody else made is noticed", and a fleet
    tool or a sed is a legitimate way to make it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CCSFM55BcUEAHECabpeSr4
---
 CHANGELOG.md                                  |  2 +-
 bin/failproofai.mjs                           |  4 +-
 .../tests/collector_reload_e2e.rs             | 58 +++++++++++++++++++
 crates/fpai-collect/src/config.rs             | 44 ++++++++++++++
 src/hooks/harness-cli.ts                      | 46 ++++++++++-----
 5 files changed, 137 insertions(+), 17 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ca831c71..d8e58aae 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,7 @@
 ### Features
 - Add `failproofai flush` — deliver what is already spooled, now. The collector is unhurried on purpose (a batch is swept once it is older than two minutes, at most 64 per pass, on a 60-second cadence), which is right for a backlog and exactly wrong for somebody standing at a dashboard waiting to see their own events: from there "not delivered yet" and "not working" look identical. The command asks the daemon for a pass with no minimum age and no cap, and `--wait` blocks until the spool drains so a script can flush and then assert. It re-sends nothing — for history the collector already read past, that is still `backfill`. (#PR)
 - Rename the cloud-policy vocabulary: a **generation** is now a **deployment**, and a policy **revision** is a **version**. Both were words the product used nowhere else — a customer reads "deployment 7" and "version 3" without a glossary. The rename goes through the wire format and the on-disk manifest, not just the labels, and lands with the matching AgentEye change: a server and a daemon that disagree on these names means the fleet stops reconciling, silently. (#PR)
-- Capture sessions from more than one location per agent CLI. Every source watched exactly the place its own installer puts it — `~/.claude/projects`, `~/.hermes/state.db` — which is right for one machine and wrong for every other arrangement: a second profile, a mounted team share, a container's home beside the host's, an agent an operator relocated. Those hold real sessions and nothing collected them. `failproofai harness add-path <harness> [<label>=]<path>` (plus `list` / `remove-path`) writes `[collector.sources.<harness>] extra_paths` in `config.toml`; `FAILPROOFAI_<HARNESS>_EXTRA_PATHS` overrides it for containers. Covers all twelve harnesses — thirteen sources, since `claude` carries its subagent transcripts, which share a root and would otherwise be silently dropped under an added path. Grammar, folder-name label fallback and `<label>-<agentId>` namespacing match AgentEye's collector (`--openclaw-extra-path`, `--hermes-extra-path`) rather than inventing a second answer to what an extra path is. Three things are structural rather than incidental: **each labelled path is its own task**, because `roots` is walked by one task with one `Params` and the label lives there — sharing would capture both under one id; each gets **its own cursor directory**, because the store writes its whole map atomically and two instances sharing one clobber each other's watermark and both re-read from zero after every restart; and each gets **its own health key**, or they overwrite each other's record and `root_present` alternates, destroying the "absent root versus idle source" distinction that file exists to draw — the exact failure Hermes hit with its per-profile databases. The label is applied in `SpoolWriter::push`, the one point every event from every source passes through (where `machine_id` and `user` are already stamped for the same reason), and **not** in either engine: a SQLite format is handed `params.agent_id` only as a fallback and derives the real id from the row (`devin::agent_id` returns `devin-<project>` and never consults the fallback for a session that has a working directory, which is all of them), so prefixing there would namespace only the sessions that failed to derive an id. A path overlapping one already captured is refused at startup rather than collected twice under two ids, and an unrecognised `[collector.sources.*]` table is reported instead of silently capturing nothing. A machine with nothing configured is unchanged, byte for byte, including its `config.toml`. (#PR)
+- Capture sessions from more than one location per agent CLI. Every source watched exactly the place its own installer puts it — `~/.claude/projects`, `~/.hermes/state.db` — which is right for one machine and wrong for every other arrangement: a second profile, a mounted team share, a container's home beside the host's, an agent an operator relocated. Those hold real sessions and nothing collected them. `failproofai harness add-path <harness> [<label>=]<path>` (plus `list` / `remove-path`) writes `[collector.sources.<harness>] extra_paths` in `config.toml`; `FAILPROOFAI_<HARNESS>_EXTRA_PATHS` overrides it for containers. Covers all twelve harnesses — thirteen sources, since `claude` carries its subagent transcripts, which share a root and would otherwise be silently dropped under an added path. Grammar, folder-name label fallback and `<label>-<agentId>` namespacing match AgentEye's collector (`--openclaw-extra-path`, `--hermes-extra-path`) rather than inventing a second answer to what an extra path is. Three things are structural rather than incidental: **each labelled path is its own task**, because `roots` is walked by one task with one `Params` and the label lives there — sharing would capture both under one id; each gets **its own cursor directory**, because the store writes its whole map atomically and two instances sharing one clobber each other's watermark and both re-read from zero after every restart; and each gets **its own health key**, or they overwrite each other's record and `root_present` alternates, destroying the "absent root versus idle source" distinction that file exists to draw — the exact failure Hermes hit with its per-profile databases. The label is applied in `SpoolWriter::push`, the one point every event from every source passes through (where `machine_id` and `user` are already stamped for the same reason), and **not** in either engine: a SQLite format is handed `params.agent_id` only as a fallback and derives the real id from the row (`devin::agent_id` returns `devin-<project>` and never consults the fallback for a session that has a working directory, which is all of them), so prefixing there would namespace only the sessions that failed to derive an id. A path overlapping one already captured is refused at startup rather than collected twice under two ids, and an unrecognised `[collector.sources.*]` table is reported instead of silently capturing nothing. A machine with nothing configured is unchanged, byte for byte, including its `config.toml`. Adding or removing a path needs no restart and no sudo: the daemon's collector manager already re-reads `config.toml` on an interval and cycles the collector whenever the resolved `CollectorConfig` changes, and `sources` rides that by living inside the compared value — verified live (task count 21 → 23 within one interval, and the first transcript under the new path reached the server) and pinned by an e2e test that drives the real binary against a hand-edited config. (#PR)
 
 ### Fixes
 - Stop an upgrade from layout 1 silently emptying the user's policy selection. Layout 1 kept it at `~/.failproofai/policies-config.json` and layout 2 keeps it at `policies/local-policies/policies-config.json` — and BOTH were on the reset list, so moving between them discarded every builtin the user had enabled, every explicit `customPoliciesPaths` entry and every `policyParams` value. The reset runs unattended from `checkLayoutForCli` on the first command after an upgrade, and the machine still read as configured afterwards (`isConfigured()` is a union that sees the agent CLIs' untouched settings files) — so the wizard never re-asked, and hooks kept firing against a policy set that had quietly become the default one. That is the same silent enforcement gap `migrateConventionPolicies()` and `migrateHookActivity()` already exist to close, by a third route. The carry is deliberately narrow, and stays inside the standing wipe-and-re-setup decision: everything derived (cursors, spool, health, audit cache) still goes and is rebuilt, and what moves is only what a person typed and nothing regenerates. It is an ALLOWLIST rather than a copy, because layout 1's file also carried a `collector` block in camelCase and layout 2 moved those settings to `[collector]` in `config.toml` in snake_case — carrying it would put a key into the new file that nothing reads, looking preserved and behaving absent, which is the exact bug `fpai-collect`'s `Settings` documents. It runs in two phases (read before the deletions, write after) because its source AND its destination's parent are both on the reset list; writing first would have the reset delete the carry moments after it happened, which the note on `hookActivityDir()` records happening once already. A reset FROM the current layout no longer clears `local-policies/` at all — that is not a layout migration, and there it would discard a current, valid selection. An existing layout-2 config is never overwritten by the layout-1 file beside it. (#PR)
diff --git a/bin/failproofai.mjs b/bin/failproofai.mjs
index c88eb6f9..18394f39 100755
--- a/bin/failproofai.mjs
+++ b/bin/failproofai.mjs
@@ -696,8 +696,8 @@ NOTES
     [collector] in ~/.failproofai/config.toml like the default ones do.
   • A path overlapping one already captured is REFUSED by the daemon at startup
     rather than collected twice under two ids. It says so in the journal.
-  • Takes effect at the next daemon restart — the collector builds its task list
-    once, at startup.
+  • Takes effect within seconds — the daemon re-reads config.toml on an interval
+    and cycles its collector. No restart, no sudo.
 
 EXAMPLES
   failproofai harness add-path claude work=/srv/team/.claude/projects
diff --git a/crates/failproofaid/tests/collector_reload_e2e.rs b/crates/failproofaid/tests/collector_reload_e2e.rs
index 9cd28311..1f0fbec0 100644
--- a/crates/failproofaid/tests/collector_reload_e2e.rs
+++ b/crates/failproofaid/tests/collector_reload_e2e.rs
@@ -271,3 +271,61 @@ fn disabling_collection_stops_it_and_re_enabling_starts_it_again() {
     daemon.wait_for("collector enabled", 2, Duration::from_secs(20));
     let _ = std::fs::remove_dir_all(&home);
 }
+
+/// An extra capture path added by hand is picked up without a restart.
+///
+/// `failproofai harness add-path` writes `[collector.sources.<harness>]
+/// extra_paths` and tells the user the daemon will notice on its own. That
+/// promise rests entirely on `sources` living inside the `CollectorConfig` the
+/// manager compares each tick — nothing registers the field explicitly, and
+/// moving it anywhere resolved later would break the promise silently: the CLI
+/// keeps reporting success, the config keeps parsing, and the running daemon
+/// simply never captures the path until it is restarted for some unrelated
+/// reason.
+///
+/// Asserted on the REAL binary against a hand-edited file, like the cases above
+/// and for the same reason — the property is "an edit somebody else made is
+/// noticed", and a fleet tool or a `sed` is a legitimate way to make it.
+///
+/// The task-count line is what proves the path was actually REGISTERED rather
+/// than merely triggering a cycle: `sessions = true` turns the session sources
+/// on, and each labelled path adds its own task on top (claude's extra path
+/// adds two — the main and subagent formats share a root).
+#[test]
+fn an_extra_capture_path_added_by_hand_is_registered_without_a_restart() {
+    let home = unique_home("extra-path");
+    make_home(&home, "a-key");
+    // Session capture on: extra paths are a session-source feature, and the
+    // default config `make_home` writes has it off.
+    let cfg = home.join("config.toml");
+    let base = std::fs::read_to_string(&cfg)
+        .unwrap()
+        .replace("sessions = false", "sessions = true");
+    std::fs::write(&cfg, &base).unwrap();
+
+    let daemon = spawn_daemon(&home);
+    daemon.wait_for("collector enabled", 1, Duration::from_secs(20));
+    daemon.wait_for("collector started", 1, Duration::from_secs(20));
+
+    let extra = home.join("extra-claude-projects");
+    std::fs::create_dir_all(&extra).unwrap();
+    std::fs::write(
+        &cfg,
+        format!(
+            "{base}\n[collector.sources.claude]\nextra_paths = [\"late={}\"]\n",
+            extra.display()
+        ),
+    )
+    .unwrap();
+
+    daemon.wait_for(
+        "collector configuration changed; cycling the collector",
+        1,
+        Duration::from_secs(20),
+    );
+    // The daemon names every extra path it accepts, so this is the line that
+    // says the entry was parsed and not rejected.
+    daemon.wait_for("also capturing", 1, Duration::from_secs(20));
+    daemon.wait_for("collector started", 2, Duration::from_secs(20));
+    let _ = std::fs::remove_dir_all(&home);
+}
diff --git a/crates/fpai-collect/src/config.rs b/crates/fpai-collect/src/config.rs
index 297f7a67..b3f67b7e 100644
--- a/crates/fpai-collect/src/config.rs
+++ b/crates/fpai-collect/src/config.rs
@@ -716,6 +716,50 @@ interval_days = 7
         );
     }
 
+    /// Adding an extra path must change the resolved `CollectorConfig`.
+    ///
+    /// This is what makes `failproofai harness add-path` take effect on a
+    /// RUNNING daemon with no restart and no sudo. `spawn_collector_manager` in
+    /// failproofaid re-reads this config on an interval and cycles the collector
+    /// whenever the whole value differs from the one the live generation was
+    /// built from — it does not know or care which field moved.
+    ///
+    /// So the mechanism rests entirely on `sources` being INSIDE the compared
+    /// value. Move it out — to its own file, a lazily-read side table, anything
+    /// resolved after this struct — and nothing breaks loudly: the CLI keeps
+    /// reporting success, the config keeps parsing, and the running daemon
+    /// simply never picks the path up until it is restarted for some other
+    /// reason. Verified live at the time of writing: task count 21 -> 23 within
+    /// one poll interval, and the first transcript under the new path reached
+    /// the server.
+    #[test]
+    fn collector_config_change_cycles_the_collector() {
+        let d = home_with("[collector]\nsessions = true\n");
+        let before = load(d.path()).unwrap();
+
+        fs::write(
+            d.path().join(CONFIG_FILE),
+            "[collector]\nsessions = true\n\n[collector.sources.claude]\nextra_paths = [\"late=/srv/x\"]\n",
+        )
+        .unwrap();
+        let after = load(d.path()).unwrap();
+
+        assert_ne!(
+            before, after,
+            "adding an extra path did not change CollectorConfig, so a running \
+             daemon would never cycle and the path would be captured only after \
+             an unrelated restart"
+        );
+        assert_eq!(
+            after.settings.extra_paths_for("claude"),
+            vec!["late=/srv/x".to_string()]
+        );
+
+        // ...and removing it changes back, so `remove-path` also takes effect.
+        fs::write(d.path().join(CONFIG_FILE), "[collector]\nsessions = true\n").unwrap();
+        assert_eq!(load(d.path()).unwrap(), before);
+    }
+
     /// A source whose name contains `-` must map to a legal env var name.
     #[test]
     fn a_hyphenated_source_name_maps_to_an_underscored_env_var() {
diff --git a/src/hooks/harness-cli.ts b/src/hooks/harness-cli.ts
index 3d5a6f48..8f1318d7 100644
--- a/src/hooks/harness-cli.ts
+++ b/src/hooks/harness-cli.ts
@@ -21,13 +21,18 @@
  * other detector: `[collector.sources.claud]` is valid TOML, parses cleanly,
  * captures nothing, and is mentioned nowhere else a user would look.
  *
- * # Why a restart is mentioned and not performed
+ * # No restart, and no sudo
  *
- * The collector builds its task list once, when collection becomes enabled. A
- * path added now is captured after the daemon next starts. Restarting it is
- * `sudo systemctl restart` against a system-scope unit — this command writes a
- * file without root and says what to run, rather than prompting for a password
- * from under a command that had no other reason to need one.
+ * This writes one file in the user's own home and nothing else. The daemon's
+ * collector manager re-reads `config.toml` 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 { readConfig, updateConfig } from "./fp-config";
@@ -116,13 +121,26 @@ function writePaths(harness: string, paths: string[]): void {
   });
 }
 
-const RESTART_HINT = [
-  "",
-  "The collector builds its task list at startup, so this takes effect when the",
-  "daemon next restarts:",
+/**
+ * No restart, and deliberately no instruction to perform one.
+ *
+ * The daemon's collector manager re-reads `config.toml` 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 = [
   "",
-  "  sudo systemctl restart failproofaid@$USER    # linux",
-  "  sudo launchctl kickstart -k system/ai.befailproof.failproofaid   # macos",
+  "The daemon picks this up on its own within a few seconds — no restart, no sudo.",
 ];
 
 export function addPath(harness: string, entry: string): HarnessResult {
@@ -173,7 +191,7 @@ export function addPath(harness: string, entry: string): HarnessResult {
       ? `  agent ids will be namespaced ${wanted}-*`
       : "  a label will be derived from the folder name; `failproofai harness list` shows it",
     `  written to ${configFile()}`,
-    ...RESTART_HINT,
+    ...TAKES_EFFECT_HINT,
   ]);
 }
 
@@ -199,7 +217,7 @@ export function removePath(harness: string, target: string): HarnessResult {
     "",
     "Already-collected sessions from that path are NOT removed — they are on the",
     "server. This only stops new ones.",
-    ...RESTART_HINT,
+    ...TAKES_EFFECT_HINT,
   ]);
 }