macro-agent 0.1.8 → 0.1.11

package/docs/design/task-dispatcher.md

@@ -0,0 +1,880 @@
+# Task Dispatcher Design
+
+## Implementation Status
+
+**Extracted to standalone package: [`swarm-dispatch`](https://www.npmjs.com/package/swarm-dispatch).**
+
+The dispatch logic originally described in this document was first implemented inside macro-agent's `trigger/dispatch/` directory, then extracted to a runtime-agnostic npm package. macro-agent now consumes `swarm-dispatch` via two thin adapters in `boot-v2.ts`:
+
+- **DispatchTaskSource** — wraps `TasksAdapter` (opentasks IPC)
+- **DispatchAgentRuntime** — wraps `AgentManagerV2` (spawn, terminate, onStopped)
+
+The dispatcher is exposed on `MacroAgentSystemV2.taskDispatcher` (optional). Dispatch events are bridged to MAP via `mapSidecar.emitEvent()` for observability.
+
+**What moved to swarm-dispatch:**
+- Dispatch tracker (concurrency, retry, state reconstruction)
+- Eligibility checker (static filters + heuristic scoring)
+- Prompt builder (default markdown template)
+- Reconciliation (external state change detection)
+- The dispatch loop itself (poll → claim → spawn → monitor)
+- OpenTasks adapter (`createOpenTasksSource`)
+
+**What stays in macro-agent:**
+- Boot wiring (~40 lines in `boot-v2.ts`)
+- AgentManagerV2 adapter (spawn with `parent: null`, lifecycle events)
+- MAP event bridge (dispatch events → MAP sidecar)
+- E2E tests (3 files: mocked, live agent, live agent + opentasks)
+
+The rest of this document is the original design that informed the implementation.
+
+---
+
+## Overview (Original Design)
+
+A dispatch mode for macro-agent's trigger system that polls opentasks for ready work and spawns agents to execute it. Turns the existing event-driven trigger architecture into an autonomous work processor — the swarmkit equivalent of Symphony's daemon loop, built on primitives that already exist.
+
+## Problem
+
+Swarmkit can coordinate agents and track tasks across systems, but has no "point at a backlog, walk away" mode. Today, agents must be manually spawned or externally triggered. There's no continuous loop that:
+
+1. Watches for ready tasks
+2. Claims and dispatches them to agents
+3. Manages concurrency, retries, and cleanup
+
+## Architecture
+
+The dispatcher is **not a new system** — it's three components wired into the existing trigger pipeline:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      trigger system v2                          │
+│                                                                 │
+│  ┌──────────┐     ┌──────────────┐     ┌───────────────────┐   │
+│  │ CronJob  │────▶│ TriggerEvent │────▶│ TaskDispatch      │   │
+│  │ "poll"   │     │ (internal)   │     │ RoutingStrategy   │   │
+│  │ every N  │     └──────────────┘     │                   │   │
+│  └──────────┘                          │  query ready ─────┼──▶ opentasks
+│                          ┌─────────────│  check capacity   │   │
+│  ┌──────────┐            │             │  claim + spawn ───┼──▶ agentManager
+│  │ Reconcile│────────────┘             │  reconcile state  │   │
+│  │ CronJob  │  (separate cadence)      │  track dispatch   │   │
+│  │ every M  │                          └───────────────────┘   │
+│  └──────────┘                                                   │
+│                                                                 │
+│  ┌──────────────────┐     ┌─────────────────────────────────┐  │
+│  │ DispatchLifecycle │────▶│ onLifecycleEvent() callback    │  │
+│  │ Listener          │     │ + inbox signal filter           │  │
+│  │                   │     │ + retry on failure              │  │
+│  └──────────────────┘     └─────────────────────────────────┘  │
+│                                                                 │
+│  ┌──────────────────┐                                          │
+│  │ DispatchTracker  │  in-memory state: active dispatches,     │
+│  │                  │  retry queue, concurrency counts          │
+│  │                  │  + reconstruction from opentasks on boot  │
+│  └──────────────────┘                                          │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Design Decisions
+
+### 1. Parentless Agents
+
+**Decision: Dispatched agents spawn as root agents (`parent: null`).**
+
+AgentManagerV2 already supports parentless agents — they're treated as "head managers" with `isHeadManager: true`. The lifecycle works without a parent:
+
+- `spawn()` accepts `parent: undefined` with no validation error (agent-manager-v2.ts:348)
+- Signal emission is skipped when `!context.parentId` (handlers-v2.ts:59)
+- Cascade termination works regardless of parent (agent-manager-v2.ts:801-822)
+
+This means dispatched agents are **peers, not children**. They don't report upward via signals — the dispatcher tracks them directly via lifecycle events (see §7 below).
+
+**Why not a synthetic coordinator parent?** A headless coordinator that nobody interacts with adds complexity for no benefit. The dispatcher itself is the coordination layer — it tracks state, manages retries, and handles lifecycle. A parent agent would just be a proxy for logic that already lives in the dispatch strategy.
+
+**Implication:** Dispatched agents can't use the `done()` signal path to notify a parent. Instead, the dispatcher listens to `onLifecycleEvent()` callbacks (type `"stopped"`) and inbox signals via `addSignalFilter()`. See §7.
+
+---
+
+### 2. Hybrid Push/Pull Dispatch
+
+**Decision: Support both modes, configurable per dispatch config. Default to push.**
+
+The dispatcher supports three modes:
+
+```typescript
+export type DispatchMode =
+  | "push"       // Dispatcher assigns task, spawns dedicated agent
+  | "pull"       // Dispatcher maintains a pool of idle workers that self-claim
+  | "hybrid";    // Dispatcher pushes high-priority, workers pull the rest
+```
+
+#### Push Mode (default)
+
+Dispatcher claims task → spawns agent with task prompt → agent works on assigned task → done.
+
+- **Pros:** Predictable, simple lifecycle, one agent per task
+- **Cons:** Cold start per task (agent spawn overhead)
+- **Best for:** Heavy tasks, tasks needing specific roles/prompts
+
+#### Pull Mode
+
+Dispatcher maintains N idle worker agents. Workers call `claim_task` / `list_claimable_tasks` to self-select work. Dispatcher respawns workers when they terminate or the pool drops below threshold.
+
+```typescript
+export interface PullModeConfig {
+  /** Target number of idle workers to maintain */
+  poolSize: number;
+  /** Role for pool workers */
+  workerRole: string;
+  /** How long a worker can be idle before termination (ms) */
+  idleTimeoutMs?: number;
+  /** Whether workers should loop (claim next task after completing one) */
+  workerLoop: boolean;
+}
+```
+
+- **Pros:** Amortizes spawn cost, workers self-select based on capability
+- **Cons:** Pool management complexity, workers may compete for same tasks
+- **Best for:** Many small tasks, fast throughput
+
+#### Hybrid Mode
+
+High-priority tasks (priority >= threshold) get push-dispatched. Everything else is available for pool workers to pull.
+
+```typescript
+export interface HybridConfig {
+  push: DispatchConfig;
+  pull: PullModeConfig;
+  /** Tasks at or above this priority get push-dispatched */
+  pushPriorityThreshold: number;
+}
+```
+
+---
+
+### 3. Workspace Lifecycle Across Retries
+
+**Decision: Configurable per dispatch config. Three strategies:**
+
+```typescript
+export type RetryWorkspaceStrategy =
+  | "reuse"     // Keep worktree, agent resumes from existing state
+  | "fresh"     // Delete worktree, agent starts clean
+  | "branch";   // Keep worktree but create a new branch from the pre-failure state
+```
+
+```yaml
+dispatch:
+  retry:
+    maxRetries: 3
+    workspaceStrategy: reuse     # or "fresh" or "branch"
+    preserveOnExhaustion: true   # keep workspace for inspection after final failure
+    cleanupDelayMs: 300000       # wait 5 min before cleaning completed workspaces
+```
+
+**`reuse` (default):** The agent gets the workspace as-is. Its prompt includes retry context (attempt number, previous error). This matches Symphony's behavior — workspace persists across turns/retries.
+
+**`fresh`:** The worktree is deleted and recreated. Appropriate when failures leave corrupted state (bad merges, broken dependencies).
+
+**`branch`:** Creates a new branch from the current worktree state before retrying. Preserves progress while giving the agent a clean commit history to work from.
+
+**Cleanup:** On final completion, worktree cleanup happens after `cleanupDelayMs` (default: 5 min, configurable to 0 for immediate). On retry exhaustion with `preserveOnExhaustion: true`, the workspace is preserved and a MAP event is emitted so operators can inspect it.
+
+---
+
+### 4. Task-to-Prompt Mapping via Opentasks
+
+**Decision: Extend opentasks with a `context` field and a prompt assembly pipeline.**
+
+The current opentasks `TaskRecord` has `title`, `content`, and `metadata` — not enough for rich agent prompts. Rather than building prompt logic into the dispatcher, extend opentasks to carry structured context that any consumer (dispatcher, agent, dashboard) can use:
+
+```typescript
+// Extension to opentasks TaskRecord
+export interface TaskContext {
+  /** Structured description (markdown) */
+  description?: string;
+  /** File paths relevant to this task */
+  files?: string[];
+  /** Related task IDs for cross-reference */
+  related?: string[];
+  /** Acceptance criteria */
+  criteria?: string[];
+  /** Labels/categories from the source tracker */
+  labels?: string[];
+  /** Source tracker URL (e.g., Linear issue URL) */
+  sourceUrl?: string;
+  /** Free-form key-value context from the tracker */
+  extra?: Record<string, unknown>;
+}
+```
+
+The dispatcher's prompt pipeline then becomes composable:
+
+```typescript
+export interface PromptPipeline {
+  /** Ordered list of prompt builders — each appends context */
+  stages: PromptStage[];
+}
+
+export interface PromptStage {
+  name: string;
+  build(task: TaskRecord, context: PromptContext): Promise<string | null>;
+}
+
+// Built-in stages:
+// 1. "task-core"     — title, description, criteria, files
+// 2. "retry-context" — attempt number, previous error, workspace state
+// 3. "playbook"      — query cognitive-core for relevant playbooks (opt-in)
+// 4. "role-prompt"   — append role-specific instructions from openteams
+// 5. "custom"        — user-provided function
+```
+
+This keeps the dispatcher thin (it calls the pipeline) while making prompt assembly extensible. The playbook stage is opt-in — only active if cognitive-core is configured.
+
+---
+
+### 5. Task Eligibility: Heuristic + Configurable + Agent-Driven
+
+**Decision: Three-layer eligibility check before dispatch.**
+
+"Ready" (no blockers in opentasks) is necessary but not sufficient. The dispatcher applies:
+
+#### Layer 1: Static Filters (config-driven)
+
+```yaml
+dispatch:
+  eligibility:
+    tags: [backend, auto]           # Only tasks with these tags
+    excludeTags: [manual, blocked]  # Skip tasks with these tags
+    trackers: [linear, github]      # Only from these tracker types
+    minPriority: 2                  # Skip low-priority tasks
+    maxAge: 86400000                # Skip tasks older than 24h (ms)
+    requireFields: [description]    # Skip tasks missing required fields
+```
+
+#### Layer 2: Heuristic Scoring (built-in)
+
+Tasks that pass static filters get a dispatch score:
+
+```typescript
+export interface EligibilityScore {
+  taskId: string;
+  score: number;       // 0-1, higher = more eligible
+  reasons: string[];   // Why this score
+}
+
+function scoreTask(task: TaskRecord): EligibilityScore {
+  let score = 1.0;
+  const reasons: string[] = [];
+
+  // Penalize tasks with no description
+  if (!task.content && !task.metadata?.description) {
+    score *= 0.3;
+    reasons.push("no description — agent may lack context");
+  }
+
+  // Penalize tasks with too many prior failures
+  const failures = task.metadata?.failureCount as number ?? 0;
+  if (failures > 0) {
+    score *= Math.pow(0.7, failures);
+    reasons.push(`${failures} prior failures`);
+  }
+
+  // Boost tasks with acceptance criteria
+  if (task.metadata?.criteria) {
+    score *= 1.2;
+    reasons.push("has acceptance criteria");
+  }
+
+  // Boost tasks with file references
+  if (task.metadata?.files) {
+    score *= 1.1;
+    reasons.push("has file references");
+  }
+
+  return { taskId: task.id, score: Math.min(score, 1), reasons };
+}
+```
+
+Tasks below a configurable `minScore` threshold (default: 0.3) are skipped. They stay in opentasks as ready but aren't dispatched until they gain more context.
+
+#### Layer 3: Agent-Driven Triage (opt-in)
+
+For teams that want smarter triage, the dispatcher can spawn a lightweight triage agent that evaluates borderline tasks:
+
+```yaml
+dispatch:
+  eligibility:
+    agentTriage:
+      enabled: true
+      role: triage              # Role from openteams
+      minScoreForTriage: 0.3    # Only triage tasks in this range
+      maxScoreForTriage: 0.7
+      maxTriagePerCycle: 3      # Don't triage too many per poll
+```
+
+The triage agent gets a batch of borderline tasks and returns a verdict per task: `dispatch`, `skip`, or `needs-context` (which creates an opentasks annotation requesting more info from the human).
+
+This is the AI router pattern applied to task eligibility — same trade-off (expensive but intelligent).
+
+---
+
+### 6. Multi-Instance Safety
+
+**Decision: Opentasks daemon is the coordination point. Add atomic claim to opentasks.**
+
+macro-agent is single-process-per-project by design. But multiple instances (different machines, CI environments) may share the same opentasks task pool. The current `claimTask` is not atomic (query → assign is TOCTOU).
+
+#### Required: Atomic Claim in Opentasks
+
+```typescript
+// New opentasks operation: atomic claim-if-unclaimed
+interface AtomicClaimRequest {
+  action: "claim";
+  taskId: string;
+  claimant: string;      // Unique claimant ID (instance + agent)
+  ttlMs?: number;        // Claim expires if not renewed (heartbeat)
+}
+
+interface AtomicClaimResponse {
+  success: boolean;
+  claimedBy?: string;    // Who currently holds the claim (if failed)
+}
+```
+
+This must be atomic at the opentasks daemon level — a single IPC operation that checks and sets. If two dispatchers race, one gets `success: false` and moves on.
+
+#### Instance Identity
+
+Each dispatcher registers with a unique claimant prefix:
+
+```typescript
+const claimantId = `${hostname}:${pid}:${instanceId}`;
+// e.g., "dev-laptop:12345:inst_a1b2c3d4"
+```
+
+This uses the existing `stable-instance-id.ts` (path-derived hash) plus hostname/pid for uniqueness.
+
+#### Claim TTL + Heartbeat
+
+Claims have a TTL (default: 5 min). The dispatch poll loop doubles as a heartbeat — each cycle renews claims for active dispatches. If an instance crashes, its claims expire and other instances can pick up the work.
+
+```typescript
+// In the dispatch strategy's route(), after spawning:
+tracker.track(taskId, spawned.id, attempt);
+
+// In every poll cycle, renew claims for active dispatches:
+for (const record of tracker.listActive()) {
+  await tasksAdapter.renewClaim(record.taskId, claimantId);
+}
+```
+
+#### What NOT to Add
+
+- No leader election — dispatchers are peers, not primary/secondary
+- No distributed lock service — opentasks daemon's atomic claim is sufficient
+- No shared state beyond opentasks — each instance has its own DispatchTracker (in-memory), reconstructed from opentasks on boot
+
+---
+
+### 7. Lifecycle Integration via Existing Signals
+
+**Decision: Use `onLifecycleEvent()` callback + inbox signal filter. No new event surface.**
+
+AgentManagerV2 already emits lifecycle events via `onLifecycleEvent()`:
+
+- `{ type: "spawned", agent }` — on spawn (agent-manager-v2.ts:629)
+- `{ type: "started", agent }` — on session start (agent-manager-v2.ts:630)
+- `{ type: "stopped", agent, reason }` — on terminate (agent-manager-v2.ts:799)
+
+And agents emit inbox signals via done handlers:
+
+- `WORKER_DONE` — worker completed (handlers-v2.ts:49-80)
+- `HELP_NEEDED` — worker blocked
+- `WORKER_DEFERRED` — worker deferred
+
+The dispatcher hooks into both:
+
+```typescript
+// trigger/dispatch/dispatch-lifecycle.ts
+
+export function createDispatchLifecycleListener(
+  tracker: DispatchTracker,
+  tasksAdapter: TasksAdapter,
+  agentManager: AgentManager,
+  inboxAdapter: InboxAdapter,
+  claimantId: string
+): DispatchLifecycleListener {
+
+  // Hook 1: AgentManager lifecycle callback
+  // Catches all terminations (normal, crash, external kill)
+  const unsubscribe = agentManager.onLifecycleEvent((event) => {
+    if (event.type !== "stopped") return;
+
+    const taskId = tracker.findTaskForAgent(event.agent.id);
+    if (!taskId) return; // Not a dispatched agent
+
+    const reason = event.reason;
+    if (reason === "done" || reason === "completed") {
+      tracker.complete(taskId);
+      tasksAdapter.transitionTask(taskId, "complete");
+      tasksAdapter.releaseClaim(taskId, claimantId);
+    } else {
+      tracker.fail(taskId, `agent stopped: ${reason}`);
+      if (!tracker.isTracked(taskId)) {
+        // Retries exhausted
+        tasksAdapter.transitionTask(taskId, "fail");
+        tasksAdapter.releaseClaim(taskId, claimantId);
+      }
+      // If still tracked (retry queued), claim is kept — retry will reuse it
+    }
+  });
+
+  // Hook 2: Inbox signal filter for richer status
+  // Captures HELP_NEEDED, WORKER_DEFERRED for status tracking
+  inboxAdapter.addSignalFilter("dispatch-lifecycle", (message) => {
+    const signal = message.content?.event;
+    if (!signal) return true; // Pass through
+
+    const agentId = message.from;
+    const taskId = tracker.findTaskForAgent(agentId);
+    if (!taskId) return true; // Not dispatched, pass through
+
+    if (signal === "HELP_NEEDED") {
+      tracker.updateStatus(taskId, "blocked");
+      // Emit MAP event for observability
+    }
+
+    return true; // Always pass through — we're observing, not filtering
+  });
+
+  return { unsubscribe };
+}
+```
+
+**Why not new events?** The lifecycle callback handles the critical path (agent stopped → update tracker). Inbox signals provide richer status (blocked, deferred) but are supplementary. No changes needed to AgentManagerV2 or the handler chain.
+
+**Edge case: agent crash without done().** The `"stopped"` lifecycle event fires on all terminations, including crashes. The stop reason distinguishes normal completion from crashes. If an agent crashes, the dispatcher treats it as a failure and queues retry.
+
+---
+
+### 8. Team-Aware Dispatch
+
+**Decision: Task metadata specifies spawn mode. Dispatcher supports single agent, team template, or custom topology.**
+
+```typescript
+export type SpawnMode =
+  | { type: "agent"; role?: string }                     // Single agent (default)
+  | { type: "team"; template: string; config?: object }  // Full team from openteams
+  | { type: "custom"; spawn: (task: TaskRecord, context: RoutingContext) => Promise<string[]> };
+```
+
+In opentasks, task metadata carries the spawn hint:
+
+```json
+{
+  "id": "task-123",
+  "title": "Security audit for auth module",
+  "metadata": {
+    "spawn": {
+      "type": "team",
+      "template": "security-audit"
+    }
+  }
+}
+```
+
+The dispatch strategy checks `task.metadata.spawn` and delegates:
+
+```typescript
+// In the dispatch strategy
+async function spawnForTask(
+  task: TaskRecord,
+  attempt: number,
+  context: RoutingContext,
+  config: DispatchConfig
+): Promise<string[]> {
+  const spawnMode = task.metadata?.spawn as SpawnMode
+    ?? { type: "agent", role: config.defaultRole };
+
+  switch (spawnMode.type) {
+    case "agent":
+      const spawned = await context.agentManager.spawn({
+        task: buildPrompt(task, attempt),
+        task_id: task.id,
+        role: spawnMode.role ?? config.defaultRole,
+        parent: null,
+      });
+      return [spawned.id];
+
+    case "team":
+      // Use TeamManagerV2 to start a team instance for this task
+      const team = await teamManager.startTeam(spawnMode.template, {
+        taskId: task.id,
+        config: spawnMode.config,
+      });
+      return team.agents.map(a => a.id);
+
+    case "custom":
+      return spawnMode.spawn(task, context);
+  }
+}
+```
+
+**Lifecycle for teams:** When a team is dispatched, the tracker records all agent IDs. The team's coordinator handles internal lifecycle. The dispatcher watches for the coordinator's `"stopped"` event as the signal that the team is done.
+
+---
+
+### 9. Configurable Concurrency Scoping
+
+**Decision: Concurrency limits are hierarchical and composable.**
+
+```yaml
+dispatch:
+  concurrency:
+    # Global cap across everything
+    global: 10
+
+    # Per-project limits (project = opentasks project context)
+    perProject:
+      backend-api: 5
+      frontend: 3
+
+    # Per-tracker limits
+    perTracker:
+      linear: 8
+      github: 4
+
+    # Per-role limits
+    perRole:
+      worker: 8
+      security-auditor: 2
+
+    # Per-tag limits (useful for resource-bound work)
+    perTag:
+      gpu: 1
+      database-migration: 1
+```
+
+Enforcement is **most restrictive wins** — a dispatch only happens if ALL applicable limits have available slots:
+
+```typescript
+function hasCapacity(task: TaskRecord, tracker: DispatchTracker, config: ConcurrencyConfig): boolean {
+  const checks = [
+    tracker.activeCount() < config.global,
+    tracker.activeByProject(task.project) < (config.perProject?.[task.project] ?? Infinity),
+    tracker.activeByTracker(task.tracker) < (config.perTracker?.[task.tracker] ?? Infinity),
+    tracker.activeByRole(task.role) < (config.perRole?.[task.role] ?? Infinity),
+    ...task.tags.map(tag =>
+      tracker.activeByTag(tag) < (config.perTag?.[tag] ?? Infinity)
+    ),
+  ];
+  return checks.every(Boolean);
+}
+```
+
+The DispatchTracker is extended with indexed counts:
+
+```typescript
+export interface DispatchTracker {
+  // ... existing methods ...
+  activeByProject(project: string): number;
+  activeByTracker(tracker: string): number;
+  activeByRole(role: string): number;
+  activeByTag(tag: string): number;
+}
+```
+
+---
+
+### 10. External State Reconciliation
+
+**Decision: Separate reconciliation cron job, following Symphony's approach.**
+
+Symphony handles this in its orchestrator tick loop (orchestrator.ex:275-298):
+
+1. Each tick, fetches current state from Linear for all running issues
+2. Compares against configured `active_states` / `terminal_states`
+3. If issue moved to terminal state externally → stop agent + cleanup workspace
+4. If issue reassigned → stop agent (no cleanup)
+5. If issue moved to non-active state (e.g., "blocked") → stop agent (no cleanup)
+
+**Our equivalent:** A second cron job (separate from the dispatch poll) that reconciles external tracker state:
+
+```typescript
+// Reconciliation strategy — registered alongside dispatch strategy
+export function createReconcileStrategy(
+  tasksAdapter: TasksAdapter,
+  tracker: DispatchTracker,
+  agentManager: AgentManager,
+  config: ReconcileConfig
+): RoutingStrategy {
+  return {
+    name: "task-reconcile",
+    canHandle: (e) => e.source.type === "cron" && e.source.jobName === "task-reconcile",
+
+    async route(_event, context): Promise<RoutingDecision> {
+      const active = tracker.listActive();
+
+      for (const record of active) {
+        const task = await tasksAdapter.getTask(record.taskId);
+
+        // Task was closed/completed externally
+        if (task.status === "closed") {
+          await agentManager.terminate(record.agentId, "external_completion");
+          tracker.complete(record.taskId);
+          continue;
+        }
+
+        // Task was reassigned to someone else
+        if (task.assignee && task.assignee !== record.claimantId) {
+          await agentManager.terminate(record.agentId, "reassigned");
+          tracker.complete(record.taskId); // Don't retry — human took over
+          continue;
+        }
+
+        // Task moved to blocked state
+        if (task.status === "blocked") {
+          await agentManager.terminate(record.agentId, "blocked_externally");
+          // Don't retry immediately — wait for unblock via normal poll
+          tracker.complete(record.taskId);
+          continue;
+        }
+
+        // Task disappeared (deleted from tracker)
+        if (!task) {
+          await agentManager.terminate(record.agentId, "task_deleted");
+          tracker.complete(record.taskId);
+          continue;
+        }
+      }
+
+      return { targetAgents: [], reason: "reconciliation complete" };
+    },
+  };
+}
+```
+
+```yaml
+dispatch:
+  reconcile:
+    enabled: true
+    intervalMs: 60000   # Check every 60s (slower than dispatch poll)
+```
+
+**Why a separate cron job?** Reconciliation is read-heavy (fetches current state from external tracker per active task) and less time-sensitive than dispatch. Running it at a slower cadence (60s vs 15s) reduces API load on Linear/GitHub/Jira.
+
+**Agent-cooperative check:** In addition to dispatcher-side reconciliation, agents should also check task state between turns (like Symphony's `continue_with_issue?()` check). This can be added as a standard instruction in the prompt pipeline: "Before starting a new turn, verify your task is still active via the `task` tool."
+
+---
+
+## Updated Component Design
+
+### Component 1: DispatchTracker
+
+Extended from original design with multi-dimensional concurrency, claim management, and state reconstruction.
+
+```typescript
+// trigger/dispatch/dispatch-tracker.ts
+
+export interface DispatchRecord {
+  taskId: string;
+  agentIds: string[];           // Multiple for team dispatch
+  spawnedAt: number;
+  attempt: number;
+  status: "running" | "completed" | "failed" | "retrying" | "blocked";
+  project?: string;
+  tracker?: string;
+  role?: string;
+  tags?: string[];
+  claimantId: string;
+  workspacePath?: string;
+}
+
+export interface DispatchTracker {
+  track(record: Omit<DispatchRecord, "spawnedAt" | "status">): void;
+  complete(taskId: string): void;
+  fail(taskId: string, error?: string): void;
+  updateStatus(taskId: string, status: DispatchRecord["status"]): void;
+  getRetryReady(): RetryEntry[];
+  isTracked(taskId: string): boolean;
+  findTaskForAgent(agentId: string): string | undefined;
+
+  // Concurrency queries
+  activeCount(): number;
+  activeByProject(project: string): number;
+  activeByTracker(tracker: string): number;
+  activeByRole(role: string): number;
+  activeByTag(tag: string): number;
+  availableSlots(config: ConcurrencyConfig, task?: TaskRecord): number;
+
+  // Observability
+  listActive(): DispatchRecord[];
+  listRetries(): RetryEntry[];
+
+  // Reconstruction
+  reconstructFromTasks(tasks: TaskRecord[], claimantId: string): void;
+}
+```
+
+**Reconstruction on boot:** When the dispatcher starts, it queries opentasks for all tasks claimed by this instance's `claimantId` that are still `in_progress`. These become the initial `active` set. This handles process restarts without losing track of running agents.
+
+### Component 2: TaskDispatch Routing Strategy
+
+Updated to support push/pull/hybrid modes, team dispatch, eligibility checking, and atomic claiming.
+
+```typescript
+// trigger/strategies/task-dispatch.ts
+
+export interface TaskDispatchStrategyDeps {
+  tasksAdapter: TasksAdapter;
+  tracker: DispatchTracker;
+  agentManager: AgentManager;
+  teamManager?: TeamManagerV2;      // Optional, for team dispatch
+  promptPipeline: PromptPipeline;
+  eligibility: EligibilityChecker;
+}
+
+export interface TaskDispatchStrategyConfig {
+  mode: DispatchMode;
+  concurrency: ConcurrencyConfig;
+  retry: RetryConfig;
+  claimantId: string;
+  push?: { defaultRole: string; tags?: string[] };
+  pull?: PullModeConfig;
+  hybrid?: HybridConfig;
+}
+```
+
+### Component 3: Dispatch Lifecycle Listener
+
+Updated to use `onLifecycleEvent()` + inbox signal filter (see §7 above).
+
+### Component 4: Reconciliation Strategy
+
+New component (see §10 above).
+
+---
+
+## Configuration
+
+Full dispatch config:
+
+```yaml
+dispatch:
+  enabled: true
+
+  mode: push                     # push | pull | hybrid
+
+  poll:
+    intervalMs: 15000            # Dispatch poll cadence
+
+  reconcile:
+    enabled: true
+    intervalMs: 60000            # External state check cadence
+
+  concurrency:
+    global: 10
+    perProject: { backend: 5 }
+    perTracker: { linear: 8 }
+    perRole: { worker: 8 }
+    perTag: { gpu: 1 }
+
+  retry:
+    maxRetries: 3
+    baseDelayMs: 10000
+    maxDelayMs: 300000
+    workspaceStrategy: reuse     # reuse | fresh | branch
+    preserveOnExhaustion: true
+    cleanupDelayMs: 300000
+
+  eligibility:
+    tags: [auto]
+    excludeTags: [manual]
+    minPriority: 2
+    minScore: 0.3
+    requireFields: [description]
+    agentTriage:
+      enabled: false
+      role: triage
+      minScoreForTriage: 0.3
+      maxScoreForTriage: 0.7
+
+  prompt:
+    stages: [task-core, retry-context, role-prompt]
+    # Add "playbook" to include cognitive-core context
+
+  push:
+    defaultRole: worker
+
+  pull:
+    poolSize: 3
+    workerRole: worker
+    idleTimeoutMs: 300000
+    workerLoop: true
+
+  hybrid:
+    pushPriorityThreshold: 3
+```
+
+---
+
+## What This Reuses (Not New)
+
+| Concern | Existing Component | How Dispatch Uses It |
+|---|---|---|
+| Scheduling | CronService | `every` jobs for poll + reconcile |
+| Routing | TriggerRouter + RoutingStrategy | Two strategies (dispatch + reconcile) |
+| Agent spawn | AgentManagerV2.spawn() | Parentless root agents |
+| Team spawn | TeamManagerV2.startTeam() | Team-aware dispatch |
+| Workspace isolation | WorkspaceManager | createWorkspaceForRole() called by spawn |
+| Task state | TasksAdapter + opentasks | Atomic claim, transition, release |
+| Lifecycle events | onLifecycleEvent() | Agent stopped → update tracker |
+| Inbox signals | addSignalFilter() | WORKER_DONE, HELP_NEEDED observation |
+| Event delivery | SystemEventQueue + WakeManager | Cron → event → route → dispatch |
+
+## What This Adds
+
+| File | ~Lines | Purpose |
+|---|---|---|
+| `trigger/dispatch/dispatch-tracker.ts` | 200 | Multi-dimensional concurrency + retry + reconstruction |
+| `trigger/strategies/task-dispatch.ts` | 200 | Routing strategy (push/pull/hybrid + eligibility) |
+| `trigger/strategies/task-reconcile.ts` | 80 | External state reconciliation |
+| `trigger/dispatch/dispatch-lifecycle.ts` | 80 | Lifecycle + signal listener |
+| `trigger/dispatch/eligibility.ts` | 120 | Scoring + filtering + triage |
+| `trigger/dispatch/prompt-pipeline.ts` | 100 | Composable prompt assembly |
+| `trigger/dispatch/types.ts` | 80 | All dispatch-specific types |
+| Boot wiring | 40 | Opt-in init |
+| **Total** | **~900** | |
+
+## What Needs to Change in Opentasks
+
+| Change | Scope | Purpose |
+|---|---|---|
+| Atomic `claim` operation | opentasks daemon | Prevent TOCTOU race in multi-instance |
+| Claim TTL + heartbeat renewal | opentasks daemon | Auto-release on instance crash |
+| `TaskContext` extension | opentasks schema | Richer task metadata for prompts |
+| `releaseClaim` operation | opentasks daemon | Explicit claim release on completion |
+
+## Comparison to Symphony
+
+| Feature | Symphony | This Design |
+|---|---|---|
+| Polling | GenServer tick | CronService `every` job |
+| Dispatch | Orchestrator.dispatch | TaskDispatch routing strategy |
+| Workspace isolation | Per-issue directory + git clone | WorkspaceManager worktrees |
+| Retry | In-orchestrator backoff queue | DispatchTracker retry map |
+| Concurrency | max_concurrent_agents | Multi-dimensional (global/project/tracker/role/tag) |
+| Agent hierarchy | None (flat) | None (parentless root agents) |
+| Reconciliation | In tick loop, checks Linear | Separate reconcile cron, checks opentasks |
+| Multi-instance | Disjoint issue sets via Linear assignee | Atomic claims + TTL in opentasks |
+| Agent runtime | Codex only | Any AgentFactory (Claude Code, Codex, etc.) |
+| Configuration | WORKFLOW.md (single file) | macro-agent config (composable) |
+| Observability | Phoenix LiveView dashboard | MAP protocol events |
+| Task source | Linear only | Any tracker via opentasks federation |
+| Memory/learning | None | cognitive-core + minimem (opt-in) |
+| Team dispatch | No | Yes (openteams templates) |
+| Push/pull | Push only | Push, pull, or hybrid |
+| Task eligibility | None (all active issues) | Configurable filters + scoring + AI triage |