@indigoai-us/hq-cli 5.107.1 → 5.108.0

package/dist/utils/client-health.js

@@ -20,7 +20,10 @@
  *     caller-supplied identity outright).
  *   - Sync state is read through the engine's `listJournals()` — the ONLY
  *     correct enumeration of per-scope journals (single-path reconstruction
- *     regressed before: feedback_9fbf1f82 / feedback_46288b7b).
+ *     regressed before: feedback_9fbf1f82 / feedback_46288b7b). It stays the
+ *     only enumeration, but it is now rate-limited rather than run on every
+ *     command: it is expensive and synchronous, so it could not be bounded on
+ *     the command path (see {@link JOURNAL_OBSERVATION_TTL_MS}).
  *
  * Local state (installation identity + monotonic sequence + sync outcome
  * counters) lives at `{stateDir}/cli-client-health.json` next to the sync
@@ -35,9 +38,42 @@ import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-sess
 import { vaultApiFetch } from "./vault-api.js";
 import { collectVersions } from "./feedback-versions.js";
 import { CLIENT_HEALTH_CONTRACT_VERSION, parseClientHealthHeartbeat, } from "./client-health-contract.js";
+import { collectLocalFilesOverview } from "./local-files-overview.js";
 /** Same bound as CLI telemetry: a heartbeat may never stall a command. */
 export const CLIENT_HEALTH_TIMEOUT_MS = 1_200;
 export const CLIENT_HEALTH_STATE_FILE = "cli-client-health.json";
