heyio 0.5.0 → 0.6.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.",
@@ -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/store/db.js

@@ -109,6 +109,12 @@ export function getDb() {
     )`,
         `CREATE INDEX IF NOT EXISTS idx_io_schedules_due
        ON io_schedules (enabled, next_run_at)`,
+        `CREATE VIEW IF NOT EXISTS agent_stats AS
+SELECT agent_slug,
+       COUNT(*)        AS task_count,
+       MAX(started_at) AS last_delegated_at
+FROM agent_tasks
+GROUP BY agent_slug`,
     ];
     for (const migration of migrations) {
         try {

package/dist/store/squads.js

@@ -93,6 +93,16 @@ export function updateAgentStatus(squadSlug, characterName, status) {
         .prepare("UPDATE squad_agents SET status = ? WHERE squad_slug = ? AND character_name = ?")
         .run(status, squadSlug, characterName);
 }
+/**
+ * Clear an agent's persisted copilot_session_id. Used during error recovery
+ * so the next task creates a fresh session instead of trying to resume a
+ * poisoned one.
+ */
+export function clearAgentSession(squadSlug, characterName) {
+    getDb()
+        .prepare("UPDATE squad_agents SET copilot_session_id = NULL WHERE squad_slug = ? AND character_name = ?")
+        .run(squadSlug, characterName);
+}
 /**
  * Reset any agent left in a non-idle status from a previous daemon run.
  * The in-memory Copilot sessions don't survive a restart, so persisted

package/dist/store/tasks.js

@@ -39,6 +39,28 @@ export function listRecentTasks(limit = 50) {
         .prepare("SELECT * FROM agent_tasks ORDER BY datetime(started_at) DESC, task_id DESC LIMIT ?")
         .all(limit);
 }
+/**
+ * Per-agent task count for the most recent `limit` tasks belonging to a
+ * squad. Matches tasks routed to the squad itself (`agent_slug = squadSlug`)
+ * AND tasks routed to a named agent on the squad (`agent_slug LIKE 'squadSlug:%'`).
+ * Used by squad_status to surface fan-out imbalance.
+ */
+export function getSquadWorkDistribution(squadSlug, limit = 20) {
+    const rows = getDb()
+        .prepare(`SELECT agent_slug FROM agent_tasks
+       WHERE agent_slug = ? OR agent_slug LIKE ?
+       ORDER BY datetime(started_at) DESC, task_id DESC
+       LIMIT ?`)
+        .all(squadSlug, `${squadSlug}:%`, limit);
+    const counts = new Map();
+    for (const row of rows) {
+        counts.set(row.agent_slug, (counts.get(row.agent_slug) ?? 0) + 1);
+    }
+    const perAgent = Array.from(counts.entries())
+        .map(([agent_slug, count]) => ({ agent_slug, count }))
+        .sort((a, b) => b.count - a.count);
+    return { total: rows.length, perAgent };
+}
 export function createReview(taskId, squadSlug, reviewerCharacter, approved, comments) {
     const db = getDb();
     const info = db
@@ -53,4 +75,104 @@ export function getTaskReviews(taskId) {
         .prepare("SELECT * FROM squad_task_reviews WHERE task_id = ? ORDER BY created_at ASC, id ASC")
         .all(taskId);
 }
+/**
+ * Per-character delegation stats for a squad.
+ *
+ * Returns one row PER CHARACTER NAME passed in `characterNames`, plus an
+ * extra row with character_name="" for any tasks routed to the bare squad
+ * slug (legacy lead tasks). Always returns a row for every requested
+ * character, even if they have never been delegated to (task_count: 0,
+ * last_delegated_at: null).
+ *
+ * Reads from the agent_stats view. Filters with `agent_slug = ?`
+ * (for the bare slug) and `agent_slug = ?` for each `<slug>:<char>`.
+ */
+export function getAgentTaskStats(squadSlug, characterNames) {
+    // Build the full set of agent_slug values we care about
+    const bareSlug = squadSlug;
+    const namedSlugs = characterNames.map((c) => `${squadSlug}:${c}`);
+    const allSlugs = [bareSlug, ...namedSlugs];
+    const placeholders = allSlugs.map(() => "?").join(", ");
+    const rows = getDb()
+        .prepare(`SELECT agent_slug, task_count, last_delegated_at FROM agent_stats WHERE agent_slug IN (${placeholders})`)
+        .all(...allSlugs);
+    const bySlug = new Map();
+    for (const row of rows)
+        bySlug.set(row.agent_slug, row);
+    const results = [];
+    // Bare slug row (legacy lead tasks routed without a named agent)
+    const bareRow = bySlug.get(bareSlug);
+    results.push({
+        character_name: "",
+        agent_slug: bareSlug,
+        task_count: bareRow?.task_count ?? 0,
+        last_delegated_at: bareRow?.last_delegated_at ?? null,
+    });
+    // One row per requested character
+    for (const char of characterNames) {
+        const slug = `${squadSlug}:${char}`;
+        const row = bySlug.get(slug);
+        results.push({
+            character_name: char,
+            agent_slug: slug,
+            task_count: row?.task_count ?? 0,
+            last_delegated_at: row?.last_delegated_at ?? null,
+        });
+    }
+    return results;
+}
+/**
+ * Pick the stalest specialist in a squad. "Stalest" = the character who
+ * has been delegated to least recently (oldest last_delegated_at), with
+ * never-delegated agents considered staler than any delegated agent.
+ *
+ * Excludes character names listed in `excludeCharacters` (use this to
+ * skip the lead). Returns null if the squad has no eligible agents OR if
+ * all eligible agents have been delegated to within `freshIfWithinHours`
+ * (default 48). The threshold is meant to suppress the hint when the
+ * squad is already distributing well.
+ *
+ * On tie (e.g. two agents have never been delegated), returns the one
+ * that sorts first by character_name (deterministic).
+ */
+export function getStalestSpecialist(squadSlug, characterNames, options) {
+    const exclude = new Set(options?.excludeCharacters ?? []);
+    const freshThresholdHours = options?.freshIfWithinHours ?? 48;
+    const stats = getAgentTaskStats(squadSlug, characterNames);
+    // Filter: named agents only (skip the bare-slug "" row), skip excluded
+    const eligible = stats.filter((s) => s.character_name !== "" && !exclude.has(s.character_name));
+    if (eligible.length === 0)
+        return null;
+    const now = Date.now();
+    // Sort: never-delegated (null) first, then ascending by last_delegated_at
+    eligible.sort((a, b) => {
+        if (a.last_delegated_at === null && b.last_delegated_at === null) {
+            return a.character_name.localeCompare(b.character_name);
+        }
+        if (a.last_delegated_at === null)
+            return -1;
+        if (b.last_delegated_at === null)
+            return 1;
+        const tA = new Date(a.last_delegated_at + "Z").getTime();
+        const tB = new Date(b.last_delegated_at + "Z").getTime();
+        if (tA !== tB)
+            return tA - tB;
+        return a.character_name.localeCompare(b.character_name);
+    });
+    const stalest = eligible[0];
+    let staleHours = null;
+    if (stalest.last_delegated_at !== null) {
+        const delegatedAt = new Date(stalest.last_delegated_at + "Z").getTime();
+        staleHours = Math.round((now - delegatedAt) / 3_600_000);
+        // Squad is distributing well — suppress the hint
+        if (staleHours < freshThresholdHours)
+            return null;
+    }
+    // null last_delegated_at means never-delegated: always considered stale
+    return {
+        character_name: stalest.character_name,
+        last_delegated_at: stalest.last_delegated_at,
+        staleHours,
+    };
+}
 //# sourceMappingURL=tasks.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heyio",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "IO — a personal AI assistant built on the GitHub Copilot SDK",
   "bin": {
     "io": "dist/index.js"