@os-eco/overstory-cli 0.8.6 → 0.9.1

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)
 
@@ -83,17 +84,18 @@ Every command supports `--json` where noted. Global flags: `-q`/`--quiet`, `--ti
 | Command | Description |
 |---------|-------------|
 | `ov init` | Initialize `.overstory/` and bootstrap os-eco tools (`--yes`, `--name`, `--tools`, `--skip-mulch`, `--skip-seeds`, `--skip-canopy`, `--skip-onboard`, `--json`) |
-| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--base-branch`, `--json`) |
+| `ov sling <task-id>` | Spawn a worker agent (`--capability`, `--name`, `--spec`, `--files`, `--parent`, `--depth`, `--skip-scout`, `--skip-review`, `--max-agents`, `--dispatch-max-agents`, `--skip-task-check`, `--no-scout-check`, `--runtime`, `--base-branch`, `--profile`, `--json`) |
 | `ov stop <agent-name>` | Terminate a running agent (`--clean-worktree`, `--json`) |
 | `ov prime` | Load context for orchestrator/agent (`--agent`, `--compact`) |
 | `ov spec write <task-id>` | Write a task specification (`--body`) |
+| `ov discover` | Discover a brownfield codebase via coordinator-driven scout swarm (`--skip`, `--name`, `--attach`, `--watchdog`, `--json`) |
 | `ov update` | Refresh `.overstory/` managed files from installed package (`--agents`, `--manifest`, `--hooks`, `--dry-run`, `--json`) |
 
 ### Coordination
 
 | Command | Description |
 |---------|-------------|
-| `ov coordinator start` | Start persistent coordinator agent (`--attach`/`--no-attach`, `--watchdog`, `--monitor`) |
+| `ov coordinator start` | Start persistent coordinator agent (`--attach`/`--no-attach`, `--watchdog`, `--monitor`, `--profile`) |
 | `ov coordinator stop` | Stop coordinator |
 | `ov coordinator status` | Show coordinator state |
 | `ov coordinator send` | Fire-and-forget message to coordinator (`--subject`) |
@@ -177,14 +179,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
 
@@ -233,7 +237,7 @@ overstory/
     config.ts                     Config loader + validation
     errors.ts                     Custom error types
     json.ts                       Standardized JSON envelope helpers
-    commands/                     One file per CLI subcommand (35 commands)
+    commands/                     One file per CLI subcommand (36 commands)
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle
       supervisor.ts               Team lead management [DEPRECATED]
@@ -267,7 +271,10 @@ overstory/
       ecosystem.ts                os-eco tool dashboard
       update.ts                   Refresh managed files
       upgrade.ts                  npm version upgrades
+      discover.ts                 Brownfield codebase discovery via coordinator-driven scout swarm
       completions.ts              Shell completion generation (bash/zsh/fish)
+    canopy/
+      client.ts                   Canopy client (prompt rendering, listing, emission)
     agents/                       Agent lifecycle management
       manifest.ts                 Agent registry (load + query)
       overlay.ts                  Dynamic CLAUDE.md overlay generator
@@ -284,7 +291,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/ov-co-creation.md

