@indigoai-us/hq-cli 5.122.1 → 5.123.0

package/dist/lib/mesh/live/daemon/credentials.d.ts

@@ -49,6 +49,11 @@ export interface PresenceCompany {
     companyUid: string;
     presenceTopic: string;
 }
+export interface DroppedPresenceCompany {
+    companyUid: string;
+    /** Server-supplied cause when available; otherwise a deliberately neutral label. */
+    reason: string;
+}
 export interface Contract3Bundle {
     contractVersion: 3;
     credentials: IotCredentials;
@@ -58,7 +63,7 @@ export interface Contract3Bundle {
     actorUid: string;
     actorType: "human" | "agent";
     companies: PresenceCompany[];
-    droppedCompanies: string[];
+    droppedCompanies: DroppedPresenceCompany[];
     expiresAt: string;
 }
 export type CredentialsFetcher = () => Promise<Contract3Bundle>;

package/dist/lib/mesh/live/daemon/credentials.js

@@ -229,9 +229,25 @@ export function normalizeContract3Bundle(raw) {
     if (!expiresAt) {
         throw new Error("contract-3 vend missing expiresAt");
     }
-    const dropped = Array.isArray(r.droppedCompanies)
-        ? r.droppedCompanies.filter((x) => typeof x === "string")
-        : [];
+    const droppedCompanies = [];
+    for (const item of Array.isArray(r.droppedCompanies) ? r.droppedCompanies : []) {
+        if (typeof item === "string" && item.trim()) {
+            droppedCompanies.push({ companyUid: item, reason: "unknown" });
+            continue;
+        }
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const row = item;
+        const companyUid = typeof row.companyUid === "string" ? row.companyUid.trim() : "";
+        if (!companyUid)
+            continue;
+        droppedCompanies.push({
+            companyUid,
+            reason: typeof row.reason === "string" && row.reason.trim()
+                ? row.reason.trim()
+                : "not included",
+        });
+    }
     return {
         contractVersion: 3,
         credentials: {
@@ -246,7 +262,7 @@ export function normalizeContract3Bundle(raw) {
         actorUid,
         actorType,
         companies,
-        droppedCompanies: dropped,
+        droppedCompanies,
         expiresAt,
     };
 }

package/dist/lib/mesh/live/daemon/doctor.d.ts

@@ -32,6 +32,8 @@ export interface DaemonDoctorReport {
     actorKind: CognitoActorKind;
     /** Credential vend refused (disabled / unsupported / 403). */
     presenceRefusal?: DaemonStateFile["presenceRefusal"];
+    /** Companies the current presence credential did not include. */
+    presenceDroppedCompanies: NonNullable<DaemonStateFile["presenceDroppedCompanies"]>;
     /** Pending events awaiting a retry drain (POST /v1/mesh/events). */
     emitRetryDepth: number;
     /** Last successful direct-emit POST time. */

package/dist/lib/mesh/live/daemon/doctor.js

@@ -105,6 +105,10 @@ export function collectDaemonDoctor(deps = {}) {
             `(spool=${unattributedEvents.spool} held=${unattributedEvents.held} dead-letter=${unattributedEvents.deadLetter})`);
     }
     const presenceRefusal = state?.presenceRefusal ?? null;
+    const presenceDroppedCompanies = state?.presenceDroppedCompanies ?? [];
+    if (presenceDroppedCompanies.length > 0) {
+        unhealthyReasons.push(`presence unavailable for ${presenceDroppedCompanies.length} companies`);
+    }
     if (presenceRefusal) {
         unhealthyReasons.push(`presence credential refused (${presenceRefusal.code}); next retry ${presenceRefusal.nextRetryAt}`);
     }
@@ -132,6 +136,7 @@ export function collectDaemonDoctor(deps = {}) {
         tokenSource: auth.tokenSource,
         actorKind: auth.actorKind,
         presenceRefusal,
+        presenceDroppedCompanies,
         emitMode,
         subscribed,
         emitRetryDepth: emitRetry,
@@ -174,6 +179,13 @@ export function formatDaemonDoctor(report) {
     if (report.presenceRefusal) {
         lines.push(`presence refusal: ${report.presenceRefusal.code} (HTTP ${report.presenceRefusal.status}); next retry at ${report.presenceRefusal.nextRetryAt}`);
     }
+    if (report.presenceDroppedCompanies.length > 0) {
+        lines.push(`presence not published for ${report.presenceDroppedCompanies.length} companies: ` +
+            report.presenceDroppedCompanies
+                .map((company) => `${company.companyUid} (${company.reason})`)
+                .join(", ") +
+            `; presence credential holds ${report.companiesOnline.length} companies; these were not included`);
+    }
     if (report.unhealthy) {
         lines.push(`health: UNHEALTHY`);
         for (const reason of report.unhealthyReasons) {

package/dist/lib/mesh/live/daemon/install.d.ts

@@ -34,6 +34,13 @@ export interface InstallResult {
     message: string;
 }
 export declare function detectPlatform(platform?: NodeJS.Platform): DaemonInstallPlatform;
+/**
+ * HQ updates moved the CLI from toolchain/node/bin/hq to
+ * toolchain/npm-global/bin/hq. A LaunchAgent that still names the old path
+ * dies with MODULE_NOT_FOUND on the next restart. Prefer the live npm-global
+ * binary when both exist.
+ */
+export declare function preferStableHqBinary(entry: string): string;
 /** Resolve the hq binary the current shell uses (argv[1] or PATH). */
 export declare function resolveHqBinary(argv?: string[], env?: NodeJS.ProcessEnv): string;
 export declare function resolveNodeBinary(execPath?: string, env?: NodeJS.ProcessEnv): string;

package/dist/lib/mesh/live/daemon/install.js

@@ -21,11 +21,27 @@ export function detectPlatform(platform = process.platform) {
         return "linux";
     return "other";
 }
+/**
+ * HQ updates moved the CLI from toolchain/node/bin/hq to
+ * toolchain/npm-global/bin/hq. A LaunchAgent that still names the old path
+ * dies with MODULE_NOT_FOUND on the next restart. Prefer the live npm-global
+ * binary when both exist.
+ */
+export function preferStableHqBinary(entry) {
+    const stale = `${path.sep}toolchain${path.sep}node${path.sep}bin${path.sep}`;
+    const stable = `${path.sep}toolchain${path.sep}npm-global${path.sep}bin${path.sep}`;
+    if (!entry.includes(stale))
+        return entry;
+    const candidate = entry.replace(stale, stable);
+    if (candidate !== entry && fs.existsSync(candidate))
+        return path.resolve(candidate);
+    return entry;
+}
 /** Resolve the hq binary the current shell uses (argv[1] or PATH). */
 export function resolveHqBinary(argv = process.argv, env = process.env) {
     const entry = argv[1];
     if (entry && fs.existsSync(entry)) {
-        return path.resolve(entry);
+        return preferStableHqBinary(path.resolve(entry));
     }
     const pathEnv = env.PATH ?? "";
     for (const dir of pathEnv.split(path.delimiter)) {

package/dist/lib/mesh/live/daemon/run.js

@@ -162,7 +162,7 @@ export async function runMeshDaemon(deps = {}) {
         });
     let presence = null;
     if (deps.enablePresence !== false) {
-        const fetchCredentials = deps.fetchCredentials ??
+        const fetchCredentialsRaw = deps.fetchCredentials ??
             (async () => {
                 const t = await getToken();
                 return createContract3Fetcher({
@@ -171,6 +171,11 @@ export async function runMeshDaemon(deps = {}) {
                     env,
                 })();
             });
+        const fetchCredentials = async () => {
+            const bundle = await fetchCredentialsRaw();
+            patchDaemonState(dir, { presenceDroppedCompanies: bundle.droppedCompanies }, now);
+            return bundle;
+        };
         const presenceOpts = {
             fetchCredentials,
             mqttConnect: deps.mqttConnect,

package/dist/lib/mesh/live/daemon/state.d.ts

@@ -3,6 +3,7 @@
  */
 import type { MqttConnectionState } from "./presence.js";
 import type { FlushSummary } from "../flush.js";
+import type { DroppedPresenceCompany } from "./credentials.js";
 export interface PresenceRefusalState {
     code: string;
     status: number;
@@ -14,6 +15,8 @@ export interface DaemonStateFile {
     startedAt: string;
     mqttState: MqttConnectionState;
     companiesOnline: string[];
+    /** Companies omitted from the current presence credential bundle. */
+    presenceDroppedCompanies?: DroppedPresenceCompany[];
     actorUid?: string;
     lastFlushAt?: string;
     lastFlushResult?: FlushSummary & {

package/dist/utils/cli-telemetry.d.ts

@@ -1,4 +1,25 @@
 export declare const TELEMETRY_TIMEOUT_MS = 1200;
+/**
+ * Exact stderr line printed once on the first signed-in TTY run that is not
+ * `--json`. Wording matches the event body: CLI version + timestamp only.
+ */
+export declare const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+/**
+ * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
+ * CLI POST to `/v1/telemetry/events`. `HQ_TELEMETRY_TIMEOUT_MS` is unchanged.
+ */
+export declare function isCliTelemetryDisabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function telemetryDisclosureMarkerPath(): string;
+/**
+ * Print the one-line disclosure at most once per machine. Returns whether
+ * the notice has been shown (this run or a previous one). `--json` and
+ * non-TTY stdout skip the print and do not record the marker.
+ */
+export declare function maybeDiscloseCliTelemetry(stderr?: {
+    write: (chunk: string) => unknown;
+}, stdout?: {
+    isTTY?: boolean;
+}, argv?: readonly string[]): boolean;
 /**
  * Emit the authenticated CLI session signal using an already-cached token.
  * This deliberately never refreshes a session or opens a browser.

package/dist/utils/cli-telemetry.js

@@ -1,8 +1,80 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import { CLI_VERSION } from "../cli-version.js";
 import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
 import { vaultApiFetch } from "./vault-api.js";
 export const TELEMETRY_TIMEOUT_MS = 1_200;
+/**
+ * Exact stderr line printed once on the first signed-in TTY run that is not
+ * `--json`. Wording matches the event body: CLI version + timestamp only.
+ */
+export const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+const TELEMETRY_DISABLED_VALUES = new Set(["0", "false", "off"]);
+const DISCLOSURE_MARKER = "cli-telemetry-disclosed";
 let cliSessionStartedPromise;
+/**
+ * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
+ * CLI POST to `/v1/telemetry/events`. `HQ_TELEMETRY_TIMEOUT_MS` is unchanged.
+ */
+export function isCliTelemetryDisabled(env = process.env) {
+    const raw = env.HQ_TELEMETRY?.trim().toLowerCase();
+    if (!raw)
+        return false;
+    return TELEMETRY_DISABLED_VALUES.has(raw);
+}
+function hqConfigDir() {
+    const home = process.env.HOME?.trim() || os.homedir();
+    return path.join(home, ".hq");
+}
+export function telemetryDisclosureMarkerPath() {
+    return path.join(hqConfigDir(), DISCLOSURE_MARKER);
+}
+function wantsJsonOutput(argv = process.argv) {
+    return argv.includes("--json");
+}
+function canPrintDisclosure(stdout = process.stdout, argv = process.argv) {
+    return Boolean(stdout.isTTY) && !wantsJsonOutput(argv);
+}
+function hasShownDisclosure() {
+    try {
+        return fs.existsSync(telemetryDisclosureMarkerPath());
+    }
+    catch {
+        return false;
+    }
+}
+function recordDisclosureShown() {
+    try {
+        const dir = hqConfigDir();
+        // Do not create ~/.hq. Signed-in runs already have it (cached tokens).
+        if (!fs.existsSync(dir))
+            return;
+        fs.writeFileSync(telemetryDisclosureMarkerPath(), `${new Date().toISOString()}\n`);
+    }
+    catch {
+        // Marker write is best effort; a repeat print is better than crashing.
+    }
+}
+/**
+ * Print the one-line disclosure at most once per machine. Returns whether
+ * the notice has been shown (this run or a previous one). `--json` and
+ * non-TTY stdout skip the print and do not record the marker.
+ */
+export function maybeDiscloseCliTelemetry(stderr = process.stderr, stdout = process.stdout, argv = process.argv) {
+    if (hasShownDisclosure())
+        return true;
+    if (!canPrintDisclosure(stdout, argv))
+        return false;
+    try {
+        stderr.write(`${TELEMETRY_DISCLOSURE_LINE}\n`);
+    }
+    catch {
+        return false;
+    }
+    recordDisclosureShown();
+    return true;
+}
 /**
  * Emit the authenticated CLI session signal using an already-cached token.
  * This deliberately never refreshes a session or opens a browser.
@@ -13,12 +85,16 @@ export function emitCliSessionStarted(timeoutMs = TELEMETRY_TIMEOUT_MS) {
 }
 async function emitCachedCliSessionStarted(timeoutMs) {
     try {
+        if (isCliTelemetryDisabled())
+            return;
         const cached = loadCachedTokens();
         if (!cached || isExpiring(cached, 120))
             return;
         const token = isMachineIdentity() ? cached.idToken : cached.accessToken;
         if (!token)
             return;
+        const disclosed = maybeDiscloseCliTelemetry();
+        const consentBasis = disclosed ? "disclosed" : "no-consent";
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), timeoutMs);
         try {
@@ -33,7 +109,7 @@ async function emitCachedCliSessionStarted(timeoutMs) {
                             app: "hq-cli",
                             source: "cli",
                             occurredAt: new Date().toISOString(),
-                            consentBasis: "no-consent",
+                            consentBasis,
                             schemaVersion: 1,
                             properties: { version: CLI_VERSION },
                         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.122.1",
+  "version": "5.123.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -13,7 +13,8 @@
     "assets/scaffold",
     "assets/bot-workers",
     "assets/mesh-daemon",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "README.md"
   ],
   "scripts": {
     "build": "node scripts/generate-dsn.mjs && tsc && node scripts/generate-command-catalog.mjs --check && node scripts/copy-schemas.mjs && node scripts/chmod-bins.mjs",