@os-eco/overstory-cli 0.8.5 → 0.8.7

package/README.md

@@ -19,6 +19,7 @@ Requires [Bun](https://bun.sh) v1.0+, git, and tmux. At least one supported agen
 - [GitHub Copilot](https://github.com/features/copilot) (`copilot` CLI)
 - [Codex](https://github.com/openai/codex) (`codex` CLI)
 - [Gemini CLI](https://github.com/google-gemini/gemini-cli) (`gemini` CLI)
+- [Cursor CLI](https://cursor.com/docs/cli/overview) (`agent` CLI)
 - [Sapling](https://github.com/jayminwest/sapling) (`sp` CLI)
 - [OpenCode](https://opencode.ai) (`opencode` CLI)
 
@@ -99,6 +100,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 |
@@ -176,14 +178,16 @@ Overstory uses instruction overlays and tool-call guards to turn agent sessions
 
 Overstory is runtime-agnostic. The `AgentRuntime` interface (`src/runtimes/types.ts`) defines the contract — each adapter handles spawning, config deployment, guard enforcement, readiness detection, and transcript parsing for its runtime. Set the default in `config.yaml` or override per-agent with `ov sling --runtime <name>`.
 
-| Runtime | CLI | Guard Mechanism | Status |
-|---------|-----|-----------------|--------|
+| Runtime | CLI | Guard Mechanism | Stability |
+|---------|-----|-----------------|-----------|
 | Claude Code | `claude` | `settings.local.json` hooks | Stable |
-| Pi | `pi` | `.pi/extensions/` guard extension | Active development |
-| Copilot | `copilot` | (none — `--allow-all-tools`) | Active development |
-| Codex | `codex` | OS-level sandbox (Seatbelt/Landlock) | Active development |
-| Gemini | `gemini` | `--sandbox` flag | Active development |
-| Sapling | `sp` | `.sapling/guards.json` | Active development |
+| Sapling | `sp` | `.sapling/guards.json` | Stable |
+| Pi | `pi` | `.pi/extensions/` guard extension | Experimental |
+| Copilot | `copilot` | (none — `--allow-all-tools`) | Experimental |
+| Cursor | `agent` | (none — `--yolo`) | Experimental |
+| Codex | `codex` | OS-level sandbox (Seatbelt/Landlock) | Experimental |
+| Gemini | `gemini` | `--sandbox` flag | Experimental |
+| OpenCode | `opencode` | (none) | Experimental |
 
 ## How It Works
 
@@ -232,7 +236,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]
@@ -283,7 +287,7 @@ overstory/
     metrics/                      SQLite metrics + pricing + transcript parsing
     doctor/                       Health check modules (11 checks)
     insights/                     Session insight analyzer for auto-expertise
-    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini, Sapling, OpenCode)
+    runtimes/                     AgentRuntime abstraction (registry + adapters: Claude, Pi, Copilot, Codex, Gemini, Sapling, OpenCode, Cursor)
     tracker/                      Pluggable task tracker (beads + seeds backends)
     mulch/                        mulch client (programmatic API + CLI wrapper)
     e2e/                          End-to-end lifecycle tests

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.7",
 	"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/agents/hooks-deployer.test.ts

@@ -8,6 +8,7 @@ import {
 	buildBashFileGuardScript,
 	buildBashPathBoundaryScript,
 	buildPathBoundaryGuardScript,
+	buildTrackerCloseGuardScript,
 	deployHooks,
 	escapeForSingleQuotedShell,
 	extractQualityGatePrefixes,
@@ -15,6 +16,7 @@ import {
 	getCapabilityGuards,
 	getDangerGuards,
 	getPathBoundaryGuards,
+	getTrackerCloseGuards,
 	isOverstoryHookEntry,
 	PATH_PREFIX,
 } from "./hooks-deployer.ts";
@@ -468,9 +470,9 @@ describe("deployHooks", () => {
 		expect(writeBlockGuard).toBeDefined();
 		expect(writeBlockGuard.hooks[0].command).toContain('"decision":"block"');
 
-		// Should have multiple Bash guards: danger guard + file guard + universal push guard
+		// Should have multiple Bash guards: danger guard + file guard + tracker close guard + universal push guard
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3); // danger guard + file guard + universal push guard
+		expect(bashGuards.length).toBe(4); // danger guard + file guard + tracker close guard + universal push guard
 	});
 
 	test("reviewer capability adds same guards as scout", async () => {
@@ -512,9 +514,9 @@ describe("deployHooks", () => {
 		expect(guardMatchers).toContain("NotebookEdit");
 		expect(guardMatchers).toContain("Bash");
 
-		// Should have 3 Bash guards: danger guard + file guard + universal push guard
+		// Should have 4 Bash guards: danger guard + file guard + tracker close guard + universal push guard
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 	});
 
 	test("builder capability gets path boundary + Bash danger + Bash path boundary guards + native team tool blocks", async () => {
@@ -544,9 +546,9 @@ describe("deployHooks", () => {
 		expect(writeGuards[0].hooks[0].command).toContain("OVERSTORY_WORKTREE_PATH");
 		expect(writeGuards[0].hooks[0].command).not.toContain("cannot modify files");
 
-		// Builder should have 3 Bash guards: danger guard + path boundary guard + universal push guard
+		// Builder should have 4 Bash guards: danger guard + path boundary guard + tracker close guard + universal push guard
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 		// One should be the danger guard (checks git push)
 		const dangerGuard = bashGuards.find(
 			(h: { hooks: Array<{ command: string }> }) =>
@@ -1607,7 +1609,7 @@ describe("structural enforcement integration", () => {
 
 		// Find the bash file guard (the second Bash entry, after the danger guard)
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 
 		// The file guard (second Bash guard) should whitelist git add/commit
 		const fileGuard = bashGuards[1];
@@ -2070,8 +2072,8 @@ describe("bash path boundary integration", () => {
 		const preToolUse = parsed.hooks.PreToolUse;
 
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		// Should have 3 Bash guards: danger guard + path boundary guard + universal push guard
-		expect(bashGuards.length).toBe(3);
+		// Should have 4 Bash guards: danger guard + path boundary guard + tracker close guard + universal push guard
+		expect(bashGuards.length).toBe(4);
 
 		// Find the path boundary guard
 		const pathGuard = bashGuards.find((h: { hooks: Array<{ command: string }> }) =>
@@ -2092,7 +2094,7 @@ describe("bash path boundary integration", () => {
 		const preToolUse = parsed.hooks.PreToolUse;
 
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 
 		const pathGuard = bashGuards.find((h: { hooks: Array<{ command: string }> }) =>
 			h.hooks[0]?.command?.includes("Bash path boundary violation"),
@@ -2110,9 +2112,9 @@ describe("bash path boundary integration", () => {
 		const parsed = JSON.parse(content);
 		const preToolUse = parsed.hooks.PreToolUse;
 
-		// Scout gets danger guard + file guard + universal push guard (3 Bash guards), but NOT path boundary
+		// Scout gets danger guard + file guard + tracker close guard + universal push guard (4 Bash guards), but NOT path boundary
 		const bashGuards = preToolUse.filter((h: { matcher: string }) => h.matcher === "Bash");
-		expect(bashGuards.length).toBe(3);
+		expect(bashGuards.length).toBe(4);
 
 		const pathGuard = bashGuards.find((h: { hooks: Array<{ command: string }> }) =>
 			h.hooks[0]?.command?.includes("Bash path boundary violation"),
@@ -2401,6 +2403,177 @@ describe("PATH prefix in deployed hooks", () => {
 	});
 });
 
+describe("buildTrackerCloseGuardScript", () => {
+	test("returns a string containing key patterns", () => {
+		const script = buildTrackerCloseGuardScript();
+		expect(typeof script).toBe("string");
+		expect(script.length).toBeGreaterThan(0);
+		expect(script).toContain("sd");
+		expect(script).toContain("bd");
+		expect(script).toContain("close");
+		expect(script).toContain("update");
+	});
+
+	test("contains ENV_GUARD prefix", () => {
+		const script = buildTrackerCloseGuardScript();
+		expect(script).toContain('[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0;');
+	});
+
+	test("contains OVERSTORY_TASK_ID early-exit check", () => {
+		const script = buildTrackerCloseGuardScript();
+		expect(script).toContain('[ -z "$OVERSTORY_TASK_ID" ] && exit 0;');
+	});
+
+	test("blocks sd close with wrong ID", async () => {
+		const script = buildTrackerCloseGuardScript();
+		const input = JSON.stringify({ command: "sd close other-task" });
+		const proc = Bun.spawn(["sh", "-c", script], {
+			stdin: new TextEncoder().encode(input),
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "test-agent", OVERSTORY_TASK_ID: "my-task" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		const parsed = JSON.parse(output.trim());
+		expect(parsed.decision).toBe("block");
+		expect(parsed.reason).toContain("other-task");
+		expect(parsed.reason).toContain("my-task");
+	});
+
+	test("allows sd close with matching ID", async () => {
+		const script = buildTrackerCloseGuardScript();
+		const input = JSON.stringify({ command: "sd close my-task" });
+		const proc = Bun.spawn(["sh", "-c", script], {
+			stdin: new TextEncoder().encode(input),
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "test-agent", OVERSTORY_TASK_ID: "my-task" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		expect(output.trim()).toBe("");
+	});
+
+	test("blocks bd close with wrong ID", async () => {
+		const script = buildTrackerCloseGuardScript();
+		const input = JSON.stringify({ command: "bd close other-task" });
+		const proc = Bun.spawn(["sh", "-c", script], {
+			stdin: new TextEncoder().encode(input),
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "test-agent", OVERSTORY_TASK_ID: "my-task" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		const parsed = JSON.parse(output.trim());
+		expect(parsed.decision).toBe("block");
+		expect(parsed.reason).toContain("other-task");
+	});
+
+	test("blocks sd update --status with wrong ID", async () => {
+		const script = buildTrackerCloseGuardScript();
+		const input = JSON.stringify({ command: "sd update other-task --status in_progress" });
+		const proc = Bun.spawn(["sh", "-c", script], {
+			stdin: new TextEncoder().encode(input),
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "test-agent", OVERSTORY_TASK_ID: "my-task" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		const parsed = JSON.parse(output.trim());
+		expect(parsed.decision).toBe("block");
+		expect(parsed.reason).toContain("other-task");
+	});
+
+	test("exits early when OVERSTORY_TASK_ID is empty (coordinator/monitor)", async () => {
+		const script = buildTrackerCloseGuardScript();
+		const input = JSON.stringify({ command: "sd close coordinator-task" });
+		const proc = Bun.spawn(["sh", "-c", script], {
+			stdin: new TextEncoder().encode(input),
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "coordinator", OVERSTORY_TASK_ID: "" },
+		});
+		const output = await new Response(proc.stdout).text();
+		await proc.exited;
+		expect(output.trim()).toBe("");
+	});
+});
+
+describe("getTrackerCloseGuards", () => {
+	test("returns exactly 1 Bash guard entry", () => {
+		const guards = getTrackerCloseGuards();
+		expect(guards).toHaveLength(1);
+		expect(guards[0]?.matcher).toBe("Bash");
+	});
+
+	test("guard hook type is command", () => {
+		const guards = getTrackerCloseGuards();
+		expect(guards[0]?.hooks[0]?.type).toBe("command");
+	});
+
+	test("guard command contains OVERSTORY_TASK_ID check", () => {
+		const guards = getTrackerCloseGuards();
+		const command = guards[0]?.hooks[0]?.command ?? "";
+		expect(command).toContain("OVERSTORY_TASK_ID");
+	});
+
+	test("guard command includes ENV_GUARD prefix", () => {
+		const guards = getTrackerCloseGuards();
+		const command = guards[0]?.hooks[0]?.command ?? "";
+		expect(command).toContain('[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0;');
+	});
+});
+
+describe("deployHooks tracker close guard integration", () => {
+	let tempDir: string;
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "overstory-tracker-close-test-"));
+	});
+
+	afterEach(async () => {
+		await cleanupTempDir(tempDir);
+	});
+
+	test("deployHooks includes tracker close guard in PreToolUse for builder", async () => {
+		const worktreePath = join(tempDir, "builder-tc-wt");
+		await deployHooks(worktreePath, "builder-tc", "builder");
+
+		const content = await Bun.file(join(worktreePath, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content);
+		const preToolUse = parsed.hooks.PreToolUse;
+
+		const trackerGuard = preToolUse.find(
+			(h: { matcher: string; hooks: Array<{ command: string }> }) =>
+				h.matcher === "Bash" && h.hooks[0]?.command?.includes("OVERSTORY_TASK_ID"),
+		);
+		expect(trackerGuard).toBeDefined();
+		expect(trackerGuard.hooks[0].command).toContain("OVERSTORY_TASK_ID");
+	});
+
+	test("deployHooks includes tracker close guard in PreToolUse for all capabilities", async () => {
+		const capabilities = ["builder", "scout", "reviewer", "lead", "merger", "coordinator"];
+
+		for (const cap of capabilities) {
+			const wt = join(tempDir, `${cap}-tc-wt`);
+			await deployHooks(wt, `${cap}-tc`, cap);
+
+			const content = await Bun.file(join(wt, ".claude", "settings.local.json")).text();
+			const parsed = JSON.parse(content);
+			const preToolUse = parsed.hooks.PreToolUse;
+
+			const trackerGuard = preToolUse.find(
+				(h: { matcher: string; hooks: Array<{ command: string }> }) =>
+					h.matcher === "Bash" && h.hooks[0]?.command?.includes("OVERSTORY_TASK_ID"),
+			);
+			expect(trackerGuard).toBeDefined();
+		}
+	});
+});
+
 describe("escapeForSingleQuotedShell", () => {
 	test("no single quotes: string passes through unchanged", () => {
 		expect(escapeForSingleQuotedShell("hello world")).toBe("hello world");

package/src/agents/hooks-deployer.ts

@@ -283,6 +283,61 @@ export function buildBashFileGuardScript(
 	return script;
 }
 
+/**
+ * Build a PreToolUse guard script that prevents agents from closing or updating
+ * issues they don't own.
+ *
+ * Guards against two patterns:
+ * - `sd/bd close <id>` — blocks if <id> != $OVERSTORY_TASK_ID
+ * - `sd/bd update <id> --status` — blocks if <id> != $OVERSTORY_TASK_ID
+ *
+ * Agents without OVERSTORY_TASK_ID (coordinator, monitor) exit early and are unaffected.
+ */
+export function buildTrackerCloseGuardScript(): string {
+	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/\');',
+		// Check for sd/bd close <id>
+		"if echo \"$CMD\" | grep -qE '^\\s*(sd|bd)\\s+close\\s'; then",
+		"  ISSUE_ID=$(echo \"$CMD\" | sed -E 's/^[[:space:]]*(sd|bd)[[:space:]]+close[[:space:]]+([^ ]+).*/\\2/');",
+		'  if [ "$ISSUE_ID" != "$OVERSTORY_TASK_ID" ]; then',
+		'    echo "{\\"decision\\":\\"block\\",\\"reason\\":\\"Cannot close issue $ISSUE_ID — agents may only close their own task ($OVERSTORY_TASK_ID). Report completion via worker_done mail to your parent instead.\\"}";',
+		"    exit 0;",
+		"  fi;",
+		"fi;",
+		// Check for sd/bd update <id> --status
+		"if echo \"$CMD\" | grep -qE '^\\s*(sd|bd)\\s+update\\s.*--status'; then",
+		"  ISSUE_ID=$(echo \"$CMD\" | sed -E 's/^[[:space:]]*(sd|bd)[[:space:]]+update[[:space:]]+([^ ]+).*/\\2/');",
+		'  if [ "$ISSUE_ID" != "$OVERSTORY_TASK_ID" ]; then',
+		'    echo "{\\"decision\\":\\"block\\",\\"reason\\":\\"Cannot update issue $ISSUE_ID — agents may only update their own task ($OVERSTORY_TASK_ID).\\"}";',
+		"    exit 0;",
+		"  fi;",
+		"fi;",
+	].join(" ");
+	return script;
+}
+
+/**
+ * Generate a PreToolUse guard that blocks tracker close/update for foreign issues.
+ *
+ * Returns a single Bash matcher entry. Applied to ALL agent capabilities
+ * so that no agent can accidentally close the coordinator's dispatch issue.
+ * Agents without OVERSTORY_TASK_ID (coordinator, monitor) are unaffected.
+ */
+export function getTrackerCloseGuards(): HookEntry[] {
+	return [
+		{
+			matcher: "Bash",
+			hooks: [{ type: "command", command: buildTrackerCloseGuardScript() }],
+		},
+	];
+}
+
 /**
  * Capabilities that are allowed to modify files via Bash commands.
  * These get the Bash path boundary guard instead of a blanket file-modification block.
@@ -539,7 +594,8 @@ export async function deployHooks(
 	const pathGuards = getPathBoundaryGuards();
 	const dangerGuards = getDangerGuards(agentName);
 	const capabilityGuards = getCapabilityGuards(capability, qualityGates);
-	const allGuards = [...pathGuards, ...dangerGuards, ...capabilityGuards];
+	const trackerCloseGuards = getTrackerCloseGuards();
+	const allGuards = [...pathGuards, ...dangerGuards, ...capabilityGuards, ...trackerCloseGuards];
 
 	if (allGuards.length > 0) {
 		const preToolUse = config.hooks.PreToolUse ?? [];

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