@os-eco/overstory-cli 0.8.2 → 0.8.4

package/README.md

@@ -19,7 +19,7 @@ Requires [Bun](https://bun.sh) v1.0+, git, and tmux. At least one supported agen
 - [GitHub Copilot](https://github.com/features/copilot) (`copilot` CLI)
 - [Codex](https://github.com/openai/codex) (`codex` CLI)
 - [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini` CLI)
-- [Sapling](https://github.com/nichochar/sapling) (`sp` CLI)
+- [Sapling](https://github.com/jayminwest/sapling) (`sp` CLI)
 
 ```bash
 bun install -g @os-eco/overstory-cli

package/agents/builder.md

@@ -20,7 +20,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, file scope, spec path, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
+Your task-specific context (task ID, file scope, spec path, branch name, parent agent) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
 
 ## constraints
 
@@ -108,7 +108,7 @@ You are an implementation specialist. Given a spec and a set of files you own, y
 
 ## workflow
 
-1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task ID, spec path, file scope, branch name, and agent name.
+1. **Read your overlay** at `{{INSTRUCTION_PATH}}` in your worktree. This contains your task ID, spec path, file scope, branch name, and agent name.
 2. **Read the task spec** at the path specified in your overlay. Understand what needs to be built.
 3. **Load expertise** via `ml prime [domain]` for domains listed in your overlay. Apply existing patterns and conventions.
 4. **Implement the changes:**

package/agents/lead.md

@@ -43,7 +43,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, spec path, hierarchy depth, agent name, whether you can spawn) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to coordinate. This file tells you HOW to coordinate.
+Your task-specific context (task ID, spec path, hierarchy depth, agent name, whether you can spawn) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `ov sling` and tells you WHAT to coordinate. This file tells you HOW to coordinate.
 
 ## constraints
 
@@ -160,7 +160,7 @@ Action: Full Scout → Build → Verify pipeline. Spawn scouts for exploration,
 
 Delegate exploration to scouts so you can focus on decomposition and planning.
 
-1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task ID, hierarchy depth, and agent name.
+1. **Read your overlay** at `{{INSTRUCTION_PATH}}` in your worktree. This contains your task ID, hierarchy depth, and agent name.
 2. **Load expertise** via `ml prime [domain]` for relevant domains.
 3. **Search mulch for relevant context** before decomposing. Run `ml search <task keywords>` and review failure patterns, conventions, and decisions. Factor these insights into your specs.
 4. **Load file-specific expertise** if files are known. Use `ml prime --files <file1,file2,...>` to get file-scoped context. Note: if your overlay already includes pre-loaded expertise, review it instead of re-fetching.

package/agents/merger.md

@@ -19,7 +19,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, branches to merge, target branch, merge order, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to merge. This file tells you HOW to merge.
+Your task-specific context (task ID, branches to merge, target branch, merge order, parent agent) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `overstory sling` and tells you WHAT to merge. This file tells you HOW to merge.
 
 ## constraints
 
@@ -97,7 +97,7 @@ You are a branch integration specialist. When workers complete their tasks on se
 
 ## workflow
 
-1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task ID, the branches to merge, the target branch, and your agent name.
+1. **Read your overlay** at `{{INSTRUCTION_PATH}}` in your worktree. This contains your task ID, the branches to merge, the target branch, and your agent name.
 2. **Read the task spec** at the path specified in your overlay. Understand which branches need merging and in what order.
 3. **Review the branches** before merging:
    - `git log <target>..<branch>` to see what each branch contains.

package/agents/orchestrator.md

@@ -31,7 +31,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, file scope, spec path, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
+Your task-specific context (task ID, file scope, spec path, branch name, parent agent) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `ov sling` and tells you WHAT to work on. This file tells you HOW to work.
 
 ## constraints
 

package/agents/reviewer.md

@@ -16,7 +16,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (task ID, code to review, branch name, parent agent) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to review. This file tells you HOW to review.
+Your task-specific context (task ID, code to review, branch name, parent agent) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `overstory sling` and tells you WHAT to review. This file tells you HOW to review.
 
 ## constraints
 
@@ -95,7 +95,7 @@ You are a validation specialist. Given code to review, you check it for correctn
 
 ## workflow
 
-1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task ID, the code or branch to review, and your agent name.
+1. **Read your overlay** at `{{INSTRUCTION_PATH}}` in your worktree. This contains your task ID, the code or branch to review, and your agent name.
 2. **Read the task spec** at the path specified in your overlay. Understand what was supposed to be built.
 3. **Load expertise** via `ml prime [domain]` to understand project conventions and standards.
 4. **Review the code changes:**

package/agents/scout.md

@@ -16,7 +16,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Your task-specific context (what to explore, who spawned you, your agent name) is in `.claude/CLAUDE.md` in your worktree. That file is generated by `overstory sling` and tells you WHAT to work on. This file tells you HOW to work.
+Your task-specific context (what to explore, who spawned you, your agent name) is in `{{INSTRUCTION_PATH}}` in your worktree. That file is generated by `overstory sling` and tells you WHAT to work on. This file tells you HOW to work.
 
 ## constraints
 
@@ -97,7 +97,7 @@ You perform reconnaissance. Given a research question, exploration target, or an
 
 ## workflow
 
-1. **Read your overlay** at `.claude/CLAUDE.md` in your worktree. This contains your task assignment, spec path, and agent name.
+1. **Read your overlay** at `{{INSTRUCTION_PATH}}` in your worktree. This contains your task assignment, spec path, and agent name.
 2. **Read the task spec** at the path specified in your overlay.
 3. **Load relevant expertise** via `ml prime [domain]` for domains listed in your overlay.
 4. **Explore systematically:**

package/agents/supervisor.md

@@ -31,7 +31,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 
 ## overlay
 
-Unlike the coordinator (which has no overlay), you receive your task-specific context via the overlay CLAUDE.md at `.claude/CLAUDE.md` in your worktree root. This file is generated by `ov supervisor start` (or `ov sling` with `--capability supervisor`) and provides:
+Unlike the coordinator (which has no overlay), you receive your task-specific context via the overlay CLAUDE.md at `{{INSTRUCTION_PATH}}` in your worktree root. This file is generated by `ov supervisor start` (or `ov sling` with `--capability supervisor`) and provides:
 
 - **Agent Name** (`$OVERSTORY_AGENT_NAME`) -- your mail address
 - **Task ID** -- the issue you are assigned to
@@ -163,7 +163,7 @@ Before spawning, check `ov status` to ensure non-overlapping file scope across a
 
 ## workflow
 
-1. **Receive the dispatch.** Your overlay (`.claude/CLAUDE.md`) contains your task ID and spec path. The coordinator sends you a `dispatch` mail with task details.
+1. **Receive the dispatch.** Your overlay (`{{INSTRUCTION_PATH}}`) contains your task ID and spec path. The coordinator sends you a `dispatch` mail with task details.
 2. **Read your task spec** at the path specified in your overlay. Understand the full scope of work assigned to you.
 3. **Load expertise** via `ml prime [domain]` for each relevant domain. Check `{{TRACKER_CLI}} show <task-id>` for task details and dependencies.
 4. **Analyze scope and decompose.** Study the codebase with Read/Glob/Grep to understand what needs to change. Determine:
@@ -418,7 +418,7 @@ You are long-lived within a project. You survive across batches and can recover
 - **Checkpoints** are saved to `.overstory/agents/$OVERSTORY_AGENT_NAME/checkpoint.json` before compaction or handoff. The checkpoint contains: agent name, assigned task ID, active worker IDs, task group ID, session ID, progress summary, and files modified.
 - **On recovery**, reload context by:
   1. Reading your checkpoint: `.overstory/agents/$OVERSTORY_AGENT_NAME/checkpoint.json`
-  2. Reading your overlay: `.claude/CLAUDE.md` (task ID, spec path, depth, parent)
+  2. Reading your overlay: `{{INSTRUCTION_PATH}}` (task ID, spec path, depth, parent)
   3. Checking active group: `ov group status <group-id>`
   4. Checking worker states: `ov status`
   5. Checking unread mail: `ov mail check --agent $OVERSTORY_AGENT_NAME`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.8.2",
+	"version": "0.8.4",
 	"description": "Multi-agent orchestration for AI coding agents — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution. Pluggable runtime adapters for Claude Code, Pi, and more.",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/agents/overlay.test.ts

@@ -875,6 +875,48 @@ describe("formatQualityGatesCapabilities", () => {
 	});
 });
 
+describe("INSTRUCTION_PATH placeholder", () => {
+	test("defaults to .claude/CLAUDE.md when instructionPath is not set", async () => {
+		const config = makeConfig({
+			baseDefinition: "Read your overlay at {{INSTRUCTION_PATH}} in your worktree.",
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).toContain("Read your overlay at .claude/CLAUDE.md in your worktree.");
+		expect(output).not.toContain("{{INSTRUCTION_PATH}}");
+	});
+
+	test("uses custom instructionPath when set", async () => {
+		const config = makeConfig({
+			instructionPath: "SAPLING.md",
+			baseDefinition: "Read your overlay at {{INSTRUCTION_PATH}} in your worktree.",
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).toContain("Read your overlay at SAPLING.md in your worktree.");
+		expect(output).not.toContain("{{INSTRUCTION_PATH}}");
+		expect(output).not.toContain(".claude/CLAUDE.md");
+	});
+
+	test("INSTRUCTION_PATH in base definition replaced throughout (multiple occurrences)", async () => {
+		const config = makeConfig({
+			instructionPath: "AGENTS.md",
+			baseDefinition: "Step 1: read {{INSTRUCTION_PATH}}.\nContext is in {{INSTRUCTION_PATH}}.",
+		});
+		const output = await generateOverlay(config);
+
+		expect(output).not.toContain("{{INSTRUCTION_PATH}}");
+		expect(output.split("AGENTS.md").length - 1).toBeGreaterThanOrEqual(2);
+	});
+
+	test("no unreplaced INSTRUCTION_PATH placeholders in final output", async () => {
+		const config = makeConfig({ instructionPath: "SAPLING.md" });
+		const output = await generateOverlay(config);
+
+		expect(output).not.toContain("{{INSTRUCTION_PATH}}");
+	});
+});
+
 describe("quality gate placeholders in base definitions", () => {
 	test("QUALITY_GATE_INLINE in base definition gets replaced", async () => {
 		const config = makeConfig({

package/src/agents/overlay.ts

@@ -320,6 +320,7 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 		"{{QUALITY_GATE_CAPABILITIES}}": formatQualityGatesCapabilities(config.qualityGates),
 		"{{TRACKER_CLI}}": config.trackerCli ?? "sd",
 		"{{TRACKER_NAME}}": config.trackerName ?? "seeds",
+		"{{INSTRUCTION_PATH}}": config.instructionPath ?? ".claude/CLAUDE.md",
 	};
 
 	let result = template;

package/src/commands/agents.ts

@@ -10,7 +10,7 @@ import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
 import { accent, color } from "../logging/color.ts";
-import { getRuntime } from "../runtimes/registry.ts";
+import { getAllRuntimes, getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { type AgentSession, SUPPORTED_CAPABILITIES } from "../types.ts";
 
@@ -30,12 +30,10 @@ export interface DiscoveredAgent {
 	lastActivity: string;
 }
 
-/** Known instruction file paths, tried in order until one exists. */
-const KNOWN_INSTRUCTION_PATHS = [
-	join(".claude", "CLAUDE.md"), // Claude Code, Pi
-	"AGENTS.md", // Codex (future)
-	"GEMINI.md", // Gemini CLI
-];
+/** Build the list of known instruction file paths from all registered runtimes. */
+function getKnownInstructionPaths(): string[] {
+	return [...new Set(getAllRuntimes().map((r) => r.instructionPath))];
+}
 
 /**
  * Extract file scope from an agent's overlay instruction file.
@@ -52,9 +50,10 @@ export async function extractFileScope(
 ): Promise<string[]> {
 	try {
 		let content: string | null = null;
+		const knownPaths = getKnownInstructionPaths();
 		const pathsToTry = runtimeInstructionPath
-			? [runtimeInstructionPath, ...KNOWN_INSTRUCTION_PATHS]
-			: KNOWN_INSTRUCTION_PATHS;
+			? [runtimeInstructionPath, ...knownPaths]
+			: knownPaths;
 		for (const relPath of pathsToTry) {
 			const overlayPath = join(worktreePath, relPath);
 			const overlayFile = Bun.file(overlayPath);

package/src/commands/coordinator.ts

@@ -363,7 +363,7 @@ async function startCoordinator(
 		);
 		const manifest = await manifestLoader.load();
 		const resolvedModel = resolveModel(config, manifest, "coordinator", "opus");
-		const runtime = getRuntime(undefined, config);
+		const runtime = getRuntime(undefined, config, "coordinator");
 
 		// Deploy hooks to the project root so the coordinator gets event logging,
 		// mail check --inject, and activity tracking via the standard hook pipeline.

package/src/commands/costs.ts

@@ -14,9 +14,11 @@ import { ValidationError } from "../errors.ts";
 import { jsonError, jsonOutput } from "../json.ts";
 import { color } from "../logging/color.ts";
 import { renderHeader, separator } from "../logging/theme.ts";
+import { estimateCost } from "../metrics/pricing.ts";
 import { createMetricsStore } from "../metrics/store.ts";
-import { estimateCost, parseTranscriptUsage } from "../metrics/transcript.ts";
+import { parseTranscriptUsage } from "../metrics/transcript.ts";
 import { getRuntime } from "../runtimes/registry.ts";
+import type { AgentRuntime } from "../runtimes/types.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { SessionMetrics } from "../types.ts";
 
@@ -43,41 +45,21 @@ function padLeft(str: string, width: number): string {
 	return str.length >= width ? str : " ".repeat(width - str.length) + str;
 }
 
-/**
- * Resolve the transcript directory for a given runtime and project root.
- *
- * @param runtimeId - The runtime identifier (e.g. "claude")
- * @param projectRoot - Absolute path to the project root
- * @returns Absolute path to the transcript directory, or null if not supported
- */
-function getTranscriptDir(runtimeId: string, projectRoot: string): string | null {
-	const homeDir = process.env.HOME ?? "";
-	if (homeDir.length === 0) return null;
-	switch (runtimeId) {
-		case "claude": {
-			const projectKey = projectRoot.replace(/\//g, "-");
-			return join(homeDir, ".claude", "projects", projectKey);
-		}
-		default:
-			return null;
-	}
-}
-
 /**
  * Discover the orchestrator's transcript JSONL file for the given runtime.
  *
  * Scans the runtime-specific transcript directory for JSONL files and returns
  * the most recently modified one, corresponding to the current orchestrator session.
  *
- * @param runtimeId - The runtime identifier (e.g. "claude")
+ * @param runtime - The agent runtime adapter
  * @param projectRoot - Absolute path to the project root
  * @returns Absolute path to the most recent transcript, or null if none found
  */
 async function discoverOrchestratorTranscript(
-	runtimeId: string,
+	runtime: AgentRuntime,
 	projectRoot: string,
 ): Promise<string | null> {
-	const transcriptDir = getTranscriptDir(runtimeId, projectRoot);
+	const transcriptDir = runtime.getTranscriptDir(projectRoot);
 	if (transcriptDir === null) return null;
 
 	let entries: string[];
@@ -292,7 +274,7 @@ async function executeCosts(opts: CostsOpts): Promise<void> {
 	// Handle --self flag (early return for self-scan)
 	if (self) {
 		const runtime = getRuntime(undefined, config);
-		const transcriptPath = await discoverOrchestratorTranscript(runtime.id, config.project.root);
+		const transcriptPath = await discoverOrchestratorTranscript(runtime, config.project.root);
 		if (!transcriptPath) {
 			if (json) {
 				jsonError("costs", `No transcript found for runtime '${runtime.id}'`);

package/src/commands/log.ts

@@ -21,8 +21,9 @@ import { analyzeSessionInsights } from "../insights/analyzer.ts";
 import { createLogger } from "../logging/logger.ts";
 import { createMailClient } from "../mail/client.ts";
 import { createMailStore } from "../mail/store.ts";
+import { estimateCost } from "../metrics/pricing.ts";
 import { createMetricsStore } from "../metrics/store.ts";
-import { estimateCost, parseTranscriptUsage } from "../metrics/transcript.ts";
+import { parseTranscriptUsage } from "../metrics/transcript.ts";
 import { createMulchClient, type MulchClient } from "../mulch/client.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";

package/src/commands/monitor.ts

@@ -117,7 +117,7 @@ async function startMonitor(opts: { json: boolean; attach: boolean }): Promise<v
 		);
 		const manifest = await manifestLoader.load();
 		const resolvedModel = resolveModel(config, manifest, "monitor", "sonnet");
-		const runtime = getRuntime(undefined, config);
+		const runtime = getRuntime(undefined, config, "monitor");
 
 		// Deploy monitor-specific hooks to the project root's .claude/ directory.
 		await runtime.deployConfig(projectRoot, undefined, {

package/src/commands/sling.test.ts

@@ -20,6 +20,7 @@ import {
 	checkRunSessionLimit,
 	checkTaskLock,
 	extractMulchRecordIds,
+	generateAgentName,
 	getCurrentBranch,
 	inferDomainsFromFiles,
 	isRunningAsRoot,
@@ -342,6 +343,31 @@ describe("shouldShowScoutWarning", () => {
 	});
 });
 
+describe("generateAgentName", () => {
+	test("returns capability-taskId when no collision", () => {
+		expect(generateAgentName("builder", "overstory-2f10", [])).toBe("builder-overstory-2f10");
+	});
+
+	test("returns capability-taskId when takenNames is empty", () => {
+		expect(generateAgentName("scout", "task-123", [])).toBe("scout-task-123");
+	});
+
+	test("appends -2 when base name is taken", () => {
+		expect(generateAgentName("builder", "overstory-2f10", ["builder-overstory-2f10"])).toBe(
+			"builder-overstory-2f10-2",
+		);
+	});
+
+	test("skips taken suffixes and returns -3 when -2 is also taken", () => {
+		expect(
+			generateAgentName("builder", "overstory-2f10", [
+				"builder-overstory-2f10",
+				"builder-overstory-2f10-2",
+			]),
+		).toBe("builder-overstory-2f10-3");
+	});
+});
+
 /**
  * Tests for hierarchy validation in sling.
  *
@@ -352,14 +378,12 @@ describe("shouldShowScoutWarning", () => {
  */
 
 describe("validateHierarchy", () => {
-	test("rejects builder when parentAgent is null", () => {
-		expect(() => validateHierarchy(null, "builder", "test-builder", 0, false)).toThrow(
-			HierarchyError,
-		);
+	test("allows builder when parentAgent is null", () => {
+		expect(() => validateHierarchy(null, "builder", "test-builder", 0, false)).not.toThrow();
 	});
 
-	test("rejects scout when parentAgent is null", () => {
-		expect(() => validateHierarchy(null, "scout", "test-scout", 0, false)).toThrow(HierarchyError);
+	test("allows scout when parentAgent is null", () => {
+		expect(() => validateHierarchy(null, "scout", "test-scout", 0, false)).not.toThrow();
 	});
 
 	test("rejects reviewer when parentAgent is null", () => {
@@ -404,15 +428,15 @@ describe("validateHierarchy", () => {
 
 	test("error has correct fields and code", () => {
 		try {
-			validateHierarchy(null, "builder", "my-builder", 0, false);
+			validateHierarchy(null, "reviewer", "my-reviewer", 0, false);
 			expect.unreachable("should have thrown");
 		} catch (err) {
 			expect(err).toBeInstanceOf(HierarchyError);
 			const he = err as HierarchyError;
 			expect(he.code).toBe("HIERARCHY_VIOLATION");
-			expect(he.agentName).toBe("my-builder");
-			expect(he.requestedCapability).toBe("builder");
-			expect(he.message).toContain("builder");
+			expect(he.agentName).toBe("my-reviewer");
+			expect(he.requestedCapability).toBe("reviewer");
+			expect(he.message).toContain("reviewer");
 			expect(he.message).toContain("lead");
 		}
 	});

package/src/commands/sling.ts

@@ -32,7 +32,6 @@ import { printSuccess } from "../logging/color.ts";
 import { createMailClient } from "../mail/client.ts";
 import { createMailStore } from "../mail/store.ts";
 import { createMulchClient } from "../mulch/client.ts";
-import { setConnection } from "../runtimes/connections.ts";
 import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
@@ -78,6 +77,29 @@ export function calculateStaggerDelay(
 	return remaining > 0 ? remaining : 0;
 }
 
+/**
+ * Generate a unique agent name from capability and taskId.
+ * Base: capability-taskId. If that collides with takenNames,
+ * appends -2, -3, etc. up to 100. Falls back to -Date.now() for guaranteed uniqueness.
+ */
+export function generateAgentName(
+	capability: string,
+	taskId: string,
+	takenNames: readonly string[],
+): string {
+	const base = `${capability}-${taskId}`;
+	if (!takenNames.includes(base)) {
+		return base;
+	}
+	for (let i = 2; i <= 100; i++) {
+		const candidate = `${base}-${i}`;
+		if (!takenNames.includes(candidate)) {
+			return candidate;
+		}
+	}
+	return `${base}-${Date.now()}`;
+}
+
 /**
  * Check if the current process is running as root (UID 0).
  * Returns true if running as root, false otherwise.
@@ -348,9 +370,10 @@ export function validateHierarchy(
 		return;
 	}
 
-	if (parentAgent === null && capability !== "lead") {
+	const directSpawnCapabilities = ["lead", "scout", "builder"];
+	if (parentAgent === null && !directSpawnCapabilities.includes(capability)) {
 		throw new HierarchyError(
-			`Coordinator cannot spawn "${capability}" directly. Only "lead" is allowed without --parent. Use a lead as intermediary, or pass --force-hierarchy to bypass.`,
+			`Coordinator cannot spawn "${capability}" directly. Only lead, scout, and builder are allowed without --parent. Use a lead as intermediary, or pass --force-hierarchy to bypass.`,
 			{ agentName: name, requestedCapability: capability },
 		);
 	}
@@ -429,7 +452,9 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 	}
 
 	const capability = opts.capability ?? "builder";
-	const name = opts.name;
+	const rawName = opts.name?.trim() ?? "";
+	const nameWasAutoGenerated = rawName.length === 0;
+	let name = nameWasAutoGenerated ? `${capability}-${taskId}` : rawName;
 	const specPath = opts.spec ?? null;
 	const filesRaw = opts.files;
 	const parentAgent = opts.parent ?? null;
@@ -439,10 +464,6 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 	const skipScout = opts.skipScout ?? false;
 	const skipTaskCheck = opts.skipTaskCheck ?? false;
 
-	if (!name || name.trim().length === 0) {
-		throw new ValidationError("--name is required for sling", { field: "name" });
-	}
-
 	if (Number.isNaN(depth) || depth < 0) {
 		throw new ValidationError("--depth must be a non-negative integer", {
 			field: "depth",
@@ -597,11 +618,16 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			);
 		}
 
-		const existing = store.getByName(name);
-		if (existing && existing.state !== "zombie" && existing.state !== "completed") {
-			throw new AgentError(`Agent name "${name}" is already in use (state: ${existing.state})`, {
-				agentName: name,
-			});
+		if (nameWasAutoGenerated) {
+			const takenNames = activeSessions.map((s) => s.agentName);
+			name = generateAgentName(capability, taskId, takenNames);
+		} else {
+			const existing = store.getByName(name);
+			if (existing && existing.state !== "zombie" && existing.state !== "completed") {
+				throw new AgentError(`Agent name "${name}" is already in use (state: ${existing.state})`, {
+					agentName: name,
+				});
+			}
 		}
 
 		// 5d. Task-level locking: prevent concurrent agents on the same task ID.
@@ -717,6 +743,9 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			}
 		}
 
+		// Resolve runtime before overlayConfig so we can pass runtime.instructionPath
+		const runtime = getRuntime(opts.runtime, config, capability);
+
 		const overlayConfig: OverlayConfig = {
 			agentName: name,
 			taskId: taskId,
@@ -742,11 +771,9 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			qualityGates: config.project.qualityGates,
 			trackerCli: trackerCliName(resolvedBackend),
 			trackerName: resolvedBackend,
+			instructionPath: runtime.instructionPath,
 		};
 
-		// Resolve runtime before writeOverlay so we can pass runtime.instructionPath
-		const runtime = getRuntime(opts.runtime, config);
-
 		try {
 			await writeOverlay(worktreePath, overlayConfig, config.project.root, runtime.instructionPath);
 		} catch (err) {
@@ -854,14 +881,14 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			});
 
 			// Create a timestamped log dir for this headless agent session.
-			// Redirecting stdout/stderr to files prevents OS pipe buffer backpressure:
-			// when nobody reads the pipe, the child blocks on write() after ~64 KB and
-			// becomes a zombie. File writes have no such limit.
+			// Always redirect stdout to a file. This prevents SIGPIPE death:
+			// ov sling exits after spawning, closing the pipe's read end.
+			// If stdout is a pipe, the agent dies on the next write (SIGPIPE).
+			// File writes have no such limit, and the agent survives the CLI exit.
 			//
-			// Exception: RPC-capable runtimes need a live stdout pipe to receive
-			// JSON-RPC 2.0 responses (getState). In that case stdoutFile is omitted
-			// and the caller consumes the stream via the RuntimeConnection.
-			const hasRpcConnect = typeof runtime.connect === "function";
+			// Note: RPC connection wiring is intentionally omitted here. The RPC pipe
+			// is only useful when the spawner stays alive to consume it. ov sling is
+			// a short-lived CLI — any connection created here dies with the process.
 			const logTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
 			const agentLogDir = join(overstoryDir, "logs", name, logTimestamp);
 			mkdirSync(agentLogDir, { recursive: true });
@@ -869,21 +896,10 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			const headlessProc = await spawnHeadlessAgent(argv, {
 				cwd: worktreePath,
 				env: { ...(process.env as Record<string, string>), ...directEnv },
-				stdoutFile: hasRpcConnect ? undefined : join(agentLogDir, "stdout.log"),
+				stdoutFile: join(agentLogDir, "stdout.log"),
 				stderrFile: join(agentLogDir, "stderr.log"),
 			});
 
-			// Wire up RPC connection for runtimes that support it (e.g., Sapling).
-			// The connection is stored in the module-level registry so the watchdog
-			// and other subsystems can call getState() for health checks.
-			if (hasRpcConnect && headlessProc.stdout && runtime.connect) {
-				const connection = runtime.connect({
-					stdin: headlessProc.stdin,
-					stdout: headlessProc.stdout,
-				});
-				setConnection(name, connection);
-			}
-
 			// 13. Record session with empty tmuxSession (no tmux pane for headless agents).
 			const session: AgentSession = {
 				id: `session-${Date.now()}-${name}`,