Symphony -- Stage 3 Expansion: Multi-Agent Architecture

packages/
  agent-adapters/                   # REPLACES codex-client/
    package.json                    # deps: @anthropic-ai/claude-agent-sdk, gray-matter
    tsconfig.json
    src/
      index.ts                      # Public API barrel export
      interface.ts                  # AgentAdapter interface + event types
      factory.ts                    # createAdapter(kind) factory function
      event-normalizer.ts           # Maps agent-specific events to AgentEvent
      approval-router.ts            # Central approval policy engine
      session-registry.ts           # Maps symphonyRunId -> { agentKind, agentSessionId }

      adapters/
        claude.ts                   # Claude Code adapter via @anthropic-ai/claude-agent-sdk
        codex.ts                    # Codex adapter via app-server JSON-RPC
        gemini.ts                   # Gemini CLI adapter (subprocess MVP, ACP future)

      mappings/
        claude-events.ts            # Claude message types -> AgentEvent
        codex-events.ts             # Codex notification types -> AgentEvent
        gemini-events.ts            # Gemini NDJSON types -> AgentEvent
        approval-modes.ts           # ApprovalMode -> agent-specific flags

      types/
        claude-types.ts             # Types from claude-agent-sdk (re-exported for clarity)
        codex-types.ts              # Types from codex app-server generate-ts
        gemini-types.ts             # Manually defined types for Gemini stream-json

      __tests__/
        interface.test.ts           # Type-level tests (verify exhaustiveness)
        factory.test.ts             # Factory returns correct adapter
        claude-events.test.ts       # Event mapping correctness
        codex-events.test.ts
        gemini-events.test.ts
        claude.integration.test.ts  # Real Claude subprocess
        codex.integration.test.ts   # Real Codex app-server
        gemini.integration.test.ts  # Real Gemini subprocess

  linear-client/                    # UNCHANGED
  workspace-manager/                # UNCHANGED (minor: reconciler becomes agent-agnostic)
  state-machine/                    # UPDATED (IssueState stores agentKind)
  prompt-renderer/                  # UPDATED (WORKFLOW.md agent config parsing)
  metrics/                          # UPDATED (labels include agent kind)
  logger/                           # UNCHANGED

symphony-daemon
  |-- linear-client              (polls/receives issues)
  |-- state-machine              (owns per-issue lifecycle)
  |     |-- agent-adapters       (REPLACES codex-client)
  |     |     |-- claude.ts      (spawns Claude Code sessions)
  |     |     |-- codex.ts       (spawns Codex sessions)
  |     |     +-- gemini.ts      (spawns Gemini sessions)
  |     |-- workspace-manager    (isolates filesystem)
  |     |-- prompt-renderer      (renders WORKFLOW.md)
  |     +-- logger
  |-- metrics                    (instruments everything, labels by agent kind)
  +-- logger

{
  "name": "@symphony/agent-adapters",
  "version": "0.1.0",
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.3.0"
  },
  "devDependencies": {
    "bun-types": "latest"
  }
}

// packages/agent-adapters/src/interface.ts

/** Agent identity */
export type AgentKind = "claude" | "gemini" | "codex";

/** Unified approval modes that map to each agent's native system */
export type ApprovalMode =
  | "ask"           // Every tool requires approval
  | "auto-edit"     // Auto-approve file edits, ask for commands
  | "auto-all"      // Auto-approve everything (Claude: bypassPermissions, Gemini: yolo, Codex: dangerFullAccess)
  | "read-only";    // No writes (Claude: plan, Gemini: plan, Codex: readOnly sandbox)

/** Session configuration passed to initialize() */
export interface SessionConfig {
  cwd: string;
  model?: string;
  approvalMode: ApprovalMode;
  systemPrompt?: string;
  mcpServers?: Record<string, McpServerConfig>;
  allowedTools?: string[];
  deniedTools?: string[];
  maxBudgetUsd?: number;           // Claude only -- ignored by others
  maxTurns?: number;
  env?: Record<string, string>;
  timeoutMs?: number;              // Per-session timeout (all agents)
}

/** Unified events emitted by all agent adapters */
export type AgentEvent =
  | { type: "session_start"; sessionId: string; agent: AgentKind }
  | { type: "text_delta"; text: string; sessionId: string }
  | { type: "text_complete"; text: string; sessionId: string }
  | { type: "tool_start"; toolName: string; toolId: string; input: unknown }
  | { type: "tool_result"; toolId: string; output: string; exitCode?: number }
  | { type: "approval_request"; requestId: string; toolName: string; input: unknown; reason?: string }
  | { type: "file_change"; filePath: string; diff: string }
  | { type: "error"; message: string; code?: string; recoverable: boolean }
  | { type: "turn_complete"; turnId: string; status: "completed" | "interrupted" | "failed" }
  | { type: "session_end"; sessionId: string; usage: UsageInfo }
  | { type: "reasoning"; summary: string }
  | { type: "plan_update"; steps: PlanStep[] };

