macro-agent 0.1.1 → 0.1.3

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # macro-agent
 
-A multi-agent orchestration system for spawning and managing hierarchical Claude Code agents.
+A multi-agent orchestration system for spawning and managing hierarchical Claude Code agents. Delegates messaging to **agent-inbox** and task management to **opentasks**.
 
 ## Project Overview
 
@@ -8,183 +8,320 @@ macro-agent enables coordinated work across multiple AI agents with:
 - **Role-based agents** (Worker, Integrator, Coordinator, Monitor + custom team roles)
 - **Team templates** for declarative multi-agent topologies (YAML config)
 - **Pluggable integration strategies** (queue, trunk, optimistic)
-- **Workspace isolation** via git worktrees
+- **Workspace isolation** via git worktrees (powered by git-cascade)
 - **Merge queue** for serialized integration
-- **Task backend** abstraction (memory or opentasks) with push and pull modes
-- **In-flight steering** via context injection
-- **Signal filtering and emission enforcement** for communication topology
-- **Session continuations** for long-running daemon agents
-- **Observability** via throughput, utilization, and error metrics
+- **Messaging** via agent-inbox (structured inbox/outbox, threading, federation)
+- **Task management** via opentasks (graph-based dependencies, providers, claiming)
+- **Control socket** for MCP subprocess lifecycle RPC (NDJSON over UNIX socket)
+- **Composite signal filtering and emission enforcement** for multi-team communication topology
+- **Trigger system** with pluggable routing strategies, wake management, cron, and webhooks
+- **Agent detection** for discovering installed CLI coding agents (Claude Code, Codex, etc.)
+- **Health check heartbeats** from MCP subprocesses to the control server
 
 ## Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                      External Clients                       │
-│           (CLI, WebSocket ACP, REST API)                    │
+│                     (CLI, ACP stdio)                        │
 └───────────────────────────┬─────────────────────────────────┘
                             │
 ┌───────────────────────────▼─────────────────────────────────┐
-│                     Team Runtime (optional)                   │
-│  - Loads team YAML config (topology, communication)         │
-│  - Bootstraps root + companion agents                       │
-│  - Installs spawn interceptor, signal filters, validators   │
-│  - Manages integration strategy and session continuations   │
+│                   boot-v2.ts (System Wiring)                │
+│  1. AgentStore (SQLite)      5. AgentManagerV2              │
+│  2. InboxAdapter (embedded)  6. TriggerSystemV2             │
+│  3. TasksAdapter (IPC)       7. ControlServer               │
+│  4. RoleRegistry             8. Return MacroAgentSystemV2   │
 └───────────────────────────┬─────────────────────────────────┘
                             │
 ┌───────────────────────────▼─────────────────────────────────┐
-│                     Agent Manager                            │
-│  - Spawns agents via acp-factory                            │
-│  - Manages lifecycle (spawn, prompt, stop, continue)        │
-│  - Spawn interception for team role/topic injection         │
-└───────────────────────────┬─────────────────────────────────┘
-                            │
-        ┌───────────────────┼───────────────────┐
-        │                   │                   │
-        ▼                   ▼                   ▼
-┌──────────────┐   ┌──────────────┐   ┌──────────────┐
-│    Roles     │   │   Workspace  │   │    Tasks     │
-│  Built-in +  │   │  Bare Repo   │   │  Backend     │
-│  Team-defined│   │  Worktrees   │   │  (memory/    │
-│  (via YAML)  │   │  Strategies  │   │  opentasks)  │
-│              │   │  (queue/     │   │  Push/Pull   │
-│              │   │   trunk/opt) │   │   modes      │
-└──────────────┘   └──────────────┘   └──────────────┘
-        │                   │                   │
-        └───────────────────┼───────────────────┘
-                            │
-┌───────────────────────────▼─────────────────────────────────┐
-│                     Message Router                           │
-│  - MAP addressing (agent, role, scope, parent/child)        │
-│  - sendToAddress() for all message routing                  │
-│  - Topic-based status routing with signal filtering         │
-│  - Emission validation (strict/permissive/audit)            │
-│  - Activity waking for sleeping agents                      │
+│              TeamManagerV2 (optional, multi-team)            │
+│  - Holds multiple TeamRuntimeV2 instances                   │
+│  - Composite spawn interceptor (delegates per agent-team)   │
+│  - Composite signal filters via addSignalFilter(id, fn)     │
+│  - Composite emission validators via addEmissionValidator()  │
+│  - Agent-to-team mapping (auto-registers children)          │
+│  - Each TeamRuntimeV2:                                      │
+│    - Loads team YAML, bootstraps root + companions          │
+│    - Scoped inbox (scope = team name)                       │
+│    - Per-team signal filter + emission validator             │
 └───────────────────────────┬─────────────────────────────────┘
                             │
 ┌───────────────────────────▼─────────────────────────────────┐
