twinclaw 1.0.0

package/dist/interfaces/dispatcher.js

@@ -0,0 +1,214 @@
+import fs from 'node:fs';
+import { logThought } from '../utils/logger.js';
+import { getDmPairingService, normalizePairingSenderId, } from '../services/dm-pairing.js';
+import { InboundDebounceService } from '../services/inbound-debounce.js';
+import { EmbeddedBlockChunker } from '../services/block-chunker.js';
+import { getConfigValue } from '../config/config-loader.js';
+const DEFAULT_ACCESS_CONFIG = {
+    dmPolicy: 'pairing',
+    allowFrom: [],
+};
+function buildPairingChallenge(channel, code) {
+    return (`[TwinBot] Pairing required before I can process your messages on ${channel}.\n` +
+        `Run: twinbot pairing approve ${channel} ${code}`);
+}
+/**
+ * Unified Interface Dispatcher
+ *
+ * Connects all active interface adapters (Telegram, WhatsApp, …) to the core gateway.
+ * Responsibilities:
+ *   1. Register as the message callback on each adapter.
+ *   2. Transcribe voice notes via the STT service before forwarding to the gateway.
+ *   3. Route the normalized InboundMessage to the gateway for processing.
+ *   4. Send the gateway's text response back to the originating platform
+ *      with retry/backoff and delivery tracking.
+ *   5. Clean up ephemeral audio files after transcription.
+ *
+ * Adding a new interface adapter in the future only requires registering it here.
+ */
+export class Dispatcher {
+    #telegram;
+    #whatsapp;
+    #stt;
+    #tts;
+    #gateway;
+    #queue;
+    #pairingService;
+    #accessConfig;
+    #debounce;
+    #chunker;
+    #humanDelayMs;
+    constructor(telegram, whatsapp, stt, tts, gateway, queue, options = {}) {
+        this.#telegram = telegram;
+        this.#whatsapp = whatsapp;
+        this.#stt = stt;
+        this.#tts = tts;
+        this.#gateway = gateway;
+        this.#queue = queue;
+        this.#pairingService = options.pairingService ?? getDmPairingService();
+        this.#accessConfig = {
+            telegram: this.#resolveAccessConfig('telegram', options.telegram),
+            whatsapp: this.#resolveAccessConfig('whatsapp', options.whatsapp),
+        };
+        this.#debounce = new InboundDebounceService(options.debounce);
+        const streamingEnabled = getConfigValue('BLOCK_STREAMING_DEFAULT') === 'true';
+        if (streamingEnabled) {
+            this.#chunker = new EmbeddedBlockChunker({
+                minChars: Number(getConfigValue('BLOCK_STREAMING_MIN_CHARS')) || 50,
+                maxChars: Number(getConfigValue('BLOCK_STREAMING_MAX_CHARS')) || 800,
+                breakOn: getConfigValue('BLOCK_STREAMING_BREAK') || 'paragraph',
+                coalesce: getConfigValue('BLOCK_STREAMING_COALESCE') !== 'false',
+            });
+            this.#humanDelayMs = Number(getConfigValue('HUMAN_DELAY_MS')) || 800;
+        }
+        else {
+            this.#chunker = new EmbeddedBlockChunker({
+                minChars: options.streaming?.minChars ?? 50,
+                maxChars: options.streaming?.maxChars ?? 800,
+                breakOn: options.streaming?.breakOn ?? 'paragraph',
+                coalesce: options.streaming?.coalesce ?? true,
+            });
+            this.#humanDelayMs = options.streaming?.humanDelayMs ?? 0;
+        }
+        // Wire inbound message callbacks through debounce layer.
+        if (this.#telegram)
+            this.#telegram.onMessage = (msg) => this.#handleDebounced(msg);
+        if (this.#whatsapp)
+            this.#whatsapp.onMessage = (msg) => this.#handleDebounced(msg);
+    }
+    /** Expose the queue service for reliability and dead-letter controls. */
+    get queue() {
+        return this.#queue;
+    }
+    get debounceService() {
+        return this.#debounce;
+    }
+    // ── Core Dispatch Loop ────────────────────────────────────────────────────────
+    async #handleDebounced(message) {
+        try {
+            const debounced = await this.#debounce.debounce(message);
+            await this.#handle(debounced);
+        }
+        catch (err) {
+            console.error('[Dispatcher] Unhandled error in debounce handling:', err);
+            await logThought(`[Dispatcher] Debounce error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async #handle(message) {
+        try {
+            const access = this.#authorizeSender(message);
+            if (!access.allowed) {
+                if (access.challengeText) {
+                    this.#queue.enqueue(message.platform, message.chatId, access.challengeText);
+                }
+                return;
+            }
+            const normalized = await this.#resolveAudio(message);
+            const responseText = await this.#gateway.processMessage(normalized);
+            await this.#dispatch(normalized, responseText);
+        }
+        catch (err) {
+            console.error('[Dispatcher] Unhandled error processing message:', err);
+            await logThought(`[Dispatcher] Unhandled error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    #resolveAccessConfig(channel, config) {
+        const dmPolicy = config?.dmPolicy === 'allowlist' ? 'allowlist' : 'pairing';
+        const allowFrom = [...new Set((config?.allowFrom ?? DEFAULT_ACCESS_CONFIG.allowFrom)
+                .map((senderId) => normalizePairingSenderId(channel, senderId))
+                .filter((senderId) => senderId.length > 0))];
+        this.#pairingService.seedAllowFrom(channel, allowFrom);
+        return { dmPolicy, allowFrom };
+    }
+    #authorizeSender(message) {
+        const channel = message.platform;
+        const normalizedSenderId = normalizePairingSenderId(channel, message.senderId);
+        if (!normalizedSenderId) {
+            return { allowed: false };
+        }
+        const config = this.#accessConfig[message.platform];
+        const allowlist = new Set(config.allowFrom);
+        if (allowlist.has(normalizedSenderId) || this.#pairingService.isApproved(channel, normalizedSenderId)) {
+            return { allowed: true };
+        }
+        if (config.dmPolicy !== 'pairing') {
+            return { allowed: false };
+        }
+        const request = this.#pairingService.requestPairing(channel, normalizedSenderId);
+        if (request.status === 'created' && request.request) {
+            return {
+                allowed: false,
+                challengeText: buildPairingChallenge(channel, request.request.code),
+            };
+        }
+        return { allowed: false };
+    }
+    /**
+     * If the message contains an audio file, transcribe it and substitute the
+     * result as `text`. The temp file is deleted after transcription regardless
+     * of the outcome (best-effort cleanup).
+     */
+    async #resolveAudio(message) {
+        if (!message.audioFilePath)
+            return message;
+        const filePath = message.audioFilePath;
+        let transcribedText;
+        try {
+            transcribedText = await this.#stt.transcribeFile(filePath);
+        }
+        finally {
+            fs.unlink(filePath, (unlinkErr) => {
+                if (unlinkErr) {
+                    console.warn('[Dispatcher] Could not delete temp audio file:', unlinkErr.message);
+                }
+            });
+        }
+        return { ...message, audioFilePath: undefined, text: transcribedText };
+    }
+    /**
+     * Route the gateway's response back to the originating platform
+     * via the persistent delivery queue. Chunks text if block streaming is enabled.
+     */
+    async #dispatch(origin, responseText) {
+        const safeText = EmbeddedBlockChunker.ensureCodeFenceClosed(responseText);
+        const chunks = this.#chunker.chunk(safeText);
+        if (chunks.length <= 1) {
+            this.#queue.enqueue(origin.platform, origin.chatId, responseText);
+            return;
+        }
+        for (let i = 0; i < chunks.length; i++) {
+            const isLast = i === chunks.length - 1;
+            const chunk = chunks[i];
+            this.#queue.enqueue(origin.platform, origin.chatId, chunk);
+            if (!isLast && this.#humanDelayMs > 0) {
+                await new Promise((resolve) => setTimeout(resolve, this.#humanDelayMs));
+            }
+        }
+    }
+    /**
+     * Send a proactive (agent-initiated) message to a specific platform target
+     * via the persistent delivery queue. Uses chunking if enabled.
+     */
+    async sendProactive(platform, chatId, text) {
+        const safeText = EmbeddedBlockChunker.ensureCodeFenceClosed(text);
+        const chunks = this.#chunker.chunk(safeText);
+        if (chunks.length <= 1) {
+            this.#queue.enqueue(platform, chatId, text);
+            return;
+        }
+        for (let i = 0; i < chunks.length; i++) {
+            const isLast = i === chunks.length - 1;
+            const chunk = chunks[i];
+            this.#queue.enqueue(platform, chatId, chunk);
+            if (!isLast && this.#humanDelayMs > 0) {
+                await new Promise((resolve) => setTimeout(resolve, this.#humanDelayMs));
+            }
+        }
+    }
+    /** Tear down all active interface adapters cleanly. */
+    shutdown() {
+        this.#debounce.clear();
+        this.#telegram?.stop();
+        this.#whatsapp?.stop();
+    }
+}

package/dist/interfaces/telegram_handler.js

@@ -0,0 +1,82 @@
+import TelegramBot from 'node-telegram-bot-api';
+import os from 'node:os';
+import path from 'node:path';
+/** Minimum ms delay between processing successive messages (human-like pacing). */
+const RATE_LIMIT_MS = 1500;
+/**
+ * Wraps the Telegram Bot API to provide:
+ *   - Inbound message normalization for the dispatcher
+ *   - Human-like rate limiting between messages
+ *   - Normalized InboundMessage delivery including voice-note file paths
+ */
+export class TelegramHandler {
+    #bot;
+    #lastMessageAt = 0;
+    /**
+     * @param token          - Telegram Bot token from @BotFather (TELEGRAM_BOT_TOKEN).
+     */
+    constructor(token) {
+        this.#bot = new TelegramBot(token, { polling: true });
+        this.#registerListeners();
+    }
+    /** Callback invoked by the dispatcher for every authorized, normalized message. */
+    onMessage;
+    // ── Private Helpers ──────────────────────────────────────────────────────────
+    async #applyRateLimit() {
+        const elapsed = Date.now() - this.#lastMessageAt;
+        if (elapsed < RATE_LIMIT_MS) {
+            await new Promise((resolve) => setTimeout(resolve, RATE_LIMIT_MS - elapsed));
+        }
+        this.#lastMessageAt = Date.now();
+    }
+    #registerListeners() {
+        this.#bot.on('message', async (msg) => {
+            if (!msg.from)
+                return;
+            await this.#applyRateLimit();
+            const base = {
+                platform: 'telegram',
+                senderId: String(msg.from.id),
+                chatId: msg.chat.id,
+                text: msg.text,
+                rawPayload: msg,
+            };
+            // Voice note: download to tmp dir, transcription happens in the dispatcher.
+            if (msg.voice) {
+                try {
+                    const tmpDir = os.tmpdir();
+                    const localPath = await this.#bot.downloadFile(msg.voice.file_id, tmpDir);
+                    const inbound = {
+                        ...base,
+                        audioFilePath: path.resolve(localPath),
+                    };
+                    await this.onMessage?.(inbound);
+                }
+                catch (err) {
+                    console.error('[TelegramHandler] Failed to download voice note:', err);
+                }
+                return;
+            }
+            await this.onMessage?.(base);
+        });
+        this.#bot.on('polling_error', (err) => {
+            console.error('[TelegramHandler] Polling error:', err.message);
+        });
+    }
+    // ── Public Send Methods ───────────────────────────────────────────────────────
+    /** Send a plain-text reply to a chat. */
+    async sendText(chatId, text) {
+        await this.#bot.sendMessage(Number(chatId), text);
+    }
+    /**
+     * Send a synthesized voice reply as an audio/wav message.
+     * @param audio - Raw WAV buffer produced by the TTS service.
+     */
+    async sendVoice(chatId, audio) {
+        await this.#bot.sendVoice(Number(chatId), audio, {}, { contentType: 'audio/wav', filename: 'response.wav' });
+    }
+    /** Gracefully stop the polling loop. */
+    stop() {
+        this.#bot.stopPolling();
+    }
+}

