@os-eco/overstory-cli 0.7.9 → 0.8.2

package/src/commands/update.ts

@@ -0,0 +1,263 @@
+/**
+ * CLI command: ov update [--agents] [--manifest] [--hooks] [--dry-run] [--json]
+ *
+ * Refreshes .overstory/ managed files from the installed npm package without
+ * requiring a full `ov init`. Distinct from `ov upgrade` (which updates the
+ * npm package itself).
+ *
+ * Managed files refreshed:
+ * - Agent definitions (.overstory/agent-defs/*.md)
+ * - agent-manifest.json
+ * - hooks.json
+ * - .gitignore
+ * - README.md
+ *
+ * Does NOT touch: config.yaml, config.local.yaml, SQLite databases,
+ * agents/, worktrees/, specs/, logs/, or .claude/settings.local.json.
+ */
+
+import { mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { Command } from "commander";
+import { ValidationError } from "../errors.ts";
+import { jsonOutput } from "../json.ts";
+import { printHint, printSuccess } from "../logging/color.ts";
+import {
+	buildAgentManifest,
+	buildHooksJson,
+	OVERSTORY_GITIGNORE,
+	OVERSTORY_README,
+	writeOverstoryGitignore,
+	writeOverstoryReadme,
+} from "./init.ts";
+
+export interface UpdateOptions {
+	agents?: boolean;
+	manifest?: boolean;
+	hooks?: boolean;
+	dryRun?: boolean;
+	json?: boolean;
+}
+
+/** Agent def files to exclude (deprecated). */
+const EXCLUDED_AGENT_DEFS = new Set(["supervisor.md"]);
+
+interface UpdateResult {
+	agentDefs: { updated: string[]; unchanged: string[] };
+	manifest: { updated: boolean };
+	hooks: { updated: boolean };
+	gitignore: { updated: boolean };
+	readme: { updated: boolean };
+}
+
+/**
+ * Entry point for `ov update [flags]`.
+ */
+export async function executeUpdate(opts: UpdateOptions): Promise<void> {
+	const json = opts.json ?? false;
+	const dryRun = opts.dryRun ?? false;
+
+	const projectRoot = process.cwd();
+	const overstoryDir = join(projectRoot, ".overstory");
+
+	// Verify .overstory/config.yaml exists (already initialized)
+	const configFile = Bun.file(join(overstoryDir, "config.yaml"));
+	if (!(await configFile.exists())) {
+		throw new ValidationError("Not initialized. Run 'ov init' first to set up .overstory/.", {
+			field: "config.yaml",
+		});
+	}
+
+	// Determine what to refresh. No flags = refresh all.
+	const hasGranularFlags = opts.agents || opts.manifest || opts.hooks;
+	const doAgents = hasGranularFlags ? (opts.agents ?? false) : true;
+	const doManifest = hasGranularFlags ? (opts.manifest ?? false) : true;
+	const doHooks = hasGranularFlags ? (opts.hooks ?? false) : true;
+	const doGitignore = !hasGranularFlags;
+	const doReadme = !hasGranularFlags;
+
+	const result: UpdateResult = {
+		agentDefs: { updated: [], unchanged: [] },
+		manifest: { updated: false },
+		hooks: { updated: false },
+		gitignore: { updated: false },
+		readme: { updated: false },
+	};
+
+	// 1. Refresh agent definitions
+	if (doAgents) {
+		const sourceDir = join(import.meta.dir, "..", "..", "agents");
+		const targetDir = join(overstoryDir, "agent-defs");
+
+		await mkdir(targetDir, { recursive: true });
+
+		const sourceFiles = await readdir(sourceDir);
+		for (const fileName of sourceFiles) {
+			if (!fileName.endsWith(".md")) continue;
+			if (EXCLUDED_AGENT_DEFS.has(fileName)) continue;
+
+			const sourceContent = await Bun.file(join(sourceDir, fileName)).text();
+			const targetPath = join(targetDir, fileName);
+			const targetFile = Bun.file(targetPath);
+
+			let needsUpdate = true;
+			if (await targetFile.exists()) {
+				const existing = await targetFile.text();
+				if (existing === sourceContent) {
+					needsUpdate = false;
+				}
+			}
+
+			if (needsUpdate) {
+				if (!dryRun) {
+					await Bun.write(targetPath, sourceContent);
+				}
+				result.agentDefs.updated.push(fileName);
+			} else {
+				result.agentDefs.unchanged.push(fileName);
+			}
+		}
+	}
+
+	// 2. Refresh agent-manifest.json
+	if (doManifest) {
+		const manifestPath = join(overstoryDir, "agent-manifest.json");
+		const newContent = `${JSON.stringify(buildAgentManifest(), null, "\t")}\n`;
+		const manifestFile = Bun.file(manifestPath);
+
+		let needsUpdate = true;
+		if (await manifestFile.exists()) {
+			const existing = await manifestFile.text();
+			if (existing === newContent) {
+				needsUpdate = false;
+			}
+		}
+
+		if (needsUpdate) {
+			if (!dryRun) {
+				await Bun.write(manifestPath, newContent);
+			}
+			result.manifest.updated = true;
+		}
+	}
+
+	// 3. Refresh hooks.json
+	if (doHooks) {
+		const hooksPath = join(overstoryDir, "hooks.json");
+		const newContent = buildHooksJson();
+		const hooksFile = Bun.file(hooksPath);
+
+		let needsUpdate = true;
+		if (await hooksFile.exists()) {
+			const existing = await hooksFile.text();
+			if (existing === newContent) {
+				needsUpdate = false;
+			}
+		}
+
+		if (needsUpdate) {
+			if (!dryRun) {
+				await Bun.write(hooksPath, newContent);
+			}
+			result.hooks.updated = true;
+		}
+	}
+
+	// 4. Refresh .gitignore
+	if (doGitignore) {
+		const gitignorePath = join(overstoryDir, ".gitignore");
+		const gitignoreFile = Bun.file(gitignorePath);
+
+		let needsUpdate = true;
+		if (await gitignoreFile.exists()) {
+			const existing = await gitignoreFile.text();
+			if (existing === OVERSTORY_GITIGNORE) {
+				needsUpdate = false;
+			}
+		}
+
+		if (needsUpdate) {
+			if (!dryRun) {
+				await writeOverstoryGitignore(overstoryDir);
+			}
+			result.gitignore.updated = true;
+		}
+	}
+
+	// 5. Refresh README.md
+	if (doReadme) {
+		const readmePath = join(overstoryDir, "README.md");
+		const readmeFile = Bun.file(readmePath);
+
+		let needsUpdate = true;
+		if (await readmeFile.exists()) {
+			const existing = await readmeFile.text();
+			if (existing === OVERSTORY_README) {
+				needsUpdate = false;
+			}
+		}
+
+		if (needsUpdate) {
+			if (!dryRun) {
+				await writeOverstoryReadme(overstoryDir);
+			}
+			result.readme.updated = true;
+		}
+	}
+
+	// Output
+	if (json) {
+		jsonOutput("update", { dryRun, ...result });
+		return;
+	}
+
+	const prefix = dryRun ? "Would update" : "Updated";
+	let anyChanged = false;
+
+	if (result.agentDefs.updated.length > 0) {
+		anyChanged = true;
+		for (const f of result.agentDefs.updated) {
+			printSuccess(prefix, `agent-defs/${f}`);
+		}
+	}
+
+	if (result.manifest.updated) {
+		anyChanged = true;
+		printSuccess(prefix, "agent-manifest.json");
+	}
+
+	if (result.hooks.updated) {
+		anyChanged = true;
+		printSuccess(prefix, "hooks.json");
+		if (!dryRun) {
+			printHint("If hooks are deployed, run 'ov hooks install --force' to redeploy");
+		}
+	}
+
+	if (result.gitignore.updated) {
+		anyChanged = true;
+		printSuccess(prefix, ".gitignore");
+	}
+
+	if (result.readme.updated) {
+		anyChanged = true;
+		printSuccess(prefix, "README.md");
+	}
+
+	if (!anyChanged) {
+		printSuccess("Already up to date");
+	}
+}
+
+export function createUpdateCommand(): Command {
+	return new Command("update")
+		.description("Refresh .overstory/ managed files from the installed package")
+		.option("--agents", "Refresh agent definition files only")
+		.option("--manifest", "Refresh agent-manifest.json only")
+		.option("--hooks", "Refresh hooks.json only")
+		.option("--dry-run", "Show what would change without writing")
+		.option("--json", "Output as JSON")
+		.action(async (opts: UpdateOptions) => {
+			await executeUpdate(opts);
+		});
+}

package/src/config.test.ts

@@ -2,7 +2,14 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, realpath } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { DEFAULT_CONFIG, DEFAULT_QUALITY_GATES, loadConfig, resolveProjectRoot } from "./config.ts";
+import {
+	clearProjectRootOverride,
+	DEFAULT_CONFIG,
+	DEFAULT_QUALITY_GATES,
+	loadConfig,
+	resolveProjectRoot,
+	setProjectRootOverride,
+} from "./config.ts";
 import { ValidationError } from "./errors.ts";
 import { cleanupTempDir, createTempGitRepo, runGitInDir } from "./test-helpers.ts";
 