-│                      Event Store                             │
-│  - Append-only event log (SQLite)                           │
-│  - Materialized views for queries                           │
-│  - Agents, tasks, messages, events, team config             │
-└─────────────────────────────────────────────────────────────┘
+│                  AgentManagerV2                              │
+│  - Spawns agents via acp-factory (AgentFactory)             │
+│  - Manages lifecycle (spawn, prompt, stop, continue, fork)  │
+│  - Registers agents in agent-inbox on spawn                 │
+│  - Creates tasks in opentasks on spawn                      │
+│  - Workspace allocation via WorkspaceManager                │
+│  - Cascade termination with change consolidation            │
+│  - Spawn interceptor hook (set by TeamManager)              │
+│  - Lifecycle listeners for child-auto-join-team             │
+└──────────┬────────────────────────────────────┬─────────────┘
+           │                                    │
+┌──────────▼──────────┐              ┌──────────▼──────────────┐
+│  Control Socket     │              │  MCP Server (per agent)  │
+│  (UNIX socket)      │              │  runs as subprocess      │
+│                     │              │                          │
+│  Main process:      │◄─────────── │  cli/mcp.ts connects to: │
+│  ControlServer      │  NDJSON RPC │  - ControlClient (spawn,  │
+│  - spawn            │             │    terminate, hierarchy)  │
+│  - terminate        │             │  - InboxClientAdapter     │
+│  - get_agent        │             │    (send, check messages) │
+│  - list_agents      │             │  - AgentStore (read-only) │
+│  - get_children     │             │  - TasksAdapter (IPC)     │
+│  - get_hierarchy    │             │                          │
+│  - ping             │             │  Registers 5-8 tools:     │
+│  - health_check     │             │  done, spawn_agent,       │
+│                     │             │  stop_agent, get_hierarchy│
+│  MCP subprocess:    │             │  inject_context,          │
+│  ControlClient      │             │  claim_task, unclaim_task,│
+│  - auto-reconnect   │             │  list_claimable_tasks     │
+│  - heartbeat ping   │             │                          │
+└─────────────────────┘              └──────────────────────────┘
+           │
+┌──────────┼──────────────────────────────────────┐
+│          │                                      │
+│  ┌───────▼───────┐  ┌──────────────┐  ┌────────▼───────────┐
+│  │ TriggerSystem │  │  Workspace   │  │    Adapters        │
+│  │               │  │  Worktrees   │  │                    │
+│  │ Router with   │  │  Strategies  │  │  InboxAdapter      │
+│  │  pluggable    │  │  (queue/     │  │  (embedded inbox   │
+│  │  strategies   │  │   trunk/opt) │  │   + IPC server)    │
+│  │ - direct      │  │  MergeQueue  │  │                    │
+│  │ - role        │  │  git-cascade │  │  TasksAdapter      │
+│  │ - head        │  │              │  │  (opentasks IPC)   │
+│  │ - custom      │  │              │  │                    │
+│  │               │  │              │  │  InboxClientAdapter │
+│  │ WakeManager   │  │              │  │  (MCP subprocess   │
+│  │ CronService   │  │              │  │   IPC client)      │
+│  │ WebhookHandler│  │              │  │                    │
+│  └───────────────┘  └──────────────┘  └────────┬───────────┘
+│                                                │
+│                    ┌───────────────────┬────────┘
+│                    │                   │
+│           ┌────────▼─────────┐  ┌──────▼───────────────┐
+│           │   agent-inbox    │  │     opentasks        │
+│           │  (embedded)      │  │  (IPC to daemon)     │
+│           │                  │  │                      │
+│           │  - Messaging     │  │  - Task graph        │
+│           │  - Threading     │  │  - Dependencies      │
+│           │  - IPC server    │  │  - Providers         │
+│           │  - Federation    │  │  - Claiming          │
+│           └──────────────────┘  └──────────────────────┘
+└─────────────────────────────────────────────────────────┘
 ```
 
 ## Source Directory Structure
 
 ```
 src/
-├── acp/                 # Agent Communication Protocol
-│   ├── macro-agent.ts      # ACP agent implementation (mount, fork)
-│   ├── websocket-server.ts # Multi-client WebSocket ACP
-│   └── session-mapper.ts   # Session → Agent ID mapping
+├── adapters/                # Subsystem integration layer
+│   ├── types.ts                # InboxAdapter + TasksAdapter interfaces
+│   ├── inbox-adapter.ts        # Wraps agent-inbox (embedded, hybrid IPC)
+│   ├── inbox-client-adapter.ts # IPC-only client for MCP subprocesses
+│   ├── tasks-adapter.ts        # Wraps opentasks client (IPC to daemon)
+│   ├── opentasks-daemon.ts     # Daemon lifecycle helper (start/stop/probe)
+│   └── index.ts                # Public exports
+│
+├── agent/                   # Agent lifecycle
+│   ├── agent-manager.ts        # AgentManager interface + SpawnInterceptor type
+│   ├── agent-manager-v2.ts     # Implementation using adapters + AgentStore
+│   ├── agent-store.ts          # Minimal SQLite store (agents + sessions tables)
+│   ├── system-prompt.ts        # Agent system prompt generation
+│   ├── types.ts                # SpawnAgentOptions, AgentFilter, MCPServerConfig, etc.
+│   ├── prompts/                # Prompt fragments
+│   │   ├── coordinator-signals.ts
+│   │   └── index.ts
+│   └── index.ts                # Public exports
 │
