failproofai 1.0.2-beta.6 → 1.0.2-beta.7

package/bin/failproofai.mjs

@@ -296,6 +296,76 @@ if (hookIdx >= 0) {
  * CliError  → clean message, no stack trace, exit exitCode (1 or 2)
  * Error     → unexpected; shows message only, exits 2
  */
+/**
+ * Every `--help` in this file, and the index itself, drawn by ONE renderer.
+ *
+ * They used to be twelve template literals: `USAGE` on one screen and `Usage:`
+ * on the next, a description column hand-counted per screen, no version on any
+ * of them, and no colour on any of them while the index they were reached from
+ * had all three. The words are still each screen's own — this owns the shape,
+ * so a screen cannot drift out of the family without editing the family.
+ *
+ * Capped at 80 columns by `helpOptsFor`, so help reads the same in a maximised
+ * window as in a tmux pane, and narrows on a terminal smaller than that.
+ */
+/**
+ * Lines a module ALREADY laid out with the kit — `harness`, `publish`,
+ * `policies add`, the pack lane — printed with the outer margins every other
+ * screen gets. They used to go out one `console.log` at a time, which is the
+ * one thing `printBlock` exists to own: the block arrived flush against the
+ * prompt above it while every neighbouring command was breathing.
+ */
+async function printLines(lines, ok = true) {
+  const { printBlock } = await import("../src/hooks/tui");
+  printBlock(ok ? process.stdout : process.stderr, lines);
+}
+
+/**
+ * What an action surface prints when it is done: a heading naming the command,
+ * then the lines it produced, indented and margined like every other screen.
+ *
+ * The modules keep returning bare facts — `runFlushCommand` says "2 batches
+ * spooled", not how to draw it — so the presentation lives in exactly one
+ * place instead of five, and a flush report and a `policies` listing stop
+ * looking like output from two different programs.
+ *
+ * Lines that already carry their own leading space are passed through: those
+ * are sub-items a module laid out on purpose, and re-wrapping them would
+ * flatten the structure they were expressing.
+ */
+async function printReport(command, lines, opts = {}) {
+  const { title, wrap, stack, printBlock, optsFor, INDENT, brandAnsi, ANSI_RESET } =
+    await import("../src/hooks/tui");
+  const ok = opts.ok !== false;
+  const stream = ok ? process.stdout : process.stderr;
+  const o = optsFor(stream);
+  // `\`like this\`` becomes pink, and loses the backticks. These messages name
+  // the command to run next more often than not, and pink is what you type
+  // everywhere else on the CLI now — the help screens, the bullets, the next
+  // steps. Applied AFTER wrapping, because an escape sequence has no width and
+  // colouring first would make every wrap measure the wrong length.
+  const paint = (line) =>
+    o.color && (line.match(/`/g) || []).length % 2 === 0
+      ? line.replace(/`([^`]+)`/g, `${brandAnsi("pink")}$1${ANSI_RESET}`)
+      : line;
+  const body = [];
+  for (const line of lines) {
+    if (line.trim() === "") body.push("");
+    else if (line.startsWith(" ")) body.push(paint(`${INDENT}${line}`));
+    else {
+      for (const w of wrap(line, Math.max(20, o.cols - INDENT.length * 2))) {
+        body.push(paint(`${INDENT}${w}`));
+      }
+    }
+  }
+  printBlock(stream, stack(title(`failproofai ${command}`, opts.meta, o), body));
+}
+
+async function printHelp(spec) {
+  const { helpScreen, helpOptsFor, printBlock } = await import("../src/hooks/tui");
+  printBlock(process.stdout, helpScreen({ version, ...spec }, helpOptsFor(process.stdout)));
+}
+
 async function runCli() {
   // --help / -h  (only when not inside a subcommand that handles its own --help)
   // `update` and `migrate` were missing here, so `failproofai update --help`
@@ -322,25 +392,37 @@ async function runCli() {
     // string — so it gets a topic here rather than a line on the index, where a
     // machine-facing flag would only take space from the human-facing commands.
     if (helpTopic === "hook") {
-      console.log(`
-failproofai --hook <event> [--cli <name>]
-
-The entry point your agent CLI spawns, once per tool call. You do not run this;
-\`failproofai config\` writes it into each CLI's hook configuration for you.
-
-  --hook <event>   PreToolUse, PostToolUse, UserPromptSubmit, Stop,
-                   SubagentStop, SessionStart, SessionEnd, PreCompact,
-                   Notification, PermissionRequest
-  --cli <name>     claude, codex, copilot, cursor, opencode, pi, hermes,
-                   openclaw, factory, devin, antigravity, goose.
-                   Defaults to claude. It selects which payload shape to
-                   expect: each CLI names its events and tool arguments
-                   differently, and failproofai canonicalizes them.
-
-It reads the event as JSON on stdin and answers on stdout, in whatever shape
-that CLI honours. Exit codes and response shapes differ per CLI by necessity —
-see docs.befailproof.ai. Denials are reported to the agent, never to you.
-`.trimStart());
+      await printHelp({
+        command: "--hook",
+        tagline: "the entry point your agent CLI spawns, once per tool call",
+        sections: [
+          {
+            label: "usage",
+            entries: [["failproofai --hook <event> [--cli <name>]"]],
+            after: [
+              "You do not run this; `failproofai config` writes it into each CLI's",
+              "hook configuration for you.",
+            ],
+          },
+          {
+            label: "options",
+            entries: [
+              ["--hook <event>", "PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact, Notification, PermissionRequest"],
+              ["--cli <name>", "claude, codex, copilot, cursor, opencode, pi, hermes, openclaw, factory, devin, antigravity, goose. Defaults to claude. It selects which payload shape to expect: each CLI names its events and tool arguments differently, and failproofai canonicalizes them."],
+            ],
+          },
+          {
+            label: "how it answers",
+            lines: [
+              "It reads the event as JSON on stdin and answers on stdout, in whatever",
+              "shape that CLI honours. Exit codes and response shapes differ per CLI by",
+              "necessity — see docs.befailproof.ai. Denials are reported to the agent,",
+              "never to you.",
+            ],
+          },
+        ],
+      });
+      process.exit(0);
       process.exit(0);
     }
     // Canonicalize the topic the same way a typed command is canonicalized, so
@@ -369,62 +451,53 @@ see docs.befailproof.ai. Denials are reported to the agent, never to you.
     if (extraArgs.length > 0) {
       throw new CliError(`Unexpected argument: ${extraArgs[0]}\nRun \`failproofai help\` for usage.`);
     }
-    // Built row by row rather than as one literal, so the command column can be
-    // painted without the escape sequences becoming part of the layout. Colour
-    // is decoration here and never meaning: the column position already says
-    // which half is a command, so this reads identically under NO_COLOR, piped
-    // to a file, or on a terminal that has never heard of 24-bit.
-    const { brandAnsi, ANSI_RESET, ANSI_BOLD, ANSI_DIM, colorsEnabled } =
-      await import("../src/hooks/tui");
-    const tint = colorsEnabled(process.stdout);
-    const pink = (t) => (tint ? `${brandAnsi("pink")}${t}${ANSI_RESET}` : t);
-    const mint = (t) => (tint ? `${brandAnsi("guide")}${t}${ANSI_RESET}` : t);
-    const dim = (t) => (tint ? `${ANSI_DIM}${t}${ANSI_RESET}` : t);
-    const bold = (t) => (tint ? `${ANSI_BOLD}${t}${ANSI_RESET}` : t);
-
-    // Padded BEFORE painting: an escape sequence has no width, so padding a
-    // coloured string right-aligns nothing and the description column drifts.
-    const row = (cmd, desc) => `  ${pink(cmd.padEnd(18))}${desc}`;
-    // 78 visible columns, matching the body. Computed from the VISIBLE prefix —
-    // `"  \u2501\u2501 "` is 5, the label is `${n}  ${title}`, then one space — because the
-    // painted string's length counts escape bytes and would shorten every rule
-    // by however many the terminal happened to need.
-    const section = (n, title) => {
-      const label = `${n}  ${title}`;
-      const fill = 78 - (5 + label.length + 1);
-      return dim("  \u2501\u2501 ") + bold(label) + " " + dim("\u2501".repeat(Math.max(0, fill)));
-    };
-
-    console.log([
-      `${bold("fa")}${pink("il")}${bold("proofai")} v${version}` +
-        `${" ".repeat(23)}${dim("-v version   -h this screen")}`,
-      `  ${dim("Usage")}  failproofai <command> [options]    ${dim("Detail")}  failproofai help <command>`,
-      section(1, "GET IT RUNNING"),
-      row("config, setup", "Interactive setup: agents, daemon, cloud"),
-      row("config --connect", "Connect to Cloud with no prompts: --token <key>"),
-      row("update", "Finish an npm upgrade: migrate home, match daemon"),
-      section(2, "CHOOSE WHAT IT ENFORCES"),
-      row("policies", "Every policy on this machine, and whether it is on"),
-      row("policies add", "Pick from a list, or name one: <policy> or <owner>/<repo>"),
-      row("policies remove", "Turn one policy off, or uninstall a whole pack"),
-      row("policies show", "What a pack contains, before you install it"),
-      row("publish", "Ship your own policies as a pack anyone can install"),
-      section(3, "SEE WHAT IT CAUGHT"),
-      row("(no args)", "Open the policy dashboard on localhost:8020"),
-      row("audit", "Scan your agents' history, then open the audit view"),
-      row("config --status", "Cloud connection, daemon version, pause state"),
-      row("harness", "Extra paths to capture agent sessions from"),
-      section(4, "PUT IT RIGHT"),
-      row("config --pause", "Pause enforcement for one session (30m; max 8h)"),
-      row("flush --wait", "Send everything spooled now, and block until it lands"),
-      row("backfill --since", "Re-send history already read past: 30d, 6m, YYYY-MM-DD"),
-      row("policies -i / -u", "Wire failproofai into your agent CLIs, or unwire"),
-      row("migrate", "Run pending ~/.failproofai layout migrations"),
-      row("uninstall", "Remove hooks and daemon, BEFORE npm rm -g failproofai"),
-      "",
-      `  ${dim("Docs")}  ${mint("docs.befailproof.ai")}           ${dim("Code")}  github.com/failproofai/failproofai`,
-      `  ${dim("Chat")}  ${mint("discord.befailproof.ai")}        ${dim("Forum")} reddit.com/r/failproofai`,
-    ].join("\n"));
+    // The index is DATA, not a template literal: one renderer draws it and the
+    // eleven `<command> --help` screens, so a row added here cannot end up in a
+    // different dialect from the screen it points at. Colour is decoration and
+    // never meaning — the column position already says which half is a command,
+    // so this reads identically under NO_COLOR, piped to a file, or on a
+    // terminal that has never heard of 24-bit.
+    await printHelp({
+      tagline: "guardrails for the coding agents on this machine",
+      sections: [
+        {
+          label: "get it running",
+          entries: [
+            ["config", "Set this machine up: agents, daemon, cloud"],
+            ["config --token <key>", "Set up and connect to Cloud, no questions asked"],
+            ["update", "Finish an npm upgrade: migrate home, match the daemon"],
+          ],
+        },
+        {
+          label: "choose what it enforces",
+          entries: [
+            ["policies", "Every policy on this machine, and whether it is on"],
+            ["policies add", "Turn one on, or install a pack: <owner>/<repo>"],
+            ["policies remove", "Turn one off, or uninstall a whole pack"],
+            ["publish", "Ship your own policies as a pack anyone can install"],
+          ],
+        },
+        {
+          label: "see what it caught",
+          entries: [
+            ["(no args)", "Open the policy dashboard on localhost:8020"],
+            ["audit", "Scan your agents' history, then open the audit view"],
+            ["config --status", "Cloud connection, daemon version, pause state"],
+          ],
+        },
+        // Named, not described. Everything here is real and reachable through
+        // `help <command>`; none of it is what anyone types on the first day,
+        // and a full row each is what made this screen read as a manual.
+        {
+          label: "less often",
+          lines: ["policies show, harness, flush, backfill, migrate, uninstall, config --pause"],
+        },
+      ],
+      footer: [
+        "failproofai <command> [options]     failproofai help <command> for detail",
+        "docs.befailproof.ai   discord.befailproof.ai   -h this screen   -v version",
+      ],
+    });
     process.exit(0);
   }
 
@@ -574,27 +647,35 @@ see docs.befailproof.ai. Denials are reported to the agent, never to you.
   if (args[0] === "flush") {
     const subArgs = args.slice(1);
     if (subArgs.includes("--help") || subArgs.includes("-h")) {
-      console.log(`
-failproofai flush — deliver what is already spooled, now
-
-USAGE
-  failproofai flush [--wait] [--timeout <secs>]
-
-WHY
-  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. That pacing keeps a
-  backlog from stampeding the server, and it is exactly wrong when you are
-  standing at a dashboard waiting to see your own events — "not delivered yet"
-  and "not working" look identical from there.
-
-  This asks the daemon to make a pass right now, with no minimum age and no
-  per-pass cap. It re-sends nothing: only batches already spooled and not yet
-  delivered. For history the collector has already read past, use \`backfill\`.
-
-OPTIONS
-  --wait             Block until the spool drains, or --timeout elapses.
-  --timeout <secs>   How long --wait waits. Default: 60.
-`);
+      await printHelp({
+        command: "flush",
+        tagline: "deliver what is already spooled, now",
+        sections: [
+          { label: "usage", entries: [["failproofai flush [--wait] [--timeout <secs>]"]] },
+          {
+            label: "why",
+            lines: [
+              "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. That pacing",
+              "keeps a backlog from stampeding the server, and it is exactly wrong when",
+              "you are standing at a dashboard waiting to see your own events — \"not",
+              "delivered yet\" and \"not working\" look identical from there.",
+              "",
+              "This asks the daemon to make a pass right now, with no minimum age and no",
+              "per-pass cap. It re-sends nothing: only batches already spooled and not",
+              "yet delivered. For history the collector has already read past, use",
+              "`failproofai backfill`.",
+            ],
+          },
+          {
+            label: "options",
+            entries: [
+              ["--wait", "Block until the spool drains, or --timeout elapses."],
+              ["--timeout <secs>", "How long --wait waits. Default: 60."],
+            ],
+          },
+        ],
+      });
       process.exit(0);
     }
 
@@ -623,10 +704,7 @@ OPTIONS
     lastSubcommand = "flush";
     const { runFlushCommand } = await import("../src/hooks/flush-cli");
     const result = await runFlushCommand({ wait: subArgs.includes("--wait"), timeoutSecs });
-    for (const line of result.lines) {
-      if (result.exitCode === 0) console.log(line);
-      else console.error(line);
-    }
+    await printReport("flush", result.lines, { ok: result.exitCode === 0 });
     await track("cli_flush", {
       ok: result.exitCode === 0,
       waited: subArgs.includes("--wait"),
@@ -640,29 +718,39 @@ OPTIONS
   if (args[0] === "backfill") {
     const subArgs = args.slice(1);
     if (subArgs.includes("--help") || subArgs.includes("-h")) {
-      console.log(`
-failproofai backfill — re-send history the collector has already read past
-
-USAGE
-  failproofai backfill [--since <when>] [--dry-run]
-
-WHY
-  The collector never re-reads a file it has a cursor for, which is right until
-  the dashboard's data is cleared, a machine is re-enrolled, or cursors advanced
-  before there was anywhere to send. Then the history exists on disk and nowhere
-  else, with no way to ask for it again.
-
-  Re-sending is safe: redaction is deterministic, so a re-sent event hashes
-  identically to its first send and collapses into the row already there.
-
-OPTIONS
-  --since <when>   How far back. \`30d\`, \`6m\`, or \`YYYY-MM-DD\`.
-                   Default: 30 days.
-  --dry-run        Report what would be re-read and change nothing.
-
-  Which streams are sent follows [collector] in ~/.failproofai/config.toml —
-  a backfill never sends something your config says you do not want.
-`);
+      await printHelp({
+        command: "backfill",
+        tagline: "re-send history the collector has already read past",
+        sections: [
+          { label: "usage", entries: [["failproofai backfill [--since <when>] [--dry-run]"]] },
+          {
+            label: "why",
+            lines: [
+              "The collector never re-reads a file it has a cursor for, which is right",
+              "until the dashboard's data is cleared, a machine is re-enrolled, or",
+              "cursors advanced before there was anywhere to send. Then the history",
+              "exists on disk and nowhere else, with no way to ask for it again.",
+              "",
+              "Re-sending is safe: redaction is deterministic, so a re-sent event hashes",
+              "identically to its first send and collapses into the row already there.",
+            ],
+          },
+          {
+            label: "options",
+            entries: [
+              ["--since <when>", "How far back: `30d`, `6m`, `YYYY-MM-DD`. Default 30 days."],
+              ["--dry-run", "Report what would be re-read and change nothing."],
+            ],
+          },
+          {
+            label: "note",
+            lines: [
+              "Which streams are sent follows [collector] in ~/.failproofai/config.toml —",
+              "a backfill never sends something your config says you do not want.",
+            ],
+          },
+        ],
+      });
       process.exit(0);
     }
 
@@ -697,10 +785,7 @@ OPTIONS
     lastSubcommand = "backfill";
     const { runBackfillCommand } = await import("../src/hooks/backfill-cli");
     const result = runBackfillCommand({ sinceMs, dryRun: subArgs.includes("--dry-run") });
-    for (const line of result.lines) {
-      if (result.exitCode === 0) console.log(line);
-      else console.error(line);
-    }
+    await printReport("backfill", result.lines, { ok: result.exitCode === 0 });
     await track("cli_backfill", { ok: result.exitCode === 0, dry_run: subArgs.includes("--dry-run"), explicit_since: sinceIdx >= 0 });
     lastSubcommand = null;
     await exitAfterFlush(result.exitCode);
@@ -713,156 +798,102 @@ OPTIONS
   // 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.
-  // pack list | add | remove
-  //
-  // Policies that did not ship compiled into this build. Fetches over the
-  // network, so it is a CLI command only and is never reachable from the hook
-  // path.
-  if (args[0] === "pack") {
-    const subArgs = args.slice(1);
-    if (subArgs.includes("--help") || subArgs.includes("-h")) {
-      console.log(`
-failproofai pack — install policy packs published as GitHub releases
-
-Usage:
-  failproofai policies add FailproofAI/policies                     the Failproof AI policies
-  failproofai policies add FailproofAI/policies --policy <a,b>      just these
-  failproofai policies add FailproofAI/policies --category <x,y>    whole categories
-  failproofai policies add FailproofAI/policies --all               everything in it
-  failproofai pack list                         packs installed here
-  failproofai pack list <source>                what a pack out there contains
-  failproofai pack add <source> [--policy <a,b>] [--category <x,y>] [--all]
-  failproofai pack remove <publisher/name>
-  failproofai pack build <entry.mjs> --id <publisher/name> --version <v>
-
-A pack is one entry artifact plus a manifest, verified against the release's
-SHA256SUMS at install time. The digest is recorded, and re-verified before every
-import — so a pack cannot change under this machine after you installed it.
-
-<source> is any GitHub repo publishing a pack — ours included:
-  acme/support-agent                 newest release, pinned to its exact tag
-  acme/support-agent@v2.1.0          that release
-  github:acme/support-agent@v2.1.0   same, explicit
-  https://github.com/acme/support-agent/releases/tag/v2.1.0
-
-Naming no tag installs the newest release AND pins it, so what gets recorded
-always names one version — running the same command later can install something
-different, and it will tell you the tag it chose.
-
-By default you get the pack's OWN defaults — the policies its author marked
-safe to switch on unattended — not everything it contains. Take more, or less:
-
-  --category x,y  Take whole categories (see: failproofai pack list)
-  --only a,b      Take exactly these policies
-  --all           Take everything the pack contains
-
-Re-adding at a newer version keeps whatever you chose rather than switching the
-rest back on.
-
-Examples:
-  failproofai pack add FailproofAI/policies
-  failproofai policies add FailproofAI/policies --category sanitize,git
-  failproofai pack add github:acme/support-agent@v2.1.0 --only block-refunds
-  failproofai pack remove acme/support-agent
-
-Publishing: pack build writes failproofai-pack.json, failproofai-pack.mjs and
-SHA256SUMS. Attach all three to a GitHub release; anyone then runs
-failproofai pack add <owner>/<repo>
-
-Offline: FAILPROOFAI_NO_DOWNLOAD=1 refuses to fetch, while packs already
-installed keep enforcing. FAILPROOFAI_PACK_BASE_URL points the whole thing at a
-mirror instead of github.com.
-`.trimStart());
-      process.exit(0);
-    }
-
-    lastSubcommand = "pack";
-    const { runPackCommand } = await import("../src/hooks/pack-cli");
-    const result = await runPackCommand(subArgs);
-    for (const line of result.lines) {
-      if (result.exitCode === 0) console.log(line);
-      else console.error(line);
-    }
-    await track("cli_pack", {
-      ok: result.exitCode === 0,
-      // The subcommand only — never the pack id, source or policy names. A pack
-      // source is a value the user typed, and a third-party pack name is a
-      // publisher-controlled string; we send shape, never value.
-      sub: ["list", "add", "remove"].includes(subArgs[0]) ? subArgs[0] : "unknown",
-    });
-    lastSubcommand = null;
-    await exitAfterFlush(result.exitCode);
-    return;
-  }
+  // There is no `pack` branch here on purpose. `pack`, `policy` and `p` are
+  // rewritten to `policies` at the top of this file, above every dispatch, so
+  // `args[0]` can never be "pack" by the time this runs. One lived here anyway
+  // for a while, unreachable, carrying a sixty-line help screen that still
+  // advertised `pack list`, `pack add` and `pack build` — three spellings this
+  // CLI no longer has — in a third heading dialect nothing else used. Nobody
+  // could reach it to notice. The pack lane is entered from
+  // `policies add|remove|show` below, which is the only door it has.
 
   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 live
-    under "collector" in ~/.failproofai/config.json 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.
-  • Two entries sharing a LABEL are refused too: they would share one cursor
-    directory, whose whole map is written at once, so each would clobber the
-    other's watermark and re-read from zero after every restart.
-  • Takes effect within seconds — the daemon re-reads config.json on an interval
-    and cycles its collector. No restart, no sudo.
-
-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
-
-  One home per person — label them, or both derive the same folder-name label
-  and the second is refused:
-  failproofai harness add-path openclaw user1=/srv/.openclaw-user1
-  failproofai harness add-path openclaw user2=/srv/.openclaw-user2
-
-  Containers: FAILPROOFAI_<HARNESS>_EXTRA_PATHS replaces the file's entries.
-  FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/.openclaw-user1,user2=/srv/.openclaw-user2"
-
-`.trimStart());
+      await printHelp({
+        command: "harness",
+        tagline: "capture sessions from more than one location per agent CLI",
+        sections: [
+          {
+            label: "usage",
+            entries: [
+              ["failproofai harness list [<harness>]"],
+              ["failproofai harness add-path <harness> [<label>=]<path>"],
+              ["failproofai harness remove-path <harness> <path|label>"],
+            ],
+          },
+          {
+            label: "why",
+            lines: [
+              "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.",
+            ],
+          },
+          {
+            label: "the label",
+            lines: [
+              "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.",
+            ],
+          },
+          {
+            label: "harnesses",
+            lines: [
+              "claude, codex, copilot, openclaw, pi, factory, antigravity, cursor,",
+              "goose, opencode, devin, hermes",
+              "",
+              "`claude` covers subagent transcripts too — they live under the same root.",
+            ],
+          },
+          {
+            label: "notes",
+            lines: [
+              "• Session collection must be on for any of this to be read; extra paths",
+              "  live under \"collector\" in ~/.failproofai/config.json like the defaults.",
+              "• 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.",
+              "• Two entries sharing a LABEL are refused too: they would share one",
+              "  cursor directory, whose whole map is written at once, so each would",
+              "  clobber the other's watermark and re-read from zero after a restart.",
+              "• Takes effect within seconds — the daemon re-reads config.json on an",
+              "  interval and cycles its collector. No restart, no sudo.",
+            ],
+          },
+          {
+            label: "examples",
+            lines: [
+              "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",
+              "",
+              "One home per person — label them, or both derive the same folder-name",
+              "label and the second is refused:",
+              "failproofai harness add-path openclaw user1=/srv/.openclaw-user1",
+              "failproofai harness add-path openclaw user2=/srv/.openclaw-user2",
+              "",
+              "Containers: FAILPROOFAI_<HARNESS>_EXTRA_PATHS replaces the file's entries.",
+              "FAILPROOFAI_OPENCLAW_EXTRA_PATHS=\"user1=/srv/.a,user2=/srv/.b\"",
+            ],
+          },
+        ],
+      });
       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 printLines(result.lines, result.exitCode === 0);
     await track("cli_harness", {
       ok: result.exitCode === 0,
       // The subcommand only — never the harness name, the label or the path.
@@ -884,30 +915,38 @@ EXAMPLES
   if (args[0] === "migrate") {
     const subArgs = args.slice(1);
     if (subArgs.includes("--help") || subArgs.includes("-h")) {
-      console.log(`
-failproofai migrate — bring ~/.failproofai up to the layout this version speaks
-
-USAGE
-  failproofai migrate [--dry-run]
-
-WHY
-  npm cannot update an installed package on its own, so a machine can sit on an
-  old version for months and then jump several layouts at once. This runs the
-  steps for that jump in order, keyed on the LAYOUT recorded in
-  ~/.failproofai/VERSION rather than on the npm version — so skipping thirty
-  releases with no layout change runs nothing at all.
-
-  It normally happens by itself, on the first command after an upgrade. This is
-  for running it deliberately, and for seeing what it would do first.
-
-  Your settings, cloud enrolment, policy selection, your own policy files,
-  decision history and undelivered events are carried across, not removed. The
-  irreplaceable files are copied to migrations/backup-layout<n>/ before anything
-  runs, and every step is recorded in migrations/applied.json.
-
-OPTIONS
-  --dry-run   Print the steps and the files that would be saved. Change nothing.
-`);
+      await printHelp({
+        command: "migrate",
+        tagline: "bring ~/.failproofai up to the layout this version speaks",
+        sections: [
+          { label: "usage", entries: [["failproofai migrate [--dry-run]"]] },
+          {
+            label: "why",
+            lines: [
+              "npm cannot update an installed package on its own, so a machine can sit",
+              "on an old version for months and then jump several layouts at once. This",
+              "runs the steps for that jump in order, keyed on the LAYOUT recorded in",
+              "~/.failproofai/VERSION rather than on the npm version — so skipping",
+              "thirty releases with no layout change runs nothing at all.",
+              "",
+              "It normally happens by itself, on the first command after an upgrade.",
+              "This is for running it deliberately, and for seeing what it would do",
+              "first.",
+              "",
+              "Your settings, cloud enrolment, policy selection, your own policy files,",
+              "decision history and undelivered events are carried across, not removed.",
+              "The irreplaceable files are copied to migrations/backup-layout<n>/ before",
+              "anything runs, and every step is recorded in migrations/applied.json.",
+            ],
+          },
+          {
+            label: "options",
+            entries: [
+              ["--dry-run", "Print the steps and the files it would save. Change nothing."],
+            ],
+          },
+        ],
+      });
       process.exit(0);
     }
 
@@ -929,11 +968,12 @@ OPTIONS
     // data is fine and an upgrade would read it, so migrating "forward" from it
     // is not a thing that exists.
     if (state.kind === "future") {
-      console.error(
-        `This machine's failproofai directory was written by a newer version (layout ${state.found};`,
-      );
-      console.error(`this build speaks ${LAYOUT_VERSION}). Upgrade rather than migrate:`);
-      console.error(`  npm install -g failproofai@latest`);
+      await printReport("migrate", [
+        `This machine's failproofai directory was written by a newer version ` +
+          `(layout ${state.found}; this build speaks ${LAYOUT_VERSION}). Upgrade rather than migrate:`,
+        "",
+        "  npm install -g failproofai@latest",
+      ], { ok: false, meta: `layout ${state.found}` });
       await track("cli_migrate", { ok: false, reason: "future_layout" });
       lastSubcommand = null;
       await exitAfterFlush(1);
@@ -942,7 +982,7 @@ OPTIONS
 
     const from = state.kind === "stale" ? state.found : LAYOUT_VERSION;
     if (subArgs.includes("--dry-run")) {
-      for (const line of describePlan(from)) console.log(line);
+      await printReport("migrate", describePlan(from), { meta: "dry run" });
       await track("cli_migrate", { ok: true, dry_run: true, from });
       lastSubcommand = null;
       await exitAfterFlush(0);
@@ -950,7 +990,7 @@ OPTIONS
     }
 
     if (state.kind !== "stale") {
-      console.log(`Already at layout ${LAYOUT_VERSION}. Nothing to migrate.`);
+      await printReport("migrate", [`Already at layout ${LAYOUT_VERSION}. Nothing to migrate.`]);
       await track("cli_migrate", { ok: true, from, steps: 0 });
       lastSubcommand = null;
       await exitAfterFlush(0);
@@ -958,16 +998,21 @@ OPTIONS
     }
 
     const run = runMigrations(from);
-    for (const step of run.steps) {
-      console.log(`${step.ok ? "migrated" : "FAILED  "} layout ${step.from} → ${step.to}`);
-    }
-    if (run.backedUp.length > 0) {
-      console.log(`Saved first: ${run.backedUp.join(", ")}`);
-    }
+    const report = run.steps.map(
+      (step) => `  ${step.ok ? "migrated" : "FAILED  "} layout ${step.from} → ${step.to}`,
+    );
+    if (run.backedUp.length > 0) report.push("", `Saved first: ${run.backedUp.join(", ")}`);
     if (run.failed) {
-      console.error(`Step ${run.failed.from} → ${run.failed.to} did not finish: ${run.failed.error}`);
-      console.error(`The home is still marked layout ${from} and will be retried.`);
+      report.push(
+        "",
+        `Step ${run.failed.from} → ${run.failed.to} did not finish: ${run.failed.error}`,
+        `The home is still marked layout ${from} and will be retried.`,
+      );
     }
+    await printReport("migrate", report, {
+      ok: !run.failed,
+      meta: `layout ${from} → ${LAYOUT_VERSION}`,
+    });
     await track("cli_migrate", {
       ok: !run.failed,
       from,
@@ -982,26 +1027,35 @@ OPTIONS
   if (args[0] === "update") {
     const subArgs = args.slice(1);
     if (subArgs.includes("--help") || subArgs.includes("-h")) {
-      console.log(`
-failproofai update — finish an upgrade: migrate the home, match the daemon
-
-USAGE
-  npm install -g failproofai@latest && failproofai update [--no-daemon]
-
-WHY
-  npm replaces the CLI and nothing else. The daemon binary lives at
-  ~/.failproofai/bin/failproofaid-<version> and stays exactly where it was, so
-  after an npm upgrade the two halves are different versions — and failproofaid
-  refuses to start against a layout it does not speak, which is the loud version
-  of that problem rather than the silent one.
-
-  This does the rest of the upgrade: runs any pending layout migrations, puts the
-  matching daemon binary in place, and restarts the service.
-
-OPTIONS
-  --no-daemon   Migrate the home only. Leaves a version-skewed daemon in place,
-                so prefer letting it run.
-`);
+      await printHelp({
+        command: "update",
+        tagline: "finish an upgrade: migrate the home, match the daemon",
+        sections: [
+          {
+            label: "usage",
+            entries: [["npm install -g failproofai@latest && failproofai update [--no-daemon]"]],
+          },
+          {
+            label: "why",
+            lines: [
+              "npm replaces the CLI and nothing else. The daemon binary lives at",
+              "~/.failproofai/bin/failproofaid-<version> and stays exactly where it was,",
+              "so after an npm upgrade the two halves are different versions — and",
+              "failproofaid refuses to start against a layout it does not speak, which",
+              "is the loud version of that problem rather than the silent one.",
+              "",
+              "This does the rest of the upgrade: runs any pending layout migrations,",
+              "puts the matching daemon binary in place, and restarts the service.",
+            ],
+          },
+          {
+            label: "options",
+            entries: [
+              ["--no-daemon", "Migrate the home only. Leaves a version-skewed daemon in place, so prefer letting it run."],
+            ],
+          },
+        ],
+      });
       process.exit(0);
     }
 
@@ -1025,17 +1079,22 @@ OPTIONS
     const state = detectLayout();
 
     if (state.kind === "future") {
-      console.error(
-        `This machine's failproofai directory was written by a NEWER version (layout ${state.found};`,
-      );
-      console.error(`this build speaks ${LAYOUT_VERSION}). This CLI is the stale half:`);
-      console.error(`  npm install -g failproofai@latest`);
+      await printReport("update", [
+        `This machine's failproofai directory was written by a NEWER version ` +
+          `(layout ${state.found}; this build speaks ${LAYOUT_VERSION}). This CLI is the stale half:`,
+        "",
+        "  npm install -g failproofai@latest",
+      ], { ok: false, meta: `layout ${state.found}` });
       await track("cli_update", { ok: false, reason: "future_layout" });
       lastSubcommand = null;
       await exitAfterFlush(1);
       return;
     }
 
+    // Collected rather than printed as it goes, so `update` closes with ONE
+    // report — heading, then both halves of the upgrade under it — instead of
+    // a run of bare sentences at column zero.
+    const report = [];
     let migrationsRan = 0;
     let migrationFailed = false;
     if (state.kind === "stale") {
@@ -1043,17 +1102,18 @@ OPTIONS
       migrationsRan = run.steps.length;
       migrationFailed = Boolean(run.failed);
       for (const step of run.steps) {
-        console.log(`${step.ok ? "migrated" : "FAILED  "} layout ${step.from} → ${step.to}`);
+        report.push(`  ${step.ok ? "migrated" : "FAILED  "} layout ${step.from} → ${step.to}`);
       }
-      if (run.backedUp.length > 0) console.log(`Saved first: ${run.backedUp.join(", ")}`);
+      if (run.backedUp.length > 0) report.push("", `Saved first: ${run.backedUp.join(", ")}`);
       if (run.failed) {
-        console.error(
+        report.push(
+          "",
           `Step ${run.failed.from} → ${run.failed.to} did not finish: ${run.failed.error}`,
+          `The home is still marked layout ${state.found} and will be retried.`,
         );
-        console.error(`The home is still marked layout ${state.found} and will be retried.`);
       }
     } else {
-      console.log(`Home is at layout ${LAYOUT_VERSION}; no migration was needed.`);
+      report.push(`Home is at layout ${LAYOUT_VERSION}; no migration was needed.`);
     }
 
     // The daemon is refreshed even when a step failed, and deliberately: the
@@ -1062,20 +1122,24 @@ OPTIONS
     // the half that can be fixed. The exit code still reports the failure.
     let daemonOk = true;
     if (subArgs.includes("--no-daemon")) {
-      console.log("Skipped the daemon (--no-daemon). Its version may not match this CLI.");
+      report.push("", "Skipped the daemon (--no-daemon). Its version may not match this CLI.");
     } else {
       const svc = await import("../src/hooks/daemon-service");
       if (!svc.isDaemonSupportedPlatform()) {
-        console.log(`failproofaid does not run on ${process.platform}; nothing to update.`);
+        report.push("", `failproofaid does not run on ${process.platform}; nothing to update.`);
       } else {
         // `refreshDaemonToCliVersion` answers "is there a service at all" itself,
         // so there is no separate installed check to get out of step with it.
         const result = await svc.refreshDaemonToCliVersion();
-        for (const line of result.lines) console.log(line);
+        report.push("", ...result.lines);
         daemonOk = result.ok;
       }
     }
 
+    await printReport("update", report, {
+      ok: daemonOk && !migrationFailed,
+      meta: `v${version}`,
+    });
     await track("cli_update", {
       ok: daemonOk && !migrationFailed,
       migrations: migrationsRan,
@@ -1089,32 +1153,41 @@ OPTIONS
   if (args[0] === "uninstall") {
     const subArgs = args.slice(1);
     if (subArgs.includes("--help") || subArgs.includes("-h")) {
-      console.log(`
-failproofai uninstall — remove failproofai from this machine
-
-USAGE
-  failproofai uninstall [--purge] [--dry-run] [--yes]
-
-WHAT IT REMOVES
-  • failproofai hook entries from every agent CLI that has them
-  • the failproofaid daemon service — ASKED on a plain uninstall (kept unless
-    you say yes); always removed with --purge, which prompts for your password
-    rather than printing commands to paste
-  • the "require the daemon" flag — cleared FIRST, so a partial uninstall can
-    never leave this machine denying every tool call
-
-OPTIONS
-  --purge         Also delete ~/.failproofai — settings, credentials, audit
-                  history and the downloaded daemon binary. Off by default so a
-                  reinstall keeps your history.
-  --dry-run       Print what would be removed and change nothing.
-  --yes, -y       Skip the confirmation prompt. Required when there is no TTY.
-
-WHY THIS EXISTS
-  npm runs no uninstall script, so \`npm rm -g failproofai\` removes the package
-  and leaves the hook entries and the service behind. Run this first, then:
-      npm rm -g failproofai
-`);
+      await printHelp({
+        command: "uninstall",
+        tagline: "remove failproofai from this machine",
+        sections: [
+          { label: "usage", entries: [["failproofai uninstall [--purge] [--dry-run] [--yes]"]] },
+          {
+            label: "what it removes",
+            lines: [
+              "• failproofai hook entries from every agent CLI that has them",
+              "• the failproofaid daemon service — ASKED on a plain uninstall (kept",
+              "  unless you say yes); always removed with --purge, which prompts for",
+              "  your password rather than printing commands to paste",
+              "• the \"require the daemon\" flag — cleared FIRST, so a partial uninstall",
+              "  can never leave this machine denying every tool call",
+            ],
+          },
+          {
+            label: "options",
+            entries: [
+              ["--purge", "Also delete ~/.failproofai — settings, credentials, audit history and the downloaded daemon binary. Off by default so a reinstall keeps your history."],
+              ["--dry-run", "Print what would be removed and change nothing."],
+              ["--yes, -y", "Skip the confirmation prompt. Required when there is no TTY."],
+            ],
+          },
+          {
+            label: "why this exists",
+            lines: [
+              "npm runs no uninstall script, so `npm rm -g failproofai` removes the",
+              "package and leaves the hook entries and the service behind. Run this",
+              "first, then:",
+              "    npm rm -g failproofai",
+            ],
+          },
+        ],
+      });
       process.exit(0);
     }
 
@@ -1191,10 +1264,10 @@ WHY THIS EXISTS
     // show the same block twice. `planLines` is reported by the command rather
     // than guessed from the text — see UninstallResult.
     const skip = planWasShown ? result.planLines : 0;
-    for (const line of result.lines.slice(skip)) {
-      if (result.exitCode === 0) console.log(line);
-      else console.error(line);
-    }
+    await printReport("uninstall", result.lines.slice(skip), {
+      ok: result.exitCode === 0,
+      meta: subArgs.includes("--purge") ? "purge" : subArgs.includes("--dry-run") ? "dry run" : undefined,
+    });
     // NOT after a purge. `track` resolves the instance id, and `getInstanceId()`
     // lazily WRITES ~/.failproofai/state/telemetry-id — which re-created the
     // whole directory seconds after the purge deleted it, leaving a machine the
@@ -1226,118 +1299,139 @@ WHY THIS EXISTS
     // worked out from the directory and the git remote. Printing help there
     // made the one documented command the only one that did nothing.
     if (subArgs.includes("--help") || subArgs.includes("-h")) {
-      console.log(`
-failproofai publish — ship your policies as a pack anyone can install
-
-TWO COMMANDS, FROM NOTHING
-
-  failproofai publish --init      write a policy to start from
-  failproofai publish             ship it
-
-  Write your policies in a git repo, run publish, answer one question, done.
-  It asks WHERE only when nothing tells it — no remote to read — and works
-  the rest out: which files hold policies, what version is next, who you are.
-
-  Every flag below overrides something it would otherwise decide for you.
-  None of them is required, and on a pipe or in CI the flags are all there
-  is: nothing prompts where nobody can answer.
-
-WHAT --init DOES
-  Asks what the pack is called, writes <name>.mjs, and stops. No network, no
-  git, nothing published.
-
-  The file is not a template with blanks — it is one policy that already
-  blocks git push --force. So the first thing you do is edit something that
-  works. Refuses rather than overwriting a file that already exists.
-
-  Then try it on THIS machine, before anyone else can see it:
-
-    failproofai policies -i -c ./<name>.mjs
-
-  That enforces the file right now — any path, any filename. Ask your agent to
-  do the thing you blocked and watch it get refused. Iterate here; nothing is
-  published and nobody else is affected.
-
-WHAT publish DOES
-  In order, and it stops before touching GitHub if anything is wrong:
-
-  1  Finds the policy file here, by CONTENT — one that imports failproofai
-     and calls customPolicies.add — not by filename. So it finds guards.mjs
-     and ignores an unrelated policies.mjs. Not recursive: publishing a
-     fixture is worse than being asked. Two candidates and it lists them.
-  2  Reads the repo from git remote get-url origin, in the FILE's directory
-     rather than yours — a policy in another checkout is normal.
-  3  Decides the version (see below).
-  4  Finds your credential: GITHUB_TOKEN, GH_TOKEN, or gh auth login. Needs
-     release-write and nothing else. Never printed.
-  5  Creates the repository if it does not exist. Public — see below.
-  6  Builds the three assets, validating with the LOADER's own rules: the code
-     that decides what may install on a stranger's machine. A pack that could
-     never install fails here, where you can fix it.
-  7  Creates or reuses the release, and uploads the assets — replacing any of
-     the same name, because the install URL is built from fixed names and a
-     stale copy is what somebody would fetch.
-
-HOW THE VERSION IS DECIDED
-  --version if you pass one. Otherwise a tag on HEAD — someone who tagged
-  v1.2.0 has SAID what this release is. Otherwise one past the highest version
-  the repository has already published: 1.0.0, then 1.0.1, and so on.
-
-  Counted from the repository's own releases, not anything local, so a fresh
-  clone still gets the right number and two people cannot both mint 1.0.1.
-  Releases that are not semver (nightly) are ignored rather than guessed at.
-
-  A tag names a COMMIT, so it is refused when the file has uncommitted changes:
-  those bytes are not in that commit, and two packs would claim one version. A
-  counted version names no commit and has no such problem.
-
-THE REPO MUST BE PUBLIC
-  Installs are anonymous HTTPS with no credential to offer, so a private
-  repository publishes to nobody. A repo created here is public for that
-  reason; an existing private one still publishes, and warns.
-
-  Only the release matters. Installs read releases/download/<tag>/<asset> and
-  never touch your git tree — pushing the source is for humans reading it.
-
-YOUR POLICY FILES
-  Write as many as you like — one per category reads well. Every file here
-  that registers policies is found and bundled into the single artifact a
-  pack has to be, because only the entry is digest-pinned and a pack
-  importing siblings could not honestly claim to be verified. Bundling needs
-  bun; without it, name one self-contained file.
-
-  Each policy may carry category and defaultEnabled alongside the usual
-  fields. category is what --category selects on; defaultEnabled is what a
-  bare 'policies add' switches on, and it defaults to false.
-
-OPTIONS
-  --init [file]           Write a starter policy and stop.
-  --repo <owner>/<repo>   Where to release it, created if missing.
-  --version <version>     Skip the counting and say which version this is.
-  --id <publisher/name>   The pack's id. Defaults to --repo.
-  --tag <tag>             Release tag. Defaults to the version; v prefix ok.
-  --notes <text>          Release notes.
-  --out <dir>             Where to write the assets (default: dist-pack)
-  --effect enforce|observe
-                          observe records and blocks nothing (default: enforce)
-  --dry-run               Build the assets, publish nothing. No credential.
-
-EXAMPLES
-  failproofai publish --init
-  failproofai publish
-  failproofai publish --dry-run
-  failproofai publish ./guards.mjs --repo me/guards --version 2.0.0
-`.trimStart());
+      await printHelp({
+        command: "publish",
+        tagline: "ship your policies as a pack anyone can install",
+        sections: [
+          {
+            label: "two commands, from nothing",
+            entries: [
+              ["failproofai publish --init", "write a policy to start from"],
+              ["failproofai publish", "ship it"],
+            ],
+            after: [
+              "Write your policies in a git repo, run publish, answer one question,",
+              "done. It asks WHERE only when nothing tells it — no remote to read —",
+              "and works the rest out: which files hold policies, what version is",
+              "next, who you are. Every flag below overrides something it would",
+              "otherwise decide. None is required, and on a pipe or in CI the flags",
+              "are all there is: nothing prompts where nobody can answer.",
+            ],
+          },
+          {
+            label: "what --init does",
+            lines: [
+              "Asks what the pack is called, writes <name>.mjs, and stops. No network,",
+              "no git, nothing published. The file is not a template with blanks — it",
+              "is one policy that already blocks git push --force, so the first thing",
+              "you do is edit something that works. It refuses rather than overwriting",
+              "a file that exists.",
+              "",
+              "Then try it on THIS machine, before anyone else can see it:",
+              "",
+              "    failproofai policies -i -c ./<name>.mjs",
+              "",
+              "That enforces the file right now — any path, any filename. Ask your",
+              "agent to do the thing you blocked and watch it get refused. Nothing is",
+              "published and nobody else is affected.",
+            ],
+          },
+          {
+            label: "what publish does",
+            lines: [
+              "In order, stopping before it touches GitHub if anything is wrong:",
+              "",
+              "1  Finds the policy file here by CONTENT — one that imports failproofai",
+              "   and calls customPolicies.add — not by filename, so it finds",
+              "   guards.mjs and ignores an unrelated policies.mjs. Not recursive:",
+              "   publishing a fixture is worse than being asked. Two candidates and",
+              "   it lists them.",
+              "2  Reads the repo from git remote get-url origin, in the FILE's",
+              "   directory rather than yours, and decides the version (see below).",
+              "3  Finds your credential: GITHUB_TOKEN, GH_TOKEN, or gh auth login.",
+              "   Needs release-write and nothing else. Never printed.",
+              "4  Creates the repository if it does not exist — public, see below.",
+              "5  Builds the three assets, validating with the LOADER's own rules: the",
+              "   code that decides what may install on a stranger's machine. A pack",
+              "   that could never install fails here, where you can fix it.",
+              "6  Creates or reuses the release and uploads, replacing assets of the",
+              "   same name — the install URL is built from fixed names, so a stale",
+              "   copy is what somebody would fetch.",
+            ],
+          },
+          {
+            label: "how the version is decided",
+            lines: [
+              "--version if you pass one. Otherwise a tag on HEAD — someone who tagged",
+              "v1.2.0 has SAID what this release is. Otherwise one past the highest",
+              "the repository has published: 1.0.0, then 1.0.1, and so on.",
+              "",
+              "Counted from the repository's own releases, never anything local, so a",
+              "fresh clone still gets the right number and two people cannot both mint",
+              "1.0.1. Non-semver releases (nightly) are ignored rather than guessed at.",
+              "",
+              "A tag names a COMMIT, so it is refused when the file has uncommitted",
+              "changes: those bytes are not in that commit, and two packs would claim",
+              "one version. A counted version names no commit and has no such problem.",
+            ],
+          },
+          {
+            label: "the repo must be public",
+            lines: [
+              "Installs are anonymous HTTPS with no credential to offer, so a private",
+              "repository publishes to nobody. A repo created here is public for that",
+              "reason; an existing private one still publishes, and warns.",
+              "",
+              "Only the release matters. Installs read releases/download/<tag>/<asset>",
+              "and never touch your git tree — pushing the source is for humans.",
+            ],
+          },
+          {
+            label: "your policy files",
+            lines: [
+              "Write as many as you like — one per category reads well. Every file",
+              "here that registers policies is bundled into the single artifact a pack",
+              "has to be: only the entry is digest-pinned, and a pack importing",
+              "siblings could not honestly claim to be verified. Bundling needs bun;",
+              "without it, name one self-contained file.",
+              "",
+              "Each policy may carry category and defaultEnabled alongside the usual",
+              "fields. category is what --category selects on; defaultEnabled is what",
+              "a bare `policies add` switches on, and it defaults to false.",
+            ],
+          },
+          {
+            label: "options",
+            entries: [
+              ["--init [file]", "Write a starter policy and stop."],
+              ["--repo <owner>/<repo>", "Where to release it, created if missing."],
+              ["--version <version>", "Skip the counting and say which version this is."],
+              ["--id <publisher/name>", "The pack's id. Defaults to --repo."],
+              ["--tag <tag>", "Release tag. Defaults to the version; v prefix ok."],
+              ["--notes <text>", "Release notes."],
+              ["--out <dir>", "Where to write the assets. Default: dist-pack."],
+              ["--effect <effect>", "enforce or observe. observe records and blocks nothing. Default: enforce."],
+              ["--dry-run", "Build the assets, publish nothing. No credential."],
+            ],
+          },
+          {
+            label: "examples",
+            lines: [
+              "failproofai publish --init",
+              "failproofai publish",
+              "failproofai publish --dry-run",
+              "failproofai publish ./guards.mjs --repo me/guards --version 2.0.0",
+            ],
+          },
+        ],
+      });
       process.exit(0);
     }
 
     lastSubcommand = "publish";
     const { runPublishCommand } = await import("../src/hooks/pack-cli");
     const result = await runPublishCommand(subArgs);
-    for (const line of result.lines) {
-      if (result.exitCode === 0) console.log(line);
-      else console.error(line);
-    }
+    await printLines(result.lines, result.exitCode === 0);
     // Shape, never value: whether it published and whether it worked. Never the
     // repo, the pack id or the entry path — all three are things the user typed.
     await track("cli_publish", { ok: result.exitCode === 0, dry_run: subArgs.includes("--dry-run") });
@@ -1364,55 +1458,78 @@ EXAMPLES
     const subArgs = args.slice(1);
 
     if (subArgs.length === 0 || subArgs.includes("--help") || subArgs.includes("-h")) {
-      console.log(`
-failproofai policies add|remove|show — choose what your agents may do
-
-USAGE
-  failproofai policies add                 Pick from what is installed here
-  failproofai policies add <name>          Turn one policy on
-  failproofai policies add <owner>/<repo>  Install someone's pack
-  failproofai policies add FailproofAI/policies            Our pack, fetched like any other
-  failproofai policies remove <name>       Turn one policy off
-  failproofai policies remove <pack-id>    Uninstall a pack
-  failproofai policies show <owner>/<repo> What a pack contains, before you take it
-
-A NAME OR A SOURCE
-  Anything with a slash is a pack source; anything without is a policy name.
-  Policy names cannot contain a slash, so there is nothing to guess at.
-
-    block-sudo                              a policy
-    acme/deploy-guard                       a pack, newest release, pinned
-    acme/deploy-guard@v2.1.0                that release
-    github:acme/deploy-guard@v2.1.0         same, explicit
-    https://github.com/acme/x/releases/tag/v2  the URL you copied
-
-CHOOSING PART OF A PACK
-  With no flags you get the pack's own defaults and are shown the rest.
-  --policy a,b     exactly these
-  --category x,y   whole categories (see: failproofai policies show <source>)
-  --all            everything it contains
-  Re-adding at a newer version keeps what you chose.
-
-OPTIONS (policy names only)
-  --cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose
-                                     Agent CLI(s) to apply to; space-separated or repeated.
-                                     Omit to detect installed CLIs and prompt.
-  --scope user|project|local         Config scope (default: user)
-  --beta                             Allow beta policies
-
-EXAMPLES
-  failproofai policies add
-  failproofai policies add block-sudo
-  failproofai policies add sanitize-api-keys --scope project
-  failproofai policies add FailproofAI/policies --category sanitize,git
-  failproofai policies add acme/deploy-guard --policy block-prod-deploy
-  failproofai policies show acme/deploy-guard
-  failproofai policies remove block-sudo
-
-Publishing your own: failproofai publish --help
-Offline: FAILPROOFAI_NO_DOWNLOAD=1 refuses to fetch; packs already installed
-keep enforcing. FAILPROOFAI_PACK_BASE_URL points it all at a mirror.
-`.trimStart());
+      await printHelp({
+        command: "policies add|remove|show",
+        tagline: "choose what your agents may do",
+        sections: [
+          {
+            label: "usage",
+            // Without the `failproofai policies` prefix, which the heading two
+            // lines up already carries: repeating it costs 21 of the 80 columns
+            // on every row and pushes each description into a second line. The
+            // examples below are the copy-pasteable spelling.
+            entries: [
+              ["add", "Pick from what is installed here"],
+              ["add <name>", "Turn one policy on"],
+              ["add <owner>/<repo>", "Install someone's pack"],
+              ["remove <name>", "Turn one policy off"],
+              ["remove <pack-id>", "Uninstall a pack"],
+              ["show <owner>/<repo>", "What a pack contains, before you take it"],
+            ],
+          },
+          {
+            label: "a name or a source",
+            lines: [
+              "Anything with a slash is a pack source; anything without is a policy",
+              "name. Policy names cannot contain a slash, so there is nothing to guess.",
+              "",
+              "  block-sudo                               a policy",
+              "  FailproofAI/policies                     our pack, like any other",
+              "  acme/deploy-guard                        newest release, pinned",
+              "  acme/deploy-guard@v2.1.0                 that release",
+              "  github:acme/deploy-guard@v2.1.0          same, explicit",
+              "  https://github.com/acme/x/releases/tag/v2   the URL you copied",
+            ],
+          },
+          {
+            label: "choosing part of a pack",
+            entries: [
+              ["--policy a,b", "exactly these"],
+              ["--category x,y", "whole categories (failproofai policies show <source>)"],
+              ["--all", "everything it contains"],
+            ],
+          },
+          {
+            label: "options (policy names only)",
+            entries: [
+              ["--cli <agent>...", "Agent CLI(s) to apply to; space-separated or repeated. Omit to detect installed CLIs and prompt."],
+              ["--scope user|project|local", "Config scope. Default: user."],
+              ["--beta", "Allow beta policies"],
+            ],
+          },
+          {
+            label: "examples",
+            lines: [
+              "failproofai policies add",
+              "failproofai policies add block-sudo",
+              "failproofai policies add sanitize-api-keys --scope project",
+              "failproofai policies add FailproofAI/policies --category sanitize,git",
+              "failproofai policies add acme/deploy-guard --policy block-prod-deploy",
+              "failproofai policies show acme/deploy-guard",
+              "failproofai policies remove block-sudo",
+            ],
+          },
+        ],
+        footer: [
+          "With no flags you get the pack's own defaults and are shown the rest.",
+          "Re-adding at a newer version keeps what you chose.",
+          "Agents: claude, codex, copilot, cursor, opencode, pi, hermes, openclaw,",
+          "factory, devin, antigravity, goose.",
+          "Publishing your own: failproofai publish --help",
+          "Offline: FAILPROOFAI_NO_DOWNLOAD=1 refuses to fetch; packs already",
+          "installed keep enforcing. FAILPROOFAI_PACK_BASE_URL points it at a mirror.",
+        ],
+      });
       process.exit(0);
     }
 
@@ -1475,10 +1592,7 @@ keep enforcing. FAILPROOFAI_PACK_BASE_URL points it all at a mirror.
         action === "show" ? ["list", ...rest] : [action, ...rest];
       const { runPackCommand } = await import("../src/hooks/pack-cli");
       const result = await runPackCommand(packArgs);
-      for (const line of result.lines) {
-        if (result.exitCode === 0) console.log(line);
-        else console.error(line);
-      }
+      await printLines(result.lines, result.exitCode === 0);
       await track("cli_pack", {
         ok: result.exitCode === 0,
         // The subcommand only — never the pack id, source or policy names. A
@@ -1553,10 +1667,7 @@ keep enforcing. FAILPROOFAI_PACK_BASE_URL points it all at a mirror.
       // the answer is to SHOW the list, here, with what is already on ticked.
       const { runPolicyPicker } = await import("../src/hooks/pack-cli");
       const result = await runPolicyPicker(action, { stdin: process.stdin, stdout: process.stdout });
-      for (const line of result.lines) {
-        if (result.exitCode === 0) console.log(line);
-        else console.error(line);
-      }
+      await printLines(result.lines, result.exitCode === 0);
       await track("cli_policy_picker", { ok: result.exitCode === 0, action });
       lastSubcommand = null;
       await exitAfterFlush(result.exitCode);
@@ -1630,69 +1741,63 @@ keep enforcing. FAILPROOFAI_PACK_BASE_URL points it all at a mirror.
     const isHelp      = subArgs.includes("--help")       || subArgs.includes("-h");
 
     if (isHelp) {
-      console.log(`
-failproofai policies — manage Failproof AI policies
-
-USAGE
-  failproofai policies                       List all policies and their status
-  failproofai policies add [what]            Turn one on, take a pack, or pick
-  failproofai policies remove <what>         Turn one off, or uninstall a pack
-  failproofai policies show <owner>/<repo>   What a pack holds, before you take it
-  failproofai policies --install, -i         Wire policies into your agent CLIs
-  failproofai policies --uninstall, -u       Unwire them, or strip the hooks
-
-  policy, pack and p are all spellings of policies.
-  Detail on the first three:  failproofai policies add --help
-
-OPTIONS (install)
-  [names...]                     Specific policy names to enable (omit for interactive)
-  --cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose
-                                 Agent CLI(s) to install for; space-separated
-                                 (e.g. --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose) or repeated.
-                                 Omit to detect installed CLIs and prompt (or
-                                 auto-pick if only one is found).
-  --scope user|project|local     Config scope to write to (default: user)
-                                 (Codex / Copilot / Cursor / OpenCode / Pi support user|project only)
-  --beta                         Include beta policies
-  --custom, -c <path>            Custom policy file (repeat for multiple files)
-                                 (skips interactive prompt; validates file first)
-
-OPTIONS (uninstall)
-  [names...]                     Specific policy names to disable (omit to remove hooks)
-  --cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose
-                                 Agent CLI(s) to uninstall from
-  --scope user|project|local|all Config scope to remove from (default: user)
-  --beta                         Remove only beta policies
-  --custom, -c                   Clear all explicit custom policy paths
-
-EXAMPLES
-  failproofai policies
-  failproofai policies --install
-  failproofai policies --install block-sudo sanitize-api-keys
-  failproofai policies --install --cli codex --scope project
-  failproofai policies --install --cli copilot --scope project
-  failproofai policies --install --cli cursor --scope project
-  failproofai policies --install --cli opencode --scope project
-  failproofai policies --install --cli pi --scope project
-  failproofai policies --install --cli factory --scope project
-  failproofai policies --install --cli devin --scope project
-  failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose
-  failproofai policies --install --custom ./my-policies.js
-  failproofai policies --install --custom ./security.js --custom ./workflow.js
-  failproofai policies -i -c ./my-policies.js
-  failproofai policies --uninstall block-sudo
-  failproofai policies --uninstall --cli codex
-  failproofai policies --uninstall --cli copilot
-  failproofai policies --uninstall --cli cursor
-  failproofai policies --uninstall --cli opencode
-  failproofai policies --uninstall --cli pi
-  failproofai policies -u
-  failproofai policies --uninstall --custom
-  failproofai policies add FailproofAI/policies
-  failproofai policies add FailproofAI/policies --category git,database
-  failproofai pack list acme/support-agent
-  failproofai pack build ./my-policies.mjs --id acme/support --version 1.0.0
-`.trimStart());
+      await printHelp({
+        command: "policies",
+        tagline: "manage the policies your agents run under",
+        sections: [
+          {
+            label: "usage",
+            entries: [
+              ["(bare)", "List every policy here and whether it is on"],
+              ["add [what]", "Turn one on, take a pack, or pick from a list"],
+              ["remove <what>", "Turn one off, or uninstall a pack"],
+              ["show <owner>/<repo>", "What a pack holds, before you take it"],
+              ["--install, -i", "Wire policies into your agent CLIs"],
+              ["--uninstall, -u", "Unwire them, or strip the hooks"],
+            ],
+          },
+          {
+            label: "options",
+            entries: [
+              ["[names...]", "Policy names. Omit for the interactive picker."],
+              ["--cli <agent>...", "Agent CLI(s); space-separated or repeated. Omit to detect what is installed and prompt."],
+              ["--scope <scope>", "user, project or local. Default: user. --uninstall also takes all."],
+              ["--beta", "Include beta policies. On --uninstall, only those."],
+              ["--custom, -c <path>", "Custom policy file; repeat for several. Bare on --uninstall, clears every explicit path."],
+            ],
+          },
+          {
+            // Enumerated ONCE. It used to be spelled out in full four times on
+            // this screen — twice in the --cli lines, twice more as examples
+            // differing only in which agent they named.
+            label: "agents",
+            lines: [
+              "claude, codex, copilot, cursor, opencode, pi, hermes, openclaw,",
+              "factory, devin, antigravity, goose",
+              "",
+              "Codex, Copilot, Cursor, OpenCode and Pi take user or project scope only.",
+            ],
+          },
+          {
+            label: "examples",
+            lines: [
+              "failproofai policies",
+              "failproofai policies --install",
+              "failproofai policies --install block-sudo sanitize-api-keys",
+              "failproofai policies --install --cli codex --scope project",
+              "failproofai policies --install --cli claude codex copilot cursor",
+              "failproofai policies -i -c ./my-policies.js",
+              "failproofai policies --uninstall block-sudo",
+              "failproofai policies -u",
+              "failproofai policies add FailproofAI/policies --category git,database",
+            ],
+          },
+        ],
+        footer: [
+          "policy, pack and p are all spellings of policies.",
+          "add, remove and show in full:  failproofai policies add --help",
+        ],
+      });
       process.exit(0);
     }
 
@@ -1914,82 +2019,100 @@ EXAMPLES
   // onboarding via bare `failproofai`).
   if (args[0] === "config") {
     if (args.includes("--help") || args.includes("-h")) {
-      console.log(`
-failproofai config — set this machine up
-
-USAGE
-  failproofai config             Guided setup
-  failproofai configure          Alias for config
-  failproofai setup              Alias for config
-
-WHAT IT DOES
-  Installs the failproofaid service (needs root once), wires hooks into every
-  agent CLI it supports, and optionally connects this machine to Cloud. It
-  chooses NO policies — take some with 'failproofai policies add <owner>/<repo>'.
-
-WITH NO TERMINAL (CI, containers, an agent driving it)
-  It just runs. There is nothing to confirm when nobody is watching, so it
-  applies rather than asking — no flag needed.
-
-  failproofai config                          set up, stay local
-  failproofai config --token <key>            set up and connect to Cloud
-    --url <url>                     somewhere other than app.befailproof.ai
-    --machine-id <id>               defaults to a stable per-machine key
-    --machine-label <name>          defaults to this host's name
-    --no-transcripts                decisions only, no session transcripts
-
-  The key can come from FAILPROOFAI_CLOUD_TOKEN instead of the command line,
-  and the url from FAILPROOFAI_CLOUD_URL — the same variable the daemon reads.
-  Prefer the environment: an argument is readable from 'ps' by every user on
-  the box, and lands in shell history and CI logs.
-
-  Exit 1 if anything it was asked to do did not happen — including a key the
-  server refused, and a machine that could not reach root. 'sudo' is never
-  prompted for here; it either works without a password or you are told the
-  exact commands to run.
-
-FAILPROOF CLOUD
-  failproofai config --connect <url> --token <key> [--machine-id <id>]
-                                    Connect this machine to FailproofAI Cloud
-                                    [--no-transcripts] decisions only, no transcripts
-  failproofai config --disconnect   Stop pulling policy and sending activity
-  failproofai config --status       Show connection, daemon and pause state
-  failproofai config --pause [--session <id>]
-                                    Pause enforcement, time-boxed
-  failproofai config --resume [--all]
-                                    Resume enforcement
-
-    --machine-label <name>          Human-readable name in the dashboard
-                                    (use alone to rename an already-connected machine)
-
-  One connection, two capabilities: this machine PULLS centrally-managed
-  policies and SENDS what its hooks decided, so the dashboard shows the fleet
-  it is enforcing on. Both are checked against the server before anything is
-  written, and reported separately — a key carrying policies:pull but not
-  events:add connects for policy and says exactly why the dashboard is empty.
-
-  Tokens are stored owner-only in ~/.failproofai/, never in the service unit —
-  that file is world-readable. Connecting needs no sudo, and the machine id
-  defaults to this host's name.
-
-  Connecting sends BOTH policy decisions and full session transcripts. A
-  transcript carries prompts, file contents and whatever was pasted into a
-  terminal — that is the point of connecting, and it is stated here rather than
-  buried behind a flag nobody finds. Use --no-transcripts for decisions only.
-
-PAUSING ENFORCEMENT (one session, always time-boxed)
-  failproofai config --pause         Pause this directory's newest agent session (30m)
-  failproofai config --pause 10m     Pause for a given time (max 8h; s/m/h, bare = minutes)
-  failproofai config --resume        End the pause early
-  failproofai config --status        Show what is paused and when it lifts
-    --session <id>                     Target a specific session
-    --all                              With --resume, end every active pause
-
-  A pause suspends builtin, custom and convention policies for that session
-  only, and always expires on its own. Cloud-managed policies keep enforcing.
-
-  Prefer flags? See \`failproofai policies --help\`.
-`.trimStart());
+      await printHelp({
+        command: "config",
+        tagline: "set this machine up",
+        sections: [
+          {
+            label: "usage",
+            entries: [
+              ["(bare)", "Guided setup: agents, daemon, cloud"],
+              ["--token <key>", "Set up and connect to Cloud, asking nothing"],
+              ["--status", "Connection, daemon version and pause state"],
+              ["--pause [<time>]", "Pause enforcement for one session"],
+              ["--resume [--all]", "End a pause early"],
+              ["--disconnect", "Stop pulling policy and sending activity"],
+              ["configure, setup", "Aliases for config"],
+            ],
+          },
+          {
+            label: "what it does",
+            lines: [
+              "Installs the failproofaid service (needs root once), wires hooks into",
+              "every agent CLI it supports, and optionally connects this machine to",
+              "Cloud. It chooses NO policies — take some with:",
+              "",
+              "    failproofai policies add <owner>/<repo>",
+            ],
+          },
+          {
+            label: "with no terminal (CI, containers, an agent driving it)",
+            lines: [
+              "It just runs. There is nothing to confirm when nobody is watching, so it",
+              "applies rather than asking — no flag needed.",
+              "",
+              "Exit 1 if anything it was asked to do did not happen — including a key",
+              "the server refused, and a machine that could not reach root. sudo is",
+              "never prompted for here; it either works without a password, or you are",
+              "told the exact commands to run.",
+            ],
+          },
+          {
+            label: "failproof cloud",
+            entries: [
+              ["--token <key>", "The API key. Passing one IS the request to connect."],
+              ["--url <url>", "Somewhere other than app.befailproof.ai"],
+              ["--machine-id <id>", "Defaults to a stable per-machine key"],
+              ["--machine-label <n>", "Dashboard name. Alone, renames a connected machine."],
+              ["--no-transcripts", "Decisions only, no session transcripts"],
+              ["--connect <url>", "Enrol only, on a machine already set up"],
+              ["--disconnect", "Stop pulling policy and sending activity"],
+            ],
+          },
+          {
+            label: "what connecting means",
+            lines: [
+              "The key can come from FAILPROOFAI_CLOUD_TOKEN instead of the command",
+              "line, and the url from FAILPROOFAI_CLOUD_URL — the same variable the",
+              "daemon reads. Prefer the environment: an argument is readable from `ps`",
+              "by every user on the box, and lands in shell history and CI logs.",
+              "",
+              "One connection, two capabilities: this machine PULLS centrally-managed",
+              "policies and SENDS what its hooks decided. Both are checked against the",
+              "server before anything is written, and reported separately — a key",
+              "carrying policies:pull but not events:add connects for policy and says",
+              "exactly why the dashboard is empty.",
+              "",
+              "Connecting sends BOTH policy decisions and full session transcripts. A",
+              "transcript carries prompts, file contents and whatever was pasted into a",
+              "terminal — that is the point of connecting, and it is stated here rather",
+              "than buried behind a flag nobody finds. Use --no-transcripts for",
+              "decisions only.",
+              "",
+              "Tokens are stored owner-only in ~/.failproofai/, never in the service",
+              "unit — that file is world-readable. Connecting needs no sudo.",
+            ],
+          },
+          {
+            label: "pausing enforcement (one session, always time-boxed)",
+            entries: [
+              ["--pause", "This directory's newest agent session, for 30m"],
+              ["--pause 10m", "A given time (max 8h; s/m/h, bare = minutes)"],
+              ["--resume", "End the pause early"],
+              ["--resume --all", "End every active pause"],
+              ["--session <id>", "Target a specific session"],
+              ["--status", "What is paused, and when it lifts"],
+            ],
+            after: [
+              "A pause suspends builtin, custom and convention policies for that",
+              "session only, and always expires on its own. Cloud-managed policies",
+              "keep enforcing.",
+            ],
+          },
+        ],
+        footer: ["Prefer flags?  failproofai policies --help"],
+      });
+      process.exit(0);
       process.exit(0);
     }
     lastSubcommand = "config";
@@ -2047,10 +2170,7 @@ PAUSING ENFORCEMENT (one session, always time-boxed)
           sessions: !args.includes("--no-transcripts"),
         });
       }
-      for (const line of result.lines) {
-        if (result.exitCode === 0) console.log(line);
-        else console.error(line);
-      }
+      await printLines(result.lines, result.exitCode === 0);
       await track("cli_cloud_enrollment", {
         action: wantsRename ? "rename" : wantsDisconnect ? "disconnect" : "connect",
         ok: result.exitCode === 0,
@@ -2121,10 +2241,7 @@ PAUSING ENFORCEMENT (one session, always time-boxed)
           ),
         );
       } else {
-        for (const line of result.lines) {
-          if (result.exitCode === 0) console.log(line);
-          else console.error(line);
-        }
+        await printLines(result.lines, result.exitCode === 0);
       }
       await track("cli_pause_invoked", {
         action: pauseIdx >= 0 ? "pause" : wantsResume ? "resume" : "status",