pikiloop 0.4.0

package/dist/dashboard/runtime.js

@@ -0,0 +1,410 @@
+/**
+ * runtime.ts — Singleton module holding the runtime state previously
+ * scattered across startDashboard() closure variables.
+ *
+ * Provides bot ref management, runtime prefs (agent/model/effort),
+ * channel state caching, and validated setup state construction.
+ */
+import { EventEmitter } from 'node:events';
+import { applyChannelEnvFallback, loadUserConfig, resolveUserWorkdir } from '../core/config/user-config.js';
+import { listAgents, resolveDefaultAgent } from '../agent/index.js';
+import { collectSetupState } from '../cli/onboarding.js';
+import { validateDingtalkConfig, validateDiscordConfig, validateFeishuConfig, validateSlackConfig, validateTelegramConfig, validateWecomConfig, validateWeixinConfig, } from '../core/config/validation.js';
+import { shouldCacheChannelStates } from '../channels/states.js';
+import { DASHBOARD_TIMEOUTS } from '../core/constants.js';
+import { withTimeoutFallback } from '../core/utils.js';
+import { writeScopedLog } from '../core/logging.js';
+import { DEFAULT_AGENT_EFFORTS, DEFAULT_AGENT_MODELS, resolveAgentEffort, resolveAgentModel, resolveAgentWorkflowEnabled, resolveClaudeAccessMode, setAgentEffortEnv, setAgentModelEnv, setAgentWorkflowEnv, setClaudeAccessModeEnv, } from '../core/config/runtime-config.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const CHANNEL_STATUS_VALIDATION_TIMEOUT_MS = DASHBOARD_TIMEOUTS.channelStatusValidation;
+const CHANNEL_STATUS_CACHE_TTL_MS = DASHBOARD_TIMEOUTS.channelStatusCacheTtl;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function buildLocalChannelStates(rawConfig) {
+    // Hydrate env-only channel tokens (docker / systemd) so the dashboard
+    // doesn't report "missing" when the operator passed `-e TELEGRAM_BOT_TOKEN=…`
+    // instead of editing setting.json.
+    const config = applyChannelEnvFallback(rawConfig);
+    const weixinBaseUrl = String(config.weixinBaseUrl || '').trim();
+    const weixinBotToken = String(config.weixinBotToken || '').trim();
+    const weixinAccountId = String(config.weixinAccountId || '').trim();
+    const weixinConfigured = !!(weixinBaseUrl || weixinBotToken || weixinAccountId);
+    const weixinReady = !!(weixinBaseUrl && weixinBotToken && weixinAccountId);
+    const telegramConfigured = !!String(config.telegramBotToken || '').trim();
+    const feishuAppId = String(config.feishuAppId || '').trim();
+    const feishuSecret = String(config.feishuAppSecret || '').trim();
+    const feishuConfigured = !!(feishuAppId || feishuSecret);
+    const feishuReady = !!(feishuAppId && feishuSecret);
+    const slackBot = String(config.slackBotToken || '').trim();
+    const slackApp = String(config.slackAppToken || '').trim();
+    const slackConfigured = !!(slackBot || slackApp);
+    const slackReady = !!(slackBot && slackApp);
+    const discordToken = String(config.discordBotToken || '').trim();
+    const discordConfigured = !!discordToken;
+    const dingtalkId = String(config.dingtalkClientId || '').trim();
+    const dingtalkSecret = String(config.dingtalkClientSecret || '').trim();
+    const dingtalkConfigured = !!(dingtalkId || dingtalkSecret);
+    const dingtalkReady = !!(dingtalkId && dingtalkSecret);
+    const wecomId = String(config.wecomBotId || '').trim();
+    const wecomSecret = String(config.wecomBotSecret || '').trim();
+    const wecomConfigured = !!(wecomId || wecomSecret);
+    const wecomReady = !!(wecomId && wecomSecret);
+    return [
+        {
+            channel: 'weixin',
+            configured: weixinConfigured,
+            ready: false,
+            validated: false,
+            status: !weixinConfigured ? 'missing' : weixinReady ? 'checking' : 'invalid',
+            detail: !weixinConfigured
+                ? 'Weixin is not configured.'
+                : weixinReady
+                    ? 'Validating Weixin credentials...'
+                    : 'Base URL, Bot Token, and Account ID are required.',
+        },
+        {
+            channel: 'telegram',
+            configured: telegramConfigured,
+            ready: false,
+            validated: false,
+            status: telegramConfigured ? 'checking' : 'missing',
+            detail: telegramConfigured ? 'Validating Telegram credentials…' : 'Telegram is not configured.',
+        },
+        {
+            channel: 'feishu',
+            configured: feishuConfigured,
+            ready: false,
+            validated: false,
+            status: !feishuConfigured ? 'missing' : feishuReady ? 'checking' : 'invalid',
+            detail: !feishuConfigured
+                ? 'Feishu credentials are not configured.'
+                : feishuReady
+                    ? 'Validating Feishu credentials…'
+                    : 'Both App ID and App Secret are required.',
+        },
+        {
+            channel: 'slack',
+            configured: slackConfigured,
+            ready: false,
+            validated: false,
+            status: !slackConfigured ? 'missing' : slackReady ? 'checking' : 'invalid',
+            detail: !slackConfigured
+                ? 'Slack is not configured.'
+                : slackReady
+                    ? 'Validating Slack credentials…'
+                    : 'Both Bot Token (xoxb-) and App-Level Token (xapp-) are required.',
+        },
+        {
+            channel: 'discord',
+            configured: discordConfigured,
+            ready: false,
+            validated: false,
+            status: discordConfigured ? 'checking' : 'missing',
+            detail: discordConfigured ? 'Validating Discord credentials…' : 'Discord is not configured.',
+        },
+        {
+            channel: 'dingtalk',
+            configured: dingtalkConfigured,
+            ready: false,
+            validated: false,
+            status: !dingtalkConfigured ? 'missing' : dingtalkReady ? 'checking' : 'invalid',
+            detail: !dingtalkConfigured
+                ? 'DingTalk is not configured.'
+                : dingtalkReady
+                    ? 'Validating DingTalk credentials…'
+                    : 'Both Client ID and Client Secret are required.',
+        },
+        {
+            channel: 'wecom',
+            configured: wecomConfigured,
+            ready: false,
+            validated: false,
+            status: !wecomConfigured ? 'missing' : wecomReady ? 'checking' : 'invalid',
+            detail: !wecomConfigured
+                ? 'WeChat Work is not configured.'
+                : wecomReady
+                    ? 'Validating WeChat Work credentials…'
+                    : 'Both Bot ID and Bot Secret are required.',
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// Runtime singleton
+// ---------------------------------------------------------------------------
+class Runtime {
+    botRef = null;
+    runtimePrefs = { models: {}, efforts: {}, workflow: {}, accessMode: {} };
+    /** Dashboard event bus — WebSocket connections subscribe to this. */
+    events = new EventEmitter();
+    /** Emit a dashboard event to all connected WebSocket clients. */
+    emitDashboardEvent(event) {
+        this.events.emit('dashboard-event', event);
+    }
+    /**
+     * Per-channel validation cache. Keyed by channel name so that changing
+     * one channel's credentials (or the channels array) doesn't invalidate
+     * the cached validation result for unrelated channels — which would
+     * otherwise flicker their UI status to "Validating…" until the next
+     * poll completes.
+     */
+    channelStateCache = new Map();
+    knownAgents = new Set(['claude', 'codex', 'gemini', 'hermes']);
+    defaultModels = DEFAULT_AGENT_MODELS;
+    defaultEfforts = DEFAULT_AGENT_EFFORTS;
+    // -- Bot ref management --
+    getBotRef() {
+        return this.botRef;
+    }
+    attachBot(bot) {
+        this.botRef = bot;
+        if (this.runtimePrefs.defaultAgent)
+            bot.setDefaultAgent(this.runtimePrefs.defaultAgent);
+        for (const [agent, model] of Object.entries(this.runtimePrefs.models)) {
+            if (this.isAgent(agent) && typeof model === 'string' && model.trim())
+                bot.setModelForAgent(agent, model);
+        }
+        for (const [agent, effort] of Object.entries(this.runtimePrefs.efforts)) {
+            if (this.isAgent(agent) && typeof effort === 'string' && effort.trim())
+                bot.setEffortForAgent(agent, effort);
+        }
+        for (const [agent, enabled] of Object.entries(this.runtimePrefs.workflow)) {
+            if (this.isAgent(agent) && typeof enabled === 'boolean')
+                bot.setWorkflowEnabledForAgent(agent, enabled);
+        }
+        for (const [agent, mode] of Object.entries(this.runtimePrefs.accessMode)) {
+            if (agent === 'claude' && (mode === 'subscription' || mode === 'api'))
+                bot.setClaudeAccessMode(mode);
+        }
+        // Wire stream snapshots → dashboard WebSocket
+        const prevPhases = new Map();
+        bot.onStreamSnapshot((sessionKey, snapshot) => {
+            this.emitDashboardEvent({ type: 'stream-update', key: sessionKey, snapshot });
+            // Emit sessions-changed on phase *transitions* (not every snapshot update)
+            // so the sidebar refreshes when a session starts running, finishes, etc.
+            const phase = snapshot && typeof snapshot === 'object' ? snapshot.phase : null;
+            const prev = prevPhases.get(sessionKey) ?? null;
+            if (phase !== prev) {
+                prevPhases.set(sessionKey, phase);
+                if (!phase)
+                    prevPhases.delete(sessionKey); // clean up null entries
+                this.emitDashboardEvent({ type: 'sessions-changed', key: sessionKey });
+            }
+        });
+    }
+    // -- Type guards --
+    isAgent(value) {
+        return typeof value === 'string' && this.knownAgents.has(value);
+    }
+    // -- Workdir --
+    getRuntimeWorkdir(config) {
+        return this.botRef?.workdir || resolveUserWorkdir({ config });
+    }
+    getRequestWorkdir(config = loadUserConfig()) {
+        return this.getRuntimeWorkdir(config);
+    }
+    // -- Agent / model / effort --
+    getRuntimeDefaultAgent(config) {
+        if (this.botRef)
+            return this.botRef.defaultAgent;
+        // No bot yet (e.g. setup flow): resolve the stored preference (baseline
+        // 'codex' when unset) against installed CLIs so the dashboard never
+        // surfaces an uninstalled default the user can't run.
+        const preferred = this.runtimePrefs.defaultAgent || config.defaultAgent || 'codex';
+        return resolveDefaultAgent(preferred, listAgents().agents);
+    }
+    setModelEnv(agent, value) {
+        setAgentModelEnv(agent, value);
+    }
+    setEffortEnv(agent, value) {
+        setAgentEffortEnv(agent, value);
+    }
+    setWorkflowEnv(agent, value) {
+        setAgentWorkflowEnv(agent, value);
+    }
+    setClaudeAccessModeEnv(value) {
+        setClaudeAccessModeEnv(value);
+    }
+    getRuntimeModel(agent, config = loadUserConfig()) {
+        if (this.botRef)
+            return this.botRef.modelForAgent(agent) || this.defaultModels[agent];
+        return String(this.runtimePrefs.models[agent] || resolveAgentModel(config, agent)).trim();
+    }
+    getRuntimeEffort(agent, config = loadUserConfig()) {
+        if (this.botRef)
+            return this.botRef.effortForAgent(agent);
+        const value = String(this.runtimePrefs.efforts[agent] || resolveAgentEffort(config, agent) || '').trim().toLowerCase();
+        return value || null;
+    }
+    getRuntimeWorkflowEnabled(agent, config = loadUserConfig()) {
+        if (this.botRef)
+            return this.botRef.workflowEnabledForAgent(agent);
+        const pref = this.runtimePrefs.workflow[agent];
+        if (typeof pref === 'boolean')
+            return pref;
+        return resolveAgentWorkflowEnabled(config, agent);
+    }
+    getRuntimeClaudeAccessMode(config = loadUserConfig()) {
+        if (this.botRef)
+            return this.botRef.claudeAccessMode;
+        const pref = this.runtimePrefs.accessMode.claude;
+        if (pref === 'subscription' || pref === 'api')
+            return pref;
+        return resolveClaudeAccessMode(config);
+    }
+    // -- Channel state cache --
+    credKeyForChannel(channel, config) {
+        switch (channel) {
+            case 'weixin':
+                return JSON.stringify({
+                    baseUrl: String(config.weixinBaseUrl || '').trim(),
+                    token: String(config.weixinBotToken || '').trim(),
+                    accountId: String(config.weixinAccountId || '').trim(),
+                });
+            case 'telegram':
+                return JSON.stringify({
+                    token: String(config.telegramBotToken || '').trim(),
+                    allowed: String(config.telegramAllowedChatIds || '').trim(),
+                });
+            case 'feishu':
+                return JSON.stringify({
+                    appId: String(config.feishuAppId || '').trim(),
+                    appSecret: String(config.feishuAppSecret || '').trim(),
+                });
+            case 'slack':
+                return JSON.stringify({
+                    botToken: String(config.slackBotToken || '').trim(),
+                    appToken: String(config.slackAppToken || '').trim(),
+                });
+            case 'discord':
+                return JSON.stringify({ botToken: String(config.discordBotToken || '').trim() });
+            case 'dingtalk':
+                return JSON.stringify({
+                    clientId: String(config.dingtalkClientId || '').trim(),
+                    clientSecret: String(config.dingtalkClientSecret || '').trim(),
+                });
+            case 'wecom':
+                return JSON.stringify({
+                    botId: String(config.wecomBotId || '').trim(),
+                    botSecret: String(config.wecomBotSecret || '').trim(),
+                });
+        }
+    }
+    validateChannel(channel, config) {
+        switch (channel) {
+            case 'weixin':
+                // The Weixin getupdates endpoint is a long-poll that holds the
+                // connection open for ~8s by default. For dashboard validation we
+                // only care whether the credentials are accepted (bad creds return
+                // an errcode quickly; good creds simply hold the poll). Use a
+                // tight internal timeout so we resolve well within the dashboard's
+                // CHANNEL_STATUS_VALIDATION_TIMEOUT_MS window — the abort path
+                // returns ret=0 which is treated as "valid".
+                return validateWeixinConfig(config.weixinBaseUrl, config.weixinBotToken, config.weixinAccountId, { timeoutMs: 2_000 }).then(r => r.state);
+            case 'telegram':
+                return validateTelegramConfig(config.telegramBotToken, config.telegramAllowedChatIds).then(r => r.state);
+            case 'feishu':
+                return validateFeishuConfig(config.feishuAppId, config.feishuAppSecret).then(r => r.state);
+            case 'slack':
+                return validateSlackConfig(config.slackBotToken, config.slackAppToken).then(r => r.state);
+            case 'discord':
+                return validateDiscordConfig(config.discordBotToken).then(r => r.state);
+            case 'dingtalk':
+                return validateDingtalkConfig(config.dingtalkClientId, config.dingtalkClientSecret).then(r => r.state);
+            case 'wecom':
+                return validateWecomConfig(config.wecomBotId, config.wecomBotSecret).then(r => r.state);
+        }
+    }
+    async resolveChannelStates(rawConfig) {
+        const config = applyChannelEnvFallback(rawConfig);
+        const now = Date.now();
+        const fallback = buildLocalChannelStates(config);
+        // Channels listed in the same order as buildLocalChannelStates().
+        const channelOrder = fallback.map(state => state.channel);
+        const plans = channelOrder.map((channel, idx) => {
+            const key = this.credKeyForChannel(channel, config);
+            const cached = this.channelStateCache.get(channel);
+            if (cached && cached.key === key && cached.expiresAt > now) {
+                return { channel, key, cached: cached.state, livePromise: null, fallback: fallback[idx] };
+            }
+            return { channel, key, cached: null, livePromise: this.validateChannel(channel, config), fallback: fallback[idx] };
+        });
+        const resolved = await Promise.all(plans.map(plan => {
+            if (plan.cached)
+                return Promise.resolve(plan.cached);
+            return withTimeoutFallback(plan.livePromise, CHANNEL_STATUS_VALIDATION_TIMEOUT_MS, plan.fallback);
+        }));
+        // Persist freshly-validated channels into the per-channel cache. If a
+        // channel's validation timed out, keep the live promise alive in the
+        // background so the next dashboard poll can pick up the real result
+        // instantly instead of re-issuing the network call.
+        plans.forEach((plan, i) => {
+            if (!plan.livePromise)
+                return;
+            const state = resolved[i];
+            if (shouldCacheChannelStates([state])) {
+                this.channelStateCache.set(plan.channel, {
+                    key: plan.key,
+                    expiresAt: now + CHANNEL_STATUS_CACHE_TTL_MS,
+                    state,
+                });
+                return;
+            }
+            void plan.livePromise.then(bgState => {
+                if (!shouldCacheChannelStates([bgState]))
+                    return;
+                // Skip if newer credentials have replaced the cache for this channel.
+                const current = this.channelStateCache.get(plan.channel);
+                if (current && current.key !== plan.key)
+                    return;
+                this.channelStateCache.set(plan.channel, {
+                    key: plan.key,
+                    expiresAt: Date.now() + CHANNEL_STATUS_CACHE_TTL_MS,
+                    state: bgState,
+                });
+            }).catch(() => { });
+        });
+        return resolved;
+    }
+    // -- Setup state --
+    getSetupState(config = loadUserConfig(), agentOptions = {}) {
+        const agents = listAgents(agentOptions).agents;
+        const channels = buildLocalChannelStates(applyChannelEnvFallback(config));
+        const readyChannel = channels.find(channel => channel.ready)?.channel;
+        const configuredChannel = channels.find(channel => channel.configured)?.channel;
+        return collectSetupState({
+            agents,
+            channel: readyChannel || configuredChannel || 'telegram',
+            tokenProvided: channels.some(channel => channel.configured),
+            channels,
+        });
+    }
+    async buildValidatedSetupState(config = loadUserConfig(), agentOptions = {}) {
+        const agents = listAgents(agentOptions).agents;
+        const channels = await this.resolveChannelStates(config);
+        const readyChannel = channels.find(channel => channel.ready)?.channel;
+        const configuredChannel = channels.find(channel => channel.configured)?.channel;
+        return collectSetupState({
+            agents,
+            channel: readyChannel || configuredChannel || 'telegram',
+            tokenProvided: channels.some(channel => channel.configured),
+            channels,
+        });
+    }
+    // -- Logging --
+    log(message, level = 'info') {
+        writeScopedLog('dashboard', message, { level });
+    }
+    debug(message) {
+        this.log(message, 'debug');
+    }
+    warn(message) {
+        this.log(message, 'warn');
+    }
+}
+// ---------------------------------------------------------------------------
+// Singleton export
+// ---------------------------------------------------------------------------
+export const runtime = new Runtime();

package/dist/dashboard/server.js

@@ -0,0 +1,237 @@
+/**
+ * Hono-based dashboard HTTP server: static files and API routes.
+ */
+import http from 'node:http';
+import { Hono } from 'hono';
+import { getRequestListener } from '@hono/node-server';
+import { serveStatic } from '@hono/node-server/serve-static';
+import path from 'node:path';
+import fs from 'node:fs';
+import { exec } from 'node:child_process';
+import { WebSocketServer } from 'ws';
+import configRoutes from './routes/config.js';
+import agentRoutes, { preloadAgentStatus } from './routes/agents.js';
+import sessionRoutes from './routes/sessions.js';
+import extensionRoutes from './routes/extensions.js';
+import cliRoutes from './routes/cli.js';
+import modelsRoutes from './routes/models.js';
+import localModelsRoutes from './routes/local-models.js';
+import { runtime } from './runtime.js';
+import { registerProcessRuntime } from '../core/process-control.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DASHBOARD_PORT_RETRY_LIMIT = 10;
+const WS_KEEPALIVE_MS = 25_000;
+function attachWebSocketServer(httpServer) {
+    const wss = new WebSocketServer({ noServer: true });
+    const clients = new Set();
+    httpServer.on('upgrade', (req, socket, head) => {
+        const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+        if (url.pathname !== '/ws') {
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            wss.emit('connection', ws, req);
+        });
+    });
+    wss.on('connection', (ws) => {
+        clients.add(ws);
+        const keepalive = setInterval(() => {
+            if (ws.readyState === ws.OPEN)
+                ws.ping();
+        }, WS_KEEPALIVE_MS);
+        ws.on('message', (raw) => {
+            try {
+                const msg = JSON.parse(String(raw));
+                if (msg?.type === 'ping') {
+                    ws.send(JSON.stringify({ type: 'pong' }));
+                }
+            }
+            catch { /* ignore malformed messages */ }
+        });
+        ws.on('close', () => {
+            clients.delete(ws);
+            clearInterval(keepalive);
+        });
+        ws.on('error', () => {
+            clients.delete(ws);
+            clearInterval(keepalive);
+        });
+    });
+    const onEvent = (event) => {
+        const data = JSON.stringify(event);
+        for (const ws of clients) {
+            if (ws.readyState === ws.OPEN) {
+                ws.send(data);
+            }
+        }
+    };
+    runtime.events.on('dashboard-event', onEvent);
+    const closeAllClients = () => {
+        runtime.events.off('dashboard-event', onEvent);
+        for (const ws of clients)
+            ws.close();
+        clients.clear();
+        wss.close();
+    };
+    httpServer.on('close', closeAllClients);
+    return { closeAllClients };
+}
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+export async function startDashboard(opts = {}) {
+    const preferredPort = opts.port || 3939;
+    if (opts.bot)
+        runtime.attachBot(opts.bot);
+    const app = new Hono();
+    // -- API routes --
+    app.route('/', configRoutes);
+    app.route('/', agentRoutes);
+    app.route('/', sessionRoutes);
+    app.route('/', extensionRoutes);
+    app.route('/', cliRoutes);
+    app.route('/', modelsRoutes);
+    app.route('/', localModelsRoutes);
+    // -- Static files: serve dashboard build output --
+    // Resolve path relative to this file's location (src/ or dist/)
+    const dashboardRoot = path.resolve(import.meta.dirname, '..', '..', 'dashboard', 'dist');
+    // Serve /assets/* for Vite-hashed JS/CSS bundles. Filenames are
+    // content-hashed, so they can be cached indefinitely — a new build emits
+    // new filenames rather than mutating these.
+    app.use('/assets/*', serveStatic({
+        root: dashboardRoot,
+        onFound: (_path, c) => {
+            c.header('Cache-Control', 'public, max-age=31536000, immutable');
+        },
+    }));
+    // Serve other static files at root level (favicon, manifest, etc.).
+    // This mount also serves index.html for "/" (directory index), so the HTML
+    // shell is tagged no-cache here too — same reason as the SPA fallback below.
+    app.use('/*', serveStatic({
+        root: dashboardRoot,
+        onFound: (p, c) => {
+            if (p.endsWith('.html'))
+                c.header('Cache-Control', 'no-cache');
+        },
+        onNotFound: () => {
+            // Fall through to the SPA catch-all below
+        },
+    }));
+    // SPA fallback: serve index.html for all non-API routes
+    app.get('*', async (c) => {
+        // Don't catch API routes that fell through (shouldn't happen, but guard anyway)
+        if (c.req.path.startsWith('/api/')) {
+            return c.json({ error: 'Not Found' }, 404);
+        }
+        const indexPath = path.join(dashboardRoot, 'index.html');
+        try {
+            const html = fs.readFileSync(indexPath, 'utf-8');
+            // The HTML shell references content-hashed asset filenames, so it must
+            // never be cached: otherwise an open tab keeps loading stale JS after the
+            // server self-updates (npx pikiloop@latest) until a manual hard refresh.
+            c.header('Cache-Control', 'no-cache');
+            return c.html(html);
+        }
+        catch {
+            return c.text('Dashboard build not found. Run: npm run build:dashboard', 500);
+        }
+    });
+    // -- Process runtime registration --
+    let nodeServer = null;
+    let wsHandle = null;
+    const RESTART_CLOSE_TIMEOUT_MS = 3000;
+    const unregisterProcessRuntime = registerProcessRuntime({
+        label: 'dashboard',
+        prepareForRestart: () => new Promise(resolve => {
+            if (!nodeServer) {
+                resolve();
+                return;
+            }
+            // Close all WebSocket clients first — otherwise server.close() hangs
+            // waiting for persistent connections to end.
+            wsHandle?.closeAllClients();
+            const timer = setTimeout(resolve, RESTART_CLOSE_TIMEOUT_MS);
+            nodeServer.close(() => { clearTimeout(timer); resolve(); });
+        }),
+    });
+    // -- Start server with port retry --
+    return new Promise((resolve, reject) => {
+        let nextPort = preferredPort;
+        let settled = false;
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        };
+        function tryListen(port) {
+            try {
+                // Create HTTP server manually so we can attach WebSocket upgrade handler
+                // before Hono's request listener consumes the connection.
+                const requestListener = getRequestListener(app.fetch);
+                const server = http.createServer(requestListener);
+                // Attach WebSocket BEFORE listening — ensures upgrade events are captured
+                wsHandle = attachWebSocketServer(server);
+                server.listen(port, () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    nodeServer = server;
+                    const addr = server.address();
+                    const actualPort = typeof addr === 'object' && addr ? addr.port : port;
+                    const dashUrl = `http://localhost:${actualPort}`;
+                    const ts = new Date().toTimeString().slice(0, 8);
+                    process.stdout.write(`[pikiloop ${ts}] dashboard: ${dashUrl}\n`);
+                    // Preload agent status cache so the first dashboard page load is instant
+                    preloadAgentStatus();
+                    if (opts.open !== false) {
+                        const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+                        exec(`${cmd} ${dashUrl}`);
+                    }
+                    resolve({
+                        port: actualPort,
+                        url: dashUrl,
+                        attachBot(bot) {
+                            runtime.attachBot(bot);
+                        },
+                        close() {
+                            return new Promise(resolveClose => {
+                                unregisterProcessRuntime();
+                                if (!server) {
+                                    resolveClose();
+                                    return;
+                                }
+                                server.close(() => resolveClose());
+                            });
+                        },
+                    });
+                });
+                // Handle EADDRINUSE by retrying on next port
+                server.on('error', (err) => {
+                    if (settled)
+                        return;
+                    if (err.code === 'EADDRINUSE') {
+                        if (nextPort >= preferredPort + DASHBOARD_PORT_RETRY_LIMIT) {
+                            fail(new Error(`Dashboard ports ${preferredPort}-${preferredPort + DASHBOARD_PORT_RETRY_LIMIT} are already in use.`));
+                            return;
+                        }
+                        nextPort += 1;
+                        tryListen(nextPort);
+                        return;
+                    }
+                    fail(err);
+                });
+                server.on('close', () => {
+                    unregisterProcessRuntime();
+                });
+            }
+            catch (err) {
+                fail(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        tryListen(preferredPort);
+    });
+}