@os-eco/overstory-cli 0.6.11 → 0.7.0

package/README.md

@@ -75,7 +75,7 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 | Command | Description |
 |---------|-------------|
 | `ov init` | Initialize `.overstory/` in current project (`--yes`, `--name`) |
-| `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`, `--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`, `--runtime`, `--json`) |
 | `ov stop <agent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |
 | `ov prime` | Load context for orchestrator/agent (`--agent`, `--compact`) |
 | `ov spec write <task-id>` | Write a task specification (`--body`) |
@@ -250,12 +250,13 @@ overstory/
     mail/                         SQLite mail system (typed protocol, broadcast)
     merge/                        FIFO queue + conflict resolution
     watchdog/                     Tiered health monitoring (daemon, triage, health)
-    logging/                      Multi-format logger + sanitizer + reporter + color control
+    logging/                      Multi-format logger + sanitizer + reporter + color control + shared theme/format
     metrics/                      SQLite metrics + transcript parsing
     doctor/                       Health check modules (10 checks)
     insights/                     Session insight analyzer for auto-expertise
+    runtimes/                     AgentRuntime abstraction (registry + adapters)
     tracker/                      Pluggable task tracker (beads + seeds backends)
-    mulch/                        mulch CLI wrapper
+    mulch/                        mulch client (programmatic API + CLI wrapper)
     e2e/                          End-to-end lifecycle tests
   agents/                         Base agent definitions (.md, 8 roles) + skill definitions
   templates/                      Templates for overlays and hooks
@@ -265,12 +266,9 @@ overstory/
 
 Overstory is part of the [os-eco](https://github.com/jayminwest/os-eco) AI agent tooling ecosystem.
 
-```
-▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  overstory   orchestration
-▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  canopy      prompts
-▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  seeds       issues
-▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓  mulch       expertise
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jayminwest/os-eco/main/branding/logo.png" alt="os-eco" width="444" />
+</p>
 
 ## Contributing
 

package/agents/lead.md

@@ -1,6 +1,6 @@
 ## propulsion-principle
 
-Read your assignment. Assess complexity. For simple tasks, start implementing immediately. For moderate tasks, write a spec and spawn a builder. For complex tasks, spawn scouts and create issues. Do not ask for confirmation, do not propose a plan and wait for approval. Start working within your first tool calls.
+Read your assignment. Assess complexity. For simple tasks, start implementing immediately. For moderate tasks, write a spec and spawn a builder. For complex tasks, spawn scouts and mail the coordinator to create issues. Do not ask for confirmation, do not propose a plan and wait for approval. Start working within your first tool calls.
 
 ## dispatch-overrides
 
@@ -39,6 +39,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` before all subtasks are complete or accounted for, or without sending `merge_ready` to the coordinator.
 - **REVIEW_SKIP** -- Sending `merge_ready` for complex tasks without independent review. For complex multi-file changes, always spawn a reviewer. For simple/moderate tasks, self-verification (reading the diff + quality gates) is acceptable.
 - **MISSING_MULCH_RECORD** -- Closing without recording mulch learnings. Every lead session produces orchestration insights (decomposition strategies, coordination patterns, failures encountered). Skipping `ml record` loses knowledge for future agents.
+- **WORKTREE_ISSUE_CREATE** -- Running `{{TRACKER_CLI}} create` in a worktree. Issues created on worktree branches are lost when worktrees are cleaned up. Mail the coordinator to create issues on main instead.
 
 ## overlay
 
@@ -55,6 +56,7 @@ Your task-specific context (task ID, spec path, hierarchy depth, agent name, whe
 - **Never push to the canonical branch.** Commit to your worktree branch. Merging is handled by the coordinator.
 - **Do not spawn more workers than needed.** Start with the minimum. You can always spawn more later. Target 2-5 builders per lead.
 - **Review before merge for complex tasks.** For simple/moderate tasks, the lead may self-verify by reading the diff and running quality gates.
+- **Never create issues in worktrees.** Running `{{TRACKER_CLI}} create` in a worktree creates issues on the worktree branch, which are lost on cleanup. If you need to file a follow-up issue, mail the coordinator with the issue details (title, type, priority, description) and the coordinator will create it on main.
 
 ## communication-protocol
 
@@ -62,6 +64,9 @@ Your task-specific context (task ID, spec path, hierarchy depth, agent name, whe
 - **To your workers:** Send `status` messages with clarifications or answers to their questions.
 - **Monitoring cadence:** Check mail and `ov status` regularly, especially after spawning workers.
 - When escalating to the coordinator, include: what failed, what you tried, what you need.
+- **Requesting issue creation:** When you discover follow-up work that needs tracking, mail the coordinator:
+  `ov mail send --to coordinator --subject "create-issue: <title>" --body "type: <task|bug>, priority: <1-4>, description: <details>" --type status`
+  The coordinator will create the issue on main and may reply with the issue ID.
 
 ## intro
 
@@ -84,7 +89,7 @@ You are primarily a coordinator, but you can also be a doer for simple tasks. Yo
 - **Bash:**
   - `git add`, `git commit`, `git diff`, `git log`, `git status`
 {{QUALITY_GATE_CAPABILITIES}}
-  - `{{TRACKER_CLI}} create`, `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} update` (full {{TRACKER_NAME}} management)
+  - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} update` ({{TRACKER_NAME}} management — read, update, close)
   - `{{TRACKER_CLI}} sync` (sync {{TRACKER_NAME}} with git)
   - `ml prime`, `ml record`, `ml query`, `ml search` (expertise)
   - `ov sling` (spawn sub-workers)
