@os-eco/overstory-cli 0.8.7 → 0.9.2

package/src/commands/logs.ts

@@ -18,45 +18,13 @@ import { color } from "../logging/color.ts";
 import { formatAbsoluteTime, formatDate, logLevelColor, logLevelLabel } from "../logging/format.ts";
 import { renderHeader } from "../logging/theme.ts";
 import type { LogEvent } from "../types.ts";
-
-/**
- * Parse relative time formats like "1h", "30m", "2d", "10s" into a Date object.
- * Falls back to parsing as ISO 8601 if not in relative format.
- */
-function parseRelativeTime(timeStr: string): Date {
-	const relativeMatch = /^(\d+)(s|m|h|d)$/.exec(timeStr);
-	if (relativeMatch) {
-		const value = Number.parseInt(relativeMatch[1] ?? "0", 10);
-		const unit = relativeMatch[2];
-		const now = Date.now();
-		let offsetMs = 0;
-
-		switch (unit) {
-			case "s":
-				offsetMs = value * 1000;
-				break;
-			case "m":
-				offsetMs = value * 60 * 1000;
-				break;
-			case "h":
-				offsetMs = value * 60 * 60 * 1000;
-				break;
-			case "d":
-				offsetMs = value * 24 * 60 * 60 * 1000;
-				break;
-		}
-
-		return new Date(now - offsetMs);
-	}
-
-	// Not a relative format, treat as ISO 8601
-	return new Date(timeStr);
-}
+import { parseRelativeTime } from "../utils/time.ts";
 
 /**
  * Build a detail string for a log event based on its data.
+ * @internal Exported for testing.
  */
