@indigoai-us/hq-cli 5.106.3 → 5.107.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [5.107.0] — 2026-09-03
+
+### Added
+
+- The CLI now reports client health to HQ Cloud, so support can see which
+  versions a person is running and when their sync last actually succeeded —
+  without asking them for a screenshot. Each authenticated invocation reports
+  the installed CLI, HQ Core, and desktop versions, and sync commands report
+  both the attempt and its real outcome. The contribution is bounded, is never
+  allowed to delay or change a command's result or exit code, and is skipped
+  entirely on machines that have no HQ installation.
+- `hq doctor` gained a `sync` check family covering installed versions,
+  available updates, and per-company sync journal staleness. An unreadable
+  journal store is now reported as `UNKNOWN` rather than being mistaken for
+  "cloud sync not in use".
+- Reindexing now trusts the HQ folder for Claude Code, not only Codex and Grok.
+
+### Fixed
+
+- Sync commands that exit early on failure now record that failure instead of
+  leaving the run marked as still in progress.
+
 ## [5.106.3] — 2026-09-02
 
 ## [5.106.2] — 2026-09-02

package/dist/commands/cloud.d.ts

@@ -15,6 +15,34 @@
 import { Command } from "commander";
 import { type ConflictStrategy, type MembershipSyncConfig, type SyncMode, type PullScope, type ExplicitGrant } from "@indigoai-us/hq-cloud";
 import { type BannerLevel } from "../lib/narrow-hint-banner.js";
+/**
+ * Terminal-failure signal for the sync fanout runners. The runners
+ * (`runPushAll` / `runPullAll` / `runPullPersonal` / `runNowSingle` /
+ * `runNowAll`) NEVER call `process.exit` themselves — they print their own
+ * diagnostics and throw this instead, so control always unwinds back into
+ * {@link withSyncHealthReport}, which records the terminal client-health
+ * outcome BEFORE the process exits. A direct `process.exit` inside a runner
+ * would skip the wrapper's catch, leaving a dangling `sync_attempt`
+ * ("syncing") heartbeat with no terminal success/failure and a wrong local
+ * `consecutiveFailures` counter (US-003 review fix).
+ */
+export declare class SyncExitError extends Error {
+    readonly code: number;
+    constructor(code: number);
+}
+/**
+ * US-003: run one sync fanout under a client-health attempt/outcome report.
+ * The report is best-effort, bounded, and swallowed — it can only append a
+ * short bounded wait, never change the run's result, thrown error, or exit
+ * code. Direct reporting from the sync command itself (never reconstructed
+ * from cli_session_started analytics).
+ *
+ * Outcome reporting cannot be skipped: runners signal failure exits via
+ * {@link SyncExitError} (never a direct `process.exit`), so EVERY terminal
+ * path — return, throw, or exit — flows through `succeeded()`/`failed()`
+ * before this wrapper exits the process on the runner's behalf.
+ */
+export declare function withSyncHealthReport<T>(run: () => Promise<T>): Promise<T>;
 /**
  * Build a loud, human-readable warning when a push dropped files because
  * they fell outside the caller's granted write scope. Returns null when
@@ -302,4 +330,6 @@ export interface PerCompanyPullResolveResult {
 }
 export declare function resolvePerCompanyPullPlan(client: PerCompanyPullResolveClient, targetCompany: string | undefined): Promise<PerCompanyPullResolveResult>;
 export declare function registerCloudCommands(program: Command): void;
+/** Exported for the US-003 sync-health exit-path regression test. */
+export declare function runPullPersonal(hqRoot: string, onConflict?: ConflictStrategy): Promise<void>;
 //# sourceMappingURL=cloud.d.ts.map

package/dist/commands/cloud.js

