@os-eco/overstory-cli 0.6.9 → 0.6.11

package/src/doctor/structure.test.ts

@@ -6,7 +6,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, utimes } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { OverstoryConfig } from "../types.ts";
@@ -34,6 +34,7 @@ describe("checkStructure", () => {
 				staggerDelayMs: 1000,
 				maxDepth: 2,
 				maxSessionsPerRun: 0,
+				maxAgentsPerLead: 5,
 			},
 			worktrees: {
 				baseDir: ".overstory/worktrees",
@@ -288,4 +289,133 @@ describe("checkStructure", () => {
 		expect(tempFilesCheck).toBeDefined();
 		expect(tempFilesCheck?.status).toBe("pass");
 	});
+
+	test("fix() creates missing subdirectories", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const dirsCheck = checks.find((c) => c.name === "Required subdirectories");
+		expect(dirsCheck?.status).toBe("fail");
+		expect(dirsCheck?.fix).toBeDefined();
+
+		const actions = await dirsCheck?.fix?.();
+		expect(actions).toBeDefined();
+		expect(actions?.length).toBeGreaterThan(0);
+		expect(actions?.some((a) => a.includes("agents/"))).toBe(true);
+		expect(actions?.some((a) => a.includes("worktrees/"))).toBe(true);
+		expect(actions?.some((a) => a.includes("specs/"))).toBe(true);
+		expect(actions?.some((a) => a.includes("logs/"))).toBe(true);
+
+		// Verify directories were actually created
+		const { stat: fsStat } = await import("node:fs/promises");
+		const agentsStat = await fsStat(join(overstoryDir, "agents"));
+		expect(agentsStat.isDirectory()).toBe(true);
+		const worktreesStat = await fsStat(join(overstoryDir, "worktrees"));
+		expect(worktreesStat.isDirectory()).toBe(true);
+	});
+
+	test("fix() appends missing .gitignore entries", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		await Bun.write(join(overstoryDir, ".gitignore"), `*\n!.gitignore\n!config.yaml\n`);
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const gitignoreCheck = checks.find((c) => c.name === ".gitignore entries");
+		expect(gitignoreCheck?.status).toBe("warn");
+		expect(gitignoreCheck?.fix).toBeDefined();
+
+		const actions = await gitignoreCheck?.fix?.();
+		expect(actions).toBeDefined();
+		expect(actions?.length).toBeGreaterThan(0);
+		expect(actions?.some((a) => a.includes("!agent-manifest.json"))).toBe(true);
+
+		// Verify entries were appended
+		const content = await Bun.file(join(overstoryDir, ".gitignore")).text();
+		expect(content).toContain("!agent-manifest.json");
+		expect(content).toContain("!hooks.json");
+	});
+
+	test("fix() removes leftover temp files", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		const tmpFile = join(overstoryDir, "config.yaml.tmp");
+		const bakFile = join(overstoryDir, "old.bak");
+		await Bun.write(tmpFile, "temp content");
+		await Bun.write(bakFile, "backup content");
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const tempCheck = checks.find((c) => c.name === "Leftover temp files");
+		expect(tempCheck?.status).toBe("warn");
+		expect(tempCheck?.fix).toBeDefined();
+
+		const actions = await tempCheck?.fix?.();
+		expect(actions).toBeDefined();
+		expect(actions?.some((a) => a.includes("config.yaml.tmp"))).toBe(true);
+		expect(actions?.some((a) => a.includes("old.bak"))).toBe(true);
+
+		// Verify files were deleted
+		expect(await Bun.file(tmpFile).exists()).toBe(false);
+		expect(await Bun.file(bakFile).exists()).toBe(false);
+	});
+
+	test("passes when no stale lock files exist", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const lockCheck = checks.find((c) => c.name === "Stale lock files");
+		expect(lockCheck).toBeDefined();
+		expect(lockCheck?.status).toBe("pass");
+		expect(lockCheck?.fix).toBeUndefined();
+	});
+
+	test("warns when stale lock files exist", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		const lockFile = join(overstoryDir, "mail.lock");
+		await Bun.write(lockFile, "locked");
+		// Set mtime to 10 minutes ago
+		const tenMinutesAgo = new Date(Date.now() - 10 * 60 * 1000);
+		await utimes(lockFile, tenMinutesAgo, tenMinutesAgo);
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const lockCheck = checks.find((c) => c.name === "Stale lock files");
+		expect(lockCheck).toBeDefined();
+		expect(lockCheck?.status).toBe("warn");
+		expect(lockCheck?.details).toContain("mail.lock");
+		expect(lockCheck?.fixable).toBe(true);
+		expect(lockCheck?.fix).toBeDefined();
+	});
+
+	test("does not warn about fresh lock files", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		// Write a fresh lock file (just created = now)
+		await Bun.write(join(overstoryDir, "sessions.lock"), "locked");
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const lockCheck = checks.find((c) => c.name === "Stale lock files");
+		expect(lockCheck?.status).toBe("pass");
+	});
+
+	test("fix() removes stale lock files", async () => {
+		await mkdir(overstoryDir, { recursive: true });
+		const lockFile = join(overstoryDir, "stale.lock");
+		await Bun.write(lockFile, "locked");
+		// Set mtime to 10 minutes ago
+		const tenMinutesAgo = new Date(Date.now() - 10 * 60 * 1000);
+		await utimes(lockFile, tenMinutesAgo, tenMinutesAgo);
+
+		const checks = await checkStructure(mockConfig, overstoryDir);
+
+		const lockCheck = checks.find((c) => c.name === "Stale lock files");
+		expect(lockCheck?.fix).toBeDefined();
+
+		const actions = await lockCheck?.fix?.();
+		expect(actions?.some((a) => a.includes("stale.lock"))).toBe(true);
+
+		// Verify the lock file was removed
+		expect(await Bun.file(lockFile).exists()).toBe(false);
+	});
 });

