@indigoai-us/hq-cli 5.108.17 → 5.108.19

package/CHANGELOG.md

@@ -2,8 +2,46 @@
 
 ## [Unreleased]
 
+## [5.108.19] — 2026-09-07
+
+## [5.108.18] — 2026-09-07
+
+### Fixed
+
+- A global `hq` reinstall running underneath a starting command no longer
+  crashes it (Sentry HQ-CLI-1G/1H/1J/1K — 7713386011, 7713482655, 7713783135,
+  7714501738). `hq` resolves most of its command graph lazily as its first real
+  step, so when an external updater — the outpost `hq-cli-update` timer, an
+  agent box's self-update, or the desktop app — renames the installed package
+  aside and re-extracts it file by file (~16s every 6h on every box), a command
+  that started a moment earlier resolved a deferred import against a directory
+  that no longer held it and died with `ERR_MODULE_NOT_FOUND` /
+  `MODULE_NOT_FOUND`, filing a separate high-priority crash for each missing
+  path. hq-cli cannot stop the foreign updater, but the registration phase is
+  provably side-effect free (it runs before any command action), so a
+  resolution failure there is now caught: the CLI prints one informational line,
+  waits — bounded, default 90s, `HQ_INSTALL_SETTLE_TIMEOUT_MS` to override — for
+  the install to settle (shared update lock released, the missing target back,
+  the retired `.hq-cli-*` sibling gone, a healthy manifest), and then re-runs
+  the command once on the settled tree. A genuinely broken or incomplete install
+  still reports exactly once, with a reinstall remedy naming the missing module
+  and bounded diagnostics, so real packaging faults stay visible. The recovery
+  re-execs at most once per invocation and never runs a command twice.
+
 ## [5.108.17] — 2026-09-07
 
+### Fixed
+
+- The Work Mesh Live daemon's transcript watcher no longer rescans every file
+  under `~/.claude/projects` and `~/.codex/sessions` every 15 seconds. It keeps a
+  per-directory mtime cache and only relists directories that changed, re-stats
+  recently active files, revalidates every cached directory at least every five
+  minutes (content appends do not change a directory's mtime, so a session that
+  resumes after idling is still picked up), backs the interval off from 30 s to
+  120 s on busy machines, caps the entries examined per tick with per-root
+  budgets, never runs two ticks at once, and bounds its cache. Capped ticks skip
+  disappearance reconciliation so an unvisited session is never ended falsely.
+
 ## [5.108.16] — 2026-09-07
 
 ### Fixed
@@ -41,15 +79,6 @@
   at most every five minutes, and `held.jsonl` is capped at 20,000 lines with
   the oldest overflow dead-lettered as `HELD_OVERFLOW` (loss-free under failure
   and concurrent flushers). (#525)
-- The Work Mesh Live daemon's transcript watcher no longer rescans every file
-  under `~/.claude/projects` and `~/.codex/sessions` every 15 seconds. It keeps a
-  per-directory mtime cache and only relists directories that changed, re-stats
-  recently active files, revalidates every cached directory at least every five
-  minutes (content appends do not change a directory's mtime, so a session that
-  resumes after idling is still picked up), backs the interval off from 30 s to
-  120 s on busy machines, caps the entries examined per tick with per-root
-  budgets, never runs two ticks at once, and bounds its cache. Capped ticks skip
-  disappearance reconciliation so an unvisited session is never ended falsely.
 
 ## [5.108.14] — 2026-09-07
 
@@ -81,15 +110,6 @@
   `incomplete_install` context so the next occurrence is attributable. The drop
   is wired both at the top-level boundary and in the shared `beforeSend`, so it
   covers every capture route.
-- The Work Mesh Live daemon's transcript watcher no longer rescans every file
-  under `~/.claude/projects` and `~/.codex/sessions` every 15 seconds. It keeps a
-  per-directory mtime cache and only relists directories that changed, re-stats
-  recently active files, revalidates every cached directory at least every five
-  minutes (content appends do not change a directory's mtime, so a session that
-  resumes after idling is still picked up), backs the interval off from 30 s to
-  120 s on busy machines, caps the entries examined per tick with per-root
-  budgets, never runs two ticks at once, and bounds its cache. Capped ticks skip
-  disappearance reconciliation so an unvisited session is never ended falsely.
 
 ## [5.108.13] — 2026-09-06
 

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