@os-eco/overstory-cli 0.8.5 → 0.8.6

package/README.md

@@ -99,6 +99,7 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 | `ov coordinator send` | Fire-and-forget message to coordinator (`--subject`) |
 | `ov coordinator ask` | Synchronous request/response to coordinator (`--subject`, `--timeout`) |
 | `ov coordinator output` | Show recent coordinator output (`--lines`) |
+| `ov coordinator check-complete` | Evaluate exit triggers, return completion status |
 | `ov supervisor start` | **[DEPRECATED]** Start per-project supervisor agent |
 | `ov supervisor stop` | **[DEPRECATED]** Stop supervisor |
 | `ov supervisor status` | **[DEPRECATED]** Show supervisor state |
@@ -232,7 +233,7 @@ overstory/
     config.ts                     Config loader + validation
     errors.ts                     Custom error types
     json.ts                       Standardized JSON envelope helpers
-    commands/                     One file per CLI subcommand (34 commands)
+    commands/                     One file per CLI subcommand (35 commands)
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle
       supervisor.ts               Team lead management [DEPRECATED]

package/agents/coordinator.md

@@ -22,6 +22,7 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **UNNECESSARY_SPAWN** -- Spawning a lead for a trivially small task. If the objective is a single small change, a single lead is sufficient. Only spawn multiple leads for genuinely independent work streams.
 - **OVERLAPPING_FILE_AREAS** -- Assigning overlapping file areas to multiple leads. Check existing agent file scopes via `ov status` before dispatching.
 - **PREMATURE_MERGE** -- Merging a branch before the lead signals `merge_ready`. Always wait for the lead's explicit `merge_ready` mail. Watchdog completion nudges (e.g. "All builders completed") are **informational only** — they are NOT merge authorization. Only a typed `merge_ready` mail from the owning lead authorizes a merge.
+- **PREMATURE_ISSUE_CLOSE** -- Closing a seeds issue before the lead has sent `merge_ready` AND the branch has been successfully merged. Builder completion alone does NOT authorize issue closure. The required sequence is strictly: lead sends `merge_ready` → coordinator merges branch → merge succeeds → then close the issue. Closing based on builder `worker_done` signals, group auto-close, or `ov status` showing agents completed is a bug. Always verify the merge step is complete first.
 - **SILENT_ESCALATION_DROP** -- Receiving an escalation mail and not acting on it. Every escalation must be routed according to its severity.
 - **ORPHANED_AGENTS** -- Dispatching leads and losing track of them. Every dispatched lead must be in a task group.
 - **SCOPE_EXPLOSION** -- Decomposing into too many leads. Target 2-5 leads per batch. Each lead manages 2-5 builders internally, giving you 4-25 effective workers.
