macro-agent 0.1.8 → 0.1.11

package/CLAUDE.md

@@ -7,14 +7,16 @@ A multi-agent orchestration system for spawning and managing hierarchical AI cod
 macro-agent enables coordinated work across multiple AI agents with:
 - **Role-based agents** (Worker, Integrator, Coordinator, Monitor, Analyst + custom team roles)
 - **Team templates** for declarative multi-agent topologies (YAML config)
-- **Pluggable integration strategies** (queue, trunk, optimistic)
-- **Workspace isolation** via git worktrees (powered by git-cascade)
-- **Merge queue** for serialized integration
+- **Stream-first workspace layer (V3)** — YAML-driven `TopologyPolicy` compiles role config into per-spawn workspace decisions; falls back to capability-based dispatch for programmatic callers
+- **Pluggable `LandingStrategy`** — `merge-to-parent`, `queue-to-branch`, `direct-push`, `optimistic-push` built-ins; registered on WorkspaceManager, selected per-role via YAML
+- **Pluggable `ConflictRecoveryStrategy`** — `defer`, `abandon`, `escalate`, `auto-resolve` (real git `-X` merge), `spawn-resolver` (LLM resolver agent)
+- **Workspace isolation** via git worktrees + Change-Id tracking (powered by git-cascade 0.0.3+)
 - **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 (including AI router), wake management, cron, and webhooks
+- **Task dispatch** (opt-in, via `swarm-dispatch` v0.3+) — autonomous orchestrator that polls opentasks for ready work, routes to idle agents via agent-inbox or spawns new ones, tracks lifecycle with continuation/retry split, detects stalls, and reconciles external state changes
 - **Agent detection** for discovering installed CLI coding agents (Claude Code, Codex, etc.)
 - **Health check heartbeats** from MCP subprocesses to the control server
 - **ACP protocol server** with WebSocket transport for external client integration
@@ -271,26 +273,46 @@ src/
 │   │   └── index.ts
 │   └── index.ts                # Public exports
 │
-└── 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
+└── workspace/               # Workspace isolation — V3 stream-first + legacy role-shaped
+    ├── workspace-manager.ts    # WorkspaceManager implementation (legacy + V3 surfaces)
+    ├── git-cascade-adapter.ts  # Wraps git-cascade tracker (40+ primitives surfaced)
+    ├── config.ts               # GitCascadeConfig + pool config
+    ├── types.ts                # WorkspaceManager interface (legacy + V3), events
+    ├── types-v3.ts             # V3 types: Principal, StreamSpec, LandingStrategy, etc.
+    ├── yaml-schema.ts          # Zod schema for `macro_agent.workspace`
+    ├── topology/               # TopologyPolicy — compiles YAML → spawn decisions
+    │   ├── types.ts            # TopologyPolicy, WorkspaceDecision, contexts
+    │   ├── yaml-driven.ts      # YamlDrivenTopology (primary)
+    │   ├── no-workspace.ts     # NoWorkspaceTopology (null policy)
+    │   └── index.ts
+    ├── landing/                # LandingStrategy — pluggable merge/push algorithms
+    │   ├── merge-to-parent.ts  # mergeStream into parent + optional cascadeRebase
+    │   ├── queue-to-branch.ts  # git-cascade built-in merge queue
+    │   ├── direct-push.ts      # rebase + push
+    │   ├── optimistic-push.ts  # direct-push + validation event
+    │   └── index.ts            # registerBuiltinLandingStrategies()
+    ├── recovery/               # ConflictRecoveryStrategy
+    │   ├── types.ts            # ConflictContext, ConflictResolution
+    │   ├── defer.ts            # Leave conflict record; no-op
+    │   ├── abandon.ts          # Abandon the conflicted stream
+    │   ├── escalate.ts         # Pause + notify human
+    │   ├── auto-resolve.ts     # Replay merge with -X ours|theirs|union
+    │   ├── spawn-resolver.ts   # Spawn a resolver agent (requires AgentManager)
+    │   └── index.ts            # buildBuiltinRecoveryRegistry()
     ├── pool/                   # Worktree pool management
     │   ├── worktree-pool.ts
     │   ├── types.ts
     │   └── index.ts
