@os-eco/overstory-cli 0.10.3 → 0.11.0

package/src/commands/sling.ts

@@ -158,6 +158,27 @@ export interface SlingOptions {
 	profile?: string;
 	headless?: boolean;
 	recover?: boolean;
+	/**
+	 * Comma-separated list of sibling agent names dispatched in parallel that
+	 * may share file scope with this agent (overstory-f76a). Plumbed through
+	 * to `OverlayConfig.siblings` so the overlay renders rebase-before-merge_ready
+	 * guidance.
+	 */
+	siblings?: string;
+}
+
+/**
+ * Parse the `--siblings <names>` argument into a normalized string array.
+ * Trims whitespace, drops empty entries. Empty / undefined input → `[]`.
+ *
+ * Exported for unit-testing.
+ */
+export function parseSiblings(raw: string | undefined): string[] {
+	if (!raw) return [];
+	return raw
+		.split(",")
+		.map((s) => s.trim())
+		.filter((s) => s.length > 0);
 }
 
 const WORKABLE_STATUSES = ["open", "in_progress"] as const;
@@ -173,12 +194,51 @@ export function isTaskWorkable(status: string, recover: boolean): boolean {
 	return (WORKABLE_STATUSES as readonly string[]).includes(status);
 }
 
+/**
+ * Resolve the effective `parentAgent` for a sling invocation, preserving the
+ * prior session's link on a re-spawn (`--recover`) when `--parent` was not
+ * explicitly passed.
+ *
+ * Pre-fix, sling always read `opts.parent ?? null` and upserted that into the
+ * session row, overwriting the prior `parent_agent` with null whenever a
+ * coordinator/lead invoked `ov sling --recover --name <existing>` without
+ * threading `--parent`. The runner then read `parentAgent === null` and
+ * skipped its in-band `worker_died` notify on a resumed-turn parser stall —
+ * the lead waited forever on a signal that never came (overstory-de3c).
+ *
+ * Resolution rules:
+ *   - **Explicit caller intent wins.** If `opts.parent` is defined (including
+ *     an empty string), use it verbatim. The caller may legitimately want to
+ *     change or clear the parent on re-spawn.
+ *   - **Caller silence preserves linkage.** If `opts.parent` is undefined and
+ *     a prior session row exists with a non-null `parentAgent`, fall back to
+ *     the prior value. Otherwise return null.
+ *
+ * Pure function so the regression test in `sling.test.ts` can assert behavior
+ * without spinning up the full sling command pipeline.
+ */
+export function resolveParentAgent(
+	optsParent: string | undefined,
+	existingSession: { parentAgent: string | null } | null,
+): string | null {
+	if (optsParent !== undefined) {
+		return optsParent;
+	}
+	return existingSession?.parentAgent ?? null;
+}
+
 export interface AutoDispatchOptions {
 	agentName: string;
 	taskId: string;
 	capability: string;
 	specPath: string | null;
 	parentAgent: string | null;
+	/**
+	 * The agent who invoked `ov sling` (from `OVERSTORY_AGENT_NAME` env var);
+	 * takes precedence over `parentAgent` for the mail `from` field, since
+	 * `--parent` describes the new agent's hierarchical parent, not the slinger.
+	 */
+	slingerName: string | null;
 	instructionPath: string;
 }
 
@@ -195,7 +255,7 @@ export function buildAutoDispatch(opts: AutoDispatchOptions): {
 	subject: string;
 	body: string;
 } {
-	const from = opts.parentAgent ?? "orchestrator";
+	const from = opts.slingerName ?? opts.parentAgent ?? "orchestrator";
 	const specLine = opts.specPath
 		? `Spec file: ${opts.specPath}`
 		: "No spec file provided. Check your overlay for task details.";
@@ -537,7 +597,9 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 	let name = nameWasAutoGenerated ? `${capability}-${taskId}` : rawName;
 	const specPath = opts.spec ?? null;
 	const filesRaw = opts.files;
-	const parentAgent = opts.parent ?? null;
+	// Reassigned later when re-spawning an existing agent to preserve the prior
+	// row's parentAgent — see overstory-de3c at the existingSession lookup below.
+	let parentAgent = opts.parent ?? null;
 	const depthStr = opts.depth;
 	const depth = depthStr !== undefined ? Number.parseInt(depthStr, 10) : 0;
 	const forceHierarchy = opts.forceHierarchy ?? false;
@@ -614,6 +676,8 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 				.filter((f) => f.length > 0)
 		: [];
 
+	const siblings = parseSiblings(opts.siblings);
+
 	// 1. Load config
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
@@ -715,18 +779,35 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			);
 		}
 
+		// Track the prior session row when re-spawning against an existing agent
+		// name so downstream code can preserve linkage (parentAgent, claudeSessionId)
+		// that the upsert would otherwise erase. Auto-generated names are unique
+		// so there is never a prior row to preserve.
+		let existingSession: AgentSession | null = null;
 		if (nameWasAutoGenerated) {
 			const takenNames = activeSessions.map((s) => s.agentName);
 			name = generateAgentName(capability, taskId, takenNames);
 		} else {
-			const existing = store.getByName(name);
-			if (existing && existing.state !== "zombie" && existing.state !== "completed") {
-				throw new AgentError(`Agent name "${name}" is already in use (state: ${existing.state})`, {
-					agentName: name,
-				});
+			existingSession = store.getByName(name);
+			if (
+				existingSession &&
+				existingSession.state !== "zombie" &&
+				existingSession.state !== "completed"
+			) {
+				throw new AgentError(
+					`Agent name "${name}" is already in use (state: ${existingSession.state})`,
+					{
+						agentName: name,
+					},
+				);
 			}
 		}
 
+		// Preserve the prior session's parentAgent on re-spawn when --parent was
+		// not explicitly passed (overstory-de3c). See `resolveParentAgent` for the
+		// full rationale and resolution rules.
+		parentAgent = resolveParentAgent(opts.parent, existingSession);
+
 		// 5d. Task-level locking: prevent concurrent agents on the same task ID.
 		// Exception: the parent agent may delegate its own task to a child.
 		const lockHolder = checkTaskLock(activeSessions, taskId);
@@ -897,6 +978,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 				trackerCli: trackerCliName(resolvedBackend),
 				trackerName: resolvedBackend,
 				instructionPath: runtime.instructionPath,
+				siblings,
 			};
 
 			await writeOverlay(worktreePath, overlayConfig, config.project.root, runtime.instructionPath);
@@ -922,12 +1004,14 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 
 			// 9b. Send auto-dispatch mail so it exists when SessionStart hook fires.
 			// This eliminates the race where coordinator sends dispatch AFTER agent boots.
+			const slingerName = process.env.OVERSTORY_AGENT_NAME?.trim() || null;
 			const dispatch = buildAutoDispatch({
 				agentName: name,
 				taskId,
 				capability,
 				specPath: absoluteSpecPath,
 				parentAgent,
+				slingerName,
 				instructionPath: runtime.instructionPath,
 			});
 			const mailStore = createMailStore(join(overstoryDir, "mail.db"));
@@ -996,7 +1080,10 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 				// (or "completed" if terminal mail observed), and exits. No persistent
 				// process remains after this returns; subsequent turns are driven by
 				// `ov serve` (mail) or `ov nudge`.
-				const priorClaudeSessionId = store.getByName(name)?.claudeSessionId ?? null;
+				// `existingSession` was captured during the name-collision check (above).
+				// Re-using it here keeps re-spawn linkage (parentAgent + claudeSessionId)
+				// resolved from the same row.
+				const priorClaudeSessionId = existingSession?.claudeSessionId ?? null;
 
 				// Build the initial prompt (mulch expertise + pending mail + beacon)
 				// as the first user turn.

package/src/commands/stop.test.ts

@@ -634,6 +634,87 @@ describe("stopCommand stop behavior", () => {
 		);
 	});
 
