@indigoai-us/hq-cli 5.345.6 → 5.345.8

package/dist/lib/lanes/wait.d.ts

@@ -1,11 +1,7 @@
 import type { LaneRecord, QuestionRecord } from "./types.js";
-export declare const LANE_WAIT_POLL_INTERVAL_MS = 2000;
-export declare const LANE_WAIT_MAX_LANES = 64;
 export declare const LANE_WAIT_TIMEOUT_EXIT_CODE = 4;
 export declare const LANE_WAIT_INVALID_INPUT_EXIT_CODE = 2;
-export declare const LANE_WAIT_CHANGE_TYPES: readonly ["envelope", "question", "state"];
-export type LaneWaitChangeType = (typeof LANE_WAIT_CHANGE_TYPES)[number];
-export type LaneWaitChange = {
+type LaneWaitChange = {
     type: "envelope";
     ref: string;
     decision: "done" | "ask" | "blocked";
@@ -36,4 +32,5 @@ export interface LaneWaitDeps {
  * lock. Question records are scanned in one pass when question changes matter.
  */
 export declare function runLaneWait(hqRoot: string, laneIds: readonly string[], changeTypes: readonly string[], timeoutMs: number, deps?: LaneWaitDeps): Promise<LaneWaitResult | null>;
+export {};
 //# sourceMappingURL=wait.d.ts.map

package/dist/lib/lanes/wait.js

@@ -1,10 +1,10 @@
 import { listQuestionIds, readLane, readQuestion } from "./store.js";
 import { LanesError } from "./errors.js";
-export const LANE_WAIT_POLL_INTERVAL_MS = 2_000;
-export const LANE_WAIT_MAX_LANES = 64;
+const LANE_WAIT_POLL_INTERVAL_MS = 2_000;
+const LANE_WAIT_MAX_LANES = 64;
 export const LANE_WAIT_TIMEOUT_EXIT_CODE = 4;
 export const LANE_WAIT_INVALID_INPUT_EXIT_CODE = 2;
-export const LANE_WAIT_CHANGE_TYPES = ["envelope", "question", "state"];
+const LANE_WAIT_CHANGE_TYPES = ["envelope", "question", "state"];
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/lib/local-tree-diff.d.ts

@@ -24,8 +24,8 @@
  * for the destructive side effects (delete, tombstone, PUT sync-config).
  */
 import { type SyncJournal } from "@indigoai-us/hq-cloud";
-export type DirtyReason = "modified-after-sync" | "hash-mismatch" | "not-in-journal" | "stat-error";
-export interface NarrowFile {
+type DirtyReason = "modified-after-sync" | "hash-mismatch" | "not-in-journal" | "stat-error";
+interface NarrowFile {
     /**
      * COMPANY-RELATIVE path (e.g. `meetings/a.md`) — the canonical namespace
      * shared by the per-company journal keys, the vault S3 keys, and the
@@ -117,4 +117,5 @@ export declare function toPosixKey(p: string): string;
 export declare function formatNarrowPlanSummary(plan: NarrowPlan): string;
 /** Human-readable byte counts with a fixed unit ladder. */
 export declare function formatBytes(n: number): string;
+export {};
 //# sourceMappingURL=local-tree-diff.d.ts.map

package/dist/lib/search-index/background.d.ts

@@ -93,8 +93,6 @@ export declare function defaultSpawnWorker({ logPath, fallbackLogPath }: {
 }, io?: SpawnWorkerIo): number;
 /** Defaults used by the CLI; tests supply every nondeterministic dependency. */
 export declare function defaultBackgroundDependencies(hqRoot: string): BackgroundDependencies;
-/** Match the shell forwarder's hosted-agent markers before looking up qmd. */
-export declare function isHostedAgent(env?: NodeJS.ProcessEnv): boolean;
 export declare function installWorkerCleanup(cleanup: () => void, processEvents?: Pick<NodeJS.Process, 'once'>, exit?: (code: number) => void): void;
 /** Start a detached worker; this public entry never owns the qmd pipeline. */
 export declare function runBackgroundLauncher(dependencies: BackgroundDependencies): BackgroundResult;

package/dist/lib/search-index/background.js

@@ -129,7 +129,7 @@ export function defaultBackgroundDependencies(hqRoot) {
     };
 }
 /** Match the shell forwarder's hosted-agent markers before looking up qmd. */
-export function isHostedAgent(env = process.env) {
+function isHostedAgent(env = process.env) {
     if (env.HQ_QMD_REINDEX_MODE === 'skip-agent' || env.HQ_QMD_REINDEX_MODE === 'skip')
         return true;
     if (env.HQ_AGENT_BOX && env.HQ_AGENT_BOX !== '0')

package/dist/lib/search-index/index.d.ts

@@ -327,19 +327,6 @@ export type ResolveQmdBinOptions = {
  * independent of the dependency's own exports map.
  */
 export declare function packageLocalBin(): string | undefined;
-/**
- * Locate the bundled qmd's Node LAUNCHER — `@tobilu/qmd`'s `bin.qmd` entry
- * (`bin/qmd`, a `#!/usr/bin/env node` script) — by the same upward walk
- * {@link resolveQmdVersion} uses to find the package. Returns the absolute
- * launcher path only when both the manifest and the launcher file exist.
- *
- * This is the shell-free preferred resolution: invoking `node <launcher>`
- * bypasses the npm-generated `.cmd` shim entirely, so the Windows CVE-2024-27980
- * EINVAL never arises and no user-supplied search text reaches cmd.exe. A
- * missing/partial layout returns undefined so the caller falls back to the
- * `.bin` shim (which the shared spawn plan now makes spawnable on Windows too).
- */
-export declare function packageLocalNodeEntry(): string | undefined;
 /**
  * Return the pinned package version when qmd is supplied by this CLI.
  *
@@ -412,12 +399,6 @@ export type EnsureQmdStoreDirOptions = {
 export declare function ensureQmdStoreDir(env?: NodeJS.ProcessEnv, options?: EnsureQmdStoreDirOptions): void;
 /** Reset per-process probe/repair memoisation. Test-only. */
 export declare function __resetQmdProbeStateForTests(): void;
-/** Probe a resolved invocation, memoised per invocation; records the failure
- * detail under the qmd bin identity so repair can read it. */
-export declare function isUsableInvocation(invocation: QmdInvocation, options?: {
-    platform?: NodeJS.Platform;
-    spawn?: QmdSpawn;
-}): boolean;
 /** Backwards-compatible string form: probe a bare bin path shell-free (or via
  * the shell plan when it is a Windows `.cmd`/`.bat`). */
 export declare function isUsableQmd(bin: string): boolean;

package/dist/lib/search-index/index.js

@@ -332,7 +332,7 @@ export function packageLocalBin() {
  * missing/partial layout returns undefined so the caller falls back to the
  * `.bin` shim (which the shared spawn plan now makes spawnable on Windows too).
  */
-export function packageLocalNodeEntry() {
+function packageLocalNodeEntry() {
     let directory = path.dirname(fileURLToPath(import.meta.url));
     for (let depth = 0; depth < 10; depth++) {
         const manifest = path.join(directory, 'node_modules', '@tobilu', 'qmd', 'package.json');
@@ -644,7 +644,7 @@ function probeQmd(invocation, options = {}) {
 }
 /** Probe a resolved invocation, memoised per invocation; records the failure
  * detail under the qmd bin identity so repair can read it. */
-export function isUsableInvocation(invocation, options = {}) {
+function isUsableInvocation(invocation, options = {}) {
     const key = invocationKey(invocation);
     const cached = usableQmdCache.get(key);
     if (cached !== undefined)

package/dist/main.d.ts

@@ -44,6 +44,9 @@ export type TopLevelErrorDependencies = {
     openUrl?: (url: string) => Promise<void>;
     upgradeToTeam?: typeof upgradeToTeam;
 };
+export declare const MAX_OWN_DIST_RELATIVE_PATH_BYTES = 256;
+/** Return a bounded path only when targetPath is beneath packageRoot/dist. */
+export declare function relativeOwnDistModulePath(packageRootPath: string, targetPath: string): string | undefined;
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export declare function handleTopLevelError(err: unknown, deps?: TopLevelErrorDependencies): Promise<void>;
 //# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -6,6 +6,7 @@
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 import "./node-preflight.js";
 import "./node-network-compat.js";
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
@@ -52,10 +53,11 @@ import { settleWithin } from "./utils/settle-with-timeout.js";
 import { isVersionRequest } from "./version-request.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
 import { kickFlagRegistryReadiness, waitForFlagRegistryRefresh, } from "./lib/flag-registry.js";
-import { isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
+import { boundedDiagnosticValue, isPackageRootResolutionError, packageRootCaptureContext, } from "./utils/package-root-diagnostics.js";
 import { registerCommandsWithRecovery } from "./startup-registration.js";
 import { releasePackageUseLeaseAfterCommandLoad } from "./utils/package-use-lease.js";
-import { installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTreeTornError, } from "./utils/install-tree-torn.js";
+import { packageRoot } from "./utils/hq-roots.js";
+import { classifyModuleNotFound, 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";
 import { runGlobalNetworkLifecycle } from "./utils/cli-network-lifecycle.js";
@@ -410,6 +412,110 @@ function integrationsGatewayCaptureContext(err) {
         },
     };
 }
+export const MAX_OWN_DIST_RELATIVE_PATH_BYTES = 256;
+function resolveThroughExistingAncestors(pathApi, inputPath) {
+    let cursor = pathApi.resolve(inputPath);
+    const missingSegments = [];
+    while (true) {
+        try {
+            const realPath = fs.realpathSync.native(cursor);
+            if (missingSegments.length > 0 && !fs.statSync(realPath).isDirectory()) {
+                return undefined;
+            }
+            return pathApi.join(realPath, ...missingSegments);
+        }
+        catch (error) {
+            const code = error !== null && typeof error === "object" && "code" in error
+                ? error.code
+                : undefined;
+            // A missing final module is expected here. Walk to its nearest existing
+            // parent so symlinked package roots and junctions still compare by their
+            // actual location. Other filesystem errors leave enrichment unavailable;
+            // the original error remains on the generic capture path.
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                return undefined;
+            const parent = pathApi.dirname(cursor);
+            if (parent === cursor)
+                return undefined;
+            missingSegments.unshift(pathApi.basename(cursor));
+            cursor = parent;
+        }
+    }
+}
+/** Return a bounded path only when targetPath is beneath packageRoot/dist. */
+export function relativeOwnDistModulePath(packageRootPath, targetPath) {
+    const hasWindowsAbsolutePath = (value) => /^[A-Za-z]:[\\/]/.test(value) || /^\\\\/.test(value);
+    const pathApi = hasWindowsAbsolutePath(packageRootPath) || hasWindowsAbsolutePath(targetPath)
+        ? path.win32
+        : path;
+    let resolvedRoot;
+    let resolvedTarget;
+    if (pathApi === path.win32) {
+        // Use Windows lexical semantics for drive paths and UNC paths even when
+        // this helper is exercised on a non-Windows host.
+        resolvedRoot = pathApi.resolve(packageRootPath);
+        resolvedTarget = pathApi.resolve(targetPath);
+    }
+    else {
+        const canonicalRoot = resolveThroughExistingAncestors(pathApi, packageRootPath);
+        const canonicalTarget = resolveThroughExistingAncestors(pathApi, targetPath);
+        if (canonicalRoot === undefined || canonicalTarget === undefined)
+            return undefined;
+        resolvedRoot = canonicalRoot;
+        resolvedTarget = canonicalTarget;
+    }
+    const distRoot = pathApi.resolve(resolvedRoot, "dist");
+    const relativePath = pathApi.relative(distRoot, resolvedTarget);
+    if (relativePath.length === 0 ||
+        relativePath === ".." ||
+        relativePath.startsWith(`..${pathApi.sep}`) ||
+        pathApi.isAbsolute(relativePath)) {
+        return undefined;
+    }
+    return boundedDiagnosticValue(relativePath, MAX_OWN_DIST_RELATIVE_PATH_BYTES);
+}
+/**
+ * Add bounded evidence when an ESM resolver failure names a file in hq-cli's
+ * own dist tree. This only enriches an event that is already captured; it does
+ * not infer that the package tree was torn or change the recovery path.
+ */
+function ownDistModuleMissingCaptureContext(err) {
+    if (err === null || typeof err !== "object")
+        return undefined;
+    const record = err;
+    if (record.code !== "ERR_MODULE_NOT_FOUND")
+        return undefined;
+    const classified = classifyModuleNotFound(err);
+    if (!classified ||
+        classified.code !== "ERR_MODULE_NOT_FOUND" ||
+        classified.dialect !== "esm-path" ||
+        classified.target.kind !== "path") {
+        return undefined;
+    }
+    let root;
+    try {
+        root = packageRoot();
+    }
+    catch {
+        // Enrichment is optional. If root discovery itself is unavailable, retain
+        // the original generic capture without changing its recovery or output.
+        return undefined;
+    }
+    const relativePath = relativeOwnDistModulePath(root, classified.target.path);
+    if (relativePath === undefined)
+        return undefined;
+    return {
+        tags: {
+            module_missing_scope: "own_dist",
+            cli_version: CLI_VERSION,
+        },
+        contexts: {
+            module_missing_target: {
+                relative_path: relativePath,
+            },
+        },
+    };
+}
 /** Classify a top-level failure without making the CLI process boundary opaque to tests. */
 export async function handleTopLevelError(err, deps = defaultTopLevelErrorDependencies) {
     // A typed plan gate, or an hq-cloud vault error carrying a plan-limit
@@ -920,22 +1026,30 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else {
             // A genuinely unclassified fault is still captured exactly once. Two
             // shapes attach bounded, hq-derived context so the next occurrence
-            // carries the evidence this one lacked: a qmd spawn-level failure the fix
-            // could not attribute (HQ-CLI-1A), and a loader/resolver ENOENT whose path
-            // did not survive delivery (HQ-CLI-1M esm-load, HQ-CLI-1S resolve-time,
-            // HQ-CLI-20 CJS load-time — the unattributable incomplete-install shape).
+            // carries evidence otherwise missing: qmd spawn failures (HQ-CLI-1A),
+            // loader/resolver ENOENTs with no usable path (HQ-CLI-1M/1S/20), and an
+            // ESM module miss under hq-cli's own dist tree. The latter remains a
+            // captured fault without guessing whether the artifact or install tore.
             // Every other error captures bare, exactly as before.
             const spawnContext = qmdSpawnFailureCaptureContext(err);
             const installContext = incompleteInstallCaptureContext(err);
             const qmdContext = qmdExitCaptureContext(err);
             const gatewayContext = integrationsGatewayCaptureContext(err);
-            if (spawnContext || installContext || qmdContext || gatewayContext) {
+            const moduleContext = ownDistModuleMissingCaptureContext(err);
+            const tags = {
+                ...qmdContext?.tags,
+                ...gatewayContext?.tags,
+                ...moduleContext?.tags,
+            };
+            const contexts = {
+                ...spawnContext?.contexts,
+                ...installContext,
+                ...moduleContext?.contexts,
+            };
+            if (Object.keys(tags).length > 0 || Object.keys(contexts).length > 0) {
                 deps.sentry.captureException(err, {
-                    ...qmdContext,
-                    ...(gatewayContext ? { tags: gatewayContext.tags } : {}),
-                    ...((spawnContext || installContext)
-                        ? { contexts: { ...spawnContext?.contexts, ...installContext } }
-                        : {}),
+                    ...(Object.keys(tags).length > 0 ? { tags } : {}),
+                    ...(Object.keys(contexts).length > 0 ? { contexts } : {}),
                 });
             }
             else {

package/dist/types.d.ts

@@ -9,9 +9,8 @@
  */
 import type { ContributionKey } from './utils/contribution-table.js';
 export type LegacyStrategy = 'link' | 'merge' | 'copy';
-export type SyncStrategy = LegacyStrategy | 'package';
 export type AccessLevel = 'public' | 'team' | `role:${string}`;
-export interface PathMapping {
+interface PathMapping {
     src: string;
     dest: string;
 }
@@ -83,7 +82,7 @@ export interface PackAuthor {
  * tracks installed packs by FILESYSTEM PRESENCE — not `modules.yaml`). `version`
  * is an optional semver RANGE the installed dependency must satisfy.
  */
-export interface PackDependency {
+interface PackDependency {
     name: string;
     version?: string;
 }
@@ -129,4 +128,5 @@ export interface PackManifest {
         prompt?: string;
     };
 }
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/utils/client-health-contract.d.ts

@@ -32,19 +32,19 @@
  *     ({@link shouldApplyHeartbeat}).
  */
 export declare const CLIENT_HEALTH_CONTRACT_VERSION = 1;
-export declare const CLIENT_HEALTH_PLATFORMS: readonly ["macos", "windows", "linux"];
+declare const CLIENT_HEALTH_PLATFORMS: readonly ["macos", "windows", "linux"];
 export type ClientHealthPlatform = (typeof CLIENT_HEALTH_PLATFORMS)[number];
-export declare const CLIENT_HEALTH_ARCHS: readonly ["x64", "arm64"];
+declare const CLIENT_HEALTH_ARCHS: readonly ["x64", "arm64"];
 export type ClientHealthArch = (typeof CLIENT_HEALTH_ARCHS)[number];
 /** Which client produced the heartbeat. Desktop is always-on; CLI contributes per invocation. */
-export declare const CLIENT_HEALTH_SOURCES: readonly ["desktop", "cli"];
-export type ClientHealthSource = (typeof CLIENT_HEALTH_SOURCES)[number];
+declare const CLIENT_HEALTH_SOURCES: readonly ["desktop", "cli"];
+type ClientHealthSource = (typeof CLIENT_HEALTH_SOURCES)[number];
 /**
  * Current sync state of the installation. `paused` and `conflict_blocked` are
  * first-class states (not failures folded into `error`) because support treats
  * them differently: pause may be intentional and conflicts are user-owned.
  */
-export declare const CLIENT_HEALTH_SYNC_STATES: readonly ["idle", "syncing", "paused", "conflict_blocked", "error", "never_synced"];
+declare const CLIENT_HEALTH_SYNC_STATES: readonly ["idle", "syncing", "paused", "conflict_blocked", "error", "never_synced"];
 export type ClientHealthSyncState = (typeof CLIENT_HEALTH_SYNC_STATES)[number];
 /**
  * Updater state. ABSENCE of the field means the client is too old to report
@@ -62,19 +62,15 @@ export type ClientHealthFailureReason = (typeof CLIENT_HEALTH_FAILURE_REASONS)[n
  * fails closed.
  */
 export declare const CLIENT_HEALTH_REPAIR_KINDS: readonly ["CHECK_NOW", "RETRY_SYNC", "RESUME_SYNC", "REPAIR_CLI", "UPDATE_CORE", "APPLY_DESKTOP_UPDATE", "RESTART_APP"];
-export type ClientHealthRepairKind = (typeof CLIENT_HEALTH_REPAIR_KINDS)[number];
+type ClientHealthRepairKind = (typeof CLIENT_HEALTH_REPAIR_KINDS)[number];
 /** Command/receipt lifecycle states (queued → acknowledged → running → terminal). */
-export declare const CLIENT_HEALTH_COMMAND_STATES: readonly ["queued", "acknowledged", "running", "succeeded", "failed", "expired"];
-export type ClientHealthCommandState = (typeof CLIENT_HEALTH_COMMAND_STATES)[number];
+declare const CLIENT_HEALTH_COMMAND_STATES: readonly ["queued", "acknowledged", "running", "succeeded", "failed", "expired"];
+type ClientHealthCommandState = (typeof CLIENT_HEALTH_COMMAND_STATES)[number];
 /** Closed diagnostic probe identifiers (US-007). */
-export declare const CLIENT_HEALTH_DIAGNOSTIC_CHECKS: readonly ["auth", "runner", "cli", "core", "updater", "sync", "conflicts", "storage", "permissions"];
-export type ClientHealthDiagnosticCheck = (typeof CLIENT_HEALTH_DIAGNOSTIC_CHECKS)[number];
-export declare const CLIENT_HEALTH_CHECK_STATUSES: readonly ["pass", "fail", "skip"];
-export type ClientHealthCheckStatus = (typeof CLIENT_HEALTH_CHECK_STATUSES)[number];
-export declare const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
-export declare const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100000;
-export declare const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100000;
-export declare const CLIENT_HEALTH_MAX_CHECKS = 16;
+declare const CLIENT_HEALTH_DIAGNOSTIC_CHECKS: readonly ["auth", "runner", "cli", "core", "updater", "sync", "conflicts", "storage", "permissions"];
+type ClientHealthDiagnosticCheck = (typeof CLIENT_HEALTH_DIAGNOSTIC_CHECKS)[number];
+declare const CLIENT_HEALTH_CHECK_STATUSES: readonly ["pass", "fail", "skip"];
+type ClientHealthCheckStatus = (typeof CLIENT_HEALTH_CHECK_STATUSES)[number];
 /**
  * Local-files-overview bounds (client-sync-health-control-plane hq-cli
  * addition, US-016). These cap the closed set of bounded facts support sees
@@ -146,7 +142,7 @@ export interface ClientHealthHeartbeat {
     /** Absent on older clients / non-sync-outcome events. See {@link ClientHealthLocalFilesOverview}. */
     localFilesOverview?: ClientHealthLocalFilesOverview;
 }
-export interface ClientHealthCheckResult {
+interface ClientHealthCheckResult {
     check: ClientHealthDiagnosticCheck;
     status: ClientHealthCheckStatus;
     /** Present only on `fail` — a closed reason code, never prose. */
@@ -187,4 +183,5 @@ export declare function parseClientHealthCommandReceipt(input: unknown): ClientH
  * answers idempotently and the current snapshot remains unchanged).
  */
 export declare function shouldApplyHeartbeat(storedSequence: number | undefined, incomingSequence: number): boolean;
+export {};
 //# sourceMappingURL=client-health-contract.d.ts.map

package/dist/utils/client-health-contract.js

@@ -34,16 +34,16 @@
 // ─── Contract version ────────────────────────────────────────────────────────
 export const CLIENT_HEALTH_CONTRACT_VERSION = 1;
 // ─── Closed enums ────────────────────────────────────────────────────────────
-export const CLIENT_HEALTH_PLATFORMS = ["macos", "windows", "linux"];
-export const CLIENT_HEALTH_ARCHS = ["x64", "arm64"];
+const CLIENT_HEALTH_PLATFORMS = ["macos", "windows", "linux"];
+const CLIENT_HEALTH_ARCHS = ["x64", "arm64"];
 /** Which client produced the heartbeat. Desktop is always-on; CLI contributes per invocation. */
-export const CLIENT_HEALTH_SOURCES = ["desktop", "cli"];
+const CLIENT_HEALTH_SOURCES = ["desktop", "cli"];
 /**
  * Current sync state of the installation. `paused` and `conflict_blocked` are
  * first-class states (not failures folded into `error`) because support treats
  * them differently: pause may be intentional and conflicts are user-owned.
  */
-export const CLIENT_HEALTH_SYNC_STATES = [
+const CLIENT_HEALTH_SYNC_STATES = [
     "idle",
     "syncing",
     "paused",
@@ -94,7 +94,7 @@ export const CLIENT_HEALTH_REPAIR_KINDS = [
     "RESTART_APP",
 ];
 /** Command/receipt lifecycle states (queued → acknowledged → running → terminal). */
-export const CLIENT_HEALTH_COMMAND_STATES = [
+const CLIENT_HEALTH_COMMAND_STATES = [
     "queued",
     "acknowledged",
     "running",
@@ -103,7 +103,7 @@ export const CLIENT_HEALTH_COMMAND_STATES = [
     "expired",
 ];
 /** Closed diagnostic probe identifiers (US-007). */
-export const CLIENT_HEALTH_DIAGNOSTIC_CHECKS = [
+const CLIENT_HEALTH_DIAGNOSTIC_CHECKS = [
     "auth",
     "runner",
     "cli",
@@ -114,12 +114,12 @@ export const CLIENT_HEALTH_DIAGNOSTIC_CHECKS = [
     "storage",
     "permissions",
 ];
-export const CLIENT_HEALTH_CHECK_STATUSES = ["pass", "fail", "skip"];
+const CLIENT_HEALTH_CHECK_STATUSES = ["pass", "fail", "skip"];
 // ─── Bounds ──────────────────────────────────────────────────────────────────
-export const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
-export const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100_000;
-export const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100_000;
-export const CLIENT_HEALTH_MAX_CHECKS = 16;
+const CLIENT_HEALTH_MAX_STRING_LENGTH = 64;
+const CLIENT_HEALTH_MAX_CONSECUTIVE_FAILURES = 100_000;
+const CLIENT_HEALTH_MAX_CONFLICT_COUNT = 100_000;
+const CLIENT_HEALTH_MAX_CHECKS = 16;
 /**
  * Local-files-overview bounds (client-sync-health-control-plane hq-cli
  * addition, US-016). These cap the closed set of bounded facts support sees

package/dist/utils/self-update.d.ts

@@ -145,6 +145,8 @@ export interface SelfUpdateDeps {
     /** Same-filesystem install rename, injectable for rollback tests. */
     renamePath?: typeof fs.renameSync;
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
+    /** Delay between bounded npm retries when the just-published target is not visible yet. */
+    sleep?: (ms: number) => Promise<void>;
     reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
     /** Async process-spawn seam for lease handoff tests. */
     spawnReexec?: typeof spawn;

package/dist/utils/self-update.js

@@ -693,6 +693,18 @@ function reexecErrorClass(error) {
     }
     return "unknown";
 }
+const NPM_NOTARGET_RETRY_DELAYS_MS = [30_000, 60_000, 90_000];
+const NPM_NOTARGET_MAX_ATTEMPTS = NPM_NOTARGET_RETRY_DELAYS_MS.length + 1;
+function isNpmNotargetFailure(result) {
+    const code = (result.diagnosticCode ?? result.code)?.toUpperCase();
+    if (code === "ETARGET" || code === "NOTARGET")
+        return true;
+    return result.failureKind === "package_manager_exit" &&
+        /\bETARGET\b|\bnpm\s+(?:ERR!|error)\s+notarget\b/i.test(result.detail ?? "");
+}
+function sleepForRetry(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function updateAndReexec(argv, flavor, known, deps) {
     const env = deps.env ?? process.env;
     if (env[REEXEC_GUARD_ENV] === "1" || env.HQ_NO_UPDATE_CHECK === "1") {
@@ -795,14 +807,32 @@ async function updateAndReexec(argv, flavor, known, deps) {
         // Forward env only when PNPM_HOME had to be injected, so the common path
         // spawns with the inherited environment and keeps the two-argument runner
         // call it has always made.
-        if (staged) {
-            result = stagedNpmInstall(install, latestValid, { run: runner, env, rename: renamePath });
-        }
-        else if (updateEnv === undefined) {
-            result = runner(plan.cmd, plan.args);
+        const runInstall = () => {
+            if (staged) {
+                return stagedNpmInstall(install, latestValid, { run: runner, env, rename: renamePath });
+            }
+            return updateEnv === undefined
+                ? runner(plan.cmd, plan.args)
+                : runner(plan.cmd, plan.args, updateEnv);
+        };
+        let attempt = 1;
+        result = runInstall();
+        while (install.manager === "npm" &&
+            !result.ok &&
+            isNpmNotargetFailure(result) &&
+            attempt < NPM_NOTARGET_MAX_ATTEMPTS) {
+            const delay = NPM_NOTARGET_RETRY_DELAYS_MS[attempt - 1];
+            const nextAttempt = attempt + 1;
+            console.error(chalk.dim(`  npm has not published hq-cli ${latestValid} yet; retrying install (attempt ${nextAttempt}/${NPM_NOTARGET_MAX_ATTEMPTS}) after ${delay} ms.`));
+            await (deps.sleep ?? sleepForRetry)(delay);
+            attempt = nextAttempt;
+            result = runInstall();
         }
-        else {
-            result = runner(plan.cmd, plan.args, updateEnv);
+        if (!result.ok && attempt > 1) {
+            result = {
+                ...result,
+                detail: `${result.detail ?? "npm install failed"} (attempts: ${attempt})`,
+            };
         }
         if (result.ok && !staged && install.manager === "npm" && install.prefix && install.packageRoot) {
             const bins = verifyOrRepairNpmBins(install.prefix, install.packageRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.6",
+  "version": "5.345.8",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {