@os-eco/overstory-cli 0.6.10 → 0.6.11

package/src/agents/overlay.test.ts

@@ -495,6 +495,85 @@ describe("generateOverlay", () => {
 
 		expect(output).toContain("bd close overstory-back");
 	});
+
+	test("dispatch overrides: skipReview injects SKIP REVIEW directive for leads", async () => {
+		const config = makeConfig({
+			capability: "lead",
+			skipReview: true,
+			canSpawn: true,
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).toContain("Dispatch Overrides");
+		expect(output).toContain("SKIP REVIEW");
+		expect(output).toContain("Self-verify");
+	});
+
+	test("dispatch overrides: maxAgentsOverride injects MAX AGENTS directive for leads", async () => {
+		const config = makeConfig({
+			capability: "lead",
+			maxAgentsOverride: 3,
+			canSpawn: true,
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).toContain("Dispatch Overrides");
+		expect(output).toContain("MAX AGENTS");
+		expect(output).toContain("3");
+	});
+
+	test("dispatch overrides: both skipReview and maxAgentsOverride together", async () => {
+		const config = makeConfig({
+			capability: "lead",
+			skipReview: true,
+			maxAgentsOverride: 4,
+			canSpawn: true,
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).toContain("SKIP REVIEW");
+		expect(output).toContain("MAX AGENTS");
+		expect(output).toContain("4");
+	});
+
+	test("dispatch overrides: not injected for builder capability", async () => {
+		const config = makeConfig({
+			capability: "builder",
+			skipReview: true,
+			maxAgentsOverride: 3,
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).not.toContain("Dispatch Overrides");
+	});
+
+	test("dispatch overrides: not injected when no overrides set", async () => {
+		const config = makeConfig({
+			capability: "lead",
+			canSpawn: true,
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).not.toContain("Dispatch Overrides");
+	});
+
+	test("dispatch overrides: maxAgentsOverride of 0 is not injected", async () => {
+		const config = makeConfig({
+			capability: "lead",
+			maxAgentsOverride: 0,
+			canSpawn: true,
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).not.toContain("MAX AGENTS");
+	});
+
+	test("no unreplaced DISPATCH_OVERRIDES placeholder", async () => {
+		const config = makeConfig();
+		const output = await generateOverlay(config);
+
+		expect(output).not.toContain("{{DISPATCH_OVERRIDES}}");
+	});
 });
 
 describe("writeOverlay", () => {

package/src/agents/overlay.ts

@@ -72,6 +72,43 @@ Do NOT spawn scout agents. Do NOT explore the codebase extensively.
 Your parent has already gathered the context you need.
 `;
 
+/**
+ * Build the dispatch overrides section for lead overlays.
+ * Only generates content when overrides are actually set.
+ * The overlay is the source of truth -- leads read these directives, not mail.
+ */
+function formatDispatchOverrides(config: OverlayConfig): string {
+	if (config.capability !== "lead") return "";
+
+	const sections: string[] = [];
+
+	if (config.skipReview) {
+		sections.push(
+			"- **SKIP REVIEW**: You have been instructed to skip the review phase. " +
+				"Self-verify by reading the diff and running quality gates instead of spawning a reviewer.",
+		);
+	}
+
+	if (config.maxAgentsOverride !== undefined && config.maxAgentsOverride > 0) {
+		sections.push(
+			`- **MAX AGENTS**: Your per-lead agent ceiling has been set to **${config.maxAgentsOverride}**. ` +
+				"Do not spawn more than this many sub-workers.",
+		);
+	}
+
+	if (sections.length === 0) return "";
+
+	return [
+		"## Dispatch Overrides",
+		"",
+		"Your coordinator has set the following overrides for this work stream:",
+		"",
+		...sections,
+		"",
+		"Honor these directives. They override the default workflow described in your base definition.",
+	].join("\n");
+}
+
 /**
  * Format the quality gates section. Read-only agents (scout, reviewer) get
  * a lightweight section that only tells them to close the issue and report.
@@ -261,7 +298,7 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 
 	const replacements: Record<string, string> = {
 		"{{AGENT_NAME}}": config.agentName,
-		"{{BEAD_ID}}": config.taskId,
+		"{{TASK_ID}}": config.taskId,
 		"{{SPEC_PATH}}": config.specPath ?? "No spec file provided",
 		"{{BRANCH_NAME}}": config.branchName,
 		"{{WORKTREE_PATH}}": config.worktreePath,
@@ -275,13 +312,14 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 		"{{CONSTRAINTS}}": formatConstraints(config),
 		"{{SPEC_INSTRUCTION}}": specInstruction,
 		"{{SKIP_SCOUT}}": config.skipScout ? SKIP_SCOUT_SECTION : "",
+		"{{DISPATCH_OVERRIDES}}": formatDispatchOverrides(config),
 		"{{BASE_DEFINITION}}": config.baseDefinition,
 		"{{QUALITY_GATE_INLINE}}": formatQualityGatesInline(config.qualityGates),
 		"{{QUALITY_GATE_STEPS}}": formatQualityGatesSteps(config.qualityGates),
 		"{{QUALITY_GATE_BASH}}": formatQualityGatesBash(config.qualityGates),
 		"{{QUALITY_GATE_CAPABILITIES}}": formatQualityGatesCapabilities(config.qualityGates),
 		"{{TRACKER_CLI}}": config.trackerCli ?? "bd",
-		"{{TRACKER_NAME}}": config.trackerName ?? "beads",
+		"{{TRACKER_NAME}}": config.trackerName ?? "seeds",
 	};
 
 	let result = template;

package/src/commands/completions.ts

@@ -236,7 +236,7 @@ export const COMMANDS: readonly CommandDef[] = [
 	},
 	{
 		name: "trace",
-		desc: "Chronological event timeline for agent/bead",
+		desc: "Chronological event timeline for agent or task",
 		flags: [
 			{ name: "--json", desc: "JSON output" },
 			{ name: "--since", desc: "Time range filter (ISO 8601)", takesValue: true },
@@ -366,7 +366,7 @@ export const COMMANDS: readonly CommandDef[] = [
 				name: "start",
 				desc: "Start supervisor",
 				flags: [
-					{ name: "--task", desc: "Bead task ID", takesValue: true },
+					{ name: "--task", desc: "Task ID", takesValue: true },
 					{ name: "--name", desc: "Unique name", takesValue: true },
 					{ name: "--parent", desc: "Parent agent", takesValue: true },
 					{ name: "--depth", desc: "Hierarchy depth", takesValue: true },
@@ -543,7 +543,7 @@ export const COMMANDS: readonly CommandDef[] = [
 		desc: "Task groups",
 		flags: [
 			{ name: "--json", desc: "JSON output" },
-			{ name: "--skip-validation", desc: "Skip beads checks" },
+			{ name: "--skip-validation", desc: "Skip task validation" },
 			{ name: "--help", desc: "Show help" },
 		],
 		subcommands: [

package/src/commands/coordinator.ts

@@ -2,13 +2,13 @@
  * CLI command: ov coordinator start|stop|status
  *
  * Manages the persistent coordinator agent lifecycle. The coordinator runs
- * at the project root (NOT in a worktree), receives work via mail and beads,
+ * at the project root (NOT in a worktree), receives work via mail and tasks,
  * and dispatches agents via ov sling.
  *
  * Unlike regular agents spawned by sling, the coordinator:
  * - Has no worktree (operates on the main working tree)
- * - Has no bead assignment (it creates beads, not works on them)
- * - Has no overlay CLAUDE.md (context comes via mail + beads + checkpoints)
+ * - Has no task assignment (it creates tasks, not works on them)
+ * - Has no overlay CLAUDE.md (context comes via mail + tasks + checkpoints)
  * - Persists across work batches
  */
 
@@ -381,7 +381,7 @@ async function startCoordinator(
 			capability: "coordinator",
 			worktreePath: projectRoot, // Coordinator uses project root, not a worktree
 			branchName: config.project.canonicalBranch, // Operates on canonical branch
-			taskId: "", // No specific bead assignment
+			taskId: "", // No specific task assignment
 			tmuxSession,
 			state: "booting",
 			pid,

package/src/commands/group.ts

@@ -2,7 +2,7 @@
  * CLI command: ov group create|status|add|remove|list
  *
  * Manages TaskGroups for batch work coordination. Groups track collections
- * of beads issues and auto-close when all member issues are closed.
+ * of issues and auto-close when all member issues are closed.
  *
  * Storage: `.overstory/groups.json` (array of TaskGroup objects).
  */
@@ -312,7 +312,7 @@ export function createGroupCommand(): Command {
 		.argument("<name>", "Group name")
 		.argument("<ids...>", "Issue IDs to include")
 		.option("--json", "Output as JSON")
-		.option("--skip-validation", "Skip beads issue validation (for offline use)")
+		.option("--skip-validation", "Skip task validation (for offline use)")
 		.action(
 			async (name: string, ids: string[], opts: { json?: boolean; skipValidation?: boolean }) => {
 				const config = await loadConfig(process.cwd());
@@ -343,7 +343,7 @@ export function createGroupCommand(): Command {
 		.description("Show progress for one or all groups")
 		.argument("[group-id]", "Group ID (optional, shows all if omitted)")
 		.option("--json", "Output as JSON")
-		.option("--skip-validation", "Skip beads issue validation (for offline use)")
+		.option("--skip-validation", "Skip task validation (for offline use)")
 		.action(
 			async (groupId: string | undefined, opts: { json?: boolean; skipValidation?: boolean }) => {
 				const config = await loadConfig(process.cwd());
@@ -398,7 +398,7 @@ export function createGroupCommand(): Command {
 		.argument("<group-id>", "Group ID")
 		.argument("<ids...>", "Issue IDs to add")
 		.option("--json", "Output as JSON")
-		.option("--skip-validation", "Skip beads issue validation (for offline use)")
+		.option("--skip-validation", "Skip task validation (for offline use)")
 		.action(
 			async (
 				groupId: string,

package/src/commands/mail.test.ts

@@ -14,7 +14,7 @@ import { stripAnsi } from "../logging/color.ts";
 import { createMailClient } from "../mail/client.ts";
 import { createMailStore } from "../mail/store.ts";
 import type { StoredEvent } from "../types.ts";
-import { mailCommand } from "./mail.ts";
+import { AUTO_NUDGE_TYPES, isDispatchNudge, mailCommand, shouldAutoNudge } from "./mail.ts";
 
 describe("mailCommand", () => {
 	let tempDir: string;
@@ -1269,3 +1269,65 @@ describe("mailCommand", () => {
 		});
 	});
 });
+
+describe("shouldAutoNudge", () => {
+	test("returns true for urgent priority regardless of type", () => {
+		expect(shouldAutoNudge("status", "urgent")).toBe(true);
+	});
+
+	test("returns true for high priority regardless of type", () => {
+		expect(shouldAutoNudge("status", "high")).toBe(true);
+	});
+
+	test("returns true for worker_done type at normal priority", () => {
+		expect(shouldAutoNudge("worker_done", "normal")).toBe(true);
+	});
+
+	test("returns true for merge_ready type at normal priority", () => {
+		expect(shouldAutoNudge("merge_ready", "normal")).toBe(true);
+	});
+
+	test("returns true for error type at normal priority", () => {
+		expect(shouldAutoNudge("error", "normal")).toBe(true);
+	});
+
+	test("returns false for status type at normal priority", () => {
+		expect(shouldAutoNudge("status", "normal")).toBe(false);
+	});
+
+	test("returns false for question type at low priority", () => {
+		expect(shouldAutoNudge("question", "low")).toBe(false);
+	});
+});
+
+describe("isDispatchNudge", () => {
+	test("returns true for dispatch type", () => {
+		expect(isDispatchNudge("dispatch")).toBe(true);
+	});
+
+	test("returns false for worker_done type", () => {
+		expect(isDispatchNudge("worker_done")).toBe(false);
+	});
+
+	test("returns false for status type", () => {
+		expect(isDispatchNudge("status")).toBe(false);
+	});
+
+	test("returns false for error type", () => {
+		expect(isDispatchNudge("error")).toBe(false);
+	});
+});
+
+describe("AUTO_NUDGE_TYPES", () => {
+	test("contains worker_done, merge_ready, and error", () => {
+		expect(AUTO_NUDGE_TYPES.has("worker_done")).toBe(true);
+		expect(AUTO_NUDGE_TYPES.has("merge_ready")).toBe(true);
+		expect(AUTO_NUDGE_TYPES.has("error")).toBe(true);
+	});
+
+	test("does not contain regular semantic types", () => {
+		expect(AUTO_NUDGE_TYPES.has("status")).toBe(false);
+		expect(AUTO_NUDGE_TYPES.has("question")).toBe(false);
+		expect(AUTO_NUDGE_TYPES.has("result")).toBe(false);
+	});
+});

package/src/commands/mail.ts

@@ -24,7 +24,7 @@ import { MAIL_MESSAGE_TYPES } from "../types.ts";
  * Protocol message types that require immediate recipient attention.
  * These trigger auto-nudge regardless of priority level.
  */
-const AUTO_NUDGE_TYPES: ReadonlySet<MailMessageType> = new Set([
+export const AUTO_NUDGE_TYPES: ReadonlySet<MailMessageType> = new Set([
 	"worker_done",
 	"merge_ready",
 	"error",
@@ -32,6 +32,23 @@ const AUTO_NUDGE_TYPES: ReadonlySet<MailMessageType> = new Set([
 	"merge_failed",
 ]);
 
+/**
+ * Check if a message type/priority combination should trigger a pending nudge.
+ * Exported for testability.
+ */
+export function shouldAutoNudge(type: MailMessageType, priority: MailMessage["priority"]): boolean {
+	return priority === "urgent" || priority === "high" || AUTO_NUDGE_TYPES.has(type);
+}
+
+/**
+ * Check if a message type should trigger an immediate tmux dispatch nudge.
+ * Dispatch nudges target newly spawned agents at the welcome screen.
+ * Exported for testability.
+ */
+export function isDispatchNudge(type: MailMessageType): boolean {
+	return type === "dispatch";
+}
+
 /** Format a single message for human-readable output. */
 function formatMessage(msg: MailMessage): string {
 	const readMarker = msg.read ? " " : "*";

package/src/commands/merge.ts

@@ -47,7 +47,7 @@ function parseAgentName(branchName: string): string {
  * Pattern: overstory/{agentName}/{taskId}
  * Falls back to "unknown" if the pattern does not match.
  */
-function parseBeadId(branchName: string): string {
+function parseTaskId(branchName: string): string {
 	const parts = branchName.split("/");
 	if (parts[0] === "overstory" && parts[2] !== undefined) {
 		return parts[2];
@@ -213,7 +213,7 @@ async function handleBranch(
 		}
 
 		const agentName = parseAgentName(branchName);
-		const taskId = parseBeadId(branchName);
+		const taskId = parseTaskId(branchName);
 		const filesModified = await detectModifiedFiles(repoRoot, canonicalBranch, branchName);
 
 		entry = queue.enqueue({

package/src/commands/monitor.ts

@@ -8,7 +8,7 @@
  *
  * Unlike regular agents spawned by sling, the monitor:
  * - Has no worktree (operates on the main working tree)
- * - Has no bead assignment (it monitors, not implements)
+ * - Has no task assignment (it monitors, not implements)
  * - Has no overlay CLAUDE.md (context comes via ov status + mail)
  * - Persists across patrol cycles
  */
@@ -158,7 +158,7 @@ async function startMonitor(opts: { json: boolean; attach: boolean }): Promise<v
 			capability: "monitor",
 			worktreePath: projectRoot, // Monitor uses project root, not a worktree
 			branchName: config.project.canonicalBranch, // Operates on canonical branch
-			taskId: "", // No specific bead assignment
+			taskId: "", // No specific task assignment
 			tmuxSession,
 			state: "booting",
 			pid,

package/src/commands/sling.test.ts

@@ -8,8 +8,10 @@ import {
 	buildAutoDispatch,
 	buildBeacon,
 	calculateStaggerDelay,
-	checkBeadLock,
+	checkDuplicateLead,
+	checkParentAgentLimit,
 	checkRunSessionLimit,
+	checkTaskLock,
 	inferDomainsFromFiles,
 	isRunningAsRoot,
 	parentHasScouts,
@@ -554,66 +556,66 @@ describe("isRunningAsRoot", () => {
 });
 
 /**
- * Tests for checkBeadLock.
+ * Tests for checkTaskLock.
  *
- * checkBeadLock prevents concurrent agents from working the same task ID.
+ * checkTaskLock prevents concurrent agents from working the same task ID.
  * It checks the active session list and returns the agent name that holds
- * the lock (i.e., is already working on the bead), or null if the bead is free.
+ * the lock (i.e., is already working on the task), or null if the task is free.
  */
 
-function makeBeadSession(agentName: string, taskId: string): { agentName: string; taskId: string } {
+function makeTaskSession(agentName: string, taskId: string): { agentName: string; taskId: string } {
 	return { agentName, taskId };
 }
 
-describe("checkBeadLock", () => {
+describe("checkTaskLock", () => {
 	test("returns null when no sessions exist", () => {
-		expect(checkBeadLock([], "overstory-abc")).toBeNull();
+		expect(checkTaskLock([], "overstory-abc")).toBeNull();
 	});
 
 	test("returns null when no session matches the task ID", () => {
 		const sessions = [
-			makeBeadSession("builder-1", "overstory-xyz"),
-			makeBeadSession("builder-2", "overstory-def"),
+			makeTaskSession("builder-1", "overstory-xyz"),
+			makeTaskSession("builder-2", "overstory-def"),
 		];
 
-		expect(checkBeadLock(sessions, "overstory-abc")).toBeNull();
+		expect(checkTaskLock(sessions, "overstory-abc")).toBeNull();
 	});
 
 	test("returns the agent name when a session matches", () => {
 		const sessions = [
-			makeBeadSession("builder-1", "overstory-abc"),
-			makeBeadSession("builder-2", "overstory-xyz"),
+			makeTaskSession("builder-1", "overstory-abc"),
+			makeTaskSession("builder-2", "overstory-xyz"),
 		];
 
-		expect(checkBeadLock(sessions, "overstory-abc")).toBe("builder-1");
+		expect(checkTaskLock(sessions, "overstory-abc")).toBe("builder-1");
 	});
 
 	test("returns the first matching agent when multiple sessions match", () => {
 		// Multiple sessions can have the same taskId (e.g., retried agent)
-		// checkBeadLock returns the first match
+		// checkTaskLock returns the first match
 		const sessions = [
-			makeBeadSession("builder-1", "overstory-abc"),
-			makeBeadSession("builder-2", "overstory-abc"),
+			makeTaskSession("builder-1", "overstory-abc"),
+			makeTaskSession("builder-2", "overstory-abc"),
 		];
 
-		expect(checkBeadLock(sessions, "overstory-abc")).toBe("builder-1");
+		expect(checkTaskLock(sessions, "overstory-abc")).toBe("builder-1");
 	});
 });
 
-describe("checkBeadLock parent bypass", () => {
+describe("checkTaskLock parent bypass", () => {
 	test("parent matching lock holder is allowed (returns lock holder name for caller to compare)", () => {
-		// checkBeadLock is a pure function — it returns the lock holder name or null.
-		// The parent bypass logic is in slingCommand, not checkBeadLock.
+		// checkTaskLock is a pure function — it returns the lock holder name or null.
+		// The parent bypass logic is in slingCommand, not checkTaskLock.
 		// These tests verify the building blocks work correctly.
-		const sessions = [makeBeadSession("lead-alpha", "overstory-abc")];
-		// checkBeadLock still returns the holder — the caller (slingCommand) decides
+		const sessions = [makeTaskSession("lead-alpha", "overstory-abc")];
+		// checkTaskLock still returns the holder — the caller (slingCommand) decides
 		// whether to allow based on parentAgent match.
-		expect(checkBeadLock(sessions, "overstory-abc")).toBe("lead-alpha");
+		expect(checkTaskLock(sessions, "overstory-abc")).toBe("lead-alpha");
 	});
 
 	test("non-parent lock holder blocks spawn", () => {
-		const sessions = [makeBeadSession("other-agent", "overstory-abc")];
-		const lockHolder = checkBeadLock(sessions, "overstory-abc");
+		const sessions = [makeTaskSession("other-agent", "overstory-abc")];
+		const lockHolder = checkTaskLock(sessions, "overstory-abc");
 		const parentAgent = "lead-alpha";
 		// lockHolder is 'other-agent', parentAgent is 'lead-alpha' — not equal, should block
 		expect(lockHolder).not.toBeNull();
@@ -621,8 +623,8 @@ describe("checkBeadLock parent bypass", () => {
 	});
 
 	test("null parent with lock holder blocks spawn", () => {
-		const sessions = [makeBeadSession("lead-alpha", "overstory-abc")];
-		const lockHolder = checkBeadLock(sessions, "overstory-abc");
+		const sessions = [makeTaskSession("lead-alpha", "overstory-abc")];
+		const lockHolder = checkTaskLock(sessions, "overstory-abc");
 		const parentAgent = null;
 		// lockHolder is non-null and parentAgent is null — should block
 		expect(lockHolder).not.toBeNull();
@@ -630,6 +632,71 @@ describe("checkBeadLock parent bypass", () => {
 	});
 });
 
+/**
+ * Tests for checkDuplicateLead.
+ *
+ * checkDuplicateLead prevents spawning a second lead agent for the same task ID.
+ * It filters the active session list to only "lead" capability sessions, so
+ * builder/scout children working the same bead via parent delegation do not
+ * trigger this check.
+ *
+ * The activeSessions input is pre-filtered by store.getActive() to exclude
+ * completed and zombie sessions.
+ */
+
+function makeLeadSession(
+	agentName: string,
+	taskId: string,
+	capability: string,
+): { agentName: string; taskId: string; capability: string } {
+	return { agentName, taskId, capability };
+}
+
+describe("checkDuplicateLead", () => {
+	test("returns lead agent name when an active lead exists for the task", () => {
+		const sessions = [
+			makeLeadSession("lead-alpha", "overstory-abc", "lead"),
+			makeLeadSession("builder-1", "overstory-xyz", "builder"),
+		];
+		expect(checkDuplicateLead(sessions, "overstory-abc")).toBe("lead-alpha");
+	});
+
+	test("returns null when no lead exists for the task", () => {
+		const sessions = [
+			makeLeadSession("lead-alpha", "overstory-xyz", "lead"),
+			makeLeadSession("builder-1", "overstory-abc", "builder"),
+		];
+		expect(checkDuplicateLead(sessions, "overstory-abc")).toBeNull();
+	});
+
+	test("returns null when no sessions exist (completed/zombie filtered out)", () => {
+		// activeSessions from store.getActive() already excludes completed/zombie
+		expect(checkDuplicateLead([], "overstory-abc")).toBeNull();
+	});
+
+	test("ignores non-lead agents working the same bead", () => {
+		const sessions = [
+			makeLeadSession("builder-1", "overstory-abc", "builder"),
+			makeLeadSession("scout-1", "overstory-abc", "scout"),
+			makeLeadSession("reviewer-1", "overstory-abc", "reviewer"),
+		];
+		expect(checkDuplicateLead(sessions, "overstory-abc")).toBeNull();
+	});
+
+	test("returns first matching lead when multiple leads exist for the same bead", () => {
+		const sessions = [
+			makeLeadSession("lead-alpha", "overstory-abc", "lead"),
+			makeLeadSession("lead-beta", "overstory-abc", "lead"),
+		];
+		expect(checkDuplicateLead(sessions, "overstory-abc")).toBe("lead-alpha");
+	});
+
+	test("differentiates between task IDs", () => {
+		const sessions = [makeLeadSession("lead-alpha", "overstory-abc", "lead")];
+		expect(checkDuplicateLead(sessions, "overstory-xyz")).toBeNull();
+	});
+});
+
 /**
  * Tests for checkRunSessionLimit.
  *
@@ -660,6 +727,67 @@ describe("checkRunSessionLimit", () => {
 	});
 });
 
+describe("checkParentAgentLimit", () => {
+	test("returns false when limit is 0 (unlimited)", () => {
+		const sessions = [{ parentAgent: "lead-alpha" }, { parentAgent: "lead-alpha" }];
+		expect(checkParentAgentLimit(sessions, "lead-alpha", 0)).toBe(false);
+	});
+
+	test("returns false when count is below limit", () => {
+		const sessions = [{ parentAgent: "lead-alpha" }];
+		expect(checkParentAgentLimit(sessions, "lead-alpha", 5)).toBe(false);
+	});
+
+	test("returns true when count equals limit", () => {
+		const sessions = [
+			{ parentAgent: "lead-alpha" },
+			{ parentAgent: "lead-alpha" },
+			{ parentAgent: "lead-alpha" },
+		];
+		expect(checkParentAgentLimit(sessions, "lead-alpha", 3)).toBe(true);
+	});
+
+	test("returns true when count exceeds limit", () => {
+		const sessions = [
+			{ parentAgent: "lead-alpha" },
+			{ parentAgent: "lead-alpha" },
+			{ parentAgent: "lead-alpha" },
+			{ parentAgent: "lead-alpha" },
+		];
+		expect(checkParentAgentLimit(sessions, "lead-alpha", 3)).toBe(true);
+	});
+
+	test("returns false when limit is negative (treated as unlimited)", () => {
+		const sessions = [{ parentAgent: "lead-alpha" }];
+		expect(checkParentAgentLimit(sessions, "lead-alpha", -1)).toBe(false);
+	});
+
+	test("only counts children of the specified parent", () => {
+		const sessions = [
+			{ parentAgent: "lead-alpha" },
+			{ parentAgent: "lead-beta" },
+			{ parentAgent: "lead-alpha" },
+			{ parentAgent: "lead-gamma" },
+		];
+		expect(checkParentAgentLimit(sessions, "lead-alpha", 3)).toBe(false);
+		expect(checkParentAgentLimit(sessions, "lead-alpha", 2)).toBe(true);
+	});
+
+	test("returns false when no sessions match the parent", () => {
+		const sessions = [{ parentAgent: "lead-beta" }, { parentAgent: "lead-gamma" }];
+		expect(checkParentAgentLimit(sessions, "lead-alpha", 1)).toBe(false);
+	});
+
+	test("ignores sessions with null parent", () => {
+		const sessions = [{ parentAgent: null }, { parentAgent: "lead-alpha" }, { parentAgent: null }];
+		expect(checkParentAgentLimit(sessions, "lead-alpha", 2)).toBe(false);
+	});
+
+	test("returns false when sessions array is empty", () => {
+		expect(checkParentAgentLimit([], "lead-alpha", 5)).toBe(false);
+	});
+});
+
 /**
  * Tests for sling provider env injection building blocks.
  *
@@ -691,6 +819,7 @@ function makeConfig(
 			staggerDelayMs: 0,
 			maxDepth: 2,
 			maxSessionsPerRun: 0,
+			maxAgentsPerLead: 5,
 		},
 		worktrees: { baseDir: ".overstory/worktrees" },
 		taskTracker: { backend: "auto", enabled: false },
@@ -933,3 +1062,21 @@ describe("buildAutoDispatch", () => {
 		expect(dispatch.to).toBe("my-builder");
 	});
 });
+
+/**
+ * Beacon verification loop (sling.ts step 13d)
+ *
+ * NOT UNIT-TESTABLE: The beacon verification loop at sling.ts lines 687-698
+ * uses capturePaneContent() to poll tmux and resend the beacon if the agent
+ * is still at the welcome screen ("Try "). This involves real tmux operations
+ * that cannot be reliably mocked without mock.module() (which leaks across
+ * test files — see mx-56558b).
+ *
+ * Manual verification:
+ * 1. `ov sling <task-id> --name test --capability builder`
+ * 2. Watch tmux pane: `tmux capture-pane -t overstory-<project>-test -p`
+ * 3. Verify the beacon text appears and the agent starts processing
+ *
+ * Integration coverage: The beacon loop has been validated through production
+ * agent spawns. Failure mode is agents stuck at welcome screen (overstory-3271).
+ */