dexterm-cli 0.1.7 → 0.2.1

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

@@ -0,0 +1,289 @@
+// dexterm autotrade — the always-on service: lock, heartbeat, stop marker, crash-loop guard and the `ensure`
+// decision (0.2.0 card B, AUTOTRADE-SPEC §7.4 / AT-10). Mode-agnostic: the service hosts `run --all` and never
+// decides paper or real itself.
+//
+// Shape (one per machine and DEXTERM_HOME):
+//   OS scheduler (LaunchAgent / systemd user timer / scheduled task), every 60 s and at login
+//     └─ `dexterm autotrade service ensure`   exits at once when the heartbeat is fresh; otherwise starts the service
+//          └─ `dexterm autotrade service run`  detached: service lock + heartbeat every 10 s + guard + the fleet
+//
+// Files under $DEXTERM_HOME/autotrade/service/:
+//   service.lock    {pid, bootAt, startedAt}: a stale lock is reclaimed only when that pid is dead (or from an older boot)
+//   heartbeat.json  dexterm-autotrade-service/1: state, fleet id, guard states; rewritten every 10 s; `stopped` on a
+//                   clean exit (anything else with a dead pid is a crash)
+//   STOP            the stop marker: `service stop`, a Telegram / Q-screen / CLI stop of the fleet, or a plain `touch`.
+//                   A clean stop stays stopped: `ensure` does nothing until `service start` removes it.
+//   starts.json     the crash-loop guard: every start after a crash, and the give-up record (`attention`)
+//   state.json      the fleet the service is running (recovery after a crash reads its ledgers, service-recover.ts)
+// Logs: $DEXTERM_HOME/autotrade/logs/service.log (+ .1), size-capped (BoundedLog).
+//
+// Crash-loop guard: a start that follows a crash waits a backoff (0, 0, 1, 2, 4 min for the 1st..5th crash in an
+// hour); the 6th crash within an hour writes `attention`, sends ONE notification and leaves the service down until
+// `dexterm autotrade service status --clear`. A clean stop and a manual `service start` never count.
+//
+// Nothing here holds a key, signs, touches a wallet or the network, and no model reaches any of it.
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync } from 'node:fs';
+import { uptime } from 'node:os';
+import { join } from 'node:path';
+import { writeJsonAtomic } from "./ledger.js";
+export const SERVICE_SCHEMA = 'dexterm-autotrade-service/1';
+export const SERVICE_HEARTBEAT_MS = 10_000;
+/** `ensure` treats a heartbeat older than this as "not running" (three missed beats). */
+export const SERVICE_STALE_MS = 35_000;
+/** A live pid whose heartbeat is this old is hung: `ensure` ends it so the next tick restarts it. */
+export const SERVICE_HUNG_MS = 180_000;
+export const CRASH_WINDOW_MS = 60 * 60_000;
+/** Crash restarts allowed in CRASH_WINDOW_MS; the next one gives up. */
+export const MAX_CRASH_RESTARTS = 5;
+export const serviceDir = (home) => join(home, 'autotrade', 'service');
+export const serviceLogDir = (home) => join(home, 'autotrade', 'logs');
+export const serviceLockPath = (home) => join(serviceDir(home), 'service.lock');
+export const serviceHeartbeatPath = (home) => join(serviceDir(home), 'heartbeat.json');
+export const serviceStopPath = (home) => join(serviceDir(home), 'STOP');
+export const serviceStartsPath = (home) => join(serviceDir(home), 'starts.json');
+export const serviceStatePath = (home) => join(serviceDir(home), 'state.json');
+export const serviceLogPath = (home) => join(serviceLogDir(home), 'service.log');
+const mkdirs = (home) => { mkdirSync(serviceDir(home), { recursive: true, mode: 0o700 }); };
+const readJson = (path) => { try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+catch {
+    return null;
+} };
+export const pidAlive = (pid) => {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+};
+/** This boot's start, rounded to the minute (a pid from an older boot is never this process). */
+export const bootAt = () => Math.round((Date.now() - uptime() * 1000) / 60_000) * 60_000;
+/** Take the service lock (O_EXCL). A holder is stale only when its pid is dead or it is from an older boot. */
+export function acquireServiceLock(home, d = {}) {
+    mkdirs(home);
+    const path = serviceLockPath(home);
+    const alive = d.alive ?? pidAlive;
+    const lock = { pid: d.pid ?? process.pid, bootAt: d.boot ?? bootAt(), startedAt: d.now ?? Date.now() };
+    let reclaimed = null;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(path, 'wx', 0o600);
+            writeSync(fd, `${JSON.stringify(lock)}\n`);
+            closeSync(fd);
+            return { ok: true, lock, reclaimed };
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+        }
+        const held = readJson(path);
+        if (held && typeof held.pid === 'number' && alive(held.pid) && Math.abs((held.bootAt ?? 0) - lock.bootAt) <= 5 * 60_000)
+            return { ok: false, holder: held };
+        reclaimed = held;
+        rmSync(path, { force: true });
+    }
+    throw new Error(`could not take ${path}`);
+}
+export function releaseServiceLock(home, pid = process.pid) {
+    const held = readJson(serviceLockPath(home));
+    if (held && held.pid === pid)
+        rmSync(serviceLockPath(home), { force: true });
+}
+/** The lock holder when its pid is alive (and from this boot), else null. */
+export function liveServiceHolder(home, alive = pidAlive, boot = bootAt()) {
+    const held = readJson(serviceLockPath(home));
+    if (!held || typeof held.pid !== 'number' || !alive(held.pid))
+        return null;
+    return Math.abs((held.bootAt ?? 0) - boot) <= 5 * 60_000 ? held : null;
+}
+export function writeServiceHeartbeat(home, hb) {
+    mkdirs(home);
+    writeJsonAtomic(serviceHeartbeatPath(home), hb);
+}
+export function readServiceHeartbeat(home) {
+    const d = readJson(serviceHeartbeatPath(home));
+    return d && d.schema === SERVICE_SCHEMA && typeof d.pid === 'number' && typeof d.heartbeatAt === 'number' ? d : null;
+}
+export function writeStopMarker(home, by, reason, now = Date.now()) {
+    mkdirs(home);
+    const m = { at: now, by, reason: reason.slice(0, 200) };
+    writeJsonAtomic(serviceStopPath(home), m);
+    return m;
+}
+/** The stop marker, or null. A file that is not our JSON (a plain `touch`) is still a stop. */
+export function readStopMarker(home) {
+    const p = serviceStopPath(home);
+    if (!existsSync(p))
+        return null;
+    const d = readJson(p);
+    if (d && typeof d.at === 'number')
+        return { at: d.at, by: (d.by ?? 'file'), reason: typeof d.reason === 'string' ? d.reason : 'stop' };
+    let at = 0;
+    try {
+        at = statSync(p).mtimeMs;
+    }
+    catch { /* raced */ }
+    return { at, by: 'file', reason: 'the STOP file is present' };
+}
+export const clearStopMarker = (home) => { rmSync(serviceStopPath(home), { force: true }); };
+const EMPTY_STARTS = { crashStarts: [], lastStartAt: null, attention: null, downNotifiedAt: null };
+export function readStarts(home) {
+    const d = readJson(serviceStartsPath(home));
+    if (!d)
+        return { ...EMPTY_STARTS, crashStarts: [] };
+    return {
+        crashStarts: Array.isArray(d.crashStarts) ? d.crashStarts.filter((t) => typeof t === 'number') : [],
+        lastStartAt: typeof d.lastStartAt === 'number' ? d.lastStartAt : null,
+        attention: d.attention && typeof d.attention.at === 'number' ? { at: d.attention.at, why: String(d.attention.why ?? ''), notified: !!d.attention.notified } : null,
+        downNotifiedAt: typeof d.downNotifiedAt === 'number' ? d.downNotifiedAt : null,
+    };
+}
+export function writeStarts(home, d) { mkdirs(home); writeJsonAtomic(serviceStartsPath(home), d); }
+/** Wait before the n-th crash restart within the window (1-based): 0, 0, 1, 2, 4 minutes. */
+export function crashBackoffMs(n) { return n <= 2 ? 0 : Math.min(15, 2 ** (n - 3)) * 60_000; }
+/** `service status --clear`: forget the crash history and lift the give-up. */
+export function clearAttention(home) {
+    const d = { ...readStarts(home), crashStarts: [], attention: null };
+    writeStarts(home, d);
+    return d;
+}
+/** True when the last run did not end cleanly (a heartbeat that is not `stopped`, with no live holder). */
+export function lastRunCrashed(hb) { return !!hb && hb.state !== 'stopped'; }
+/**
+ * What one scheduler tick does. Pure: the caller reads the files and carries the action out (startService,
+ * the kill, the notification, writeStarts).
+ */
+export function ensureDecision(i) {
+    if (i.holder) {
+        const age = i.heartbeat && i.heartbeat.pid === i.holder.pid ? i.now - i.heartbeat.heartbeatAt : i.now - i.holder.startedAt;
+        if (age <= SERVICE_STALE_MS)
+            return { action: 'noop', why: `running (pid ${i.holder.pid}, heartbeat ${Math.round(age / 1000)} s old)` };
+        if (age >= SERVICE_HUNG_MS)
+            return { action: 'kill-hung', pid: i.holder.pid, why: `pid ${i.holder.pid} is alive but its heartbeat is ${Math.round(age / 1000)} s old (hung)` };
+        return { action: 'noop', why: `pid ${i.holder.pid} is alive; heartbeat ${Math.round(age / 1000)} s old (starting or busy)` };
+    }
+    if (i.stop)
+        return { action: 'noop', why: `stopped (${i.stop.reason}); \`dexterm autotrade service start\` starts it again` };
+    if (i.starts.attention)
+        return { action: 'give-up', why: i.starts.attention.why, notify: !i.starts.attention.notified };
+    if (i.panic)
+        return { action: 'noop', why: `the panic switch is engaged (${i.panic}); nothing starts until \`dexterm wallet resume\`` };
+    const crashed = lastRunCrashed(i.heartbeat);
+    if (!crashed)
+        return { action: 'start', crashed: false, why: i.heartbeat ? 'the service is not running' : 'first start', notifyDown: false };
+    const recent = i.starts.crashStarts.filter((t) => i.now - t < CRASH_WINDOW_MS);
+    if (recent.length >= MAX_CRASH_RESTARTS) {
+        return { action: 'give-up', why: `crash loop: ${recent.length + 1} crashes within an hour; the service stays down until \`dexterm autotrade service status --clear\``, notify: true };
+    }
+    const wait = crashBackoffMs(recent.length + 1);
+    const last = recent.length ? Math.max(...recent) : 0;
+    if (last && i.now - last < wait)
+        return { action: 'wait', why: `crash ${recent.length + 1} within the hour: backing off ${Math.round(wait / 60_000)} min`, untilMs: last + wait };
+    const notifyDown = !i.starts.downNotifiedAt || i.now - i.starts.downNotifiedAt >= CRASH_WINDOW_MS;
+    return { action: 'start', crashed: true, why: `the last run ended without a clean stop (pid ${i.heartbeat.pid}); restarting`, notifyDown };
+}
+/** Record what a decision did in starts.json (the caller does the process work). */
+export function applyEnsure(home, d, now) {
+    const s = readStarts(home);
+    s.crashStarts = s.crashStarts.filter((t) => now - t < CRASH_WINDOW_MS);
+    if (d.action === 'start') {
+        s.lastStartAt = now;
+        if (d.crashed)
+            s.crashStarts.push(now);
+        if (d.notifyDown)
+            s.downNotifiedAt = now;
+    }
+    else if (d.action === 'give-up') {
+        s.attention = { at: s.attention?.at ?? now, why: d.why, notified: true };
+    }
+    writeStarts(home, s);
+    return s;
+}
+export function writeServiceState(home, d) { mkdirs(home); writeJsonAtomic(serviceStatePath(home), d); }
+export function readServiceState(home) {
+    const d = readJson(serviceStatePath(home));
+    return d && typeof d.startedAt === 'number' ? { fleetId: typeof d.fleetId === 'string' ? d.fleetId : null, startedAt: d.startedAt, pid: Number(d.pid) || 0 } : null;
+}
+// ───────────────────────────── the bounded log ─────────────────────────────
+export const LOG_MAX_BYTES = 4 * 1024 * 1024;
+/**
+ * An append-only log capped at maxBytes: past the cap the file moves to `.1` (replacing the older one) and a new
+ * file starts, so the log never holds more than about 2 × maxBytes. Each line is stamped; write errors are swallowed
+ * (a full disk must never stop the exits).
+ */
+export class BoundedLog {
+    path;
+    max;
+    size;
+    constructor(path, maxBytes = LOG_MAX_BYTES) {
+        this.path = path;
+        this.max = maxBytes;
+        try {
+            mkdirSync(join(path, '..'), { recursive: true, mode: 0o700 });
+        }
+        catch { /* reported on write */ }
+        try {
+            this.size = statSync(path).size;
+        }
+        catch {
+            this.size = 0;
+        }
+        if (this.size >= this.max)
+            this.rotate();
+    }
+    rotate() {
+        try {
+            renameSync(this.path, `${this.path}.1`);
+        }
+        catch { /* nothing to move */ }
+        this.size = 0;
+    }
+    line(s, now = Date.now()) {
+        const text = `${new Date(now).toISOString()} ${s.replace(/\n+$/, '')}\n`;
+        const n = Buffer.byteLength(text);
+        if (this.size + n > this.max)
+            this.rotate();
+        try {
+            appendFileSync(this.path, text, { mode: 0o600 });
+            this.size += n;
+        }
+        catch { /* never the service's problem */ }
+    }
+    /** A stream-like face for code that writes chunks (the fleet's stdout / stderr). */
+    writer(prefix = '') {
+        let buf = '';
+        return {
+            write: (s) => {
+                buf += s;
+                let i;
+                while ((i = buf.indexOf('\n')) >= 0) {
+                    this.line(prefix + buf.slice(0, i));
+                    buf = buf.slice(i + 1);
+                }
+                if (buf.length > 8192) {
+                    this.line(prefix + buf);
+                    buf = '';
+                }
+                return true;
+            },
+        };
+    }
+}
+/** The last n lines of the service log (and the rotated one before it when short). */
+export function tailServiceLog(home, n = 50) {
+    const read = (p) => { try {
+        return readFileSync(p, 'utf8').split('\n').filter(Boolean);
+    }
+    catch {
+        return [];
+    } };
+    const cur = read(serviceLogPath(home));
+    if (cur.length >= n)
+        return cur.slice(-n);
+    return [...read(`${serviceLogPath(home)}.1`), ...cur].slice(-n);
+}

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