package/dist/interfaces/tui-dashboard.js

@@ -0,0 +1,53 @@
+import blessed from 'blessed';
+import contrib from 'blessed-contrib';
+// Capture native logs so we can pipe them to the dashboard log view
+const nativeLog = console.log;
+const nativeError = console.error;
+export function startTUI() {
+    const screen = blessed.screen({ smartCSR: true });
+    screen.title = 'TwinBot Native Dashboard';
+    const grid = new contrib.grid({ rows: 12, cols: 12, screen: screen });
+    const logView = grid.set(0, 0, 8, 8, contrib.log, {
+        fg: "green",
+        selectedFg: "green",
+        label: ' Live System Logs '
+    });
+    const memoryDonut = grid.set(0, 8, 4, 4, contrib.donut, {
+        label: ' System Memory ',
+        radius: 12,
+        arcWidth: 4,
+        yPadding: 2
+    });
+    const providerView = grid.set(4, 8, 4, 4, contrib.markdown, {
+        label: ' Active Provider '
+    });
+    const statusView = grid.set(8, 0, 4, 12, contrib.markdown, {
+        label: ' TwinBot Status '
+    });
+    // Replace console defaults
+    console.log = (...args) => {
+        const text = args.map(a => typeof a === 'object' ? JSON.stringify(a) : a).join(' ');
+        logView.log(text);
+        screen.render();
+    };
+    console.error = (...args) => {
+        const text = args.map(a => typeof a === 'object' ? JSON.stringify(a) : a).join(' ');
+        logView.log(`{red-fg}[ERROR]{/red-fg} ${text}`);
+        screen.render();
+    };
+    setInterval(() => {
+        const mem = process.memoryUsage();
+        const percent = Math.round((mem.heapUsed / mem.heapTotal) * 100);
+        memoryDonut.update([
+            { percent: percent, label: 'Heap', color: 'blue' }
+        ]);
+        providerView.setMarkdown(`**Current Target:**\nOpenRouter (Claude 3.5 Sonnet)\n\n**Fallback Chains:**\n1. Google AI Studio\n2. Modal Serverless\n\n**Status:** Online 🟢`);
+        statusView.setMarkdown(`TwinBot Autonomous Service running.\nMemory: Local SQLite + sqlite-vec.\nBackground Job Engine: Active.\n\nPress **Escape**, **q**, or **C-c** to quit.`);
+        screen.render();
+    }, 1000);
+    screen.key(['escape', 'q', 'C-c'], () => {
+        return process.exit(0);
+    });
+    console.log('TUI Initialized. Monitoring agent activities...');
+    screen.render();
+}