-    ├── merge-queue/            # SQLite-backed merge queue
-    │   ├── merge-queue.ts
-    │   ├── schema.ts
-    │   ├── types.ts
+    ├── merge-queue/            # @deprecated — legacy SQLite-backed queue,
+    │   ├── merge-queue.ts      #   duplicates git-cascade's built-in. Use
+    │   ├── schema.ts           #   GitCascadeAdapter.addToMergeQueue for
+    │   ├── types.ts            #   new code (via QueueToBranchStrategy).
     │   └── 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)
+    ├── strategies/             # @deprecated — old IntegrationStrategy.
+    │   ├── types.ts            #   Superseded by workspace/landing/.
+    │   ├── queue.ts            #   Scheduled for removal once all teams
+    │   ├── trunk.ts            #   migrate to macro_agent.workspace YAML.
+    │   ├── optimistic.ts
     │   └── index.ts
     └── index.ts                # Public exports
 ```
@@ -371,16 +393,98 @@ Agents are assigned roles that determine their capabilities:
 
 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
+### Workspace Layer (V3 Stream-First)
+
+The workspace layer went through a v3 redesign. Two paths coexist:
+
+**V3 path (YAML-driven, recommended for teams):**
+- `macro_agent.workspace` block in `team.yaml` declares per-role workspace decisions
+- `TopologyPolicy` (`workspace/topology/`) compiles YAML → `WorkspaceDecision` per spawn
+- `LandingStrategy` (`workspace/landing/`) finalizes work at `done()` time
+- `ConflictRecoveryStrategy` (`workspace/recovery/`) dispatches on conflicts
+- Auto-wired by `TeamManagerV2.startTeam()` when workspace config is present
+
+**Legacy path (programmatic / capability-based):**
+- Direct `agentManager.spawn({ capabilities: ['workspace.worktree'|'workspace.stream'|'workspace.integrate'], streamId, streamConfig })`
+- `capabilityBasedDispatch` in `AgentManagerV2` routes to role-shaped `WorkspaceManager` methods (`createWorkerWorkspace`, etc.)
+- Retained for programmatic callers (tools, libraries, tests that don't load team YAML)
+
+**Dispatch priority in `AgentManagerV2.createWorkspaceForRole()`:**
+1. If `topologyPolicy` is set → V3 path via `executeWorkspaceDecision`
+2. Else → `capabilityBasedDispatch` using role-shaped methods
+
+### TopologyPolicy (V3)
+
+`TopologyPolicy` (`workspace/topology/types.ts`) is the contract for compiling
+team YAML into per-spawn workspace decisions. Three built-ins:
+
+| Policy | Module | Purpose |
+|---|---|---|
+| **YamlDrivenTopology** | `topology/yaml-driven.ts` | Primary; reads `macro_agent.workspace` |
+| **NoWorkspaceTopology** | `topology/no-workspace.ts` | Null policy; returns `share-parent-cwd` for all |
+
+Hook methods:
+- `onTeamStart(ctx)` → creates team-root stream if any role needs it
+- `onAgentSpawn(ctx)` → returns `WorkspaceDecision` (`none` / `share-parent-cwd` / `share-with-agent` / `attach-to-stream` / `new-stream`)
+- `onAgentComplete(ctx)` → deallocates the agent's worktree
+- `onTeamStop(ctx)` → applies `on_team_complete` action (`keep` / `merge_to_main` / `abandon`)
+
+The YAML schema (`workspace/yaml-schema.ts`) supports:
+- `workspace`: `none` / `attach_to_team_root` / `share_with_agent` / `share_parent_cwd` / `new_stream`
+- `stream_lineage`: `from_team_root` / `fork_from_team_root` / `fork_from_parent` / `independent` / `track_existing_branch`
+- `allocation`, `landing`, `landing_config`, `on_conflict`, `on_conflict_recovery`, `conflict_recovery_config`, `cascade_on_parent_update`, `on_parent_advanced`, `share_with`, `track_branch`, `capabilities`
+
+### LandingStrategies (V3)
+
+`LandingStrategy` (`workspace/types-v3.ts`) is how a streamed agent finalizes
+its work. Registered on `WorkspaceManager` via `registerLandingStrategy(s)`
+and selected per-role via YAML `landing:`. Four built-ins registered by
+`registerBuiltinLandingStrategies()`:
+
+| Strategy | Module | Semantics |
+|---|---|---|
+| **merge-to-parent** | `landing/merge-to-parent.ts` | `mergeStream(source → parent)`, optional `cascadeRebase` via `strategyConfig.cascade: true` |
+| **queue-to-branch** | `landing/queue-to-branch.ts` | `GitCascadeAdapter.addToMergeQueue(streamId, targetBranch)` — drained by integrator-capable agents |
+| **direct-push** | `landing/direct-push.ts` | Rebase + `git push` with retries (trunk flow) |
+| **optimistic-push** | `landing/optimistic-push.ts` | `direct-push` + emits validation event |
+
+`LandingContext` carries: `agentId`, `streamId`, `sourceWorktree`,
+`targetStreamId`, `strategyConfig` (from YAML `landing_config`), and a back-
+reference to `WorkspaceManager`.
+
+### Conflict Recovery (V3)
 
-Pluggable strategies for landing worker changes:
-- **Queue** (`queue.ts`): Wraps merge queue with serialized integration
-- **Trunk** (`trunk.ts`): Direct push with rebase-retry loop
-- **Optimistic** (`optimistic.ts`): Same as trunk + emits validation event
+When a landing returns a conflict, the agent's `done()` flow dispatches to a
+`ConflictRecoveryStrategy` (`workspace/recovery/types.ts`) selected via YAML
+`on_conflict_recovery:` or team default. Five built-ins:
 
-### Workspace Isolation
+| Strategy | Mode | Behavior |
+|---|---|---|
+| **defer** | sync | No-op — leaves conflict record for later manual recovery |
+| **abandon** | sync | `abandonStream(streamId)` — throwaway work |
+| **escalate** | async | `pauseStream` + emit escalation — awaits external `resolve_conflict` MCP call |
+| **auto-resolve** | sync | Replays merge with `-X ours|theirs|union` in the agent's worktree, commits, notifies `workspaceManager.resolveConflict` |
+| **spawn-resolver** | async | Spawns a resolver agent on the conflicted stream; awaits `conflict:resolved` event or timeout |
 
-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.
+`spawn-resolver` requires `AgentManager` injection (not in default registry;
+register via `createSpawnResolverStrategy({ agentManager })`). Max concurrent
+resolvers per stream is configurable; timeout falls back to `escalated`.
+
+`ConflictContext` carries: `conflictId`, `streamId`, `paths`, `operation`
+(`merge` | `sync` | `rebase` | `cascade`), `worktree?` (required for
+`auto-resolve`), `landingAgentId?`, `recoveryDepth`, `strategyConfig`.
+
+### Workspace Isolation (shared across paths)
+
+Each streamed agent gets an isolated git worktree via `WorkspaceManager`,
+backed by git-cascade's `MultiAgentRepoTracker`. V3 agents use
+`allocateWorktree({ agentId, streamId })`; legacy agents use role-specific
+`createWorkerWorkspace` / `createIntegratorWorkspace` / `createCoordinatorWorkspace`.
+Both produce the same underlying git worktree structure.
+
+Change-Id tracking via `commitChanges({ agentId, streamId, worktree, message })`
+(v3) — each commit gets a stable `Change-Id: c-xxxxxxxx` trailer that survives
+rebases. Legacy callers that use raw `git commit` bypass this tracking.
 
 ### MCP Tool Surface
 
@@ -422,6 +526,81 @@ Strategy resolution order: explicit `strategyName` > first `canHandle()` match >
 - 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
 
+### Task Dispatch (Autonomous Mode)
+
+Opt-in autonomous dispatch mode powered by [`swarm-dispatch`](https://www.npmjs.com/package/swarm-dispatch) (v0.3+). The orchestrator polls opentasks for ready work, routes to idle agents or spawns new ones, tracks lifecycle, retries failures with exponential backoff, detects stalls, and reconciles external state changes.
+
+Enabled via `config.dispatch.enabled` in boot. The orchestrator, state machine, eligibility, concurrency, retry, continuation, and reconciliation are all provided by `swarm-dispatch` — macro-agent provides adapters for the five ports:
+
+1. **TaskSource adapter** — wraps `TasksAdapter` (opentasks IPC) for task queries, claiming, and state transitions
+2. **AgentRuntime adapter** — wraps `AgentManagerV2` for agent spawning, termination, and lifecycle event subscription
+3. **MessagePort adapter** — wraps the embedded `agent-inbox` for mail-based work routing and result envelopes (via `createAgentInboxPort`)
+4. **AgentRoster adapter** — queries inbox agent storage for idle agents to route work to before spawning
+5. **Dispatch mode** — auto-selects `prefer-route` when MessagePort + Roster are present (mail-first, spawn-fallback); falls back to `spawn-only` when either is absent
+
+**Boot wiring** (`boot-v2.ts`):
+```typescript
+import { createOrchestrator, createAgentInboxPort } from "swarm-dispatch";
+
+const orchestrator = createOrchestrator(source, runtime, {
+  claimantId,
+  pollIntervalMs: 15_000,
+  concurrency: { global: 3 },
+  retry: { maxRetries: 3, baseDelayMs: 10_000, maxDelayMs: 300_000 },
+  continuation: { delayMs: 1_000, maxTurns: 20 },
+  reconcile: { enabled: true, intervalMs: 60_000, stallTimeoutMs: 300_000 },
+  messagePort,    // agent-inbox adapter (opt-in)
+  roster,         // inbox agent listing (opt-in)
+  dispatchMode,   // prefer-route | spawn-only | route-only | prefer-spawn
+});
+await orchestrator.start();
+```
+
+The `Orchestrator` is exposed on `MacroAgentSystemV2.taskDispatcher` (optional, only present when dispatch is enabled) for observability, snapshots, and manual triggering via `dispatchNow()` / `reconcileNow()`.
+
+**Configuration** (in `BootV2Config.dispatch`):
+```yaml
+dispatch:
+  enabled: true
+  pollIntervalMs: 15000        # Dispatch poll cadence
+  maxConcurrent: 3             # Global concurrency limit
+  defaultRole: worker          # Role for spawned agents
+  tags: [auto]                 # Only dispatch tasks with these tags
+  maxRetries: 3                # Retry attempts per task
+  dispatchMode: prefer-route   # route-only | spawn-only | prefer-route | prefer-spawn
+  enableMailRouting: true       # Wire MessagePort via agent-inbox (default: true)
+  enableRoster: true            # Wire AgentRoster via inbox agent listing (default: true)
+  continuation:
+    delayMs: 1000               # Delay before continuation re-dispatch
+    maxTurns: 20                # Max continuation turns per task
+  reconcile:
+    enabled: true
+    intervalMs: 60000           # Reconciliation cadence
+    stallTimeoutMs: 300000      # Terminate agents with no activity past this
+  eligibility:
+    minPriority: 2
+    excludeTags: [wip]
+```
+
+**Dispatch flow:**
+1. Orchestrator polls opentasks for ready tasks
+2. For each eligible task: check AgentRoster for idle agents → route via MessagePort if found → spawn via AgentRuntime if not
+3. Agent works on the task; lifecycle events flow back through `onStopped`
+4. On normal completion: check if task is still active → if yes, schedule continuation (same logical run, next turn)
+5. On abnormal exit: queue retry with exponential backoff
+6. Reconcile tick: check external state (task closed? reassigned?), detect stalls, terminate stale agents
+
+**Key design decisions:**
+- Dispatch logic lives in `swarm-dispatch` (runtime-agnostic npm package), not macro-agent
+- **Mail-first, spawn-fallback**: when MessagePort + Roster are wired, the orchestrator prefers routing to existing idle agents over spawning new ones
+- Agents spawn parentless (`parent: null`) — the dispatcher is the coordination layer, not a parent agent
+- **Continuation vs retry**: normal exit + still-active task = continuation (short delay, turn counter). Abnormal exit = retry (exponential backoff, attempt counter). Never mixed.
+- Each dispatcher instance uses a unique `claimantId` (`hostname:pid:instanceHash`) for multi-instance awareness
+- The dispatcher registers itself as an agent in the inbox (`dispatcher:<claimantId>`) to receive mail-based work delegation from other agents
+- **Cancellation propagation**: spawned agents are terminated via `runtime.terminate`; routed agents receive `x-dispatch/cancel` messages via MessagePort
+- `promptUntilDone()` auto-terminates the agent when `done()` signals `shouldTerminate: true`
+- See [swarm-dispatch README](https://www.npmjs.com/package/swarm-dispatch) for the full API
+
 ### Agent Detection
 
 The `agent-detection/` module discovers installed CLI coding agents on the system (e.g., Claude Code, Codex, Goose). It:
@@ -515,15 +694,16 @@ Teams configure communication via:
 
 All filtering is adapter-side — agent-inbox is a dumb pipe, macro-agent enforces policy via composite filters on the InboxAdapter.
 
-### Done Handler Flow (V2)
+### Done Handler Flow
 
 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
+   - **Worker / V3 streamed agent**: Commits changes via `commitChanges` (Change-Id tracked), invokes `LandingStrategy.land()` per YAML config, emits `work:done` signal
    - **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
+4. If landing returns a conflict, the recovery dispatcher selects a `ConflictRecoveryStrategy` per role's `on_conflict_recovery` YAML (or team default); strategy runs sync or async
+5. If `shouldTerminate`, AgentManagerV2 handles termination: `TopologyPolicy.onAgentComplete` deallocates the worktree; cascade termination consolidates changes for child agents
 
 ## Conventions
 
@@ -542,8 +722,8 @@ All filtering is adapter-side — agent-inbox is a dumb pipe, macro-agent enforc
 
 ### Testing
 
-- **Unit tests**: `*.test.ts` — Fast, mocked dependencies (~40 test files)
-- **E2E tests**: `*.e2e.test.ts` — Full system tests (11 test files)
+- **Unit tests**: `*.test.ts` — Fast tests, mixed real-git and mocked dependencies (~58 test files, ~990 tests)
+- **E2E tests**: `*.e2e.test.ts` — Full system tests gated by `RUN_E2E_TESTS=true`
 
 Run tests:
 ```bash
