@indigoai-us/hq-cli 5.107.0 → 5.108.0

package/dist/lib/flag-registry.js

@@ -0,0 +1,85 @@
+/**
+ * Process-wide, fail-open bridge to the HQ flag registry.
+ *
+ * Command gates read an in-memory snapshot synchronously. The first refresh is
+ * isolated in an unref'd worker because an unawaited Node fetch can otherwise
+ * keep a short-lived, offline CLI alive until the client's network deadline.
+ */
+import { Worker } from "node:worker_threads";
+import { isFlagSnapshot, resolveFlag, } from "@indigoai-us/hq-flags-client";
+/** Dedicated endpoint configuration; this is intentionally not HQ_PRO_API_URL. */
+export const FLAG_REGISTRY_ENDPOINT_ENV = "HQ_FLAGS_API_URL";
+let heldSnapshot = null;
+let processReader = null;
+function processSnapshotReader() {
+    return {
+        isEnabled(flagKey, lookup = {}) {
+            return resolveFlag({
+                flagKey,
+                env: process.env,
+                snapshot: heldSnapshot,
+                companyIdentifiers: [],
+                lookup,
+            }).value;
+        },
+    };
+}
+/**
+ * Begin one registry refresh without awaiting it or retaining the CLI process.
+ *
+ * The worker owns cached-token I/O, token use, and the potentially slow fetch.
+ * Its response is accepted only after the client has validated it as a flag
+ * snapshot. Consequently, every command path is an immediate in-memory read:
+ * a missing, unauthenticated, slow, or offline worker leaves `heldSnapshot`
+ * null and the caller's exact legacy fallback decides the gate.
+ */
+export function kickFlagRegistryReadiness(dependencies = {}) {
+    if (processReader)
+        return processReader;
+    const endpoint = (dependencies.endpoint ?? process.env[FLAG_REGISTRY_ENDPOINT_ENV] ?? "").trim();
+    if (!endpoint)
+        return null;
+    processReader = processSnapshotReader();
+    try {
+        const worker = (dependencies.createWorker ?? ((filename, options) => new Worker(filename, options)))(new URL("./flag-registry-worker.js", import.meta.url), { workerData: { endpoint } });
+        worker.on("message", (value) => {
+            if (isFlagSnapshot(value))
+                heldSnapshot = value;
+        });
+        // A failed background refresh must stay invisible to an offline CLI.
+        worker.on("error", () => { });
+        // Attach listeners first: Worker.on() re-refs the worker, so unref must be
+        // last for the parent process to remain free to exit immediately.
+        worker.unref();
+    }
+    catch {
+        // Construction can fail in restricted Node runtimes. The reader is still
+        // safe: it has no snapshot, so it resolves through the legacy vocabulary.
+    }
+    return processReader;
+}
+/**
+ * Evaluate a registry-backed gate without changing its outage default.
+ * `isEnabled` itself is synchronous and snapshot-only; any reader failure
+ * falls through to the exact legacy predicate owned by the caller.
+ */
+export function resolveFlagGate(reader, flagKey, lookup, legacyFallback) {
+    if (!reader)
+        return legacyFallback();
+    try {
+        return reader.isEnabled(flagKey, lookup);
+    }
+    catch {
+        return legacyFallback();
+    }
+}
+/** Resolve a process gate against the shared snapshot reader, when configured. */
+export function resolveProcessFlagGate(flagKey, lookup, legacyFallback) {
+    return resolveFlagGate(processReader, flagKey, lookup, legacyFallback);
+}
+/** Test-only reset for process-global readiness state. */
+export function _resetFlagRegistryForTests() {
+    heldSnapshot = null;
+    processReader = null;
+}
+//# sourceMappingURL=flag-registry.js.map

package/dist/lib/narrow-hint-banner.d.ts

@@ -22,6 +22,7 @@
  *   - the env var `HQ_SYNC_NARROW_HINT=off` is set,
  *   - the per-hqRoot CLI config (`<hqRoot>/.hq/config.json`) has
  *     `syncNarrowHint: 'off'`,