-├── agent/               # Agent lifecycle
-│   ├── agent-manager.ts    # Spawn, prompt, stop, continue agents
-│   ├── wake.ts             # Wake sleeping agents
-│   └── system-prompt.ts    # Agent system prompts
+├── agent-detection/         # CLI agent auto-detection
+│   ├── types.ts                # CLIAgentDefinition, DetectedAgent, SpawnCommand
+│   ├── detector.ts             # Scans PATH for known CLI agents
+│   ├── registry.ts             # Registry of known agent definitions
+│   ├── command-builder.ts      # Builds headless invocation commands
+│   └── index.ts                # Public exports
 │
-├── api/                 # REST API
-│   ├── server.ts           # Express routes (agents, tasks, team, metrics)
-│   └── types.ts            # Request/response types
+├── auth/                    # Authentication
+│   ├── token.ts                # AgentTokenManager for per-agent auth tokens
+│   └── index.ts                # Public exports
 │
-├── cli/                 # Command-line interface
-│   └── index.ts            # CLI commands (start, chat, status, --team)
+├── boot-v2.ts               # System wiring entry point (single boot function)
 │
-├── config/              # Project configuration
-│   └── project-config.ts   # .multiagent/config.json loader
+├── cli/                     # Command-line interfaces
+│   ├── index.ts                # multiagent-cli commands (start, chat, status, etc.)
+│   ├── acp.ts                  # multiagent ACP stdio mode
+│   ├── mcp.ts                  # multiagent-mcp subprocess entry point
+│   ├── parse-args.ts           # Argument parsing helpers
+│   └── stable-instance-id.ts   # Stable instance ID generation
 │
-├── lifecycle/           # Agent lifecycle management
-│   ├── handlers/           # Role-specific done() handlers
-│   │   ├── worker.ts       # Worker completion (strategy dispatch)
-│   │   ├── integrator.ts   # Integrator completion (merge queue)
-│   │   └── monitor.ts      # Monitor completion (health reporting)
-│   ├── cascade.ts          # Cascade termination
-│   └── cleanup.ts          # Workspace cleanup helpers
+├── config/                  # Project configuration
+│   ├── project-config.ts       # .multiagent/config.json loader
+│   └── index.ts                # Public exports
 │
-├── mcp/                 # Model Context Protocol
-│   ├── mcp-server.ts       # Per-agent MCP server (role-based tool filtering)
-│   └── tools/              # MCP tool implementations
-│       ├── done.ts         # Generalized done() tool
-│       ├── inject_context.ts # Context injection tool
-│       ├── claim_task.ts   # Claim task from pool (pull mode)
-│       ├── unclaim_task.ts # Release claimed task (pull mode)
-│       └── list_claimable_tasks.ts # List available tasks (pull mode)
+├── control/                 # Control socket (MCP subprocess ↔ main process)
+│   ├── control-server.ts       # NDJSON server, dispatches to AgentManager
+│   ├── control-client.ts       # NDJSON client with auto-reconnect
+│   ├── types.ts                # ControlCommand, ControlResponse types
+│   └── index.ts                # Public exports
 │
-├── metrics/             # Observability
-│   └── metrics.ts          # Throughput, utilization, error metrics
+├── index.ts                 # Public library exports
 │
-├── roles/               # Role system
-│   ├── types.ts            # RoleDefinition, Capability types
-│   ├── capabilities.ts     # Capability constants (incl. task.claim)
-│   ├── registry.ts         # Role registry with resolution
-│   └── builtin/            # Built-in role definitions
-│       ├── worker.ts
-│       ├── integrator.ts
-│       ├── coordinator.ts
-│       └── monitor.ts
+├── lifecycle/               # Agent lifecycle management
+│   ├── handlers-v2.ts          # Role-specific done() handlers (using adapters)
+│   ├── cascade.ts              # Cascade termination with change consolidation
+│   ├── cleanup.ts              # Workspace cleanup helpers (commitChanges)
+│   ├── types.ts                # DoneArgs, DoneResult, LifecycleContext, CascadeOptions
+│   └── index.ts                # Public exports
 │
-├── router/              # Message routing
-│   ├── message-router.ts   # Core router with signal filtering + emission validation
-│   ├── broadcast.ts        # Broadcast channel (fan-out)
-│   ├── role-resolver.ts    # Role → Agent resolution
-│   ├── wake.ts             # Activity waking (status + message)
-│   └── types.ts            # Message, Channel types
+├── mcp/                     # Model Context Protocol (per-agent tools)
+│   ├── mcp-server-v2.ts        # Factory: registers 5 core + 3 claim tools
+│   ├── tools/
+│   │   └── done-v2.ts          # done() tool using adapters
+│   ├── types.ts                # ToolContext, HierarchyNode, MCPToolError
+│   └── index.ts                # Public exports
 │
