@indigoai-us/hq-cli 5.108.17 → 5.108.19

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

@@ -50,16 +50,61 @@ export interface SyncVersionInfo {
     core: string | null;
     desktop: string | null;
 }
+/**
+ * Per-scope manifest upload state, as `hq doctor` reads it. Structurally the
+ * subset of hq-cloud's `ManifestUploadStatus` this family reports, restated so
+ * the check is injectable without a state dir.
+ */
+export interface SyncManifestUploadStatus {
+    scopeKey: string;
+    lastUploadAt: string | null;
+    snapshotId: string | null;
+    sequence: number;
+    baseUsable: boolean;
+}
 /** Injectable dependencies — defaults are the real collectors. */
 export interface SyncHealthDeps {
     versions: (hqRoot: string) => SyncVersionInfo;
     journals: () => readonly SyncJournalSummary[];
     now: () => Date;
+    /**
+     * Per-scope manifest upload state (sync-reconciliation-audit US-004).
+     *
+     * Takes the ALREADY-ENUMERATED journals so the scope list the manifest check
+     * reports is exactly the scope list the staleness checks report — deriving it
+     * a second way is how the two halves of this family would end up disagreeing
+     * about which companies exist on the machine.
+     */
+    manifestStatuses?: (journals: readonly SyncJournalSummary[]) => readonly SyncManifestUploadStatus[];
+    /**
+     * Whether the installed hq-cloud exposes the manifest exports at all.
+     * Optional; defaults to feature detection. When false the family emits a
+     * single NA row instead of failing — an older hq-cloud is a missing
+     * capability, not a broken install.
+     */
+    manifestAvailable?: () => boolean;
+    /**
+     * Scopes that appear as journal shards but cannot be turned into a manifest
+     * scope key locally (company shards, whose `companyUid` the journal listing
+     * does not carry). Reported explicitly as UNTESTED rather than silently
+     * dropped — a scope missing from the output is indistinguishable from a
+     * scope that is fine.
+     */
+    unresolvedScopes?: (journals: readonly SyncJournalSummary[]) => readonly string[];
 }
 /** 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[];
+export declare function checkSyncHealth(context: CheckContext, rawDeps?: 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;
+/**
+ * A scope whose last manifest upload is older than this is reported stale.
+ *
+ * The upload pass throttles itself to one pass per scope per 24h, so anything
+ * under two days is simply "the throttle is working". Three days means at
+ * least two scheduled passes were missed, which is a corroborated signal that
+ * something — the daemon, the network, the kill switch — is not running.
+ */
+export declare const STALE_MANIFEST_THRESHOLD_MS: number;
 //# sourceMappingURL=sync-health.d.ts.map

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

@@ -25,7 +25,12 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { listJournals } from "@indigoai-us/hq-cloud";
+// Namespace import, deliberately: hq-cloud is an ESM package, so a static
+// NAMED import of an export the installed version lacks is a link-time
+// SyntaxError that would stop `hq doctor` from starting at all. See
+// ../../hq-cloud-manifest.js.
+import * as hqCloud from "@indigoai-us/hq-cloud";
+import { loadManifestExports, MANIFEST_UNAVAILABLE_REASON, } from "../../hq-cloud-manifest.js";
 import { CLI_VERSION } from "../../../cli-version.js";
 import { readSyncVersion } from "../../../utils/feedback-versions.js";
 import { readHqVersion } from "../../../utils/pack-contributions.js";
@@ -41,6 +46,25 @@ export const SYNC_FAMILY_TITLE = "Versions & sync";
 export const STALE_JOURNAL_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
 /** The offline update cache written by the check-hq-update SessionStart hook. */
 export const UPDATE_CACHE_RELPATH = path.join("workspace", ".hq-update-check", "last-check.json");
