@os-eco/overstory-cli 0.6.1 → 0.6.5

package/README.md

@@ -127,6 +127,7 @@ overstory sling <task-id>              Spawn a worker agent
   --parent <agent-name>                  Parent (for hierarchy tracking)
   --depth <n>                            Current hierarchy depth
   --skip-scout                           Skip scout phase (passed to lead overlay)
+  --skip-task-check                      Skip task existence validation
   --json                                 JSON output
 
 overstory stop <agent-name>            Terminate a running agent
@@ -221,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
@@ -269,16 +270,16 @@ Global Flags:
 ## Tech Stack
 
 - **Runtime**: Bun (TypeScript directly, no build step)
-- **Dependencies**: Zero runtime dependencies — only 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` (2087 tests across 75 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 (2087 tests across 75 files)
+# Run tests (2145 tests across 76 files)
 bun test
 
 # Run a single test
@@ -307,14 +308,14 @@ Use the bump script to update both:
 bun run version:bump <major|minor|patch>
 ```
 
-Git tags are created automatically by GitHub Actions when a version bump is pushed to `main`.
+Git tags, npm publishing, and GitHub releases are handled automatically by the `publish.yml` workflow when a version bump is pushed to `main`.
 
 ## Project Structure
 
 ```
 overstory/
   src/
-    index.ts                      CLI entry point (command router)
+    index.ts                      CLI entry point (Commander.js program)
     types.ts                      Shared types and interfaces
     config.ts                     Config loader + validation
     errors.ts                     Custom error types
@@ -322,7 +323,7 @@ overstory/
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle
       supervisor.ts               Team lead management
-      dashboard.ts                Live TUI dashboard (ANSI, zero deps)
+      dashboard.ts                Live TUI dashboard (ANSI via Chalk)
       hooks.ts                    Orchestrator hooks management
       sling.ts                    Agent spawning
       group.ts                    Task group batch tracking

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.1",
+	"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",
@@ -21,10 +21,15 @@
 		"developer-tools"
 	],
 	"bin": {
-		"overstory": "./src/index.ts"
+		"overstory": "./src/index.ts",
+		"ov": "./src/index.ts"
 	},
 	"main": "src/index.ts",
-	"files": ["src", "agents", "templates"],
+	"files": [
+		"src",
+		"agents",
+		"templates"
+	],
 	"publishConfig": {
 		"access": "public"
 	},
@@ -38,7 +43,10 @@
 		"typecheck": "tsc --noEmit",
 		"version:bump": "bun scripts/version-bump.ts"
 	},
-	"dependencies": {},
+	"dependencies": {
+		"chalk": "^5.6.2",
+		"commander": "^14.0.3"
+	},
 	"devDependencies": {
 		"@types/bun": "latest",
 		"typescript": "^5.9.0",

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,
@@ -894,35 +895,37 @@ describe("isOverstoryHookEntry", () => {
 describe("getCapabilityGuards", () => {
 	// 10 native team tool blocks apply to ALL capabilities
 	const NATIVE_TEAM_TOOL_COUNT = 10;
+	// 3 interactive tool blocks (AskUserQuestion, EnterPlanMode, EnterWorktree) apply to ALL capabilities
+	const INTERACTIVE_TOOL_COUNT = 3;
 
-	test("returns 14 guards for scout (10 team + 3 tool blocks + 1 bash file guard)", () => {
+	test("returns 17 guards for scout (10 team + 3 interactive + 3 tool blocks + 1 bash file guard)", () => {
 		const guards = getCapabilityGuards("scout");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 4);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 4);
 	});
 
-	test("returns 14 guards for reviewer (10 team + 3 tool blocks + 1 bash file guard)", () => {
+	test("returns 17 guards for reviewer (10 team + 3 interactive + 3 tool blocks + 1 bash file guard)", () => {
 		const guards = getCapabilityGuards("reviewer");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 4);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 4);
 	});
 
-	test("returns 14 guards for lead (10 team + 3 tool blocks + 1 bash file guard)", () => {
+	test("returns 17 guards for lead (10 team + 3 interactive + 3 tool blocks + 1 bash file guard)", () => {
 		const guards = getCapabilityGuards("lead");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 4);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 4);
 	});
 
-	test("returns 11 guards for builder (10 team + 1 bash path boundary)", () => {
+	test("returns 14 guards for builder (10 team + 3 interactive + 1 bash path boundary)", () => {
 		const guards = getCapabilityGuards("builder");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 1);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 1);
 	});
 
-	test("returns 11 guards for merger (10 team + 1 bash path boundary)", () => {
+	test("returns 14 guards for merger (10 team + 3 interactive + 1 bash path boundary)", () => {
 		const guards = getCapabilityGuards("merger");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 1);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 1);
 	});
 
-	test("returns 10 guards for unknown capability (10 team tool blocks only)", () => {
+	test("returns 13 guards for unknown capability (10 team + 3 interactive tool blocks)", () => {
 		const guards = getCapabilityGuards("unknown");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT);
 	});
 
 	test("builder gets Bash path boundary guard", () => {
@@ -1039,14 +1042,90 @@ describe("getCapabilityGuards", () => {
 		expect(taskGuard?.hooks[0]?.command).toContain('[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0;');
 	});
 
-	test("coordinator gets 14 guards (10 team + 3 tool blocks + 1 bash file guard)", () => {
+	test("coordinator gets 17 guards (10 team + 3 interactive + 3 tool blocks + 1 bash file guard)", () => {
 		const guards = getCapabilityGuards("coordinator");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 4);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 4);
 	});
 
-	test("supervisor gets 14 guards (10 team + 3 tool blocks + 1 bash file guard)", () => {
+	test("supervisor gets 17 guards (10 team + 3 interactive + 3 tool blocks + 1 bash file guard)", () => {
 		const guards = getCapabilityGuards("supervisor");
-		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + 4);
+		expect(guards.length).toBe(NATIVE_TEAM_TOOL_COUNT + INTERACTIVE_TOOL_COUNT + 4);
+	});
+
+	test("all capabilities get AskUserQuestion blocked", () => {
+		for (const cap of [
+			"scout",
+			"reviewer",
+			"lead",
+			"coordinator",
+			"supervisor",
+			"builder",
+			"merger",
+			"unknown",
+		]) {
+			const guards = getCapabilityGuards(cap);
+			const guard = guards.find((g) => g.matcher === "AskUserQuestion");
+			expect(guard).toBeDefined();
+			expect(guard?.hooks[0]?.command).toContain("human interaction");
+			expect(guard?.hooks[0]?.command).toContain("overstory mail");
+		}
+	});
+
+	test("all capabilities get EnterPlanMode blocked", () => {
+		for (const cap of [
+			"scout",
+			"reviewer",
+			"lead",
+			"coordinator",
+			"supervisor",
+			"builder",
+			"merger",
+			"unknown",
+		]) {
+			const guards = getCapabilityGuards(cap);
+			const guard = guards.find((g) => g.matcher === "EnterPlanMode");
+			expect(guard).toBeDefined();
+			expect(guard?.hooks[0]?.command).toContain("human interaction");
+			expect(guard?.hooks[0]?.command).toContain("overstory mail");
+		}
+	});
+
+	test("all capabilities get EnterWorktree blocked", () => {
+		for (const cap of [
+			"scout",
+			"reviewer",
+			"lead",
+			"coordinator",
+			"supervisor",
+			"builder",
+			"merger",
+			"unknown",
+		]) {
+			const guards = getCapabilityGuards(cap);
+			const guard = guards.find((g) => g.matcher === "EnterWorktree");
+			expect(guard).toBeDefined();
+			expect(guard?.hooks[0]?.command).toContain("human interaction");
+			expect(guard?.hooks[0]?.command).toContain("overstory mail");
+		}
+	});
+
+	test("interactive guards include env var guard prefix", () => {
+		const guards = getCapabilityGuards("builder");
+		for (const tool of ["AskUserQuestion", "EnterPlanMode", "EnterWorktree"]) {
+			const guard = guards.find((g) => g.matcher === tool);
+			expect(guard).toBeDefined();
+			expect(guard?.hooks[0]?.command).toContain('[ -z "$OVERSTORY_AGENT_NAME" ] && exit 0;');
+		}
+	});
+
+	test("interactive guard block reason mentions tool name", () => {
+		const guards = getCapabilityGuards("scout");
+		const askGuard = guards.find((g) => g.matcher === "AskUserQuestion");
+		expect(askGuard?.hooks[0]?.command).toContain("AskUserQuestion");
+		const planGuard = guards.find((g) => g.matcher === "EnterPlanMode");
+		expect(planGuard?.hooks[0]?.command).toContain("EnterPlanMode");
+		const worktreeGuard = guards.find((g) => g.matcher === "EnterWorktree");
+		expect(worktreeGuard?.hooks[0]?.command).toContain("EnterWorktree");
 	});
 });
 
@@ -2038,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

@@ -46,6 +46,13 @@ const NATIVE_TEAM_TOOLS = [
 	"TaskStop",
 ];
 
+/**
+ * Tools that require human interaction and block indefinitely in non-interactive
+ * tmux sessions. Agents run non-interactively and must never call these tools.
+ * Use overstory mail (--type question) to escalate to the orchestrator instead.
+ */
+const INTERACTIVE_TOOLS = ["AskUserQuestion", "EnterPlanMode", "EnterWorktree"];
+
 /** Tools that non-implementation agents must not use. */
 const WRITE_TOOLS = ["Write", "Edit", "NotebookEdit"];
 
@@ -198,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.
  *
@@ -211,7 +232,7 @@ function blockGuard(toolName: string, reason: string): HookEntry {
 		hooks: [
 			{
 				type: "command",
-				command: `${ENV_GUARD} echo '${response}'`,
+				command: `${ENV_GUARD} echo '${escapeForSingleQuotedShell(response)}'`,
 			},
 		],
 	};
@@ -445,6 +466,17 @@ export function getCapabilityGuards(capability: string): HookEntry[] {
 	);
 	guards.push(...teamToolGuards);
 
+	// Block interactive tools for ALL overstory agents.
+	// These tools require a human to respond and block indefinitely in tmux sessions.
+	// Agents must use overstory mail (--type question) to escalate instead.
+	const interactiveGuards = INTERACTIVE_TOOLS.map((tool) =>
+		blockGuard(
+			tool,
+			`${tool} requires human interaction -- agents run non-interactively. Use overstory mail (--type question) to escalate`,
+		),
+	);
+	guards.push(...interactiveGuards);
+
 	if (NON_IMPLEMENTATION_CAPABILITIES.has(capability)) {
 		const toolGuards = WRITE_TOOLS.map((tool) =>
 			blockGuard(tool, `${capability} agents cannot modify files — ${tool} is not allowed`),

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(),
 		});