package/dist/interfaces/whatsapp_handler.js

@@ -0,0 +1,94 @@
+import WAWebJS from 'whatsapp-web.js';
+import qrcode from 'qrcode-terminal';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+const { Client, LocalAuth, MessageMedia } = WAWebJS;
+const RATE_LIMIT_MS = 1500;
+export class WhatsAppHandler {
+    #client;
+    #lastMessageAt = 0;
+    constructor() {
+        this.#client = new Client({
+            authStrategy: new LocalAuth({ dataPath: './memory/whatsapp_auth' }),
+            puppeteer: {
+                args: ['--no-sandbox', '--disable-setuid-sandbox'],
+            }
+        });
+        this.#registerListeners();
+    }
+    onMessage;
+    async #applyRateLimit() {
+        const elapsed = Date.now() - this.#lastMessageAt;
+        if (elapsed < RATE_LIMIT_MS) {
+            await new Promise((resolve) => setTimeout(resolve, RATE_LIMIT_MS - elapsed));
+        }
+        this.#lastMessageAt = Date.now();
+    }
+    #registerListeners() {
+        this.#client.on('qr', (qr) => {
+            console.log('[WhatsAppHandler] Scan this QR code to authenticate:');
+            qrcode.generate(qr, { small: true });
+        });
+        this.#client.on('ready', () => {
+            console.log('[WhatsAppHandler] Client is ready!');
+        });
+        this.#client.on('message', async (msg) => {
+            await this.#applyRateLimit();
+            const base = {
+                platform: 'whatsapp',
+                senderId: msg.from,
+                chatId: msg.from,
+                text: msg.body,
+                rawPayload: msg,
+            };
+            if (msg.hasMedia) {
+                try {
+                    const media = await msg.downloadMedia();
+                    // If it's audio (voice note or audio file)
+                    if (media && media.mimetype.startsWith('audio/')) {
+                        const tmpDir = os.tmpdir();
+                        let ext = '.ogg'; // Default for voice notes
+                        if (media.mimetype.includes('mp3'))
+                            ext = '.mp3';
+                        else if (media.mimetype.includes('mp4'))
+                            ext = '.mp4';
+                        const fileName = `wa_${randomUUID()}${ext}`;
+                        const localPath = path.join(tmpDir, fileName);
+                        const buffer = Buffer.from(media.data, 'base64');
+                        await fs.writeFile(localPath, buffer);
+                        const inbound = {
+                            ...base,
+                            audioFilePath: localPath,
+                        };
+                        await this.onMessage?.(inbound);
+                        return;
+                    }
+                }
+                catch (err) {
+                    console.error('[WhatsAppHandler] Failed to download media:', err);
+                }
+            }
+            // Exclude empty bodies unless they were intercepted voice notes
+            if (msg.body) {
+                await this.onMessage?.(base);
+            }
+        });
+        this.#client.initialize().catch(err => {
+            console.error('[WhatsAppHandler] Failed to initialize client:', err);
+        });
+    }
+    async sendText(chatId, text) {
+        await this.#client.sendMessage(chatId, text);
+    }
+    async sendVoice(chatId, audio) {
+        const media = new MessageMedia('audio/wav', audio.toString('base64'), 'response.wav');
+        await this.#client.sendMessage(chatId, media, { sendAudioAsVoice: true });
+    }
+    stop() {
+        this.#client.destroy().catch(err => {
+            console.error('[WhatsAppHandler] Failed to destroy client:', err);
+        });
+    }
+}