+/** Fill in the optional dependencies so call sites never branch on undefined. */
+function withDefaults(deps) {
+    return {
+        ...deps,
+        manifestStatuses: deps.manifestStatuses ?? defaultManifestStatuses,
+        manifestAvailable: deps.manifestAvailable ?? (() => loadManifestExports() !== null),
+        unresolvedScopes: deps.unresolvedScopes ?? defaultUnresolvedScopes,
+    };
+}
+/**
+ * Company journal shards are unresolvable by the default collector: the
+ * snapshot store keys company scopes by `companyUid`, which `listJournals()`
+ * does not carry. Naming them here keeps them visible.
+ */
+function defaultUnresolvedScopes(journals) {
+    return journals
+        .filter((entry) => !NON_COMPANY_JOURNAL_SLUGS.has(entry.slug))
+        .map((entry) => entry.slug);
+}
 function defaultVersions(hqRoot) {
     return {
         cli: CLI_VERSION,
@@ -70,9 +94,58 @@ const DEFAULT_DEPS = {
     // surface as UNKNOWN in `journalResults`, never be collapsed into the
     // empty-list (NA, "cloud sync not in use") case. False healthy is worse
     // than no check.
-    journals: () => listJournals(),
+    journals: () => hqCloud.listJournals(),
     now: () => new Date(),
+    manifestStatuses: defaultManifestStatuses,
 };
+/**
+ * Map the machine's journal shards onto the manifest scopes hq-cloud keys its
+ * snapshot store by, then read each one's last upload.
+ *
+ * The journal slug `personal` is the personal tree; every other slug is a
+ * company. Note the snapshot store keys company scopes by `companyUid`, which
+ * the journal listing does not carry — so a company whose uid we cannot name
+ * is simply not reported here rather than reported wrongly. That is the honest
+ * outcome: this check exists to tell an operator when a manifest STOPPED being
+ * uploaded, and inventing a scope key would make it lie in both directions.
+ */
+function defaultManifestStatuses(journals) {
+    // Both the legacy `personal` shard and the current personal-vault
+    // pseudo-slug name the SAME personal tree; a machine mid-migration has both
+    // on disk, so collapse them to a single personal scope rather than asking
+    // hq-cloud for the same scope twice.
+    const scopes = journals.some((entry) => NON_COMPANY_JOURNAL_SLUGS.has(entry.slug))
+        ? [{ kind: "personal" }]
+        : [];
+    if (scopes.length === 0)
+        return [];
+    // Absent on an older hq-cloud; the NA row is emitted by `manifestResults`
+    // before this ever runs, so returning empty here is belt-and-braces.
+    const exports = loadManifestExports();
+    if (!exports)
+        return [];
+    return exports.readManifestUploadStatus(exports.getStateDir(), scopes);
+}
+/** The legacy journal slug that named the personal (non-company) tree. */
+const PERSONAL_SCOPE_SLUG = "personal";
+/**
+ * hq-cloud's personal-vault pseudo-slug (`PERSONAL_VAULT_JOURNAL_SLUG`). It is
+ * a sentinel, not a company: the entity service never mints a slug with
+ * leading underscores. Inlined rather than imported so this module keeps its
+ * link-safety story (see `hq-cloud-manifest.ts`).
+ */
+const PERSONAL_VAULT_SCOPE_SLUG = "__hq_personal_vault__";
+/**
+ * Journal slugs that do NOT name a company. Every one of these is already
+ * covered by the `sync.manifest.personal` row, so listing them as unresolved
+ * company scopes would be doubly wrong: it invents a company that does not
+ * exist and tells the operator to run `hq sync manifest --scope
+ * __hq_personal_vault__`, which is not a scope the CLI accepts.
+ */
+const NON_COMPANY_JOURNAL_SLUGS = new Set([
+    PERSONAL_SCOPE_SLUG,
+    PERSONAL_VAULT_SCOPE_SLUG,
+]);
 /** The versions/sync check family. Registered in `createDefaultRegistry`. */
 export const syncHealthFamily = {
     id: SYNC_FAMILY_ID,
@@ -80,12 +153,13 @@ export const syncHealthFamily = {
     run: (context) => Promise.resolve(checkSyncHealth(context)),
 };
 /** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
-export function checkSyncHealth(context, deps = DEFAULT_DEPS) {
+export function checkSyncHealth(context, rawDeps = DEFAULT_DEPS) {
+    const deps = withDefaults(rawDeps);
     try {
         return [
             ...versionResults(context, deps),
             ...updateAvailabilityResult(context, deps),
-            ...journalResults(deps),
+            ...journalAndManifestResults(deps),
         ];
     }
     catch (error) {
@@ -204,7 +278,16 @@ export function semverGt(a, b) {
     return false;
 }
 // ─── Per-journal staleness ───────────────────────────────────────────────────
-function journalResults(deps) {
+/**
+ * Enumerate the journals ONCE, then run both the staleness checks and the
+ * manifest-upload checks off that single list.
+ *
+ * Sharing the enumeration is not just an optimisation: an enumeration failure
+ * must produce exactly one UNKNOWN, and the two checks must never disagree
+ * about which scopes exist because they asked the store at two different
+ * moments.
+ */
+function journalAndManifestResults(deps) {
     // Enumeration failure (throw / IO error) is UNKNOWN — which FAILS per the
     // doctor's exit-code contract — never NA: a broken or unreadable journal
     // store must not read as "cloud sync not in use" (a false healthy). Only a
@@ -235,6 +318,9 @@ function journalResults(deps) {
             },
         ];
     }
+    return [...journalResults(deps, journals), ...manifestResults(deps, journals)];
+}
+function journalResults(deps, journals) {
     const nowMs = deps.now().getTime();
     return journals.map((entry) => {
         const lastSync = entry.journal?.lastSync;
@@ -276,4 +362,125 @@ function journalResults(deps) {
         };
     });
 }
+// ─── Manifest upload freshness (sync-reconciliation-audit US-004) ────────────
+/**
+ * A scope whose last manifest upload is older than this is reported stale.
+ *
+ * The upload pass throttles itself to one pass per scope per 24h, so anything
+ * under two days is simply "the throttle is working". Three days means at
+ * least two scheduled passes were missed, which is a corroborated signal that
+ * something — the daemon, the network, the kill switch — is not running.
+ */
+export const STALE_MANIFEST_THRESHOLD_MS = 3 * 24 * 60 * 60 * 1000;
+/**
+ * Report the last manifest upload per scope.
+ *
+ * NEVER-UPLOADED IS INFORMATIONAL, NOT A FAILURE. The audit rolls out to a
+ * fleet that has never run a pass, and every one of those machines is working
+ * exactly as designed until the first pass is due. Reporting UNTESTED (wired
+ * but not yet exercised) rather than WARN is the whole reason the doctor's
+ * status vocabulary has that value — collapsing it into WARN would turn the
+ * first day of the rollout into a fleet-wide false alarm.
+ */
+function manifestResults(deps, journals) {
+    // An hq-cloud that predates the manifest exports is a MISSING CAPABILITY,
+    // not a fault: one NA row, and the rest of `hq doctor` runs untouched.
+    if (!deps.manifestAvailable()) {
+        return [
+            {
+                status: "NA",
+                checkId: "sync.manifest",
+                message: `${MANIFEST_UNAVAILABLE_REASON} — upgrade hq-cloud to audit manifest uploads.`,
+            },
+        ];
+    }
+    let statuses;
+    try {
+        statuses = deps.manifestStatuses(journals);
+    }
+    catch (error) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: "sync.manifest",
+                message: `Manifest upload state could not be read: ${error instanceof Error ? error.message : String(error)}`,
+                remediation: "Check that the HQ state directory is readable, then re-run `hq doctor`.",
+            },
+        ];
+    }
+    const unresolved = unresolvedResults(deps, journals);
+    if (statuses.length === 0) {
+        if (unresolved.length > 0)
+            return unresolved;
+        return [
+            {
+                status: "NA",
+                checkId: "sync.manifest",
+                message: "No manifest-auditable sync scopes on this machine — nothing to reconcile.",
+            },
+        ];
+    }
+    const nowMs = deps.now().getTime();
+    const reported = statuses.map((entry) => {
+        const checkId = `sync.manifest.${entry.scopeKey}`;
+        if (!entry.lastUploadAt) {
+            return {
+                status: "UNTESTED",
+                checkId,
+                message: `Scope '${entry.scopeKey}' has never uploaded a sync manifest — expected until the first pass runs.`,
+                remediation: "Run `hq sync manifest` to upload one now.",
+            };
+        }
+        const parsed = Date.parse(entry.lastUploadAt);
+        if (!Number.isFinite(parsed)) {
+            return {
+                status: "UNKNOWN",
+                checkId,
+                message: `Scope '${entry.scopeKey}' has an unparseable last manifest upload time (${entry.lastUploadAt}).`,
+            };
+        }
+        const ageMs = nowMs - parsed;
+        const baseNote = entry.baseUsable
+            ? `delta base ${entry.snapshotId ?? "?"}`
+            : "next pass will send a full manifest";
+        if (ageMs > STALE_MANIFEST_THRESHOLD_MS) {
+            const days = Math.floor(ageMs / 86_400_000);
+            return {
+                status: "WARN",
+                checkId,
+                message: `Scope '${entry.scopeKey}' last uploaded a sync manifest ${days} day${days === 1 ? "" : "s"} ago (${entry.lastUploadAt}) — the daily audit pass is not running.`,
+                remediation: "Run `hq sync manifest` and check HQ_SYNC_MANIFEST_DISABLED and the sync runner.",
+            };
+        }
+        return {
+            status: "PASS",
+            checkId,
+            message: `Scope '${entry.scopeKey}' uploaded a sync manifest at ${entry.lastUploadAt} (sequence ${entry.sequence}, ${baseNote}).`,
+        };
+    });
+    return [...reported, ...unresolved];
+}
+/**
+ * One explicit row per scope we could NOT resolve to a manifest scope key.
+ *
+ * UNTESTED, not NA and certainly not silence: the scope exists on this machine
+ * and is genuinely un-audited, so an operator must be able to see that the
+ * doctor did not check it. Silently skipping is how a company stops being
+ * reconciled without anyone noticing.
+ */
+function unresolvedResults(deps, journals) {
+    let slugs;
+    try {
+        slugs = deps.unresolvedScopes(journals);
+    }
+    catch {
+        return [];
+    }
+    return slugs.map((slug) => ({
+        status: "UNTESTED",
+        checkId: `sync.manifest.unresolved.${slug}`,
+        message: `Company scope '${slug}' has a sync journal but its companyUid could not be resolved locally — its manifest uploads were not checked.`,
+        remediation: `Run \`hq sync manifest --scope ${slug}\` to audit it explicitly.`,
+    }));
+}
 //# sourceMappingURL=sync-health.js.map

