bosun 0.28.1 → 0.28.2

package/.env.example

@@ -169,6 +169,13 @@ TELEGRAM_MINIAPP_ENABLED=false
 # Priority threshold for immediate delivery: 1=critical only, 2=critical+errors (default: 1)
 # TELEGRAM_IMMEDIATE_PRIORITY=1
 
+# ─── Auto-Delete Old Messages ──────────────────────────────────────────────────────────
+# Automatically delete bot messages older than N days to keep chat tidy.
+# Set to 0 to disable. Default: 3 days.
+# Note: Telegram’s API may silently skip messages older than 48 h in private
+# chats — those will just remain; no error is raised.
+# TELEGRAM_HISTORY_RETENTION_DAYS=3
+
 # ─── Presence & Multi-Instance Coordination ──────────────────────────────────
 # Presence heartbeat allows discovering multiple bosun instances.
 # Heartbeat interval in seconds (default: 60)

package/README.md

@@ -5,11 +5,19 @@
 
 Bosun is a production-grade supervisor for AI coding agents. It routes tasks across executors, automates PR lifecycles, and keeps operators in control through Telegram, the Mini App dashboard, and optional WhatsApp notifications.
 
-[Website](https://bosun.virtengine.com) · [Docs](https://bosun.virtengine.com/docs/) · [GitHub](https://github.com/virtengine/bosun?tab=readme-ov-file#bosun) · [npm](https://www.npmjs.com/package/bosun) · [Issues](https://github.com/virtengine/bosun/issues)
+<p align="center">
+  <a href="https://bosun.virtengine.com">Website</a> · <a href="https://bosun.virtengine.com/docs/">Docs</a> · <a href="https://github.com/virtengine/bosun?tab=readme-ov-file#bosun">GitHub</a> · <a href="https://www.npmjs.com/package/bosun">npm</a> · <a href="https://github.com/virtengine/bosun/issues">Issues</a>
+</p>
 
-[![CI](https://github.com/virtengine/bosun/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/virtengine/bosun/actions/workflows/ci.yaml)
-[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-[![npm](https://img.shields.io/npm/v/bosun.svg)](https://www.npmjs.com/package/bosun)
+<p align="center">
+  <img src="site/social-banner.png" alt="bosun — AI agent supervisor" width="100%" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/virtengine/bosun/actions/workflows/ci.yaml"><img src="https://github.com/virtengine/bosun/actions/workflows/ci.yaml/badge.svg?branch=main" alt="CI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License" /></a>
+  <a href="https://www.npmjs.com/package/bosun"><img src="https://img.shields.io/npm/v/bosun.svg" alt="npm" /></a>
+</p>
 
 ---
 

package/desktop/launch.mjs

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync, spawn } from "node:child_process";
@@ -7,6 +7,28 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const desktopDir = resolve(__dirname);
 const binName = process.platform === "win32" ? "electron.cmd" : "electron";
 const electronBin = resolve(desktopDir, "node_modules", ".bin", binName);
+const chromeSandbox = resolve(
+  desktopDir,
+  "node_modules",
+  "electron",
+  "dist",
+  "chrome-sandbox",
+);
+
+function shouldDisableSandbox() {
+  if (process.env.BOSUN_DESKTOP_DISABLE_SANDBOX === "1") return true;
+  if (process.platform !== "linux") return false;
+  if (!existsSync(chromeSandbox)) return true;
+  try {
+    const stats = statSync(chromeSandbox);
+    const mode = stats.mode & 0o7777;
+    const isRootOwned = stats.uid === 0;
+    const isSetuid = mode === 0o4755;
+    return !(isRootOwned && isSetuid);
+  } catch {
+    return true;
+  }
+}
 
 function ensureElectronInstalled() {
   if (existsSync(electronBin)) return true;
@@ -28,11 +50,18 @@ function launch() {
     process.exit(1);
   }
 
-  const child = spawn(electronBin, [desktopDir], {
+  const disableSandbox = shouldDisableSandbox();
+  const args = [desktopDir];
+  if (disableSandbox) {
+    args.push("--no-sandbox", "--disable-gpu-sandbox");
+  }
+
+  const child = spawn(electronBin, args, {
     stdio: "inherit",
     env: {
       ...process.env,
       BOSUN_DESKTOP: "1",
+      ...(disableSandbox ? { ELECTRON_DISABLE_SANDBOX: "1" } : {}),
     },
   });
 

package/desktop/main.mjs

@@ -1,4 +1,4 @@
-import { app, BrowserWindow } from "electron";
+import { app, BrowserWindow, session } from "electron";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { existsSync, readFileSync } from "node:fs";
@@ -18,6 +18,19 @@ let runtimeConfigLoaded = false;
 
 const DAEMON_PID_FILE = resolve(homedir(), ".cache", "bosun", "daemon.pid");
 
+// Local/private-network patterns — TLS cert bypass for the embedded UI server
+const LOCAL_HOSTNAME_RE = [
+  /^127\./,
+  /^192\.168\./,
+  /^10\./,
+  /^172\.(1[6-9]|2[0-9]|3[01])\./,
+  /^::1$/,
+  /^localhost$/i,
+];
+function isLocalHost(hostname) {
+  return LOCAL_HOSTNAME_RE.some((re) => re.test(hostname));
+}
+
 function parseBoolEnv(value, fallback) {
   if (value === undefined || value === null) return fallback;
   const normalized = String(value).trim().toLowerCase();
@@ -163,7 +176,7 @@ async function resolveDaemonUiUrl() {
 async function ensureDaemonRunning() {
   const autoStart = parseBoolEnv(
     process.env.BOSUN_DESKTOP_AUTO_START_DAEMON,
-    true,
+    false,
   );
   if (!autoStart) return;
 
@@ -239,6 +252,7 @@ async function buildUiUrl() {
 
 async function createMainWindow() {
   if (mainWindow) return;
+  const iconPath = resolveBosunRuntimePath("logo.png");
 
   mainWindow = new BrowserWindow({
     width: 1280,
@@ -246,6 +260,7 @@ async function createMainWindow() {
     minWidth: 960,
     minHeight: 640,
     backgroundColor: "#0b0b0c",
+    ...(existsSync(iconPath) ? { icon: iconPath } : {}),
     show: false,
     webPreferences: {
       contextIsolation: true,
@@ -269,9 +284,34 @@ async function createMainWindow() {
 
 async function bootstrap() {
   try {
+    if (process.env.ELECTRON_DISABLE_SANDBOX === "1") {
+      app.commandLine.appendSwitch("no-sandbox");
+      app.commandLine.appendSwitch("disable-gpu-sandbox");
+    }
     app.setAppUserModelId("com.virtengine.bosun");
+    const iconPath = resolveBosunRuntimePath("logo.png");
+    if (existsSync(iconPath)) {
+      try {
+        app.setIcon(iconPath);
+      } catch {
+        /* best effort */
+      }
+    }
     process.chdir(resolveBosunRoot());
     await loadRuntimeConfig();
+
+    // Bypass TLS verification for the local embedded UI server.
+    // setCertificateVerifyProc works at the OpenSSL level — it fires before
+    // the higher-level `certificate-error` event and stops the repeated
+    // "handshake failed" logs from Chromium's ssl_client_socket_impl.
+    session.defaultSession.setCertificateVerifyProc((request, callback) => {
+      if (isLocalHost(request.hostname)) {
+        callback(0); // 0 = verified OK
+        return;
+      }
+      callback(-3); // -3 = use Chromium default chain verification
+    });
+
     await ensureDaemonRunning();
     await createMainWindow();
     await maybeAutoUpdate();
@@ -331,10 +371,15 @@ app.on("before-quit", () => {
 app.on(
   "certificate-error",
   (event, _webContents, url, _error, _certificate, callback) => {
-    if (uiOrigin && url.startsWith(uiOrigin)) {
-      event.preventDefault();
-      callback(true);
-      return;
+    try {
+      const hostname = new URL(url).hostname;
+      if ((uiOrigin && url.startsWith(uiOrigin)) || isLocalHost(hostname)) {
+        event.preventDefault();
+        callback(true);
+        return;
+      }
+    } catch {
+      // malformed URL — fall through
     }
     callback(false);
   },

package/desktop/package.json

@@ -3,6 +3,14 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
+  "author": "VirtEngine Maintainers <hello@virtengine.com>",
+  "homepage": "https://bosun.virtengine.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/virtengine/bosun.git",
+    "directory": "/desktop"
+  },
+
   "main": "main.mjs",
   "description": "Electron wrapper for the Bosun desktop portal",
   "scripts": {

package/desktop-shortcut.mjs

@@ -9,7 +9,7 @@
  * - Linux:   .desktop entry
  */
 
-import { spawnSync } from "node:child_process";
+import { spawnSync, execSync } from "node:child_process";
 import {
   existsSync,
   readFileSync,
@@ -182,22 +182,41 @@ function installMacShortcut(desktopDir) {
 
 function installLinuxShortcut(desktopDir) {
   const desktopPath = resolve(desktopDir, `${APP_NAME}.desktop`);
+  const appDir = resolve(homedir(), ".local", "share", "applications");
+  const appPath = resolve(appDir, `${APP_NAME}.desktop`);
+  const iconPath = resolve(__dirname, "logo.png");
   const content = [
     "[Desktop Entry]",
     "Type=Application",
     `Name=${APP_NAME}`,
     "Comment=Bosun Desktop Portal",
+    `Icon=${iconPath}`,
     `Exec=${buildShellCommand()}`,
     `Path=${getWorkingDirectory()}`,
     "Terminal=false",
     "StartupNotify=true",
     "Categories=Development;Utility;",
+    "NoDisplay=false",
     "",
   ].join("\n");
 
   try {
     writeFileSync(desktopPath, content, "utf8");
     chmodSync(desktopPath, 0o755);
+    mkdirSync(appDir, { recursive: true });
+    writeFileSync(appPath, content, "utf8");
+    chmodSync(appPath, 0o755);
+
+    try {
+      execSync(`gio set "${desktopPath}" metadata::trusted true`, {
+        stdio: "ignore",
+      });
+      execSync(`gio set "${appPath}" metadata::trusted true`, {
+        stdio: "ignore",
+      });
+    } catch {
+      /* best effort */
+    }
     return {
       success: true,
       method: "Linux desktop entry",

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "bosun",
-  "version": "0.28.1",
+  "version": "0.28.2",
   "description": "AI-powered orchestrator supervisor — manages AI agent executors with failover, auto-restarts on failure, analyzes crashes with Codex SDK, creates PRs via Vibe-Kanban API, and sends Telegram notifications. Supports N executors with weighted distribution, multi-repo projects, and auto-setup.",
   "type": "module",
   "license": "Apache 2.0",
-  "author": "VirtEngine Maintainers <maintainers@virtengine.com>",
+  "author": "VirtEngine Maintainers <hello@virtengine.com>",
   "homepage": "https://bosun.virtengine.com",
   "repository": {
     "type": "git",

package/rotate-agent-logs.sh

@@ -15,11 +15,12 @@ REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 LOG_DIR="$REPO_ROOT/.cache/agent-work-logs"
 ARCHIVE_DIR="$LOG_DIR/archive"
 
-# Retention periods
-STREAM_RETENTION_DAYS=30
-ERROR_RETENTION_DAYS=90
-SESSION_RETENTION_COUNT=100
-ARCHIVE_RETENTION_DAYS=180
+# Retention periods (override via env)
+STREAM_RETENTION_DAYS="${AGENT_WORK_STREAM_RETENTION_DAYS:-30}"
+ERROR_RETENTION_DAYS="${AGENT_WORK_ERROR_RETENTION_DAYS:-90}"
+SESSION_RETENTION_COUNT="${AGENT_WORK_SESSION_RETENTION_COUNT:-100}"
+ARCHIVE_RETENTION_DAYS="${AGENT_WORK_ARCHIVE_RETENTION_DAYS:-180}"
+METRICS_ROTATION_ENABLED="${AGENT_WORK_METRICS_ROTATION_ENABLED:-true}"
 
 # ── Functions ───────────────────────────────────────────────────────────────
 
@@ -111,10 +112,10 @@ if [ -f "$LOG_DIR/agent-alerts.jsonl" ]; then
   rotate_file "$LOG_DIR/agent-alerts.jsonl" "$ALERTS_ARCHIVE" "$STREAM_RETENTION_DAYS"
 fi
 
-# Metrics log is kept indefinitely (compressed monthly)
+# Metrics log is kept indefinitely (compressed monthly unless disabled)
 if [ -f "$LOG_DIR/agent-metrics.jsonl" ]; then
   # Only rotate on first day of month
-  if [ "$(date +%d)" = "01" ]; then
+  if [ "$METRICS_ROTATION_ENABLED" != "false" ] && [ "$(date +%d)" = "01" ]; then
     METRICS_ARCHIVE="agent-metrics-$(date -d 'last month' +%Y%m).jsonl.gz"
     rotate_file "$LOG_DIR/agent-metrics.jsonl" "$METRICS_ARCHIVE" ""
   fi

package/setup.mjs

@@ -46,6 +46,7 @@ import {
 } from "./hook-profiles.mjs";
 import { detectLegacySetup, applyAllCompatibility } from "./compat.mjs";
 import { DEFAULT_MODEL_PROFILES } from "./task-complexity.mjs";
+import { pullWorkspaceRepos, listWorkspaces } from "./workspace-manager.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -729,6 +730,61 @@ function printExecutorModelReference() {
   console.log();
 }
 
+function buildRepositoryChoices(configJson, repoRoot) {
+  const choices = [];
+  const seen = new Set();
+
+  const pushChoice = (input) => {
+    if (!input) return;
+    const name = String(input.name || "").trim();
+    const slug = String(input.slug || "").trim();
+    const workspace = String(input.workspace || input.workspaceId || "").trim();
+    if (!name && !slug) return;
+    const key = slug || name;
+    if (seen.has(`${workspace}:${key}`)) return;
+    seen.add(`${workspace}:${key}`);
+    const labelParts = [];
+    if (workspace) labelParts.push(`ws:${workspace}`);
+    labelParts.push(name || slug);
+    if (slug && name && slug !== name) labelParts.push(`(${slug})`);
+    const label = labelParts.join(" ");
+    choices.push({
+      label,
+      name,
+      slug,
+      workspace,
+      value: key,
+    });
+  };
+
+  if (Array.isArray(configJson?.workspaces)) {
+    for (const ws of configJson.workspaces) {
+      const wsId = String(ws?.id || "").trim();
+      const wsName = String(ws?.name || wsId || "").trim();
+      const wsLabel = wsName || wsId;
+      for (const repo of ws?.repos || []) {
+        pushChoice({
+          name: repo?.name,
+          slug: repo?.slug,
+          workspace: wsLabel,
+        });
+      }
+    }
+  }
+
+  if (Array.isArray(configJson?.repositories)) {
+    for (const repo of configJson.repositories) {
+      pushChoice(repo);
+    }
+  }
+
+  if (choices.length === 0 && repoRoot) {
+    pushChoice({ name: basename(repoRoot) });
+  }
+
+  return choices;
+}
+
 function defaultVariantForExecutor(executor) {
   const normalized = String(executor || "").trim().toUpperCase();
   if (normalized === "CODEX") return "DEFAULT";
@@ -2113,6 +2169,7 @@ async function main() {
 
   const prompt = createPrompt();
   let aborted = false;
+  let cloneWorkspacesAfterSetup = false;
 
   try {
     // ── Step 2: Setup Mode + Project Identity ─────────────
@@ -2220,6 +2277,11 @@ async function main() {
       if (configJson.workspaces.length > 0) {
         configJson.activeWorkspace = configJson.workspaces[0].id;
       }
+
+      cloneWorkspacesAfterSetup = await prompt.confirm(
+        "Clone/pull workspace repos now (recommended)?",
+        true,
+      );
     } else {
       // Single-repo mode (classic) — still works as before
       const multiRepo = isAdvancedSetup
@@ -2725,6 +2787,52 @@ async function main() {
 
     // ── Step 7: Kanban + Execution ─────────────────────────
     headingStep(7, "Kanban & Execution", markSetupProgress);
+    const repoChoices = buildRepositoryChoices(configJson, repoRoot);
+    let selectedRepoChoice = repoChoices[0] || null;
+    if (repoChoices.length > 1) {
+      console.log(
+        chalk.dim(
+          "  Multiple repositories detected. Select which repo this bosun instance should manage tasks for.",
+        ),
+      );
+      const repoLabels = repoChoices.map((choice) => choice.label);
+      repoLabels.push("Decide later (skip)");
+      const defaultRepoIdx = (() => {
+        const slugDefault =
+          process.env.GITHUB_REPOSITORY || env.GITHUB_REPO || "";
+        if (slugDefault) {
+          const matchIdx = repoChoices.findIndex(
+            (choice) => choice.slug === slugDefault,
+          );
+          if (matchIdx >= 0) return matchIdx;
+        }
+        const primaryIdx = repoChoices.findIndex(
+          (choice) => choice.slug && choice.slug === configJson?.repositories?.find((repo) => repo.primary)?.slug,
+        );
+        return primaryIdx >= 0 ? primaryIdx : 0;
+      })();
+      const selectedIdx = await prompt.choose(
+        "Primary repo for task board",
+        repoLabels,
+        Math.min(defaultRepoIdx, repoChoices.length - 1),
+      );
+      if (selectedIdx >= 0 && selectedIdx < repoChoices.length) {
+        selectedRepoChoice = repoChoices[selectedIdx];
+        if (selectedRepoChoice?.value) {
+          configJson.defaultRepository = selectedRepoChoice.value;
+        }
+      } else {
+        selectedRepoChoice = null;
+      }
+      console.log();
+      info(
+        "If you need different task backends per repo, run separate bosun instances with different configs.",
+      );
+      console.log();
+    } else if (selectedRepoChoice?.value) {
+      configJson.defaultRepository = selectedRepoChoice.value;
+    }
+
     const backendDefault = String(
       process.env.KANBAN_BACKEND || configJson.kanban?.backend || "internal",
     )
@@ -2918,7 +3026,9 @@ async function main() {
 
     if (selectedKanbanBackend === "github") {
       const primaryRepoSlug =
-        configJson.repositories?.find((repo) => repo.primary && repo.slug)?.slug || "";
+        selectedRepoChoice?.slug ||
+        configJson.repositories?.find((repo) => repo.primary && repo.slug)?.slug ||
+        "";
       const repoSlugDefaults = [
         process.env.GITHUB_REPOSITORY,
         process.env.GITHUB_REPO,
@@ -2933,10 +3043,35 @@ async function main() {
       info(
         "Pick the repo that should receive tasks (issues/projects). If you have multiple orgs, use the owner for that repo.",
       );
-      const repoInput = await prompt.ask(
-        "GitHub repository for tasks (owner/repo or URL)",
-        repoSlugDefault,
-      );
+      let repoInput = repoSlugDefault;
+      if (repoChoices.length > 1) {
+        const repoLabels = repoChoices.map((choice) => choice.label);
+        repoLabels.push("Enter manually");
+        const repoIdx = await prompt.choose(
+          "Select GitHub repo for tasks",
+          repoLabels,
+          repoChoices.findIndex(
+            (choice) => choice.slug && choice.slug === repoSlugDefault,
+          ) >= 0
+            ? repoChoices.findIndex(
+                (choice) => choice.slug && choice.slug === repoSlugDefault,
+              )
+            : 0,
+        );
+        if (repoIdx >= 0 && repoIdx < repoChoices.length) {
+          repoInput = repoChoices[repoIdx]?.slug || repoChoices[repoIdx]?.name || repoSlugDefault;
+        } else {
+          repoInput = await prompt.ask(
+            "GitHub repository for tasks (owner/repo or URL)",
+            repoSlugDefault,
+          );
+        }
+      } else {
+        repoInput = await prompt.ask(
+          "GitHub repository for tasks (owner/repo or URL)",
+          repoSlugDefault,
+        );
+      }
       const parsedRepoSlug = parseRepoSlugFromUrl(repoInput || repoSlugDefault);
       if (parsedRepoSlug) {
         const [repoOwner, repoName] = parsedRepoSlug.split("/", 2);
@@ -4153,6 +4288,28 @@ async function main() {
   normalizeSetupConfiguration({ env, configJson, repoRoot, slug, configDir });
   await writeConfigFiles({ env, configJson, repoRoot, configDir });
   clearSetupProgress(configDir);
+
+  if (cloneWorkspacesAfterSetup && Array.isArray(configJson.workspaces) && configJson.workspaces.length > 0) {
+    heading("Cloning Workspace Repos");
+    for (const ws of configJson.workspaces) {
+      const wsId = ws?.id;
+      if (!wsId) continue;
+      try {
+        const results = pullWorkspaceRepos(configDir, wsId);
+        for (const result of results) {
+          if (result.success) {
+            success(`Workspace ${wsId}: ${result.name} ready`);
+          } else {
+            warn(
+              `Workspace ${wsId}: ${result.name} ${result.error ? `— ${result.error}` : "failed"}`,
+            );
+          }
+        }
+      } catch (err) {
+        warn(`Workspace ${wsId}: clone/pull failed — ${err.message || err}`);
+      }
+    }
+  }
 }
 
 // ── Non-Interactive Mode ─────────────────────────────────────────────────────

package/task-executor.mjs

@@ -536,6 +536,11 @@ const agentWorkSessionStarts = new Map();
 const attemptTelemetry = new Map();
 const anomalyAbortTargets = new Map();
 const internalAnomalyEnabled = process.env.BOSUN_INTERNAL_ANOMALY !== "false";
+const TELEMETRY_SAMPLE_RATE = (() => {
+  const raw = Number(process.env.BOSUN_TELEMETRY_SAMPLE_RATE || "1");
+  if (!Number.isFinite(raw)) return 1;
+  return Math.min(1, Math.max(0, raw));
+})();
 const anomalyDetector = internalAnomalyEnabled
   ? createAnomalyDetector({
       onAnomaly: (anomaly) => {
@@ -581,6 +586,14 @@ function ensureAgentWorkDirs() {
 }
 
 function writeAgentWorkEvent(entry) {
+  const eventType = String(entry?.event_type || "");
+  const shouldSample =
+    TELEMETRY_SAMPLE_RATE < 1 &&
+    ["agent_output", "tool_call", "tool_result", "usage"].includes(eventType);
+  if (shouldSample && Math.random() > TELEMETRY_SAMPLE_RATE) {
+    return;
+  }
+
   ensureAgentWorkDirs();
   const line = JSON.stringify(entry);
   appendFileSync(AGENT_WORK_STREAM, `${line}\n`, "utf8");
@@ -3897,9 +3910,6 @@ class TaskExecutor {
         taskMeta,
         gitContext,
         metrics: {
-          tool_calls: Array.isArray(validatedResult?.items)
-            ? validatedResult.items.length
-            : undefined,
           success: !!validatedResult?.success,
           retry_count: Math.max(0, (validatedResult?.attempts || 1) - 1),
           attempts: validatedResult?.attempts || 1,

package/telegram-bot.mjs

@@ -132,6 +132,18 @@ const statusBoardStatePath = resolve(
 const fwCooldownPath = resolve(repoRoot, ".cache", "ve-fw-cooldown.json");
 const FW_COOLDOWN_MS = 24 * 60 * 60 * 1000; // 24 hours
 
+// ── Message History Auto-Cleanup ──────────────────────────────────────────
+const msgHistoryPath = resolve(repoRoot, ".cache", "ve-message-history.json");
+// Days to keep bot messages in chat. 0 = disabled. Default: 3 days.
+const HISTORY_RETENTION_DAYS = (() => {
+  const v = Number(process.env.TELEGRAM_HISTORY_RETENTION_DAYS ?? "3");
+  return Number.isFinite(v) && v > 0 ? v : 0;
+})();
+const HISTORY_RETENTION_MS = HISTORY_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+const HISTORY_CLEANUP_INTERVAL_MS = 6 * 60 * 60 * 1000; // run every 6 hours
+const HISTORY_INITIAL_DELAY_MS = 2 * 60 * 1000;         // wait 2 min after boot
+const HISTORY_MAX_TRACKED = 10_000;                      // safety cap
+
 function resolveVeKanbanPs1Path() {
   const modulePath = resolve(BosunDir, "ve-kanban.ps1");
   if (existsSync(modulePath)) return modulePath;
@@ -1117,6 +1129,7 @@ async function sendDirect(chatId, text, options = {}) {
         const data = await res.json();
         if (data.ok && data.result?.message_id) {
           lastMessageId = data.result.message_id;
+          recordSentMessage(chatId, lastMessageId);
         }
       } catch (err) {
         console.warn(`[telegram-bot] send JSON parse error: ${err.message}`);
@@ -1215,6 +1228,85 @@ async function deleteDirect(chatId, messageId) {
   }
 }
 
+// ── Message History Helpers ───────────────────────────────────────────────────
+
+/** Lazy-loaded in-memory list of sent message records. */
+let _msgHistory = null;
+let _msgHistoryDirty = false;
+
+function _loadMsgHistory() {
+  if (_msgHistory !== null) return;
+  try {
+    const raw = readFileSync(msgHistoryPath, "utf8");
+    const data = JSON.parse(raw);
+    _msgHistory = Array.isArray(data.messages) ? data.messages : [];
+  } catch {
+    _msgHistory = [];
+  }
+}
+
+function _saveMsgHistory() {
+  if (!_msgHistory) return;
+  try {
+    mkdirSync(resolve(repoRoot, ".cache"), { recursive: true });
+    writeFileSync(
+      msgHistoryPath,
+      JSON.stringify({ messages: _msgHistory }, null, 2),
+      "utf8",
+    );
+    _msgHistoryDirty = false;
+  } catch {
+    /* best effort */
+  }
+}
+
+/**
+ * Record a newly sent message ID so it can be cleaned up later.
+ * No-op when HISTORY_RETENTION_MS is 0 (feature disabled).
+ */
+function recordSentMessage(chatId, messageId) {
+  if (!HISTORY_RETENTION_MS || !messageId) return;
+  _loadMsgHistory();
+  _msgHistory.push({ chat_id: chatId, message_id: messageId, sent_at: Date.now() });
+  if (_msgHistory.length > HISTORY_MAX_TRACKED) {
+    _msgHistory = _msgHistory.slice(-HISTORY_MAX_TRACKED);
+  }
+  _msgHistoryDirty = true;
+}
+
+/**
+ * Delete all tracked bot messages older than HISTORY_RETENTION_MS.
+ * Failures are silently swallowed — Telegram may refuse deletes for messages
+ * older than 48 h in private chats; we just skip those gracefully.
+ */
+async function pruneMessageHistory() {
+  if (!HISTORY_RETENTION_MS) return;
+  _loadMsgHistory();
+  if (_msgHistoryDirty) _saveMsgHistory();
+
+  const cutoff = Date.now() - HISTORY_RETENTION_MS;
+  const toDelete = _msgHistory.filter((m) => m.sent_at < cutoff);
+  if (toDelete.length === 0) return;
+
+  console.log(
+    `[telegram-bot] auto-cleanup: deleting ${toDelete.length} message(s) older than ${HISTORY_RETENTION_DAYS}d`,
+  );
+
+  let i = 0;
+  for (const m of toDelete) {
+    await deleteDirect(m.chat_id, m.message_id);
+    i++;
+    // Pace at ~20 deletes/s to stay well under Telegram’s 30 msg/s limit
+    if (i % 20 === 0) await new Promise((r) => setTimeout(r, 1000));
+  }
+
+  _msgHistory = _msgHistory.filter((m) => m.sent_at >= cutoff);
+  _saveMsgHistory();
+  console.log(
+    `[telegram-bot] auto-cleanup: done. ${_msgHistory.length} messages remaining in history.`,
+  );
+}
+
 /**
  * Answer a Telegram callback query (required to dismiss the "loading" indicator).
  * @param {string} callbackQueryId - The callback_query.id from the update
@@ -10378,6 +10470,32 @@ export async function startTelegramBot() {
     console.error(`[telegram-bot] fatal poll loop error: ${err.message}`);
     polling = false;
   });
+
+  // ── Message history auto-cleanup ──
+  if (HISTORY_RETENTION_MS) {
+    // Flush in-memory buffer to disk every 5 minutes
+    const flushTimer = setInterval(() => {
+      if (_msgHistoryDirty) _saveMsgHistory();
+    }, 5 * 60 * 1000);
+    flushTimer.unref();
+
+    // Run first prune after HISTORY_INITIAL_DELAY_MS (2 min), then every 6 h
+    setTimeout(() => {
+      pruneMessageHistory().catch((err) =>
+        console.warn(`[telegram-bot] message history cleanup error: ${err.message}`),
+      );
+      const cleanupTimer = setInterval(
+        () =>
+          pruneMessageHistory().catch((err) =>
+            console.warn(
+              `[telegram-bot] message history cleanup error: ${err.message}`,
+            ),
+          ),
+        HISTORY_CLEANUP_INTERVAL_MS,
+      );
+      cleanupTimer.unref();
+    }, HISTORY_INITIAL_DELAY_MS);
+  }
 }
 
 /**

package/ui/app.js

@@ -82,6 +82,7 @@ import { AgentsTab } from "./tabs/agents.js";
 import { InfraTab } from "./tabs/infra.js";
 import { ControlTab } from "./tabs/control.js";
 import { LogsTab } from "./tabs/logs.js";
+import { TelemetryTab } from "./tabs/telemetry.js";
 import { SettingsTab } from "./tabs/settings.js";
 
 /* ── Placeholder signals for connection quality (may be provided by api.js) ── */
@@ -203,6 +204,7 @@ const TAB_COMPONENTS = {
   infra: InfraTab,
   control: ControlTab,
   logs: LogsTab,
+  telemetry: TelemetryTab,
   settings: SettingsTab,
 };
 

package/ui/demo.html

@@ -669,6 +669,14 @@
         return { data: STATE.status };
       if (route === '/api/executor')
         return { data: { ...STATE.status, maxParallel: STATE.maxParallel, paused: STATE.paused, executors: STATE.executors } };
+      if (route === '/api/telemetry/summary')
+        return { data: { status: 'ok', updatedAt: Date.now(), totals: { tasks: STATE.tasks.length, executors: STATE.executors.length } } };
+      if (route === '/api/telemetry/errors')
+        return { data: [] };
+      if (route === '/api/telemetry/executors')
+        return { data: STATE.executors.map((e) => ({ ...e, status: e.enabled ? 'active' : 'disabled' })) };
+      if (route === '/api/telemetry/alerts')
+        return { data: [] };
       if (route === '/api/executor/pause') {
         STATE.paused = true; addLog('info', 'executor', 'Executor paused');
         return { ok: true, paused: true };

package/ui/modules/icons.js

@@ -88,6 +88,20 @@ export const ICONS = {
     <circle cx="19" cy="12" r="1.6" />
   </svg>`,
 
+  chart: html`<svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <line x1="4" y1="19" x2="20" y2="19" />
+    <rect x="6" y="10" width="3" height="9" />
+    <rect x="11" y="6" width="3" height="13" />
+    <rect x="16" y="13" width="3" height="6" />
+  </svg>`,
+
   /* ── Status / Feedback ── */
   check: html`<svg
     viewBox="0 0 24 24"

package/ui/modules/router.js

@@ -82,5 +82,6 @@ export const TAB_CONFIG = [
   { id: "chat", label: "Chat", icon: "chat" },
   { id: "infra", label: "Infra", icon: "server" },
   { id: "logs", label: "Logs", icon: "terminal" },
+  { id: "telemetry", label: "Telemetry", icon: "chart" },
   { id: "settings", label: "Settings", icon: "settings" },
 ];

package/ui/modules/settings-schema.js

@@ -53,6 +53,7 @@ export const SETTINGS_SCHEMA = [
   { key: "TELEGRAM_API_BASE_URL",          label: "API Base URL",               category: "telegram", type: "string",  defaultVal: "https://api.telegram.org", description: "Override for Telegram API proxy.", advanced: true, validate: "^https?://" },
   { key: "TELEGRAM_HTTP_TIMEOUT_MS",       label: "HTTP Timeout",               category: "telegram", type: "number",  defaultVal: 15000, min: 5000, max: 60000, unit: "ms", description: "Per-request timeout for Telegram API calls.", advanced: true },
   { key: "TELEGRAM_RETRY_ATTEMPTS",        label: "Retry Attempts",             category: "telegram", type: "number",  defaultVal: 4, min: 0, max: 10, description: "Number of retry attempts for transient Telegram API failures.", advanced: true },
+  { key: "TELEGRAM_HISTORY_RETENTION_DAYS", label: "Auto-Delete History",       category: "telegram", type: "number",  defaultVal: 3, min: 0, max: 365, unit: "days", description: "Automatically delete bot messages older than this many days to keep the chat tidy. 0 = disabled. Note: Telegram may silently skip messages older than 48 h in private chats.", restart: false },
   { key: "PROJECT_NAME",                   label: "Project Name",               category: "telegram", type: "string",  description: "Display name used in Telegram messages and logs. Auto-detected from package.json if not set." },
 
   // ── Mini App / UI Server ──────────────────────────────────────
@@ -112,6 +113,14 @@ export const SETTINGS_SCHEMA = [
   { key: "TASK_PLANNER_DEDUP_HOURS",       label: "Planner Dedup Window",       category: "kanban", type: "number", defaultVal: 6, min: 1, max: 72, unit: "hours", description: "Hours to look back for duplicate task detection.", advanced: true },
   { key: "BOSUN_PROMPT_PLANNER",  label: "Planner Prompt Path",         category: "advanced", type: "string", description: "Override the task planner prompt file path.", advanced: true },
 
+  // ── Logging / Telemetry ──────────────────────────────────────
+  { key: "BOSUN_TELEMETRY_SAMPLE_RATE",    label: "Telemetry Sample Rate",      category: "logging", type: "number", defaultVal: 1, min: 0, max: 1, description: "Sampling rate for high-volume telemetry events (agent_output/tool events). 1 = full, 0.1 = 10% sample.", advanced: true },
+  { key: "AGENT_WORK_STREAM_RETENTION_DAYS", label: "Stream Retention",         category: "logging", type: "number", defaultVal: 30, min: 1, max: 365, unit: "days", description: "How long to keep agent-work stream logs before rotation.", advanced: true },
+  { key: "AGENT_WORK_ERROR_RETENTION_DAYS",  label: "Error Retention",          category: "logging", type: "number", defaultVal: 90, min: 1, max: 365, unit: "days", description: "How long to keep error logs before rotation.", advanced: true },
+  { key: "AGENT_WORK_SESSION_RETENTION_COUNT", label: "Session Retention Count", category: "logging", type: "number", defaultVal: 100, min: 10, max: 10000, description: "Number of session log files to keep.", advanced: true },
+  { key: "AGENT_WORK_ARCHIVE_RETENTION_DAYS", label: "Archive Retention",       category: "logging", type: "number", defaultVal: 180, min: 30, max: 3650, unit: "days", description: "Retention window for compressed log archives.", advanced: true },
+  { key: "AGENT_WORK_METRICS_ROTATION_ENABLED", label: "Rotate Metrics Log",    category: "logging", type: "boolean", defaultVal: true, description: "Rotate metrics log monthly to keep file size bounded.", advanced: true },
+
   // ── GitHub / Git ─────────────────────────────────────────
   { key: "GITHUB_TOKEN",                   label: "GitHub Token",               category: "github", type: "secret", sensitive: true, description: "Personal access token or fine-grained token for GitHub API. Required for GitHub kanban backend." },
   { key: "GITHUB_REPOSITORY",              label: "Repository",                 category: "github", type: "string", description: "GitHub repository in owner/repo format. Auto-detected from git remote if not set.", validate: "^[\\w.-]+/[\\w.-]+$" },

package/ui/modules/state.js

@@ -43,6 +43,7 @@ const CACHE_TTL = {
   threads: 5000, logs: 15000, worktrees: 30000, workspaces: 30000,
   presence: 30000, config: 60000, projects: 60000, git: 20000,
   infra: 30000,
+  telemetry: 15000,
 };
 
 function _cacheKey(url) { return url; }
@@ -111,6 +112,12 @@ export const agentLogLines = signal(200);
 export const agentLogQuery = signal("");
 export const agentContext = signal(null);
 
+// ── Telemetry
+export const telemetrySummary = signal(null);
+export const telemetryErrors = signal([]);
+export const telemetryExecutors = signal({});
+export const telemetryAlerts = signal([]);
+
 // ── Config (routing, regions, etc.)
 export const configData = signal(null);
 
@@ -590,6 +597,50 @@ export async function loadConfig() {
   _markFresh("config");
 }
 
+export async function loadTelemetrySummary() {
+  const url = "/api/telemetry/summary";
+  if (_cacheFresh(url, "telemetry")) return;
+  const res = await apiFetch(url, { _silent: true }).catch(() => ({
+    ok: false,
+  }));
+  telemetrySummary.value = res?.data ?? res ?? null;
+  _cacheSet(url, telemetrySummary.value);
+  _markFresh("telemetry");
+}
+
+export async function loadTelemetryErrors() {
+  const url = "/api/telemetry/errors";
+  if (_cacheFresh(url, "telemetry")) return;
+  const res = await apiFetch(url, { _silent: true }).catch(() => ({
+    ok: false,
+  }));
+  telemetryErrors.value = res?.data ?? res ?? [];
+  _cacheSet(url, telemetryErrors.value);
+  _markFresh("telemetry");
+}
+
+export async function loadTelemetryExecutors() {
+  const url = "/api/telemetry/executors";
+  if (_cacheFresh(url, "telemetry")) return;
+  const res = await apiFetch(url, { _silent: true }).catch(() => ({
+    ok: false,
+  }));
+  telemetryExecutors.value = res?.data ?? res ?? {};
+  _cacheSet(url, telemetryExecutors.value);
+  _markFresh("telemetry");
+}
+
+export async function loadTelemetryAlerts() {
+  const url = "/api/telemetry/alerts";
+  if (_cacheFresh(url, "telemetry")) return;
+  const res = await apiFetch(url, { _silent: true }).catch(() => ({
+    ok: false,
+  }));
+  telemetryAlerts.value = res?.data ?? res ?? [];
+  _cacheSet(url, telemetryAlerts.value);
+  _markFresh("telemetry");
+}
+
 /* ═══════════════════════════════════════════════════════════════
  *  TAB REFRESH — map tab names to their required loaders
  * ═══════════════════════════════════════════════════════════════ */
@@ -609,6 +660,13 @@ const TAB_LOADERS = {
   control: () => Promise.all([loadExecutor(), loadConfig()]),
   logs: () =>
     Promise.all([loadLogs(), loadAgentLogFileList(), loadAgentLogTailData()]),
+  telemetry: () =>
+    Promise.all([
+      loadTelemetrySummary(),
+      loadTelemetryErrors(),
+      loadTelemetryExecutors(),
+      loadTelemetryAlerts(),
+    ]),
   settings: () => Promise.all([loadStatus(), loadConfig()]),
 };
 
@@ -687,6 +745,7 @@ const WS_CHANNEL_MAP = {
   infra: ["worktrees", "workspaces", "presence"],
   control: ["executor", "overview"],
   logs: ["*"],
+  telemetry: ["*"],
   settings: ["overview"],
 };
 

package/ui/styles.css

@@ -139,3 +139,91 @@
   font-size: 12px;
   text-align: center;
 }
+
+/* ─── Telemetry Tab ─── */
+.telemetry-tab {
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+}
+
+.telemetry-tab .section-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.telemetry-summary .metric-grid {
+  display: grid;
+  gap: 14px;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+}
+
+.metric-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-hint);
+}
+
+.metric-value {
+  font-size: 20px;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.telemetry-grid {
+  display: grid;
+  gap: 16px;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+}
+
+.telemetry-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.telemetry-list li {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  font-size: 13px;
+}
+
+.telemetry-label {
+  color: var(--text-secondary);
+}
+
+.telemetry-count {
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.telemetry-alerts {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.telemetry-alert-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+  font-size: 13px;
+}
+
+.telemetry-alert-meta {
+  font-size: 12px;
+  color: var(--text-hint);
+  margin-top: 4px;
+}

package/ui/tabs/telemetry.js

@@ -0,0 +1,167 @@
+/* ─────────────────────────────────────────────────────────────
+ *  Tab: Telemetry — analytics, quality signals, alerts
+ * ────────────────────────────────────────────────────────────── */
+import { h } from "preact";
+import { useMemo } from "preact/hooks";
+import htm from "htm";
+
+const html = htm.bind(h);
+
+import {
+  telemetrySummary,
+  telemetryErrors,
+  telemetryExecutors,
+  telemetryAlerts,
+  loadTelemetrySummary,
+  loadTelemetryErrors,
+  loadTelemetryExecutors,
+  loadTelemetryAlerts,
+  scheduleRefresh,
+} from "../modules/state.js";
+import { Card, EmptyState, SkeletonCard, Badge } from "../components/shared.js";
+
+function formatCount(value) {
+  if (value == null) return "–";
+  return String(value);
+}
+
+function formatSeconds(value) {
+  if (!value && value !== 0) return "–";
+  if (value >= 60) return `${Math.round(value / 60)}m`;
+  return `${value}s`;
+}
+
+function severityBadge(sev = "medium") {
+  const normalized = String(sev).toLowerCase();
+  if (normalized === "high" || normalized === "critical") return "danger";
+  if (normalized === "medium") return "warning";
+  return "info";
+}
+
+export function TelemetryTab() {
+  const summary = telemetrySummary.value;
+  const errors = telemetryErrors.value || [];
+  const executors = telemetryExecutors.value || {};
+  const alerts = telemetryAlerts.value || [];
+
+  const hasSummary = summary && summary.total > 0;
+
+  const executorRows = useMemo(
+    () => Object.entries(executors).sort((a, b) => b[1] - a[1]),
+    [executors],
+  );
+
+  const alertRows = useMemo(
+    () => alerts.slice(-10).reverse(),
+    [alerts],
+  );
+
+  return html`
+    <section class="telemetry-tab">
+      <div class="section-header">
+        <h2>Telemetry</h2>
+        <button
+          class="btn btn-ghost btn-sm"
+          onClick=${() => {
+            loadTelemetrySummary();
+            loadTelemetryErrors();
+            loadTelemetryExecutors();
+            loadTelemetryAlerts();
+            scheduleRefresh(4000);
+          }}
+        >
+          Refresh
+        </button>
+      </div>
+
+      ${!hasSummary
+        ? html`<${EmptyState}
+            title="No telemetry yet"
+            description="Telemetry appears here once agents start running."
+          />`
+        : html`<${Card} title="Summary" class="telemetry-summary">
+            <div class="metric-grid">
+              <div>
+                <div class="metric-label">Sessions</div>
+                <div class="metric-value">${formatCount(summary.total)}</div>
+              </div>
+              <div>
+                <div class="metric-label">Success</div>
+                <div class="metric-value">
+                  ${formatCount(summary.success)} (${summary.successRate}%)
+                </div>
+              </div>
+              <div>
+                <div class="metric-label">Avg Duration</div>
+                <div class="metric-value">${formatSeconds(summary.avgDuration)}</div>
+              </div>
+              <div>
+                <div class="metric-label">Errors</div>
+                <div class="metric-value">${formatCount(summary.totalErrors)}</div>
+              </div>
+            </div>
+          </${Card}>`}
+
+      <div class="telemetry-grid">
+        <${Card} title="Top Errors">
+          ${errors.length === 0
+            ? html`<${EmptyState}
+                title="No errors logged"
+                description="Errors appear here when failures are detected."
+              />`
+            : html`<ul class="telemetry-list">
+                ${errors.slice(0, 8).map(
+                  (err) => html`<li>
+                    <span class="telemetry-label">${err.fingerprint}</span>
+                    <span class="telemetry-count">${err.count}</span>
+                  </li>`,
+                )}
+              </ul>`}
+        </${Card}>
+
+        <${Card} title="Executors">
+          ${executorRows.length === 0
+            ? html`<${EmptyState}
+                title="No executor data"
+                description="Run tasks to populate executor usage."
+              />`
+            : html`<ul class="telemetry-list">
+                ${executorRows.map(
+                  ([name, count]) => html`<li>
+                    <span class="telemetry-label">${name}</span>
+                    <span class="telemetry-count">${count}</span>
+                  </li>`,
+                )}
+              </ul>`}
+        </${Card}>
+      </div>
+
+      <${Card} title="Recent Alerts">
+        ${alertRows.length === 0
+          ? html`<${EmptyState}
+              title="No alerts"
+              description="Analyzer alerts will show up here."
+            />`
+          : html`<ul class="telemetry-alerts">
+              ${alertRows.map(
+                (alert) => html`<li>
+                  <div>
+                    <div class="telemetry-alert-title">
+                      ${alert.type || "alert"}
+                      <${Badge} tone=${severityBadge(alert.severity)}>${
+                        String(alert.severity || "medium").toUpperCase()
+                      }</${Badge}>
+                    </div>
+                    <div class="telemetry-alert-meta">
+                      ${alert.attempt_id || "unknown"}
+                      ${alert.executor ? html` · ${alert.executor}` : ""}
+                    </div>
+                  </div>
+                </li>`,
+              )}
+            </ul>`}
+      </${Card}>
+    </section>
+  `;
+}
+

package/ui-server.mjs

@@ -600,6 +600,7 @@ const SETTINGS_KNOWN_KEYS = [
   "TELEGRAM_COMMAND_CONCURRENCY", "TELEGRAM_VERBOSITY", "TELEGRAM_BATCH_NOTIFICATIONS",
   "TELEGRAM_BATCH_INTERVAL_SEC", "TELEGRAM_BATCH_MAX_SIZE", "TELEGRAM_IMMEDIATE_PRIORITY",
   "TELEGRAM_API_BASE_URL", "TELEGRAM_HTTP_TIMEOUT_MS", "TELEGRAM_RETRY_ATTEMPTS",
+  "TELEGRAM_HISTORY_RETENTION_DAYS",
   "PROJECT_NAME", "TELEGRAM_MINIAPP_ENABLED", "TELEGRAM_UI_PORT", "TELEGRAM_UI_HOST",
   "TELEGRAM_UI_PUBLIC_HOST", "TELEGRAM_UI_BASE_URL", "TELEGRAM_UI_ALLOW_UNSAFE",
   "TELEGRAM_UI_AUTH_MAX_AGE_SEC", "TELEGRAM_UI_TUNNEL",
@@ -2213,6 +2214,60 @@ async function tailFile(filePath, lineCount, maxBytes = 1_000_000) {
   };
 }
 
+async function readJsonlTail(filePath, maxLines = 2000) {
+  if (!existsSync(filePath)) return [];
+  const tail = await tailFile(filePath, maxLines);
+  return (tail.lines || [])
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+function withinDays(entry, days) {
+  if (!days) return true;
+  const ts = Date.parse(entry?.timestamp || "");
+  if (!Number.isFinite(ts)) return true;
+  return ts >= Date.now() - days * 24 * 60 * 60 * 1000;
+}
+
+function summarizeTelemetry(metrics, days) {
+  const filtered = metrics.filter((m) => withinDays(m, days));
+  if (filtered.length === 0) return null;
+  const total = filtered.length;
+  const success = filtered.filter(
+    (m) => m.outcome?.status === "completed" || m.metrics?.success === true,
+  ).length;
+  const durations = filtered.map((m) => m.metrics?.duration_ms || 0);
+  const avgDuration =
+    durations.length > 0
+      ? Math.round(
+          durations.reduce((a, b) => a + b, 0) / durations.length / 1000,
+        )
+      : 0;
+  const totalErrors = filtered.reduce(
+    (sum, m) => sum + (m.error_summary?.total_errors || m.metrics?.errors || 0),
+    0,
+  );
+  const executors = {};
+  for (const m of filtered) {
+    const exec = m.executor || "unknown";
+    executors[exec] = (executors[exec] || 0) + 1;
+  }
+  return {
+    total,
+    success,
+    successRate: total > 0 ? Math.round((success / total) * 100) : 0,
+    avgDuration,
+    totalErrors,
+    executors,
+  };
+}
+
 async function listAgentLogFiles(query = "", limit = 60) {
   const entries = [];
   const files = await readdir(agentLogsDir).catch(() => []);
@@ -3183,6 +3238,79 @@ async function handleApi(req, res, url) {
     return;
   }
 
+  if (path === "/api/telemetry/summary") {
+    try {
+      const days = Number(url.searchParams.get("days") || "7");
+      const logDir = resolve(repoRoot, ".cache", "agent-work-logs");
+      const metricsPath = resolve(logDir, "agent-metrics.jsonl");
+      const metrics = await readJsonlTail(metricsPath, 3000);
+      const summary = summarizeTelemetry(metrics, days);
+      jsonResponse(res, 200, { ok: true, data: summary });
+    } catch (err) {
+      jsonResponse(res, 500, { ok: false, error: err.message });
+    }
+    return;
+  }
+
+  if (path === "/api/telemetry/errors") {
+    try {
+      const days = Number(url.searchParams.get("days") || "7");
+      const logDir = resolve(repoRoot, ".cache", "agent-work-logs");
+      const errorsPath = resolve(logDir, "agent-errors.jsonl");
+      const errors = (await readJsonlTail(errorsPath, 2000)).filter((e) =>
+        withinDays(e, days),
+      );
+      const byFingerprint = new Map();
+      for (const e of errors) {
+        const fp = e.data?.error_fingerprint || e.data?.error_message || "unknown";
+        byFingerprint.set(fp, (byFingerprint.get(fp) || 0) + 1);
+      }
+      const top = [...byFingerprint.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 20)
+        .map(([fingerprint, count]) => ({ fingerprint, count }));
+      jsonResponse(res, 200, { ok: true, data: top });
+    } catch (err) {
+      jsonResponse(res, 500, { ok: false, error: err.message });
+    }
+    return;
+  }
+
+  if (path === "/api/telemetry/executors") {
+    try {
+      const days = Number(url.searchParams.get("days") || "7");
+      const logDir = resolve(repoRoot, ".cache", "agent-work-logs");
+      const metricsPath = resolve(logDir, "agent-metrics.jsonl");
+      const metrics = await readJsonlTail(metricsPath, 3000);
+      const summary = summarizeTelemetry(metrics, days);
+      jsonResponse(res, 200, {
+        ok: true,
+        data: summary?.executors || {},
+      });
+    } catch (err) {
+      jsonResponse(res, 500, { ok: false, error: err.message });
+    }
+    return;
+  }
+
+  if (path === "/api/telemetry/alerts") {
+    try {
+      const days = Number(url.searchParams.get("days") || "7");
+      const logDir = resolve(repoRoot, ".cache", "agent-work-logs");
+      const alertsPath = resolve(logDir, "agent-alerts.jsonl");
+      const alerts = (await readJsonlTail(alertsPath, 500)).filter((a) =>
+        withinDays(a, days),
+      );
+      jsonResponse(res, 200, {
+        ok: true,
+        data: alerts.slice(-50),
+      });
+    } catch (err) {
+      jsonResponse(res, 500, { ok: false, error: err.message });
+    }
+    return;
+  }
+
   if (path === "/api/agent-logs/context") {
     try {
       const query = url.searchParams.get("query") || "";