package/src/doctor/structure.ts

@@ -1,4 +1,4 @@
-import { access, constants } from "node:fs/promises";
+import { access, constants, mkdir, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import type { AgentManifest } from "../types.ts";
 import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
@@ -87,6 +87,18 @@ export const checkStructure: DoctorCheckFn = async (
 				: `Missing ${missingDirs.length} subdirectory(ies)`,
 		details: missingDirs.length > 0 ? missingDirs : undefined,
 		fixable: missingDirs.length > 0,
+		fix:
+			missingDirs.length > 0
+				? async () => {
+						const actions: string[] = [];
+						for (const dir of missingDirs) {
+							const dirPath = join(overstoryDir, dir.replace(/\/$/, ""));
+							await mkdir(dirPath, { recursive: true });
+							actions.push(`Created missing directory: ${dir}`);
+						}
+						return actions;
+					}
+				: undefined,
 	});
 
 	// Check 4: .gitignore contents — validate wildcard+whitelist model
@@ -115,6 +127,19 @@ export const checkStructure: DoctorCheckFn = async (
 					: `Missing ${missingEntries.length} entry(ies)`,
 			details: missingEntries.length > 0 ? missingEntries : undefined,
 			fixable: missingEntries.length > 0,
+			fix:
+				missingEntries.length > 0
+					? async () => {
+							const actions: string[] = [];
+							const content = await Bun.file(gitignorePath).text();
+							const suffix = content.endsWith("\n") ? "" : "\n";
+							await Bun.write(gitignorePath, `${content + suffix + missingEntries.join("\n")}\n`);
+							for (const entry of missingEntries) {
+								actions.push(`Added .gitignore entry: ${entry}`);
+							}
+							return actions;
+						}
+					: undefined,
 		});
 	} catch {
 		// .gitignore doesn't exist, already reported in required files check
@@ -189,10 +214,71 @@ export const checkStructure: DoctorCheckFn = async (
 				tempFiles.length === 0 ? "No temp files found" : `Found ${tempFiles.length} temp file(s)`,
 			details: tempFiles.length > 0 ? tempFiles : undefined,
 			fixable: tempFiles.length > 0,
+			fix:
+				tempFiles.length > 0
+					? async () => {
+							const actions: string[] = [];
+							for (const file of tempFiles) {
+								await rm(join(overstoryDir, file), { force: true });
+								actions.push(`Removed temp file: ${file}`);
+							}
+							return actions;
+						}
+					: undefined,
 		});
 	} catch {
 		// Ignore errors scanning for temp files
 	}
 
