heyio 0.5.0 → 0.8.0

package/dist/copilot/tools.js

@@ -11,38 +11,215 @@ import { runIoScheduleNow } from "./io-scheduler.js";
 import { createSchedule, deleteSchedule, getSchedule, listSchedules, setScheduleEnabled, } from "../store/schedules.js";
 import { runScheduleNow } from "./scheduler.js";
 // ---------------------------------------------------------------------------
-// QA / test coverage heuristics
+// Squad coverage heuristics
 //
 // Every squad must have:
-//   1. At least one agent designated as QA (is_qa === 1) - see squad_set_qa.
-//   2. At least one agent whose role title implies a testing/quality focus.
+//   1. A dedicated team lead — a PM / Senior Engineer with no domain
+//      responsibility — designated via squad_set_lead. The lead's job is
+//      coordination, delegation, and review only. Lead veto power on PR
+//      promotion is automatic (see runPeerReview in agents.ts).
+//   2. At least one agent designated as QA (is_qa === 1) — see squad_set_qa.
+//   3. At least one agent whose role title implies a testing/quality focus.
 //
 // These are surfaced as warnings on squad_status, squad_agents, and
 // squad_delegate so users can fix coverage gaps before promoting work.
 // ---------------------------------------------------------------------------
 const TEST_ROLE_KEYWORDS = ["test", "qa", "quality", "tester", "sdet", "qe"];