@@ -226,6 +227,12 @@ Coordinator (you, depth 0)
     ov merge --branch <lead-branch>             # then merge
     ```
     **Do NOT merge based on watchdog nudges, `ov status` showing "completed" builders, or your own git inspection.** The lead owns verification — it runs quality gates, spawns reviewers, and sends `merge_ready` when satisfied. Wait for that mail.
+
+    After a successful merge, close the corresponding issue:
+    ```bash
+    {{TRACKER_CLI}} close <task-id> --reason "Merged branch <lead-branch>"
+    ```
+    **Do NOT close issues before their branches are merged.** Issue closure is the final step after merge confirmation, never before.
 10. **Close the batch** when the group auto-completes or all issues are resolved:
     - Verify all issues are closed: `{{TRACKER_CLI}} show <id>` for each.
     - Clean up worktrees: `ov worktree clean --completed`.
@@ -281,14 +288,55 @@ Report to the human operator immediately. Critical escalations mean the automate
 
 When a batch is complete (task group auto-closed, all issues resolved):
 
+**CRITICAL: Never close an issue until its branch is merged.** The correct close sequence is:
+1. Receive `merge_ready` from lead.
+2. Run `ov merge --branch <branch> --dry-run` (check first), then `ov merge --branch <branch>`.
+3. Verify merge succeeded (no error output, `merged` mail received or `ov status` confirms).
+4. **Only then** close the issue: `{{TRACKER_CLI}} close <id> --reason "Merged branch <branch-name>"`.
+
 1. Verify all issues are closed: run `{{TRACKER_CLI}} show <id>` for each issue in the group.
-2. Verify all branches are merged: check `ov status` for unmerged branches.
+2. Verify all branches are merged: check `ov status` for unmerged branches. If any branch is unmerged, do NOT proceed — wait for the lead's `merge_ready` signal.
 3. Clean up worktrees: `ov worktree clean --completed`.
 4. Record orchestration insights: `ml record <domain> --type <type> --classification <foundational|tactical|observational> --description "<insight>"`.
-5. Report to the human operator: summarize what was accomplished, what was merged, any issues encountered.
-6. Check for follow-up work: `{{TRACKER_CLI}} ready` to see if new issues surfaced during the batch.
+5. Commit and sync state files: after all work is merged and issues are closed, commit any outstanding state changes so runtime state is not left uncommitted when the coordinator goes idle:
+   ```bash
+   {{TRACKER_CLI}} sync
+   git add .overstory/ .mulch/
+   git diff --cached --quiet || git commit -m "chore: sync runtime state"
+   git push
+   ```
+6. Report to the human operator: summarize what was accomplished, what was merged, any issues encountered.
+7. Check for follow-up work: `{{TRACKER_CLI}} ready` to see if new issues surfaced during the batch.
+
+After processing each batch of mail and dispatching work, evaluate whether your exit conditions are met:
+
+```bash
+ov coordinator check-complete --json
+```
+
+The command evaluates configured `coordinator.exitTriggers` from config.yaml:
+- **allAgentsDone**: all spawned agents in the current run have completed and branches merged
+- **taskTrackerEmpty**: `{{TRACKER_CLI}} ready` returns no unblocked work
+- **onShutdownSignal**: a shutdown message was received via mail
+
+When ALL enabled triggers are met (`complete: true` in the JSON output):
+
+1. Commit and sync state files so runtime state is not left uncommitted:
+   ```bash
+   {{TRACKER_CLI}} sync
+   git add .overstory/ .mulch/
+   git diff --cached --quiet || git commit -m "chore: sync runtime state"
+   git push
+   ```
+2. Run `ov run complete` to mark the current run as finished.
+3. Send a final status mail to the operator:
+   ```bash
+   ov mail send --to operator --subject "Run complete" \
+     --body "All exit triggers met. Run completed." --type status
+   ```
+4. Stop processing. Do not spawn additional agents or process further mail.
 
-The coordinator itself does NOT close or terminate after a batch. It persists across batches, ready for the next objective.
+If no exit triggers are configured (all false), the coordinator runs indefinitely until manually stopped. This is the default behavior for backward compatibility.
 
 ## persistence-and-context-recovery
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.8.5",
+	"version": "0.8.6",
 	"description": "Multi-agent orchestration for AI coding agents — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution. Pluggable runtime adapters for Claude Code, Pi, and more.",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/commands/clean.test.ts

@@ -77,6 +77,12 @@ describe("validation", () => {
 	test("no flags throws ValidationError", async () => {
 		await expect(cleanCommand({})).rejects.toThrow("No cleanup targets specified");
 	});
+
+	test("--agent and --all throws ValidationError", async () => {
+		await expect(cleanCommand({ agent: "my-builder", all: true })).rejects.toThrow(
+			"--agent and --all are mutually exclusive",
+		);
+	});
 });
 
 // === --all ===
@@ -656,3 +662,133 @@ describe("mulch health checks", () => {
 		expect(stdoutOutput).toBeDefined();
 	});
 });
+
+// === --agent ===
+
+describe("--agent", () => {
+	function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
+		return {
+			id: "s1",
+			agentName: "test-builder",
+			capability: "builder",
+			worktreePath: join(tempDir, ".overstory", "worktrees", "test-builder"),
+			branchName: "overstory/test-builder/task-1",
+			taskId: "task-1",
+			tmuxSession: "overstory-test-project-test-builder",
+			state: "working",
+			pid: 99999,
+			parentAgent: null,
+			depth: 1,
+			runId: "run-123",
+			startedAt: new Date().toISOString(),
+			lastActivity: new Date().toISOString(),
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+			...overrides,
+		};
+	}
+
+	function saveSession(session: AgentSession): void {
+		const { store } = openSessionStore(overstoryDir);
+		try {
+			store.upsert(session);
+		} finally {
+			store.close();
+		}
+	}
+
+	test("throws AgentError when agent not found", async () => {
+		await expect(cleanCommand({ agent: "nonexistent" })).rejects.toThrow("not found");
+	});
+
+	test("clears agent and logs directories", async () => {
+		const session = makeSession();
+		saveSession(session);
+
+		// Create agent and logs dirs with content
+		const agentDir = join(overstoryDir, "agents", "test-builder");
+		const logsDir = join(overstoryDir, "logs", "test-builder");
+		await mkdir(agentDir, { recursive: true });
+		await mkdir(logsDir, { recursive: true });
+		await writeFile(join(agentDir, "identity.yaml"), "name: test-builder");
+		await writeFile(join(logsDir, "session.log"), "log data");
+
+		await cleanCommand({ agent: "test-builder" });
+
+		// Dirs should be cleared (but still exist)
+		const agentEntries = await readdir(agentDir);
+		const logEntries = await readdir(logsDir);
+		expect(agentEntries).toHaveLength(0);
+		expect(logEntries).toHaveLength(0);
+
+		expect(stdoutOutput).toContain("Agent cleaned");
+		expect(stdoutOutput).toContain("test-builder");
+	});
+
+	test("marks agent session as completed", async () => {
+		const session = makeSession({ state: "working" });
+		saveSession(session);
+
+		await cleanCommand({ agent: "test-builder" });
+
+		const { store } = openSessionStore(overstoryDir);
+		const updated = store.getByName("test-builder");
+		store.close();
+		expect(updated?.state).toBe("completed");
+	});
+
+	test("logs synthetic session-end event for non-completed agent", async () => {
+		const session = makeSession({ state: "working" });
+		saveSession(session);
+
+		await cleanCommand({ agent: "test-builder" });
+
+		const eventsDbPath = join(overstoryDir, "events.db");
+		const eventStore = createEventStore(eventsDbPath);
+		const events = eventStore.getByAgent("test-builder");
+		eventStore.close();
+
+		const sessionEndEvents = events.filter((e) => e.eventType === "session_end");
+		expect(sessionEndEvents).toHaveLength(1);
+		const data = JSON.parse(sessionEndEvents[0]?.data ?? "{}");
+		expect(data.reason).toContain("clean --agent");
+	});
+
+	test("does not log session-end event for already-completed agent", async () => {
+		const session = makeSession({ state: "completed" });
+		saveSession(session);
+
+		await cleanCommand({ agent: "test-builder" });
+
+		const eventsDbPath = join(overstoryDir, "events.db");
+		if (existsSync(eventsDbPath)) {
+			const eventStore = createEventStore(eventsDbPath);
+			const events = eventStore.getByAgent("test-builder");
+			eventStore.close();
+			const sessionEndEvents = events.filter((e) => e.eventType === "session_end");
+			expect(sessionEndEvents).toHaveLength(0);
+		}
+	});
+
+	test("--agent + --json returns JSON with agent result", async () => {
+		const session = makeSession({ state: "working" });
+		saveSession(session);
+
+		await cleanCommand({ agent: "test-builder", json: true });
+
+		const result = JSON.parse(stdoutOutput);
+		expect(result).toHaveProperty("agent");
+		expect(result.agent).toHaveProperty("agentName", "test-builder");
+		expect(result.agent).toHaveProperty("markedCompleted");
+	});
+
+	test("handles missing agent/logs directories gracefully", async () => {
+		const session = makeSession({ state: "completed" });
+		saveSession(session);
+
+		// No agent or logs dirs — should not error
+		await cleanCommand({ agent: "test-builder" });
+		expect(stdoutOutput).toContain("Agent cleaned");
+	});
+});

package/src/commands/clean.ts

@@ -23,7 +23,7 @@ import { existsSync } from "node:fs";
 import { readdir, rm, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { loadConfig } from "../config.ts";
-import { ValidationError } from "../errors.ts";
+import { AgentError, ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess } from "../logging/color.ts";
@@ -31,9 +31,16 @@ import { createMulchClient } from "../mulch/client.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { AgentSession, MulchDoctorResult, MulchPruneResult, MulchStatus } from "../types.ts";
 import { listWorktrees, removeWorktree } from "../worktree/manager.ts";
-import { killSession, listSessions } from "../worktree/tmux.ts";
+import {
+	isProcessAlive,
+	isSessionAlive,
+	killProcessTree,
+	killSession,
+	listSessions,
+} from "../worktree/tmux.ts";
 
 export interface CleanOptions {
+	agent?: string;
 	all?: boolean;
 	mail?: boolean;
 	sessions?: boolean;
@@ -395,6 +402,158 @@ async function checkMulchHealth(repoRoot: string): Promise<{
 	}
 }
 
+interface AgentCleanResult {
+	agentName: string;
+	tmuxKilled: boolean;
+	pidKilled: boolean;
+	worktreeRemoved: boolean;
+	branchDeleted: boolean;
+	agentDirCleared: boolean;
+	logsDirCleared: boolean;
+	sessionEndEventLogged: boolean;
+	markedCompleted: boolean;
+}
+
+/**
+ * Delete a git branch (best-effort).
+ */
+async function deleteBranch(repoRoot: string, branch: string): Promise<boolean> {
+	try {
+		const proc = Bun.spawn(["git", "branch", "-D", branch], {
+			cwd: repoRoot,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const exitCode = await proc.exited;
+		return exitCode === 0;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Perform targeted cleanup of a single agent.
+ *
+ * Kills its tmux session or process, removes its worktree, deletes its branch,
+ * clears its agent and log directories, logs a synthetic session-end event,
+ * and marks the session as completed.
+ */
+async function cleanSingleAgent(
+	agentName: string,
+	overstoryDir: string,
+	projectRoot: string,
+): Promise<AgentCleanResult> {
+	const result: AgentCleanResult = {
+		agentName,
+		tmuxKilled: false,
+		pidKilled: false,
+		worktreeRemoved: false,
+		branchDeleted: false,
+		agentDirCleared: false,
+		logsDirCleared: false,
+		sessionEndEventLogged: false,
+		markedCompleted: false,
+	};
+
+	const { store } = openSessionStore(overstoryDir);
+	let session: AgentSession | undefined;
+	try {
+		const found = store.getByName(agentName);
+		if (!found) {
+			throw new AgentError(`Agent "${agentName}" not found`, { agentName });
+		}
+		session = found;
+
+		// Log synthetic session-end event for non-completed agents
+		if (session.state !== "completed") {
+			try {
+				const eventsDbPath = join(overstoryDir, "events.db");
+				const eventStore = createEventStore(eventsDbPath);
+				try {
+					eventStore.insert({
+						runId: session.runId,
+						agentName: session.agentName,
+						sessionId: session.id,
+						eventType: "session_end",
+						toolName: null,
+						toolArgs: null,
+						toolDurationMs: null,
+						level: "info",
+						data: JSON.stringify({ reason: "clean --agent", capability: session.capability }),
+					});
+					result.sessionEndEventLogged = true;
+				} finally {
+					eventStore.close();
+				}
+			} catch {
+				// Best effort
+			}
+		}
+
+		const isHeadless = session.tmuxSession === "" && session.pid !== null;
+
+		// Kill tmux session or process
+		if (isHeadless && session.pid !== null) {
+			try {
+				if (isProcessAlive(session.pid)) {
+					await killProcessTree(session.pid);
+					result.pidKilled = true;
+				}
+			} catch {
+				// Best effort
+			}
+		} else if (session.tmuxSession) {
+			try {
+				if (await isSessionAlive(session.tmuxSession)) {
+					await killSession(session.tmuxSession);
+					result.tmuxKilled = true;
+				}
+			} catch {
+				// Best effort
+			}
+		}
+
+		// Remove worktree (force)
+		if (session.worktreePath) {
+			try {
+				await removeWorktree(projectRoot, session.worktreePath, {
+					force: true,
+					forceBranch: false,
+				});
+				result.worktreeRemoved = true;
+			} catch {
+				// Best effort
+			}
+		}
+
+		// Delete branch
+		if (session.branchName) {
+			result.branchDeleted = await deleteBranch(projectRoot, session.branchName);
+		}
+
+		// Mark completed
+		if (session.state !== "completed") {
+			store.updateState(agentName, "completed");
+			store.updateLastActivity(agentName);
+			result.markedCompleted = true;
+		}
+	} finally {
+		store.close();
+	}
+
+	// Clear agent identity directory
+	if (session) {
+		const agentDir = join(overstoryDir, "agents", agentName);
+		result.agentDirCleared = await clearDirectory(agentDir);
+
+		// Clear agent logs directory
+		const logsDir = join(overstoryDir, "logs", agentName);
+		result.logsDirCleared = await clearDirectory(logsDir);
+	}
+
+	return result;
+}
+
 /**
  * Entry point for `ov clean [flags]`.
  *
@@ -403,6 +562,15 @@ async function checkMulchHealth(repoRoot: string): Promise<{
 export async function cleanCommand(opts: CleanOptions): Promise<void> {
 	const json = opts.json ?? false;
 	const all = opts.all ?? false;
+	const agentName = opts.agent;
+
+	// --agent and --all are mutually exclusive
+	if (agentName && all) {
+		throw new ValidationError(
+			"--agent and --all are mutually exclusive. Use --agent <name> for single-agent cleanup or --all for full cleanup.",
+			{ field: "flags" },
+		);
+	}
 
 	const doWorktrees = all || (opts.worktrees ?? false);
 	const doBranches = all || (opts.branches ?? false);
@@ -414,11 +582,19 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 	const doSpecs = all || (opts.specs ?? false);
 
 	const anySelected =
-		doWorktrees || doBranches || doMail || doSessions || doMetrics || doLogs || doAgents || doSpecs;
+		agentName ||
+		doWorktrees ||
+		doBranches ||
+		doMail ||
+		doSessions ||
+		doMetrics ||
+		doLogs ||
+		doAgents ||
+		doSpecs;
 
 	if (!anySelected) {
 		throw new ValidationError(
-			"No cleanup targets specified. Use --all for full cleanup, or individual flags (--mail, --sessions, --metrics, --logs, --worktrees, --branches, --agents, --specs).",
+			"No cleanup targets specified. Use --all for full cleanup, --agent <name> for single-agent cleanup, or individual flags (--mail, --sessions, --metrics, --logs, --worktrees, --branches, --agents, --specs).",
 			{ field: "flags" },
 		);
 	}
@@ -427,6 +603,24 @@ export async function cleanCommand(opts: CleanOptions): Promise<void> {
 	const root = config.project.root;
 	const overstoryDir = join(root, ".overstory");
 
+	// Per-agent cleanup: targeted single-agent cleanup
+	if (agentName) {
+		const agentResult = await cleanSingleAgent(agentName, overstoryDir, root);
+		if (json) {
+			jsonOutput("clean", { agent: agentResult });
+		} else {
+			printSuccess("Agent cleaned", agentName);
+			if (agentResult.tmuxKilled) process.stdout.write(`  Tmux session killed\n`);
+			if (agentResult.pidKilled) process.stdout.write(`  Process killed (PID)\n`);
+			if (agentResult.worktreeRemoved) process.stdout.write(`  Worktree removed\n`);
+			if (agentResult.branchDeleted)
+				process.stdout.write(`  Branch deleted: ${agentResult.agentName}\n`);
+			if (agentResult.agentDirCleared) process.stdout.write(`  Cleared agents/${agentName}/\n`);
+			if (agentResult.logsDirCleared) process.stdout.write(`  Cleared logs/${agentName}/\n`);
+		}
+		return;
+	}
+
 	const result: CleanResult = {
 		sessionEndEventsLogged: 0,
 		tmuxKilled: 0,