@@ -553,16 +733,23 @@ 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:
+E2E test files (selected):
 - `agent-lifecycle.e2e.test.ts` — Spawn, prompt, terminate flows
+- `workspace-lifecycle.e2e.test.ts` — Legacy capability-based workspace path (programmatic API)
+- `workspace-v3.e2e.test.ts` — V3 YAML-driven path: peer swarm, merge-to-parent landing, conflict recovery, legacy regression guard
 - `cognitive-workspace.e2e.test.ts` — Cognitive-core backend workspace operations
 - `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`)
+- `dispatch.e2e.test.ts` — Task dispatch Phase 1 boot wiring via swarm-dispatch (mocked agents)
+- `dispatch-phase2.e2e.test.ts` — Task dispatch Phase 2 boot wiring: MessagePort, AgentRoster, dispatch modes, snapshot, stall config (mocked agents)
+- `dispatch-live.e2e.test.ts` — Task dispatch with real agents via swarm-dispatch (requires `RUN_FULL_AGENT_TESTS`)
+- `dispatch-phase2-live.e2e.test.ts` — Task dispatch Phase 2 with real agents: prefer-route fallback, snapshot, lifecycle tracking, reconciliation (requires `RUN_FULL_AGENT_TESTS`)
+- `dispatch-opentasks.e2e.test.ts` — Task dispatch with real agents + real opentasks daemon via swarm-dispatch (requires `RUN_FULL_AGENT_TESTS`)
+- `dispatch-coordination.e2e.test.ts` — Dispatch coordination with mock MAP connection
 - `conflict-resolution-git.e2e.test.ts` — Git merge conflict handling
 - `real-git-operations.e2e.test.ts` — Real git worktree operations
 
