@os-eco/overstory-cli 0.8.3 → 0.8.5

package/src/events/tailer.ts

@@ -0,0 +1,235 @@
+/**
+ * Background NDJSON event tailer for headless agent stdout logs.
+ *
+ * Headless agents (e.g. Sapling) write NDJSON events to a stdout.log file
+ * in .overstory/logs/{agentName}/{timestamp}/stdout.log. After ov sling exits,
+ * nobody reads this stream — so ov status, ov dashboard, and ov feed cannot
+ * show live progress for headless agents.
+ *
+ * This module provides startEventTailer(), which polls the log file on a
+ * configurable interval, parses new NDJSON lines, and writes them into events.db
+ * via EventStore. The watchdog daemon starts a tailer for each headless agent
+ * session and stops it when the session completes or terminates.
+ */
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { EventStore, EventType } from "../types.ts";
+import { createEventStore } from "./store.ts";
+
+/**
+ * Handle to a running event tailer.
+ * Call stop() to halt polling and close the database connection.
+ */
+export interface TailerHandle {
+	/** Agent name being tailed. */
+	readonly agentName: string;
+	/** Absolute path to the stdout.log file being tailed. */
+	readonly logPath: string;
+	/** Stop polling and release all resources. */
+	stop(): void;
+}
+
+/** Map NDJSON event type strings to EventStore EventType. */
+function mapEventType(type: string): EventType {
+	switch (type) {
+		case "tool_start":
+			return "tool_start";
+		case "tool_end":
+			return "tool_end";
+		case "session_start":
+			return "session_start";
+		case "session_end":
+			return "session_end";
+		case "turn_start":
+			return "turn_start";
+		case "turn_end":
+			return "turn_end";
+		case "progress":
+			return "progress";
+		case "result":
+			return "result";
+		case "error":
+			return "error";
+		default:
+			return "custom";
+	}
+}
+
+/** Options for startEventTailer. */
+export interface TailerOptions {
+	/** Absolute path to the stdout.log file to tail. */
+	stdoutLogPath: string;
+	/** Agent name for event attribution in events.db. */
+	agentName: string;
+	/** Run ID to associate events with, or null. */
+	runId: string | null;
+	/** Absolute path to events.db. The tailer opens its own connection. */
+	eventsDbPath: string;
+	/** Poll interval in milliseconds (default: 500). */
+	pollIntervalMs?: number;
+	/** DI: injected EventStore for testing (overrides eventsDbPath). */
+	_eventStore?: EventStore;
+}
+
+/**
+ * Start a background event tailer for a headless agent's stdout.log.
+ *
+ * Polls the log file on a configurable interval, reads new bytes since the
+ * last poll using file.size as a byte cursor, parses NDJSON lines, and writes
+ * normalized events to events.db. Maintains its own SQLite connection so it
+ * can outlive the daemon tick that created it.
+ *
+ * All errors (file not found, parse failures, DB write failures) are swallowed
+ * silently — the tailer must never crash the watchdog daemon.
+ *
+ * @param opts - Tailer configuration (log path, agent, run, db path)
+ * @returns TailerHandle with stop() to halt polling and close resources
+ */
+export function startEventTailer(opts: TailerOptions): TailerHandle {
+	const { stdoutLogPath, agentName, runId, eventsDbPath, pollIntervalMs = 500 } = opts;
+
+	// Open a dedicated EventStore for this tailer's lifetime (not tick-scoped).
+	// Injected _eventStore is used for testing without an actual DB file.
+	let eventStore: EventStore | null = opts._eventStore ?? null;
+	let ownedEventStore = false;
+	if (!eventStore) {
+		try {
+			eventStore = createEventStore(eventsDbPath);
+			ownedEventStore = true;
+		} catch {
+			// If we can't open the event store, the tailer becomes a no-op.
+		}
+	}
+
+	let stopped = false;
+	let byteOffset = 0;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+
+	const poll = async (): Promise<void> => {
+		if (stopped) return;
+
+		try {
+			const file = Bun.file(stdoutLogPath);
+			const size = file.size;
+
+			if (size > byteOffset) {
+				// Read only new bytes since last poll — avoids re-processing old lines.
+				const newContent = await file.slice(byteOffset, size).text();
+				byteOffset = size;
+
+				const lines = newContent.split("\n");
+				for (const line of lines) {
+					const trimmed = line.trim();
+					if (!trimmed) continue;
+
+					let event: Record<string, unknown>;
+					try {
+						event = JSON.parse(trimmed) as Record<string, unknown>;
+					} catch {
+						// Skip malformed lines — partial writes or debug output.
+						continue;
+					}
+
+					const type = typeof event.type === "string" ? event.type : "custom";
+					const eventType = mapEventType(type);
+					const level = type === "error" ? "error" : "info";
+
+					// Extract tool name from various field names runtimes may use.
+					let toolName: string | null = null;
+					if (typeof event.tool === "string") {
+						toolName = event.tool;
+					} else if (typeof event.tool_name === "string") {
+						toolName = event.tool_name;
+					} else if (typeof event.toolName === "string") {
+						toolName = event.toolName;
+					}
+
+					const toolDurationMs = typeof event.duration_ms === "number" ? event.duration_ms : null;
+
+					try {
+						eventStore?.insert({
+							runId,
+							agentName,
+							sessionId: null,
+							eventType,
+							toolName,
+							toolArgs: null,
+							toolDurationMs,
+							level,
+							data: JSON.stringify(event),
+						});
+					} catch {
+						// DB write failure is non-fatal.
+					}
+				}
+			}
+		} catch {
+			// File read failure is non-fatal — agent may not have started writing yet.
+		}
+
+		if (!stopped) {
+			timer = setTimeout(poll, pollIntervalMs);
+		}
+	};
+
+	// Schedule first poll.
+	timer = setTimeout(poll, pollIntervalMs);
+
+	return {
+		agentName,
+		logPath: stdoutLogPath,
+		stop() {
+			stopped = true;
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+			// Close only the EventStore this tailer owns (not the injected one).
+			if (ownedEventStore && eventStore) {
+				try {
+					eventStore.close();
+				} catch {
+					// Non-fatal.
+				}
+				eventStore = null;
+			}
+		},
+	};
+}
+
+/**
+ * Discover the most recent stdout.log path for a headless agent.
+ *
+ * Scans .overstory/logs/{agentName}/ for timestamped session directories and
+ * returns the stdout.log path from the lexicographically last directory.
+ * Directories use ISO timestamps with `-` replacing `.` and `:`, which sort
+ * correctly in lexicographic order (e.g. 2026-03-05T14-52-26-089Z).
+ *
+ * Returns null if no log directory exists or no stdout.log is found.
+ *
+ * @param overstoryDir - Absolute path to .overstory/
+ * @param agentName - Agent name to look up (matches .overstory/logs/{agentName}/)
+ */
+export async function findLatestStdoutLog(
+	overstoryDir: string,
+	agentName: string,
+): Promise<string | null> {
+	const agentLogsDir = join(overstoryDir, "logs", agentName);
+	try {
+		const entries = await readdir(agentLogsDir);
+		if (entries.length === 0) return null;
+
+		// Lexicographic sort: ISO timestamps sort correctly without parsing.
+		const sorted = entries.sort();
+		const latest = sorted[sorted.length - 1];
+		if (!latest) return null;
+
+		const logPath = join(agentLogsDir, latest, "stdout.log");
+		const file = Bun.file(logPath);
+		if (await file.exists()) return logPath;
+		return null;
+	} catch {
+		return null;
+	}
+}