-├── steering/            # In-flight steering
-│   ├── inject.ts           # Context injection with fallback
-│   └── types.ts            # Injection types
+├── roles/                   # Role system
+│   ├── types.ts                # RoleDefinition, RoleRegistry, Capability types
+│   ├── capabilities.ts         # Capability constants (AGENT_CAPABILITIES, WORKSPACE_CAPABILITIES)
+│   ├── registry.ts             # DefaultRoleRegistry with resolution + tool filtering
+│   ├── config-loader.ts        # Load role definitions from YAML files
+│   ├── builtin/                # Built-in role definitions
+│   │   ├── worker.ts
+│   │   ├── integrator.ts
+│   │   ├── coordinator.ts
+│   │   ├── monitor.ts
+│   │   ├── generic.ts
+│   │   └── index.ts
+│   └── index.ts                # Public exports
 │
-├── store/               # Event sourcing
-│   ├── event-store.ts      # Core event store
-│   ├── instance.ts         # Global instance management
-│   ├── backends/           # Storage backends
-│   │   ├── sqlite-backend.ts
-│   │   └── memory-backend.ts
-│   └── types/              # Type definitions
-│       ├── agents.ts
-│       ├── tasks.ts
-│       ├── events.ts
-│       └── primitives.ts
+├── store/                   # Shared type definitions (no runtime implementation)
+│   ├── types/
+│   │   ├── agents.ts           # Agent, AgentState, StopReason
+│   │   ├── tasks.ts            # Task, TaskStatus
+│   │   ├── events.ts           # Event, EventType, EventSource
+│   │   ├── messages.ts         # QueuedMessage, Subscription types
+│   │   ├── primitives.ts       # AgentId, TaskId, EventId, SessionId, Timestamp
+│   │   └── index.ts            # Re-exports all types
+│   └── index.ts                # Public exports
 │
-├── task/                # Task management
-│   ├── task-manager.ts     # Legacy task manager
-│   └── backend/            # Pluggable task backends
-│       ├── types.ts        # TaskBackend interface (+ claim/unclaim/listClaimable)
-│       ├── memory.ts       # InMemoryTaskBackend (push + pull)
-│       ├── unified-tool-provider.ts # Unified task MCP tool provider (7 tools)
-│       └── opentasks/      # OpenTasks integration
+├── teams/                   # Team template system
+│   ├── types.ts                # TeamManifest, TeamTopology, TeamCommunication
+│   ├── team-loader.ts          # YAML loading, role resolution, validation
+│   ├── team-runtime-v2.ts      # Per-team runtime (scoped inbox, signal filtering)
+│   ├── team-manager-v2.ts      # Multi-team orchestrator (composite filters)
+│   ├── seed-defaults.ts        # Seed default team templates
+│   └── index.ts                # Public exports
 │
-├── teams/               # Team template system
-│   ├── types.ts            # TeamManifest, TeamTopology, TeamCommunication
-│   ├── team-loader.ts      # YAML loading, role resolution, validation
-│   ├── team-runtime.ts     # Initialize, bootstrap, peer routing, signal filtering
-│   └── index.ts            # Public exports
+├── trigger/                 # Trigger system
+│   ├── trigger-system-v2.ts    # Factory + TriggerRouterV2 with routing strategies
+│   ├── types.ts                # TriggerEvent, TriggerSource, RoutingHint types
+│   ├── queue/                  # Per-agent system event queue
+│   │   ├── system-event-queue.ts
+│   │   ├── types.ts
+│   │   └── index.ts
+│   ├── wake/                   # Wake manager
+│   │   ├── wake-manager.ts     # Heartbeat + coalesce + inject→interrupt→prompt
+│   │   ├── types.ts
+│   │   └── index.ts
+│   ├── sources/                # Trigger event sources
+│   │   ├── cron/
+│   │   │   ├── cron-service.ts
+│   │   │   ├── scheduler.ts
+│   │   │   ├── types.ts
+│   │   │   └── index.ts
+│   │   ├── webhook/
+│   │   │   ├── webhook-handler.ts
+│   │   │   ├── types.ts
+│   │   │   └── index.ts
+│   │   └── index.ts
+│   └── index.ts                # Public exports
 │
