@os-eco/overstory-cli 0.9.4 → 0.11.0

package/src/insights/quality-gates.test.ts

@@ -0,0 +1,141 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	cleanupTempDir,
+	commitFile,
+	createTempGitRepo,
+	getDefaultBranch,
+} from "../test-helpers.ts";
+import type { QualityGate } from "../types.ts";
+import { hasWorkToVerify, runQualityGates } from "./quality-gates.ts";
+
+describe("runQualityGates", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "qg-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	test("returns null when gates list is empty", async () => {
+		const result = await runQualityGates([], tempDir);
+		expect(result).toBeNull();
+	});
+
+	test("status is 'success' when all gates exit 0", async () => {
+		const gates: QualityGate[] = [
+			{ name: "True", command: "true", description: "always passes" },
+			{ name: "Echo", command: "echo ok", description: "always passes" },
+		];
+		const result = await runQualityGates(gates, tempDir);
+		expect(result).not.toBeNull();
+		expect(result?.status).toBe("success");
+		expect(result?.results).toHaveLength(2);
+		expect(result?.results.every((r) => r.passed)).toBe(true);
+	});
+
+	test("status is 'failure' when no gates exit 0", async () => {
+		const gates: QualityGate[] = [
+			{ name: "False1", command: "false", description: "always fails" },
+			{ name: "False2", command: "false", description: "always fails" },
+		];
+		const result = await runQualityGates(gates, tempDir);
+		expect(result).not.toBeNull();
+		expect(result?.status).toBe("failure");
+		expect(result?.results.every((r) => !r.passed)).toBe(true);
+	});
+
+	test("status is 'partial' on mixed exit codes", async () => {
+		const gates: QualityGate[] = [
+			{ name: "Pass", command: "true", description: "passes" },
+			{ name: "Fail", command: "false", description: "fails" },
+		];
+		const result = await runQualityGates(gates, tempDir);
+		expect(result).not.toBeNull();
+		expect(result?.status).toBe("partial");
+		expect(result?.results.filter((r) => r.passed)).toHaveLength(1);
+		expect(result?.results.filter((r) => !r.passed)).toHaveLength(1);
+	});
+
+	test("a gate that hangs past the timeout is treated as failed", async () => {
+		const gates: QualityGate[] = [
+			{ name: "Sleeper", command: "sleep 5", description: "intentionally slow" },
+		];
+		const result = await runQualityGates(gates, tempDir, { timeoutMs: 200 });
+		expect(result).not.toBeNull();
+		expect(result?.status).toBe("failure");
+		expect(result?.results[0]?.passed).toBe(false);
+		expect(result?.results[0]?.exitCode).toBe(-1);
+		// Should return well before the 5s the gate would otherwise take
+		expect(result?.totalDurationMs).toBeLessThan(2_000);
+	});
+
+	test("captures per-gate duration and exit code", async () => {
+		const gates: QualityGate[] = [{ name: "Quick", command: "true", description: "passes fast" }];
+		const result = await runQualityGates(gates, tempDir);
+		expect(result?.results[0]?.exitCode).toBe(0);
+		expect(result?.results[0]?.durationMs).toBeGreaterThanOrEqual(0);
+		expect(result?.totalDurationMs).toBeGreaterThanOrEqual(result?.results[0]?.durationMs ?? 0);
+	});
+});
+
+describe("hasWorkToVerify", () => {
+	let repoDir: string;
+
+	beforeEach(async () => {
+		repoDir = await createTempGitRepo();
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(repoDir);
+	});
+
+	test("returns false on a fresh repo with no commits past base and a clean tree", async () => {
+		const branch = await getDefaultBranch(repoDir);
+		const result = await hasWorkToVerify(repoDir, branch);
+		expect(result).toBe(false);
+	});
+
+	test("returns true when worktree has uncommitted changes", async () => {
+		const branch = await getDefaultBranch(repoDir);
+		await Bun.write(join(repoDir, "dirty.txt"), "uncommitted content");
+		const result = await hasWorkToVerify(repoDir, branch);
+		expect(result).toBe(true);
+	});
+
+	test("returns true when there are commits past base", async () => {
+		// Pin a "base-ref" branch at the initial commit, then add a new commit
+		// on the working branch so HEAD is one commit ahead of base-ref.
+		const proc = Bun.spawn(["git", "branch", "base-ref", "HEAD"], { cwd: repoDir });
+		await proc.exited;
+		await commitFile(repoDir, "new-file.txt", "second commit", "second commit");
+
+		const result = await hasWorkToVerify(repoDir, "base-ref");
+		expect(result).toBe(true);
+	});
+
+	test("returns true when base ref cannot be resolved (fail open)", async () => {
+		const result = await hasWorkToVerify(repoDir, "definitely-not-a-real-ref");
+		expect(result).toBe(true);
+	});
+
+	test("defaults baseRef to 'main' when not provided", async () => {
+		// On a clean repo with default branch 'main' the function should resolve
+		// 'main' successfully and report no work to verify.
+		const branch = await getDefaultBranch(repoDir);
+		// Skip this assertion if the default branch isn't 'main' (e.g., master on
+		// some CI runners) — fall back to passing the explicit branch.
+		if (branch === "main") {
+			const result = await hasWorkToVerify(repoDir);
+			expect(result).toBe(false);
+		} else {
+			const result = await hasWorkToVerify(repoDir, branch);
+			expect(result).toBe(false);
+		}
+	});
+});

