openbroker 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to Open Broker will be documented in this file.
 
+## [1.3.0] - 2026-05-07
+
+### Added
+- **`openbroker auto prune`**: New subcommand for trimming the local audit DB
+  - `--older-than <duration>` accepts `7d`, `24h`, `30m`, etc.
+  - `--status <list>` filters by run status (default: `stopped,error,stale`)
+  - `--keep-last <N>` retains the N most-recent runs per `automation_id`
+  - `--all` deletes everything except runs whose process is still alive
+  - `--vacuum` reclaims disk after deletion
+  - `--dry` previews matches without writing — also reconcile is dry-safe
+
+### Changed
+- **`openbroker auto clean`**: Now also reconciles the audit DB. Runs whose pid is dead but whose row still says `status='running'` get marked `stopped` with `stop_reason='reconciled (process exited)'`, fixing dashboards that previously kept rendering them as live/stale long after `auto stop`.
+
 ## [1.0.59] - 2026-03-11
 
 ### Fixed

package/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: openbroker
+description: Hyperliquid trading CLI skill for agents. Use when an agent needs to inspect markets/accounts, place or manage perp/spot/HIP-4 orders, or write and run Hyperliquid trading automations directly through the `openbroker` CLI without requiring the OpenClaw plugin.
+license: MIT
+compatibility: Requires Node.js 22+, network access to api.hyperliquid.xyz
+homepage: https://www.npmjs.com/package/openbroker
+metadata: {"author": "monemetrics", "version": "1.3.1"}
+allowed-tools: Bash(openbroker:*)
+---
+
+# OpenBroker — Hyperliquid CLI skill
+
+OpenBroker is first a CLI. The OpenClaw plugin is optional: use `ob_*` tools when present for common structured calls, but keep the CLI model in mind because it is the complete surface area and the safest fallback.
+
+## Operating rules
+
+- For unfamiliar assets, **search before trading**. Hyperliquid has main perps, HIP-3 perps, spot markets, and HIP-4 outcomes that can share names.
+- Prefer `--json` for machine-readable info commands.
+- Before any write, verify the asset, account, open positions/orders, size, and whether the action should be reduce-only.
+- For new or changed trading logic, start with `--dry`, inspect the plan/audit trail, then go live only when that matches the user’s intent.
+- Treat CLI output as exchange state, not just prose: parse order IDs, balances, fills, and errors instead of assuming success.
+
+## Setup and identity
+
+```bash
+npm install -g openbroker
+openbroker setup
+openbroker account --json
+```
+
+`setup` supports:
+
+1. **Fresh wallet** — simplest for agents; builder fee approval is handled automatically.
+2. **Imported key** — use an existing wallet.
+3. **API wallet** — can trade but not withdraw; the human owner must approve it in a browser.
+
+For API wallets, `HYPERLIQUID_PRIVATE_KEY` is the signing key and `HYPERLIQUID_ACCOUNT_ADDRESS` must be the funded master account. If account output shows `$0` equity unexpectedly, check that mapping first.
+
+Common globals:
+
+| Flag | Meaning |
+|---|---|
+| `-c, --config <path>` | Use a specific `.env` file |
+| `--testnet` | Use testnet |
+| `--dry` | Preview write commands without executing |
+| `--verbose` | Debug output |
+| `--json` | Machine-readable output on info commands |
+
+## Asset discovery and IDs
+
+```bash
+openbroker search --query GOLD --json
+openbroker search --query BTC --type perp --json
+openbroker all-markets --type hip3 --json
+openbroker outcomes --query BTC --json
+```
+
+- HIP-3 perps use `dex:COIN`, e.g. `xyz:CL`, not bare `CL`.
+- `assetId` is the canonical identifier for comparisons and persisted agent state; order placement still uses `--coin`.
+- HIP-4 outcome orders use `--outcome <id|#encoding|+encoding>` plus `--outcome-side yes|no` when the reference is a plain ID.
+- On testnet, HIP-3 metadata may need an explicit prefixed coin such as `dex:COIN`.
+
+## CLI command map
+
+### Info commands
+
+Most info commands accept `--json`. Use `--coin`, `--top`, and `--address` where the command supports them rather than repeating bespoke parsing logic.
+
+| Command | Main use | Distinct flags |
+|---|---|---|
+| `account` | Equity, margin, spot balances, positions | `--orders`, `--address` |
+| `positions` | Open perp positions and liquidation distance | `--coin`, `--address` |
+| `funding` | Funding rates | `--coin`, `--top`, `--sort annualized|hourly|oi`, `--all`, `--include-hip3` |
+| `markets` | Perp market data | `--coin`, `--top`, `--sort volume|oi|change`, `--include-hip3` |
+| `all-markets` | Browse every venue type | `--type perp|hip3|spot|outcome|all`, `--top` |
+| `search` | Find markets across providers | `--query`, `--type` |
+| `spot` | Spot markets or balances | `--coin`, `--balances`, `--address`, `--top` |
+| `fills` | Recent fills | `--coin`, `--side buy|sell`, `--top`, `--address` |
+| `orders` | Order history/open orders | `--coin`, `--status`, `--open`, `--top`, `--address` |
+| `order-status` | One order by exchange/client ID | `--oid`, `--address` |
+| `fees` | Fee tier and rates | `--address` |
+| `candles` | OHLCV | `--coin`, `--interval`, `--bars` |
+| `funding-history` | Historical funding | `--coin`, `--hours` |
+| `trades` | Recent tape | `--coin`, `--top` |
+| `rate-limit` | API usage | — |
+| `funding-scan` | Cross-dex scan | `--threshold`, `--main-only`, `--hip3-only`, `--pairs`, `--watch`, `--interval`, `--top` |
+| `outcomes` | HIP-4 discovery/balances | `--query`, `--outcome`, `--side`, `--balances`, `--top` |
+
+### Perp trading
+
+Shared perp order flags:
+
+| Flag | Meaning |
+|---|---|
+| `--coin <COIN>` | Main perp or HIP-3 `dex:COIN` |
+| `--side buy|sell` | Required except `buy` / `sell` shortcuts |
+| `--size <SIZE>` | Base-asset size |
+| `--leverage <N>` | Main perps use cross; HIP-3 uses isolated |
+| `--reduce` | Reduce-only; use when closing/reducing exposure |
+| `--slippage <bps>` | Market/SL slippage tolerance |
+
+| Command | Shape |
+|---|---|
+| `buy`, `sell` | Market shortcuts: `openbroker buy --coin ETH --size 0.1` |
+| `market` | Explicit market order with `--side` |
+| `limit` | Add `--price` and optional `--tif GTC|IOC|ALO` |
+| `trigger` | Add `--trigger`, `--type tp|sl`, optional `--limit` |
+| `tpsl` | Protect an existing position with `--tp` and/or `--sl`; accepts absolute, `%`, or `entry` forms |
+| `cancel` | `--all`, `--coin`, or `--oid` |
+
+### Spot and HIP-4 outcome trading
+
+| Family | Commands | Shared flags |
+|---|---|---|
+| Spot | `spot-buy`, `spot-sell`, `spot-order` | `--coin`, `--side`, `--size`, optional `--price`, `--tif Gtc|Ioc|Alo`, `--slippage` |
+| Outcomes | `outcome-buy`, `outcome-sell`, `outcome-open`, `outcome-close`, `outcome-order` | `--outcome`, `--outcome-side`, `--side`, `--size`, optional `--price`, `--tif`, `--slippage`, `--sz-decimals` |
+
+### Advanced execution
+
+| Command | Use | Distinct flags |
+|---|---|---|
+| `twap` | Exchange-managed TWAP | `--duration`, `--randomize`, `--reduce-only` |
+| `twap-cancel` | Stop a TWAP | `--coin`, `--twap-id` |
+| `twap-status` | Inspect TWAPs | `--active` |
+| `scale` | Multi-level ladder | `--levels`, `--range`, `--distribution linear|exponential|flat`, `--tif` |
+| `bracket` | Entry + TP + SL | `--entry market|limit`, `--price`, `--tp`, `--sl` |
+| `chase` | Repriced ALO order | `--offset`, `--timeout`, `--interval`, `--max-chase` |
+
+## High-signal workflows
+
+Inspect before trading:
+
+```bash
+openbroker search --query HYPE --json
+openbroker account --orders --json
+openbroker positions --json
+openbroker markets --coin HYPE --json
+openbroker buy --coin HYPE --size 1 --dry
+```
+
+Close rather than flip:
+
+```bash
+openbroker positions --coin ETH --json
+openbroker sell --coin ETH --size 0.1 --reduce --dry
+```
+
+For large or passive execution, prefer `limit`, `chase`, `scale`, or `twap` over a blind market order.
+
+## Automations
+
+Automations are TypeScript scripts run by the CLI:
+
+```bash
+openbroker auto run <script> [--id <name>] [--set key=value] [--poll <ms>] [--dry]
+```
+
+Management commands:
+
+| Command | Use |
+|---|---|
+| `auto examples` | Inspect bundled examples and schemas |
+| `auto run <script>` | Run a custom script by path or from `~/.openbroker/automations/` |
+| `auto list` | List available automations |
+| `auto status` | Show running automations |
+| `auto stop <id>` | Unregister/stop an automation |
+| `auto report <id>` | Summarize audit data |
+| `auto clean` | Reconcile stale registry entries |
+| `auto prune ...` | Delete old audit runs |
+
+Run flags:
+
+| Flag | Meaning |
+|---|---|
+| `--set key=value` | Repeatable typed config values |
+| `--id <name>` | Stable automation ID |
+| `--poll <ms>` | Poll interval, minimum 1000 ms |
+| `--dry` | Intercept write methods |
+| `--no-ws` | Disable WebSocket and rely on REST polling |
+| `--allow-sleep` | Do not request OS sleep inhibition |
+
+Bundled examples are **references, not production strategies**. Read them for API patterns, then write a purpose-built script with explicit sizing, exit logic, and failure behavior.
+
+### Automation API essentials
+
+- `api.client` — full Hyperliquid client.
+- `api.on(...)`, `api.every(...)`, `api.onStart(...)`, `api.onStop(...)`, `api.onError(...)`.
+- `api.state` — persisted state; survives restarts.
+- `api.audit.record(...)` / `api.audit.metric(...)` — durable observability.
+- `api.publish(...)` — notify an OpenClaw agent when hooks are configured.
+- `api.dryRun` — whether writes are intercepted.
+
+Core events include `tick`, `price_change`, `funding_update`, `position_opened`, `position_closed`, `position_changed`, `pnl_threshold`, `margin_warning`, `order_filled`, `order_update`, and `liquidation`.
+
+### Monitoring and dashboard
+
+`openbroker-monitoring` is optional but useful for long-running automations, live debugging, and post-run inspection.
+
+```bash
+npm install openbroker-monitoring
+openbroker auto run ./my-automation.ts --id my-auto
+openbroker-monitoring serve --host 127.0.0.1 --port 3001
+```
+
+- The local dashboard reads `~/.openbroker/automation-audit.sqlite` directly; it works for any standard `openbroker auto run` automation and does **not** need vault config, webhooks, or remote forwarding.
+- Configure it with `OB_MONITOR_HOST`, `OB_MONITOR_PORT`, or `OPENBROKER_AUDIT_DB_PATH`, or the equivalent `serve --host/--port/--db` flags.
+- When installed alongside OpenBroker, the package is convention-loaded as an audit observer. Remote forwarding is separate and only activates when `OB_DASHBOARD_URL` plus `HYPERSTABLE_VAULT_ADDRESS` or `VAULT` are configured; `OB_DASHBOARD_API_KEY` is optional.
+- Start the dashboard when the user wants a live view, troubleshooting help, or ongoing monitoring. It is helpful infrastructure, not a prerequisite for every automation.
+
+### Hyperliquid automation design rules
+
+These matter more than boilerplate:
+
+1. **Model the strategy as a state machine.** Persist flags, streaks, targets, and recovery state with `api.state`; handlers can fire repeatedly and processes can restart.
+2. **Use hysteresis, not one-print decisions.** Confirmation loops, separate enter/exit thresholds, and debounce logic prevent churn from noisy funding or tiny price moves.
+3. **Use the freshest correct signal.** For funding strategies, prefer `getPredictedFundings()` when available; if you fall back to instantaneous funding from metadata, ensure the metadata cache is refreshed so the signal does not freeze after startup.
+4. **Price the flip, not just the signal.** Before closing and later reopening a carry, compare expected hold cost with round-trip trading cost. The HYPE carry automation counts maker fees across both legs plus builder fees before deciding whether a mildly negative funding window is worth exiting.
+5. **Respect settlement timing.** If the current predicted funding is still positive, a close right before hourly settlement can be economically wrong even when the broader signal weakened. Add a settlement-proximity guard when the strategy depends on funding capture.
+6. **Sequence multi-leg hedges deliberately.** For spot-long / perp-short carry, build spot first, then short only up to spot-backed exposure; unwind spot first, then close the short reduce-only. Recover accidental one-sided exposure explicitly instead of pretending it cannot happen.
+7. **Separate strategy logic from execution policy.** Maker-first execution can reduce fees, but it needs bounded retries, post-only rejection handling, order cancellation, partial-fill accounting, minimum trade thresholds, and a defined IOC fallback. Measure progress from refreshed balances/positions, not only from submit responses.
+8. **Size from real NAV and hard caps.** Multi-leg strategies often need spot balances, spot USDC, and perp account value combined; a 50/50 carry target derived from total NAV must then be halved per side and still respect a hard per-side cap.
+9. **Define stop behavior intentionally.** On shutdown, always handle working orders, but do not blindly flatten every strategy. A hedged carry may need “preserve hedge and alert,” while a transient execution bot may need “cancel and flatten.”
+10. **Instrument first-class decisions.** Log and audit funding source, targets, leg notionals, settlement distance, hold/close decisions, fills, retries, and error paths. If using the plugin, publish events that need human attention.
+
+Additional practical caveats:
+
+- Positive-funding carry and negative-funding carry are not automatically symmetric. If the hedge requires short spot and the client/runtime cannot express that safely, do not invent an unhedged mirror trade.
+- `funding_update` fires for many assets every poll; filter by coin early.
+- Dust matters: if residual size falls below exchange precision or `minTradeUsd`, stop chasing it.
+- `ALO` / post-only orders can be rejected when they would cross; treat that as an execution branch, not a surprise.
+- Naked directional positions usually need explicit TP/SL or equivalent risk logic. Hedged multi-leg strategies need strategy-specific exits instead of cargo-cult TP/SL rules.
+- For new automations, do a dry run, inspect `auto report`, and only then run live unless the user explicitly requested immediate live execution.
+
+## Plugin-aware use
+
+When the OpenClaw plugin is available:
+
+- Prefer `ob_*` tools for common structured reads and simple writes.
+- Use `ob_watcher_status` for background monitoring state.
+- Use `ob_auto_run`, `ob_auto_stop`, and `ob_auto_list` for supported automation actions.
+- Fall back to the CLI for unsupported commands, debugging, richer flags, or if a tool returns empty/unexpected data.
+
+Representative mappings:
+
+| Plugin tool | CLI equivalent |
+|---|---|
+| `ob_account` | `openbroker account --json` |
+| `ob_positions` | `openbroker positions --json` |
+| `ob_funding` | `openbroker funding --json --include-hip3` |
+| `ob_search` | `openbroker search --query <QUERY> --json` |
+| `ob_buy` / `ob_sell` | `openbroker buy|sell --coin <COIN> --size <SIZE>` |
+| `ob_limit` | `openbroker limit ...` |
+| `ob_tpsl` | `openbroker tpsl ...` |
+| `ob_auto_run` | `openbroker auto run <script> ...` |
+
+Skill-only mode is fully usable through the CLI; the plugin adds agent tools, watcher notifications, and OpenClaw webhook integration.
+
+## Failure checks
+
+- `No market data found` → search again; likely wrong venue prefix.
+- `$0` equity on an API wallet → likely missing `HYPERLIQUID_ACCOUNT_ADDRESS`.
+- Unexpected funding behavior → check whether you are reading predicted vs cached instantaneous data.
+- Strategy churn → inspect confirmation loops, fee-aware hold logic, settlement guards, and min-trade thresholds before changing position size.
+- Tool failure in plugin mode → rerun the equivalent CLI command with `--json` and `--verbose` if needed.

