@os-eco/overstory-cli 0.8.3 → 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.8.3",
+	"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/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.ts

@@ -744,7 +744,7 @@ 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);
+		const runtime = getRuntime(opts.runtime, config, capability);
 
 		const overlayConfig: OverlayConfig = {
 			agentName: name,

package/src/commands/supervisor.ts

@@ -143,7 +143,7 @@ async function startSupervisor(opts: {
 		);
 		const manifest = await manifestLoader.load();
 		const resolvedModel = resolveModel(config, manifest, "supervisor", "opus");
-		const runtime = getRuntime(undefined, config);
+		const runtime = getRuntime(undefined, config, "supervisor");
 
 		// Deploy supervisor-specific hooks to the project root's .claude/ directory.
 		await runtime.deployConfig(projectRoot, undefined, {

package/src/config.ts

@@ -706,6 +706,17 @@ function validateConfig(config: OverstoryConfig): void {
 		}
 	}
 
+	if (config.runtime?.capabilities) {
+		for (const [cap, runtimeName] of Object.entries(config.runtime.capabilities)) {
+			if (runtimeName !== undefined && (typeof runtimeName !== "string" || runtimeName === "")) {
+				throw new ValidationError(`runtime.capabilities.${cap} must be a non-empty string`, {
+					field: `runtime.capabilities.${cap}`,
+					value: runtimeName,
+				});
+			}
+		}
+	}
+
 	// models: validate each value.
 	// - Standard runtimes: aliases (sonnet/opus/haiku) or provider-prefixed refs.
 	// - Codex runtime: also allow bare model refs (e.g. gpt-5.3-codex).

package/src/index.ts

@@ -49,7 +49,7 @@ import { ConfigError, OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.8.3";
+export const VERSION = "0.8.4";
 
 const rawArgs = process.argv.slice(2);
 

package/src/merge/resolver.test.ts

@@ -290,6 +290,105 @@ describe("createMergeResolver", () => {
 		});
 	});
 
+	describe("Dirty working tree pre-check", () => {
+		test("throws MergeError when unstaged changes exist on tracked files", async () => {
+			const repoDir = await createTempGitRepo();
+			try {
+				const defaultBranch = await getDefaultBranch(repoDir);
+				// Create a tracked file and then leave it modified (unstaged)
+				await commitFile(repoDir, "src/main.ts", "original content\n");
+				await runGitInDir(repoDir, ["checkout", "-b", "feature-branch"]);
+				await commitFile(repoDir, "src/feature.ts", "feature content\n");
+				await runGitInDir(repoDir, ["checkout", defaultBranch]);
+				// Modify a tracked file without staging
+				await Bun.write(`${repoDir}/src/main.ts`, "modified content\n");
+
+				const entry = makeTestEntry({
+					branchName: "feature-branch",
+					filesModified: ["src/feature.ts"],
+				});
+
+				const resolver = createMergeResolver({
+					aiResolveEnabled: false,
+					reimagineEnabled: false,
+				});
+
+				await expect(resolver.resolve(entry, defaultBranch, repoDir)).rejects.toThrow(MergeError);
+			} finally {
+				await cleanupTempDir(repoDir);
+			}
+		});
+
+		test("throws MergeError with message listing dirty files", async () => {
+			const repoDir = await createTempGitRepo();
+			try {
+				const defaultBranch = await getDefaultBranch(repoDir);
+				await commitFile(repoDir, "src/main.ts", "original content\n");
+				await runGitInDir(repoDir, ["checkout", "-b", "feature-branch"]);
+				await commitFile(repoDir, "src/feature.ts", "feature content\n");
+				await runGitInDir(repoDir, ["checkout", defaultBranch]);
+				await Bun.write(`${repoDir}/src/main.ts`, "modified content\n");
+
+				const entry = makeTestEntry({ branchName: "feature-branch" });
+				const resolver = createMergeResolver({ aiResolveEnabled: false, reimagineEnabled: false });
+
+				try {
+					await resolver.resolve(entry, defaultBranch, repoDir);
+					expect(true).toBe(false); // should not reach
+				} catch (err: unknown) {
+					expect(err).toBeInstanceOf(MergeError);
+					const mergeErr = err as MergeError;
+					expect(mergeErr.message).toContain("src/main.ts");
+					expect(mergeErr.message).toContain("Commit or stash");
+				}
+			} finally {
+				await cleanupTempDir(repoDir);
+			}
+		});
+
+		test("throws MergeError when staged but uncommitted changes exist", async () => {
+			const repoDir = await createTempGitRepo();
+			try {
+				const defaultBranch = await getDefaultBranch(repoDir);
+				await commitFile(repoDir, "src/main.ts", "original content\n");
+				await runGitInDir(repoDir, ["checkout", "-b", "feature-branch"]);
+				await commitFile(repoDir, "src/feature.ts", "feature content\n");
+				await runGitInDir(repoDir, ["checkout", defaultBranch]);
+				// Modify and stage (but don't commit)
+				await Bun.write(`${repoDir}/src/main.ts`, "staged but not committed\n");
+				await runGitInDir(repoDir, ["add", "src/main.ts"]);
+
+				const entry = makeTestEntry({ branchName: "feature-branch" });
+				const resolver = createMergeResolver({ aiResolveEnabled: false, reimagineEnabled: false });
+
+				await expect(resolver.resolve(entry, defaultBranch, repoDir)).rejects.toThrow(MergeError);
+			} finally {
+				await cleanupTempDir(repoDir);
+			}
+		});
+
+		test("clean working tree proceeds normally to Tier 1", async () => {
+			const repoDir = await createTempGitRepo();
+			try {
+				const defaultBranch = await getDefaultBranch(repoDir);
+				await setupCleanMerge(repoDir, defaultBranch);
+
+				const entry = makeTestEntry({
+					branchName: "feature-branch",
+					filesModified: ["src/feature-file.ts"],
+				});
+
+				const resolver = createMergeResolver({ aiResolveEnabled: false, reimagineEnabled: false });
+				const result = await resolver.resolve(entry, defaultBranch, repoDir);
+
+				expect(result.success).toBe(true);
+				expect(result.tier).toBe("clean-merge");
+			} finally {
+				await cleanupTempDir(repoDir);
+			}
+		});
+	});
+
 	describe("Tier 1 fail -> Tier 2: Auto-resolve", () => {
 		test("auto-resolves conflicts keeping incoming changes with correct content", async () => {
 			const repoDir = await createTempGitRepo();

package/src/merge/resolver.ts

@@ -50,6 +50,26 @@ async function runGit(
 	return { stdout, stderr, exitCode };
 }
 
+/**
+ * Get the list of tracked files with uncommitted changes (unstaged or staged).
+ * Returns deduplicated list of file paths. An empty list means the working tree is clean.
+ */
+async function checkDirtyWorkingTree(repoRoot: string): Promise<string[]> {
+	const { stdout: unstaged } = await runGit(repoRoot, ["diff", "--name-only"]);
+	const { stdout: staged } = await runGit(repoRoot, ["diff", "--name-only", "--cached"]);
+	const files = [
+		...unstaged
+			.trim()
+			.split("\n")
+			.filter((l) => l.length > 0),
+		...staged
+			.trim()
+			.split("\n")
+			.filter((l) => l.length > 0),
+	];
+	return [...new Set(files)];
+}
+
 /**
  * Get the list of conflicted files from `git diff --name-only --diff-filter=U`.
  */
@@ -593,6 +613,17 @@ export function createMergeResolver(options: {
 				}
 			}
 
+			// Pre-check: abort early if working tree has uncommitted changes.
+			// When dirty tracked files exist, git merge refuses to start (exit 1, no conflict markers),
+			// causing all tiers to cascade with empty conflict lists and a misleading final error.
+			const dirtyFiles = await checkDirtyWorkingTree(repoRoot);
+			if (dirtyFiles.length > 0) {
+				throw new MergeError(
+					`Working tree has uncommitted changes to tracked files: ${dirtyFiles.join(", ")}. Commit or stash changes before running ov merge.`,
+					{ branchName: entry.branchName },
+				);
+			}
+
 			let lastTier: ResolutionTier = "clean-merge";
 			let conflictFiles: string[] = [];
 

package/src/metrics/transcript.test.ts

@@ -6,7 +6,7 @@
  *
  * Coverage:
  *   - parseTranscriptUsage (transcript.ts)
- *   - estimateCost re-export (transcript.ts -> pricing.ts)
+ *   - estimateCost (pricing.ts, imported directly)
  *   - getPricingForModel (pricing.ts)
  */
 
@@ -15,8 +15,8 @@ import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { cleanupTempDir } from "../test-helpers.ts";
-import { getPricingForModel, estimateCost as pricingEstimateCost } from "./pricing.ts";
-import { estimateCost, parseTranscriptUsage } from "./transcript.ts";
+import { estimateCost, getPricingForModel } from "./pricing.ts";
+import { parseTranscriptUsage } from "./transcript.ts";
 
 let tempDir: string;
 
@@ -479,17 +479,5 @@ describe("getPricingForModel", () => {
 	});
 });
 
-// === re-export parity ===
-
-describe("estimateCost re-export parity", () => {
-	test("transcript.estimateCost and pricing.estimateCost produce same result", () => {
-		const usage = {
-			inputTokens: 1_000_000,
-			outputTokens: 1_000_000,
-			cacheReadTokens: 1_000_000,
-			cacheCreationTokens: 1_000_000,
-			modelUsed: "claude-opus-4-6",
-		};
-		expect(estimateCost(usage)).toBe(pricingEstimateCost(usage));
-	});
-});
+// estimateCost re-export removed from transcript.ts (overstory-aa00).
+// estimateCost is now imported directly from pricing.ts everywhere.

package/src/metrics/transcript.ts

@@ -27,8 +27,6 @@ import type { TokenUsage } from "./pricing.ts";
 
 export type TranscriptUsage = TokenUsage;
 
-export { estimateCost } from "./pricing.ts";
-
 /**
  * Narrow an unknown value to determine if it looks like a transcript assistant entry.
  * Returns the usage fields if valid, or null otherwise.

package/src/runtimes/claude.ts

@@ -5,7 +5,8 @@
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { deployHooks } from "../agents/hooks-deployer.ts";
-import { estimateCost, parseTranscriptUsage } from "../metrics/transcript.ts";
+import { estimateCost } from "../metrics/pricing.ts";
+import { parseTranscriptUsage } from "../metrics/transcript.ts";
 import type { ResolvedModel } from "../types.ts";
 import type {
 	AgentRuntime,
@@ -219,6 +220,22 @@ export class ClaudeRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/**
+	 * Return the Claude Code transcript directory for a given project root.
+	 *
+	 * Claude Code stores session transcripts at ~/.claude/projects/<projectKey>/
+	 * where <projectKey> is the project root path with "/" replaced by "-".
+	 *
+	 * @param projectRoot - Absolute path to the project root
+	 * @returns Absolute path to the transcript directory, or null if HOME is unavailable
+	 */
+	getTranscriptDir(projectRoot: string): string | null {
+		const home = process.env.HOME ?? "";
+		if (home.length === 0) return null;
+		const projectKey = projectRoot.replace(/\//g, "-");
+		return join(home, ".claude", "projects", projectKey);
+	}
 }
 
 /** Singleton instance for use in callers that do not need DI. */

package/src/runtimes/codex.ts

@@ -230,4 +230,9 @@ export class CodexRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Codex does not produce transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/copilot.ts

@@ -223,4 +223,9 @@ export class CopilotRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Copilot does not produce transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/gemini.ts

@@ -232,4 +232,9 @@ export class GeminiRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Gemini does not produce transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/pi.ts

@@ -245,4 +245,9 @@ export class PiRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Pi uses RPC — no transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/registry.test.ts

@@ -117,4 +117,40 @@ describe("getRuntime", () => {
 		expect(runtime).toBeInstanceOf(GeminiRuntime);
 		expect(runtime.id).toBe("gemini");
 	});
+
+	describe("capability routing", () => {
+		it("resolves capability-specific runtime from config", () => {
+			const config = {
+				runtime: { default: "claude", capabilities: { builder: "gemini" } },
+			} as unknown as OverstoryConfig;
+			const runtime = getRuntime(undefined, config, "builder");
+			expect(runtime).toBeInstanceOf(GeminiRuntime);
+			expect(runtime.id).toBe("gemini");
+		});
+
+		it("falls back to default when capability has no override", () => {
+			const config = {
+				runtime: { default: "codex", capabilities: { builder: "gemini" } },
+			} as unknown as OverstoryConfig;
+			const runtime = getRuntime(undefined, config, "scout");
+			expect(runtime).toBeInstanceOf(CodexRuntime);
+			expect(runtime.id).toBe("codex");
+		});
+
+		it("explicit name overrides capability routing", () => {
+			const config = {
+				runtime: { default: "claude", capabilities: { builder: "gemini" } },
+			} as unknown as OverstoryConfig;
+			const runtime = getRuntime("copilot", config, "builder");
+			expect(runtime).toBeInstanceOf(CopilotRuntime);
+			expect(runtime.id).toBe("copilot");
+		});
+
+		it("works when capabilities is undefined", () => {
+			const config = { runtime: { default: "claude" } } as OverstoryConfig;
+			const runtime = getRuntime(undefined, config, "coordinator");
+			expect(runtime).toBeInstanceOf(ClaudeRuntime);
+			expect(runtime.id).toBe("claude");
+		});
+	});
 });

package/src/runtimes/registry.ts

@@ -20,24 +20,54 @@ const runtimes = new Map<string, () => AgentRuntime>([
 	["sapling", () => new SaplingRuntime()],
 ]);
 
+/**
+ * Return all registered runtime adapter instances.
+ *
+ * Used by callers that need to enumerate all runtimes (e.g. to build a
+ * dynamic list of known instruction file paths from each runtime's
+ * `instructionPath` property).
+ *
+ * @returns Array of one fresh instance per registered runtime.
+ */
+export function getAllRuntimes(): AgentRuntime[] {
+	return [
+		new ClaudeRuntime(),
+		new CodexRuntime(),
+		new PiRuntime(),
+		new CopilotRuntime(),
+		new GeminiRuntime(),
+		new SaplingRuntime(),
+	];
+}
+
 /**
  * Resolve a runtime adapter by name.
  *
  * Lookup order:
  * 1. Explicit `name` argument (if provided)
- * 2. `config.runtime.default` (if config is provided)
- * 3. `"claude"` (hardcoded fallback)
+ * 2. `config.runtime.capabilities[capability]` (if capability provided)
+ * 3. `config.runtime.default` (if config is provided)
+ * 4. `"claude"` (hardcoded fallback)
  *
  * Special cases:
  * - Pi runtime receives `config.runtime.pi` for model alias expansion.
  *
  * @param name - Runtime name to resolve (e.g. "claude"). Omit to use config default.
  * @param config - Overstory config for reading the default runtime.
+ * @param capability - Agent capability (e.g. "coordinator", "builder") for per-capability routing.
  * @throws {Error} If the resolved runtime name is not registered.
  * @returns A fresh AgentRuntime instance.
  */
-export function getRuntime(name?: string, config?: OverstoryConfig): AgentRuntime {
-	const runtimeName = name ?? config?.runtime?.default ?? "claude";
+export function getRuntime(
+	name?: string,
+	config?: OverstoryConfig,
+	capability?: string,
+): AgentRuntime {
+	const capabilityRuntime =
+		capability && config?.runtime?.capabilities
+			? config.runtime.capabilities[capability]
+			: undefined;
+	const runtimeName = name ?? capabilityRuntime ?? config?.runtime?.default ?? "claude";
 
 	// Pi runtime needs config for model alias expansion.
 	if (runtimeName === "pi") {

package/src/runtimes/sapling.ts

@@ -695,4 +695,9 @@ export class SaplingRuntime implements AgentRuntime {
 
 		return env;
 	}
+
+	/** Sapling uses NDJSON event streaming — no transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/types.ts

@@ -184,6 +184,15 @@ export interface AgentRuntime {
 	 */
 	parseTranscript(path: string): Promise<TranscriptSummary | null>;
 
+	/**
+	 * Return the directory containing session transcript files for this runtime,
+	 * or null if transcript discovery is not supported.
+	 *
+	 * @param projectRoot - Absolute path to the project root
+	 * @returns Absolute path to the transcript directory, or null
+	 */
+	getTranscriptDir(projectRoot: string): string | null;
+
 	/**
 	 * Build runtime-specific environment variables for model/provider routing.
 	 * Claude Code uses ANTHROPIC_API_KEY; Codex uses OPENAI_API_KEY; Pi passes

package/src/types.ts

@@ -97,6 +97,11 @@ export interface OverstoryConfig {
 	runtime?: {
 		/** Default runtime adapter name (default: "claude"). */
 		default: string;
+		/**
+		 * Per-capability runtime overrides. Maps capability names (e.g. "coordinator", "builder")
+		 * to runtime adapter names. Lookup chain: explicit --runtime flag > capabilities[cap] > default > "claude".
+		 */
+		capabilities?: Partial<Record<string, string>>;
 		/**
 		 * Runtime adapter for headless one-shot AI calls (--print mode).
 		 * Used by merge/resolver.ts and watchdog/triage.ts.