+ *   - the synced flag registry disables `sync.narrow-hint`,
  *   - or the same `{companyUid, level}` pair has already been shown this
  *     process (module-singleton dedupe; the runner imports the same module
  *     once per `hq` invocation so a single invocation prints at most one
@@ -46,6 +47,7 @@
  * `syncNarrowHintMinBytes` — see `resolveNarrowHintMinBytes`.
  */
 import * as fs from "node:fs";
+import { type FlagReader } from "./flag-registry.js";
 export type BannerLevel = "hint" | "warning" | "strict";
 /**
  * Default size gate for the narrow-mode nudge: 5 GiB. A local company folder
@@ -85,6 +87,8 @@ export interface ShouldShowBannerOpts {
     readFile?: (p: string) => string;
     /** Test seam: override `fs.existsSync`. */
     existsFile?: (p: string) => boolean;
+    /** Test seam: held registry snapshot reader. */
+    flagReader?: FlagReader;
 }
 /**
  * Decides whether a banner should be printed AT ALL — independent of
@@ -150,7 +154,14 @@ export declare function companyFolderExceedsThreshold(companyDir: string, thresh
  * `companyFolderExceedsThreshold`). A strict-level all-mode membership whose
  * folder is under the threshold is never refused.
  */
-export declare function isStrictRefusal(syncMode: BannerInput["syncMode"], level: BannerLevel): boolean;
+export declare function isStrictRefusal(syncMode: BannerInput["syncMode"], level: BannerLevel, flagReader?: FlagReader): boolean;
+/**
+ * Keep the rendered banner honest about the decision that this invocation
+ * actually made. Hint and warning remain local presentation choices. `strict`
+ * is reserved for a real refusal, so a registry opt-out of an old strict level
+ * degrades to the local warning presentation instead of claiming a block.
+ */
+export declare function resolveNarrowHintPresentationLevel(level: BannerLevel, strictRefusal: boolean): BannerLevel;
 /**
  * Emit a one-time-per-{company,level} banner. Writes to `stderr` by
  * default; tests inject a sink. Idempotent — repeated calls with the

package/dist/lib/narrow-hint-banner.js

@@ -22,6 +22,7 @@
  *   - the env var `HQ_SYNC_NARROW_HINT=off` is set,
  *   - the per-hqRoot CLI config (`<hqRoot>/.hq/config.json`) has
  *     `syncNarrowHint: 'off'`,
+ *   - the synced flag registry disables `sync.narrow-hint`,
  *   - or the same `{companyUid, level}` pair has already been shown this
  *     process (module-singleton dedupe; the runner imports the same module
  *     once per `hq` invocation so a single invocation prints at most one
@@ -48,6 +49,7 @@
 import chalk from "chalk";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { resolveFlagGate, resolveProcessFlagGate, } from "./flag-registry.js";
 /**
  * Default size gate for the narrow-mode nudge: 5 GiB. A local company folder
  * smaller than this is cheap to keep in full, so all-mode is left alone and no
@@ -99,7 +101,21 @@ export function shouldShowBanner(opts = {}) {
             }
         }
     }
-    return true;
+    const lookup = {
+        globalEnvVar: "HQ_SYNC_NARROW_HINT",
+        globalValueSemantics: {
+            onValues: [],
+            offValues: ["off"],
+            unrecognizedValue: true,
+            unsetValue: true,
+            // Deliberately no `trim`: the legacy parser only case-folds.
+            caseInsensitive: true,
+        },
+        fallback: true,
+    };
+    return opts.flagReader
+        ? resolveFlagGate(opts.flagReader, "sync.narrow-hint", lookup, () => true)
+        : resolveProcessFlagGate("sync.narrow-hint", lookup, () => true);
 }
 /**
  * Resolve the banner level from environment overrides. Defaults to
@@ -230,8 +246,34 @@ export function companyFolderExceedsThreshold(companyDir, thresholdBytes, deps =
  * `companyFolderExceedsThreshold`). A strict-level all-mode membership whose
  * folder is under the threshold is never refused.
  */
