@os-eco/overstory-cli 0.9.4 → 0.11.0

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/mail-poll-detect.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "bun:test";
+import { detectMailPollPattern } from "./mail-poll-detect.ts";
+
+describe("detectMailPollPattern", () => {
+	describe("matched patterns", () => {
+		test("until ov mail list with sleep body", () => {
+			const result = detectMailPollPattern("until ov mail list; do sleep 1; done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("until ov mail loop");
+		});
+
+		test("while ! ov mail check with sleep body", () => {
+			const result = detectMailPollPattern("while ! ov mail check; do sleep 5; done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("while-not ov mail loop");
+		});
+
+		test("while ! ov mail list --unread with sleep body", () => {
+			const result = detectMailPollPattern("while ! ov mail list --unread; do sleep 2; done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("while-not ov mail loop");
+		});
+
+		test("until ov mail check with extra args and sleep body", () => {
+			const result = detectMailPollPattern("until ov mail check --agent foo; do sleep 1; done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("until ov mail loop");
+		});
+
+		test("until [ ... $(ov mail list ... | wc -l) ... ] piped condition", () => {
+			const result = detectMailPollPattern(
+				`until [ "$(ov mail list --unread | wc -l)" -gt 0 ]; do sleep 1; done`,
+			);
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("ov mail piped condition");
+		});
+
+		test("while [ -z $(ov mail check | jq) ] piped condition", () => {
+			const result = detectMailPollPattern(
+				`while [ -z "$(ov mail check | jq '.id')" ]; do sleep 2; done`,
+			);
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("ov mail piped condition");
+		});
+
+		test("multi-line with leading whitespace and tabs is detected", () => {
+			const cmd = "\t\tuntil ov mail list;\n\t\tdo\n\t\t\tsleep 1;\n\t\tdone";
+			const result = detectMailPollPattern(cmd);
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("until ov mail loop");
+		});
+
+		test("multi-line newline-separated (no semicolons before do/done) is detected", () => {
+			const cmd = "until ov mail list\ndo\n  sleep 1\ndone";
+			const result = detectMailPollPattern(cmd);
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("until ov mail loop");
+		});
+
+		test("while loop with negated ov mail and pipe-through is the piped variant", () => {
+			// `while [ ... ]` (no `!`) with `ov mail` substituted inside the test
+			// expression is the piped form, not while-not.
+			const result = detectMailPollPattern(
+				`while [ "$(ov mail list --unread --json)" = "[]" ]; do sleep 3; done`,
+			);
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("ov mail piped condition");
+		});
+
+		test("until with extra padding around ! does not derail kind detection", () => {
+			// Note: `until !` is unusual but the spec says `!` may have surrounding
+			// spaces; we only assert that `until` direct form still classifies.
+			const result = detectMailPollPattern("until   ov mail check  ;  do  sleep 1 ;  done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("until ov mail loop");
+		});
+
+		test("while !ov (no space after !) still classifies as while-not", () => {
+			const result = detectMailPollPattern("while !ov mail check; do sleep 1; done");
+			expect(result.matched).toBe(true);
+			expect(result.reason).toBe("while-not ov mail loop");
+		});
+	});
+
+	describe("not matched", () => {
+		test("ov mail check (no loop wrapper)", () => {
+			expect(detectMailPollPattern("ov mail check").matched).toBe(false);
+		});
+
+		test("ov mail list --unread --json (no loop wrapper)", () => {
+			expect(detectMailPollPattern("ov mail list --unread --json").matched).toBe(false);
+		});
+
+		test("for loop sending mail (bounded, not a wait-poll)", () => {
+			const cmd =
+				"for i in 1 2 3; do ov mail send --to lead --subject hi --body x --type status; done";
+			expect(detectMailPollPattern(cmd).matched).toBe(false);
+		});
+
+		test("while read line over a file (no ov mail reference)", () => {
+			expect(detectMailPollPattern("while read line; do echo $line; done < file.txt").matched).toBe(
+				false,
+			);
+		});
+
+		test("until-loop with ov mail in condition but no sleep in body (not a poll)", () => {
+			// Without `sleep` the body is a one-shot reaction, not a wait-poll.
+			expect(detectMailPollPattern("until ov mail check; do echo got-mail; done").matched).toBe(
+				false,
+			);
+		});
+
+		test("non-string command (undefined) returns matched=false without throwing", () => {
+			expect(() => detectMailPollPattern(undefined)).not.toThrow();
+			expect(detectMailPollPattern(undefined).matched).toBe(false);
+		});
+
+		test("non-string command (null) returns matched=false", () => {
+			expect(detectMailPollPattern(null).matched).toBe(false);
+		});
+
+		test("non-string command (number) returns matched=false", () => {
+			expect(detectMailPollPattern(42).matched).toBe(false);
+		});
+
+		test("empty string returns matched=false", () => {
+			expect(detectMailPollPattern("").matched).toBe(false);
+		});
+
+		test("for loop with sleep but no ov mail reference is not a poll", () => {
+			expect(detectMailPollPattern("for i in 1 2 3; do sleep 1; echo hi; done").matched).toBe(
+				false,
+			);
+		});
+	});
+
+	describe("regex statefulness", () => {
+		test("repeated calls return consistent results (no lastIndex leakage)", () => {
+			const cmd = "until ov mail list; do sleep 1; done";
+			for (let i = 0; i < 5; i++) {
+				const result = detectMailPollPattern(cmd);
+				expect(result.matched).toBe(true);
+				expect(result.reason).toBe("until ov mail loop");
+			}
+		});
+
+		test("matched call followed by non-match returns non-match correctly", () => {
+			expect(detectMailPollPattern("until ov mail list; do sleep 1; done").matched).toBe(true);
+			expect(detectMailPollPattern("ov mail check").matched).toBe(false);
+			expect(detectMailPollPattern("until ov mail list; do sleep 1; done").matched).toBe(true);
+		});
+	});
+});

package/src/agents/mail-poll-detect.ts

@@ -0,0 +1,73 @@
+/**
+ * Defense-in-depth detector for Bash mail-poll patterns (overstory-c92c).
+ *
+ * The lead.md prompt forbids Bash polling for mail (overstory-fa84) — the
+ * primary mitigation. This helper is the runtime backstop: if a future custom
+ * overlay or contributed agent definition silently reintroduces the pattern,
+ * the turn-runner emits a warning and a custom event so it surfaces in
+ * `ov logs` / `ov feed` / the UI. Warn-only by design; the seed's P3 severity
+ * is met without aborting the turn.
+ *
+ * What counts as a wait-poll:
+ *   1. A `until` or `while` loop construct.
+ *   2. The loop condition references `ov mail check` or `ov mail list`
+ *      (directly, negated with `!`, or wrapped in `[ "$(...)" ... ]`).
+ *   3. The loop body contains `sleep` (otherwise it's bounded work, not a
+ *      poll).
+ *
+ * `for` loops are bounded and never classified as wait-polls — `for i in 1 2 3;
+ * do ov mail send ...; done` is a legitimate batched send, not a poll.
+ */
+
+const LOOP_PATTERN =
+	/\b(until|while)\b([\s\S]*?)\s*(?:;|\n)\s*do\b([\s\S]*?)\s*(?:;|\n)\s*\bdone\b/g;
+const SLEEP_IN_BODY = /\bsleep\b/;
+const OV_MAIL_REF = /\bov\s+mail\s+(?:check|list)\b/;
+const DIRECT_OV_MAIL = /^ov\s+mail\s+(?:check|list)\b/;
+const NEGATED_OV_MAIL = /^!\s*ov\s+mail\s+(?:check|list)\b/;
+
+export interface MailPollDetectionResult {
+	matched: boolean;
+	reason?: string;
+}
+
+/**
+ * Pure detector — no I/O, no side effects. Accepts any input and returns
+ * `{ matched: false }` for non-string values so callers can pass the raw
+ * `event.input.command` field without pre-validation.
+ */
+export function detectMailPollPattern(command: unknown): MailPollDetectionResult {
+	if (typeof command !== "string") return { matched: false };
+
+	// Reset lastIndex because the regex is module-level with the `g` flag.
+	LOOP_PATTERN.lastIndex = 0;
+	let match: RegExpExecArray | null = LOOP_PATTERN.exec(command);
+	while (match !== null) {
+		const kind = match[1] as "until" | "while";
+		const condition = (match[2] ?? "").trim();
+		const body = match[3] ?? "";
+
+		if (!SLEEP_IN_BODY.test(body)) {
+			match = LOOP_PATTERN.exec(command);
+			continue;
+		}
+		if (!OV_MAIL_REF.test(condition)) {
+			match = LOOP_PATTERN.exec(command);
+			continue;
+		}
+
+		if (kind === "until") {
+			if (DIRECT_OV_MAIL.test(condition)) {
+				return { matched: true, reason: "until ov mail loop" };
+			}
+			return { matched: true, reason: "ov mail piped condition" };
+		}
+
+		if (NEGATED_OV_MAIL.test(condition)) {
+			return { matched: true, reason: "while-not ov mail loop" };
+		}
+		return { matched: true, reason: "ov mail piped condition" };
+	}
+
+	return { matched: false };
+}

package/src/agents/overlay.test.ts

@@ -10,6 +10,7 @@ import {
 	formatQualityGatesCapabilities,
 	formatQualityGatesInline,
 	formatQualityGatesSteps,
+	formatSiblings,
 	generateOverlay,
 	isCanonicalRoot,
 	writeOverlay,
@@ -523,7 +524,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 +533,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 +547,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 () => {
@@ -1000,3 +1001,58 @@ describe("quality gate placeholders in base definitions", () => {
 		expect(output).not.toContain("{{QUALITY_GATE");
 	});
 });
+
+describe("formatSiblings (overstory-f76a)", () => {
+	test("empty siblings array → empty string", () => {
+		const config = makeConfig({ siblings: [] });
+		expect(formatSiblings(config)).toBe("");
+	});
+
+	test("missing siblings field → empty string", () => {
+		const config = makeConfig();
+		expect(formatSiblings(config)).toBe("");
+	});
+
+	test("one sibling → markdown with the name and rebase guidance", () => {
+		const config = makeConfig({ siblings: ["sibling-a"] });
+		const out = formatSiblings(config);
+		expect(out).toContain("## Parallel Siblings");
+		expect(out).toContain("- sibling-a");
+		expect(out).toContain("git fetch origin main:main");
+		expect(out).toContain("git rebase main");
+		expect(out).toContain("merge_ready");
+	});
+
+	test("multiple siblings render every name as a bullet", () => {
+		const config = makeConfig({ siblings: ["sibling-a", "sibling-b", "sibling-c"] });
+		const out = formatSiblings(config);
+		expect(out).toContain("- sibling-a");
+		expect(out).toContain("- sibling-b");
+		expect(out).toContain("- sibling-c");
+	});
+});
+
+describe("generateOverlay siblings wiring (overstory-f76a)", () => {
+	test("siblings field renders Parallel Siblings section in overlay", async () => {
+		const config = makeConfig({ siblings: ["sibling-a", "sibling-b"] });
+		const output = await generateOverlay(config);
+		expect(output).toContain("## Parallel Siblings");
+		expect(output).toContain("- sibling-a");
+		expect(output).toContain("- sibling-b");
+		expect(output).toContain("git rebase main");
+		expect(output).not.toContain("{{SIBLINGS}}");
+	});
+
+	test("no siblings → overlay omits Parallel Siblings section", async () => {
+		const config = makeConfig();
+		const output = await generateOverlay(config);
+		expect(output).not.toContain("## Parallel Siblings");
+		expect(output).not.toContain("{{SIBLINGS}}");
+	});
+
+	test("empty siblings array → overlay omits Parallel Siblings section", async () => {
+		const config = makeConfig({ siblings: [] });
+		const output = await generateOverlay(config);
+		expect(output).not.toContain("## Parallel Siblings");
+	});
+});

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.
@@ -13,6 +33,38 @@ function getTemplatePath(): string {
 	return join(dirname(import.meta.dir), "..", "templates", "overlay.md.tmpl");
 }
 
+/**
+ * Format the parallel-siblings section (overstory-f76a). Returns empty string
+ * when no siblings are configured. When set, renders a markdown section that
+ * names each sibling and instructs the agent to rebase onto `main` BEFORE
+ * sending `merge_ready`. Reason: parallel leads branch off pre-merge `main`;
+ * whichever merges second carries a stale base and risks reverting sibling
+ * work (mx-c0c122 stale-base-revert).
+ *
+ * Exported for unit-testing.
+ */
+export function formatSiblings(config: OverlayConfig): string {
+	const siblings = config.siblings;
+	if (!siblings || siblings.length === 0) return "";
+
+	const bullets = siblings.map((name) => `- ${name}`).join("\n");
+	return [
+		"## Parallel Siblings",
+		"",
+		"The coordinator has dispatched the following sibling agents in parallel that may share file scope with you:",
+		"",
+		bullets,
+		"",
+		"**CRITICAL**: rebase your branch onto the latest `main` BEFORE sending `merge_ready`, then re-run quality gates AFTER the rebase. Sibling work may have landed on `main` while you were working — sending `merge_ready` from a stale base risks reverting their changes (mx-c0c122 stale-base-revert).",
+		"",
+		"```bash",
+		"git fetch origin main:main",
+		"git rebase main",
+		"# re-run quality gates here, then signal merge_ready",
+		"```",
+	].join("\n");
+}
+
 /**
  * Format the file scope list as a markdown bullet list.
  * Returns a human-readable fallback if no files are scoped.
@@ -105,14 +157,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 +254,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 +298,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 +318,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");
 }
@@ -339,6 +393,7 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 		"{{SPEC_INSTRUCTION}}": specInstruction,
 		"{{SKIP_SCOUT}}": config.skipScout ? SKIP_SCOUT_SECTION : "",
 		"{{DISPATCH_OVERRIDES}}": formatDispatchOverrides(config),
+		"{{SIBLINGS}}": formatSiblings(config),
 		"{{BASE_DEFINITION}}": config.baseDefinition,
 		"{{PROFILE_INSTRUCTIONS}}": formatProfile(config.profileContent),
 		"{{QUALITY_GATE_INLINE}}": formatQualityGatesInline(config.qualityGates),