failproofai 1.0.0-beta.1 → 1.0.0-beta.11

package/src/hooks/cloud-connection.ts

@@ -0,0 +1,354 @@
+/**
+ * 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,
+  validateCloudUrl,
+  verifyCloudCredentials,
+  writeCloudCredentials,
+  type CloudCredentials,
+} from "./cloud-enrollment";
+import { updateConfig, readCredentials, writeCredentials } from "./fp-config";
+import {
+  introspectKey,
+  hasPermission,
+  describeOrg,
+  PERMISSION_EVENTS,
+  PERMISSION_POLICIES,
+} from "./cloud-introspect";
+import {
+  ingestPath,
+  validateIngestKey,
+  writeCollectorSettings,
+  writeIngestCredential,
+  type CollectorSettings,
+} from "./collector-config";
+
+/**
+ * The path ingest is served on, appended to the cloud base URL.
+ *
+ * `/v1/events` rather than `/events`, and the difference is load-bearing for
+ * the hosted deployment. The server mounts its route list TWICE — flat at `/`
+ * and nested under `/v1` — so both reach the same handler when you talk to the
+ * server directly. But on the dashboard hostname a reverse proxy routes only
+ * `/v1/*` and `/enforcement/v1/*` to the server and sends EVERYTHING ELSE to
+ * the Next.js app. So `https://app.befailproof.ai/events` does not reach ingest
+ * at all; it reaches a web app that will happily answer.
+ *
+ * `/v1/events` is therefore the only path that works on all three shapes: the
+ * dashboard hostname, the server hostname, and a Compose deployment with no
+ * proxy at all. That is what lets one `--connect <origin>` configure BOTH
+ * capabilities from a single URL.
+ */
+export const INGEST_PATH = "/v1/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(/\/$/, "");
+  // Strip either ingest path. People paste what an older setup asked for, what
+  // is already in their config, or what a colleague sent them — and `/events`
+  // was the documented value for the whole life of the product before `/v1`.
+  // Refusing a URL we can read perfectly well is pedantry; silently treating
+  // `https://host/events` as an ORIGIN would be worse, because every derived
+  // URL would then carry a stray `/events` segment.
+  for (const suffix of [INGEST_PATH, "/events"]) {
+    if (trimmed.endsWith(suffix)) return trimmed.slice(0, -suffix.length);
+  }
+  return trimmed;
+}
+
+export interface ConnectInput {
+  /**
+   * Cloud base URL. Re-validated with `validateCloudUrl` on entry rather than
+   * trusted — this used to say "already validated by `validateCloudUrl`", and
+   * the wizard did not.
+   */
+  url: string;
+  token: string;
+  machineId: string;
+  /** Human-facing display name for this machine. Defaults to the hostname. */
+  machineLabel?: string;
+  /**
+   * Send session transcripts.
+   *
+   * Both callers — the wizard and `--connect` — now pass `true` unless the
+   * user opts out, because transcripts are what makes a dashboard worth
+   * connecting to. This function itself still requires it EXPLICITLY and
+   * treats `undefined` as off: a library that silently opts a caller into
+   * shipping prompts and file contents is the wrong default at this layer,
+   * whatever the product default above it happens to be.
+   */
+  sessions?: boolean;
+  environment?: string;
+  /** Injected by tests so nothing reaches the network. */
+  verifyPolicy?: typeof verifyCloudCredentials;
+  verifyIngest?: typeof validateIngestKey;
+  introspect?: typeof introspectKey;
+}
+
+export interface CapabilityOutcome {
+  ok: boolean;
+  reason?: string;
+}
+
+export interface ConnectOutcome {
+  policy: CapabilityOutcome & { policyCount?: number; generation?: number };
+  ingest: CapabilityOutcome;
+  /** Which organisation the key belongs to. Absent on a pre-introspect server. */
+  org?: { id?: string; slug?: string; name?: string };
+  /** 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> {
+  // Checked HERE, not only at the call sites. `ConnectInput.url` is documented
+  // as "already validated by `validateCloudUrl`", and that was true of exactly
+  // one of the two callers: `--connect` validated, and the interactive wizard —
+  // the documented primary path — matched `/^https?:\/\//` and handed the raw
+  // string straight to `validateIngestKey` and then to here. So the flow most
+  // people use sent the machine's bearer token to any `http://` host in clear.
+  // A precondition worth stating in a docstring is worth enforcing at the
+  // boundary that depends on it.
+  const checked = validateCloudUrl(input.url);
+  if (!checked.ok) {
+    return {
+      policy: { ok: false, reason: checked.reason },
+      ingest: { ok: false, reason: checked.reason },
+      anyConfigured: false,
+    };
+  }
+
+  const creds: CloudCredentials = {
+    url: input.url,
+    machineId: input.machineId,
+    token: input.token,
+    machineLabel: input.machineLabel,
+  };
+
+  const verifyPolicy = input.verifyPolicy ?? verifyCloudCredentials;
+  const verifyIngest = input.verifyIngest ?? validateIngestKey;
+  const introspect = input.introspect ?? introspectKey;
+  const ingestUrl = ingestUrlFor(input.url);
+
+  // ── Ask the key what it is, before using it for anything ──────────────────
+  //
+  // One request answers three questions that are otherwise indistinguishable
+  // until much later: is the key accepted, which ORG does it report into, and
+  // does it carry the permissions this machine needs. Probing the endpoints
+  // (below) can only ever answer the first, and only by inference.
+  //
+  // A rejected key stops here — probing two more endpoints with a credential
+  // the server has already refused tells us nothing and costs two more
+  // unauthenticated database lookups on a surface with no rate limiting.
+  const identity = await introspect(input.url, input.token);
+  if (identity.kind === "rejected") {
+    return {
+      policy: { ok: false, reason: "the server did not accept that key" },
+      ingest: { ok: false, reason: "the server did not accept that key" },
+      anyConfigured: false,
+    };
+  }
+
+  // `unsupported` — an AgentEye older than the introspect endpoint. Fall
+  // through to probing, which is what every release before this one did. The
+  // CLI ships independently of whatever server a customer runs, so a good key
+  // on an older deployment must still connect.
+  const known = identity.kind === "ok" ? identity.identity : null;
+
+  // Skip a probe the key provably cannot pass. This is not an optimisation: a
+  // permission failure surfaces from `/events` as a 403 whose message reads
+  // like a server problem, where introspect can say exactly which permission is
+  // missing and for which org.
+  const canIngest = known ? hasPermission(known, PERMISSION_EVENTS) : true;
+  const canPolicy = known ? hasPermission(known, PERMISSION_POLICIES) : true;
+
+  const missing = (permission: string) =>
+    `that key does not carry \`${permission}\`` +
+    (known ? ` (it is valid for ${describeOrg(known)})` : "");
+
+  // 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([
+    canPolicy
+      ? verifyPolicy(creds)
+      : Promise.resolve({ ok: false as const, reason: missing(PERMISSION_POLICIES) }),
+    canIngest
+      ? verifyIngest({ url: ingestUrl, key: input.token })
+      : Promise.resolve({ ok: false as const, reason: missing(PERMISSION_EVENTS) }),
+  ]);
+
+  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,
+    org: known
+      ? { id: known.orgId, slug: known.orgSlug, name: known.orgName }
+      : undefined,
+  };
+
+  if (policyResult.ok) {
+writeCloudCredentials(creds);
+    outcome.anyConfigured = true;
+  }
+
+  // Mode is the hard gate, set only once a capability actually verified.
+  // "cloud" is never inferred from a token merely being present: a machine
+  // that has not proven it can reach the server must stay provably silent.
+  if (policyResult.ok || ingestResult.ok) {
+    updateConfig({ mode: "cloud" });
+  }
+
+  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,
+      // Explicit only — see the `sessions` doc on ConnectInput. Callers decide
+      // the product default; this layer never infers one.
+      sessions: input.sessions === true,
+      environment: input.environment,
+      // So the daemon stamps this machine's id on every collected event and the
+      // dashboard groups by machine, not by per-project agent_id.
+      machineId: input.machineId,
+    };
+    writeCollectorSettings(settings);
+    outcome.anyConfigured = true;
+  }
+
+  // Last, and only once something actually configured: recording an org for a
+  // machine that connected to nothing would be a claim about where data goes
+  // from a machine that sends none. Merged into whatever the two writers above
+  // just wrote, so it cannot race them.
+  if (outcome.anyConfigured && known && (known.orgId || known.orgSlug || known.orgName)) {
+    writeCredentials({
+      ...readCredentials(),
+      org: { id: known.orgId, slug: known.orgSlug, name: known.orgName },
+    });
+  }
+
+  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[] = [];
+
+  // Named on every branch that connected, including the partial ones. A key
+  // pasted from the wrong organisation authenticates perfectly and reports into
+  // somewhere the user is not looking; the org is the only thing on screen that
+  // makes that visible, and it is worth nothing if it only prints on success.
+  const org = outcome.org
+    ? outcome.org.name && outcome.org.slug
+      ? `${outcome.org.name} (${outcome.org.slug})`
+      : (outcome.org.name ?? outcome.org.slug ?? outcome.org.id)
+    : undefined;
+  const into = org ? ` into ${org}` : "";
+
+  if (outcome.policy.ok && outcome.ingest.ok) {
+    lines.push(`Connected to ${url} as ${machineId}${into}.`);
+    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}${into}, 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}${into}, 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());
+  // Deduplicated because layout 2 consolidated both credentials into
+  // `credentials.toml`, so the two capabilities now name the SAME file and the
+  // closing note read "stored in <path> and <path>" — the same path, twice.
+  // They stay two entries above because the JSON override can still split them.
+  return [...new Set(paths)];
+}

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

@@ -0,0 +1,325 @@
+/**
+ * `failproofai config --connect | --disconnect`, and the connection half of
+ * `--status`.
+ */
+import {
+  clearCloudCredentials,
+  maskToken,
+  readCloudCredentials,
+  resolveMachineId,
+  resolveMachineLabel,
+  validateCloudUrl,
+  verifyCloudCredentials,
+  writeCloudCredentials,
+  cloudCredentialPath,
+} from "./cloud-enrollment";
+import { daemonRestartCommand, daemonServiceStatus, daemonVersionSkew } from "./daemon-service";
+import { clearActiveCloudManagedPolicies } from "./cloud-managed-policies";
+import { readVersionFile, readCredentials } from "./fp-config";
+import { version as cliVersion } from "../../package.json";
+import { daemonSocketPresent } from "./daemon-client";
+import {
+  cloudBaseFor,
+  configuredPaths,
+  connectToCloud,
+  describeOutcome,
+  ingestUrlFor,
+} from "./cloud-connection";
+import {
+  clearIngestCredential,
+  hasIngestCredential,
+  readIngestCredential,
+  validateIngestKey,
+} from "./collector-config";
+import { updateConfig } from "./fp-config";
+import type { introspectKey } from "./cloud-introspect";
+
+export interface ConnectOptions {
+  url?: string;
+  token?: string;
+  machineId?: string;
+  /** Human-facing display name for this machine. Defaults to the hostname. */
+  machineLabel?: string;
+  /**
+   * The hostname, passed in by the caller (and injected by tests). Used as the
+   * default machine *label*, no longer as the machine id — the id now mints or
+   * reuses a stable key so two hosts with the same hostname never merge.
+   */
+  defaultMachineId?: string;
+  /**
+   * Send full session transcripts as well as hook decisions.
+   *
+   * DEFAULTS ON. A transcript carries prompts, file contents and whatever was
+   * pasted into a terminal — which is precisely what makes a dashboard worth
+   * connecting to, so hiding it behind an opt-in produced the empty-dashboard
+   * problem in a different costume. `false` is the explicit opt-out; the
+   * disclosure is printed either way.
+   */
+  sessions?: boolean;
+  environment?: string;
+  /**
+   * Injected for tests so nothing reaches the network.
+   *
+   * All THREE must be here, and a new network call added below has to gain its
+   * seam in the same commit: `introspect` was added without one, so every test
+   * in `cloud-enrollment-cli.test.ts` silently began making a real request to
+   * `be.failproof.ai`. It usually failed fast enough to pass, which is the worst
+   * available outcome — the suite went intermittently red on network timing
+   * rather than on anything a change had broken.
+   */
+  verify?: typeof verifyCloudCredentials;
+  verifyIngest?: typeof validateIngestKey;
+  introspect?: typeof introspectKey;
+  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] };
+
+  // The stable key: an explicit --machine-id wins, else the id already enrolled
+  // here is reused (idempotent re-connect), else a fresh one is minted. Never
+  // the hostname — that is the label, so same-hostname hosts do not merge.
+  const machineId = resolveMachineId(opts.machineId);
+  const machineLabel = resolveMachineLabel(opts.machineLabel ?? opts.defaultMachineId);
+  // Humans read the label; the id is shown in parentheses only when it differs,
+  // so an operator who set an explicit --machine-id still sees it.
+  const shownAs = machineLabel === machineId ? machineId : `${machineLabel} (${machineId})`;
+
+  // 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,
+    machineLabel,
+    sessions: opts.sessions,
+    environment: opts.environment,
+    verifyPolicy: opts.verify,
+    verifyIngest: opts.verifyIngest,
+    introspect: opts.introspect,
+  });
+
+  if (!outcome.anyConfigured) {
+    return { exitCode: 1, lines: describeOutcome(outcome, shownAs, 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, shownAs, validated.url),
+    `  Token ${maskToken(opts.token)} stored in ${paths.join(" and ")} (owner-only).`,
+  ];
+  if (outcome.ingest.ok) {
+    // Stated on BOTH branches, never only on the surprising one. Connecting
+    // sends transcripts by default — prompts, file contents, command output —
+    // and a default that carries that much is one the user has to be told
+    // about at the moment it takes effect, not left to find in --help.
+    lines.push(
+      opts.sessions === false
+        ? "  Session transcripts are NOT being sent (--no-transcripts). Decisions only."
+        : "  Sending policy decisions AND full session transcripts (prompts, file\n" +
+          "  contents, command output). Use --no-transcripts for decisions only.",
+    );
+  }
+  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();
+  // Stop ENFORCING them too, not merely refreshing them. Clearing the
+  // credential ends the daemon's polling; every artifact already on disk stayed
+  // referenced by `active.json` and kept being loaded on every tool call — so a
+  // machine that had deliberately left its organisation went on being governed
+  // by whatever generation was current when it left, indefinitely, while
+  // `--status` reported it as unconnected.
+  const stoppedManaged = clearActiveCloudManagedPolicies();
+  // Back to OSS. Leaving mode = "cloud" with no credentials would describe a
+  // machine that does not exist, and every cloud code path keys off this flag
+  // rather than off "is a token lying around" precisely so that a disconnected
+  // machine is provably silent instead of silent-by-happenstance.
+  updateConfig({ mode: "oss" });
+
+  if (!removed && !existing && !hadIngest && !stoppedManaged) {
+    return { exitCode: 0, lines: ["This machine is not connected to Failproof Cloud."] };
+  }
+
+  const lines = [
+    "Disconnected from Failproof Cloud.",
+    "",
+    stoppedManaged
+      ? "  Cloud-managed policies stop being enforced and stop being refreshed.\n" +
+        "  Local builtin, custom and convention policies are unaffected."
+      : "  Local builtin, custom and convention policies are unaffected.",
+  ];
+  if (removedIngest) {
+    // Named honestly. The collector manager starts once for the daemon's
+    // lifetime (`main.rs`) and the uploader caches its bearer key at
+    // construction, so nothing already running notices this file disappear —
+    // "stop being sent" was true only of the NEXT daemon start. Telling the
+    // user the step that makes it true beats a claim that quietly is not.
+    lines.push(
+      "  No new hook activity or transcripts will be queued. A running failproofaid",
+      "  keeps the key it started with, so restart it to stop the current process",
+      `  sending: ${daemonRestartCommand() ?? "restart failproofaid"}`,
+    );
+  }
+  return { exitCode: 0, lines };
+}
+
+/** The connection half of `--status`. Never prints the token. */
+/**
+ * The version line for `--status`.
+ *
+ * First thing worth knowing in a bug report, and the only place a user can
+ * currently find out which daemon they are running without listing a directory.
+ */
+export function versionStatusLines(): string[] {
+  const skew = daemonVersionSkew();
+  const recorded = readVersionFile();
+  const daemon = recorded?.daemon ?? "not installed";
+  return [
+    `CLI ${cliVersion} · daemon ${daemon}${skew ? " (STALE)" : ""} · layout ${recorded?.layout ?? "-"}`,
+    ...(skew ? ["  Run `failproofai config` to update the daemon."] : []),
+  ];
+}
+
+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."];
+
+  // Recorded at connect time from the server's own answer, never guessed from
+  // the URL: one deployment hosts many orgs, so the host says nothing about
+  // which one this machine's data lands in. Absent against a server with no
+  // introspect endpoint, and on credentials written before this was recorded —
+  // in both cases the line is simply omitted rather than guessed at.
+  const org = readCredentials().org;
+  const orgLine = org
+    ? org.name && org.slug
+      ? `${org.name} (${org.slug})`
+      : (org.name ?? org.slug ?? org.id)
+    : undefined;
+
+  const lines: string[] = [];
+  if (creds) {
+    // Show the human label with the stable id in parentheses; fall back to the
+    // bare id for credentials written before labels existed.
+    const shownAs = creds.machineLabel
+      ? `${creds.machineLabel} (${creds.machineId})`
+      : creds.machineId;
+    lines.push(`Cloud: connected to ${creds.url} as ${shownAs} (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 (orgLine) lines.push(`  Org       ${orgLine}`);
+
+  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;
+}