export interface UsageInfo {
  inputTokens: number;
  outputTokens: number;
  totalCostUsd?: number;           // Claude provides this; Codex/Gemini may not
  durationMs: number;
}

export interface PlanStep {
  id: string;
  description: string;
  status: "pending" | "in_progress" | "completed" | "failed";
}

export type ApprovalResponse =
  | { action: "accept" }
  | { action: "accept_session" }
  | { action: "deny"; reason?: string }
  | { action: "cancel" };

export interface McpServerConfig {
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

/** Resume capabilities vary by agent */
export interface ResumeCapability {
  /** Whether the agent supports session resume at all */
  canResume: boolean;
  /** Whether resume preserves full context (true) or requires context re-injection (false) */
  fullContextRestore: boolean;
  /** The native identifier type used for resume */
  identifierType: "uuid" | "thread_id" | "index" | "none";
}

/**
 * The core adapter interface.
 *
 * Each agent (Claude, Gemini, Codex) implements this interface.
 * The orchestrator never calls agent-specific methods -- it only
 * uses this interface. This is the single most important contract
 * in the multi-agent expansion.
 */
export interface AgentAdapter {
  readonly kind: AgentKind;
  readonly resumeCapability: ResumeCapability;

  initialize(config: SessionConfig): Promise<void>;

  startSession(opts: {
    resumeId?: string;
    forkFrom?: string;
    prompt?: string;
  }): Promise<string>;

  sendPrompt(
    sessionId: string,
    prompt: string,
  ): AsyncIterable<AgentEvent>;

  respondToApproval(
    sessionId: string,
    requestId: string,
    response: ApprovalResponse,
  ): Promise<void>;

  interrupt(sessionId: string): Promise<void>;

  endSession(sessionId: string): Promise<UsageInfo>;

  isAlive(): boolean;

  shutdown(): Promise<void>;
}

// packages/agent-adapters/src/adapters/claude.ts
import { ClaudeSDKClient, ClaudeAgentOptions } from "@anthropic-ai/claude-agent-sdk";
import type { AgentAdapter, SessionConfig, AgentEvent, ApprovalResponse, UsageInfo, ResumeCapability } from "../interface";
import { mapClaudeMessage } from "../mappings/claude-events";
import { mapApprovalMode } from "../mappings/approval-modes";

export class ClaudeAdapter implements AgentAdapter {
  readonly kind = "claude" as const;
  readonly resumeCapability: ResumeCapability = {
    canResume: true,
    fullContextRestore: true,
    identifierType: "uuid",
  };

  private client: ClaudeSDKClient | null = null;
  private config: SessionConfig | null = null;
  private currentSessionId: string | null = null;
  private alive = false;

  async initialize(config: SessionConfig): Promise<void> {
    this.config = config;

    const options: ClaudeAgentOptions = {
      permissionMode: mapApprovalMode("claude", config.approvalMode),
      cwd: config.cwd,
      model: config.model,
      allowedTools: config.allowedTools,
      disallowedTools: config.deniedTools,
      maxTurns: config.maxTurns,
      maxBudgetUsd: config.maxBudgetUsd,
      includePartialMessages: true,
      env: config.env,
    };

    // MCP servers configuration
    if (config.mcpServers) {
      options.mcpServers = Object.fromEntries(
        Object.entries(config.mcpServers).map(([name, cfg]) => [
          name,
          { type: "stdio" as const, command: cfg.command, args: cfg.args, env: cfg.env },
        ])
      );
    }

    // Custom approval handler that emits approval_request events
    // The orchestrator's ApprovalRouter resolves these
    options.canUseTool = async (toolName, inputData, context) => {
      // This callback is invoked by the SDK when a tool needs approval.
      // We emit an approval_request event, and the orchestrator responds
      // via respondToApproval(), which resolves the pending promise.
      // Implementation deferred to the approval routing section below.
      return this.approvalBridge.waitForDecision(toolName, inputData);
    };

    this.client = new ClaudeSDKClient(options);
    this.alive = true;
  }

