heyio 0.5.0 → 0.8.0

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/session-timeout.test.js

@@ -0,0 +1,372 @@
+/**
+ * Tests for src/copilot/session-timeout.ts — sendWithIdleTimeout
+ *
+ * Strategy: build a FakeSession class whose sendAndWait() is controlled by
+ * a deferred Promise. Event handlers registered via .on() are stored in a
+ * subscriber list and can be triggered manually with .emit(). Timer
+ * behaviour is driven by node:test's mock.timers so no real setTimeout fires.
+ */
+import { describe, it, before, after, beforeEach, mock } from "node:test";
+import assert from "node:assert/strict";
+import { sendWithIdleTimeout, } from "./session-timeout.js";
+/** Minimal fake implementing only what sendWithIdleTimeout needs. */
+function makeFakeSession() {
+    const broadcastHandlers = [];
+    const deltaHandlers = [];
+    let resolveWait;
+    let rejectWait;
+    let aborted = false;
+    const session = {
+        // Typed overload: session.on("assistant.message_delta", handler)
+        // Generic overload: session.on(handler)
+        on(typeOrHandler, handler) {
+            if (typeof typeOrHandler === "function") {
+                broadcastHandlers.push(typeOrHandler);
+                return () => {
+                    const idx = broadcastHandlers.indexOf(typeOrHandler);
+                    if (idx !== -1)
+                        broadcastHandlers.splice(idx, 1);
+                };
+            }
+            // typed: only care about delta for accumulation
+            if (typeOrHandler === "assistant.message_delta" && handler) {
+                deltaHandlers.push(handler);
+                return () => {
+                    const idx = deltaHandlers.indexOf(handler);
+                    if (idx !== -1)
+                        deltaHandlers.splice(idx, 1);
+                };
+            }
+            return () => { };
+        },
+        sendAndWait(_opts, _timeout) {
+            return new Promise((resolve, reject) => {
+                resolveWait = resolve;
+                rejectWait = reject;
+            });
+        },
+        abort() {
+            aborted = true;
+            return Promise.resolve();
+        },
+        // ── Test-only helpers ──────────────────────────────────────────────────
+        /** Emit an event to all broad-listener handlers. */
+        emit(event) {
+            for (const h of broadcastHandlers)
+                h(event);
+        },
+        /** Emit an assistant.message_delta event with the given text chunk. */
+        emitDelta(deltaContent) {
+            const deltaEvent = {
+                type: "assistant.message_delta",
+                id: "evt-1",
+                timestamp: new Date().toISOString(),
+                parentId: null,
+                ephemeral: true,
+                data: { messageId: "msg-1", deltaContent },
+            };
+            // Notify delta-specific handlers
+            for (const h of deltaHandlers) {
+                h(deltaEvent);
+            }
+            // Also broadcast to all-event handlers so idle timer resets
+            this.emit(deltaEvent);
+        },
+        /** Emit a generic progress event (e.g. tool.execution_complete). */
+        emitProgress(type) {
+            const event = {
+                type,
+                id: "evt-2",
+                timestamp: new Date().toISOString(),
+                parentId: null,
+                ephemeral: false,
+                data: {},
+            };
+            this.emit(event);
+        },
+        /** Resolve the sendAndWait promise with a final content string. */
+        resolve(content) {
+            resolveWait?.({ data: { content } });
+        },
+        /** Resolve the sendAndWait promise with undefined (triggers accumulated fallback). */
+        resolveUndefined() {
+            resolveWait?.(undefined);
+        },
+        /** Reject the sendAndWait promise with a timeout-style error. */
+        rejectWithTimeout() {
+            rejectWait?.(new Error("Timeout after 600000ms waiting for session.idle"));
+        },
+        /** Reject the sendAndWait promise with a non-timeout error. */
+        rejectWithError(msg) {
+            rejectWait?.(new Error(msg));
+        },
+        get wasAborted() {
+            return aborted;
+        },
+    };
+    return session;
+}
+// Cast FakeSession to CopilotSession for type-compatibility with sendWithIdleTimeout.
+// The fake satisfies the structural subset used by the function.
+function asSession(fake) {
+    return fake;
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+const DEFAULT_OPTS = {
+    idleMs: 5_000,
+    hardCapMs: 30_000,
+};
+// ── Tests ─────────────────────────────────────────────────────────────────────
+describe("sendWithIdleTimeout", () => {
+    before(() => {
+        mock.timers.enable({ apis: ["setTimeout"] });
+    });
+    after(() => {
+        mock.timers.reset();
+    });
+    beforeEach(() => {
+        // Reset the fake timer state between tests without disabling
+        mock.timers.reset();
+        mock.timers.enable({ apis: ["setTimeout"] });
+    });
+    // ── happy path ──────────────────────────────────────────────────────────
+    it("returns content and timedOut=false when session resolves normally", async () => {
+        const fake = makeFakeSession();
+        const promise = sendWithIdleTimeout(asSession(fake), "do something", DEFAULT_OPTS);
+        // Let the initial idle timer be registered, then resolve immediately
+        fake.resolve("task done successfully");
+        const result = await promise;
+        assert.equal(result.timedOut, false);
+        assert.equal(result.content, "task done successfully");
+        assert.equal(result.timeoutReason, undefined);
+    });
+    it("accumulates delta content during streaming (verified via resolveUndefined)", async () => {
+        const fake = makeFakeSession();
+        const promise = sendWithIdleTimeout(asSession(fake), "stream this", DEFAULT_OPTS);
+        fake.emitDelta("Hello ");
+        fake.emitDelta("world");
+        fake.emitDelta("!");
+        // resolveUndefined triggers `response?.data?.content ?? accumulated` → uses accumulated
+        fake.resolveUndefined();
+        const result = await promise;
+        assert.equal(result.timedOut, false);
+        assert.equal(result.content, "Hello world!");
+    });
+    it("falls back to accumulated delta when sendAndWait resolves with undefined", async () => {
+        const fake = makeFakeSession();
+        const promise = sendWithIdleTimeout(asSession(fake), "stream this", DEFAULT_OPTS);
+        fake.emitDelta("partial ");
+        fake.emitDelta("output");
+        // Resolve with undefined to trigger the `response?.data?.content ?? accumulated` fallback
+        fake.resolveUndefined();
+        const result = await promise;
+        assert.equal(result.timedOut, false);
+        assert.equal(result.content, "partial output");
+    });
+    // ── idle timer reset ────────────────────────────────────────────────────
+    it("resets idle timer on assistant.message_delta", async () => {
+        const fake = makeFakeSession();
+        const idleTimeoutFired = { value: false };
+        const opts = {
+            ...DEFAULT_OPTS,
+            idleMs: 1_000,
+            onIdleTimeout: () => { idleTimeoutFired.value = true; },
+        };
+        const promise = sendWithIdleTimeout(asSession(fake), "do work", opts);
+        // Advance to just before idle timeout — timer should NOT fire yet
+        mock.timers.tick(800);
+        assert.equal(idleTimeoutFired.value, false);
+        // Emit a progress event — should reset the idle timer
+        fake.emitProgress("tool.execution_complete");
+        // Advance another 800ms — if reset worked, timer still hasn't fired (800 < 1000)
+        mock.timers.tick(800);
+        assert.equal(idleTimeoutFired.value, false, "idle timer should have been reset by progress event");
+        // Resolve and clean up
+        fake.resolve("done");
+        await promise;
+    });
+    it("fires idle timeout after idleMs of silence", async () => {
+        const fake = makeFakeSession();
+        let idleFired = false;
+        const opts = {
+            ...DEFAULT_OPTS,
+            idleMs: 2_000,
+            onIdleTimeout: () => { idleFired = true; },
+        };
+        const promise = sendWithIdleTimeout(asSession(fake), "long task", opts);
+        // Advance past idle timeout — no events emitted
+        mock.timers.tick(2_001);
+        // Abort fires async; wait a tick then check
+        await Promise.resolve();
+        assert.equal(idleFired, true, "onIdleTimeout should have fired");
+        assert.equal(fake.wasAborted, true, "session.abort() should have been called");
+        // Simulate the sendAndWait timing out after abort
+        fake.rejectWithTimeout();
+        const result = await promise;
+        assert.equal(result.timedOut, true);
+    });
+    it("resets idle timer on tool.execution_complete", async () => {
+        const fake = makeFakeSession();
+        let idleFired = false;
+        const opts = {
+            ...DEFAULT_OPTS,
+            idleMs: 1_000,
+            onIdleTimeout: () => { idleFired = true; },
+        };
+        const promise = sendWithIdleTimeout(asSession(fake), "tool task", opts);
+        mock.timers.tick(700);
+        fake.emitProgress("tool.execution_complete");
+        mock.timers.tick(700); // 700ms since last reset — still under 1000ms
+        assert.equal(idleFired, false, "idle timer should have been reset by tool event");
+        fake.resolve("done");
+        await promise;
+        assert.equal(idleFired, false);
+    });
+    it("resets idle timer on assistant.turn_start", async () => {
+        const fake = makeFakeSession();
+        let idleFired = false;
+        const opts = {
+            ...DEFAULT_OPTS,
+            idleMs: 1_000,
+            onIdleTimeout: () => { idleFired = true; },
+        };
+        const promise = sendWithIdleTimeout(asSession(fake), "turn task", opts);
+        mock.timers.tick(700);
+        fake.emitProgress("assistant.turn_start");
+        mock.timers.tick(700);
+        assert.equal(idleFired, false, "idle timer should reset on assistant.turn_start");
+        fake.resolve("done");
+        await promise;
+    });
+    it("does NOT reset idle timer for unrecognised event types", async () => {
+        const fake = makeFakeSession();
+        let idleFired = false;
+        const opts = {
+            ...DEFAULT_OPTS,
+            idleMs: 1_000,
+            onIdleTimeout: () => { idleFired = true; },
+        };
+        const promise = sendWithIdleTimeout(asSession(fake), "noisy task", opts);
+        mock.timers.tick(700);
+        // This event type is not in PROGRESS_EVENT_TYPES
+        fake.emitProgress("some.unknown.event");
+        mock.timers.tick(400); // 700 + 400 = 1100ms since last real reset
+        await Promise.resolve();
+        assert.equal(idleFired, true, "idle timer should fire — unknown event should not reset it");
+        fake.rejectWithTimeout();
+        const result = await promise;
+        assert.equal(result.timedOut, true);
+    });
+    // ── graceful timeout capture ─────────────────────────────────────────────
+    it("captures partial content when idle timeout fires mid-stream", async () => {
+        const fake = makeFakeSession();
+        const opts = {
+            ...DEFAULT_OPTS,
+            idleMs: 1_000,
+        };
+        const promise = sendWithIdleTimeout(asSession(fake), "long output", opts);
+        // Agent emits some content then goes silent
+        fake.emitDelta("Step 1 done. ");
+        fake.emitDelta("Step 2 in progress...");
+        // Advance past idle timeout
+        mock.timers.tick(1_001);
+        await Promise.resolve();
+        // sendAndWait throws a timeout error after abort
+        fake.rejectWithTimeout();
+        const result = await promise;
+        assert.equal(result.timedOut, true);
+        // idle timer fires first → abortReason="idle"; catch block sees aborted=true and preserves it
+        assert.equal(result.timeoutReason, "idle", "idle fired before sendAndWait rejection → reason stays idle");
+        assert.ok(result.content.includes("Step 1 done.") && result.content.includes("Step 2 in progress..."), `partial content should be captured; got: ${result.content}`);
+    });
+    it("returns fallback message when no content was accumulated before timeout", async () => {
+        const fake = makeFakeSession();
+        const opts = { ...DEFAULT_OPTS, idleMs: 500 };
+        const promise = sendWithIdleTimeout(asSession(fake), "silent agent", opts);
+        mock.timers.tick(501);
+        await Promise.resolve();
+        fake.rejectWithTimeout();
+        const result = await promise;
+        assert.equal(result.timedOut, true);
+        assert.ok(result.content.includes("no output captured"), `should report no output captured; got: ${result.content}`);
+    });
+    it("sets timeoutReason=idle when abort fires before sendAndWait throws", async () => {
+        const fake = makeFakeSession();
+        let idleCallbackInfo;
+        const opts = {
+            ...DEFAULT_OPTS,
+            idleMs: 500,
+            onIdleTimeout: (info) => { idleCallbackInfo = info; },
+        };
+        const promise = sendWithIdleTimeout(asSession(fake), "silent", opts);
+        mock.timers.tick(501);
+        await Promise.resolve(); // let abort() fire
+        // When aborted=true, the resolve branch returns timedOut:true with timeoutReason from abortReason
+        fake.resolve("some final content");
+        const result = await promise;
+        assert.equal(result.timedOut, true);
+        assert.equal(result.timeoutReason, "idle");
+        assert.ok(idleCallbackInfo, "onIdleTimeout callback should have been called");
+        assert.equal(idleCallbackInfo?.idleMs, 500);
+    });
+    it("calls onProgress for each recognised event type", async () => {
+        const fake = makeFakeSession();
+        const progressEvents = [];
+        const opts = {
+            ...DEFAULT_OPTS,
+            onProgress: (type) => progressEvents.push(type),
+        };
+        const promise = sendWithIdleTimeout(asSession(fake), "track progress", opts);
+        fake.emitProgress("tool.execution_start");
+        fake.emitProgress("tool.execution_complete");
+        fake.emitDelta("some output");
+        fake.resolve("done");
+        await promise;
+        assert.ok(progressEvents.includes("tool.execution_start"));
+        assert.ok(progressEvents.includes("tool.execution_complete"));
+        assert.ok(progressEvents.includes("assistant.message_delta"));
+    });
+    it("tracks lastEventType in result", async () => {
+        const fake = makeFakeSession();
+        const promise = sendWithIdleTimeout(asSession(fake), "track last", DEFAULT_OPTS);
+        fake.emitProgress("tool.execution_start");
+        fake.emitProgress("tool.execution_complete");
+        fake.resolve("done");
+        const result = await promise;
+        assert.equal(result.lastEventType, "tool.execution_complete");
+    });
+    // ── error handling ───────────────────────────────────────────────────────
+    it("re-throws non-timeout errors", async () => {
+        const fake = makeFakeSession();
+        const promise = sendWithIdleTimeout(asSession(fake), "bad prompt", DEFAULT_OPTS);
+        fake.rejectWithError("unexpected authentication failure");
+        await assert.rejects(() => promise, (err) => {
+            assert.ok(err.message.includes("unexpected authentication failure"));
+            return true;
+        });
+    });
+    it("calls onHardCap when sendAndWait throws timeout and aborted=false", async () => {
+        const fake = makeFakeSession();
+        let hardCapFired = false;
+        const opts = {
+            ...DEFAULT_OPTS,
+            onHardCap: () => { hardCapFired = true; },
+        };
+        const promise = sendWithIdleTimeout(asSession(fake), "hard task", opts);
+        // Don't advance past idle timer — just let the hard cap throw
+        fake.rejectWithTimeout();
+        const result = await promise;
+        assert.equal(result.timedOut, true);
+        assert.equal(result.timeoutReason, "hard_cap");
+        assert.equal(hardCapFired, true);
+    });
+    it("cleans up subscriptions after normal completion (no memory leak)", async () => {
+        const fake = makeFakeSession();
+        const promise = sendWithIdleTimeout(asSession(fake), "cleanup test", DEFAULT_OPTS);
+        fake.resolve("done");
+        const result = await promise;
+        assert.equal(result.timedOut, false);
+        // If unsubscribe threw, the test would fail — we're asserting no throw
+    });
+});
+//# sourceMappingURL=session-timeout.test.js.map

package/dist/copilot/skills.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "fs";
 import { join, basename } from "path";
 import { execSync } from "child_process";
 import { SKILLS_DIR } from "../paths.js";
@@ -80,11 +80,85 @@ export function listSkills() {
     }
     return skills;
 }
