@ag-eco/agentplate-cli 0.13.0

package/src/agents/scope-detect.ts

@@ -0,0 +1,146 @@
+/**
+ * Scope-violation detection for builder/merger turns (agentplate-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 agentplateDir: string;
+
+	beforeEach(async () => {
+		agentplateDir = await mkdtemp(join(tmpdir(), "agentplate-turnlock-test-"));
+		_resetInProcessLocks();
+	});
+
+	afterEach(async () => {
+		_resetInProcessLocks();
+		await rm(agentplateDir, { recursive: true, force: true });
+	});
+
+	test("turnLockDbPath joins agentplate dir + turn-locks.db", () => {
+		expect(turnLockDbPath("/tmp/agentplate")).toBe("/tmp/agentplate/turn-locks.db");
+	});
+
+	test("acquire creates the row and records holder pid", async () => {
+		const handle = await acquireTurnLock({ agentName: "alpha", agentplateDir });
+		try {
+			const state = readTurnLock(agentplateDir, "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", agentplateDir });
+		handle.release();
+		// Calling release a second time must not throw.
+		handle.release();
+		const state = readTurnLock(agentplateDir, "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", agentplateDir });
+			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, agentplateDir });
+			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",
+			agentplateDir,
+			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",
+			agentplateDir,
+			ownerPid: 12345,
+			_isProcessAlive: () => false, // prior holder reported dead
+		});
+		try {
+			const state = readTurnLock(agentplateDir, "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",
+			agentplateDir,
+			ownerPid: 77777,
+			_isProcessAlive: () => true,
+		});
+		// Intentionally do NOT release planted — keep the row active.
+
+		_resetInProcessLocks();
+
+		const start = Date.now();
+		await expect(
+			acquireTurnLock({
+				agentName: "blocked",
+				agentplateDir,
+				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",
+			agentplateDir,
+			ownerPid: 4242,
+		});
+		// Simulate an in-process crash that lost the in-process tail.
+		_resetInProcessLocks();
+
+		const second = await acquireTurnLock({
+			agentName: "reentry",
+			agentplateDir,
+			ownerPid: 4242,
+			timeoutMs: 500,
+		});
+		try {
+			const state = readTurnLock(agentplateDir, "reentry");
+			expect(state.heldByPid).toBe(4242);
+		} finally {
+			second.release();
+			first.release();
+		}
+	});
+});

package/src/agents/turn-lock.ts

@@ -0,0 +1,235 @@
+/**
+ * Per-agent serialization lock for the spawn-per-turn engine.
+ *
+ * Ensures that two `runTurn` calls for the same agent never overlap. The lock
+ * is layered:
+ *
+ * 1. **In-process layer** — a module-level `Map<agentName, Promise<void>>`
+ *    chained via `.then`. Concurrent calls inside the same Bun process queue up.
+ *
+ * 2. **Cross-process layer** — a SQLite-backed lease at
+ *    `{agentplateDir}/turn-locks.db`. Each agent has at most one row in
+ *    `turn_locks(agent_name, held_by_pid, acquired_at)`. Acquire wraps the
+ *    state change in `BEGIN IMMEDIATE` so two processes cannot claim the same
+ *    row in the same instant. The transaction itself is short — it does not
+ *    span the whole turn — so other agents' acquires are not blocked.
+ *
+ * Stale leases (where `held_by_pid` is no longer alive) are stolen on the
+ * next acquire attempt. Both layers are released when `release()` is called.
+ */
+
+import { Database } from "bun:sqlite";
+import { join } from "node:path";
+
+/** In-process serialization tail per agent. Holds the latest queued promise. */
+const inProcessTails = new Map<string, Promise<void>>();
+
+export interface TurnLockHandle {
+	readonly agentName: string;
+	/** Release both layers. Idempotent. */
+	release(): void;
+}
+
+export interface AcquireTurnLockOpts {
+	agentName: string;
+	agentplateDir: string;
+	/** Process id recorded as the holder. Defaults to `process.pid`. */
+	ownerPid?: number;
+	/** Maximum time to wait for cross-process acquisition, in ms. Default 60_000. */
+	timeoutMs?: number;
+	/** Polling interval between cross-process retries when contended. Default 50ms. */
+	pollMs?: number;
+	/** Test injection: time source. */
+	_now?: () => number;
+	/** Test injection: liveness check (default uses `process.kill(pid, 0)`). */
+	_isProcessAlive?: (pid: number) => boolean;
+	/** Test injection: explicit DB path (overrides `{agentplateDir}/turn-locks.db`). */
+	_dbPath?: string;
+}
+
+const CREATE_TABLE = `
+CREATE TABLE IF NOT EXISTS turn_locks (
+  agent_name TEXT PRIMARY KEY,
+  held_by_pid INTEGER,
+  acquired_at TEXT
+)`;
+
+/** Default cross-process database path. */
+export function turnLockDbPath(agentplateDir: string): string {
+	return join(agentplateDir, "turn-locks.db");
+}
+
+function defaultIsProcessAlive(pid: number): boolean {
+	if (!Number.isFinite(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		// EPERM means the process exists but we lack permission to signal it.
+		// Treat as alive so we don't steal an active lock.
+		const code = (err as NodeJS.ErrnoException).code;
+		return code === "EPERM";
+	}
+}
+
+function openDb(path: string): Database {
+	const db = new Database(path);
+	db.exec("PRAGMA journal_mode = WAL");
+	db.exec("PRAGMA synchronous = NORMAL");
+	db.exec("PRAGMA busy_timeout = 5000");
+	db.exec(CREATE_TABLE);
+	return db;
+}
+
+/**
+ * Acquire the per-agent turn lock. Resolves once both layers are held.
+ *
+ * The returned handle MUST be released — failure to do so leaves a stale row
+ * that future acquires will treat as held until the holder's pid expires.
+ */
+export async function acquireTurnLock(opts: AcquireTurnLockOpts): Promise<TurnLockHandle> {
+	const { agentName, agentplateDir } = opts;
+	const ownerPid = opts.ownerPid ?? process.pid;
+	const now = opts._now ?? (() => Date.now());
+	const isProcessAlive = opts._isProcessAlive ?? defaultIsProcessAlive;
+	const dbPath = opts._dbPath ?? turnLockDbPath(agentplateDir);
+	const timeoutMs = opts.timeoutMs ?? 60_000;
+	const pollMs = opts.pollMs ?? 50;
+
+	// === Layer 1: in-process serialization ===
+	const previous = inProcessTails.get(agentName) ?? Promise.resolve();
+	let inProcessRelease!: () => void;
+	const current = new Promise<void>((resolve) => {
+		inProcessRelease = resolve;
+	});
+	inProcessTails.set(
+		agentName,
+		previous.then(() => current),
+	);
+	await previous;
+
+	// === Layer 2: cross-process SQLite lease ===
+	const db = openDb(dbPath);
+	const ensureRowStmt = db.prepare<void, { $n: string }>(
+		"INSERT OR IGNORE INTO turn_locks (agent_name, held_by_pid, acquired_at) VALUES ($n, NULL, NULL)",
+	);
+	const selectStmt = db.prepare<
+		{ held_by_pid: number | null; acquired_at: string | null },
+		{ $n: string }
+	>("SELECT held_by_pid, acquired_at FROM turn_locks WHERE agent_name = $n");
+	const claimStmt = db.prepare<void, { $n: string; $p: number; $a: string }>(
+		"UPDATE turn_locks SET held_by_pid = $p, acquired_at = $a WHERE agent_name = $n",
+	);
+	const releaseStmt = db.prepare<void, { $n: string; $p: number }>(
+		"UPDATE turn_locks SET held_by_pid = NULL, acquired_at = NULL WHERE agent_name = $n AND held_by_pid = $p",
+	);
+
+	const tearDown = (): void => {
+		try {
+			db.close();
+		} catch {
+			// best-effort
+		}
+		inProcessRelease();
+	};
+
+	const deadline = now() + timeoutMs;
+	let acquired = false;
+
+	while (!acquired) {
+		try {
+			db.exec("BEGIN IMMEDIATE");
+		} catch (err) {
+			// busy_timeout exhausted — fall through to retry until our own deadline.
+			if (now() >= deadline) {
+				tearDown();
+				throw err;
+			}
+			await Bun.sleep(pollMs);
+			continue;
+		}
+
+		try {
+			ensureRowStmt.run({ $n: agentName });
+			const row = selectStmt.get({ $n: agentName });
+			const held = row?.held_by_pid ?? null;
+			const stale = held !== null && !isProcessAlive(held);
+			if (held === null || stale || held === ownerPid) {
+				claimStmt.run({
+					$n: agentName,
+					$p: ownerPid,
+					$a: new Date(now()).toISOString(),
+				});
+				db.exec("COMMIT");
+				acquired = true;
+			} else {
+				db.exec("ROLLBACK");
+			}
+		} catch (err) {
+			try {
+				db.exec("ROLLBACK");
+			} catch {
+				// ignore
+			}
+			tearDown();
+			throw err;
+		}
+
+		if (!acquired) {
+			if (now() >= deadline) {
+				tearDown();
+				throw new Error(
+					`turn-lock: timed out after ${timeoutMs}ms acquiring lock for "${agentName}"`,
+				);
+			}
+			await Bun.sleep(pollMs);
+		}
+	}
+
+	let released = false;
+	return {
+		agentName,
+		release(): void {
+			if (released) return;
+			released = true;
+			try {
+				releaseStmt.run({ $n: agentName, $p: ownerPid });
+			} catch {
+				// best-effort: SQL failure must not block in-process release.
+			}
+			try {
+				db.close();
+			} catch {
+				// best-effort
+			}
+			inProcessRelease();
+		},
+	};
+}
+
+/** Inspect the persisted lock state. Used by tests and diagnostics. */
+export function readTurnLock(
+	agentplateDir: string,
+	agentName: string,
+	dbPath?: string,
+): { heldByPid: number | null; acquiredAt: string | null } {
+	const db = openDb(dbPath ?? turnLockDbPath(agentplateDir));
+	try {
+		const stmt = db.prepare<
+			{ held_by_pid: number | null; acquired_at: string | null },
+			{ $n: string }
+		>("SELECT held_by_pid, acquired_at FROM turn_locks WHERE agent_name = $n");
+		const row = stmt.get({ $n: agentName });
+		return {
+			heldByPid: row?.held_by_pid ?? null,
+			acquiredAt: row?.acquired_at ?? null,
+		};
+	} finally {
+		db.close();
+	}
+}
+
+/** Reset the in-process tail map. Used by tests; not exported through index. */
+export function _resetInProcessLocks(): void {
+	inProcessTails.clear();
+}