+	// Check 7: Stale lock files (older than 5 minutes)
+	try {
+		const lockEntries = await Array.fromAsync(new Bun.Glob("*.lock").scan({ cwd: overstoryDir }));
+		const now = Date.now();
+		const staleLockThresholdMs = 5 * 60 * 1000;
+		const staleLockFiles: string[] = [];
+
+		for (const lockFile of lockEntries) {
+			try {
+				const lockPath = join(overstoryDir, lockFile);
+				const stats = await stat(lockPath);
+				const ageMs = now - stats.mtimeMs;
+				if (ageMs > staleLockThresholdMs) {
+					staleLockFiles.push(lockFile);
+				}
+			} catch {
+				// ignore stat errors
+			}
+		}
+
+		checks.push({
+			name: "Stale lock files",
+			category: "structure",
+			status: staleLockFiles.length === 0 ? "pass" : "warn",
+			message:
+				staleLockFiles.length === 0
+					? "No stale lock files found"
+					: `Found ${staleLockFiles.length} stale lock file(s)`,
+			details: staleLockFiles.length > 0 ? staleLockFiles : undefined,
+			fixable: staleLockFiles.length > 0,
+			fix:
+				staleLockFiles.length > 0
+					? async () => {
+							const actions: string[] = [];
+							for (const file of staleLockFiles) {
+								try {
+									await rm(join(overstoryDir, file), { force: true });
+									actions.push(`Removed stale lock file: ${file}`);
+								} catch {
+									// ignore removal errors
+								}
+							}
+							return actions;
+						}
+					: undefined,
+		});
+	} catch {
+		// ignore errors scanning for lock files
+	}
+
 	return checks;
 };

package/src/doctor/types.ts

@@ -12,7 +12,8 @@ export type DoctorCategory =
 	| "agents"
 	| "merge"
 	| "logs"
-	| "version";
+	| "version"
+	| "ecosystem";
 
 /** Result of a single doctor health check. */
 export interface DoctorCheck {
@@ -21,8 +22,10 @@ export interface DoctorCheck {
 	status: "pass" | "warn" | "fail";
 	message: string;
 	details?: string[];
-	/** Whether this check issues can be auto-fixed (future --fix flag). */
+	/** Whether this check issues can be auto-fixed via --fix. */
 	fixable?: boolean;
+	/** Auto-fix closure — called when --fix flag is passed. Captures context at construction time. */
+	fix?: () => Promise<string[]> | string[];
 }
 
 /**

package/src/doctor/version.test.ts

@@ -16,6 +16,7 @@ const mockConfig: OverstoryConfig = {
 		staggerDelayMs: 1000,
 		maxDepth: 2,
 		maxSessionsPerRun: 0,
+		maxAgentsPerLead: 5,
 	},
 	worktrees: {
 		baseDir: "/tmp/.overstory/worktrees",

package/src/index.ts

@@ -15,6 +15,7 @@ import { createCoordinatorCommand } from "./commands/coordinator.ts";
 import { createCostsCommand } from "./commands/costs.ts";
 import { createDashboardCommand } from "./commands/dashboard.ts";
 import { createDoctorCommand } from "./commands/doctor.ts";
+import { createEcosystemCommand } from "./commands/ecosystem.ts";
 import { createErrorsCommand } from "./commands/errors.ts";
 import { createFeedCommand } from "./commands/feed.ts";
 import { createGroupCommand } from "./commands/group.ts";
@@ -37,13 +38,14 @@ import { createStatusCommand } from "./commands/status.ts";
 import { stopCommand } from "./commands/stop.ts";
 import { createSupervisorCommand } from "./commands/supervisor.ts";
 import { traceCommand } from "./commands/trace.ts";
+import { createUpgradeCommand } from "./commands/upgrade.ts";
 import { createWatchCommand } from "./commands/watch.ts";
 import { createWorktreeCommand } from "./commands/worktree.ts";
 import { OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.6.9";
+export const VERSION = "0.6.11";
 
 const rawArgs = process.argv.slice(2);
 
@@ -86,12 +88,14 @@ const COMMANDS = [
 	"logs",
 	"watch",
 	"trace",
+	"ecosystem",
 	"feed",
 	"errors",
 	"replay",
 	"run",
 	"costs",
 	"metrics",
+	"upgrade",
 ];
 
 function editDistance(a: string, b: string): number {
@@ -129,6 +133,8 @@ function suggestCommand(input: string): string | undefined {
 
 const program = new Command();
 
+let timingStart: number | undefined;
+
 program
 	.name("ov")
 	.description("Multi-agent orchestration for Claude Code")
@@ -136,6 +142,7 @@ program
 	.option("-q, --quiet", "Suppress non-error output")
 	.option("--json", "JSON output")
 	.option("--verbose", "Verbose output")
+	.option("--timing", "Print command execution time to stderr")
 	.addHelpCommand(false)
 	.configureHelp({
 		formatHelp(cmd, helper): string {
@@ -191,6 +198,17 @@ program.hook("preAction", (thisCmd) => {
 	if (opts.quiet) {
 		setQuiet(true);
 	}
+	if (opts.timing) {
+		timingStart = performance.now();
+	}
+});
+program.hook("postAction", () => {
+	if (program.opts().timing && timingStart !== undefined) {
+		const elapsed = performance.now() - timingStart;
+		const formatted =
+			elapsed < 1000 ? `${Math.round(elapsed)}ms` : `${(elapsed / 1000).toFixed(2)}s`;
+		process.stderr.write(`${muted(`Done in ${formatted}`)}\n`);
+	}
 });
 
 // Migrated commands — use addCommand() with createXCommand() factories
@@ -234,6 +252,9 @@ program
 	.option("--skip-scout", "Skip scout phase for lead agents")
 	.option("--skip-task-check", "Skip task existence validation")
 	.option("--force-hierarchy", "Bypass hierarchy validation")
+	.option("--max-agents <n>", "Max children per lead (overrides config)")
+	.option("--skip-review", "Skip review phase for lead agents")
+	.option("--dispatch-max-agents <n>", "Per-lead max agents ceiling (injected into overlay)")
 	.option("--json", "Output result as JSON")
 	.action(async (taskId, opts) => {
 		await slingCommand(taskId, opts);
@@ -243,8 +264,8 @@ const specCmd = program.command("spec").description("Manage task specifications"
 
 specCmd
 	.command("write")
-	.description("Write a spec file to .overstory/specs/<bead-id>.md")
-	.argument("<bead-id>", "Task ID for the spec file")
+	.description("Write a spec file to .overstory/specs/<task-id>.md")
+	.argument("<task-id>", "Task ID for the spec file")
 	.option("--body <content>", "Spec content (or pipe via stdin)")
 	.option("--agent <name>", "Agent writing the spec (for attribution)")
 	.action(async (taskId, opts) => {
@@ -335,7 +356,7 @@ program
 
 program
 	.command("trace")
-	.description("Chronological event timeline for agent/bead")
+	.description("Chronological event timeline for agent or task")
 	.allowUnknownOption()
 	.allowExcessArguments()
 	.action(async (_opts, cmd) => {
@@ -344,6 +365,8 @@ program
 
 program.addCommand(createFeedCommand());
 
+program.addCommand(createEcosystemCommand());
+
 program.addCommand(createErrorsCommand());
 
 program.addCommand(createReplayCommand());
@@ -354,6 +377,8 @@ program.addCommand(createCostsCommand());
 
 program.addCommand(createMetricsCommand());
 
+program.addCommand(createUpgradeCommand());
+
 // Handle unknown commands with Levenshtein fuzzy-match suggestions
 program.on("command:*", (operands) => {
 	const unknown = operands[0] ?? "";

package/src/types.ts

@@ -53,6 +53,7 @@ export interface OverstoryConfig {
 		staggerDelayMs: number; // Delay between spawns
 		maxDepth: number; // Hierarchy depth limit (default 2)
 		maxSessionsPerRun: number; // Max total sessions per run (0 = unlimited)
+		maxAgentsPerLead: number; // Max children a single lead can spawn (0 = unlimited)
 	};
 	worktrees: {
 		baseDir: string; // Where worktrees live
@@ -258,6 +259,12 @@ export interface DispatchPayload {
 	specPath: string;
 	capability: Capability;
 	fileScope: string[];
+	/** Optional: skip scout phase for lead agents */
+	skipScouts?: boolean;
+	/** Optional: skip review phase for lead agents */
+	skipReview?: boolean;
+	/** Optional: per-lead max agent ceiling override */
+	maxAgents?: number;
 }
 
 /** Supervisor assigns work to a specific worker. */
