twinclaw 1.0.0

package/dist/core/pairing-cli.js

@@ -0,0 +1,78 @@
+import { getDmPairingService, isPairingChannel, } from '../services/dm-pairing.js';
+function printPairingUsage() {
+    console.log(`Pairing commands:
+  pairing list <channel>
+  pairing approve <channel> <CODE>
+
+Supported channels: telegram, whatsapp`);
+}
+function parseChannel(input) {
+    if (!input) {
+        throw new Error('Missing channel. Use: pairing <list|approve> <channel>.');
+    }
+    const normalized = input.trim().toLowerCase();
+    if (!isPairingChannel(normalized)) {
+        throw new Error(`Unsupported channel '${input}'. Supported channels: telegram, whatsapp.`);
+    }
+    return normalized;
+}
+function runPairingList(service, channel) {
+    const requests = service.listPending(channel);
+    if (requests.length === 0) {
+        console.log(`No pending pairing requests for channel '${channel}'.`);
+        return;
+    }
+    console.log(`Pending pairing requests for '${channel}' (${requests.length}):`);
+    for (const request of requests) {
+        console.log(`  code=${request.code}\tsender=${request.senderId}\texpires=${request.expiresAt}`);
+    }
+}
+function runPairingApprove(service, channel, code) {
+    if (!code) {
+        throw new Error('Missing pairing code. Use: pairing approve <channel> <CODE>.');
+    }
+    const result = service.approve(channel, code);
+    switch (result.status) {
+        case 'approved':
+            console.log(`Approved sender '${result.senderId}' for channel '${channel}' using code '${code.toUpperCase()}'.`);
+            return;
+        case 'expired':
+            throw new Error(`Pairing code '${code.toUpperCase()}' is expired for channel '${channel}'.`);
+        case 'not_found':
+            throw new Error(`Pairing code '${code.toUpperCase()}' not found for channel '${channel}'.`);
+    }
+}
+/**
+ * Handle one-shot pairing commands.
+ * Returns true when invocation was recognized (handled or failed), false otherwise.
+ */
+export function handlePairingCli(argv, service = getDmPairingService()) {
+    if (argv[0] !== 'pairing') {
+        return false;
+    }
+    const command = argv[1];
+    try {
+        switch (command) {
+            case 'list': {
+                const channel = parseChannel(argv[2]);
+                runPairingList(service, channel);
+                return true;
+            }
+            case 'approve': {
+                const channel = parseChannel(argv[2]);
+                runPairingApprove(service, channel, argv[3]);
+                return true;
+            }
+            default:
+                printPairingUsage();
+                process.exitCode = 1;
+                return true;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Pairing command failed: ${message}`);
+        process.exitCode = 1;
+        return true;
+    }
+}

package/dist/core/secret-vault-cli.js

@@ -0,0 +1,204 @@
+import { getSecretVaultService } from '../services/secret-vault.js';
+import { validateRuntimeConfig } from '../config/env-validator.js';
+function readOption(args, flag) {
+    const index = args.indexOf(flag);
+    if (index === -1) {
+        return undefined;
+    }
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}.`);
+    }
+    return value;
+}
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+function parseOptionalNumber(args, flag) {
+    const value = readOption(args, flag);
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${flag} must be a positive number.`);
+    }
+    return parsed;
+}
+function printUsage() {
+    console.log(`Secret vault commands:
+  secret list
+  secret doctor
+  secret set <NAME> <VALUE> [--scope <scope>] [--source <source>] [--required] [--rotation-hours <n>] [--warning-hours <n>] [--expires-at <ISO8601>]
+  secret rotate <NAME> <NEXT_VALUE> [--reason <text>] [--rotation-hours <n>] [--warning-hours <n>] [--expires-at <ISO8601>]
+  secret revoke <NAME> [--reason <text>]
+  config doctor`);
+}
+function runList(service) {
+    const secrets = service.listSecrets();
+    if (secrets.length === 0) {
+        console.log('No secrets registered.');
+        return;
+    }
+    for (const secret of secrets) {
+        console.log(`${secret.name}\tstatus=${secret.status}\tscope=${secret.scope}\tsource=${secret.source}\t` +
+            `required=${secret.required}\tversion=${secret.version}\t` +
+            `lastRotated=${secret.lastRotatedAt ?? 'n/a'}\texpires=${secret.expiresAt ?? 'none'}`);
+    }
+}
+function runDoctor(service) {
+    const diagnostics = service.getDiagnostics();
+    const status = diagnostics.health.hasIssues ? 'degraded' : 'ok';
+    console.log(`Secret vault status: ${status}`);
+    console.log(`Totals: total=${diagnostics.total}, active=${diagnostics.active}, expired=${diagnostics.expired}, revoked=${diagnostics.revoked}`);
+    if (diagnostics.health.missingRequired.length > 0) {
+        console.log(`Missing required: ${diagnostics.health.missingRequired.join(', ')}`);
+    }
+    if (diagnostics.health.expired.length > 0) {
+        console.log(`Expired: ${diagnostics.health.expired.join(', ')}`);
+    }
+    if (diagnostics.health.warnings.length > 0) {
+        console.log(`Warnings: ${diagnostics.health.warnings.join(' | ')}`);
+    }
+    if (diagnostics.dueForRotation.length > 0) {
+        console.log(`Due for rotation: ${diagnostics.dueForRotation.join(', ')}`);
+    }
+}
+function runSet(service, args) {
+    const name = args[0];
+    const value = args[1];
+    if (!name || !value) {
+        throw new Error('Usage: secret set <NAME> <VALUE> [...options]');
+    }
+    const scope = readOption(args, '--scope');
+    const source = readOption(args, '--source');
+    const metadata = service.setSecret({
+        name,
+        value,
+        scope,
+        source,
+        required: hasFlag(args, '--required'),
+        rotationWindowHours: parseOptionalNumber(args, '--rotation-hours'),
+        warningWindowHours: parseOptionalNumber(args, '--warning-hours'),
+        expiresAt: readOption(args, '--expires-at'),
+    });
+    console.log(`Secret '${metadata.name}' saved. version=${metadata.version}, status=${metadata.status}, expires=${metadata.expiresAt ?? 'none'}.`);
+}
+function runRotate(service, args) {
+    const name = args[0];
+    const nextValue = args[1];
+    if (!name || !nextValue) {
+        throw new Error('Usage: secret rotate <NAME> <NEXT_VALUE> [...options]');
+    }
+    const metadata = service.rotateSecret({
+        name,
+        nextValue,
+        reason: readOption(args, '--reason'),
+        rotationWindowHours: parseOptionalNumber(args, '--rotation-hours'),
+        warningWindowHours: parseOptionalNumber(args, '--warning-hours'),
+        expiresAt: readOption(args, '--expires-at'),
+    });
+    console.log(`Secret '${metadata.name}' rotated. version=${metadata.version}, status=${metadata.status}, expires=${metadata.expiresAt ?? 'none'}.`);
+}
+function runRevoke(service, args) {
+    const name = args[0];
+    if (!name) {
+        throw new Error('Usage: secret revoke <NAME> [--reason <text>]');
+    }
+    const metadata = service.revokeSecret({
+        name,
+        reason: readOption(args, '--reason'),
+    });
+    console.log(`Secret '${metadata.name}' revoked.`);
+}
+function runConfigDoctor() {
+    const result = validateRuntimeConfig();
+    const overallStatus = result.ok ? 'ok' : 'degraded';
+    console.log(`Config validation status: ${overallStatus}`);
+    console.log(`Validated at: ${result.validatedAt}`);
+    console.log(`Present keys (${result.presentKeys.length}): ${result.presentKeys.join(', ') || 'none'}`);
+    if (result.activeFeatures.length > 0) {
+        console.log(`Active features: ${result.activeFeatures.join(', ')}`);
+    }
+    if (result.issues.length === 0) {
+        console.log('No config issues detected.');
+        return;
+    }
+    if (result.fatalIssues.length > 0) {
+        console.log(`\nFatal issues (${result.fatalIssues.length}):`);
+        for (const issue of result.fatalIssues) {
+            console.log(`  [${issue.key}] ${issue.message}`);
+            console.log(`    Remediation: ${issue.remediation}`);
+        }
+    }
+    const nonFatal = result.issues.filter((i) => i.class !== 'missing_required');
+    if (nonFatal.length > 0) {
+        console.log(`\nWarnings (${nonFatal.length}):`);
+        for (const issue of nonFatal) {
+            console.log(`  [${issue.class}] [${issue.key}] ${issue.message}`);
+            console.log(`    Remediation: ${issue.remediation}`);
+        }
+    }
+}
+/**
+ * Handles one-shot secret and config CLI workflows.
+ * Returns true when invocation was recognized (handled or failed), false otherwise.
+ */
+export function handleSecretVaultCli(argv, service = getSecretVaultService()) {
+    const topCommand = argv[0];
+    // ── config subcommands ─────────────────────────────────────────────────────
+    if (topCommand === 'config') {
+        const subcommand = argv[1];
+        try {
+            switch (subcommand) {
+                case 'doctor':
+                    runConfigDoctor();
+                    return true;
+                default:
+                    console.log('Config commands:\n  config doctor');
+                    process.exitCode = 1;
+                    return true;
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Config command failed: ${message}`);
+            process.exitCode = 1;
+            return true;
+        }
+    }
+    if (topCommand !== 'secret') {
+        return false;
+    }
+    const command = argv[1];
+    const commandArgs = argv.slice(2);
+    try {
+        switch (command) {
+            case 'list':
+                runList(service);
+                return true;
+            case 'doctor':
+                runDoctor(service);
+                return true;
+            case 'set':
+                runSet(service, commandArgs);
+                return true;
+            case 'rotate':
+                runRotate(service, commandArgs);
+                return true;
+            case 'revoke':
+                runRevoke(service, commandArgs);
+                return true;
+            default:
+                printUsage();
+                process.exitCode = 1;
+                return true;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Secret vault command failed: ${message}`);
+        process.exitCode = 1;
+        return true;
+    }
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,404 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+import { handleOnboardCli, runOnboarding, runSetupWizard, startBasicREPL } from './core/onboarding.js';
+import { Gateway } from './core/gateway.js';
+import { handleDoctorCli, handleHelpCli, handleUnknownCommand } from './core/cli.js';
+import { handleInstallCli } from './core/install-cli.js';
+import { HeartbeatService } from './core/heartbeat.js';
+import { Dispatcher } from './interfaces/dispatcher.js';
+import { TelegramHandler } from './interfaces/telegram_handler.js';
+import { WhatsAppHandler } from './interfaces/whatsapp_handler.js';
+import { FileWatcherService } from './services/file-watcher.js';
+import { ProactiveNotifier } from './services/proactive-notifier.js';
+import { SkillRegistry } from './services/skill-registry.js';
+import { McpServerManager } from './services/mcp-server-manager.js';
+import { createBuiltinSkills } from './skills/builtin.js';
+import { SttService } from './services/stt-service.js';
+import { TtsService } from './services/tts-service.js';
+import { QueueService } from './services/queue-service.js';
+import { ModelRouter } from './services/model-router.js';
+import { IncidentManager } from './services/incident-manager.js';
+import { RuntimeBudgetGovernor } from './services/runtime-budget-governor.js';
+import { LocalStateBackupService } from './services/local-state-backup.js';
+import { logThought } from './utils/logger.js';
+import { PolicyEngine } from './services/policy-engine.js';
+import { savePolicyAuditLog } from './services/db.js';
+import { getSecretVaultService } from './services/secret-vault.js';
+import { getConfigValue, checkAndMigrateWorkspace } from './config/config-loader.js';
+import { getIdentityDir, getWorkspaceSubdir } from './config/workspace.js';
+import { handleSecretVaultCli } from './core/secret-vault-cli.js';
+import { handlePairingCli } from './core/pairing-cli.js';
+import { handleChannelsCli } from './core/channels-cli.js';
+import { handleGatewayCli } from './core/gateway-cli.js';
+import { handleLogsCli } from './core/logs-cli.js';
+import { getDmPairingService } from './services/dm-pairing.js';
+import { randomUUID } from 'node:crypto';
+const secretVault = getSecretVaultService();
+const pairingService = getDmPairingService();
+function assertWindowsOnlyRuntime() {
+    if (process.platform === 'win32') {
+        return;
+    }
+    console.error(`[TwinBot] Windows-only runtime: detected unsupported platform '${process.platform}'.`);
+    process.exit(1);
+}
+assertWindowsOnlyRuntime();
+// ── Early one-shot CLI commands (bypass service startup) ─────────────────────
+if (handleHelpCli(process.argv.slice(2))) {
+    process.exit(process.exitCode ?? 0);
+}
+if (handleDoctorCli(process.argv.slice(2))) {
+    process.exit(process.exitCode ?? 0);
+}
+if (await handleInstallCli(process.argv.slice(2))) {
+    process.exit(process.exitCode ?? 0);
+}
+if (handleSecretVaultCli(process.argv.slice(2), secretVault)) {
+    process.exit(process.exitCode ?? 0);
+}
+if (handlePairingCli(process.argv.slice(2), pairingService)) {
+    process.exit(process.exitCode ?? 0);
+}
+const onboardCliHandled = await handleOnboardCli(process.argv.slice(2));
+if (onboardCliHandled) {
+    process.exit(process.exitCode ?? 0);
+}
+const logsCliHandled = await handleLogsCli(process.argv.slice(2));
+if (logsCliHandled) {
+    if (process.argv.includes('--follow') || process.argv.includes('-f')) {
+        await new Promise(() => { }); // Block event loop for watcher
+    }
+    else {
+        process.exit(process.exitCode ?? 0);
+    }
+}
+const gatewayCliHandled = await handleGatewayCli(process.argv.slice(2));
+if (gatewayCliHandled) {
+    process.exit(process.exitCode ?? 0);
+}
+const channelsCliHandled = await handleChannelsCli(process.argv.slice(2));
+if (channelsCliHandled) {
+    if (process.exitCode !== undefined) {
+        process.exit(process.exitCode);
+    }
+    // Hang the main thread so async tasks (like WhatsApp login) can complete
+    await new Promise(() => { });
+}
+if (handleUnknownCommand(process.argv.slice(2))) {
+    process.exit(process.exitCode ?? 1);
+}
+// Check for setup mode or missing critical configuration
+const isSetupMode = process.argv[2] === 'setup';
+const onboardFlag = process.argv.includes('--onboard');
+if (onboardFlag) {
+    await runOnboarding();
+    process.exit(0);
+}
+checkAndMigrateWorkspace();
+// ── Auto-Setup Trigger (If critical config missing) ──────────────────────────
+async function tryAutoSetup() {
+    try {
+        secretVault.assertStartupPreflight(['API_SECRET']);
+    }
+    catch (error) {
+        console.log("\n[TwinBot] Welcome! Critical configuration missing.");
+        console.log("Starting the interactive setup wizard to configure your agent.\n");
+        const result = await runSetupWizard();
+        if (result.status !== 'success') {
+            const exitCode = result.status === 'cancelled' ? 130 : 1;
+            process.exit(exitCode);
+        }
+        console.log("\n[TwinBot] Setup complete. Initializing Gateway...\n");
+    }
+}
+if (!isSetupMode) {
+    await tryAutoSetup();
+}
+else {
+    const result = await runSetupWizard();
+    if (result.status === 'success') {
+        process.exit(0);
+    }
+    if (result.status === 'cancelled') {
+        process.exit(130);
+    }
+    process.exit(1);
+}
+console.log("TwinBot Gateway Initialized.");
+// ── Heartbeat & Job Scheduler ────────────────────────────────────────────────
+const heartbeat = new HeartbeatService(async (message) => {
+    console.log(`\n[TwinBot Heartbeat] ${message}\n`);
+});
+heartbeat.start();
+void logThought('TwinBot process started and heartbeat initialized.');
+// ── File Watcher ─────────────────────────────────────────────────────────────
+const fileWatcher = new FileWatcherService();
+fileWatcher.addTarget({
+    id: 'identity',
+    directory: getIdentityDir(),
+    exclude: [],
+});
+fileWatcher.addTarget({
+    id: 'memory-logs',
+    directory: getWorkspaceSubdir('memory'),
+    exclude: ['**/*.db', '**/*.db-journal', '**/*.sqlite', '**/*.sqlite-journal'],
+});
+// ── MCP Skill Registry & Server Manager ──────────────────────────────────────
+const skillRegistry = new SkillRegistry();
+skillRegistry.registerMany(createBuiltinSkills());
+const mcpManager = new McpServerManager(skillRegistry);
+void (async () => {
+    try {
+        await mcpManager.loadConfig();
+        await mcpManager.connectAll();
+        const summary = skillRegistry.summary();
+        const servers = mcpManager.listServers();
+        const connectedCount = servers.filter((s) => s.state === 'connected').length;
+        console.log(`[TwinBot MCP] ${connectedCount}/${servers.length} servers connected | ` +
+            `${summary.builtin ?? 0} builtin + ${summary.mcp ?? 0} MCP skills registered.`);
+        await logThought(`[MCP] Initialized: ${connectedCount} servers, ${summary.mcp ?? 0} MCP tools, ${summary.builtin ?? 0} builtins.`);
+    }
+    catch (err) {
+        console.error('[TwinBot MCP] Initialization failed:', err);
+    }
+})();
+// ── Gateway & Interface Dispatcher ────────────────────────────────────────────
+const policyEngine = new PolicyEngine();
+policyEngine.onDecision = (sessionId, decision) => {
+    savePolicyAuditLog(randomUUID(), sessionId, decision.skillName, decision.action, decision.reason, decision.profileId);
+};
+function parseToolSelectors(rawValue) {
+    if (!rawValue) {
+        return [];
+    }
+    return rawValue
+        .split(',')
+        .map((value) => value.trim())
+        .filter((value, index, all) => value.length > 0 && all.indexOf(value) === index);
+}
+const runtimeBudgetGovernor = new RuntimeBudgetGovernor();
+const modelRouter = new ModelRouter({ budgetGovernor: runtimeBudgetGovernor });
+const gateway = new Gateway(skillRegistry, {
+    policyEngine,
+    router: modelRouter,
+    toolPolicy: {
+        allow: parseToolSelectors(getConfigValue('TOOLS_ALLOW')),
+        deny: parseToolSelectors(getConfigValue('TOOLS_DENY')),
+    },
+});
+const telegramBotToken = secretVault.readSecret('TELEGRAM_BOT_TOKEN');
+const telegramUserId = getConfigValue('TELEGRAM_USER_ID')?.trim();
+const whatsappPhoneNumber = secretVault.readSecret('WHATSAPP_PHONE_NUMBER') ?? getConfigValue('WHATSAPP_PHONE_NUMBER');
+const groqApiKey = secretVault.readSecret('GROQ_API_KEY');
+let dispatcher = null;
+if (telegramBotToken || whatsappPhoneNumber) {
+    if (groqApiKey) {
+        let telegramHandler;
+        let whatsappHandler;
+        const telegramAllowFrom = [];
+        const whatsappAllowFrom = [];
+        if (telegramBotToken) {
+            telegramHandler = new TelegramHandler(telegramBotToken);
+            if (telegramUserId) {
+                const parsedTelegramUserId = Number(telegramUserId);
+                if (!Number.isInteger(parsedTelegramUserId) || parsedTelegramUserId <= 0) {
+                    console.error('[TwinBot] TELEGRAM_USER_ID must be a positive integer when provided.');
+                }
+                else {
+                    telegramAllowFrom.push(String(parsedTelegramUserId));
+                }
+            }
+        }
+        if (whatsappPhoneNumber) {
+            whatsappHandler = new WhatsAppHandler();
+            whatsappAllowFrom.push(whatsappPhoneNumber);
+        }
+        const sttService = new SttService(groqApiKey);
+        const ttsService = new TtsService(groqApiKey);
+        // Initialize persistent delivery queue
+        const queueService = new QueueService(async (platform, chatId, text) => {
+            switch (platform) {
+                case 'telegram':
+                    if (!telegramHandler)
+                        throw new Error('Telegram handler not configured');
+                    await telegramHandler.sendText(Number(chatId), text);
+                    break;
+                case 'whatsapp':
+                    if (!whatsappHandler)
+                        throw new Error('WhatsApp handler not configured');
+                    await whatsappHandler.sendText(String(chatId), text);
+                    break;
+                default:
+                    throw new Error(`Unsupported platform in queue: ${platform}`);
+            }
+        }, heartbeat.scheduler);
+        queueService.start();
+        dispatcher = new Dispatcher(telegramHandler, whatsappHandler, sttService, ttsService, gateway, queueService, {
+            pairingService,
+            telegram: {
+                dmPolicy: 'pairing',
+                allowFrom: telegramAllowFrom,
+            },
+            whatsapp: {
+                dmPolicy: 'pairing',
+                allowFrom: whatsappAllowFrom,
+            },
+        });
+        void logThought('[TwinBot] Messaging dispatcher and persistent queue initialized.');
+    }
+    else {
+        console.warn('[TwinBot] Dispatcher requires GROQ_API_KEY.');
+    }
+}
+else {
+    console.log('[TwinBot] Messaging dispatcher not initialized (missing Telegram AND WhatsApp configs).');
+}
+const incidentManager = new IncidentManager({
+    gateway,
+    router: modelRouter,
+    queue: dispatcher?.queue,
+    scheduler: heartbeat.scheduler,
+});
+incidentManager.start();
+const localStateBackup = new LocalStateBackupService({
+    scheduler: heartbeat.scheduler,
+});
+localStateBackup.start();
+void logThought('[TwinBot] Incident self-healing manager initialized.');
+void logThought('[TwinBot] Local-state backup automation initialized.');
+void logThought('[TwinBot] Runtime budget governor initialized.');
+// ── Proactive Notifier ─────────────────────────────────────────────────────
+const proactiveEnabled = !!telegramUserId;
+const notifier = new ProactiveNotifier(async (target, text) => {
+    if (dispatcher) {
+        await dispatcher.sendProactive(target.platform, target.chatId, text);
+        await logThought(`[Proactive] Delivered message to ${target.platform}:${target.chatId}`);
+        return;
+    }
+    console.log(`[Proactive → ${target.platform}:${target.chatId}] ${text}`);
+    await logThought(`[Proactive] Dispatcher unavailable; message logged for ${target.platform}:${target.chatId}`);
+}, {
+    platform: 'telegram',
+    chatId: telegramUserId ?? 'unknown',
+}, proactiveEnabled);
+// Wire scheduler events to the notifier
+heartbeat.scheduler.on('job:error', (event) => {
+    void notifier.onSchedulerEvent(event);
+});
+heartbeat.scheduler.on('job:done', (event) => {
+    void notifier.onSchedulerEvent(event);
+});
+// Wire file watcher events to the notifier
+fileWatcher.onEvent((event) => {
+    void notifier.onFileEvent(event);
+});
+// Start file watchers
+void fileWatcher.startAll().catch((err) => {
+    console.error('[TwinBot] Failed to start file watchers:', err);
+});
+// ── Control Plane HTTP API ───────────────────────────────────────────────────
+import { startApiServer } from './api/router.js';
+import { WsHub } from './api/websocket-hub.js';
+import { RuntimeEventProducer } from './api/runtime-event-producer.js';
+const wsHub = new WsHub();
+const runtimeEventProducer = new RuntimeEventProducer({
+    hub: wsHub,
+    incidentManager,
+    budgetGovernor: runtimeBudgetGovernor,
+    dispatcher: dispatcher ?? undefined,
+    modelRouter,
+});
+const apiPort = Number(getConfigValue('API_PORT')) || 18789;
+startApiServer({
+    heartbeat,
+    skillRegistry,
+    mcpManager,
+    gateway,
+    dispatcher: dispatcher ?? undefined,
+    incidentManager,
+    budgetGovernor: runtimeBudgetGovernor,
+    localStateBackup,
+    modelRouter,
+    wsHub,
+});
+runtimeEventProducer.start();
+async function waitForStartupHealthProbe(port, timeoutMs = 30_000, intervalMs = 500) {
+    const healthUrl = `http://localhost:${port}/health`;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+        try {
+            const response = await fetch(healthUrl, {
+                method: 'GET',
+                headers: { accept: 'application/json' },
+                signal: AbortSignal.timeout(2_000),
+            });
+            if (response.ok) {
+                const body = await response.json();
+                if (body.data?.status === 'ok' || body.data?.status === 'degraded') {
+                    return true;
+                }
+            }
+        }
+        catch {
+            // Server not ready yet, continue polling
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    return false;
+}
+void (async () => {
+    const healthOk = await waitForStartupHealthProbe(apiPort);
+    if (healthOk) {
+        console.log('[TwinBot] Startup health probe passed. Gateway is ready.');
+        void logThought('[TwinBot] Startup health probe passed.');
+    }
+    else {
+        console.error('[TwinBot] Startup health probe failed within timeout. Gateway may not be healthy.');
+        void logThought('[TwinBot] Startup health probe FAILED.');
+    }
+})();
+// ── Signal Handlers ──────────────────────────────────────────────────────────
+process.on('SIGINT', () => {
+    heartbeat.stop();
+    incidentManager.stop();
+    localStateBackup.stop();
+    runtimeEventProducer.stop();
+    wsHub.stop();
+    if (dispatcher) {
+        dispatcher.queue.stop();
+        dispatcher.shutdown();
+    }
+    void fileWatcher.stopAll();
+    void mcpManager.disconnectAll();
+    void logThought('TwinBot process received SIGINT; services stopped.');
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    heartbeat.stop();
+    incidentManager.stop();
+    localStateBackup.stop();
+    runtimeEventProducer.stop();
+    wsHub.stop();
+    if (dispatcher) {
+        dispatcher.queue.stop();
+        dispatcher.shutdown();
+    }
+    void fileWatcher.stopAll();
+    void mcpManager.disconnectAll();
+    void logThought('TwinBot process received SIGTERM; services stopped.');
+    process.exit(0);
+});
+// ── Entry Point ──────────────────────────────────────────────────────────────
+if (isSetupMode) {
+    runSetupWizard().catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[TwinBot] Setup wizard failed: ${message}`);
+        process.exit(1);
+    });
+}
+else if (process.argv.includes('--onboard')) {
+    runOnboarding().catch(console.error);
+}
+else {
+    startBasicREPL(gateway);
+}