dexterm-cli 0.1.7 → 0.2.0

package/dist/packages/autotrade/examples/executor/README.md

@@ -0,0 +1,70 @@
+# dexterm executor reference kit
+
+dexterm holds no key and signs nothing. In real mode a strategy sends a **LIVE TRADE FIRE** signal
+(`dexterm-trade-fire/1`) for every buy and sell. **Your own executor** acts on it: a Telegram trading bot you chose,
+or any script.
+
+This folder holds three small executors you can wire up in minutes, so you can see the whole path work before
+anything can spend money:
+
+| file | channel | how dexterm reaches it |
+|---|---|---|
+| `webhook-executor.mjs` | webhook | `dexterm autotrade signal channels --webhook http://127.0.0.1:8787/signal` |
+| `signal-cmd-executor.mjs` | command hook | `dexterm autotrade signal channels --signal-cmd '["/abs/node","/abs/signal-cmd-executor.mjs","--account","main"]'` |
+| `jsonl-tail-executor.mjs` | JSONL stream | `dexterm autotrade signal channels --jsonl on` (add `--jsonl-signed on` for HMAC lines) |
+
+Each one handles every signal the same way:
+
+1. It verifies the HMAC, when you give it the secret file. Without `--secret-file` it acts on unsigned bodies (it says `HMAC NOT checked` when it starts); before you put a real trade into `act()`, run it with `--secret-file` and `--require-hmac`.
+2. It checks the account id.
+3. It dedupes by nonce. Delivery is at-least-once, so a repeat is normal, and the seen set survives a restart.
+4. It ignores anything past `expiresAt` (the TTL).
+5. It writes a receipt to dexterm's `autotrade/real/receipts.jsonl` and a heartbeat to `autotrade/real/executor.jsonl`.
+
+**All of them are DRY RUN.** `act()` in `kit.mjs` only logs what it WOULD do, and the receipt says so:
+status `rejected`, reason `dry-run: would BUY …`. There is no wallet code, no key and no chain call anywhere in this
+kit. Trading for real means replacing `act()` with your own code, or handing the order to your own bot. That is your
+code and your wallet, never dexterm's.
+
+## Five minutes, end to end (paper money only)
+
+```sh
+# 1. a secret for the HMAC (written to a 0600 file, stored in your keychain, never printed)
+dexterm autotrade signal secret generate --out ~/.dexterm-exec.secret
+
+# 2. start the kit's webhook executor (dry run) in another terminal
+node webhook-executor.mjs --account main --secret-file ~/.dexterm-exec.secret
+
+# 3. point dexterm at it, then prove the round trip
+dexterm autotrade signal channels --webhook http://127.0.0.1:8787/signal
+dexterm autotrade signal test          # per channel: delivered, latency, the kit's receipt
+dexterm autotrade executor status      # alive · last heartbeat · last receipt · lag
+```
+
+`signal test` sends a signal marked `test: true` that names no mint, so there is nothing in it to trade. The kit
+receipts it as `rejected` (`test signal: received, never traded`).
+
+## Heartbeats and the silence pause
+
+dexterm counts a heartbeat, a receipt, or an ack on the webhook or command hook as a sign of life. When it hears
+nothing for longer than your `executorSilenceMin` limit (placeholder: 15 min), a real run **pauses new buy
+signals** and tells you in the run log and on Telegram. Exits keep going out. The kit sends a heartbeat every 60 s
+(`--heartbeat-sec`). Your own executor can append the same line, POST it to the run's loopback listener
+(`--executor-port`), or run `dexterm autotrade executor heartbeat`:
+
+```json
+{"schema":"dexterm-executor-heartbeat/1","at":1761300000000,"executor":"my-bot","accountId":"main","dryRun":false,"lastNonce":42}
+```
+
+## Receipts
+
+A receipt is data only. It moves a real position from `unconfirmed` to executed / rejected / failed. With a fill
+(`priceUsd`, `sizeSol`, `tokens`, `txSig`), dexterm also measures how far the real fill was from its own paper fill:
+slippage, latency, partial fills and rejections. That shows in `dexterm autotrade audit`, `signal status` and
+`dexterm autotrade report`.
+
+```json
+{"schema":"dexterm-trade-receipt/1","signalId":"<the signal's id>","nonce":42,"accountId":"main","status":"executed","at":1761300001200,"fill":{"priceUsd":0.00123,"sizeSol":0.25,"tokens":40650,"txSig":null},"reason":null,"executor":"my-bot"}
+```
+
+See `telegram-bot-recipe.md` for the Telegram trading-bot setup. The bot executes, and dexterm never signs.