+// Words in a role title that imply the agent owns a hands-on engineering
+// domain (and therefore should NOT be the team lead).
+const DOMAIN_ROLE_KEYWORDS = [
+    "frontend",
+    "backend",
+    "fullstack",
+    "full-stack",
+    "api",
+    "ui",
+    "ux",
+    "test",
+    "tester",
+    "qa",
+    "quality",
+    "sdet",
+    "qe",
+    "devops",
+    "sre",
+    "ops",
+    "infrastructure",
+    "platform",
+    "data",
+    "database",
+    "db",
+    "ml",
+    "ai",
+    "sdk",
+    "mobile",
+    "ios",
+    "android",
+    "web",
+    "security",
+    "embedded",
+    "integration",
+    "telegram",
+    "tui",
+    "vue",
+    "react",
+    "angular",
+    "express",
+    "sqlite",
+    "wiki",
+];
+// Words that mark a role as coordination/leadership-focused.
+const LEAD_ROLE_KEYWORDS = [
+    "lead",
+    "manager",
+    "pm",
+    "principal",
+    "coordinator",
+    "director",
+];
+function containsWord(haystack, word) {
+    const re = new RegExp(`(^|[^a-z])${word}([^a-z]|$)`);
+    return re.test(haystack);
+}
 export function roleLooksLikeTesting(roleTitle) {
     if (!roleTitle)
         return false;
     const lower = roleTitle.toLowerCase();
-    return TEST_ROLE_KEYWORDS.some((kw) => {
-        const re = new RegExp(`(^|[^a-z])${kw}([^a-z]|$)`);
-        return re.test(lower);
-    });
+    return TEST_ROLE_KEYWORDS.some((kw) => containsWord(lower, kw));
+}
+/**
+ * A dedicated team lead has a role title that emphasises coordination/seniority
+ * and does NOT also claim a hands-on engineering domain. Examples:
+ *   ✅ "Engineering Lead", "Project Manager", "Senior Engineering Lead",
+ *      "Principal Engineer", "Tech Lead", "Senior Engineer"
+ *   ❌ "Frontend Lead", "Test Manager", "QA Lead", "Backend Engineer",
+ *      "Express API Engineer"
+ */
+export function roleLooksLikeDedicatedLead(roleTitle) {
+    if (!roleTitle)
+        return false;
+    const lower = roleTitle.toLowerCase();
+    const hasDomainKw = DOMAIN_ROLE_KEYWORDS.some((kw) => containsWord(lower, kw));
+    if (hasDomainKw)
+        return false;
+    const hasLeadKw = LEAD_ROLE_KEYWORDS.some((kw) => containsWord(lower, kw));
+    if (hasLeadKw)
+        return true;
+    // "Senior Engineer" / "Sr. Engineer" with no domain qualifier also counts.
+    if (/(^|[^a-z])(senior|sr\.?)\s+engineer($|[^a-z])/.test(lower))
+        return true;
+    return false;
 }
 export function assessSquadCoverage(agents) {
+    const leadAgent = agents.find((a) => a.is_lead === 1);
+    const hasLead = !!leadAgent;
+    const hasDedicatedLead = !!leadAgent && roleLooksLikeDedicatedLead(leadAgent.role_title);
     const hasQa = agents.some((a) => a.is_qa === 1);
     const hasTestRole = agents.some((a) => roleLooksLikeTesting(a.role_title));
     const missing = [];
+    if (!hasLead) {
+        missing.push("dedicated team lead (use squad_set_lead with a PM/Senior Engineer who owns no domain)");
+    }
+    else if (!hasDedicatedLead) {
+        missing.push(`dedicated lead role (current lead "${leadAgent.role_title}" looks like a domain specialist — team leads must be PM/Senior Engineer with no domain ownership)`);
+    }
     if (!hasQa)
         missing.push("QA reviewer (use squad_set_qa)");
     if (!hasTestRole) {
         missing.push("test/quality engineer (add an agent whose role_title contains 'test', 'qa', or 'quality')");
     }
     const warning = missing.length > 0
-        ? `⚠️ Squad coverage gap: missing ${missing.join(" and ")}.`
+        ? `⚠️ Squad coverage gap: missing ${missing.join("; ")}.`
         : null;
-    return { hasQa, hasTestRole, missing, warning };
+    return { hasLead, hasDedicatedLead, hasQa, hasTestRole, missing, warning };
+}
+// ---------------------------------------------------------------------------
+// Work-distribution diagnostics
+//
+// Squads can fall into an anti-pattern (#51) where the team lead handles
+// every delegated task instead of fanning out to specialists. We surface a
+// soft warning on squad_status when the lead handles more than this share
+// of recent tasks.
+// ---------------------------------------------------------------------------
+const WORK_DISTRIBUTION_WINDOW = 20;
+const LEAD_OVERLOAD_THRESHOLD = 0.8;
+function formatWorkDistribution(squadSlug, lead, deps) {
+    const dist = deps.getSquadWorkDistribution(squadSlug, WORK_DISTRIBUTION_WINDOW);
+    if (dist.total === 0)
+        return "";
+    const friendly = (agentSlug) => {
+        if (agentSlug === squadSlug)
+            return "(unassigned)";
+        const idx = agentSlug.indexOf(":");
+        return idx >= 0 ? agentSlug.slice(idx + 1) : agentSlug;
+    };
+    const breakdown = dist.perAgent
+        .map((a) => `${friendly(a.agent_slug)} ${a.count} (${Math.round((a.count / dist.total) * 100)}%)`)
+        .join(", ");
+    const lines = [];
+    lines.push(`\n  📊 Work distribution (last ${dist.total} task${dist.total === 1 ? "" : "s"}): ${breakdown}`);
+    if (lead) {
+        const leadKey = `${squadSlug}:${lead.character_name}`;
+        const leadCount = dist.perAgent.find((a) => a.agent_slug === leadKey)?.count ?? 0;
+        const share = leadCount / dist.total;
+        if (share > LEAD_OVERLOAD_THRESHOLD) {
+            lines.push(`\n  ⚠️ Lead overload: ${lead.character_name} handled ${Math.round(share * 100)}% of recent tasks (threshold ${Math.round(LEAD_OVERLOAD_THRESHOLD * 100)}%). The lead should be delegating to specialists via delegate_to_teammate, not self-implementing — see issue #51.`);
+        }
+    }
+    return lines.join("");
+}
+// ---------------------------------------------------------------------------
+// Per-agent delegation-stat formatters (issue #61)
+// ---------------------------------------------------------------------------
+/**
+ * Format an ISO timestamp as a short relative time string. SQLite emits
+ * naive UTC strings, so we suffix "Z" before parsing if it isn't already
+ * timezone-qualified.
+ */
+function formatRelativeTime(iso) {
+    if (!iso)
+        return "never";
+    const tzQualified = /[zZ]$|[+-]\d{2}:?\d{2}$/.test(iso);
+    const ts = new Date(tzQualified ? iso : iso + "Z").getTime();
+    if (Number.isNaN(ts))
+        return "never";
+    const deltaMs = Date.now() - ts;
+    if (deltaMs < 60_000)
+        return "just now";
+    if (deltaMs < 3_600_000) {
+        const m = Math.round(deltaMs / 60_000);
+        return `${m}m ago`;
+    }
+    if (deltaMs < 86_400_000) {
+        const h = Math.round(deltaMs / 3_600_000);
+        return `${h}h ago`;
+    }
+    const d = Math.round(deltaMs / 86_400_000);
+    return `${d}d ago`;
+}
+/**
+ * Format a stale-hours number as a short duration. >=24h rounds to days,
+ * smaller values stay in hours. Floors to keep behaviour consistent across
+ * the squad_agents and squad_task_status renderers.
+ */
+function formatStaleDuration(staleHours) {
+    if (staleHours >= 24) {
+        const d = Math.floor(staleHours / 24);
+        return `${d}d`;
+    }
+    return `${Math.floor(staleHours)}h`;
+}
+/**
+ * Build the ⚠️ stalest-specialist hint string from a getStalestSpecialist
+ * result. Returns "" if the input is null (squad is healthy).
+ */
+function formatStalestHint(stalest) {
+    if (!stalest)
+        return "";
+    if (stalest.staleHours == null) {
+        return `⚠️ ${stalest.character_name} has never been delegated to`;
+    }
+    return `⚠️ ${stalest.character_name} has not been delegated to in ${formatStaleDuration(stalest.staleHours)}`;
 }
 // Ensure child processes have HOME set (systemd services often don't)
 function shellEnv() {
@@ -159,7 +336,15 @@ export function createTools(deps) {
                     : "\n  Agents: none — use squad_add_agent to build the team";
                 const coverage = assessSquadCoverage(agents);
                 const coverageLine = coverage.warning ? `\n  ${coverage.warning}` : "";
-                return `- **${s.name}** (\`${s.slug}\`) — ${s.status} — 🎬 ${universeName}${leadLine}${agentList}${coverageLine}\n  📁 ${s.projectPath}`;
+                const distLine = formatWorkDistribution(s.slug, lead, deps);
+                const recentDecisions = deps.getRecentDecisions(s.slug, 3);
+                const decisionsLine = recentDecisions.length === 0
+                    ? "\n  📜 Recent decisions: _none recorded — squad is not capturing institutional knowledge_"
+                    : "\n  📜 Recent decisions: " +
+                        recentDecisions
+                            .map((d) => `\"${d.decision.length > 80 ? d.decision.slice(0, 80) + "…" : d.decision}\"`)
+                            .join("; ");
+                return `- **${s.name}** (\`${s.slug}\`) — ${s.status} — 🎬 ${universeName}${leadLine}${agentList}${coverageLine}${distLine}${decisionsLine}\n  📁 ${s.projectPath}`;
             })
                 .join("\n");
         },