  async startSession(opts: { resumeId?: string; prompt?: string }): Promise<string> {
    if (!this.client) throw new Error("Claude adapter not initialized");

    if (opts.resumeId) {
      // Claude Code resume: --resume <session_id>
      // The SDK supports this via session continuation
      await this.client.resume(opts.resumeId);
      this.currentSessionId = opts.resumeId;
    } else if (opts.prompt) {
      // Start new session with initial prompt
      await this.client.query(opts.prompt);
      // Session ID is extracted from the init SystemMessage
      this.currentSessionId = this.client.sessionId;
    }

    return this.currentSessionId!;
  }

  async *sendPrompt(sessionId: string, prompt: string): AsyncIterable<AgentEvent> {
    if (!this.client) throw new Error("Claude adapter not initialized");

    await this.client.query(prompt);
    for await (const msg of this.client.receiveResponse()) {
      const event = mapClaudeMessage(msg, sessionId);
      if (event) yield event;
    }
  }

  async respondToApproval(sessionId: string, requestId: string, response: ApprovalResponse): Promise<void> {
    this.approvalBridge.resolve(requestId, response);
  }

  async interrupt(sessionId: string): Promise<void> {
    await this.client?.interrupt();
  }

  async endSession(sessionId: string): Promise<UsageInfo> {
    // Claude SDK provides usage in the final ResultMessage
    const result = this.client?.lastResult;
    return {
      inputTokens: result?.usage?.input_tokens ?? 0,
      outputTokens: result?.usage?.output_tokens ?? 0,
      totalCostUsd: result?.total_cost_usd,
      durationMs: result?.duration_ms ?? 0,
    };
  }

  isAlive(): boolean { return this.alive; }

  async shutdown(): Promise<void> {
    await this.client?.close();
    this.alive = false;
  }
}

// packages/agent-adapters/src/adapters/codex.ts
import type { AgentAdapter, SessionConfig, AgentEvent, ApprovalResponse, UsageInfo, ResumeCapability } from "../interface";
import { mapCodexNotification } from "../mappings/codex-events";
import { mapApprovalMode } from "../mappings/approval-modes";

export class CodexAdapter implements AgentAdapter {
  readonly kind = "codex" as const;
  readonly resumeCapability: ResumeCapability = {
    canResume: true,
    fullContextRestore: true,     // thread/resume replays all RolloutItems
    identifierType: "thread_id",
  };

  private proc: import("bun").Subprocess | null = null;
  private abortController: AbortController | null = null;
  private requestCounter = 0;
  private pendingResponses = new Map<string, { resolve: Function; reject: Function; timer: Timer }>();
  private config: SessionConfig | null = null;
  private initialized = false;

  async initialize(config: SessionConfig): Promise<void> {
    this.config = config;
    this.abortController = new AbortController();

    this.proc = Bun.spawn(["codex", "app-server"], {
      stdin: "pipe",
      stdout: "pipe",
      stderr: "pipe",
      signal: this.abortController.signal,
      env: { ...process.env, ...config.env },
    });

    // Phase 1: Send initialize request
    const initResult = await this.sendRequest("initialize", {
      clientInfo: { name: "symphony", title: "Symphony Orchestrator", version: "0.1.0" },
      capabilities: { experimentalApi: true },
    });

    // Phase 2: Send initialized notification (no response expected)
    this.sendNotification("initialized", {});
    this.initialized = true;
  }

  async startSession(opts: { resumeId?: string; prompt?: string }): Promise<string> {
    if (!this.initialized) throw new Error("Codex adapter not initialized");

    if (opts.resumeId) {
      // thread/resume: replays all RolloutItems from [home-path]
      const result = await this.sendRequest("thread/resume", { threadId: opts.resumeId });
      return opts.resumeId;
    }

    // thread/start creates a new thread
    const result = await this.sendRequest("thread/start", {});
    return result.thread.id;
  }

  async *sendPrompt(sessionId: string, prompt: string): AsyncIterable<AgentEvent> {
    // turn/start begins a turn within the thread
    await this.sendRequest("turn/start", {
      threadId: sessionId,
      input: [{ type: "text", text: prompt }],
      cwd: this.config!.cwd,
      model: this.config!.model ?? "o4-mini",
      approvalPolicy: mapApprovalMode("codex", this.config!.approvalMode),
      sandboxPolicy: {
        type: "workspaceWrite",
        writableRoots: [this.config!.cwd],
        networkAccess: true,
      },
    });

    // Consume notifications until turn/completed
    for await (const notification of this.readNotifications()) {
      const event = mapCodexNotification(notification, sessionId);
      if (event) yield event;
      if (notification.method === "turn/completed") break;
    }
  }

