pikiloom 0.4.26 → 0.4.27

package/dist/dashboard/routes/sessions.js

@@ -1,6 +1,3 @@
-/**
- * Dashboard API routes: session CRUD, workspace, streaming state.
- */
 import { Hono } from 'hono';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -15,9 +12,6 @@ import { cancelSessionTask, stopSessionTasks, getSessionStreamState, queueDashbo
 import { querySessions, querySessionTail, querySessionMessages, getWorkspaceOverviews, updateSession, linkSessions, buildMigrationContext, exportSession, importSession, deleteSession, loadWorkspaces, addWorkspace, removeWorkspace, updateWorkspace, } from '../../bot/session-hub.js';
 import { DASHBOARD_PAGINATION } from '../../core/constants.js';
 import { runtime } from '../runtime.js';
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
 const DEFAULT_SESSION_PAGE_SIZE = DASHBOARD_PAGINATION.defaultPageSize;
 const MAX_SESSION_PAGE_SIZE = DASHBOARD_PAGINATION.maxPageSize;
 function parsePageNumber(value, fallback = 0) {
@@ -50,9 +44,6 @@ function enrichWithRuntimeStatus(sessions, bot) {
     return sessions.map(session => {
         const status = bot ? getSessionStatusForBot(bot, session) : null;
         const isRunning = status ? status.isRunning : !!session.running;
-        // "Waiting on background work" only applies to a session that isn't
-        // currently running — surface the marker the agent parked (if any) so the
-        // dashboard can show a distinct "waiting" state instead of "completed".
         const awaiting = !isRunning && session.workdir && session.sessionId
             ? readAwaitResume(session.workdir, session.agent, session.sessionId)
             : null;
@@ -65,20 +56,12 @@ function enrichWithRuntimeStatus(sessions, bot) {
         };
     });
 }
-// Session list cards render only the *head* of these text fields (previews via
-// firstMeaningfulLine / slice / sanitize) and use them for client-side substring
-// search. A session whose last turn dumped a huge tool output or long answer would
-// otherwise ship tens of KB per card that the list never displays — on a busy
-// workspace the swim-lane ballooned to ~600KB, dominated by these fields. Cap each
-// to a preview length: previews are unchanged and search still matches the head.
-// Full text remains available from the session-detail / messages endpoints.
 const LIST_PREVIEW_FIELD_CAP = 2048;
 function capPreviewField(value) {
     return typeof value === 'string' && value.length > LIST_PREVIEW_FIELD_CAP
         ? value.slice(0, LIST_PREVIEW_FIELD_CAP)
         : value;
 }
-/** Thin a session for list/swim-lane responses by capping its heavy preview text. */
 export function projectSessionForList(session) {
     return {
         ...session,
@@ -176,14 +159,7 @@ async function parseSessionSendRequest(c) {
         cleanup: async () => { },
     };
 }
-// ---------------------------------------------------------------------------
-// Routes
-// ---------------------------------------------------------------------------
 const app = new Hono();
-// ==========================================================================
-// Legacy session routes (backward-compat for dashboard-ui)
-// ==========================================================================
-// Sessions per agent: GET /api/sessions/:agent
 app.get('/api/sessions/:agent', async (c) => {
     const agent = c.req.param('agent');
     const config = loadUserConfig();
@@ -205,7 +181,6 @@ app.get('/api/sessions/:agent', async (c) => {
         ...paged,
     });
 });
-// All sessions (swim lane): GET /api/sessions
 app.get('/api/sessions', async (c) => {
     const config = loadUserConfig();
     const workdir = runtime.getRequestWorkdir(config);
@@ -231,7 +206,6 @@ app.get('/api/sessions', async (c) => {
     }));
     return c.json(swimLane);
 });
-// Session detail (tail): GET /api/session-detail/:agent/:id
 app.get('/api/session-detail/:agent/:id', async (c) => {
     const agent = c.req.param('agent');
     const sessionId = decodeURIComponent(c.req.param('id'));
@@ -245,12 +219,8 @@ app.get('/api/session-detail/:agent/:id', async (c) => {
         `messages=${tail.messages.length} error=${tail.error || '(none)'}`);
     return c.json(tail);
 });
-// ==========================================================================
-// Workspace CRUD
-// ==========================================================================
 app.get('/api/workspaces', (c) => {
     const workspaces = loadWorkspaces();
-    // Always include the current runtimeWorkdir, deduplicating by path
     const config = loadUserConfig();
     const rwd = runtime.getRuntimeWorkdir(config);
     if (rwd && !workspaces.some(w => w.path === rwd)) {
@@ -302,9 +272,6 @@ app.patch('/api/workspaces', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-// ==========================================================================
-// Workspace overviews
-// ==========================================================================
 app.get('/api/workspace-overviews', async (c) => {
     try {
         const overviews = await getWorkspaceOverviews();
@@ -314,9 +281,6 @@ app.get('/api/workspace-overviews', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-// ==========================================================================
-// Session hub operations
-// ==========================================================================
 app.post('/api/session-hub/sessions', async (c) => {
     try {
         const body = await c.req.json();
@@ -432,17 +396,7 @@ app.post('/api/session-hub/session/messages', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-// Prepare a session message read for the dashboard:
-//   1. Rewrite on-disk image/file blocks into compact attachment HTTP URLs so a
-//      remote browser can fetch the bytes (inline data: images pass through).
-//   2. Append the session's delivered artifacts (files the agent handed the
-//      user via `im_send_file`) as a trailing assistant message, so they render
-//      and stay retrievable after a reload regardless of which terminal
-//      delivered them. Only added when this window includes the conversation
-//      tail (`!hasNewer`) to avoid duplicating across paginated reads.
 function prepareSessionMessagesForDashboard(result, agent, sessionId) {
-    // Only operate in rich mode — a `rich:false` read returns plain text and must
-    // not gain a synthetic richMessages array.
     if (result.richMessages === undefined)
         return result;
     const richMessages = result.richMessages.map(message => ({
@@ -461,7 +415,6 @@ function prepareSessionMessagesForDashboard(result, agent, sessionId) {
         return result;
     return { ...result, richMessages };
 }
-/** Plain-text fallback for the delivered-artifacts message (IM tail / exports). */
 function deliveredSummaryText(blocks) {
     const names = blocks
         .map(b => b.fileName || (b.type === 'image' ? 'image' : 'file'))
@@ -470,12 +423,6 @@ function deliveredSummaryText(blocks) {
         return '';
     return names.length === 1 ? `Delivered: ${names[0]}` : `Delivered ${names.length} files: ${names.join(', ')}`;
 }
-// Attachment endpoint — serves on-disk images AND delivered files referenced by
-// RichMessage image/file blocks via opaque base64url path tokens. The allowlist
-// (see images.ts) confines reads to a known set of agent-managed dirs + the
-// session's workdir + the per-session delivered-artifacts dir. Streams the
-// bytes (no full-buffer) and supports Range so large artifacts (video,
-// archives) download/seek without pinning memory.
 app.get('/api/sessions/:agent/:id/attachment', async (c) => {
     const agent = c.req.param('agent');
     const sessionId = decodeURIComponent(c.req.param('id'));
@@ -492,16 +439,6 @@ app.get('/api/sessions/:agent/:id/attachment', async (c) => {
     if (!requestedPath || requestedPath.includes('\0')) {
         return c.json({ ok: false, error: 'invalid path' }, 400);
     }
-    // Widen the allowlist with the session's recorded workdir when known —
-    // images generated under the project tree resolve cleanly. Session indexes
-    // are per-workdir and this URL carries no workdir, so a lookup against the
-    // runtime workdir alone misses sessions living in any OTHER registered
-    // workspace (the Session Hub renders all of them through this endpoint) —
-    // their user-attached images 403'd as "broken image" in the dashboard.
-    // Registered workspace roots come from server-side config, never request
-    // input, so widening to all of them keeps the same trust boundary and also
-    // covers the pending→native id promotion window where no index has the
-    // session yet.
     const config = loadUserConfig();
     const fallbackWorkdir = runtime.getRequestWorkdir(config);
     const managed = findPikiloomSession(fallbackWorkdir, agent, sessionId);
@@ -524,14 +461,9 @@ app.get('/api/sessions/:agent/:id/attachment', async (c) => {
         return c.json({ ok: false, error: 'not a file' }, 400);
     const mime = mimeForArtifact(resolved);
     const downloadName = sanitizeDownloadName(c.req.query('n'), resolved);
-    // Inline images so <img> renders them; everything else downloads with its
-    // pristine name. RFC 5987 filename* carries non-ASCII names safely.
     const disposition = mime.startsWith('image/') ? 'inline' : 'attachment';
     const asciiName = downloadName.replace(/[^\x20-\x7e]/g, '_').replace(/"/g, "'");
     const contentDisposition = `${disposition}; filename="${asciiName}"; filename*=UTF-8''${encodeURIComponent(downloadName)}`;
-    // The path is stamp-unique for delivered artifacts and hash-immutable for
-    // agent-managed dirs (`ig_<sha>.png`, …); the session lifecycle keeps the
-    // file stable — long cache is safe.
     const baseHeaders = {
         'Content-Type': mime,
         'Content-Disposition': contentDisposition,
@@ -539,7 +471,6 @@ app.get('/api/sessions/:agent/:id/attachment', async (c) => {
         'X-Content-Type-Options': 'nosniff',
         'Accept-Ranges': 'bytes',
     };
-    // Honor a single byte-range request (e.g. video seek / resumable download).
     const range = parseByteRange(c.req.header('range'), stat.size);
     if (range) {
         const nodeStream = fs.createReadStream(resolved, { start: range.start, end: range.end });
@@ -555,16 +486,11 @@ app.get('/api/sessions/:agent/:id/attachment', async (c) => {
         'Content-Length': String(stat.size),
     });
 });
-/** Sanitize the optional `&n=` download-name hint; fall back to the basename. */
 function sanitizeDownloadName(raw, resolved) {
     const candidate = (raw || '').trim();
     const name = candidate || path.basename(resolved);
-    // Strip path separators / control chars; the on-disk path is already
-    // validated — `n` only affects the Content-Disposition filename.
     return name.replace(/[/\\\0\r\n]+/g, '_').replace(/^\.+/, '').slice(0, 200) || 'download';
 }
-/** Parse a single `bytes=start-end` range header against `size`; null if absent
- *  or unsatisfiable (caller then serves the full body). */
 function parseByteRange(header, size) {
     if (!header || size <= 0)
         return null;
@@ -580,7 +506,6 @@ function parseByteRange(header, size) {
         end = hasEnd ? parseInt(m[2], 10) : size - 1;
     }
     else if (hasEnd) {
-        // Suffix range: last N bytes.
         const suffix = parseInt(m[2], 10);
         if (suffix <= 0)
             return null;
@@ -649,9 +574,6 @@ app.post('/api/session-hub/import', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-// ==========================================================================
-// Skills
-// ==========================================================================
 app.get('/api/session-hub/skills', (c) => {
     const workdir = c.req.query('workdir') || '';
     if (!workdir)
@@ -664,9 +586,6 @@ app.get('/api/session-hub/skills', (c) => {
         return c.json({ ok: false, skills: [], error: e.message }, 500);
     }
 });
-// ==========================================================================
-// Session interaction (send / recall / steer / stream)
-// ==========================================================================
 app.post('/api/session-hub/session/send', async (c) => {
     try {
         const { workdir, agent, sessionId, prompt, model, effort, workflow, attachments, previousAgent, previousSessionId, cleanup } = await parseSessionSendRequest(c);
@@ -695,7 +614,6 @@ app.post('/api/session-hub/session/send', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-// Polling endpoint: GET /api/session-hub/session/stream-state?agent=X&sessionId=Y
 app.get('/api/session-hub/session/stream-state', (c) => {
     const agent = c.req.query('agent') || '';
     const sessionId = c.req.query('sessionId') || '';
@@ -704,9 +622,6 @@ app.get('/api/session-hub/session/stream-state', (c) => {
     }
     return c.json(getSessionStreamState(agent, sessionId));
 });
-// Fork: branch off a parent session at `atTurn`, queue the new prompt against
-// the freshly forked child. Returns the queued task + the pending child session
-// key so the dashboard can navigate the user into the child immediately.
 app.post('/api/session-hub/session/fork', async (c) => {
     try {
         const body = await c.req.json();
@@ -749,10 +664,6 @@ app.post('/api/session-hub/session/recall', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-// Stop only the currently running stream for a session — queued follow-ups
-// are kept so they run next. Takes (agent, sessionId) rather than taskId so it
-// works during the moment after a fresh send where the client hasn't yet
-// learned the streamTaskId.
 app.post('/api/session-hub/session/stop', async (c) => {
     try {
         const body = await c.req.json();
@@ -781,9 +692,6 @@ app.post('/api/session-hub/session/steer', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-// ==========================================================================
-// Persistent thread goal (analogous to Codex CLI's `/goal`).
-// ==========================================================================
 app.get('/api/session-hub/session/goal', async (c) => {
     const workdir = c.req.query('workdir') || '';
     const agent = c.req.query('agent') || '';
@@ -878,16 +786,11 @@ app.post('/api/session-hub/session/goal/clear', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-// ==========================================================================
-// Interaction prompts (human-in-the-loop)
-// ==========================================================================
-/** GET /api/interaction/:promptId — Get interaction prompt state. */
 app.get('/api/interaction/:promptId', (c) => {
     const { promptId } = c.req.param();
     const result = getInteractionPrompt(promptId);
     return c.json(result, result.ok ? 200 : 503);
 });
-/** POST /api/interaction/:promptId/select — Select an option. */
 app.post('/api/interaction/:promptId/select', async (c) => {
     try {
         const { promptId } = c.req.param();
@@ -903,7 +806,6 @@ app.post('/api/interaction/:promptId/select', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-/** POST /api/interaction/:promptId/text — Submit freeform text. */
 app.post('/api/interaction/:promptId/text', async (c) => {
     try {
         const { promptId } = c.req.param();
@@ -919,7 +821,6 @@ app.post('/api/interaction/:promptId/text', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-/** POST /api/interaction/:promptId/skip — Skip current question. */
 app.post('/api/interaction/:promptId/skip', async (c) => {
     try {
         const { promptId } = c.req.param();
@@ -930,7 +831,6 @@ app.post('/api/interaction/:promptId/skip', async (c) => {
         return c.json({ ok: false, error: e.message }, 500);
     }
 });
-/** POST /api/interaction/:promptId/cancel — Cancel interaction prompt. */
 app.post('/api/interaction/:promptId/cancel', async (c) => {
     try {
         const { promptId } = c.req.param();

package/dist/dashboard/runtime.js

@@ -1,10 +1,3 @@
-/**
- * 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';
@@ -15,18 +8,9 @@ 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();
@@ -131,30 +115,17 @@ function buildLocalChannelStates(rawConfig) {
         },
     ];
 }
-// ---------------------------------------------------------------------------
-// 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;
     }
@@ -178,40 +149,31 @@ class Runtime {
             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
+                    prevPhases.delete(sessionKey);
                 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);
     }
@@ -254,7 +216,6 @@ class Runtime {
             return pref;
         return resolveClaudeAccessMode(config);
     }
-    // -- Channel state cache --
     credKeyForChannel(channel, config) {
         switch (channel) {
             case 'weixin':
@@ -295,13 +256,6 @@ class Runtime {
     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);
@@ -321,7 +275,6 @@ class Runtime {
         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);
@@ -336,10 +289,6 @@ class Runtime {
                 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;
@@ -355,7 +304,6 @@ class Runtime {
             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;
@@ -368,7 +316,6 @@ class Runtime {
         });
         return resolved;
     }
-    // -- Setup state --
     getSetupState(config = loadUserConfig(), agentOptions = {}) {
         const agents = listAgents(agentOptions).agents;
         const channels = buildLocalChannelStates(applyChannelEnvFallback(config));
@@ -393,7 +340,6 @@ class Runtime {
             channels,
         });
     }
-    // -- Logging --
     log(message, level = 'info') {
         writeScopedLog('dashboard', message, { level });
     }
@@ -404,7 +350,4 @@ class Runtime {
         this.log(message, 'warn');
     }
 }
-// ---------------------------------------------------------------------------
-// Singleton export
-// ---------------------------------------------------------------------------
 export const runtime = new Runtime();

package/dist/dashboard/server.js

@@ -1,6 +1,3 @@
-/**
- * Hono-based dashboard HTTP server: static files and API routes.
- */
 import http from 'node:http';
 import { Hono } from 'hono';
 import { compress } from 'hono/compress';
@@ -19,30 +16,13 @@ import localModelsRoutes from './routes/local-models.js';
 import { runtime } from './runtime.js';
 import { registerProcessRuntime } from '../core/process-control.js';
 import { mountPikichannel } from '../pikichannel/server.js';
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
 const DASHBOARD_PORT_RETRY_LIMIT = 10;
-// The dashboard's live push transport is pikichannel (`/pikichannel/ws`) — the
-// same universal channel mobile/web clients use. There is no separate dashboard
-// WebSocket layer anymore; the pikichannel adapter subscribes to the runtime
-// 'dashboard-event' bus directly, so the SPA and remote clients share one stack.
-// ---------------------------------------------------------------------------
-// Server
-// ---------------------------------------------------------------------------
 export async function startDashboard(opts = {}) {
     const preferredPort = opts.port || 3939;
     if (opts.bot)
         runtime.attachBot(opts.bot);
     const app = new Hono();
-    // -- Compression --
-    // gzip/deflate every compressible response (JSON API payloads, JS/CSS bundles,
-    // the HTML shell). Session message/list endpoints ship hundreds of KB of JSON;
-    // Vite chunks are another few hundred KB raw. The middleware skips already-
-    // compressed binary types (png/ico) by content-type, so the immutable image
-    // assets pay no CPU cost. Registered first so it wraps both routes and static.
     app.use('*', compress());
-    // -- API routes --
     app.route('/', configRoutes);
     app.route('/', agentRoutes);
     app.route('/', sessionRoutes);
@@ -50,10 +30,6 @@ export async function startDashboard(opts = {}) {
     app.route('/', cliRoutes);
     app.route('/', modelsRoutes);
     app.route('/', localModelsRoutes);
-    // -- pikichannel: pluggable agent-session transport (WebSocket + WebRTC) --
-    // Mounted BEFORE the static catch-all so its routes (demo page, browser SDK,
-    // status) win. Returns a handle whose upgrade router is attached per HTTP
-    // server below. Failure here must not block the dashboard, so it is guarded.
     let pikichannel = null;
     try {
         pikichannel = await mountPikichannel(app);
@@ -61,21 +37,13 @@ export async function startDashboard(opts = {}) {
     catch (err) {
         runtime.warn(`[pikichannel] mount failed: ${err?.message || err}`);
     }
-    // -- 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) => {
@@ -83,21 +51,15 @@ export async function startDashboard(opts = {}) {
                 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 pikiloom@latest) until a manual hard refresh.
             c.header('Cache-Control', 'no-cache');
             return c.html(html);
         }
@@ -105,7 +67,6 @@ export async function startDashboard(opts = {}) {
             return c.text('Dashboard build not found. Run: npm run build:dashboard', 500);
         }
     });
-    // -- Process runtime registration --
     let nodeServer = null;
     const RESTART_CLOSE_TIMEOUT_MS = 3000;
     const unregisterProcessRuntime = registerProcessRuntime({
@@ -115,14 +76,11 @@ export async function startDashboard(opts = {}) {
                 resolve();
                 return;
             }
-            // Tear down pikichannel peers first — otherwise server.close() hangs
-            // waiting for the persistent WebSocket/datachannel connections to end.
             pikichannel?.stop();
             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;
@@ -134,13 +92,8 @@ export async function startDashboard(opts = {}) {
         };
         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);
-                // Single WebSocket-upgrade dispatcher (attached before listening so no
-                // upgrade is missed): pikichannel owns `/pikichannel/*` — its WS data
-                // channel and WebRTC signaling. Anything else is rejected.
                 server.on('upgrade', (req, socket, head) => {
                     if (pikichannel?.handleUpgrade(req, socket, head))
                         return;
@@ -156,7 +109,6 @@ export async function startDashboard(opts = {}) {
                     const dashUrl = `http://localhost:${actualPort}`;
                     const ts = new Date().toTimeString().slice(0, 8);
                     process.stdout.write(`[pikiloom ${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';
@@ -180,7 +132,6 @@ export async function startDashboard(opts = {}) {
                         },
                     });
                 });
-                // Handle EADDRINUSE by retrying on next port
                 server.on('error', (err) => {
                     if (settled)
                         return;