@os-eco/overstory-cli 0.7.4 → 0.7.6

package/README.md

@@ -6,7 +6,7 @@ Multi-agent orchestration for AI coding agents.
 [![CI](https://github.com/jayminwest/overstory/actions/workflows/ci.yml/badge.svg)](https://github.com/jayminwest/overstory/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Overstory turns a single coding session into a multi-agent team by spawning worker agents in git worktrees via tmux, coordinating them through a custom SQLite mail system, and merging their work back with tiered conflict resolution. A pluggable `AgentRuntime` interface lets you swap between runtimes — Claude Code, [Pi](https://github.com/nichochar/pi-coding-agent), or your own adapter.
+Overstory turns a single coding session into a multi-agent team by spawning worker agents in git worktrees via tmux, coordinating them through a custom SQLite mail system, and merging their work back with tiered conflict resolution. A pluggable `AgentRuntime` interface lets you swap between runtimes — Claude Code, [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent), or your own adapter.
 
 > **Warning: Agent swarms are not a universal solution.** Do not deploy Overstory without understanding the risks of multi-agent orchestration — compounding error rates, cost amplification, debugging complexity, and merge conflicts are the normal case, not edge cases. Read [STEELMAN.md](STEELMAN.md) for a full risk analysis and the [Agentic Engineering Book](https://github.com/jayminwest/agentic-engineering-book) ([web version](https://jayminwest.com/agentic-engineering-book)) before using this tool in production.
 
@@ -15,7 +15,8 @@ Overstory turns a single coding session into a multi-agent team by spawning work
 Requires [Bun](https://bun.sh) v1.0+, git, and tmux. At least one supported agent runtime must be installed:
 
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude` CLI)
-- [Pi](https://github.com/nichochar/pi-coding-agent) (`pi` CLI)
+- [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) (`pi` CLI)
+- [GitHub Copilot](https://github.com/features/copilot) (`copilot` CLI)
 
 ```bash
 bun install -g @os-eco/overstory-cli
@@ -77,7 +78,7 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 
 | Command | Description |
 |---------|-------------|
-| `ov init` | Initialize `.overstory/` in current project (`--yes`, `--name`) |
+| `ov init` | Initialize `.overstory/` and bootstrap os-eco tools (`--yes`, `--name`, `--tools`, `--skip-mulch`, `--skip-seeds`, `--skip-canopy`, `--skip-onboard`, `--json`) |
 | `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--json`) |
 | `ov stop <agent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |
 | `ov prime` | Load context for orchestrator/agent (`--agent`, `--compact`) |
@@ -132,7 +133,7 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 | `ov replay` | Interleaved chronological replay (`--run`, `--agent`, `--since`, `--until`, `--limit`, `--json`) |
 | `ov feed` | Unified real-time event stream (`--follow`, `--interval`, `--agent`, `--run`, `--json`) |
 | `ov logs` | Query NDJSON logs across agents (`--agent`, `--level`, `--since`, `--until`, `--follow`, `--json`) |
-| `ov costs` | Token/cost analysis and breakdown (`--live`, `--self`, `--agent`, `--run`, `--by-capability`, `--last`, `--json`) |
+| `ov costs` | Token/cost analysis and breakdown (`--live`, `--self`, `--agent`, `--run`, `--bead`, `--by-capability`, `--last`, `--json`) |
 | `ov metrics` | Show session metrics (`--last`, `--json`) |
 | `ov run list` | List orchestration runs (`--last`, `--json`) |
 | `ov run show <id>` | Show run details |
@@ -153,7 +154,7 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 | `ov monitor status` | Show monitor state |
 | `ov log <event>` | Log a hook event (`--agent`) |
 | `ov clean` | Clean up worktrees, sessions, artifacts (`--completed`, `--all`, `--run`) |
-| `ov doctor` | Run health checks on overstory setup (`--category`, `--fix`, `--json`) |
+| `ov doctor` | Run health checks on overstory setup — 11 categories (`--category`, `--fix`, `--json`) |
 | `ov ecosystem` | Show os-eco tool versions and health (`--json`) |
 | `ov upgrade` | Upgrade overstory to latest npm version (`--check`, `--all`, `--json`) |
 | `ov agents discover` | Discover agents by capability/state/parent (`--capability`, `--state`, `--parent`, `--json`) |
@@ -171,6 +172,7 @@ Overstory is runtime-agnostic. The `AgentRuntime` interface (`src/runtimes/types
 |---------|-----|-----------------|--------|
 | Claude Code | `claude` | `settings.local.json` hooks | Stable |
 | Pi | `pi` | `.pi/extensions/` guard extension | Active development |
+| Copilot | `copilot` | (none — `--allow-all-tools`) | Active development |
 
 ## How It Works
 
@@ -240,7 +242,7 @@ overstory/
       run.ts                      Orchestration run lifecycle
       trace.ts                    Agent/task timeline viewing
       clean.ts                    Worktree/session cleanup
-      doctor.ts                   Health check runner (10 check modules)
+      doctor.ts                   Health check runner (11 check modules)
       inspect.ts                  Deep per-agent inspection
       spec.ts                     Task spec management
       errors.ts                   Aggregated error view
@@ -265,9 +267,9 @@ overstory/
     watchdog/                     Tiered health monitoring (daemon, triage, health)
     logging/                      Multi-format logger + sanitizer + reporter + color control + shared theme/format
     metrics/                      SQLite metrics + pricing + transcript parsing
-    doctor/                       Health check modules (10 checks)
+    doctor/                       Health check modules (11 checks)
     insights/                     Session insight analyzer for auto-expertise
-    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi)
+    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot)
     tracker/                      Pluggable task tracker (beads + seeds backends)
     mulch/                        mulch client (programmatic API + CLI wrapper)
     e2e/                          End-to-end lifecycle tests

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.7.4",
+	"version": "0.7.6",
 	"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,6 +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 { openSessionStore } from "../sessions/compat.ts";
 import { type AgentSession, SUPPORTED_CAPABILITIES } from "../types.ts";
 
@@ -41,12 +42,19 @@ const KNOWN_INSTRUCTION_PATHS = [
  * or can't be read.
  *
  * @param worktreePath - Absolute path to the agent's worktree
+ * @param runtimeInstructionPath - Optional runtime-specific instruction path to try first
  * @returns Array of file paths (relative to worktree root)
  */
-export async function extractFileScope(worktreePath: string): Promise<string[]> {
+export async function extractFileScope(
+	worktreePath: string,
+	runtimeInstructionPath?: string,
+): Promise<string[]> {
 	try {
 		let content: string | null = null;
-		for (const relPath of KNOWN_INSTRUCTION_PATHS) {
+		const pathsToTry = runtimeInstructionPath
+			? [runtimeInstructionPath, ...KNOWN_INSTRUCTION_PATHS]
+			: KNOWN_INSTRUCTION_PATHS;
+		for (const relPath of pathsToTry) {
 			const overlayPath = join(worktreePath, relPath);
 			const overlayFile = Bun.file(overlayPath);
 			if (await overlayFile.exists()) {
@@ -112,6 +120,16 @@ export async function discoverAgents(
 	const overstoryDir = join(root, ".overstory");
 	const { store } = openSessionStore(overstoryDir);
 
+	// Resolve runtime instruction path from config; fall back gracefully if config is absent.
+	let runtimeInstructionPath: string | undefined;
+	try {
+		const config = await loadConfig(root);
+		const runtime = getRuntime(undefined, config);
+		runtimeInstructionPath = runtime.instructionPath;
+	} catch {
+		// Config may not exist in all contexts; KNOWN_INSTRUCTION_PATHS will be used as fallback.
+	}
+
 	try {
 		const sessions: AgentSession[] = opts?.includeAll ? store.getAll() : store.getActive();
 
@@ -124,7 +142,7 @@ export async function discoverAgents(
 		// Extract file scopes for each agent
 		const agents: DiscoveredAgent[] = await Promise.all(
 			filteredSessions.map(async (session) => {
-				const fileScope = await extractFileScope(session.worktreePath);
+				const fileScope = await extractFileScope(session.worktreePath, runtimeInstructionPath);
 				return {
 					agentName: session.agentName,
 					capability: session.capability,

package/src/commands/completions.ts

@@ -55,12 +55,18 @@ export const COMMANDS: readonly CommandDef[] = [
 	},
 	{
 		name: "init",
-		desc: "Initialize .overstory/ in current project",
+		desc: "Initialize .overstory/ and bootstrap os-eco ecosystem tools",
 		flags: [
 			{ name: "--force", desc: "Overwrite existing configuration" },
 			{ name: "--yes", desc: "Accept all defaults without prompting" },
 			{ name: "-y", desc: "Alias for --yes" },
 			{ name: "--name", desc: "Project name", takesValue: true },
+			{ name: "--tools", desc: "Comma-separated list of tools to bootstrap", takesValue: true },
+			{ name: "--skip-mulch", desc: "Skip mulch bootstrap" },
+			{ name: "--skip-seeds", desc: "Skip seeds bootstrap" },
+			{ name: "--skip-canopy", desc: "Skip canopy bootstrap" },
+			{ name: "--skip-onboard", desc: "Skip CLAUDE.md onboarding step" },
+			{ name: "--json", desc: "Output result as JSON" },
 			{ name: "--help", desc: "Show help" },
 		],
 	},

package/src/commands/coordinator.test.ts

@@ -540,7 +540,9 @@ describe("startCoordinator", () => {
 		expect(calls.createSession).toHaveLength(1);
 		const cmd = calls.createSession[0]?.command ?? "";
 		expect(cmd).toContain("--append-system-prompt");
-		expect(cmd).toContain("# Coordinator Agent");
+		// File path is passed via $(cat ...) instead of inlining content (overstory#45)
+		expect(cmd).toContain("$(cat '");
+		expect(cmd).toContain("agent-defs/coordinator.md");
 	});
 
 	test("reads model from manifest instead of hardcoding", async () => {

package/src/commands/coordinator.ts

@@ -363,17 +363,20 @@ async function startCoordinator(
 		// Inject the coordinator base definition via --append-system-prompt so the
 		// coordinator knows its role, hierarchy rules, and delegation patterns
 		// (overstory-gaio, overstory-0kwf).
+		// Pass the file path (not content) so the shell inside the tmux pane reads
+		// it via $(cat ...) — avoids tmux IPC "command too long" errors with large
+		// agent definitions (overstory#45).
 		const agentDefPath = join(projectRoot, ".overstory", "agent-defs", "coordinator.md");
 		const agentDefFile = Bun.file(agentDefPath);
-		let appendSystemPrompt: string | undefined;
+		let appendSystemPromptFile: string | undefined;
 		if (await agentDefFile.exists()) {
-			appendSystemPrompt = await agentDefFile.text();
+			appendSystemPromptFile = agentDefPath;
 		}
 		const spawnCmd = runtime.buildSpawnCommand({
 			model: resolvedModel.model,
 			permissionMode: "bypass",
 			cwd: projectRoot,
-			appendSystemPrompt,
+			appendSystemPromptFile,
 			env: {
 				...runtime.buildEnv(resolvedModel),
 				OVERSTORY_AGENT_NAME: COORDINATOR_NAME,

package/src/commands/costs.test.ts

@@ -1023,6 +1023,48 @@ describe("costsCommand", () => {
 		});
 	});
 
+	// === --bead filter ===
+
+	describe("--bead filter", () => {
+		test("--bead filters by task ID (JSON)", async () => {
+			const dbPath = join(tempDir, ".overstory", "metrics.db");
+			const store = createMetricsStore(dbPath);
+			store.recordSession(makeMetrics({ agentName: "builder-1", taskId: "task-A" }));
+			store.recordSession(makeMetrics({ agentName: "builder-2", taskId: "task-A" }));
+			store.recordSession(
+				makeMetrics({ agentName: "scout-1", taskId: "task-B", capability: "scout" }),
+			);
+			store.close();
+
+			await costsCommand(["--json", "--bead", "task-A"]);
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as { sessions: Record<string, unknown>[] };
+			expect(parsed.sessions).toHaveLength(2);
+			expect(parsed.sessions.every((s) => s.taskId === "task-A")).toBe(true);
+		});
+
+		test("--bead returns empty for unknown task", async () => {
+			const dbPath = join(tempDir, ".overstory", "metrics.db");
+			const store = createMetricsStore(dbPath);
+			store.recordSession(makeMetrics({ agentName: "builder-1", taskId: "task-A" }));
+			store.close();
+
+			await costsCommand(["--json", "--bead", "nonexistent"]);
+			const out = output();
+
+			const parsed = JSON.parse(out.trim()) as { sessions: unknown[] };
+			expect(parsed.sessions).toEqual([]);
+		});
+
+		test("--bead appears in help text", async () => {
+			await costsCommand(["--help"]);
+			const out = output();
+
+			expect(out).toContain("--bead");
+		});
+	});
+
 	// === --self flag ===
 
 	describe("--self flag", () => {
@@ -1111,7 +1153,7 @@ describe("costsCommand", () => {
 			await costsCommand(["--self"]);
 			const out = output();
 
-			expect(out).toContain("No orchestrator transcript found");
+			expect(out).toContain("No transcript found");
 		});
 
 		test("--self --json outputs error JSON when no transcript found", async () => {
@@ -1122,7 +1164,8 @@ describe("costsCommand", () => {
 			const out = output();
 
 			const parsed = JSON.parse(out.trim()) as Record<string, unknown>;
-			expect(parsed.error).toBe("No orchestrator transcript found");
+			expect(typeof parsed.error).toBe("string");
+			expect(parsed.error as string).toContain("No transcript found");
 		});
 
 		test("--self in help text", async () => {

package/src/commands/costs.ts

@@ -16,6 +16,7 @@ import { color } from "../logging/color.ts";
 import { renderHeader, separator } from "../logging/theme.ts";
 import { createMetricsStore } from "../metrics/store.ts";
 import { estimateCost, parseTranscriptUsage } from "../metrics/transcript.ts";
+import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { SessionMetrics } from "../types.ts";
 
@@ -43,24 +44,45 @@ function padLeft(str: string, width: number): string {
 }
 
 /**
- * Discover the orchestrator's Claude Code transcript JSONL file.
- *
- * Scans ~/.claude/projects/{project-key}/ for JSONL files and returns
- * the most recently modified one, corresponding to the current orchestrator session.
+ * 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 most recent transcript, or null if none found
+ * @returns Absolute path to the transcript directory, or null if not supported
  */
-async function discoverOrchestratorTranscript(projectRoot: string): Promise<string | null> {
+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;
+	}
+}
 
-	const projectKey = projectRoot.replace(/\//g, "-");
-	const projectDir = join(homeDir, ".claude", "projects", projectKey);
+/**
+ * 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 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,
+	projectRoot: string,
+): Promise<string | null> {
+	const transcriptDir = getTranscriptDir(runtimeId, projectRoot);
+	if (transcriptDir === null) return null;
 
 	let entries: string[];
 	try {
-		entries = await readdir(projectDir);
+		entries = await readdir(transcriptDir);
 	} catch {
 		return null;
 	}
@@ -72,7 +94,7 @@ async function discoverOrchestratorTranscript(projectRoot: string): Promise<stri
 	let bestMtime = 0;
 
 	for (const file of jsonlFiles) {
-		const filePath = join(projectDir, file);
+		const filePath = join(transcriptDir, file);
 		try {
 			const fileStat = await stat(filePath);
 			if (fileStat.mtimeMs > bestMtime) {
@@ -236,6 +258,7 @@ interface CostsOpts {
 	byCapability?: boolean;
 	agent?: string;
 	run?: string;
+	bead?: string;
 	last?: string;
 	json?: boolean;
 }
@@ -247,6 +270,7 @@ async function executeCosts(opts: CostsOpts): Promise<void> {
 	const byCapability = opts.byCapability ?? false;
 	const agentName = opts.agent;
 	const runId = opts.run;
+	const beadId = opts.bead;
 	const lastStr = opts.last;
 
 	if (lastStr !== undefined) {
@@ -267,13 +291,15 @@ async function executeCosts(opts: CostsOpts): Promise<void> {
 
 	// Handle --self flag (early return for self-scan)
 	if (self) {
-		const transcriptPath = await discoverOrchestratorTranscript(config.project.root);
+		const runtime = getRuntime(undefined, config);
+		const transcriptPath = await discoverOrchestratorTranscript(runtime.id, config.project.root);
 		if (!transcriptPath) {
 			if (json) {
-				jsonError("costs", "No orchestrator transcript found");
+				jsonError("costs", `No transcript found for runtime '${runtime.id}'`);
 			} else {
 				process.stdout.write(
-					"No orchestrator transcript found.\nExpected at: ~/.claude/projects/{project-key}/*.jsonl\n",
+					`No transcript found for runtime '${runtime.id}'.\n` +
+						"Transcript discovery may not be supported for this runtime.\n",
 				);
 			}
 			return;
@@ -521,6 +547,8 @@ async function executeCosts(opts: CostsOpts): Promise<void> {
 			sessions = metricsStore.getSessionsByAgent(agentName);
 		} else if (runId !== undefined) {
 			sessions = metricsStore.getSessionsByRun(runId);
+		} else if (beadId !== undefined) {
+			sessions = metricsStore.getSessionsByTask(beadId);
 		} else {
 			sessions = metricsStore.getRecentSessions(last);
 		}
@@ -559,6 +587,7 @@ export function createCostsCommand(): Command {
 		.option("--self", "Show cost for the current orchestrator session")
 		.option("--agent <name>", "Filter by agent name")
 		.option("--run <id>", "Filter by run ID")
+		.option("--bead <id>", "Show cost breakdown for a specific task/bead")
 		.option("--by-capability", "Group results by capability with subtotals")
 		.option("--last <n>", "Number of recent sessions (default: 20)")
 		.option("--json", "Output as JSON")

package/src/commands/doctor.ts

@@ -15,6 +15,7 @@ import { checkDependencies } from "../doctor/dependencies.ts";
 import { checkEcosystem } from "../doctor/ecosystem.ts";
 import { checkLogs } from "../doctor/logs.ts";
 import { checkMergeQueue } from "../doctor/merge-queue.ts";
+import { checkProviders } from "../doctor/providers.ts";
 import { checkStructure } from "../doctor/structure.ts";
 import type { DoctorCategory, DoctorCheck, DoctorCheckFn } from "../doctor/types.ts";
 import { checkVersion } from "../doctor/version.ts";
@@ -35,6 +36,7 @@ const ALL_CHECKS: Array<{ category: DoctorCategory; fn: DoctorCheckFn }> = [
 	{ category: "logs", fn: checkLogs },
 	{ category: "version", fn: checkVersion },
 	{ category: "ecosystem", fn: checkEcosystem },
+	{ category: "providers", fn: checkProviders },
 ];
 
 /**
@@ -166,7 +168,7 @@ export function createDoctorCommand(options?: DoctorCommandOptions): Command {
 		.option("--fix", "Attempt to auto-fix issues")
 		.addHelpText(
 			"after",
-			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem",
+			"\nCategories: dependencies, structure, config, databases, consistency, agents, merge, logs, version, ecosystem, providers",
 		)
 		.action(
 			async (opts: { json?: boolean; verbose?: boolean; category?: string; fix?: boolean }) => {