-└── workspace/           # Workspace isolation
-    ├── workspace-manager.ts # Worktree management
-    ├── config.ts           # Workspace configuration
-    ├── merge-queue/        # Merge queue
-    │   ├── merge-queue.ts  # SQLite-backed queue
-    │   ├── types.ts        # Queue types
-    │   └── schema.ts       # Database schema
-    └── strategies/         # Integration strategies
-        ├── types.ts        # IntegrationStrategy interface
-        ├── registry.ts     # Strategy factory registry
-        ├── queue.ts        # Queue strategy (wraps merge queue)
-        ├── trunk.ts        # Trunk strategy (direct push + rebase)
-        └── optimistic.ts   # Optimistic strategy (push + validation event)
+└── workspace/               # Workspace isolation
+    ├── workspace-manager.ts    # WorkspaceManager implementation
+    ├── dataplane-adapter.ts    # Bridges to git-cascade dataplane
+    ├── config.ts               # Workspace configuration
+    ├── types.ts                # Workspace, WorkspaceManager interface
+    ├── pool/                   # Worktree pool management
+    │   ├── worktree-pool.ts
+    │   ├── types.ts
+    │   └── index.ts
+    ├── merge-queue/            # SQLite-backed merge queue
+    │   ├── merge-queue.ts
+    │   ├── schema.ts
+    │   ├── types.ts
+    │   └── index.ts
+    ├── strategies/             # Integration strategies
+    │   ├── types.ts            # IntegrationStrategy interface
+    │   ├── registry.ts         # Strategy factory registry
+    │   ├── queue.ts            # Queue strategy (wraps merge queue)
+    │   ├── trunk.ts            # Trunk strategy (direct push + rebase)
+    │   ├── optimistic.ts       # Optimistic strategy (push + validation event)
+    │   └── index.ts
+    └── index.ts                # Public exports
 ```
 
 ## Key Concepts
 
+### Subsystem Architecture
+
+macro-agent delegates two major concerns to external subsystems:
+
+- **agent-inbox**: All messaging (send/receive, threading, conversations, federation). Embedded in-process for zero-latency events, with IPC server for agent MCP subprocesses.
+- **opentasks**: All task management (CRUD, dependencies, claiming, state transitions). Connected via IPC to opentasks daemon (auto-started if needed).
+
+macro-agent owns: agent lifecycle, workspace isolation, team topology, role system, trigger/wake, control socket.
+
+### Adapter Layer
+
+Three adapters form the integration boundary:
+
+| Adapter | Module | Used By | Purpose |
+|---------|--------|---------|---------|
+| **InboxAdapter** | `adapters/inbox-adapter.ts` | Main process | Embeds agent-inbox, owns composite signal filters + emission validators |
+| **InboxClientAdapter** | `adapters/inbox-client-adapter.ts` | MCP subprocesses | IPC client to main process's agent-inbox |
+| **TasksAdapter** | `adapters/tasks-adapter.ts` | Both | IPC client to opentasks daemon |
+
+InboxAdapter key details:
+- `send()`: Runs emission validators (all must pass) before forwarding to agent-inbox
+- `onDelivery()`: Runs signal filters (AND logic — all must return true) before invoking handlers
+- Multi-team support: `addSignalFilter(id, fn)` / `addEmissionValidator(id, fn)` for named composite hooks
+- Single-team compat: `setSignalFilter(fn)` installs under the "default" key
+
+### Control Socket
+
+NDJSON-over-UNIX-socket RPC between MCP subprocesses and the main process. Separates the **control plane** (lifecycle operations) from the **data plane** (messaging via agent-inbox IPC).
+
+| Component | Module | Process |
+|-----------|--------|---------|
+| **ControlServer** | `control/control-server.ts` | Main process |
+| **ControlClient** | `control/control-client.ts` | MCP subprocess |
+
+Commands: `spawn`, `terminate`, `get_agent`, `list_agents`, `get_children`, `get_hierarchy`, `ping`, `health_check`
+
+Health check heartbeats:
+- MCP subprocesses send periodic `health_check` commands with `agentId` and `mcpPid`
+- ControlServer tracks `lastSeen` timestamps per agent
+- Enables detection of stale/crashed MCP subprocesses
+
+ControlClient features:
+- Auto-reconnect with exponential backoff on socket close
+- Configurable timeout (default 30s)
+- Sequence-numbered request/response correlation
+
+### AgentStore
+
+Minimal SQLite store (`~/.macro-agent/agents.db`) with two tables: `agents` and `sessions`. Replaces the heavy EventStore + TinyBase materialized views. Simple CRUD, no event sourcing. Accessed read-only by MCP subprocesses via SQLite WAL mode.
+
 ### Teams
 
-Teams are declarative YAML configurations that define multi-agent topologies:
+Teams are declarative YAML configurations that define multi-agent topologies.
+
 - **TeamLoader** (`team-loader.ts`): Parses `team.yaml`, resolves role inheritance, validates topology
-- **TeamRuntime** (`team-runtime.ts`): Wires team config into running services (roles, spawn interceptor, peer routing, signal filtering, emission validation, continuation monitoring)
-- Teams compose on top of existing primitives — no team loaded = identical behavior to pre-team codebase
-- Team config is shared across processes via EventStore `team_config` event
+- **TeamRuntimeV2** (`team-runtime-v2.ts`): Per-team runtime — registers roles, bootstraps root + companions, installs scoped signal filter + emission validator on InboxAdapter via named keys
+- **TeamManagerV2** (`team-manager-v2.ts`): Multi-team orchestrator — holds all TeamRuntimeV2 instances, installs a composite spawn interceptor on AgentManager, maintains agent-to-team mapping, auto-registers children in parent's team via lifecycle listener
+- **Scope**: Each team gets its own agent-inbox scope (scope = team name)
+- **Composite filters**: Multiple teams install named signal filters and emission validators on the same InboxAdapter. The adapter evaluates all filters with AND logic (all must pass) and all validators (first rejection wins).
 
 ### Roles
 
@@ -196,51 +333,89 @@ Agents are assigned roles that determine their capabilities:
 | **Integrator** | Manage merge queue and resolve conflicts | Merge operations, branch management |
 | **Coordinator** | Orchestrate workers and manage tasks | Spawn agents, assign tasks, broadcast |
 | **Monitor** | Health monitoring and alerts | Read-only access, activity watching |
+| **Generic** | Base role for custom extensions | Minimal capabilities |
 
-Teams can define custom roles (e.g., planner, grinder, judge) that extend built-in roles via `extends` in `roles/<name>.yaml`. Custom roles can add/remove capabilities and provide custom prompts.
+Teams can define custom roles (e.g., planner, grinder, judge) that extend built-in roles via `extends` in `roles/<name>.yaml`. Tool filtering is role-based — `isToolAllowedForRole()` checks the role's capabilities before registering each MCP tool.
 
 ### Integration Strategies
 
 Pluggable strategies for landing worker changes:
 - **Queue** (`queue.ts`): Wraps merge queue with serialized integration
-- **Trunk** (`trunk.ts`): Direct push with rebase-retry loop, configurable `conflictAction`
-- **Optimistic** (`optimistic.ts`): Same as trunk + emits `validation:requested` event
-
-Strategy is set per-team in `team.yaml` under `macro_agent.integration.strategy`.
+- **Trunk** (`trunk.ts`): Direct push with rebase-retry loop
+- **Optimistic** (`optimistic.ts`): Same as trunk + emits validation event
 
 ### Workspace Isolation
 
-Each worker gets an isolated git worktree:
-- Workers operate on feature branches
-- Changes merge through the queue or strategy
-- Conflicts detected and resolved by integrator
+Each worker gets an isolated git worktree via the WorkspaceManager (backed by git-cascade). Changes are merged at the terminate level — `AgentManagerV2.terminate()` calls `terminateWithChangeConsolidation()` which handles merge requests. Agents never construct merge requests directly.
+
+### MCP Tool Surface
+
+Each agent gets tools from three sources:
+
+| Source | Tools | Mount method |
+|--------|-------|-------------|
+| **macro-agent** (MCPServerV2) | `done`, `spawn_agent`, `stop_agent`, `get_hierarchy`, `inject_context` | Built-in MCP server (stdio) |
+| **macro-agent** (MCPServerV2, pull mode) | `claim_task`, `unclaim_task`, `list_claimable_tasks` | Built-in MCP server (gated by `task.claim` capability) |
+| **agent-inbox** | `send_message`, `check_inbox`, `read_thread`, `list_agents` | IPC socket (separate MCP server) |
+| **opentasks** | `task`, `link`, `annotate`, `query` | IPC socket (separate MCP server) |
+
+Tool registration in MCPServerV2 is role-gated: `shouldRegister(toolName)` checks `isToolAllowedForRole()` before calling `server.registerTool()`.
+
+### Trigger System
+
+Routes external events and inbox delivery events to agents via pluggable routing strategies.
+
+**Components:**
+- **TriggerRouterV2**: Pluggable strategy-based router
+- **WakeManager**: Heartbeat + coalesce + inject/interrupt/prompt fallback chain
+- **SystemEventQueue**: Per-agent event queue with priority and deduplication
+- **CronService**: Time-based agent activation via cron schedules
+- **WebhookHandler**: HTTP endpoint triggers
+
+**Routing Strategies** (pluggable via `RoutingStrategy` interface):
+
+| Strategy | Description | Selection |
+|----------|-------------|-----------|
+| **direct** | Route to a specific agent by ID | `routing.target.type === "agent"` |
+| **role** | Route to all agents with a given role | `routing.target.type === "role"` |
+| **head** | Route to all running root agents (default) | Fallback when no strategy matches |
+| **custom** | User-defined strategies via `registerStrategy()` | By name or `canHandle()` |
 
-### Task Backend
+Strategy resolution order: explicit `strategyName` > first `canHandle()` match > default strategy.
 
-Two backends available:
-- **memory**: In-memory tasks with EventStore persistence (supports push + pull modes)
-- **opentasks**: External issue tracking with dependency management (supports push + pull modes)
+**Inbox-to-Wake integration:**
+- `InboxAdapter.onDelivery` fires on every message delivery
+- Importance is mapped to wake action: `urgent` → interrupt/wake, `high` → inject/wake, `normal` → queue/wake, `low` → queue
+- Events are enqueued in SystemEventQueue, then WakeManager handles delivery
 
-The unified task tool provider exposes 7 MCP tools:
-- Always available: `create_task`, `get_task`, `list_tasks`, `assign_task`
-- When OpenTasks client available: `task` (upsert), `link`, `annotate`
-- Pull mode adds: `claim_task`, `unclaim_task`, `list_claimable_tasks` (gated by `task.claim` capability)
+### Agent Detection
+
+The `agent-detection/` module discovers installed CLI coding agents on the system (e.g., Claude Code, Codex, Goose). It:
+- Scans PATH for known binaries
+- Extracts version information
+- Builds headless invocation commands with proper flags
+- Supports custom agent definitions via `additionalAgents` config
 
 ### Communication Topology
 
-Teams configure non-hierarchical communication via:
-- **Channels**: Named topics (e.g., `work_coordination`, `task_updates`) with defined signals
+Teams configure communication via:
+- **Channels**: Named topics with defined signals
 - **Subscriptions**: Per-role channel subscriptions with optional signal filters
-- **Peer routing**: Directional connections between roles (`via: direct|topic|scope`) with per-peer signal filters
-- **Emissions**: Per-role allowed signal lists, enforced by emission validator
-- **Enforcement**: `strict` (reject violations), `permissive` (warn), `audit` (record to EventStore)
+- **Peer routing**: Directional connections with per-peer signal filters
+- **Emissions**: Per-role allowed signal lists
+- **Enforcement**: `strict` (reject), `permissive` (warn), `audit` (log)
+
+All filtering is adapter-side — agent-inbox is a dumb pipe, macro-agent enforces policy via composite filters on the InboxAdapter.
 
-### Context Injection
+### Done Handler Flow (V2)
 
-Inject context into running agents:
-- `inject()`: Direct session injection (if supported)
-- `interruptWith()`: Fallback interrupt method
-- High-priority message: Final fallback
+1. Agent calls `done()` MCP tool with status + summary
+2. MCPServerV2 dispatches to `createDoneHandlerV2()` which builds a handler using `HandlerDepsV2` (InboxAdapter, TasksAdapter, AgentManager)
+3. Role-specific handler runs:
+   - **Worker**: Commits changes, emits `work:done` signal to parent via InboxAdapter, transitions task via TasksAdapter
+   - **Coordinator**: Emits completion signal, cascade-terminates children if needed
+   - **Monitor**: Emits health report
+4. If `shouldTerminate`, AgentManagerV2 handles termination including workspace cleanup and change consolidation
 
 ## Conventions
 
@@ -257,50 +432,52 @@ Inject context into running agents:
 - **kebab-case** for file names
 - **SCREAMING_SNAKE** for constants
 
-#### ID Field Naming Convention
-
-Different layers use different naming for ID fields by design:
-
-| Layer | Convention | Example | Rationale |
-|-------|------------|---------|-----------|
-| **Internal** (store, router, activity) | `agent_id`, `task_id` | `source.agent_id` | Database/event conventions, explicit |
-| **MAP Protocol** (map/types) | `agent`, `task` | `address.agent` | Protocol spec, cleaner syntax |
-
-The `store/types/events.ts` module bridges these conventions when converting between internal events and MAP addresses.
-
 ### Testing
 
-- **Unit tests**: `*.test.ts` - Fast, mocked dependencies
-- **Integration tests**: `*-integration.test.ts` - Real dependencies
-- **E2E tests**: `*.e2e.test.ts` - Full system tests
+- **Unit tests**: `*.test.ts` — Fast, mocked dependencies (41 test files)
+- **E2E tests**: `*.e2e.test.ts` — Full system tests (10 test files)
 
 Run tests:
 ```bash
