@os-eco/overstory-cli 0.9.4 → 0.11.0

package/src/agents/scope-detect.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test } from "bun:test";
+import {
+	detectScopeViolation,
+	findScopeViolations,
+	hasExpansionReason,
+	IMPLEMENTATION_CAPABILITIES,
+	parseExpansionReasonsFromGitLog,
+} from "./scope-detect.ts";
+
+describe("findScopeViolations", () => {
+	test("literal match: in-scope file is not a violation", () => {
+		const result = findScopeViolations(["src/foo.ts"], ["src/foo.ts"]);
+		expect(result).toEqual([]);
+	});
+
+	test("glob match: src/foo/**/*.ts allows nested file", () => {
+		const result = findScopeViolations(
+			["src/foo/bar/baz.ts", "src/foo/qux.ts"],
+			["src/foo/**/*.ts"],
+		);
+		expect(result).toEqual([]);
+	});
+
+	test("out-of-scope file is reported", () => {
+		const result = findScopeViolations(["src/other.ts"], ["src/foo.ts"]);
+		expect(result).toEqual(["src/other.ts"]);
+	});
+
+	test("empty fileScope is treated as unrestricted", () => {
+		const result = findScopeViolations(["any/file.ts", "another.ts"], []);
+		expect(result).toEqual([]);
+	});
+
+	test("partial violations: returns only the out-of-scope subset", () => {
+		const result = findScopeViolations(
+			["src/foo.ts", "src/other.ts", "src/bar.ts"],
+			["src/foo.ts", "src/bar.ts"],
+		);
+		expect(result).toEqual(["src/other.ts"]);
+	});
+
+	test("glob match: literal path equals scope entry without a glob char", () => {
+		const result = findScopeViolations(["a.ts"], ["a.ts"]);
+		expect(result).toEqual([]);
+	});
+});
+
+describe("hasExpansionReason", () => {
+	test("expansion_reason: with value → true", () => {
+		expect(hasExpansionReason("expansion_reason: foo")).toBe(true);
+	});
+
+	test("Expansion_Reason: case-insensitive → true", () => {
+		expect(hasExpansionReason("Expansion_Reason: bar")).toBe(true);
+	});
+
+	test("EXPANSION_REASON: multi-word value → true", () => {
+		expect(hasExpansionReason("EXPANSION_REASON: baz quux")).toBe(true);
+	});
+
+	test("expansion_reason: empty value → false", () => {
+		expect(hasExpansionReason("expansion_reason:")).toBe(false);
+	});
+
+	test("expansion_reason: only whitespace → false", () => {
+		expect(hasExpansionReason("expansion_reason:   ")).toBe(false);
+	});
+
+	test("expansion-reason: hyphen separator → false", () => {
+		expect(hasExpansionReason("expansion-reason: foo")).toBe(false);
+	});
+
+	test("no marker → false", () => {
+		expect(hasExpansionReason("no reason here")).toBe(false);
+	});
+
+	test("marker embedded in commit body with prefix → true", () => {
+		const body = "Refactor the thing\n\nexpansion_reason: had to update shared types\n";
+		expect(hasExpansionReason(body)).toBe(true);
+	});
+});
+
+describe("parseExpansionReasonsFromGitLog", () => {
+	test("returns each value across multiple commit bodies", () => {
+		const log = [
+			"feat: a thing",
+			"",
+			"expansion_reason: needed shared type",
+			"",
+			"fix: another thing",
+			"",
+			"expansion_reason: had to update barrel export",
+		].join("\n");
+		const result = parseExpansionReasonsFromGitLog(log);
+		expect(result).toEqual(["needed shared type", "had to update barrel export"]);
+	});
+
+	test("trims whitespace around values", () => {
+		const log = "expansion_reason:    surrounded by spaces   \n";
+		const result = parseExpansionReasonsFromGitLog(log);
+		expect(result).toEqual(["surrounded by spaces"]);
+	});
+
+	test("ignores commits without the marker", () => {
+		const log = "feat: regular commit\n\nfix: another\n";
+		expect(parseExpansionReasonsFromGitLog(log)).toEqual([]);
+	});
+
+	test("empty log returns empty array", () => {
+		expect(parseExpansionReasonsFromGitLog("")).toEqual([]);
+	});
+
+	test("case-insensitive match", () => {
+		const log = "Expansion_Reason: capitalized variant\n";
+		expect(parseExpansionReasonsFromGitLog(log)).toEqual(["capitalized variant"]);
+	});
+});
+
+describe("detectScopeViolation", () => {
+	test("returns expected violations and expansion reasons via stub", () => {
+		const stub = (args: string[]): string => {
+			if (args[0] === "diff") return "src/foo.ts\nsrc/other.ts\n";
+			if (args[0] === "log") return "feat: change\n\nexpansion_reason: cross-cutting\n";
+			return "";
+		};
+		const result = detectScopeViolation({
+			worktreePath: "/tmp/wt",
+			baseRef: "main",
+			fileScope: ["src/foo.ts"],
+			gitRunner: stub,
+		});
+		expect(result.violations).toEqual(["src/other.ts"]);
+		expect(result.expansionReasons).toEqual(["cross-cutting"]);
+	});
+
+	test("returns empty when stub throws", () => {
+		const stub = (): string => {
+			throw new Error("boom");
+		};
+		const result = detectScopeViolation({
+			worktreePath: "/tmp/wt",
+			baseRef: "main",
+			fileScope: ["src/foo.ts"],
+			gitRunner: stub,
+		});
+		expect(result.violations).toEqual([]);
+		expect(result.expansionReasons).toEqual([]);
+	});
+
+	test("empty fileScope yields no violations regardless of diff", () => {
+		const stub = (args: string[]): string => {
+			if (args[0] === "diff") return "src/anything.ts\n";
+			return "";
+		};
+		const result = detectScopeViolation({
+			worktreePath: "/tmp/wt",
+			baseRef: "main",
+			fileScope: [],
+			gitRunner: stub,
+		});
+		expect(result.violations).toEqual([]);
+	});
+
+	test("blank diff lines are filtered", () => {
+		const stub = (args: string[]): string => {
+			if (args[0] === "diff") return "\nsrc/foo.ts\n\n\nsrc/bar.ts\n";
+			return "";
+		};
+		const result = detectScopeViolation({
+			worktreePath: "/tmp/wt",
+			baseRef: "main",
+			fileScope: ["src/foo.ts"],
+			gitRunner: stub,
+		});
+		expect(result.violations).toEqual(["src/bar.ts"]);
+	});
+});
+
+describe("IMPLEMENTATION_CAPABILITIES", () => {
+	test("includes builder and merger", () => {
+		expect(IMPLEMENTATION_CAPABILITIES.has("builder")).toBe(true);
+		expect(IMPLEMENTATION_CAPABILITIES.has("merger")).toBe(true);
+	});
+
+	test("excludes read-only roles", () => {
+		expect(IMPLEMENTATION_CAPABILITIES.has("scout")).toBe(false);
+		expect(IMPLEMENTATION_CAPABILITIES.has("reviewer")).toBe(false);
+		expect(IMPLEMENTATION_CAPABILITIES.has("lead")).toBe(false);
+	});
+});