@@ -131,12 +131,10 @@ class ClaudeCliSession {
                     tools: iso.tools, mcpServers: iso.mcpServers, plugins: iso.plugins, agents: iso.agents, skills: iso.skills, slashCommands: iso.slashCommands,
                 };
                 this.o.onInit?.(init);
-                if (!this.o.account.expectApiKeySource.includes(init.apiKeySource)) {
-                    this.kill('account-mismatch');
-                    return;
-                }
-                if (init.tools !== 0 || init.mcpServers !== 0) {
-                    this.kill('not-tool-less');
+                const failed = !this.o.account.expectApiKeySource.includes(init.apiKeySource) ? 'account-mismatch' : init.tools !== 0 || init.mcpServers !== 0 ? 'not-tool-less' : null;
+                if (failed) {
+                    this.o.onProofFailed?.(failed);
+                    this.kill(failed);
                     return;
                 }
                 continue;
@@ -229,6 +227,8 @@ export class SessionGate {
     pausedUntil = 0;
     /** Set when a session proved the account or the tool list wrong: no new session until the runner restarts. */
     blocked = null;
+    /** The session whose own failure set `blocked` (null when the block came from elsewhere, e.g. a sibling strategy). */
+    blockedBy = null;
     constructor(caps, guard, opts = {}) {
         this.caps = caps;
         this.guard = guard;
@@ -312,7 +312,12 @@ export class SessionGate {
     /** Are new sessions paused by the allowance guard right now (wall clock)? */
     paused() { return this.clock() < this.pausedUntil; }
     /** A misconfigured account (or a CLI that reports tools) fails the same way every time: stop spawning for this run. */
-    block(reason) { this.blocked ??= reason; }
+    block(reason, sessionId) {
+        if (this.blocked !== null)
+            return;
+        this.blocked = reason;
+        this.blockedBy = sessionId ?? null;
+    }
 }
 const isRec = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 /** The MCP-shaped sections a replay can honestly fill from the tape row; everything else is named as unavailable. */
@@ -455,6 +460,7 @@ export function claudeSessionFactory(f) {
             catch (e) {
                 failed = 'account-unavailable';
                 f.log('session_account_error', { sessionId: id, error: e.message });
+                f.gate.block(failed, id);
                 return null;
             }
             if (closed)
@@ -467,6 +473,9 @@ export function claudeSessionFactory(f) {
                 onRateLimit: (r) => { f.gate.rateLimit(r); f.log('allowance', { sessionId: id, status: r.status, fiveHour: r.fiveHour, sevenDay: r.sevenDay, resetsAt: r.resetsAt }); },
                 onLate: (text) => f.log('late_reply_ignored', { sessionId: id, why: 'arrived after decideWithinSec', text: text.slice(0, 400) }),
                 onRaw: f.onRaw ? (line) => f.onRaw(id, line) : undefined,
+                // The gate closes at the failed proof itself, not when the runner later reads this session's (null) reply: a
+                // candidate that closes first (its TTL) must not leave the gate open for more sessions on the wrong account.
+                onProofFailed: (why) => f.gate.block(why, id),
             });
             return inner;
         })());

