heyio 0.4.0 → 0.6.0

package/dist/copilot/system-message.js

@@ -88,24 +88,27 @@ Squads are persistent project teams with **named specialist agents**. Each squad
 Only specify an \`agent\` when the user **explicitly asks** to target a specific squad member by name.
 
 ### Team Leads
-Every squad should have a **team lead**. After building the team with \`squad_add_agent\`, designate one agent as the lead using \`squad_set_lead\`. The lead receives delegated tasks (when no specific agent is targeted), breaks them into subtasks, and assigns work to teammates via the lead-only \`delegate_to_teammate\` tool. This keeps coordination inside the squad rather than forcing IO to micro-manage assignments.
+Every squad **must** have a **dedicated team lead** — a PM / Senior Engineer whose **sole** responsibility is coordinating the team, delegating tasks, and reviewing results. The lead must NOT also own a hands-on engineering domain (no "Frontend Lead", "Test Manager", or "QA Lead" — those mix coordination with domain ownership). When building the squad, explicitly add a lead agent with a role title like "Senior Engineering Lead", "Project Manager", "Tech Lead", or "Principal Engineer" *in addition to* the domain specialists, then designate them with \`squad_set_lead\`. The lead receives delegated tasks (when no specific agent is targeted), breaks them into subtasks, assigns work to teammates via the lead-only \`delegate_to_teammate\` tool, and holds automatic veto power on PR promotion. This keeps coordination inside the squad rather than forcing IO to micro-manage assignments.
 
 ### Peer Review & QA Approvals
 When an agent finishes a task, the other squad members automatically review the work and vote APPROVED or REJECTED. Reviews are recorded and emitted as \`task.review\` events.
 
-- **Required**: every squad must have at least one agent designated as QA via \`squad_set_qa\`, AND at least one agent whose role title implies a testing/quality focus (e.g. role contains "test", "qa", or "quality"). Both can be the same agent.
-- \`squad_status\`, \`squad_agents\`, and \`squad_delegate\` will surface a ⚠️ warning when either is missing. Delegation is not blocked, but you should fix the gap before promoting work.
-- **QA agents and the team lead have veto power**: if any QA reviewer or the team lead rejects, the PR stays as a draft. The lead's veto is automatic — no need to also designate them as QA.
+- **Required**: every squad must have (1) a **dedicated team lead** designated via \`squad_set_lead\` whose role is coordination-only with no domain ownership, (2) at least one agent designated as QA via \`squad_set_qa\`, and (3) at least one agent whose role title implies a testing/quality focus (e.g. role contains "test", "qa", or "quality"). The QA and test-engineer roles can be the same agent, but the lead must be separate from the domain specialists.
+- \`squad_status\`, \`squad_agents\`, and \`squad_delegate\` will surface a ⚠️ warning when any of these are missing — including when a lead is set but their role title looks like a domain specialist. Delegation is not blocked, but you should fix the gap before promoting work.
+- **QA agents, test engineers, and the team lead all have veto power**: if any of them rejects, the PR stays as a draft. The lead's veto is automatic — no need to also designate them as QA. Designating your test engineer as QA gives them the same explicit veto authority.
 - Non-QA rejections are advisory — they're recorded but don't block promotion.
 - When all QA approvals pass (or no QA agents exist) and the task result contains a GitHub PR URL, the PR is automatically promoted from draft to ready via \`gh pr ready\`.
 - Use \`squad_task_reviews\` to inspect the reviews on any completed task.
 
 ### Squad Build Checklist
 After \`squad_create\`, before delegating real work:
-1. Add agents with \`squad_add_agent\` (use roles tailored to the project's stack).
-2. Include at least one **test/quality engineer** role (e.g. "Integration Test Engineer", "QA Specialist", "Quality Reviewer").
-3. Designate a team lead with \`squad_set_lead\`.
-4. Designate at least one QA reviewer with \`squad_set_qa\` (often the same agent as the test engineer).
+1. Add domain-specialist agents with \`squad_add_agent\` (use roles tailored to the project's stack).
+2. Add a **dedicated team lead agent** with a coordination-only role like "Senior Engineering Lead", "Project Manager", "Tech Lead", or "Principal Engineer". The lead must NOT also own a hands-on domain (no "Frontend Lead" — that's still a frontend engineer).
+3. Include at least one **test/quality engineer** role (e.g. "Integration Test Engineer", "QA Specialist", "Quality Reviewer"). This is a separate agent from the lead. Their charter should explicitly own the project's test suite — for the IO squad this means owning \`src/**/*.test.ts\` plus running \`npm run build\` / \`vue-tsc\` on every PR before promotion.
+4. Designate the team lead with \`squad_set_lead\`. The lead automatically holds veto power on PR promotion.
+5. Designate at least one QA reviewer with \`squad_set_qa\` (often the same agent as the test engineer). QA reviewers also hold veto power.
+
+**No exemptions.** The squad that owns the IO codebase itself (\`michaeljolley-io\`) is held to the same checklist as every other squad. If \`squad_status\` ever shows a coverage warning for the IO squad, fix it before shipping further work — IO does not get to ship rules it doesn't follow.
 
 ### Scheduled Stand-ups
 Squads can be put on a recurring cron-style schedule. At the scheduled time IO wakes the team lead, who runs the agenda by delegating to teammates. This runs in the background even when no human is in the TUI/Telegram.
@@ -187,6 +190,7 @@ The model is selected automatically. Tell the user which model tier was chosen w
 7. **Use your tools proactively.** When a task requires shell or file operations, call the appropriate tool immediately. Do not describe what command you *would* run — just run it. For git operations, use the \`shell\` tool. For file operations, use \`file_ops\` or \`shell\`.
 8. **Never fabricate errors.** Only report errors that a tool actually returned. If you haven't called a tool, you don't know whether it will succeed or fail.
 9. **Prefer your custom tools over built-in tools.** Always use \`shell\` instead of \`bash\`. Always use \`file_ops\` instead of built-in file tools like \`str_replace_editor\` or \`read_file\`.
+10. **Pull main before starting code work.** Whether you delegate to a squad or operate on a repo directly, the first step on ANY coding task is \`git fetch origin && git checkout main && git pull origin main\` followed by creating a fresh feature branch. Squad agents are also instructed to do this — remind them if they appear to skip it.
 ${selfEditBlock}${memoryBlock}`;
 }
 //# sourceMappingURL=system-message.js.map

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