@@ -0,0 +1,90 @@
+---
+name: ov-co-creation
+description: Co-creation workflow profile — human-in-the-loop at explicit decision gates
+---
+
+## propulsion-principle
+
+Read your assignment. For implementation work within an approved plan, execute immediately — no confirmation needed for routine decisions (naming, file organization, test strategy, implementation details within spec).
+
+PAUSE at decision gates. When you encounter an architectural choice, design fork, scope boundary, or tool selection, stop and do not proceed. Instead:
+
+1. Write a structured decision document (context, options, tradeoffs, recommendation).
+2. Send it as a decision_gate mail to the coordinator.
+3. Wait for a response before proceeding past the gate.
+
+Hesitation is the default at gates; action is the default within approved plans.
+
+## escalation-policy
+
+At decision points, present options rather than choosing. When you encounter a meaningful decision:
+
+1. Write a structured decision document: context, 2+ options with tradeoffs, and your recommendation.
+2. Send it as a decision_gate mail to the coordinator and wait.
+3. Do not proceed until you receive a reply selecting an option.
+
+Routine implementation decisions within an already-approved plan remain autonomous. Do not send decision gates for: variable names, file organization within spec, test strategy, or minor implementation choices that do not affect overall direction.
+
+Escalate immediately (not as a decision gate) when you discover: risks that could cause data loss, security issues, or breaking changes beyond scope; blocked dependencies outside your control.
+
+## artifact-expectations
+
+Decision artifacts come before code. Deliverables in order:
+
+1. **Option memos**: For any decision with multiple viable approaches, write a structured memo with options, tradeoffs, and a recommendation. Send as a decision_gate mail and await approval.
+2. **ADRs (Architecture Decision Records)**: For architectural choices, create a lightweight ADR capturing context, decision, and consequences.
+3. **Tradeoff matrices**: When comparing approaches across multiple dimensions, present a structured comparison.
+4. **Code and tests**: Implementation proceeds after decision artifacts are approved. Code must be clean, follow project conventions, and include automated tests.
+5. **Quality gates**: All lints, type checks, and tests must pass before reporting completion.
+
+Do not write implementation code before decisions are resolved. The human reviews and approves decision documents; implementation follows approval.
+
+## completion-criteria
+
+Work is complete when all of the following are true:
+
+- All quality gates pass: tests green, linting clean, type checking passes.
+- Changes are committed to the appropriate branch.
+- Any issues tracked in the task system are updated or closed.
+- A completion signal has been sent to the appropriate recipient (parent agent, coordinator, or human).
+
+Do not declare completion prematurely. Run the quality gates yourself — do not assume they pass. If a gate fails, fix the issue before reporting done.
+
+## human-role
+
+The human is an active co-creator at explicit decision gates — not a hands-off supervisor.
+
+- **Active at gates.** The human reviews decision documents and selects options via mail reply. The agent waits for this input before proceeding.
+- **Autonomous between gates.** Once a direction is approved, the agent executes without further check-ins. Implementation details within an approved plan are delegated.
+- **Milestone reviews.** The human reviews work at defined checkpoints (planning, prototype, final). These are collaborative reviews with explicit proceed signals.
+- **Minimal interruption between gates.** Do not ask questions that could be answered by reading the codebase or attempting something. Reserve interruptions for genuinely ambiguous requirements.
+
+## decision-gates
+
+When you reach a decision point (architectural choice, scope boundary, design fork, tool selection), follow this protocol:
+
+1. **Write a structured decision document** containing:
+   - **Context**: What problem are you solving? What constraints apply?
+   - **Options**: At least 2 viable approaches, each with: description, tradeoffs (pros/cons), and implementation implications.
+   - **Recommendation**: Which option you recommend and why.
+
+2. **Send a decision_gate mail** to the coordinator with the decision document in the body. Include a payload with the options array and brief context. Use --type decision_gate.
+
+3. **BLOCK and wait** for a reply. Do not continue past the gate without a response. Poll your inbox periodically while waiting.
+
+Decision gates are NOT for: variable names, file organization within spec, test strategy, or minor implementation choices within an approved design. They are for choices that meaningfully affect the direction of work.
+
+## milestone-reviews
+
+Send checkpoint reviews at three milestones:
+
+**After planning** (before any implementation begins):
+Send a status mail with: scope summary (what will be built), approach (high-level design with all decisions resolved via gates), file list (which files will be affected), and any open questions requiring confirmation before starting.
+
+**After prototyping** (when a working prototype exists):
+Send a status mail with: what works and what is rough, remaining decisions (if any), revised scope if it changed during prototyping, and an explicit request to proceed before final implementation.
+
+**Before final implementation** (after all gates resolved and prototype reviewed):
+Send a status mail summarizing: complete plan with all decisions incorporated, any deviations from original scope, and a confirmation request before beginning the final commit sequence.
+
+Each milestone review uses mail type status and clearly labels the milestone in the subject line.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.8.6",
+	"version": "0.9.1",
 	"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/agents/overlay.ts

@@ -35,6 +35,18 @@ function formatMulchDomains(domains: readonly string[]): string {
 	return `\`\`\`bash\nml prime ${domains.join(" ")}\n\`\`\``;
 }
 