@@ -18,6 +18,52 @@ import * as path from "path";
 import { share, sync, getStateDir, listJournals, loadCachedTokens, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
+import { beginSyncHealthReport, } from "../utils/client-health.js";
+/**
+ * Terminal-failure signal for the sync fanout runners. The runners
+ * (`runPushAll` / `runPullAll` / `runPullPersonal` / `runNowSingle` /
+ * `runNowAll`) NEVER call `process.exit` themselves — they print their own
+ * diagnostics and throw this instead, so control always unwinds back into
+ * {@link withSyncHealthReport}, which records the terminal client-health
+ * outcome BEFORE the process exits. A direct `process.exit` inside a runner
+ * would skip the wrapper's catch, leaving a dangling `sync_attempt`
+ * ("syncing") heartbeat with no terminal success/failure and a wrong local
+ * `consecutiveFailures` counter (US-003 review fix).
+ */
+export class SyncExitError extends Error {
+    code;
+    constructor(code) {
+        super(`sync command exit ${code}`);
+        this.code = code;
+        this.name = "SyncExitError";
+    }
+}
+/**
+ * US-003: run one sync fanout under a client-health attempt/outcome report.
+ * The report is best-effort, bounded, and swallowed — it can only append a
+ * short bounded wait, never change the run's result, thrown error, or exit
+ * code. Direct reporting from the sync command itself (never reconstructed
+ * from cli_session_started analytics).
+ *
+ * Outcome reporting cannot be skipped: runners signal failure exits via
+ * {@link SyncExitError} (never a direct `process.exit`), so EVERY terminal
+ * path — return, throw, or exit — flows through `succeeded()`/`failed()`
+ * before this wrapper exits the process on the runner's behalf.
+ */
+export async function withSyncHealthReport(run) {
+    const health = beginSyncHealthReport();
+    try {
+        const result = await run();
+        await health.succeeded();
+        return result;
+    }
+    catch (err) {
+        await health.failed();
+        if (err instanceof SyncExitError)
+            process.exit(err.code);
+        throw err;
+    }
+}
 /**
  * Build a loud, human-readable warning when a push dropped files because
  * they fell outside the caller's granted write scope. Returns null when
@@ -601,7 +647,7 @@ export function registerCloudCommands(program) {
             // the fanout" — wired through to `pushAll.skipPersonal`. Outside
             // `--all` the flag has no effect (logged above as part of the
             // option's help text).
-            await runPushAll(options.hqRoot, options.message, options.onConflict, options.personal === false);
+            await withSyncHealthReport(() => runPushAll(options.hqRoot, options.message, options.onConflict, options.personal === false));
             return;
         }
         const jsonMode = options.json === true;
@@ -614,6 +660,9 @@ export function registerCloudCommands(program) {
         const emitJson = (event) => {
             process.stderr.write(JSON.stringify(event) + "\n");
         };
+        // Assigned right before the sync engine runs, so option-validation
+        // failures never count as a sync attempt (US-003).
+        let syncHealth;
         try {
             if (options.personal && options.credsFromStdin) {
                 throw new Error("`--personal` cannot be combined with --creds-from-stdin: " +
@@ -708,6 +757,7 @@ export function registerCloudCommands(program) {
                 const scope = await resolveCliPullScope(scopeClient, targetCompany, options.hqRoot);
                 pushPrefixSet = scope?.prefixSet;
             }
+            syncHealth = beginSyncHealthReport();
             const result = await share({
                 paths: targetPaths,
                 company: targetCompany,
@@ -738,6 +788,7 @@ export function registerCloudCommands(program) {
             }
             if (result.aborted) {
                 log(chalk.yellow(`\n⚠ Push aborted (${result.filesUploaded} uploaded, ${result.filesSkipped} skipped)`));
+                await syncHealth.failed();
                 process.exit(1);
             }
             if (result.filesExcludedByScope > 0) {
@@ -751,8 +802,11 @@ export function registerCloudCommands(program) {
             else {
                 log(chalk.green(`\n✓ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ${result.filesSkipped} skipped)`));
             }
+            await syncHealth.succeeded();
         }
         catch (err) {
+            if (syncHealth)
+                await syncHealth.failed();
             const message = err instanceof Error ? err.message : String(err);
             if (jsonMode) {
                 // In JSON mode, the parent process is parsing stderr for ndjson —
@@ -806,13 +860,14 @@ export function registerCloudCommands(program) {
             // `options.personal === false` is Commander's auto-negation of
             // `--personal`; in `--all` mode that means "drop the personal
             // leg from the fanout" (see `--no-personal` option above).
-            await runPullAll(options.hqRoot, options.onConflict, options.modeAll === true, options.personal === false, options.forceScopeShrink === true);
+            await withSyncHealthReport(() => runPullAll(options.hqRoot, options.onConflict, options.modeAll === true, options.personal === false, options.forceScopeShrink === true));
             return;
         }
         if (options.personal) {
-            await runPullPersonal(options.hqRoot, options.onConflict);
+            await withSyncHealthReport(() => runPullPersonal(options.hqRoot, options.onConflict));
             return;
         }
+        let syncHealth;
         try {
             console.log(chalk.bold("\nHQ Sync — Pull"));
             console.log(`  HQ root:  ${options.hqRoot}`);
@@ -856,6 +911,7 @@ export function registerCloudCommands(program) {
                 process.exit(1);
             }
             const excludePrefixes = readScopeExcludePrefixes(pullScope);
+            syncHealth = beginSyncHealthReport();
             const result = await sync({
                 company: options.company,
                 onConflict: options.onConflict,
@@ -874,6 +930,7 @@ export function registerCloudCommands(program) {
             });
             if (result.aborted) {
                 console.log(chalk.yellow(`\n⚠ Pull aborted (${result.filesDownloaded} downloaded, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
+                await syncHealth.failed();
                 process.exit(1);
             }
             console.log(chalk.green(`\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
@@ -887,8 +944,11 @@ export function registerCloudCommands(program) {
                     level: narrowHintLevel,
                 });
             }
+            await syncHealth.succeeded();
         }
         catch (err) {
+            if (syncHealth)
+                await syncHealth.failed();
             console.error(chalk.red("\n✗ Pull failed:"), err instanceof Error ? err.message : String(err));
             process.exit(1);
         }
@@ -999,10 +1059,10 @@ export function registerCloudCommands(program) {
                 // of `--personal`; in `--all` mode that means "drop the
                 // personal leg from both legs of the bidirectional fanout"
                 // (see `--no-personal` option above).
-                await runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true, options.personal === false, options.forceScopeShrink === true);
+                await withSyncHealthReport(() => runNowAll(options.hqRoot, options.message, options.onConflict, options.modeAll === true, options.personal === false, options.forceScopeShrink === true));
                 return;
             }
-            await runNowSingle(options.hqRoot, options.company, options.personal === true, options.message, options.onConflict, options.modeAll === true, options.forceScopeShrink === true);
+            await withSyncHealthReport(() => runNowSingle(options.hqRoot, options.company, options.personal === true, options.message, options.onConflict, options.modeAll === true, options.forceScopeShrink === true));
         }
         catch (err) {
             console.error(chalk.red("\n✗ Sync now failed:"), err instanceof Error ? err.message : String(err));
@@ -1074,7 +1134,9 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
     }
     catch (err) {
         console.error(chalk.red("\n✗ Pull-all failed:"), err instanceof Error ? err.message : String(err));
-        process.exit(1);
+        // Unwind (never process.exit) so withSyncHealthReport records the
+        // terminal sync_failure before exiting on our behalf.
+        throw new SyncExitError(1);
     }
     for (const row of result.perCompany) {
         if (row.error) {
@@ -1095,9 +1157,10 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
         `target(s); ${result.conflicts} conflict(s); ${errored} error(s)`;
     console.log(errored > 0 ? chalk.yellow(summary) : chalk.green(summary));
     if (errored > 0)
-        process.exit(1);
+        throw new SyncExitError(1);
 }
-async function runPullPersonal(hqRoot, onConflict) {
+/** Exported for the US-003 sync-health exit-path regression test. */
+export async function runPullPersonal(hqRoot, onConflict) {
     console.log(chalk.bold("\nHQ Sync — Pull (personal)"));
     console.log(`  HQ root:  ${hqRoot}`);
     console.log(`  Strategy: ${onConflict ?? "(interactive)"}\n`);
@@ -1120,13 +1183,15 @@ async function runPullPersonal(hqRoot, onConflict) {
         });
         if (result.aborted) {
             console.log(chalk.yellow(`\n⚠ Pull aborted (${result.filesDownloaded} downloaded, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
-            process.exit(1);
+            throw new SyncExitError(1);
         }
         console.log(chalk.green(`\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
     }
     catch (err) {
+        if (err instanceof SyncExitError)
+            throw err;
         console.error(chalk.red("\n✗ Pull (personal) failed:"), err instanceof Error ? err.message : String(err));
-        process.exit(1);
+        throw new SyncExitError(1);
     }
 }
 async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
@@ -1192,7 +1257,9 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
     }
     catch (err) {
         console.error(chalk.red("\n✗ Push-all failed:"), err instanceof Error ? err.message : String(err));
-        process.exit(1);
+        // Unwind (never process.exit) so withSyncHealthReport records the
+        // terminal sync_failure before exiting on our behalf.
+        throw new SyncExitError(1);
     }
     for (const row of result.perCompany) {
         if (row.error) {
@@ -1222,7 +1289,7 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
         console.log(chalk.yellow(scopeExcludedWarning(result.filesExcludedByScope)));
     }
     if (errored > 0)
-        process.exit(1);
+        throw new SyncExitError(1);
 }
 async function runNowSingle(hqRoot, company, personal, message, onConflict, modeAllOverride, forceScopeShrink) {
     console.log(chalk.bold("\nHQ Sync — Now"));
@@ -1304,7 +1371,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         }
         if (pushResult.aborted) {
             console.log(chalk.yellow("\n⚠ Sync now aborted on push leg; pull skipped."));
-            process.exit(1);
+            throw new SyncExitError(1);
         }
         // US-011: resolve membership sync-config so we can either nudge an
         // all-mode owner or refuse the pull when strict-mode is on. Skipped
@@ -1352,7 +1419,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             console.error(chalk.red("\n✗ Sync now refused: strict narrow-hint mode is on and this " +
                 "company's local folder has grown large. Run `hq sync narrow --apply` " +
                 "to migrate, or re-run with --mode-all."));
-            process.exit(1);
+            throw new SyncExitError(1);
         }
         // DEV-1768: resolve the membership's real scope and thread it into the
         // pull leg, so `hq sync now` stops seeding all-mode PullRecords. Personal