+	test("lead falls back to historical subject when mail store cannot be opened (overstory-7291)", async () => {
+		const session = makeAgentSession({
+			agentName: "lead-zeta",
+			capability: "lead",
+			state: "working",
+			tmuxSession: "overstory-lead-zeta",
+		});
+		saveSessionsToDb([session]);
+
+		// Make mail.db un-openable by creating a directory at that path. SQLite
+		// cannot open a directory as a database, so createMailStore() throws and
+		// buildLeadCompletedSubject hits its outer-catch fallback.
+		const mailDbPath = join(overstoryDir, "mail.db");
+		await mkdir(mailDbPath, { recursive: true });
+
+		const { deps } = makeDeps({ [session.tmuxSession]: true });
+		await stopCommand("lead-zeta", {}, deps);
+
+		const markerPath = join(overstoryDir, "pending-nudges", "coordinator.json");
+		const marker = JSON.parse(await Bun.file(markerPath).text());
+		expect(marker.subject).toBe(
+			"Lead lead-zeta completed — check mail for merge_ready/worker_done",
+		);
+	});
+
+	test("lead with malformed merge_ready payload skips that message (overstory-7291)", async () => {
+		const session = makeAgentSession({
+			agentName: "lead-eta",
+			capability: "lead",
+			state: "working",
+			tmuxSession: "overstory-lead-eta",
+		});
+		saveSessionsToDb([session]);
+
+		// Insert two merge_ready rows directly via the store: one with a valid
+		// MergeReadyPayload, one with a non-JSON payload string. sendProtocol
+		// would JSON.stringify any payload, so it cannot produce a malformed
+		// row — the low-level store accepts the payload column verbatim. The
+		// loop must skip the malformed one (inner catch + continue) and use
+		// the valid one, yielding the single-branch subject variant.
+		const mailStore = createMailStore(join(overstoryDir, "mail.db"));
+		const validPayload: MergeReadyPayload = {
+			branch: "overstory/lead-eta/bead-99",
+			taskId: "bead-99",
+			agentName: "lead-eta",
+			filesModified: ["src/x.ts"],
+		};
+		mailStore.insert({
+			id: "msg-valid",
+			from: "lead-eta",
+			to: "coordinator",
+			subject: "merge_ready: bead-99",
+			body: "ready",
+			type: "merge_ready",
+			priority: "normal",
+			threadId: null,
+			payload: JSON.stringify(validPayload),
+		});
+		mailStore.insert({
+			id: "msg-malformed",
+			from: "lead-eta",
+			to: "coordinator",
+			subject: "merge_ready: broken",
+			body: "ready",
+			type: "merge_ready",
+			priority: "normal",
+			threadId: null,
+			payload: "not-json{",
+		});
+		mailStore.close();
+
+		const { deps } = makeDeps({ [session.tmuxSession]: true });
+		await stopCommand("lead-eta", {}, deps);
+
+		const markerPath = join(overstoryDir, "pending-nudges", "coordinator.json");
+		const marker = JSON.parse(await Bun.file(markerPath).text());
+		expect(marker.subject).toBe(
+			"Lead lead-eta sent merge_ready for branch overstory/lead-eta/bead-99",
+		);
+	});
+
 	test("stopping a non-lead agent does NOT write lead_completed pending-nudge", async () => {
 		const session = makeAgentSession({ state: "working", capability: "builder" });
 		saveSessionsToDb([session]);

package/src/index.ts

@@ -52,7 +52,7 @@ import { ConfigError, OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.10.3";
+export const VERSION = "0.11.0";
 
 const rawArgs = process.argv.slice(2);
 
@@ -287,6 +287,10 @@ program
 	.option("--name <name>", "Unique agent name (auto-generated if omitted)")
 	.option("--spec <path>", "Path to task spec file")
 	.option("--files <list>", "Exclusive file scope (comma-separated)")
+	.option(
+		"--siblings <names>",
+		"Comma-separated names of parallel sibling agents that may share file scope. Renders rebase-before-merge_ready guidance into the overlay.",
+	)
 	.option("--parent <agent>", "Parent agent for hierarchy tracking")
 	.option("--depth <n>", "Current hierarchy depth", "0")
 	.option("--skip-scout", "Skip scout phase for lead agents")

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/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",