@os-eco/overstory-cli 0.9.4 → 0.10.3

package/src/agents/hooks-deployer.ts

@@ -339,6 +339,114 @@ export function getTrackerCloseGuards(): HookEntry[] {
 	];
 }
 
+/**
+ * Build a PreToolUse guard script that enforces the merge_ready gate on lead
+ * agents (overstory-3899, overstory-da9b): a lead may not run
+ * `sd/bd close $OVERSTORY_TASK_ID` unless (a) it has sent at least one
+ * `merge_ready` mail AND has sent at least one `merge_ready` per `worker_done`
+ * it has received, AND (b) the lead's branch (worktree HEAD) is reachable
+ * from the merge target (session-branch.txt > "main") via
+ * `git merge-base --is-ancestor`. (a) proves the lead reported completion;
+ * (b) proves the coordinator actually merged the work.
+ *
+ * Counts are derived by querying `ov mail list --json` and grep-counting
+ * `"id":"` occurrences in the JSON response (no jq dependency). The gate
+ * is a no-op for non-lead agents because it is only deployed to leads via
+ * `getLeadCloseGateGuards()`, but it still self-protects: the script
+ * exits early when OVERSTORY_AGENT_NAME or OVERSTORY_TASK_ID is unset.
+ * The merge-ancestor check fails open when OVERSTORY_WORKTREE_PATH is unset
+ * or the target ref cannot be resolved locally — in those cases we cannot
+ * make a definitive claim, so we don't block.
+ *
+ * Foreign-task closes are caught earlier by `buildTrackerCloseGuardScript`,
+ * so this gate only fires when the issue ID matches OVERSTORY_TASK_ID.
+ */
+export function buildLeadCloseGateScript(): string {
+	const blockNoMergeReady = JSON.stringify({
+		decision: "block",
+		reason:
+			'merge_ready gate: cannot close your task — you have not sent a merge_ready mail to coordinator. Required: ov mail send --to coordinator --subject "merge_ready: <task>" --body "<branch + files>" --type merge_ready --from $OVERSTORY_AGENT_NAME. Then retry the close.',
+	});
+	const blockUnderCount = JSON.stringify({
+		decision: "block",
+		reason:
+			"merge_ready gate: cannot close your task — merge_ready count is less than worker_done received. Send one merge_ready per worker_done before closing.",
+	});
+	const blockNotMerged = JSON.stringify({
+		decision: "block",
+		reason:
+			"merge_ready gate: cannot close your task — your branch is not yet merged into the target (session-branch.txt or main). Wait for the coordinator to merge before closing. The merge step is what makes the work real.",
+	});
+
+	const script = [
+		// Only enforce for overstory agent sessions
+		ENV_GUARD,
+		// Skip if task ID is not set (coordinator/monitor have no task)
+		'[ -z "$OVERSTORY_TASK_ID" ] && exit 0;',
+		"read -r INPUT;",
+		// Extract command value from JSON
+		'CMD=$(echo "$INPUT" | sed \'s/.*"command": *"\\([^"]*\\)".*/\\1/\');',
+		// Only inspect sd/bd close commands
+		"if ! echo \"$CMD\" | grep -qE '^\\s*(sd|bd)\\s+close\\s'; then exit 0; fi;",
+		// Extract the issue ID being closed
+		"ISSUE_ID=$(echo \"$CMD\" | sed -E 's/^[[:space:]]*(sd|bd)[[:space:]]+close[[:space:]]+([^ ]+).*/\\2/');",
+		// Only gate when the lead is closing its own task. Foreign closes are blocked by buildTrackerCloseGuardScript.
+		'[ "$ISSUE_ID" != "$OVERSTORY_TASK_ID" ] && exit 0;',
+		// Count merge_ready mails sent by this agent
+		'MR=$(ov mail list --json --from "$OVERSTORY_AGENT_NAME" --type merge_ready 2>/dev/null | grep -o \'"id":"\' | wc -l | tr -d \' \');',
+		// Count worker_done mails received by this agent
+		'WD=$(ov mail list --json --to "$OVERSTORY_AGENT_NAME" --type worker_done 2>/dev/null | grep -o \'"id":"\' | wc -l | tr -d \' \');',
+		// Default to 0 if the count failed for any reason.
+		// biome-ignore lint/suspicious/noTemplateCurlyInString: shell parameter expansion, not a JS template
+		"MR=${MR:-0}; WD=${WD:-0};",
+		// Block if no merge_ready was ever sent
+		'if [ "$MR" -eq 0 ]; then',
+		`  echo '${escapeForSingleQuotedShell(blockNoMergeReady)}';`,
+		"  exit 0;",
+		"fi;",
+		// Block if not enough merge_ready for the worker_done count
+		'if [ "$MR" -lt "$WD" ]; then',
+		`  echo '${escapeForSingleQuotedShell(blockUnderCount)}';`,
+		"  exit 0;",
+		"fi;",
+		// Verify the lead's branch is actually merged into the target (overstory-da9b).
+		// merge_ready alone doesn't prove the work landed — the coordinator may still be
+		// verifying or the merge may have failed.
+		// Skip if worktree path is missing (test envs etc.) — fail open.
+		'[ -z "$OVERSTORY_WORKTREE_PATH" ] && exit 0;',
+		// Resolve target branch: $OVERSTORY_PROJECT_ROOT/.overstory/session-branch.txt > "main"
+		'TARGET="";',
+		'if [ -n "$OVERSTORY_PROJECT_ROOT" ] && [ -f "$OVERSTORY_PROJECT_ROOT/.overstory/session-branch.txt" ]; then',
+		'  TARGET=$(tr -d "[:space:]" < "$OVERSTORY_PROJECT_ROOT/.overstory/session-branch.txt" 2>/dev/null);',
+		"fi;",
+		'[ -z "$TARGET" ] && TARGET=main;',
+		// If the target ref doesn't exist locally, we can't verify — fail open.
+		'if ! git -C "$OVERSTORY_WORKTREE_PATH" rev-parse --verify "$TARGET" >/dev/null 2>&1; then exit 0; fi;',
+		// Block if HEAD is not yet an ancestor of the target.
+		'if ! git -C "$OVERSTORY_WORKTREE_PATH" merge-base --is-ancestor HEAD "$TARGET" >/dev/null 2>&1; then',
+		`  echo '${escapeForSingleQuotedShell(blockNotMerged)}';`,
+		"  exit 0;",
+		"fi;",
+	].join(" ");
+	return script;
+}
+
+/**
+ * Generate the lead-only PreToolUse guard that gates `sd/bd close <own-task>`
+ * on merge_ready emission. Wraps `buildLeadCloseGateScript` with the standard
+ * PATH_PREFIX so `ov` resolves under Claude Code's minimal hook PATH.
+ *
+ * Only deployed to lead agents (see getCapabilityGuards).
+ */
+export function getLeadCloseGateGuards(): HookEntry[] {
+	return [
+		{
+			matcher: "Bash",
+			hooks: [{ type: "command", command: `${PATH_PREFIX} ${buildLeadCloseGateScript()}` }],
+		},
+	];
+}
+
 /**
  * Capabilities that are allowed to modify files via Bash commands.
  * These get the Bash path boundary guard instead of a blanket file-modification block.
@@ -507,6 +615,13 @@ export function getCapabilityGuards(capability: string, qualityGates?: QualityGa
 		guards.push(...getBashPathBoundaryGuards());
 	}
 
+	// Lead agents get the merge_ready gate on sd/bd close (overstory-3899).
+	// Blocks closing the lead's own task unless at least one merge_ready mail
+	// has been sent and the count covers all worker_done received.
+	if (capability === "lead") {
+		guards.push(...getLeadCloseGateGuards());
+	}
+
 	return guards;
 }
 
@@ -538,9 +653,23 @@ export function isOverstoryHookEntry(entry: HookEntry): boolean {
  * Overstory hooks are placed before user hooks per event type so security
  * guards run first.
  *
+ * In `headlessOnly` mode, only PreToolUse hooks are deployed (overstory-e24b).
+ * Headless Claude Code (`-p --output-format stream-json`) DOES dispatch hooks
+ * from settings.local.json, so PreToolUse security guards (path boundary,
+ * capability blocks, bash danger patterns, tracker close, lead close gate)
+ * are required to keep parity with tmux mode. The other hook types are dropped
+ * because they have headless equivalents already wired up:
+ *  - SessionStart  → buildInitialHeadlessPrompt() in sling.ts
+ *  - UserPromptSubmit → mail injection loop owned by `ov serve`
+ *  - PostToolUse → stream-json parser captures tool_use/tool_result
+ *  - Stop → stream-json parser captures the `result` event
+ *  - PreCompact → deferred (tracked separately)
+ *
  * @param worktreePath - Absolute path to the agent's git worktree (or project root)
  * @param agentName - The unique name of the agent
  * @param capability - Agent capability (builder, scout, reviewer, lead, merger)
+ * @param qualityGates - Quality gates whose commands are whitelisted as safe Bash prefixes
+ * @param headlessOnly - When true, deploy only PreToolUse entries (overstory-e24b)
  * @throws {AgentError} If the template is not found or the write fails
  */
 export async function deployHooks(
@@ -548,6 +677,7 @@ export async function deployHooks(
 	agentName: string,
 	capability = "builder",
 	qualityGates?: QualityGate[],
+	headlessOnly = false,
 ): Promise<void> {
 	const templatePath = getTemplatePath();
 	const file = Bun.file(templatePath);
@@ -578,6 +708,17 @@ export async function deployHooks(
 	// Parse the base config from the template
 	const config = JSON.parse(content) as { hooks: Record<string, HookEntry[]> };
 
+	// Headless mode: drop all template-derived hook entries.
+	// Under spawn-per-turn (Phase 3, overstory-2cf9), the turn-runner provides
+	// the user prompt and emits its own observability events for every turn;
+	// the template's SessionStart/UserPromptSubmit/PostToolUse/Stop/PreCompact
+	// hooks would either double-deliver mail (UserPromptSubmit re-injects on top
+	// of the runner's prompt) or duplicate session_end / per-tool events.
+	// Only the dynamic PreToolUse security guards added below are retained.
+	if (headlessOnly) {
+		config.hooks = {};
+	}
+
 	// Extend PATH in all template hook commands.
 	// Claude Code invokes hooks with PATH=/usr/bin:/bin:/usr/sbin:/sbin — ~/.bun/bin
 	// (where ov, ml, sd, etc. live) is not included. Prepend PATH_PREFIX so CLIs resolve.

package/src/agents/overlay.test.ts

@@ -523,7 +523,7 @@ describe("generateOverlay", () => {
 		expect(output).toContain("3");
 	});
 
-	test("dispatch overrides: maxAgentsOverride of 1 enables combined lead/worker guidance", async () => {
+	test("dispatch overrides: maxAgentsOverride of 1 directs the lead to spend the slot on a single builder", async () => {
 		const config = makeConfig({
 			capability: "lead",
 			maxAgentsOverride: 1,
@@ -532,8 +532,8 @@ describe("generateOverlay", () => {
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("MAX AGENTS");
-		expect(output).toContain("combined **lead/worker**");
-		expect(output).toContain("only slot");
+		expect(output).toContain("single builder");
+		expect(output).toContain("Leads cannot implement directly");
 	});
 
 	test("dispatch overrides: maxAgentsOverride of 2 enables compressed-mode guidance", async () => {
@@ -546,7 +546,7 @@ describe("generateOverlay", () => {
 
 		expect(output).toContain("MAX AGENTS");
 		expect(output).toContain("compressed mode");
-		expect(output).toContain("self-verification");
+		expect(output).toContain("Leads do not implement");
 	});
 
 	test("dispatch overrides: both skipReview and maxAgentsOverride together", async () => {

package/src/agents/overlay.ts

@@ -3,6 +3,26 @@ import { dirname, join, resolve } from "node:path";
 import { DEFAULT_QUALITY_GATES } from "../config.ts";
 import { AgentError } from "../errors.ts";
 import type { OverlayConfig, QualityGate } from "../types.ts";
+import { terminalMailTypesFor } from "./capabilities.ts";
+
+/**
+ * Capability-specific completion-mail guidance for the dynamic overlay.
+ *
+ * Returns the terminal mail-type name and a one-line example fragment so the
+ * overlay can render: "ov mail send ... --type <terminalType> ...".
+ *
+ * Crucial: this MUST stay in sync with `terminalMailTypesFor()` — overstory-1a4c
+ * found that overlay text saying `--type result` while the runner watched only
+ * for `worker_done` left worker sessions stuck in `working`.
+ */
+function completionMailTypeFor(capability: string): string {
+	const types = terminalMailTypesFor(capability);
+	// `terminalMailTypesFor` returns the canonical type first
+	// (worker_done for workers, merged for mergers). Use that for prose;
+	// agents may also use the secondary types (`merge_failed`, etc.) where
+	// applicable per their base prompt.
+	return types[0] ?? "worker_done";
+}
 
 /**
  * Resolve the path to the overlay template file.
@@ -105,14 +125,14 @@ function formatDispatchOverrides(config: OverlayConfig): string {
 		if (config.maxAgentsOverride === 1) {
 			sections.push(
 				"- **MAX AGENTS**: Your per-lead agent ceiling has been set to **1**. " +
-					"Operate as a combined **lead/worker**: implement the task yourself unless a single specialist is absolutely necessary. " +
-					"Do not spend your only slot on a scout or reviewer unless that specialist work is the real bottleneck.",
+					"Spend that slot on a single builder for the whole task — skip scouts and reviewers and self-verify the builder's diff yourself. " +
+					"Leads cannot implement directly (Write/Edit/`git add`/`git commit` are blocked by the harness), so the one slot must be a builder.",
 			);
 		} else if (config.maxAgentsOverride === 2) {
 			sections.push(
 				"- **MAX AGENTS**: Your per-lead agent ceiling has been set to **2**. " +
-					"Operate in compressed mode: use at most one helper at a time when possible, then complete the remaining implementation and verification yourself. " +
-					"Prefer self-verification over spawning a separate reviewer.",
+					"Operate in compressed mode: spend the slots on builders (one or two), skip scouts and reviewers, and self-verify each diff yourself. " +
+					"Leads do not implement; every change requires a builder spawn.",
 			);
 		} else {
 			sections.push(
@@ -202,14 +222,15 @@ export function formatQualityGatesCapabilities(gates: QualityGate[] | undefined)
 
 function formatQualityGates(config: OverlayConfig): string {
 	if (READ_ONLY_CAPABILITIES.has(config.capability)) {
+		const completionType = completionMailTypeFor(config.capability);
 		return [
 			"## Completion",
 			"",
 			"Before reporting completion:",
 			"",
 			`1. **Record mulch learnings:** \`ml record <domain> --type <convention|pattern|reference> --description "..."\` — capture reusable knowledge from your work`,
-			`2. **Close issue:** \`${config.trackerCli ?? "sd"} close ${config.taskId} --reason "summary of findings"\``,
-			`3. **Send results:** \`ov mail send --to ${config.parentAgent ?? "coordinator"} --subject "done" --body "Summary" --type result --agent ${config.agentName}\``,
+			`2. **Signal completion:** send \`${completionType}\` mail to ${config.parentAgent ?? "coordinator"}: \`ov mail send --to ${config.parentAgent ?? "coordinator"} --subject "Worker done: ${config.taskId}" --body "Summary of findings" --type ${completionType} --agent ${config.agentName}\``,
+			`3. **Close issue:** \`${config.trackerCli ?? "sd"} close ${config.taskId} --reason "summary of findings"\``,
 			"",
 			"You are a read-only agent. Do NOT commit, modify files, or run quality gates.",
 		].join("\n");
@@ -245,13 +266,14 @@ function formatQualityGates(config: OverlayConfig): string {
  * Writable agents get file-scope and branch constraints.
  */
 function formatConstraints(config: OverlayConfig): string {
+	const completionType = completionMailTypeFor(config.capability);
 	if (READ_ONLY_CAPABILITIES.has(config.capability)) {
 		return [
 			"## Constraints",
 			"",
 			"- You are **read-only**: do NOT modify, create, or delete any files",
 			"- Do NOT commit, push, or make any git state changes",
-			`- Report completion via \`${config.trackerCli ?? "sd"} close\` AND \`ov mail send --type result\``,
+			`- Report completion via \`${config.trackerCli ?? "sd"} close\` AND \`ov mail send --type ${completionType}\``,
 			"- If you encounter a blocking issue, send mail with `--priority urgent --type error`",
 		].join("\n");
 	}
@@ -264,7 +286,7 @@ function formatConstraints(config: OverlayConfig): string {
 		"- Only modify files in your File Scope",
 		`- Commit only to your branch: ${config.branchName}`,
 		"- Never push to the canonical branch",
-		`- Report completion via \`${config.trackerCli ?? "sd"} close\` AND \`ov mail send --type result\``,
+		`- Report completion via \`${config.trackerCli ?? "sd"} close\` AND \`ov mail send --type ${completionType}\``,
 		"- If you encounter a blocking issue, send mail with `--priority urgent --type error`",
 	].join("\n");
 }

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();
+		}
+	});
+});