package/dist/packages/autotrade/examples/executor/jsonl-tail-executor.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// dexterm executor reference kit: the JSONL stream tail (task-1654). DRY RUN: logs what it would do; no wallet code.
+//
+//   node jsonl-tail-executor.mjs --account main [--stream FILE] [--secret-file FILE --require-hmac] [--once] [--poll-ms 1000]
+//
+// Turn the stream on in dexterm (`dexterm autotrade signal channels --jsonl on`, default file
+// autotrade/real/signals.jsonl). With `--jsonl-signed on` each line is an HMAC envelope this tail verifies; a bare
+// line has no signature, so --require-hmac refuses it. The read offset is saved, so a restart resumes where it was.
+// --once reads what is there and exits (handy for a test).
+
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SeenStore, args, dextermHome, handle, heartbeat, readSecret, realDir, unwrapLine } from './kit.mjs';
+
+const a = args();
+if (!a.account) { console.error('usage: node jsonl-tail-executor.mjs --account ID [--stream FILE] [--secret-file FILE] [--once]'); process.exit(2); }
+const home = a.home || dextermHome();
+const stream = a.stream || join(realDir(home), 'signals.jsonl');
+const offFile = a['offset-file'] || join(realDir(home), 'kit-tail-offset.json');
+const seen = new SeenStore(a.state || join(realDir(home), 'kit-tail-seen.json'));
+const secret = readSecret(a['secret-file']);
+const name = String(a.name || 'kit-jsonl-tail').slice(0, 32);
+const log = (s) => console.log(`[${new Date().toISOString()}] ${s}`);
+let offset = 0;
+try { offset = Number(JSON.parse(readFileSync(offFile, 'utf8')).offset) || 0; } catch { /* from the start */ }
+let carry = '';
+
+function poll() {
+  if (!existsSync(stream)) return;
+  const size = statSync(stream).size;
+  if (size < offset) { offset = 0; carry = ''; }
+  if (size === offset) return;
+  const fd = openSync(stream, 'r');
+  const buf = Buffer.alloc(size - offset);
+  try { readSync(fd, buf, 0, buf.length, offset); } finally { closeSync(fd); }
+  offset = size;
+  const lines = (carry + buf.toString('utf8')).split('\n');
+  carry = lines.pop() ?? '';
+  for (const l of lines) {
+    if (!l.trim()) continue;
+    const { body, signature } = unwrapLine(l);
+    handle(body, { accountId: a.account, secret, requireHmac: !!a['require-hmac'], signature, seen, home, executor: name, log, now: Date.now() });
+  }
+  writeFileSync(offFile, JSON.stringify({ offset: offset - Buffer.byteLength(carry) }));
+}
+
+const beat = () => { try { heartbeat(home, { executor: name, accountId: a.account, lastNonce: seen.maxNonce || null }); } catch (e) { log(`heartbeat failed: ${e.message}`); } };
+poll();
+beat();
+if (!a.once) {
+  log(`dexterm kit JSONL tail executor (DRY RUN) on ${stream} · account ${a.account}`);
+  const t1 = setInterval(poll, Math.max(100, Number(a['poll-ms'] ?? 1000)));
+  const t2 = setInterval(beat, Math.max(5, Number(a['heartbeat-sec'] ?? 60)) * 1000);
+  const stop = () => { clearInterval(t1); clearInterval(t2); process.exit(0); };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+}

package/dist/packages/autotrade/examples/executor/kit.mjs

