perp-cli 0.12.17 → 0.14.1

package/dist/bot/quarantine.js

@@ -0,0 +1,190 @@
+/**
+ * Position quarantine (design §12.3) — GLOBAL per symbol.
+ *
+ * A spot leg whose outcome is unknown (ORDER_PENDING), a perp leg that could not be
+ * confirmed, a close whose post-trade verification failed, or a position left unhedged
+ * by a failed rollback must NOT be retried automatically: a retry can double-buy,
+ * double-sell or open a naked perp. Such a symbol is quarantined here, persisted in
+ * ~/.perp/bot-quarantine.json, and skipped by EVERY automated path — the bot strategies
+ * (funding-arb, funding-arb-v2, spot-perp-arb, funding-auto), `perp arb exec` (perp-perp
+ * and spot:<venue>) and the `perp arb auto` / `arb dex-auto` daemons — no entry, no close,
+ * no rotation — until a human clears it (`perp arb close` refuses it without --force):
+ *
+ *   perp strategy quarantine                       # list
+ *   perp strategy quarantine-clear <symbol> [--strategy <source>]
+ *
+ * Entries are stored per source ("<source>:<KEY>", source = strategy name or CLI path)
+ * but CHECKED by the canonical key alone (quarantineKey: HIP-3 dex prefix and "-PERP"
+ * stripped, DENOMINATION_ALIASES applied, uppercased — "xyz:TSLA" ≡ "TSLA", "KPEPE" ≡
+ * "1000PEPE"): one venue's unknown outcome blocks the underlying for all strategies,
+ * venues and processes. `entry.symbol` keeps the symbol as the source reported it. The file is re-read on every check, so a clear
+ * from the CLI takes effect in running bots on their next tick (no restart). Only an
+ * entry whose persist failed is held in process memory (logged CRITICAL); it holds
+ * until that process stops.
+ *
+ * Network scope: an entry records the network it was set on (`network`); a process that called
+ * setQuarantineNetwork(n) sees only entries of n plus entries of unknown network (null — set by
+ * a process that never declared its network: they apply to EVERY network, fail closed). Entries
+ * written before network scoping have no tag and are MAINNET (like the arb state's legacy file).
+ * A process that never declared its network sees every entry (fail closed). Mainnet / unknown
+ * entries keep the legacy key "<source>:<KEY>"; testnet ones are keyed "testnet:<source>:<KEY>".
+ * Every load → modify → save of the file holds the cross-process lock (withFileLock).
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { PerpError } from "../errors.js";
+import { DENOMINATION_ALIASES } from "../exchanges/canonical-symbols.js";
+import { withFileLock } from "../arb/file-lock.js";
+const PERP_DIR = resolve(process.env.HOME || "~", ".perp");
+export const QUARANTINE_FILE = resolve(PERP_DIR, "bot-quarantine.json");
+/** Entries whose persist failed, by "<source>:<KEY>" (this process only). */
+const unpersisted = new Map();
+/**
+ * Canonical quarantine key for a symbol — the ONLY way a symbol is compared here (set,
+ * check, clear): uppercased, HIP-3 dex prefix ("xyz:") and "-PERP" suffix stripped,
+ * DENOMINATION_ALIASES applied (KPEPE → 1000PEPE, UBTC → BTC).
+ */
+export function quarantineKey(symbol) {
+    let up = symbol.trim().toUpperCase();
+    const colon = up.lastIndexOf(":");
+    if (colon >= 0)
+        up = up.slice(colon + 1);
+    up = up.replace(/-PERP$/, "");
+    return DENOMINATION_ALIASES[up] ?? up;
+}
+/** The network this process trades on (setQuarantineNetwork); null = not declared → every entry applies. */
+let activeNetwork = null;
+/** Declare the network this process trades on: entries are set on it and checked against it. */
+export function setQuarantineNetwork(network) {
+    activeNetwork = network;
+}
+/** Test hook: back to "network not declared". */
+export function resetQuarantineNetwork() {
+    activeNetwork = null;
+}
+function keyOf(source, symbol, network) {
+    return `${network === "testnet" ? "testnet:" : ""}${source}:${quarantineKey(symbol)}`;
+}
+/** Does `e` block on this process's network? (unknown on either side → yes, fail closed) */
+function applies(e) {
+    return activeNetwork === null || e.network === null || e.network === activeNetwork;
+}
+/** Read the file. A missing file = nothing quarantined; an unreadable / malformed file throws (never "empty"). */
+function load() {
+    if (!existsSync(QUARANTINE_FILE))
+        return { version: 1, entries: {} };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(QUARANTINE_FILE, "utf-8"));
+    }
+    catch (e) {
+        throw new PerpError("INVALID_PARAMS", `Bot quarantine file is unreadable: ${QUARANTINE_FILE} (${e instanceof Error ? e.message : String(e)})`, {
+            remediation: `Fix or remove ${QUARANTINE_FILE} after verifying every quarantined position on the venues`,
+        });
+    }
+    const f = parsed;
+    if (f === null || f.version !== 1 || typeof f.entries !== "object" || f.entries === null) {
+        throw new PerpError("INVALID_PARAMS", `Bot quarantine file has an unexpected shape: ${QUARANTINE_FILE}`, {
+            remediation: `Fix or remove ${QUARANTINE_FILE} after verifying every quarantined position on the venues`,
+        });
+    }
+    // Legacy entries (written before network scoping) have no tag: they are mainnet.
+    for (const e of Object.values(f.entries)) {
+        if (e.network === undefined)
+            e.network = "mainnet";
+    }
+    return f;
+}
+function withQuarantineLock(fn) {
+    return withFileLock(QUARANTINE_FILE, "Bot quarantine file", fn);
+}
+function save(f) {
+    if (!existsSync(PERP_DIR))
+        mkdirSync(PERP_DIR, { recursive: true, mode: 0o700 });
+    const tmp = QUARANTINE_FILE + ".tmp";
+    writeFileSync(tmp, JSON.stringify(f, null, 2), { mode: 0o600 });
+    renameSync(tmp, QUARANTINE_FILE);
+}
+/**
+ * Quarantine `symbol` (for every strategy / CLI path) and log CRITICAL with the
+ * remediation. `source` records who did it. If persisting fails the entry is held in
+ * this process's memory and the failure is logged loudly.
+ */
+export function quarantineSymbol(source, symbol, reason, remediation, log) {
+    const sym = symbol.toUpperCase();
+    const key = quarantineKey(sym);
+    const entry = { strategy: source, symbol: sym, reason, remediation, time: new Date().toISOString(), network: activeNetwork };
+    const k = keyOf(source, sym, activeNetwork);
+    log(`  [QUARANTINE] CRITICAL: ${sym}${key !== sym ? ` (key ${key})` : ""} quarantined by ${source} — ${reason}`);
+    log(`  [QUARANTINE] Remediation: ${remediation}`);
+    log(`  [QUARANTINE] No bot / arb path will touch ${key} until cleared: perp strategy quarantine-clear ${key}`);
+    try {
+        withQuarantineLock(() => {
+            const f = load();
+            // Never narrow: an existing unknown-network entry under this key keeps applying everywhere.
+            if (f.entries[k]?.network === null)
+                entry.network = null;
+            f.entries[k] = entry;
+            save(f);
+        });
+    }
+    catch (e) {
+        unpersisted.set(k, entry);
+        log(`  [QUARANTINE] CRITICAL: could not persist quarantine to ${QUARANTINE_FILE} (${e instanceof Error ? e.message : String(e)}) — it holds only until this process stops`);
+    }
+}
+/**
+ * The quarantine entry blocking `symbol` (any source), or null. Re-reads the file on
+ * every call. An unreadable quarantine file fails CLOSED (a synthetic entry, logged) —
+ * never "not quarantined".
+ */
+export function quarantineEntryFor(symbol, log) {
+    const sym = symbol.toUpperCase();
+    const key = quarantineKey(sym);
+    for (const e of unpersisted.values())
+        if (quarantineKey(e.symbol) === key && applies(e))
+            return e;
+    try {
+        for (const e of Object.values(load().entries))
+            if (quarantineKey(e.symbol) === key && applies(e))
+                return e;
+        return null;
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        log(`  [QUARANTINE] CRITICAL: ${msg} — treating ${sym} as quarantined`);
+        return { strategy: "quarantine-file", symbol: sym, reason: msg, remediation: `Fix or remove ${QUARANTINE_FILE}`, time: new Date().toISOString(), network: activeNetwork };
+    }
+}
+/** true when `symbol` is quarantined by any strategy / CLI path (see quarantineEntryFor). */
+export function isQuarantined(symbol, log) {
+    return quarantineEntryFor(symbol, log) !== null;
+}
+/** Entries that apply on this process's network (every entry when it never declared one). */
+export function listQuarantine() {
+    return [...Object.values(load().entries), ...unpersisted.values()].filter(applies);
+}
+/** Remove entries (that apply on this process's network) whose quarantineKey matches symbol's (one source, or every source when null). Returns the removed entries. */
+export function clearQuarantine(symbol, strategy) {
+    return withQuarantineLock(() => {
+        const f = load();
+        const key = quarantineKey(symbol);
+        const removed = [];
+        const match = (e) => quarantineKey(e.symbol) === key && (strategy === null || e.strategy === strategy) && applies(e);
+        for (const [k, e] of Object.entries(f.entries)) {
+            if (match(e)) {
+                removed.push(e);
+                delete f.entries[k];
+            }
+        }
+        for (const [k, e] of unpersisted) {
+            if (match(e)) {
+                removed.push(e);
+                unpersisted.delete(k);
+            }
+        }
+        if (removed.length > 0)
+            save(f);
+        return removed;
+    });
+}