@@ -164,8 +169,8 @@ Delegate exploration to scouts so you can focus on decomposition and planning.
 
    Single scout example:
    ```bash
-   {{TRACKER_CLI}} create --title="Scout: explore <area> for <objective>" --type=task --priority=2
-   ov sling <scout-bead-id> --capability scout --name <scout-name> \
+   ov sling <parent-task-id> --capability scout --name <scout-name> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ov mail send --to <scout-name> --subject "Explore: <area>" \
      --body "Investigate <what to explore>. Report: file layout, existing patterns, types, dependencies." \
@@ -175,16 +180,16 @@ Delegate exploration to scouts so you can focus on decomposition and planning.
    Parallel scouts example:
    ```bash
    # Scout 1: implementation files
-   {{TRACKER_CLI}} create --title="Scout: explore implementation for <objective>" --type=task --priority=2
-   ov sling <scout1-bead-id> --capability scout --name <scout1-name> \
+   ov sling <parent-task-id> --capability scout --name <scout1-name> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ov mail send --to <scout1-name> --subject "Explore: implementation" \
      --body "Investigate implementation files: <files>. Report: patterns, types, dependencies." \
      --type dispatch
 
    # Scout 2: tests and interfaces
-   {{TRACKER_CLI}} create --title="Scout: explore tests/types for <objective>" --type=task --priority=2
-   ov sling <scout2-bead-id> --capability scout --name <scout2-name> \
+   ov sling <parent-task-id> --capability scout --name <scout2-name> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ov mail send --to <scout2-name> --subject "Explore: tests and interfaces" \
      --body "Investigate test files and type definitions: <files>. Report: test patterns, type contracts." \
@@ -204,17 +209,14 @@ Write specs from scout findings and dispatch builders.
    - File scope (which files the builder owns -- non-overlapping)
    - Context (relevant types, interfaces, existing patterns from scout findings)
    - Dependencies (what must be true before this work starts)
-7. **Create {{TRACKER_NAME}} issues** for each subtask:
+7. **Spawn builders** for parallel tasks:
    ```bash
-   {{TRACKER_CLI}} create --title="<subtask title>" --priority=P1 --desc="<spec summary>"
-   ```
-8. **Spawn builders** for parallel tasks:
-   ```bash
-   ov sling <bead-id> --capability builder --name <builder-name> \
+   ov sling <parent-task-id> --capability builder --name <builder-name> \
      --spec .overstory/specs/<bead-id>.md --files <scoped-files> \
+     --skip-task-check \
      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
    ```
-9. **Send dispatch mail** to each builder:
+8. **Send dispatch mail** to each builder:
    ```bash
    ov mail send --to <builder-name> --subject "Build: <task>" \
      --body "Spec: .overstory/specs/<bead-id>.md. Begin immediately." --type dispatch
@@ -248,10 +250,9 @@ Review is a quality investment. For complex, multi-file changes, spawn a reviewe
 
     To spawn a reviewer:
     ```bash
