dexterm-cli 0.1.1 → 0.1.2

package/dist/packages/cli/src/update.js

@@ -0,0 +1,294 @@
+// task-1397 — `dexterm update` and the quiet startup notice.
+//
+// The check is two anonymous GETs: the npm registry's `latest` for dexterm-cli and GitHub's latest published
+// release of dexterm-xyz/dexterm. Both carry only fixed headers (no version, no OS, no ids, no cookies); nothing
+// about the user or the machine is sent beyond the IP any request has. No telemetry.
+//
+// Startup: a live interactive run reads ~/.dexterm/update-check.json (no network) and shows one toast when a
+// newer version was seen; at most once a day it refreshes that file in the background (never blocks, never in
+// --fixtures/--replay, never with DEXTERM_OFFLINE/CI). Off switches: `dexterm update --off`,
+// DEXTERM_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER=1. `dexterm update` itself never upgrades anything: it prints
+// the exact command for how this copy was installed (npm, Homebrew, release tarball, git checkout).
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dextermHome } from "./boot-state.js";
+import { VERSION } from "./version.js";
+export const NPM_PACKAGE = 'dexterm-cli';
+export const GITHUB_REPO = 'dexterm-xyz/dexterm';
+export const NPM_LATEST_URL = `https://registry.npmjs.org/${NPM_PACKAGE}/latest`;
+export const GITHUB_LATEST_URL = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+export const RELEASES_URL = `https://github.com/${GITHUB_REPO}/releases`;
+/** Fixed request headers: the same bytes for every user (GitHub's API requires a user-agent). */
+export const REQUEST_HEADERS = Object.freeze({ accept: 'application/json', 'user-agent': 'dexterm' });
+export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+export const REQUEST_TIMEOUT_MS = 4000;
+export const UPDATE_FILE = 'update-check.json';
+export const UPDATE_USAGE = `usage: dexterm update          check npm + GitHub now and print the upgrade command for this install
+       dexterm update --off    turn the once-a-day startup check off (dexterm update still works)
+       dexterm update --on     turn it back on`;
+/** `1.2.3`, `v1.2.3`, `1.2.3-rc.1` → parts; anything else → null (never guessed). */
+export function parseVersion(s) {
+    if (typeof s !== 'string')
+        return null;
+    const m = /^v?(\d{1,6})\.(\d{1,6})\.(\d{1,6})(?:-([0-9A-Za-z.-]{1,64}))?(?:\+[0-9A-Za-z.-]{1,64})?$/.exec(s.trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre: m[4] ? m[4].split('.') : [] };
+}
+/** Semver precedence: < 0 when a is older than b. Unparseable versions compare equal (no notice on junk). */
+export function compareVersions(a, b) {
+    const x = parseVersion(a), y = parseVersion(b);
+    if (!x || !y)
+        return 0;
+    for (const k of ['major', 'minor', 'patch'])
+        if (x[k] !== y[k])
+            return x[k] - y[k];
+    if (!x.pre.length || !y.pre.length)
+        return y.pre.length - x.pre.length; // a release outranks its prereleases
+    for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+        const p = x.pre[i], q = y.pre[i];
+        if (p === undefined)
+            return -1;
+        if (q === undefined)
+            return 1;
+        const pn = /^\d+$/.test(p), qn = /^\d+$/.test(q);
+        if (pn && qn) {
+            if (Number(p) !== Number(q))
+                return Number(p) - Number(q);
+        }
+        else if (pn !== qn)
+            return pn ? -1 : 1;
+        else if (p !== q)
+            return p < q ? -1 : 1;
+    }
+    return 0;
+}
+const bare = (v) => v.trim().replace(/^v/, '');
+/** This module's real path (symlinks resolved): …/node_modules/dexterm-cli/dist/…, …/Cellar/dexterm/…, or a source tree. */
+export function selfPath() {
+    const p = fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** The source tree's root for a tarball/checkout install (this file is packages/cli/src/update.ts). */
+export function sourceRoot(path = selfPath()) {
+    return resolve(dirname(path), '..', '..', '..');
+}
+export function detectInstall(path = selfPath(), exists = existsSync) {
+    const p = path.replace(/\\/g, '/');
+    if (p.includes(`/node_modules/${NPM_PACKAGE}/`))
+        return 'npm';
+    if (/\/Cellar\/dexterm\/|\/opt\/homebrew\/|\/home\/linuxbrew\/\.linuxbrew\//.test(p))
+        return 'brew';
+    return exists(join(sourceRoot(path), '.git')) ? 'checkout' : 'tarball';
+}
+export const INSTALL_LABEL = {
+    npm: `npm (${NPM_PACKAGE})`, brew: 'Homebrew (dexterm-xyz/dexterm tap)', tarball: 'release tarball (install.sh)', checkout: 'git checkout',
+};
+/** The exact commands that move this install to `latest`. Nothing here is ever run by dexterm. */
+export function upgradeCommands(kind, latest, opts = {}) {
+    const v = bare(latest);
+    if (kind === 'npm')
+        return [`npm i -g ${NPM_PACKAGE}@${v}`];
+    if (kind === 'brew')
+        return ['brew update', 'brew upgrade dexterm'];
+    if (kind === 'checkout')
+        return [`git -C ${shellQuote(opts.root ?? sourceRoot())} pull --ff-only`];
+    const base = `${RELEASES_URL}/download/v${v}`;
+    const file = `dexterm-${v}-src.tar.gz`;
+    const sum = (opts.platform ?? process.platform) === 'darwin' ? 'shasum -a 256 -c' : 'sha256sum -c';
+    return [
+        `curl -fL -O ${base}/${file} -O ${base}/SHA256SUMS`,
+        `grep ' ${file}$' SHA256SUMS | ${sum}`,
+        `tar -xzf ${file} && cd dexterm-${v} && ./install.sh`,
+    ];
+}
+function shellQuote(s) {
+    return /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+async function getJson(fetchFn, url, timeoutMs, cancel) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const res = await fetchFn(url, { headers: { ...REQUEST_HEADERS }, signal: cancel ? AbortSignal.any([cancel, timeout]) : timeout, redirect: 'follow' });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return res.json();
+}
+function why(e) {
+    const err = e;
+    if (err?.name === 'TimeoutError' || err?.name === 'AbortError')
+        return 'timed out';
+    return String(err?.message ?? e).slice(0, 120);
+}
+/** Ask both sources. Never throws; each side reports its own error. */
+export async function fetchLatest(fetchFn = fetch, timeoutMs = REQUEST_TIMEOUT_MS, cancel) {
+    const npm = getJson(fetchFn, NPM_LATEST_URL, timeoutMs, cancel).then((b) => {
+        const v = b?.version;
+        return parseVersion(v) ? { ok: true, version: bare(v), url: `https://www.npmjs.com/package/${NPM_PACKAGE}` } : { ok: false, error: 'no version in the registry reply' };
+    }, (e) => ({ ok: false, error: why(e) }));
+    const github = getJson(fetchFn, GITHUB_LATEST_URL, timeoutMs, cancel).then((b) => {
+        const r = b;
+        if (r?.draft || r?.prerelease || !parseVersion(r?.tag_name))
+            return { ok: false, error: 'no published release in the reply' };
+        const tag = r.tag_name;
+        return { ok: true, version: bare(tag), url: `${RELEASES_URL}/tag/${tag}` };
+    }, (e) => ({ ok: false, error: why(e) }));
+    return { npm: await npm, github: await github };
+}
+/** The newest stable version either source reported, or null. */
+export function newestOf(r) {
+    let best = null;
+    for (const s of [r.npm, r.github]) {
+        if (!s.ok || parseVersion(s.version)?.pre.length)
+            continue;
+        if (best === null || compareVersions(s.version, best) > 0)
+            best = s.version;
+    }
+    return best;
+}
+/** The version this install's channel can actually move to: npm → the registry; the rest → the GitHub release. */
+export function targetFor(kind, r) {
+    const primary = kind === 'npm' ? r.npm : r.github;
+    return primary.ok ? primary.version : newestOf(r);
+}
+export function updateStatePath(env) {
+    return join(dextermHome(env), UPDATE_FILE);
+}
+export function readUpdateState(env) {
+    try {
+        const j = JSON.parse(readFileSync(updateStatePath(env), 'utf8'));
+        return {
+            enabled: j.enabled !== false,
+            checkedAt: typeof j.checkedAt === 'number' && Number.isFinite(j.checkedAt) ? j.checkedAt : null,
+            latest: typeof j.latest === 'string' && parseVersion(j.latest) ? bare(j.latest) : null,
+        };
+    }
+    catch {
+        return { enabled: true, checkedAt: null, latest: null };
+    }
+}
+export function writeUpdateState(env, s) {
+    const p = updateStatePath(env);
+    mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+    const tmp = `${p}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(s, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, p);
+}
+const truthy = (v) => !!v && v !== '0' && v.toLowerCase() !== 'false';
+/** Why the startup check is off, or null when it may run. `dexterm update` itself ignores all but DEXTERM_OFFLINE. */
+export function startupCheckOff(env, s) {
+    if (truthy(env.DEXTERM_NO_UPDATE_CHECK))
+        return 'DEXTERM_NO_UPDATE_CHECK is set';
+    if (truthy(env.NO_UPDATE_NOTIFIER))
+        return 'NO_UPDATE_NOTIFIER is set';
+    if (truthy(env.DEXTERM_OFFLINE))
+        return 'DEXTERM_OFFLINE is set';
+    if (truthy(env.CI))
+        return 'CI is set';
+    if (!s.enabled)
+        return 'turned off with dexterm update --off';
+    return null;
+}
+/** The one-line notice for a cached result, or null. */
+export function noticeFor(current, latest) {
+    if (!latest || parseVersion(latest)?.pre.length || compareVersions(latest, current) <= 0)
+        return null;
+    return `dexterm ${bare(latest)} is available (you have ${bare(current)}) · run dexterm update`;
+}
+/**
+ * Startup: the cached notice now, plus a background refresh when the last check is older than a day.
+ * The caller decides where the notice goes (the interactive loop shows it as a toast after the boot).
+ */
+export function startupCheck(env, opts = {}) {
+    const s = readUpdateState(env);
+    const none = () => { };
+    if (startupCheckOff(env, s))
+        return { notice: null, refresh: null, cancel: none };
+    const current = opts.current ?? VERSION;
+    const now = opts.now ?? Date.now();
+    const notice = noticeFor(current, s.latest);
+    if (s.checkedAt !== null && now - s.checkedAt >= 0 && now - s.checkedAt < CHECK_EVERY_MS)
+        return { notice, refresh: null, cancel: none };
+    const ctl = new AbortController();
+    const refresh = fetchLatest(opts.fetchFn, REQUEST_TIMEOUT_MS, ctl.signal).then((r) => {
+        if (ctl.signal.aborted || (!r.npm.ok && !r.github.ok))
+            return null; // quit / offline / blocked: try again next launch
+        const latest = newestOf(r);
+        try {
+            writeUpdateState(env, { ...s, checkedAt: now, latest });
+        }
+        catch { /* read-only home: no cache */ }
+        // only a notice the cache did not already produce
+        const n = noticeFor(current, latest);
+        return n && n !== notice ? n : null;
+    }).catch(() => null);
+    return { notice, refresh, cancel: () => ctl.abort() };
+}
+export async function updateCommand(argv, io, deps = {}) {
+    const [arg, ...rest] = argv;
+    const env = io.env;
+    if (arg === '-h' || arg === '--help' || arg === 'help') {
+        io.stdout.write(UPDATE_USAGE + '\n');
+        return 0;
+    }
+    if (rest.length || (arg !== undefined && arg !== '--off' && arg !== '--on')) {
+        io.stderr.write(`dexterm update: unknown argument ${JSON.stringify(String(rest[0] ?? arg).slice(0, 20))}\n${UPDATE_USAGE}\n`);
+        return 2;
+    }
+    const state = readUpdateState(env);
+    if (arg === '--off' || arg === '--on') {
+        try {
+            writeUpdateState(env, { ...state, enabled: arg === '--on' });
+        }
+        catch (e) {
+            io.stderr.write(`dexterm update: ${e.message}\n`);
+            return 1;
+        }
+        io.stdout.write(arg === '--off'
+            ? `startup update check: off (saved to ${updateStatePath(env)}). dexterm update still checks when you run it.\n`
+            : `startup update check: on (at most once a day; saved to ${updateStatePath(env)})\n`);
+        return 0;
+    }
+    if (truthy(env.DEXTERM_OFFLINE)) {
+        io.stderr.write('dexterm update: DEXTERM_OFFLINE is set; the check needs the network\n');
+        return 2;
+    }
+    const current = deps.current ?? VERSION;
+    const kind = deps.install ?? detectInstall();
+    const r = await fetchLatest(deps.fetchFn);
+    const line = (label, s) => `  ${label.padEnd(20)} ${s.ok ? `${s.version.padEnd(10)} ${s.url}` : `unavailable (${s.error})`}\n`;
+    io.stdout.write(`dexterm ${current} · installed via ${INSTALL_LABEL[kind]}\n`);
+    io.stdout.write(line(`npm ${NPM_PACKAGE}`, r.npm));
+    io.stdout.write(line('GitHub release', r.github));
+    if (!r.npm.ok && !r.github.ok) {
+        io.stderr.write(`dexterm update: could not reach npm or GitHub; check your connection, or see ${RELEASES_URL}\n`);
+        return 1;
+    }
+    const latest = newestOf(r);
+    try {
+        writeUpdateState(env, { ...state, checkedAt: deps.now ?? Date.now(), latest });
+    }
+    catch { /* read-only home */ }
+    const target = targetFor(kind, r);
+    if (!target || compareVersions(target, current) <= 0) {
+        const ahead = latest && compareVersions(latest, current) > 0;
+        io.stdout.write(ahead
+            ? `You are on the newest version ${kind === 'npm' ? 'npm has' : 'the GitHub release has'} (${current}); ${latest} is out on the other channel and reaches yours shortly.\n`
+            : `You are up to date (${current}).\n`);
+    }
+    else {
+        io.stdout.write(`\ndexterm ${target} is available. Upgrade with:\n\n`);
+        for (const c of upgradeCommands(kind, target, { platform: deps.platform, root: deps.root }))
+            io.stdout.write(`  ${c}\n`);
+        io.stdout.write('\n');
+        if (kind === 'tarball')
+            io.stdout.write(`Verify the download first: ${RELEASES_URL}/tag/v${target} (docs/verify-your-download.md). Release notes: CHANGELOG.md.\n`);
+    }
+    const off = startupCheckOff(env, readUpdateState(env));
+    io.stdout.write(`startup check: ${off ? `off (${off})` : 'on, at most once a day; dexterm update --off or DEXTERM_NO_UPDATE_CHECK=1 turns it off'}. No telemetry: two anonymous GETs (registry.npmjs.org, api.github.com).\n`);
+    return 0;
+}

package/dist/packages/cli/src/version.js

@@ -0,0 +1,3 @@
+// The one place the app's version lives (task-1397). --version, the help banner and `dexterm update` read it;
+// cli.test.ts keeps it equal to packages/cli/package.json (release.yml refuses a tag that differs).
+export const VERSION = '0.1.2';

package/dist/packages/cli/src/voice-cmd.js

@@ -0,0 +1,119 @@
+// `dexterm voice …` (task-1408): inspect the voice engines on this machine and download the two
+// optional voice models — whisper.cpp base.en (speech-in) and the Piper en_GB-alan-medium voice
+// (neural speech-out). Downloads are OFF by default: this is the ONLY place dexterm fetches a model,
+// it asks before it does, and it verifies the download against a pinned checksum from the official
+// source. Nothing here runs the signer, touches keys, or changes trading behaviour.
+//
+// No new dependencies: the confirm prompt is node:readline, the download uses global fetch, and the
+// checksum/stream logic lives in @dexterm/voice (unit-tested with an injected fetch).
+import { createInterface } from 'node:readline';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { modelRegistry, downloadModel, modelStatus, resolvePiperBin, pickPlayer, PIPER_MODEL, DEFAULT_PIPER_VOICE } from '../../voice/src/index.js';
+import { dextermHome } from '../../custom/src/index.js';
+export const VOICE_USAGE = [
+    'usage:',
+    '  dexterm voice [status]                 show the voice engines + which models are installed',
+    '  dexterm voice download <model> [--yes] download a voice model (asks first; checksum-verified)',
+    '',
+    '  models: whisper        whisper.cpp base.en  (speech-to-text, off macOS this is the default)',
+    '          piper-voice    Piper en_GB-alan-medium (neural speech-out, preferred over espeak-ng)',
+    '          all            both of the above',
+].join('\n');
+function onPath(bin, env) {
+    const sep = process.platform === 'win32' ? ';' : ':';
+    for (const p of (env.PATH ?? '').split(sep)) {
+        if (p && existsSync(join(p, bin)))
+            return true;
+    }
+    return false;
+}
+/** y/N prompt on a TTY. Without a TTY (piped/CI) it returns false — the caller tells the user to pass --yes. */
+function askYesNo(io, question) {
+    if (!io.stdin.isTTY)
+        return Promise.resolve(false);
+    const rl = createInterface({ input: io.stdin, output: io.stdout });
+    return new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (ans) => { rl.close(); resolve(/^y(es)?$/i.test(ans.trim())); });
+    });
+}
+async function printStatus(io) {
+    const home = dextermHome(io.env);
+    const reg = modelRegistry(home);
+    const lines = ['dexterm voice', ''];
+    if (process.platform === 'darwin') {
+        lines.push('  speech-out  macOS `say` (built-in) · see `dexterm doctor` for the resolved voice');
+        lines.push('  speech-in   Apple Speech (swiftc) preferred, else whisper.cpp');
+    }
+    else {
+        const piperBin = resolvePiperBin();
+        const player = pickPlayer();
+        const piperReady = piperBin !== null && existsSync(PIPER_MODEL) && player !== null;
+        lines.push(`  speech-out  Piper ${piperReady ? `ready (${DEFAULT_PIPER_VOICE}, plays via ${player})` : 'not ready'}${piperReady ? '' : ` · espeak-ng ${onPath('espeak-ng', io.env) || onPath('espeak', io.env) ? 'ready (baseline)' : 'not installed'}`}`);
+        lines.push(`  speech-in   whisper.cpp (default off macOS) · mic tool ${['arecord', 'sox', 'rec', 'ffmpeg'].find((b) => onPath(b, io.env)) ?? 'none found'}`);
+    }
+    lines.push('', '  models:');
+    for (const spec of Object.values(reg)) {
+        const st = await modelStatus(spec);
+        lines.push(`    ${st.installed ? '✓' : '·'} ${spec.id.padEnd(12)} ${spec.label}${st.installed ? ' (installed)' : ''}`);
+    }
+    lines.push('', `  download a model: dexterm voice download <whisper|piper-voice|all>`);
+    io.stdout.write(lines.join('\n') + '\n');
+    return 0;
+}
+async function runDownload(io, which, yes) {
+    const home = dextermHome(io.env);
+    const reg = modelRegistry(home);
+    const ids = which === 'all' ? Object.keys(reg) : [which];
+    const specs = [];
+    for (const id of ids) {
+        const spec = reg[id];
+        if (!spec) {
+            io.stderr.write(`dexterm voice: unknown model ${JSON.stringify(id)}\n${VOICE_USAGE}\n`);
+            return 2;
+        }
+        specs.push(spec);
+    }
+    if (!yes && !io.stdin.isTTY) {
+        io.stderr.write('dexterm voice download: no interactive terminal to confirm; re-run with --yes to approve the download.\n');
+        return 2;
+    }
+    let anyFailed = false;
+    for (const spec of specs) {
+        try {
+            const res = await downloadModel(spec, {
+                confirm: (prompt) => (yes ? Promise.resolve(true) : askYesNo(io, `\n${prompt}`)),
+                log: (s) => io.stdout.write(s + '\n'),
+            });
+            if (res.status === 'cancelled')
+                return 1; // the user said no — stop here
+        }
+        catch (e) {
+            io.stderr.write(`dexterm voice download ${spec.id}: ${e.message}\n`);
+            anyFailed = true;
+        }
+    }
+    return anyFailed ? 1 : 0;
+}
+/** `dexterm voice …`. Returns the process exit code. */
+export async function voiceCommand(argv, io) {
+    const yes = argv.includes('--yes') || argv.includes('-y');
+    const rest = argv.filter((a) => a !== '--yes' && a !== '-y');
+    const sub = rest[0];
+    if (sub === undefined || sub === 'status')
+        return printStatus(io);
+    if (sub === 'download') {
+        const which = rest[1];
+        if (!which) {
+            io.stderr.write(`dexterm voice download: name a model.\n${VOICE_USAGE}\n`);
+            return 2;
+        }
+        return runDownload(io, which, yes);
+    }
+    if (sub === '--help' || sub === '-h' || sub === 'help') {
+        io.stdout.write(VOICE_USAGE + '\n');
+        return 0;
+    }
+    io.stderr.write(`dexterm voice: unknown subcommand ${JSON.stringify(sub)}\n${VOICE_USAGE}\n`);
+    return 2;
+}

package/dist/packages/cli/src/watch-cmd.js

@@ -0,0 +1,190 @@
+// dexterm — `dexterm watch` (task-1398): run the rules engine against the live feed with NO TUI and PUSH
+// every fired alert (and, when alerts.proposals is on, a one-line proposal summary) through the delivery
+// layer — so a price / holder / LARP / new-pair alert reaches you when the terminal is closed.
+//
+//   dexterm watch [--interval S] [--ticks N | --once] [--replay FILE] [--db PATH] [--verbose]
+//
+// SAFETY: this builds NO signer and passes no `trade` option; a rule can only alert / annotate / open an
+// inert PROPOSAL (RulesEngine's money-safety invariant). The notifier only reads an AlertDelivery. There is
+// no arm/sign/confirm/cap path anywhere under here (asserted by alerts-1398.test.ts).
+import { dextermHome, loadConfig, RulesEngine } from '../../custom/src/index.js';
+import { openHistoryReadOnly, LARP_PACK } from '../../recorder/src/index.js';
+import { buildNotifier } from "./alerts/notifier.js";
+import { alertToDelivery, proposalToDelivery } from "./alerts/format.js";
+import { redactCreds } from "./alerts/creds.js";
+import { larpGrade } from "./rules.js";
+export const WATCH_USAGE = `usage: dexterm watch [--interval S] [--ticks N | --once] [--replay FILE] [--db PATH] [--verbose]
+
+  Runs your rules headless and pushes alerts to the channels you enabled with \`dexterm alerts\`
+  (terminal line + desktop notification + your Telegram bot / Discord webhook). Ctrl-C to stop.
+`;
+function parseArgs(argv) {
+    const a = { intervalMs: 15_000, ticks: Infinity, replay: null, db: null, verbose: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        if (t === '--help' || t === '-h')
+            a.help = true;
+        else if (t === '--verbose' || t === '-v')
+            a.verbose = true;
+        else if (t === '--once')
+            a.ticks = 1;
+        else if (t === '--interval') {
+            const n = Number(argv[++i]);
+            if (!Number.isFinite(n) || n < 1)
+                return { error: '--interval needs seconds ≥ 1' };
+            a.intervalMs = Math.round(n * 1000);
+        }
+        else if (t === '--ticks') {
+            const n = Number(argv[++i]);
+            if (!Number.isInteger(n) || n < 1)
+                return { error: '--ticks needs an integer ≥ 1' };
+            a.ticks = n;
+        }
+        else if (t === '--replay') {
+            a.replay = argv[++i] ?? null;
+            if (!a.replay)
+                return { error: '--replay needs a FILE' };
+        }
+        else if (t === '--db') {
+            a.db = argv[++i] ?? null;
+            if (!a.db)
+                return { error: '--db needs a PATH' };
+        }
+        else
+            return { error: `unknown option "${t}"` };
+    }
+    return a;
+}
+/** Latest LARP verdict per mint from a read-only recorder DB (best effort; empty map on any problem). */
+function larpMapFromDb(path) {
+    const map = new Map();
+    if (!path || path === ':memory:')
+        return map;
+    const db = openHistoryReadOnly(path);
+    if (!db)
+        return map;
+    try {
+        const rows = db.prepare('SELECT mint, verdict FROM verdicts WHERE pack = ? AND verdict IS NOT NULL ORDER BY t').all(LARP_PACK);
+        for (const r of rows)
+            map.set(r.mint, r.verdict); // ORDER BY t → last write per mint wins
+    }
+    catch { /* table may not exist yet */ }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+    }
+    return map;
+}
+/** Map a screener row to a rule row (cluster is only known with the wallet-intel scan, absent headless; larp from the DB). */
+export function toRuleRow(r, larp) {
+    return Object.assign(Object.create(null), r, { cluster: null, larp: larpGrade(larp.get(r.mint)) });
+}
+/** The production source: refresh the live (or replay) feed, map rows, yield a snapshot. Replay yields once. */
+function createFeedSource(opts) {
+    let feed = null;
+    let yielded = 0;
+    const larp = larpMapFromDb(opts.db);
+    return {
+        async next() {
+            if (opts.stop.aborted)
+                return null;
+            const { createLiveFeed, createReplayFeed } = await import("./feed.js");
+            if (!feed)
+                feed = opts.replay ? createReplayFeed(opts.replay, {}) : createLiveFeed({ dbPath: opts.db ?? undefined });
+            else {
+                if (opts.replay)
+                    return null; // a recording is a single snapshot: one evaluate, then stop
+                await opts.stop.wait(opts.intervalMs);
+                if (opts.stop.aborted)
+                    return null;
+            }
+            const rows = await feed.refresh();
+            yielded++;
+            if (opts.verbose)
+                opts.io.stderr.write(`watch: tick ${yielded}, ${rows.length} rows\n`);
+            return { rows: rows.map((r) => toRuleRow(r, larp)), now: opts.now() };
+        },
+        close() { try {
+            feed?.close();
+        }
+        catch { /* ignore */ } },
+    };
+}
+export async function watchCommand(argv, io, deps = {}) {
+    const parsed = parseArgs(argv);
+    if ('error' in parsed) {
+        io.stderr.write(`dexterm watch: ${parsed.error}\n\n${WATCH_USAGE}`);
+        return 2;
+    }
+    if (parsed.help) {
+        io.stdout.write(WATCH_USAGE);
+        return 0;
+    }
+    const now = deps.now ?? (() => Date.now());
+    const home = dextermHome(io.env);
+    const loaded = loadConfig(home);
+    for (const e of loaded.errors)
+        io.stderr.write(`dexterm watch: config: ${e}\n`);
+    const rules = loaded.config.rules ?? [];
+    const engine = new RulesEngine({ rules, now: now() });
+    for (const e of engine.errors)
+        io.stderr.write(`dexterm watch: rule ${e.id}: ${e.msg}\n`);
+    const enabled = engine.rules.filter((r) => r.enabled).length;
+    if (enabled === 0)
+        io.stderr.write('dexterm watch: no enabled rules (add some with `dexterm rules add`); nothing will fire\n');
+    // SIGINT-aware sleeper for the production loop.
+    const stop = (() => {
+        let aborted = false;
+        let wake = () => { };
+        return {
+            get aborted() { return aborted; },
+            abort() { aborted = true; wake(); },
+            wake() { wake(); },
+            wait(ms) { return new Promise((res) => { const t = setTimeout(res, ms); wake = () => { clearTimeout(t); res(); }; }); },
+        };
+    })();
+    const notifier = deps.notifier ?? buildNotifier(home, loaded.config.alerts, {
+        toastSink: (line) => io.stdout.write(`${new Date(now()).toISOString().slice(11, 19)} ${line}\n`),
+    });
+    const source = deps.source ?? createFeedSource({ replay: parsed.replay, db: parsed.db, intervalMs: parsed.intervalMs, verbose: parsed.verbose, io, now, stop });
+    const ready = notifier.readyChannels();
+    if (parsed.verbose || !deps.notifier)
+        io.stderr.write(`dexterm watch: ${enabled} rule(s), channels: ${ready.length ? ready.join(', ') : 'toast'}\n`);
+    const onSigint = () => { io.stderr.write('\ndexterm watch: stopping…\n'); stop.abort(); };
+    const addSig = !deps.source; // only own SIGINT for the real loop (tests drive a finite source)
+    if (addSig)
+        process.on('SIGINT', onSigint);
+    let delivered = 0;
+    try {
+        for (let tick = 0; tick < parsed.ticks; tick++) {
+            const snap = await source.next();
+            if (!snap)
+                break;
+            engine.observe(snap.rows, snap.now);
+            const res = engine.evaluate(snap.rows, snap.now, { watchlist: snap.watchlist, positions: snap.positions });
+            for (const a of res.alerts) {
+                await notifier.deliver(alertToDelivery(a));
+                delivered++;
+            }
+            if (loaded.config.alerts?.proposals)
+                for (const p of res.proposals) {
+                    await notifier.deliver(proposalToDelivery(p));
+                    delivered++;
+                }
+        }
+    }
+    catch (e) {
+        io.stderr.write(`dexterm watch: ${redactCreds(e.message)}\n`);
+        return 1;
+    }
+    finally {
+        if (addSig)
+            process.removeListener('SIGINT', onSigint);
+        await source.close?.();
+    }
+    if (parsed.verbose || !deps.notifier)
+        io.stderr.write(`dexterm watch: delivered ${delivered} alert(s)\n`);
+    return 0;
+}

package/dist/packages/custom/src/rules.js

@@ -3,7 +3,7 @@ export const FIELDS = {
     vol5m: (r) => r.vol5m, vol1h: (r) => r.vol1h, vol24: (r) => r.vol24,
     holders: (r) => r.holders, org: (r) => r.org, top10: (r) => r.top10, dev: (r) => r.dev,
     lplocked: (r) => r.lpLocked, bundled: (r) => r.bundled, snipers: (r) => r.snipers,
-    cluster: (r) => r.cluster,
+    cluster: (r) => r.cluster, larp: (r) => r.larp,
     age: (r) => r.ageMin, m5: (r) => r.chg?.m5, h1: (r) => r.chg?.h1, h6: (r) => r.chg?.h6, h24: (r) => r.chg?.h24,
     buys: (r) => r.buys, sells: (r) => r.sells, bonding: (r) => r.bonding,
 };

package/dist/packages/custom/src/schema.js

@@ -199,6 +199,9 @@ export const SCHEMAS = {
             token: { type: 'object', additional: false, props: { tape: { type: 'boolean' }, social: { type: 'boolean' }, analyst: { type: 'boolean' } } },
         } },
     screenLayout: { oneOf: ['layoutNode', { type: 'object', additional: false, props: { wide: 'layoutNode', standard: 'layoutNode', compact: 'layoutNode' } }] },
+    /** task-1398: one alert-delivery channel. A `levels` filter (subset of up|down|info|warn); absent = every level. */
+    alertLevels: { type: 'array', max: 4, items: { type: 'string', enum: ['up', 'down', 'info', 'warn'] } },
+    alertChannel: { type: 'object', additional: false, props: { enabled: { type: 'boolean' }, levels: 'alertLevels' } },
     ruleJson: { type: 'object', additional: false, required: ['id', 'when', 'then'], props: {
             id: { type: 'string', pattern: NAME },
             name: { type: 'string', max: 80 },
@@ -258,6 +261,26 @@ export const SCHEMAS = {
                     /** Reserved: the trading gate is NOT here (signer policy owns it); listed so a proposal that tries gets a precise refusal. */
                     gate: { type: 'string', enum: ['keypress'] },
                 } },
+            /** task-1393: voice-out preferences. `/voice` is user-only (DENIED_FOR_MODELS), so only the keyboard sets it. */
+            voice: { type: 'object', additional: false, props: {
+                    name: { type: 'string', max: 64 },
+                    rate: { type: 'number', int: true, min: 80, max: 400 },
+                    pitch: { type: 'number', int: true, min: 0, max: 100 },
+                } },
+            /**
+             * task-1398: alert delivery routing. Enable flags + a per-channel `levels` filter ONLY; NO credentials here
+             * (bot tokens / webhook URLs live in ~/.dexterm/telegram.json and discord.json, 0600, like every other key).
+             * `/alerts` is user-only (DENIED_FOR_MODELS) so a model can never redirect your alerts to its own channel.
+             */
+            alerts: { type: 'object', additional: false, props: {
+                    channels: { type: 'object', additional: false, props: {
+                            toast: 'alertChannel', desktop: 'alertChannel',
+                            telegram: { type: 'object', additional: false, props: { enabled: { type: 'boolean' }, levels: 'alertLevels', chatId: { type: 'string', pattern: '^-?[0-9]{1,19}$' } } },
+                            discord: 'alertChannel',
+                        } },
+                    /** Deliver a one-line summary of ticket/ask PROPOSALS too (never the ticket itself; off by default). */
+                    proposals: { type: 'boolean' },
+                } },
             scan: { type: 'object', additional: true },
             popups: { type: 'object', additional: false, props: { rain: { type: 'object', additional: false, props: { enabled: { type: 'boolean' }, speedScale: { type: 'number', min: 0, max: 4 }, density: { type: 'number', min: 0, max: 1 } } } } },
             /** Forward-compat bag: unknown sections from a newer dexterm survive a downgrade here. */
@@ -403,7 +426,7 @@ export function applyOps(doc, ops) {
 export const DENIED_FOR_MODELS = [
     /^\/signer(\/|$)/, /^\/trading(\/|$)/, /^\/keys(\/|$)/, /^\/caps(\/|$)/, /^\/mandates?(\/|$)/, /^\/wallet(\/|$)/,
     /^\/packs(\/|$)/, /^\/plugins\/[^/]+\/(capabilities|enabled)(\/|$)/, /^\/plugins\/[^/]+$/, /^\/plugins$/,
-    /^\/jarvis\/gate(\/|$)/, /^\/jarvis\/configAssistant$/, /^\/voice(\/|$)/, /^\/agents(\/|$)/, /^\/version$/,
+    /^\/jarvis\/gate(\/|$)/, /^\/jarvis\/configAssistant$/, /^\/voice(\/|$)/, /^\/alerts(\/|$)/, /^\/agents(\/|$)/, /^\/version$/,
     /^\/rules\/(\d+|-)\/then\/(\d+|-)\/args\/(arm|armed|auto|autoArm|confirm|execute|sign|send)(\/|$)/,
 ];
 /** Keys a model-authored VALUE may never contain at any depth (money/secret-shaped), whatever the path. */