@@ -1392,7 +1459,7 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             (pullResult.aborted ? " — aborted" : ""));
         if (pullResult.aborted) {
             console.log(chalk.yellow("\n⚠ Sync now finished with pull leg aborted."));
-            process.exit(1);
+            throw new SyncExitError(1);
         }
         // Emit the hint banner after a successful pull so it appears at the
         // bottom of the summary rather than mid-stream. Size-gated: only a large
@@ -1407,8 +1474,10 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
         console.log(chalk.green("\n✓ Sync now complete"));
     }
     catch (err) {
+        if (err instanceof SyncExitError)
+            throw err;
         console.error(chalk.red("\n✗ Sync now failed:"), err instanceof Error ? err.message : String(err));
-        process.exit(1);
+        throw new SyncExitError(1);
     }
 }
 async function runNowAll(hqRoot, message, onConflict, modeAllOverride, skipPersonal, forceScopeShrink) {

package/dist/commands/reindex.js

@@ -1,7 +1,7 @@
 /**
  * hq reindex — surface namespaced skills, mirror the personal overlay into
  * core/, regenerate the workers registry, and converge HQ-owned hook trust for
- * Codex and Grok.
+ * Codex, Grok, and Claude Code.
  *
  * Thin wrapper over @indigoai-us/hq-cloud's reindex(), which execs the bundled
  * scripts/reindex.sh against the HQ root. This command is what the hq-core
@@ -493,7 +493,7 @@ export function registerReindexCommand(program) {
     program
         .command('reindex')
         .alias('master-sync')
-        .description('Surface namespaced skills, materialize legacy knowledge repos, regenerate the workers registry, and trust HQ hooks for Codex and Grok')
+        .description('Surface namespaced skills, materialize legacy knowledge repos, regenerate the workers registry, and trust HQ hooks for Codex, Grok, and Claude Code')
         .option('--repo-root <path>', 'HQ root to operate on (defaults to the current directory)')
         .option('--from-hook', 'Invoked from a Claude/Codex lifecycle hook: never wait on the per-root operation lock — if a sync/rescue holds it, skip this reindex instead of blocking the session (equivalent to --lock-timeout 0)')
         .option('--lock-timeout <seconds>', 'Bound the wait for the per-root operation lock (seconds). 0 = refuse immediately; omitted = wait indefinitely (the interactive default). --from-hook implies 0; an explicit --lock-timeout wins.')
@@ -518,13 +518,23 @@ export function registerReindexCommand(program) {
         if (lockTimeoutSec !== undefined && process.env.HQ_OP_LOCK_TIMEOUT === undefined) {
             process.env.HQ_OP_LOCK_TIMEOUT = String(lockTimeoutSec);
         }
-        const hqRoot = resolveHqRoot(opts.repoRoot);
+        // Keep the pre-realpath spelling: `resolveHqRoot` canonicalizes, and
+        // Claude keys its trusted projects by session cwd, so a user who lives
+        // in a symlinked HQ root would otherwise never get that spelling trusted.
+        const literalHqRoot = path.resolve(opts.repoRoot ?? findHqRoot());
+        const hqRoot = resolveHqRoot(literalHqRoot);
         const sweepStartedAt = Date.now();
         removeStaleHqWorktrees(hqRoot, sweepStartedAt, opts.fromHook ? sweepStartedAt + WORKTREE_HOOK_SWEEP_BUDGET_MS : Number.POSITIVE_INFINITY);
         const { status } = reindex({ repoRoot: opts.repoRoot });
         repairExtremeHookDrift(hqRoot, status === 0);
-        if (status === 0)
-            await trustHqRuntimeHooks(hqRoot);
+        if (status === 0) {
+            await trustHqRuntimeHooks(hqRoot, undefined, {
+                rootAliases: [literalHqRoot],
+                // A lifecycle hook must never block the agent waiting on another HQ
+                // process's config write; trust converges on the next reindex.
+                lockWaitMs: opts.fromHook ? 0 : undefined,
+            });
+        }
         // Runs even when reindex failed: a failed reindex does not make an
         // oversized blob any less likely to wedge the next push.
         reportLargeFileGuard(hqRoot);

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

@@ -0,0 +1,65 @@
+/**
+ * Versions & sync health — the doctor family the registry docblock always
+ * anticipated (client-sync-health-control-plane US-015).
+ *
+ * Reports, per install:
+ *   - the CLI / Core / desktop (hq-sync menubar) component versions, from the
+ *     same collectors the feedback and client-health paths use (US-003), so
+ *     `hq doctor --json` shows exactly what a heartbeat would report;
+ *   - whether a newer hq-core release is known to be available — read OFFLINE
+ *     from the cache stamped by the `check-hq-update` SessionStart hook
+ *     (`workspace/.hq-update-check/last-check.json`), never from the network,
+ *     preserving the doctor's offline contract (no cache → UNTESTED, not PASS);
+ *   - per-company sync journal staleness via the engine's `listJournals()` —
+ *     the ONLY correct enumeration of per-scope journal shards
+ *     (single-path reconstruction regressed before: feedback_9fbf1f82 /
+ *     feedback_46288b7b).
+ *
+ * Caution paid for in blood (bridge-health false positives): a machine with no
+ * journals at all is NA, not WARN — CLI-only installs never sync locally and
+ * must not read as degraded. Staleness warns only on a corroborated signal: a
+ * journal that EXISTS and carries a parseable, old `lastSync`.
+ *
+ * Every dependency is injectable so the family is unit-testable without an HQ
+ * tree, a state dir, or the wall clock.
+ */
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+/** The id of the versions/sync family. */
+export declare const SYNC_FAMILY_ID = "sync";
+/** Human title for grouped output. */
+export declare const SYNC_FAMILY_TITLE = "Versions & sync";
+/**
+ * A journal shard older than this is reported stale. Seven days: long enough
+ * that a laptop shut over a weekend never warns, short enough that a silently
+ * dead sync runner surfaces well before data divergence becomes painful.
+ */
+export declare const STALE_JOURNAL_THRESHOLD_MS: number;
+/** The offline update cache written by the check-hq-update SessionStart hook. */
+export declare const UPDATE_CACHE_RELPATH: string;
+/** The minimal journal shape this family reads. Matches `JournalSummary`. */
+export interface SyncJournalSummary {
+    slug: string;
+    path: string;
+    journal: {
+        lastSync?: string | null;
+    };
+}
+/** The component versions this family reports. */
+export interface SyncVersionInfo {
+    cli: string;
+    core: string | null;
+    desktop: string | null;
+}
+/** Injectable dependencies — defaults are the real collectors. */
+export interface SyncHealthDeps {
+    versions: (hqRoot: string) => SyncVersionInfo;
+    journals: () => readonly SyncJournalSummary[];
+    now: () => Date;
+}
+/** The versions/sync check family. Registered in `createDefaultRegistry`. */
+export declare const syncHealthFamily: CheckFamily;
+/** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
+export declare function checkSyncHealth(context: CheckContext, deps?: SyncHealthDeps): CheckResult[];
+/** True when `a` > `b` for plain X.Y.Z versions. Non-numeric parts compare 0. */
+export declare function semverGt(a: string, b: string): boolean;
+//# sourceMappingURL=sync-health.d.ts.map