package/src/agents/scope-detect.ts

@@ -0,0 +1,146 @@
+/**
+ * Scope-violation detection for builder/merger turns (overstory-9f4d).
+ *
+ * Surfaces a soft, advisory signal when an agent's modified files exceed its
+ * declared FILE_SCOPE without an `expansion_reason:` justification. The
+ * turn-runner consumes this on terminal-mail observation; the lead reads the
+ * `events.db` record during merge verification.
+ *
+ * This is observability only — never a hard block. All errors are swallowed.
+ */
+
+/**
+ * Capabilities allowed to modify files. Mirrors the set in
+ * `src/agents/hooks-deployer.ts`. Read-only roles (scout, reviewer) do not
+ * commit work, so scope detection is a no-op for them. Lead is excluded for
+ * the same reason — leads delegate, they don't touch files directly.
+ */
+export const IMPLEMENTATION_CAPABILITIES: ReadonlySet<string> = new Set(["builder", "merger"]);
+
+/**
+ * Synchronous git runner contract. Accepts argv (without the `git` prefix) and
+ * a working directory; returns combined stdout. Tests inject a stub; production
+ * calls `Bun.spawnSync(["git", ...args], { cwd })`.
+ */
+export type GitRunner = (args: string[], cwd: string) => string;
+
+const defaultGitRunner: GitRunner = (args, cwd) => {
+	const proc = Bun.spawnSync(["git", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
+	if (proc.exitCode !== 0) {
+		return "";
+	}
+	return proc.stdout.toString();
+};
+
+/**
+ * Return the subset of `modifiedFiles` not covered by any FILE_SCOPE entry.
+ *
+ * - Empty `fileScope` is treated as unrestricted: returns `[]`.
+ * - A file is in scope when any scope entry matches it literally OR when
+ *   `new Bun.Glob(entry).match(file)` returns true.
+ */
+export function findScopeViolations(modifiedFiles: string[], fileScope: string[]): string[] {
+	if (fileScope.length === 0) return [];
+
+	const globs: Array<{ entry: string; glob: Bun.Glob }> = [];
+	for (const entry of fileScope) {
+		try {
+			globs.push({ entry, glob: new Bun.Glob(entry) });
+		} catch {
+			// malformed glob — fall back to literal-only match for this entry
+			globs.push({ entry, glob: new Bun.Glob(entry.replace(/[*?[\]{}]/g, "\\$&")) });
+		}
+	}
+
+	const violations: string[] = [];
+	for (const file of modifiedFiles) {
+		let matched = false;
+		for (const { entry, glob } of globs) {
+			if (entry === file) {
+				matched = true;
+				break;
+			}
+			try {
+				if (glob.match(file)) {
+					matched = true;
+					break;
+				}
+			} catch {
+				// ignore malformed pattern; continue
+			}
+		}
+		if (!matched) violations.push(file);
+	}
+	return violations;
+}
+
+/**
+ * Case-insensitive check for `expansion_reason:` followed by at least one
+ * non-whitespace character before the next newline.
+ *
+ * - Matches `expansion_reason: foo`, `Expansion_Reason: bar`, `EXPANSION_REASON: baz quux`.
+ * - Rejects `expansion_reason:` (empty value) and `expansion-reason: foo` (different separator).
+ */
+export function hasExpansionReason(message: string): boolean {
+	return /expansion_reason:[^\S\n]*\S+/i.test(message);
+}
+
+/**
+ * Parse `expansion_reason:` values from the output of `git log --format=%B <range>`.
+ * Returns each value (trimmed) in encounter order. Commits without the marker
+ * are ignored.
+ */
+export function parseExpansionReasonsFromGitLog(log: string): string[] {
+	const reasons: string[] = [];
+	const re = /expansion_reason:[^\S\n]*([^\n]*\S)/gi;
+	let m: RegExpExecArray | null = re.exec(log);
+	while (m !== null) {
+		const value = m[1]?.trim();
+		if (value && value.length > 0) reasons.push(value);
+		m = re.exec(log);
+	}
+	return reasons;
+}
+
+export interface DetectScopeViolationOpts {
+	worktreePath: string;
+	baseRef: string;
+	fileScope: string[];
+	/** Test injection — replaces `Bun.spawnSync` for git calls. */
+	gitRunner?: GitRunner;
+}
+
+export interface ScopeViolationResult {
+	violations: string[];
+	expansionReasons: string[];
+}
+
+/**
+ * Detect scope violations for a worktree at HEAD relative to `baseRef`.
+ *
+ * - Runs `git diff --name-only baseRef...HEAD` to enumerate modified files.
+ * - Runs `git log --format=%B baseRef..HEAD` and parses `expansion_reason:`
+ *   markers from commit bodies.
+ *
+ * Always returns. Any failure (git error, parse failure) yields
+ * `{ violations: [], expansionReasons: [] }` — this is an advisory signal and
+ * must never break the runner.
+ */
+export function detectScopeViolation(opts: DetectScopeViolationOpts): ScopeViolationResult {
+	const runner = opts.gitRunner ?? defaultGitRunner;
+	try {
+		const diffOut = runner(["diff", "--name-only", `${opts.baseRef}...HEAD`], opts.worktreePath);
+		const modifiedFiles = diffOut
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((line) => line.length > 0);
+
+		const logOut = runner(["log", "--format=%B", `${opts.baseRef}..HEAD`], opts.worktreePath);
+		const expansionReasons = parseExpansionReasonsFromGitLog(logOut);
+
+		const violations = findScopeViolations(modifiedFiles, opts.fileScope);
+		return { violations, expansionReasons };
+	} catch {
+		return { violations: [], expansionReasons: [] };
+	}
+}

package/src/agents/turn-lock.test.ts

@@ -0,0 +1,181 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	_resetInProcessLocks,
+	acquireTurnLock,
+	readTurnLock,
+	turnLockDbPath,
+} from "./turn-lock.ts";
+
+describe("turn-lock", () => {
+	let overstoryDir: string;
+
+	beforeEach(async () => {
+		overstoryDir = await mkdtemp(join(tmpdir(), "overstory-turnlock-test-"));
+		_resetInProcessLocks();
+	});
+
+	afterEach(async () => {
+		_resetInProcessLocks();
+		await rm(overstoryDir, { recursive: true, force: true });
+	});
+
+	test("turnLockDbPath joins overstory dir + turn-locks.db", () => {
+		expect(turnLockDbPath("/tmp/overstory")).toBe("/tmp/overstory/turn-locks.db");
+	});
+
+	test("acquire creates the row and records holder pid", async () => {
+		const handle = await acquireTurnLock({ agentName: "alpha", overstoryDir });
+		try {
+			const state = readTurnLock(overstoryDir, "alpha");
+			expect(state.heldByPid).toBe(process.pid);
+			expect(state.acquiredAt).toBeTruthy();
+		} finally {
+			handle.release();
+		}
+	});
+
+	test("release clears the row and is idempotent", async () => {
+		const handle = await acquireTurnLock({ agentName: "alpha", overstoryDir });
+		handle.release();
+		// Calling release a second time must not throw.
+		handle.release();
+		const state = readTurnLock(overstoryDir, "alpha");
+		expect(state.heldByPid).toBeNull();
+		expect(state.acquiredAt).toBeNull();
+	});
+
+	test("two acquires for the same agent serialize via in-process queue", async () => {
+		// Track entry/exit windows via timestamps. The second call must start
+		// AFTER the first releases, never overlap.
+		const events: Array<{ id: number; phase: "enter" | "exit"; ts: number }> = [];
+
+		const work = async (id: number, holdMs: number): Promise<void> => {
+			const handle = await acquireTurnLock({ agentName: "shared", overstoryDir });
+			events.push({ id, phase: "enter", ts: Date.now() });
+			await Bun.sleep(holdMs);
+			events.push({ id, phase: "exit", ts: Date.now() });
+			handle.release();
+		};
+
+		await Promise.all([work(1, 100), work(2, 50)]);
+
+		// Sort events by timestamp; verify each acquire's enter follows the
+		// previous holder's exit.
+		const ordered = [...events].sort((a, b) => a.ts - b.ts);
+		expect(ordered.length).toBe(4);
+		expect(ordered[0]?.phase).toBe("enter");
+		expect(ordered[1]?.phase).toBe("exit");
+		expect(ordered[1]?.id).toBe(ordered[0]?.id);
+		expect(ordered[2]?.phase).toBe("enter");
+		expect(ordered[3]?.phase).toBe("exit");
+		expect(ordered[3]?.id).toBe(ordered[2]?.id);
+	});
+
+	test("acquires for different agents proceed concurrently", async () => {
+		// Both calls should overlap because the in-process map is keyed per agent.
+		let active = 0;
+		let maxActive = 0;
+		const work = async (name: string): Promise<void> => {
+			const handle = await acquireTurnLock({ agentName: name, overstoryDir });
+			active++;
+			maxActive = Math.max(maxActive, active);
+			await Bun.sleep(80);
+			active--;
+			handle.release();
+		};
+
+		await Promise.all([work("alpha"), work("beta"), work("gamma")]);
+		expect(maxActive).toBeGreaterThan(1);
+	});
+
+	test("stale lock (dead pid) is taken over by next acquirer", async () => {
+		// Inject _isProcessAlive that says the recorded holder is gone.
+		const handle = await acquireTurnLock({
+			agentName: "stale",
+			overstoryDir,
+			ownerPid: 99999, // pretend we are this dead pid
+			_isProcessAlive: () => true, // claim alive to plant the lock
+		});
+		// Don't call release() — we want the row to look orphaned.
+
+		// Reset in-process locks so the next call is not blocked by the queue
+		// from the same Bun process. Cross-process is what we are exercising.
+		_resetInProcessLocks();
+
+		const stolen = await acquireTurnLock({
+			agentName: "stale",
+			overstoryDir,
+			ownerPid: 12345,
+			_isProcessAlive: () => false, // prior holder reported dead
+		});
+		try {
+			const state = readTurnLock(overstoryDir, "stale");
+			expect(state.heldByPid).toBe(12345);
+		} finally {
+			stolen.release();
+			// release() of the original handle would still be safe because the
+			// row pid no longer matches its ownerPid (99999).
+			handle.release();
+		}
+	});
+
+	test("acquire times out when the lock is held by a live foreign pid", async () => {
+		// Plant a lock owned by a different live pid (we say always-alive).
+		const planted = await acquireTurnLock({
+			agentName: "blocked",
+			overstoryDir,
+			ownerPid: 77777,
+			_isProcessAlive: () => true,
+		});
+		// Intentionally do NOT release planted — keep the row active.
+
+		_resetInProcessLocks();
+
+		const start = Date.now();
+		await expect(
+			acquireTurnLock({
+				agentName: "blocked",
+				overstoryDir,
+				ownerPid: 88888,
+				_isProcessAlive: () => true,
+				timeoutMs: 200,
+				pollMs: 25,
+			}),
+		).rejects.toThrow(/timed out/);
+		const elapsed = Date.now() - start;
+		expect(elapsed).toBeGreaterThanOrEqual(150);
+
+		planted.release();
+	});
+
+	test("re-acquire by the same owner pid is allowed (re-entrant by pid)", async () => {
+		// First acquire records pid X. A subsequent acquire by the same pid
+		// (after in-process queue clears) should succeed without timing out
+		// even if the row still names X — this models recovery from a crashed
+		// in-process holder where the SQLite row was never released.
+		const first = await acquireTurnLock({
+			agentName: "reentry",
+			overstoryDir,
+			ownerPid: 4242,
+		});
+		// Simulate an in-process crash that lost the in-process tail.
+		_resetInProcessLocks();
+
+		const second = await acquireTurnLock({
+			agentName: "reentry",
+			overstoryDir,
+			ownerPid: 4242,
+			timeoutMs: 500,
+		});
+		try {
+			const state = readTurnLock(overstoryDir, "reentry");
+			expect(state.heldByPid).toBe(4242);
+		} finally {
+			second.release();
+			first.release();
+		}
+	});
+});