+/**
+ * Format profile content (Layer 2: deployment-specific WHAT KIND) for embedding in the overlay.
+ * Returns empty string if no profile was provided (omits the section entirely).
+ * When profile IS provided, renders it as-is — the caller (canopy) owns the formatting.
+ */
+function formatProfile(profileContent: string | undefined): string {
+	if (!profileContent || profileContent.trim().length === 0) {
+		return "";
+	}
+	return profileContent;
+}
+
 /**
  * Format pre-fetched mulch expertise for embedding in the overlay.
  * Returns empty string if no expertise was provided (omits the section entirely).
@@ -314,6 +326,7 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 		"{{SKIP_SCOUT}}": config.skipScout ? SKIP_SCOUT_SECTION : "",
 		"{{DISPATCH_OVERRIDES}}": formatDispatchOverrides(config),
 		"{{BASE_DEFINITION}}": config.baseDefinition,
+		"{{PROFILE_INSTRUCTIONS}}": formatProfile(config.profileContent),
 		"{{QUALITY_GATE_INLINE}}": formatQualityGatesInline(config.qualityGates),
 		"{{QUALITY_GATE_STEPS}}": formatQualityGatesSteps(config.qualityGates),
 		"{{QUALITY_GATE_BASH}}": formatQualityGatesBash(config.qualityGates),

package/src/canopy/client.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Tests for the Canopy CLI client.
+ *
+ * Uses real `cn` CLI calls against the actual .canopy/ directory.
+ * We do not mock the CLI — the project root has real prompts to test against.
+ * Tests are skipped if the `cn` CLI is not installed (e.g. in CI).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { AgentError } from "../errors.ts";
+import { createCanopyClient } from "./client.ts";
+
+// Check if canopy CLI is available
+let hasCanopy = false;
+try {
+	const proc = Bun.spawn(["which", "cn"], { stdout: "pipe", stderr: "pipe" });
+	const exitCode = await proc.exited;
+	hasCanopy = exitCode === 0;
+} catch {
+	hasCanopy = false;
+}
+
+// The worktree root has its own .canopy/ symlinked/shared from the canonical root.
+// Use process.cwd() which is set to the worktree root in bun test.
+const cwd = process.cwd();
+const client = createCanopyClient(cwd);
+
+describe("CanopyClient.list()", () => {
+	test.skipIf(!hasCanopy)("returns prompts array with at least one entry", async () => {
+		const result = await client.list();
+		expect(result.success).toBe(true);
+		expect(Array.isArray(result.prompts)).toBe(true);
+		expect(result.prompts.length).toBeGreaterThan(0);
+		const first = result.prompts[0];
+		expect(first).toBeDefined();
+		expect(typeof first?.name).toBe("string");
+		expect(typeof first?.version).toBe("number");
+		expect(Array.isArray(first?.sections)).toBe(true);
+	});
+});
+
+describe("CanopyClient.render()", () => {
+	test.skipIf(!hasCanopy)(
+		"returns CanopyRenderResult with name, version, sections for 'builder' prompt",
+		async () => {
+			const result = await client.render("builder");
+			expect(result.success).toBe(true);
+			expect(result.name).toBe("builder");
+			expect(typeof result.version).toBe("number");
+			expect(result.version).toBeGreaterThan(0);
+			expect(Array.isArray(result.sections)).toBe(true);
+			expect(result.sections.length).toBeGreaterThan(0);
+			const section = result.sections[0];
+			expect(section).toBeDefined();
+			expect(typeof section?.name).toBe("string");
+			expect(typeof section?.body).toBe("string");
+		},
+	);
+
+	test.skipIf(!hasCanopy)("throws AgentError on non-existent prompt", async () => {
+		await expect(client.render("nonexistent-prompt-xyz-404")).rejects.toThrow(AgentError);
+	});
+});
+
+describe("CanopyClient.show()", () => {
+	test.skipIf(!hasCanopy)("returns prompt object for 'builder'", async () => {
+		const result = await client.show("builder");
+		expect(result.success).toBe(true);
+		expect(result.prompt).toBeDefined();
+		expect(result.prompt.name).toBe("builder");
+		expect(typeof result.prompt.version).toBe("number");
+		expect(typeof result.prompt.id).toBe("string");
+		expect(Array.isArray(result.prompt.sections)).toBe(true);
+	});
+
+	test.skipIf(!hasCanopy)("throws AgentError on non-existent prompt", async () => {
+		await expect(client.show("nonexistent-prompt-xyz-404")).rejects.toThrow(AgentError);
+	});
+});
+
+describe("CanopyClient.validate()", () => {
+	test.skipIf(!hasCanopy)("returns {success, errors} for a named prompt", async () => {
+		const result = await client.validate("scout");
+		expect(typeof result.success).toBe("boolean");
+		expect(Array.isArray(result.errors)).toBe(true);
+		if (result.success) {
+			expect(result.errors.length).toBe(0);
+		}
+	});
+
+	test.skipIf(!hasCanopy)("returns success=false with errors for an invalid prompt", async () => {
+		// 'builder' is known to fail schema validation (missing test gate)
+		const result = await client.validate("builder");
+		expect(typeof result.success).toBe("boolean");
+		expect(Array.isArray(result.errors)).toBe(true);
+		// Either valid or invalid — just verify structure is correct
+		if (!result.success) {
+			expect(result.errors.length).toBeGreaterThan(0);
+		}
+	});
+
+	test.skipIf(!hasCanopy)("validate --all returns result with success boolean", async () => {
+		const result = await client.validate(undefined, { all: true });
+		expect(typeof result.success).toBe("boolean");
+		expect(Array.isArray(result.errors)).toBe(true);
+	});
+});