-export function isStrictRefusal(syncMode, level) {
-    return level === "strict" && syncMode === "all";
+export function isStrictRefusal(syncMode, level, flagReader) {
+    if (syncMode !== "all")
+        return false;
+    const lookup = {
+        globalEnvVar: "HQ_SYNC_NARROW_HINT_LEVEL",
+        globalValueSemantics: {
+            onValues: ["strict"],
+            offValues: ["hint", "warning"],
+            unrecognizedValue: false,
+            unsetValue: false,
+            caseInsensitive: true,
+        },
+        fallback: level === "strict",
+    };
+    return flagReader
+        ? resolveFlagGate(flagReader, "sync.narrow-hint-strict", lookup, () => level === "strict")
+        : resolveProcessFlagGate("sync.narrow-hint-strict", lookup, () => level === "strict");
+}
+/**
+ * Keep the rendered banner honest about the decision that this invocation
+ * actually made. Hint and warning remain local presentation choices. `strict`
+ * is reserved for a real refusal, so a registry opt-out of an old strict level
+ * degrades to the local warning presentation instead of claiming a block.
+ */
+export function resolveNarrowHintPresentationLevel(level, strictRefusal) {
+    if (strictRefusal)
+        return "strict";
+    return level === "strict" ? "warning" : level;
 }
 /**
  * Emit a one-time-per-{company,level} banner. Writes to `stderr` by

package/dist/lib/plan-limit-nag.d.ts

@@ -15,6 +15,7 @@
  * Additive only — never throws, never touches `process.exitCode`, never
  * writes to stdout. Env off-switch: `HQ_NO_PLAN_LIMIT_NAG=1`.
  */
+import { type FlagReader } from "./flag-registry.js";
 export declare const PLAN_LIMIT_UPGRADE_URL = "https://app.indigo-hq.com/billing/upgrade";
 export interface PlanLimitEntry {
     used: number;
@@ -39,6 +40,8 @@ export declare function emitPlanLimitNag(opts?: {
     write?: (s: string) => void;
     now?: () => Date;
     statePath?: string;
+    /** Test seam: held registry snapshot reader. */
+    flagReader?: FlagReader;
 }): void;
 /** Test-only helper — clears last-seen status and session dedupe flags. */
 export declare function _resetForTests(): void;

package/dist/lib/plan-limit-nag.js

@@ -19,6 +19,7 @@ import chalk from "chalk";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { resolveFlagGate, resolveProcessFlagGate, } from "./flag-registry.js";
 export const PLAN_LIMIT_UPGRADE_URL = "https://app.indigo-hq.com/billing/upgrade";
 const DAY_MS = 24 * 60 * 60 * 1000;
 /** Module-level last-seen cell — overwritten by each successful parse. */
@@ -33,6 +34,22 @@ function defaultStatePath() {
 function isOptedOut() {
     return process.env.HQ_NO_PLAN_LIMIT_NAG === "1";
 }
+function isPlanLimitNagEnabled(flagReader) {
+    const lookup = {
+        globalEnvVar: "HQ_NO_PLAN_LIMIT_NAG",
+        globalValueSemantics: {
+            onValues: [],
+            offValues: ["1"],
+            unrecognizedValue: true,
+            unsetValue: true,
+        },
+        fallback: true,
+    };
+    const legacyFallback = () => !isOptedOut();
+    return flagReader
+        ? resolveFlagGate(flagReader, "cli.plan-limit-nag", lookup, legacyFallback)
+        : resolveProcessFlagGate("cli.plan-limit-nag", lookup, legacyFallback);
+}
 /**
  * Defensively parse a single planLimits entry. Returns null if the shape is
  * not well-formed (non-numeric used/limit, non-boolean over, etc.).
@@ -164,7 +181,7 @@ function buildOverBox(overEntries) {
  */
 export function emitPlanLimitNag(opts = {}) {
     try {
-        if (isOptedOut())
+        if (!isPlanLimitNagEnabled(opts.flagReader))
             return;
         if (lastSeen === null)
             return;

package/dist/main.js

@@ -93,6 +93,7 @@ import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
 import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
+import { kickFlagRegistryReadiness } from "./lib/flag-registry.js";
 import { isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
 /** Hard upper bound for non-user-visible release-health finalization. */
@@ -290,14 +291,22 @@ registerDoctorCommand(program);
 // from `hq doctor` (hook guardrails). Does not start MQTT listen.
 registerMeshCommand(program);
 program.hook("preAction", async () => {
-    // Both are best-effort, bounded (1.2s), and fully swallowed: neither can
-    // delay past its bound or change the command's result or exit code.
+    // Both are best-effort and fully swallowed: neither can change the command's
+    // result or exit code. The 1.2s bound they carry is a TIMER, so it only
+    // preempts asynchronous work — synchronous work inside them runs to
+    // completion regardless, because the timer cannot be serviced while the
+    // event loop is blocked. Keep anything added here asynchronous, or
+    // separately cheap: this hook is on the path of EVERY hq command.
     await Promise.all([
         emitCliSessionStarted(),
         reportCliClientHealthInvocation(),
     ]);
 });
 export async function runCli() {
+    // Begin one registry refresh without awaiting it. Every command gate reads
+    // only the client's held snapshot and falls back locally, so an offline or
+    // slow registry cannot delay command parsing or alter a command failure.
+    void kickFlagRegistryReadiness();
     // Set when a self-update re-exec'd this command on a newer CLI: the child
     // already did the work, so this process only has to carry its exit status
     // out (after the finally block's telemetry, hence not process.exit here).

package/dist/run/hq-plugin.js

@@ -181,7 +181,7 @@ export async function prewarmHqSecrets(graph /* EnvGraph */, opts, state) {
             state.loadedSecretsByName.set(s.name, s.value);
             const cacheTtlMs = normalizeCacheTtlMs(s);
             if (cacheTtlMs > 0) {
-                writeCache(uid, s.name, s.value, cacheTtlMs);
+                writeCache(uid, s.name, s.value, cacheTtlMs, s.version);
             }
             else {
                 removeCacheEntry(uid, s.name);

package/dist/utils/client-health-contract.d.ts

@@ -75,6 +75,15 @@ export declare const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
 export declare const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100000;
 export declare const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100000;
 export declare const CLIENT_HEALTH_MAX_CHECKS = 16;
+/**
+ * Local-files-overview bounds (client-sync-health-control-plane hq-cli
+ * addition, US-016). These cap the closed set of bounded facts support sees
+ * about a user's local log/journal FILES — never a path, never file content,
+ * never a log line of text. See {@link ClientHealthLocalFilesOverview}.
+ */
+export declare const CLIENT_HEALTH_MAX_ERROR_LINE_COUNT = 50;
+export declare const CLIENT_HEALTH_MAX_FILE_SIZE_BYTES = 1073741824;
+export declare const CLIENT_HEALTH_MAX_FILE_AGE_SECONDS = 315360000;
 /**
  * The four client versions. All optional: a CLI-only installation has no
  * desktop/syncRunner version, and older clients may omit any of them.
@@ -85,6 +94,25 @@ export interface ClientHealthVersions {
     core?: string;
     syncRunner?: string;
 }
+/**
+ * Closed, bounded-fact summary of the user's local log/journal FILES —
+ * existence, size, age, and a capped count of recent error-marker lines.
+ * NEVER a path, NEVER file content, NEVER a line of log text: every field is
+ * a boolean or a bounded integer (see the `CLIENT_HEALTH_MAX_*` bounds).
+ * Attached to sync-outcome heartbeats (US-016) so support can see "does this
+ * installation even have a log, and does it look like it's erroring" without
+ * a customer screenshot.
+ */
+export interface ClientHealthLocalFilesOverview {
+    syncLogExists: boolean;
+    syncLogSizeBytes: number;
+    syncLogAgeSeconds: number;
+    journalExists: boolean;
+    journalSizeBytes: number;
+    journalAgeSeconds: number;
+    /** Capped at {@link CLIENT_HEALTH_MAX_ERROR_LINE_COUNT}. */
+    recentErrorLineCount: number;
+}
 export interface ClientHealthHeartbeat {
     contractVersion: number;
     /** Stable random installation identity — NOT a hardware fingerprint. */
@@ -106,6 +134,8 @@ export interface ClientHealthHeartbeat {
     conflictCount?: number;
     updaterState?: ClientHealthUpdaterState;
     failureReason?: ClientHealthFailureReason;
+    /** Absent on older clients / non-sync-outcome events. See {@link ClientHealthLocalFilesOverview}. */
+    localFilesOverview?: ClientHealthLocalFilesOverview;
 }
 export interface ClientHealthCheckResult {
     check: ClientHealthDiagnosticCheck;

package/dist/utils/client-health-contract.js

@@ -120,6 +120,15 @@ export const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
 export const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100_000;
 export const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100_000;
 export const CLIENT_HEALTH_MAX_CHECKS = 16;
+/**
+ * Local-files-overview bounds (client-sync-health-control-plane hq-cli
+ * addition, US-016). These cap the closed set of bounded facts support sees
+ * about a user's local log/journal FILES — never a path, never file content,
+ * never a log line of text. See {@link ClientHealthLocalFilesOverview}.
+ */
+export const CLIENT_HEALTH_MAX_ERROR_LINE_COUNT = 50;
+export const CLIENT_HEALTH_MAX_FILE_SIZE_BYTES = 1_073_741_824; // 1 GiB
+export const CLIENT_HEALTH_MAX_FILE_AGE_SECONDS = 315_360_000; // 10 years
 export class ClientHealthContractError extends Error {
     code;
     field;
@@ -194,6 +203,13 @@ function assertBoundedInt(field, value, max) {
         throw new ClientHealthContractError("OUT_OF_BOUNDS", field);
     return value;
 }
+function assertBoolean(field, value) {
+    if (value === undefined || value === null)
+        throw new ClientHealthContractError("MISSING_FIELD", field);
+    if (typeof value !== "boolean")
+        throw new ClientHealthContractError("INVALID_TYPE", field, "expected boolean");
+    return value;
+}
 function asRecord(field, value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new ClientHealthContractError("INVALID_TYPE", field, "expected object");
@@ -246,8 +262,29 @@ export function parseClientHealthHeartbeat(input) {
     if (raw.failureReason !== undefined) {
         heartbeat.failureReason = assertEnum("failureReason", raw.failureReason, CLIENT_HEALTH_FAILURE_REASONS);
     }
+    if (raw.localFilesOverview !== undefined) {
+        heartbeat.localFilesOverview = parseClientHealthLocalFilesOverview("localFilesOverview", raw.localFilesOverview);
+    }
     return heartbeat;
 }
+/**
+ * Parse + validate a {@link ClientHealthLocalFilesOverview}. Every field is a
+ * boolean or a bounded integer — there is no string field to be path- or
+ * content-shaped, so this fails closed purely on type/bounds, same as any
+ * other bounded-fact block in this contract.
+ */
+function parseClientHealthLocalFilesOverview(field, input) {
+    const raw = asRecord(field, input);
+    return {
+        syncLogExists: assertBoolean(`${field}.syncLogExists`, raw.syncLogExists),
+        syncLogSizeBytes: assertBoundedInt(`${field}.syncLogSizeBytes`, raw.syncLogSizeBytes, CLIENT_HEALTH_MAX_FILE_SIZE_BYTES),
+        syncLogAgeSeconds: assertBoundedInt(`${field}.syncLogAgeSeconds`, raw.syncLogAgeSeconds, CLIENT_HEALTH_MAX_FILE_AGE_SECONDS),
+        journalExists: assertBoolean(`${field}.journalExists`, raw.journalExists),
+        journalSizeBytes: assertBoundedInt(`${field}.journalSizeBytes`, raw.journalSizeBytes, CLIENT_HEALTH_MAX_FILE_SIZE_BYTES),
+        journalAgeSeconds: assertBoundedInt(`${field}.journalAgeSeconds`, raw.journalAgeSeconds, CLIENT_HEALTH_MAX_FILE_AGE_SECONDS),
+        recentErrorLineCount: assertBoundedInt(`${field}.recentErrorLineCount`, raw.recentErrorLineCount, CLIENT_HEALTH_MAX_ERROR_LINE_COUNT),
+    };
+}
 /** Parse + validate one diagnostic/repair command receipt. Unknown kinds fail closed. */
 export function parseClientHealthCommandReceipt(input) {
     const raw = asRecord("receipt", input);

package/dist/utils/client-health.d.ts

@@ -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
@@ -29,10 +32,42 @@
  */
 import { isExpiring, loadCachedTokens } from "./cognito-session.js";
 import { type VersionInfo } from "./feedback-versions.js";
-import { type ClientHealthArch, type ClientHealthHeartbeat, type ClientHealthPlatform } from "./client-health-contract.js";
+import { type ClientHealthArch, type ClientHealthHeartbeat, type ClientHealthLocalFilesOverview, type ClientHealthPlatform } from "./client-health-contract.js";
 /** Same bound as CLI telemetry: a heartbeat may never stall a command. */
 export declare const CLIENT_HEALTH_TIMEOUT_MS = 1200;
 export declare 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 declare const CLIENT_HEALTH_OBSERVE_LOCK_FILE = "cli-client-health.observe.lock";
+/** Cached journal observation — see {@link JournalObservation}. */
+export declare 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 declare const JOURNAL_OBSERVATION_TTL_MS: number;
+/** An observation lock older than this is treated as abandoned. */
+export declare const JOURNAL_OBSERVATION_LOCK_STALE_MS: number;
 export interface CliClientHealthState {
     /** Stable random installation identity — regenerated only if invalid. */
     installationId: string;
@@ -43,6 +78,22 @@ export interface CliClientHealthState {
     lastSyncAttemptAt?: string;
     lastSyncSuccessAt?: string;
 }
+/**
+ * Cached result of one `listJournals()` read.
+ *
+ * Deliberately its OWN file rather than a field on {@link CliClientHealthState}:
+ * older CLI versions rewrite the state file and drop fields they do not know,
+ * so an observation stored there would be erased by any co-installed older
+ * `hq` — permanently on a machine that runs a mixed fleet, and throughout any
+ * staged rollout. That was observed in practice on the controller this change
+ * was measured on.
+ */
+export interface JournalObservation {
+    /** Engine-recorded journal `lastSync` at the time of the read. */
+    lastSyncAt?: string;
+    /** When the read was taken, ISO-8601. */
+    observedAt?: string;
+}
 export declare function newInstallationId(): string;
 /**
  * Load (or initialize) the persisted installation state. Any read/parse
@@ -50,6 +101,10 @@ export declare function newInstallationId(): string;
  * never break a CLI command.
  */
 export declare function loadClientHealthState(stateDir: string): CliClientHealthState;
+/** Load the cached journal observation; any problem reads as "none". */
+export declare function loadJournalObservation(stateDir: string): JournalObservation;
+/** Best-effort persist — a read-only disk must never fail a command. */
+export declare function persistJournalObservation(stateDir: string, observation: JournalObservation): void;
 /** Best-effort persist — a read-only disk must never fail a command. */
 export declare function persistClientHealthState(stateDir: string, state: CliClientHealthState): void;
 /**
@@ -69,6 +124,16 @@ interface JournalLike {
  * contract ISO-UTC. Null when nothing has ever synced.
  */
 export declare function latestJournalSyncTime(journals: readonly JournalLike[]): string | null;
+/**
+ * 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 declare function shouldObserveJournals(kind: ClientHealthEventKind, observation: JournalObservation, now: Date, ttlMs: number): boolean;
 export type ClientHealthEventKind = "invocation" | "sync_attempt" | "sync_success" | "sync_failure";
 export interface BuildCliHeartbeatInput {
     kind: ClientHealthEventKind;
@@ -80,6 +145,12 @@ export interface BuildCliHeartbeatInput {
     now: Date;
     platform?: ClientHealthPlatform | null;
     arch?: ClientHealthArch | null;
+    /**
+     * Bounded local log/journal file facts (US-016). Only ever attached for
+     * `sync_success` / `sync_failure` kinds — support asked for this on the
+     * sync OUTCOME events, not on every invocation heartbeat.
+     */
+    localFilesOverview?: ClientHealthLocalFilesOverview | null;
 }
 /**
  * Build one contract-valid CLI heartbeat, or null when this environment
@@ -98,6 +169,12 @@ export interface ClientHealthDeps {
     journals?: () => readonly JournalLike[];
     post?: HeartbeatPoster;
     timeoutMs?: number;
+    /** US-016: overridable for tests; defaults to {@link collectLocalFilesOverview}. */
+    localFilesOverview?: () => ClientHealthLocalFilesOverview;
+    /** Override for {@link JOURNAL_OBSERVATION_TTL_MS}. */
+    journalObservationTtlMs?: number;
+    /** Override for {@link JOURNAL_OBSERVATION_LOCK_STALE_MS}. */
+    journalObservationLockStaleMs?: number;
 }
 /**
  * Apply one health event: update local installation state, then — only when a