@@ -205,7 +390,7 @@ export function createTools(deps) {
                 }, agent);
                 const agentLabel = agent ? `agent "${agent}" in squad "${slug}"` : `squad "${slug}"`;
                 const warningPrefix = coverage.warning
-                    ? `${coverage.warning} Reviews from this squad will not be vetoed by a designated QA agent until this is fixed.\n\n`
+                    ? `${coverage.warning} A dedicated lead and a QA reviewer should both hold veto power on PR promotion — fix gaps before promoting work.\n\n`
                     : "";
                 return `${warningPrefix}Task delegated to ${agentLabel}. Task ID: ${taskId}\n\nThe agent is working on this in the background. Use squad_task_status to check progress.`;
             }
@@ -233,14 +418,58 @@ export function createTools(deps) {
                     const result = task.result.length > 4000 ? task.result.slice(0, 4000) + "\n[…truncated]" : task.result;
                     response += `\n\nResult:\n${result}`;
                 }
+                // Stalest-specialist hint for the squad this task belongs to (#61).
+                try {
+                    const squadSlug = task.agent_slug.split(":")[0];
+                    if (squadSlug) {
+                        const roster = deps.listSquadAgents(squadSlug);
+                        const characterNames = roster.map((a) => a.character_name);
+                        const lead = roster.find((a) => a.is_lead === 1);
+                        const stalest = deps.getStalestSpecialist(squadSlug, characterNames, {
+                            excludeCharacters: lead ? [lead.character_name] : [],
+                        });
+                        const hint = formatStalestHint(stalest);
+                        if (hint)
+                            response += `\n\n${hint}`;
+                    }
+                }
+                catch (err) {
+                    console.error("[io] squad_task_status: stalest-specialist hint failed:", err);
+                }
                 return response;
             }
             const tasks = deps.getActiveAgentTasks();
             if (tasks.length === 0)
                 return "No active tasks.";