package/dist/lib/hq-cloud-manifest.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Feature detection for the hq-cloud manifest exports.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * `runManifestUploadPass` / `readManifestUploadStatus` were added in the
+ * hq-cloud sync-reconciliation-audit branch and are NOT in the currently
+ * published `~6.16.6` line that this CLI pins. hq-cloud is an ES module, so a
+ * static named import of an export that does not exist is a LINK-TIME
+ * SyntaxError: the importing module never evaluates, and every command that
+ * transitively imports it dies at startup. `hq doctor` is one of those
+ * commands, and it is one of the most widely used in the CLI — a doctor that
+ * cannot start is strictly worse than a doctor missing one row.
+ *
+ * So nothing imports those symbols by name. We import the module NAMESPACE
+ * (always link-safe, regardless of which exports exist) and feature-detect the
+ * functions on it. Callers that need them ask for them and degrade when they
+ * are absent:
+ *   - `hq doctor` emits a single NA row ("manifest status unavailable");
+ *   - `hq sync manifest` prints the version requirement and exits non-zero.
+ *
+ * Once the hq-cloud release carrying these exports lands and the pin is bumped,
+ * this module keeps working unchanged — detection simply always succeeds.
+ */
+/**
+ * The first hq-cloud release that carries the manifest upload exports.
+ *
+ * 6.16.23 is the release that actually ships `runManifestUploadPass` /
+ * `readManifestUploadStatus`, and is the version this package pins.
+ *
+ * Used only for the human-facing "you need at least X" message; the actual
+ * gate is capability detection, never a version comparison — a version string
+ * can lie about what a build contains, a function reference cannot. So a stale
+ * value here misinforms, but never misgates.
+ */
+export declare const MANIFEST_MIN_HQ_CLOUD_VERSION = "6.16.23";
+/** One-line explanation shared by every degradation path. */
+export declare const MANIFEST_UNAVAILABLE_REASON: string;
+/** The subset of hq-cloud the manifest paths need, once proven present. */
+export interface ManifestExports {
+    runManifestUploadPass: (options: never) => unknown;
+    readManifestUploadStatus: (...args: never[]) => unknown;
+    getStateDir: () => string;
+}
+/** Thrown by {@link requireManifestExports}. Carries a user-ready message. */
+export declare class ManifestUnsupportedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Resolve the manifest exports, or null when the installed hq-cloud predates
+ * them.
+ *
+ * The module object is injectable so the absent-export path is testable
+ * without mocking the package (and so the test cannot accidentally pass merely
+ * because the local `link:` override happens to be new enough).
+ */
+export declare function loadManifestExports(mod?: Record<string, unknown>): ManifestExports | null;
+/** True when the installed hq-cloud can do manifest passes at all. */
+export declare function manifestExportsAvailable(mod?: Record<string, unknown>): boolean;
+/** Like {@link loadManifestExports}, but throws instead of returning null. */
+export declare function requireManifestExports(mod?: Record<string, unknown>): ManifestExports;
+//# sourceMappingURL=hq-cloud-manifest.d.ts.map

