@os-eco/overstory-cli 0.8.7 → 0.9.2

package/src/commands/coordinator.ts

@@ -46,6 +46,24 @@ import { isRunningAsRoot } from "./sling.ts";
 /** Default coordinator agent name. */
 const COORDINATOR_NAME = "coordinator";
 
+export interface PersistentAgentSpec {
+	commandName: string;
+	displayName: string;
+	agentName: string;
+	capability: string;
+	agentDefFile: string;
+	beaconBuilder: (trackerCli: string) => string;
+}
+
+const COORDINATOR_SPEC: PersistentAgentSpec = {
+	commandName: "coordinator",
+	displayName: "Coordinator",
+	agentName: COORDINATOR_NAME,
+	capability: "coordinator",
+	agentDefFile: "coordinator.md",
+	beaconBuilder: buildCoordinatorBeacon,
+};
+
 /** Poll interval for the ask subcommand reply loop. */
 const ASK_POLL_INTERVAL_MS = 2_000;
 
@@ -56,8 +74,8 @@ const ASK_DEFAULT_TIMEOUT_S = 120;
  * Build the tmux session name for the coordinator.
  * Includes the project name to prevent cross-project collisions (overstory-pcef).
  */
-function coordinatorTmuxSession(projectName: string): string {
-	return `overstory-${projectName}-${COORDINATOR_NAME}`;
+function coordinatorTmuxSession(projectName: string, name: string = COORDINATOR_NAME): string {
+	return `overstory-${projectName}-${name}`;
 }
 
 /** Dependency injection for testing. Uses real implementations when omitted. */
@@ -273,8 +291,8 @@ export function buildCoordinatorBeacon(cliName = "bd"): string {
 	const parts = [
 		`[OVERSTORY] ${COORDINATOR_NAME} (coordinator) ${timestamp}`,
 		"Depth: 0 | Parent: none | Role: persistent orchestrator",
-		"HIERARCHY: You ONLY spawn leads (ov sling --capability lead). Leads spawn scouts, builders, reviewers. NEVER spawn non-lead agents directly.",
-		"DELEGATION: For any exploration/scouting, spawn a lead who will spawn scouts. Do NOT explore the codebase yourself beyond initial planning.",
+		"HIERARCHY: Default to leads (ov sling --capability lead). For low-budget or very narrow work, you may spawn scout/builder directly. NEVER spawn reviewer or merger directly.",
+		"DELEGATION: For substantial work streams, spawn a lead who will handle scouts/builders/reviewers. For tight agent budgets, compress roles by using direct scout/builder fallback or --dispatch-max-agents 1/2 on the lead.",
 		`Startup: run mulch prime, check mail (ov mail check --agent ${COORDINATOR_NAME}), check ${cliName} ready, check ov group status, then begin work`,
 	];
 	return parts.join(" — ");
@@ -290,8 +308,37 @@ export function resolveAttach(args: string[], isTTY: boolean): boolean {
 	return isTTY;
 }
 
-async function startCoordinator(
-	opts: { json: boolean; attach: boolean; watchdog: boolean; monitor: boolean },
+/**
+ * Options for the reusable coordinator session startup core.
+ * Used by startCoordinatorSession() and consumed by commands like ov discover.
+ */
+export interface CoordinatorSessionOptions {
+	json: boolean;
+	attach: boolean;
+	watchdog: boolean;
+	monitor: boolean;
+	profile?: string;
+	/** Override coordinator name (default: "coordinator"). */
+	coordinatorName?: string;
+	/** Generic persistent agent name override. Preferred over coordinatorName for new callers. */
+	agentName?: string;
+	/** Capability stored in the session registry and used for manifest/runtime resolution. */
+	capability?: string;
+	/** Agent definition file to append as the system prompt. */
+	agentDefFile?: string;
+	/** Human-readable label for output. */
+	displayName?: string;
+	/** Custom beacon builder. Receives tracker CLI name, returns beacon string. */
+	beaconBuilder?: (trackerCli: string) => string;
+}
+
+/**
+ * Core coordinator session startup logic. Reusable by commands that need to
+ * start a coordinator-like session with a custom name or beacon
+ * (e.g., ov discover uses coordinatorName: "discover-coordinator").
+ */
+export async function startCoordinatorSession(
+	opts: CoordinatorSessionOptions,
 	deps: CoordinatorDeps = {},
 ): Promise<void> {
 	const tmux = deps._tmux ?? {
@@ -304,7 +351,25 @@ async function startCoordinator(
 		ensureTmuxAvailable,
 	};
 
-	const { json, attach: shouldAttach, watchdog: watchdogFlag, monitor: monitorFlag } = opts;
+	const {
+		json,
+		attach: shouldAttach,
+		watchdog: watchdogFlag,
+		monitor: monitorFlag,
+		profile: profileFlag,
+		coordinatorName: coordinatorNameOpt,
+		agentName: agentNameOpt,
+		capability: capabilityOpt,
+		agentDefFile: agentDefFileOpt,
+		displayName: displayNameOpt,
+		beaconBuilder: beaconBuilderOpt,
+	} = opts;
+
+	const coordinatorName = agentNameOpt ?? coordinatorNameOpt ?? COORDINATOR_NAME;
+	const capability = capabilityOpt ?? COORDINATOR_SPEC.capability;
+	const agentDefFile = agentDefFileOpt ?? COORDINATOR_SPEC.agentDefFile;
+	const displayName = displayNameOpt ?? COORDINATOR_SPEC.displayName;
+	const beaconBuilder = beaconBuilderOpt ?? buildCoordinatorBeacon;
 
 	if (isRunningAsRoot()) {
 		throw new AgentError(
@@ -317,17 +382,17 @@ async function startCoordinator(
 	const projectRoot = config.project.root;
 	const watchdog = deps._watchdog ?? createDefaultWatchdog(projectRoot);
 	const monitor = deps._monitor ?? createDefaultMonitor(projectRoot);
-	const tmuxSession = coordinatorTmuxSession(config.project.name);
+	const tmuxSession = coordinatorTmuxSession(config.project.name, coordinatorName);
 
-	// Check for existing coordinator
+	// Check for existing coordinator session with the same name
 	const overstoryDir = join(projectRoot, ".overstory");
 	const { store } = openSessionStore(overstoryDir);
 	try {
-		const existing = store.getByName(COORDINATOR_NAME);
+		const existing = store.getByName(coordinatorName);
 
 		if (
 			existing &&
-			existing.capability === "coordinator" &&
+			existing.capability === capability &&
 			existing.state !== "completed" &&
 			existing.state !== "zombie"
 		) {
@@ -340,19 +405,19 @@ async function startCoordinator(
 					// Zombie: tmux pane exists but agent process has exited.
 					// Kill the empty session and reclaim the slot.
 					await tmux.killSession(existing.tmuxSession);
-					store.updateState(COORDINATOR_NAME, "completed");
+					store.updateState(coordinatorName, "completed");
 				} else {
 					// Either the process is genuinely running (pid alive), or pid is null
 					// (e.g. sessions migrated from an older schema). In both cases we
 					// cannot prove the session is a zombie, so treat it as active.
 					throw new AgentError(
-						`Coordinator is already running (tmux: ${existing.tmuxSession}, since: ${existing.startedAt})`,
-						{ agentName: COORDINATOR_NAME },
+						`${displayName} is already running (tmux: ${existing.tmuxSession}, since: ${existing.startedAt})`,
+						{ agentName: coordinatorName },
 					);
 				}
 			} else {
 				// Session is dead or tmux server is not running -- clean up stale DB entry.
-				store.updateState(COORDINATOR_NAME, "completed");
+				store.updateState(coordinatorName, "completed");
 			}
 		}
 
@@ -362,8 +427,8 @@ async function startCoordinator(
 			join(projectRoot, config.agents.baseDir),
 		);
 		const manifest = await manifestLoader.load();
-		const resolvedModel = resolveModel(config, manifest, "coordinator", "opus");
-		const runtime = getRuntime(undefined, config, "coordinator");
+		const resolvedModel = resolveModel(config, manifest, capability, "opus");
+		const runtime = getRuntime(undefined, config, capability);
 
 		// Deploy hooks to the project root so the coordinator gets event logging,
 		// mail check --inject, and activity tracking via the standard hook pipeline.
@@ -372,19 +437,19 @@ async function startCoordinator(
 		// the coordinator's tmux session), so the user's own Claude Code session
 		// at the project root is unaffected.
 		await runtime.deployConfig(projectRoot, undefined, {
-			agentName: COORDINATOR_NAME,
-			capability: "coordinator",
+			agentName: coordinatorName,
+			capability,
 			worktreePath: projectRoot,
 		});
 
 		// Create coordinator identity if first run
 		const identityBaseDir = join(projectRoot, ".overstory", "agents");
 		await mkdir(identityBaseDir, { recursive: true });
-		const existingIdentity = await loadIdentity(identityBaseDir, COORDINATOR_NAME);
+		const existingIdentity = await loadIdentity(identityBaseDir, coordinatorName);
 		if (!existingIdentity) {
 			await createIdentity(identityBaseDir, {
-				name: COORDINATOR_NAME,
-				capability: "coordinator",
+				name: coordinatorName,
+				capability,
 				created: new Date().toISOString(),
 				sessionsCompleted: 0,
 				expertiseDomains: config.mulch.enabled ? config.mulch.domains : [],
@@ -403,10 +468,10 @@ async function startCoordinator(
 		// Pass the file path (not content) so the shell inside the tmux pane reads
 		// it via $(cat ...) — avoids tmux IPC "command too long" errors with large
 		// agent definitions (overstory#45).
-		const agentDefPath = join(projectRoot, ".overstory", "agent-defs", "coordinator.md");
-		const agentDefFile = Bun.file(agentDefPath);
+		const agentDefPath = join(projectRoot, ".overstory", "agent-defs", agentDefFile);
+		const agentDefHandle = Bun.file(agentDefPath);
 		let appendSystemPromptFile: string | undefined;
-		if (await agentDefFile.exists()) {
+		if (await agentDefHandle.exists()) {
 			appendSystemPromptFile = agentDefPath;
 		}
 		const spawnCmd = runtime.buildSpawnCommand({
@@ -416,17 +481,19 @@ async function startCoordinator(
 			appendSystemPromptFile,
 			env: {
 				...runtime.buildEnv(resolvedModel),
-				OVERSTORY_AGENT_NAME: COORDINATOR_NAME,
+				OVERSTORY_AGENT_NAME: coordinatorName,
+				...(profileFlag ? { OVERSTORY_PROFILE: profileFlag } : {}),
 			},
 		});
 		const pid = await tmux.createSession(tmuxSession, projectRoot, spawnCmd, {
 			...runtime.buildEnv(resolvedModel),
-			OVERSTORY_AGENT_NAME: COORDINATOR_NAME,
+			OVERSTORY_AGENT_NAME: coordinatorName,
+			...(profileFlag ? { OVERSTORY_PROFILE: profileFlag } : {}),
 		});
 
 		// Create a run for this coordinator session BEFORE recording the session,
 		// so the session can reference the run ID from the start.
-		const sessionId = `session-${Date.now()}-${COORDINATOR_NAME}`;
+		const sessionId = `session-${Date.now()}-${coordinatorName}`;
 		const runId = `run-${new Date().toISOString().replace(/[:.]/g, "-")}`;
 		const runStore = createRunStore(join(overstoryDir, "sessions.db"));
 		try {
@@ -434,7 +501,7 @@ async function startCoordinator(
 				id: runId,
 				startedAt: new Date().toISOString(),
 				coordinatorSessionId: sessionId,
-				coordinatorName: COORDINATOR_NAME,
+				coordinatorName,
 				status: "active",
 			});
 		} finally {
@@ -449,8 +516,8 @@ async function startCoordinator(
 		// leaving the coordinator stuck in "booting" (overstory-036f).
 		const session: AgentSession = {
 			id: sessionId,
-			agentName: COORDINATOR_NAME,
-			capability: "coordinator",
+			agentName: coordinatorName,
+			capability,
 			worktreePath: projectRoot, // Coordinator uses project root, not a worktree
 			branchName: config.project.canonicalBranch, // Operates on canonical branch
 			taskId: "", // No specific task assignment
@@ -484,29 +551,29 @@ async function startCoordinator(
 			const alive = await tmux.isSessionAlive(tmuxSession);
 			if (!alive) {
 				// Clean up the stale session record
-				store.updateState(COORDINATOR_NAME, "completed");
+				store.updateState(coordinatorName, "completed");
 				const sessionState = await tmux.checkSessionState(tmuxSession);
 				const detail =
 					sessionState === "no_server"
 						? "The tmux server is no longer running. It may have crashed or been killed externally."
 						: "The Claude Code process may have crashed or exited immediately. Check tmux logs or try running the claude command manually.";
 				throw new AgentError(
-					`Coordinator tmux session "${tmuxSession}" died during startup. ${detail}`,
-					{ agentName: COORDINATOR_NAME },
+					`${displayName} tmux session "${tmuxSession}" died during startup. ${detail}`,
+					{ agentName: coordinatorName },
 				);
 			}
 			await tmux.killSession(tmuxSession);
-			store.updateState(COORDINATOR_NAME, "completed");
+			store.updateState(coordinatorName, "completed");
 			throw new AgentError(
-				`Coordinator tmux session "${tmuxSession}" did not become ready during startup. Claude Code may still be waiting on an interactive dialog or initializing too slowly.`,
-				{ agentName: COORDINATOR_NAME },
+				`${displayName} tmux session "${tmuxSession}" did not become ready during startup. Claude Code may still be waiting on an interactive dialog or initializing too slowly.`,
+				{ agentName: coordinatorName },
 			);
 		}
 		await Bun.sleep(1_000);
 
 		const resolvedBackend = await resolveBackend(config.taskTracker.backend, config.project.root);
 		const trackerCli = trackerCliName(resolvedBackend);
-		const beacon = buildCoordinatorBeacon(trackerCli);
+		const beacon = beaconBuilder(trackerCli);
 		await tmux.sendKeys(tmuxSession, beacon);
 
 		// Follow-up Enters with increasing delays to ensure submission
@@ -544,8 +611,8 @@ async function startCoordinator(
 		}
 
 		const output = {
-			agentName: COORDINATOR_NAME,
-			capability: "coordinator",
+			agentName: coordinatorName,
+			capability,
 			tmuxSession,
 			projectRoot,
 			pid,
@@ -554,9 +621,9 @@ async function startCoordinator(
 		};
 
 		if (json) {
-			jsonOutput("coordinator start", output);
+			jsonOutput(`${capability} start`, output);
 		} else {
-			printSuccess("Coordinator started");
+			printSuccess(`${displayName} started`);
 			process.stdout.write(`  Tmux:    ${tmuxSession}\n`);
 			process.stdout.write(`  Root:    ${projectRoot}\n`);
 			process.stdout.write(`  PID:     ${pid}\n`);
@@ -572,6 +639,36 @@ async function startCoordinator(
 	}
 }
 
+async function startPersistentAgent(
+	spec: PersistentAgentSpec,
+	opts: { json: boolean; attach: boolean; watchdog: boolean; monitor: boolean; profile?: string },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
+	await startCoordinatorSession(
+		{
+			...opts,
+			agentName: spec.agentName,
+			capability: spec.capability,
+			agentDefFile: spec.agentDefFile,
+			displayName: spec.displayName,
+			beaconBuilder: spec.beaconBuilder,
+		},
+		deps,
+	);
+}
+
+function isActivePersistentAgentSession(
+	session: AgentSession | null,
+	spec: PersistentAgentSpec,
+): session is AgentSession {
+	return (
+		session !== null &&
+		session.capability === spec.capability &&
+		session.state !== "completed" &&
+		session.state !== "zombie"
+	);
+}
+
 /**
  * Stop the coordinator agent.
  *
@@ -580,7 +677,11 @@ async function startCoordinator(
  * 3. Mark session as completed in SessionStore
  * 4. Auto-complete the active run (if current-run.txt exists)
  */
-async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps = {}): Promise<void> {
+async function stopPersistentAgent(
+	spec: PersistentAgentSpec,
+	opts: { json: boolean },
+	deps: CoordinatorDeps = {},
+): Promise<void> {
 	const tmux = deps._tmux ?? {
 		createSession,
 		isSessionAlive,
@@ -601,16 +702,11 @@ async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps =
 	const overstoryDir = join(projectRoot, ".overstory");
 	const { store } = openSessionStore(overstoryDir);
 	try {
-		const session = store.getByName(COORDINATOR_NAME);
+		const session = store.getByName(spec.agentName);
 
-		if (
-			!session ||
-			session.capability !== "coordinator" ||
-			session.state === "completed" ||
-			session.state === "zombie"
-		) {
-			throw new AgentError("No active coordinator session found", {
-				agentName: COORDINATOR_NAME,
+		if (!isActivePersistentAgentSession(session, spec)) {
+			throw new AgentError(`No active ${spec.commandName} session found`, {
+				agentName: spec.agentName,
 			});
 		}
 
@@ -627,8 +723,8 @@ async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps =
 		const monitorStopped = await monitor.stop();
 
 		// Update session state
-		store.updateState(COORDINATOR_NAME, "completed");
-		store.updateLastActivity(COORDINATOR_NAME);
+		store.updateState(spec.agentName, "completed");
+		store.updateLastActivity(spec.agentName);
 
 		// Auto-complete the current run
 		let runCompleted = false;
@@ -657,7 +753,7 @@ async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps =
 		}
 
 		if (json) {
-			jsonOutput("coordinator stop", {
+			jsonOutput(`${spec.commandName} stop`, {
 				stopped: true,
 				sessionId: session.id,
 				watchdogStopped,
@@ -665,7 +761,7 @@ async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps =
 				runCompleted,
 			});
 		} else {
-			printSuccess("Coordinator stopped", session.id);
+			printSuccess(`${spec.displayName} stopped`, session.id);
 			if (watchdogStopped) {
 				printHint("Watchdog stopped");
 			} else {
@@ -692,7 +788,8 @@ async function stopCoordinator(opts: { json: boolean }, deps: CoordinatorDeps =
  *
  * Checks session registry and tmux liveness to report actual state.
  */
-async function statusCoordinator(
+async function statusPersistentAgent(
+	spec: PersistentAgentSpec,
 	opts: { json: boolean },
 	deps: CoordinatorDeps = {},
 ): Promise<void> {
@@ -716,20 +813,19 @@ async function statusCoordinator(
 	const overstoryDir = join(projectRoot, ".overstory");
 	const { store } = openSessionStore(overstoryDir);
 	try {
-		const session = store.getByName(COORDINATOR_NAME);
+		const session = store.getByName(spec.agentName);
 		const watchdogRunning = await watchdog.isRunning();
 		const monitorRunning = await monitor.isRunning();
 
-		if (
-			!session ||
-			session.capability !== "coordinator" ||
-			session.state === "completed" ||
-			session.state === "zombie"
-		) {
+		if (!isActivePersistentAgentSession(session, spec)) {
 			if (json) {
-				jsonOutput("coordinator status", { running: false, watchdogRunning, monitorRunning });
+				jsonOutput(`${spec.commandName} status`, {
+					running: false,
+					watchdogRunning,
+					monitorRunning,
+				});
 			} else {
-				printHint("Coordinator is not running");
+				printHint(`${spec.displayName} is not running`);
 				if (watchdogRunning) {
 					printHint("Watchdog: running");
 				}
@@ -746,8 +842,8 @@ async function statusCoordinator(
 		// We already filtered out completed/zombie states above, so if tmux is dead
 		// this session needs to be marked as zombie.
 		if (!alive) {
-			store.updateState(COORDINATOR_NAME, "zombie");
-			store.updateLastActivity(COORDINATOR_NAME);
+			store.updateState(spec.agentName, "zombie");
+			store.updateLastActivity(spec.agentName);
 			session.state = "zombie";
 		}
 
@@ -764,10 +860,10 @@ async function statusCoordinator(
 		};
 
 		if (json) {
-			jsonOutput("coordinator status", status);
+			jsonOutput(`${spec.commandName} status`, status);
 		} else {
 			const stateLabel = alive ? "running" : session.state;
-			process.stdout.write(`Coordinator: ${stateLabel}\n`);
+			process.stdout.write(`${spec.displayName}: ${stateLabel}\n`);
 			process.stdout.write(`  Session:   ${session.id}\n`);
 			process.stdout.write(`  Tmux:      ${session.tmuxSession}\n`);
 			process.stdout.write(`  PID:       ${session.pid}\n`);
@@ -787,7 +883,8 @@ async function statusCoordinator(
  * Sends a mail message (from: operator, type: dispatch) and auto-nudges the
  * coordinator via tmux sendKeys. Replaces the two-step `ov mail send + ov nudge` pattern.
  */
-async function sendToCoordinator(
+async function sendToPersistentAgent(
+	spec: PersistentAgentSpec,
 	body: string,
 	opts: { subject: string; json: boolean },
 	deps: CoordinatorDeps = {},
@@ -811,26 +908,24 @@ async function sendToCoordinator(
 	const overstoryDir = join(projectRoot, ".overstory");
 	const { store } = openSessionStore(overstoryDir);
 	try {
-		const session = store.getByName(COORDINATOR_NAME);
+		const session = store.getByName(spec.agentName);
 
-		if (
-			!session ||
-			session.capability !== "coordinator" ||
-			session.state === "completed" ||
-			session.state === "zombie"
-		) {
-			throw new AgentError("No active coordinator session found", {
-				agentName: COORDINATOR_NAME,
+		if (!isActivePersistentAgentSession(session, spec)) {
+			throw new AgentError(`No active ${spec.commandName} session found`, {
+				agentName: spec.agentName,
 			});
 		}
 
 		const alive = await tmux.isSessionAlive(session.tmuxSession);
 		if (!alive) {
-			store.updateState(COORDINATOR_NAME, "zombie");
-			store.updateLastActivity(COORDINATOR_NAME);
-			throw new AgentError(`Coordinator tmux session "${session.tmuxSession}" is not alive`, {
-				agentName: COORDINATOR_NAME,
-			});
+			store.updateState(spec.agentName, "zombie");
+			store.updateLastActivity(spec.agentName);
+			throw new AgentError(
+				`${spec.displayName} tmux session "${session.tmuxSession}" is not alive`,
+				{
+					agentName: spec.agentName,
+				},
+			);
 		}
 
 		// Send mail
@@ -841,7 +936,7 @@ async function sendToCoordinator(
 		try {
 			id = mailClient.send({
 				from: "operator",
-				to: COORDINATOR_NAME,
+				to: spec.agentName,
 				subject,
 				body,
 				type: "dispatch",
@@ -855,16 +950,16 @@ async function sendToCoordinator(
 		const nudgeMessage = `[DISPATCH] ${subject}: ${body.slice(0, 500)}`;
 		let nudged = false;
 		try {
-			const nudgeResult = await nudge(projectRoot, COORDINATOR_NAME, nudgeMessage, true);
+			const nudgeResult = await nudge(projectRoot, spec.agentName, nudgeMessage, true);
 			nudged = nudgeResult.delivered;
 		} catch {
 			// Nudge is fire-and-forget — silently ignore errors
 		}
 
 		if (json) {
-			jsonOutput("coordinator send", { id, nudged });
+			jsonOutput(`${spec.commandName} send`, { id, nudged });
 		} else {
-			printSuccess("Sent to coordinator", id);
+			printSuccess(`Sent to ${spec.commandName}`, id);
 		}
 	} finally {
 		store.close();
@@ -883,6 +978,15 @@ export async function askCoordinator(
 	body: string,
 	opts: { subject: string; timeout: number; json: boolean },
 	deps: CoordinatorDeps = {},
+): Promise<void> {
+	await askPersistentAgent(COORDINATOR_SPEC, body, opts, deps);
+}
+
+export async function askPersistentAgent(
+	spec: PersistentAgentSpec,
+	body: string,
+	opts: { subject: string; timeout: number; json: boolean },
+	deps: CoordinatorDeps = {},
 ): Promise<void> {
 	const tmux = deps._tmux ?? {
 		createSession,
@@ -904,26 +1008,24 @@ export async function askCoordinator(
 	const overstoryDir = join(projectRoot, ".overstory");
 	const { store } = openSessionStore(overstoryDir);
 	try {
-		const session = store.getByName(COORDINATOR_NAME);
+		const session = store.getByName(spec.agentName);
 
-		if (
-			!session ||
-			session.capability !== "coordinator" ||
-			session.state === "completed" ||
-			session.state === "zombie"
-		) {
-			throw new AgentError("No active coordinator session found", {
-				agentName: COORDINATOR_NAME,
+		if (!isActivePersistentAgentSession(session, spec)) {
+			throw new AgentError(`No active ${spec.commandName} session found`, {
+				agentName: spec.agentName,
 			});
 		}
 
 		const alive = await tmux.isSessionAlive(session.tmuxSession);
 		if (!alive) {
-			store.updateState(COORDINATOR_NAME, "zombie");
-			store.updateLastActivity(COORDINATOR_NAME);
-			throw new AgentError(`Coordinator tmux session "${session.tmuxSession}" is not alive`, {
-				agentName: COORDINATOR_NAME,
-			});
+			store.updateState(spec.agentName, "zombie");
+			store.updateLastActivity(spec.agentName);
+			throw new AgentError(
+				`${spec.displayName} tmux session "${session.tmuxSession}" is not alive`,
+				{
+					agentName: spec.agentName,
+				},
+			);
 		}
 
 		// Generate correlation ID for tracking this request/response pair
@@ -937,7 +1039,7 @@ export async function askCoordinator(
 		try {
 			sentId = mailClient.send({
 				from: "operator",
-				to: COORDINATOR_NAME,
+				to: spec.agentName,
 				subject,
 				body,
 				type: "dispatch",
@@ -951,7 +1053,7 @@ export async function askCoordinator(
 		// Auto-nudge (fire-and-forget)
 		const nudgeMessage = `[ASK] ${subject}: ${body.slice(0, 500)}`;
 		try {
-			await nudge(projectRoot, COORDINATOR_NAME, nudgeMessage, true);
+			await nudge(projectRoot, spec.agentName, nudgeMessage, true);
 		} catch {
 			// Nudge is fire-and-forget — silently ignore errors
 		}
@@ -965,13 +1067,13 @@ export async function askCoordinator(
 			let reply: import("../types.ts").MailMessage | undefined;
 			try {
 				const replies = pollStore.getByThread(sentId);
-				reply = replies.find((m) => m.from === COORDINATOR_NAME && m.to === "operator");
+				reply = replies.find((m) => m.from === spec.agentName && m.to === "operator");
 			} finally {
 				pollStore.close();
 			}
 			if (reply) {
 				if (json) {
-					jsonOutput("coordinator ask", {
+					jsonOutput(`${spec.commandName} ask`, {
 						correlationId,
 						sentId,
 						replyId: reply.id,
@@ -987,8 +1089,8 @@ export async function askCoordinator(
 		}
 
 		throw new AgentError(
-			`Timed out after ${timeout}s waiting for coordinator reply (correlationId: ${correlationId})`,
-			{ agentName: COORDINATOR_NAME },
+			`Timed out after ${timeout}s waiting for ${spec.commandName} reply (correlationId: ${correlationId})`,
+			{ agentName: spec.agentName },
 		);
 	} finally {
 		store.close();
@@ -1000,7 +1102,8 @@ export async function askCoordinator(
  *
  * Wraps capturePaneContent() from tmux.ts. Supports --follow for continuous polling.
  */
-async function outputCoordinator(
+async function outputPersistentAgent(
+	spec: PersistentAgentSpec,
 	opts: { follow: boolean; lines: number; interval: number; json: boolean },
 	deps: CoordinatorDeps = {},
 ): Promise<void> {
@@ -1023,26 +1126,24 @@ async function outputCoordinator(
 	const overstoryDir = join(projectRoot, ".overstory");
 	const { store } = openSessionStore(overstoryDir);
 	try {
-		const session = store.getByName(COORDINATOR_NAME);
+		const session = store.getByName(spec.agentName);
 
-		if (
-			!session ||
-			session.capability !== "coordinator" ||
-			session.state === "completed" ||
-			session.state === "zombie"
-		) {
-			throw new AgentError("No active coordinator session found", {
-				agentName: COORDINATOR_NAME,
+		if (!isActivePersistentAgentSession(session, spec)) {
+			throw new AgentError(`No active ${spec.commandName} session found`, {
+				agentName: spec.agentName,
 			});
 		}
 
 		const alive = await tmux.isSessionAlive(session.tmuxSession);
 		if (!alive) {
-			store.updateState(COORDINATOR_NAME, "zombie");
-			store.updateLastActivity(COORDINATOR_NAME);
-			throw new AgentError(`Coordinator tmux session "${session.tmuxSession}" is not alive`, {
-				agentName: COORDINATOR_NAME,
-			});
+			store.updateState(spec.agentName, "zombie");
+			store.updateLastActivity(spec.agentName);
+			throw new AgentError(
+				`${spec.displayName} tmux session "${session.tmuxSession}" is not alive`,
+				{
+					agentName: spec.agentName,
+				},
+			);
 		}
 
 		const tmuxSession = session.tmuxSession;
@@ -1057,7 +1158,7 @@ async function outputCoordinator(
 			while (running) {
 				const content = await capturePane(tmuxSession, lines);
 				if (json) {
-					jsonOutput("coordinator output", { content, lines });
+					jsonOutput(`${spec.commandName} output`, { content, lines });
 				} else {
 					process.stdout.write(content ?? "");
 				}
@@ -1068,7 +1169,7 @@ async function outputCoordinator(
 		} else {
 			const content = await capturePane(tmuxSession, lines);
 			if (json) {
-				jsonOutput("coordinator output", { content, lines });
+				jsonOutput(`${spec.commandName} output`, { content, lines });
 			} else {
 				process.stdout.write(content ?? "");
 			}
@@ -1242,30 +1343,41 @@ export async function checkComplete(
 	return result;
 }
 
-/**
- * Create the Commander command for `ov coordinator`.
- */
-export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
-	const cmd = new Command("coordinator").description("Manage the persistent coordinator agent");
+export function createPersistentAgentCommand(
+	spec: PersistentAgentSpec,
+	deps: CoordinatorDeps = {},
+): Command {
+	const cmd = new Command(spec.commandName).description(
+		`Manage the persistent ${spec.commandName} agent`,
+	);
 
 	cmd
 		.command("start")
-		.description("Start the coordinator (spawns Claude Code at project root)")
+		.description(`Start the ${spec.commandName} (spawns Claude Code at project root)`)
 		.option("--attach", "Always attach to tmux session after start")
 		.option("--no-attach", "Never attach to tmux session after start")
-		.option("--watchdog", "Auto-start watchdog daemon with coordinator")
-		.option("--monitor", "Auto-start Tier 2 monitor agent with coordinator")
+		.option("--watchdog", `Auto-start watchdog daemon with ${spec.commandName}`)
+		.option("--monitor", `Auto-start Tier 2 monitor agent with ${spec.commandName}`)
+		.option("--profile <name>", "Canopy profile to apply to spawned agents")
 		.option("--json", "Output as JSON")
 		.action(
-			async (opts: { attach?: boolean; watchdog?: boolean; monitor?: boolean; json?: boolean }) => {
+			async (opts: {
+				attach?: boolean;
+				watchdog?: boolean;
+				monitor?: boolean;
+				json?: boolean;
+				profile?: string;
+			}) => {
 				// opts.attach = true if --attach, false if --no-attach, undefined if neither
 				const shouldAttach = opts.attach !== undefined ? opts.attach : !!process.stdout.isTTY;
-				await startCoordinator(
+				await startPersistentAgent(
+					spec,
 					{
 						json: opts.json ?? false,
 						attach: shouldAttach,
 						watchdog: opts.watchdog ?? false,
 						monitor: opts.monitor ?? false,
+						profile: opts.profile,
 					},
 					deps,
 				);
@@ -1274,39 +1386,45 @@ export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
 
 	cmd
 		.command("stop")
-		.description("Stop the coordinator (kills tmux session)")
+		.description(`Stop the ${spec.commandName} (kills tmux session)`)
 		.option("--json", "Output as JSON")
 		.action(async (opts: { json?: boolean }) => {
-			await stopCoordinator({ json: opts.json ?? false }, deps);
+			await stopPersistentAgent(spec, { json: opts.json ?? false }, deps);
 		});
 
 	cmd
 		.command("status")
-		.description("Show coordinator state")
+		.description(`Show ${spec.commandName} state`)
 		.option("--json", "Output as JSON")
 		.action(async (opts: { json?: boolean }) => {
-			await statusCoordinator({ json: opts.json ?? false }, deps);
+			await statusPersistentAgent(spec, { json: opts.json ?? false }, deps);
 		});
 
 	cmd
 		.command("send")
-		.description("Send a message to the coordinator (fire-and-forget)")
+		.description(`Send a message to the ${spec.commandName} (fire-and-forget)`)
 		.requiredOption("--body <text>", "Message body")
 		.option("--subject <text>", "Message subject", "operator dispatch")
 		.option("--json", "Output as JSON")
 		.action(async (opts: { body: string; subject: string; json?: boolean }) => {
-			await sendToCoordinator(opts.body, { subject: opts.subject, json: opts.json ?? false }, deps);
+			await sendToPersistentAgent(
+				spec,
+				opts.body,
+				{ subject: opts.subject, json: opts.json ?? false },
+				deps,
+			);
 		});
 
 	cmd
 		.command("ask")
-		.description("Send a request to the coordinator and wait for a reply")
+		.description(`Send a request to the ${spec.commandName} and wait for a reply`)
 		.requiredOption("--body <text>", "Message body")
 		.option("--subject <text>", "Message subject", "operator request")
 		.option("--timeout <seconds>", "Timeout in seconds", String(ASK_DEFAULT_TIMEOUT_S))
 		.option("--json", "Output as JSON")
 		.action(async (opts: { body: string; subject: string; timeout?: string; json?: boolean }) => {
-			await askCoordinator(
+			await askPersistentAgent(
+				spec,
 				opts.body,
 				{
 					subject: opts.subject,
@@ -1319,14 +1437,15 @@ export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
 
 	cmd
 		.command("output")
-		.description("Show recent coordinator output (tmux pane content)")
+		.description(`Show recent ${spec.commandName} output (tmux pane content)`)
 		.option("--follow, -f", "Continuously poll for new output")
 		.option("--lines <n>", "Number of lines to capture", "50")
 		.option("--interval <ms>", "Poll interval in milliseconds (with --follow)", "2000")
 		.option("--json", "Output as JSON")
 		.action(
 			async (opts: { follow?: boolean; lines?: string; interval?: string; json?: boolean }) => {
-				await outputCoordinator(
+				await outputPersistentAgent(
+					spec,
 					{
 						follow: opts.follow ?? false,
 						lines: Number.parseInt(opts.lines ?? "50", 10),
@@ -1338,6 +1457,15 @@ export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
 			},
 		);
 
+	return cmd;
+}
+
+/**
+ * Create the Commander command for `ov coordinator`.
+ */
+export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
+	const cmd = createPersistentAgentCommand(COORDINATOR_SPEC, deps);
+
 	cmd
 		.command("check-complete")
 		.description("Evaluate exit triggers and report completion status")
@@ -1349,6 +1477,36 @@ export function createCoordinatorCommand(deps: CoordinatorDeps = {}): Command {
 	return cmd;
 }
 
+export async function persistentAgentCommand(
+	args: string[],
+	spec: PersistentAgentSpec,
+	deps: CoordinatorDeps = {},
+): Promise<void> {
+	const cmd = createPersistentAgentCommand(spec, deps);
+	cmd.exitOverride();
+
+	if (args.length === 0) {
+		process.stdout.write(cmd.helpInformation());
+		return;
+	}
+
+	try {
+		await cmd.parseAsync(args, { from: "user" });
+	} catch (err: unknown) {
+		if (err && typeof err === "object" && "code" in err) {
+			const code = (err as { code: string }).code;
+			if (code === "commander.helpDisplayed" || code === "commander.version") {
+				return;
+			}
+			if (code === "commander.unknownCommand") {
+				const message = err instanceof Error ? err.message : String(err);
+				throw new ValidationError(message, { field: "subcommand" });
+			}
+		}
+		throw err;
+	}
+}
+
 /**
  * Entry point for `ov coordinator <subcommand>`.
  *