-    {{TRACKER_CLI}} create --title="Review: <builder-task-summary>" --type=task --priority=P1
-    ov sling <review-bead-id> --capability reviewer --name review-<builder-name> \
-      --spec .overstory/specs/<builder-bead-id>.md --parent $OVERSTORY_AGENT_NAME \
-      --depth <current+1>
+    ov sling <parent-task-id> --capability reviewer --name review-<builder-name> \
+      --spec .overstory/specs/<builder-bead-id>.md --skip-task-check \
+      --parent $OVERSTORY_AGENT_NAME --depth <current+1>
     ov mail send --to review-<builder-name> \
       --subject "Review: <builder-task>" \
       --body "Review the changes on branch <builder-branch>. Spec: .overstory/specs/<builder-bead-id>.md. Run quality gates and report PASS or FAIL." \

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.11",
+	"version": "0.7.0",
 	"description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
 	"author": "Jaymin West",
 	"license": "MIT",
@@ -44,12 +44,14 @@
 		"version:bump": "bun scripts/version-bump.ts"
 	},
 	"dependencies": {
+		"@os-eco/mulch-cli": "^0.6.2",
 		"chalk": "^5.6.2",
 		"commander": "^14.0.3"
 	},
 	"devDependencies": {
+		"@biomejs/biome": "^2.3.15",
 		"@types/bun": "latest",
-		"typescript": "^5.9.0",
-		"@biomejs/biome": "^2.3.15"
+		"@types/js-yaml": "^4.0.9",
+		"typescript": "^5.9.0"
 	}
 }

package/src/agents/overlay.test.ts

@@ -736,6 +736,29 @@ describe("writeOverlay", () => {
 		const exists = await Bun.file(outputPath).exists();
 		expect(exists).toBe(true);
 	});