-            return tasks
+            const taskLines = tasks
                 .map((t) => `- **${t.taskId}** (${t.agentSlug}) — ${t.status} — ${t.description}`)
                 .join("\n");
+            // Per-squad stalest-specialist hint block (#61).
+            let hintsBlock = "";
+            try {
+                const uniqueSquadSlugs = Array.from(new Set(tasks.map((t) => t.agentSlug.split(":")[0]).filter((x) => !!x)));
+                const hintLines = [];
+                for (const squadSlug of uniqueSquadSlugs) {
+                    const roster = deps.listSquadAgents(squadSlug);
+                    if (roster.length === 0)
+                        continue;
+                    const characterNames = roster.map((a) => a.character_name);
+                    const lead = roster.find((a) => a.is_lead === 1);
+                    const stalest = deps.getStalestSpecialist(squadSlug, characterNames, {
+                        excludeCharacters: lead ? [lead.character_name] : [],
+                    });
+                    const hint = formatStalestHint(stalest);
+                    if (hint)
+                        hintLines.push(`- ${squadSlug}: ${hint}`);
+                }
+                if (hintLines.length > 0) {
+                    hintsBlock = `\n\n**Distribution hints:**\n${hintLines.join("\n")}`;
+                }
+            }
+            catch (err) {
+                console.error("[io] squad_task_status: distribution hints failed:", err);
+            }
+            return `${taskLines}${hintsBlock}`;
         },
     });
     // --- Squad analyze ---