-npm test                    # All unit tests
-npm run test:e2e            # E2E tests (requires RUN_E2E_TESTS=true)
+npm test                              # Run all unit tests (watch mode)
+npx vitest run                        # Run all unit tests (single run)
+npm run test:e2e                      # E2E tests (mocked agent sessions)
+npm run test:e2e-full-agents          # E2E tests with real agent spawning (RUN_FULL_AGENT_TESTS=true)
 ```
 
+E2E test files:
+- `agent-lifecycle.e2e.test.ts` — Spawn, prompt, terminate flows
+- `done-scenarios.e2e.test.ts` — Done handler scenarios per role
+- `workspace-lifecycle.e2e.test.ts` — Worktree allocation and cleanup
+- `trigger-wake.e2e.test.ts` — Trigger delivery and wake flows
+- `resume-continue.e2e.test.ts` — Session continuation
+- `pull-mode.e2e.test.ts` — Task claiming workflows
+- `opentasks-integration.e2e.test.ts` — TasksAdapter integration
+- `live-agent.e2e.test.ts` — Full agent with real Claude Code (requires `RUN_FULL_AGENT_TESTS`)
+- `conflict-resolution-git.e2e.test.ts` — Git merge conflict handling
+- `real-git-operations.e2e.test.ts` — Real git worktree operations
+
 ### Error Handling
 
-- Use typed errors with codes
-- Graceful degradation over hard failures
+- Use typed errors with codes (`AgentManagerError`, `MCPToolError`, `AgentDetectionError`)
+- Graceful degradation over hard failures (e.g., opentasks daemon not available is non-fatal)
 - Log warnings for recoverable issues
 
 ## Common Tasks
 
-### Adding a New MCP Tool
+### Adding a New MCP Tool (macro-agent specific)
 
-1. Create `src/mcp/tools/your_tool.ts`
-2. Define schema with Zod
-3. Export tool info and handler
-4. Register in `src/mcp/mcp-server.ts`
+1. Define Zod schema in `src/mcp/mcp-server-v2.ts` (or separate file for complex tools)
+2. Add `server.registerTool()` call inside `createMCPServerV2()`, gated by `shouldRegister(toolName)`
+3. If the tool needs lifecycle access, use `agentManager` (via ControlClient in subprocess, or directly in main process)
+4. If the tool needs messaging, use `inboxAdapter.send()`
 
 ### Adding a New Built-in Role
 
 1. Create `src/roles/builtin/your_role.ts`
 2. Define `RoleDefinition` with capabilities
-3. Add enforcement implementations
-4. Register in `src/roles/builtin/index.ts`
+3. Register in `src/roles/builtin/index.ts`
+4. Update `isToolAllowedForRole()` in `src/roles/registry.ts` if needed
 
 ### Adding a Team Role (via YAML)
 
@@ -309,30 +486,85 @@ npm run test:e2e            # E2E tests (requires RUN_E2E_TESTS=true)
 3. Create `.multiagent/teams/<team>/prompts/<role>.md` for custom prompt
 4. Reference the role in `team.yaml` topology and communication sections
 
-### Modifying Task Backend
+### Adding a Routing Strategy
+
+1. Implement the `RoutingStrategy` interface from `src/trigger/trigger-system-v2.ts`
+2. Define `name`, `route()`, and optionally `canHandle()`, `initialize()`, `cleanup()`
+3. Register with `triggerSystem.router.registerStrategy(strategy)`
+4. Optionally set as default: `triggerSystem.router.setDefaultStrategy(name)`
 
-1. Update interface in `src/task/backend/types.ts`
-2. Implement in both `memory.ts` and `opentasks/`
-3. Update unified tool provider if adding new operations
+### Adding a Control Command
+
+1. Add the command type to `ControlCommand` union in `src/control/types.ts`
+2. Handle the command in `ControlServer.handleCommand()` in `src/control/control-server.ts`
+3. Add typed method on `ControlClient` in `src/control/control-client.ts`
 
 ## Environment Variables
 
+### Set by boot-v2 / system config
+
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `MACRO_TASK_BACKEND` | Task backend: `memory` or `opentasks` | `opentasks` |
-| `OPENTASKS_SOCKET_PATH` | Path to OpenTasks socket | — |
+| `MACRO_BASE_DIR` | Base directory for data storage | `~/.macro-agent` |
 | `MACRO_WORKSPACE_POOL_SIZE` | Max concurrent workspaces | `10` |
 | `MACRO_MERGE_QUEUE_DB` | Merge queue SQLite path | `:memory:` |
-| `MACRO_TEAM_NAME` | Team name (injected into agent env by team runtime) | — |
-| `MACRO_TASK_MODE` | Task mode: `push` or `pull` (injected by team runtime) | — |
-| `MACRO_INTEGRATION_STRATEGY` | Integration strategy name (injected by team runtime) | — |
-| `MACRO_INSTANCE_ID` | EventStore instance ID (for MCP subprocess access) | — |
-| `MACRO_BASE_DIR` | EventStore base directory (for MCP subprocess access) | — |
+| `MACRO_TEAMS` | Comma-separated team templates to auto-start | -- |
+| `MACRO_AGENT_HOME` | Alternative base directory (used by CLI clear) | `~/.macro-agent` |
+
+### Injected into MCP subprocesses (by AgentManagerV2)
+
+| Variable | Description |
+|----------|-------------|
+| `MACRO_AGENT_ID` | ID of the calling agent |
+| `MACRO_PARENT_ID` | Parent agent ID |
+| `MACRO_TASK_ID` | Task ID |
+| `MACRO_AGENT_CWD` | Working directory |
+| `MACRO_PERMISSION_MODE` | Permission mode |
+| `MACRO_SESSION_ID` | Session ID |
+| `MACRO_STREAM_ID` | Workspace stream ID |
+| `MACRO_AGENT_LINEAGE` | JSON array of ancestor agent IDs |
+| `MACRO_CONTROL_SOCKET_PATH` | Control socket for lifecycle RPC |
+| `INBOX_SOCKET_PATH` | agent-inbox IPC socket path |
+
+### Injected by team runtime
+
+| Variable | Description |
+|----------|-------------|
+| `MACRO_TEAM_NAME` | Team name |
+| `MACRO_TASK_MODE` | Task mode: `push` or `pull` |
+| `MACRO_INTEGRATION_STRATEGY` | Integration strategy name |
+
+## Dependencies
+
+### Runtime
+
+| Package | Purpose |
+|---------|---------|
+| `agent-inbox` | Messaging, threading, federation (embedded in-process) |
+| `opentasks` | Task graph, dependencies, providers (IPC to daemon) |
+| `acp-factory` | Agent process management (Claude Code sessions) |
+| `openteams` | Team template loading and resolution |
+| `git-cascade` | Git worktree and merge queue operations |
+| `better-sqlite3` | AgentStore + InboxAdapter persistence |
+| `@modelcontextprotocol/sdk` | MCP server implementation |
+| `@multi-agent-protocol/sdk` | MAP protocol types |
+| `@sudocode-ai/claude-code-acp` | Claude Code ACP adapter |
+| `zod` | Schema validation for MCP tools |
+| `commander` | CLI argument parsing |
+| `chalk` | CLI output formatting |
+| `js-yaml` | Team YAML config parsing |
+| `nanoid` | ID generation |
+| `unique-names-generator` | Human-readable agent names |
+
+### Dev
+
+| Package | Purpose |
+|---------|---------|
+| `vitest` | Test runner |
+| `typescript` | Type checking and compilation |
+| `@sudocode-ai/cli` | Sudocode CLI integration |
 
 ## References
 
-- [README.md](README.md) - User-facing documentation
-- [docs/architecture.md](docs/architecture.md) - Full architecture documentation
-- [docs/configuration.md](docs/configuration.md) - Configuration reference
 - [docs/teams.md](docs/teams.md) - Team template schema reference
 - [docs/team-templates.md](docs/team-templates.md) - Team template format and examples