@os-eco/overstory-cli 0.6.11 → 0.7.0

package/src/commands/sling.ts

@@ -32,6 +32,7 @@ import { printSuccess } from "../logging/color.ts";
 import { createMailClient } from "../mail/client.ts";
 import { createMailStore } from "../mail/store.ts";
 import { createMulchClient } from "../mulch/client.ts";
+import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
 import type { TrackerIssue } from "../tracker/factory.ts";
@@ -122,6 +123,7 @@ export interface SlingOptions {
 	maxAgents?: string;
 	skipReview?: boolean;
 	dispatchMaxAgents?: string;
+	runtime?: string;
 }
 
 export interface AutoDispatchOptions {
@@ -699,10 +701,20 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 
 		// 12. Create tmux session running claude in interactive mode
 		const tmuxSessionName = `overstory-${config.project.name}-${name}`;
-		const { model, env } = resolveModel(config, manifest, capability, agentDef.model);
-		const claudeCmd = `claude --model ${model} --permission-mode bypassPermissions`;
-		const pid = await createSession(tmuxSessionName, worktreePath, claudeCmd, {
-			...env,
+		const resolvedModel = resolveModel(config, manifest, capability, agentDef.model);
+		const runtime = getRuntime(opts.runtime, config);
+		const spawnCmd = runtime.buildSpawnCommand({
+			model: resolvedModel.model,
+			permissionMode: "bypass",
+			cwd: worktreePath,
+			env: {
+				...runtime.buildEnv(resolvedModel),
+				OVERSTORY_AGENT_NAME: name,
+				OVERSTORY_WORKTREE_PATH: worktreePath,
+			},
+		});
+		const pid = await createSession(tmuxSessionName, worktreePath, spawnCmd, {
+			...runtime.buildEnv(resolvedModel),
 			OVERSTORY_AGENT_NAME: name,
 			OVERSTORY_WORKTREE_PATH: worktreePath,
 		});
@@ -743,7 +755,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 		// 13b. Wait for Claude Code TUI to render before sending input.
 		// Polling capture-pane is more reliable than a fixed sleep because
 		// TUI init time varies by machine load and model state.
-		await waitForTuiReady(tmuxSessionName);
+		await waitForTuiReady(tmuxSessionName, (content) => runtime.detectReady(content));
 		// Buffer for the input handler to attach after initial render
 		await Bun.sleep(1_000);
 
@@ -765,17 +777,20 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 		}
 
 		// 13d. Verify beacon was received — if pane still shows the welcome
-		// screen ("Try "), resend the beacon. Claude Code's TUI sometimes
-		// consumes the Enter keystroke during late initialization, swallowing
+		// screen (detectReady returns "ready"), resend the beacon. Claude Code's TUI
+		// sometimes consumes the Enter keystroke during late initialization, swallowing
 		// the beacon text entirely (overstory-3271).
 		const verifyAttempts = 5;
 		for (let v = 0; v < verifyAttempts; v++) {
 			await Bun.sleep(2_000);
 			const paneContent = await capturePaneContent(tmuxSessionName);
-			if (paneContent && !paneContent.includes('Try "')) {
-				break; // Agent is processing — beacon was received
+			if (paneContent) {
+				const readyState = runtime.detectReady(paneContent);
+				if (readyState.phase !== "ready") {
+					break; // Agent is processing — beacon was received
+				}
 			}
-			// Still at welcome screen — resend beacon
+			// Still at welcome/idle screen — resend beacon
 			await sendKeys(tmuxSessionName, beacon);
 			await Bun.sleep(1_000);
 			await sendKeys(tmuxSessionName, ""); // Follow-up Enter

package/src/commands/status.ts

@@ -11,6 +11,8 @@ import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
 import { accent, color } from "../logging/color.ts";
+import { formatDuration } from "../logging/format.ts";
+import { renderHeader } from "../logging/theme.ts";
 import { createMailStore } from "../mail/store.ts";
 import { createMergeQueue } from "../merge/queue.ts";
 import { createMetricsStore } from "../metrics/store.ts";
@@ -68,20 +70,6 @@ export async function getCachedTmuxSessions(
 	}
 }
 
-/**
- * Format a duration in ms to a human-readable string.
- */
-function formatDuration(ms: number): string {
-	const seconds = Math.floor(ms / 1000);
-	if (seconds < 60) return `${seconds}s`;
-	const minutes = Math.floor(seconds / 60);
-	const remainSec = seconds % 60;
-	if (minutes < 60) return `${minutes}m ${remainSec}s`;
-	const hours = Math.floor(minutes / 60);
-	const remainMin = minutes % 60;
-	return `${hours}h ${remainMin}m`;
-}
-
 export interface VerboseAgentDetail {
 	worktreePath: string;
 	logsDir: string;
@@ -190,7 +178,7 @@ export async function gatherStatus(
 			const metricsFile = Bun.file(metricsDbPath);
 			if (await metricsFile.exists()) {
 				const metricsStore = createMetricsStore(metricsDbPath);
-				recentMetricsCount = metricsStore.getRecentSessions(100).length;
+				recentMetricsCount = metricsStore.countSessions();
 				metricsStore.close();
 			}
 		} catch {
@@ -256,8 +244,7 @@ export function printStatus(data: StatusData): void {
 	const now = Date.now();
 	const w = process.stdout.write.bind(process.stdout);
 
-	w("Overstory Status\n");
-	w(`${"═".repeat(60)}\n\n`);
+	w(`${renderHeader("Overstory Status")}\n\n`);
 	if (data.currentRunId) {
 		w(`Run: ${accent(data.currentRunId)}\n`);
 	}

package/src/commands/supervisor.ts

@@ -22,6 +22,7 @@ import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess } from "../logging/color.ts";
+import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createTrackerClient, resolveBackend, trackerCliName } from "../tracker/factory.ts";
 import type { AgentSession } from "../types.ts";
@@ -160,26 +161,35 @@ async function startSupervisor(opts: {
 			join(projectRoot, config.agents.baseDir),
 		);
 		const manifest = await manifestLoader.load();
-		const { model, env } = resolveModel(config, manifest, "supervisor", "opus");
+		const resolvedModel = resolveModel(config, manifest, "supervisor", "opus");
+		const runtime = getRuntime(undefined, config);
 
 		// Spawn tmux session at project root with Claude Code (interactive mode).
 		// Inject the supervisor base definition via --append-system-prompt.
 		const tmuxSession = `overstory-${config.project.name}-supervisor-${opts.name}`;
 		const agentDefPath = join(projectRoot, ".overstory", "agent-defs", "supervisor.md");
 		const agentDefFile = Bun.file(agentDefPath);
-		let claudeCmd = `claude --model ${model} --permission-mode bypassPermissions`;
+		let appendSystemPrompt: string | undefined;
 		if (await agentDefFile.exists()) {
-			const agentDef = await agentDefFile.text();
-			const escaped = agentDef.replace(/'/g, "'\\''");
-			claudeCmd += ` --append-system-prompt '${escaped}'`;
+			appendSystemPrompt = await agentDefFile.text();
 		}
-		const pid = await createSession(tmuxSession, projectRoot, claudeCmd, {
-			...env,
+		const spawnCmd = runtime.buildSpawnCommand({
+			model: resolvedModel.model,
+			permissionMode: "bypass",
+			cwd: projectRoot,
+			appendSystemPrompt,
+			env: {
+				...runtime.buildEnv(resolvedModel),
+				OVERSTORY_AGENT_NAME: opts.name,
+			},
+		});
+		const pid = await createSession(tmuxSession, projectRoot, spawnCmd, {
+			...runtime.buildEnv(resolvedModel),
 			OVERSTORY_AGENT_NAME: opts.name,
 		});
 
 		// Wait for Claude Code TUI to render before sending input
-		await waitForTuiReady(tmuxSession);
+		await waitForTuiReady(tmuxSession, (content) => runtime.detectReady(content));
 		await Bun.sleep(1_000);
 
 		const beacon = buildSupervisorBeacon({

package/src/commands/trace.test.ts

@@ -317,7 +317,7 @@ describe("traceCommand", () => {
 			await traceCommand(["builder-1"]);
 			const out = output();
 
-			expect(out).toContain("=".repeat(70));
+			expect(out).toContain("─".repeat(70));
 		});
 
 		test("event type labels are shown", async () => {
@@ -370,7 +370,7 @@ describe("traceCommand", () => {
 			await traceCommand(["builder-1"]);
 			const out = output();
 
-			expect(out).toContain("duration=42ms");
+			expect(out).toContain("dur=42ms");
 		});
 
 		test("custom data fields are shown in detail", async () => {
@@ -389,8 +389,7 @@ describe("traceCommand", () => {
 			await traceCommand(["builder-1"]);
 			const out = output();
 
-			expect(out).toContain("reason=testing");
-			expect(out).toContain("count=5");
+			expect(out).toContain('data={"reason":"testing","count":5}');
 		});
 
 		test("date separator appears in timeline", async () => {
@@ -684,8 +683,8 @@ describe("traceCommand", () => {
 
 			// The full 200-char value should not appear
 			expect(out).not.toContain(longValue);
-			// But a truncated version with "..." should
-			expect(out).toContain("...");
+			// But a truncated version with "…" should
+			expect(out).toContain("…");
 		});
 
 		test("non-JSON data is shown raw if short", async () => {

package/src/commands/trace.ts

@@ -11,23 +11,16 @@ import { loadConfig } from "../config.ts";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import { jsonOutput } from "../json.ts";
-import type { ColorFn } from "../logging/color.ts";
 import { accent, color } from "../logging/color.ts";
+import {
+	buildEventDetail,
+	formatAbsoluteTime,
+	formatDate,
+	formatRelativeTime,
+} from "../logging/format.ts";
+import { eventLabel, renderHeader } from "../logging/theme.ts";
 import { openSessionStore } from "../sessions/compat.ts";
-import type { EventType, StoredEvent } from "../types.ts";
-
-/** Labels and colors for each event type. */
-const EVENT_LABELS: Record<EventType, { label: string; color: ColorFn }> = {
-	tool_start: { label: "TOOL START", color: color.blue },
-	tool_end: { label: "TOOL END  ", color: color.blue },
-	session_start: { label: "SESSION  +", color: color.green },
-	session_end: { label: "SESSION  -", color: color.yellow },
-	mail_sent: { label: "MAIL SENT ", color: color.cyan },
-	mail_received: { label: "MAIL RECV ", color: color.cyan },
-	spawn: { label: "SPAWN     ", color: color.magenta },
-	error: { label: "ERROR     ", color: color.red },
-	custom: { label: "CUSTOM    ", color: color.gray },
-};
+import type { StoredEvent } from "../types.ts";
 
 /**
  * Detect whether a target string looks like a task ID.
@@ -37,101 +30,13 @@ function looksLikeTaskId(target: string): boolean {
 	return /^[a-z][a-z0-9]*-[a-z0-9]{3,}$/i.test(target);
 }
 
-/**
- * Format a relative time string from a timestamp.
- * Returns strings like "2m ago", "1h ago", "3d ago".
- */
-function formatRelativeTime(timestamp: string): string {
-	const eventTime = new Date(timestamp).getTime();
-	const now = Date.now();
-	const diffMs = now - eventTime;
-
-	if (diffMs < 0) return "just now";
-
-	const seconds = Math.floor(diffMs / 1000);
-	if (seconds < 60) return `${seconds}s ago`;
-
-	const minutes = Math.floor(seconds / 60);
-	if (minutes < 60) return `${minutes}m ago`;
-
-	const hours = Math.floor(minutes / 60);
-	if (hours < 24) return `${hours}h ago`;
-
-	const days = Math.floor(hours / 24);
-	return `${days}d ago`;
-}
-
-/**
- * Format an absolute time from an ISO timestamp.
- * Returns "HH:MM:SS" portion.
- */
-function formatAbsoluteTime(timestamp: string): string {
-	const match = /T(\d{2}:\d{2}:\d{2})/.exec(timestamp);
-	if (match?.[1]) {
-		return match[1];
-	}
-	return timestamp;
-}
-
-/**
- * Format the date portion of an ISO timestamp.
- * Returns "YYYY-MM-DD".
- */
-function formatDate(timestamp: string): string {
-	const match = /^(\d{4}-\d{2}-\d{2})/.exec(timestamp);
-	if (match?.[1]) {
-		return match[1];
-	}
-	return "";
-}
-
-/**
- * Build a detail string for a timeline event based on its type and fields.
- */
-function buildEventDetail(event: StoredEvent): string {
-	const parts: string[] = [];
-
-	if (event.toolName) {
-		parts.push(`tool=${event.toolName}`);
-	}
-
-	if (event.toolDurationMs !== null) {
-		parts.push(`duration=${event.toolDurationMs}ms`);
-	}
-
-	if (event.data) {
-		try {
-			const parsed: unknown = JSON.parse(event.data);
-			if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-				const data = parsed as Record<string, unknown>;
-				for (const [key, value] of Object.entries(data)) {
-					if (value !== null && value !== undefined) {
-						const strValue = typeof value === "string" ? value : JSON.stringify(value);
-						// Truncate long values
-						const truncated = strValue.length > 80 ? `${strValue.slice(0, 77)}...` : strValue;
-						parts.push(`${key}=${truncated}`);
-					}
-				}
-			}
-		} catch {
-			// data is not valid JSON; show it raw if short enough
-			if (event.data.length <= 80) {
-				parts.push(event.data);
-			}
-		}
-	}
-
-	return parts.join(" ");
-}
-
 /**
  * Print events as a formatted timeline with ANSI colors.
  */
 function printTimeline(events: StoredEvent[], agentName: string, useAbsoluteTime: boolean): void {
 	const w = process.stdout.write.bind(process.stdout);
 
-	w(`${color.bold(`Timeline for ${accent(agentName)}`)}\n`);
-	w(`${"=".repeat(70)}\n`);
+	w(`${renderHeader(`Timeline for ${accent(agentName)}`)}\n`);
 
 	if (events.length === 0) {
 		w(`${color.dim("No events found.")}\n`);
@@ -157,10 +62,7 @@ function printTimeline(events: StoredEvent[], agentName: string, useAbsoluteTime
 			? formatAbsoluteTime(event.createdAt)
 			: formatRelativeTime(event.createdAt);
 
-		const eventInfo = EVENT_LABELS[event.eventType] ?? {
-			label: event.eventType.padEnd(10),
-			color: color.gray,
-		};
+		const label = eventLabel(event.eventType);
 
 		const levelColorFn =
 			event.level === "error" ? color.red : event.level === "warn" ? color.yellow : null;
@@ -173,7 +75,7 @@ function printTimeline(events: StoredEvent[], agentName: string, useAbsoluteTime
 
 		w(
 			`${color.dim(timeStr.padStart(10))} ` +
-				`${applyLevel(eventInfo.color(color.bold(eventInfo.label)))}` +
+				`${applyLevel(label.color(color.bold(label.full)))}` +
 				`${agentLabel}${detailSuffix}\n`,
 		);
 	}

package/src/config.ts

@@ -62,6 +62,9 @@ export const DEFAULT_CONFIG: OverstoryConfig = {
 		verbose: false,
 		redactSecrets: true,
 	},
+	runtime: {
+		default: "claude",
+	},
 };
 
 const CONFIG_FILENAME = "config.yaml";
@@ -625,6 +628,13 @@ function validateConfig(config: OverstoryConfig): void {
 		}
 	}
 
+	// runtime.default must be a string if present
+	if (config.runtime !== undefined && typeof config.runtime.default !== "string") {
+		process.stderr.write(
+			`[overstory] WARNING: runtime.default must be a string. Got: ${typeof config.runtime.default}. Ignoring.\n`,
+		);
+	}
+
 	// models: validate each value — accepts aliases and provider-prefixed refs
 	const validAliases = ["sonnet", "opus", "haiku"];
 	const toolHeavyRoles = ["builder", "scout"];

package/src/index.ts

@@ -45,7 +45,7 @@ import { OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.6.11";
+export const VERSION = "0.7.0";
 
 const rawArgs = process.argv.slice(2);
 
@@ -255,6 +255,7 @@ program
 	.option("--max-agents <n>", "Max children per lead (overrides config)")
 	.option("--skip-review", "Skip review phase for lead agents")
 	.option("--dispatch-max-agents <n>", "Per-lead max agents ceiling (injected into overlay)")
+	.option("--runtime <name>", "Runtime adapter (default: config or claude)")
 	.option("--json", "Output result as JSON")
 	.action(async (taskId, opts) => {
 		await slingCommand(taskId, opts);

package/src/logging/format.ts

@@ -0,0 +1,214 @@
+/**
+ * Shared formatting utilities for overstory CLI output.
+ *
+ * Duration, timestamp, event detail, agent color mapping, and status color
+ * helpers used across all observability commands.
+ */
+
+import type { StoredEvent } from "../types.ts";
+import type { ColorFn } from "./color.ts";
+import { color, noColor } from "./color.ts";
+import { AGENT_COLORS } from "./theme.ts";
+
+// === Duration ===
+
+/**
+ * Formats a duration in milliseconds to a human-readable string.
+ * Examples: "0s", "12s", "3m 45s", "2h 15m"
+ */
+export function formatDuration(ms: number): string {
+	if (ms === 0) return "0s";
+	const totalSeconds = Math.floor(ms / 1000);
+	const hours = Math.floor(totalSeconds / 3600);
+	const minutes = Math.floor((totalSeconds % 3600) / 60);
+	const seconds = totalSeconds % 60;
+	if (hours > 0) {
+		return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+	}
+	if (minutes > 0) {
+		return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+	}
+	return `${seconds}s`;
+}
+
+// === Timestamps ===
+
+/**
+ * Extracts "HH:MM:SS" from an ISO 8601 timestamp string.
+ * Returns the raw substring if the timestamp is well-formed.
+ */
+export function formatAbsoluteTime(timestamp: string): string {
+	// ISO format: "YYYY-MM-DDTHH:MM:SS..." or "YYYY-MM-DD HH:MM:SS..."
+	const match = timestamp.match(/T?(\d{2}:\d{2}:\d{2})/);
+	return match?.[1] ?? timestamp;
+}
+
+/**
+ * Extracts "YYYY-MM-DD" from an ISO 8601 timestamp string.
+ */
+export function formatDate(timestamp: string): string {
+	const match = timestamp.match(/^(\d{4}-\d{2}-\d{2})/);
+	return match?.[1] ?? timestamp;
+}
+
+/**
+ * Formats a timestamp as a human-readable relative time string.
+ * Examples: "12s ago", "3m ago", "2h ago", "5d ago"
+ */
+export function formatRelativeTime(timestamp: string): string {
+	const now = Date.now();
+	const then = new Date(timestamp).getTime();
+	const diffMs = now - then;
+	if (diffMs < 0) return "just now";
+	const diffSeconds = Math.floor(diffMs / 1000);
+	const diffMinutes = Math.floor(diffSeconds / 60);
+	const diffHours = Math.floor(diffMinutes / 60);
+	const diffDays = Math.floor(diffHours / 24);
+	if (diffDays > 0) return `${diffDays}d ago`;
+	if (diffHours > 0) return `${diffHours}h ago`;
+	if (diffMinutes > 0) return `${diffMinutes}m ago`;
+	return `${diffSeconds}s ago`;
+}
+
+// === Event Details ===
+
+/**
+ * Builds a compact "key=value" detail string from a StoredEvent's fields.
+ * Values are truncated to maxValueLen (default 80) characters.
+ */
+export function buildEventDetail(event: StoredEvent, maxValueLen = 80): string {
+	const parts: string[] = [];
+
+	if (event.toolName) {
+		parts.push(`tool=${event.toolName}`);
+	}
+	if (event.toolArgs) {
+		const truncated =
+			event.toolArgs.length > maxValueLen
+				? `${event.toolArgs.slice(0, maxValueLen)}…`
+				: event.toolArgs;
+		parts.push(`args=${truncated}`);
+	}
+	if (event.toolDurationMs !== null && event.toolDurationMs !== undefined) {
+		parts.push(`dur=${event.toolDurationMs}ms`);
+	}
+	if (event.data) {
+		const truncated =
+			event.data.length > maxValueLen ? `${event.data.slice(0, maxValueLen)}…` : event.data;
+		parts.push(`data=${truncated}`);
+	}
+
+	return parts.join(" ");
+}
+
+// === Agent Color Mapping ===
+
+/**
+ * Builds a stable color map for agents by first-appearance order in events.
+ * Agents are assigned colors from AGENT_COLORS cycling as needed.
+ */
+export function buildAgentColorMap(events: StoredEvent[]): Map<string, ColorFn> {
+	const colorMap = new Map<string, ColorFn>();
+	let idx = 0;
+	for (const event of events) {
+		if (!colorMap.has(event.agentName)) {
+			const colorFn = AGENT_COLORS[idx % AGENT_COLORS.length] ?? noColor;
+			colorMap.set(event.agentName, colorFn);
+			idx++;
+		}
+	}
+	return colorMap;
+}
+
+/**
+ * Extends an existing agent color map with new agents from the given events.
+ * Used in follow mode to add agents discovered in incremental event batches.
+ */
+export function extendAgentColorMap(colorMap: Map<string, ColorFn>, events: StoredEvent[]): void {
+	let idx = colorMap.size;
+	for (const event of events) {
+		if (!colorMap.has(event.agentName)) {
+			const colorFn = AGENT_COLORS[idx % AGENT_COLORS.length] ?? noColor;
+			colorMap.set(event.agentName, colorFn);
+			idx++;
+		}
+	}
+}
+
+// === Status Colors ===
+
+/**
+ * Returns a color function for a merge status string.
+ * pending=yellow, merging=blue, conflict=red, merged=green
+ */
+export function mergeStatusColor(status: string): ColorFn {
+	switch (status) {
+		case "pending":
+			return color.yellow;
+		case "merging":
+			return color.blue;
+		case "conflict":
+			return color.red;
+		case "merged":
+			return color.green;
+		default:
+			return (text: string) => text;
+	}
+}
+
+/**
+ * Returns a color function for a priority string.
+ * urgent=red, high=yellow, normal=identity, low=dim
+ */
+export function priorityColor(priority: string): ColorFn {
+	switch (priority) {
+		case "urgent":
+			return color.red;
+		case "high":
+			return color.yellow;
+		case "normal":
+			return (text: string) => text;
+		case "low":
+			return color.dim;
+		default:
+			return (text: string) => text;
+	}
+}
+
+/**
+ * Returns a color function for a log level string.
+ * debug=gray, info=blue, warn=yellow, error=red
+ */
+export function logLevelColor(level: string): ColorFn {
+	switch (level) {
+		case "debug":
+			return color.gray;
+		case "info":
+			return color.blue;
+		case "warn":
+			return color.yellow;
+		case "error":
+			return color.red;
+		default:
+			return (text: string) => text;
+	}
+}
+
+/**
+ * Returns a 3-character label for a log level string.
+ * debug="DBG", info="INF", warn="WRN", error="ERR"
+ */
+export function logLevelLabel(level: string): string {
+	switch (level) {
+		case "debug":
+			return "DBG";
+		case "info":
+			return "INF";
+		case "warn":
+			return "WRN";
+		case "error":
+			return "ERR";
+		default:
+			return level.slice(0, 3).toUpperCase();
+	}
+}