-function buildLogDetail(event: LogEvent): string {
+export function buildLogDetail(event: LogEvent): string {
 	const parts: string[] = [];
 
 	for (const [key, value] of Object.entries(event.data)) {
@@ -74,8 +42,9 @@ function buildLogDetail(event: LogEvent): string {
 /**
  * Discover all events.ndjson files in the logs directory.
  * Returns array of { agentName, sessionTimestamp, path }.
+ * @internal Exported for testing.
  */
-async function discoverLogFiles(
+export async function discoverLogFiles(
 	logsDir: string,
 	agentFilter?: string,
 ): Promise<
@@ -145,8 +114,9 @@ async function discoverLogFiles(
 /**
  * Parse a single NDJSON file and return log events.
  * Silently skips invalid lines.
+ * @internal Exported for testing.
  */
-async function parseLogFile(path: string): Promise<LogEvent[]> {
+export async function parseLogFile(path: string): Promise<LogEvent[]> {
 	const events: LogEvent[] = [];
 
 	try {
@@ -184,8 +154,9 @@ async function parseLogFile(path: string): Promise<LogEvent[]> {
 
 /**
  * Apply filters to log events.
+ * @internal Exported for testing.
  */
-function filterEvents(
+export function filterEvents(
 	events: LogEvent[],
 	filters: {
 		level?: string;
@@ -255,6 +226,95 @@ function printLogs(events: LogEvent[]): void {
 	}
 }
 
+/**
+ * Process one poll tick of log tailing: scan discovered log files for new data
+ * since lastKnownSizes, parse new lines, apply filters, and return the count
+ * of new events found.
+ * @internal Exported for testing.
+ *
+ * @param logFiles - Array of discovered log file paths
+ * @param lastKnownSizes - Map of file path to last-seen byte offset (mutated in place)
+ * @param filters - Level filter to apply
+ * @returns Number of new events emitted
+ */
+export async function pollLogTick(
+	logFiles: Array<{ path: string }>,
+	lastKnownSizes: Map<string, number>,
+	filters: { level?: string },
+): Promise<number> {
+	const w = process.stdout.write.bind(process.stdout);
+	let emitted = 0;
+
+	for (const { path } of logFiles) {
+		const file = Bun.file(path);
+		let fileSize: number;
+
+		try {
+			const fileStat = await stat(path);
+			fileSize = fileStat.size;
+		} catch {
+			continue; // File disappeared
+		}
+
+		const lastPosition = lastKnownSizes.get(path) ?? 0;
+
+		if (fileSize > lastPosition) {
+			// New data available
+			try {
+				const fullText = await file.text();
+				const newText = fullText.slice(lastPosition);
+				const lines = newText.split("\n");
+
+				for (const line of lines) {
+					if (line.trim() === "") {
+						continue;
+					}
+
+					try {
+						const parsed: unknown = JSON.parse(line);
+						if (
+							typeof parsed === "object" &&
+							parsed !== null &&
+							"timestamp" in parsed &&
+							"event" in parsed
+						) {
+							const event = parsed as LogEvent;
+
+							// Apply level filter
+							if (filters.level !== undefined && event.level !== filters.level) {
+								continue;
+							}
+
+							// Print immediately
+							const time = formatAbsoluteTime(event.timestamp);
+							const levelColorFn = logLevelColor(event.level);
+							const levelStr = logLevelLabel(event.level);
+
+							const agentLabel = event.agentName ? `[${event.agentName}]` : "[unknown]";
+							const detail = buildLogDetail(event);
+							const detailSuffix = detail ? ` ${color.dim(detail)}` : "";
+
+							w(
+								`${time} ${levelColorFn(levelStr)} ` +
+									`${event.event} ${color.dim(agentLabel)}${detailSuffix}\n`,
+							);
+							emitted++;
+						}
+					} catch {
+						// Invalid JSON line, skip
+					}
+				}
+
+				lastKnownSizes.set(path, fileSize);
+			} catch {
+				// File read error, skip
+			}
+		}
+	}
+
+	return emitted;
+}
+
 /**
  * Follow mode: tail logs in real time.
  */
@@ -274,72 +334,7 @@ async function followLogs(
 
 	while (true) {
 		const discovered = await discoverLogFiles(logsDir, filters.agent);
-
-		for (const { path } of discovered) {
-			const file = Bun.file(path);
-			let fileSize: number;
-
-			try {
-				const fileStat = await stat(path);
-				fileSize = fileStat.size;
-			} catch {
-				continue; // File disappeared
-			}
-
-			const lastPosition = filePositions.get(path) ?? 0;
-
-			if (fileSize > lastPosition) {
-				// New data available
-				try {
-					const fullText = await file.text();
-					const newText = fullText.slice(lastPosition);
-					const lines = newText.split("\n");
-
-					for (const line of lines) {
-						if (line.trim() === "") {
-							continue;
-						}
-
-						try {
-							const parsed: unknown = JSON.parse(line);
-							if (
-								typeof parsed === "object" &&
-								parsed !== null &&
-								"timestamp" in parsed &&
-								"event" in parsed
-							) {
-								const event = parsed as LogEvent;
-
-								// Apply level filter
-								if (filters.level !== undefined && event.level !== filters.level) {
-									continue;
-								}
-
-								// Print immediately
-								const time = formatAbsoluteTime(event.timestamp);
-								const levelColorFn = logLevelColor(event.level);
-								const levelStr = logLevelLabel(event.level);
-
-								const agentLabel = event.agentName ? `[${event.agentName}]` : "[unknown]";
-								const detail = buildLogDetail(event);
-								const detailSuffix = detail ? ` ${color.dim(detail)}` : "";
-
-								w(
-									`${time} ${levelColorFn(levelStr)} ` +
-										`${event.event} ${color.dim(agentLabel)}${detailSuffix}\n`,
-								);
-							}
-						} catch {
-							// Invalid JSON line, skip
-						}
-					}
-
-					filePositions.set(path, fileSize);
-				} catch {
-					// File read error, skip
-				}
-			}
-		}
+		await pollLogTick(discovered, filePositions, { level: filters.level });
 
 		// Sleep for 1 second before next poll
 		await Bun.sleep(1000);

package/src/commands/orchestrator.ts

@@ -0,0 +1,42 @@
+import type { Command } from "commander";
+import {
+	type CoordinatorDeps,
+	createPersistentAgentCommand,
+	type PersistentAgentSpec,
+	persistentAgentCommand,
+} from "./coordinator.ts";
+
+const ORCHESTRATOR_SPEC: PersistentAgentSpec = {
+	commandName: "orchestrator",
+	displayName: "Orchestrator",
+	agentName: "orchestrator",
+	capability: "orchestrator",
+	agentDefFile: "orchestrator.md",
+	beaconBuilder: buildOrchestratorBeacon,
+};
+
+/**
+ * Build the startup beacon for the ecosystem-level orchestrator session.
+ */
+export function buildOrchestratorBeacon(cliName = "bd"): string {
+	const timestamp = new Date().toISOString();
+	const parts = [
+		`[OVERSTORY] orchestrator (orchestrator) ${timestamp}`,
+		"Depth: 0 | Parent: none | Role: persistent ecosystem orchestrator",
+		"HIERARCHY: You start per-repo coordinators with ov coordinator start --project <path>. Do NOT use ov sling directly.",
+		"DELEGATION: Work flows through sub-repo coordinators. Dispatch objectives by mail, then monitor coordinator progress and escalate only when needed.",
+		`Startup: run mulch prime, check mail (ov mail check --agent orchestrator), check ${cliName} ready, inspect ecosystem status, then begin coordination`,
+	];
+	return parts.join(" — ");
+}
+
+export function createOrchestratorCommand(deps: CoordinatorDeps = {}): Command {
+	return createPersistentAgentCommand(ORCHESTRATOR_SPEC, deps);
+}
+
+export async function orchestratorCommand(
+	args: string[],
+	deps: CoordinatorDeps = {},
+): Promise<void> {
+	await persistentAgentCommand(args, ORCHESTRATOR_SPEC, deps);
+}

package/src/commands/prime.test.ts

@@ -3,8 +3,8 @@ import { mkdir, mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
-import type { AgentSession } from "../types.ts";
-import { primeCommand } from "./prime.ts";
+import type { AgentManifest, AgentSession, SessionMetrics } from "../types.ts";
+import { formatManifest, formatMetrics, primeCommand } from "./prime.ts";
 
 /**
  * Tests for `overstory prime` command.
@@ -435,3 +435,178 @@ sessions.db
 		});
 	});
 });
+
+describe("formatManifest", () => {
+	test("returns 'No agents registered.' for empty agents record", () => {
+		const manifest: AgentManifest = {
+			version: "1",
+			agents: {},
+			capabilityIndex: {},
+		};
+		expect(formatManifest(manifest)).toBe("No agents registered.");
+	});
+
+	test("formats single agent with capabilities", () => {
+		const manifest: AgentManifest = {
+			version: "1",
+			agents: {
+				scout: {
+					file: "agents/scout.md",
+					model: "sonnet",
+					tools: ["Read", "Glob"],
+					capabilities: ["explore", "analyze"],
+					canSpawn: false,
+					constraints: [],
+				},
+			},
+			capabilityIndex: { explore: ["scout"], analyze: ["scout"] },
+		};
+		const result = formatManifest(manifest);
+		expect(result).toContain("**scout**");
+		expect(result).toContain("[sonnet]");
+		expect(result).toContain("explore, analyze");
+		expect(result).not.toContain("(can spawn)");
+	});
+
+	test("marks agents that can spawn", () => {
+		const manifest: AgentManifest = {
+			version: "1",
+			agents: {
+				lead: {
+					file: "agents/lead.md",
+					model: "opus",
+					tools: ["Read", "Bash"],
+					capabilities: ["coordinate"],
+					canSpawn: true,
+					constraints: [],
+				},
+			},
+			capabilityIndex: { coordinate: ["lead"] },
+		};
+		const result = formatManifest(manifest);
+		expect(result).toContain("(can spawn)");
+	});
+
+	test("formats multiple agents as separate lines", () => {
+		const manifest: AgentManifest = {
+			version: "1",
+			agents: {
+				scout: {
+					file: "agents/scout.md",
+					model: "sonnet",
+					tools: [],
+					capabilities: ["explore"],
+					canSpawn: false,
+					constraints: [],
+				},
+				builder: {
+					file: "agents/builder.md",
+					model: "opus",
+					tools: [],
+					capabilities: ["implement"],
+					canSpawn: false,
+					constraints: [],
+				},
+			},
+			capabilityIndex: {},
+		};
+		const result = formatManifest(manifest);
+		const lines = result.split("\n");
+		expect(lines).toHaveLength(2);
+		expect(lines[0]).toContain("scout");
+		expect(lines[1]).toContain("builder");
+	});
+});
+
+describe("formatMetrics", () => {
+	test("returns 'No recent sessions.' for empty array", () => {
+		expect(formatMetrics([])).toBe("No recent sessions.");
+	});
+
+	test("formats a completed session with duration and merge result", () => {
+		const sessions: SessionMetrics[] = [
+			{
+				agentName: "builder-1",
+				taskId: "task-001",
+				capability: "builder",
+				startedAt: "2026-01-01T00:00:00Z",
+				completedAt: "2026-01-01T00:05:00Z",
+				durationMs: 300_000,
+				exitCode: 0,
+				mergeResult: "clean-merge",
+				parentAgent: "coordinator",
+				inputTokens: 0,
+				outputTokens: 0,
+				cacheReadTokens: 0,
+				cacheCreationTokens: 0,
+				estimatedCostUsd: null,
+				modelUsed: null,
+				runId: null,
+			},
+		];
+		const result = formatMetrics(sessions);
+		expect(result).toContain("builder-1");
+		expect(result).toContain("(builder)");
+		expect(result).toContain("task-001");
+		expect(result).toContain("completed");
+		expect(result).toContain("(300s)");
+		expect(result).toContain("[clean-merge]");
+	});
+
+	test("formats an in-progress session without duration or merge result", () => {
+		const sessions: SessionMetrics[] = [
+			{
+				agentName: "scout-1",
+				taskId: "task-002",
+				capability: "scout",
+				startedAt: "2026-01-01T00:00:00Z",
+				completedAt: null,
+				durationMs: 0,
+				exitCode: null,
+				mergeResult: null,
+				parentAgent: null,
+				inputTokens: 0,
+				outputTokens: 0,
+				cacheReadTokens: 0,
+				cacheCreationTokens: 0,
+				estimatedCostUsd: null,
+				modelUsed: null,
+				runId: null,
+			},
+		];
+		const result = formatMetrics(sessions);
+		expect(result).toContain("scout-1");
+		expect(result).toContain("in-progress");
+		expect(result).not.toContain("[");
+	});
+
+	test("formats multiple sessions as separate lines", () => {
+		const base: SessionMetrics = {
+			agentName: "builder-1",
+			taskId: "task-001",
+			capability: "builder",
+			startedAt: "2026-01-01T00:00:00Z",
+			completedAt: "2026-01-01T00:05:00Z",
+			durationMs: 300_000,
+			exitCode: 0,
+			mergeResult: null,
+			parentAgent: null,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheCreationTokens: 0,
+			estimatedCostUsd: null,
+			modelUsed: null,
+			runId: null,
+		};
+		const sessions: SessionMetrics[] = [
+			base,
+			{ ...base, agentName: "builder-2", taskId: "task-002" },
+		];
+		const result = formatMetrics(sessions);
+		const lines = result.split("\n");
+		expect(lines).toHaveLength(2);
+		expect(lines[0]).toContain("builder-1");
+		expect(lines[1]).toContain("builder-2");
+	});
+});

package/src/commands/prime.ts

@@ -31,8 +31,9 @@ export interface PrimeOptions {
 
 /**
  * Format the agent manifest section for output.
+ * @internal Exported for testing.
  */
-function formatManifest(manifest: AgentManifest): string {
+export function formatManifest(manifest: AgentManifest): string {
 	const lines: string[] = [];
 	for (const [name, def] of Object.entries(manifest.agents)) {
 		const caps = def.capabilities.join(", ");
@@ -44,8 +45,9 @@ function formatManifest(manifest: AgentManifest): string {
 
 /**
  * Format recent session metrics for output.
+ * @internal Exported for testing.
  */
-function formatMetrics(sessions: SessionMetrics[]): string {
+export function formatMetrics(sessions: SessionMetrics[]): string {
 	if (sessions.length === 0) {
 		return "No recent sessions.";
 	}

package/src/commands/sling.ts

@@ -24,6 +24,7 @@ import { join, resolve } from "node:path";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
 import { writeOverlay } from "../agents/overlay.ts";
+import { createCanopyClient } from "../canopy/client.ts";
 import { loadConfig } from "../config.ts";
 import { AgentError, HierarchyError, ValidationError } from "../errors.ts";
 import { inferDomain } from "../insights/analyzer.ts";
@@ -153,6 +154,7 @@ export interface SlingOptions {
 	runtime?: string;
 	noScoutCheck?: boolean;
 	baseBranch?: string;
+	profile?: string;
 }
 
 export interface AutoDispatchOptions {
@@ -369,11 +371,11 @@ export function checkParentAgentLimit(
 }
 
 /**
- * Validate hierarchy constraints: the coordinator (no parent) may only spawn leads.
+ * Validate hierarchy constraints for direct coordinator/human spawns.
  *
  * When parentAgent is null, the caller is the coordinator or a human.
- * Only "lead" capability is allowed in that case. All other capabilities
- * (builder, scout, reviewer, merger) must be spawned by a lead
+ * Direct spawns are allowed for "lead", "scout", and "builder".
+ * Other capabilities (reviewer, merger, etc.) must be spawned by a lead
  * that passes --parent.
  *
  * @param parentAgent - The --parent flag value (null = coordinator/human)
@@ -784,6 +786,23 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 				}
 			}
 
+			// 8b. Resolve canopy profile if specified
+			const profileName =
+				opts.profile ?? process.env.OVERSTORY_PROFILE ?? config.project.defaultProfile;
+			let profileContent: string | undefined;
+			if (profileName) {
+				try {
+					const canopy = createCanopyClient(config.project.root);
+					const rendered = await canopy.render(profileName);
+					if (rendered.success && rendered.sections.length > 0) {
+						profileContent = rendered.sections.map((s) => s.body).join("\n\n");
+					}
+				} catch {
+					// Non-fatal: canopy may not be installed or profile may not exist
+					profileContent = undefined;
+				}
+			}
+
 			// Resolve runtime before overlayConfig so we can pass runtime.instructionPath
 			const runtime = getRuntime(opts.runtime, config, capability);
 
@@ -802,6 +821,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 				canSpawn: agentDef.canSpawn,
 				capability,
 				baseDefinition,
+				profileContent,
 				mulchExpertise,
 				skipScout: skipScout && capability === "lead",
 				skipReview: opts.skipReview === true && capability === "lead",

package/src/commands/update.test.ts

@@ -29,6 +29,7 @@ const AGENT_DEF_FILES = [
 	"merger.md",
 	"monitor.md",
 	"orchestrator.md",
+	"ov-co-creation.md",
 	"reviewer.md",
 	"scout.md",
 ];

package/src/commands/upgrade.test.ts

@@ -44,3 +44,5 @@ describe("createUpgradeCommand — CLI structure", () => {
 		expect(typeof cmd.parse).toBe("function");
 	});
 });
+
+// getCurrentVersion and fetchLatestVersion tests moved to src/utils/version.test.ts

package/src/commands/upgrade.ts

@@ -10,6 +10,7 @@
 import { Command } from "commander";
 import { jsonError, jsonOutput } from "../json.ts";
 import { muted, printError, printHint, printSuccess, printWarning } from "../logging/color.ts";
+import { fetchLatestVersion, getCurrentVersion } from "../utils/version.ts";
 
 const OVERSTORY_PACKAGE = "@os-eco/overstory-cli";
 
@@ -26,23 +27,6 @@ export interface UpgradeOptions {
 	json?: boolean;
 }
 
-async function getCurrentVersion(): Promise<string> {
-	const pkgPath = new URL("../../package.json", import.meta.url);
-	const pkg = JSON.parse(await Bun.file(pkgPath).text()) as { version: string };
-	return pkg.version;
-}
-
-async function fetchLatestVersion(packageName: string): Promise<string> {
-	const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`);
-	if (!res.ok) {
-		throw new Error(
-			`Failed to fetch npm registry for ${packageName}: ${res.status} ${res.statusText}`,
-		);
-	}
-	const data = (await res.json()) as { version: string };
-	return data.version;
-}
-
 async function runInstall(packageName: string): Promise<number> {
 	const proc = Bun.spawn(["bun", "install", "-g", `${packageName}@latest`], {
 		stdout: "inherit",

package/src/commands/watch.test.ts

@@ -3,7 +3,8 @@ import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { cleanupTempDir } from "../test-helpers.ts";
-import { watchCommand } from "./watch.ts";
+import type { HealthCheck } from "../types.ts";
+import { formatCheck, watchCommand } from "./watch.ts";
 
 /**
  * Tests for `overstory watch` command.
@@ -144,3 +145,68 @@ describe("watchCommand", () => {
 		// If it doesn't exist, that's also valid (spawn failed before writing new PID)
 	});
 });
+
+describe("formatCheck", () => {
+	function makeCheck(overrides: Partial<HealthCheck>): HealthCheck {
+		return {
+			agentName: "test-agent",
+			timestamp: new Date().toISOString(),
+			processAlive: true,
+			tmuxAlive: true,
+			pidAlive: true,
+			lastActivity: new Date().toISOString(),
+			state: "working",
+			action: "none",
+			reconciliationNote: null,
+			...overrides,
+		};
+	}
+
+	test("terminate action uses x icon", () => {
+		const result = formatCheck(makeCheck({ action: "terminate" }));
+		expect(result).toMatch(/^x /);
+	});
+
+	test("escalate action uses ! icon", () => {
+		const result = formatCheck(makeCheck({ action: "escalate" }));
+		expect(result).toMatch(/^! /);
+	});
+
+	test("investigate action uses > icon", () => {
+		const result = formatCheck(makeCheck({ action: "investigate" }));
+		expect(result).toMatch(/^> /);
+	});
+
+	test("pidAlive true shows up", () => {
+		const result = formatCheck(makeCheck({ pidAlive: true }));
+		expect(result).toContain("pid=up");
+	});
+
+	test("pidAlive false shows down", () => {
+		const result = formatCheck(makeCheck({ pidAlive: false }));
+		expect(result).toContain("pid=down");
+	});
+
+	test("pidAlive null shows n/a", () => {
+		const result = formatCheck(makeCheck({ pidAlive: null }));
+		expect(result).toContain("pid=n/a");
+	});
+
+	test("includes reconciliation note when present", () => {
+		const result = formatCheck(makeCheck({ reconciliationNote: "stale session" }));
+		expect(result).toContain("[stale session]");
+	});
+
+	test("no reconciliation note brackets when null", () => {
+		const result = formatCheck(makeCheck({ reconciliationNote: null }));
+		expect(result).not.toContain("[");
+	});
+
+	test("includes agent name and state", () => {
+		const result = formatCheck(makeCheck({ agentName: "builder-1", state: "stalled" }));
+		expect(result).toContain("builder-1");
+		expect(result).toContain("stalled");
+	});
+});
+
+// PID and bin utility tests moved to src/utils/pid.test.ts and src/utils/bin.test.ts