failproofai 1.0.0-beta.2 → 1.0.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "description": "The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously — for Claude Code & the Agents SDK",
   "bin": {
     "failproofai": "./dist/cli.mjs",
@@ -109,7 +109,7 @@
     "eslint-plugin-react-hooks": "7.0.1",
     "vite": "8.0.16",
     "undici": "7.28.0",
-    "brace-expansion": "5.0.8",
+    "brace-expansion": "5.0.9",
     "sharp": "0.35.0"
   }
 }

package/src/hooks/builtin-policies.ts

@@ -170,6 +170,99 @@ const RUNAS_RE = /(?:^|;|&&|\|\|)\s*runas\s/i;
 
 // blockCurlPipeSh
 const CURL_PIPE_SH_RE = /(?:curl|wget)\s.*\|\s*(?:sh|bash|zsh|dash|ksh|csh|tcsh|fish|ash)\b/;
+/**
+ * `failproofai config --pause` in any of its reachable spellings — direct, via
+ * `npx`/`bunx`/`pnpm dlx`, by absolute path, or through the `configure`/`setup`
+ * aliases the CLI normalizes. Only `--pause` matches: `--resume` and `--status`
+ * restore or merely report enforcement, so an agent running either is harmless.
+ *
+ * Two details carry the whole policy, and an earlier version got both wrong:
+ *
+ * `failproofai[^\s]*` rather than `\bfailproofai\b`. A word boundary stops at
+ * the character after the name, so every ordinary way of pinning or pathing the
+ * binary walked straight through: `npx failproofai@latest`, `npx -y
+ * failproofai@0.0.16`, `bunx failproofai@latest`, and
+ * `node /usr/lib/node_modules/failproofai/bin/failproofai.mjs`. The suffix has
+ * to be absorbed by the same token.
+ *
+ * `\s+--pause` rather than `\s--pause`. With a single `\s`, two spaces before
+ * the flag — which no shell cares about and any agent may emit — did not match.
+ *
+ * This still raises the bar rather than closing the class: base64, a wrapper
+ * script, an alias or a shell variable all still reach the same state. Closing
+ * it properly means a pause cannot originate from a tool call at all.
+ *
+ * Matched against BOTH the raw command and its shell-unescaped form (see
+ * `stripShellQuoting`), because a shell reconstructs the binary name from
+ * fragments a regex over the raw string cannot see.
+ */
+const SELF_PAUSE_RE =
+  /failproofai[^\s]*(?:\s+\S+)*?\s+(?:config|configure|setup)\b(?:\s+\S+)*?\s+--pause\b/;
+
+/**
+ * Decode one ANSI-C `$'...'` body (the text between the quotes) to the bytes a
+ * shell would produce. Covers the escape forms that can reconstruct an ASCII
+ * identifier: `\xHH`, octal `\NNN`, `\uHHHH`, `\UHHHHHHHH`, and the named
+ * controls. An out-of-range or malformed sequence is left as-is rather than
+ * throwing — this runs on adversarial input and must never crash the hook.
+ */
+function decodeAnsiC(body: string): string {
+  return body.replace(
+    /\\(x[0-9A-Fa-f]{1,2}|u[0-9A-Fa-f]{1,4}|U[0-9A-Fa-f]{1,8}|[0-7]{1,3}|.)/g,
+    (_, seq: string) => {
+      try {
+        if (seq[0] === "x") return String.fromCharCode(parseInt(seq.slice(1), 16));
+        if (seq[0] === "u" || seq[0] === "U") return String.fromCodePoint(parseInt(seq.slice(1), 16));
+        if (/^[0-7]+$/.test(seq)) return String.fromCharCode(parseInt(seq, 8));
+      } catch {
+        return seq;
+      }
+      const named: Record<string, string> = {
+        a: "\x07", b: "\b", e: "\x1b", f: "\f", n: "\n",
+        r: "\r", t: "\t", v: "\v", "\\": "\\", "'": "'", '"': '"', "?": "?",
+      };
+      return named[seq] ?? seq;
+    },
+  );
+}
+
+/**
+ * Collapse the quoting a POSIX shell resolves LEXICALLY — before it execs a
+ * command — so a literal matcher sees roughly what will actually run.
+ *
+ * Two adversarial red-team rounds defeated the pattern above by reassembling
+ * the binary name from fragments the regex could not see: first backslash and
+ * quote splitting (`fail\proofai`, `fail"proof"ai`, `f\a\i\l\p\r\o\o\f\a\i`),
+ * then ANSI-C quoting (`$'fail\x70roofai'`, octal `\160`, unicode `p`).
+ * Each executes the real pause. This now normalizes all three lexical forms:
+ * ANSI-C `$'...'` bodies are decoded first (the generic backslash pass below
+ * would otherwise turn `\x70` into `x70`), then surrounding single/double
+ * quotes and lone backslash-escapes are removed.
+ *
+ * The boundary is principled, not arbitrary: everything handled here is pure
+ * shell LEXING. What remains — a variable (`f=failproofai; $f …`), command
+ * substitution (`$(printf failproofai)`), `eval`, an alias, a base64 pipe —
+ * requires the shell to EXECUTE something to reconstruct the name, which no
+ * PreToolUse hook inspecting a command string can follow. That class is the one
+ * the header comment above calls out, and the only real closure is to make the
+ * pause ACTION itself refuse to originate from a tool call — deferred with the
+ * rest of the daemon-side redesign.
+ */
+function stripShellQuoting(command: string): string {
+  // Line continuation FIRST. A shell deletes a backslash-newline pair entirely
+  // and rejoins the fragments, so `fail\<newline>proofai` runs the real binary.
+  // The generic `\(.)` strip below cannot catch it — JS `.` excludes newline —
+  // so it has to be removed before that pass, or the fragments never join.
+  // (A third red-team round rode exactly this in.) `\r?\n` also covers a
+  // CRLF-joined line.
+  const joined = command.replace(/\\\r?\n/g, "");
+  // `$'...'` next, honoring `\'` inside the body, so its own escapes decode
+  // before the generic backslash-strip can mangle them.
+  const ansiDecoded = joined.replace(/\$'((?:[^'\\]|\\.)*)'/g, (_, body: string) =>
+    decodeAnsiC(body),
+  );
+  return ansiDecoded.replace(/\\(.)/g, "$1").replace(/['"]/g, "");
+}
 const PS_WEB_PIPE_RE = /(?:Invoke-WebRequest|iwr|Invoke-RestMethod|irm)\s+.*\|\s*(?:Invoke-Expression|iex)/i;
 
 // blockForcePush
@@ -579,6 +672,42 @@ function blockSudo(ctx: PolicyContext): PolicyResult {
   return allow();
 }
 
+/**
+ * A pause the agent can issue is not a guardrail.
+ *
+ * `failproofai config --pause` is a human affordance: you watched the agent get
+ * blocked, you judged the block wrong, you suspended enforcement for a bit. An
+ * agent that can run it turns every other policy advisory — it need only shell
+ * out once to switch them all off, and the pause even survives into later turns.
+ *
+ * This raises the bar rather than closing the class: an agent can still reach
+ * the same state obfuscated (base64, a wrapper script, an alias). Closing it
+ * properly means the pause cannot originate from a tool call at all — a
+ * dashboard action, or a daemon that accepts it only from a TTY. Until then,
+ * the honest description of this policy is "stops the obvious attempt".
+ *
+ * It is deliberately NOT redundant with `block-failproofai-commands`, which
+ * blocks the CLI far more broadly. That one anchors on a command boundary
+ * (`FAILPROOFAI_CLI_RE`), so `npx -y failproofai config --pause` does not match
+ * it — and being broad, it is a policy people plausibly switch off so agents
+ * can run `failproofai audit`. Neither gap should leave pausing reachable, so
+ * this stays narrow, matches the runner forms, and survives that one being off.
+ */
+function blockSelfPause(ctx: PolicyContext): PolicyResult {
+  if (ctx.toolName !== "Bash") return allow();
+  const cmd = getCommand(ctx);
+  // The raw command AND its shell-unescaped form: a shell strips quotes and
+  // backslashes before running the binary, so `fail\proofai config --pause`
+  // reaches the pause CLI even though the literal name is broken.
+  if (SELF_PAUSE_RE.test(cmd) || SELF_PAUSE_RE.test(stripShellQuoting(cmd))) {
+    return deny(
+      "Pausing failproofai enforcement is a human action, not an agent one. " +
+        "If a policy is blocking legitimate work, say so and let the operator decide.",
+    );
+  }
+  return allow();
+}
+
 function blockCurlPipeSh(ctx: PolicyContext): PolicyResult {
   if (ctx.toolName !== "Bash") return allow();
   const cmd = getCommand(ctx);
@@ -1752,6 +1881,16 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
       },
     } satisfies PolicyParamsSchema,
   },
