heyio 0.5.0 → 0.6.0

package/dist/api/server.js

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 import express from "express";
 import { config } from "../config.js";
-import { listSkills } from "../copilot/skills.js";
+import { listSkills, installSkill } from "../copilot/skills.js";
 import { listSquads, createSquad, listSquadAgents } from "../store/squads.js";
 import { getAgentInfo, cancelAgentTask, getTaskEvents, subscribeToTaskEvents } from "../copilot/agents.js";
 import { summarize, summarizeEvent } from "../copilot/event-summary.js";
@@ -67,6 +67,36 @@ export async function startApiServer() {
             res.status(500).json({ error: "Failed to list skills" });
         }
     });
+    // Install a skill from a git repo URL (mirrors the skill_install tool)
+    api.post("/skills", async (req, res) => {
+        const { repoUrl } = req.body;
+        if (repoUrl === undefined || repoUrl === null || typeof repoUrl !== "string") {
+            res.status(400).json({ error: "Missing required field: repoUrl" });
+            return;
+        }
+        if (repoUrl.trim() === "") {
+            res.status(400).json({ error: "repoUrl must not be empty" });
+            return;
+        }
+        const trimmed = repoUrl.trim();
+        const looksLikeGitUrl = trimmed.startsWith("http://") ||
+            trimmed.startsWith("https://") ||
+            trimmed.startsWith("git@") ||
+            trimmed.startsWith("git://") ||
+            trimmed.endsWith(".git");
+        if (!looksLikeGitUrl) {
+            res.status(400).json({ error: "repoUrl does not look like a git repository URL" });
+            return;
+        }
+        try {
+            const skill = await installSkill(trimmed);
+            res.status(201).json({ skill });
+        }
+        catch (e) {
+            console.error("Error installing skill:", e);
+            res.status(500).json({ error: e instanceof Error ? e.message : String(e) });
+        }
+    });
     // Squads endpoints
     api.get("/squads", (_req, res) => {
         try {

package/dist/copilot/agents.js

@@ -7,8 +7,9 @@ import { homedir } from "os";
 import { defineTool, approveAll } from "@github/copilot-sdk";
 import { z } from "zod";
 import { getClient } from "./client.js";
+import { sendWithIdleTimeout } from "./session-timeout.js";
 import { getModelForTask, getModelForTier, classifyComplexity } from "./model-router.js";
-import { getSquad, updateSquadSession, updateSquadStatus, getDecisionsSummary, logDecision, listSquadAgents, getSquadAgent, getSquadLead, updateAgentSession, updateAgentStatus, } from "../store/squads.js";
+import { getSquad, updateSquadSession, updateSquadStatus, getDecisions, getDecisionsSummary, logDecision, listSquadAgents, getSquadAgent, getSquadLead, updateAgentSession, updateAgentStatus, } from "../store/squads.js";
 import { createTask, completeTask, createReview, failTask, getActiveTasks, getTask, cancelTask, } from "../store/tasks.js";
 import { SESSIONS_DIR } from "../paths.js";
 import { getUniverse } from "./universes.js";
@@ -18,6 +19,16 @@ const agentSessionModels = new Map();
 function agentSessionKey(squadSlug, characterName) {
     return characterName ? `${squadSlug}:${characterName}` : squadSlug;
 }
+/**
+ * Drop the in-memory cached Copilot session (and model) for an agent so the
+ * next task creates a fresh one. Pairs with `clearAgentSession` in the
+ * store, which nulls the persisted copilot_session_id.
+ */
+export function clearAgentInMemorySession(squadSlug, characterName) {
+    const key = agentSessionKey(squadSlug, characterName);
+    agentSessions.delete(key);
+    agentSessionModels.delete(key);
+}
 export function getAgentInfo() {
     const activeTasks = getActiveTasks();
     const tasksByAgent = new Map();
@@ -104,6 +115,49 @@ export function subscribeToTaskEvents(taskId, listener) {
     taskEventEmitter.on(taskId, listener);
     return () => taskEventEmitter.off(taskId, listener);
 }
+// ---------------------------------------------------------------------------
+// Task prompt envelope (issue #54)
+//
+// Before sending a task to an agent we prepend a short "Recent squad
+// decisions" preamble and append a tail that asks the agent to call
+// squad_log_decision if their work involved a non-trivial architectural
+// choice. This is the lowest-friction nudge we can give: agents see what
+// they're augmenting AND a reminder to capture institutional knowledge.
+// ---------------------------------------------------------------------------
+const RECENT_DECISIONS_LIMIT = 5;
+function buildTaskPromptEnvelope(squadSlug, task) {
+    const recent = getDecisions(squadSlug, RECENT_DECISIONS_LIMIT);
+    const preamble = recent.length === 0
+        ? `## Recent squad decisions
+_(None recorded yet — be the first to log one with \`squad_log_decision\` if your work involves a real architectural choice.)_`
+        : `## Recent squad decisions (last ${recent.length})
+You should treat these as load-bearing context. Reverse them only with a clear reason and a new \`squad_log_decision\` entry.
+
+${recent
+            .slice()
+            .reverse()
+            .map((d) => {
+            const ctx = d.context ? ` — _${d.context}_` : "";
+            return `- [${d.created_at}] **${d.decision}**${ctx}`;
+        })
+            .join("\n")}`;
+    const tail = `## Capturing institutional knowledge
+When you finish this task, if your work involved a non-trivial architectural choice (a strategy, a tradeoff, an interface decision, a workaround with a clear reason), call \`squad_log_decision\` with **one sentence** summarizing the choice and **a short context** explaining why. Examples:
+- decision: "Use idle-reset timeout instead of wall-clock for agent tasks" / context: "Wall-clock killed 2/3 long-running tasks mid-progress (#42, #45)."
+- decision: "Veto power expanded to lead + QA + test engineers" / context: "Single-reviewer veto was too narrow when test engineer wasn't designated QA."
+
+If your work was a routine implementation that didn't make a real choice (e.g. small docs edit, mechanical refactor, one-line fix), skip the call — don't log noise.`;
+    return `${preamble}
+
+---
+
+## Task
+${task}
+
+---
+
+${tail}`;
+}
 export async function delegateToAgent(squadSlug, task, onComplete, targetAgent) {
     const squad = getSquad(squadSlug);
     if (!squad) {
@@ -131,13 +185,26 @@ export async function delegateToAgent(squadSlug, task, onComplete, targetAgent)
             }
         }
     }
+    const agentKey = agent
+        ? agentSessionKey(squadSlug, agent.character_name)
+        : squadSlug;
+    // Idempotency: if an identical task is already running on this agent_slug,
+    // join the existing task instead of racing a second instance. (Issue #53)
+    const normalizedTask = task.trim();
+    const duplicate = getActiveTasks().find((t) => t.agent_slug === agentKey && t.description.trim() === normalizedTask);
+    if (duplicate) {
+        console.error(`[io] Dedup: task with identical description already running on ${agentKey} (taskId=${duplicate.task_id}); returning existing taskId.`);
+        recordTaskEvent(duplicate.task_id, {
+            ts: Date.now(),
+            type: "task.dedup_joined",
+            data: { agentKey, description: normalizedTask },
+        });
+        return duplicate.task_id;
+    }
     const session = agent
         ? await getOrCreateAgentSession(squadSlug, agent, task)
         : await getOrCreateSession(squadSlug, task);
     const taskId = randomUUID();
-    const agentKey = agent
-        ? agentSessionKey(squadSlug, agent.character_name)
-        : squadSlug;
     createTask(taskId, agentKey, task);
     updateSquadStatus(squadSlug, "working");
     if (agent)
@@ -161,8 +228,40 @@ export async function delegateToAgent(squadSlug, task, onComplete, targetAgent)
     // Run the task in the background — return taskId immediately
     void (async () => {
         try {
-            const response = await session.sendAndWait({ prompt: task }, 600_000);
-            const result = response?.data?.content ?? "Task completed (no output)";
+            const envelopedTask = buildTaskPromptEnvelope(squadSlug, task);
+            const sendResult = await sendWithIdleTimeout(session, envelopedTask, {
+                // Reset on every progress event; only abort if the agent goes
+                // genuinely silent for this long. 10 minutes covers the longest
+                // realistic tool call (npm install, full build, large file edits)
+                // while still catching truly stuck sessions. (Issue #53)
+                idleMs: 10 * 60_000,
+                // Absolute upper bound — 60 minutes. Anything longer is almost
+                // certainly a runaway loop; cap it.
+                hardCapMs: 60 * 60_000,
+                onIdleTimeout: ({ lastEventType, idleMs }) => {
+                    console.error(`[io] Agent task ${taskId} idle for ${Math.round(idleMs / 1000)}s (last event: ${lastEventType ?? "none"}) — aborting session.`);
+                },
+            });
+            if (sendResult.timedOut) {
+                const partial = sendResult.content;
+                recordTaskEvent(taskId, {
+                    ts: Date.now(),
+                    type: "task.timeout",
+                    data: {
+                        reason: sendResult.timeoutReason,
+                        lastEventType: sendResult.lastEventType,
+                        partial,
+                    },
+                });
+                const stamped = `[task timed out — ${sendResult.timeoutReason === "idle" ? "idle reset" : "hard cap"}; last event: ${sendResult.lastEventType ?? "none"}]\n\n${partial}`;
+                failTask(taskId, stamped);
+                updateSquadStatus(squadSlug, "idle");
+                if (agent)
+                    updateAgentStatus(squadSlug, agent.character_name, "idle");
+                onComplete(taskId, stamped);
+                return;
+            }
+            const result = sendResult.content || "Task completed (no output)";
             completeTask(taskId, result);
             updateSquadStatus(squadSlug, "idle");
             if (agent)
@@ -300,10 +399,26 @@ async function getOrCreateAgentSession(squadSlug, agent, taskDescription) {
         leadSection = `
 
 ## Team Lead Role
-You are the team lead for this squad. When you receive a task, your job is to:
-1. Break it down into concrete subtasks
-2. Assign each subtask to the most appropriate teammate using the \`delegate_to_teammate\` tool
-3. Collect results and synthesize a final summary
+You are the team lead for this squad. **Your sole job is coordination — you do NOT write code, own any domain, or implement features yourself.** Every incoming task must be analyzed, decomposed, and assigned to the appropriate domain specialist via the \`delegate_to_teammate\` tool. The only work you perform directly is breaking tasks down, delegating, and synthesizing results.
+
+### Fan-out planning (REQUIRED before any work begins)
+When a task arrives, BEFORE touching code or shell, you MUST:
+
+1. **List every distinct work-area** the task touches (e.g. "API endpoint", "DB migration", "frontend component", "tests", "docs"). One bullet per area.
+2. **Score each teammate's charter** against each area — for every area, name the teammate whose charter most closely matches and quote the keyword/phrase from their charter that justifies the assignment.
+3. **Produce a fan-out plan** as a short markdown list: \`- <area> → <teammate> — <one-sentence subtask>\`.
+4. **Delegate each subtask in the plan via \`delegate_to_teammate\`** — in parallel where the subtasks are independent. Do NOT shell, edit, or write code yourself between steps 1–3 and the first \`delegate_to_teammate\` call.
+
+### When you may implement directly
+Only if **all** of the following are true:
+- The task is genuinely trivial (a one-line change, a typo fix, a single-file rename) AND fits no teammate's charter better than yours.
+- No teammate's charter covers the work-area at all.
+- A prior \`delegate_to_teammate\` attempt for this exact subtask failed twice with a clear, unrecoverable error.
+
+If you find yourself reaching for the shell or file_ops on a normal feature/bug task, **stop** — that's a signal you skipped the fan-out plan. Go back and delegate.
+
+### Reviewing teammate output
+After every \`delegate_to_teammate\` call returns, read the result, decide whether it satisfies the subtask, and either accept it (move on to the next subtask) or send a follow-up \`delegate_to_teammate\` to the same teammate with the specific gap to address. Synthesize the final summary only after every subtask is accepted.
 
 ## Your Team
 ${roster}`;
@@ -324,6 +439,17 @@ ${agent.charter ?? "General-purpose agent. Handle tasks as they come."}
 ## Past Decisions
 ${decisions}${leadSection}
 
+## Repository Hygiene
+Before you make ANY code changes, you MUST sync your working copy with the remote default branch and work from a fresh feature branch. This prevents the merge conflicts the team hit on PRs like #45.
+
+1. \`cd\` to the project path above.
+2. \`git fetch origin\` — pick up everything that has merged since your last task.
+3. \`git checkout main && git pull origin main\` — fast-forward your local main.
+4. \`git checkout -b <your-handle>/<short-slug>\` — create a fresh branch from the updated main. Never commit directly to main, and never reuse a stale branch from a prior task.
+5. Only THEN start editing files, running tools, or delegating subtasks.
+
+If the project's default branch is not \`main\` (e.g. \`master\`, \`develop\`), substitute it everywhere above. If you are not in a git repository, skip this section and proceed normally.
+
 ## Instructions
 You are a coding agent. Use the shell tool to run commands and file_ops to read/write files.
 Log important decisions with squad_log_decision so they persist.
@@ -380,6 +506,17 @@ async function getOrCreateSession(squadSlug, taskDescription) {
 ## Past Decisions
 ${decisions}
 
+## Repository Hygiene
+Before you make ANY code changes, you MUST sync your working copy with the remote default branch and work from a fresh feature branch. This prevents the merge conflicts the team hit on PRs like #45.
+
+1. \`cd\` to the project path above.
+2. \`git fetch origin\` — pick up everything that has merged since your last task.
+3. \`git checkout main && git pull origin main\` — fast-forward your local main.
+4. \`git checkout -b <your-handle>/<short-slug>\` — create a fresh branch from the updated main. Never commit directly to main, and never reuse a stale branch from a prior task.
+5. Only THEN start editing files, running tools, or delegating subtasks.
+
+If the project's default branch is not \`main\` (e.g. \`master\`, \`develop\`), substitute it everywhere above. If you are not in a git repository, skip this section and proceed normally.
+
 ## Your Role
 You are a coding agent. Use the shell tool to run commands and file_ops to read/write files.
 Log important decisions with squad_log_decision so they persist.`,
@@ -549,17 +686,40 @@ function buildAgentTools(squadSlug, isLead = false) {
                     if (teammateAgent.is_lead === 1) {
                         return `Error: "${teammate}" is the team lead. Delegate to a non-lead teammate.`;
                     }
+                    // Record this sub-delegation as a first-class task so the squad's
+                    // work-distribution stats reflect real fan-out (issue #51).
+                    const childTaskId = randomUUID();
+                    const childAgentKey = agentSessionKey(squadSlug, teammateAgent.character_name);
+                    createTask(childTaskId, childAgentKey, task, "delegate_to_teammate");
                     updateAgentStatus(squadSlug, teammateAgent.character_name, "working");
                     try {
                         const session = await getOrCreateAgentSession(squadSlug, teammateAgent, task);
-                        const response = await session.sendAndWait({ prompt: task }, 300_000);
-                        const result = response?.data?.content ?? "(teammate returned no output)";
+                        const envelopedTask = buildTaskPromptEnvelope(squadSlug, task);
+                        // Idle-reset timeout: 10min between progress events, 30min
+                        // hard cap. (Issue #53 — replaces #51's 30min wall-clock cap
+                        // that still killed agents mid-tool-call when they had
+                        // long-running shell work between assistant messages.)
+                        const sendResult = await sendWithIdleTimeout(session, envelopedTask, {
+                            idleMs: 10 * 60_000,
+                            hardCapMs: 30 * 60_000,
+                            onIdleTimeout: ({ lastEventType }) => {
+                                console.error(`[io] Teammate ${teammateAgent.character_name} idle (last event: ${lastEventType ?? "none"}) — aborting.`);
+                            },
+                        });
+                        const result = sendResult.content || "(teammate returned no output)";
                         updateAgentStatus(squadSlug, teammateAgent.character_name, "idle");
+                        if (sendResult.timedOut) {
+                            const stamped = `[teammate timed out — ${sendResult.timeoutReason === "idle" ? "idle reset" : "hard cap"}; last event: ${sendResult.lastEventType ?? "none"}]\n\n${result}`;
+                            failTask(childTaskId, stamped);
+                            return stamped;
+                        }
+                        completeTask(childTaskId, result);
                         return result;
                     }
                     catch (err) {
                         updateAgentStatus(squadSlug, teammateAgent.character_name, "error");
                         const message = err instanceof Error ? err.message : String(err);
+                        failTask(childTaskId, message);
                         return `Error from teammate "${teammate}": ${message}`;
                     }
                 }

package/dist/copilot/orchestrator.js

@@ -3,8 +3,8 @@ import { approveAll, } from "@github/copilot-sdk";
 import { config } from "../config.js";
 import { SESSIONS_DIR, IO_VERSION } from "../paths.js";
 import { getState, setState, deleteState, logConversation } from "../store/db.js";
-import { clearStaleTasks, getTask, getTaskReviews } from "../store/tasks.js";
-import { getSquad, listSquads, createSquad, deleteSquad, logDecision, getDecisionsSummary, updateSquadStatus, addSquadAgent, listSquadAgents, removeSquadAgent, setSquadLead, getSquadLead, setSquadQA, } from "../store/squads.js";
+import { clearStaleTasks, getAgentTaskStats, getSquadWorkDistribution, getStalestSpecialist, getTask, getTaskReviews } from "../store/tasks.js";
+import { getSquad, listSquads, createSquad, deleteSquad, logDecision, getDecisions, getDecisionsSummary, updateSquadStatus, addSquadAgent, listSquadAgents, removeSquadAgent, updateAgentStatus, clearAgentSession, setSquadLead, getSquadLead, setSquadQA, } from "../store/squads.js";
 import { readPage, writePage, assertPagePath, deletePage, listPages } from "../wiki/fs.js";
 import { resolveModelTiers } from "./model-router.js";
 import { searchWiki, getWikiSummary } from "../wiki/search.js";
@@ -12,7 +12,7 @@ import { getOrchestratorSystemMessage } from "./system-message.js";
 import { createTools } from "./tools.js";
 import { getSkillDirectories, listSkills, installSkill, removeSkill, searchSkillsRegistry } from "./skills.js";
 import { resetClient } from "./client.js";
-import { delegateToAgent, getActiveAgentTasks } from "./agents.js";
+import { delegateToAgent, getActiveAgentTasks, clearAgentInMemorySession } from "./agents.js";
 import { saveConfig } from "../config.js";
 import { checkForUpdate } from "../update.js";
 // ---------------------------------------------------------------------------
@@ -56,6 +56,11 @@ function getToolDeps() {
         deleteSquad,
         logDecision,
         getDecisionsSummary,
+        getRecentDecisions: (slug, limit) => getDecisions(slug, limit ?? 5).map((d) => ({
+            decision: d.decision,
+            context: d.context,
+            created_at: d.created_at,
+        })),
         updateSquadStatus,
         delegateToAgent,
         getTask,
@@ -77,6 +82,25 @@ function getToolDeps() {
             is_qa: a.is_qa,
         })),
         removeSquadAgent,
+        resetSquadAgent: (squadSlug, characterName) => {
+            const agents = listSquadAgents(squadSlug);
+            const target = agents.find((a) => a.character_name === characterName);
+            if (!target) {
+                return { found: false, previousStatus: "", agent: null };
+            }
+            const previousStatus = target.status;
+            updateAgentStatus(squadSlug, characterName, "idle");
+            clearAgentSession(squadSlug, characterName);
+            clearAgentInMemorySession(squadSlug, characterName);
+            return {
+                found: true,
+                previousStatus,
+                agent: {
+                    character_name: target.character_name,
+                    role_title: target.role_title,
+                },
+            };
+        },
         setSquadLead,
         getSquadLead: (slug) => {
             const lead = getSquadLead(slug);
@@ -91,6 +115,9 @@ function getToolDeps() {
             comments: r.comments,
             squad_slug: r.squad_slug,
         })),
+        getSquadWorkDistribution: (slug, limit) => getSquadWorkDistribution(slug, limit),
+        getAgentTaskStats: (squadSlug, characterNames) => getAgentTaskStats(squadSlug, characterNames),
+        getStalestSpecialist: (squadSlug, characterNames, options) => getStalestSpecialist(squadSlug, characterNames, options),
         listSkills,
         installSkill,
         removeSkill,

package/dist/copilot/session-timeout.js

@@ -0,0 +1,112 @@
+/**
+ * Idle timeout helper for agent task execution (issue #53).
+ *
+ * The Copilot SDK's `sendAndWait(prompt, timeout)` enforces a wall-clock
+ * timeout. Long-running squad tasks were silently killed at 600s even when
+ * the agent was actively making progress (#42, #45). This helper replaces
+ * the wall-clock timeout with an **idle-reset** timeout: every progress
+ * event (tool execution, assistant message, turn boundary) resets the
+ * timer. The agent is only killed if it stops emitting events for `idleMs`
+ * — i.e. it is actually stuck, not just slow.
+ *
+ * On graceful timeout we capture the partial content emitted so far and
+ * surface it to the caller instead of throwing.
+ */
+const PROGRESS_EVENT_TYPES = new Set([
+    "assistant.turn_start",
+    "assistant.message_delta",
+    "assistant.message",
+    "assistant.turn_end",
+    "assistant.reasoning",
+    "assistant.reasoning_delta",
+    "tool.execution_start",
+    "tool.execution_progress",
+    "tool.execution_partial_result",
+    "tool.execution_complete",
+]);
+export async function sendWithIdleTimeout(session, prompt, opts) {
+    let accumulated = "";
+    let lastEventType;
+    let idleTimer;
+    let aborted = false;
+    let abortReason;
+    const triggerIdleAbort = () => {
+        if (aborted)
+            return;
+        aborted = true;
+        abortReason = "idle";
+        opts.onIdleTimeout?.({ lastEventType, idleMs: opts.idleMs });
+        void session.abort().catch(() => {
+            /* best-effort */
+        });
+    };
+    const resetIdle = () => {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(triggerIdleAbort, opts.idleMs);
+    };
+    const unsubDelta = session.on("assistant.message_delta", (event) => {
+        const delta = event?.data?.deltaContent;
+        if (typeof delta === "string")
+            accumulated += delta;
+    });
+    const unsubAll = session.on((event) => {
+        if (PROGRESS_EVENT_TYPES.has(event.type)) {
+            lastEventType = event.type;
+            opts.onProgress?.(event.type);
+            resetIdle();
+        }
+    });
+    resetIdle();
+    try {
+        const response = await session.sendAndWait({ prompt }, opts.hardCapMs);
+        if (aborted) {
+            return {
+                content: response?.data?.content ?? accumulated,
+                timedOut: true,
+                timeoutReason: abortReason,
+                lastEventType,
+            };
+        }
+        return {
+            content: response?.data?.content ?? accumulated,
+            timedOut: false,
+            lastEventType,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const looksLikeTimeout = /timeout/i.test(message);
+        if (aborted || looksLikeTimeout) {
+            if (!aborted && looksLikeTimeout) {
+                abortReason = "hard_cap";
+                opts.onHardCap?.();
+            }
+            return {
+                content: accumulated ||
+                    `(no output captured before timeout; last event: ${lastEventType ?? "none"})`,
+                timedOut: true,
+                timeoutReason: abortReason ?? "hard_cap",
+                lastEventType,
+            };
+        }
+        throw err;
+    }
+    finally {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        try {
+            unsubDelta();
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            unsubAll();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+//# sourceMappingURL=session-timeout.js.map

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