@@ -602,6 +789,27 @@ E2E test files:
 3. Register with `triggerSystem.router.registerStrategy(strategy)`
 4. Optionally set as default: `triggerSystem.router.setDefaultStrategy(name)`
 
+### Adding a Landing Strategy (V3)
+
+1. Implement the `LandingStrategy` interface from `src/workspace/types-v3.ts`
+2. Define `name`, `land(ctx)`, optionally `canLand(ctx)`, `initialize()`, `close()`
+3. Register via `workspaceManager.registerLandingStrategy(new YourStrategy())` (typically at boot after built-ins)
+4. Reference from team YAML: `roles.<role>.landing: your_strategy_name`; pass config via `landing_config`
+
+### Adding a Conflict Recovery Strategy (V3)
+
+1. Implement the `ConflictRecoveryStrategy` interface from `src/workspace/recovery/types.ts`
+2. Define `name`, `mode` (`sync` | `async`), `recover(ctx)`, optionally `canHandle(ctx)`
+3. If the strategy needs `AgentManager` (like `spawn-resolver`), expose a factory that accepts it
+4. Register into the team's recovery registry; selected per-role via `on_conflict_recovery:` or team default
+
+### Adding a Topology Policy (V3)
+
+1. Implement the `TopologyPolicy` interface from `src/workspace/topology/types.ts`
+2. Define `onTeamStart`, `onAgentSpawn`, `onAgentComplete`, `onTeamStop`
+3. Return `WorkspaceDecision` values from `onAgentSpawn` (`none` / `share-parent-cwd` / `share-with-agent` / `attach-to-stream` / `new-stream`)
+4. Inject via `agentManager.setTopologyPolicy(policy)` — or have `TeamManagerV2.startTeam` auto-wire from YAML via `YamlDrivenTopology`
+
 ### Adding a Control Command
 
 1. Add the command type to `ControlCommand` union in `src/control/types.ts`