package/dist/lib/hq-cloud-manifest.js

@@ -0,0 +1,83 @@
+/**
+ * Feature detection for the hq-cloud manifest exports.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * `runManifestUploadPass` / `readManifestUploadStatus` were added in the
+ * hq-cloud sync-reconciliation-audit branch and are NOT in the currently
+ * published `~6.16.6` line that this CLI pins. hq-cloud is an ES module, so a
+ * static named import of an export that does not exist is a LINK-TIME
+ * SyntaxError: the importing module never evaluates, and every command that
+ * transitively imports it dies at startup. `hq doctor` is one of those
+ * commands, and it is one of the most widely used in the CLI — a doctor that
+ * cannot start is strictly worse than a doctor missing one row.
+ *
+ * So nothing imports those symbols by name. We import the module NAMESPACE
+ * (always link-safe, regardless of which exports exist) and feature-detect the
+ * functions on it. Callers that need them ask for them and degrade when they
+ * are absent:
+ *   - `hq doctor` emits a single NA row ("manifest status unavailable");
+ *   - `hq sync manifest` prints the version requirement and exits non-zero.
+ *
+ * Once the hq-cloud release carrying these exports lands and the pin is bumped,
+ * this module keeps working unchanged — detection simply always succeeds.
+ */
+import * as hqCloud from "@indigoai-us/hq-cloud";
+/**
+ * The first hq-cloud release that carries the manifest upload exports.
+ *
+ * 6.16.23 is the release that actually ships `runManifestUploadPass` /
+ * `readManifestUploadStatus`, and is the version this package pins.
+ *
+ * Used only for the human-facing "you need at least X" message; the actual
+ * gate is capability detection, never a version comparison — a version string
+ * can lie about what a build contains, a function reference cannot. So a stale
+ * value here misinforms, but never misgates.
+ */
+export const MANIFEST_MIN_HQ_CLOUD_VERSION = "6.16.23";
+/** One-line explanation shared by every degradation path. */
+export const MANIFEST_UNAVAILABLE_REASON = `manifest status unavailable: hq-cloud too old ` +
+    `(requires an hq-cloud release with manifest support ` +
+    `(>= ${MANIFEST_MIN_HQ_CLOUD_VERSION}))`;
+/** Thrown by {@link requireManifestExports}. Carries a user-ready message. */
+export class ManifestUnsupportedError extends Error {
+    constructor(message = MANIFEST_UNAVAILABLE_REASON) {
+        super(message);
+        this.name = "ManifestUnsupportedError";
+    }
+}
+/**
+ * Resolve the manifest exports, or null when the installed hq-cloud predates
+ * them.
+ *
+ * The module object is injectable so the absent-export path is testable
+ * without mocking the package (and so the test cannot accidentally pass merely
+ * because the local `link:` override happens to be new enough).
+ */
+export function loadManifestExports(mod = hqCloud) {
+    const runManifestUploadPass = mod.runManifestUploadPass;
+    const readManifestUploadStatus = mod.readManifestUploadStatus;
+    const getStateDir = mod.getStateDir;
+    if (typeof runManifestUploadPass !== "function" ||
+        typeof readManifestUploadStatus !== "function" ||
+        typeof getStateDir !== "function") {
+        return null;
+    }
+    return {
+        runManifestUploadPass,
+        readManifestUploadStatus,
+        getStateDir,
+    };
+}
+/** True when the installed hq-cloud can do manifest passes at all. */
+export function manifestExportsAvailable(mod) {
+    return loadManifestExports(mod) !== null;
+}
+/** Like {@link loadManifestExports}, but throws instead of returning null. */
+export function requireManifestExports(mod) {
+    const exports = loadManifestExports(mod);
+    if (!exports)
+        throw new ManifestUnsupportedError();
+    return exports;
+}
+//# sourceMappingURL=hq-cloud-manifest.js.map