@@ -961,6 +968,63 @@ describe("resolveProjectRoot", () => {
 	});
 });
 
+describe("projectRootOverride", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-test-"));
+		clearProjectRootOverride();
+	});
+
+	afterEach(async () => {
+		clearProjectRootOverride();
+		await cleanupTempDir(tempDir);
+	});
+
+	test("setProjectRootOverride makes resolveProjectRoot return the override", async () => {
+		setProjectRootOverride(tempDir);
+		const result = await resolveProjectRoot("/some/other/dir");
+		expect(result).toBe(tempDir);
+	});
+
+	test("clearProjectRootOverride restores normal resolution", async () => {
+		setProjectRootOverride("/completely/fake/path");
+		clearProjectRootOverride();
+		// After clearing, normal resolution returns startDir when no .overstory present
+		const result = await resolveProjectRoot(tempDir);
+		expect(result).toBe(tempDir);
+	});
+
+	test("loadConfig respects project root override", async () => {
+		await mkdir(join(tempDir, ".overstory"), { recursive: true });
+		await Bun.write(
+			join(tempDir, ".overstory", "config.yaml"),
+			"project:\n  canonicalBranch: override-branch\n",
+		);
+		setProjectRootOverride(tempDir);
+		const config = await loadConfig("/completely/different/path");
+		expect(config.project.root).toBe(tempDir);
+		expect(config.project.canonicalBranch).toBe("override-branch");
+	});
+
+	test("override takes precedence over worktree resolution", async () => {
+		// Even if we're in a worktree, the override wins
+		const otherDir = await mkdtemp(join(tmpdir(), "overstory-other-"));
+		try {
+			await mkdir(join(otherDir, ".overstory"), { recursive: true });
+			await Bun.write(
+				join(otherDir, ".overstory", "config.yaml"),
+				"project:\n  canonicalBranch: other-branch\n",
+			);
+			setProjectRootOverride(otherDir);
+			const result = await resolveProjectRoot(tempDir);
+			expect(result).toBe(otherDir);
+		} finally {
+			await cleanupTempDir(otherDir);
+		}
+	});
+});
+
 describe("DEFAULT_CONFIG", () => {
 	test("has all required top-level keys", () => {
 		expect(DEFAULT_CONFIG.project).toBeDefined();

package/src/config.ts

@@ -2,6 +2,24 @@ import { dirname, join, resolve } from "node:path";
 import { ConfigError, ValidationError } from "./errors.ts";
 import type { OverstoryConfig, QualityGate, TaskTrackerBackend } from "./types.ts";
 
+// Module-level project root override (set by --project global flag)
+let _projectRootOverride: string | undefined;
+
+/** Override project root for all config resolution (used by --project global flag). */
+export function setProjectRootOverride(path: string): void {
+	_projectRootOverride = path;
+}
+
+/** Get the current project root override, if any. */
+export function getProjectRootOverride(): string | undefined {
+	return _projectRootOverride;
+}
+
+/** Clear the project root override (used in tests and cleanup). */
+export function clearProjectRootOverride(): void {
+	_projectRootOverride = undefined;
+}
+
 /**
  * Default configuration with all fields populated.
  * Used as the base; file-loaded values are merged on top.
@@ -777,6 +795,11 @@ async function mergeLocalConfig(
  * @returns The resolved project root containing `.overstory/`
  */
 export async function resolveProjectRoot(startDir: string): Promise<string> {
+	// Check for explicit override first (set by --project global flag)
+	if (_projectRootOverride !== undefined) {
+		return _projectRootOverride;
+	}
+
 	const { existsSync } = require("node:fs") as typeof import("node:fs");
 
 	// Check git worktree FIRST. When running from an agent worktree

package/src/e2e/init-sling-lifecycle.test.ts

@@ -30,6 +30,7 @@ const EXPECTED_AGENT_DEFS = [
 	"lead.md",
 	"merger.md",
 	"monitor.md",
+	"orchestrator.md",
 	"reviewer.md",
 	"scout.md",
 ];
@@ -81,7 +82,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 		const gitignoreFile = Bun.file(join(overstoryDir, ".gitignore"));
 		expect(await gitignoreFile.exists()).toBe(true);
 
-		// agent-defs/ contains all 7 agent definition files (supervisor deprecated)
+		// agent-defs/ contains all 8 agent definition files (supervisor deprecated)
 		const agentDefsDir = join(overstoryDir, "agent-defs");
 		const agentDefFiles = (await readdir(agentDefsDir)).filter((f) => f.endsWith(".md")).sort();
 		expect(agentDefFiles).toEqual(EXPECTED_AGENT_DEFS);
@@ -113,7 +114,7 @@ describe("E2E: init→sling lifecycle on external project", () => {
 		expect(config.project.name).toBeTruthy();
 	});
 
-	test("manifest loads successfully with all 7 agents (supervisor deprecated)", async () => {
+	test("manifest loads successfully with all 8 agents (supervisor deprecated)", async () => {
 		await initCommand({ _spawner: noopSpawner });
 
 		const manifestPath = join(tempDir, ".overstory", "agent-manifest.json");

package/src/index.ts

@@ -7,6 +7,8 @@
  * Usage: ov <command> [args...]
  */
 
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { Command, Help } from "commander";
 import { createAgentsCommand } from "./commands/agents.ts";
 import { cleanCommand } from "./commands/clean.ts";
@@ -38,14 +40,16 @@ 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 { createUpdateCommand } from "./commands/update.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 { setProjectRootOverride } from "./config.ts";
+import { ConfigError, OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.7.9";
+export const VERSION = "0.8.2";
 
 const rawArgs = process.argv.slice(2);
 
@@ -95,6 +99,7 @@ const COMMANDS = [
 	"run",
 	"costs",
 	"metrics",
+	"update",
 	"upgrade",
 	"completions",
 ];
@@ -144,6 +149,7 @@ program
 	.option("--json", "JSON output")
 	.option("--verbose", "Verbose output")
 	.option("--timing", "Print command execution time to stderr")
+	.option("--project <path>", "Target project root (overrides auto-detection)")
 	.addHelpCommand(false)
 	.configureHelp({
 		formatHelp(cmd, helper): string {
@@ -199,6 +205,17 @@ program.hook("preAction", (thisCmd) => {
 	if (opts.quiet) {
 		setQuiet(true);
 	}
+	const projectFlag = opts.project as string | undefined;
+	if (projectFlag !== undefined) {
+		const resolvedProject = resolve(process.cwd(), projectFlag);
+		if (!existsSync(join(resolvedProject, ".overstory", "config.yaml"))) {
+			throw new ConfigError(
+				`'${resolvedProject}' is not an overstory project (missing .overstory/config.yaml). Run 'ov init' first.`,
+				{ configPath: join(resolvedProject, ".overstory", "config.yaml") },
+			);
+		}
+		setProjectRootOverride(resolvedProject);
+	}
 	if (opts.timing) {
 		timingStart = performance.now();
 	}
@@ -390,6 +407,8 @@ program.addCommand(createCostsCommand());
 
 program.addCommand(createMetricsCommand());
 
+program.addCommand(createUpdateCommand());
+
 program.addCommand(createUpgradeCommand());
 
 // Handle unknown commands with Levenshtein fuzzy-match suggestions

package/src/logging/theme.ts

@@ -66,6 +66,10 @@ const EVENT_LABELS: Record<EventType, EventLabel> = {
 	spawn: { compact: "SPAWN", full: "SPAWN     ", color: color.magenta },
 	error: { compact: "ERROR", full: "ERROR     ", color: color.red },
 	custom: { compact: "CUSTM", full: "CUSTOM    ", color: color.gray },
+	turn_start: { compact: "TURN+", full: "TURN START", color: color.green },
+	turn_end: { compact: "TURN-", full: "TURN END  ", color: color.yellow },
+	progress: { compact: "PROG ", full: "PROGRESS  ", color: color.cyan },
+	result: { compact: "RSULT", full: "RESULT    ", color: color.green },
 };
 
 /** Returns the EventLabel for a given event type. */

package/src/runtimes/connections.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { getConnection, removeConnection, setConnection } from "./connections.ts";
+import type { ConnectionState, RuntimeConnection } from "./types.ts";
+
+/** Minimal RuntimeConnection stub for testing the registry. */
+function makeConn(onClose?: () => void): RuntimeConnection {
+	return {
+		sendPrompt: async (_text: string) => {},
+		followUp: async (_text: string) => {},
+		abort: async () => {},
+		getState: async (): Promise<ConnectionState> => ({ status: "idle" }),
+		close: () => {
+			if (onClose) onClose();
+		},
+	};
+}
+
+describe("connection registry", () => {
+	// Reset registry between tests by removing any entries set during each test.
+	// We track names used so we can clean up without affecting other entries.
+	const usedNames: string[] = [];
+
+	afterEach(() => {
+		for (const name of usedNames.splice(0)) {
+			const conn = getConnection(name);
+			if (conn) {
+				removeConnection(name);
+			}
+		}
+	});
+
+	test("set and get returns the registered connection", () => {
+		const conn = makeConn();
+		usedNames.push("agent-alpha");
+		setConnection("agent-alpha", conn);
+		expect(getConnection("agent-alpha")).toBe(conn);
+	});
+
+	test("get unknown returns undefined", () => {
+		expect(getConnection("does-not-exist-xyz")).toBeUndefined();
+	});
+
+	test("removeConnection calls close() on the connection", () => {
+		let closed = false;
+		const conn = makeConn(() => {
+			closed = true;
+		});
+		usedNames.push("agent-beta");
+		setConnection("agent-beta", conn);
+		removeConnection("agent-beta");
+		expect(closed).toBe(true);
+	});
+
+	test("removeConnection deletes the entry (get returns undefined after)", () => {
+		const conn = makeConn();
+		usedNames.push("agent-gamma");
+		setConnection("agent-gamma", conn);
+		removeConnection("agent-gamma");
+		expect(getConnection("agent-gamma")).toBeUndefined();
+	});
+
+	test("removeConnection on unknown name is a no-op (does not throw)", () => {
+		expect(() => removeConnection("never-registered-xyz")).not.toThrow();
+	});
+
+	test("setConnection overwrites an existing entry", () => {
+		const conn1 = makeConn();
+		const conn2 = makeConn();
+		usedNames.push("agent-delta");
+		setConnection("agent-delta", conn1);
+		setConnection("agent-delta", conn2);
+		expect(getConnection("agent-delta")).toBe(conn2);
+	});
+});

package/src/runtimes/connections.ts

@@ -0,0 +1,34 @@
+/**
+ * Module-level connection registry for active RuntimeConnection instances.
+ *
+ * Tracks RPC connections to headless agent processes (e.g., Sapling).
+ * Keyed by agent name — same namespace as AgentSession.agentName.
+ *
+ * Thread safety: single-threaded Bun runtime; no locking needed.
+ */
+
+import type { RuntimeConnection } from "./types.ts";
+
+const connections = new Map<string, RuntimeConnection>();
+
+/** Retrieve the active connection for a given agent, or undefined if none. */
+export function getConnection(agentName: string): RuntimeConnection | undefined {
+	return connections.get(agentName);
+}
+
+/** Register a connection for a given agent. Overwrites any existing entry. */
+export function setConnection(agentName: string, conn: RuntimeConnection): void {
+	connections.set(agentName, conn);
+}
+
+/**
+ * Remove the connection for a given agent, calling close() first.
+ * Safe to call if no connection exists (no-op).
+ */
+export function removeConnection(agentName: string): void {
+	const conn = connections.get(agentName);
+	if (conn) {
+		conn.close();
+		connections.delete(agentName);
+	}
+}

package/src/runtimes/registry.test.ts

@@ -22,7 +22,7 @@ describe("getRuntime", () => {
 
 	it("throws with a helpful message for an unknown runtime", () => {
 		expect(() => getRuntime("unknown-runtime")).toThrow(
-			'Unknown runtime: "unknown-runtime". Available: claude, codex, pi, copilot, gemini',
+			'Unknown runtime: "unknown-runtime". Available: claude, codex, pi, copilot, gemini, sapling',
 		);
 	});
 

package/src/runtimes/registry.ts

@@ -7,6 +7,7 @@ import { CodexRuntime } from "./codex.ts";
 import { CopilotRuntime } from "./copilot.ts";
 import { GeminiRuntime } from "./gemini.ts";
 import { PiRuntime } from "./pi.ts";
+import { SaplingRuntime } from "./sapling.ts";
 import type { AgentRuntime } from "./types.ts";
 
 /** Registry of config-independent runtime adapters (name → factory). */
@@ -16,6 +17,7 @@ const runtimes = new Map<string, () => AgentRuntime>([
 	["pi", () => new PiRuntime()],
 	["copilot", () => new CopilotRuntime()],
 	["gemini", () => new GeminiRuntime()],
+	["sapling", () => new SaplingRuntime()],
 ]);
 
 /**