  async respondToApproval(sessionId: string, requestId: string, response: ApprovalResponse): Promise<void> {
    // Codex sends approval as a JSON-RPC request with an id.
    // We respond to that request with the approval decision.
    const pending = this.pendingResponses.get(requestId);
    if (!pending) throw new Error(`No pending approval for requestId: ${requestId}`);

    const codexResponse = response.action === "accept" || response.action === "accept_session"
      ? { decision: response.action === "accept_session" ? "acceptForSession" : "accept" }
      : { decision: "decline", reason: response.action === "deny" ? response.reason : undefined };

    pending.resolve(codexResponse);
  }

  async interrupt(sessionId: string): Promise<void> {
    // Graceful: send turn/interrupt first
    try {
      await this.sendRequest("turn/interrupt", { threadId: sessionId });
    } catch {
      // If interrupt fails, hard kill via AbortController
      this.abortController?.abort();
    }
  }

  async endSession(sessionId: string): Promise<UsageInfo> {
    await this.sendNotification("thread/unsubscribe", { threadId: sessionId });
    return {
      inputTokens: this.accumulatedUsage.inputTokens,
      outputTokens: this.accumulatedUsage.outputTokens,
      durationMs: Date.now() - this.sessionStartTime,
    };
  }

  isAlive(): boolean {
    return this.proc !== null && !this.proc.killed;
  }

  async shutdown(): Promise<void> {
    this.abortController?.abort();
    for (const [, pending] of this.pendingResponses) {
      clearTimeout(pending.timer);
      pending.reject(new Error("Adapter shutdown"));
    }
    this.pendingResponses.clear();
  }

  // --- Private transport methods ---

  private async sendRequest(method: string, params: unknown): Promise<any> {
    const id = String(++this.requestCounter);
    const msg = JSON.stringify({ method, id, params }) + "\n";
    this.proc!.stdin.write(msg);
    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => reject(new Error(`RPC timeout: ${method}`)), 30_000);
      this.pendingResponses.set(id, { resolve, reject, timer });
    });
  }

  private sendNotification(method: string, params: unknown): void {
    const msg = JSON.stringify({ method, params }) + "\n";
    this.proc!.stdin.write(msg);
  }

  private async *readNotifications(): AsyncGenerator<any> {
    const reader = this.proc!.stdout.getReader();
    const decoder = new TextDecoder();
    let buffer = "";

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });

      let idx: number;
      while ((idx = buffer.indexOf("\n")) !== -1) {
        const line = buffer.slice(0, idx).trim();
        buffer = buffer.slice(idx + 1);
        if (!line) continue;

        const msg = JSON.parse(line);
        if ("id" in msg && this.pendingResponses.has(msg.id)) {
          const pending = this.pendingResponses.get(msg.id)!;
          clearTimeout(pending.timer);
          this.pendingResponses.delete(msg.id);
          if (msg.error) pending.reject(msg.error);
          else pending.resolve(msg.result);
        } else if ("method" in msg) {
          // Handle approval requests (these are server-initiated requests with an id)
          if (msg.method.endsWith("/requestApproval") && msg.id) {
            this.pendingResponses.set(msg.id, { /* bridged to respondToApproval */ });
            yield { method: "approval_request", params: msg.params, _rpcId: msg.id };
          } else {
            yield msg;
          }
        }
      }
    }
  }
}

// packages/agent-adapters/src/adapters/gemini.ts
import type { AgentAdapter, SessionConfig, AgentEvent, ApprovalResponse, UsageInfo, ResumeCapability } from "../interface";
import { mapGeminiEvent } from "../mappings/gemini-events";
import { mapApprovalMode } from "../mappings/approval-modes";

export class GeminiAdapter implements AgentAdapter {
  readonly kind = "gemini" as const;
  readonly resumeCapability: ResumeCapability = {
    canResume: false,              // No reliable session persistence for programmatic use
    fullContextRestore: false,
    identifierType: "none",
  };

  private proc: import("bun").Subprocess | null = null;
  private abortController: AbortController | null = null;
  private config: SessionConfig | null = null;
  private sessionCounter = 0;

  async initialize(config: SessionConfig): Promise<void> {
    this.config = config;
    // Gemini adapter does not spawn a persistent process.
    // Each sendPrompt() spawns a new subprocess.
    // This is the correct architecture because Gemini CLI
    // has no daemon mode and no reliable session persistence.
  }

