@os-eco/overstory-cli 0.7.4 → 0.7.6

package/src/doctor/providers.ts

@@ -0,0 +1,250 @@
+import type { OverstoryConfig, ProviderConfig } from "../types.ts";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/** Roles that rely heavily on tool-use (function calling). */
+const TOOL_HEAVY_ROLES = new Set(["builder", "scout", "merger"]);
+
+/**
+ * Provider and multi-runtime configuration checks.
+ *
+ * Validates gateway provider reachability, auth tokens, model-provider references,
+ * and tool-use compatibility across configured runtimes.
+ */
+export const checkProviders: DoctorCheckFn = async (
+	config,
+	_overstoryDir,
+): Promise<DoctorCheck[]> => {
+	const checks: DoctorCheck[] = [];
+
+	// Base check: at least one provider configured
+	checks.push(buildProvidersConfigured(config));
+
+	// Identify gateway providers
+	const gatewayEntries = Object.entries(config.providers).filter(([, p]) => p.type === "gateway");
+
+	// Check 1: provider-reachable-{name} — one per gateway provider with baseUrl
+	for (const [name, provider] of gatewayEntries) {
+		if (provider.baseUrl) {
+			checks.push(await checkProviderReachable(name, provider));
+		}
+	}
+
+	// Check 2: provider-auth-token-{name} — one per gateway provider with authTokenEnv
+	for (const [name, provider] of gatewayEntries) {
+		if (provider.authTokenEnv) {
+			checks.push(buildProviderAuthToken(name, provider));
+		}
+	}
+
+	// Check 3: tool-use-compat — one warn per tool-heavy role using a provider-prefixed model
+	checks.push(...buildToolUseCompat(config));
+
+	// Check 4: model-provider-ref(s) — one per provider-prefixed model, or single pass
+	checks.push(...buildModelProviderRefs(config));
+
+	// Check 5: gateway-api-key-reminder — only when gateway providers exist
+	if (gatewayEntries.length > 0) {
+		checks.push(buildGatewayApiKeyReminder());
+	}
+
+	return checks;
+};
+
+/**
+ * Base check: verifies at least one provider is configured.
+ */
+function buildProvidersConfigured(config: OverstoryConfig): DoctorCheck {
+	const entries = Object.entries(config.providers);
+
+	if (entries.length > 0) {
+		return {
+			name: "providers-configured",
+			category: "providers",
+			status: "pass",
+			message: `${entries.length} provider${entries.length === 1 ? "" : "s"} configured`,
+			details: entries.map(([name, p]) => `${name} (${p.type})`),
+		};
+	}
+
+	return {
+		name: "providers-configured",
+		category: "providers",
+		status: "warn",
+		message: "No providers configured — add providers to config.yaml",
+		details: ["At least one native or gateway provider should be configured."],
+	};
+}
+
+/**
+ * Check 1: HTTP reachability of a gateway provider's baseUrl.
+ *
+ * Uses fetch() with a 5-second timeout. Any HTTP response (any status code)
+ * counts as reachable — only network errors or timeouts produce a warn.
+ */
+async function checkProviderReachable(
+	name: string,
+	provider: ProviderConfig,
+): Promise<DoctorCheck> {
+	const baseUrl = provider.baseUrl as string; // caller guards baseUrl is defined
+
+	try {
+		await fetch(baseUrl, {
+			method: "HEAD",
+			signal: AbortSignal.timeout(5000),
+		});
+
+		return {
+			name: `provider-reachable-${name}`,
+			category: "providers",
+			status: "pass",
+			message: `Gateway provider '${name}' is reachable`,
+			details: [baseUrl],
+		};
+	} catch (error) {
+		const errorMsg = error instanceof Error ? error.message : String(error);
+		return {
+			name: `provider-reachable-${name}`,
+			category: "providers",
+			status: "warn",
+			message: `Gateway provider '${name}' is unreachable`,
+			details: [baseUrl, errorMsg],
+		};
+	}
+}
+
+/**
+ * Check 2: Validate that the auth token env var for a gateway provider is set.
+ *
+ * Reports the env var NAME in details — never the value.
+ */
+function buildProviderAuthToken(name: string, provider: ProviderConfig): DoctorCheck {
+	const envVar = provider.authTokenEnv as string; // caller guards authTokenEnv is defined
+	const value = process.env[envVar];
+
+	if (value && value.length > 0) {
+		return {
+			name: `provider-auth-token-${name}`,
+			category: "providers",
+			status: "pass",
+			message: `Auth token for provider '${name}' is set`,
+			details: [`Env var: ${envVar}`],
+		};
+	}
+
+	return {
+		name: `provider-auth-token-${name}`,
+		category: "providers",
+		status: "warn",
+		message: `Auth token for provider '${name}' is missing`,
+		details: [`Env var: ${envVar}`, `Set ${envVar} to authenticate with this provider.`],
+	};
+}
+
+/**
+ * Check 3: Tool-use compatibility for tool-heavy roles using non-Anthropic models.
+ *
+ * Tool-heavy roles (builder, scout, merger) rely on structured tool-use (function
+ * calling). Non-Anthropic models accessed via gateway providers may have different
+ * tool-use behavior. Emits one warn per affected role, or a single pass if none.
+ */
+function buildToolUseCompat(config: OverstoryConfig): DoctorCheck[] {
+	const checks: DoctorCheck[] = [];
+
+	for (const [role, model] of Object.entries(config.models)) {
+		if (!TOOL_HEAVY_ROLES.has(role)) continue;
+		if (model === undefined) continue;
+		if (!model.includes("/")) continue;
+
+		checks.push({
+			name: "tool-use-compat",
+			category: "providers",
+			status: "warn",
+			message: `models.${role} uses non-Anthropic model — tool-use compatibility not guaranteed`,
+			details: [
+				`Model: ${model}`,
+				"Tool use (function calling) behavior varies across providers.",
+				"Test agent behavior thoroughly before using in production.",
+			],
+		});
+	}
+
+	if (checks.length === 0) {
+		checks.push({
+			name: "tool-use-compat",
+			category: "providers",
+			status: "pass",
+			message: "No tool-heavy roles use non-Anthropic models",
+		});
+	}
+
+	return checks;
+}
+
+/**
+ * Check 4: Validate that provider-prefixed model references point to configured providers.
+ *
+ * For each config.models entry containing '/' (provider-qualified), extracts the
+ * provider name and verifies it exists in config.providers. Emits one check per
+ * provider-prefixed model, or a single pass if no such models exist.
+ */
+function buildModelProviderRefs(config: OverstoryConfig): DoctorCheck[] {
+	const checks: DoctorCheck[] = [];
+
+	for (const [role, model] of Object.entries(config.models)) {
+		if (model === undefined) continue;
+		if (!model.includes("/")) continue;
+
+		const providerName = model.split("/")[0];
+		if (!providerName) continue;
+
+		if (config.providers[providerName]) {
+			checks.push({
+				name: "model-provider-ref",
+				category: "providers",
+				status: "pass",
+				message: `models.${role} references defined provider '${providerName}'`,
+				details: [`Model: ${model}`],
+			});
+		} else {
+			checks.push({
+				name: "model-provider-ref",
+				category: "providers",
+				status: "fail",
+				message: `models.${role} references undefined provider '${providerName}'`,
+				details: [
+					`Model: ${model}`,
+					`Provider '${providerName}' is not defined in config.yaml providers section.`,
+					`Add it: providers:\n  ${providerName}:\n    type: gateway\n    baseUrl: https://...`,
+				],
+			});
+		}
+	}
+
+	if (checks.length === 0) {
+		checks.push({
+			name: "model-provider-refs",
+			category: "providers",
+			status: "pass",
+			message: "No provider-prefixed model references",
+		});
+	}
+
+	return checks;
+}
+
+/**
+ * Check 5: Reminder about ANTHROPIC_API_KEY when gateway providers are configured.
+ *
+ * Agents spawned via gateway routes receive ANTHROPIC_API_KEY="" so they use the
+ * gateway instead of Anthropic directly. Any direct Anthropic API calls (e.g.,
+ * from merge/resolver.ts) require a separate key.
+ */
+function buildGatewayApiKeyReminder(): DoctorCheck {
+	return {
+		name: "gateway-api-key-reminder",
+		category: "providers",
+		status: "warn",
+		message:
+			"Gateway providers configured — agents using gateway routes will have ANTHROPIC_API_KEY set to empty string. Direct Anthropic API calls require a separate key.",
+	};
+}