package/bin/openbroker.js

@@ -25,6 +25,9 @@ const child = spawn(
       OPENBROKER_CWD: process.cwd(),
       // Suppress Node.js experimental warnings
       NODE_NO_WARNINGS: '1',
+      // node:sqlite is stable in Node 24+, experimental-with-flag in 22/23.
+      // The flag is accepted (as a no-op) on 24+, so it's safe to set unconditionally.
+      NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --experimental-sqlite`.trim(),
     },
   }
 );
@@ -42,6 +45,7 @@ child.on('error', (err) => {
           ...process.env,
           OPENBROKER_CWD: process.cwd(),
           NODE_NO_WARNINGS: '1',
+          NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --experimental-sqlite`.trim(),
         },
       }
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {
@@ -15,6 +15,7 @@
     "bin/",
     "scripts/",
     "config/example.env",
+    "SKILL.md",
     "README.md",
     "CHANGELOG.md"
   ],

package/scripts/auto/cli.ts

@@ -23,7 +23,8 @@ Usage:
   openbroker auto stop <id>                 Unregister an automation (won't restart)
   openbroker auto list                      List available automations
   openbroker auto status                    Show running automations
-  openbroker auto clean                     Remove stale entries from registry
+  openbroker auto clean                     Remove stale entries from registry + reconcile audit DB
+  openbroker auto prune [options]           Delete stale runs from the audit DB
 
 Options (for run):
   --example <name>   Run a bundled example (dca, grid, funding-arb, mm-spread, mm-maker)
@@ -33,6 +34,15 @@ Options (for run):
   --id <name>        Custom automation ID (default: filename)
   --poll <ms>        Poll interval in milliseconds (default: 10000)
   --no-ws            Disable WebSocket; fall back to REST-only polling
+  --allow-sleep      Do not request OS idle-sleep inhibition for this run
+
+Options (for prune):
+  --older-than <d>   Only prune runs started before this duration ago (e.g. 7d, 24h)
+  --status <list>    CSV of statuses to consider (default: stopped,error,stale)
+  --keep-last <N>    Keep the N most-recent runs per automation_id
+  --all              Prune everything except runs that are still alive
+  --vacuum           VACUUM the DB after deletion to reclaim disk space
+  --dry              Preview what would be deleted without writing
 
 Scripts are loaded from:
   1. Absolute or relative path
@@ -116,6 +126,7 @@ async function runCommand(args: Record<string, string | boolean>, positional: st
   const dryRun = args.dry === true;
   const verbose = args.verbose === true;
   const useWebSocket = args['no-ws'] !== true;
+  const keepAwake = args['allow-sleep'] === true ? false : undefined;
   const pollIntervalMs = args.poll ? parseInt(String(args.poll), 10) : undefined;
   const id = args.id ? String(args.id) : undefined;
 
@@ -141,6 +152,7 @@ async function runCommand(args: Record<string, string | boolean>, positional: st
     verbose,
     pollIntervalMs,
     useWebSocket,
+    keepAwake,
     initialState: Object.keys(initialState).length > 0 ? initialState : undefined,
     hooksToken: envHooksToken,
     gatewayPort: envGatewayPort && !isNaN(envGatewayPort) ? envGatewayPort : undefined,
@@ -288,9 +300,83 @@ function stopCommand(positional: string[]) {
   console.log(`Unregistered: ${id} (will not restart on next gateway start)`);
 }
 
-function cleanCommand() {
+async function cleanCommand() {
   cleanRegistry();
   console.log('Cleaned stale entries from registry');
+
+  // Also reconcile the audit DB so dead processes whose rows still say
+  // 'running' get marked 'stopped'. Without this, the dashboard keeps showing
+  // 'stale' badges for automations the operator already cleaned out of the
+  // registry.
+  try {
+    const { prune } = await import('./prune.js');
+    const result = prune({ reconcileOnly: true });
+    if (result.reconciled > 0) {
+      console.log(`Reconciled ${result.reconciled} orphan run row${result.reconciled === 1 ? '' : 's'} in audit DB (status: running → stopped)`);
+    } else {
+      console.log('Audit DB already consistent');
+    }
+  } catch (err) {
+    console.warn(`Could not reconcile audit DB: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+async function pruneCommand(args: Record<string, string | boolean>) {
+  const { fmtBytes, parseDuration, prune } = await import('./prune.js');
+  const olderThanRaw = args['older-than'];
+  const olderThanMs = typeof olderThanRaw === 'string' ? parseDuration(olderThanRaw) : undefined;
+  const statusesRaw = typeof args.status === 'string' ? args.status : undefined;
+  const statuses = statusesRaw
+    ? new Set(statusesRaw.split(',').map((s) => s.trim()).filter(Boolean))
+    : undefined;
+  const keepLastRaw = args['keep-last'];
+  const keepLast = typeof keepLastRaw === 'string' ? Number(keepLastRaw)
+    : typeof keepLastRaw === 'number' ? keepLastRaw
+    : undefined;
+  if (keepLast !== undefined && (!Number.isFinite(keepLast) || keepLast < 0)) {
+    console.error('Error: --keep-last must be a non-negative integer');
+    process.exit(1);
+  }
+
+  const opts = {
+    olderThanMs,
+    statuses,
+    keepLastPerAutomation: keepLast,
+    all: args.all === true,
+    vacuum: args.vacuum === true,
+    dryRun: args.dry === true,
+  };
+
+  const result = prune(opts);
+
+  if (result.reconciled > 0) {
+    const verb = result.dryRun ? 'Would reconcile' : 'Reconciled';
+    console.log(`${verb} ${result.reconciled} orphan run row${result.reconciled === 1 ? '' : 's'} (running → stopped)`);
+  }
+
+  const verb = result.dryRun ? 'Would delete' : 'Deleted';
+  if (result.candidateRunIds.length === 0) {
+    console.log('No runs matched pruning filters.');
+    return;
+  }
+  console.log(`${verb} ${result.candidateRunIds.length} automation run${result.candidateRunIds.length === 1 ? '' : 's'}:`);
+  for (const id of result.candidateRunIds.slice(0, 25)) {
+    console.log(`  · ${id}`);
+  }
+  if (result.candidateRunIds.length > 25) {
+    console.log(`  … and ${result.candidateRunIds.length - 25} more`);
+  }
+  if (!result.dryRun) {
+    const totalChild = Object.values(result.deletedRows).reduce((a, b) => a + b, 0);
+    console.log(`Removed ${totalChild.toLocaleString()} child rows across ${Object.keys(result.deletedRows).length} tables`);
+    if (result.freedBytes > 0) {
+      console.log(`Reclaimed ~${fmtBytes(result.freedBytes)}${opts.vacuum ? ' (post-VACUUM)' : ''}`);
+    } else if (opts.vacuum) {
+      console.log('No disk reclaimed (VACUUM completed)');
+    } else {
+      console.log('Run again with --vacuum to reclaim disk space.');
+    }
+  }
 }
 
 function reportCommand(rawArgs: string[]) {
@@ -364,7 +450,10 @@ async function main() {
       statusCommand();
       break;
     case 'clean':
-      cleanCommand();
+      await cleanCommand();
+      break;
+    case 'prune':
+      await pruneCommand(args);
       break;
     case 'report':
       reportCommand(restArgs);

package/scripts/auto/keep-awake.ts

@@ -0,0 +1,100 @@
+import { spawn, type ChildProcess } from 'child_process';
+
+type KeepAwakeLogger = {
+  info(message: string): void;
+  warn(message: string): void;
+};
+
+export interface KeepAwakeHandle {
+  backend: string;
+  stop(): void;
+}
+
+function createHandle(
+  child: ChildProcess,
+  backend: string,
+  log: KeepAwakeLogger,
+): KeepAwakeHandle {
+  let stopping = false;
+
+  child.once('error', (error) => {
+    if (!stopping) {
+      log.warn(`keep-awake unavailable via ${backend}: ${error.message}`);
+    }
+  });
+
+  child.once('exit', (code, signal) => {
+    if (!stopping) {
+      const suffix = signal ? `signal ${signal}` : `code ${code ?? 'unknown'}`;
+      log.warn(`keep-awake helper ${backend} exited unexpectedly (${suffix}); host may sleep.`);
+    }
+  });
+
+  return {
+    backend,
+    stop() {
+      stopping = true;
+      if (!child.killed) child.kill();
+    },
+  };
+}
+
+function startDarwin(log: KeepAwakeLogger): KeepAwakeHandle {
+  const child = spawn('caffeinate', ['-i', '-w', String(process.pid)], {
+    stdio: 'ignore',
+  });
+  return createHandle(child, 'caffeinate', log);
+}
+
+function startLinux(reason: string, log: KeepAwakeLogger): KeepAwakeHandle {
+  const child = spawn(
+    'systemd-inhibit',
+    [
+      '--what=sleep',
+      '--who=OpenBroker',
+      `--why=${reason}`,
+      '--mode=block',
+      'sh',
+      '-c',
+      'while kill -0 "$1" 2>/dev/null; do sleep 30; done',
+      'sh',
+      String(process.pid),
+    ],
+    { stdio: 'ignore' },
+  );
+  return createHandle(child, 'systemd-inhibit', log);
+}
+
+function startWindows(log: KeepAwakeLogger): KeepAwakeHandle {
+  const script = [
+    'Add-Type -Namespace OpenBroker -Name Native -MemberDefinition',
+    '\'"[DllImport(\\\"kernel32.dll\\\")] public static extern uint SetThreadExecutionState(uint esFlags);"\';',
+    '[OpenBroker.Native]::SetThreadExecutionState(0x80000001) | Out-Null;',
+    `Wait-Process -Id ${process.pid};`,
+    '[OpenBroker.Native]::SetThreadExecutionState(0x80000000) | Out-Null;',
+  ].join(' ');
+
+  const child = spawn(
+    'powershell.exe',
+    ['-NoProfile', '-NonInteractive', '-Command', script],
+    {
+      stdio: 'ignore',
+      windowsHide: true,
+    },
+  );
+  return createHandle(child, 'SetThreadExecutionState', log);
+}
+
+export function startKeepAwake(reason: string, log: KeepAwakeLogger): KeepAwakeHandle | null {
+  switch (process.platform) {
+    case 'darwin':
+      return startDarwin(log);
+    case 'linux':
+      return startLinux(reason, log);
+    case 'win32':
+      return startWindows(log);
+    default:
+      log.warn(`keep-awake is not supported on platform ${process.platform}; host may sleep.`);
+      return null;
+  }
+}

package/scripts/auto/prune.ts

@@ -0,0 +1,252 @@
+// Audit DB pruning — delete stale automation runs and their child rows.
+//
+// The audit DB is the same SQLite file the daemon writes to and the dashboard
+// reads from. WAL mode lets us open it from another process for delete writes
+// without blocking the daemon. We always protect runs whose status is 'running'
+// AND whose pid is alive.
+//
+// Used by: `openbroker auto prune` and as a sub-step of `openbroker auto clean`.
+
+import os from 'os';
+import path from 'path';
+import { existsSync } from 'fs';
+import { DatabaseSync } from 'node:sqlite';
+import { ensureConfigDir } from '../core/config.js';
+
+export const AUDIT_DB_PATH = process.env.OPENBROKER_AUDIT_DB_PATH
+  || path.join(ensureConfigDir(), 'automation-audit.sqlite');
+
+export interface PruneFilters {
+  /** Delete runs whose started_at < (now - olderThanMs). Falsy = no age filter. */
+  olderThanMs?: number;
+  /** Delete runs whose status is in this set. Default: stopped, error, stale. */
+  statuses?: Set<string>;
+  /** For each automation_id, keep the N most recent runs regardless of other filters. */
+  keepLastPerAutomation?: number;
+  /** Delete every run that is not currently alive (overrides status/age). */
+  all?: boolean;
+}
+
+export interface PruneOptions extends PruneFilters {
+  dbPath?: string;
+  dryRun?: boolean;
+  vacuum?: boolean;
+  /**
+   * When true, skip the deletion phase and only update status of orphaned
+   * 'running' rows whose pid is dead — used by `auto clean` to reconcile state
+   * without losing history.
+   */
+  reconcileOnly?: boolean;
+}
+
+export interface PruneResult {
+  reconciled: number;
+  candidateRunIds: string[];
+  deletedRows: Record<string, number>;
+  freedBytes: number;
+  dryRun: boolean;
+}
+
+const CHILD_TABLES = [
+  'automation_logs',
+  'automation_events',
+  'automation_actions',
+  'automation_snapshots',
+  'automation_order_updates',
+  'automation_fills',
+  'automation_user_events',
+  'automation_state_changes',
+  'automation_publishes',
+  'automation_errors',
+  'automation_notes',
+  'automation_metrics',
+] as const;
+
+const DEFAULT_STATUSES = new Set(['stopped', 'error', 'stale']);
+
+function isProcessAlive(pid: number | null | undefined): boolean {
+  if (typeof pid !== 'number' || !Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Parse human-friendly durations like `7d`, `24h`, `30m`, `45s`. */
+export function parseDuration(input: string): number {
+  const m = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d|w)?\s*$/.exec(input);
+  if (!m) throw new Error(`invalid duration: ${input}`);
+  const n = Number(m[1]);
+  const unit = m[2] ?? 'ms';
+  const mult: Record<string, number> = {
+    ms: 1, s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 7 * 86_400_000,
+  };
+  return n * mult[unit];
+}
+
+/** Reconcile orphan-running rows in the DB (process dead → mark stopped). */
+export function reconcileStaleRuns(db: DatabaseSync, opts: { dryRun?: boolean; now?: number } = {}): number {
+  const now = opts.now ?? Date.now();
+  const runningRows = db.prepare(`
+    SELECT run_id, pid FROM automation_runs WHERE status = 'running'
+  `).all() as { run_id: string; pid: number | null }[];
+
+  const orphans = runningRows.filter((r) => !isProcessAlive(r.pid));
+  if (orphans.length === 0) return 0;
+  if (opts.dryRun) return orphans.length;
+
+  const update = db.prepare(`
+    UPDATE automation_runs
+    SET status = 'stopped',
+        stop_reason = COALESCE(stop_reason, 'reconciled (process exited)'),
+        stopped_at = COALESCE(stopped_at, ?)
+    WHERE run_id = ?
+  `);
+  let n = 0;
+  for (const o of orphans) {
+    update.run(now, o.run_id);
+    n++;
+  }
+  return n;
+}
+
+export function prune(opts: PruneOptions = {}): PruneResult {
+  const dbPath = opts.dbPath ?? AUDIT_DB_PATH;
+  if (!existsSync(dbPath)) {
+    return {
+      reconciled: 0,
+      candidateRunIds: [],
+      deletedRows: {},
+      freedBytes: 0,
+      dryRun: !!opts.dryRun,
+    };
+  }
+
+  const db = new DatabaseSync(dbPath);
+  db.exec('PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000;');
+
+  try {
+    const reconciled = reconcileStaleRuns(db, { dryRun: opts.dryRun });
+    if (opts.reconcileOnly) {
+      return {
+        reconciled,
+        candidateRunIds: [],
+        deletedRows: {},
+        freedBytes: 0,
+        dryRun: !!opts.dryRun,
+      };
+    }
+
+    const allRuns = db.prepare(`
+      SELECT run_id, automation_id, status, pid, started_at
+      FROM automation_runs
+      ORDER BY started_at DESC
+    `).all() as {
+      run_id: string;
+      automation_id: string;
+      status: string;
+      pid: number | null;
+      started_at: number;
+    }[];
+
+    const statuses = opts.statuses ?? DEFAULT_STATUSES;
+    const cutoff = opts.olderThanMs && opts.olderThanMs > 0 ? Date.now() - opts.olderThanMs : null;
+
+    // group runs per automation_id (already sorted DESC by started_at)
+    const byAuto = new Map<string, typeof allRuns>();
+    for (const r of allRuns) {
+      const arr = byAuto.get(r.automation_id) ?? [];
+      arr.push(r);
+      byAuto.set(r.automation_id, arr);
+    }
+
+    const candidates: typeof allRuns = [];
+
+    for (const [, runs] of byAuto) {
+      const protectedIdx = new Set<number>();
+      if (opts.keepLastPerAutomation && opts.keepLastPerAutomation > 0) {
+        for (let i = 0; i < Math.min(opts.keepLastPerAutomation, runs.length); i++) {
+          protectedIdx.add(i);
+        }
+      }
+      runs.forEach((r, i) => {
+        if (protectedIdx.has(i)) return;
+        // never delete a truly-running automation
+        if (r.status === 'running' && isProcessAlive(r.pid)) return;
+        if (opts.all) {
+          candidates.push(r);
+          return;
+        }
+        if (!statuses.has(r.status)) {
+          // 'running' rows that aren't actually alive were just reconciled to
+          // 'stopped' above, so the status check catches them.
+          return;
+        }
+        if (cutoff !== null && r.started_at >= cutoff) return;
+        candidates.push(r);
+      });
+    }
+
+    const candidateRunIds = candidates.map((r) => r.run_id);
+    const deletedRows: Record<string, number> = {};
+    let freedBytes = 0;
+
+    if (!opts.dryRun && candidateRunIds.length > 0) {
+      const sizeBefore = db.prepare('PRAGMA page_count').get() as { page_count: number };
+      const pageSize = db.prepare('PRAGMA page_size').get() as { page_size: number };
+
+      db.exec('BEGIN');
+      try {
+        for (const table of CHILD_TABLES) {
+          let n = 0;
+          const stmt = db.prepare(`DELETE FROM ${table} WHERE run_id = ?`);
+          for (const id of candidateRunIds) {
+            const info = stmt.run(id) as { changes?: number };
+            n += Number(info.changes ?? 0);
+          }
+          deletedRows[table] = n;
+        }
+        const runStmt = db.prepare('DELETE FROM automation_runs WHERE run_id = ?');
+        let runChanges = 0;
+        for (const id of candidateRunIds) {
+          const info = runStmt.run(id) as { changes: number };
+          runChanges += Number(info.changes ?? 0);
+        }
+        deletedRows.automation_runs = runChanges;
+        db.exec('COMMIT');
+      } catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+      }
+
+      if (opts.vacuum) {
+        // VACUUM cannot run inside a transaction
+        db.exec('VACUUM');
+      }
+
+      const sizeAfter = db.prepare('PRAGMA page_count').get() as { page_count: number };
+      freedBytes = (Number(sizeBefore.page_count) - Number(sizeAfter.page_count)) * Number(pageSize.page_size);
+    }
+
+    return {
+      reconciled,
+      candidateRunIds,
+      deletedRows,
+      freedBytes: Math.max(0, freedBytes),
+      dryRun: !!opts.dryRun,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+export function fmtBytes(n: number): string {
+  if (!Number.isFinite(n) || n <= 0) return '0 B';
+  const u = ['B', 'KB', 'MB', 'GB'];
+  let i = 0;
+  let v = n;
+  while (v >= 1024 && i < u.length - 1) { v /= 1024; i++; }
+  return `${v.toFixed(v >= 100 || i === 0 ? 0 : 1)} ${u[i]}`;
+}

package/scripts/auto/runtime.ts

@@ -15,6 +15,7 @@ import { AutomationEventBus } from './events.js';
 import { loadAutomation } from './loader.js';
 import { registerAutomation, unregisterAutomation, getRegisteredAutomations as getRegisteredFromFile } from './registry.js';
 import { createAutomationAudit, toSerializable, type AutomationAuditSink } from './audit.js';
+import { startKeepAwake, type KeepAwakeHandle } from './keep-awake.js';
 import type {
   AutomationAPI,
   AutomationAuditObserver,
@@ -288,6 +289,12 @@ function createAuditedClient(
 async function buildSnapshot(
   client: HyperliquidClient,
 ): Promise<AutomationSnapshot> {
+  // `metaAndAssetCtxs` contains both mostly-static market metadata and live
+  // funding/premium values. The client caches it for market lookups, so clear
+  // it before each automation poll snapshot or funding_update events freeze at
+  // the first fetched value.
+  client.invalidateMetaCache();
+
   const [state, mids, metaCtxs] = await Promise.all([
     client.getUserStateAll(),
     client.getAllMids(),
@@ -321,20 +328,29 @@ async function buildSnapshot(
 
   // Build funding rates from asset contexts
   const fundingRates = new Map<string, { rate: number; premium: number }>();
+  const addFundingRates = (
+    universe: Array<{ name?: string }> | undefined,
+    assetCtxs: Array<{ funding?: string | number | null; premium?: string | number | null }> | undefined,
+  ) => {
+    if (!universe || !assetCtxs) return;
+    for (let i = 0; i < universe.length; i++) {
+      const meta = universe[i];
+      const ctx = assetCtxs[i];
+      if (ctx && meta?.name) {
+        fundingRates.set(meta.name, {
+          rate: parseFloat(String(ctx.funding || '0')),
+          premium: parseFloat(String(ctx.premium || '0')),
+        });
+      }
+    }
+  };
+
   if (metaCtxs && Array.isArray(metaCtxs)) {
     for (const group of metaCtxs) {
-      if (!group.universe || !group.assetCtxs) continue;
-      for (let i = 0; i < group.universe.length; i++) {
-        const meta = group.universe[i];
-        const ctx = group.assetCtxs[i];
-        if (ctx && meta) {
-          fundingRates.set(meta.name, {
-            rate: parseFloat(ctx.funding || '0'),
-            premium: parseFloat(ctx.premium || '0'),
-          });
-        }
-      }
+      addFundingRates(group.universe, group.assetCtxs);
     }
+  } else if (metaCtxs) {
+    addFundingRates(metaCtxs.meta?.universe, metaCtxs.assetCtxs);
   }
 
   return {
@@ -436,6 +452,11 @@ export interface RuntimeOptions {
    * @default true
    */
   useWebSocket?: boolean;
+  /**
+   * Best-effort host idle-sleep inhibition for the lifetime of the automation.
+   * Enabled by default for live runs and disabled by default for dry runs.
+   */
+  keepAwake?: boolean;
 }
 
 /** Registry of all running automations */
@@ -501,6 +522,14 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
   stateController.attachAudit(audit);
 
   const log = createLogger(id, verbose, audit);
+  const keepAwakeEnabled = options.keepAwake ?? !dryRun;
+  let keepAwake: KeepAwakeHandle | null = null;
+  if (keepAwakeEnabled) {
+    keepAwake = startKeepAwake(`OpenBroker automation ${id} is running`, log);
+    if (keepAwake) {
+      log.info(`keep-awake enabled via ${keepAwake.backend}.`);
+    }
+  }
   const observers = await loadConventionObservers(log);
   const baseClient = dryRun ? createDryClient(rawClient, log) : rawClient;
   const client = createAuditedClient(baseClient, audit, dryRun, observers);
@@ -561,6 +590,7 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
       pollCount: 0,
       eventsEmitted: 0,
     });
+    keepAwake?.stop();
     throw error;
   }
 
@@ -934,6 +964,8 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
       }
     }
 
+    keepAwake?.stop();
+
     eventBus.removeAll();
     registry.delete(id);
 

package/scripts/core/client.ts

@@ -1067,7 +1067,11 @@ export class HyperliquidClient {
 
     const response = await fetch(baseUrl + '/info', {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-cache, no-store, max-age=0',
+        Pragma: 'no-cache',
+      },
       body: JSON.stringify({ type: 'predictedFundings' }),
     });
     const data = await response.json() as Array<[