  async startSession(opts: { resumeId?: string; prompt?: string }): Promise<string> {
    if (opts.resumeId) {
      // Gemini has no reliable programmatic resume.
      // The orchestrator must re-inject context via the prompt.
      // The session ID is synthetic -- it does not correspond to
      // any Gemini-internal identifier.
      return `gemini-resumed-${opts.resumeId}`;
    }
    return `gemini-${++this.sessionCounter}-${Date.now()}`;
  }

  async *sendPrompt(sessionId: string, prompt: string): AsyncIterable<AgentEvent> {
    this.abortController = new AbortController();

    const args: string[] = [
      "-p", prompt,
      "--output-format", "stream-json",
      "--approval-mode", mapApprovalMode("gemini", this.config!.approvalMode),
    ];

    if (this.config!.model) args.push("--model", this.config!.model);

    this.proc = Bun.spawn(["gemini", ...args], {
      cwd: this.config!.cwd,
      stdin: "pipe",
      stdout: "pipe",
      stderr: "pipe",
      signal: this.abortController.signal,
      env: { ...process.env, ...this.config!.env },
    });

    yield { type: "session_start", sessionId, agent: "gemini" };

    const reader = this.proc.stdout.getReader();
    const decoder = new TextDecoder();
    let buffer = "";

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });

      let idx: number;
      while ((idx = buffer.indexOf("\n")) !== -1) {
        const line = buffer.slice(0, idx).trim();
        buffer = buffer.slice(idx + 1);
        if (!line) continue;

        try {
          const raw = JSON.parse(line);
          const event = mapGeminiEvent(raw, sessionId);
          if (event) yield event;
        } catch {
          // Malformed JSON line -- skip (known Gemini issue #9009)
        }
      }
    }

    // Check exit code for error classification
    const exitCode = await this.proc.exited;
    if (exitCode === 53) {
      yield { type: "turn_complete", turnId: sessionId, status: "interrupted" }; // turn limit
    } else if (exitCode !== 0) {
      yield { type: "error", message: `Gemini exited with code ${exitCode}`, recoverable: exitCode === 1 };
    }
    yield { type: "turn_complete", turnId: sessionId, status: exitCode === 0 ? "completed" : "failed" };
  }

  async respondToApproval(sessionId: string, requestId: string, response: ApprovalResponse): Promise<void> {
    // In subprocess mode with --approval-mode yolo, no approvals are requested.
    // In future ACP mode, this would send session/request_permission response.
    throw new Error("Gemini subprocess mode does not support interactive approvals. Use auto-all approval mode.");
  }

  async interrupt(sessionId: string): Promise<void> {
    this.abortController?.abort();
  }

  async endSession(sessionId: string): Promise<UsageInfo> {
    return {
      inputTokens: this.accumulatedUsage?.inputTokens ?? 0,
      outputTokens: this.accumulatedUsage?.outputTokens ?? 0,
      durationMs: Date.now() - (this.sessionStartTime ?? Date.now()),
    };
  }

  isAlive(): boolean {
    return this.proc !== null && !this.proc.killed;
  }

  async shutdown(): Promise<void> {
    this.abortController?.abort();
    this.proc = null;
  }
}

// packages/agent-adapters/src/factory.ts
import type { AgentAdapter, AgentKind } from "./interface";
import { ClaudeAdapter } from "./adapters/claude";
import { CodexAdapter } from "./adapters/codex";
import { GeminiAdapter } from "./adapters/gemini";

export function createAdapter(kind: AgentKind): AgentAdapter {
  switch (kind) {
    case "claude": return new ClaudeAdapter();
    case "codex":  return new CodexAdapter();
    case "gemini": return new GeminiAdapter();
    default: {
      const _exhaustive: never = kind;
      throw new Error(`Unknown agent kind: ${kind}`);
    }
  }
}

---
# Agent configuration
agent:
  kind: claude                   # "claude" | "codex" | "gemini"
  model: opus                    # Agent-specific model identifier
  approval_mode: auto-edit       # "ask" | "auto-edit" | "auto-all" | "read-only"
  max_turns: 20                  # Maximum turns within a session
  timeout_ms: 3600000            # 1 hour per-session timeout

  # Per-agent overrides (only the block matching agent.kind is applied)
  claude:
    allowed_tools: ["Read", "Edit", "Bash", "Grep", "Glob"]
    max_budget_usd: 10.0
    thinking: adaptive           # "enabled" | "disabled" | "adaptive"
    effort: high                 # "low" | "medium" | "high" | "max"

  codex:
    approval_policy: auto-approve
    sandbox: full-auto
    effort: medium

  gemini:
    sandbox_mode: relaxed
    extensions: []