package/src/doctor/types.ts

@@ -13,7 +13,8 @@ export type DoctorCategory =
 	| "merge"
 	| "logs"
 	| "version"
-	| "ecosystem";
+	| "ecosystem"
+	| "providers";
 
 /** Result of a single doctor health check. */
 export interface DoctorCheck {

package/src/e2e/init-sling-lifecycle.test.ts

@@ -3,6 +3,7 @@ import { readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { createManifestLoader } from "../agents/manifest.ts";
 import { writeOverlay } from "../agents/overlay.ts";
+import type { Spawner } from "../commands/init.ts";
 import { initCommand } from "../commands/init.ts";
 import { loadConfig } from "../config.ts";
 import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
@@ -15,10 +16,14 @@ import type { OverlayConfig } from "../types.ts";
  * fresh temp git repo (NOT the overstory repo itself), then verifying all
  * artifacts, loading config + manifest via real APIs, and generating an overlay.
  *
- * Uses real filesystem and real git repos. No mocks.
+ * Uses real filesystem and real git repos.
+ * Uses a no-op spawner so ecosystem CLIs (ml/sd/cn) don't need to be installed in CI.
  * Suppresses stdout because initCommand prints status lines.
  */
 
+/** No-op spawner that treats all ecosystem tools as "not installed". */
+const noopSpawner: Spawner = async () => ({ exitCode: 1, stdout: "", stderr: "not found" });
+
 const EXPECTED_AGENT_DEFS = [
 	"builder.md",
 	"coordinator.md",
@@ -51,7 +56,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 	});
 
 	test("init creates all expected artifacts", async () => {
-		await initCommand({});
+		await initCommand({ _spawner: noopSpawner });
 
 		const overstoryDir = join(tempDir, ".overstory");
 
@@ -91,7 +96,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 	});
 
 	test("loadConfig returns valid config pointing to temp dir", async () => {
-		await initCommand({});
+		await initCommand({ _spawner: noopSpawner });
 
 		const config = await loadConfig(tempDir);
 
@@ -109,7 +114,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 	});
 
 	test("manifest loads successfully with all 7 agents (supervisor deprecated)", async () => {
-		await initCommand({});
+		await initCommand({ _spawner: noopSpawner });
 
 		const manifestPath = join(tempDir, ".overstory", "agent-manifest.json");
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");
@@ -143,7 +148,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 	});
 
 	test("manifest capability index is consistent", async () => {
-		await initCommand({});
+		await initCommand({ _spawner: noopSpawner });
 
 		const manifestPath = join(tempDir, ".overstory", "agent-manifest.json");
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");
@@ -165,7 +170,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 	});
 
 	test("overlay generation works for external project", async () => {
-		await initCommand({});
+		await initCommand({ _spawner: noopSpawner });
 
 		const agentDefsDir = join(tempDir, ".overstory", "agent-defs");
 		const baseDefinition = await Bun.file(join(agentDefsDir, "builder.md")).text();
@@ -213,7 +218,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 		// init → load config → load manifest → generate overlay
 
 		// Step 1: Init
-		await initCommand({});
+		await initCommand({ _spawner: noopSpawner });
 
 		// Step 2: Load config
 		const config = await loadConfig(tempDir);

package/src/index.ts

@@ -45,7 +45,7 @@ import { OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.7.4";
+export const VERSION = "0.7.6";
 
 const rawArgs = process.argv.slice(2);
 
@@ -228,10 +228,19 @@ program.addCommand(createCompletionsCommand());
 // Unmigrated commands — passthrough pattern
 program
 	.command("init")
-	.description("Initialize .overstory/ in current project")
+	.description("Initialize .overstory/ and bootstrap os-eco ecosystem tools")
 	.option("--force", "Reinitialize even if .overstory/ already exists")
 	.option("-y, --yes", "Accept all defaults without prompting (non-interactive mode)")
 	.option("--name <name>", "Project name (skips auto-detection)")
+	.option(
+		"--tools <list>",
+		"Comma-separated list of ecosystem tools to bootstrap (default: mulch,seeds,canopy)",
+	)
+	.option("--skip-mulch", "Skip mulch bootstrap")
+	.option("--skip-seeds", "Skip seeds bootstrap")
+	.option("--skip-canopy", "Skip canopy bootstrap")
+	.option("--skip-onboard", "Skip CLAUDE.md onboarding step for ecosystem tools")
+	.option("--json", "Output result as JSON")
 	.action(async (opts) => {
 		await initCommand(opts);
 	});

package/src/metrics/pricing.ts

@@ -26,8 +26,9 @@ export interface ModelPricing {
 	cacheCreationPerMTok: number;
 }
 
-/** Hardcoded pricing for known Claude models. */
+/** Pricing for known AI models across providers. */
 const MODEL_PRICING: Record<string, ModelPricing> = {
+	// --- Claude ---
 	opus: {
 		inputPerMTok: 15,
 		outputPerMTok: 75,
@@ -46,18 +47,72 @@ const MODEL_PRICING: Record<string, ModelPricing> = {
 		cacheReadPerMTok: 0.08, // 10% of input
 		cacheCreationPerMTok: 0.2, // 25% of input
 	},
+	// --- OpenAI GPT ---
+	"gpt-4o-mini": {
+		inputPerMTok: 0.15,
+		outputPerMTok: 0.6,
+		cacheReadPerMTok: 0.075, // 50% of input
+		cacheCreationPerMTok: 0.15,
+	},
+	"gpt-4o": {
+		inputPerMTok: 2.5,
+		outputPerMTok: 10,
+		cacheReadPerMTok: 1.25,
+		cacheCreationPerMTok: 2.5,
+	},
+	"gpt-5": {
+		inputPerMTok: 10,
+		outputPerMTok: 40,
+		cacheReadPerMTok: 5,
+		cacheCreationPerMTok: 10,
+	},
+	o1: {
+		inputPerMTok: 15,
+		outputPerMTok: 60,
+		cacheReadPerMTok: 7.5,
+		cacheCreationPerMTok: 15,
+	},
+	o3: {
+		inputPerMTok: 10,
+		outputPerMTok: 40,
+		cacheReadPerMTok: 5,
+		cacheCreationPerMTok: 10,
+	},
+	// --- Google Gemini ---
+	"gemini-flash": {
+		inputPerMTok: 0.1,
+		outputPerMTok: 0.4,
+		cacheReadPerMTok: 0.025,
+		cacheCreationPerMTok: 0.1,
+	},
+	"gemini-pro": {
+		inputPerMTok: 1.25,
+		outputPerMTok: 5,
+		cacheReadPerMTok: 0.3125,
+		cacheCreationPerMTok: 1.25,
+	},
 };
 
 /**
  * Determine the pricing tier for a given model string.
- * Matches on substring: "opus" -> opus pricing, "sonnet" -> sonnet, "haiku" -> haiku.
+ * Matches on substring in priority order to avoid ambiguous overlaps.
  * Returns null if unrecognized.
  */
 export function getPricingForModel(model: string): ModelPricing | null {
 	const lower = model.toLowerCase();
+	// --- Claude ---
 	if (lower.includes("opus")) return MODEL_PRICING.opus ?? null;
 	if (lower.includes("sonnet")) return MODEL_PRICING.sonnet ?? null;
 	if (lower.includes("haiku")) return MODEL_PRICING.haiku ?? null;
+	// --- OpenAI GPT --- (gpt-4o-mini before gpt-4o; o3 before o1)
+	if (lower.includes("gpt-4o-mini")) return MODEL_PRICING["gpt-4o-mini"] ?? null;
+	if (lower.includes("gpt-4o")) return MODEL_PRICING["gpt-4o"] ?? null;
+	if (lower.includes("gpt-5")) return MODEL_PRICING["gpt-5"] ?? null;
+	if (lower.includes("o3")) return MODEL_PRICING.o3 ?? null;
+	if (lower.includes("o1")) return MODEL_PRICING.o1 ?? null;
+	// --- Google Gemini --- (flash before generic gemini+pro check)
+	if (lower.includes("flash")) return MODEL_PRICING["gemini-flash"] ?? null;
+	if (lower.includes("gemini") && lower.includes("pro")) return MODEL_PRICING["gemini-pro"] ?? null;
 	return null;
 }
 

package/src/metrics/store.test.ts

@@ -224,6 +224,44 @@ describe("getSessionsByAgent", () => {
 	});
 });
 
+// === getSessionsByTask ===
+
+describe("getSessionsByTask", () => {
+	test("returns sessions matching task_id", () => {
+		store.recordSession(makeSession({ agentName: "agent-1", taskId: "task-A" }));
+		store.recordSession(makeSession({ agentName: "agent-2", taskId: "task-A" }));
+		store.recordSession(makeSession({ agentName: "agent-3", taskId: "task-B" }));
+
+		const sessions = store.getSessionsByTask("task-A");
+		expect(sessions).toHaveLength(2);
+		expect(sessions.every((s) => s.taskId === "task-A")).toBe(true);
+	});
+
+	test("returns empty array for unknown task_id", () => {
+		store.recordSession(makeSession({ agentName: "agent-1", taskId: "task-A" }));
+
+		expect(store.getSessionsByTask("nonexistent")).toEqual([]);
+	});
+
+	test("returns sessions ordered by started_at DESC", () => {
+		store.recordSession(
+			makeSession({ agentName: "agent-1", taskId: "task-X", startedAt: "2026-01-01T10:00:00Z" }),
+		);
+		store.recordSession(
+			makeSession({ agentName: "agent-2", taskId: "task-X", startedAt: "2026-01-01T12:00:00Z" }),
+		);
+		store.recordSession(
+			makeSession({ agentName: "agent-3", taskId: "task-X", startedAt: "2026-01-01T11:00:00Z" }),
+		);
+
+		const sessions = store.getSessionsByTask("task-X");
+		expect(sessions).toHaveLength(3);
+		expect(sessions[0]?.startedAt).toBe("2026-01-01T12:00:00Z"); // most recent first
+		expect(sessions[1]?.startedAt).toBe("2026-01-01T11:00:00Z");
+		expect(sessions[2]?.startedAt).toBe("2026-01-01T10:00:00Z");
+	});
+});
+
 // === getAverageDuration ===
 
 describe("getAverageDuration", () => {

package/src/metrics/store.ts

@@ -13,6 +13,7 @@ export interface MetricsStore {
 	getRecentSessions(limit?: number): SessionMetrics[];
 	getSessionsByAgent(agentName: string): SessionMetrics[];
 	getSessionsByRun(runId: string): SessionMetrics[];
+	getSessionsByTask(taskId: string): SessionMetrics[];
 	getAverageDuration(capability?: string): number;
 	/** Count the total number of sessions in the database (no limit cap). */
 	countSessions(): number;
@@ -250,6 +251,10 @@ export function createMetricsStore(dbPath: string): MetricsStore {
 		SELECT * FROM sessions WHERE run_id = $run_id ORDER BY started_at DESC
 	`);
 
+	const byTaskStmt = db.prepare<SessionRow, { $task_id: string }>(`
+		SELECT * FROM sessions WHERE task_id = $task_id ORDER BY started_at DESC
+	`);
+
 	const avgDurationAllStmt = db.prepare<{ avg_duration: number | null }, Record<string, never>>(`
 		SELECT AVG(duration_ms) AS avg_duration FROM sessions WHERE completed_at IS NOT NULL
 	`);
@@ -342,6 +347,11 @@ export function createMetricsStore(dbPath: string): MetricsStore {
 			return rows.map(rowToMetrics);
 		},
 
+		getSessionsByTask(taskId: string): SessionMetrics[] {
+			const rows = byTaskStmt.all({ $task_id: taskId });
+			return rows.map(rowToMetrics);
+		},
+
 		getAverageDuration(capability?: string): number {
 			if (capability !== undefined) {
 				const row = avgDurationByCapStmt.get({ $capability: capability });

package/src/metrics/transcript.test.ts

@@ -311,12 +311,38 @@ describe("estimateCost", () => {
 			outputTokens: 1_000_000,
 			cacheReadTokens: 0,
 			cacheCreationTokens: 0,
-			modelUsed: "gpt-4o",
+			modelUsed: "unknown-model-xyz",
 		});
 
 		expect(cost).toBeNull();
 	});
 
+	test("calculates cost for gpt-4o", () => {
+		const cost = estimateCost({
+			inputTokens: 1_000_000,
+			outputTokens: 1_000_000,
+			cacheReadTokens: 1_000_000,
+			cacheCreationTokens: 1_000_000,
+			modelUsed: "gpt-4o",
+		});
+
+		// gpt-4o: input=2.5, output=10, cacheRead=1.25, cacheCreation=2.5 => total=16.25
+		expect(cost).toBeCloseTo(16.25, 2);
+	});
+
+	test("calculates cost for gemini flash", () => {
+		const cost = estimateCost({
+			inputTokens: 1_000_000,
+			outputTokens: 1_000_000,
+			cacheReadTokens: 1_000_000,
+			cacheCreationTokens: 1_000_000,
+			modelUsed: "gemini-2.5-flash",
+		});
+
+		// gemini-flash: input=0.1, output=0.4, cacheRead=0.025, cacheCreation=0.1 => total=0.625
+		expect(cost).toBeCloseTo(0.625, 3);
+	});
+
 	test("returns null when modelUsed is null", () => {
 		const cost = estimateCost({
 			inputTokens: 1_000_000,
@@ -392,9 +418,65 @@ describe("getPricingForModel", () => {
 	});
 
 	test("returns null for unknown model", () => {
-		const pricing = getPricingForModel("gpt-4o");
+		const pricing = getPricingForModel("unknown-model-xyz");
 		expect(pricing).toBeNull();
 	});
+
+	test("matches gpt-4o", () => {
+		const pricing = getPricingForModel("gpt-4o");
+		expect(pricing).not.toBeNull();
+		if (pricing !== null) {
+			expect(pricing.inputPerMTok).toBe(2.5);
+		}
+	});
+
+	test("matches gpt-4o-mini", () => {
+		const pricing = getPricingForModel("gpt-4o-mini");
+		expect(pricing).not.toBeNull();
+		if (pricing !== null) {
+			expect(pricing.inputPerMTok).toBe(0.15);
+		}
+	});
+
+	test("matches gpt-5", () => {
+		const pricing = getPricingForModel("gpt-5");
+		expect(pricing).not.toBeNull();
+		if (pricing !== null) {
+			expect(pricing.inputPerMTok).toBe(10);
+		}
+	});
+
+	test("matches o1", () => {
+		const pricing = getPricingForModel("o1");
+		expect(pricing).not.toBeNull();
+		if (pricing !== null) {
+			expect(pricing.inputPerMTok).toBe(15);
+		}
+	});
+
+	test("matches o3", () => {
+		const pricing = getPricingForModel("o3");
+		expect(pricing).not.toBeNull();
+		if (pricing !== null) {
+			expect(pricing.inputPerMTok).toBe(10);
+		}
+	});
+
+	test("matches gemini flash", () => {
+		const pricing = getPricingForModel("gemini-2.5-flash");
+		expect(pricing).not.toBeNull();
+		if (pricing !== null) {
+			expect(pricing.inputPerMTok).toBe(0.1);
+		}
+	});
+
+	test("matches gemini pro", () => {
+		const pricing = getPricingForModel("gemini-2.5-pro");
+		expect(pricing).not.toBeNull();
+		if (pricing !== null) {
+			expect(pricing.inputPerMTok).toBe(1.25);
+		}
+	});
 });
 
 // === re-export parity ===

package/src/metrics/transcript.ts

@@ -3,7 +3,7 @@
  *
  * This is a Claude Code-specific JSONL parser that extracts token usage data
  * from assistant-type entries in transcript files at
- * ~/.claude/projects/{project-slug}/{session-id}.jsonl.
+ * the runtime-specific transcript directory (e.g. ~/.claude/projects/ for Claude Code).
  *
  * Runtime-agnostic pricing logic lives in ./pricing.ts. Other runtimes
  * implement their own transcript parsing via AgentRuntime.parseTranscript().

package/src/runtimes/claude.test.ts

@@ -73,6 +73,46 @@ describe("ClaudeRuntime", () => {
 			);
 		});
 
+		test("with appendSystemPromptFile uses $(cat ...) expansion", () => {
+			const opts: SpawnOpts = {
+				model: "opus",
+				permissionMode: "bypass",
+				cwd: "/project",
+				env: {},
+				appendSystemPromptFile: "/project/.overstory/agent-defs/coordinator.md",
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toBe(
+				`claude --model opus --permission-mode bypassPermissions --append-system-prompt "$(cat '/project/.overstory/agent-defs/coordinator.md')"`,
+			);
+		});
+
+		test("appendSystemPromptFile with single quotes in path", () => {
+			const opts: SpawnOpts = {
+				model: "opus",
+				permissionMode: "bypass",
+				cwd: "/project",
+				env: {},
+				appendSystemPromptFile: "/project/it's a path/agent.md",
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toContain("$(cat '/project/it'\\''s a path/agent.md')");
+		});
+
+		test("appendSystemPromptFile takes precedence over appendSystemPrompt", () => {
+			const opts: SpawnOpts = {
+				model: "opus",
+				permissionMode: "bypass",
+				cwd: "/project",
+				env: {},
+				appendSystemPromptFile: "/project/.overstory/agent-defs/coordinator.md",
+				appendSystemPrompt: "This inline content should be ignored",
+			};
+			const cmd = runtime.buildSpawnCommand(opts);
+			expect(cmd).toContain("$(cat ");
+			expect(cmd).not.toContain("This inline content should be ignored");
+		});
+
 		test("without appendSystemPrompt omits the flag", () => {
 			const opts: SpawnOpts = {
 				model: "haiku",