+
+	test("writes to custom instruction path when provided", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		const config = makeConfig();
+		await writeOverlay(worktreePath, config, "/nonexistent-canonical-root", "AGENTS.md");
+		const outputPath = join(worktreePath, "AGENTS.md");
+		expect(await Bun.file(outputPath).exists()).toBe(true);
+		expect(await Bun.file(join(worktreePath, ".claude", "CLAUDE.md")).exists()).toBe(false);
+	});
+
+	test("custom instruction path creates necessary subdirectories", async () => {
+		const worktreePath = join(tempDir, "worktree");
+		const config = makeConfig();
+		await writeOverlay(
+			worktreePath,
+			config,
+			"/nonexistent-canonical-root",
+			".pi/instructions/AGENT.md",
+		);
+		expect(await Bun.file(join(worktreePath, ".pi", "instructions", "AGENT.md")).exists()).toBe(
+			true,
+		);
+	});
 });
 
 describe("isCanonicalRoot", () => {

package/src/agents/overlay.ts

@@ -369,6 +369,7 @@ export async function writeOverlay(
 	worktreePath: string,
 	config: OverlayConfig,
 	canonicalRoot: string,
+	instructionPath = ".claude/CLAUDE.md",
 ): Promise<void> {
 	// Guard: never write agent overlays to the canonical project root.
 	// The project root's .claude/CLAUDE.md belongs to the orchestrator/user.
@@ -383,13 +384,13 @@ export async function writeOverlay(
 	}
 
 	const content = await generateOverlay(config);
-	const claudeDir = join(worktreePath, ".claude");
-	const outputPath = join(claudeDir, "CLAUDE.md");
+	const outputPath = join(worktreePath, instructionPath);
+	const outputDir = dirname(outputPath);
 
 	try {
-		await mkdir(claudeDir, { recursive: true });
+		await mkdir(outputDir, { recursive: true });
 	} catch (err) {
-		throw new AgentError(`Failed to create .claude/ directory at: ${claudeDir}`, {
+		throw new AgentError(`Failed to create directory for instruction file at: ${outputDir}`, {
 			agentName: config.agentName,
 			cause: err instanceof Error ? err : undefined,
 		});

package/src/commands/coordinator.ts

@@ -22,6 +22,7 @@ import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess, printWarning } from "../logging/color.ts";
+import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
 import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
@@ -62,6 +63,7 @@ export interface CoordinatorDeps {
 		sendKeys: (name: string, keys: string) => Promise<void>;
 		waitForTuiReady: (
 			name: string,
+			detectReady: (paneContent: string) => import("../runtimes/types.ts").ReadyState,
 			timeoutMs?: number,
 			pollIntervalMs?: number,
 		) => Promise<boolean>;
@@ -347,7 +349,8 @@ async function startCoordinator(
 			join(projectRoot, config.agents.baseDir),
 		);
 		const manifest = await manifestLoader.load();
-		const { model, env } = resolveModel(config, manifest, "coordinator", "opus");
+		const resolvedModel = resolveModel(config, manifest, "coordinator", "opus");
+		const runtime = getRuntime(undefined, config);
 
 		// Preflight: verify tmux is installed before attempting to spawn.
 		// Without this check, a missing tmux leads to cryptic errors later.
@@ -359,15 +362,22 @@ async function startCoordinator(
 		// (overstory-gaio, overstory-0kwf).
 		const agentDefPath = join(projectRoot, ".overstory", "agent-defs", "coordinator.md");
 		const agentDefFile = Bun.file(agentDefPath);
-		let claudeCmd = `claude --model ${model} --permission-mode bypassPermissions`;
+		let appendSystemPrompt: string | undefined;
 		if (await agentDefFile.exists()) {
-			const agentDef = await agentDefFile.text();
-			// Single-quote the content for safe shell expansion (only escape single quotes)
-			const escaped = agentDef.replace(/'/g, "'\\''");
-			claudeCmd += ` --append-system-prompt '${escaped}'`;
+			appendSystemPrompt = await agentDefFile.text();
 		}
-		const pid = await tmux.createSession(tmuxSession, projectRoot, claudeCmd, {
-			...env,
+		const spawnCmd = runtime.buildSpawnCommand({
+			model: resolvedModel.model,
+			permissionMode: "bypass",
+			cwd: projectRoot,
+			appendSystemPrompt,
+			env: {
+				...runtime.buildEnv(resolvedModel),
+				OVERSTORY_AGENT_NAME: COORDINATOR_NAME,
+			},
+		});
+		const pid = await tmux.createSession(tmuxSession, projectRoot, spawnCmd, {
+			...runtime.buildEnv(resolvedModel),
 			OVERSTORY_AGENT_NAME: COORDINATOR_NAME,
 		});
 
@@ -397,7 +407,9 @@ async function startCoordinator(
 		store.upsert(session);
 
 		// Wait for Claude Code TUI to render before sending input
-		const tuiReady = await tmux.waitForTuiReady(tmuxSession);
+		const tuiReady = await tmux.waitForTuiReady(tmuxSession, (content) =>
+			runtime.detectReady(content),
+		);
 		if (!tuiReady) {
 			// Session may have died — check liveness before proceeding
 			const alive = await tmux.isSessionAlive(tmuxSession);

package/src/commands/costs.test.ts

@@ -303,7 +303,7 @@ describe("costsCommand", () => {
 			await costsCommand([]);
 			const out = output();
 
-			expect(out).toContain("=".repeat(70));
+			expect(out).toContain("\u2500".repeat(70));
 		});
 
 		test("shows Total row", async () => {

package/src/commands/costs.ts

@@ -13,6 +13,7 @@ import { loadConfig } from "../config.ts";
 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 { createMetricsStore } from "../metrics/store.ts";
 import { estimateCost, parseTranscriptUsage } from "../metrics/transcript.ts";
 import { openSessionStore } from "../sessions/compat.ts";
@@ -141,10 +142,8 @@ function groupByCapability(sessions: SessionMetrics[]): CapabilityGroup[] {
 /** Print the standard per-agent cost summary table. */
 function printCostSummary(sessions: SessionMetrics[]): void {
 	const w = process.stdout.write.bind(process.stdout);
-	const separator = "\u2500".repeat(70);
 
-	w(`${color.bold("Cost Summary")}\n`);
-	w(`${"=".repeat(70)}\n`);
+	w(`${renderHeader("Cost Summary")}\n`);
 
 	if (sessions.length === 0) {
 		w(`${color.dim("No session data found.")}\n`);
@@ -156,7 +155,7 @@ function printCostSummary(sessions: SessionMetrics[]): void {
 			`${padLeft("Input", 10)}${padLeft("Output", 10)}` +
 			`${padLeft("Cache", 10)}${padLeft("Cost", 10)}\n`,
 	);
-	w(`${color.dim(separator)}\n`);
+	w(`${color.dim(separator())}\n`);
 
 	for (const s of sessions) {
 		const cacheTotal = s.cacheReadTokens + s.cacheCreationTokens;
@@ -170,7 +169,7 @@ function printCostSummary(sessions: SessionMetrics[]): void {
 	}
 
 	const totals = computeTotals(sessions);
-	w(`${color.dim(separator)}\n`);
+	w(`${color.dim(separator())}\n`);
 	w(
 		`${color.green(
 			color.bold(
@@ -187,10 +186,8 @@ function printCostSummary(sessions: SessionMetrics[]): void {
 /** Print the capability-grouped cost table. */
 function printByCapability(sessions: SessionMetrics[]): void {
 	const w = process.stdout.write.bind(process.stdout);
-	const separator = "\u2500".repeat(70);
 
-	w(`${color.bold("Cost by Capability")}\n`);
-	w(`${"=".repeat(70)}\n`);
+	w(`${renderHeader("Cost by Capability")}\n`);
 
 	if (sessions.length === 0) {
 		w(`${color.dim("No session data found.")}\n`);
@@ -202,7 +199,7 @@ function printByCapability(sessions: SessionMetrics[]): void {
 			`${padLeft("Input", 10)}${padLeft("Output", 10)}` +
 			`${padLeft("Cache", 10)}${padLeft("Cost", 10)}\n`,
 	);
-	w(`${color.dim(separator)}\n`);
+	w(`${color.dim(separator())}\n`);
 
 	const groups = groupByCapability(sessions);
 
@@ -218,7 +215,7 @@ function printByCapability(sessions: SessionMetrics[]): void {
 	}
 
 	const totals = computeTotals(sessions);
-	w(`${color.dim(separator)}\n`);
+	w(`${color.dim(separator())}\n`);
 	w(
 		`${color.green(
 			color.bold(
@@ -299,17 +296,15 @@ async function executeCosts(opts: CostsOpts): Promise<void> {
 			});
 		} else {
 			const w = process.stdout.write.bind(process.stdout);
-			const separator = "\u2500".repeat(70);
 
-			w(`${color.bold("Orchestrator Session Cost")}\n`);
-			w(`${"=".repeat(70)}\n`);
+			w(`${renderHeader("Orchestrator Session Cost")}\n`);
 			w(`${padRight("Model:", 12)}${usage.modelUsed ?? "unknown"}\n`);
 			w(`${padRight("Transcript:", 12)}${transcriptPath}\n`);
-			w(`${color.dim(separator)}\n`);
+			w(`${color.dim(separator())}\n`);
 			w(`${padRight("Input tokens:", 22)}${padLeft(formatNumber(usage.inputTokens), 12)}\n`);
 			w(`${padRight("Output tokens:", 22)}${padLeft(formatNumber(usage.outputTokens), 12)}\n`);
 			w(`${padRight("Cache tokens:", 22)}${padLeft(formatNumber(cacheTotal), 12)}\n`);
-			w(`${color.dim(separator)}\n`);
+			w(`${color.dim(separator())}\n`);
 			w(
 				`${color.green(color.bold(padRight("Estimated cost:", 22) + padLeft(formatCost(cost), 12)))}\n`,
 			);
@@ -453,16 +448,14 @@ async function executeCosts(opts: CostsOpts): Promise<void> {
 				});
 			} else {
 				const w = process.stdout.write.bind(process.stdout);
-				const separator = "\u2500".repeat(70);
 
-				w(`${color.bold(`Live Token Usage (${agentData.length} active agents)`)}\n`);
-				w(`${"=".repeat(70)}\n`);
+				w(`${renderHeader(`Live Token Usage (${agentData.length} active agents)`)}\n`);
 				w(
 					`${padRight("Agent", 19)}${padRight("Capability", 12)}` +
 						`${padLeft("Input", 10)}${padLeft("Output", 10)}` +
 						`${padLeft("Cache", 10)}${padLeft("Cost", 10)}\n`,
 				);
-				w(`${color.dim(separator)}\n`);
+				w(`${color.dim(separator())}\n`);
 
 				for (const agent of agentData) {
 					const cacheTotal = agent.cacheReadTokens + agent.cacheCreationTokens;
@@ -475,7 +468,7 @@ async function executeCosts(opts: CostsOpts): Promise<void> {
 					);
 				}
 
-				w(`${color.dim(separator)}\n`);
+				w(`${color.dim(separator())}\n`);
 				w(
 					`${color.green(
 						color.bold(