macro-agent 0.1.1 → 0.1.2

package/src/map/adapter/index.ts

@@ -155,4 +155,9 @@ export {
   registerResumeExtension,
   unregisterResumeExtension,
   type ResumeExtensionServices,
+  // Stream/checkpoint/diffStack/mergeQueue
+  registerStreamExtensions,
+  unregisterStreamExtensions,
+  STREAM_EXTENSION_METHODS,
+  type StreamExtensionServices,
 } from "./extensions/index.js";

package/src/map/adapter/types.ts

@@ -168,7 +168,14 @@ export type MAPEventType =
   | "task.created"
   | "task.assigned"
   | "task.completed"
-  | "task.failed";
+  | "task.failed"
+  // Stream/checkpoint/merge events (git-cascade)
+  | "stream.updated"
+  | "checkpoint.created"
+  | "diffstack.created"
+  | "diffstack.updated"
+  | "merge_request.created"
+  | "merge_request.updated";
 
 /**
  * Filter for event subscriptions.

package/src/mcp/mcp-server.ts

@@ -103,6 +103,8 @@ export interface MCPServices {
   integrationStrategy?: import("../workspace/strategies/types.js").IntegrationStrategy;
   /** Optional task backend for pull model tools (claim/unclaim) */
   taskBackend?: import("../task/backend/types.js").TaskBackend;
+  /** Optional workspace manager for workspace isolation */
+  workspaceManager?: import("../workspace/types.js").WorkspaceManager;
 }
 
 // ─────────────────────────────────────────────────────────────────
@@ -1046,6 +1048,7 @@ export function createMCPServer(
         roleRegistry,
         integrationStrategy: services.integrationStrategy,
         taskMode: services.taskMode,
+        workspaceManager: services.workspaceManager,
       });
 
       try {
@@ -1056,6 +1059,14 @@ export function createMCPServer(
           task_id?: string;
         });
 