package/dist/bot/quote-rules.d.ts

@@ -0,0 +1,23 @@
+import type { ExchangeAdapter } from "../exchanges/interface.js";
+export interface QuoteRules {
+    /** Market tick; null = the venue publishes none on this data path (the adapter itself rounds / validates, e.g. HL). */
+    tickSize: string | null;
+    stepSize: string;
+    minSize: string | null;
+    minNotional: string | null;
+}
+/** The market's tick / lot / minimums (venue public market list + the adapter's lot step). Failed read → throws. */
+export declare function quoteRulesOf(adapter: ExchangeAdapter, symbol: string): Promise<QuoteRules>;
+/** Limit quote on the venue grid: price aligned passively (buy ↓, sell ↑), size floored to the lot, minimums checked. */
+export declare function prepareLimitQuote(rules: QuoteRules, venue: string, symbol: string, side: "buy" | "sell", price: string, size: string): {
+    price: string;
+    size: string;
+};
+/**
+ * A COMPUTED limit price aligned to the venue's own price grid when the venue publishes no tick
+ * (Hyperliquid: 5 significant figures / szDecimals rule, `alignComputedPrice`), passively for
+ * `side` (buy ↓, sell ↑). Venues with a tick are already aligned by the callers; returned as is.
+ */
+export declare function alignComputedLimitPrice(adapter: ExchangeAdapter, symbol: string, side: "buy" | "sell", price: string): Promise<string>;
+/** Market order size floored to the lot; the minimum order value is checked against `refPrice` (null = size minimum only). */
+export declare function prepareMarketSize(rules: QuoteRules, venue: string, symbol: string, size: string, refPrice: number | null): string;