package/dist/release/cli.js

@@ -0,0 +1,97 @@
+import { ReleasePipelineService } from '../services/release-pipeline.js';
+function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    const parsed = { command };
+    for (let index = 0; index < rest.length; index += 1) {
+        const token = rest[index];
+        const next = rest[index + 1];
+        if (token === '--health-url' && next) {
+            parsed.healthUrl = next;
+            index += 1;
+            continue;
+        }
+        if (token === '--snapshot' && next) {
+            parsed.snapshotId = next;
+            index += 1;
+            continue;
+        }
+        if (token === '--restart-command' && next) {
+            parsed.restartCommand = next;
+            index += 1;
+            continue;
+        }
+        if (token === '--release-id' && next) {
+            parsed.releaseId = next;
+            index += 1;
+            continue;
+        }
+        if (token === '--retention' && next) {
+            const parsedNumber = Number(next);
+            if (Number.isFinite(parsedNumber) && parsedNumber >= 1) {
+                parsed.retentionLimit = Math.floor(parsedNumber);
+            }
+            index += 1;
+            continue;
+        }
+    }
+    return parsed;
+}
+function printUsage() {
+    console.error([
+        'Usage:',
+        '  tsx src/release/cli.ts preflight [--health-url <url>]',
+        '  tsx src/release/cli.ts prepare [--health-url <url>] [--release-id <id>] [--retention <n>]',
+        '  tsx src/release/cli.ts rollback [--snapshot <id>] [--health-url <url>] [--restart-command "<cmd>"]',
+        '  tsx src/release/cli.ts drill [--snapshot <id>] [--health-url <url>]',
+    ].join('\n'));
+}
+function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (!parsed.command) {
+        printUsage();
+        process.exitCode = 1;
+        return;
+    }
+    const service = new ReleasePipelineService();
+    if (parsed.command === 'preflight') {
+        const result = await service.runPreflight({ healthUrl: parsed.healthUrl });
+        printJson(result);
+        process.exitCode = result.passed ? 0 : 1;
+        return;
+    }
+    if (parsed.command === 'prepare') {
+        const manifest = await service.prepareRelease({
+            healthUrl: parsed.healthUrl,
+            releaseId: parsed.releaseId,
+            retentionLimit: parsed.retentionLimit,
+        });
+        printJson(manifest);
+        process.exitCode = manifest.status === 'ready' ? 0 : 1;
+        return;
+    }
+    if (parsed.command === 'rollback') {
+        const result = await service.rollback({
+            snapshotId: parsed.snapshotId,
+            healthUrl: parsed.healthUrl,
+            restartCommand: parsed.restartCommand,
+        });
+        printJson(result);
+        process.exitCode = result.status === 'failed' ? 1 : 0;
+        return;
+    }
+    if (parsed.command === 'drill') {
+        const result = await service.runDrill({
+            snapshotId: parsed.snapshotId,
+            healthUrl: parsed.healthUrl,
+        });
+        printJson(result);
+        process.exitCode = result.status === 'passed' ? 0 : 1;
+        return;
+    }
+    printUsage();
+    process.exitCode = 1;
+}
+void main();