@@ -300,6 +307,10 @@ export interface OverlayConfig {
 	mulchExpertise?: string;
 	/** When true, lead agents should skip Phase 1 (scout) and go straight to Phase 2 (build). */
 	skipScout?: boolean;
+	/** When true, lead agents should skip Phase 3 review and self-verify instead. */
+	skipReview?: boolean;
+	/** Per-lead max agents ceiling override from dispatch. Injected into overlay for lead visibility. */
+	maxAgentsOverride?: number;
 	trackerCli?: string; // "sd" or "bd"
 	trackerName?: string; // "seeds" or "beads"
 	/** Quality gate commands for the agent overlay. Falls back to defaults if undefined. */

package/templates/overlay.md.tmpl

@@ -10,7 +10,7 @@
 ## Your Assignment
 
 - **Agent Name:** {{AGENT_NAME}}
-- **Task ID:** {{BEAD_ID}}
+- **Task ID:** {{TASK_ID}}
 - **Spec:** {{SPEC_PATH}}
 - **Branch:** {{BRANCH_NAME}}
 - **Worktree:** {{WORKTREE_PATH}}
@@ -21,6 +21,8 @@
 
 {{SKIP_SCOUT}}
 
+{{DISPATCH_OVERRIDES}}
+
 ## Working Directory
 
 Your worktree root is: `{{WORKTREE_PATH}}`