package/src/index.ts

@@ -49,7 +49,7 @@ 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.8.3";
+export const VERSION = "0.8.5";
 
 const rawArgs = process.argv.slice(2);
 

package/src/merge/resolver.test.ts

@@ -290,6 +290,105 @@ describe("createMergeResolver", () => {
 		});
 	});
 
+	describe("Dirty working tree pre-check", () => {
+		test("throws MergeError when unstaged changes exist on tracked files", async () => {
+			const repoDir = await createTempGitRepo();
+			try {
+				const defaultBranch = await getDefaultBranch(repoDir);
+				// Create a tracked file and then leave it modified (unstaged)
+				await commitFile(repoDir, "src/main.ts", "original content\n");
+				await runGitInDir(repoDir, ["checkout", "-b", "feature-branch"]);
+				await commitFile(repoDir, "src/feature.ts", "feature content\n");
+				await runGitInDir(repoDir, ["checkout", defaultBranch]);
+				// Modify a tracked file without staging
+				await Bun.write(`${repoDir}/src/main.ts`, "modified content\n");
+
+				const entry = makeTestEntry({
+					branchName: "feature-branch",
+					filesModified: ["src/feature.ts"],
+				});
+
+				const resolver = createMergeResolver({
+					aiResolveEnabled: false,
+					reimagineEnabled: false,
+				});
+
+				await expect(resolver.resolve(entry, defaultBranch, repoDir)).rejects.toThrow(MergeError);
+			} finally {
+				await cleanupTempDir(repoDir);
+			}
+		});
+
+		test("throws MergeError with message listing dirty files", async () => {
+			const repoDir = await createTempGitRepo();
+			try {
+				const defaultBranch = await getDefaultBranch(repoDir);
+				await commitFile(repoDir, "src/main.ts", "original content\n");
+				await runGitInDir(repoDir, ["checkout", "-b", "feature-branch"]);
+				await commitFile(repoDir, "src/feature.ts", "feature content\n");
+				await runGitInDir(repoDir, ["checkout", defaultBranch]);
+				await Bun.write(`${repoDir}/src/main.ts`, "modified content\n");
+
+				const entry = makeTestEntry({ branchName: "feature-branch" });
+				const resolver = createMergeResolver({ aiResolveEnabled: false, reimagineEnabled: false });
+
+				try {
+					await resolver.resolve(entry, defaultBranch, repoDir);
+					expect(true).toBe(false); // should not reach
+				} catch (err: unknown) {
+					expect(err).toBeInstanceOf(MergeError);
+					const mergeErr = err as MergeError;
+					expect(mergeErr.message).toContain("src/main.ts");
+					expect(mergeErr.message).toContain("Commit or stash");
+				}
+			} finally {
+				await cleanupTempDir(repoDir);
+			}
+		});
+
+		test("throws MergeError when staged but uncommitted changes exist", async () => {
+			const repoDir = await createTempGitRepo();
+			try {
+				const defaultBranch = await getDefaultBranch(repoDir);
+				await commitFile(repoDir, "src/main.ts", "original content\n");
+				await runGitInDir(repoDir, ["checkout", "-b", "feature-branch"]);
+				await commitFile(repoDir, "src/feature.ts", "feature content\n");
+				await runGitInDir(repoDir, ["checkout", defaultBranch]);
+				// Modify and stage (but don't commit)
+				await Bun.write(`${repoDir}/src/main.ts`, "staged but not committed\n");
+				await runGitInDir(repoDir, ["add", "src/main.ts"]);
+
+				const entry = makeTestEntry({ branchName: "feature-branch" });
+				const resolver = createMergeResolver({ aiResolveEnabled: false, reimagineEnabled: false });
+
+				await expect(resolver.resolve(entry, defaultBranch, repoDir)).rejects.toThrow(MergeError);
+			} finally {
+				await cleanupTempDir(repoDir);
+			}
+		});
+
+		test("clean working tree proceeds normally to Tier 1", async () => {
+			const repoDir = await createTempGitRepo();
+			try {
+				const defaultBranch = await getDefaultBranch(repoDir);
+				await setupCleanMerge(repoDir, defaultBranch);
+
+				const entry = makeTestEntry({
+					branchName: "feature-branch",
+					filesModified: ["src/feature-file.ts"],
+				});
+
+				const resolver = createMergeResolver({ aiResolveEnabled: false, reimagineEnabled: false });
+				const result = await resolver.resolve(entry, defaultBranch, repoDir);
+
+				expect(result.success).toBe(true);
+				expect(result.tier).toBe("clean-merge");
+			} finally {
+				await cleanupTempDir(repoDir);
+			}
+		});
+	});
+
 	describe("Tier 1 fail -> Tier 2: Auto-resolve", () => {
 		test("auto-resolves conflicts keeping incoming changes with correct content", async () => {
 			const repoDir = await createTempGitRepo();

package/src/merge/resolver.ts

@@ -50,6 +50,26 @@ async function runGit(
 	return { stdout, stderr, exitCode };
 }
 
+/**
+ * Get the list of tracked files with uncommitted changes (unstaged or staged).
+ * Returns deduplicated list of file paths. An empty list means the working tree is clean.
+ */
+async function checkDirtyWorkingTree(repoRoot: string): Promise<string[]> {
+	const { stdout: unstaged } = await runGit(repoRoot, ["diff", "--name-only"]);
+	const { stdout: staged } = await runGit(repoRoot, ["diff", "--name-only", "--cached"]);
+	const files = [
+		...unstaged
+			.trim()
+			.split("\n")
+			.filter((l) => l.length > 0),
+		...staged
+			.trim()
+			.split("\n")
+			.filter((l) => l.length > 0),
+	];
+	return [...new Set(files)];
+}
+
 /**
  * Get the list of conflicted files from `git diff --name-only --diff-filter=U`.
  */
@@ -593,6 +613,17 @@ export function createMergeResolver(options: {
 				}
 			}
 
+			// Pre-check: abort early if working tree has uncommitted changes.
+			// When dirty tracked files exist, git merge refuses to start (exit 1, no conflict markers),
+			// causing all tiers to cascade with empty conflict lists and a misleading final error.
+			const dirtyFiles = await checkDirtyWorkingTree(repoRoot);
+			if (dirtyFiles.length > 0) {
+				throw new MergeError(
+					`Working tree has uncommitted changes to tracked files: ${dirtyFiles.join(", ")}. Commit or stash changes before running ov merge.`,
+					{ branchName: entry.branchName },
+				);
+			}
+
 			let lastTier: ResolutionTier = "clean-merge";
 			let conflictFiles: string[] = [];
 

package/src/metrics/transcript.test.ts

@@ -6,7 +6,7 @@
  *
  * Coverage:
  *   - parseTranscriptUsage (transcript.ts)
- *   - estimateCost re-export (transcript.ts -> pricing.ts)
+ *   - estimateCost (pricing.ts, imported directly)
  *   - getPricingForModel (pricing.ts)
  */
 
@@ -15,8 +15,8 @@ import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { cleanupTempDir } from "../test-helpers.ts";
-import { getPricingForModel, estimateCost as pricingEstimateCost } from "./pricing.ts";
-import { estimateCost, parseTranscriptUsage } from "./transcript.ts";
+import { estimateCost, getPricingForModel } from "./pricing.ts";
+import { parseTranscriptUsage } from "./transcript.ts";
 
 let tempDir: string;
 
@@ -479,17 +479,5 @@ describe("getPricingForModel", () => {
 	});
 });
 
-// === re-export parity ===
-
-describe("estimateCost re-export parity", () => {
-	test("transcript.estimateCost and pricing.estimateCost produce same result", () => {
-		const usage = {
-			inputTokens: 1_000_000,
-			outputTokens: 1_000_000,
-			cacheReadTokens: 1_000_000,
-			cacheCreationTokens: 1_000_000,
-			modelUsed: "claude-opus-4-6",
-		};
-		expect(estimateCost(usage)).toBe(pricingEstimateCost(usage));
-	});
-});
+// estimateCost re-export removed from transcript.ts (overstory-aa00).
+// estimateCost is now imported directly from pricing.ts everywhere.

package/src/metrics/transcript.ts

@@ -27,8 +27,6 @@ import type { TokenUsage } from "./pricing.ts";
 
 export type TranscriptUsage = TokenUsage;
 
-export { estimateCost } from "./pricing.ts";
-
 /**
  * Narrow an unknown value to determine if it looks like a transcript assistant entry.
  * Returns the usage fields if valid, or null otherwise.

package/src/runtimes/claude.test.ts

@@ -651,7 +651,7 @@ describe("ClaudeRuntime integration: registry resolves 'claude' as default", ()
 
 	test("getRuntime rejects unknown runtimes", async () => {
 		const { getRuntime } = await import("./registry.ts");
-		expect(() => getRuntime("opencode")).toThrow('Unknown runtime: "opencode"');
 		expect(() => getRuntime("aider")).toThrow('Unknown runtime: "aider"');
+		expect(() => getRuntime("cursor")).toThrow('Unknown runtime: "cursor"');
 	});
 });

package/src/runtimes/claude.ts

@@ -5,7 +5,8 @@
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { deployHooks } from "../agents/hooks-deployer.ts";
-import { estimateCost, parseTranscriptUsage } from "../metrics/transcript.ts";
+import { estimateCost } from "../metrics/pricing.ts";
+import { parseTranscriptUsage } from "../metrics/transcript.ts";
 import type { ResolvedModel } from "../types.ts";
 import type {
 	AgentRuntime,
@@ -219,6 +220,22 @@ export class ClaudeRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/**
+	 * Return the Claude Code transcript directory for a given project root.
+	 *
+	 * Claude Code stores session transcripts at ~/.claude/projects/<projectKey>/
+	 * where <projectKey> is the project root path with "/" replaced by "-".
+	 *
+	 * @param projectRoot - Absolute path to the project root
+	 * @returns Absolute path to the transcript directory, or null if HOME is unavailable
+	 */
+	getTranscriptDir(projectRoot: string): string | null {
+		const home = process.env.HOME ?? "";
+		if (home.length === 0) return null;
+		const projectKey = projectRoot.replace(/\//g, "-");
+		return join(home, ".claude", "projects", projectKey);
+	}
 }
 
 /** Singleton instance for use in callers that do not need DI. */

package/src/runtimes/codex.ts

@@ -230,4 +230,9 @@ export class CodexRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Codex does not produce transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/copilot.ts

@@ -223,4 +223,9 @@ export class CopilotRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Copilot does not produce transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }

package/src/runtimes/gemini.ts

@@ -232,4 +232,9 @@ export class GeminiRuntime implements AgentRuntime {
 	buildEnv(model: ResolvedModel): Record<string, string> {
 		return model.env ?? {};
 	}
+
+	/** Gemini does not produce transcript files. */
+	getTranscriptDir(_projectRoot: string): string | null {
+		return null;
+	}
 }