# Execution configuration (unchanged from Stage 2)
max_retries: 3
max_retry_backoff_ms: 300000
hooks:
  pre-session: |
    npm install
    npm run build
  post-session: |
    npm run lint --fix
    npm run test

# Fallback chain (new)
fallback:
  enabled: true
  chain: [claude, codex]         # If primary fails, try next in chain
  max_fallback_attempts: 1       # Only try one fallback agent
---

You are working on issue {{ issue_id }}: {{ issue_title }}.
...

// packages/prompt-renderer/src/types.ts
export interface WorkflowConfig {
  agent: {
    kind: AgentKind;
    model?: string;
    approvalMode: ApprovalMode;
    maxTurns: number;
    timeoutMs: number;
    overrides: Record<AgentKind, Record<string, unknown>>;
  };
  maxRetries: number;
  maxRetryBackoffMs: number;
  hooks: { preSession?: string; postSession?: string };
  fallback: { enabled: boolean; chain: AgentKind[]; maxFallbackAttempts: number };
}

// packages/state-machine/src/types.ts
type IssueState =
  | { status: "queued"; enqueuedAt: number; agentKind: AgentKind }
  | { status: "retry_queued"; enqueuedAt: number; retryCount: number; agentKind: AgentKind }
  | { status: "cloning"; startedAt: number; agentKind: AgentKind }
  | { status: "workspace_ready"; workspacePath: string; agentKind: AgentKind }
  | { status: "session_starting"; workspacePath: string; agentSessionId: string; agentKind: AgentKind }
  | { status: "session_active"; workspacePath: string; agentSessionId: string; turnCount: number; pid: number; agentKind: AgentKind }
  | { status: "reconciling"; workspacePath: string; agentSessionId: string; output: SessionOutput; agentKind: AgentKind }
  | { status: "done"; workspacePath: string; prUrl: string | null; completedAt: number; agentKind: AgentKind }
  | { status: "failed"; reason: string; retryCount: number; lastFailedAt: number; agentKind: AgentKind }
  | { status: "released"; releasedAt: number; reason: string; agentKind: AgentKind };

function transition(state: IssueState, event: TransitionEvent): IssueState {
  // agentKind is threaded through -- never branched on
  switch (state.status) {
    case "cloning":
      if (event.type === "clone_complete")
        return { status: "workspace_ready", workspacePath: event.workspacePath, agentKind: state.agentKind };
      // ...
    case "session_active":
      if (event.type === "session_complete")
        return { status: "reconciling", workspacePath: state.workspacePath, agentSessionId: state.agentSessionId, output: event.output, agentKind: state.agentKind };
      // ...
  }
}

