opencodekit 0.11.1 → 0.12.1

package/dist/template/.opencode/plugin/beads.ts

@@ -1,5 +1,10 @@
+import { createHash } from "crypto";
 import { type Plugin, tool } from "@opencode-ai/plugin";
 
+// =============================================================================
+// Types
+// =============================================================================
+
 interface TaskState {
 	currentTask: string | null;
 	reservedFiles: Set<string>;
@@ -9,63 +14,580 @@ interface TaskState {
 	agentId: string;
 }
 
+interface Task {
+	id: string;
+	title: string;
+	status?: string;
+	priority?: number;
+	type?: string;
+	tags?: string[];
+	description?: string;
+}
+
+interface LockData {
+	path: string;
+	agent: string;
+	reason?: string;
+	created: number;
+	expires: number;
+	task: string | null;
+}
+
+interface Message {
+	id: string;
+	from: string;
+	to: string;
+	subj: string;
+	body?: string;
+	importance: string;
+	thread?: string;
+	global?: boolean;
+	at: number;
+	read: boolean;
+}
+
+interface BdListResult {
+	tasks: Task[];
+	error?: string;
+}
+
+interface BdSingleResult {
+	task?: Task;
+	id?: string;
+	output?: string;
+	error?: string;
+}
+
+interface BdGenericResult {
+	output?: string;
+	error?: string;
+}
+
+// =============================================================================
+// Plugin
+// =============================================================================
+
 export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
+	// Generate deterministic agent ID from directory + process
+	const agentId = `agent-${createHash("md5")
+		.update(`${directory}-${process.pid}`)
+		.digest("hex")
+		.slice(0, 8)}`;
+
 	const state: TaskState = {
 		currentTask: null,
 		reservedFiles: new Set(),
 		team: "default",
 		role: "",
 		initialized: false,
-		agentId: `agent-${Date.now().toString(36)}`,
+		agentId,
 	};
 
-	async function bd(...args: string[]): Promise<any> {
+	const RESERVATIONS_DIR = ".reservations";
+
+	// =============================================================================
+	// Shell Helpers
+	// =============================================================================
+
+	// (Removed unused shell/shellQuiet helpers)
+
+	// =============================================================================
+	// Typed BD CLI Wrappers
+	// =============================================================================
+
+	async function bdList(
+		opts: {
+			status?: string;
+			sort?: string;
+			reverse?: boolean;
+			label?: string;
+			assignee?: string;
+			type?: string;
+			priorityMin?: number;
+			priorityMax?: number;
+			limit?: number;
+		} = {},
+	): Promise<{ tasks: Task[]; error?: string }> {
+		try {
+			const args = ["list", "--json"];
+			if (opts.status) args.push("--status", opts.status);
+			if (opts.sort) args.push("--sort", opts.sort);
+			if (opts.reverse) args.push("--reverse");
+			if (opts.label) args.push("--label", opts.label);
+			if (opts.assignee) args.push("--assignee", opts.assignee);
+			if (opts.type) args.push("--type", opts.type);
+			if (opts.priorityMin !== undefined)
+				args.push("--priority-min", String(opts.priorityMin));
+			if (opts.priorityMax !== undefined)
+				args.push("--priority-max", String(opts.priorityMax));
+			if (opts.limit) args.push("--limit", String(opts.limit));
+			const result = await $`bd ${args}`.cwd(directory).text();
+			const parsed = JSON.parse(result);
+			return { tasks: Array.isArray(parsed) ? parsed : [] };
+		} catch (e) {
+			return { tasks: [], error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdReady(
+		opts: {
+			sort?: string;
+			limit?: number;
+			assignee?: string;
+			label?: string;
+			unassigned?: boolean;
+		} = {},
+	): Promise<{ tasks: Task[]; error?: string }> {
+		try {
+			const args = ["ready", "--json"];
+			if (opts.sort) args.push("--sort", opts.sort);
+			if (opts.limit) args.push("--limit", String(opts.limit));
+			if (opts.assignee) args.push("--assignee", opts.assignee);
+			if (opts.label) args.push("--label", opts.label);
+			if (opts.unassigned) args.push("--unassigned");
+			const result = await $`bd ${args}`.cwd(directory).text();
+			const parsed = JSON.parse(result);
+			return { tasks: Array.isArray(parsed) ? parsed : [] };
+		} catch (e) {
+			return { tasks: [], error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdShow(id: string): Promise<{ task?: Task; error?: string }> {
+		try {
+			const result = await $`bd show ${id} --json`.cwd(directory).text();
+			return { task: JSON.parse(result) };
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdCreate(
+		title: string,
+		opts: {
+			priority?: number;
+			type?: string;
+			description?: string;
+			parent?: string;
+			tags?: string[];
+			deps?: string[];
+			assignee?: string;
+			estimate?: number; // minutes
+			acceptance?: string;
+		} = {},
+	): Promise<{ id?: string; error?: string }> {
+		try {
+			const args = ["create", title, "-p", String(opts.priority ?? 2)];
+			if (opts.type && opts.type !== "task") args.push("--type", opts.type);
+			if (opts.description) args.push("--description", opts.description);
+			if (opts.parent) args.push("--parent", opts.parent);
+			if (opts.tags?.length) args.push("--labels", opts.tags.join(","));
+			if (opts.deps?.length) args.push("--deps", opts.deps.join(","));
+			if (opts.assignee) args.push("--assignee", opts.assignee);
+			if (opts.estimate !== undefined)
+				args.push("--estimate", String(opts.estimate));
+			if (opts.acceptance) args.push("--acceptance", opts.acceptance);
+			args.push("--json");
+
+			const result = await $`bd ${args}`.cwd(directory).text();
+			// bd create may output warnings before JSON, extract JSON
+			const jsonMatch = result.match(/\{[\s\S]*\}/);
+			if (jsonMatch) {
+				const parsed = JSON.parse(jsonMatch[0]);
+				return { id: parsed.id };
+			}
+			return { id: result.trim() };
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdUpdate(
+		id: string,
+		opts: {
+			status?: string;
+			addLabel?: string;
+			removeLabel?: string;
+			setLabels?: string;
+			title?: string;
+			description?: string;
+			notes?: string;
+			priority?: number;
+			assignee?: string;
+			estimate?: string;
+			removeDep?: string;
+			addDep?: string;
+		},
+	): Promise<{ error?: string }> {
+		try {
+			const args = ["update", id];
+			if (opts.status) args.push("--status", opts.status);
+			if (opts.addLabel) args.push("--add-label", opts.addLabel);
+			if (opts.removeLabel) args.push("--remove-label", opts.removeLabel);
+			if (opts.setLabels) args.push("--set-labels", opts.setLabels);
+			if (opts.title) args.push("--title", opts.title);
+			if (opts.description) args.push("--description", opts.description);
+			if (opts.notes) args.push("--notes", opts.notes);
+			if (opts.priority !== undefined)
+				args.push("--priority", String(opts.priority));
+			if (opts.assignee) args.push("--assignee", opts.assignee);
+			if (opts.estimate) args.push("--estimate", opts.estimate);
+			if (opts.removeDep) args.push("--remove-dep", opts.removeDep);
+			if (opts.addDep) args.push("--add-dep", opts.addDep);
+			await $`bd ${args}`.cwd(directory).quiet();
+			return {};
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdClose(
+		id: string,
+		reason: string,
+	): Promise<{ error?: string }> {
+		try {
+			await $`bd close ${id} --reason ${reason}`.cwd(directory).quiet();
+			return {};
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdReopen(id: string): Promise<{ error?: string }> {
+		try {
+			await $`bd reopen ${id}`.cwd(directory).quiet();
+			return {};
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdSearch(
+		query: string,
+	): Promise<{ tasks: Task[]; error?: string }> {
+		try {
+			const result = await $`bd search ${query} --json`.cwd(directory).text();
+			const parsed = JSON.parse(result);
+			return { tasks: Array.isArray(parsed) ? parsed : [] };
+		} catch (e) {
+			return { tasks: [], error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdDepAdd(
+		child: string,
+		parent: string,
+		type = "blocks",
+	): Promise<{ error?: string }> {
+		try {
+			await $`bd dep add ${child} ${parent} --type ${type}`
+				.cwd(directory)
+				.quiet();
+			return {};
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdDepRemove(
+		child: string,
+		parent: string,
+	): Promise<{ error?: string }> {
+		try {
+			await $`bd dep remove ${child} ${parent}`.cwd(directory).quiet();
+			return {};
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdDepTree(
+		id: string,
+	): Promise<{ output?: string; error?: string }> {
 		try {
-			const result = await $`bd ${args}`.text();
+			const result = await $`bd dep tree ${id}`.cwd(directory).text();
+			return { output: result.trim() };
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdSync(): Promise<{ output?: string; error?: string }> {
+		try {
+			const result = await $`bd sync`.cwd(directory).text();
+			return { output: result.trim() };
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdDoctor(): Promise<{ output?: string; error?: string }> {
+		try {
+			const result = await $`bd doctor`.cwd(directory).text();
+			return { output: result.trim() };
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	async function bdCleanup(
+		days: number,
+	): Promise<{ output?: string; error?: string }> {
+		try {
+			const result = await $`bd cleanup --older-than ${days} --force`
+				.cwd(directory)
+				.text();
+			return { output: result.trim() };
+		} catch (e) {
+			return { error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	// =============================================================================
+	// File Locking (Atomic mkdir-based)
+	// =============================================================================
+
+	async function bdBlocked(): Promise<{ tasks: Task[]; error?: string }> {
+		try {
+			const result = await $`bd blocked --json`.cwd(directory).text();
+			const parsed = JSON.parse(result);
+			return { tasks: Array.isArray(parsed) ? parsed : [] };
+		} catch (e) {
+			return { tasks: [], error: e instanceof Error ? e.message : String(e) };
+		}
+	}
+
+	function lockDir(filePath: string): string {
+		const safe = filePath.replace(/[/\\]/g, "_").replace(/\.\./g, "_");
+		return `${RESERVATIONS_DIR}/${safe}.lock`;
+	}
+
+	async function acquireLock(
+		filePath: string,
+		reason?: string,
+		ttlSeconds = 600,
+	): Promise<{ acquired: boolean; holder?: string }> {
+		const lockPath = lockDir(filePath);
+		const now = Date.now();
+		const expires = now + ttlSeconds * 1000;
+
+		// Atomic: mkdir fails if dir exists
+		try {
+			await $`mkdir ${lockPath}`.cwd(directory);
+		} catch {
+			// Lock exists - check if expired
 			try {
-				return JSON.parse(result);
+				const metaPath = `${lockPath}/meta.json`;
+				const content = await $`cat ${metaPath}`.cwd(directory).text();
+				const lock: LockData = JSON.parse(content);
+
+				if (lock.expires < now) {
+					// Expired - remove and retry
+					await $`rm -rf ${lockPath}`.cwd(directory).quiet();
+					return acquireLock(filePath, reason, ttlSeconds);
+				}
+
+				if (lock.agent === state.agentId) {
+					// We already hold this lock - refresh it
+					lock.expires = expires;
+					await $`echo ${JSON.stringify(lock)} > ${metaPath}`
+						.cwd(directory)
+						.quiet();
+					return { acquired: true };
+				}
+
+				return { acquired: false, holder: lock.agent };
 			} catch {
-				return { output: result.trim() };
+				// Corrupted lock - remove and retry
+				await $`rm -rf ${lockPath}`.cwd(directory).quiet();
+				return acquireLock(filePath, reason, ttlSeconds);
 			}
-		} catch (e: any) {
-			return { error: e.message || String(e) };
 		}
-	}
 
-	function j(data: any): string {
-		return JSON.stringify(data, null, 0);
+		// Lock acquired - write metadata
+		const lockData: LockData = {
+			path: filePath,
+			agent: state.agentId,
+			reason,
+			created: now,
+			expires,
+			task: state.currentTask,
+		};
+
+		const metaPath = `${lockPath}/meta.json`;
+		await $`echo ${JSON.stringify(lockData)} > ${metaPath}`
+			.cwd(directory)
+			.quiet();
+		state.reservedFiles.add(filePath);
+		return { acquired: true };
 	}
 
-	function reservationPath(filePath: string): string {
-		const safe = filePath.replace(/[\/\\]/g, "_").replace(/\.\./g, "_");
-		return `.reservations/${safe}.lock`;
+	async function releaseLock(filePath: string): Promise<void> {
+		const lockPath = lockDir(filePath);
+		await $`rm -rf ${lockPath}`
+			.cwd(directory)
+			.quiet()
+			.catch(() => {});
+		state.reservedFiles.delete(filePath);
 	}
 
-	async function getAllReservations(): Promise<any[]> {
+	async function getAllLocks(): Promise<LockData[]> {
 		try {
-			const dir = ".reservations";
-			const result = await $`test -d ${dir} && ls -1 ${dir}`
-				.text()
-				.catch(() => "");
+			const result =
+				await $`find ${RESERVATIONS_DIR} -name "meta.json" -type f 2>/dev/null`
+					.cwd(directory)
+					.text()
+					.catch(() => "");
+
 			if (!result.trim()) return [];
 
-			const reservations: any[] = [];
-			for (const file of result.trim().split("\n")) {
-				if (!file.endsWith(".lock")) continue;
+			const locks: LockData[] = [];
+			const now = Date.now();
+
+			for (const metaPath of result.trim().split("\n")) {
 				try {
-					const content = await $`cat "${dir}/${file}"`.text();
-					const lock = JSON.parse(content);
-					if (lock.expires > Date.now()) {
-						reservations.push(lock);
+					const content = await $`cat ${metaPath}`.cwd(directory).text();
+					const lock: LockData = JSON.parse(content);
+					if (lock.expires > now) {
+						locks.push(lock);
 					}
-				} catch {}
+				} catch {
+					// Skip invalid
+				}
 			}
-			return reservations;
+			return locks;
 		} catch {
 			return [];
 		}
 	}
 
+	async function cleanupExpiredLocks(): Promise<number> {
+		let cleaned = 0;
+		try {
+			const result =
+				await $`find ${RESERVATIONS_DIR} -name "meta.json" -type f 2>/dev/null`
+					.cwd(directory)
+					.text()
+					.catch(() => "");
+
+			if (!result.trim()) return 0;
+
+			const now = Date.now();
+			for (const metaPath of result.trim().split("\n")) {
+				try {
+					const content = await $`cat ${metaPath}`.cwd(directory).text();
+					const lock: LockData = JSON.parse(content);
+					if (lock.expires < now) {
+						const lockDir = metaPath.replace("/meta.json", "");
+						await $`rm -rf ${lockDir}`.cwd(directory).quiet();
+						cleaned++;
+					}
+				} catch {
+					// Remove corrupted lock
+					const lockDir = metaPath.replace("/meta.json", "");
+					await $`rm -rf ${lockDir}`.cwd(directory).quiet();
+					cleaned++;
+				}
+			}
+		} catch {
+			// Ignore
+		}
+		return cleaned;
+	}
+
+	// =============================================================================
+	// Message Helpers
+	// =============================================================================
+
+	async function ensureReservationsDir(): Promise<void> {
+		await $`mkdir -p ${RESERVATIONS_DIR}`.cwd(directory).quiet();
+	}
+
+	async function appendMessage(msg: Message): Promise<void> {
+		await ensureReservationsDir();
+		await $`echo ${JSON.stringify(msg)} >> ${RESERVATIONS_DIR}/messages.jsonl`
+			.cwd(directory)
+			.quiet();
+	}
+
+	async function readMessages(
+		limit: number,
+		unreadOnly: boolean,
+	): Promise<Message[]> {
+		try {
+			const content =
+				await $`cat ${RESERVATIONS_DIR}/messages.jsonl 2>/dev/null`
+					.cwd(directory)
+					.text();
+
+			if (!content.trim()) return [];
+
+			let msgs: Message[] = content
+				.trim()
+				.split("\n")
+				.map((line) => {
+					try {
+						return JSON.parse(line) as Message;
+					} catch {
+						return null;
+					}
+				})
+				.filter((m): m is Message => m !== null)
+				.filter((m) => m.to === "all" || m.to === state.agentId);
+
+			if (unreadOnly) msgs = msgs.filter((m) => !m.read);
+			return msgs.slice(-limit).reverse();
+		} catch {
+			return [];
+		}
+	}
+
+	async function cleanupOldMessages(maxAgeDays: number): Promise<number> {
+		try {
+			const content =
+				await $`cat ${RESERVATIONS_DIR}/messages.jsonl 2>/dev/null`
+					.cwd(directory)
+					.text();
+
+			if (!content.trim()) return 0;
+
+			const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+			const msgs = content
+				.trim()
+				.split("\n")
+				.map((line) => {
+					try {
+						return JSON.parse(line) as Message;
+					} catch {
+						return null;
+					}
+				})
+				.filter((m): m is Message => m !== null && m.at > cutoff);
+
+			const originalCount = content.trim().split("\n").length;
+			const newContent = msgs.map((m) => JSON.stringify(m)).join("\n");
+			await $`echo ${newContent} > ${RESERVATIONS_DIR}/messages.jsonl`
+				.cwd(directory)
+				.quiet();
+
+			return originalCount - msgs.length;
+		} catch {
+			return 0;
+		}
+	}
+
+	// =============================================================================
+	// JSON Response Helper
+	// =============================================================================
+
+	function json(data: Record<string, unknown>): string {
+		return JSON.stringify(data, null, 0);
+	}
+
+	// =============================================================================
+	// Tools
+	// =============================================================================
+
 	return {
 		tool: {
 			bd_init: tool({
@@ -78,8 +600,11 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.describe("Role: fe|be|mobile|devops|qa"),
 				},
 				async execute(args) {
-					await $`bd init`.quiet().catch(() => {});
-					await $`mkdir -p .reservations`.quiet();
+					await $`bd init`
+						.cwd(directory)
+						.quiet()
+						.catch(() => {});
+					await ensureReservationsDir();
 
 					state.team = args.team || "default";
 					state.role = args.role || "";
@@ -87,12 +612,16 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 					state.currentTask = null;
 					state.reservedFiles.clear();
 
-					return j({
+					// Cleanup expired locks on init
+					const cleaned = await cleanupExpiredLocks();
+
+					return json({
 						ok: 1,
 						agent: state.agentId,
 						ws: directory,
 						team: state.team,
 						role: state.role || undefined,
+						cleaned_locks: cleaned || undefined,
 					});
 				},
 			}),
@@ -101,27 +630,28 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				description: "Claim next ready task. Auto-syncs, marks in_progress.",
 				args: {},
 				async execute() {
-					if (!state.initialized) return j({ error: "Call bd_init() first" });
+					if (!state.initialized)
+						return json({ error: "Call bd_init() first" });
 
-					await $`bd sync`.quiet().catch(() => {});
-					const ready = await bd("ready", "--json");
-					if (ready.error) return j({ error: ready.error });
-
-					const tasks = Array.isArray(ready) ? ready : [];
-					if (!tasks.length) return j({ msg: "no ready tasks" });
+					await bdSync();
+					const { tasks, error } = await bdReady();
+					if (error) return json({ error });
+					if (!tasks.length) return json({ msg: "no ready tasks" });
 
 					let task = tasks[0];
 					if (state.role) {
-						const roleTask = tasks.find((t: any) =>
-							t.tags?.includes(state.role),
-						);
+						const roleTask = tasks.find((t) => t.tags?.includes(state.role));
 						if (roleTask) task = roleTask;
 					}
 
-					await $`bd update ${task.id} --status in_progress`.quiet();
+					const updateResult = await bdUpdate(task.id, {
+						status: "in_progress",
+					});
+					if (updateResult.error) return json({ error: updateResult.error });
+
 					state.currentTask = task.id;
 
-					return j({
+					return json({
 						id: task.id,
 						t: task.title,
 						p: task.priority,
@@ -142,19 +672,20 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				},
 				async execute(args) {
 					const taskId = args.id || state.currentTask;
-					if (!taskId) return j({ error: "No task ID" });
+					if (!taskId) return json({ error: "No task ID" });
 
-					await bd("close", taskId, "--reason", args.msg);
+					const closeResult = await bdClose(taskId, args.msg);
+					if (closeResult.error) return json({ error: closeResult.error });
 
+					// Release all locks
 					for (const path of state.reservedFiles) {
-						await $`rm -f ${reservationPath(path)}`.quiet().catch(() => {});
+						await releaseLock(path);
 					}
-					state.reservedFiles.clear();
 
-					await $`bd sync`.quiet().catch(() => {});
+					await bdSync();
 					state.currentTask = null;
 
-					return j({ ok: 1, closed: taskId, hint: "Restart session" });
+					return json({ ok: 1, closed: taskId, hint: "Restart session" });
 				},
 			}),
 
@@ -183,22 +714,35 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.array(tool.schema.string())
 						.optional()
 						.describe("Dependencies (type:id format)"),
+					assignee: tool.schema.string().optional().describe("Assignee name"),
+					estimate: tool.schema
+						.number()
+						.optional()
+						.describe("Time estimate in minutes (e.g. 60 for 1h)"),
+					acceptance: tool.schema
+						.string()
+						.optional()
+						.describe("Acceptance criteria"),
 				},
 				async execute(args) {
-					if (!args.title) return j({ error: "title required" });
-
-					const cmdArgs = ["create", args.title, "-p", String(args.pri || 2)];
-					if (args.type && args.type !== "task")
-						cmdArgs.push("--type", args.type);
-					if (args.desc) cmdArgs.push("--description", args.desc);
-					if (args.parent) cmdArgs.push("--parent", args.parent);
-					if (args.tags?.length) cmdArgs.push("--tags", args.tags.join(","));
-					if (args.deps?.length) cmdArgs.push("--deps", args.deps.join(","));
-					cmdArgs.push("--json");
-
-					const result = await bd(...cmdArgs);
-					return j({
-						id: result.id || result.output,
+					if (!args.title) return json({ error: "title required" });
+
+					const result = await bdCreate(args.title, {
+						priority: args.pri,
+						type: args.type,
+						description: args.desc,
+						parent: args.parent,
+						tags: args.tags,
+						deps: args.deps,
+						assignee: args.assignee,
+						estimate: args.estimate,
+						acceptance: args.acceptance,
+					});
+
+					if (result.error) return json({ error: result.error });
+
+					return json({
+						id: result.id,
 						t: args.title,
 						p: args.pri || 2,
 					});
@@ -218,21 +762,24 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				},
 				async execute(args) {
 					if (!args.id || !args.role)
-						return j({ error: "id and role required" });
+						return json({ error: "id and role required" });
 
-					await bd("update", args.id, "--tags", args.role);
+					const result = await bdUpdate(args.id, { addLabel: args.role });
+					if (result.error) return json({ error: result.error });
 
 					if (args.notify !== false) {
-						const notif = {
-							type: "assign",
-							task: args.id,
-							role: args.role,
+						await appendMessage({
+							id: `notify-${Date.now().toString(36)}`,
+							from: state.agentId,
+							to: "all",
+							subj: `Task ${args.id} assigned to ${args.role}`,
+							importance: "normal",
 							at: Date.now(),
-						};
-						await $`echo ${JSON.stringify(notif)} >> .reservations/notifications.jsonl`.quiet();
+							read: false,
+						});
 					}
 
-					return j({ ok: 1, id: args.id, role: args.role });
+					return json({ ok: 1, id: args.id, role: args.role });
 				},
 			}),
 
@@ -242,25 +789,61 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 					status: tool.schema.string().default("open"),
 					limit: tool.schema.number().default(10),
 					offset: tool.schema.number().default(0),
+					sort: tool.schema
+						.string()
+						.optional()
+						.describe("Sort by: priority|created|updated|title"),
+					reverse: tool.schema
+						.boolean()
+						.optional()
+						.describe("Reverse sort order"),
+					label: tool.schema.string().optional().describe("Filter by label"),
+					assignee: tool.schema
+						.string()
+						.optional()
+						.describe("Filter by assignee"),
+					type: tool.schema
+						.string()
+						.optional()
+						.describe("Filter by type: task|bug|feature|epic"),
+					priorityMin: tool.schema
+						.number()
+						.optional()
+						.describe("Min priority (0-4)"),
+					priorityMax: tool.schema
+						.number()
+						.optional()
+						.describe("Max priority (0-4)"),
 				},
 				async execute(args) {
 					const status = args.status || "open";
 					const limit = Math.min(args.limit || 10, 50);
+					const offset = args.offset || 0;
 
-					let result: any;
-					if (status === "ready") {
-						result = await bd("ready", "--json");
-					} else if (status === "all") {
-						result = await bd("list", "--json");
-					} else {
-						result = await bd("list", "--status", status, "--json");
-					}
+					const opts = {
+						status: status === "all" ? undefined : status,
+						sort: args.sort,
+						reverse: args.reverse,
+						label: args.label,
+						assignee: args.assignee,
+						type: args.type,
+						priorityMin: args.priorityMin,
+						priorityMax: args.priorityMax,
+					};
 
-					if (result.error) return j({ error: result.error });
+					const result =
+						status === "ready"
+							? await bdReady({
+									sort: args.sort,
+									limit,
+									assignee: args.assignee,
+									label: args.label,
+								})
+							: await bdList(opts);
 
-					const tasks = Array.isArray(result) ? result : [];
-					const offset = args.offset || 0;
-					const items = tasks.slice(offset, offset + limit).map((t: any) => ({
+					if (result.error) return json({ error: result.error });
+
+					const items = result.tasks.slice(offset, offset + limit).map((t) => ({
 						id: t.id,
 						t: t.title,
 						p: t.priority,
@@ -268,7 +851,11 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						tags: t.tags?.length ? t.tags : undefined,
 					}));
 
-					return j({ items, count: items.length, total: tasks.length });
+					return json({
+						items,
+						count: items.length,
+						total: result.tasks.length,
+					});
 				},
 			}),
 
@@ -276,9 +863,10 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				description: "Get full issue details.",
 				args: { id: tool.schema.string().describe("Issue ID") },
 				async execute(args) {
-					if (!args.id) return j({ error: "id required" });
-					const result = await bd("show", args.id, "--json");
-					return j(result);
+					if (!args.id) return json({ error: "id required" });
+					const result = await bdShow(args.id);
+					if (result.error) return json({ error: result.error });
+					return json(result.task as unknown as Record<string, unknown>);
 				},
 			}),
 
@@ -295,46 +883,25 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.describe("Seconds until expiry"),
 				},
 				async execute(args) {
-					if (!args.paths?.length) return j({ error: "paths required" });
+					if (!args.paths?.length) return json({ error: "paths required" });
 
-					await $`mkdir -p .reservations`.quiet();
+					await ensureReservationsDir();
 
 					const granted: string[] = [];
 					const conflicts: { path: string; holder?: string }[] = [];
-					const now = Date.now();
-					const expires = now + (args.ttl || 600) * 1000;
 
 					for (const path of args.paths) {
-						const lockFile = reservationPath(path);
-
-						try {
-							const content = await $`cat ${lockFile} 2>/dev/null`.text();
-							if (content) {
-								const lock = JSON.parse(content);
-								if (lock.expires > now && lock.agent !== state.agentId) {
-									conflicts.push({ path, holder: lock.agent });
-									continue;
-								}
-							}
-						} catch {}
-
-						const lockData = JSON.stringify({
-							path,
-							agent: state.agentId,
-							reason: args.reason,
-							created: now,
-							expires,
-							task: state.currentTask,
-						});
-
-						await $`echo ${lockData} > ${lockFile}`.quiet();
-						granted.push(path);
-						state.reservedFiles.add(path);
+						const result = await acquireLock(path, args.reason, args.ttl);
+						if (result.acquired) {
+							granted.push(path);
+						} else {
+							conflicts.push({ path, holder: result.holder });
+						}
 					}
 
-					const result: any = { granted };
-					if (conflicts.length) result.conflicts = conflicts;
-					return j(result);
+					const response: Record<string, unknown> = { granted };
+					if (conflicts.length) response.conflicts = conflicts;
+					return json(response);
 				},
 			}),
 
@@ -352,11 +919,10 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						: [...state.reservedFiles];
 
 					for (const path of toRelease) {
-						await $`rm -f ${reservationPath(path)}`.quiet().catch(() => {});
-						state.reservedFiles.delete(path);
+						await releaseLock(path);
 					}
 
-					return j({ released: toRelease });
+					return json({ released: toRelease });
 				},
 			}),
 
@@ -364,15 +930,15 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				description: "List active file locks. Check before editing.",
 				args: {},
 				async execute() {
-					const reservations = await getAllReservations();
-					return j({
-						locks: reservations.map((r) => ({
+					const locks = await getAllLocks();
+					return json({
+						locks: locks.map((r) => ({
 							path: r.path,
 							agent: r.agent,
 							expires: new Date(r.expires).toISOString(),
 							task: r.task,
 						})),
-						count: reservations.length,
+						count: locks.length,
 					});
 				},
 			}),
@@ -398,9 +964,9 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.describe("Send to all workspaces"),
 				},
 				async execute(args) {
-					if (!args.subj) return j({ error: "subj required" });
+					if (!args.subj) return json({ error: "subj required" });
 
-					const msg = {
+					const msg: Message = {
 						id: `msg-${Date.now().toString(36)}`,
 						from: state.agentId,
 						to: args.to || "all",
@@ -413,10 +979,8 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						read: false,
 					};
 
-					await $`mkdir -p .reservations`.quiet();
-					await $`echo ${JSON.stringify(msg)} >> .reservations/messages.jsonl`.quiet();
-
-					return j({ ok: 1, id: msg.id });
+					await appendMessage(msg);
+					return json({ ok: 1, id: msg.id });
 				},
 			}),
 
@@ -431,31 +995,8 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.describe("Include cross-workspace"),
 				},
 				async execute(args) {
-					try {
-						const content =
-							await $`cat .reservations/messages.jsonl 2>/dev/null`.text();
-						if (!content.trim()) return j({ msgs: [], count: 0 });
-
-						let msgs = content
-							.trim()
-							.split("\n")
-							.map((line) => {
-								try {
-									return JSON.parse(line);
-								} catch {
-									return null;
-								}
-							})
-							.filter((m) => m !== null)
-							.filter((m) => m.to === "all" || m.to === state.agentId);
-
-						if (args.unread) msgs = msgs.filter((m) => !m.read);
-						msgs = msgs.slice(-(args.n || 5)).reverse();
-
-						return j({ msgs, count: msgs.length });
-					} catch {
-						return j({ msgs: [], count: 0 });
-					}
+					const msgs = await readMessages(args.n || 5, args.unread || false);
+					return json({ msgs, count: msgs.length });
 				},
 			}),
 
@@ -468,19 +1009,19 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.describe("Include agent info"),
 				},
 				async execute(args) {
-					const [ready, inProgress, reservations] = await Promise.all([
-						bd("ready", "--json"),
-						bd("list", "--status", "in_progress", "--json"),
-						getAllReservations(),
+					const [ready, inProgress, locks] = await Promise.all([
+						bdReady(),
+						bdList({ status: "in_progress" }),
+						getAllLocks(),
 					]);
 
-					const result: any = {
+					const result: Record<string, unknown> = {
 						ws: directory,
 						team: state.team,
 						current_task: state.currentTask,
-						ready: Array.isArray(ready) ? ready.length : 0,
-						in_progress: Array.isArray(inProgress) ? inProgress.length : 0,
-						locks: reservations.length,
+						ready: ready.tasks.length,
+						in_progress: inProgress.tasks.length,
+						locks: locks.length,
 					};
 
 					if (args.include_agents) {
@@ -491,7 +1032,7 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						};
 					}
 
-					return j(result);
+					return json(result);
 				},
 			}),
 
@@ -499,8 +1040,8 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				description: "Sync with git. Pull/push changes.",
 				args: {},
 				async execute() {
-					const result = await bd("sync");
-					return j({ ok: 1, output: result.output });
+					const result = await bdSync();
+					return json({ ok: 1, output: result.output });
 				},
 			}),
 
@@ -513,12 +1054,8 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 						.describe("Delete closed >N days"),
 				},
 				async execute(args) {
-					const result = await bd(
-						"cleanup",
-						"--older-than",
-						`${args.days || 2}d`,
-					);
-					return j({ ok: 1, output: result.output });
+					const result = await bdCleanup(args.days || 2);
+					return json({ ok: 1, output: result.output });
 				},
 			}),
 
@@ -526,141 +1063,191 @@ export const BeadsCorePlugin: Plugin = async ({ $, directory }) => {
 				description: "Check/repair database health.",
 				args: {},
 				async execute() {
-					const result = await bd("doctor", "--fix");
-					return j({ ok: 1, output: result.output });
+					const result = await bdDoctor();
+					return json({ ok: 1, output: result.output });
 				},
 			}),
 
-			bd_insights: tool({
-				description:
-					"Graph analysis: bottlenecks, keystones, cycles, PageRank.",
+			bd_dep: tool({
+				description: "Manage dependencies. action: add|remove|tree",
+				args: {
+					action: tool.schema.string().describe("add|remove|tree"),
+					child: tool.schema.string().describe("Child issue ID"),
+					parent: tool.schema
+						.string()
+						.optional()
+						.describe("Parent issue ID (for add/remove)"),
+					type: tool.schema
+						.string()
+						.default("blocks")
+						.describe("Dependency type: blocks|related|parent"),
+				},
+				async execute(args) {
+					if (!args.action || !args.child)
+						return json({ error: "action and child required" });
+
+					if (args.action === "tree") {
+						const result = await bdDepTree(args.child);
+						if (result.error) return json({ error: result.error });
+						return json({ tree: result.output });
+					}
+
+					if (!args.parent)
+						return json({ error: "parent required for add/remove" });
+
+					if (args.action === "add") {
+						const result = await bdDepAdd(args.child, args.parent, args.type);
+						if (result.error) return json({ error: result.error });
+						return json({
+							ok: 1,
+							child: args.child,
+							parent: args.parent,
+							type: args.type,
+						});
+					}
+
+					if (args.action === "remove") {
+						const result = await bdDepRemove(args.child, args.parent);
+						if (result.error) return json({ error: result.error });
+						return json({
+							ok: 1,
+							removed: { child: args.child, parent: args.parent },
+						});
+					}
+
+					return json({ error: "action must be add|remove|tree" });
+				},
+			}),
+
+			bd_blocked: tool({
+				description: "Show blocked issues (have unresolved dependencies).",
 				args: {},
 				async execute() {
-					const result = await bd("stats", "--json");
-					if (result.error) return j({ error: result.error });
-
-					const tasks = await bd("list", "--json");
-					const taskList = Array.isArray(tasks) ? tasks : [];
-
-					const blocked = taskList.filter((t: any) => t.status === "blocked");
-					const highPri = taskList.filter(
-						(t: any) => t.priority <= 1 && t.status === "open",
-					);
-
-					return j({
-						total: taskList.length,
-						blocked: blocked.length,
-						high_priority: highPri.length,
-						bottlenecks: blocked.map((t: any) => ({ id: t.id, t: t.title })),
-						keystones: highPri.map((t: any) => ({
+					const { tasks, error } = await bdBlocked();
+					if (error) return json({ error });
+
+					return json({
+						items: tasks.map((t) => ({
 							id: t.id,
 							t: t.title,
 							p: t.priority,
 						})),
+						count: tasks.length,
 					});
 				},
 			}),
 
-			bd_plan: tool({
-				description: "Parallel execution plan with tracks.",
-				args: {},
-				async execute() {
-					const ready = await bd("ready", "--json");
-					const tasks = Array.isArray(ready) ? ready : [];
-
-					const tracks: Record<number, any[]> = {};
-					for (const task of tasks) {
-						const p = task.priority || 2;
-						if (!tracks[p]) tracks[p] = [];
-						tracks[p].push({ id: task.id, t: task.title });
-					}
+			bd_reopen: tool({
+				description: "Reopen a closed issue.",
+				args: {
+					id: tool.schema.string().describe("Issue ID to reopen"),
+				},
+				async execute(args) {
+					if (!args.id) return json({ error: "id required" });
 
-					return j({
-						tracks: Object.entries(tracks).map(([pri, items]) => ({
-							priority: Number(pri),
-							parallel: items,
-						})),
-						total_ready: tasks.length,
-					});
+					const result = await bdReopen(args.id);
+					if (result.error) return json({ error: result.error });
+
+					return json({ ok: 1, reopened: args.id });
 				},
 			}),
 
-			bd_priority: tool({
-				description: "Priority recommendations based on graph analysis.",
+			bd_update: tool({
+				description:
+					"Update issue properties (title, status, priority, assignee, dependencies).",
 				args: {
-					limit: tool.schema
+					id: tool.schema.string().describe("Issue ID to update"),
+					title: tool.schema.string().optional().describe("New title"),
+					status: tool.schema.string().optional().describe("New status"),
+					priority: tool.schema
 						.number()
-						.default(5)
-						.describe("Max issues to return"),
+						.optional()
+						.describe("New priority (0-4)"),
+					assignee: tool.schema
+						.string()
+						.optional()
+						.describe("Assign to user/role"),
+					removeDep: tool.schema
+						.string()
+						.optional()
+						.describe("Remove dependency"),
+					addDep: tool.schema.string().optional().describe("Add dependency"),
 				},
 				async execute(args) {
-					const ready = await bd("ready", "--json");
-					const tasks = Array.isArray(ready) ? ready : [];
+					if (!args.id) return json({ error: "id required" });
+
+					const result = await bdUpdate(args.id, {
+						title: args.title,
+						status: args.status,
+						priority: args.priority,
+						assignee: args.assignee,
+						removeDep: args.removeDep,
+						addDep: args.addDep,
+					});
+					if (result.error) return json({ error: result.error });
+
+					return json({ ok: 1, updated: args.id });
+				},
+			}),
 
-					const sorted = tasks
-						.sort((a: any, b: any) => (a.priority || 2) - (b.priority || 2))
-						.slice(0, args.limit || 5);
+			bd_ready: tool({
+				description: "List ready-to-work tasks (no unresolved dependencies).",
+				args: {
+					sort: tool.schema.string().optional().describe("Sort field"),
+					limit: tool.schema.number().optional().describe("Max results"),
+					assignee: tool.schema
+						.string()
+						.optional()
+						.describe("Filter by assignee"),
+					label: tool.schema.string().optional().describe("Filter by label"),
+				},
+				async execute(args) {
+					const result = await bdReady({
+						sort: args.sort,
+						limit: args.limit,
+						assignee: args.assignee,
+						label: args.label,
+					});
+					if (result.error) return json({ error: result.error });
 
-					return j({
-						recommended: sorted.map((t: any) => ({
+					return json({
+						items: result.tasks.map((t: Task) => ({
 							id: t.id,
-							t: t.title,
-							p: t.priority,
-							reason:
-								t.priority === 0
-									? "critical"
-									: t.priority === 1
-										? "high priority"
-										: "ready",
+							title: t.title,
+							priority: t.priority,
 						})),
+						count: result.tasks.length,
 					});
 				},
 			}),
 
-			bd_diff: tool({
-				description: "Compare issue changes between git revisions.",
+			bd_search: tool({
+				description: "Search issues by text query.",
 				args: {
-					since: tool.schema
-						.string()
-						.optional()
-						.describe("Start revision (commit, tag, date)"),
-					as_of: tool.schema
-						.string()
-						.optional()
-						.describe("End revision (default: current)"),
+					query: tool.schema.string().describe("Search text"),
 				},
 				async execute(args) {
-					const sinceArg = args.since || "HEAD~10";
-					const asOfArg = args.as_of || "HEAD";
+					if (!args.query) return json({ error: "query required" });
 
-					try {
-						const diff =
-							await $`git diff ${sinceArg}..${asOfArg} -- .beads/`.text();
-						const lines = diff.split("\n");
-
-						const added = lines.filter(
-							(l) => l.startsWith("+") && !l.startsWith("+++"),
-						).length;
-						const removed = lines.filter(
-							(l) => l.startsWith("-") && !l.startsWith("---"),
-						).length;
-
-						return j({
-							since: sinceArg,
-							as_of: asOfArg,
-							changes: { added, removed },
-							summary: diff.length > 500 ? diff.slice(0, 500) + "..." : diff,
-						});
-					} catch (e: any) {
-						return j({ error: e.message });
-					}
+					const { tasks, error } = await bdSearch(args.query);
+					if (error) return json({ error });
+
+					return json({
+						items: tasks.map((t) => ({
+							id: t.id,
+							t: t.title,
+							p: t.priority,
+							s: t.status,
+						})),
+						count: tasks.length,
+					});
 				},
 			}),
 		},
 
 		event: async ({ event }) => {
 			if (event.type === "session.idle" && state.currentTask) {
-				await $`bd sync`.quiet().catch(() => {});
+				await bdSync();
 			}
 		},
 	};