+/**
+ * Single-flight marker for the journal observation below. Held only for the
+ * duration of one `listJournals()` call.
+ */
+export const CLIENT_HEALTH_OBSERVE_LOCK_FILE = "cli-client-health.observe.lock";
+/** Cached journal observation — see {@link JournalObservation}. */
+export const CLIENT_HEALTH_OBSERVATION_FILE = "cli-client-health.observation.json";
+/**
+ * How long one journal `lastSync` observation stays usable before an
+ * `invocation` heartbeat re-reads it from the engine.
+ *
+ * `listJournals()` is the correct enumeration, but it is NOT cheap: it returns
+ * fully materialized journals, so the engine opens every area of the local
+ * sync state store, replays each area's write-ahead log, and deep-clones the
+ * whole aggregate file table (`AreaLedger.read` → `readCached` →
+ * `primeAggregateCache` → `materializeArea`). On a controller with a large,
+ * un-compacted store that measured 21 s of CPU per `hq` invocation — for the
+ * ONE field this module actually consumes, `journal.lastSync`.
+ *
+ * Worse, that work is fully SYNCHRONOUS, so the `settleWithin` bound below
+ * cannot preempt it: its timer cannot be serviced until the work it is meant
+ * to bound has already finished. Every `hq` command awaits the preAction hook,
+ * so an expensive store turned a best-effort telemetry heartbeat into a
+ * multi-second stall on every single command, secrets fetches included.
+ *
+ * The heartbeat only needs a coarse "when did this installation last sync"
+ * signal, so one observation is reused for this window instead. Sync commands
+ * always re-observe — they have opened the store anyway, so it costs nothing.
+ */
+export const JOURNAL_OBSERVATION_TTL_MS = 15 * 60_000;
+/** An observation lock older than this is treated as abandoned. */
+export const JOURNAL_OBSERVATION_LOCK_STALE_MS = 5 * 60_000;
 /**
  * Pre-filter mirror of the contract's SemVer shape (the contract keeps its
  * validators private). A version failing this is DROPPED individually so one
@@ -107,6 +143,38 @@ export function loadClientHealthState(stateDir) {
     }
     return state;
 }
+function observationFilePath(stateDir) {
+    return path.join(stateDir, CLIENT_HEALTH_OBSERVATION_FILE);
+}
+/** Load the cached journal observation; any problem reads as "none". */
+export function loadJournalObservation(stateDir) {
+    let raw = {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(observationFilePath(stateDir), "utf-8"));
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            raw = parsed;
+        }
+    }
+    catch {
+        // Missing or corrupt: no usable observation.
+    }
+    const observation = {};
+    if (typeof raw.lastSyncAt === "string")
+        observation.lastSyncAt = raw.lastSyncAt;
+    if (typeof raw.observedAt === "string")
+        observation.observedAt = raw.observedAt;
+    return observation;
+}
+/** Best-effort persist — a read-only disk must never fail a command. */
+export function persistJournalObservation(stateDir, observation) {
+    try {
+        fs.mkdirSync(stateDir, { recursive: true });
+        fs.writeFileSync(observationFilePath(stateDir), `${JSON.stringify(observation, null, 2)}\n`, "utf-8");
+    }
+    catch {
+        // Best effort only.
+    }
+}
 /** Best-effort persist — a read-only disk must never fail a command. */
 export function persistClientHealthState(stateDir, state) {
     try {
@@ -165,6 +233,87 @@ export function latestJournalSyncTime(journals) {
     }
     return latest === null ? null : new Date(latest).toISOString();
 }
+/**
+ * True when this event kind must pay for a fresh `listJournals()` read.
+ *
+ * Sync events always do: `hq sync` has already opened the state store, so the
+ * marginal cost is nil and the resulting heartbeat is the one that most needs
+ * an exact timestamp. Plain invocations reuse the last observation until it
+ * ages past `ttlMs`, which is what keeps the enumeration off the hot path of
+ * every unrelated command.
+ */
+export function shouldObserveJournals(kind, observation, now, ttlMs) {
+    if (kind !== "invocation")
+        return true;
+    const observed = typeof observation.observedAt === "string"
+        ? Date.parse(observation.observedAt)
+        : NaN;
+    if (!Number.isFinite(observed))
+        return true;
+    const age = now.getTime() - observed;
+    // A stamp from the future (clock step, shared home directory) is not
+    // evidence of a recent read — re-observe rather than trust it forever.
+    return age < 0 || age >= ttlMs;
+}
+/**
+ * Best-effort exclusive claim on the journal observation, returning a release
+ * function, or null when another process already holds it.
+ *
+ * Fleet workers spawn many `hq` processes at once. Without this, a burst that
+ * all see the same expired observation would all pay the full enumeration
+ * simultaneously — precisely the CPU storm this change exists to remove. Any
+ * failure here resolves toward "do not observe", which is the cheap and safe
+ * direction for best-effort telemetry.
+ */
+function readObservationLockOwner(lockPath) {
+    try {
+        return fs.readFileSync(lockPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+function acquireJournalObservationLock(stateDir, nowMs, staleMs) {
+    const lockPath = path.join(stateDir, CLIENT_HEALTH_OBSERVE_LOCK_FILE);
+    // Reclaim an abandoned lock — but only the EXACT one just inspected. The
+    // owner token is re-read immediately before the unlink and the removal is
+    // dropped if it changed. Unfenced, two processes arriving together on the
+    // same aged lock could both decide to remove it, the second deleting the
+    // first's freshly created lock, and both would then run the enumeration this
+    // lock exists to serialise.
+    const abandoned = readObservationLockOwner(lockPath);
+    if (abandoned !== null) {
+        try {
+            const age = nowMs - fs.statSync(lockPath).mtimeMs;
+            const stale = age >= staleMs || age < -staleMs;
+            if (stale && readObservationLockOwner(lockPath) === abandoned) {
+                fs.rmSync(lockPath, { force: true });
+            }
+        }
+        catch {
+            // Vanished or unreadable mid-inspection: the exclusive create below is
+            // the real single-flight, so losing this race is safe.
+        }
+    }
+    const owner = `${process.pid}:${randomBytes(8).toString("hex")}`;
+    try {
+        fs.writeFileSync(lockPath, owner, { flag: "wx" });
+    }
+    catch {
+        return null;
+    }
+    return () => {
+        try {
+            // Never remove a lock this process no longer owns.
+            if (readObservationLockOwner(lockPath) === owner) {
+                fs.rmSync(lockPath, { force: true });
+            }
+        }
+        catch {
+            // Best effort; a leaked lock ages out via `staleMs`.
+        }
+    };
+}
 /**
  * Build one contract-valid CLI heartbeat, or null when this environment
  * cannot be represented in the closed contract enums (unknown platform/arch)
@@ -217,6 +366,10 @@ export function buildCliHeartbeat(input) {
     if (lastSyncSuccessAt !== null) {
         heartbeat.lastSyncSuccessAt = lastSyncSuccessAt;
     }
+    if ((input.kind === "sync_success" || input.kind === "sync_failure") &&
+        input.localFilesOverview) {
+        heartbeat.localFilesOverview = input.localFilesOverview;
+    }
     return heartbeat;
 }
 function latestIso(a, b) {
@@ -310,12 +463,60 @@ async function contributeClientHealthUnbounded(kind, deps) {
         const sequence = nextHeartbeatSequence(state, now.getTime());
         state.sequence = sequence;
         persistClientHealthState(stateDir, state);
-        let journalLastSyncAt = null;
-        try {
-            journalLastSyncAt = latestJournalSyncTime((deps.journals ?? listJournals)());
+        // Journal enumeration is the single most expensive thing this module can
+        // do — see JOURNAL_OBSERVATION_TTL_MS. Reuse the last observation unless
+        // this event kind requires a fresh one and no other process is taking it.
+        const observation = loadJournalObservation(stateDir);
+        let journalLastSyncAt = observation.lastSyncAt ?? null;
+        const ttlMs = deps.journalObservationTtlMs ?? JOURNAL_OBSERVATION_TTL_MS;
+        if (shouldObserveJournals(kind, observation, now, ttlMs)) {
+            const release = acquireJournalObservationLock(stateDir, now.getTime(), deps.journalObservationLockStaleMs ?? JOURNAL_OBSERVATION_LOCK_STALE_MS);
+            if (!release) {
+                // Another process is producing the authoritative observation right now.
+                // Emitting an invocation heartbeat here would carry a value already
+                // known to be stale under a HIGHER wall-clock sequence than the
+                // in-flight accurate one, and the server's monotonic gate would then
+                // discard the good heartbeat. Withhold instead — invocation heartbeats
+                // are best effort, and the next one reports the refreshed value. Sync
+                // OUTCOME heartbeats are never withheld; they carry a result.
+                if (kind === "invocation")
+                    return;
+            }
+            else {
+                try {
+                    const observed = latestJournalSyncTime((deps.journals ?? listJournals)());
+                    if (observed !== null) {
+                        journalLastSyncAt = observed;
+                        observation.lastSyncAt = observed;
+                    }
+                    // Publish freshness only once the value behind it is ready. Stamping
+                    // first would let a process that arrives mid-read treat the previous
+                    // (or absent) value as current.
+                    //
+                    // A process that dies inside the engine therefore leaves no stamp —
+                    // it leaves its LOCK, which holds contenders off until
+                    // `journalObservationLockStaleMs`. That is what bounds retries of an
+                    // enumeration already known to be pathological on this machine.
+                    observation.observedAt = now.toISOString();
+                    persistJournalObservation(stateDir, observation);
+                }
+                catch {
+                    // Journal enumeration is best effort.
+                }
+                finally {
+                    release();
+                }
+            }
         }
-        catch {
-            // Journal enumeration is best effort.
+        let localFilesOverview = null;
+        if (kind === "sync_success" || kind === "sync_failure") {
+            try {
+                localFilesOverview = (deps.localFilesOverview ?? collectLocalFilesOverview)();
+            }
+            catch {
+                // Collection is best effort — never blocks or drops the heartbeat.
+                localFilesOverview = null;
+            }
         }
         const heartbeat = buildCliHeartbeat({
             kind,
@@ -324,6 +525,7 @@ async function contributeClientHealthUnbounded(kind, deps) {
             versions: (deps.versions ?? collectVersions)(),
             journalLastSyncAt,
             now,
+            localFilesOverview,
         });
         if (!heartbeat)
             return;

package/dist/utils/local-files-overview.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Local log/journal FILE METADATA overview (client-sync-health-control-plane
+ * US-016, hq-cli only).
+ *
+ * Support asked for a bounded overview of a user's local log/journal files
+ * so they can debug sync issues without a screenshot. This module collects
+ * ONLY closed-enum booleans and bounded integers — existence, size, age, and
+ * a capped count of recent error-marker lines — and NEVER a path, NEVER file
+ * content, NEVER a line of log text. The returned
+ * {@link ClientHealthLocalFilesOverview} is the entire surface that can ever
+ * cross the wire; there is no string field on it for anything sensitive to
+ * hide inside.
+ *
+ * Sources (metadata only, via `fs.stat` — full content is read only for the
+ * bounded error-line count below, and even then only a capped tail window,
+ * and even then only an integer count is ever returned):
+ *   - the hq-sync desktop app's log file, `~/.hq/logs/hq-sync.log`
+ *   - the CLI's own per-company sync journals, enumerated via `listJournals()`
+ *     (never a hand-reconstructed path — see client-health.ts's note on the
+ *     single-path-reconstruction regression this mirrors).
+ *
+ * Every fs operation is independently best-effort: a missing file, a
+ * permission-denied stat, or a file that disappears mid-read (TOCTOU race)
+ * degrades that one field to its "absent" value and never throws. Collection
+ * must never break a heartbeat, let alone a CLI command.
+ */
+import { type ClientHealthLocalFilesOverview } from "./client-health-contract.js";
+/**
+ * Only the last N bytes of the sync log are read for error-line counting —
+ * this bounds memory/CPU regardless of how large the on-disk log has grown.
+ * Metadata (size/age) still reflects the FULL file via `fs.stat`.
+ */
+export declare const LOCAL_FILES_OVERVIEW_TAIL_READ_BYTES: number;
+/**
+ * Count lines that look like an error marker in the last
+ * {@link LOCAL_FILES_OVERVIEW_TAIL_READ_BYTES} of `filePath`, capped at
+ * {@link CLIENT_HEALTH_MAX_ERROR_LINE_COUNT}. Returns 0 on any read failure
+ * (missing file, permission denied, race). Only the resulting integer is
+ * ever returned — the read buffer never leaves this function.
+ */
+export declare function countRecentErrorLines(filePath: string, maxBytes?: number, cap?: number): number;
+export interface CollectLocalFilesOverviewDeps {
+    now?: () => Date;
+    homeDir?: () => string;
+    journals?: () => readonly {
+        path: string;
+    }[];
+    countErrorLines?: (filePath: string) => number;
+}
+/**
+ * Collect the bounded local-files overview for the current installation.
+ * NEVER throws. When per-company journals exist, `journalExists` is true if
+ * ANY journal file is present, sizes are summed (capped), and the age
+ * reflects the FRESHEST journal (smallest age) — the signal support cares
+ * about is "is this installation still writing journals at all."
+ */
+export declare function collectLocalFilesOverview(deps?: CollectLocalFilesOverviewDeps): ClientHealthLocalFilesOverview;
+//# sourceMappingURL=local-files-overview.d.ts.map

package/dist/utils/local-files-overview.js

@@ -0,0 +1,170 @@
+/**
+ * Local log/journal FILE METADATA overview (client-sync-health-control-plane
+ * US-016, hq-cli only).
+ *
+ * Support asked for a bounded overview of a user's local log/journal files
+ * so they can debug sync issues without a screenshot. This module collects
+ * ONLY closed-enum booleans and bounded integers — existence, size, age, and
+ * a capped count of recent error-marker lines — and NEVER a path, NEVER file
+ * content, NEVER a line of log text. The returned
+ * {@link ClientHealthLocalFilesOverview} is the entire surface that can ever
+ * cross the wire; there is no string field on it for anything sensitive to
+ * hide inside.
+ *
+ * Sources (metadata only, via `fs.stat` — full content is read only for the
+ * bounded error-line count below, and even then only a capped tail window,
+ * and even then only an integer count is ever returned):
+ *   - the hq-sync desktop app's log file, `~/.hq/logs/hq-sync.log`
+ *   - the CLI's own per-company sync journals, enumerated via `listJournals()`
+ *     (never a hand-reconstructed path — see client-health.ts's note on the
+ *     single-path-reconstruction regression this mirrors).
+ *
+ * Every fs operation is independently best-effort: a missing file, a
+ * permission-denied stat, or a file that disappears mid-read (TOCTOU race)
+ * degrades that one field to its "absent" value and never throws. Collection
+ * must never break a heartbeat, let alone a CLI command.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { listJournals } from "@indigoai-us/hq-cloud";
+import { CLIENT_HEALTH_MAX_ERROR_LINE_COUNT, CLIENT_HEALTH_MAX_FILE_AGE_SECONDS, CLIENT_HEALTH_MAX_FILE_SIZE_BYTES, } from "./client-health-contract.js";
+/**
+ * Only the last N bytes of the sync log are read for error-line counting —
+ * this bounds memory/CPU regardless of how large the on-disk log has grown.
+ * Metadata (size/age) still reflects the FULL file via `fs.stat`.
+ */
+export const LOCAL_FILES_OVERVIEW_TAIL_READ_BYTES = 2 * 1024 * 1024; // 2 MiB
+/** Case-insensitive marker matched against each line (or JSON-lines `level`). */
+const ERROR_MARKER = /error/i;
+const JSON_LEVEL_ERROR = /"level"\s*:\s*"error"/i;
+const ABSENT = { exists: false, sizeBytes: 0, ageSeconds: 0 };
+function clampInt(value, max) {
+    if (!Number.isFinite(value) || value < 0)
+        return 0;
+    return Math.min(Math.floor(value), max);
+}
+/**
+ * Best-effort `fs.lstat`. Never throws: missing/denied/raced degrades to
+ * absent. Uses `lstat` (not `stat`) and rejects symlinks outright — a
+ * symlinked log/journal path could otherwise point anywhere on disk, and
+ * this module has no business following it (defense in depth: even though
+ * only bounded numbers ever leave this module, nothing here should read an
+ * arbitrary attacker- or misconfiguration-controlled file at all).
+ */
+function statFacts(filePath, nowMs) {
+    try {
+        const stat = fs.lstatSync(filePath);
+        if (!stat.isFile())
+            return ABSENT;
+        const ageSeconds = (nowMs - stat.mtimeMs) / 1000;
+        return {
+            exists: true,
+            sizeBytes: clampInt(stat.size, CLIENT_HEALTH_MAX_FILE_SIZE_BYTES),
+            ageSeconds: clampInt(ageSeconds, CLIENT_HEALTH_MAX_FILE_AGE_SECONDS),
+        };
+    }
+    catch {
+        return ABSENT;
+    }
+}
+/** True only when `filePath` exists, is not a symlink, and is a regular file. */
+function isSafeRegularFile(filePath) {
+    try {
+        return fs.lstatSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Count lines that look like an error marker in the last
+ * {@link LOCAL_FILES_OVERVIEW_TAIL_READ_BYTES} of `filePath`, capped at
+ * {@link CLIENT_HEALTH_MAX_ERROR_LINE_COUNT}. Returns 0 on any read failure
+ * (missing file, permission denied, race). Only the resulting integer is
+ * ever returned — the read buffer never leaves this function.
+ */
+export function countRecentErrorLines(filePath, maxBytes = LOCAL_FILES_OVERVIEW_TAIL_READ_BYTES, cap = CLIENT_HEALTH_MAX_ERROR_LINE_COUNT) {
+    if (!isSafeRegularFile(filePath))
+        return 0;
+    let fd;
+    try {
+        fd = fs.openSync(filePath, "r");
+        const size = fs.fstatSync(fd).size;
+        const readSize = Math.min(size, maxBytes);
+        if (readSize <= 0)
+            return 0;
+        const start = size - readSize;
+        const buffer = Buffer.alloc(readSize);
+        fs.readSync(fd, buffer, 0, readSize, start);
+        const text = buffer.toString("utf-8");
+        let count = 0;
+        for (const line of text.split("\n")) {
+            if (count >= cap)
+                break;
+            if (ERROR_MARKER.test(line) || JSON_LEVEL_ERROR.test(line))
+                count += 1;
+        }
+        return Math.min(count, cap);
+    }
+    catch {
+        return 0;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // Best effort only.
+            }
+        }
+    }
+}
+/**
+ * Collect the bounded local-files overview for the current installation.
+ * NEVER throws. When per-company journals exist, `journalExists` is true if
+ * ANY journal file is present, sizes are summed (capped), and the age
+ * reflects the FRESHEST journal (smallest age) — the signal support cares
+ * about is "is this installation still writing journals at all."
+ */
+export function collectLocalFilesOverview(deps = {}) {
+    const now = (deps.now ?? (() => new Date()))();
+    const nowMs = now.getTime();
+    const homeDir = (deps.homeDir ?? os.homedir)();
+    const countErrorLines = deps.countErrorLines ?? countRecentErrorLines;
+    const syncLogPath = path.join(homeDir, ".hq", "logs", "hq-sync.log");
+    const syncLogFacts = statFacts(syncLogPath, nowMs);
+    const recentErrorLineCount = syncLogFacts.exists ? countErrorLines(syncLogPath) : 0;
+    let journalEntries;
+    try {
+        journalEntries = (deps.journals ?? listJournals)();
+    }
+    catch {
+        // Journal enumeration is best effort — mirrors client-health.ts.
+        journalEntries = [];
+    }
+    let journalExists = false;
+    let journalSizeBytesTotal = 0;
+    let journalAgeSecondsMin;
+    for (const entry of journalEntries) {
+        const facts = statFacts(entry.path, nowMs);
+        if (!facts.exists)
+            continue;
+        journalExists = true;
+        journalSizeBytesTotal += facts.sizeBytes;
+        if (journalAgeSecondsMin === undefined || facts.ageSeconds < journalAgeSecondsMin) {
+            journalAgeSecondsMin = facts.ageSeconds;
+        }
+    }
+    return {
+        syncLogExists: syncLogFacts.exists,
+        syncLogSizeBytes: syncLogFacts.sizeBytes,
+        syncLogAgeSeconds: syncLogFacts.ageSeconds,
+        journalExists,
+        journalSizeBytes: clampInt(journalSizeBytesTotal, CLIENT_HEALTH_MAX_FILE_SIZE_BYTES),
+        journalAgeSeconds: clampInt(journalAgeSecondsMin ?? 0, CLIENT_HEALTH_MAX_FILE_AGE_SECONDS),
+        recentErrorLineCount: clampInt(recentErrorLineCount, CLIENT_HEALTH_MAX_ERROR_LINE_COUNT),
+    };
+}
+//# sourceMappingURL=local-files-overview.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.107.1",
+  "version": "5.108.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -31,6 +31,7 @@
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
     "@indigoai-us/hq-cloud": "~6.16.6",
+    "@indigoai-us/hq-flags-client": "^0.1.2",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",