@@ -423,14 +652,49 @@ export function createTools(deps) {
             const universeName = squad.universe
                 ? UNIVERSES.find((u) => u.id === squad.universe)?.name ?? squad.universe
                 : "none";
+            // Pull per-agent task stats once and key by character_name (issue #61).
+            // If the helper throws (e.g. brand-new DB before view migration), fall
+            // back to an empty map so rendering is unchanged rather than 500-ing.
+            const characterNames = agents.map((a) => a.character_name);
+            const statsByName = new Map();
+            try {
+                for (const st of deps.getAgentTaskStats(slug, characterNames)) {
+                    statsByName.set(st.character_name, {
+                        task_count: st.task_count,
+                        last_delegated_at: st.last_delegated_at,
+                    });
+                }
+            }
+            catch (err) {
+                console.error("[io] squad_agents: getAgentTaskStats failed:", err);
+            }
             const lines = agents.map((a) => {
                 const leadBadge = a.is_lead === 1 ? " ⭐ [LEAD]" : "";
                 const qaBadge = a.is_qa === 1 ? " 🛡️ [QA]" : "";
-                return `- **${a.character_name}**${leadBadge}${qaBadge} — ${a.role_title} (${a.model_tier}) — ${a.status}${a.personality ? `\n  _${a.personality}_` : ""}`;
+                const st = statsByName.get(a.character_name) ?? { task_count: 0, last_delegated_at: null };
+                const statsStr = st.task_count === 0
+                    ? " — 📊 never delegated"
+                    : ` — 📊 ${st.task_count} ${st.task_count === 1 ? "task" : "tasks"} · last ${formatRelativeTime(st.last_delegated_at)}`;
+                return `- **${a.character_name}**${leadBadge}${qaBadge} — ${a.role_title} (${a.model_tier}) — ${a.status}${statsStr}${a.personality ? `\n  _${a.personality}_` : ""}`;
             });
             const coverage = assessSquadCoverage(agents);
             const coverageBlock = coverage.warning ? `\n\n${coverage.warning}` : "";
-            return `**${squad.name}** — 🎬 ${universeName}\n\n${lines.join("\n")}${coverageBlock}`;
+            // Stalest-specialist hint (issue #61): exclude the lead so the hint
+            // points at an under-utilised teammate rather than the coordinator.
+            let stalestBlock = "";
+            try {
+                const lead = agents.find((a) => a.is_lead === 1);
+                const stalest = deps.getStalestSpecialist(slug, characterNames, {
+                    excludeCharacters: lead ? [lead.character_name] : [],
+                });
+                const hint = formatStalestHint(stalest);
+                if (hint)
+                    stalestBlock = `\n\n${hint}`;
+            }
+            catch (err) {
+                console.error("[io] squad_agents: getStalestSpecialist failed:", err);
+            }
+            return `**${squad.name}** — 🎬 ${universeName}\n\n${lines.join("\n")}${coverageBlock}${stalestBlock}`;
         },
     });
     // --- Squad remove agent ---
@@ -449,6 +713,33 @@ export function createTools(deps) {
                 : `Agent "${character_name}" not found in squad "${slug}".`;
         },
     });
