@bli-cockpit/cli 0.2.47 → 0.2.48

package/dist/commands/heartbeat.js

@@ -25,6 +25,7 @@ import os from "node:os";
 import path from "node:path";
 import { COLLECTOR_HEARTBEAT_SCHEMA_VERSION, } from "@bli-cockpit/telemetry-core";
 import { describeError } from "../health-detail.js";
+import { shouldSuppressFleetReceipts, } from "../dev-build.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
 const HEARTBEAT_TIMEOUT_MS = 5_000;
 /**
@@ -112,6 +113,23 @@ export function buildCollectorHeartbeat(options) {
  * `sync.err.log` alone when the dashboard says a device is quiet.
  */
 export async function sendCollectorHeartbeatBestEffort(options) {
+    // BLI-3554. A checkout's heartbeat would move `last_seen_at` on a real fleet
+    // device row, so an agent's worktree could keep a genuinely dead machine
+    // looking alive to the BLI-3550 reader.
+    const suppression = shouldSuppressFleetReceipts({
+        dashboardUrl: options.dashboardUrl,
+        ...(options.devBuildProbe ? { probe: options.devBuildProbe } : {}),
+    });
+    if (suppression.suppressed) {
+        console.error("[heartbeat] dev build; this tick is not checking in with the fleet", JSON.stringify({
+            reason: "receipt_suppressed:dev_build",
+            detected_by: suppression.reason,
+            root_count: options.roots.length,
+            sync_status: options.facts.status,
+            fix: "set COCKPIT_DEV=0 to heartbeat from a checkout deliberately",
+        }));
+        return false;
+    }
     const paths = getCollectorRuntimePaths(options.homeDir);
     const session = await readLocalCollectorSessionFile(paths).catch(() => null);
     if (!session ||

package/dist/commands/install-receipts.js

@@ -14,6 +14,7 @@ import { errorMessage, writeLine } from "./cli-io.js";
 import { describeError, maskLocalIdentifiers, redactedHealthDetail, } from "../health-detail.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
 import { redactSecretLikeContent } from "@bli-cockpit/telemetry-core";
+import { shouldSuppressFleetReceipts, } from "../dev-build.js";
 import { enqueueInstallEventEntry, readPendingInstallEventEntries, recordInstallEventAttemptFailure, removeInstallEventEntry, } from "../spool/install-event-outbox.js";
 export function addInstallEvent(events, step, status, errorCode, 
 // BLI-2542: the bucket alone cannot be acted on. Callers that hold the reason
@@ -47,6 +48,25 @@ export function sanitizeInstallErrorCode(value) {
 export async function reportInstallEventsBestEffort(options) {
     if (options.events.length === 0)
         return null;
+    // BLI-3554. Withheld BEFORE the outbox, not before the POST: an entry queued
+    // by a checkout survives in `~/.cockpit` and the next real scheduled tick
+    // would deliver it under the workspace version, which is exactly how 47
+    // sandbox receipts reached the production fleet table.
+    const suppression = shouldSuppressFleetReceipts({
+        dashboardUrl: options.dashboardUrl,
+        ...(options.devBuildProbe ? { probe: options.devBuildProbe } : {}),
+    });
+    if (suppression.suppressed) {
+        console.error("[install-receipts] dev build; install receipts withheld from the fleet", JSON.stringify({
+            reason: "receipt_suppressed:dev_build",
+            detected_by: suppression.reason,
+            command: options.command,
+            event_count: options.events.length,
+            cli_version: LOCAL_COLLECTOR_VERSION,
+            fix: "set COCKPIT_DEV=0 to post receipts from a checkout deliberately",
+        }));
+        return null;
+    }
     const paths = getCollectorRuntimePaths(options.homeDir);
     try {
         await enqueueInstallEventEntry(paths, {
@@ -98,6 +118,7 @@ export async function reportInstallEventsBestEffort(options) {
     }
     const pending = (await readPendingInstallEventEntries(paths)).slice(0, 20);
     const failures = [];
+    let delivered = 0;
     let observedMinCliVersion = null;
     for (let offset = 0; offset < pending.length; offset += 5) {
         await Promise.all(pending.slice(offset, offset + 5).map(async (entry) => {
@@ -138,6 +159,7 @@ export async function reportInstallEventsBestEffort(options) {
                     observedMinCliVersion = receipt.min_cli_version.trim();
                 }
                 await removeInstallEventEntry(paths, entry.outbox_id);
+                delivered += 1;
             }
             catch (error) {
                 const failureReason = classifyInstallTelemetryError(error);
@@ -170,6 +192,18 @@ export async function reportInstallEventsBestEffort(options) {
             }
         }));
     }
+    if (delivered > 0) {
+        // The success branch says so too (BLI-3554 / the logging contract): a log
+        // that only fires on failure cannot answer "did any receipt land at all
+        // today?", which is the question a suppressed dev build now provokes.
+        console.error("[install-receipts] install events delivered", JSON.stringify({
+            reason: "install_events_delivered",
+            command: options.command,
+            delivered_entries: delivered,
+            kept_for_retry: pending.length - delivered,
+            cli_version: LOCAL_COLLECTOR_VERSION,
+        }));
+    }
     if (options.json && failures.length > 0) {
         writeLine(options.io.stderr, `Install event telemetry queued for retry: ${[...new Set(failures)].join(",")}`);
     }

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.47");
+    writeLine(io?.stdout ?? process.stdout, "0.2.48");
     return 0;
   }
 

package/dist/dev-build.js

@@ -0,0 +1,186 @@
+/**
+ * Is this collector a DEV BUILD? One predicate, two callers.
+ *
+ * BLI-3554. Edward's device row carried 47 `npm_install_eacces` receipts
+ * stamped `cli_version` 0.1.50 between 2026-09-02T16:55Z and 2026-09-03T06:25Z.
+ * 0.1.50 was never a published install on that machine — it was the workspace
+ * version in `packages/cockpit-local-collector/package.json` at the time, so
+ * every one of those rows came from an agent or a test running the built
+ * collector inside a worktree. They land in the same production
+ * `cockpit_install_events` table the fleet reader (BLI-3550,
+ * `apps/dashboard/src/lib/ops/fleet-liveness.ts`) alarms on, so a developer's
+ * sandbox failure reads as a fleet machine in trouble.
+ *
+ * The predicate is deliberately NOT a version comparison. A version equal to
+ * the workspace version is a symptom: it changes on every release, it is equal
+ * for the one machine that legitimately runs the newest published build the
+ * day it ships, and it says nothing about where the code was loaded from.
+ * What we can actually observe is the FILE the running code was loaded from:
+ *
+ * - a published install lives under a `node_modules/` prefix
+ *   (`/opt/homebrew/lib/node_modules/@bli-cockpit/cli/dist/…`,
+ *   `C:\\Users\\x\\AppData\\Roaming\\npm\\node_modules\\@bli-cockpit\\cli\\dist\\…`),
+ *   and that is the whole fleet;
+ * - a dev build lives inside a checkout of this repo — a
+ *   `packages/cockpit-local-collector/` (or `packages/cockpit-cli/`) ancestor
+ *   whose `package.json` names the workspace, with a `.git` marker or a
+ *   `.claude/worktrees` segment above it.
+ *
+ * `COCKPIT_DEV=1` forces dev. `COCKPIT_DEV=0` forces the opposite — that is the
+ * escape hatch for a deliberate live test from a checkout, documented in
+ * `docs/runbooks/cockpit-collector-receipts.md`.
+ *
+ * Suppression only bites when the target is a PRODUCTION dashboard. Pointing a
+ * checkout at `http://localhost:3000` is how the receipt path itself is
+ * developed, and refusing to post there would make this predicate the reason
+ * the next receipt bug cannot be reproduced.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** The workspaces whose `dist/` a developer or agent runs from a checkout. */
+const WORKSPACE_PACKAGE_NAMES = new Set([
+    "@bli-cockpit/local-collector",
+    "@bli-cockpit/cli",
+]);
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+const FALSE_VALUES = new Set(["0", "false", "no", "off"]);
+/**
+ * Walks up from the running module. Pure apart from the two injected readers,
+ * so a Windows layout can be asserted from a macOS test run.
+ */
+export function detectDevBuild(probe = {}) {
+    const env = probe.env ?? process.env;
+    const rawFlag = (env.COCKPIT_DEV ?? "").trim().toLowerCase();
+    if (TRUE_VALUES.has(rawFlag)) {
+        return { devBuild: true, reason: "cockpit_dev_env" };
+    }
+    if (FALSE_VALUES.has(rawFlag)) {
+        // Deliberate live test from a checkout: the operator has said so out loud,
+        // and the path evidence below is not allowed to overrule them.
+        return { devBuild: false, reason: "cockpit_dev_env_disabled" };
+    }
+    const pathApi = probe.pathApi ?? path;
+    const modulePath = probe.modulePath ?? currentModulePath();
+    if (!modulePath)
+        return { devBuild: false, reason: "not_a_checkout" };
+    if (hasNodeModulesSegment(modulePath)) {
+        // Every published install is under a `node_modules/` prefix, on both host
+        // families. This branch is the whole fleet, and it is checked first so a
+        // machine that happens to have a repo checkout somewhere above its global
+        // npm prefix cannot be mislabelled.
+        return { devBuild: false, reason: "published_install" };
+    }
+    const readPackageName = probe.readPackageName ?? defaultReadPackageName;
+    const pathExists = probe.pathExists ?? defaultPathExists;
+    const packageRoot = findWorkspacePackageRoot(pathApi.dirname(modulePath), pathApi, readPackageName);
+    if (!packageRoot)
+        return { devBuild: false, reason: "not_a_checkout" };
+    if (!hasCheckoutMarkerAbove(packageRoot, pathApi, pathExists)) {
+        return { devBuild: false, reason: "not_a_checkout" };
+    }
+    return { devBuild: true, reason: "workspace_checkout" };
+}
+/**
+ * Should this process withhold fleet receipts (install events, heartbeat)?
+ *
+ * Two facts, in this order: is the code a dev build, and is the target the
+ * production fleet. A dev build talking to `localhost` still posts, because
+ * that is the only way to exercise the receipt path at all.
+ */
+export function shouldSuppressFleetReceipts(options) {
+    const verdict = detectDevBuild(options.probe ?? {});
+    if (!verdict.devBuild)
+        return { suppressed: false, reason: verdict.reason };
+    if (isLocalDashboardUrl(options.dashboardUrl)) {
+        return { suppressed: false, reason: "local_dashboard" };
+    }
+    return { suppressed: true, reason: verdict.reason };
+}
+/** A dashboard on this machine — safe for a checkout to post at. */
+export function isLocalDashboardUrl(dashboardUrl) {
+    let hostname;
+    try {
+        hostname = new URL(dashboardUrl).hostname.toLowerCase();
+    }
+    catch {
+        // An unparseable URL is not demonstrably local, and this predicate only
+        // ever widens suppression when it says false.
+        return false;
+    }
+    const bare = hostname.replace(/^\[|\]$/gu, "");
+    return (bare === "localhost" ||
+        bare === "127.0.0.1" ||
+        bare === "::1" ||
+        bare === "0.0.0.0" ||
+        bare.endsWith(".localhost"));
+}
+function currentModulePath() {
+    try {
+        return fileURLToPath(import.meta.url);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Case-insensitive on purpose: Windows spells the same folder
+ * `Node_Modules` without complaint, and both separators appear on that host
+ * because a POSIX-style path survives most Node APIs there.
+ */
+function hasNodeModulesSegment(modulePath) {
+    return modulePath
+        .split(/[\\/]+/u)
+        .some((segment) => segment.toLowerCase() === "node_modules");
+}
+function findWorkspacePackageRoot(startDir, pathApi, readPackageName) {
+    let dir = startDir;
+    // Bounded: `path.dirname` reaches a fixed point at `/` or `C:\`, and the
+    // depth guard keeps a pathological symlink loop from spinning a sync walk.
+    for (let depth = 0; depth < 64; depth += 1) {
+        const name = readPackageName(pathApi.join(dir, "package.json"));
+        if (name && WORKSPACE_PACKAGE_NAMES.has(name))
+            return dir;
+        const parent = pathApi.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * A repo checkout marker at or above the workspace package: `.git` (a
+ * directory in a normal clone, a FILE in a `git worktree`), or the
+ * `.claude/worktrees` staging area agents run from.
+ */
+function hasCheckoutMarkerAbove(packageRoot, pathApi, pathExists) {
+    let dir = packageRoot;
+    for (let depth = 0; depth < 64; depth += 1) {
+        if (pathExists(pathApi.join(dir, ".git")))
+            return true;
+        if (pathExists(pathApi.join(dir, ".claude", "worktrees")))
+            return true;
+        const parent = pathApi.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+    return false;
+}
+function defaultReadPackageName(packageJsonPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        return typeof parsed.name === "string" ? parsed.name : null;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultPathExists(candidate) {
+    try {
+        return fs.existsSync(candidate);
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.47",
+  "version": "0.2.48",
   "private": false,
   "type": "module",
   "bin": {
@@ -24,7 +24,7 @@
     "pretypecheck": "npm run build",
     "typecheck": "node -e \"await import('./dist/commands/public-root.js')\"",
     "pretest": "npm run build",
-    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
+    "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
     "@bli-cockpit/telemetry-core": "0.1.26"