+        // Persist events emitted by the done handler (MERGE_REQUEST, WORKER_DONE, etc.)
+        // so the main process polling can see them via EventStore reload.
+        try {
+          await eventStore.persist();
+        } catch {
+          // Best-effort — events may still be picked up on next reload
+        }
+
         // If shouldTerminate is true, schedule termination after this tool returns
         // The agent will be terminated after the tool execution completes
         if (result.shouldTerminate) {
@@ -1091,7 +1102,7 @@ export function createMCPServer(
   // Tools: claim_task, unclaim_task, list_claimable_tasks (pull model)
   // ─────────────────────────────────────────────────────────────────
 
-  if (services.taskBackend && shouldRegisterTool("claim_task")) {
+  if (services.taskBackend && services.taskMode === "pull" && shouldRegisterTool("claim_task")) {
     server.registerTool(CLAIM_TASK_TOOL_INFO.name, {
       description: CLAIM_TASK_TOOL_INFO.description,
       inputSchema: ClaimTaskSchema,
@@ -1104,7 +1115,7 @@ export function createMCPServer(
     });
   }
 
-  if (services.taskBackend && shouldRegisterTool("unclaim_task")) {
+  if (services.taskBackend && services.taskMode === "pull" && shouldRegisterTool("unclaim_task")) {
     server.registerTool(UNCLAIM_TASK_TOOL_INFO.name, {
       description: UNCLAIM_TASK_TOOL_INFO.description,
       inputSchema: UnclaimTaskSchema,
@@ -1117,7 +1128,7 @@ export function createMCPServer(
     });
   }
 
-  if (services.taskBackend && shouldRegisterTool("list_claimable_tasks")) {
+  if (services.taskBackend && services.taskMode === "pull" && shouldRegisterTool("list_claimable_tasks")) {
     server.registerTool(LIST_CLAIMABLE_TASKS_TOOL_INFO.name, {
       description: LIST_CLAIMABLE_TASKS_TOOL_INFO.description,
       inputSchema: ListClaimableTasksSchema,

package/src/mcp/tools/done.ts

@@ -147,6 +147,13 @@ export function buildLifecycleContext(
     streamId = workspace?.streamId;
   }
 
+  // Fallback: read streamId from env var (set by buildMacroAgentMcp during spawn).
+  // WorkspaceManager is not available in MCP subprocesses, but the streamId is
+  // needed for MERGE_REQUEST signal details so the team runtime can submit to the merge queue.
+  if (!streamId && process.env.MACRO_STREAM_ID) {
+    streamId = process.env.MACRO_STREAM_ID;
+  }
+
   return {
     agentId: toolContext.agent_id,
     role,
@@ -206,6 +213,18 @@ export function createDoneHandler(context: ToolContext, deps: DoneToolDeps) {
       workspaceManager
     );
 
+    // Resolve capabilities for capability-based handler dispatch (team roles)
+    if (roleRegistry) {
+      try {
+        const resolvedRole = roleRegistry.resolveRole(role);
+        if (resolvedRole?.capabilities) {
+          lifecycleContext.capabilities = [...resolvedRole.capabilities];
+        }
+      } catch {
+        // Role not in registry — capabilities stay undefined
+      }
+    }
+
     const cleanupStatus = detectCleanupStatus(lifecycleContext, {
       messageRouter,
     });

package/src/roles/builtin/coordinator.ts

@@ -11,6 +11,7 @@ import {
   TASK_CAPABILITIES,
   AGENT_CAPABILITIES,
   MSG_CAPABILITIES,
+  WORKSPACE_CAPABILITIES,
 } from "../capabilities.js";
 
 /**
@@ -42,6 +43,7 @@ export const CoordinatorRole: RoleDefinition = {
     MSG_CAPABILITIES.SEND,
     MSG_CAPABILITIES.BROADCAST,
     MSG_CAPABILITIES.SUBSCRIBE,
+    WORKSPACE_CAPABILITIES.STREAM,
     // Note: lifecycle.done is optional, configured per-coordinator
   ],
 

package/src/roles/builtin/integrator.ts

@@ -12,6 +12,7 @@ import {
   AGENT_CAPABILITIES,
   LIFECYCLE_CAPABILITIES,
   MSG_CAPABILITIES,
+  WORKSPACE_CAPABILITIES,
 } from "../capabilities.js";
 
 /**
@@ -39,6 +40,7 @@ export const IntegratorRole: RoleDefinition = {
     LIFECYCLE_CAPABILITIES.DONE,
     MSG_CAPABILITIES.SEND,
     MSG_CAPABILITIES.SUBSCRIBE,
+    WORKSPACE_CAPABILITIES.INTEGRATE,
   ],
 
   workspace: {

package/src/roles/builtin/worker.ts

@@ -13,6 +13,7 @@ import {
   LIFECYCLE_CAPABILITIES,
   AGENT_CAPABILITIES,
   MSG_CAPABILITIES,
+  WORKSPACE_CAPABILITIES,
 } from "../capabilities.js";
 
 /** 30 minutes in milliseconds (stale timeout) */
@@ -45,6 +46,7 @@ export const WorkerRole: RoleDefinition = {
     LIFECYCLE_CAPABILITIES.DONE,
     AGENT_CAPABILITIES.SPAWN_WORKER,
     MSG_CAPABILITIES.SEND,
+    WORKSPACE_CAPABILITIES.WORKTREE,
   ],
 
   workspace: {
@@ -100,6 +102,7 @@ export const ResolverWorkerRole: RoleDefinition = {
     LIFECYCLE_CAPABILITIES.DONE,
     AGENT_CAPABILITIES.SPAWN_WORKER,
     MSG_CAPABILITIES.SEND,
+    WORKSPACE_CAPABILITIES.WORKTREE,
   ],
 
   // Inherits workspace from worker

package/src/roles/capabilities.ts

@@ -66,6 +66,13 @@ export const MSG_CAPABILITIES = {
   SUBSCRIBE: "msg.subscribe" as const,
 };
 
+/** Workspace capabilities */
+export const WORKSPACE_CAPABILITIES = {
+  WORKTREE: "workspace.worktree" as const,    // Gets own git worktree; done() submits to merge queue
+  STREAM: "workspace.stream" as const,         // Creates integration stream at spawn
+  INTEGRATE: "workspace.integrate" as const,   // Joins stream; processes merge queue entries
+};
+
 /** Wildcard capability */
 export const WILDCARD_CAPABILITY = "*" as const;
 
@@ -112,6 +119,10 @@ export const ALL_CAPABILITIES: Set<Capability> = new Set([
   MSG_CAPABILITIES.SEND,
   MSG_CAPABILITIES.BROADCAST,
   MSG_CAPABILITIES.SUBSCRIBE,
+  // Workspace
+  WORKSPACE_CAPABILITIES.WORKTREE,
+  WORKSPACE_CAPABILITIES.STREAM,
+  WORKSPACE_CAPABILITIES.INTEGRATE,
   // Wildcard
   WILDCARD_CAPABILITY,
 ]);

package/src/roles/config-loader.ts

@@ -126,10 +126,11 @@ export function getProjectConfigPath(projectPath?: string): string {
 /**
  * Get the user-level config file path
  *
- * @returns Path to ~/.multiagent/roles.json
+ * @returns Path to ~/.multiagent/roles.json (or MACRO_AGENT_HOME/roles.json)
  */
 export function getUserConfigPath(): string {
-  return path.join(os.homedir(), USER_CONFIG_DIR, CONFIG_FILE_NAME);
+  const globalDir = process.env.MACRO_AGENT_HOME || path.join(os.homedir(), USER_CONFIG_DIR);
+  return path.join(globalDir, CONFIG_FILE_NAME);
 }
 
 // =============================================================================

package/src/roles/types.ts

@@ -54,6 +54,12 @@ export type ExecCapability =
 /** Communication capabilities */
 export type MsgCapability = "msg.send" | "msg.broadcast" | "msg.subscribe";
 
+/** Workspace capabilities */
+export type WorkspaceCapability =
+  | "workspace.worktree"
+  | "workspace.stream"
+  | "workspace.integrate";
+
 /** All capability types combined, plus wildcard */
 export type Capability =
   | FileCapability
@@ -63,6 +69,7 @@ export type Capability =
   | TaskCapability
   | ExecCapability
   | MsgCapability
+  | WorkspaceCapability
   | "*"; // Wildcard for all capabilities
 
 // =============================================================================

package/src/server/combined-server.ts

@@ -31,9 +31,11 @@ import {
   registerTaskExtensions,
   registerResumeExtension,
   registerAgentLifecycleExtensions,
+  registerStreamExtensions,
   type MAPAdapter,
   type MAPAdapterServices,
   type MAPWebSocketHandler,
+  type StreamExtensionServices,
 } from "../map/adapter/index.js";
 import type { Agent, AgentId } from "../store/types/index.js";
 import type { Address, SendOptions } from "../map/types.js";
@@ -49,6 +51,7 @@ import {
   secureCompare,
 } from "../auth/token.js";
 import { TaskBackend, TaskToolProvider } from "../task/backend/types.js";
+import type { TeamManager } from "../teams/team-manager.js";
 
 // ─────────────────────────────────────────────────────────────────
 // Types
@@ -73,6 +76,12 @@ export interface CombinedServerServices {
   agentTokenManager?: AgentTokenManager;
   /** Get connected opentasks project paths (for health endpoint) */
   getConnectedProjects?: () => string[];
+  /** Optional stream extension services for git-cascade stream/checkpoint/merge-queue features */
+  streamExtensions?: StreamExtensionServices;
+  /** Optional team manager for dynamic team management */
+  teamManager?: TeamManager;
+  /** Optional workspace manager for workspace isolation and merge queue */
+  workspaceManager?: import("../workspace/types.js").WorkspaceManager;
 }
 
 export interface CombinedServerConfig {
@@ -258,7 +267,7 @@ export function createCombinedServer(
   // Create Express app with API routes (include mail services)
   const app = createAPIApp(
     { ...services, mailService, conversationMap },
-    { cors, serverToken: resolvedServerToken },
+    { cors, serverToken: resolvedServerToken, defaultCwd },
   );
 
   // Create HTTP server with Express
@@ -369,6 +378,11 @@ export function createCombinedServer(
       agentTokenManager: services.agentTokenManager,
     });
 
+    // Register stream/checkpoint/diffStack/mergeQueue extensions
+    if (services.streamExtensions) {
+      registerStreamExtensions(mapAdapter, services.streamExtensions);
+    }
+
     mapHandler = createMAPWebSocketHandler(mapAdapter);
   }
 

package/src/store/__tests__/event-store-oob.test.ts

@@ -0,0 +1,109 @@
+/**
+ * EventStore Out-of-Band Field Preservation Tests
+ *
+ * Tests that fields written via updateAgentMetadata() (out-of-band,
+ * not through events) survive the rebuildViews() cycle that occurs
+ * on every auto-load (every 1 second) and on reload().
+ *
+ * The preservation relies on OUT_OF_BAND_FIELDS in rebuildViews()
+ * which saves these values before clearing views, replays all events,
+ * then restores the saved values.
+ *
+ * @module store/__tests__/event-store-oob
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createEventStore, type EventStore } from "../event-store.js";
+import type { AgentId } from "../types/index.js";
+
+describe("EventStore — Out-of-Band Field Preservation", () => {
+  let eventStore: EventStore;
+
+  const AGENT_ID = "oob-test-001" as AgentId;
+
+  beforeEach(async () => {
+    eventStore = await createEventStore({ instanceId: `oob-test-${Date.now()}` });
+
+    // Create an agent via spawn event
+    eventStore.emit({
+      type: "spawn",
+      source: { agent_id: AGENT_ID },
+      payload: {
+        agent_id: AGENT_ID,
+        task: "Test task",
+        role: "worker",
+        cwd: "/original/path",
+      },
+    });
+    await eventStore.persist();
+  });
+
+  afterEach(async () => {
+    try { await eventStore.close(); } catch { /* ignore */ }
+  });
+
+  it("cwd survives rebuildViews after updateAgentMetadata", async () => {
+    // Verify initial cwd from spawn event
+    expect(eventStore.getAgent(AGENT_ID)?.cwd).toBe("/original/path");
+
+    // Update cwd out-of-band
+    eventStore.updateAgentMetadata(AGENT_ID, { cwd: "/workspace/worktree-001" });
+    expect(eventStore.getAgent(AGENT_ID)?.cwd).toBe("/workspace/worktree-001");
+
+    // Persist and reload (triggers rebuildViews)
+    await eventStore.persist();
+    await eventStore.reload();
+
+    // cwd should survive the rebuild
+    const agent = eventStore.getAgent(AGENT_ID);
+    expect(agent).not.toBeNull();
+    expect(agent!.cwd).toBe("/workspace/worktree-001");
+  });
+
+  it("team_instance survives rebuildViews", async () => {
+    // Set team_instance out-of-band
+    eventStore.updateAgentMetadata(AGENT_ID, { team_instance: "team-alpha-001" });
+    expect(eventStore.getAgent(AGENT_ID)?.team_instance).toBe("team-alpha-001");
+
+    // Persist and reload
+    await eventStore.persist();
+    await eventStore.reload();
+
+    // team_instance should survive
+    expect(eventStore.getAgent(AGENT_ID)?.team_instance).toBe("team-alpha-001");
+  });
+
+  it("all OUT_OF_BAND_FIELDS preserved together", async () => {
+    // Set all out-of-band fields simultaneously
+    eventStore.updateAgentMetadata(AGENT_ID, {
+      name: "Developer Alpha",
+      plan: [{ content: "Step 1: do the thing", priority: "high", status: "pending" }],
+      metadata: { custom_key: "custom_value" },
+      cwd: "/workspace/worktree-002",
+      team_instance: "team-beta-002",
+    });
+
+    // Verify all set correctly
+    const before = eventStore.getAgent(AGENT_ID)!;
+    expect(before.name).toBe("Developer Alpha");
+    expect(before.cwd).toBe("/workspace/worktree-002");
+    expect(before.team_instance).toBe("team-beta-002");
+
+    // Persist and reload (triggers rebuildViews)
+    await eventStore.persist();
+    await eventStore.reload();
+
+    // All fields should survive
+    const after = eventStore.getAgent(AGENT_ID)!;
+    expect(after.name).toBe("Developer Alpha");
+    expect(after.cwd).toBe("/workspace/worktree-002");
+    expect(after.team_instance).toBe("team-beta-002");
+
+    // plan and metadata may be stored as JSON strings or objects depending on TinyBase internals
+    const plan = typeof after.plan === "string" ? JSON.parse(after.plan) : after.plan;
+    expect(plan).toEqual([{ content: "Step 1: do the thing", priority: "high", status: "pending" }]);
+
+    const metadata = typeof after.metadata === "string" ? JSON.parse(after.metadata) : after.metadata;
+    expect(metadata).toEqual({ custom_key: "custom_value" });
+  });
+});

package/src/store/event-store.ts

@@ -58,6 +58,7 @@ import {
   readInstanceMeta,
   touchInstance,
   registerInstance,
+  DEFAULT_BASE_DIR,
   DEFAULT_NAMESPACE,
   DEFAULT_PEER_VISIBILITY,
   filterEventsForPeer,
@@ -308,7 +309,7 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
   }
 
   // Track baseDir for MCP subprocess communication
-  const baseDir = config.baseDir ?? path.join(os.homedir(), '.multiagent');
+  const baseDir = config.baseDir ?? DEFAULT_BASE_DIR;
 
   // Get peer visibility config (default is restrictive)
   const peerVisibility: PeerVisibilityConfig =
@@ -382,7 +383,7 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
 
     // Register in namespace for discovery
     registerInstance(
-      config.baseDir ?? path.join(os.homedir(), '.multiagent'),
+      config.baseDir ?? DEFAULT_BASE_DIR,
       namespace,
       instanceId,
       { label: config.label }
@@ -548,6 +549,12 @@ export async function createEventStore(config: StoreConfig = {}): Promise<EventS
       const existing = row.metadata ? JSON.parse(row.metadata as string) : {};
       partial.metadata = JSON.stringify({ ...existing, ...updates.metadata });
     }
+    if (updates.team_instance !== undefined) {
+      partial.team_instance = updates.team_instance;
+    }
+    if (updates.cwd !== undefined) {
+      partial.cwd = updates.cwd;
+    }
 
     store.setPartialRow('agents', agentId, partial);
 
@@ -1332,7 +1339,7 @@ function rebuildViews(store: Store): void {
   // Preserve out-of-band agent fields that aren't derived from events.
   // These fields are written directly (not through events),
   // so they would be lost when we clear and replay.
-  const OUT_OF_BAND_FIELDS = ['plan', 'name', 'metadata'] as const;
+  const OUT_OF_BAND_FIELDS = ['plan', 'name', 'metadata', 'cwd', 'team_instance'] as const;
   const savedOutOfBand = new Map<string, Record<string, string>>();
   for (const rowId of store.getRowIds('agents')) {
     const row = store.getRow('agents', rowId);
@@ -1478,6 +1485,7 @@ function applySpawnEvent(
     task_id?: TaskId;
     parent?: AgentId | null;
     role?: string;
+    team_instance?: string;
     config?: Record<string, unknown>;
     cwd?: string;
   };
@@ -1508,6 +1516,7 @@ function applySpawnEvent(
     task: payload.task,
     task_id: payload.task_id ?? '',
     role: payload.role ?? '',
+    team_instance: payload.team_instance ?? '',
     config: JSON.stringify(payload.config ?? {}),
     cwd: payload.cwd ?? process.cwd(),
     plan: '[]',
@@ -1866,6 +1875,7 @@ function rowToAgent(row: Record<string, unknown>): Agent {
     task: row.task as string,
     task_id: (row.task_id as string) || undefined,
     role: (row.role as string) || undefined,
+    team_instance: (row.team_instance as string) || undefined,
     config: row.config ? JSON.parse(row.config as string) : {},
     cwd: (row.cwd as string) || process.cwd(),
     plan: row.plan ? JSON.parse(row.plan as string) : [],

package/src/store/instance.ts

@@ -221,8 +221,8 @@ export interface ResolvedInstance {
 // Constants
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** Default base directory */
-export const DEFAULT_BASE_DIR = path.join(os.homedir(), '.multiagent');
+/** Default base directory (override with MACRO_AGENT_HOME env var) */
+export const DEFAULT_BASE_DIR = process.env.MACRO_AGENT_HOME || path.join(os.homedir(), '.multiagent');
 
 /** Default namespace */
 export const DEFAULT_NAMESPACE = 'default';

package/src/store/types/agents.ts

@@ -40,6 +40,8 @@ export interface Agent {
   task: string;
   task_id?: TaskId;
   role?: string;
+  /** Team instance ID this agent belongs to (set by TeamManager) */
+  team_instance?: string;
   config: AgentConfig;
   cwd: string;
   plan: Array<{ content: string; priority: string; status: string }>;
@@ -61,4 +63,7 @@ export interface AgentMetadataUpdate {
   name?: string;
   plan?: Array<{ content: string; priority: string; status: string }>;
   metadata?: Record<string, unknown>;
+  team_instance?: string;
+  /** Override the agent's working directory (e.g., to workspace worktree path) */
+  cwd?: string;
 }

package/src/task/backend/__tests__/memory-pull-mode.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Pull-Mode Task Backend Tests
+ *
+ * Tests the claim/unclaim/listClaimable methods of InMemoryTaskBackend
+ * which enable the pull model where workers claim tasks from a pool.
+ *
+ * @module task/backend/__tests__/memory-pull-mode
+ */
+
+import { describe, it, expect, beforeEach } from "vitest";
+import { createEventStore, type EventStore } from "../../../store/event-store.js";
+import { InMemoryTaskBackend } from "../memory.js";
+import type { AgentId, TaskId } from "../../../store/types/index.js";
+
+describe("InMemoryTaskBackend — Pull Mode", () => {
+  let eventStore: EventStore;
+  let backend: InMemoryTaskBackend;
+
+  const AGENT_A = "agent-a" as AgentId;
+  const AGENT_B = "agent-b" as AgentId;
+  const CREATOR = "creator-001" as AgentId;
+
+  beforeEach(async () => {
+    eventStore = await createEventStore({ instanceId: `pull-test-${Date.now()}` });
+    backend = new InMemoryTaskBackend(eventStore);
+  });
+
+  // ─────────────────────────────────────────────────────────────────
+  // claim()
+  // ─────────────────────────────────────────────────────────────────
+
+  it("claim returns first pending unblocked task", async () => {
+    const t1 = await backend.create({ description: "Task 1", created_by: CREATOR });
+    const t2 = await backend.create({ description: "Task 2", created_by: CREATOR });
+    const t3 = await backend.create({ description: "Task 3", created_by: CREATOR });
+
+    const claimed = await backend.claim!(AGENT_A);
+    expect(claimed).not.toBeNull();
+    expect(claimed!.id).toBe(t1.id);
+    expect(claimed!.assigned_agent).toBe(AGENT_A);
+
+    // Second claim should return t2
+    const claimed2 = await backend.claim!(AGENT_B);
+    expect(claimed2).not.toBeNull();
+    expect(claimed2!.id).toBe(t2.id);
+    expect(claimed2!.assigned_agent).toBe(AGENT_B);
+  });
+
+  it("claim skips assigned tasks", async () => {
+    const t1 = await backend.create({ description: "Task 1", created_by: CREATOR });
+    const t2 = await backend.create({ description: "Task 2", created_by: CREATOR });
+
+    // Assign t1 directly
+    await backend.assign(t1.id, { agent_id: AGENT_A });
+
+    // claim should skip t1 and return t2
+    const claimed = await backend.claim!(AGENT_B);
+    expect(claimed).not.toBeNull();
+    expect(claimed!.id).toBe(t2.id);
+  });
+
+  it("claim skips blocked tasks", async () => {
+    const blocker = await backend.create({ description: "Blocker task", created_by: CREATOR });
+    const blocked = await backend.create({ description: "Blocked task", created_by: CREATOR });
+    const available = await backend.create({ description: "Available task", created_by: CREATOR });
+
+    // Add blocker dependency
+    await backend.addBlocker(blocked.id, blocker.id);
+
+    // claim should skip blocked and return available
+    const claimed = await backend.claim!(AGENT_A);
+    expect(claimed).not.toBeNull();
+    // Should return either blocker or available (blocker is pending+unblocked, so it comes first)
+    // blocker is pending + not assigned + not blocked → claimable
+    // blocked is pending + not assigned but IS blocked → not claimable
+    // available is pending + not assigned + not blocked → claimable
+    expect([blocker.id, available.id]).toContain(claimed!.id);
+    expect(claimed!.id).not.toBe(blocked.id);
+  });
+
+  it("claim returns null when no claimable tasks", async () => {
+    // Create a task and assign it
+    const t1 = await backend.create({ description: "Task 1", created_by: CREATOR });
+    await backend.assign(t1.id, { agent_id: AGENT_A });
+
+    // No unassigned pending tasks left
+    const claimed = await backend.claim!(AGENT_B);
+    expect(claimed).toBeNull();
+  });
+
+  // ─────────────────────────────────────────────────────────────────
+  // unclaim()
+  // ─────────────────────────────────────────────────────────────────
+
+  it("unclaim returns task to pending pool", async () => {
+    const t1 = await backend.create({ description: "Task 1", created_by: CREATOR });
+
+    // Claim it
+    const claimed = await backend.claim!(AGENT_A);
+    expect(claimed!.id).toBe(t1.id);
+    expect(claimed!.assigned_agent).toBe(AGENT_A);
+
+    // Unclaim it
+    await backend.unclaim!(t1.id);
+
+    // Task should be claimable again
+    const reClaimed = await backend.claim!(AGENT_B);
+    expect(reClaimed).not.toBeNull();
+    expect(reClaimed!.id).toBe(t1.id);
+    expect(reClaimed!.assigned_agent).toBe(AGENT_B);
+  });
+
+  it("unclaim throws on unassigned task", async () => {
+    const t1 = await backend.create({ description: "Task 1", created_by: CREATOR });
+
+    await expect(backend.unclaim!(t1.id)).rejects.toThrow("not assigned");
+  });
+
+  // ─────────────────────────────────────────────────────────────────
+  // listClaimable()
+  // ─────────────────────────────────────────────────────────────────
+
+  it("listClaimable filters by tags", async () => {
+    await backend.create({
+      description: "Frontend task",
+      created_by: CREATOR,
+      tags: ["frontend", "ui"],
+    });
+    await backend.create({
+      description: "Backend task",
+      created_by: CREATOR,
+      tags: ["backend", "api"],
+    });
+    await backend.create({
+      description: "Untagged task",
+      created_by: CREATOR,
+    });
+
+    // Filter by "backend" tag
+    const claimable = await backend.listClaimable!({ tags: ["backend"] });
+    expect(claimable.length).toBe(1);
+    expect(claimable[0].description).toBe("Backend task");
+
+    // Filter by "frontend" tag
+    const frontendTasks = await backend.listClaimable!({ tags: ["frontend"] });
+    expect(frontendTasks.length).toBe(1);
+    expect(frontendTasks[0].description).toBe("Frontend task");
+
+    // No filter returns all claimable
+    const allClaimable = await backend.listClaimable!();
+    expect(allClaimable.length).toBe(3);
+  });
+});

package/src/task/backend/opentasks/daemon-manager.ts

@@ -54,7 +54,10 @@ export interface DaemonManagerResult {
 // Constants
 // =============================================================================
 
-const DEFAULT_CENTRAL_PATH = path.join(os.homedir(), ".multiagent", "opentasks");
+const DEFAULT_CENTRAL_PATH = path.join(
+  process.env.MACRO_AGENT_HOME || path.join(os.homedir(), ".multiagent"),
+  "opentasks",
+);
 
 /** Grace period (ms) between client disconnect and daemon.stop() to let children finish disconnecting */
 const DAEMON_DRAIN_MS = 500;