+    const squadResetAgent = defineTool("squad_reset_agent", {
+        description: "Clear a squad agent's error state and return them to idle without removing them. Preserves their charter, role title, character name, and is_lead/is_qa flags. Drops the agent's in-memory and persisted Copilot session so the next task starts fresh. Safe to call on a non-error agent (no-op with a clear message).",
+        skipPermission: true,
+        parameters: z.object({
+            slug: z.string().describe("Squad slug"),
+            character_name: z.string().describe("Character name of the agent to reset"),
+        }),
+        handler: async ({ slug, character_name }) => {
+            console.error(`[io] squad_reset_agent called: ${slug} — ${character_name}`);
+            const squad = deps.getSquad(slug);
+            if (!squad)
+                return `Squad not found: ${slug}`;
+            const result = deps.resetSquadAgent(slug, character_name);
+            if (!result.found || !result.agent) {
+                return `Agent "${character_name}" not found in squad "${slug}".`;
+            }
+            const { previousStatus, agent } = result;
+            if (previousStatus === "error") {
+                return `🔄 ${agent.character_name} (${agent.role_title}) reset from 'error' → 'idle'. Charter and role preserved; next task will create a fresh Copilot session.`;
+            }
+            if (previousStatus === "idle") {
+                return `${agent.character_name} (${agent.role_title}) is already 'idle'. No-op: in-memory session cache and persisted session id were cleared anyway so the next task starts fresh.`;
+            }
+            // working / unknown
+            return `⚠️ ${agent.character_name} (${agent.role_title}) was in '${previousStatus}' (not 'error'). Forced to 'idle' and cleared session anyway — verify no task is actually still running for this agent (call squad_task_status).`;
+        },
+    });
     // --- Squad delete ---
     const squadDelete = defineTool("squad_delete", {
         description: "Delete a squad and all its agents and decisions. This is permanent.",
@@ -485,10 +776,10 @@ export function createTools(deps) {
         },
     });
     const skillInstall = defineTool("skill_install", {
-        description: "Install a skill from a git repository URL. The repo must contain a SKILL.md file.",
+        description: "Install a skill from a git repository URL or a direct SKILL.md file URL. Accepts full repo URLs (clones the repo) and GitHub blob/raw URLs pointing to a specific SKILL.md (fetches just that file).",
         skipPermission: true,
         parameters: z.object({
-            repo_url: z.string().describe("Git repository URL (e.g., https://github.com/user/my-skill.git)"),
+            repo_url: z.string().describe("Git repository URL (e.g., https://github.com/user/my-skill.git) or direct SKILL.md URL (e.g., https://github.com/user/repo/blob/main/skills/my-skill/SKILL.md)"),
         }),
         handler: async ({ repo_url }) => {
             console.error(`[io] skill_install called: ${repo_url}`);
@@ -1115,13 +1406,13 @@ export function createTools(deps) {
         },
     });
     const squadSetLead = defineTool("squad_set_lead", {
-        description: "Designate an agent as the team lead for their squad. The lead receives delegated tasks (when no specific agent is targeted) and orchestrates the team by divvying subtasks to teammates.",
+        description: "Designate an agent as the team lead for their squad. The lead MUST be a dedicated PM / Senior Engineer with NO domain responsibility — their sole job is coordinating, delegating, and reviewing the team's work. Do not pick an agent who also owns the backend, frontend, tests, or any other implementation domain. The lead receives delegated tasks (when no specific agent is targeted), orchestrates the team via delegate_to_teammate, and holds automatic veto power on PR promotion.",
         skipPermission: true,
         parameters: z.object({
             slug: z.string().describe("Squad slug"),
             character_name: z
                 .string()
-                .describe("Character name of the agent to make team lead"),
+                .describe("Character name of the agent to make team lead. Choose a PM / Senior Engineer with no domain ownership."),
         }),
         handler: async ({ slug, character_name }) => {
             try {
@@ -1134,7 +1425,12 @@ export function createTools(deps) {
                     return `Agent "${character_name}" not found in squad "${slug}". Use squad_agents to list the roster.`;
                 }
                 deps.setSquadLead(slug, character_name);
-                return `⭐ ${character_name} (${target.role_title}) is now the team lead for squad "${squad.name}".`;
+                const dedicated = roleLooksLikeDedicatedLead(target.role_title);
+                const base = `⭐ ${character_name} (${target.role_title}) is now the team lead for squad "${squad.name}". They have automatic veto power on PR promotion.`;
+                if (!dedicated) {
+                    return `${base}\n\n⚠️ "${target.role_title}" looks like a domain specialist. Team leads should be a dedicated PM / Senior Engineer with no other domain responsibility — consider adding a dedicated lead agent (e.g. role "Senior Engineering Lead" or "Project Manager") and reassigning.`;
+                }
+                return base;
             }
             catch (err) {
                 return `Error: ${err instanceof Error ? err.message : String(err)}`;
@@ -1376,7 +1672,7 @@ export function createTools(deps) {
             return `🚀 Fired IO schedule ${id} now.`;
         },
     });
-    return [wikiRead, wikiWrite, wikiSearch, wikiDelete, wikiList, squadCreate, squadRecall, squadStatus, squadLogDecision, squadDelegate, squadTaskStatus, squadDelete, squadAnalyze, squadAddAgent, squadAgents, squadRemoveAgent, squadSetLead, squadSetQA, squadTaskReviews, squadScheduleCreate, squadScheduleList, squadScheduleDelete, squadSchedulePause, squadScheduleResume, squadScheduleRunNow, scheduleCreate, scheduleList, scheduleDelete, schedulePause, scheduleResume, scheduleRunNow, skillList, skillInstall, skillRemove, skillSearch, configUpdate, checkUpdate, shell, fileOps, bash, readFile, viewTool, grepTool, strReplaceEditor, github];
+    return [wikiRead, wikiWrite, wikiSearch, wikiDelete, wikiList, squadCreate, squadRecall, squadStatus, squadLogDecision, squadDelegate, squadTaskStatus, squadDelete, squadAnalyze, squadAddAgent, squadAgents, squadRemoveAgent, squadResetAgent, squadSetLead, squadSetQA, squadTaskReviews, squadScheduleCreate, squadScheduleList, squadScheduleDelete, squadSchedulePause, squadScheduleResume, squadScheduleRunNow, scheduleCreate, scheduleList, scheduleDelete, schedulePause, scheduleResume, scheduleRunNow, skillList, skillInstall, skillRemove, skillSearch, configUpdate, checkUpdate, shell, fileOps, bash, readFile, viewTool, grepTool, strReplaceEditor, github];
 }
 function walkDirectory(dir, maxDepth = 3, depth = 0) {
     if (depth >= maxDepth)

package/dist/daemon.js

@@ -1,7 +1,11 @@
 import { getClient, stopClient } from "./copilot/client.js";
 import { initOrchestrator, sendToOrchestrator, shutdownOrchestrator } from "./copilot/orchestrator.js";
-import { startApiServer, setMessageHandler as setApiHandler } from "./api/server.js";
-import { createBot, startBot, stopBot, sendProactiveMessage, setMessageHandler as setTelegramHandler } from "./telegram/bot.js";
+import { startApiServer, setMessageHandler as setApiHandler, broadcastNotificationToSSE } from "./api/server.js";
+import { createBot, startBot, stopBot, sendProactiveMessage, sendBackgroundNotification, setMessageHandler as setTelegramHandler } from "./telegram/bot.js";
+import { setTelegramSender, setTuiSender, setSseBroadcaster } from "./notify.js";
+import { pruneOldScheduleRuns } from "./store/schedule-runs.js";
+import { pruneOldNotifications } from "./store/notifications.js";
+import { printBackgroundNotification } from "./tui/index.js";
 import { getDb, closeDb } from "./store/db.js";
 import { clearStaleTasks } from "./store/tasks.js";
 import { reconcileAgentStatuses, reconcileSquadStatuses } from "./store/squads.js";
@@ -118,6 +122,35 @@ export async function startDaemon() {
     startScheduler();
     // Start the IO-level scheduler (squad-independent recurring tasks).
     startIoScheduler();
+    // Background-notification dispatch surfaces (issue #78)
+    setSseBroadcaster((p) => broadcastNotificationToSSE(p));
+    setTuiSender((opts) => printBackgroundNotification(opts));
+    setTelegramSender((opts) => sendBackgroundNotification(opts));
+    // Daily cleanup — prune schedule runs and notifications older than 30 days
+    const PRUNE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+    const PRUNE_RETENTION_DAYS = 30;
+    const pruneTimer = setInterval(() => {
+        try {
+            const runsDeleted = pruneOldScheduleRuns(PRUNE_RETENTION_DAYS);
+            const notificationsDeleted = pruneOldNotifications(PRUNE_RETENTION_DAYS);
+            if (runsDeleted > 0 || notificationsDeleted > 0) {
+                console.log(`[prune] Cleaned up ${runsDeleted} schedule runs and ${notificationsDeleted} notifications older than ${PRUNE_RETENTION_DAYS} days`);
+            }
+        }
+        catch (err) {
+            console.error("[prune] Error during cleanup:", err);
+        }
+    }, PRUNE_INTERVAL_MS);
+    pruneTimer.unref();
+    // Run once on startup after a brief delay
+    const pruneStartup = setTimeout(() => {
+        try {
+            pruneOldScheduleRuns(PRUNE_RETENTION_DAYS);
+            pruneOldNotifications(PRUNE_RETENTION_DAYS);
+        }
+        catch { /* best effort */ }
+    }, 5000);
+    pruneStartup.unref?.();
     console.log("[io] IO is fully operational.");
     // Notify Telegram if restarting
     if (config.telegramEnabled && process.env.IO_RESTARTED === "1") {

package/dist/notify.js

@@ -0,0 +1,105 @@
+import { config } from "./config.js";
+import { insertNotification, } from "./store/notifications.js";
+const HEARTBEAT_PATTERNS = [
+    /^no active tasks?\.?$/i,
+    /^nothing to report\.?$/i,
+    /^all clear\.?$/i,
+    /^no updates?\.?$/i,
+    /^no changes?\.?$/i,
+    /^idle\.?$/i,
+    /^heartbeat\.?$/i,
+    /^ok\.?$/i,
+];
+export function isMeaningfulOutput(text) {
+    const trimmed = (text ?? "").trim();
+    if (trimmed.length < 20)
+        return false;
+    const firstLine = trimmed.split("\n").map((l) => l.trim()).find((l) => l.length > 0) ?? "";
+    if (HEARTBEAT_PATTERNS.some((re) => re.test(firstLine)))
+        return false;
+    return true;
+}
+let telegramSender;
+let tuiSender;
+let sseBroadcaster;
+export function setTelegramSender(fn) {
+    telegramSender = fn;
+}
+export function setTuiSender(fn) {
+    tuiSender = fn;
+}
+export function setSseBroadcaster(fn) {
+    sseBroadcaster = fn;
+}
+export function _resetNotifySendersForTests() {
+    telegramSender = undefined;
+    tuiSender = undefined;
+    sseBroadcaster = undefined;
+}
+export async function notifyBackground(input) {
+    const dispatched = { telegram: false, tui: false, sse: false };
+    const text = (input.text ?? "").trim();
+    if (text.length === 0)
+        return { dispatched, skipped: "empty" };
+    const mode = config.backgroundNotifyMode ?? "meaningful";
+    if (mode === "off")
+        return { dispatched, skipped: "off" };
+    if (mode === "meaningful" && !isMeaningfulOutput(text)) {
+        return { dispatched, skipped: "not-meaningful" };
+    }
+    const { source, title } = input;
+    const sourceRefJson = JSON.stringify(stripType(source));
+    let row;
+    try {
+        row = insertNotification({
+            source_type: source.type,
+            source_ref: sourceRefJson === "{}" ? null : sourceRefJson,
+            title,
+            text,
+        });
+    }
+    catch (err) {
+        console.error("[notify] failed to persist notification:", err);
+        return { dispatched };
+    }
+    if (sseBroadcaster) {
+        try {
+            sseBroadcaster({
+                id: row.id,
+                source: { type: source.type, ...stripType(source) },
+                title,
+                text,
+                createdAt: row.created_at,
+            });
+            dispatched.sse = true;
+        }
+        catch (err) {
+            console.error("[notify] sse broadcast failed:", err);
+        }
+    }
+    if (tuiSender && (config.backgroundNotifyTui ?? true)) {
+        try {
+            tuiSender({ title, text });
+            dispatched.tui = true;
+        }
+        catch (err) {
+            console.error("[notify] tui send failed:", err);
+        }
+    }
+    if (telegramSender && (config.backgroundNotifyTelegram ?? true)) {
+        try {
+            await telegramSender({ title, text });
+            dispatched.telegram = true;
+        }
+        catch (err) {
+            console.error("[notify] telegram send failed:", err);
+        }
+    }
+    return { id: row.id, dispatched };
+}
+function stripType(s) {
+    const { type: _t, ...rest } = s;
+    void _t;
+    return rest;
+}
+//# sourceMappingURL=notify.js.map