package/dist/main.js

@@ -6,6 +6,8 @@
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
 import "./node-network-compat.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
@@ -46,10 +48,19 @@ 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 { registerCommandsWithRecovery } from "./startup-registration.js";
+import { installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTreeTornError, } from "./utils/install-tree-torn.js";
 import { isVaultAccessDeniedError, vaultAccessDeniedMessage, } from "./utils/vault-access-denied-error.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
 /** Hard upper bound for non-user-visible release-health finalization. */
 const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
+/**
+ * The RUNNING install's own entrypoint (`<pkg>/dist/index.js`), used as the
+ * torn-install recovery re-exec target. It must be this resolved path — never
+ * `hq` from PATH — because a global reinstall leaves `bin/hq` absent for much of
+ * the rewrite window, while this path now holds the settled tree.
+ */
+const RUNNING_ENTRY_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "index.js");
 const defaultStreamErrorDependencies = {
     stderr: process.stderr,
     exit: (code) => process.exit(code),
@@ -160,13 +171,31 @@ export async function runCli() {
         // `--help`, a bare `hq`, an unknown command, any command not on the
         // manifest — falls back to the complete graph, so its behaviour is
         // unchanged. See register-all.ts for the measurements that motivated this.
-        const lazy = findLazyCommand(process.argv);
-        if (lazy) {
-            await lazy.register(program);
-        }
-        else {
-            const { registerAllCommands } = await import("./register-all.js");
-            registerAllCommands(program);
+        // The same lazy/full registration as before, wrapped so it recovers ONCE if
+        // a global reinstall is tearing the install tree out from under these
+        // deferred imports (Sentry HQ-CLI-1G/1H/1J/1K). Which modules are imported,
+        // and in what order, is unchanged — only the failure handling is added.
+        const registration = await registerCommandsWithRecovery({
+            register: async () => {
+                const lazy = findLazyCommand(process.argv);
+                if (lazy) {
+                    await lazy.register(program);
+                }
+                else {
+                    const { registerAllCommands } = await import("./register-all.js");
+                    registerAllCommands(program);
+                }
+            },
+            argv: process.argv,
+            env: process.env,
+            entryPath: RUNNING_ENTRY_PATH,
+            stderr: process.stderr,
+        });
+        if (registration.reexecStatus !== undefined) {
+            // The re-exec'd child ran the command on the settled tree; carry its exit
+            // status out (after the finally block), exactly as the self-update re-exec.
+            reexecStatus = registration.reexecStatus;
+            return;
         }
         await program.parseAsync();
     }
@@ -337,6 +366,21 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         });
         deps.setExitCode(1);
     }
