@tokenoftrust/cli 1.3.4-rc.2 → 1.3.4-rc.4

package/bin/tot.cjs

@@ -40,21 +40,49 @@ if (!meets) {
       "  → next: install Node " + RECOMMENDED_NODE + " (LTS) — nvm: `nvm install " + RECOMMENDED_NODE +
       " && nvm use " + RECOMMENDED_NODE + "`, or https://nodejs.org/ — then re-run the same command.\n"
   );
-  process.exit(1);
-}
+  // Beacon the hosted cockpit that this machine dead-ended on the Node floor, then
+  // exit. This is THE headline obstacle: an invited dev whose `tot login` (the
+  // pasted setup command) can't even run because their Node is too old. We're
+  // pre-login, pre-ESM, maybe pre-`fetch` — so the beacon reads the bridge
+  // credential straight from the pasted flags and posts over require("https").
+  // Best-effort and time-boxed: the ✗ message is already printed; we only linger
+  // (≤ the beacon's own timeout) to deliver telemetry before exit(1).
+  beaconNodeTooOld(nodeVersion, function () { process.exit(1); });
+} else {
+  // Supported Node from here on. Hand off to the ESM CLI; pathToFileURL keeps
+  // the import specifier correct on Windows drive-letter paths too.
+  var path = require("path");
+  var pathToFileURL = require("url").pathToFileURL;
+  var entry = pathToFileURL(path.join(__dirname, "tot.mjs")).href;
 
-// Supported Node from here on. Hand off to the ESM CLI; pathToFileURL keeps
-// the import specifier correct on Windows drive-letter paths too.
-var path = require("path");
-var pathToFileURL = require("url").pathToFileURL;
-var entry = pathToFileURL(path.join(__dirname, "tot.mjs")).href;
+  // new Function with a CONSTANT body ("return import(u)") — nothing is ever
+  // interpolated into the code string; the entry URL travels as an argument. This
+  // indirection exists only so pre-import() parsers never see the import syntax.
+  new Function("u", "return import(u)")(entry).catch(function (e) {
+    // tot.mjs formats + exits on its own errors; landing here means the CLI
+    // itself failed to LOAD on a supported Node — a packaging bug, worth the detail.
+    process.stderr.write("✗ tot failed to start: " + ((e && e.message) || e) + "\n");
+    process.exit(1);
+  });
+}
 