package/dist/packages/autotrade/src/signal-channels.js

@@ -0,0 +1,312 @@
+// dexterm autotrade — the trade-fire delivery channels and their config (task-1645, 0.2.0 card A).
+//
+// The user enables any of these, in ONE place: the `signals` block of $DEXTERM_HOME/connectors.json, next to the
+// Telegram setup (`dexterm autotrade signal channels …`, shown by `dexterm telegram status` too). No secret is in
+// the file: the webhook's HMAC secret lives in the OS keychain store, like the bot token.
+//
+//   webhook    POST the signal line to a loopback URL (http://127.0.0.1|localhost|[::1]) or a user https URL.
+//              Headers: x-dexterm-signature (HMAC, signal.ts), x-dexterm-nonce, idempotency-key. Redirects are an
+//              error. 2xx = ack, 409 = duplicate (ack), 408/425/429 and 5xx/network = retry, other 4xx = rejected.
+//   cmd        `--signal-cmd`: an argv (absolute program path, no shell, no PATH lookup); the signal line on stdin;
+//              a minimal environment (no dexterm secret, DEXTERM_SIGNAL_SIGNATURE when an HMAC secret is set).
+//              Exit 0 = ack, 2 = rejected, 3 = duplicate (ack), anything else or a 10 s timeout = retry.
+//   jsonl      append the line to a stream file (default autotrade/real/signals.jsonl, 0600); an executor tails it.
+//              task-1654: `signed` (opt-in, needs the HMAC secret) writes each line as an envelope instead,
+//              {"schema":"dexterm-trade-fire-envelope/1","signature":"t=…,v1=…","signal":"<the exact signal line>"},
+//              so a tailing executor can verify the HMAC like the webhook's.
+//   mcp        append to autotrade/real/mcp-feed.jsonl, which the MCP tool `trade_fire_feed` reads (status only).
+//   telegram   the human-visible copy to the paired chat (the bot cannot be the executor's input: a bot cannot read
+//              another bot's messages). Never sufficient on its own for real mode.
+import { spawn } from 'node:child_process';
+import { closeSync, fsyncSync, mkdirSync, openSync, writeSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { chooseSecretStore, secretStore, SIGNAL_HMAC_ITEM } from "./chat/secrets.js";
+import { loadConnectors, saveConnectors, CONNECTORS_SCHEMA, defaultTelegram } from "./chat/config.js";
+import { inert, shortMint, usdShort } from "./chat/format.js";
+import { realDir } from "./outbox.js";
+import { clampTtl, signBody, SIGNAL_TTL_DEFAULT_SEC } from "./signal.js";
+export const defaultSignalsConfig = () => ({
+    webhook: { enabled: false, url: null, secretStore: null }, cmd: { enabled: false, argv: [] }, jsonl: { enabled: false, path: null, signed: false },
+    mcp: { enabled: false }, telegram: { enabled: true }, ttlSec: SIGNAL_TTL_DEFAULT_SEC, executor: { listenPort: null },
+});
+export const streamPathDefault = (home) => join(realDir(home), 'signals.jsonl');
+export const mcpFeedPath = (home) => join(realDir(home), 'mcp-feed.jsonl');
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]', '::1']);
+/** null when the URL may receive signals: loopback http(s), or https anywhere. No credentials in the URL. */
+export function webhookUrlProblem(u) {
+    let url;
+    try {
+        url = new URL(u);
+    }
+    catch {
+        return 'not a URL';
+    }
+    if (url.username || url.password)
+        return 'credentials in a URL are refused (the HMAC secret lives in the keychain)';
+    if (url.protocol === 'https:')
+        return null;
+    if (url.protocol === 'http:' && LOOPBACK.has(url.hostname))
+        return null;
+    return 'use https://, or http:// to 127.0.0.1 / localhost / [::1] only';
+}
+export function argvProblem(argv) {
+    if (!Array.isArray(argv) || argv.length < 1 || argv.length > 16)
+        return 'the command is an argv array of 1 to 16 strings';
+    if (!argv.every((a) => typeof a === 'string' && a.length > 0 && a.length <= 512 && !a.includes('\0')))
+        return 'every argv item is a non-empty string (512 chars max)';
+    if (!isAbsolute(argv[0]))
+        return 'the program is an absolute path (no shell, no PATH lookup)';
+    return null;
+}
+/** Read the `signals` block; anything invalid is turned off (fail closed), with the reasons. */
+export function parseSignalsConfig(raw) {
+    const c = defaultSignalsConfig();
+    const problems = [];
+    const r = (raw && typeof raw === 'object' ? raw : {});
+    const w = (r.webhook ?? {});
+    if (typeof w.url === 'string') {
+        const p = webhookUrlProblem(w.url);
+        if (p)
+            problems.push(`webhook: ${p}`);
+        else
+            c.webhook.url = w.url;
+    }
+    c.webhook.enabled = w.enabled === true && c.webhook.url !== null;
+    c.webhook.secretStore = w.secretStore === 'keychain' || w.secretStore === 'libsecret' || w.secretStore === 'file' ? w.secretStore : null;
+    const m = (r.cmd ?? {});
+    if (m.argv !== undefined) {
+        const p = argvProblem(m.argv);
+        if (p)
+            problems.push(`cmd: ${p}`);
+        else
+            c.cmd.argv = [...m.argv];
+    }
+    c.cmd.enabled = m.enabled === true && c.cmd.argv.length > 0;
+    const j = (r.jsonl ?? {});
+    if (typeof j.path === 'string') {
+        if (isAbsolute(j.path))
+            c.jsonl.path = j.path;
+        else
+            problems.push('jsonl: the stream path must be absolute');
+    }
+    c.jsonl.enabled = j.enabled === true;
+    c.jsonl.signed = j.signed === true;
+    const ex = (r.executor ?? {});
+    if (ex.listenPort !== undefined && ex.listenPort !== null) {
+        const n = Number(ex.listenPort);
+        if (Number.isInteger(n) && n >= 1024 && n <= 65535)
+            c.executor.listenPort = n;
+        else
+            problems.push('executor: listenPort must be a whole number from 1024 to 65535');
+    }
+    c.mcp.enabled = (r.mcp ?? {}).enabled === true;
+    c.telegram.enabled = (r.telegram ?? {}).enabled !== false;
+    c.ttlSec = clampTtl(typeof r.ttlSec === 'number' ? r.ttlSec : SIGNAL_TTL_DEFAULT_SEC);
+    return { config: c, problems };
+}
+/** The `signals` block of connectors.json (a missing file or block = the defaults: only the Telegram copy). */
+export function loadSignalsConfig(home) {
+    const c = loadConnectors(home);
+    if (!c.ok)
+        return { config: { ...defaultSignalsConfig(), telegram: { enabled: false } }, problems: [c.error] };
+    return parseSignalsConfig(c.config.signals);
+}
+/** Write the `signals` block back, keeping the Telegram setup as it is. */
+export function saveSignalsConfig(home, sc) {
+    const c = loadConnectors(home);
+    if (!c.ok)
+        throw new Error(c.error);
+    saveConnectors(home, { ...(c.ok ? c.config : { schema: CONNECTORS_SCHEMA, telegram: defaultTelegram() }), signals: sc });
+}
+export function enabledChannels(c) {
+    return [c.webhook.enabled ? 'webhook' : null, c.cmd.enabled ? 'cmd' : null, c.jsonl.enabled ? 'jsonl' : null, c.mcp.enabled ? 'mcp' : null, c.telegram.enabled ? 'telegram' : null].filter((x) => !!x);
+}
+export class WebhookChannel {
+    name = 'webhook';
+    o;
+    constructor(o) {
+        const p = webhookUrlProblem(o.url);
+        if (p)
+            throw new Error(`webhook: ${p}`);
+        this.o = o;
+    }
+    async deliver(s, line) {
+        const headers = { 'content-type': 'application/json', 'x-dexterm-nonce': String(s.nonce), 'idempotency-key': s.id, 'user-agent': 'dexterm-trade-fire/1' };
+        const secret = this.o.secret();
+        if (secret)
+            headers['x-dexterm-signature'] = signBody(secret, line, (this.o.now ?? Date.now)());
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), this.o.timeoutMs ?? 5000);
+        try {
+            const f = this.o.fetch ?? globalThis.fetch;
+            const res = await f(this.o.url, { method: 'POST', headers, body: line, redirect: 'error', signal: ac.signal });
+            if (res.status >= 200 && res.status < 300)
+                return { ok: true };
+            if (res.status === 409)
+                return { ok: true, duplicate: true };
+            if (res.status === 408 || res.status === 425 || res.status === 429 || res.status >= 500)
+                return { ok: false, retry: true, why: `http ${res.status}` };
+            return { ok: false, retry: false, why: `http ${res.status}` };
+        }
+        catch (e) {
+            return { ok: false, retry: true, why: ac.signal.aborted ? 'timeout' : e.message.slice(0, 120) };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+// ───────────────────────────── command hook ─────────────────────────────
+export class CommandChannel {
+    name = 'cmd';
+    o;
+    constructor(o) {
+        const p = argvProblem(o.argv);
+        if (p)
+            throw new Error(`signal-cmd: ${p}`);
+        this.o = o;
+    }
+    deliver(s, line) {
+        const secret = this.o.secret?.() ?? null;
+        // A minimal environment: no token, no RPC URL, no DEXTERM_* setting leaks into the user's executor.
+        const env = { PATH: process.env.PATH ?? '/usr/bin:/bin', LANG: process.env.LANG ?? 'C.UTF-8', DEXTERM_SIGNAL_NONCE: String(s.nonce), DEXTERM_SIGNAL_ID: s.id };
+        if (process.env.HOME)
+            env.HOME = process.env.HOME;
+        if (process.env.SystemRoot)
+            env.SystemRoot = process.env.SystemRoot;
+        if (secret)
+            env.DEXTERM_SIGNAL_SIGNATURE = signBody(secret, line, (this.o.now ?? Date.now)());
+        return new Promise((done) => {
+            let settled = false;
+            const finish = (r) => { if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                done(r);
+            } };
+            let child;
+            try {
+                child = spawn(this.o.argv[0], this.o.argv.slice(1), { shell: false, env, stdio: ['pipe', 'ignore', 'ignore'], windowsHide: true });
+            }
+            catch (e) {
+                done({ ok: false, retry: true, why: `spawn: ${e.message.slice(0, 100)}` });
+                return;
+            }
+            const timer = setTimeout(() => { child.kill('SIGKILL'); finish({ ok: false, retry: true, why: 'timeout' }); }, this.o.timeoutMs ?? 10_000);
+            child.on('error', (e) => finish({ ok: false, retry: true, why: `spawn: ${e.message.slice(0, 100)}` }));
+            child.on('close', (code) => finish(code === 0 ? { ok: true } : code === 3 ? { ok: true, duplicate: true } : code === 2 ? { ok: false, retry: false, why: 'rejected (exit 2)' } : { ok: false, retry: true, why: `exit ${code}` }));
+            child.stdin.on('error', () => { });
+            child.stdin.end(`${line}\n`);
+        });
+    }
+}
+// ───────────────────────────── JSONL stream / MCP feed ─────────────────────────────
+export const ENVELOPE_SCHEMA = 'dexterm-trade-fire-envelope/1';
+export class JsonlChannel {
+    name;
+    path;
+    signer;
+    /** task-1654: `signed` = HMAC envelope lines (a secret must be set, else the line is retried until one is). */
+    constructor(path, name = 'jsonl', signed) { this.path = path; this.name = name; this.signer = signed ? { secret: signed.secret, now: signed.now ?? Date.now } : null; }
+    async deliver(_s, line) {
+        let out = line;
+        if (this.signer) {
+            const secret = this.signer.secret();
+            if (!secret)
+                return { ok: false, retry: true, why: 'signed stream: no HMAC secret set (dexterm autotrade signal secret generate --out FILE)' };
+            out = JSON.stringify({ schema: ENVELOPE_SCHEMA, signature: signBody(secret, line, this.signer.now()), signal: line });
+        }
+        try {
+            mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+            const fd = openSync(this.path, 'a', 0o600);
+            try {
+                writeSync(fd, `${out}\n`);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return { ok: true };
+        }
+        catch (e) {
+            return { ok: false, retry: true, why: e.code ?? e.message.slice(0, 80) };
+        }
+    }
+}
+// ───────────────────────────── Telegram copy ─────────────────────────────
+/** The human-visible copy (plain text lines, the LIVE badge). The symbol is already sanitized; it still goes through inert(). */
+export function telegramLines(s, now = Date.now()) {
+    const left = Math.max(0, Math.round((s.expiresAt - now) / 1000));
+    const strat = `${inert(s.strategy.id, 32)} v${inert(s.strategy.version, 12)}`;
+    if (s.type === 'halted') {
+        // task-1679 (0.2.0 decision): open positions at the end of a real run must be impossible to miss.
+        const open = s.open ?? [];
+        return [
+            `LIVE TRADE FIRE · HALTED · ${inert(s.reason, 40)}`,
+            `${s.outstanding.length} outstanding signal(s) · run ${inert(s.runId.slice(-12), 16)} · account ${inert(s.accountId, 32)} · nonce ${s.nonce}`,
+            ...(open.length ? [`${open.length} position(s): ${open.slice(0, 10).map(shortMint).join(', ')}${open.length > 10 ? ` +${open.length - 10} more` : ''}`, 'these positions are still open: manage them in your executor', 'until the next real run of this strategy, dexterm sends NO signal for them, sells included'] : []),
+            'no more signals from this run',
+        ];
+    }
+    if (s.type === 'test')
+        return ['LIVE TRADE FIRE · TEST', `nonce ${s.nonce} · account ${inert(s.accountId, 32)} · never trade on this`];
+    const size = s.side === 'buy' ? `${s.sizeSol} SOL (${usdShort(s.sizeUsd)}, ${s.pctOfBook}% of book)` : `${Math.round((s.sellFraction ?? 1) * 1000) / 10}% of the position (~${s.sizeSol} SOL)`;
+    return [
+        `LIVE TRADE FIRE · ${s.side.toUpperCase()} "${inert(s.symbol, 16)}" ${shortMint(s.mint)}`,
+        `${size}${s.exitReason ? ` · ${inert(s.exitReason, 40)}` : ''}`,
+        `${strat} · account ${inert(s.accountId, 32)} · nonce ${s.nonce} · ignore after ${left} s`,
+        'your executor acts on it, not this chat',
+    ];
+}
+export class TelegramCopyChannel {
+    name = 'telegram';
+    send;
+    now;
+    constructor(send, now = Date.now) { this.send = send; this.now = now; }
+    async deliver(s) {
+        try {
+            await this.send(telegramLines(s, this.now()));
+            return { ok: true };
+        }
+        catch (e) {
+            return { ok: false, retry: true, why: e.message.slice(0, 120) };
+        }
+    }
+}
+// ───────────────────────────── from the config ─────────────────────────────
+/** Where the webhook's HMAC secret is (the store setup recorded, else the best on this machine). */
+export function hmacStore(home, sc, env = process.env) {
+    return sc.webhook.secretStore ? secretStore(sc.webhook.secretStore, home, SIGNAL_HMAC_ITEM) : chooseSecretStore(home, env, process.platform, SIGNAL_HMAC_ITEM);
+}
+/**
+ * The channel objects for a config. Without a Telegram sender (outside a run) the copy is deferred: it stays pending
+ * in the outbox for the next run instead of being dropped. The secret is read once, on first use.
+ */
+export function channelsFromConfig(home, sc, o = {}) {
+    let cached;
+    const store = o.secret ?? hmacStore(home, sc, o.env);
+    const secret = () => { if (cached === undefined) {
+        try {
+            cached = store.get();
+        }
+        catch {
+            cached = null;
+        }
+    } return cached; };
+    const out = [];
+    const defer = [];
+    if (sc.webhook.enabled && sc.webhook.url)
+        out.push(new WebhookChannel({ url: sc.webhook.url, secret, fetch: o.fetch, now: o.now }));
+    if (sc.cmd.enabled && sc.cmd.argv.length)
+        out.push(new CommandChannel({ argv: sc.cmd.argv, secret, now: o.now }));
+    if (sc.jsonl.enabled)
+        out.push(new JsonlChannel(sc.jsonl.path ?? streamPathDefault(home), 'jsonl', sc.jsonl.signed ? { secret, now: o.now } : undefined));
+    if (sc.mcp.enabled)
+        out.push(new JsonlChannel(mcpFeedPath(home), 'mcp'));
+    if (sc.telegram.enabled) {
+        if (o.telegram)
+            out.push(new TelegramCopyChannel(o.telegram, o.now));
+        else
+            defer.push('telegram');
+    }
+    return { channels: out, defer };
+}