+    else if (isInstallTreeTornError(err)) {
+        // HQ-CLI-1G/1H/1J/1K: a global reinstall tore the install tree out from
+        // under a starting `hq` and the bounded settle-wait + single re-exec could
+        // not recover it (a still-incomplete tree, a foreign updater, or a failed
+        // re-exec). Print the fixed reinstall remedy naming the bounded missing
+        // specifier, and STILL capture WITH bounded diagnostics — a genuinely
+        // pruned or incomplete install must stay visible. Mirrors the package-root
+        // branch's print-and-capture shape; a class-instance check disjoint from
+        // every neighbour, so no existing ordering changes. A SUCCESSFUL recovery
+        // never reaches here (it returns the child's status), so this line and this
+        // capture only ever mark a real, unrecovered break.
+        deps.stderr.write(`hq: ${installTreeTornStderrLine(err)}\n`);
+        deps.sentry.captureException(err, installTreeTornCaptureContext(err));
+        deps.setExitCode(1);
+    }
     else if (isVaultAccessDeniedError(err)) {
         // ARM B (Sentry 7709408531): `hq skill create`'s post-register vault sync
         // was DENIED by S3 — an AWS SDK v3 403 from an hq-pro IAM session-policy

package/dist/register-all.js

@@ -33,6 +33,7 @@ import { registerUpdateCommand } from "./commands/update.js";
 import { registerCloudCommands } from "./commands/cloud.js";
 import { registerSyncModeCommand } from "./commands/sync-mode.js";
 import { registerSyncNarrowCommand } from "./commands/sync-narrow.js";
+import { registerSyncManifestCommand } from "./commands/sync-manifest.js";
 import { registerCloudProvisionCommands } from "./commands/cloud-provision.js";
 import { registerCloudDemoteCommands } from "./commands/cloud-demote.js";
 import { registerLoginCommand } from "./commands/login.js";
@@ -121,6 +122,7 @@ export function registerAllCommands(program) {
     registerCloudCommands(syncCmd);
     registerSyncModeCommand(syncCmd);
     registerSyncNarrowCommand(syncCmd);
+    registerSyncManifestCommand(syncCmd);
     // Cloud provisioning subcommand group (entity + bucket + initial sync)
     // Distinct from `hq sync` which assumes provisioning has already happened.
     const cloudCmd = program

package/dist/startup-registration.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The command-registration recovery seam for the "install tree torn out from
+ * under a starting `hq`" condition (Sentry HQ-CLI-1G/1H/1J/1K).
+ *
+ * `runCli` registers commands as its last step before `program.parseAsync()` —
+ * the lazy command import or `import("./register-all.js")` and everything those
+ * pull in. That is the ONE place a module-resolution failure is provably safe to
+ * recover from: it is inside hq-cli's own graph, it runs before `parseAsync` and
+ * before the preAction hook, so no command action, telemetry, or stdin read has
+ * happened yet, and a single re-exec can therefore never run a command twice.
+ *
+ * This wraps the existing `register()` call with exactly that recovery, driven by
+ * the classifier / probe / settle wait / carrier in ./utils/install-tree-torn.ts.
+ * It changes nothing about WHICH modules are imported or in what order — only the
+ * failure handling around the existing imports. Dependency-injected in the house
+ * style of handleTopLevelError so the whole seam is unit-testable without real
+ * spawns, waits, or a real install tree.
+ */
+import { type WaitForInstallTreeSettledArgs, type WaitForInstallTreeSettledResult } from "./utils/install-tree-torn.js";
+/**
+ * Set on the re-exec'd child so it can NEVER wait or re-exec again — distinct
+ * from self-update's HQ_RESCUE_SELF_UPDATED so the two recovery paths cannot
+ * shadow each other.
+ */
+export declare const INSTALL_TREE_RECOVERY_GUARD_ENV = "HQ_INSTALL_TREE_RECOVERED";
+/** Operator override for the settle wait's deadline. */
+export declare const INSTALL_SETTLE_TIMEOUT_ENV = "HQ_INSTALL_SETTLE_TIMEOUT_MS";
+/** Default settle deadline (ms). Overridable by {@link INSTALL_SETTLE_TIMEOUT_ENV}. */
+export declare const DEFAULT_INSTALL_SETTLE_TIMEOUT_MS = 90000;
+/**
+ * The single dim, informational line emitted when — and only when — a wait
+ * actually happens. It tells a human why the command paused and is the e2e's
+ * synchronization point; it is never a remedy and never sets an error exit code.
+ */
+export declare const INSTALL_TREE_WAIT_NOTICE = "hq: the hq-cli install is being updated underneath this command; waiting for it to finish\u2026";
+/** Resolve the settle deadline from the environment (0 = evaluate once; default on invalid). */
+export declare function resolveSettleTimeoutMs(env: NodeJS.ProcessEnv): number;
+/** Minimal view of a `spawnSync` result the seam relies on. */
+export interface RecoverySpawnResult {
+    status: number | null;
+    error?: Error;
+}
+export interface RegisterRecoveryDeps {
+    spawn?: (command: string, args: string[], options: {
+        stdio: "inherit";
+        env: NodeJS.ProcessEnv;
+    }) => RecoverySpawnResult;
+    resolveInstall?: () => {
+        packageRoot: string | null;
+    };
+    lockPath?: () => string;
+    waitForSettled?: (args: WaitForInstallTreeSettledArgs) => Promise<WaitForInstallTreeSettledResult>;
+    /** node flags to forward to the re-exec child (defaults to process.execArgv). */
+    execArgv?: readonly string[];
+}
+export interface RegisterCommandsWithRecoveryArgs {
+    /** Runs the existing registration (lazy command import or register-all import). */
+    register: () => Promise<void>;
+    argv: readonly string[];
+    env: NodeJS.ProcessEnv;
+    /** The RUNNING install's own `dist/index.js` — the safe re-exec target. */
+    entryPath: string;
+    stderr: Pick<typeof process.stderr, "write">;
+    deps?: RegisterRecoveryDeps;
+}
+export interface RegisterCommandsWithRecoveryResult {
+    /** Set only when a re-exec ran: its exit status becomes this invocation's. */
+    reexecStatus?: number;
+}
+/**
+ * Register commands, recovering once from a torn-install module-resolution
+ * failure. On a clean registration this returns `{}` and touches nothing else.
+ * On a classified failure it waits (bounded) for the install to settle and
+ * re-execs the running install's own entrypoint once; a child (guarded), an
+ * unsettled wait, or a failed spawn each throws an {@link InstallTreeTornError}
+ * carrying bounded diagnostics so a genuinely broken install stays visible.
+ */
+export declare function registerCommandsWithRecovery(args: RegisterCommandsWithRecoveryArgs): Promise<RegisterCommandsWithRecoveryResult>;
+//# sourceMappingURL=startup-registration.d.ts.map