+const GITHUB_BLOB_RE = /^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/blob\/([^\/]+)\/(.+\/)?SKILL\.md$/i;
+const RAW_GH_RE = /^https:\/\/raw\.githubusercontent\.com\/([^\/]+)\/([^\/]+)\/([^\/]+)\/(.+\/)?SKILL\.md$/i;
+const GENERIC_SKILL_MD_RE = /\/SKILL\.md$/i;
+function deriveSlug(repo, pathPrefix) {
+    if (!pathPrefix)
+        return repo;
+    const segments = pathPrefix.replace(/\/$/, "").split("/").filter(Boolean);
+    const last = segments[segments.length - 1];
+    return last ? `${repo}-${last}` : repo;
+}
 /**
- * Clone a git repo into SKILLS_DIR and return the installed skill info.
- * Throws if the cloned repo does not contain a SKILL.md file.
+ * Determine whether the input URL points to a full repo or a specific
+ * SKILL.md file. For GitHub blob URLs the raw download URL is derived
+ * automatically.
  */
-export async function installSkill(repoUrl) {
+export function parseSkillUrl(input) {
+    const blobMatch = input.match(GITHUB_BLOB_RE);
+    if (blobMatch) {
+        const [, owner, repo, branch, pathPrefix] = blobMatch;
+        const rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${pathPrefix ?? ""}SKILL.md`;
+        return { type: "file", rawUrl, slug: deriveSlug(repo, pathPrefix) };
+    }
+    const rawMatch = input.match(RAW_GH_RE);
+    if (rawMatch) {
+        const [, _owner, repo, _branch, pathPrefix] = rawMatch;
+        return { type: "file", rawUrl: input, slug: deriveSlug(repo, pathPrefix) };
+    }
+    if (GENERIC_SKILL_MD_RE.test(input)) {
+        if (!input.startsWith("https://")) {
+            throw new Error("Only https:// URLs are supported for SKILL.md installs.");
+        }
+        const urlObj = new URL(input);
+        const segments = urlObj.pathname.split("/").filter(Boolean);
+        // Use the segment before SKILL.md, or the hostname as slug fallback
+        const slug = segments.length >= 2
+            ? segments[segments.length - 2]
+            : urlObj.hostname.replace(/\./g, "-");
+        return { type: "file", rawUrl: input, slug };
+    }
+    return { type: "repo", url: input };
+}
+async function installSkillFromFile(rawUrl, slug) {
+    if (!rawUrl.startsWith("https://")) {
+        throw new Error("Only https:// URLs are supported for SKILL.md installs.");
+    }
+    const destDir = join(SKILLS_DIR, slug);
+    if (existsSync(destDir)) {
+        throw new Error(`Skill "${slug}" is already installed.`);
+    }
+    const response = await fetch(rawUrl);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch SKILL.md from ${rawUrl} (HTTP ${response.status})`);
+    }
+    const content = await response.text();
+    // Validate: at least one markdown heading in the first 10 lines
+    const first10 = content.split(/\r?\n/).slice(0, 10);
+    if (!first10.some((line) => /^#\s+/.test(line))) {
+        throw new Error("URL does not appear to contain a valid SKILL.md file.");
+    }
+    mkdirSync(destDir, { recursive: true });
+    writeFileSync(join(destDir, "SKILL.md"), content, "utf-8");
+    const { name, description } = parseSkillMd(content);
+    return {
+        name: name || slug,
+        slug,
+        description,
+        path: destDir,
+    };
+}
+/**
+ * Install a skill from a git repo URL or a direct SKILL.md file URL.
+ * Throws if the repo/file does not contain a valid SKILL.md.
+ */
+export async function installSkill(input) {
+    const parsed = parseSkillUrl(input);
+    if (parsed.type === "file") {
+        return installSkillFromFile(parsed.rawUrl, parsed.slug);
+    }
+    const repoUrl = parsed.url;
     const repoName = basename(repoUrl, ".git").replace(/\.git$/, "");
     const destDir = join(SKILLS_DIR, repoName);
     execSync(`git clone ${repoUrl} ${destDir}`, { stdio: "pipe" });

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