@os-eco/overstory-cli 0.6.4 → 0.6.5

package/README.md

@@ -222,7 +222,7 @@ overstory inspect <agent>               Deep per-agent inspection
   --no-tmux                              Skip tmux capture
   --limit <n>                            Limit events shown
 
-overstory spec write <bead-id>          Write a task specification
+overstory spec write <task-id>          Write a task specification
   --body <content>                       Spec content (or pipe via stdin)
 
 overstory errors                        Aggregated error view across agents
@@ -270,16 +270,16 @@ Global Flags:
 ## Tech Stack
 
 - **Runtime**: Bun (TypeScript directly, no build step)
-- **Dependencies**: Minimal runtime — `chalk` (color output), core I/O via Bun built-in APIs
+- **Dependencies**: Minimal runtime — `chalk` (color output), `commander` (CLI framework), core I/O via Bun built-in APIs
 - **Database**: SQLite via `bun:sqlite` (WAL mode for concurrent access)
 - **Linting**: Biome (formatter + linter)
-- **Testing**: `bun test` (2128 tests across 76 files, colocated with source)
+- **Testing**: `bun test` (2145 tests across 76 files, colocated with source)
 - **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
 
 ## Development
 
 ```bash
-# Run tests (2128 tests across 76 files)
+# Run tests (2145 tests across 76 files)
 bun test
 
 # Run a single test

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.4",
+	"version": "0.6.5",
 	"description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/agents/checkpoint.test.ts

@@ -9,7 +9,7 @@ import { clearCheckpoint, loadCheckpoint, saveCheckpoint } from "./checkpoint.ts
 function makeCheckpoint(overrides?: Partial<SessionCheckpoint>): SessionCheckpoint {
 	return {
 		agentName: "test-agent",
-		beadId: "overstory-abc1",
+		taskId: "overstory-abc1",
 		sessionId: "session-001",
 		timestamp: "2025-01-01T00:00:00.000Z",
 		progressSummary: "Implemented checkpoint module",
@@ -40,7 +40,7 @@ describe("checkpoint", () => {
 
 		expect(loaded).not.toBeNull();
 		expect(loaded?.agentName).toBe("test-agent");
-		expect(loaded?.beadId).toBe("overstory-abc1");
+		expect(loaded?.taskId).toBe("overstory-abc1");
 		expect(loaded?.sessionId).toBe("session-001");
 		expect(loaded?.progressSummary).toBe("Implemented checkpoint module");
 		expect(loaded?.filesModified).toEqual(["src/agents/checkpoint.ts"]);

package/src/agents/hooks-deployer.test.ts

@@ -8,6 +8,7 @@ import {
 	buildBashPathBoundaryScript,
 	buildPathBoundaryGuardScript,
 	deployHooks,
+	escapeForSingleQuotedShell,
 	getBashPathBoundaryGuards,
 	getCapabilityGuards,
 	getDangerGuards,
@@ -2116,3 +2117,39 @@ describe("bash path boundary integration", () => {
 		expect(universalGuard.hooks[0].command).toContain('"decision":"block"');
 	});
 });
+
+describe("escapeForSingleQuotedShell", () => {
+	test("no single quotes: string passes through unchanged", () => {
+		expect(escapeForSingleQuotedShell("hello world")).toBe("hello world");
+	});
+
+	test("single quotes escaped: it's becomes it'\\''s", () => {
+		expect(escapeForSingleQuotedShell("it's")).toBe("it'\\''s");
+	});
+
+	test("multiple single quotes: each one is escaped independently", () => {
+		expect(escapeForSingleQuotedShell("can't won't")).toBe("can'\\''t won'\\''t");
+	});
+
+	test("empty string: returns empty string", () => {
+		expect(escapeForSingleQuotedShell("")).toBe("");
+	});
+
+	test("blockGuard shell command outputs valid JSON when executed", async () => {
+		const guards = getCapabilityGuards("builder");
+		const taskGuard = guards.find((g) => g.matcher === "Task");
+		expect(taskGuard).toBeDefined();
+		const cmd = taskGuard?.hooks[0]?.command ?? "";
+		const echoCmd = cmd.replace('[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0; ', "");
+		const proc = Bun.spawn(["sh", "-c", echoCmd], {
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, OVERSTORY_AGENT_NAME: "test-agent" },
+		});
+		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("overstory sling");
+	});
+});

package/src/agents/hooks-deployer.ts

@@ -205,6 +205,20 @@ export function getPathBoundaryGuards(): HookEntry[] {
 	];
 }
 
+/**
+ * Escape a string for use inside a single-quoted POSIX shell string.
+ *
+ * POSIX single-quoted strings cannot contain single quotes at all.
+ * The standard technique is to end the single-quoted segment, emit an escaped
+ * single quote using $'\'', then start a new single-quoted segment:
+ *   'it'\''s fine'  →  it's fine
+ *
+ * Exported so tests can verify escaping directly.
+ */
+export function escapeForSingleQuotedShell(str: string): string {
+	return str.replace(/'/g, "'\\''");
+}
+
 /**
  * Build a PreToolUse guard that blocks a specific tool.
  *
@@ -218,7 +232,7 @@ function blockGuard(toolName: string, reason: string): HookEntry {
 		hooks: [
 			{
 				type: "command",
-				command: `${ENV_GUARD} echo '${response}'`,
+				command: `${ENV_GUARD} echo '${escapeForSingleQuotedShell(response)}'`,
 			},
 		],
 	};

package/src/agents/identity.test.ts

@@ -72,12 +72,12 @@ describe("identity", () => {
 				expertiseDomains: [],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: "Fixed authentication bug",
 						completedAt: "2024-01-15T12:00:00Z",
 					},
 					{
-						beadId: "beads-002",
+						taskId: "beads-002",
 						summary: "Added user profile page",
 						completedAt: "2024-01-16T14:30:00Z",
 					},
@@ -89,10 +89,10 @@ describe("identity", () => {
 			const filePath = join(tempDir, "test-agent", "identity.yaml");
 			const content = await Bun.file(filePath).text();
 			expect(content).toContain("recentTasks:");
-			expect(content).toContain("\t- beadId: beads-001");
+			expect(content).toContain("\t- taskId: beads-001");
 			expect(content).toContain("\t\tsummary: Fixed authentication bug");
 			expect(content).toContain('\t\tcompletedAt: "2024-01-15T12:00:00Z"');
-			expect(content).toContain("\t- beadId: beads-002");
+			expect(content).toContain("\t- taskId: beads-002");
 			expect(content).toContain("\t\tsummary: Added user profile page");
 			expect(content).toContain('\t\tcompletedAt: "2024-01-16T14:30:00Z"');
 		});
@@ -106,7 +106,7 @@ describe("identity", () => {
 				expertiseDomains: ["domain: with colon", "domain#with hash", " leading space"],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: 'Fixed bug: "memory leak"',
 						completedAt: "2024-01-15T12:00:00Z",
 					},
@@ -198,7 +198,7 @@ describe("identity", () => {
 				expertiseDomains: ["typescript", "testing"],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: "Fixed bug",
 						completedAt: "2024-01-15T12:00:00Z",
 					},
@@ -216,7 +216,7 @@ describe("identity", () => {
 			expect(loaded?.sessionsCompleted).toBe(7);
 			expect(loaded?.expertiseDomains).toEqual(["typescript", "testing"]);
 			expect(loaded?.recentTasks).toHaveLength(1);
-			expect(loaded?.recentTasks[0]?.beadId).toBe("beads-001");
+			expect(loaded?.recentTasks[0]?.taskId).toBe("beads-001");
 			expect(loaded?.recentTasks[0]?.summary).toBe("Fixed bug");
 			expect(loaded?.recentTasks[0]?.completedAt).toBe("2024-01-15T12:00:00Z");
 		});
@@ -252,17 +252,17 @@ describe("identity", () => {
 				expertiseDomains: [],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: "Task 1",
 						completedAt: "2024-01-15T12:00:00Z",
 					},
 					{
-						beadId: "beads-002",
+						taskId: "beads-002",
 						summary: "Task 2",
 						completedAt: "2024-01-16T12:00:00Z",
 					},
 					{
-						beadId: "beads-003",
+						taskId: "beads-003",
 						summary: "Task 3",
 						completedAt: "2024-01-17T12:00:00Z",
 					},
@@ -273,9 +273,9 @@ describe("identity", () => {
 			const loaded = await loadIdentity(tempDir, "test-agent");
 
 			expect(loaded?.recentTasks).toHaveLength(3);
-			expect(loaded?.recentTasks[0]?.beadId).toBe("beads-001");
-			expect(loaded?.recentTasks[1]?.beadId).toBe("beads-002");
-			expect(loaded?.recentTasks[2]?.beadId).toBe("beads-003");
+			expect(loaded?.recentTasks[0]?.taskId).toBe("beads-001");
+			expect(loaded?.recentTasks[1]?.taskId).toBe("beads-002");
+			expect(loaded?.recentTasks[2]?.taskId).toBe("beads-003");
 		});
 
 		test("handles quoted strings with special characters", async () => {
@@ -287,7 +287,7 @@ describe("identity", () => {
 				expertiseDomains: ["domain: with colon", "domain#with hash"],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: 'Fixed bug: "memory leak"',
 						completedAt: "2024-01-15T12:00:00Z",
 					},
@@ -311,7 +311,7 @@ describe("identity", () => {
 				expertiseDomains: [],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: "Path: C:\\Users\\test\\file.txt",
 						completedAt: "2024-01-15T12:00:00Z",
 					},
@@ -435,14 +435,14 @@ recentTasks: []
 			const beforeUpdate = Date.now();
 			const updated = await updateIdentity(tempDir, "test-agent", {
 				completedTask: {
-					beadId: "beads-001",
+					taskId: "beads-001",
 					summary: "Fixed authentication bug",
 				},
 			});
 			const afterUpdate = Date.now();
 
 			expect(updated.recentTasks).toHaveLength(1);
-			expect(updated.recentTasks[0]?.beadId).toBe("beads-001");
+			expect(updated.recentTasks[0]?.taskId).toBe("beads-001");
 			expect(updated.recentTasks[0]?.summary).toBe("Fixed authentication bug");
 
 			// Verify timestamp is within the update window
@@ -454,7 +454,7 @@ recentTasks: []
 		test("caps recentTasks at 20 entries, dropping oldest", async () => {
 			// Create identity with 19 tasks
 			const existingTasks = Array.from({ length: 19 }, (_, i) => ({
-				beadId: `beads-${i.toString().padStart(3, "0")}`,
+				taskId: `beads-${i.toString().padStart(3, "0")}`,
 				summary: `Task ${i}`,
 				completedAt: `2024-01-${(i + 1).toString().padStart(2, "0")}T12:00:00Z`,
 			}));
@@ -472,20 +472,20 @@ recentTasks: []
 
 			// Add two more tasks (total would be 21)
 			let updated = await updateIdentity(tempDir, "test-agent", {
-				completedTask: { beadId: "beads-019", summary: "Task 19" },
+				completedTask: { taskId: "beads-019", summary: "Task 19" },
 			});
 
 			expect(updated.recentTasks).toHaveLength(20);
-			expect(updated.recentTasks[0]?.beadId).toBe("beads-000");
+			expect(updated.recentTasks[0]?.taskId).toBe("beads-000");
 
 			updated = await updateIdentity(tempDir, "test-agent", {
-				completedTask: { beadId: "beads-020", summary: "Task 20" },
+				completedTask: { taskId: "beads-020", summary: "Task 20" },
 			});
 
 			expect(updated.recentTasks).toHaveLength(20);
 			// Oldest task (beads-000) should be dropped
-			expect(updated.recentTasks[0]?.beadId).toBe("beads-001");
-			expect(updated.recentTasks[19]?.beadId).toBe("beads-020");
+			expect(updated.recentTasks[0]?.taskId).toBe("beads-001");
+			expect(updated.recentTasks[19]?.taskId).toBe("beads-020");
 		});
 
 		test("applies multiple updates simultaneously", async () => {
@@ -503,7 +503,7 @@ recentTasks: []
 				sessionsCompleted: 2,
 				expertiseDomains: ["testing", "architecture"],
 				completedTask: {
-					beadId: "beads-001",
+					taskId: "beads-001",
 					summary: "Completed task",
 				},
 			});
@@ -554,12 +554,12 @@ recentTasks: []
 				expertiseDomains: ["typescript", "testing", "architecture"],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: "Implemented feature X",
 						completedAt: "2024-01-15T12:00:00Z",
 					},
 					{
-						beadId: "beads-002",
+						taskId: "beads-002",
 						summary: "Fixed bug in module Y",
 						completedAt: "2024-01-16T14:30:00Z",
 					},
@@ -587,7 +587,7 @@ recentTasks: []
 				],
 				recentTasks: [
 					{
-						beadId: "beads-001",
+						taskId: "beads-001",
 						summary: 'Summary with "quotes" and: colons',
 						completedAt: "2024-01-15T12:00:00Z",
 					},

package/src/agents/identity.ts

@@ -39,7 +39,7 @@ function serializeIdentityYaml(identity: AgentIdentity): string {
 	} else {
 		lines.push("recentTasks:");
 		for (const task of identity.recentTasks) {
-			lines.push(`\t- beadId: ${quoteIfNeeded(task.beadId)}`);
+			lines.push(`\t- taskId: ${quoteIfNeeded(task.taskId)}`);
 			lines.push(`\t\tsummary: ${quoteIfNeeded(task.summary)}`);
 			lines.push(`\t\tcompletedAt: ${quoteIfNeeded(task.completedAt)}`);
 		}
@@ -82,7 +82,7 @@ function quoteIfNeeded(value: string): string {
  * This is a purpose-built parser for the identity YAML format. It handles:
  * - Simple key: value pairs (strings, numbers)
  * - Arrays of scalars (expertiseDomains)
- * - Arrays of objects (recentTasks with beadId, summary, completedAt)
+ * - Arrays of objects (recentTasks with taskId, summary, completedAt)
  * - Empty arrays (`[]`)
  * - Quoted strings
  * - Tab indentation
@@ -95,10 +95,10 @@ function parseIdentityYaml(text: string): AgentIdentity {
 	let created = "";
 	let sessionsCompleted = 0;
 	const expertiseDomains: string[] = [];
-	const recentTasks: Array<{ beadId: string; summary: string; completedAt: string }> = [];
+	const recentTasks: Array<{ taskId: string; summary: string; completedAt: string }> = [];
 
 	let currentSection: "none" | "expertiseDomains" | "recentTasks" = "none";
-	let currentTask: { beadId: string; summary: string; completedAt: string } | null = null;
+	let currentTask: { taskId: string; summary: string; completedAt: string } | null = null;
 
 	for (const rawLine of lines) {
 		const trimmed = rawLine.trim();
@@ -169,7 +169,7 @@ function parseIdentityYaml(text: string): AgentIdentity {
 				if (currentTask !== null) {
 					recentTasks.push(currentTask);
 				}
-				currentTask = { beadId: "", summary: "", completedAt: "" };
+				currentTask = { taskId: "", summary: "", completedAt: "" };
 
 				// Parse the key-value on the same line as the dash
 				const itemContent = trimmed.slice(2).trim();
@@ -210,13 +210,13 @@ function parseIdentityYaml(text: string): AgentIdentity {
  * Assign a parsed field value to a task object by key name.
  */
 function assignTaskField(
-	task: { beadId: string; summary: string; completedAt: string },
+	task: { taskId: string; summary: string; completedAt: string },
 	key: string,
 	value: string,
 ): void {
 	switch (key) {
-		case "beadId":
-			task.beadId = value;
+		case "taskId":
+			task.taskId = value;
 			break;
 		case "summary":
 			task.summary = value;
@@ -336,7 +336,7 @@ export async function updateIdentity(
 	baseDir: string,
 	name: string,
 	update: Partial<Pick<AgentIdentity, "sessionsCompleted" | "expertiseDomains">> & {
-		completedTask?: { beadId: string; summary: string };
+		completedTask?: { taskId: string; summary: string };
 	},
 ): Promise<AgentIdentity> {
 	const identity = await loadIdentity(baseDir, name);
@@ -364,7 +364,7 @@ export async function updateIdentity(
 	// Append completed task
 	if (update.completedTask !== undefined) {
 		identity.recentTasks.push({
-			beadId: update.completedTask.beadId,
+			taskId: update.completedTask.taskId,
 			summary: update.completedTask.summary,
 			completedAt: new Date().toISOString(),
 		});

package/src/agents/lifecycle.test.ts

@@ -23,7 +23,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-1",
 			sessionId: "session-100",
-			beadId: "overstory-xyz1",
+			taskId: "overstory-xyz1",
 			reason: "compaction",
 			progressSummary: "Built the widget",
 			pendingWork: "Tests remain",
@@ -56,7 +56,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-2",
 			sessionId: "session-200",
-			beadId: "overstory-abc2",
+			taskId: "overstory-abc2",
 			reason: "crash",
 			progressSummary: "Halfway done",
 			pendingWork: "Finish implementation",
@@ -82,7 +82,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-3",
 			sessionId: "session-300",
-			beadId: "overstory-def3",
+			taskId: "overstory-def3",
 			reason: "manual",
 			progressSummary: "Done with phase 1",
 			pendingWork: "Phase 2",
@@ -116,7 +116,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-4",
 			sessionId: "session-400",
-			beadId: "overstory-ghi4",
+			taskId: "overstory-ghi4",
 			reason: "compaction",
 			progressSummary: "First session work",
 			pendingWork: "Continue",
@@ -137,7 +137,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-4",
 			sessionId: "session-401",
-			beadId: "overstory-ghi4",
+			taskId: "overstory-ghi4",
 			reason: "timeout",
 			progressSummary: "Second session work",
 			pendingWork: "Finish up",
@@ -172,7 +172,7 @@ describe("lifecycle", () => {
 			agentsDir,
 			agentName: "builder-5",
 			sessionId: "session-500",
-			beadId: "overstory-jkl5",
+			taskId: "overstory-jkl5",
 			reason: "compaction",
 			progressSummary: "Done",
 			pendingWork: "Nothing",

package/src/agents/lifecycle.ts

@@ -73,7 +73,7 @@ export async function initiateHandoff(options: {
 	agentsDir: string;
 	agentName: string;
 	sessionId: string;
-	beadId: string;
+	taskId: string;
 	reason: SessionHandoff["reason"];
 	progressSummary: string;
 	pendingWork: string;
@@ -83,7 +83,7 @@ export async function initiateHandoff(options: {
 }): Promise<SessionHandoff> {
 	const checkpoint: SessionCheckpoint = {
 		agentName: options.agentName,
-		beadId: options.beadId,
+		taskId: options.taskId,
 		sessionId: options.sessionId,
 		timestamp: new Date().toISOString(),
 		progressSummary: options.progressSummary,

package/src/agents/overlay.test.ts

@@ -25,7 +25,7 @@ Read your assignment. Execute immediately.
 function makeConfig(overrides?: Partial<OverlayConfig>): OverlayConfig {
 	return {
 		agentName: "test-builder",
-		beadId: "overstory-abc",
+		taskId: "overstory-abc",
 		specPath: ".overstory/specs/overstory-abc.md",
 		branchName: "agent/test-builder/overstory-abc",
 		worktreePath: "/tmp/test-project/.overstory/worktrees/test-builder",
@@ -48,8 +48,8 @@ describe("generateOverlay", () => {
 		expect(output).toContain("my-scout");
 	});
 
-	test("output contains bead ID", async () => {
-		const config = makeConfig({ beadId: "overstory-xyz" });
+	test("output contains task ID", async () => {
+		const config = makeConfig({ taskId: "overstory-xyz" });
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("overstory-xyz");
@@ -261,7 +261,7 @@ describe("generateOverlay", () => {
 		const config = makeConfig({
 			capability: "scout",
 			agentName: "recon-1",
-			beadId: "overstory-task1",
+			taskId: "overstory-task1",
 			parentAgent: "lead-alpha",
 		});
 		const output = await generateOverlay(config);
@@ -419,7 +419,7 @@ describe("generateOverlay", () => {
 	});
 
 	test("default trackerCli renders as bd in quality gates", async () => {
-		const config = makeConfig({ capability: "builder", beadId: "overstory-task1" });
+		const config = makeConfig({ capability: "builder", taskId: "overstory-task1" });
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("bd close overstory-task1");
@@ -429,7 +429,7 @@ describe("generateOverlay", () => {
 		const config = makeConfig({
 			capability: "builder",
 			trackerCli: "sd",
-			beadId: "overstory-test1",
+			taskId: "overstory-test1",
 		});
 		const output = await generateOverlay(config);
 
@@ -451,7 +451,7 @@ describe("generateOverlay", () => {
 		const config = makeConfig({
 			capability: "scout",
 			trackerCli: "sd",
-			beadId: "overstory-test2",
+			taskId: "overstory-test2",
 		});
 		const output = await generateOverlay(config);
 
@@ -482,7 +482,7 @@ describe("generateOverlay", () => {
 	});
 
 	test("defaults backward-compatible: no trackerCli/trackerName produces bd/beads", async () => {
-		const config = makeConfig({ capability: "builder", beadId: "overstory-back" });
+		const config = makeConfig({ capability: "builder", taskId: "overstory-back" });
 		const output = await generateOverlay(config);
 
 		expect(output).toContain("bd close overstory-back");
@@ -521,7 +521,7 @@ describe("writeOverlay", () => {
 		const outputPath = join(worktreePath, ".claude", "CLAUDE.md");
 		const content = await Bun.file(outputPath).text();
 		expect(content).toContain("file-writer-test");
-		expect(content).toContain(config.beadId);
+		expect(content).toContain(config.taskId);
 		expect(content).toContain(config.branchName);
 	});
 

package/src/agents/overlay.ts

@@ -91,7 +91,7 @@ function formatQualityGates(config: OverlayConfig): string {
 			"Before reporting completion:",
 			"",
 			`1. **Record mulch learnings:** \`mulch record <domain> --type <convention|pattern|reference> --description "..."\` — capture reusable knowledge from your work`,
