openbroker 1.9.3 → 1.9.5

package/scripts/auto/types.ts

@@ -220,7 +220,7 @@ export interface AutomationAPI {
   /** Subscribe to a market/account event */
   on<E extends AutomationEventType>(event: E, handler: AutomationEventHandler<E>): void;
 
-  /** Run a handler on a recurring interval (ms). Aligned to the poll loop. */
+  /** Run a handler on its own recurring scheduler, independent of REST reconciliation. */
   every(intervalMs: number, handler: () => void | Promise<void>): void;
 
   /** Called after all handlers are registered and polling begins */
@@ -290,6 +290,7 @@ export interface ScheduledTask {
   intervalMs: number;
   handler: () => void | Promise<void>;
   lastRun: number;
+  running?: boolean;
 }
 
 export interface RunningAutomation {

package/scripts/core/client.ts

@@ -21,6 +21,28 @@ import type {
 import { loadConfig, isMainnet } from './config.js';
 import { roundPrice, roundSize } from './utils.js';
 
+export interface RealtimeBookSnapshot {
+  coin: string;
+  time: number;
+  levels: [
+    Array<{ px: string; sz: string; n: number }>,
+    Array<{ px: string; sz: string; n: number }>,
+  ];
+}
+
+export interface RealtimeDataProvider {
+  readonly connected: boolean;
+  getAllMids(): Record<string, string> | null;
+  getMainAssetCtxs(): AssetCtx[] | null;
+  getUserState(user: string, dex?: string): ClearinghouseState | null;
+  getUserStateAll(user: string): ClearinghouseState | null;
+  getSpotBalances(user: string): {
+    balances: Array<{ coin: string; token: number; hold: string; total: string; entryNtl: string }>;
+  } | null;
+  getOpenOrders(user: string): OpenOrder[] | null;
+  getL2Book(coin: string): Promise<RealtimeBookSnapshot | null>;
+}
+
 export class HyperliquidClient {
   private config: OpenBrokerConfig;
   private account: PrivateKeyAccount;
@@ -33,6 +55,8 @@ export class HyperliquidClient {
   private szDecimalsMap: Map<string, number> = new Map();
   /** Maps coin name → dex info for HIP-3 assets. Main dex assets have dexName=null */
   private coinDexMap: Map<string, { dexName: string | null; dexIdx: number; localName: string }> = new Map();
+  /** Static positional universe per dex, used to join allDexsAssetCtxs WS pushes. */
+  private dexUniverseMap: Map<string, string[]> = new Map();
   /** Cache of perpDexs list */
   private perpDexsCache: Array<{ name: string; fullName: string; deployer: string } | null> | null = null;
   /** Whether HIP-3 assets have been loaded into maps */
@@ -63,6 +87,16 @@ export class HyperliquidClient {
   private spotMetaLoaded: boolean = false;
   /** HIP-4 outcome metadata cache */
   private outcomeMeta: OutcomeMetaResponse | null = null;
+  /** Static main-dex universe retained while live asset contexts arrive over WebSocket. */
+  private staticMeta: MetaAndAssetCtxs['meta'] | null = null;
+  /** Runtime-owned live data cache. CLI calls leave this detached and remain REST-only. */
+  private realtime: RealtimeDataProvider | null = null;
+  private predictedFundingsCache: {
+    value: Array<[string, Array<[string, { fundingRate: string; nextFundingTime: number }]>]>;
+    timestamp: number;
+  } | null = null;
+  private predictedFundingsInFlight: Promise<Array<[string, Array<[string, { fundingRate: string; nextFundingTime: number }]>]>> | null = null;
+  private spotMetaCache: Awaited<ReturnType<HyperliquidClient['getSpotMeta']>> | null = null;
   public verbose: boolean = false;
 
   constructor(config?: OpenBrokerConfig) {
@@ -226,6 +260,11 @@ export class HyperliquidClient {
     return !isMainnet();
   }
 
+  /** Attach/detach the automation runtime's WebSocket-first data cache. */
+  setRealtimeDataProvider(provider: RealtimeDataProvider | null): void {
+    this.realtime = provider;
+  }
+
   /**
    * Returns vaultAddress param for SDK exchange calls.
    * Only used for vault trading (HYPERLIQUID_VAULT_ADDRESS set explicitly).
@@ -255,6 +294,10 @@ export class HyperliquidClient {
   // ============ Market Data ============
 
   async getMetaAndAssetCtxs(): Promise<MetaAndAssetCtxs> {
+    const liveCtxs = this.realtime?.connected ? this.realtime.getMainAssetCtxs() : null;
+    if (this.staticMeta && liveCtxs) {
+      return { meta: this.staticMeta, assetCtxs: liveCtxs };
+    }
     if (this.meta) return this.meta;
 
     this.log('Fetching metaAndAssetCtxs...');
@@ -277,6 +320,8 @@ export class HyperliquidClient {
       assetCtxs: response[1] as AssetCtx[],
     };
     this.meta = meta;
+    this.staticMeta = meta.meta;
+    this.dexUniverseMap.set('', meta.meta.universe.map((asset) => asset.name));
 
     // Build lookup maps for main dex
     meta.meta.universe.forEach((asset, index) => {
@@ -294,6 +339,29 @@ export class HyperliquidClient {
     return meta;
   }
 
+  /**
+   * Warm only the native/main static universe for an automation runtime.
+   * Dynamic contexts arrive via allDexsAssetCtxs, and HIP-3 metadata is loaded
+   * on demand when a strategy references a prefixed market. This avoids the
+   * old startup burst that fetched every HIP-3 dex before the socket opened.
+   */
+  async initializeRealtimeMetadata(): Promise<void> {
+    if (this.staticMeta) return;
+    const response = await this.withRetry(() => this.info.metaAndAssetCtxs(), 'metaAndAssetCtxs(realtime-init)');
+    const meta: MetaAndAssetCtxs = {
+      meta: { universe: response[0].universe as AssetMeta[] },
+      assetCtxs: response[1] as AssetCtx[],
+    };
+    this.meta = meta;
+    this.staticMeta = meta.meta;
+    this.dexUniverseMap.set('', meta.meta.universe.map((asset) => asset.name));
+    meta.meta.universe.forEach((asset, index) => {
+      this.assetMap.set(asset.name, index);
+      this.szDecimalsMap.set(asset.name, asset.szDecimals);
+      this.coinDexMap.set(asset.name, { dexName: null, dexIdx: 0, localName: asset.name });
+    });
+  }
+
   /**
    * Load HIP-3 perp dex assets into the asset/szDecimals maps.
    * Asset index formula: 100000 + dexIdx * 10000 + assetIdx
@@ -422,11 +490,16 @@ export class HyperliquidClient {
         this.coinDexMap.set(coinName, { dexName, dexIdx, localName });
         if (asset.maxLeverage) this.hip3MaxLeverageMap.set(coinName, asset.maxLeverage);
       });
+      this.dexUniverseMap.set(dexName, universe.map((asset) => (
+        asset.name.startsWith(`${dexName}:`) ? asset.name : `${dexName}:${asset.name}`
+      )));
     }
     this.loadedHip3Dexes.add(dexName);
   }
 
   async getAllMids(): Promise<Record<string, string>> {
+    const live = this.realtime?.connected ? this.realtime.getAllMids() : null;
+    if (live) return { ...live };
     this.log('Fetching allMids...');
     let response: Record<string, string>;
     try {
@@ -584,6 +657,7 @@ export class HyperliquidClient {
       isCanonical: boolean;
     }>;
   }> {
+    if (this.spotMetaCache) return this.spotMetaCache;
     this.log('Fetching spotMeta...');
     const data = await this.postInfo<{
       tokens: Array<{
@@ -602,6 +676,7 @@ export class HyperliquidClient {
         isCanonical: boolean;
       }>;
     }>({ type: 'spotMeta' }, 'spotMeta');
+    this.spotMetaCache = data;
     this.log('spotMeta response:', JSON.stringify(data).slice(0, 500));
     return data;
   }
@@ -634,6 +709,23 @@ export class HyperliquidClient {
       prevDayPx: string;
     }>;
   }> {
+    const liveMids = this.realtime?.connected ? this.realtime.getAllMids() : null;
+    if (liveMids) {
+      const meta = await this.getSpotMeta();
+      return {
+        meta,
+        assetCtxs: meta.universe.map((pair) => {
+          const price = liveMids[pair.name] ?? '0';
+          return {
+            coin: pair.name,
+            dayNtlVlm: '0',
+            markPx: price,
+            midPx: price,
+            prevDayPx: price,
+          };
+        }),
+      };
+    }
     this.log('Fetching spotMetaAndAssetCtxs...');
     const data = await this.postInfo<unknown>(
       { type: 'spotMetaAndAssetCtxs' },
@@ -1003,6 +1095,9 @@ export class HyperliquidClient {
       entryNtl: string;
     }>;
   }> {
+    const target = user ?? this.address;
+    const live = this.realtime?.connected ? this.realtime.getSpotBalances(target) : null;
+    if (live) return live;
     this.log('Fetching spotClearinghouseState for:', user ?? this.address);
     const data = await this.postInfo<{
       balances: Array<{
@@ -1076,6 +1171,32 @@ export class HyperliquidClient {
   async getPredictedFundings(): Promise<Array<[
     string, // coin
     Array<[string, { fundingRate: string; nextFundingTime: number }]> // venue funding rates
+  ]>> {
+    const ttlMs = 60_000;
+    if (this.predictedFundingsCache && Date.now() - this.predictedFundingsCache.timestamp < ttlMs) {
+      return this.predictedFundingsCache.value;
+    }
+    if (this.predictedFundingsInFlight) return this.predictedFundingsInFlight;
+
+    this.predictedFundingsInFlight = this.fetchPredictedFundings();
+    try {
+      const value = await this.predictedFundingsInFlight;
+      this.predictedFundingsCache = { value, timestamp: Date.now() };
+      return value;
+    } catch (error) {
+      if (this.predictedFundingsCache) {
+        this.log('predictedFundings refresh failed; using stale cache:', this.describeError(error));
+        return this.predictedFundingsCache.value;
+      }
+      throw error;
+    } finally {
+      this.predictedFundingsInFlight = null;
+    }
+  }
+
+  private async fetchPredictedFundings(): Promise<Array<[
+    string,
+    Array<[string, { fundingRate: string; nextFundingTime: number }]>
   ]>> {
     this.log('Fetching predictedFundings...');
     const baseUrl = isMainnet()
@@ -1091,11 +1212,15 @@ export class HyperliquidClient {
       },
       body: JSON.stringify({ type: 'predictedFundings' }),
     });
+    if (!response.ok) {
+      throw new Error(`predictedFundings failed: HTTP ${response.status} ${response.statusText}`);
+    }
     const data = await response.json() as Array<[
       string,
       Array<[string, { fundingRate: string; nextFundingTime: number }]>
     ]>;
-    this.log('predictedFundings response length:', data?.length);
+    if (!Array.isArray(data)) throw new Error('predictedFundings returned malformed payload');
+    this.log('predictedFundings response length:', data.length);
     return data;
   }
 
@@ -1112,6 +1237,9 @@ export class HyperliquidClient {
     spread: number;
     spreadBps: number;
   }> {
+    const live = this.realtime?.connected ? await this.realtime.getL2Book(coin) : null;
+    if (live) return this.normalizeL2Book(live.levels);
+
     this.log('Fetching l2Book for:', coin);
     // API accepts prefixed names directly (e.g., "xyz:CL")
     let response: Awaited<ReturnType<typeof this.info.l2Book>>;
@@ -1129,8 +1257,20 @@ export class HyperliquidClient {
       throw new Error(`l2Book(${coin}) returned empty/malformed payload.`);
     }
 
-    const bids = (response.levels[0] ?? []) as Array<{ px: string; sz: string; n: number }>;
-    const asks = (response.levels[1] ?? []) as Array<{ px: string; sz: string; n: number }>;
+    return this.normalizeL2Book(response.levels as RealtimeBookSnapshot['levels']);
+  }
+
+  private normalizeL2Book(levels: RealtimeBookSnapshot['levels']): {
+    bids: Array<{ px: string; sz: string; n: number }>;
+    asks: Array<{ px: string; sz: string; n: number }>;
+    bestBid: number;
+    bestAsk: number;
+    midPrice: number;
+    spread: number;
+    spreadBps: number;
+  } {
+    const bids = levels[0] ?? [];
+    const asks = levels[1] ?? [];
 
     const bestBid = bids.length > 0 ? parseFloat(bids[0].px) : 0;
     const bestAsk = asks.length > 0 ? parseFloat(asks[0].px) : 0;
@@ -1266,6 +1406,28 @@ export class HyperliquidClient {
     // Keep the asset/szDecimals/coinDex maps - they don't change
   }
 
+  /** Join an allDexsAssetCtxs WebSocket payload with the cached static universes. */
+  fundingRatesFromWs(ctxs: ReadonlyArray<[
+    string,
+    ReadonlyArray<{ funding?: string | number | null; premium?: string | number | null }>,
+  ]>): Map<string, { rate: number; premium: number }> {
+    const rates = new Map<string, { rate: number; premium: number }>();
+    for (const [dexName, values] of ctxs) {
+      const universe = this.dexUniverseMap.get(dexName || '');
+      if (!universe) continue;
+      for (let index = 0; index < Math.min(universe.length, values.length); index++) {
+        const coin = universe[index];
+        const value = values[index];
+        if (!coin || !value) continue;
+        rates.set(coin, {
+          rate: Number(value.funding ?? 0),
+          premium: Number(value.premium ?? 0),
+        });
+      }
+    }
+    return rates;
+  }
+
   /**
    * Get all loaded asset names (main + HIP-3)
    */
@@ -1952,6 +2114,9 @@ export class HyperliquidClient {
   }
 
   async getUserState(user?: string, dex?: string): Promise<ClearinghouseState> {
+    const target = user ?? this.address;
+    const live = this.realtime?.connected ? this.realtime.getUserState(target, dex) : null;
+    if (live) return live;
     this.log('Fetching clearinghouseState for:', user ?? this.address, dex ? `dex: ${dex}` : '');
     const params: { user: string; dex?: string } = { user: user ?? this.address };
     if (dex !== undefined) params.dex = dex;
@@ -2107,6 +2272,9 @@ export class HyperliquidClient {
    * For standard accounts: aggregates margin summaries from each dex.
    */
   async getUserStateAll(user?: string): Promise<ClearinghouseState> {
+    const target = user ?? this.address;
+    const live = this.realtime?.connected ? this.realtime.getUserStateAll(target) : null;
+    if (live) return live;
     await this.getMetaAndAssetCtxs(); // Ensure HIP-3 dex list is loaded
 
     const unified = await this.isUnifiedAccount(user);
@@ -2149,7 +2317,10 @@ export class HyperliquidClient {
   }
 
   async getOpenOrders(user?: string): Promise<OpenOrder[]> {
-    this.log('Fetching openOrders for:', user ?? this.address);
+    const target = user ?? this.address;
+    const live = this.realtime?.connected ? this.realtime.getOpenOrders(target) : null;
+    if (live) return live;
+    this.log('Fetching openOrders for:', target);
     await this.getMetaAndAssetCtxs(); // Ensure HIP-3 dex list is loaded
 
     // Fetch main dex orders

package/scripts/core/ws.ts

@@ -12,8 +12,9 @@ import type {
   AllDexsAssetCtxsWsEvent,
   AllDexsClearinghouseStateWsEvent,
   SpotStateWsEvent,
+  OpenOrdersWsEvent,
 } from '@nktkas/hyperliquid';
-import type { ClearinghouseState } from './types.js';
+import type { ClearinghouseState, OpenOrder } from './types.js';
 import { isMainnet } from './config.js';
 
 // ── Event types ────────────────────────────────────────────────────
@@ -71,6 +72,8 @@ export interface WsEventMap {
   spotState: {
     balances: Array<{ coin: string; token: number; total: string; hold: string; entryNtl?: string }>;
   };
+  /** Complete open-order snapshot for one user + dex (empty dex = native/main). */
+  openOrders: { user: string; dex: string; orders: OpenOrder[] };
   /** Order status changed (filled, canceled, rejected, etc.) */
   orderUpdate: {
     order: {
@@ -136,6 +139,7 @@ export class WebSocketManager {
   private subscriptions: ISubscription[] = [];
   private handlers = new Map<WsEventType, Set<Function>>();
   private _connected = false;
+  private closing = false;
   private verbose: boolean;
 
   constructor(verbose = false) {
@@ -158,17 +162,38 @@ export class WebSocketManager {
     this.transport = new WebSocketTransport({
       isTestnet: !isMainnet(),
       resubscribe: true, // auto-resubscribe on reconnect
+      reconnect: { maxRetries: Infinity },
+    });
+
+    const socket = this.transport.socket as unknown as WebSocket;
+    socket.addEventListener('open', () => {
+      if (this._connected) return;
+      this._connected = true;
+      this.emit('connected', undefined);
+      this.log('Connected to', isMainnet() ? 'mainnet' : 'testnet');
+    });
+    socket.addEventListener('close', () => {
+      if (!this._connected) return;
+      this._connected = false;
+      this.emit('disconnected', { reason: this.closing ? 'manual close' : 'socket closed' });
+      this.log(this.closing ? 'Closed' : 'Disconnected; transport will reconnect');
+    });
+    socket.addEventListener('error', () => {
+      this.emit('error', { error: new Error('Hyperliquid WebSocket transport error') });
     });
 
     this.client = new SubscriptionClient({ transport: this.transport });
 
     await this.transport.ready();
-    this._connected = true;
-    this.emit('connected', undefined);
-    this.log('Connected to', isMainnet() ? 'mainnet' : 'testnet');
+    if (!this._connected) {
+      this._connected = true;
+      this.emit('connected', undefined);
+      this.log('Connected to', isMainnet() ? 'mainnet' : 'testnet');
+    }
   }
 
   async close(): Promise<void> {
+    this.closing = true;
     for (const sub of this.subscriptions) {
       try { await sub.unsubscribe(); } catch { /* ignore */ }
     }
@@ -180,9 +205,12 @@ export class WebSocketManager {
       this.client = null;
     }
 
-    this._connected = false;
-    this.emit('disconnected', { reason: 'manual close' });
-    this.log('Closed');
+    if (this._connected) {
+      this._connected = false;
+      this.emit('disconnected', { reason: 'manual close' });
+      this.log('Closed');
+    }
+    this.closing = false;
   }
 
   // ── Event system ───────────────────────────────────────────────
@@ -304,6 +332,19 @@ export class WebSocketManager {
     return this.trackSub(sub);
   }
 
+  /** Subscribe to complete open-order snapshots for one dex. */
+  async subscribeOpenOrders(user: `0x${string}`, dex = ''): Promise<ISubscription> {
+    const client = this.ensureClient();
+    const sub = await client.openOrders({ user, dex }, (data: OpenOrdersWsEvent) => {
+      this.emit('openOrders', {
+        user: data.user,
+        dex: data.dex,
+        orders: data.orders as unknown as OpenOrder[],
+      });
+    });
+    return this.trackSub(sub);
+  }
+
   /**
    * Subscribe to order lifecycle events (fill, cancel, reject, etc.).
    * This is the most important subscription for trading automations.
@@ -377,16 +418,24 @@ export class WebSocketManager {
   /**
    * Start all subscriptions needed for the automation runtime:
    * - allMids (price feed)
+   * - allDexsAssetCtxs (funding / mark / oracle contexts)
+   * - allDexsClearinghouseState + spotState (positions, margin, balances)
+   * - openOrders for main + requested HIP-3 dexes
    * - orderUpdates (order lifecycle)
    * - userFills (trade fills)
    * - userEvents (liquidations, funding payments, system cancels)
    */
-  async subscribeAll(user: `0x${string}`): Promise<void> {
+  async subscribeAll(user: `0x${string}`, dexNames: string[] = []): Promise<void> {
     await this.connect();
     this.log('Subscribing to all feeds for', user);
 
     await Promise.all([
       this.subscribeAllMids(),
+      this.subscribeAllDexsAssetCtxs(),
+      this.subscribeAllDexsClearinghouseState(user),
+      this.subscribeSpotState(user),
+      this.subscribeOpenOrders(user),
+      ...dexNames.map((dex) => this.subscribeOpenOrders(user, dex)),
       this.subscribeOrderUpdates(user),
       this.subscribeUserFills(user),
       this.subscribeUserEvents(user),

package/scripts/setup/install.ts

@@ -6,21 +6,59 @@ import * as path from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
+import {
+  INSTALLABLE_PACKAGES,
+  packageSpec,
+  resolveInstallablePackage,
+} from './package-catalog.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const packageRoot = path.resolve(__dirname, '../..');
-const args = new Set(process.argv.slice(2));
+const rawArgs = process.argv.slice(2);
+const args = new Set(rawArgs);
+
+function positionalArgs(): string[] {
+  const positionals: string[] = [];
+  for (let index = 0; index < rawArgs.length; index++) {
+    const arg = rawArgs[index];
+    if (arg === '--tag') {
+      index++;
+      continue;
+    }
+    if (!arg.startsWith('-')) positionals.push(arg);
+  }
+  return positionals;
+}
+
+function optionValue(flag: string): string | null {
+  const index = rawArgs.indexOf(flag);
+  if (index < 0) return null;
+  const value = rawArgs[index + 1];
+  if (!value || value.startsWith('-')) fail(`${flag} requires a value`);
+  return value;
+}
 
 function printUsage(): void {
   console.log(`
-OpenBroker Harness Installer
-============================
+OpenBroker Installer
+====================
 
 Usage:
+  openbroker install <package> [--tag <version>] [--dry]
+  openbroker install --list
   openbroker install --codex [options]
   npx openbroker@latest install --codex [options]
 
+Companion packages:
+  monitoring    Install the local automation dashboard
+  extended      Install the Extended Exchange CLI
+
+Package options:
+  --tag <tag>   Install a release tag or exact version (default: latest)
+  --dry         Print the npm command without installing
+  --list        List supported companion packages
+
 Harnesses:
   --codex       Install the OpenBroker skill for Codex
 
@@ -93,6 +131,62 @@ function installGlobalCli(): void {
   }
 }
 
+function printInstallablePackages(): void {
+  console.log('Installable OpenBroker packages:\n');
+  for (const entry of INSTALLABLE_PACKAGES) {
+    console.log(`  ${entry.key.padEnd(12)} ${entry.packageName.padEnd(26)} ${entry.description}`);
+  }
+  console.log('\nInstall or upgrade with: openbroker install <package>');
+}
+
+function installCompanionPackage(target: string): void {
+  const entry = resolveInstallablePackage(target);
+  if (!entry) {
+    printInstallablePackages();
+    fail(`unknown installable package: ${target}`);
+  }
+
+  const allowedFlags = new Set(['--tag', '--dry']);
+  const unsupported = rawArgs.filter((arg, index) => (
+    arg.startsWith('-')
+    && !allowedFlags.has(arg)
+    && rawArgs[index - 1] !== '--tag'
+  ));
+  if (unsupported.length > 0) fail(`unsupported package option: ${unsupported[0]}`);
+
+  const tag = optionValue('--tag') ?? 'latest';
+  let spec: string;
+  try {
+    spec = packageSpec(entry, tag);
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const npmArgs = ['install', '--global', spec];
+
+  console.log(`OpenBroker — Install ${entry.key}`);
+  console.log('================================\n');
+  console.log(`Package: ${spec}`);
+  console.log(`Command: ${npmCommand} ${npmArgs.join(' ')}`);
+
+  if (args.has('--dry')) {
+    console.log('\nDry run only; nothing was installed.');
+    return;
+  }
+
+  const result = spawnSync(npmCommand, npmArgs, { stdio: 'inherit' });
+  if (result.error) fail(`could not start npm: ${result.error.message}`);
+  if (result.status !== 0) {
+    fail(`installation failed for ${entry.packageName}; resolve the npm error and retry`);
+  }
+
+  console.log(`\n✅ ${entry.packageName} installed successfully.`);
+  console.log(`Available command: ${entry.command}`);
+  console.log('\nNext steps:');
+  for (const step of entry.nextSteps) console.log(`  ${step}`);
+}
+
 function runApiWalletSetup(): void {
   const onboardPath = path.join(packageRoot, 'scripts', 'setup', 'onboard.ts');
 
@@ -121,6 +215,19 @@ function main(): void {
     return;
   }
 
+  if (args.has('--list')) {
+    printInstallablePackages();
+    return;
+  }
+
+  const positionals = positionalArgs();
+  if (positionals.length > 0) {
+    if (positionals.length > 1) fail(`expected one package name, received: ${positionals.join(' ')}`);
+    if (args.has('--codex')) fail('choose either a companion package or the --codex harness installer');
+    installCompanionPackage(positionals[0]);
+    return;
+  }
+
   if (!args.has('--codex')) {
     printUsage();
     fail('choose a supported harness flag such as --codex');

package/scripts/setup/package-catalog.test.ts

@@ -0,0 +1,50 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  INSTALLABLE_PACKAGES,
+  packageSpec,
+  resolveInstallablePackage,
+} from './package-catalog.js';
+
+const installScript = fileURLToPath(new URL('./install.ts', import.meta.url));
+
+test('resolves companion packages by short name and npm package name', () => {
+  assert.equal(resolveInstallablePackage('monitoring')?.packageName, 'openbroker-monitoring');
+  assert.equal(resolveInstallablePackage('openbroker-monitoring')?.key, 'monitoring');
+  assert.equal(resolveInstallablePackage('EXTENDED')?.command, 'openbroker-ex');
+  assert.equal(resolveInstallablePackage('unknown'), null);
+});
+
+test('builds pinned or latest npm package specs without accepting arbitrary specs', () => {
+  const monitoring = INSTALLABLE_PACKAGES.find((entry) => entry.key === 'monitoring');
+  assert.ok(monitoring);
+  assert.equal(packageSpec(monitoring), 'openbroker-monitoring@latest');
+  assert.equal(packageSpec(monitoring, '1.4.2'), 'openbroker-monitoring@1.4.2');
+  assert.throws(() => packageSpec(monitoring, 'npm:unrelated-package'));
+  assert.throws(() => packageSpec(monitoring, '../local-package'));
+});
+
+test('installer dry run prints the global npm operation without writing', () => {
+  const result = spawnSync(
+    process.execPath,
+    ['--import', 'tsx', installScript, 'monitoring', '--tag', '1.4.2', '--dry'],
+    { encoding: 'utf8' },
+  );
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /npm install --global openbroker-monitoring@1\.4\.2/);
+  assert.match(result.stdout, /nothing was installed/i);
+});
+
+test('installer rejects packages outside the catalog', () => {
+  const result = spawnSync(
+    process.execPath,
+    ['--import', 'tsx', installScript, 'unrelated-package', '--dry'],
+    { encoding: 'utf8' },
+  );
+
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /unknown installable package/i);
+});