@os-eco/overstory-cli 0.8.7 → 0.9.2

package/src/types.ts

@@ -68,6 +68,8 @@ export interface OverstoryConfig {
 		root: string; // Absolute path to target repo
 		canonicalBranch: string; // "main" | "develop"
 		qualityGates?: QualityGate[];
+		/** Default canopy profile name. Used when --profile is not explicitly passed to sling/coordinator. */
+		defaultProfile?: string;
 	};
 	agents: {
 		manifestPath: string; // Path to agent-manifest.json
@@ -103,6 +105,9 @@ export interface OverstoryConfig {
 		staleThresholdMs: number; // When to consider agent stale
 		zombieThresholdMs: number; // When to kill
 		nudgeIntervalMs: number; // Time between progressive nudge stages (default 60_000)
+		rpcTimeoutMs?: number; // Timeout for RPC getState() calls (default 5_000)
+		triageTimeoutMs?: number; // Timeout for Tier 1 AI triage calls (default 30_000)
+		maxEscalationLevel?: number; // Maximum escalation level before termination (default 3)
 	};
 	models: Partial<Record<string, ModelRef>>;
 	logging: {
@@ -163,6 +168,7 @@ export const SUPPORTED_CAPABILITIES = [
 	"reviewer",
 	"lead",
 	"merger",
+	"orchestrator",
 	"coordinator",
 	"supervisor",
 	"monitor",
@@ -193,6 +199,7 @@ export interface AgentSession {
 	escalationLevel: number; // Progressive nudge stage: 0=warn, 1=nudge, 2=escalate, 3=terminate
 	stalledSince: string | null; // ISO timestamp when agent first entered stalled state
 	transcriptPath: string | null; // Runtime-provided transcript JSONL path (decoupled from ~/.claude/)
+	promptVersion?: string | null; // Canopy prompt version used at sling time (e.g. "builder@17")
 }
 
 // === Agent Identity ===
@@ -224,7 +231,8 @@ export type MailProtocolType =
 	| "escalation"
 	| "health_check"
 	| "dispatch"
-	| "assign";
+	| "assign"
+	| "decision_gate";
 
 /** All valid mail message types. */
 export type MailMessageType = MailSemanticType | MailProtocolType;
@@ -243,6 +251,7 @@ export const MAIL_MESSAGE_TYPES: readonly MailMessageType[] = [
 	"health_check",
 	"dispatch",
 	"assign",
+	"decision_gate",
 ] as const;
 
 export interface MailMessage {
@@ -327,6 +336,16 @@ export interface AssignPayload {
 	branch: string;
 }
 
+/** Agent pauses for a human-in-the-loop decision before proceeding. */
+export interface DecisionGatePayload {
+	/** Options for the human decision-maker to choose from. */
+	options: string[];
+	/** Context explaining why the decision is needed. */
+	context: string;
+	/** Optional deadline for the decision (ISO timestamp). */
+	deadline?: string;
+}
+
 /** Maps protocol message types to their payload interfaces. */
 export interface MailPayloadMap {
 	worker_done: WorkerDonePayload;
@@ -337,6 +356,7 @@ export interface MailPayloadMap {
 	health_check: HealthCheckPayload;
 	dispatch: DispatchPayload;
 	assign: AssignPayload;
+	decision_gate: DecisionGatePayload;
 }
 
 // === Overlay ===
@@ -355,6 +375,8 @@ export interface OverlayConfig {
 	capability: string;
 	/** Full content of the base agent definition file (Layer 1: role-specific HOW). */
 	baseDefinition: string;
+	/** Rendered profile content from canopy (Layer 2: deployment-specific WHAT KIND). Inserted between base definition and assignment. */
+	profileContent?: string;
 	/** Pre-fetched mulch expertise output to embed directly in the overlay. */
 	mulchExpertise?: string;
 	/** When true, lead agents should skip Phase 1 (scout) and go straight to Phase 2 (build). */
@@ -714,6 +736,48 @@ export interface MulchCompactResult {
 	message?: string;
 }
 
+// === Canopy CLI Results ===
+
+/** A single section within a rendered canopy prompt. */
+export interface CanopyPromptSection {
+	name: string;
+	body: string;
+}
+
+/** Summary of a canopy prompt as returned by list/show. */
+export interface CanopyPromptSummary {
+	id: string;
+	name: string;
+	version: number;
+	sections: CanopyPromptSection[];
+}
+
+/** Result from cn render — resolved prompt with all inheritance applied. */
+export interface CanopyRenderResult {
+	success: boolean;
+	name: string;
+	version: number;
+	sections: CanopyPromptSection[];
+}
+
+/** Result from cn validate — validation status and errors. */
+export interface CanopyValidateResult {
+	success: boolean;
+	errors: string[];
+}
+
+/** Result from cn list — list of all prompts. */
+export interface CanopyListResult {
+	success: boolean;
+	prompts: CanopyPromptSummary[];
+}
+
+/** Result from cn show — single prompt record. */
+export interface CanopyShowResult {
+	success: boolean;
+	prompt: CanopyPromptSummary;
+}
+
 // === Session Lifecycle (Checkpoint / Handoff / Continuity) ===
 
 /**

package/src/utils/bin.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from "bun:test";
+import { resolveOverstoryBin } from "./bin.ts";
+
+describe("resolveOverstoryBin", () => {
+	test("returns a non-empty string", async () => {
+		const bin = await resolveOverstoryBin();
+		expect(typeof bin).toBe("string");
+		expect(bin.length).toBeGreaterThan(0);
+	});
+});

package/src/utils/bin.ts

@@ -0,0 +1,37 @@
+/**
+ * Binary resolution utilities.
+ */
+import { OverstoryError } from "../errors.ts";
+
+/**
+ * Resolve the path to the overstory binary for re-launching.
+ * Uses `which ov` first, then falls back to process.argv.
+ */
+export async function resolveOverstoryBin(): Promise<string> {
+	try {
+		const proc = Bun.spawn(["which", "ov"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+		if (exitCode === 0) {
+			const binPath = (await new Response(proc.stdout).text()).trim();
+			if (binPath.length > 0) {
+				return binPath;
+			}
+		}
+	} catch {
+		// which not available or overstory not on PATH
+	}
+
+	// Fallback: use the script that's currently running (process.argv[1])
+	const scriptPath = process.argv[1];
+	if (scriptPath) {
+		return scriptPath;
+	}
+
+	throw new OverstoryError(
+		"Cannot resolve overstory binary path for background launch",
+		"WATCH_ERROR",
+	);
+}

package/src/utils/fs.test.ts

@@ -0,0 +1,119 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import { clearDirectory, deleteFile, resetJsonFile, wipeSqliteDb } from "./fs.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+	tempDir = await mkdtemp(join(tmpdir(), "ov-fs-test-"));
+});
+
+afterEach(async () => {
+	await cleanupTempDir(tempDir);
+});
+
+describe("wipeSqliteDb", () => {
+	test("deletes main db and WAL/SHM companion files", async () => {
+		const dbPath = join(tempDir, "test-wipe.db");
+		const { Database } = await import("bun:sqlite");
+		const db = new Database(dbPath);
+		db.exec("PRAGMA journal_mode=WAL");
+		db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY)");
+		db.exec("INSERT INTO t VALUES (1)");
+		db.close();
+
+		expect(existsSync(dbPath)).toBe(true);
+
+		const result = await wipeSqliteDb(dbPath);
+		expect(result).toBe(true);
+
+		expect(existsSync(dbPath)).toBe(false);
+		expect(existsSync(`${dbPath}-wal`)).toBe(false);
+		expect(existsSync(`${dbPath}-shm`)).toBe(false);
+	});
+
+	test("returns false when db file does not exist", async () => {
+		const dbPath = join(tempDir, "nonexistent.db");
+		const result = await wipeSqliteDb(dbPath);
+		expect(result).toBe(false);
+	});
+});
+
+describe("resetJsonFile", () => {
+	test("resets existing JSON file to empty array", async () => {
+		const filePath = join(tempDir, "test-reset.json");
+		await Bun.write(filePath, '[{"id":"1"},{"id":"2"}]');
+
+		const result = await resetJsonFile(filePath);
+		expect(result).toBe(true);
+
+		const content = await Bun.file(filePath).text();
+		expect(content).toBe("[]\n");
+	});
+
+	test("returns false for nonexistent file", async () => {
+		const filePath = join(tempDir, "nonexistent.json");
+		const result = await resetJsonFile(filePath);
+		expect(result).toBe(false);
+	});
+});
+
+describe("clearDirectory", () => {
+	test("clears files from a directory", async () => {
+		const dirPath = join(tempDir, "clear-test");
+		await mkdir(dirPath, { recursive: true });
+		await writeFile(join(dirPath, "file1.txt"), "hello");
+		await writeFile(join(dirPath, "file2.txt"), "world");
+
+		const result = await clearDirectory(dirPath);
+		expect(result).toBe(true);
+
+		const entries = await readdir(dirPath);
+		expect(entries).toHaveLength(0);
+	});
+
+	test("returns false for empty directory", async () => {
+		const dirPath = join(tempDir, "empty-dir");
+		await mkdir(dirPath, { recursive: true });
+
+		const result = await clearDirectory(dirPath);
+		expect(result).toBe(false);
+	});
+
+	test("returns false for nonexistent directory", async () => {
+		const result = await clearDirectory(join(tempDir, "no-such-dir"));
+		expect(result).toBe(false);
+	});
+
+	test("recursively removes subdirectories", async () => {
+		const dirPath = join(tempDir, "nested-clear");
+		await mkdir(join(dirPath, "sub", "deep"), { recursive: true });
+		await writeFile(join(dirPath, "sub", "deep", "file.txt"), "data");
+
+		const result = await clearDirectory(dirPath);
+		expect(result).toBe(true);
+
+		const entries = await readdir(dirPath);
+		expect(entries).toHaveLength(0);
+	});
+});
+
+describe("deleteFile", () => {
+	test("deletes an existing file", async () => {
+		const filePath = join(tempDir, "to-delete.txt");
+		await writeFile(filePath, "delete me");
+
+		const result = await deleteFile(filePath);
+		expect(result).toBe(true);
+		expect(existsSync(filePath)).toBe(false);
+	});
+
+	test("returns false for nonexistent file", async () => {
+		const result = await deleteFile(join(tempDir, "no-such-file.txt"));
+		expect(result).toBe(false);
+	});
+});

package/src/utils/fs.ts

@@ -0,0 +1,62 @@
+/**
+ * Filesystem utility functions for cleanup and state management.
+ */
+import { readdir, rm, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Delete a SQLite database file and its WAL/SHM companions.
+ */
+export async function wipeSqliteDb(dbPath: string): Promise<boolean> {
+	const extensions = ["", "-wal", "-shm"];
+	let wiped = false;
+	for (const ext of extensions) {
+		try {
+			await unlink(`${dbPath}${ext}`);
+			if (ext === "") wiped = true;
+		} catch {
+			// File may not exist
+		}
+	}
+	return wiped;
+}
+
+/**
+ * Reset a JSON file to an empty array.
+ */
+export async function resetJsonFile(path: string): Promise<boolean> {
+	const file = Bun.file(path);
+	if (await file.exists()) {
+		await Bun.write(path, "[]\n");
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Clear all entries inside a directory but keep the directory itself.
+ */
+export async function clearDirectory(dirPath: string): Promise<boolean> {
+	try {
+		const entries = await readdir(dirPath);
+		for (const entry of entries) {
+			await rm(join(dirPath, entry), { recursive: true, force: true });
+		}
+		return entries.length > 0;
+	} catch {
+		// Directory may not exist
+		return false;
+	}
+}
+
+/**
+ * Delete a single file if it exists.
+ */
+export async function deleteFile(path: string): Promise<boolean> {
+	try {
+		await unlink(path);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/utils/pid.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { cleanupTempDir } from "../test-helpers.ts";
+import { readPidFile, removePidFile, writePidFile } from "./pid.ts";
+
+let tempDir: string;
+
+beforeEach(async () => {
+	tempDir = await mkdtemp(join(tmpdir(), "ov-pid-test-"));
+});
+
+afterEach(async () => {
+	await cleanupTempDir(tempDir);
+});
+
+describe("readPidFile", () => {
+	test("returns pid from valid file", async () => {
+		const pidPath = join(tempDir, "test.pid");
+		await Bun.write(pidPath, "12345\n");
+		const pid = await readPidFile(pidPath);
+		expect(pid).toBe(12345);
+	});
+
+	test("returns null for nonexistent file", async () => {
+		const pid = await readPidFile(join(tempDir, "missing.pid"));
+		expect(pid).toBeNull();
+	});
+
+	test("returns null for non-numeric content", async () => {
+		const pidPath = join(tempDir, "bad.pid");
+		await Bun.write(pidPath, "not-a-number\n");
+		const pid = await readPidFile(pidPath);
+		expect(pid).toBeNull();
+	});
+
+	test("returns null for negative pid", async () => {
+		const pidPath = join(tempDir, "neg.pid");
+		await Bun.write(pidPath, "-1\n");
+		const pid = await readPidFile(pidPath);
+		expect(pid).toBeNull();
+	});
+});
+
+describe("writePidFile", () => {
+	test("roundtrip write then read", async () => {
+		const pidPath = join(tempDir, "roundtrip.pid");
+		await writePidFile(pidPath, 42);
+		const pid = await readPidFile(pidPath);
+		expect(pid).toBe(42);
+	});
+});
+
+describe("removePidFile", () => {
+	test("removes existing file", async () => {
+		const pidPath = join(tempDir, "remove.pid");
+		await Bun.write(pidPath, "99\n");
+		expect(await Bun.file(pidPath).exists()).toBe(true);
+		await removePidFile(pidPath);
+		expect(await Bun.file(pidPath).exists()).toBe(false);
+	});
+
+	test("does not throw for nonexistent file", async () => {
+		await removePidFile(join(tempDir, "nope.pid"));
+		// No throw = pass
+	});
+});

package/src/utils/pid.ts

@@ -0,0 +1,45 @@
+/**
+ * PID file management for daemon processes.
+ */
+import { unlink } from "node:fs/promises";
+
+/**
+ * Read the PID from a PID file.
+ * Returns null if the file doesn't exist or can't be parsed.
+ */
+export async function readPidFile(pidFilePath: string): Promise<number | null> {
+	const file = Bun.file(pidFilePath);
+	const exists = await file.exists();
+	if (!exists) {
+		return null;
+	}
+
+	try {
+		const text = await file.text();
+		const pid = Number.parseInt(text.trim(), 10);
+		if (Number.isNaN(pid) || pid <= 0) {
+			return null;
+		}
+		return pid;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Write a PID to a PID file.
+ */
+export async function writePidFile(pidFilePath: string, pid: number): Promise<void> {
+	await Bun.write(pidFilePath, `${pid}\n`);
+}
+
+/**
+ * Remove a PID file.
+ */
+export async function removePidFile(pidFilePath: string): Promise<void> {
+	try {
+		await unlink(pidFilePath);
+	} catch {
+		// File may already be gone — not an error
+	}
+}

package/src/utils/time.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { parseRelativeTime } from "./time.ts";
+
+describe("parseRelativeTime", () => {
+	test("parses '30s' as ~30 seconds ago", () => {
+		const before = Date.now();
+		const result = parseRelativeTime("30s");
+		const after = Date.now();
+		expect(result.getTime()).toBeGreaterThanOrEqual(before - 30 * 1000 - 50);
+		expect(result.getTime()).toBeLessThanOrEqual(after - 30 * 1000 + 50);
+	});
+
+	test("parses '5m' as ~5 minutes ago", () => {
+		const before = Date.now();
+		const result = parseRelativeTime("5m");
+		const expected = before - 5 * 60 * 1000;
+		expect(Math.abs(result.getTime() - expected)).toBeLessThan(100);
+	});
+
+	test("parses '2h' as ~2 hours ago", () => {
+		const before = Date.now();
+		const result = parseRelativeTime("2h");
+		const expected = before - 2 * 60 * 60 * 1000;
+		expect(Math.abs(result.getTime() - expected)).toBeLessThan(100);
+	});
+
+	test("parses '1d' as ~1 day ago", () => {
+		const before = Date.now();
+		const result = parseRelativeTime("1d");
+		const expected = before - 24 * 60 * 60 * 1000;
+		expect(Math.abs(result.getTime() - expected)).toBeLessThan(100);
+	});
+
+	test("parses ISO 8601 timestamp", () => {
+		const result = parseRelativeTime("2026-01-15T10:30:00.000Z");
+		expect(result.toISOString()).toBe("2026-01-15T10:30:00.000Z");
+	});
+
+	test("returns invalid Date for garbage input", () => {
+		const result = parseRelativeTime("not-a-time");
+		expect(Number.isNaN(result.getTime())).toBe(true);
+	});
+});

package/src/utils/time.ts

@@ -0,0 +1,37 @@
+/**
+ * Time parsing utilities.
+ */
+
+/**
+ * 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.
+ */
+export 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);
+}

package/src/utils/version.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { fetchLatestVersion, getCurrentVersion, getInstalledVersion } from "./version.ts";
+
+describe("getCurrentVersion", () => {
+	test("returns a semver string", async () => {
+		const version = await getCurrentVersion();
+		expect(version).toMatch(/^\d+\.\d+\.\d+/);
+	});
+});
+
+describe("fetchLatestVersion", () => {
+	test("fetches a semver string from npm registry", async () => {
+		const version = await fetchLatestVersion("@os-eco/overstory-cli");
+		expect(version).toMatch(/^\d+\.\d+\.\d+/);
+	});
+
+	test("throws for nonexistent package", async () => {
+		await expect(fetchLatestVersion("@nonexistent/package-xyz-999")).rejects.toThrow();
+	});
+});
+
+describe("getInstalledVersion", () => {
+	test("returns version for an installed CLI (bun)", async () => {
+		const version = await getInstalledVersion("bun");
+		expect(version).not.toBeNull();
+		expect(version).toMatch(/^\d+\.\d+\.\d+/);
+	});
+
+	test("returns null for nonexistent CLI", async () => {
+		const version = await getInstalledVersion("nonexistent-cli-xyz-999");
+		expect(version).toBeNull();
+	});
+});

package/src/utils/version.ts

@@ -0,0 +1,70 @@
+/**
+ * Version detection and npm registry utilities.
+ */
+
+/**
+ * Get the current installed version of overstory from package.json.
+ */
+export 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;
+}
+
+/**
+ * Fetch the latest published version of an npm package from the registry.
+ */
+export 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;
+}
+
+/**
+ * Get the installed version of a CLI tool by running `--version`.
+ * Tries `--version --json` first, then falls back to plain text.
+ */
+export async function getInstalledVersion(cli: string): Promise<string | null> {
+	// Try --version --json first
+	try {
+		const proc = Bun.spawn([cli, "--version", "--json"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+		if (exitCode === 0) {
+			const stdout = await new Response(proc.stdout).text();
+			try {
+				const data = JSON.parse(stdout.trim()) as { version?: string };
+				if (data.version) return data.version;
+			} catch {
+				// Not valid JSON, fall through to plain text
+			}
+		}
+	} catch {
+		// CLI not found — fall through to plain text fallback
+	}
+
+	// Fallback: --version plain text
+	try {
+		const proc = Bun.spawn([cli, "--version"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+		if (exitCode === 0) {
+			const stdout = await new Response(proc.stdout).text();
+			const match = stdout.match(/(\d+\.\d+\.\d+)/);
+			if (match?.[1]) return match[1];
+		}
+	} catch {
+		// CLI not found
+	}
+
+	return null;
+}