@indigoai-us/hq-cli 5.108.18 → 5.108.19

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.108.19] — 2026-09-07
+
 ## [5.108.18] — 2026-09-07
 
 ### Fixed

package/dist/commands/sync-manifest.d.ts

@@ -0,0 +1,213 @@
+/**
+ * `hq sync manifest` (sync-reconciliation-audit US-004) — the CLI half of the
+ * shared client-side manifest upload pass.
+ *
+ * WHAT THIS FILE OWNS, AND WHAT IT DELIBERATELY DOES NOT
+ * -----------------------------------------------------
+ * All of the SAFETY rules for an upload pass (sequence monotonicity, when a
+ * snapshot may become a delta base, `resend_full` handling, chunk-header
+ * identity, the 24h throttle, the per-scope lock) live in hq-cloud's
+ * {@link runManifestUploadPass}. Duplicating any of them here would let the
+ * CLI and the hq-sync daemon drift, and the failure mode of that drift is
+ * silent server-side corruption of a scope's materialised view — the exact
+ * thing this audit exists to detect.
+ *
+ * This file therefore owns only the three things hq-cloud refuses to own:
+ *
+ *   1. **Auth + base URL.** The transport is injected; we build it from the
+ *      CLI's own Cognito session and `vaultApiFetch`'s base-URL resolution.
+ *   2. **Scope resolution.** `personal` vs. a company SLUG → the `companyUid`
+ *      the wire contract wants, resolved the same way `hq sync mode` does
+ *      (memberships + `entity.get`), so both commands agree on what
+ *      `--company frogbear` means.
+ *   3. **Human output + exit codes.** The seam never throws for a runtime
+ *      condition; it returns a status. Only `failed` is a non-zero exit —
+ *      `disabled`, `throttled`, `soft_skipped` and `locked` are all normal,
+ *      expected outcomes of asking for a pass, and exiting non-zero on them
+ *      would make the command unusable from a wrapper script.
+ *
+ * IDENTITY JOIN
+ * -------------
+ * `installationId` comes from {@link loadClientHealthState} — the SAME value
+ * the client-health heartbeat reports. Minting a second id here would produce
+ * manifest rows that cannot be joined to the heartbeat rows for the same
+ * machine, which is most of the value of the audit.
+ *
+ * Cross-package note: this command depends on `runManifestUploadPass` /
+ * `readManifestUploadStatus`, added in the hq-cloud sync-reconciliation-audit
+ * branch and NOT yet published. While that is true, package.json carries a
+ * `pnpm.overrides` link to the local hq-cloud worktree; that override must be
+ * removed and the `@indigoai-us/hq-cloud` pin bumped from `~6.16.6` to the
+ * release containing these exports before this branch can merge.
+ */
+import { Command } from "commander";
+import type { ManifestUploadTransport, RunManifestUploadPassOptions, RunManifestUploadPassResult } from "@indigoai-us/hq-cloud";
+/** The server route the pass POSTs each chunk to. */
+export declare const MANIFEST_UPLOAD_PATH = "/v1/sync-manifest/upload";
+/**
+ * The kill switch hq-cloud's pass honours. Restated locally (rather than
+ * imported) for two reasons: it lives in the same unreleased module as the
+ * manifest exports, and — more importantly — we must be able to read it
+ * BEFORE deciding to do any work at all.
+ */
+export declare const MANIFEST_DISABLED_ENV = "HQ_SYNC_MANIFEST_DISABLED";
+/** True when the kill switch is set to anything other than empty/0/false. */
+export declare function manifestUploadsDisabled(env?: NodeJS.ProcessEnv): boolean;
+/** The literal `--scope` value that selects the personal (non-company) tree. */
+export declare const PERSONAL_SCOPE = "personal";
+/**
+ * The scope shape the upload pass wants. Structurally identical to hq-cloud's
+ * `BuildManifestScope`, restated locally so the resolver is unit-testable
+ * without importing the builder's whole module graph.
+ */
+export interface ResolvedManifestScope {
+    kind: "personal" | "company";
+    companyUid?: string;
+    slug?: string;
+}
+/** Subset of `VaultClient` the slug → uid resolution needs (test seam). */
+export interface SyncManifestVaultClient {
+    listMyMemberships(): Promise<{
+        companyUid: string;
+    }[]>;
+    entity: {
+        get(uid: string): Promise<{
+            uid: string;
+            slug: string;
+        }>;
+    };
+}
+/**
+ * Everything the orchestrator touches that is not a pure function. Injected so
+ * the command is testable without a Cognito session, a network, an HQ tree, or
+ * (critically) the real per-scope lock the seam takes under `~/.hq/locks`.
+ */
+export interface SyncManifestDeps {
+    /** hq-cloud's shared upload pass. */
+    runPass: (options: RunManifestUploadPassOptions) => Promise<RunManifestUploadPassResult>;
+    /** Resolves a company slug to its uid. Only called for company scopes. */
+    resolveCompanyUid: (slug: string) => Promise<string>;
+    /** The HQ state dir holding the client-health state and snapshot store. */
+    stateDir: () => string;
+    /** The stable installation identity, shared with the health heartbeat. */
+    installationId: (stateDir: string) => string;
+    /** This machine's stable, non-fingerprint id. */
+    machineId: () => string;
+    /** Builds the authed transport. Not called on `--print` (nothing is sent). */
+    transport: () => Promise<ManifestUploadTransport>;
+    /** stdout sink — captured in tests. */
+    log: (line: string) => void;
+}
+export interface RunSyncManifestOptions {
+    scopeArg?: string;
+    hqRoot: string;
+    full?: boolean;
+    print?: boolean;
+    /**
+     * Honour hq-cloud's 24h per-scope throttle. Off by default: see
+     * {@link runSyncManifest}. Set by `--respect-throttle`, which is what a cron
+     * wrapper wants — it makes the CLI behave like the daemon's cadence instead
+     * of forcing a pass on every tick.
+     */
+    respectThrottle?: boolean;
+}
+export interface RunSyncManifestOutcome {
+    result: RunManifestUploadPassResult;
+    scope: ResolvedManifestScope;
+    /** Process exit code — non-zero ONLY for a genuine `failed` pass. */
+    exitCode: number;
+}
+/**
+ * Resolve `--scope` into the wire scope.
+ *
+ * `personal` is the literal; anything else is a company SLUG, which must be
+ * turned into the server's `companyUid` — the contract carries the uid, while
+ * the local walk needs the slug (it names `companies/{slug}` and the journal
+ * shard), so BOTH end up on the resolved scope.
+ *
+ * With no `--scope`, we fall back to the active company recorded in
+ * `<hq-root>/.hq/config.json` (the same source `hq sync mode` uses), and to
+ * `personal` when there is no active company — a CLI-only install with no
+ * company still has a personal tree worth auditing.
+ */
+export declare function resolveManifestScope(scopeArg: string | undefined, hqRoot: string, resolveCompanyUid: (slug: string) => Promise<string>): Promise<ResolvedManifestScope>;
+/**
+ * A stable, human-meaningless machine id.
+ *
+ * Precedence mirrors the rest of the CLI's "ask the installer first" habit:
+ * the id HQ Sync recorded in `~/.hq/menubar.json` if there is one (so the
+ * daemon's manifests and the CLI's manifests report the SAME machine), then a
+ * sanitised hostname, then a constant. It is explicitly not a hardware
+ * fingerprint — the contract only needs it to be stable and opaque-ish.
+ */
+export declare function resolveMachineId(hqConfigDir?: string, hostname?: () => string): string;
+/**
+ * Coerce to the contract's identifier charset (`[A-Za-z0-9][A-Za-z0-9_.:-]*`,
+ * 2..64). Returns undefined when nothing usable survives, so the caller can
+ * fall through rather than send a value the server will reject.
+ */
+export declare function sanitiseIdentifier(raw: string): string | undefined;
+/** Human label for a resolved scope — what the summary line names. */
+export declare function describeScope(scope: ResolvedManifestScope): string;
+/**
+ * One-line-per-fact summary of a non-print pass.
+ *
+ * Every non-`failed` status gets an explanatory sentence rather than a bare
+ * enum: `throttled` and `soft_skipped` in particular are the statuses a user
+ * is most likely to see and most likely to misread as a failure.
+ */
+export declare function formatManifestSummary(result: RunManifestUploadPassResult, scope: ResolvedManifestScope): string;
+/**
+ * POST one chunk with the caller's Cognito bearer.
+ *
+ * It RESOLVES for every HTTP answer, including 4xx/5xx: the seam classifies
+ * status codes itself (a 200 can still carry a protocol-level `resend_full`,
+ * and a 409 means something quite specific), so throwing here would collapse
+ * all of that into an undifferentiated `transport_error`. A body that will not
+ * parse as JSON is passed through as `undefined` rather than failing the pass
+ * — the status is the load-bearing part.
+ */
+export declare function createManifestTransport(token: string): ManifestUploadTransport;
+/**
+ * Read (and, when it had to be minted, persist) the installation id shared
+ * with the client-health heartbeat. Persisting matters: `loadClientHealthState`
+ * degrades a missing/corrupt file to a FRESH id, so a first run that did not
+ * write it back would report a different installation on every invocation and
+ * the manifest rows would never join to anything.
+ */
+export declare function defaultInstallationId(stateDir: string): string;
+/** Max concurrent `entity.get` calls when resolving a slug to a companyUid. */
+export declare const MEMBERSHIP_RESOLVE_CONCURRENCY = 4;
+/**
+ * `Promise.all`-shaped map with a hard ceiling on in-flight work. Results keep
+ * input order, so callers can still index by position.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/**
+ * Production wiring. Built lazily per invocation because both the vault client
+ * and the transport need a Cognito token, and `--print` must work without one
+ * (it uploads nothing, so demanding a login would be gratuitous).
+ */
+export declare function createDefaultDeps(): SyncManifestDeps;
+/**
+ * Resolve the scope, run one upload pass, print, and decide the exit code.
+ *
+ * `--print` short-circuits the transport entirely (it is never built, so no
+ * token is required) and hands the seam `dryRun: true`, which builds the
+ * chunks without persisting a snapshot. The chunks go to stdout as JSON and
+ * nothing else is printed, so the output is pipeable into `jq`.
+ *
+ * An explicit invocation passes `ignoreThrottle: true`: a human typing
+ * `hq sync manifest` has asked for a pass NOW, and the 24h throttle exists to
+ * protect the daemon's automatic cadence, not to argue with the user. That
+ * default is deliberately unchanged — `--respect-throttle` opts back into it
+ * for scripted/scheduled callers, which are the only ones that should be
+ * bound by a cadence they did not personally ask to skip.
+ */
+export declare function runSyncManifest(options: RunSyncManifestOptions, deps: SyncManifestDeps): Promise<RunSyncManifestOutcome>;
+/**
+ * Wire `hq sync manifest` onto the existing `sync` Commander group, alongside
+ * `mode` and `narrow`.
+ */
+export declare function registerSyncManifestCommand(syncCmd: Command): void;
+//# sourceMappingURL=sync-manifest.d.ts.map