package/src/insights/quality-gates.ts

@@ -0,0 +1,156 @@
+/**
+ * Quality-gate runner used at session-end to determine the outcome status
+ * threaded into mulch record writes (success / partial / failure).
+ *
+ * Used by `src/commands/log.ts` session-end handler. Cheap precheck via
+ * `hasWorkToVerify()` lets read-only agents (scout/reviewer) skip gate
+ * execution entirely when no commits or uncommitted changes exist.
+ */
+
+import type { QualityGate } from "../types.ts";
+
+export interface QualityGateResult {
+	name: string;
+	command: string;
+	passed: boolean;
+	durationMs: number;
+	exitCode: number;
+}
+
+export interface QualityGateOutcome {
+	status: "success" | "partial" | "failure";
+	results: QualityGateResult[];
+	totalDurationMs: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+
+/**
+ * Run each configured quality gate against `cwd` and aggregate the result.
+ *
+ * Returns null when `gates` is empty.
+ *
+ * - all passed -> "success"
+ * - none passed -> "failure"
+ * - mixed -> "partial"
+ */
+export async function runQualityGates(
+	gates: QualityGate[],
+	cwd: string,
+	options?: { timeoutMs?: number },
+): Promise<QualityGateOutcome | null> {
+	if (gates.length === 0) return null;
+
+	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const results: QualityGateResult[] = [];
+	const totalStart = Date.now();
+
+	for (const gate of gates) {
+		const argv = gate.command.split(/\s+/).filter((s) => s.length > 0);
+		if (argv.length === 0) {
+			results.push({
+				name: gate.name,
+				command: gate.command,
+				passed: false,
+				durationMs: 0,
+				exitCode: -1,
+			});
+			continue;
+		}
+
+		const start = Date.now();
+		let proc: ReturnType<typeof Bun.spawn> | undefined;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let timedOut = false;
+		try {
+			proc = Bun.spawn(argv, {
+				cwd,
+				stdout: "ignore",
+				stderr: "ignore",
+			});
+			timer = setTimeout(() => {
+				timedOut = true;
+				try {
+					proc?.kill();
+				} catch {
+					// best-effort kill
+				}
+			}, timeoutMs);
+			const exitCode = await proc.exited;
+			const durationMs = Date.now() - start;
+			results.push({
+				name: gate.name,
+				command: gate.command,
+				passed: !timedOut && exitCode === 0,
+				durationMs,
+				exitCode: timedOut ? -1 : exitCode,
+			});
+		} catch {
+			results.push({
+				name: gate.name,
+				command: gate.command,
+				passed: false,
+				durationMs: Date.now() - start,
+				exitCode: -1,
+			});
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	}
+
+	const passedCount = results.filter((r) => r.passed).length;
+	let status: "success" | "partial" | "failure";
+	if (passedCount === results.length) {
+		status = "success";
+	} else if (passedCount === 0) {
+		status = "failure";
+	} else {
+		status = "partial";
+	}
+
+	return {
+		status,
+		results,
+		totalDurationMs: Date.now() - totalStart,
+	};
+}
+
+/**
+ * Cheap precheck: returns true when the worktree has commits beyond `baseRef`
+ * or any uncommitted modifications. Used to skip gate execution for read-only
+ * agents that produced no work.
+ *
+ * Fails open: if HEAD or `baseRef` cannot be resolved, returns true so that
+ * gates still run rather than silently skipping.
+ */
+export async function hasWorkToVerify(cwd: string, baseRef = "main"): Promise<boolean> {
+	const head = await runGit(cwd, ["rev-parse", "--verify", "HEAD"]);
+	const base = await runGit(cwd, ["rev-parse", "--verify", baseRef]);
+	if (head.exitCode !== 0 || base.exitCode !== 0) return true;
+
+	const ahead = await runGit(cwd, ["rev-list", "--count", `${baseRef}..HEAD`]);
+	if (ahead.exitCode === 0) {
+		const count = Number.parseInt(ahead.stdout.trim(), 10);
+		if (Number.isFinite(count) && count > 0) return true;
+	}
+
+	const status = await runGit(cwd, ["status", "--porcelain"]);
+	if (status.exitCode === 0 && status.stdout.trim().length > 0) return true;
+
+	return false;
+}
+
+async function runGit(cwd: string, args: string[]): Promise<{ stdout: string; exitCode: number }> {
+	try {
+		const proc = Bun.spawn(["git", ...args], {
+			cwd,
+			stdout: "pipe",
+			stderr: "ignore",
+		});
+		const stdout = await new Response(proc.stdout).text();
+		const exitCode = await proc.exited;
+		return { stdout, exitCode };
+	} catch {
+		return { stdout: "", exitCode: -1 };
+	}
+}

package/src/json.ts

@@ -22,3 +22,32 @@ export function jsonOutput(command: string, data: Record<string, unknown>): void
 export function jsonError(command: string, error: string): void {
 	process.stdout.write(`${JSON.stringify({ success: false, command, error })}\n`);
 }
+
+/**
+ * Build a JSON success Response for HTTP API handlers.
+ * Envelope: { success: true, command: 'serve', data, nextCursor? }
+ */
+export function apiJson(
+	data: unknown,
+	init?: { status?: number; nextCursor?: string | null },
+): Response {
+	const envelope: Record<string, unknown> = { success: true, command: "serve", data };
+	if (init?.nextCursor != null) {
+		envelope.nextCursor = init.nextCursor;
+	}
+	return new Response(JSON.stringify(envelope), {
+		status: init?.status ?? 200,
+		headers: { "Content-Type": "application/json" },
+	});
+}
+
+/**
+ * Build a JSON error Response for HTTP API handlers.
+ * Envelope: { success: false, command: 'serve', error }
+ */
+export function apiError(message: string, status: number): Response {
+	return new Response(JSON.stringify({ success: false, command: "serve", error: message }), {
+		status,
+		headers: { "Content-Type": "application/json" },
+	});
+}

package/src/logging/theme.ts

@@ -14,6 +14,8 @@ import { brand, color, noColor, visibleLength } from "./color.ts";
 /** Maps agent states to their visual color functions. */
 const STATE_COLORS: Record<AgentState, ColorFn> = {
 	working: color.green,
+	in_turn: color.green,
+	between_turns: color.cyan,
 	booting: color.yellow,
 	stalled: color.red,
 	zombie: color.dim,
@@ -23,6 +25,8 @@ const STATE_COLORS: Record<AgentState, ColorFn> = {
 /** Maps agent states to their icon characters. */
 const STATE_ICONS: Record<AgentState, string> = {
 	working: ">",
+	in_turn: ">",
+	between_turns: "~",
 	booting: "~",
 	stalled: "!",
 	zombie: "x",

package/src/mail/client.ts

@@ -7,7 +7,7 @@
  */
 
 import { MailError } from "../errors.ts";
-import type { MailMessage, MailPayloadMap, MailProtocolType } from "../types.ts";
+import type { MailMessage, MailMessageType, MailPayloadMap, MailProtocolType } from "../types.ts";
 import type { MailStore } from "./store.ts";
 
 export interface MailClient {
@@ -42,7 +42,12 @@ export interface MailClient {
 	checkInject(agentName: string): string;
 
 	/** List messages with optional filters. */
-	list(filters?: { from?: string; to?: string; unread?: boolean }): MailMessage[];
+	list(filters?: {
+		from?: string;
+		to?: string;
+		unread?: boolean;
+		type?: MailMessageType;
+	}): MailMessage[];
 
 	/** Mark a message as read by ID. Returns whether the message was already read. */
 	markRead(id: string): { alreadyRead: boolean };
@@ -50,6 +55,9 @@ export interface MailClient {
 	/** Reply to a message. Returns the new message ID. */
 	reply(messageId: string, body: string, from: string): string;
 
+	/** Delete a single message by id. Returns true if a row was deleted. */
+	deleteById(id: string): boolean;
+
 	/** Close the underlying store. */
 	close(): void;
 }
@@ -75,6 +83,7 @@ export function parsePayload<T extends MailProtocolType>(
 /** Protocol types that represent structured coordination messages. */
 const PROTOCOL_TYPES = new Set<string>([
 	"worker_done",
+	"worker_died",
 	"merge_ready",
 	"merged",
 	"merge_failed",
@@ -187,6 +196,10 @@ export function createMailClient(store: MailStore): MailClient {
 			return { alreadyRead: false };
 		},
 
+		deleteById(id): boolean {
+			return store.deleteById(id);
+		},
+
 		reply(messageId, body, from): string {
 			const original = store.getById(messageId);
 			if (!original) {

package/src/mail/store.test.ts

@@ -437,6 +437,88 @@ describe("createMailStore", () => {
 			expect(filtered).toHaveLength(1);
 			expect(filtered[0]?.subject).toBe("msg1");
 		});
+
+		test("filters by type", () => {
+			store.insert({
+				id: "",
+				from: "lead-a",
+				to: "coordinator",
+				subject: "merge_ready: t1",
+				body: "ready",
+				type: "merge_ready",
+				priority: "normal",
+				threadId: null,
+			});
+			store.insert({
+				id: "",
+				from: "builder-a",
+				to: "lead-a",
+				subject: "Worker done",
+				body: "done",
+				type: "worker_done",
+				priority: "normal",
+				threadId: null,
+			});
+			store.insert({
+				id: "",
+				from: "lead-a",
+				to: "coordinator",
+				subject: "status",
+				body: "still going",
+				type: "status",
+				priority: "normal",
+				threadId: null,
+			});
+
+			const mr = store.getAll({ type: "merge_ready" });
+			expect(mr).toHaveLength(1);
+			expect(mr[0]?.subject).toBe("merge_ready: t1");
+
+			const wd = store.getAll({ type: "worker_done" });
+			expect(wd).toHaveLength(1);
+			expect(wd[0]?.subject).toBe("Worker done");
+		});
+
+		test("combines type with from filter", () => {
+			store.insert({
+				id: "",
+				from: "lead-a",
+				to: "coordinator",
+				subject: "merge_ready: t1",
+				body: "ready",
+				type: "merge_ready",
+				priority: "normal",
+				threadId: null,
+			});
+			store.insert({
+				id: "",
+				from: "lead-b",
+				to: "coordinator",
+				subject: "merge_ready: t2",
+				body: "ready",
+				type: "merge_ready",
+				priority: "normal",
+				threadId: null,
+			});
+
+			const mine = store.getAll({ from: "lead-a", type: "merge_ready" });
+			expect(mine).toHaveLength(1);
+			expect(mine[0]?.from).toBe("lead-a");
+		});
+
+		test("returns empty array when no rows match the type filter", () => {
+			store.insert({
+				id: "",
+				from: "agent-a",
+				to: "orchestrator",
+				subject: "msg",
+				body: "body",
+				type: "status",
+				priority: "normal",
+				threadId: null,
+			});
+			expect(store.getAll({ type: "merge_ready" })).toHaveLength(0);
+		});
 	});
 
 	describe("getByThread", () => {

package/src/mail/store.ts

@@ -8,7 +8,7 @@
 
 import { Database } from "bun:sqlite";
 import { MailError } from "../errors.ts";
-import type { MailMessage } from "../types.ts";
+import type { MailMessage, MailMessageType } from "../types.ts";
 import { MAIL_MESSAGE_TYPES } from "../types.ts";
 
 export interface MailStore {
@@ -16,10 +16,18 @@ export interface MailStore {
 		message: Omit<MailMessage, "read" | "createdAt" | "payload"> & { payload?: string | null },
 	): MailMessage;
 	getUnread(agentName: string): MailMessage[];
-	getAll(filters?: { from?: string; to?: string; unread?: boolean; limit?: number }): MailMessage[];
+	getAll(filters?: {
+		from?: string;
+		to?: string;
+		unread?: boolean;
+		type?: MailMessageType;
+		limit?: number;
+	}): MailMessage[];
 	getById(id: string): MailMessage | null;
 	getByThread(threadId: string): MailMessage[];
 	markRead(id: string): void;
+	/** Delete a single message by id. Returns true if a row was deleted. */
+	deleteById(id: string): boolean;
 	/** Delete messages matching the given criteria. Returns the number of messages deleted. */
 	purge(options: { all?: boolean; olderThanMs?: number; agent?: string }): number;
 	close(): void;
@@ -84,14 +92,21 @@ function migrateSchema(db: Database): void {
 	const hasPayloadColumn = row.sql.includes("payload");
 	const hasProtocolTypes = row.sql.includes("worker_done");
 	const hasDecisionGate = row.sql.includes("decision_gate");
+	const hasWorkerDied = row.sql.includes("worker_died");
 
 	// If schema is fully up to date, nothing to do
-	if (hasCheckConstraints && hasPayloadColumn && hasProtocolTypes && hasDecisionGate) {
+	if (
+		hasCheckConstraints &&
+		hasPayloadColumn &&
+		hasProtocolTypes &&
+		hasDecisionGate &&
+		hasWorkerDied
+	) {
 		return;
 	}
 
 	// If only missing the payload column (has correct CHECK constraints), use ALTER TABLE
-	if (hasCheckConstraints && hasProtocolTypes && !hasPayloadColumn) {
+	if (hasCheckConstraints && hasProtocolTypes && hasWorkerDied && !hasPayloadColumn) {
 		db.exec("ALTER TABLE messages ADD COLUMN payload TEXT");
 		return;
 	}
@@ -232,11 +247,16 @@ export function createMailStore(dbPath: string): MailStore {
 		UPDATE messages SET read = 1 WHERE id = $id
 	`);
 
+	const deleteByIdStmt = db.prepare<void, { $id: string }>(`
+		DELETE FROM messages WHERE id = $id
+	`);
+
 	// Dynamic filter queries are built at call time since the WHERE clause varies
 	function buildFilterQuery(filters?: {
 		from?: string;
 		to?: string;
 		unread?: boolean;
+		type?: MailMessageType;
 		limit?: number;
 	}): MailMessage[] {
 		const conditions: string[] = [];
@@ -254,6 +274,10 @@ export function createMailStore(dbPath: string): MailStore {
 			conditions.push("read = $read");
 			params.$read = filters.unread ? 0 : 1;
 		}
+		if (filters?.type !== undefined) {
+			conditions.push("type = $type");
+			params.$type = filters.type;
+		}
 
 		const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
 		const limitClause = filters?.limit !== undefined ? ` LIMIT $limit` : "";
@@ -315,6 +339,7 @@ export function createMailStore(dbPath: string): MailStore {
 			from?: string;
 			to?: string;
 			unread?: boolean;
+			type?: MailMessageType;
 			limit?: number;
 		}): MailMessage[] {
 			return buildFilterQuery(filters);
@@ -334,6 +359,18 @@ export function createMailStore(dbPath: string): MailStore {
 			markReadStmt.run({ $id: id });
 		},
 
+		deleteById(id: string): boolean {
+			try {
+				const result = deleteByIdStmt.run({ $id: id });
+				return result.changes > 0;
+			} catch (err) {
+				throw new MailError(`Failed to delete message: ${id}`, {
+					messageId: id,
+					cause: err instanceof Error ? err : undefined,
+				});
+			}
+		},
+
 		purge(options: { all?: boolean; olderThanMs?: number; agent?: string }): number {
 			// Count matching rows before deletion so we can report accurate numbers
 			if (options.all) {