package/dist/bot/quote-rules.js

@@ -0,0 +1,69 @@
+/**
+ * Venue order rules for bot quotes (engine executeActions): every limit price is aligned to the
+ * market tick in the passive direction (bid DOWN, ask UP — never more aggressive than the
+ * strategy asked), every size floored to the lot, and an order under the venue's published
+ * minimum size / order value is refused before sending (SIZE_TOO_SMALL).
+ *
+ * Live 2026-10-12 (Aster SOL, tick 0.01): simple-mm / avellaneda-mm / grid-mm / liquidation-mm /
+ * regime-mm / rfq-agent quoted "108.861840" and never placed an order (requireOnTick refusal);
+ * engine-mm on Pacifica was refused by the venue ("not a multiple of tick size 0.01").
+ */
+import { PerpError } from "../errors.js";
+import { adapterNetworkOf } from "../exchanges/adapter-network.js";
+import { alignProtectionPrice, floorSize, lotStepOf } from "../exchanges/precision.js";
+import { getVenue } from "../exchanges/venue.js";
+import { symbolMatch } from "../utils.js";
+/** The market's tick / lot / minimums (venue public market list + the adapter's lot step). Failed read → throws. */
+export async function quoteRulesOf(adapter, symbol) {
+    const network = adapterNetworkOf(adapter);
+    if (network === null) {
+        throw new PerpError("EXCHANGE_ERROR", `${adapter.name}: the adapter's network is unknown, so the ${symbol} tick / minimums cannot be read; nothing was sent`, { exchange: adapter.name });
+    }
+    const [markets, stepSize] = await Promise.all([getVenue(adapter.name).publicData.fetchMarkets(network), lotStepOf(adapter, symbol)]);
+    const vm = markets.find(m => symbolMatch(m.symbol, symbol));
+    return { tickSize: vm?.tickSize ?? null, stepSize, minSize: vm?.minSize ?? null, minNotional: vm?.minNotional ?? null };
+}
+/**
+ * A plain decimal for a strategy-computed number (strategies pass toFixed() strings; an exponent
+ * form is refused by the decimal helpers).
+ */
+function plain(v, what) {
+    if (/^\d+(\.\d+)?$/.test(v))
+        return v;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new PerpError("INVALID_PARAMS", `${what} ${v} is not a positive number; nothing was sent`);
+    return n.toFixed(12).replace(/\.?0+$/, "");
+}
+/** Limit quote on the venue grid: price aligned passively (buy ↓, sell ↑), size floored to the lot, minimums checked. */
+export function prepareLimitQuote(rules, venue, symbol, side, price, size) {
+    const px = rules.tickSize === null ? plain(price, "price") : alignProtectionPrice(plain(price, "price"), rules.tickSize, side === "buy" ? "sell" : "buy");
+    const sz = floorSize(plain(size, "size"), rules.stepSize);
+    requireMinimums(rules, venue, symbol, sz, px);
+    return { price: px, size: sz };
+}
+/**
+ * A COMPUTED limit price aligned to the venue's own price grid when the venue publishes no tick
+ * (Hyperliquid: 5 significant figures / szDecimals rule, `alignComputedPrice`), passively for
+ * `side` (buy ↓, sell ↑). Venues with a tick are already aligned by the callers; returned as is.
+ */
+export async function alignComputedLimitPrice(adapter, symbol, side, price) {
+    const a = adapter;
+    return typeof a.alignComputedPrice === "function" ? a.alignComputedPrice(symbol, side, price) : price;
+}
+/** Market order size floored to the lot; the minimum order value is checked against `refPrice` (null = size minimum only). */
+export function prepareMarketSize(rules, venue, symbol, size, refPrice) {
+    const sz = floorSize(plain(size, "size"), rules.stepSize);
+    requireMinimums(rules, venue, symbol, sz, refPrice !== null && refPrice > 0 ? String(refPrice) : null);
+    return sz;
+}
+function requireMinimums(rules, venue, symbol, size, price) {
+    if (rules.minSize !== null && Number(size) < Number(rules.minSize)) {
+        throw new PerpError("SIZE_TOO_SMALL", `${venue} ${symbol}: size ${size} is below the venue minimum ${rules.minSize}; nothing was sent`, { exchange: venue, minSize: rules.minSize });
+    }
+    if (price !== null && rules.minNotional !== null && Number(size) * Number(price) < Number(rules.minNotional)) {
+        throw new PerpError("SIZE_TOO_SMALL", `${venue} ${symbol}: ${size} @ ${price} = $${(Number(size) * Number(price)).toFixed(2)} is below the venue minimum order value $${rules.minNotional}; nothing was sent`, {
+            exchange: venue, minNotional: rules.minNotional, remediation: "Raise the strategy's order size",
+        });
+    }
+}