+  {
+    name: "block-self-pause",
+    displayTitle: "Tried to pause failproofai enforcement",
+    impact: "An agent that can pause enforcement can switch off every other policy.",
+    description: "Block agents from pausing failproofai enforcement",
+    fn: blockSelfPause,
+    match: { events: ["PreToolUse", "PermissionRequest"], toolNames: ["Bash"] },
+    defaultEnabled: true,
+    category: "Dangerous Commands",
+  },
   {
     name: "block-sudo",
     displayTitle: "Tried to run a command with sudo",

package/src/hooks/cloud-connection.ts

@@ -0,0 +1,205 @@
+/**
+ * One connection to Failproof Cloud, with two capabilities.
+ *
+ * # Why this exists
+ *
+ * Enrolment (#632) and collection (#640) were built independently and each
+ * arrived with its own credential file, its own URL and its own setup step:
+ *
+ *   pull policy   ->  ~/.failproofai/cloud.json    <base>/enforcement/v1/...
+ *   push events   ->  ~/.failproofai/ingest.json   <base>/events
+ *
+ * Same server, same organisation, usually the same key. Asked twice, a user
+ * who connects for policy sees an empty dashboard and reasonably concludes the
+ * product is broken — the second setup step is invisible until someone goes
+ * looking for it.
+ *
+ * So the URL and token are asked for ONCE and both capabilities are configured
+ * from them. The two files stay separate on disk — that is a real security
+ * boundary, since `cloud.json` and `ingest.json` can hold different keys with
+ * different permissions, and the daemon reads them independently — but nothing
+ * above this module has to know that.
+ *
+ * # Capabilities are verified and reported INDEPENDENTLY
+ *
+ * A key may carry `policies:pull` and not `events:add`, or the reverse. The
+ * honest outcome is then a partial connection with a precise reason, not an
+ * all-or-nothing failure: refusing to enrol for policy because the dashboard
+ * would be empty protects nothing, and silently skipping ingest reproduces the
+ * exact confusion this module removes.
+ */
+import {
+  cloudCredentialPath,
+  verifyCloudCredentials,
+  writeCloudCredentials,
+  type CloudCredentials,
+} from "./cloud-enrollment";
+import {
+  ingestPath,
+  validateIngestKey,
+  writeCollectorSettings,
+  writeIngestCredential,
+  type CollectorSettings,
+} from "./collector-config";
+
+/** The path ingest is served on, appended to the cloud base URL. */
+export const INGEST_PATH = "/events";
+
+/**
+ * The ingest endpoint for a cloud base URL.
+ *
+ * Ingest wants a COMPLETE endpoint while enrolment wants a base, which is the
+ * whole reason two URLs were being asked for. One is derivable from the other,
+ * so only the base is ever asked for.
+ */
+export function ingestUrlFor(baseUrl: string): string {
+  return `${baseUrl.replace(/\/$/, "")}${INGEST_PATH}`;
+}
+
+/**
+ * The cloud base for whatever URL someone actually typed.
+ *
+ * Accepts either form. People paste the ingest endpoint — it is what the older
+ * prompt asked for, and what any existing runbook or `ingest.json` contains —
+ * and rejecting it as "not a base URL" would be pedantry about a URL we can
+ * read perfectly well.
+ */
+export function cloudBaseFor(url: string): string {
+  const trimmed = url.replace(/\/$/, "");
+  return trimmed.endsWith(INGEST_PATH) ? trimmed.slice(0, -INGEST_PATH.length) : trimmed;
+}
+
+export interface ConnectInput {
+  /** Cloud base URL, already validated by `validateCloudUrl`. */
+  url: string;
+  token: string;
+  machineId: string;
+  /** Transcripts are a separate, explicit opt-in. Never defaulted on. */
+  sessions?: boolean;
+  environment?: string;
+  /** Injected by tests so nothing reaches the network. */
+  verifyPolicy?: typeof verifyCloudCredentials;
+  verifyIngest?: typeof validateIngestKey;
+}
+
+export interface CapabilityOutcome {
+  ok: boolean;
+  reason?: string;
+}
+
+export interface ConnectOutcome {
+  policy: CapabilityOutcome & { policyCount?: number; generation?: number };
+  ingest: CapabilityOutcome;
+  /** True when at least one capability was configured. */
+  anyConfigured: boolean;
+}
+
+/**
+ * Verify both capabilities, then write only what actually works.
+ *
+ * Verification happens BEFORE any write, per capability. A credential file that
+ * does not work is worse than none, because `--status` then reports a
+ * connection the machine does not have.
+ */
+export async function connectToCloud(input: ConnectInput): Promise<ConnectOutcome> {
+  const creds: CloudCredentials = {
+    url: input.url,
+    machineId: input.machineId,
+    token: input.token,
+  };
+
+  const verifyPolicy = input.verifyPolicy ?? verifyCloudCredentials;
+  const verifyIngest = input.verifyIngest ?? validateIngestKey;
+  const ingestUrl = ingestUrlFor(input.url);
+
+  // Both checks run regardless of the other's result: reporting "cannot pull
+  // policy" while staying silent about ingest would send someone to fix one
+  // permission and hit the next one afterwards.
+  const [policyResult, ingestResult] = await Promise.all([
+    verifyPolicy(creds),
+    verifyIngest({ url: ingestUrl, key: input.token }),
+  ]);
+
+  const outcome: ConnectOutcome = {
+    policy: policyResult.ok
+      ? { ok: true, policyCount: policyResult.policyCount, generation: policyResult.generation }
+      : { ok: false, reason: policyResult.reason },
+    ingest: ingestResult.ok ? { ok: true } : { ok: false, reason: ingestResult.reason },
+    anyConfigured: false,
+  };
+
+  if (policyResult.ok) {
+    writeCloudCredentials(creds);
+    outcome.anyConfigured = true;
+  }
+
+  if (ingestResult.ok) {
+    writeIngestCredential({ url: ingestUrl, key: input.token });
+    const settings: CollectorSettings = {
+      // Hook activity is what makes the dashboard show anything at all, and it
+      // carries decisions and tool names — never file contents.
+      hooks: true,
+      // Transcripts carry prompts, file contents and whatever was pasted into
+      // a terminal, so they stay off unless explicitly asked for.
+      sessions: input.sessions === true,
+      environment: input.environment,
+    };
+    writeCollectorSettings(settings);
+    outcome.anyConfigured = true;
+  }
+
+  return outcome;
+}
+
+/**
+ * How to describe the outcome to someone at a terminal.
+ *
+ * The partial cases are the ones worth wording carefully: each names the
+ * missing permission, because "connected, but the dashboard will stay empty"
+ * without a cause is the message that sends people to support.
+ */
+export function describeOutcome(outcome: ConnectOutcome, machineId: string, url: string): string[] {
+  const lines: string[] = [];
+
+  if (outcome.policy.ok && outcome.ingest.ok) {
+    lines.push(`Connected to ${url} as ${machineId}.`);
+    const n = outcome.policy.policyCount ?? 0;
+    lines.push(`  Policy    ${n} polic${n === 1 ? "y" : "ies"} assigned (generation ${outcome.policy.generation ?? 0}).`);
+    lines.push(`  Dashboard hook activity will be sent to ${ingestUrlFor(url)}.`);
+    return lines;
+  }
+
+  if (outcome.policy.ok && !outcome.ingest.ok) {
+    const n = outcome.policy.policyCount ?? 0;
+    lines.push(`Connected to ${url} as ${machineId} for policy only.`);
+    lines.push(`  Policy    ${n} polic${n === 1 ? "y" : "ies"} assigned (generation ${outcome.policy.generation ?? 0}).`);
+    lines.push(`  Dashboard NOT configured: ${outcome.ingest.reason}`);
+    lines.push("");
+    lines.push("  Enforcement works. Nothing will appear in the dashboard until this");
+    lines.push("  key also carries `events:add`, or you re-run --connect with one that does.");
+    return lines;
+  }
+
+  if (!outcome.policy.ok && outcome.ingest.ok) {
+    lines.push(`Connected to ${url} as ${machineId} for dashboard reporting only.`);
+    lines.push(`  Dashboard hook activity will be sent to ${ingestUrlFor(url)}.`);
+    lines.push(`  Cloud policy NOT configured: ${outcome.policy.reason}`);
+    lines.push("");
+    lines.push("  This machine keeps enforcing its LOCAL policies and will report what");
+    lines.push("  they decide, but will not receive centrally-managed ones.");
+    return lines;
+  }
+
+  lines.push(`Could not connect to ${url}.`);
+  lines.push(`  Policy:    ${outcome.policy.reason}`);
+  lines.push(`  Dashboard: ${outcome.ingest.reason}`);
+  return lines;
+}
+
+/** Paths written, for a closing note. Only those that exist. */
+export function configuredPaths(outcome: ConnectOutcome): string[] {
+  const paths: string[] = [];
+  if (outcome.policy.ok) paths.push(cloudCredentialPath());
+  if (outcome.ingest.ok) paths.push(ingestPath());
+  return paths;
+}

package/src/hooks/cloud-enrollment-cli.ts

@@ -0,0 +1,227 @@
+/**
+ * `failproofai config --connect | --disconnect`, and the connection half of
+ * `--status`.
+ */
+import {
+  clearCloudCredentials,
+  maskToken,
+  readCloudCredentials,
+  validateCloudUrl,
+  verifyCloudCredentials,
+  writeCloudCredentials,
+  cloudCredentialPath,
+} from "./cloud-enrollment";
+import { daemonServiceStatus } from "./daemon-service";
+import { daemonSocketPresent } from "./daemon-client";
+import {
+  cloudBaseFor,
+  configuredPaths,
+  connectToCloud,
+  describeOutcome,
+  ingestUrlFor,
+} from "./cloud-connection";
+import {
+  clearIngestCredential,
+  hasIngestCredential,
+  readIngestCredential,
+  validateIngestKey,
+} from "./collector-config";
+
+export interface ConnectOptions {
+  url?: string;
+  token?: string;
+  machineId?: string;
+  /** Defaults to the hostname; injected for tests. */
+  defaultMachineId?: string;
+  /**
+   * Send full session transcripts as well as hook decisions. Off unless asked
+   * for: a transcript carries prompts, file contents and whatever was pasted
+   * into a terminal, so it can never be a side effect of connecting.
+   */
+  sessions?: boolean;
+  environment?: string;
+  /** Injected for tests so nothing reaches the network. */
+  verify?: typeof verifyCloudCredentials;
+  verifyIngest?: typeof validateIngestKey;
+  daemonStatus?: () => ReturnType<typeof daemonServiceStatus>;
+}
+
+export interface CommandResult {
+  exitCode: number;
+  lines: string[];
+}
+
+/**
+ * Warn rather than refuse when there is no daemon.
+ *
+ * Cloud policy is evaluated by failproofaid, so credentials alone pull
+ * nothing — but refusing would break baking a machine image where the daemon
+ * is installed later, and enrolment is genuinely independent of it. Say so
+ * loudly instead of failing.
+ */
+function daemonWarning(status: ReturnType<typeof daemonServiceStatus>): string[] {
+  if (status === "running") return [];
+  // A daemon started by hand is invisible to the service manager but is
+  // running and pulling. Telling someone whose machine is actively enforcing
+  // that "nothing will be pulled" is false, and it is exactly the state a
+  // developer testing locally is in.
+  if (daemonSocketPresent()) {
+    return [
+      "",
+      "  A daemon is running outside the service manager, so policy is being pulled.",
+      "  Install it as a service to survive reboot and logout: failproofai config",
+    ];
+  }
+  if (status === "unsupported-platform") {
+    return [
+      "",
+      "! failproofaid does not run on this platform yet, so nothing will be pulled.",
+      "  The credentials are stored and will work on a supported machine.",
+    ];
+  }
+  if (status === "not-installed") {
+    // "as a service", not "at all": this reads the service manager, so a daemon
+    // someone is running by hand during development is reported as absent. The
+    // wording has to be true in both cases.
+    return [
+      "",
+      "! failproofaid is not installed as a service, so nothing will be pulled yet.",
+      "  Install it with: failproofai config",
+    ];
+  }
+  return [
+    "",
+    "! failproofaid is installed but not running, so nothing will be pulled yet.",
+    "  Check it with: failproofai config --status",
+  ];
+}
+
+export async function runConnectCommand(opts: ConnectOptions): Promise<CommandResult> {
+  if (!opts.url) return { exitCode: 1, lines: ["--connect needs a URL, e.g. --connect https://be.failproof.ai"] };
+  if (!opts.token) {
+    return {
+      exitCode: 1,
+      lines: [
+        "--connect needs a machine token: --token <key>",
+        "",
+        "Create an API key carrying only the `policies:pull` permission for this",
+        "machine. Do not use an admin key.",
+      ],
+    };
+  }
+
+  // Accepts the ingest endpoint too. People paste what the older setup asked
+  // for, or what is already in their `ingest.json`, and refusing a URL we can
+  // read perfectly well is pedantry.
+  const validated = validateCloudUrl(cloudBaseFor(opts.url));
+  if (!validated.ok) return { exitCode: 1, lines: [validated.reason] };
+
+  const machineId = (opts.machineId ?? opts.defaultMachineId ?? "").trim();
+  if (!machineId) {
+    return { exitCode: 1, lines: ["Could not determine a machine id — pass one with --machine-id <id>."] };
+  }
+
+  // ONE connection, both capabilities. Each is verified before anything is
+  // written and reported on its own, because a key can carry `policies:pull`
+  // without `events:add` and the useful message names which one is missing.
+  const outcome = await connectToCloud({
+    url: validated.url,
+    token: opts.token,
+    machineId,
+    sessions: opts.sessions,
+    environment: opts.environment,
+    verifyPolicy: opts.verify,
+    verifyIngest: opts.verifyIngest,
+  });
+
+  if (!outcome.anyConfigured) {
+    return { exitCode: 1, lines: describeOutcome(outcome, machineId, validated.url) };
+  }
+
+  // The exit code tracks the PRIMARY purpose — enrolling this machine for
+  // cloud-managed policy. Configuring the dashboard is worth doing and worth
+  // reporting, but it must not turn a failed enrolment into a success: a fleet
+  // provisioning script running `--connect … && …` has to stop when the machine
+  // will not receive policy. The ingest credential still gets written, because
+  // it works and discarding it helps nobody.
+  const exitCode = outcome.policy.ok ? 0 : 1;
+
+  const status = (opts.daemonStatus ?? daemonServiceStatus)();
+  const paths = configuredPaths(outcome);
+  const lines = [
+    ...describeOutcome(outcome, machineId, validated.url),
+    `  Token ${maskToken(opts.token)} stored in ${paths.join(" and ")} (owner-only).`,
+  ];
+  if (outcome.ingest.ok && opts.sessions !== true) {
+    // Said out loud rather than left as a default: someone who wanted
+    // transcripts should not discover months later that none were sent.
+    lines.push("  Session transcripts are NOT being sent. Add --send-transcripts to include them.");
+  }
+  lines.push(...daemonWarning(status));
+
+  return { exitCode, lines };
+}
+
+export function runDisconnectCommand(): CommandResult {
+  const existing = readCloudCredentials();
+  const hadIngest = hasIngestCredential();
+  const removed = clearCloudCredentials();
+  // Disconnect means disconnect. Clearing only the policy credential would
+  // leave the machine still shipping activity to a cloud the user believes
+  // they have left — the one outcome nobody expects from this command.
+  const removedIngest = clearIngestCredential();
+
+  if (!removed && !existing && !hadIngest) {
+    return { exitCode: 0, lines: ["This machine is not connected to Failproof Cloud."] };
+  }
+
+  const lines = [
+    "Disconnected from Failproof Cloud.",
+    "",
+    "  Cloud-managed policies already on disk stop being refreshed. Local",
+    "  builtin, custom and convention policies are unaffected.",
+  ];
+  if (removedIngest) {
+    lines.push("  Hook activity and transcripts stop being sent.");
+  }
+  return { exitCode: 0, lines };
+}
+
+/** The connection half of `--status`. Never prints the token. */
+export function connectionStatusLines(daemonStatus = daemonServiceStatus): string[] {
+  const envUrl = process.env.FAILPROOFAI_CLOUD_URL;
+  if (envUrl) {
+    // Env wins over the file in the daemon, so reporting the file here would
+    // describe a configuration that is not in effect.
+    return [
+      `Cloud: configured by environment (${envUrl}), which takes precedence over ${cloudCredentialPath()}.`,
+    ];
+  }
+  const creds = readCloudCredentials();
+  const ingest = readIngestCredential();
+
+  // Reported as ONE connection with two capabilities. A machine sending
+  // activity but pulling no policy, or the reverse, is a state worth seeing at
+  // a glance — it is exactly the half-configured case this command exists to
+  // catch, and two unrelated lines made it easy to miss.
+  if (!creds && !ingest) return ["Cloud: not connected."];
+
+  const lines: string[] = [];
+  if (creds) {
+    lines.push(`Cloud: connected to ${creds.url} as ${creds.machineId} (token ${maskToken(creds.token)}).`);
+    lines.push(`  Policy    pulling centrally-managed policies.`);
+  } else {
+    lines.push(`Cloud: connected to ${cloudBaseFor(ingest!.url)} for reporting only.`);
+    lines.push(`  Policy    NOT pulling — this machine enforces only its local policies.`);
+  }
+
+  if (ingest) {
+    lines.push(`  Dashboard sending hook activity to ${ingest.url}.`);
+  } else {
+    lines.push(`  Dashboard NOT sending — nothing from this machine appears in the dashboard.`);
+    lines.push(`            Re-run: failproofai config --connect ${creds!.url} --token <key>`);
+  }
+
+  lines.push(...daemonWarning(daemonStatus()).map((l) => (l === "" ? "" : `  ${l.trim()}`)));
+  return lines;
+}