CREATE TABLE IF NOT EXISTS issue_runs (
  id TEXT PRIMARY KEY,
  issue_id TEXT NOT NULL,
  issue_identifier TEXT NOT NULL,
  agent_kind TEXT NOT NULL DEFAULT 'codex',   -- NEW: "claude" | "codex" | "gemini"
  agent_session_id TEXT,                       -- RENAMED from thread_id
  state_json TEXT NOT NULL,
  workspace_path TEXT,
  retry_count INTEGER DEFAULT 0,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_issue_runs_status ON issue_runs(json_extract(state_json, '$.status'));
CREATE INDEX IF NOT EXISTS idx_issue_runs_agent ON issue_runs(agent_kind);

ALTER TABLE symphony_runs ADD COLUMN agent_kind TEXT NOT NULL DEFAULT 'codex';
ALTER TABLE symphony_runs RENAME COLUMN thread_id TO agent_session_id;
CREATE INDEX idx_symphony_runs_agent ON symphony_runs(agent_kind);

// services/symphony-daemon/src/recovery.ts
async function recoverSessions(
  store: IssueStore,
  adapterFactory: typeof createAdapter,
): Promise<void> {
  const incomplete = store.recoverIncomplete();

  for (const run of incomplete) {
    const state = JSON.parse(run.state_json) as IssueState;

    if (state.status === "session_active" && state.agentSessionId) {
      const adapter = adapterFactory(state.agentKind);

      switch (state.agentKind) {
        case "codex": {
          // CODEX: thread/resume replays all RolloutItems from
          // [home-path]
          // Full context restored. Zero progress lost.
          logger.info({ runId: run.id, agentSessionId: state.agentSessionId },
            "Recovering Codex session via thread/resume");
          await adapter.initialize(buildConfigForRun(run));
          await adapter.startSession({ resumeId: state.agentSessionId });
          orchestrator.attachRecoveredSession(run.id, adapter);
          break;
        }

        case "claude": {
          // CLAUDE: --resume <session_id> loads from
          // [home-path]
          // Full context restored. Equivalent to Codex thread/resume.
          logger.info({ runId: run.id, agentSessionId: state.agentSessionId },
            "Recovering Claude session via --resume");
          await adapter.initialize(buildConfigForRun(run));
          await adapter.startSession({ resumeId: state.agentSessionId });
          orchestrator.attachRecoveredSession(run.id, adapter);
          break;
        }

        case "gemini": {
          // GEMINI: No reliable session resume.
          // Strategy: re-queue with context injection.
          // The prompt renderer will prepend the previous session's
          // output as "Context from previous attempt" to the new prompt.
          logger.warn({ runId: run.id },
            "Gemini session cannot be resumed -- re-queuing with context injection");
          const contextSummary = await readPreviousOutput(run.workspace_path);
          store.persist(run.id, {
            status: "queued",
            enqueuedAt: Date.now(),
            agentKind: "gemini",
            _recoveryContext: contextSummary,  // Stored in SQLite, injected by prompt renderer
          });
          break;
        }
      }
    } else if (state.status === "cloning" || state.status === "session_starting") {
      // Pre-session: re-queue from scratch for any agent
      store.persist(run.id, { status: "queued", enqueuedAt: Date.now(), agentKind: state.agentKind });
    } else if (state.status === "reconciling") {
      // Post-session: retry reconciliation (agent-agnostic)
      await orchestrator.reconcile(run.id, state);
    }
  }
}

function selectAgent(issue: LinearIssue, workflowConfig: WorkflowConfig): AgentKind {
  // Priority 1: Linear label override (highest priority)
  const agentLabel = issue.labels.find(l => l.startsWith("agent:"));
  if (agentLabel) {
    const kind = agentLabel.split(":")[1] as AgentKind;
    if (["claude", "codex", "gemini"].includes(kind)) return kind;
  }

  // Priority 2: WORKFLOW.md agent.kind (default)
  return workflowConfig.agent.kind;
}

function selectFallbackAgent(
  failedKind: AgentKind,
  workflowConfig: WorkflowConfig,
  fallbackAttemptCount: number,
): AgentKind | null {
  if (!workflowConfig.fallback.enabled) return null;
  if (fallbackAttemptCount >= workflowConfig.fallback.maxFallbackAttempts) return null;

  const chain = workflowConfig.fallback.chain;
  const currentIdx = chain.indexOf(failedKind);
  const nextIdx = currentIdx + 1;

  if (nextIdx >= chain.length) return null;
  return chain[nextIdx];
}

interface ConcurrencyLimits {
  global: number;        // Total across all agents (from symphony.toml max_concurrent_sessions)
  perAgent: Record<AgentKind, number>;
}

// Default limits (configurable in symphony.toml)
const DEFAULT_LIMITS: ConcurrencyLimits = {
  global: 5,
  perAgent: {
    claude: 3,           // Each Claude session is a subprocess (~150MB RSS)
    codex: 2,            // Codex app-server is heavier (~300MB RSS)
    gemini: 3,           // Gemini subprocess is lighter but disk-intensive
  },
};

private drainQueue(): void {
  while (this.activeSessions.size < this.limits.global && this.queue.size > 0) {
    const next = this.queue.peek();
    if (!next || next.enqueuedAt > Date.now()) break;

    const agentCount = this.countActiveSessions(next.agentKind);
    if (agentCount >= this.limits.perAgent[next.agentKind]) {
      // This agent type is at capacity. Skip to next item in queue.
      // (Priority queue may have items for a different agent kind.)
      this.queue.skipHead();
      continue;
    }

    this.queue.dequeue();
    this.spawnSession(next);
  }
}

class AdapterPool {
  private pools: Record<AgentKind, AgentAdapter[]> = {
    claude: [],
    codex: [],
    gemini: [],
  };

  async acquire(kind: AgentKind, config: SessionConfig): Promise<AgentAdapter> {
    // Check for an idle adapter of the correct kind
    const pool = this.pools[kind];
    const idle = pool.find(a => a.isAlive() && !this.isInUse(a));
    if (idle) return idle;

    // Create new adapter
    const adapter = createAdapter(kind);
    await adapter.initialize(config);
    pool.push(adapter);
    return adapter;
  }

  async release(adapter: AgentAdapter): Promise<void> {
    // Mark as available for reuse (Codex) or shutdown (Claude/Gemini subprocess)
    if (adapter.kind === "codex") {
      // Codex app-server persists -- reuse the process for the next session
      return;
    }
    // Claude/Gemini: subprocess-per-session, shutdown after use
    await adapter.shutdown();
    this.pools[adapter.kind] = this.pools[adapter.kind].filter(a => a !== adapter);
  }
}

readonly sessionsActive = this.gauge("symphony_sessions_active", "In-flight sessions", ["agent"]);
readonly sessionsTotal = this.counter("symphony_sessions_total", "Total sessions by outcome", ["outcome", "agent"]);
readonly sessionDuration = this.histogram("symphony_session_duration_seconds", "Wall-clock per session",
  [30, 60, 120, 300, 600, 1200, 1800, 2700], ["agent"]);

// New multi-agent specific metrics
readonly fallbacksTotal = this.counter("symphony_fallbacks_total", "Fallback agent activations", ["from_agent", "to_agent"]);
readonly adapterInitDuration = this.histogram("symphony_adapter_init_ms", "Adapter initialization time", [100, 500, 1000, 3000, 5000], ["agent"]);
readonly resumeSuccess = this.counter("symphony_resume_total", "Session resume attempts", ["agent", "outcome"]);

Issue Triage -> Agent Selection:

  Simple bug fix (< 100 LOC change)
    -> Codex o4-mini (free, fast) or Gemini 2.5 Flash (free, fastest)

  Moderate feature (100-500 LOC, multi-file)
    -> Claude Sonnet (best code quality per dollar) or Codex o4-mini

  Complex architecture (500+ LOC, cross-system)
    -> Claude Opus (highest reasoning quality)

  Large context (needs to read 10+ files, 50K+ tokens of context)
    -> Gemini 2.5 Pro (1M context window, free tier)

  Security-sensitive (auth, payments, encryption)
    -> Claude Opus with read-only mode first, then auto-edit

{% if labels contains "security" %}
  {# Force Claude Opus for security issues #}
{% elsif labels contains "simple-fix" %}
  {# Use cheapest available agent #}
{% endif %}

# New sections for multi-agent support

[agents]
default = "codex"                    # Default agent if WORKFLOW.md does not specify

[agents.claude]
binary = "claude"
max_concurrent = 3
default_model = "sonnet"
max_budget_usd = 10.0

[agents.codex]
binary = "codex"
args = ["app-server"]
max_concurrent = 2
default_model = "o4-mini"

[agents.gemini]
binary = "gemini"
max_concurrent = 3
default_model = "gemini-2.5-pro"

[agents.fallback]
enabled = true
chain = ["codex", "claude"]
max_attempts = 1

                          +-------------------+
                          |   Linear API      |
                          |  (poll / webhook) |
                          +--------+----------+
                                   |
                          +--------v----------+
                          |   LinearClient    |
                          |  (label parser,   |
                          |   agent override) |
                          +--------+----------+
                                   |
                                   v
     +------------------------------------------------------------+
     |                    ORCHESTRATOR                              |
     |                                                              |
     |  selectAgent() --> agentKind                                |
     |  AdapterPool.acquire(kind) --> adapter                      |
     |  drainQueue() respects per-agent concurrency limits         |
     |  handleCompletion() --> reconcile or fallback               |
     |                                                              |
     |  +------------------+  +-----------+  +-------------------+ |
     |  | Promise.race()   |  | Priority  |  | Session           | |
     |  | poll|webhook|done|  | Queue     |  | Completions       | |
     |  +------------------+  +-----------+  +-------------------+ |
     +-----+------------------+------------------+-----------------+
           |                  |                  |
           v                  v                  v
     +-----------+     +-----------+     +-----------+
     |  Claude   |     |  Codex    |     |  Gemini   |
     |  Adapter  |     |  Adapter  |     |  Adapter  |
     |           |     |           |     |           |
     | SDK Client|     | app-server|     | subprocess|
     | subprocess|     | JSON-RPC  |     | stream-json|
     +-----------+     +-----------+     +-----------+
           |                  |                  |
           v                  v                  v
     +-----+------------------+------------------+----+
     |              EVENT NORMALIZER                    |
     |  Claude msg -> AgentEvent                       |
     |  Codex notification -> AgentEvent               |
     |  Gemini NDJSON -> AgentEvent                    |
     +---+-----------+------------+-----------+--------+
         |           |            |           |
         v           v            v           v
     +-------+  +--------+  +---------+  +---------+
     | SQLite|  |Supabase|  |Prometheus|  | Logger  |
     | (local|  | (remote|  | :8601   |  | (JSON)  |
     | truth)|  | truth) |  |         |  |         |
     +-------+  +--------+  +---------+  +---------+