@@ -631,6 +839,20 @@ E2E test files:
 | `federation.systemId` | Unique instance ID for federation | -- |
 | `federation.peers` | Peer instances to federate with | `[]` |
 | `federation.trust.allowedSystems` | Trusted system ID whitelist | -- |
+| `dispatch.enabled` | Enable autonomous task dispatch mode | `false` |
+| `dispatch.pollIntervalMs` | Dispatch poll cadence (ms) | `15000` |
+| `dispatch.maxConcurrent` | Max concurrent dispatched agents | `3` |
+| `dispatch.defaultRole` | Role for spawned agents | `"worker"` |
+| `dispatch.tags` | Only dispatch tasks with these tags | -- |
+| `dispatch.maxRetries` | Retry attempts per failed task | `3` |
+| `dispatch.dispatchMode` | `route-only`, `spawn-only`, `prefer-route`, `prefer-spawn` | auto (`prefer-route` if inbox wired) |
+| `dispatch.enableMailRouting` | Wire MessagePort via agent-inbox | `true` |
+| `dispatch.enableRoster` | Wire AgentRoster via inbox agent listing | `true` |
+| `dispatch.continuation.delayMs` | Delay before continuation re-dispatch (ms) | `1000` |
+| `dispatch.continuation.maxTurns` | Max continuation turns per task | `20` |
+| `dispatch.reconcile.enabled` | Enable external state reconciliation | `true` |
+| `dispatch.reconcile.intervalMs` | Reconciliation cadence (ms) | `60000` |
+| `dispatch.reconcile.stallTimeoutMs` | Terminate agents with no activity past this (ms) | `300000` |
 
 ### Injected into MCP subprocesses (by AgentManagerV2)
 
