@indigoai-us/hq-cli 5.212.0 → 5.214.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [5.214.0] — 2026-09-26
+
+### Added
+
+- `hq doctor` now checks the last hour of the sync runner log for stuck
+  realtime lag, cloud permission refusals, runner restart loops, device-limit
+  backoff, and repeated conflicts. Client health reports send these to Sentry
+  as reason codes and counts only.
+
+### Fixed
+
+- The desktop app's first sync push now uploads files inside private folders.
+  The credentials the app hands to `hq sync push --creds-from-stdin` cannot
+  write there directly, so the push also passes the vault config to hq-cloud
+  6.18.5, which sends those files through presigned uploads.
+
+## [5.213.0] — 2026-09-26
+
+### Fixed
+
+- `hq lanes accounts set-home` and `login` return
+  `company_selection_failed` for company-selection errors without a stack
+  trace. Other resolver failures remain `internal` and include a stack trace.
+
 ## [5.212.0] — 2026-09-26
 
 ### Changed

package/dist/commands/cloud.d.ts

@@ -13,7 +13,7 @@
  *   hq sync status            — show local journal summary
  */
 import { Command } from "commander";
-import { type ConflictStrategy, type MembershipSyncConfig, type SyncMode, type PullScope, type ExplicitGrant } from "@indigoai-us/hq-cloud";
+import { type ConflictStrategy, type EntityContext, type MembershipSyncConfig, type SyncMode, type PullScope, type ExplicitGrant, type ShareOptions, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
 import { type BannerLevel } from "../lib/narrow-hint-banner.js";
 /**
  * Terminal-failure signal for the sync fanout runners. The runners
@@ -264,6 +264,18 @@ export declare function pullAll(options: PullAllOptions, deps: PullAllDeps): Pro
  * deps so tests can drive it without network or filesystem.
  */
 export declare function pushAll(options: PushAllOptions, deps: PushAllDeps): Promise<PushAllResult>;
+/**
+ * Credentials `hq sync push` hands to share(). A pre-vended EntityContext
+ * (AppBar's `--creds-from-stdin` first push) cannot write under private
+ * folders directly, so it travels with the caller's vault config as
+ * `privateFolderVaultConfig`. share() takes exactly one of `vaultConfig` /
+ * `entityContext`.
+ */
+export declare function pushShareCredentials(input: {
+    entityContext?: EntityContext;
+    vaultConfig?: VaultServiceConfig;
+    scopeVaultConfig?: VaultServiceConfig;
+}): Pick<ShareOptions, "entityContext" | "vaultConfig" | "privateFolderVaultConfig">;
 /**
  * Resolve the canonical person entity UID for the logged-in user. Used by
  * `hq sync {push,pull,now} --personal` to target the personal vault without

package/dist/commands/cloud.js

@@ -455,6 +455,24 @@ export async function pushAll(options, deps) {
     }
     return result;
 }
+/**
+ * Credentials `hq sync push` hands to share(). A pre-vended EntityContext
+ * (AppBar's `--creds-from-stdin` first push) cannot write under private
+ * folders directly, so it travels with the caller's vault config as
+ * `privateFolderVaultConfig`. share() takes exactly one of `vaultConfig` /
+ * `entityContext`.
+ */
+export function pushShareCredentials(input) {
+    if (input.entityContext) {
+        return {
+            entityContext: input.entityContext,
+            ...(input.scopeVaultConfig
+                ? { privateFolderVaultConfig: input.scopeVaultConfig }
+                : {}),
+        };
+    }
+    return input.vaultConfig ? { vaultConfig: input.vaultConfig } : {};
+}
 /**
  * Resolve the canonical person entity UID for the logged-in user. Used by
  * `hq sync {push,pull,now} --personal` to target the personal vault without
@@ -715,7 +733,7 @@ export function registerCloudCommands(program) {
             //   2. default: vend via cached Cognito session (the human CLI path).
             let entityContext;
             let vaultConfig;
-            /** Vault API config for membership/grant scope lookups. Set even on the pre-vended `--creds-from-stdin` path — share() accepts entityContext OR vaultConfig, not both. */
+            /** Vault API config for membership/grant scope lookups and, on the pre-vended `--creds-from-stdin` path, private-folder uploads. */
             let scopeVaultConfig;
             if (options.credsFromStdin) {
                 if (process.stdin.isTTY) {
@@ -798,8 +816,11 @@ export function registerCloudCommands(program) {
                 company: targetCompany,
                 message: options.message,
                 onConflict: options.onConflict,
-                vaultConfig,
-                entityContext,
+                ...pushShareCredentials({
+                    entityContext,
+                    vaultConfig,
+                    scopeVaultConfig,
+                }),
                 hqRoot: options.hqRoot,
                 onEvent,
                 ...(personalMode ? { personalMode: true } : {}),

package/dist/commands/lanes.js

@@ -121,15 +121,18 @@ function printJson(value) {
     console.log(JSON.stringify(withoutProviderHome(value), null, 2));
 }
 function failJson(err) {
-    if (isLanesError(err)) {
-        if (err.error === "hire_grant_exhausted") {
-            process.stderr.write(`hq lanes: ${err.message}\n`);
-        }
-        printJson({ ...err.toJSON(), message: err.message });
+    const commandError = err instanceof CompanySelectionError
+        ? new LanesError("company_selection_failed", err.message)
+        : err;
+    if (isLanesError(commandError)) {
+        if (commandError.error === "hire_grant_exhausted") {
+            process.stderr.write(`hq lanes: ${commandError.message}\n`);
+        }
+        printJson({ ...commandError.toJSON(), message: commandError.message });
         process.exit(1);
     }
-    const message = err instanceof Error ? err.message : String(err);
-    process.stderr.write(`hq lanes: ${message}${err instanceof Error && err.stack ? `\n${err.stack}` : ""}\n`);
+    const message = commandError instanceof Error ? commandError.message : String(commandError);
+    process.stderr.write(`hq lanes: ${message}${commandError instanceof Error && commandError.stack ? `\n${commandError.stack}` : ""}\n`);
     printJson({ error: "internal", message });
     process.exit(1);
 }

package/dist/lib/doctor/checks/sync-health.d.ts

@@ -64,6 +64,8 @@ export interface SyncManifestUploadStatus {
 }
 /** Injectable dependencies — defaults are the real collectors. */
 export interface SyncHealthDeps {
+    /** Runner log and conflict signals; omitted in unit tests of other checks. */
+    runtime?: (now: Date) => CheckResult[];
     versions: (hqRoot: string) => SyncVersionInfo;
     journals: () => readonly SyncJournalSummary[];
     now: () => Date;

package/dist/lib/doctor/checks/sync-health.js

@@ -23,6 +23,7 @@
  * Every dependency is injectable so the family is unit-testable without an HQ
  * tree, a state dir, or the wall clock.
  */
+import { defaultSyncRuntimeResults } from "./sync-runtime.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 // Namespace import, deliberately: hq-cloud is an ESM package, so a static
@@ -50,6 +51,7 @@ export const UPDATE_CACHE_RELPATH = path.join("workspace", ".hq-update-check", "
 function withDefaults(deps, hqRoot) {
     return {
         ...deps,
+        runtime: deps.runtime ?? (() => []),
         manifestStatuses: deps.manifestStatuses ?? defaultManifestStatuses,
         manifestAvailable: deps.manifestAvailable ?? (() => loadManifestExports() !== null),
         unresolvedScopes: deps.unresolvedScopes ?? defaultUnresolvedScopes,
@@ -118,6 +120,7 @@ const DEFAULT_DEPS = {
     journals: () => hqCloud.listJournals(),
     now: () => new Date(),
     manifestStatuses: defaultManifestStatuses,
+    runtime: defaultSyncRuntimeResults,
 };
 /**
  * Map the machine's journal shards onto the manifest scopes hq-cloud keys its
@@ -190,6 +193,7 @@ export function checkSyncHealth(context, rawDeps = DEFAULT_DEPS) {
             ...versionResults(context, deps),
             ...updateAvailabilityResult(context, deps),
             ...journalAndManifestResults(deps),
+            ...deps.runtime(deps.now()),
         ];
     }
     catch (error) {

package/dist/lib/doctor/checks/sync-runtime.d.ts

@@ -0,0 +1,11 @@
+import type { CheckResult } from "../types.js";
+export declare const SYNC_RUNTIME_WINDOW_MS: number;
+export interface SyncRuntimeOptions {
+    now: number;
+    conflictCount?: number;
+}
+/** Classify the last hour of sync log lines into privacy-safe results. */
+export declare function analyzeSyncRuntimeLog(lines: readonly string[], options: SyncRuntimeOptions): CheckResult[];
+/** Read the machine's sync logs and client health file. */
+export declare function defaultSyncRuntimeResults(now: Date, hqHome?: string): CheckResult[];
+//# sourceMappingURL=sync-runtime.d.ts.map

package/dist/lib/doctor/checks/sync-runtime.js

@@ -0,0 +1,166 @@
+/**
+ * Sync runtime checks: problems visible only in the running sync runner's log
+ * (realtime lag, receiver permission errors, restart loops, device-limit
+ * backoff) plus the conflict counter the desktop app keeps in client health.
+ *
+ * Results carry only a closed reason code and counts. Log content (paths,
+ * tenant ids, AWS error prose) never leaves this module.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const SYNC_RUNTIME_WINDOW_MS = 60 * 60_000;
+const LAG_SECONDS = 15 * 60;
+const LAG_MIN_RECEIPTS = 3;
+const RESTART_MIN_STARTS = 4;
+const CONFLICT_MIN_COUNT = 5;
+const LOG_TAIL_BYTES = 8 * 1024 * 1024;
+const TIMESTAMP = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)\s/;
+const PERMISSION = /AccessDenied|not authorized to perform|\b403\b/;
+const DEVICE_LIMIT = /sync device limit exceeded|"sync_device_limit"/;
+function parseRecord(rest) {
+    const start = rest.indexOf("{");
+    if (start < 0)
+        return null;
+    try {
+        const value = JSON.parse(rest.slice(start));
+        return value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Classify the last hour of sync log lines into privacy-safe results. */
+export function analyzeSyncRuntimeLog(lines, options) {
+    const since = options.now - SYNC_RUNTIME_WINDOW_MS;
+    let slowReceipts = 0;
+    let denied = 0;
+    let starts = 0;
+    let deviceLimited = 0;
+    for (const line of lines) {
+        const stamp = TIMESTAMP.exec(line);
+        if (!stamp)
+            continue;
+        const time = Date.parse(stamp[1]);
+        if (!Number.isFinite(time) || time < since || time > options.now)
+            continue;
+        const rest = line.slice(stamp[0].length);
+        if (DEVICE_LIMIT.test(rest))
+            deviceLimited += 1;
+        const record = parseRecord(rest);
+        if (!record)
+            continue;
+        const event = record.event;
+        if (event === "fanout.receive") {
+            const latency = record.latencySeconds;
+            if (typeof latency === "number" && latency > LAG_SECONDS)
+                slowReceipts += 1;
+        }
+        else if (event === "receiver.start") {
+            starts += 1;
+        }
+        if ((record.type === "receiver" || record.type === "error") &&
+            PERMISSION.test(JSON.stringify(record.err ?? record.message ?? ""))) {
+            denied += 1;
+        }
+    }
+    const conflicts = options.conflictCount ?? 0;
+    const checks = [
+        { id: "realtime-lag", reasonCode: "realtime-lag-stuck", failing: slowReceipts >= LAG_MIN_RECEIPTS, count: slowReceipts, label: "incoming changes delayed over 15 minutes" },
+        { id: "receiver-permission", reasonCode: "receiver-permission-denied", failing: denied > 0, count: denied, label: "cloud permission refusals" },
+        { id: "runner-restarts", reasonCode: "runner-restart-loop", failing: starts >= RESTART_MIN_STARTS, count: starts, label: "sync runner starts" },
+        { id: "device-limit", reasonCode: "device-limit-backoff", failing: deviceLimited > 0, count: deviceLimited, label: "device-limit backoffs" },
+        { id: "conflicts", reasonCode: "repeated-conflicts", failing: conflicts >= CONFLICT_MIN_COUNT, count: conflicts, label: "unresolved conflicts" },
+    ];
+    return checks.map((check) => check.failing
+        ? {
+            status: "WARN",
+            checkId: `sync.runtime.${check.id}`,
+            reasonCode: check.reasonCode,
+            message: `${check.count} ${check.label} in the last hour.`,
+            remediation: "Run `hq sync status` and check ~/.hq/logs/hq-sync.log.",
+        }
+        : {
+            status: "PASS",
+            checkId: `sync.runtime.${check.id}`,
+            message: `${check.count} ${check.label} in the last hour.`,
+        });
+}
+const LOG_GENERATIONS = 4;
+function readLogTail(file) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const size = fs.fstatSync(fd).size;
+        const length = Math.min(size, LOG_TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        fs.readSync(fd, buffer, 0, length, size - length);
+        return buffer.toString("utf8").split("\n");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function firstTimestamp(lines) {
+    for (const line of lines) {
+        const stamp = TIMESTAMP.exec(line);
+        if (stamp)
+            return Date.parse(stamp[1]);
+    }
+    return null;
+}
+/**
+ * Lines from the active log and as many rotated generations as needed to
+ * cover the window. Throws when a present log cannot be read.
+ */
+function readWindowLines(logFile, since) {
+    const generations = [];
+    for (let n = 0; n < LOG_GENERATIONS; n += 1) {
+        const file = n === 0 ? logFile : `${logFile}.${n}`;
+        if (!fs.existsSync(file))
+            break;
+        const lines = readLogTail(file);
+        generations.unshift(lines);
+        const first = firstTimestamp(lines);
+        if (first !== null && first <= since)
+            break;
+    }
+    return generations.length > 0 ? generations.flat() : null;
+}
+function readConflictCount(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        const count = value?.conflictCount;
+        return typeof count === "number" && Number.isFinite(count) ? count : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Read the machine's sync logs and client health file. */
+export function defaultSyncRuntimeResults(now, hqHome = path.join(os.homedir(), ".hq")) {
+    const options = {
+        now: now.getTime(),
+        conflictCount: readConflictCount(path.join(hqHome, "client-health.json")),
+    };
+    const logFile = path.join(hqHome, "logs", "hq-sync.log");
+    let lines;
+    try {
+        lines = readWindowLines(logFile, options.now - SYNC_RUNTIME_WINDOW_MS);
+    }
+    catch {
+        return [
+            { status: "UNKNOWN", checkId: "sync.runtime.log", message: "The sync runner log could not be read." },
+            ...analyzeSyncRuntimeLog([], options).filter((r) => r.checkId === "sync.runtime.conflicts"),
+        ];
+    }
+    if (lines === null) {
+        return [
+            { status: "NA", checkId: "sync.runtime.log", message: "No sync runner log on this machine." },
+            ...analyzeSyncRuntimeLog([], options).filter((r) => r.checkId === "sync.runtime.conflicts"),
+        ];
+    }
+    return analyzeSyncRuntimeLog(lines, options);
+}
+//# sourceMappingURL=sync-runtime.js.map

package/dist/lib/doctor/client-health-sentry.d.ts

@@ -5,7 +5,7 @@ export declare const CLIENT_HEALTH_INSTALL_ID_FILENAME = "install-id";
 export declare const CLIENT_HEALTH_LAST_RESULT_FILENAME = "last-result.json";
 export type ClientHealthFixOutcome = "not_auto_fixable" | "fix_failed" | "fix_timed_out";
 export type ClientHealthStatus = "FAIL" | "WARN";
-export type ClientHealthCheckClass = "sync.update.core" | "sync.journal.personal" | "sync.journal.personal_vault" | "sync.journal.company" | "sync.manifest.personal" | "sync.manifest.personal_vault" | "sync.manifest.company" | "other";
+export type ClientHealthCheckClass = "sync.update.core" | "sync.journal.personal" | "sync.journal.personal_vault" | "sync.journal.company" | "sync.manifest.personal" | "sync.manifest.personal_vault" | "sync.manifest.company" | "sync.runtime" | "other";
 export interface ClientHealthSentryEvent {
     message: string;
     level: "warning";

package/dist/lib/doctor/client-health-sentry.js

@@ -24,6 +24,11 @@ const REASON_CODES = new Set([
     "never-uploaded",
     "invalid-upload-time",
     "unresolved-company-uid",
+    "realtime-lag-stuck",
+    "receiver-permission-denied",
+    "runner-restart-loop",
+    "device-limit-backoff",
+    "repeated-conflicts",
 ]);
 const FIX_OUTCOMES = new Set(["not_auto_fixable", "fix_failed", "fix_timed_out"]);
 const INSTALL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -52,6 +57,8 @@ function cleanArchitecture(value) {
 export function normalizeClientHealthCheckId(checkId) {
     if (checkId === "sync.update.core")
         return checkId;
+    if (checkId === "sync.runtime" || checkId.startsWith("sync.runtime."))
+        return "sync.runtime";
     if (checkId === "sync.journal.__hq_personal_vault__")
         return "sync.journal.personal_vault";
     if (checkId === "sync.manifest.__hq_personal_vault__")

package/dist/lib/doctor/types.d.ts

@@ -19,7 +19,7 @@ export declare const DOCTOR_STATUSES: readonly ["PASS", "FAIL", "WARN", "UNTESTE
  */
 export type DoctorStatus = (typeof DOCTOR_STATUSES)[number];
 /** Stable, privacy-safe diagnostics emitted by the sync health family. */
-export declare const SYNC_REASON_CODES: readonly ["core-version-unavailable", "core-update-available", "no-local-tree", "never-synced", "invalid-last-sync", "stale-threshold", "manifest-unavailable", "manifest-state-unavailable", "no-manifest-scopes", "never-uploaded", "invalid-upload-time", "unresolved-company-uid"];
+export declare const SYNC_REASON_CODES: readonly ["core-version-unavailable", "core-update-available", "no-local-tree", "never-synced", "invalid-last-sync", "stale-threshold", "manifest-unavailable", "manifest-state-unavailable", "no-manifest-scopes", "never-uploaded", "invalid-upload-time", "unresolved-company-uid", "realtime-lag-stuck", "receiver-permission-denied", "runner-restart-loop", "device-limit-backoff", "repeated-conflicts"];
 export type SyncReasonCode = (typeof SYNC_REASON_CODES)[number];
 /** Runtime type guard: true only for a member of the fixed vocabulary. */
 export declare function isDoctorStatus(value: unknown): value is DoctorStatus;

package/dist/lib/doctor/types.js

@@ -35,6 +35,11 @@ export const SYNC_REASON_CODES = [
     "never-uploaded",
     "invalid-upload-time",
     "unresolved-company-uid",
+    "realtime-lag-stuck",
+    "receiver-permission-denied",
+    "runner-restart-loop",
+    "device-limit-backoff",
+    "repeated-conflicts",
 ];
 /** Runtime type guard: true only for a member of the fixed vocabulary. */
 export function isDoctorStatus(value) {

package/package.json

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