package/dist/bot/strategies/avellaneda-mm.d.ts

@@ -1,4 +1,31 @@
 import type { Strategy, StrategyContext, StrategyAction, EnrichedSnapshot } from "../strategy-types.js";
+/**
+ * Quotes farther than this from mid are refused (an error, never placed): a guard against a
+ * mis-scaled γ / κ / σ (live 2026-10-12: SOL ≈ $109 was quoted at $38.62 — the spread term
+ * (2/γ)·ln(1+γ/κ) = 1.29 was multiplied by the mid as if it were a fraction).
+ */
+export declare const AVELLANEDA_MAX_QUOTE_DISTANCE = 0.05;
+/**
+ * Avellaneda–Stoikov (2008) in absolute price units, with T − t in seconds:
+ *   r = s − q·γ·σ²·(T − t)
+ *   δ = γ·σ²·(T − t) + (2/γ)·ln(1 + γ/κ)      (total bid–ask spread)
+ *   bid = r − δ/2, ask = r + δ/2
+ * σ in $/√s, γ and κ in 1/$ — every term is then in $. Throws when a quote is more than
+ * AVELLANEDA_MAX_QUOTE_DISTANCE from mid or not positive.
+ */
+export declare function avellanedaQuotes(o: {
+    mid: number;
+    q: number;
+    gamma: number;
+    kappa: number;
+    sigma: number;
+    secondsLeft: number;
+}): {
+    reservation: number;
+    spread: number;
+    bid: number;
+    ask: number;
+};
 export declare class AvellanedaMmStrategy implements Strategy {
     readonly name = "avellaneda-mm";
     describe(): {
@@ -22,6 +49,9 @@ export declare class AvellanedaMmStrategy implements Strategy {
     init(ctx: StrategyContext, _snapshot: EnrichedSnapshot): Promise<void>;
     onTick(ctx: StrategyContext, snapshot: EnrichedSnapshot): Promise<StrategyAction[]>;
     onStop(_ctx: StrategyContext): Promise<StrategyAction[]>;
-    /** Estimate sigma from ATR or use override */
-    private estimateSigma;
 }
+/**
+ * σ in $/√s: the override, else ATR(14) of the snapshot candles (in $ per candle interval)
+ * ÷ √(interval in seconds, from the candle timestamps). Too few candles → throws (never a constant).
+ */
+export declare function estimateSigma(snapshot: Pick<EnrichedSnapshot, "klines">, sigmaOverride: number): number;

package/dist/bot/strategies/avellaneda-mm.js

@@ -1,16 +1,53 @@
 import { registerStrategy } from "../strategy-registry.js";
 import { calculateATR } from "../indicators.js";
+import { PerpError } from "../../errors.js";
+import { symbolMatch } from "../../utils.js";
+/**
+ * Quotes farther than this from mid are refused (an error, never placed): a guard against a
+ * mis-scaled γ / κ / σ (live 2026-10-12: SOL ≈ $109 was quoted at $38.62 — the spread term
+ * (2/γ)·ln(1+γ/κ) = 1.29 was multiplied by the mid as if it were a fraction).
+ */
+export const AVELLANEDA_MAX_QUOTE_DISTANCE = 0.05;
+/**
+ * Avellaneda–Stoikov (2008) in absolute price units, with T − t in seconds:
+ *   r = s − q·γ·σ²·(T − t)
+ *   δ = γ·σ²·(T − t) + (2/γ)·ln(1 + γ/κ)      (total bid–ask spread)
+ *   bid = r − δ/2, ask = r + δ/2
+ * σ in $/√s, γ and κ in 1/$ — every term is then in $. Throws when a quote is more than
+ * AVELLANEDA_MAX_QUOTE_DISTANCE from mid or not positive.
+ */
+export function avellanedaQuotes(o) {
+    const { mid, q, gamma, kappa, sigma, secondsLeft } = o;
+    for (const [k, v] of Object.entries({ mid, gamma, kappa, sigma, secondsLeft })) {
+        if (!Number.isFinite(v) || v <= 0)
+            throw new PerpError("INVALID_PARAMS", `avellaneda-mm: ${k} must be a positive number (got ${v})`);
+    }
+    if (!Number.isFinite(q))
+        throw new PerpError("INVALID_PARAMS", `avellaneda-mm: inventory is not a number (${q})`);
+    const risk = gamma * sigma ** 2 * secondsLeft;
+    const reservation = mid - q * risk;
+    const spread = risk + (2 / gamma) * Math.log(1 + gamma / kappa);
+    const bid = reservation - spread / 2;
+    const ask = reservation + spread / 2;
+    const far = Math.max(Math.abs(mid - bid), Math.abs(ask - mid)) / mid;
+    if (!(bid > 0) || far > AVELLANEDA_MAX_QUOTE_DISTANCE) {
+        throw new PerpError("INVALID_PARAMS", `avellaneda-mm: quotes ${bid.toFixed(6)} / ${ask.toFixed(6)} are ${(far * 100).toFixed(1)}% from mid ${mid} (limit ${AVELLANEDA_MAX_QUOTE_DISTANCE * 100}%) — γ=${gamma}, κ=${kappa} (per $), σ=${sigma.toPrecision(4)} $/√s, T−t=${secondsLeft.toFixed(0)}s, q=${q}; nothing was placed`, {
+            remediation: "γ and κ are per price unit: raise kappa / lower gamma for a tighter spread, or shorten --param timeHorizon",
+        });
+    }
+    return { reservation, spread, bid, ask };
+}
 export class AvellanedaMmStrategy {
     name = "avellaneda-mm";
     describe() {
         return {
-            description: "Avellaneda-Stoikov optimal market making with inventory-adjusted reservation price",
+            description: "Avellaneda-Stoikov optimal market making with inventory-adjusted reservation price (absolute price units; quotes > 5% from mid are refused)",
             params: [
-                { name: "gamma", type: "number", required: false, default: 0.1, description: "Risk aversion parameter" },
-                { name: "kappa", type: "number", required: false, default: 1.5, description: "Order arrival rate" },
-                { name: "sigma", type: "number", required: false, default: 0, description: "Volatility override (0 = auto)" },
+                { name: "gamma", type: "number", required: false, default: 0.1, description: "Risk aversion γ, per price unit (1/$)" },
+                { name: "kappa", type: "number", required: false, default: 1.5, description: "Order-book liquidity κ, per price unit (1/$)" },
+                { name: "sigma", type: "number", required: false, default: 0, description: "Volatility in $ per √second (0 = estimate from the candles' ATR)" },
                 { name: "maxPosition", type: "number", required: true, description: "Maximum position size" },
-                { name: "timeHorizon", type: "number", required: false, default: 86400, description: "Session length in seconds" },
+                { name: "timeHorizon", type: "number", required: false, default: 86400, description: "Session length T in seconds" },
                 { name: "size", type: "number", required: true, description: "Order size per level" },
             ],
         };
@@ -21,91 +58,56 @@ export class AvellanedaMmStrategy {
     _config = {};
     async init(ctx, _snapshot) {
         this._config = ctx.config;
-        ctx.state.set("inventory", 0);
         ctx.state.set("sessionStart", Date.now());
         const p = this.params;
         ctx.log(`  [AVELLANEDA-MM] gamma=${p.gamma}, kappa=${p.kappa}, sigma=${p.sigma || "auto"}, maxPos=${p.maxPosition}, T=${p.timeHorizon}s`);
     }
     async onTick(ctx, snapshot) {
         const params = this.params;
-        const actions = [];
-        actions.push({ type: "cancel_all" });
+        const actions = [{ type: "cancel_all" }];
         const gamma = params.gamma || 0.1;
         const kappa = params.kappa || 1.5;
         const mid = snapshot.price;
-        // Estimate sigma (volatility) from ATR or use override
-        const sigma = this.estimateSigma(snapshot, params.sigma);
-        // Time remaining: fraction of session left
+        const sigma = estimateSigma(snapshot, params.sigma);
         const sessionStart = ctx.state.get("sessionStart") ?? Date.now();
         const elapsed = (Date.now() - sessionStart) / 1000;
         const timeHorizon = params.timeHorizon || 86400;
-        const timeRemaining = Math.max(timeHorizon - elapsed, 1) / timeHorizon; // (T-t)/T normalized
-        // Current inventory
-        const q = ctx.state.get("inventory") ?? 0;
-        // Avellaneda-Stoikov reservation price:
-        // r = mid - q * gamma * sigma^2 * (T-t)
-        const reservationPrice = mid - q * gamma * (sigma ** 2) * timeRemaining;
-        // Optimal spread:
-        // delta = gamma * sigma^2 * (T-t) + (2/gamma) * ln(1 + gamma/kappa)
-        const optimalSpread = gamma * (sigma ** 2) * timeRemaining + (2 / gamma) * Math.log(1 + gamma / kappa);
-        const spreadInPrice = optimalSpread * mid; // convert to price terms
-        const bidPrice = reservationPrice - spreadInPrice / 2;
-        const askPrice = reservationPrice + spreadInPrice / 2;
-        // Clamp to max position: skip orders that would exceed
+        const secondsLeft = Math.max(timeHorizon - elapsed, 1);
+        // Inventory q: the venue position (signed base), never an estimate.
+        const pos = (await ctx.adapter.getPositions()).find(p => symbolMatch(p.symbol, ctx.symbol));
+        const q = pos === undefined ? 0 : (pos.side === "short" ? -1 : 1) * Math.abs(Number(pos.size));
+        const { reservation, spread, bid, ask } = avellanedaQuotes({ mid, q, gamma, kappa, sigma, secondsLeft });
         const size = params.size;
-        if (q < params.maxPosition && bidPrice > 0) {
-            actions.push({
-                type: "place_order",
-                side: "buy",
-                price: bidPrice.toFixed(6),
-                size: String(size),
-                orderType: "limit",
-            });
-        }
-        if (q > -params.maxPosition && askPrice > 0) {
-            actions.push({
-                type: "place_order",
-                side: "sell",
-                price: askPrice.toFixed(6),
-                size: String(size),
-                orderType: "limit",
-            });
-        }
-        // Update inventory estimate
-        const prevMid = ctx.state.get("prevMid") ?? mid;
-        if (mid > prevMid && q < params.maxPosition) {
-            ctx.state.set("inventory", q + size * 0.5);
-        }
-        else if (mid < prevMid && q > -params.maxPosition) {
-            ctx.state.set("inventory", q - size * 0.5);
-        }
-        ctx.state.set("prevMid", mid);
+        if (q < params.maxPosition)
+            actions.push({ type: "place_order", side: "buy", price: bid.toFixed(8), size: String(size), orderType: "limit" });
+        if (q > -params.maxPosition)
+            actions.push({ type: "place_order", side: "sell", price: ask.toFixed(8), size: String(size), orderType: "limit" });
         if (ctx.tick % 10 === 0) {
-            ctx.log(`  [AVELLANEDA-MM] r=$${reservationPrice.toFixed(2)}, spread=$${spreadInPrice.toFixed(4)}, q=${q.toFixed(4)}, sigma=${sigma.toFixed(6)}, T-t=${timeRemaining.toFixed(3)}`);
+            ctx.log(`  [AVELLANEDA-MM] mid=$${mid}, r=$${reservation.toFixed(4)}, spread=$${spread.toFixed(4)}, q=${q}, sigma=${sigma.toPrecision(4)} $/√s, T-t=${secondsLeft.toFixed(0)}s`);
         }
         return actions;
     }
     async onStop(_ctx) {
         return [{ type: "cancel_all" }];
     }
-    /** Estimate sigma from ATR or use override */
-    estimateSigma(snapshot, sigmaOverride) {
-        if (sigmaOverride > 0)
-            return sigmaOverride;
-        if (snapshot.klines.length >= 15) {
-            const candles = snapshot.klines.map(k => ({
-                high: parseFloat(k.high),
-                low: parseFloat(k.low),
-                close: parseFloat(k.close),
-            }));
-            const atr = calculateATR(candles, 14);
-            if (atr.length > 0) {
-                // Normalize ATR to fractional volatility
-                return atr[atr.length - 1] / snapshot.price;
-            }
-        }
-        // Fallback: use 24h volatility from snapshot
-        return snapshot.volatility24h / 100 || 0.02;
+}
+/**
+ * σ in $/√s: the override, else ATR(14) of the snapshot candles (in $ per candle interval)
+ * ÷ √(interval in seconds, from the candle timestamps). Too few candles → throws (never a constant).
+ */
+export function estimateSigma(snapshot, sigmaOverride) {
+    if (sigmaOverride > 0)
+        return sigmaOverride;
+    const k = [...snapshot.klines].sort((a, b) => a.time - b.time);
+    if (k.length < 15) {
+        throw new PerpError("PRICE_STALE", `avellaneda-mm: ${k.length} candles — at least 15 are needed to estimate σ (or pass --param sigma=<$ per √s>)`);
+    }
+    const atr = calculateATR(k.map(c => ({ high: parseFloat(c.high), low: parseFloat(c.low), close: parseFloat(c.close) })), 14);
+    const intervalSec = (k[k.length - 1].time - k[0].time) / (k.length - 1) / 1000;
+    const last = atr[atr.length - 1];
+    if (!(intervalSec > 0) || !(last > 0)) {
+        throw new PerpError("PRICE_STALE", `avellaneda-mm: σ cannot be estimated (ATR ${last}, candle interval ${intervalSec}s)`);
     }
+    return last / Math.sqrt(intervalSec);
 }
 registerStrategy("avellaneda-mm", (_config) => new AvellanedaMmStrategy());

package/dist/bot/strategies/basis-arb.js

@@ -1,4 +1,5 @@
 import { registerStrategy } from "../strategy-registry.js";
+import { assertFundingArbLegs } from "./funding-arb-utils.js";
 export class BasisArbStrategy {
     name = "basis-arb";
     _config = {};
@@ -16,6 +17,7 @@ export class BasisArbStrategy {
     get size() { return Number(this._config.size ?? 0.1); }
     get holdingPeriodHours() { return Number(this._config.holdingPeriodHours ?? 24); }
     async init(ctx, _snapshot) {
+        assertFundingArbLegs(ctx);
         this._config = ctx.config;
         ctx.state.set("position", null);
         ctx.log(`  [BASIS] Ready | threshold=${this.annualizedBasisThreshold}% holdingPeriod=${this.holdingPeriodHours}h size=${this.size}`);

package/dist/bot/strategies/dca-strategy.d.ts

@@ -21,5 +21,7 @@ export declare class DCAStrategy implements Strategy {
     private _config;
     init(ctx: StrategyContext, _snapshot: EnrichedSnapshot): Promise<void>;
     onTick(ctx: StrategyContext, snapshot: EnrichedSnapshot): Promise<StrategyAction[]>;
+    /** Done once the --orders total has been placed (0 = unlimited, never done). */
+    isDone(ctx: StrategyContext): boolean;
     onStop(_ctx: StrategyContext): Promise<StrategyAction[]>;
 }

package/dist/bot/strategies/dca-strategy.js

@@ -56,6 +56,11 @@ export class DCAStrategy {
                 orderType: "market",
             }];
     }
+    /** Done once the --orders total has been placed (0 = unlimited, never done). */
+    isDone(ctx) {
+        const total = this.params.total_orders;
+        return total > 0 && ctx.state.get("dcaOrdersPlaced") >= total;
+    }
     async onStop(_ctx) {
         return [{ type: "cancel_all" }];
     }

package/dist/bot/strategies/funding-arb-strategy.d.ts

@@ -26,12 +26,52 @@ export declare class FundingArbStrategy implements Strategy {
     private get params();
     private _config;
     private _failCooldown;
+    /** Consecutive failed closes per symbol, spot-perp and perp-perp (quarantined at MAX_CLOSE_FAILURES). */
+    private _closeFailures;
+    /** Venues whose positions could not be read during recovery: no entries there until re-read. */
+    private _unrecovered;
+    private executor;
+    /** Symbols this bot entered or tracked this run — the only symbols its stop cancels orders on. */
+    private _traded;
+    private quarantined;
+    /** Unknown / unhedged outcome: stop touching this symbol until a human clears it. */
+    private quarantine;
     init(ctx: StrategyContext, _snapshot: EnrichedSnapshot): Promise<void>;
+    /**
+     * Rebuild tracked positions from the venues (perp-perp pairs + same-venue spot-perp
+     * hedges). A venue whose positions or spot balances cannot be read is returned in
+     * `unreadable` — never treated as holding nothing.
+     */
+    private recoverPositions;
+    /**
+     * true when `symbol` has a live perp position on any of `venues` that the bot does not track
+     * (a manual / foreign position): no entry is stacked on it. A failed read counts as held
+     * (unknown is never "flat").
+     */
+    private heldUntracked;
     onTick(ctx: StrategyContext, _snapshot: EnrichedSnapshot): Promise<StrategyAction[]>;
     onStop(ctx: StrategyContext): Promise<StrategyAction[]>;
-    /** Close a spot-perp position: sell spot, transfer USDC back, close perp short.
-     * Returns true only if ALL steps succeed. If spot sell succeeds but perp close fails,
-     * attempts to re-buy spot as rollback and returns false. */
+    /**
+     * Close a perp-perp position: long then short, both reduce-only and verified by the
+     * position delta. Returns true when both legs are closed (or already gone).
+     *  - an unknown leg outcome → quarantine (never retried / rolled back blindly);
+     *  - long close definitely failed → hedge intact, cooldown; MAX_CLOSE_FAILURES in a row →
+     *    quarantine (no endless retry);
+     *  - short close definitely failed after THIS call closed the long → quarantine at once
+     *    (naked short). The long is never re-opened (a non-reduce-only order that could loop
+     *    close → fail → re-open every tick), same as closePerpPairVerified;
+     *  - short close failed with the long already gone → one more reduce-only close of the
+     *    orphaned short; if that fails → quarantine.
+     */
+    private closePerpPerp;
+    /**
+     * Close a spot-perp position via SpotPerpExecutor.closePosition (perp short FIRST,
+     * reduce-only and verified; spot sold only after; a perp already gone is detected by
+     * the reduce-only rejection, never by selling spot again). Returns true only when
+     * fully closed. Unknown / unhedged outcomes quarantine the symbol; a plain failure
+     * cools down, and MAX_CLOSE_FAILURES consecutive failures quarantine it — each attempt
+     * can trade (perp close → spot sell fail → re-hedge), so it never loops.
+     */
     private closeSpotPerp;
     /** Open a spot-perp position: transfer USDC to spot, buy spot, short perp */
     private openSpotPerp;