package/dist/commands/sync-manifest.js

@@ -0,0 +1,384 @@
+/**
+ * `hq sync manifest` (sync-reconciliation-audit US-004) — the CLI half of the
+ * shared client-side manifest upload pass.
+ *
+ * WHAT THIS FILE OWNS, AND WHAT IT DELIBERATELY DOES NOT
+ * -----------------------------------------------------
+ * All of the SAFETY rules for an upload pass (sequence monotonicity, when a
+ * snapshot may become a delta base, `resend_full` handling, chunk-header
+ * identity, the 24h throttle, the per-scope lock) live in hq-cloud's
+ * {@link runManifestUploadPass}. Duplicating any of them here would let the
+ * CLI and the hq-sync daemon drift, and the failure mode of that drift is
+ * silent server-side corruption of a scope's materialised view — the exact
+ * thing this audit exists to detect.
+ *
+ * This file therefore owns only the three things hq-cloud refuses to own:
+ *
+ *   1. **Auth + base URL.** The transport is injected; we build it from the
+ *      CLI's own Cognito session and `vaultApiFetch`'s base-URL resolution.
+ *   2. **Scope resolution.** `personal` vs. a company SLUG → the `companyUid`
+ *      the wire contract wants, resolved the same way `hq sync mode` does
+ *      (memberships + `entity.get`), so both commands agree on what
+ *      `--company frogbear` means.
+ *   3. **Human output + exit codes.** The seam never throws for a runtime
+ *      condition; it returns a status. Only `failed` is a non-zero exit —
+ *      `disabled`, `throttled`, `soft_skipped` and `locked` are all normal,
+ *      expected outcomes of asking for a pass, and exiting non-zero on them
+ *      would make the command unusable from a wrapper script.
+ *
+ * IDENTITY JOIN
+ * -------------
+ * `installationId` comes from {@link loadClientHealthState} — the SAME value
+ * the client-health heartbeat reports. Minting a second id here would produce
+ * manifest rows that cannot be joined to the heartbeat rows for the same
+ * machine, which is most of the value of the audit.
+ *
+ * Cross-package note: this command depends on `runManifestUploadPass` /
+ * `readManifestUploadStatus`, added in the hq-cloud sync-reconciliation-audit
+ * branch and NOT yet published. While that is true, package.json carries a
+ * `pnpm.overrides` link to the local hq-cloud worktree; that override must be
+ * removed and the `@indigoai-us/hq-cloud` pin bumped from `~6.16.6` to the
+ * release containing these exports before this branch can merge.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import chalk from "chalk";
+// `VaultClient` has shipped for many releases and is safe to import by name.
+// The manifest exports are NOT: they are absent from the published hq-cloud,
+// and a static named import of a missing ESM export is a link-time
+// SyntaxError. They are feature-detected instead. Type-only imports are erased
+// at runtime and so cost nothing here.
+import { VaultClient } from "@indigoai-us/hq-cloud";
+import { MANIFEST_MIN_HQ_CLOUD_VERSION, manifestExportsAvailable, requireManifestExports, } from "../lib/hq-cloud-manifest.js";
+import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
+import { loadClientHealthState, persistClientHealthState, } from "../utils/client-health.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { readActiveCompanySlug } from "./sync-mode.js";
+// ── Constants ───────────────────────────────────────────────────────────────
+/** The server route the pass POSTs each chunk to. */
+export const MANIFEST_UPLOAD_PATH = "/v1/sync-manifest/upload";
+/**
+ * The kill switch hq-cloud's pass honours. Restated locally (rather than
+ * imported) for two reasons: it lives in the same unreleased module as the
+ * manifest exports, and — more importantly — we must be able to read it
+ * BEFORE deciding to do any work at all.
+ */
+export const MANIFEST_DISABLED_ENV = "HQ_SYNC_MANIFEST_DISABLED";
+/** True when the kill switch is set to anything other than empty/0/false. */
+export function manifestUploadsDisabled(env = process.env) {
+    const raw = env[MANIFEST_DISABLED_ENV];
+    if (raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return value !== "" && value !== "0" && value !== "false";
+}
+/** The literal `--scope` value that selects the personal (non-company) tree. */
+export const PERSONAL_SCOPE = "personal";
+// ── Pure helpers ────────────────────────────────────────────────────────────
+/**
+ * Resolve `--scope` into the wire scope.
+ *
+ * `personal` is the literal; anything else is a company SLUG, which must be
+ * turned into the server's `companyUid` — the contract carries the uid, while
+ * the local walk needs the slug (it names `companies/{slug}` and the journal
+ * shard), so BOTH end up on the resolved scope.
+ *
+ * With no `--scope`, we fall back to the active company recorded in
+ * `<hq-root>/.hq/config.json` (the same source `hq sync mode` uses), and to
+ * `personal` when there is no active company — a CLI-only install with no
+ * company still has a personal tree worth auditing.
+ */
+export async function resolveManifestScope(scopeArg, hqRoot, resolveCompanyUid) {
+    const requested = scopeArg?.trim() || readActiveCompanySlug(hqRoot) || PERSONAL_SCOPE;
+    if (requested === PERSONAL_SCOPE)
+        return { kind: "personal" };
+    const companyUid = await resolveCompanyUid(requested);
+    return { kind: "company", companyUid, slug: requested };
+}
+/**
+ * A stable, human-meaningless machine id.
+ *
+ * Precedence mirrors the rest of the CLI's "ask the installer first" habit:
+ * the id HQ Sync recorded in `~/.hq/menubar.json` if there is one (so the
+ * daemon's manifests and the CLI's manifests report the SAME machine), then a
+ * sanitised hostname, then a constant. It is explicitly not a hardware
+ * fingerprint — the contract only needs it to be stable and opaque-ish.
+ */
+export function resolveMachineId(hqConfigDir = path.join(os.homedir(), ".hq"), 
+// Injected rather than spied: `node:os` is an ESM namespace and cannot be
+// redefined by `vi.spyOn`, so the fallback branches would be untestable.
+hostname = os.hostname) {
+    const fromMenubar = readMenubarMachineId(hqConfigDir);
+    if (fromMenubar)
+        return fromMenubar;
+    const host = sanitiseIdentifier(hostname());
+    return host ?? "unknown-machine";
+}
+function readMenubarMachineId(hqConfigDir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(hqConfigDir, "menubar.json"), "utf-8"));
+        const raw = parsed?.machineId;
+        return typeof raw === "string" ? sanitiseIdentifier(raw) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Coerce to the contract's identifier charset (`[A-Za-z0-9][A-Za-z0-9_.:-]*`,
+ * 2..64). Returns undefined when nothing usable survives, so the caller can
+ * fall through rather than send a value the server will reject.
+ */
+export function sanitiseIdentifier(raw) {
+    const cleaned = raw.replace(/[^A-Za-z0-9_.:-]/g, "-").slice(0, 64);
+    if (!/^[A-Za-z0-9]/.test(cleaned) || cleaned.length < 2)
+        return undefined;
+    return cleaned;
+}
+/** Human label for a resolved scope — what the summary line names. */
+export function describeScope(scope) {
+    return scope.kind === "personal"
+        ? PERSONAL_SCOPE
+        : `${scope.slug ?? "company"} (${scope.companyUid ?? "?"})`;
+}
+/**
+ * One-line-per-fact summary of a non-print pass.
+ *
+ * Every non-`failed` status gets an explanatory sentence rather than a bare
+ * enum: `throttled` and `soft_skipped` in particular are the statuses a user
+ * is most likely to see and most likely to misread as a failure.
+ */
+export function formatManifestSummary(result, scope) {
+    const where = describeScope(scope);
+    switch (result.status) {
+        case "uploaded":
+            return `${chalk.green("✓")} Manifest uploaded for ${chalk.bold(where)} — ${result.mode ?? "?"} mode, ${result.uploadedChunks ?? 0}/${result.chunkCount ?? 0} chunk(s)${result.snapshotId ? `, snapshot ${result.snapshotId}` : ""}.`;
+        case "resend_full_scheduled":
+            return `${chalk.yellow("!")} Server asked for a fresh baseline for ${chalk.bold(where)} — the next pass will send a full manifest.`;
+        case "throttled":
+            return `${chalk.dim("·")} Skipped for ${chalk.bold(where)}: a manifest was uploaded recently (24h throttle). Nothing to do.`;
+        case "disabled":
+            return `${chalk.dim("·")} Manifest uploads are disabled on this machine (HQ_SYNC_MANIFEST_DISABLED).`;
+        case "soft_skipped":
+            return `${chalk.dim("·")} Skipped for ${chalk.bold(where)}: preconditions for a manifest pass are not met on this machine.`;
+        case "locked":
+            return `${chalk.dim("·")} Another manifest pass for ${chalk.bold(where)} is already running. Nothing to do.`;
+        case "printed":
+            return `${chalk.dim("·")} Built ${result.chunkCount ?? 0} chunk(s) for ${chalk.bold(where)} — nothing uploaded (--print).`;
+        case "failed":
+        default:
+            return `${chalk.red("✗")} Manifest pass failed for ${chalk.bold(where)}: ${result.error?.kind ?? "unknown"}${result.error?.status ? ` (HTTP ${result.error.status})` : ""}${result.error?.detail ? ` — ${result.error.detail}` : ""}`;
+    }
+}
+// ── Transport ───────────────────────────────────────────────────────────────
+/**
+ * POST one chunk with the caller's Cognito bearer.
+ *
+ * It RESOLVES for every HTTP answer, including 4xx/5xx: the seam classifies
+ * status codes itself (a 200 can still carry a protocol-level `resend_full`,
+ * and a 409 means something quite specific), so throwing here would collapse
+ * all of that into an undifferentiated `transport_error`. A body that will not
+ * parse as JSON is passed through as `undefined` rather than failing the pass
+ * — the status is the load-bearing part.
+ */
+export function createManifestTransport(token) {
+    return async (chunk) => {
+        const response = await vaultApiFetch({
+            token,
+            path: MANIFEST_UPLOAD_PATH,
+            method: "POST",
+            body: chunk,
+        });
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = undefined;
+        }
+        return { status: response.status, body };
+    };
+}
+// ── Default dependencies ────────────────────────────────────────────────────
+/**
+ * Read (and, when it had to be minted, persist) the installation id shared
+ * with the client-health heartbeat. Persisting matters: `loadClientHealthState`
+ * degrades a missing/corrupt file to a FRESH id, so a first run that did not
+ * write it back would report a different installation on every invocation and
+ * the manifest rows would never join to anything.
+ */
+export function defaultInstallationId(stateDir) {
+    const state = loadClientHealthState(stateDir);
+    persistClientHealthState(stateDir, state);
+    return state.installationId;
+}
+/** Max concurrent `entity.get` calls when resolving a slug to a companyUid. */
+export const MEMBERSHIP_RESOLVE_CONCURRENCY = 4;
+/**
+ * `Promise.all`-shaped map with a hard ceiling on in-flight work. Results keep
+ * input order, so callers can still index by position.
+ */
+export async function mapWithConcurrency(items, limit, worker) {
+    const results = new Array(items.length);
+    let next = 0;
+    const runners = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await worker(items[index], index);
+        }
+    });
+    await Promise.all(runners);
+    return results;
+}
+function defaultResolveCompanyUid(client) {
+    return async (slug) => {
+        const vault = await client();
+        const memberships = await vault.listMyMemberships();
+        // Bounded fan-out: a `Promise.all` over every membership fires one
+        // `entity.get` per company at once, which on a heavily-membered account is
+        // a self-inflicted burst against the vault API (and the first thing to get
+        // rate-limited). Four in flight keeps it brisk without stampeding.
+        const resolved = await mapWithConcurrency(memberships, MEMBERSHIP_RESOLVE_CONCURRENCY, async (m) => {
+            try {
+                const entity = await vault.entity.get(m.companyUid);
+                return { uid: m.companyUid, slug: entity.slug };
+            }
+            catch {
+                return { uid: m.companyUid, slug: undefined };
+            }
+        });
+        const match = resolved.find((row) => row.slug === slug);
+        if (!match) {
+            const known = resolved
+                .map((r) => r.slug)
+                .filter((s) => !!s)
+                .join(", ");
+            throw new Error(`No membership found for company '${slug}'. Memberships visible to you: ${known || "(none)"}.`);
+        }
+        return match.uid;
+    };
+}
+/**
+ * Production wiring. Built lazily per invocation because both the vault client
+ * and the transport need a Cognito token, and `--print` must work without one
+ * (it uploads nothing, so demanding a login would be gratuitous).
+ */
+export function createDefaultDeps() {
+    let cachedToken;
+    const token = () => (cachedToken ??= ensureCognitoToken());
+    const vaultClient = async () => new VaultClient(buildVaultConfig(await token()));
+    // Throws ManifestUnsupportedError on an hq-cloud that predates the manifest
+    // exports. The CLI action checks availability first and prints a clean
+    // requirement message, so this is the belt-and-braces path.
+    const manifest = requireManifestExports();
+    return {
+        runPass: (options) => manifest.runManifestUploadPass(options),
+        resolveCompanyUid: defaultResolveCompanyUid(vaultClient),
+        stateDir: () => manifest.getStateDir(),
+        installationId: defaultInstallationId,
+        machineId: () => resolveMachineId(),
+        transport: async () => createManifestTransport(await token()),
+        log: (line) => console.log(line),
+    };
+}
+// ── Orchestrator ────────────────────────────────────────────────────────────
+/**
+ * Resolve the scope, run one upload pass, print, and decide the exit code.
+ *
+ * `--print` short-circuits the transport entirely (it is never built, so no
+ * token is required) and hands the seam `dryRun: true`, which builds the
+ * chunks without persisting a snapshot. The chunks go to stdout as JSON and
+ * nothing else is printed, so the output is pipeable into `jq`.
+ *
+ * An explicit invocation passes `ignoreThrottle: true`: a human typing
+ * `hq sync manifest` has asked for a pass NOW, and the 24h throttle exists to
+ * protect the daemon's automatic cadence, not to argue with the user. That
+ * default is deliberately unchanged — `--respect-throttle` opts back into it
+ * for scripted/scheduled callers, which are the only ones that should be
+ * bound by a cadence they did not personally ask to skip.
+ */
+export async function runSyncManifest(options, deps) {
+    // KILL SWITCH FIRST — before scope resolution, before the state dir, and
+    // above all before `deps.transport()`, which mints a Cognito session and can
+    // block for minutes on a machine with no usable credentials. The seam also
+    // honours this env var, but only after we have already paid for auth, so
+    // "disabled" used to mean "hang, then do nothing". Disabled is a normal,
+    // expected outcome: exit 0.
+    if (manifestUploadsDisabled()) {
+        const result = {
+            status: "disabled",
+            scopeKey: "unknown",
+        };
+        deps.log(`${chalk.dim("·")} Manifest upload disabled by ${MANIFEST_DISABLED_ENV} — nothing to do.`);
+        return { result, scope: { kind: "personal" }, exitCode: 0 };
+    }
+    const scope = await resolveManifestScope(options.scopeArg, options.hqRoot, deps.resolveCompanyUid);
+    const stateDir = deps.stateDir();
+    const print = options.print === true;
+    const result = await deps.runPass({
+        scope,
+        hqRoot: options.hqRoot,
+        stateDir,
+        installationId: deps.installationId(stateDir),
+        machineId: deps.machineId(),
+        source: "cli",
+        // `--print` uploads nothing; a no-op transport keeps us from demanding a
+        // Cognito session for a purely local build.
+        transport: print
+            ? () => Promise.resolve({ status: 0 })
+            : await deps.transport(),
+        dryRun: print,
+        forceFull: options.full === true,
+        ignoreThrottle: options.respectThrottle !== true,
+    });
+    if (print) {
+        deps.log(JSON.stringify(result.chunks ?? [], null, 2));
+    }
+    else {
+        deps.log(formatManifestSummary(result, scope));
+    }
+    return { result, scope, exitCode: result.status === "failed" ? 1 : 0 };
+}
+/**
+ * Wire `hq sync manifest` onto the existing `sync` Commander group, alongside
+ * `mode` and `narrow`.
+ */
+export function registerSyncManifestCommand(syncCmd) {
+    syncCmd
+        .command("manifest")
+        .description("Upload a file manifest for the sync reconciliation audit (personal or a company scope)")
+        .option("--scope <scope>", `'${PERSONAL_SCOPE}' or a company slug (defaults to the active company, else ${PERSONAL_SCOPE})`)
+        .option("--full", "Send a fresh full baseline instead of a delta")
+        .option("--print", "Build and print the chunks as JSON; upload nothing")
+        .option("--respect-throttle", "Honour the 24h per-scope upload throttle instead of forcing a pass (for scheduled callers)")
+        .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
+        .action(async (options) => {
+        // Capability gate BEFORE anything else: on a published hq-cloud that
+        // predates the manifest exports this command cannot work, and the honest
+        // answer is a one-line requirement, not a stack trace.
+        if (!manifestExportsAvailable()) {
+            console.error(chalk.red("✗ sync manifest is unavailable:"), `this command requires an hq-cloud release with manifest support (>= ${MANIFEST_MIN_HQ_CLOUD_VERSION}); the installed @indigoai-us/hq-cloud does not export the manifest upload pass.`);
+            process.exit(1);
+            return;
+        }
+        try {
+            const outcome = await runSyncManifest({
+                scopeArg: options.scope,
+                hqRoot: options.hqRoot,
+                full: options.full,
+                print: options.print,
+                respectThrottle: options.respectThrottle,
+            }, createDefaultDeps());
+            if (outcome.exitCode !== 0)
+                process.exit(outcome.exitCode);
+        }
+        catch (err) {
+            console.error(chalk.red("✗ sync manifest failed:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=sync-manifest.js.map

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/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/package.json

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