@@ -664,8 +886,9 @@ E2E test files:
 | `agent-inbox` | Messaging, threading, federation (embedded in-process) |
 | `opentasks` | Task graph, dependencies, providers (IPC to daemon) |
 | `acp-factory` | Agent process management (Claude Code sessions) |
+| `swarm-dispatch` | Autonomous task dispatch orchestrator (poll, route, spawn, continuation, retry, reconcile, mail-inbound, roster-aware) |
 | `openteams` | Team template loading and resolution |
-| `git-cascade` | Git worktree and merge queue operations |
+| `git-cascade` | Git worktree, stream/fork/merge/rebase, Change-Id tracking, cascade namespace, event emitter (0.0.3+) |
 | `better-sqlite3` | AgentStore + InboxAdapter persistence |
 | `@modelcontextprotocol/sdk` | MCP server implementation |
 | `@multi-agent-protocol/sdk` | MAP protocol types |
@@ -689,5 +912,12 @@ E2E test files:
 
 ## References
 
+### Team configuration
 - [docs/teams.md](docs/teams.md) - Team template schema reference
 - [docs/team-templates.md](docs/team-templates.md) - Team template format and examples
+
+### Workspace redesign (V3)
+- [docs/workspace-redesign-plan.md](docs/workspace-redesign-plan.md) - Implementation plan + status
+- [docs/workspace-interfaces.md](docs/workspace-interfaces.md) - V3 interface contracts (TypeScript)
+- [docs/git-cascade-integration-gaps.md](docs/git-cascade-integration-gaps.md) - Design narrative, workflow traces, migration plan
+- [docs/conflict-recovery.md](docs/conflict-recovery.md) - Conflict recovery strategy design