package/dist/release/mvp-gate-cli.js

@@ -0,0 +1,118 @@
+import { MvpGateService } from '../services/mvp-gate.js';
+function parseArgs(argv) {
+    const parsed = { skipHealth: false, ci: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        const next = argv[i + 1];
+        if (token === '--health-url' && next) {
+            parsed.healthUrl = next;
+            i += 1;
+            continue;
+        }
+        if (token === '--report-dir' && next) {
+            parsed.reportDir = next;
+            i += 1;
+            continue;
+        }
+        if (token === '--skip-health') {
+            parsed.skipHealth = true;
+            continue;
+        }
+        if (token === '--ci') {
+            parsed.ci = true;
+            continue;
+        }
+    }
+    return parsed;
+}
+function printUsage() {
+    console.error([
+        'Usage:',
+        '  tsx src/release/mvp-gate-cli.ts [--health-url <url>] [--report-dir <path>] [--skip-health] [--ci]',
+        '',
+        'Flags:',
+        '  --health-url <url>  Override the health endpoint URL (default: http://localhost:18789/health)',
+        '  --report-dir <path> Override the report output directory',
+        '  --skip-health       Skip the api-health check entirely',
+        '  --ci                CI mode; output remains deterministic for workflow parsing',
+        '',
+        'Exit codes:',
+        '  0  go (all hard gates passed, no advisory failures)',
+        '  1  no-go (one or more hard gates failed)',
+        '  2  advisory-only (hard gates passed but advisory checks failed)',
+    ].join('\n'));
+}
+function printHumanSummary(report) {
+    const verdictLabel = report.verdict === 'go'
+        ? '🟢 GO'
+        : report.verdict === 'no-go'
+            ? '🔴 NO-GO'
+            : '🟡 ADVISORY-ONLY';
+    console.error('');
+    console.error('════════════════════════════════════════════════════════════');
+    console.error(`  MVP Gate Report  ·  ${report.reportId}`);
+    console.error(`  Verdict: ${verdictLabel}`);
+    console.error('════════════════════════════════════════════════════════════');
+    console.error('');
+    console.error(`  ${report.summary}`);
+    console.error('');
+    if (report.failedHardGates.length > 0) {
+        console.error('  ── Blocking Failures ───────────────────────────────────');
+        for (const check of report.failedHardGates) {
+            console.error(`  ❌  [${check.id}] ${check.detail}`);
+        }
+        console.error('');
+    }
+    if (report.advisoryFailures.length > 0) {
+        console.error('  ── Advisory Failures (non-blocking) ────────────────────');
+        for (const check of report.advisoryFailures) {
+            console.error(`  ⚠️   [${check.id}] ${check.detail}`);
+        }
+        console.error('');
+    }
+    if (report.triage.length > 0) {
+        console.error('  ── Triage & Next Actions ───────────────────────────────');
+        for (const entry of report.triage) {
+            const icon = entry.severity === 'blocker' ? '🔴' : '🟡';
+            console.error(`  ${icon}  ${entry.checkId}`);
+            console.error(`     Owner: ${entry.ownerTrack}`);
+            console.error(`     Action: ${entry.nextAction}`);
+            console.error('');
+        }
+    }
+    const smokePass = report.smokeScenarios.filter((s) => s.pass).length;
+    const smokeTotal = report.smokeScenarios.length;
+    console.error(`  Smoke scenarios: ${smokePass}/${smokeTotal} passed`);
+    console.error('');
+    console.error(`  JSON report  → ${report.reportPath}`);
+    console.error(`  MD report    → ${report.markdownPath}`);
+    console.error('────────────────────────────────────────────────────────────');
+    console.error('');
+}
+async function main() {
+    if (process.argv.includes('--help') || process.argv.includes('-h')) {
+        printUsage();
+        return;
+    }
+    const args = parseArgs(process.argv.slice(2));
+    const service = new MvpGateService({ reportDir: args.reportDir });
+    const report = await service.runGate({
+        healthUrl: args.healthUrl,
+        skipHealth: args.skipHealth,
+    });
+    // Machine-readable JSON → stdout
+    console.log(JSON.stringify(report, null, 2));
+    // Human-readable summary → stderr
+    printHumanSummary(report);
+    // Exit code conveys the verdict
+    if (report.verdict === 'no-go') {
+        process.exitCode = 1;
+    }
+    else if (report.verdict === 'advisory-only') {
+        process.exitCode = 2;
+    }
+    else {
+        process.exitCode = 0;
+    }
+}
+void main();