@@ -0,0 +1,144 @@
+// dexterm executor reference kit: the shared part (task-1654). Plain Node (22+), no dependencies, no wallet code.
+//
+// Every kit executor does the same five things with a LIVE TRADE FIRE signal (`dexterm-trade-fire/1`):
+//   1. verify the HMAC (`t=<unix s>,v1=<hex sha256 of "<t>.<body>">`) when you gave it the secret file
+//   2. check the shape, and that the signal is for YOUR account id
+//   3. dedupe by nonce and id (delivery is at-least-once: a repeat is normal); the seen set survives a restart
+//   4. honor the TTL: anything past `expiresAt` is ignored, never acted on late
+//   5. write a receipt (`dexterm-trade-receipt/1`) to dexterm's receipts.jsonl, and a heartbeat now and then
+//
+// It is DRY RUN, always: `act()` below only logs what it WOULD do and the receipt says so (status "rejected",
+// reason "dry-run: …"). There is no key, no wallet and no chain call in this kit. To trade for real you replace
+// `act()` with your own executor's code (or hand the order to the Telegram trading bot you chose); dexterm never
+// signs anything.
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const SIGNAL_SCHEMA = 'dexterm-trade-fire/1';
+export const RECEIPT_SCHEMA = 'dexterm-trade-receipt/1';
+export const HEARTBEAT_SCHEMA = 'dexterm-executor-heartbeat/1';
+export const ENVELOPE_SCHEMA = 'dexterm-trade-fire-envelope/1';
+const TOLERANCE_SEC = 300;
+const MINT = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+/** `--name value` / `--flag` argv into an object. */
+export function args(argv = process.argv.slice(2)) {
+  const o = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const k = a.slice(2);
+    const v = argv[i + 1];
+    if (v !== undefined && !v.startsWith('--')) { o[k] = v; i++; } else o[k] = true;
+  }
+  return o;
+}
+
+/** Where dexterm keeps its files (DEXTERM_HOME, else ~/.dexterm). */
+export const dextermHome = (env = process.env) => env.DEXTERM_HOME || join(homedir(), '.dexterm');
+export const realDir = (home) => join(home, 'autotrade', 'real');
+
+/** The HMAC secret from a file (`dexterm autotrade signal secret generate --out FILE`), or null. */
+export function readSecret(file) {
+  if (!file) return null;
+  const v = readFileSync(file, 'utf8').trim();
+  return v || null;
+}
+
+export function verify(secret, header, body, nowMs = Date.now()) {
+  const m = /^t=(\d{1,12}),v1=([0-9a-f]{64})$/.exec(String(header ?? ''));
+  if (!m) return { ok: false, why: 'signature-missing' };
+  const t = Number(m[1]);
+  if (Math.abs(nowMs / 1000 - t) > TOLERANCE_SEC) return { ok: false, why: 'signature-stale' };
+  const want = createHmac('sha256', secret).update(`${t}.${body}`).digest();
+  const got = Buffer.from(m[2], 'hex');
+  return got.length === want.length && timingSafeEqual(got, want) ? { ok: true } : { ok: false, why: 'signature-bad' };
+}
+
+/** The seen nonces and ids, in a small JSON file so a restart does not act on a repeat. */
+export class SeenStore {
+  constructor(file) { this.file = file; this.seen = new Set(); this.maxNonce = 0; try { const d = JSON.parse(readFileSync(file, 'utf8')); for (const x of d.seen ?? []) this.seen.add(x); this.maxNonce = Number(d.maxNonce) || 0; } catch { /* first run */ } }
+  has(s) { return this.seen.has(s.id) || this.seen.has(`n${s.nonce}`); }
+  add(s) {
+    this.seen.add(s.id); this.seen.add(`n${s.nonce}`); this.maxNonce = Math.max(this.maxNonce, s.nonce);
+    const keep = [...this.seen].slice(-4000);
+    mkdirSync(dirname(this.file), { recursive: true });
+    const tmp = `${this.file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ seen: keep, maxNonce: this.maxNonce }));
+    renameSync(tmp, this.file);
+  }
+}
+
+/**
+ * Check one signal body. Returns { verdict, signal?, why }: verdict is act | duplicate | expired | rejected.
+ * `secret` null = no HMAC check (only when you chose not to set one).
+ */
+export function check(body, o) {
+  const now = o.now ?? Date.now();
+  if (o.secret) { const v = verify(o.secret, o.signature, body, now); if (!v.ok) return { verdict: 'rejected', why: v.why }; }
+  else if (o.requireHmac) return { verdict: 'rejected', why: 'signature-required' };
+  let s;
+  try { s = JSON.parse(body); } catch { return { verdict: 'rejected', why: 'not-json' }; }
+  if (!s || s.schema !== SIGNAL_SCHEMA || !['trade', 'halted', 'test'].includes(s.type) || !Number.isSafeInteger(s.nonce) || typeof s.id !== 'string') return { verdict: 'rejected', why: 'shape' };
+  if (s.paper !== false) return { verdict: 'rejected', why: 'paper-flag' };
+  if (s.accountId !== o.accountId) return { verdict: 'rejected', why: 'wrong-account', signal: s };
+  if (o.seen.has(s)) return { verdict: 'duplicate', why: 'duplicate', signal: s };
+  if (!(now <= s.expiresAt)) return { verdict: 'expired', why: 'expired', signal: s };
+  if (s.type === 'trade' && (!MINT.test(s.mint) || (s.side !== 'buy' && s.side !== 'sell'))) return { verdict: 'rejected', why: 'shape', signal: s };
+  if (s.type === 'trade' && s.nonce <= o.seen.maxNonce) return { verdict: 'rejected', why: 'nonce-replay', signal: s };
+  return { verdict: 'act', why: null, signal: s };
+}
+
+/**
+ * What the executor does with a fresh signal. DRY RUN: it only says what it WOULD do. Replace this with your own
+ * code to trade (your wallet, your bot); keep the rest of the pipeline (verify, dedupe, TTL, receipt) as it is.
+ */
+export function act(s) {
+  if (s.type === 'test') return { status: 'rejected', reason: 'test signal: received, never traded' };
+  if (s.type === 'halted') return { status: null, reason: `halted (${s.reason}): would cancel ${s.outstanding.length} outstanding signal(s)` };
+  const what = s.side === 'buy' ? `would BUY ${s.sizeSol} SOL of ${s.symbol} (${s.mint}) with ${s.slippageBps} bps slippage` : `would SELL ${Math.round(s.sellFraction * 1000) / 10}% of ${s.symbol} (${s.mint}): ${s.exitReason}`;
+  return { status: 'rejected', reason: `dry-run: ${what}`.slice(0, 120) };
+}
+
+/** Append a receipt line to dexterm's receipts.jsonl (the same file `dexterm autotrade receipt` writes). */
+export function writeReceipt(home, s, r, executor, now = Date.now()) {
+  const line = { schema: RECEIPT_SCHEMA, signalId: s.id, nonce: s.nonce, accountId: s.accountId, status: r.status, at: now, fill: r.fill ?? null, reason: r.reason ?? null, executor };
+  mkdirSync(realDir(home), { recursive: true, mode: 0o700 });
+  appendFileSync(join(realDir(home), 'receipts.jsonl'), `${JSON.stringify(line)}\n`, { mode: 0o600 });
+  return line;
+}
+
+/** Append a heartbeat to dexterm's executor.jsonl: dexterm pauses new buys when it hears nothing for too long. */
+export function heartbeat(home, o) {
+  const hb = { schema: HEARTBEAT_SCHEMA, at: o.now ?? Date.now(), executor: o.executor, accountId: o.accountId ?? null, dryRun: true, lastNonce: o.lastNonce ?? null, note: o.note ?? null };
+  mkdirSync(realDir(home), { recursive: true, mode: 0o700 });
+  appendFileSync(join(realDir(home), 'executor.jsonl'), `${JSON.stringify(hb)}\n`, { mode: 0o600 });
+  return hb;
+}
+
+/** The whole pipeline for one body: check, act (dry run), receipt, log line. Returns the verdict. */
+export function handle(body, o) {
+  const c = check(body, o);
+  const s = c.signal;
+  if (c.verdict === 'act') {
+    o.seen.add(s);
+    const r = act(s);
+    if (r.status && s.type !== 'halted') writeReceipt(o.home, s, r, o.executor, o.now ?? Date.now());
+    o.log(`#${s.nonce} ${s.type}${s.type === 'trade' ? ` ${s.side}` : ''}: ${r.reason}`);
+  } else o.log(`${s ? `#${s.nonce} ` : ''}${c.verdict}: ${c.why}`);
+  return c;
+}
+
+/** A stream line: a bare signal, or a signed envelope (`dexterm autotrade signal channels --jsonl-signed on`). */
+export function unwrapLine(line) {
+  try {
+    const x = JSON.parse(line);
+    if (x && x.schema === ENVELOPE_SCHEMA && typeof x.signal === 'string') return { body: x.signal, signature: x.signature ?? null };
+  } catch { /* handled by check() */ }
+  return { body: line, signature: null };
+}
+
+export const exists = existsSync;

package/dist/packages/autotrade/examples/executor/signal-cmd-executor.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// dexterm executor reference kit: the --signal-cmd hook (task-1654). DRY RUN: logs what it would do; no wallet code.
+//
+// dexterm runs it once per signal, with no shell, the signal line on stdin and the HMAC in DEXTERM_SIGNAL_SIGNATURE
+// (when a secret is set). Wire it with an absolute path:
+//   dexterm autotrade signal channels --signal-cmd '["/usr/local/bin/node","/path/to/signal-cmd-executor.mjs","--account","main","--secret-file","/path/to/secret"]'
+//
+// Exit codes dexterm reads: 0 acted (dry run) · 3 duplicate (counted delivered) · 2 rejected or expired (never
+// retried) · anything else is retried. A line per signal goes to --log (default autotrade/real/kit-cmd.log).
+
+import { appendFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SeenStore, args, dextermHome, handle, heartbeat, readSecret, realDir } from './kit.mjs';
+
+const a = args();
+if (!a.account) { console.error('usage: signal-cmd-executor.mjs --account ID [--secret-file FILE] [--home DIR]'); process.exit(2); }
+const home = a.home || dextermHome();
+const logFile = a.log || join(realDir(home), 'kit-cmd.log');
+const log = (s) => { try { appendFileSync(logFile, `[${new Date().toISOString()}] ${s}\n`); } catch { /* the exit code still answers */ } };
+const name = String(a.name || 'kit-signal-cmd').slice(0, 32);
+const body = readFileSync(0, 'utf8').trim();
+const seen = new SeenStore(a.state || join(realDir(home), 'kit-cmd-seen.json'));
+const c = handle(body, { accountId: a.account, secret: readSecret(a['secret-file']), requireHmac: !!a['require-hmac'], signature: process.env.DEXTERM_SIGNAL_SIGNATURE ?? null, seen, home, executor: name, log, now: Date.now() });
+try { heartbeat(home, { executor: name, accountId: a.account, lastNonce: seen.maxNonce || null }); } catch { /* optional */ }
+process.exit(c.verdict === 'act' ? 0 : c.verdict === 'duplicate' ? 3 : 2);

package/dist/packages/autotrade/examples/executor/telegram-bot-recipe.md

@@ -0,0 +1,47 @@
+# Recipe: a Telegram trading bot as your executor
+
+Many people already trade memecoins through a Telegram trading bot. That bot holds the wallet and signs the swaps.
+dexterm can drive the decision side, but it can never be the bot and never holds the bot's key.
+
+## Why the Telegram copy alone is not enough
+
+dexterm's Telegram copy of each signal goes to **your** chat, for you to read. A bot cannot read another bot's
+messages, so your trading bot never sees that copy. Something on your side has to hand each signal to the bot.
+
+## The shape that works
+
+```
+dexterm (real mode) --signal--> your small relay (one of the kit executors) --order--> your trading bot
+                     <--receipt--                                          <--fill--
+```
+
+1. Start from one of the kit executors, for example `webhook-executor.mjs`. It already verifies the HMAC, dedupes
+   by nonce, honours the TTL, writes receipts and sends heartbeats.
+2. Replace `act()` in `kit.mjs` with the call your bot offers to accounts that automate it. Depending on the bot
+   that is an HTTP API, a CLI, or a message your own user account sends to it through a Telegram client library.
+   Use only what the bot documents and allows. That code, its credentials and the wallet are yours; keep them out
+   of dexterm's folders.
+3. When the bot answers, write the receipt with the real fill: `status: "executed"` plus `priceUsd`, `sizeSol`,
+   `tokens` and `txSig`, or `rejected` / `failed` with a reason. dexterm then shows how far the real fills were
+   from paper.
+4. Keep the relay's heartbeat running. If the relay or the bot goes quiet longer than your `executorSilenceMin`,
+   dexterm pauses new buy signals and tells you.
+
+## Rules the relay must keep (the kit does)
+
+- It acts only on signals for its own `accountId`.
+- It never acts after `expiresAt`, and it never retries a stale order on its own.
+- It dedupes by `nonce` and `id`, because the same signal can arrive twice.
+- It treats `type: "test"` as a test: there is never an order.
+- On `type: "halted"`, it may cancel the `outstanding` nonces that are still open on its side. `open` lists what
+  dexterm still counts as held.
+- It sizes from its own wallet. `sizeSol` is what dexterm's limits allowed, and `sellFraction` applies to what the
+  bot really holds.
+
+## Before any real money
+
+- Run the relay in dry run first. `dexterm autotrade signal test` must show every channel delivered and the relay's
+  receipt.
+- Set your own limits (`dexterm autotrade limits set …`). The defaults are placeholders: 0.25 SOL per trade, 1 SOL
+  a day, 20 buys, 3 open, stop at -0.5 SOL a day.
+- Keep `dexterm autotrade signal kill` at hand. It stops every signal except one final `halted`.

package/dist/packages/autotrade/examples/executor/webhook-executor.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// dexterm executor reference kit: the WEBHOOK receiver (task-1654). DRY RUN: logs what it would do; no wallet code.
+//
+//   node webhook-executor.mjs --account main [--port 8787] [--secret-file FILE] [--home DIR] [--heartbeat-sec 60]
+//
+// Then point dexterm at it:  dexterm autotrade signal channels --webhook http://127.0.0.1:8787/signal
+// and prove the wiring:      dexterm autotrade signal test
+//
+// Answers: 200 acted (dry run) · 409 duplicate (dexterm counts it delivered) · 410 expired · 401 bad signature ·
+// 400 anything else it will not act on. It binds 127.0.0.1 only. Ctrl-C stops it.
+
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { SeenStore, args, dextermHome, handle, heartbeat, readSecret, realDir } from './kit.mjs';
+
+const a = args();
+if (!a.account) { console.error('usage: node webhook-executor.mjs --account ID [--port 8787] [--secret-file FILE] [--home DIR]'); process.exit(2); }
+const home = a.home || dextermHome();
+const secret = readSecret(a['secret-file']);
+const seen = new SeenStore(a.state || join(realDir(home), 'kit-webhook-seen.json'));
+const name = String(a.name || 'kit-webhook').slice(0, 32);
+const log = (s) => console.log(`[${new Date().toISOString()}] ${s}`);
+const o = { accountId: a.account, secret, requireHmac: !!a['require-hmac'], seen, home, executor: name, log };
+
+const server = createServer((req, res) => {
+  if (req.method !== 'POST') { res.writeHead(405); res.end('POST only'); return; }
+  let body = '';
+  req.setEncoding('utf8');
+  req.on('data', (c) => { body += c; if (body.length > 64 * 1024) req.destroy(); });
+  req.on('end', () => {
+    const c = handle(body, { ...o, signature: req.headers['x-dexterm-signature'] ?? null, now: Date.now() });
+    const code = c.verdict === 'act' ? 200 : c.verdict === 'duplicate' ? 409 : c.verdict === 'expired' ? 410 : /^signature/.test(c.why ?? '') ? 401 : 400;
+    res.writeHead(code, { 'content-type': 'text/plain' });
+    res.end(c.verdict);
+  });
+});
+
+const beat = () => { try { heartbeat(home, { executor: name, accountId: a.account, lastNonce: seen.maxNonce || null }); } catch (e) { log(`heartbeat failed: ${e.message}`); } };
+server.listen(Number(a.port ?? 8787), '127.0.0.1', () => {
+  const port = server.address().port;
+  log(`dexterm kit webhook executor (DRY RUN) listening on http://127.0.0.1:${port}/signal · account ${a.account} · HMAC ${secret ? 'checked' : 'NOT checked (no --secret-file)'}`);
+  beat();
+});
+const timer = setInterval(beat, Math.max(5, Number(a['heartbeat-sec'] ?? 60)) * 1000);
+const stop = () => { clearInterval(timer); server.close(() => process.exit(0)); };
+process.on('SIGINT', stop);
+process.on('SIGTERM', stop);

package/dist/packages/autotrade/src/backtest.js

@@ -32,7 +32,8 @@ export const DATA_LIMITS = [
 /** A closed trade at or below this is counted as a rug (the challenge's rugAtPct). */
 export const RUG_PCT = -80;
 export async function backtest(strategy, tape, sessions = null) {
-    const run = await runAutotrade({ strategy, tape, sessions, pacing: { mode: 'lockstep' } });
+    // task-1645: a strategy in mode real backtests as its paper twin (a backtest never emits a trade-fire signal).
+    const run = await runAutotrade({ strategy: strategy.mode === 'real' ? { ...strategy, mode: 'paper' } : strategy, tape, sessions, pacing: { mode: 'lockstep' } });
     return { report: report(strategy, tape, run), run };
 }
 export function report(s, tape, run) {

package/dist/packages/autotrade/src/chat/config.js

@@ -3,7 +3,9 @@
 // $DEXTERM_HOME/connectors.json (0600):
 //   { schema, telegram: { enabled, bot: {id, username}, secretStore, tiers, allow: [{senderId, chatId, tiers,
 //     pairedAt}], notify: {…per event…}, dailySummaryAt, quietHours, approvals, approvalExpirySec, repriceTolPct,
-//     showAbsoluteBook } }
+//     showAbsoluteBook }, signals: {…} }
+// task-1645: `signals` is the real-mode trade-fire channel setup (signal-channels.ts parses it); it lives here so the
+// Telegram copy and the executor channels are configured in one place. This module only carries it through.
 // Only local commands write it (`dexterm telegram setup|pair|revoke|approvals|notify`). From chat, exactly one
 // field can change: `approvals` from "off" to "on" (safer); everything else, and "off", is local only.
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
@@ -70,7 +72,7 @@ export function loadConnectors(home) {
         repriceTolPct: Number.isFinite(tol) && tol > 0 ? Math.min(10, tol) : 3,
         showAbsoluteBook: t.showAbsoluteBook === true,
     };
-    return { ok: true, config: { schema: CONNECTORS_SCHEMA, telegram }, exists: true };
+    return { ok: true, config: { schema: CONNECTORS_SCHEMA, telegram, ...(d.signals !== undefined ? { signals: d.signals } : {}) }, exists: true };
 }
 export function saveConnectors(home, c) {
     mkdirSync(home, { recursive: true, mode: 0o700 });

package/dist/packages/autotrade/src/chat/control.js

@@ -45,6 +45,7 @@ export class ControlRouter {
                         `open ${s.open} · candidates ${s.candidates} · day P/L ${pct(s.dayPnlPct)}`,
                         `model spend today $${s.spend.todayUsd.toFixed(2)}${Number.isFinite(s.spend.dayCapUsd) ? ` of $${s.spend.dayCapUsd}` : ''}${s.allowance?.fiveHour !== null && s.allowance?.fiveHour !== undefined ? ` · 5 h window ${Math.round(s.allowance.fiveHour * 100)}%` : ''}`,
                         `approvals: ${s.approvals}`,
+                        ...(s.real ? [`executor: ${inert(s.real.executor, 160)}`, `limits: ${inert(s.real.limits, 160)}`, ...(s.real.pause ? [`NEW BUYS PAUSED: ${inert(s.real.pause, 120)}`] : [])] : []),
                     ],
                 };
             }

package/dist/packages/autotrade/src/chat/notify.js

@@ -49,6 +49,9 @@ export class NotifyBus {
     warned = new Set();
     summarySentFor = '';
     dayStart;
+    /** task-1645: a run in mode real is LIVE in every message (its trades go to the user's executor as signals). */
+    realRun = false;
+    badge() { return this.realRun ? 'LIVE' : this.o.badge; }
     constructor(o) {
         this.o = o;
         this.now = o.now ?? Date.now;
@@ -77,7 +80,7 @@ export class NotifyBus {
         }
     }
     emit(template, lines, urgent = false) {
-        this.post(template, { kind: 'text', badge: this.o.badge, lines }, urgent);
+        this.post(template, { kind: 'text', badge: this.badge(), lines }, urgent);
     }
     post(template, msg, urgent) {
         const now = this.now();
@@ -95,7 +98,7 @@ export class NotifyBus {
     ofBook(usd) {
         const eq = this.state?.book.equityUsd ?? 0;
         const share = eq > 0 ? `${((usd / eq) * 100).toFixed(1)}% of book` : '% of book unknown';
-        return this.o.config().showAbsoluteBook && this.o.badge === 'PAPER' && eq > 0 ? `${share}, book ${usdShort(eq)}` : share;
+        return this.o.config().showAbsoluteBook && this.badge() === 'PAPER' && eq > 0 ? `${share}, book ${usdShort(eq)}` : share;
     }
     sym(mint, fallback) { return `"${inert(this.symbols.get(mint) ?? fallback ?? '?', 20)}" ${shortMint(mint)}`; }
     handle(e) {
@@ -105,8 +108,9 @@ export class NotifyBus {
         switch (e.kind) {
             case 'run_start': {
                 this.highRisk = e.highRisk === true;
+                this.realRun = e.mode === 'real';
                 this.strategyLine = `${this.highRisk ? '⚠ HIGH RISK · ' : ''}${inert(e.strategy, 32)} v${inert(e.version, 12)} (${String(e.strategyHash ?? '').slice(0, 8)})`;
-                this.emit('run_start', [`RUNNER STARTED · ${this.strategyLine}`, ...(this.highRisk ? ['full-port strategy: one entry can be the whole stake, and one rug can zero it. Experimental; not financial advice.'] : []), `entries: ${e.decide === 'agent+approve' || e.approvals === 'required' ? 'each one waits for your tap' : String(e.decide) === 'auto' ? 'mechanical' : 'your agent decides'} · /status /pause /kill /help`], true);
+                this.emit('run_start', [`RUNNER STARTED · ${this.strategyLine}`, ...(this.highRisk ? ['full-port strategy: one entry can be the whole stake, and one rug can zero it. Experimental; not financial advice.'] : []), ...(this.realRun ? ['REAL MODE: every trade below also goes to YOUR executor as a LIVE TRADE FIRE signal (dexterm holds no key). Experimental; not financial advice.'] : []), `entries: ${e.decide === 'agent+approve' || e.approvals === 'required' ? 'each one waits for your tap' : String(e.decide) === 'auto' ? 'mechanical' : 'your agent decides'} · /status /pause /kill /help`], true);
                 return;
             }
             case 'candidate': {
@@ -171,13 +175,19 @@ export class NotifyBus {
                     return;
                 const caption = `CLOSED · "${inert(t.symbol, 20)}" ${shortMint(t.mint)} · ${pct(t.pnlPct)} (${t.pnlUsd >= 0 ? '+' : ''}${usdShort(t.pnlUsd)}) by ${inert(t.exitReason, 40)} · held ${Math.max(1, Math.round((t.closedAt - t.openedAt) / 60_000))} min`;
                 const card = this.o.card;
+                // task-1645: a real run's close is the monitor's modelled view, not your executor's fills: text only, no
+                // shareable card (the receipts say what really filled).
+                if (this.realRun) {
+                    this.emit('closed', [`${caption} · modelled; your executor's fills may differ (dexterm autotrade receipt list)`]);
+                    return;
+                }
                 if (!card) {
                     this.emit('closed', [caption]);
                     return;
                 }
                 void card(t).then((png) => {
                     if (png)
-                        this.post('closed_card', { kind: 'card', badge: this.o.badge, png, caption }, false);
+                        this.post('closed_card', { kind: 'card', badge: this.badge(), png, caption }, false);
                     else
                         this.emit('closed', [caption]);
                 }, () => this.emit('closed', [caption]));
@@ -253,7 +263,7 @@ export class NotifyBus {
             this.sentAt.shift();
         if (this.digest.length && !quiet && this.sentAt.length < DIGEST_ABOVE_PER_MIN / 2) {
             const lines = this.digest.splice(0);
-            this.post('digest', { kind: 'text', badge: this.o.badge, lines: [`DIGEST · ${lines.length} update${lines.length === 1 ? '' : 's'}`, ...lines.slice(-25)] }, true);
+            this.post('digest', { kind: 'text', badge: this.badge(), lines: [`DIGEST · ${lines.length} update${lines.length === 1 ? '' : 's'}`, ...lines.slice(-25)] }, true);
         }
         this.maybeSummary(now);
         await this.queue;
@@ -270,7 +280,7 @@ export class NotifyBus {
         if (this.summarySentFor === day)
             return;
         this.summarySentFor = day;
-        this.post('daily', { kind: 'text', badge: this.o.badge, lines: this.summaryLines() }, true);
+        this.post('daily', { kind: 'text', badge: this.badge(), lines: this.summaryLines() }, true);
     }
     summaryLines() {
         const st = this.state;

package/dist/packages/autotrade/src/chat/secrets.js

@@ -14,12 +14,18 @@ import { join, resolve } from 'node:path';
 export const SECRET_SERVICE = 'xyz.dexterm.telegram';
 export const accountFor = (home) => `bot-token-${createHash('sha256').update(resolve(home)).digest('hex').slice(0, 12)}`;
 const has = (bin) => spawnSync('/usr/bin/env', ['which', bin], { stdio: 'ignore' }).status === 0;
+export const TELEGRAM_TOKEN_ITEM = { service: SECRET_SERVICE, label: 'dexterm telegram bot', file: 'telegram-bot.token', account: accountFor };
+export const SIGNAL_HMAC_ITEM = {
+    service: 'xyz.dexterm.signal', label: 'dexterm trade-fire webhook secret', file: 'signal-webhook.secret',
+    account: (home) => `signal-hmac-${createHash('sha256').update(resolve(home)).digest('hex').slice(0, 12)}`,
+};
 class KeychainStore {
     kind = 'keychain';
     account;
-    constructor(account) { this.account = account; }
+    item;
+    constructor(account, item = TELEGRAM_TOKEN_ITEM) { this.account = account; this.item = item; }
     get() {
-        const r = spawnSync('security', ['find-generic-password', '-a', this.account, '-s', SECRET_SERVICE, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const r = spawnSync('security', ['find-generic-password', '-a', this.account, '-s', this.item.service, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
         const v = r.status === 0 ? r.stdout.trim() : '';
         return v || null;
     }
@@ -27,32 +33,33 @@ class KeychainStore {
         if (!/^[A-Za-z0-9:_-]+$/.test(value))
             throw new Error('refusing to store a value with characters a bot token never has');
         // The add command (with the value) goes through stdin; argv only says "-i".
-        const r = spawnSync('security', ['-i'], { input: `add-generic-password -U -a ${this.account} -s ${SECRET_SERVICE} -l "dexterm telegram bot" -w "${value}"\n`, encoding: 'utf8', stdio: ['pipe', 'ignore', 'pipe'] });
+        const r = spawnSync('security', ['-i'], { input: `add-generic-password -U -a ${this.account} -s ${this.item.service} -l "${this.item.label}" -w "${value}"\n`, encoding: 'utf8', stdio: ['pipe', 'ignore', 'pipe'] });
         if (r.status !== 0 || this.get() !== value)
             throw new Error('the macOS keychain did not store the token');
     }
-    remove() { spawnSync('security', ['delete-generic-password', '-a', this.account, '-s', SECRET_SERVICE], { stdio: 'ignore' }); }
+    remove() { spawnSync('security', ['delete-generic-password', '-a', this.account, '-s', this.item.service], { stdio: 'ignore' }); }
 }
 class LibsecretStore {
     kind = 'libsecret';
     account;
-    constructor(account) { this.account = account; }
+    item;
+    constructor(account, item = TELEGRAM_TOKEN_ITEM) { this.account = account; this.item = item; }
     get() {
-        const r = spawnSync('secret-tool', ['lookup', 'service', SECRET_SERVICE, 'account', this.account], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const r = spawnSync('secret-tool', ['lookup', 'service', this.item.service, 'account', this.account], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
         const v = r.status === 0 ? r.stdout.trim() : '';
         return v || null;
     }
     set(value) {
-        const r = spawnSync('secret-tool', ['store', '--label=dexterm telegram bot', 'service', SECRET_SERVICE, 'account', this.account], { input: value, encoding: 'utf8', stdio: ['pipe', 'ignore', 'pipe'] });
+        const r = spawnSync('secret-tool', ['store', `--label=${this.item.label}`, 'service', this.item.service, 'account', this.account], { input: value, encoding: 'utf8', stdio: ['pipe', 'ignore', 'pipe'] });
         if (r.status !== 0 || this.get() !== value)
             throw new Error('libsecret did not store the token');
     }
-    remove() { spawnSync('secret-tool', ['clear', 'service', SECRET_SERVICE, 'account', this.account], { stdio: 'ignore' }); }
+    remove() { spawnSync('secret-tool', ['clear', 'service', this.item.service, 'account', this.account], { stdio: 'ignore' }); }
 }
 class FileStore {
     kind = 'file';
     path;
-    constructor(home) { this.path = join(home, 'secrets', 'telegram-bot.token'); }
+    constructor(home, item = TELEGRAM_TOKEN_ITEM) { this.path = join(home, 'secrets', item.file); }
     get() {
         if (!existsSync(this.path))
             return null;
@@ -77,23 +84,23 @@ export class MemoryStore {
     remove() { this.v = null; }
 }
 /** The store a kind names (the one setup recorded), for this home. */
-export function secretStore(kind, home) {
+export function secretStore(kind, home, item = TELEGRAM_TOKEN_ITEM) {
     if (kind === 'keychain')
-        return new KeychainStore(accountFor(home));
+        return new KeychainStore(item.account(home), item);
     if (kind === 'libsecret')
-        return new LibsecretStore(accountFor(home));
+        return new LibsecretStore(item.account(home), item);
     if (kind === 'memory')
         return new MemoryStore();
-    return new FileStore(home);
+    return new FileStore(home, item);
 }
 /** The best store on this machine: DEXTERM_SECRET_STORE wins, then the OS store, then the 0600 file. */
-export function chooseSecretStore(home, env = process.env, platform = process.platform) {
+export function chooseSecretStore(home, env = process.env, platform = process.platform, item = TELEGRAM_TOKEN_ITEM) {
     const want = env.DEXTERM_SECRET_STORE;
     if (want === 'file' || want === 'keychain' || want === 'libsecret')
-        return secretStore(want, home);
+        return secretStore(want, home, item);
     if (platform === 'darwin' && has('security'))
-        return secretStore('keychain', home);
+        return secretStore('keychain', home, item);
     if (platform === 'linux' && has('secret-tool'))
-        return secretStore('libsecret', home);
-    return secretStore('file', home);
+        return secretStore('libsecret', home, item);
+    return secretStore('file', home, item);
 }

package/dist/packages/autotrade/src/chat/service.js

@@ -12,6 +12,8 @@
 import { riskDelta } from '../../../mcp/src/index.js';
 import { StrategyStore } from "../store.js";
 import { requestControl } from "../safety.js";
+import { healthLine } from "../executor-health.js";
+import { limitsSummary } from "../limits.js";
 import { badgeOf } from "../execution-port.js";
 import { ApprovalBroker, CallbackStore, callbackDbPath } from "./approvals.js";
 import { ChatAudit } from "./audit.js";
@@ -64,6 +66,7 @@ export class HostControlPort {
             runId, state: st.state, haltReason: st.haltReason, strategy: st.strategy, open: st.positions.length, candidates: st.candidates.length,
             dayPnlPct: start > 0 ? (st.book.realizedTodayUsd / start) * 100 : null, spend: { todayUsd: st.spend.todayUsd, dayCapUsd: st.spend.dayCapUsd }, allowance: st.spend.allowance,
             approvals: s?.entry.decide === 'agent+approve' ? 'required by the strategy' : cfg.approvals,
+            ...(st.real?.executor ? { real: { executor: healthLine(st.real.executor), limits: limitsSummary(st.real.limits ?? {}), pause: st.real.risk?.buyPause ?? null } } : {}),
         };
     }
     positions() {