-			`2. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.beadId} --reason "summary of findings"\``,
+			`2. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.taskId} --reason "summary of findings"\``,
 			`3. **Send results:** \`overstory mail send --to ${config.parentAgent ?? "coordinator"} --subject "done" --body "Summary" --type result --agent ${config.agentName}\``,
 			"",
 			"You are a read-only agent. Do NOT commit, modify files, or run quality gates.",
@@ -113,8 +113,8 @@ function formatQualityGates(config: OverlayConfig): string {
 		...gateLines,
 		`${gateLines.length + 1}. **Commit:** all changes committed to your branch (${config.branchName})`,
 		`${gateLines.length + 2}. **Record mulch learnings:** \`mulch record <domain> --type <convention|pattern|failure|decision> --description "..." --outcome-status success --outcome-agent ${config.agentName}\` — capture insights from your work`,
-		`${gateLines.length + 3}. **Signal completion:** send \`worker_done\` mail to ${config.parentAgent ?? "coordinator"}: \`overstory mail send --to ${config.parentAgent ?? "coordinator"} --subject "Worker done: ${config.beadId}" --body "Quality gates passed." --type worker_done --agent ${config.agentName}\``,
-		`${gateLines.length + 4}. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.beadId} --reason "summary of changes"\``,
+		`${gateLines.length + 3}. **Signal completion:** send \`worker_done\` mail to ${config.parentAgent ?? "coordinator"}: \`overstory mail send --to ${config.parentAgent ?? "coordinator"} --subject "Worker done: ${config.taskId}" --body "Quality gates passed." --type worker_done --agent ${config.agentName}\``,
+		`${gateLines.length + 4}. **Close issue:** \`${config.trackerCli ?? "bd"} close ${config.taskId} --reason "summary of changes"\``,
 		"",
 		"Do NOT push to the canonical branch. Your work will be merged by the",
 		"coordinator via `overstory merge`.",
@@ -205,7 +205,7 @@ export async function generateOverlay(config: OverlayConfig): Promise<string> {
 
 	const replacements: Record<string, string> = {
 		"{{AGENT_NAME}}": config.agentName,
-		"{{BEAD_ID}}": config.beadId,
+		"{{BEAD_ID}}": config.taskId,
 		"{{SPEC_PATH}}": config.specPath ?? "No spec file provided",
 		"{{BRANCH_NAME}}": config.branchName,
 		"{{WORKTREE_PATH}}": config.worktreePath,

package/src/commands/agents.test.ts

@@ -97,7 +97,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-test"),
 			branchName: "overstory/builder-test/task-123",
-			beadId: "task-123",
+			taskId: "task-123",
 			tmuxSession: "overstory-test-builder",
 			state: "working",
 			pid: 12345,
@@ -129,7 +129,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-test"),
 			branchName: "overstory/builder-test/task-123",
-			beadId: "task-123",
+			taskId: "task-123",
 			tmuxSession: "overstory-test-builder",
 			state: "working",
 			pid: 12345,
@@ -148,7 +148,7 @@ describe("discoverAgents", () => {
 			capability: "scout",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "scout-test"),
 			branchName: "overstory/scout-test/task-456",
-			beadId: "task-456",
+			taskId: "task-456",
 			tmuxSession: "overstory-test-scout",
 			state: "working",
 			pid: 12346,
@@ -180,7 +180,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-working"),
 			branchName: "overstory/builder-working/task-123",
-			beadId: "task-123",
+			taskId: "task-123",
 			tmuxSession: "overstory-test-working",
 			state: "working",
 			pid: 12345,
@@ -199,7 +199,7 @@ describe("discoverAgents", () => {
 			capability: "builder",
 			worktreePath: join(tempDir, ".overstory", "worktrees", "builder-completed"),
 			branchName: "overstory/builder-completed/task-456",
-			beadId: "task-456",
+			taskId: "task-456",
 			tmuxSession: "overstory-test-completed",
 			state: "completed",
 			pid: null,

package/src/commands/agents.ts

@@ -18,7 +18,7 @@ export interface DiscoveredAgent {
 	agentName: string;
 	capability: string;
 	state: string;
-	beadId: string;
+	taskId: string;
 	branchName: string;
 	parentAgent: string | null;
 	depth: number;
@@ -117,7 +117,7 @@ export async function discoverAgents(
 					agentName: session.agentName,
 					capability: session.capability,
 					state: session.state,
-					beadId: session.beadId,
+					taskId: session.taskId,
 					branchName: session.branchName,
 					parentAgent: session.parentAgent,
 					depth: session.depth,
@@ -166,7 +166,7 @@ function printAgents(agents: DiscoveredAgent[]): void {
 	for (const agent of agents) {
 		const icon = getStateIcon(agent.state);
 		w(`  ${icon} ${agent.agentName} [${agent.capability}]\n`);
-		w(`    State: ${agent.state} | Task: ${agent.beadId}\n`);
+		w(`    State: ${agent.state} | Task: ${agent.taskId}\n`);
 		w(`    Branch: ${agent.branchName}\n`);
 		w(`    Parent: ${agent.parentAgent ?? "none"} | Depth: ${agent.depth}\n`);