@os-eco/overstory-cli 0.7.2 → 0.7.4

package/README.md

@@ -1,18 +1,21 @@
 # Overstory
 
-Multi-agent orchestration for Claude Code.
+Multi-agent orchestration for AI coding agents.
 
 [![npm](https://img.shields.io/npm/v/@os-eco/overstory-cli)](https://www.npmjs.com/package/@os-eco/overstory-cli)
 [![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 Claude Code 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.
+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.
 
 > **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.
 
 ## Install
 
-Requires [Bun](https://bun.sh) v1.0+, [Claude Code](https://docs.anthropic.com/en/docs/claude-code), git, and tmux.
+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)
 
 ```bash
 bun install -g @os-eco/overstory-cli
@@ -75,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 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 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`) |
 | `ov spec write <task-id>` | Write a task specification (`--body`) |
@@ -158,11 +161,20 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 
 ## Architecture
 
-Overstory uses CLAUDE.md overlays and PreToolUse hooks to turn Claude Code sessions into orchestrated agents. Each agent runs in an isolated git worktree via tmux. Inter-agent messaging is handled by a custom SQLite mail system (WAL mode, ~1-5ms per query) with typed protocol messages and broadcast support. A FIFO merge queue with 4-tier conflict resolution merges agent branches back to canonical. A tiered watchdog system (Tier 0 mechanical daemon, Tier 1 AI-assisted triage, Tier 2 monitor agent) ensures fleet health. See [CLAUDE.md](CLAUDE.md) for full technical details.
+Overstory uses instruction overlays and tool-call guards to turn agent sessions into orchestrated workers. Each agent runs in an isolated git worktree via tmux. Inter-agent messaging is handled by a custom SQLite mail system (WAL mode, ~1-5ms per query) with typed protocol messages and broadcast support. A FIFO merge queue with 4-tier conflict resolution merges agent branches back to canonical. A tiered watchdog system (Tier 0 mechanical daemon, Tier 1 AI-assisted triage, Tier 2 monitor agent) ensures fleet health. See [CLAUDE.md](CLAUDE.md) for full technical details.
+
+### Runtime Adapters
+
+Overstory is runtime-agnostic. The `AgentRuntime` interface (`src/runtimes/types.ts`) defines the contract — each adapter handles spawning, config deployment, guard enforcement, readiness detection, and transcript parsing for its runtime. Set the default in `config.yaml` or override per-agent with `ov sling --runtime <name>`.
+
+| Runtime | CLI | Guard Mechanism | Status |
+|---------|-----|-----------------|--------|
+| Claude Code | `claude` | `settings.local.json` hooks | Stable |
+| Pi | `pi` | `.pi/extensions/` guard extension | Active development |
 
 ## How It Works
 
-CLAUDE.md + hooks + the `ov` CLI turn your Claude Code session into a multi-agent orchestrator. A persistent coordinator agent manages task decomposition and dispatch, while a mechanical watchdog daemon monitors agent health in the background.
+Instruction overlays + tool-call guards + the `ov` CLI turn your coding session into a multi-agent orchestrator. A persistent coordinator agent manages task decomposition and dispatch, while a mechanical watchdog daemon monitors agent health in the background.
 
 ```
 Coordinator (persistent orchestrator at project root)
@@ -190,10 +202,10 @@ Coordinator (persistent orchestrator at project root)
 - **Worktrees**: Each agent gets an isolated git worktree — no file conflicts between agents
 - **Merge**: FIFO merge queue (SQLite-backed) with 4-tier conflict resolution
 - **Watchdog**: Tiered health monitoring — Tier 0 mechanical daemon (tmux/pid liveness), Tier 1 AI-assisted failure triage, Tier 2 monitor agent for continuous fleet patrol
-- **Tool Enforcement**: PreToolUse hooks mechanically block file modifications for non-implementation agents and dangerous git operations for all agents
+- **Tool Enforcement**: Runtime-specific guards (hooks for Claude Code, extensions for Pi) mechanically block file modifications for non-implementation agents and dangerous git operations for all agents
 - **Task Groups**: Batch coordination with auto-close when all member issues complete
 - **Session Lifecycle**: Checkpoint save/restore for compaction survivability, handoff orchestration for crash recovery
-- **Token Instrumentation**: Session metrics extracted from Claude Code transcript JSONL files
+- **Token Instrumentation**: Session metrics extracted from runtime transcript files (JSONL)
 
 ## Project Structure
 
@@ -252,7 +264,7 @@ overstory/
     merge/                        FIFO queue + conflict resolution
     watchdog/                     Tiered health monitoring (daemon, triage, health)
     logging/                      Multi-format logger + sanitizer + reporter + color control + shared theme/format
-    metrics/                      SQLite metrics + transcript parsing
+    metrics/                      SQLite metrics + pricing + transcript parsing
     doctor/                       Health check modules (10 checks)
     insights/                     Session insight analyzer for auto-expertise
     runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi)

package/agents/builder.md

@@ -54,8 +54,10 @@ Your task-specific context (task ID, file scope, spec path, branch name, parent
 5. **Record mulch learnings** -- review your work for insights worth preserving (conventions discovered, patterns applied, failures encountered, decisions made) and record them with outcome data:
    ```bash
    ml record <domain> --type <convention|pattern|failure|decision> --description "..." \
+     --classification <foundational|tactical|observational> \
      --outcome-status success --outcome-agent $OVERSTORY_AGENT_NAME
    ```
+   Classification guide: use `foundational` for stable conventions confirmed across sessions, `tactical` for session-specific patterns (default), `observational` for unverified one-off findings.
    This is a required gate, not optional. Every implementation session produces learnings. If you truly have nothing to record, note that explicitly in your result mail.
 6. Send `worker_done` mail to your parent with structured payload:
    ```bash
@@ -99,6 +101,10 @@ You are an implementation specialist. Given a spec and a set of files you own, y
 ### Expertise
 - **Load context:** `ml prime [domain]` to load domain expertise before implementing
 - **Record patterns:** `ml record <domain>` to capture useful patterns you discover
+- **Classify records:** Always pass `--classification` when recording:
+  - `foundational` — core conventions confirmed across multiple sessions (e.g., "all SQLite DBs use WAL mode")
+  - `tactical` — session-specific patterns useful for similar tasks (default if omitted)
+  - `observational` — one-off findings or unverified hypotheses worth noting
 
 ## workflow
 

package/agents/coordinator.md

@@ -145,7 +145,7 @@ Coordinator (you, depth 0)
 
 ### Expertise
 - **Load context:** `ml prime [domain]` to understand the problem space before planning
-- **Record insights:** `ml record <domain> --type <type> --description "<insight>"` to capture orchestration patterns, dispatch decisions, and failure learnings
+- **Record insights:** `ml record <domain> --type <type> --classification <foundational|tactical|observational> --description "<insight>"` to capture orchestration patterns, dispatch decisions, and failure learnings. Use `foundational` for stable conventions, `tactical` for session-specific patterns, `observational` for unverified findings.
 - **Search knowledge:** `ml search <query>` to find relevant past decisions
 
 ## workflow
@@ -243,7 +243,7 @@ When a batch is complete (task group auto-closed, all issues resolved):
 1. Verify all issues are closed: run `{{TRACKER_CLI}} show <id>` for each issue in the group.
 2. Verify all branches are merged: check `ov status` for unmerged branches.
 3. Clean up worktrees: `ov worktree clean --completed`.
-4. Record orchestration insights: `ml record <domain> --type <type> --description "<insight>"`.
+4. Record orchestration insights: `ml record <domain> --type <type> --classification <foundational|tactical|observational> --description "<insight>"`.
 5. Report to the human operator: summarize what was accomplished, what was merged, any issues encountered.
 6. Check for follow-up work: `{{TRACKER_CLI}} ready` to see if new issues surfaced during the batch.
 

package/agents/lead.md

@@ -121,6 +121,7 @@ ov sling <task-id> \
 - **Load domain context:** `ml prime [domain]` to understand the problem space before decomposing
 - **Record patterns:** `ml record <domain>` to capture orchestration insights
 - **Record worker insights:** When worker result mails contain notable findings, record them via `ml record` if they represent reusable patterns or conventions.
+- **Classify records:** Always pass `--classification` when recording. Use `foundational` for core conventions confirmed across sessions, `tactical` for session-specific patterns (default), `observational` for one-off findings.
 
 ## task-complexity-assessment
 
@@ -297,8 +298,10 @@ Good decomposition follows these principles:
 3. Run integration tests if applicable: {{QUALITY_GATE_INLINE}}.
 4. **Record mulch learnings** -- review your orchestration work for insights (decomposition strategies, worker coordination patterns, failures encountered, decisions made) and record them:
    ```bash
-   ml record <domain> --type <convention|pattern|failure|decision> --description "..."
+   ml record <domain> --type <convention|pattern|failure|decision> --description "..." \
+     --classification <foundational|tactical|observational>
    ```
+   Classification guide: use `foundational` for stable conventions confirmed across sessions, `tactical` for session-specific patterns (default), `observational` for unverified one-off findings.
    This is required. Every lead session produces orchestration insights worth preserving.
 5. Run `{{TRACKER_CLI}} close <task-id> --reason "<summary of what was accomplished>"`.
 6. Send a `status` mail to the coordinator confirming all subtasks are complete.

package/agents/merger.md

@@ -51,7 +51,8 @@ Your task-specific context (task ID, branches to merge, target branch, merge ord
 {{QUALITY_GATE_STEPS}}
 4. **Record mulch learnings** -- capture merge resolution insights (conflict patterns, resolution strategies, branch integration issues):
    ```bash
-   ml record <domain> --type <convention|pattern|failure> --description "..."
+   ml record <domain> --type <convention|pattern|failure> --description "..." \
+     --classification <foundational|tactical|observational>
    ```
    This is required for non-trivial merges (Tier 2+). Merge resolution patterns are highly reusable knowledge for future mergers. Skip for clean Tier 1 merges with no conflicts.
 5. Send a `result` mail to your parent with: tier used, conflicts resolved (if any), test status.
@@ -92,7 +93,7 @@ You are a branch integration specialist. When workers complete their tasks on se
 
 ### Expertise
 - **Load context:** `ml prime [domain]` to understand the code being merged
-- **Record patterns:** `ml record <domain>` to capture merge resolution insights
+- **Record patterns:** `ml record <domain> --classification <foundational|tactical|observational>` to capture merge resolution insights. Use `foundational` for stable merge conventions, `tactical` for resolution strategies, `observational` for one-off conflict patterns.
 
 ## workflow
 

package/agents/monitor.md

@@ -72,7 +72,7 @@ You are the watchdog's brain. While Tier 0 (mechanical daemon) checks tmux/pid l
 
 ### Expertise
 - **Load context:** `ml prime [domain]` to understand project patterns
-- **Record insights:** `ml record <domain> --type <type> --description "<insight>"` to capture monitoring patterns, failure signatures, and recovery strategies
+- **Record insights:** `ml record <domain> --type <type> --classification <foundational|tactical|observational> --description "<insight>"` to capture monitoring patterns, failure signatures, and recovery strategies. Use `foundational` for stable monitoring conventions, `tactical` for incident-specific patterns, `observational` for unverified anomaly observations.
 - **Search knowledge:** `ml search <query>` to find relevant past incidents
 
 ## workflow

package/agents/reviewer.md

@@ -91,6 +91,7 @@ You are a validation specialist. Given code to review, you check it for correctn
 ### Expertise
 - **Load conventions:** `ml prime [domain]` to understand project standards
 - **Surface insights:** Include notable findings (convention violations, code quality patterns) in your result mail so your parent has full context.
+- **Classification guidance for parents:** When including notable findings in your result mail, indicate suggested classification: `foundational` (confirmed stable convention), `tactical` (task-specific pattern), or `observational` (unverified finding). This helps your parent record accurately.
 
 ## workflow
 

package/agents/scout.md

@@ -93,6 +93,7 @@ You perform reconnaissance. Given a research question, exploration target, or an
 ### Expertise
 - **Query expertise:** `ml prime [domain]` to load relevant context
 - **Surface insights:** Include notable findings (patterns, conventions, gotchas) in your result mail so your parent has full context for spec writing.
+- **Classification guidance for parents:** When including notable findings in your result mail, indicate suggested classification: `foundational` (confirmed stable convention), `tactical` (task-specific pattern), or `observational` (unverified finding). This helps your parent record accurately.
 
 ## workflow
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.7.2",
-	"description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
+	"version": "0.7.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",
 	"type": "module",

package/src/agents/hooks-deployer.test.ts

@@ -1,8 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AgentError } from "../errors.ts";
+import { cleanupTempDir } from "../test-helpers.ts";
 import {
 	buildBashFileGuardScript,
 	buildBashPathBoundaryScript,
@@ -26,7 +27,7 @@ describe("deployHooks", () => {
 	});
 
 	afterEach(async () => {
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 
 	test("creates .claude/settings.local.json in worktree directory", async () => {
@@ -1482,7 +1483,7 @@ describe("structural enforcement integration", () => {
 	});
 
 	afterEach(async () => {
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 
 	test("non-implementation agents have more guards than implementation agents", async () => {
@@ -2055,7 +2056,7 @@ describe("bash path boundary integration", () => {
 	});
 
 	afterEach(async () => {
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 
 	test("builder gets Bash path boundary guard in deployed hooks", async () => {
@@ -2249,7 +2250,7 @@ describe("PATH prefix in deployed hooks", () => {
 	});
 
 	afterEach(async () => {
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 
 	test("SessionStart hook commands include PATH prefix", async () => {

package/src/agents/identity.test.ts

@@ -1,8 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AgentError } from "../errors.ts";
+import { cleanupTempDir } from "../test-helpers.ts";
 import type { AgentIdentity } from "../types.ts";
 import { createIdentity, loadIdentity, updateIdentity } from "./identity.ts";
 
@@ -14,7 +15,7 @@ describe("identity", () => {
 	});
 
 	afterEach(async () => {
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 
 	describe("createIdentity", () => {

package/src/agents/manifest.test.ts

@@ -1,8 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AgentError } from "../errors.ts";
+import { cleanupTempDir } from "../test-helpers.ts";
 import type { AgentManifest, OverstoryConfig } from "../types.ts";
 import { createManifestLoader, resolveModel, resolveProviderEnv } from "./manifest.ts";
 
@@ -41,7 +42,7 @@ describe("createManifestLoader", () => {
 	});
 
 	afterEach(async () => {
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 
 	/** Write the manifest JSON and create matching .md files. */
@@ -806,7 +807,7 @@ describe("manifest validation accepts arbitrary model strings", () => {
 	});
 
 	afterEach(async () => {
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 
 	test("accepts provider-prefixed model string", async () => {

package/src/agents/overlay.test.ts

@@ -1,8 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AgentError } from "../errors.ts";
+import { cleanupTempDir } from "../test-helpers.ts";
 import type { OverlayConfig, QualityGate } from "../types.ts";
 import {
 	formatQualityGatesBash,
@@ -584,7 +585,7 @@ describe("writeOverlay", () => {
 	});
 
 	afterEach(async () => {
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 
 	test("creates .claude/CLAUDE.md in worktree directory", async () => {

package/src/commands/agents.test.ts

@@ -3,10 +3,11 @@
  */
 
 import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createSessionStore } from "../sessions/store.ts";
+import { cleanupTempDir } from "../test-helpers.ts";
 import type { AgentSession } from "../types.ts";
 import { agentsCommand, discoverAgents, extractFileScope } from "./agents.ts";
 
@@ -65,7 +66,7 @@ Some expertise here.
 	});
 
 	afterEach(async () => {
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 });
 
@@ -235,7 +236,7 @@ describe("discoverAgents", () => {
 	});
 
 	afterEach(async () => {
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 });
 
@@ -322,6 +323,6 @@ logging:
 	afterEach(async () => {
 		process.stdout.write = originalStdoutWrite;
 		process.chdir(originalCwd);
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 });

package/src/commands/agents.ts

@@ -29,9 +29,15 @@ 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)
+];
+
 /**
- * Extract file scope from an agent's overlay CLAUDE.md.
- * Returns empty array if overlay doesn't exist, has no file scope restrictions,
+ * Extract file scope from an agent's overlay instruction file.
+ * Returns empty array if no overlay exists, has no file scope restrictions,
  * or can't be read.
  *
  * @param worktreePath - Absolute path to the agent's worktree
@@ -39,15 +45,19 @@ export interface DiscoveredAgent {
  */
 export async function extractFileScope(worktreePath: string): Promise<string[]> {
 	try {
-		const overlayPath = join(worktreePath, ".claude", "CLAUDE.md");
-		const overlayFile = Bun.file(overlayPath);
-
-		if (!(await overlayFile.exists())) {
+		let content: string | null = null;
+		for (const relPath of KNOWN_INSTRUCTION_PATHS) {
+			const overlayPath = join(worktreePath, relPath);
+			const overlayFile = Bun.file(overlayPath);
+			if (await overlayFile.exists()) {
+				content = await overlayFile.text();
+				break;
+			}
+		}
+		if (content === null) {
 			return [];
 		}
 
-		const content = await overlayFile.text();
-
 		// Find the section between "## File Scope (exclusive ownership)" and "## Expertise"
 		const startMarker = "## File Scope (exclusive ownership)";
 		const endMarker = "## Expertise";

package/src/commands/completions.test.ts

@@ -12,8 +12,8 @@ import {
 } from "./completions.ts";
 
 describe("COMMANDS array", () => {
-	it("should have exactly 30 commands", () => {
-		expect(COMMANDS).toHaveLength(30);
+	it("should have exactly 33 commands", () => {
+		expect(COMMANDS).toHaveLength(33);
 	});
 
 	it("should include all expected command names", () => {
@@ -48,6 +48,9 @@ describe("COMMANDS array", () => {
 		expect(names).toContain("feed");
 		expect(names).toContain("logs");
 		expect(names).toContain("stop");
+		expect(names).toContain("ecosystem");
+		expect(names).toContain("upgrade");
+		expect(names).toContain("completions");
 	});
 });
 
@@ -59,7 +62,7 @@ describe("generateBash", () => {
 		expect(script).toContain("_init_completion");
 	});
 
-	it("should include all 27 command names", () => {
+	it("should include all 33 command names", () => {
 		const script = generateBash();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);
@@ -93,7 +96,7 @@ describe("generateZsh", () => {
 		expect(script).toContain("_arguments");
 	});
 
-	it("should include all 27 command names", () => {
+	it("should include all 33 command names", () => {
 		const script = generateZsh();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);
@@ -123,7 +126,7 @@ describe("generateFish", () => {
 		expect(script).toContain("__fish_use_subcommand");
 	});
 
-	it("should include all 27 command names", () => {
+	it("should include all 33 command names", () => {
 		const script = generateFish();
 		for (const cmd of COMMANDS) {
 			expect(script).toContain(cmd.name);

package/src/commands/completions.ts

@@ -58,6 +58,9 @@ export const COMMANDS: readonly CommandDef[] = [
 		desc: "Initialize .overstory/ in current project",
 		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: "--help", desc: "Show help" },
 		],
 	},
@@ -76,7 +79,13 @@ export const COMMANDS: readonly CommandDef[] = [
 			{ name: "--files", desc: "Exclusive file scope (comma-separated)", takesValue: true },
 			{ name: "--parent", desc: "Parent agent name", takesValue: true },
 			{ name: "--depth", desc: "Current hierarchy depth", takesValue: true },
+			{ name: "--skip-scout", desc: "Skip scout phase for lead agents" },
+			{ name: "--skip-review", desc: "Skip review phase for lead agents" },
+			{ name: "--skip-task-check", desc: "Skip task existence validation" },
 			{ name: "--force-hierarchy", desc: "Bypass hierarchy validation" },
+			{ name: "--max-agents", desc: "Max children per lead", takesValue: true },
+			{ name: "--dispatch-max-agents", desc: "Per-lead max agents ceiling", takesValue: true },
+			{ name: "--runtime", desc: "Runtime adapter", takesValue: true },
 			{ name: "--json", desc: "JSON output" },
 			{ name: "--help", desc: "Show help" },
 		],
@@ -107,6 +116,7 @@ export const COMMANDS: readonly CommandDef[] = [
 			{ name: "--json", desc: "JSON output" },
 			{ name: "--verbose", desc: "Extra per-agent detail" },
 			{ name: "--agent", desc: "Filter by agent", takesValue: true },
+			{ name: "--all", desc: "Show sessions from all runs" },
 			{ name: "--watch", desc: "Watch mode" },
 			{ name: "--interval", desc: "Poll interval in ms", takesValue: true },
 			{ name: "--help", desc: "Show help" },
@@ -138,6 +148,7 @@ export const COMMANDS: readonly CommandDef[] = [
 		flags: [
 			{ name: "--branch", desc: "Specific branch to merge", takesValue: true },
 			{ name: "--all", desc: "All completed branches" },
+			{ name: "--into", desc: "Target branch to merge into", takesValue: true },
 			{ name: "--dry-run", desc: "Check for conflicts only" },
 			{ name: "--json", desc: "JSON output" },
 			{ name: "--help", desc: "Show help" },
@@ -190,8 +201,10 @@ export const COMMANDS: readonly CommandDef[] = [
 					"merge",
 					"logs",
 					"version",
+					"ecosystem",
 				],
 			},
+			{ name: "--fix", desc: "Attempt to auto-fix issues" },
 			{ name: "--help", desc: "Show help" },
 		],
 	},
@@ -606,6 +619,29 @@ export const COMMANDS: readonly CommandDef[] = [
 			},
 		],
 	},
+	{
+		name: "ecosystem",
+		desc: "Show a summary dashboard of all installed os-eco tools",
+		flags: [
+			{ name: "--json", desc: "JSON output" },
+			{ name: "--help", desc: "Show help" },
+		],
+	},
+	{
+		name: "upgrade",
+		desc: "Upgrade overstory to the latest version",
+		flags: [
+			{ name: "--check", desc: "Compare current vs latest without installing" },
+			{ name: "--all", desc: "Upgrade all os-eco tools" },
+			{ name: "--json", desc: "JSON output" },
+			{ name: "--help", desc: "Show help" },
+		],
+	},
+	{
+		name: "completions",
+		desc: "Generate shell completions",
+		flags: [{ name: "--help", desc: "Show help" }],
+	},
 ] as const;
 
 export function generateBash(): string {
@@ -618,7 +654,7 @@ export function generateBash(): string {
 		"  local cur prev words cword",
 		"  _init_completion || return",
 		"",
-		"  local commands='init sling prime stop status dashboard inspect merge nudge clean doctor log logs watch trace errors feed replay costs metrics spec coordinator supervisor hooks monitor mail group worktree run'",
+		"  local commands='agents init sling prime stop status dashboard inspect merge nudge clean doctor log logs watch trace errors feed replay costs metrics spec coordinator supervisor hooks monitor mail group worktree run ecosystem upgrade completions'",
 		"",
 		"  # Top-level completion",
 		"  if [[ $cword -eq 1 ]]; then",

package/src/commands/costs.test.ts

@@ -9,12 +9,13 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { ValidationError } from "../errors.ts";
 import { createMetricsStore } from "../metrics/store.ts";
 import { createSessionStore } from "../sessions/store.ts";
+import { cleanupTempDir } from "../test-helpers.ts";
 import type { SessionMetrics } from "../types.ts";
 import { costsCommand } from "./costs.ts";
 
@@ -72,7 +73,7 @@ describe("costsCommand", () => {
 	afterEach(async () => {
 		process.stdout.write = originalWrite;
 		process.chdir(originalCwd);
-		await rm(tempDir, { recursive: true, force: true });
+		await cleanupTempDir(tempDir);
 	});
 
 	function output(): string {
@@ -1052,7 +1053,7 @@ describe("costsCommand", () => {
 
 		afterEach(async () => {
 			process.env.HOME = originalHome;
-			await rm(tempHome, { recursive: true, force: true });
+			await cleanupTempDir(tempHome);
 		});
 
 		test("--self shows orchestrator cost when transcript exists", async () => {