-// new Function with a CONSTANT body ("return import(u)") — nothing is ever
-// interpolated into the code string; the entry URL travels as an argument. This
-// indirection exists only so pre-import() parsers never see the import syntax.
-new Function("u", "return import(u)")(entry).catch(function (e) {
-  // tot.mjs formats + exits on its own errors; landing here means the CLI
-  // itself failed to LOAD on a supported Node — a packaging bug, worth the detail.
-  process.stderr.write("✗ tot failed to start: " + ((e && e.message) || e) + "\n");
-  process.exit(1);
-});
+// Fire the node-too-old obstacle beacon, then always call `done` (exactly once,
+// bounded by the beacon's timeout). Isolated + fully guarded: any hiccup —
+// missing flags, an old Node that can't require a .cjs, a network stall — just
+// falls through to `done`, so the exit path is never blocked or altered. The
+// heavy lifting lives in the shared ES5 helper so the wire shape can't drift.
+function beaconNodeTooOld(have, done) {
+  try {
+    var mod = require("../src/obstacle-beacon.cjs");
+    var act = mod.parseActivityArgs(process.argv);
+    if (!act.url || !act.token) { done(); return; }
+    var cliVersion;
+    try { cliVersion = require("../package.json").version; } catch (e) {}
+    mod.beacon(
+      { url: act.url, token: act.token, kind: "node-too-old", have: have, need: MIN_NODE, cliVersion: cliVersion },
+      done
+    );
+  } catch (e) {
+    done();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "1.3.4-rc.2",
+  "version": "1.3.4-rc.4",
   "description": "Token of Trust developer CLI — check out a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/commands/checkout.mjs

@@ -24,6 +24,7 @@ import { createMcpClient } from "../mcp.mjs";
 import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { writeNvmrc } from "../sample.mjs";
+import { emitObstacle } from "../obstacle.mjs";
 
 const execFileP = promisify(execFile);
 
@@ -202,6 +203,10 @@ async function cloneRepo(gitRemote, dir, redact) {
   try {
     await git(["clone", gitRemote, dir]);
   } catch (e) {
+    // Beacon the cockpit before we surface the error — covers this path for both
+    // `tot checkout` and `tot start` (which clones through here). Awaited so the
+    // packet lands before the process prints + exits; swallowed either way.
+    await emitObstacle("clone-failed");
     throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
       next: `check the target dir is empty and you can reach the remote, then re-run`,
     });

package/src/commands/dev.mjs

@@ -42,6 +42,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { createMcpClient, CLI_VERSION, setRunnerVersion, versionStamp } from "../mcp.mjs";
 import { establishSession } from "../auth.mjs";
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
+import { emitObstacle } from "../obstacle.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { openBrowser, waitForServer, firstFreePort } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
@@ -435,12 +436,24 @@ export async function resolveRendererSource(args, { client } = {}) {
  * version, so a mismatch is visible, not silent. If nothing exact/minor/≤-ceiling is
  * published, we THROW — a release gap to fix by publishing the aligned runner, not paper over.
  *
+ * PIN-DIRECTION DECISION (ADR 0011 — don't relitigate inline): the runner version
+ * should be DECLARED BY THE PRODUCT, not derived from the CLI's identity. The
+ * ladder below reflects the migration:
+ *   1. explicit flag/env pin        — developer intent, always wins
+ *   2. declaredVersion              — the STORE's own `.tot/config.json#runnerVersion`
+ *                                     (rust-toolchain.toml-style; the target state)
+ *   3. exact CLI-version match      — TRANSITIONAL lockstep rung. Delete it (and the
+ *                                     lockstep publish regime) once tenant_checkout
+ *                                     stamps runnerVersion into every checkout —
+ *                                     see ADR 0011 for the exit criteria.
+ *   4. CLI-minor / ≤-ceiling        — degraded-but-safe fallbacks (never a floating tag)
+ *
  * Pure (no I/O) for testability.
  * @param {any} meta npm packument (`dist-tags` + `versions`)
- * @param {{ cliVersion: string, explicitPin?: string|null }} opts
+ * @param {{ cliVersion: string, explicitPin?: string|null, declaredVersion?: string|null }} opts
  * @returns {{ version: string, reason: string }}
  */
-export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
+export function pickRunnerVersion(meta, { cliVersion, explicitPin, declaredVersion }) {
   const distTags = meta?.["dist-tags"] || {};
   const versions = Object.keys(meta?.versions || {});
 
@@ -457,12 +470,21 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
   };
 
   // 1) Explicit pin (flag/env): the deliberate escape hatch — honored verbatim,
-  // INCLUDING above the ceiling (someone testing a newer runner on purpose). This is
-  // the ONLY way past the ceiling; every automatic path below respects it.
+  // INCLUDING above the ceiling (someone testing a newer runner on purpose).
   if (explicitPin) {
     return { version: distTags[explicitPin] || explicitPin, reason: `pinned ${explicitPin}` };
   }
 
+  // 1.5) PRODUCT-DECLARED version (ADR 0011): the store's checkout says which runner
+  // it runs — the CLI is just the resolver. Honored verbatim when published, INCLUDING
+  // above the ceiling: a declaration newer than this CLI means the CLI is what's stale
+  // (the caller nudges an update), not that the product is wrong. A declaration that
+  // ISN'T published is a product release gap — fall through to the normal ladder
+  // rather than hard-failing the developer's loop (the caller warns loudly).
+  if (declaredVersion && versions.includes(declaredVersion)) {
+    return { version: declaredVersion, reason: "declared by the store checkout (runnerVersion)" };
+  }
+
   // 2) EXACT CLI-version match — the primary path for a lockstep release: the runner
   // is published at the SAME version as the CLI (incl. prereleases like 1.3.0-rc.0,
   // which the stable-only minor match below deliberately skips). This is what makes
@@ -507,6 +529,28 @@ export function pickRunnerVersion(meta, { cliVersion, explicitPin }) {
   );
 }
 
+/**
+ * The runner version a store checkout DECLARES for itself (ADR 0011) — the
+ * `runnerVersion` field of `<workspace>/.tot/config.json`. This is the
+ * rust-toolchain.toml of the storefront: the PRODUCT (via tenant_checkout
+ * stamping it server-side) owns which runtime the store runs; the CLI just
+ * resolves it. Returns null when absent/malformed/not-semver — silence is
+ * correct: an undeclared checkout falls back to the transitional lockstep rung.
+ * Pure-ish (one file read) + exported for tests.
+ * @param {string|null|undefined} workspaceDir
+ * @returns {string|null}
+ */
+export function declaredRunnerVersion(workspaceDir) {
+  if (!workspaceDir) return null;
+  try {
+    const cfg = JSON.parse(readFileSync(join(workspaceDir, ".tot", "config.json"), "utf8"));
+    const v = cfg?.runnerVersion;
+    return typeof v === "string" && /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
 /** Parse the numeric {major, minor} from a semver (prerelease suffix ignored). Null if unparseable. */
 export function majorMinor(v) {
   const m = /^(\d+)\.(\d+)\./.exec(String(v || ""));
@@ -531,7 +575,7 @@ function compareStableAsc(a, b) {
  * override with `--renderer-version` / TOT_RUNNER_VERSION. Package/registry
  * overridable via env for testing.
  */
-export async function resolvePublicRendererSource(args, env = process.env) {
+export async function resolvePublicRendererSource(args, env = process.env, { declaredVersion = null } = {}) {
   const pkg = env.TOT_RUNNER_PACKAGE || PUBLIC_RUNNER_PACKAGE;
   const registry = (env.TOT_NPM_REGISTRY || DEFAULT_NPM_REGISTRY).replace(/\/$/, "");
   const explicitPin = args.rendererVersion || env.TOT_RUNNER_VERSION || null;
@@ -541,11 +585,29 @@ export async function resolvePublicRendererSource(args, env = process.env) {
     throw new Error(`npm metadata for ${pkg} failed: HTTP ${res.status} ${res.statusText}`);
   }
   const meta = await res.json();
-  const { version, reason } = pickRunnerVersion(meta, { cliVersion: CLI_VERSION, explicitPin });
-  // Exact is the goal (lockstep publish → runner@CLI_VERSION always present). If we
-  // resolved something ELSE, the versions are skewed — surface it LOUDLY instead of
-  // silently running a mismatched runner (the class of bug this whole change targets).
-  if (!explicitPin && version !== CLI_VERSION) {
+  const { version, reason } = pickRunnerVersion(meta, { cliVersion: CLI_VERSION, explicitPin, declaredVersion });
+  if (!explicitPin && declaredVersion) {
+    if (version === declaredVersion) {
+      // The product-declared path (ADR 0011) — the intended steady state, not skew.
+      // A declaration NEWER than this CLI means the CLI is the stale half: nudge.
+      const mm = majorMinor(declaredVersion);
+      const cliMM = majorMinor(CLI_VERSION);
+      if (mm && cliMM && (mm.major > cliMM.major || (mm.major === cliMM.major && mm.minor > cliMM.minor))) {
+        console.warn(
+          `  ~ this store declares runner ${declaredVersion}, newer than your CLI (${CLI_VERSION}) — ` +
+            `if anything misbehaves: npm i -g @tokenoftrust/cli@latest`,
+        );
+      }
+    } else {
+      console.warn(
+        `  ⚠ this store declares runner ${declaredVersion} but that version isn't on npm — ` +
+          `using ${version} (${reason}). The store's runnerVersion needs a published release.`,
+      );
+    }
+  } else if (!explicitPin && version !== CLI_VERSION) {
+    // No declaration (transitional lockstep regime — ADR 0011): exact is the goal.
+    // Resolving something ELSE means CLI/runner releases are skewed — say so LOUDLY
+    // instead of silently running a mismatched runner.
     console.warn(
       `  ⚠ runner ${version} — no exact @${CLI_VERSION} published (${reason}). ` +
         `CLI/runner versions are SKEWED; publish the runner at ${CLI_VERSION} to align ` +
@@ -733,26 +795,31 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
   }
 
   // kind === "none" — no override, not in the monorepo: fetch the PUBLIC runner
-  // from npm, PINNED to this CLI's version. No MCP, no entitlement, no login.
+  // from npm. Version = what the STORE declares (ADR 0011), else pinned to this
+  // CLI's version (transitional lockstep). No MCP, no entitlement, no login.
   const explicitPin = args.rendererVersion || env.TOT_RUNNER_VERSION || null;
-
-  // Fully-offline fast path: when the runner published lockstep at this exact CLI
-  // version is already cached, reuse it without touching npm — honouring "don't
-  // hit npm when the RIGHT version is already cached" without ever reusing a
-  // version the pin didn't choose. Safe because `public-<CLI_VERSION>` only exists
-  // if a prior run fetched exactly that (pinned) version. Skipped when an explicit
-  // pin is set (that must go through resolution).
+  const declared = declaredRunnerVersion(args.workspace || ctx?.workspacePath);
+  const wantVersion = declared || CLI_VERSION;
+
+  // Fully-offline fast path: when the WANTED version (declared, else lockstep) is
+  // already cached, reuse it without touching npm — honouring "don't hit npm when
+  // the RIGHT version is already cached" without ever reusing a version the
+  // resolution wouldn't choose. Safe because `public-<version>` only exists if a
+  // prior run fetched exactly that version. Skipped when an explicit pin is set
+  // (that must go through resolution).
   if (!explicitPin) {
-    const exact = pinnedPublicCacheDir(cacheRoot, CLI_VERSION);
+    const exact = pinnedPublicCacheDir(cacheRoot, wantVersion);
     if (exact) {
-      // Trust-but-verify: a `public-<CLI_VERSION>` dir SHOULD be a current runner,
+      // Trust-but-verify: a `public-<version>` dir SHOULD be a current runner,
       // but if it can't report its own version it predates the --version surface
       // (a corrupt/half-migrated cache) — force a fresh fetch rather than run a
       // runner we can't identify. When it DOES answer, reuse it (fully offline-safe).
       if (probeRunnerVersion(exact)) {
-        console.error(`~ renderer: cached public runner ${CLI_VERSION} (matches this CLI)`);
-        setRunnerVersion(CLI_VERSION);
-        prunePublicRunnerCache(cacheRoot, CLI_VERSION);
+        console.error(
+          `~ renderer: cached public runner ${wantVersion} (${declared ? "declared by this store" : "matches this CLI"})`,
+        );
+        setRunnerVersion(wantVersion);
+        prunePublicRunnerCache(cacheRoot, wantVersion);
         return exact;
       }
       console.error(`~ renderer: cached runner at ${exact} can't report a version — refetching (forced upgrade)`);
@@ -762,7 +829,7 @@ export async function ensureSampleRenderer(args, ctx, { env = process.env, cache
 
   let pub;
   try {
-    pub = await resolvePublicRendererSource(args, env);
+    pub = await resolvePublicRendererSource(args, env, { declaredVersion: declared });
   } catch (e) {
     // OFFLINE / npm unreachable — no way to resolve the pinned version. Last
     // resort: reuse ANY complete cached runner rather than hard-failing `tot dev`.
@@ -862,7 +929,7 @@ export async function installRunnerTarball({ source, version, isUrl = true, stri
       stages: [{ afterMs: 20000, text: "still setting up the preview engine (first run only)…" }],
     });
     try {
-      runPnpmInstall(stagingDir, { logPath: installLog });
+      await runPnpmInstall(stagingDir, { logPath: installLog });
     } finally {
       installSpin.stop();
     }
@@ -956,7 +1023,7 @@ function ensureCorepackPnpm(runnerDir, { logPath } = {}) {
  * caller's spinner owns the screen. On failure we surface a clean, business-
  * readable message + the log path — never the raw node/pnpm firehose.
  */
-function runPnpmInstall(runnerDir, { logPath } = {}) {
+async function runPnpmInstall(runnerDir, { logPath } = {}) {
   const fd = logPath ? openSync(logPath, "a") : null;
   const installArgs = ["install", "--config.dangerouslyAllowAllBuilds=true"];
   // npm FIRST: it ships with EVERY Node (including 25+, where corepack is no
@@ -989,6 +1056,7 @@ function runPnpmInstall(runnerDir, { logPath } = {}) {
         continue;
       }
       // The launcher ran; the install itself failed. That's the actionable error.
+      await emitObstacle("install-failed");
       throw new CliError(
         `couldn't set up the store preview engine${pnpmFailureHint(logPath)}` +
           (logPath ? `\n     details: ${logPath}` : ""),
@@ -998,6 +1066,7 @@ function runPnpmInstall(runnerDir, { logPath } = {}) {
     // Every launcher ENOENT'd → there's no pnpm on this machine and corepack
     // couldn't provide one (corepack isn't bundled on Node 25+). npm ships with
     // every Node, so `npm i -g pnpm` is the escape hatch that always exists.
+    await emitObstacle("pnpm-missing");
     throw new CliError(
       "couldn't set up the store preview engine — pnpm isn't available on this machine" +
         (logPath ? `\n     details: ${logPath}` : ""),

package/src/obstacle-beacon.cjs

@@ -0,0 +1,111 @@
+/**
+ * The obstacle beacon — a fire-and-forget POST that tells the hosted cockpit a
+ * `tot start` / `tot checkout` failed, so it can show the exact fix in the bridge
+ * strip (obstacle lane, server side already shipped). Best-effort telemetry that
+ * rides ALONGSIDE the house-style `✗ … → next:` error; it must NEVER change,
+ * delay past its timeout, or fail that error path.
+ *
+ *   KEEP THIS FILE ES5/CommonJS: var, string concat, function expressions — no
+ *   arrow functions, template literals, optional chaining, or const/let. The ES5
+ *   launcher (bin/tot.cjs) require()s this on a machine that FAILED the Node
+ *   floor (Node < 22.12, no global `fetch`, no ESM) to beacon `node-too-old`
+ *   pre-login — the exact old-Node dead-end the whole obstacle lane exists for.
+ *   So this uses require("https"/"http"), and a test keeps it parseable by
+ *   ancient Nodes. The ESM side (src/obstacle.mjs) imports beaconAsync from here
+ *   too, so the wire shape + endpoint live in ONE place and can't drift.
+ *
+ * The event contract is DECIDED (owned by the server's rail-obstacle-lane):
+ *   POST <activity-url>/api/dev/activity   Authorization: Bearer <token>
+ *   { event:"obstacle", kind, have?, need?, cliVersion?, at? }
+ * Send ONLY these machine-readable fields — the human remediation copy is composed
+ * SERVER-side per kind, so guidance changes without a CLI release. The server
+ * stamps its own reportedAt (skew-proof) and a later heartbeat CLEARS the obstacle.
+ */
+"use strict";
+
+var VALID_KINDS = { "node-too-old": 1, "pnpm-missing": 1, "install-failed": 1, "clone-failed": 1 };
+var TIMEOUT_MS = 2000;
+
+/**
+ * Pull --activity-url / --activity-token straight out of argv. The launcher runs
+ * BEFORE any arg framework (and before login has cached anything), so on the
+ * node-too-old path this is the only source of the bridge credential — the pasted
+ * setup command carries both flags. Returns {} for whatever is absent.
+ */
+function parseActivityArgs(argv) {
+  var out = { url: undefined, token: undefined };
+  if (!argv) return out;
+  for (var i = 0; i < argv.length; i++) {
+    if (argv[i] === "--activity-url") out.url = argv[i + 1];
+    else if (argv[i] === "--activity-token") out.token = argv[i + 1];
+  }
+  return out;
+}
+
+/**
+ * Fire one obstacle beacon. Everything is wrapped so it can never throw into the
+ * caller's error path; `done` is invoked EXACTLY once (on success, error, timeout,
+ * or a skip) — the launcher passes process.exit as `done` so the process lingers
+ * only as long as the beacon (≤ TIMEOUT_MS) before exiting.
+ *   opts: { url, token, kind, have?, need?, cliVersion?, at? }
+ */
+function beacon(opts, done) {
+  var finished = false;
+  function finish() {
+    if (finished) return;
+    finished = true;
+    try { if (timer) clearTimeout(timer); } catch (e) {}
+    if (typeof done === "function") { try { done(); } catch (e) {} }
+  }
+  var timer = null;
+  try {
+    opts = opts || {};
+    if (!opts.url || !opts.token || !VALID_KINDS[opts.kind]) { finish(); return; }
+
+    var body = { event: "obstacle", kind: opts.kind };
+    if (opts.have) body.have = opts.have;
+    if (opts.need) body.need = opts.need;
+    if (opts.cliVersion) body.cliVersion = opts.cliVersion;
+    body.at = opts.at || Date.now();
+    var payload = JSON.stringify(body);
+
+    var endpoint = String(opts.url).replace(/\/+$/, "") + "/api/dev/activity";
+    var lib = endpoint.indexOf("http://") === 0 ? require("http") : require("https");
+
+    // A hard timeout guarantees the caller's exit (or await) is bounded even if
+    // the socket hangs — telemetry never holds a failing developer hostage.
+    timer = setTimeout(finish, TIMEOUT_MS);
+
+    var req = lib.request(
+      endpoint,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: "Bearer " + opts.token,
+          "content-length": Buffer.byteLength(payload),
+        },
+      },
+      function (res) {
+        // Drain and finish — we don't care about the status, only that it was sent.
+        res.on("data", function () {});
+        res.on("end", finish);
+        res.on("error", finish);
+      }
+    );
+    req.on("error", finish);
+    req.write(payload);
+    req.end();
+  } catch (e) {
+    finish();
+  }
+}
+
+/** Promise wrapper for the ESM side (src/obstacle.mjs) so a failure path can await delivery. */
+function beaconAsync(opts) {
+  return new Promise(function (resolve) {
+    try { beacon(opts, resolve); } catch (e) { resolve(); }
+  });
+}
+
+module.exports = { parseActivityArgs: parseActivityArgs, beacon: beacon, beaconAsync: beaconAsync };

package/src/obstacle.mjs

@@ -0,0 +1,35 @@
+/**
+ * ESM front door to the obstacle beacon (src/obstacle-beacon.cjs). The post-login
+ * failure paths — `pnpm-missing`, `install-failed`, `clone-failed` — run on a
+ * supported Node where the bridge credential is already cached, so they resolve
+ * {url, token} from ~/.tot/credentials.json (the same source activityBridgeEnv +
+ * the heartbeat use) rather than argv. `node-too-old` does NOT come through here:
+ * it fires from the ES5 launcher pre-login, where creds may not exist yet.
+ *
+ * emitObstacle is awaited at the failure site so the packet is delivered before
+ * the process prints its `✗ … → next:` and exits — but it is fully swallowed, so
+ * telemetry can never disrupt or delay (past the beacon's own ~2s timeout) the
+ * error the developer actually needs to see.
+ */
+import beaconCore from "./obstacle-beacon.cjs";
+import { CLI_VERSION } from "./mcp.mjs";
+import { defaultCredentialsPath, readCredentials } from "./token-store.mjs";
+
+/**
+ * Best-effort obstacle beacon for a post-login failure. No-op (silent) when no
+ * bridge credential is cached — the developer signed in with a build that didn't
+ * carry the activity flags, or ran a bare `tot login`.
+ * @param {"pnpm-missing"|"install-failed"|"clone-failed"} kind
+ * @param {{ have?: string, need?: string, env?: NodeJS.ProcessEnv }} [opts]
+ */
+export async function emitObstacle(kind, { have, need, env = process.env } = {}) {
+  try {
+    const creds = readCredentials(defaultCredentialsPath(env));
+    const url = creds?.activityUrl;
+    const token = creds?.activityToken;
+    if (!url || !token) return;
+    await beaconCore.beaconAsync({ url, token, kind, have, need, cliVersion: CLI_VERSION });
+  } catch {
+    /* best-effort telemetry — never disrupts the error path */
+  }
+}