@reefclaw/openclaw-plugin 0.1.0

package/ingest/touched-symbols-store.js

@@ -0,0 +1,96 @@
+// Persistent set of "every symbol this user has ever traded".
+//
+// WHY THIS EXISTS
+// ---------------
+// The REST gap-filler must call /fapi/v1/userTrades per symbol — there is no
+// portfolio-wide trades endpoint. Within a session it discovers symbols
+// from WS orderUpdate events + open-position snapshots. Across restarts that
+// in-memory set is lost: a symbol that opened AND closed entirely during a
+// plugin outage will (a) not appear in the next start's open-position seed
+// (already closed) and (b) never have emitted an orderUpdate to the new
+// process. Without this on-disk anchor, gap-fill skips it forever and the
+// fill rows are missing from the audit trail.
+//
+// WHAT THIS DOES
+// --------------
+// JSON file under ~/.reefclaw, atomic write (tmp + rename), per-user file
+// name. Append-only in practice — symbols are added on every WS orderUpdate
+// and on each open-position seed. Load returns an empty set on missing /
+// corrupt file so a bad save can't permanently break ingest.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { logger, formatError } from '../logger.js';
+const TAG = 'touched-symbols';
+const SCHEMA_VERSION = 1;
+/** Default per-user path. The userId scoping prevents two parallel plugin
+ *  instances on the same machine (rare, but possible during ops) from
+ *  clobbering each other's history. */
+export function defaultTouchedSymbolsPath(userId) {
+    // Sanitize — userId comes from the trusted plugin-config but should still
+    // be safe as a filename component.
+    const safe = userId.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64) || 'unknown';
+    return join(homedir(), '.reefclaw', `touched-symbols-${safe}.json`);
+}
+export class TouchedSymbolsStore {
+    path;
+    userId;
+    now;
+    constructor(opts) {
+        this.path = opts.path ?? defaultTouchedSymbolsPath(opts.userId);
+        this.userId = opts.userId;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** Read the persisted set. Returns an empty Set on any error so a corrupt
+     *  file can't block ingest startup. The corrupt file isn't deleted —
+     *  the next save() naturally overwrites it via tmp+rename. */
+    load() {
+        try {
+            if (!existsSync(this.path))
+                return new Set();
+            const raw = readFileSync(this.path, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (!parsed ||
+                typeof parsed !== 'object' ||
+                parsed.v !== SCHEMA_VERSION ||
+                !Array.isArray(parsed.symbols)) {
+                logger.warn(TAG, `unexpected on-disk shape at ${this.path} — ignoring`);
+                return new Set();
+            }
+            const out = new Set();
+            for (const s of parsed.symbols) {
+                if (typeof s === 'string' && s.length > 0)
+                    out.add(s);
+            }
+            return out;
+        }
+        catch (err) {
+            logger.warn(TAG, `failed to load ${this.path}: ${formatError(err)} — starting fresh`);
+            return new Set();
+        }
+    }
+    /** Atomically persist the set to disk. Best-effort — failures are logged
+     *  but never thrown; persistence is a recovery helper, not on the hot path. */
+    save(symbols) {
+        try {
+            const dir = dirname(this.path);
+            if (!existsSync(dir))
+                mkdirSync(dir, { recursive: true });
+            const body = {
+                v: SCHEMA_VERSION,
+                userId: this.userId,
+                symbols: [...symbols].sort(),
+                updatedAt: this.now(),
+            };
+            const tmp = `${this.path}.tmp`;
+            writeFileSync(tmp, JSON.stringify(body, null, 2) + '\n', {
+                encoding: 'utf-8',
+                mode: 0o600,
+            });
+            renameSync(tmp, this.path);
+        }
+        catch (err) {
+            logger.warn(TAG, `failed to save ${this.path}: ${formatError(err)}`);
+        }
+    }
+}

package/ingest/trade-store-client.d.ts

@@ -0,0 +1,40 @@
+import type { FillEvent } from '@reefclaw/shared';
+export interface TradeStoreClientOptions {
+    baseUrl: string;
+    ingestToken: string;
+    /** Injectable for unit tests + observability shims. */
+    fetchImpl?: typeof fetch;
+    /** Per-attempt request timeout. */
+    requestTimeoutMs?: number;
+    /** Max total attempts (initial + retries).  Default 4. */
+    maxAttempts?: number;
+    /** Initial backoff between retries.  Doubles each attempt; ±20% jitter. */
+    baseBackoffMs?: number;
+    /** Cap on the exponential backoff. */
+    backoffCapMs?: number;
+}
+export interface TradeStoreClientHealth {
+    inFlight: number;
+    totalPosted: number;
+    totalSucceeded: number;
+    totalDroppedTerminal: number;
+    totalDroppedRetriesExhausted: number;
+}
+export declare class TradeStoreClient {
+    private readonly opts;
+    private inFlight;
+    private totalPosted;
+    private totalSucceeded;
+    private totalDroppedTerminal;
+    private totalDroppedRetriesExhausted;
+    constructor(options: TradeStoreClientOptions);
+    /** Fire-and-forget post.  Returns immediately; response handled in the
+     *  background.  Use `drain()` at shutdown to await all in-flight posts. */
+    post(userId: string, fill: FillEvent): void;
+    /** Await all in-flight posts.  Resolves when the queue is empty.
+     *  Used at shutdown so we don't lose fills mid-flight. */
+    drain(): Promise<void>;
+    getHealth(): TradeStoreClientHealth;
+    private run;
+    private sleepBackoff;
+}

package/ingest/trade-store-client.js

@@ -0,0 +1,125 @@
+// HTTP client for the webapp's /api/internal/trades ingest endpoint.
+//
+// Phase 1 of TRADE_AUDIT_TRAIL_PLAN.  Posts a FillEvent over a shared-secret
+// bearer channel and treats the response with three buckets:
+//
+//   - 2xx                 : success (including the implicit "no-op on conflict"
+//                            that the upsert returns as 200 + ok:true).
+//   - 4xx (e.g. 400, 409) : terminal failure.  Logged + dropped.  Retrying
+//                            won't help: either the payload is malformed or
+//                            we're racing on a duplicate that's already
+//                            persisted.  Both are correct outcomes for an
+//                            idempotent ingest.
+//   - 5xx, network errors : transient.  Retry with exponential backoff up to
+//                            `maxAttempts` (default 4 = ~7 s end-to-end).
+//                            After the final retry the row is dropped.  The
+//                            REST reconciler (Phase 2) will rescue it on its
+//                            next pass.
+//
+// We intentionally do NOT block the caller waiting for the response.  The WS
+// hot path runs `client.post(...)` and continues; the request happens in the
+// background.  In-flight requests are tracked so `drain()` can be awaited at
+// shutdown to avoid losing the last fills before stop.
+import { logger, formatError } from '../logger.js';
+const TAG = 'trade-store-client';
+export class TradeStoreClient {
+    opts;
+    inFlight = new Set();
+    totalPosted = 0;
+    totalSucceeded = 0;
+    totalDroppedTerminal = 0;
+    totalDroppedRetriesExhausted = 0;
+    constructor(options) {
+        this.opts = {
+            baseUrl: options.baseUrl.replace(/\/+$/, ''),
+            ingestToken: options.ingestToken,
+            fetchImpl: options.fetchImpl ?? fetch,
+            requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
+            maxAttempts: options.maxAttempts ?? 4,
+            baseBackoffMs: options.baseBackoffMs ?? 250,
+            backoffCapMs: options.backoffCapMs ?? 5_000,
+        };
+    }
+    /** Fire-and-forget post.  Returns immediately; response handled in the
+     *  background.  Use `drain()` at shutdown to await all in-flight posts. */
+    post(userId, fill) {
+        this.totalPosted++;
+        const promise = this.run(userId, fill).finally(() => {
+            this.inFlight.delete(promise);
+        });
+        this.inFlight.add(promise);
+    }
+    /** Await all in-flight posts.  Resolves when the queue is empty.
+     *  Used at shutdown so we don't lose fills mid-flight. */
+    async drain() {
+        if (this.inFlight.size === 0)
+            return;
+        logger.info(TAG, `Draining ${this.inFlight.size} in-flight trade post(s)...`);
+        await Promise.allSettled(Array.from(this.inFlight));
+    }
+    getHealth() {
+        return {
+            inFlight: this.inFlight.size,
+            totalPosted: this.totalPosted,
+            totalSucceeded: this.totalSucceeded,
+            totalDroppedTerminal: this.totalDroppedTerminal,
+            totalDroppedRetriesExhausted: this.totalDroppedRetriesExhausted,
+        };
+    }
+    // ---- Internals ----
+    async run(userId, fill) {
+        const url = `${this.opts.baseUrl}/api/internal/trades`;
+        const body = JSON.stringify(fill);
+        for (let attempt = 1; attempt <= this.opts.maxAttempts; attempt++) {
+            try {
+                const ac = new AbortController();
+                const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+                let res;
+                try {
+                    res = await this.opts.fetchImpl(url, {
+                        method: 'POST',
+                        headers: {
+                            'content-type': 'application/json',
+                            authorization: `Bearer ${this.opts.ingestToken}`,
+                            'x-user-id': userId,
+                        },
+                        body,
+                        signal: ac.signal,
+                    });
+                }
+                finally {
+                    clearTimeout(tid);
+                }
+                if (res.status >= 200 && res.status < 300) {
+                    this.totalSucceeded++;
+                    return;
+                }
+                if (res.status >= 400 && res.status < 500) {
+                    // Terminal — re-tries won't change the outcome.  409 is a duplicate
+                    // (idempotency win); 400/401/404 are bugs we want logged loudly.
+                    this.totalDroppedTerminal++;
+                    logger.warn(TAG, `POST ${url} → ${res.status} (terminal, dropped). userId=${userId} tradeId=${fill.exchangeTradeId}`);
+                    return;
+                }
+                // 5xx — fall through to retry.
+                logger.warn(TAG, `POST ${url} → ${res.status} (attempt ${attempt}/${this.opts.maxAttempts}).`);
+            }
+            catch (err) {
+                // Network error / abort.  Retry.
+                logger.warn(TAG, `POST ${url} threw (attempt ${attempt}/${this.opts.maxAttempts}): ${formatError(err)}`);
+            }
+            if (attempt < this.opts.maxAttempts) {
+                await this.sleepBackoff(attempt);
+            }
+        }
+        // All attempts exhausted.
+        this.totalDroppedRetriesExhausted++;
+        logger.error(TAG, `POST ${url} dropped after ${this.opts.maxAttempts} attempts. userId=${userId} tradeId=${fill.exchangeTradeId}. REST reconciler (Phase 2) will rescue.`);
+    }
+    async sleepBackoff(attempt) {
+        const exp = Math.min(this.opts.baseBackoffMs * 2 ** (attempt - 1), this.opts.backoffCapMs);
+        const jitter = exp * 0.2 * (Math.random() * 2 - 1); // ±20%
+        const delay = Math.max(0, Math.round(exp + jitter));
+        await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+}

package/ingest/ws-ingest.d.ts

@@ -0,0 +1,43 @@
+import type { UserDataStream } from '../live/user-data-stream.js';
+import type { TradeStoreClient } from './trade-store-client.js';
+import { type AutoCaptureContext } from './position-auto-capture.js';
+export interface WsIngestOptions {
+    /** The already-running user-data WS the controller hands us. */
+    stream: UserDataStream;
+    /** HTTP client for the webapp ingest endpoint. */
+    client: TradeStoreClient;
+    /** Trader identity — the userId that owns the trading account. */
+    userId: string;
+    /** Exchange identifier. Today always 'binance_futures'. */
+    exchange?: string;
+    /** Position-decision auto-capture context. When provided, every TRADE event
+     *  is also routed through `onWsFillObserved` to capture limit-order entries
+     *  and scale-ins that the synchronous create_order path can't see (the order
+     *  hadn't filled yet when create_order returned). Optional — when absent,
+     *  ws-ingest behaves exactly as before. */
+    autoCapture?: AutoCaptureContext;
+}
+export declare class WsIngest {
+    private readonly stream;
+    private readonly client;
+    private readonly userId;
+    private readonly exchange;
+    private readonly autoCapture?;
+    private readonly handler;
+    private started;
+    /** Total ORDER_TRADE_UPDATE events the listener saw (any executionType). */
+    private totalSeen;
+    /** Subset of events that were actual fills (executionType='TRADE' + tradeId). */
+    private totalFills;
+    /** Events skipped because executionType !== 'TRADE' or tradeId missing. */
+    private totalSkipped;
+    constructor(opts: WsIngestOptions);
+    start(): void;
+    stop(): void;
+    getHealth(): {
+        totalSeen: number;
+        totalFills: number;
+        totalSkipped: number;
+    };
+    private onOrderUpdate;
+}

package/ingest/ws-ingest.js

@@ -0,0 +1,126 @@
+// WS-side ingest — converts Binance ORDER_TRADE_UPDATE events into FillEvents
+// and pushes them to the webapp's audit-trail store.
+//
+// Phase 1 of TRADE_AUDIT_TRAIL_PLAN.  Subscribes to the existing
+// `UserDataStream.orderUpdate` event (already running in shadow on prod) and
+// filters for true fills (`executionType === 'TRADE'` with a non-null
+// tradeId).  Order-state transitions like NEW / CANCELED / EXPIRED are NOT
+// fills and are intentionally ignored — they don't move money or position.
+//
+// Idempotency lives in the upstream HTTP store: same Binance tradeId twice
+// (e.g. listenKey rotation re-deliver) collapses to one DB row.  This module
+// is therefore safe to subscribe in shadow alongside the legacy poller-write
+// path; the unique index makes double-write impossible at the DB level.
+//
+// `start()` is idempotent and `stop()` is reversible.  The class holds no
+// state beyond the bound listener so dispose-and-recreate is cheap during
+// stream reconnects.
+import { logger, formatError } from '../logger.js';
+import { onWsFillObserved } from './position-auto-capture.js';
+const TAG = 'ws-ingest';
+export class WsIngest {
+    stream;
+    client;
+    userId;
+    exchange;
+    autoCapture;
+    handler;
+    started = false;
+    /** Total ORDER_TRADE_UPDATE events the listener saw (any executionType). */
+    totalSeen = 0;
+    /** Subset of events that were actual fills (executionType='TRADE' + tradeId). */
+    totalFills = 0;
+    /** Events skipped because executionType !== 'TRADE' or tradeId missing. */
+    totalSkipped = 0;
+    constructor(opts) {
+        this.stream = opts.stream;
+        this.client = opts.client;
+        this.userId = opts.userId;
+        this.exchange = opts.exchange ?? 'binance_futures';
+        this.autoCapture = opts.autoCapture;
+        this.handler = (ev) => this.onOrderUpdate(ev);
+    }
+    start() {
+        if (this.started)
+            return;
+        this.stream.on('orderUpdate', this.handler);
+        this.started = true;
+        logger.info(TAG, `Started — userId=${this.userId} exchange=${this.exchange}`);
+    }
+    stop() {
+        if (!this.started)
+            return;
+        this.stream.off('orderUpdate', this.handler);
+        this.started = false;
+        logger.info(TAG, 'Stopped');
+    }
+    getHealth() {
+        return {
+            totalSeen: this.totalSeen,
+            totalFills: this.totalFills,
+            totalSkipped: this.totalSkipped,
+        };
+    }
+    onOrderUpdate(ev) {
+        this.totalSeen++;
+        // Only TRUE fills (executionType='TRADE' with a real tradeId) become
+        // audit-trail rows.  NEW / CANCELED / EXPIRED / CALCULATED carry no
+        // monetary movement — they're order-state transitions handled by the
+        // existing live-state-store.
+        if (ev.executionType !== 'TRADE' || ev.tradeId == null) {
+            this.totalSkipped++;
+            return;
+        }
+        // A TRADE event MUST have a positive lastFilledQty + lastFillPrice.
+        // If those are absent the parser is broken — log loudly and skip.
+        if (!(ev.lastFilledQty > 0) || ev.lastFillPrice == null || !(ev.lastFillPrice > 0)) {
+            this.totalSkipped++;
+            logger.warn(TAG, `Skipped TRADE event with missing qty/price: orderId=${ev.orderId} tradeId=${ev.tradeId} qty=${ev.lastFilledQty} px=${ev.lastFillPrice}`);
+            return;
+        }
+        const fill = {
+            exchange: this.exchange,
+            exchangeTradeId: ev.tradeId,
+            exchangeOrderId: ev.orderId,
+            clientOrderId: ev.clientOrderId,
+            source: 'ws',
+            userId: this.userId,
+            symbol: ev.symbol,
+            side: ev.side === 'sell' ? 'SELL' : 'BUY',
+            quantity: ev.lastFilledQty,
+            price: ev.lastFillPrice,
+            maker: ev.maker,
+            reduceOnly: ev.reduceOnly,
+            commission: ev.commission,
+            commissionAsset: ev.commissionAsset,
+            realizedPnl: ev.realizedPnl,
+            exchangeTime: ev.transactionTime,
+            // The full ParsedOrderUpdate is the rawPayload — we keep it as our
+            // forensic record.  The webapp persists this to JSONB so any future
+            // re-derivation has the same fields the parser saw.
+            rawPayload: ev,
+        };
+        this.totalFills++;
+        this.client.post(this.userId, fill);
+        // Position-decision auto-capture for the WS-driven path. Resolves the PR1
+        // deferral that limit-order fills + scale-ins were silently dropped. Runs
+        // as fire-and-forget — never block the audit-trail path on a decision-row
+        // POST blip.
+        if (this.autoCapture) {
+            onWsFillObserved(this.autoCapture, {
+                symbol: ev.symbol,
+                side: ev.side,
+                exchangeOrderId: ev.orderId,
+                exchangeTradeId: ev.tradeId,
+                fillPrice: ev.lastFillPrice,
+                fillSize: ev.lastFilledQty,
+                reduceOnly: ev.reduceOnly,
+                realizedPnl: ev.realizedPnl,
+                clientOrderId: ev.clientOrderId,
+                exchangeTimeMs: ev.transactionTime,
+            }).catch((err) => {
+                logger.warn(TAG, `onWsFillObserved threw for orderId=${ev.orderId}: ${formatError(err)}`);
+            });
+        }
+    }
+}

package/learning/setup-family.d.ts

@@ -0,0 +1,21 @@
+export type SetupFamily = 'trend' | 'mean_reversion' | 'range' | 'breakout' | 'funding' | 'unknown' | 'other';
+export declare const ALL_SETUP_FAMILIES: readonly SetupFamily[];
+/**
+ * Normalize a free-text `setup_type` into a stable `setup_family`.
+ * Case- and whitespace-insensitive. `null` / `undefined` / `''` → 'unknown'.
+ * Unrecognized non-empty strings → 'other' (never silently merged).
+ */
+export declare function normalizeSetupFamily(setupType: string | null | undefined): SetupFamily;
+/**
+ * Resolve a learning's `trigger_condition` setup constraint into the family/families
+ * it targets, for family-aware matching. Used IDENTICALLY by both matchers (the
+ * webapp `get_relevant_learnings` route and the plugin `scan_pairs` veto) so they
+ * can never diverge.
+ *
+ * - Prefers an explicit `setup_family` (the family-keyed miner's output), taken
+ *   verbatim (scalar or array).
+ * - Else normalizes `setup_type` (legacy / operator-authored) to family(ies).
+ * - Returns `null` when the trigger pins NO setup constraint — the caller decides
+ *   whether that means wildcard (decision-time matcher) or no-veto (scan matcher).
+ */
+export declare function resolveTriggerFamilies(triggerSetupFamily: unknown, triggerSetupType: unknown): SetupFamily[] | null;

package/learning/setup-family.js

@@ -0,0 +1,103 @@
+// Canonical `setup_type` → `setup_family` normalizer + trigger resolution.
+//
+// WHY THIS EXISTS (2026-06-22 prod finding). Learnings + mined patterns key on an
+// EXACT match against `setup_type`, but the agent invents free-text setup_type
+// strings continuously: `mean_reversion` → `mean_reversion_high_volume` →
+// `vwap_reversion`; `trend_continuation` → `daily_trend_pullback_v4` →
+// `livermore_tape_follow_v4` (drift accelerated by model swaps). An exact-match
+// learning therefore ORPHANS the moment the vocabulary moves — measured at ~0%
+// learning-citation on prod, with the dominant live setup (`daily_trend_pullback_v4`,
+// 118 entries) carrying no matching learning at all. Keying on a STABLE family
+// instead of the raw string is the prerequisite that lets a learning keep matching
+// as the agent renames its setups.
+// See docs/CLAUDE/learning-loop.md (2026-06-22 finding) +
+// memory/project_learning_loop_application_path_broken_jun22.md.
+//
+// DESIGN. An ORDERED keyword ruleset, first match wins. Robust to NEW invented
+// names as long as they carry a recognizable token (they almost always do).
+// Ordering is load-bearing:
+//   - `funding` is tested BEFORE reversion, else `funding_reversion` would be
+//     mislabelled mean_reversion.
+//   - `range` is tested BEFORE the generic `fade` token, because `range_fade` is a
+//     DISTINCT family that the data shows is profitable, whereas generic
+//     `mean_reversion` underperforms — merging them would let an "avoid
+//     mean_reversion" learning wrongly veto the profitable range fade.
+// Unrecognized strings map to 'other' (never silently merged into a real family;
+// 'other' is a signal to extend the ruleset, not a dumping ground).
+//
+// ★ CANONICAL SOURCE — KEEP IN SYNC. The plugin keeps a byte-identical copy at
+// `plugin/src/learning/setup-family.ts` (the deploy bundle strips workspace deps,
+// so shared runtime code is duplicated, not imported — same reason redact.ts is
+// duplicated ×3). Both copies are guarded by an identical behavioural test
+// (`setup-family.test.ts` in each package). Divergence between the webapp matcher
+// and the plugin scan_pairs matcher is exactly the bug class that caused the
+// 2026-05-15 wildcard-match incident (see memory/feedback_canonical_jsonb_key_naming).
+export const ALL_SETUP_FAMILIES = [
+    'trend',
+    'mean_reversion',
+    'range',
+    'breakout',
+    'funding',
+    'unknown',
+    'other',
+];
+const has = (...tokens) => (s) => tokens.some((t) => s.includes(t));
+// First match wins. ORDER IS LOAD-BEARING — see the header comment.
+const RULES = [
+    { family: 'unknown', test: (s) => s === 'unknown' },
+    // `funding` before reversion: `funding_reversion` is its own family.
+    { family: 'funding', test: has('funding') },
+    // `range` before the generic `fade`: `range_fade` is distinct from mean_reversion.
+    { family: 'range', test: has('range') },
+    { family: 'breakout', test: has('breakout', 'squeeze', 'breakdown') },
+    { family: 'trend', test: has('trend', 'pullback', 'tape_follow', 'livermore') },
+    {
+        family: 'mean_reversion',
+        test: has('mean_rev', 'revers', // matches both "reversion" and "reversal"
+        'vwap', 'oversold', 'overbought', 'fade', 'cvd', 'divergence', 'exhaustion', 'macd'),
+    },
+];
+/**
+ * Normalize a free-text `setup_type` into a stable `setup_family`.
+ * Case- and whitespace-insensitive. `null` / `undefined` / `''` → 'unknown'.
+ * Unrecognized non-empty strings → 'other' (never silently merged).
+ */
+export function normalizeSetupFamily(setupType) {
+    if (setupType == null)
+        return 'unknown';
+    const s = String(setupType).trim().toLowerCase();
+    if (s === '')
+        return 'unknown';
+    for (const rule of RULES) {
+        if (rule.test(s))
+            return rule.family;
+    }
+    return 'other';
+}
+/**
+ * Resolve a learning's `trigger_condition` setup constraint into the family/families
+ * it targets, for family-aware matching. Used IDENTICALLY by both matchers (the
+ * webapp `get_relevant_learnings` route and the plugin `scan_pairs` veto) so they
+ * can never diverge.
+ *
+ * - Prefers an explicit `setup_family` (the family-keyed miner's output), taken
+ *   verbatim (scalar or array).
+ * - Else normalizes `setup_type` (legacy / operator-authored) to family(ies).
+ * - Returns `null` when the trigger pins NO setup constraint — the caller decides
+ *   whether that means wildcard (decision-time matcher) or no-veto (scan matcher).
+ */
+export function resolveTriggerFamilies(triggerSetupFamily, triggerSetupType) {
+    if (triggerSetupFamily != null) {
+        const arr = Array.isArray(triggerSetupFamily)
+            ? triggerSetupFamily
+            : [triggerSetupFamily];
+        return arr.map((x) => String(x));
+    }
+    if (triggerSetupType != null) {
+        const arr = Array.isArray(triggerSetupType)
+            ? triggerSetupType
+            : [triggerSetupType];
+        return arr.map((x) => normalizeSetupFamily(String(x)));
+    }
+    return null;
+}

package/lifecycle/install-signal-handlers.d.ts

@@ -0,0 +1,33 @@
+import type { PluginRuntime } from '../onboarding/runtime.js';
+/** Drain helper interface — only the methods we need on the trade-store
+ *  client.  Avoids importing the full class so this module can stay narrow. */
+export interface DrainableTradeStore {
+    drain(): Promise<void>;
+}
+/** Stop helper interface for the approval-mode ProposalDecisionListener.
+ *  Same single-method shape as DrainableTradeStore — kept narrow on purpose. */
+export interface StoppableListener {
+    stop(): Promise<void>;
+}
+/** Flush helper for the paper StateManager. Narrow on purpose — we only need
+ *  flush() to force out the 1s-debounced save before the process exits. */
+export interface FlushableStateManager {
+    flush(): Promise<void>;
+}
+export interface SignalHandlerDeps {
+    runtime: PluginRuntime;
+    tradeStore?: DrainableTradeStore;
+    proposalListener?: StoppableListener;
+    /** Paper-mode state persistence. Flushed last in the drain so the final ~1s
+     *  of debounced fills/closes/PnL are not lost on every restart. */
+    stateManager?: FlushableStateManager;
+}
+/** The phase-2 drain body. Exported for direct unit-testing of the teardown
+ *  ordering + the StateManager flush wiring (the signal handler itself can't
+ *  be tested without process.exit). Every step is individually guarded so one
+ *  failing teardown never aborts the rest. */
+export declare function performShutdownDrain(deps: SignalHandlerDeps): Promise<void>;
+/** Register graceful-shutdown handlers.  Idempotent — repeat signals during
+ *  the drain are logged + ignored.  After the coordinator resolves we call
+ *  process.exit(0) so systemd doesn't escalate to SIGKILL. */
+export declare function installSignalHandlers(deps: SignalHandlerDeps): void;