agent-relay 2.3.13 → 2.4.0

package/packages/bridge/src/spawner.ts

@@ -1,2067 +0,0 @@
-/**
- * Agent Spawner
- * Handles spawning and releasing worker agents via relay-pty.
- * Workers run headlessly with output capture for logs.
- */
-
-import fs from 'node:fs';
-import { execFile, execSync } from 'node:child_process';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { sleep, resolveAgentCwd } from './utils.js';
-import { resolveCli } from './cli-resolution.js';
-import { getProjectPaths, getAgentOutboxTemplate } from '@agent-relay/config';
-import { resolveCommand } from '@agent-relay/utils/command-resolver';
-import { createTraceableError } from '@agent-relay/utils/error-tracking';
-import { createLogger } from '@agent-relay/utils/logger';
-import { mapModelToCli } from '@agent-relay/utils/model-mapping';
-import { isModelSwitchSupported, buildModelSwitchCommand, validateModelForCli } from '@agent-relay/utils/model-commands';
-import { findRelayPtyBinary as findRelayPtyBinaryUtil, getLastSearchPaths } from '@agent-relay/utils/relay-pty-path';
-import { RelayPtyOrchestrator, type RelayPtyOrchestratorConfig } from '@agent-relay/wrapper';
-import { OpenCodeWrapper, type OpenCodeWrapperConfig, OpenCodeApi } from '@agent-relay/wrapper';
-import type { SummaryEvent, SessionEndEvent } from '@agent-relay/wrapper';
-import { selectShadowCli } from './shadow-cli.js';
-
-// Get the directory where this module is located (for binary path resolution)
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-import { AgentPolicyService, type CloudPolicyFetcher } from '@agent-relay/policy';
-import { buildClaudeArgs, findAgentConfig } from '@agent-relay/config/agent-config';
-import { composeForAgent, type AgentRole } from '@agent-relay/wrapper';
-import { getUserDirectoryService } from '@agent-relay/user-directory';
-import type {
-  SpawnRequest,
-  SpawnResult,
-  WorkerInfo,
-  SpawnWithShadowRequest,
-  SpawnWithShadowResult,
-  SpeakOnTrigger,
-} from './types.js';
-
-// Logger instance for spawner (uses daemon log system instead of console)
-const log = createLogger('spawner');
-
-function extractGhTokenFromHosts(content: string): string | null {
-  const lines = content.split(/\r?\n/);
-  let inGithubSection = false;
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) {
-      continue;
-    }
-    if (!line.startsWith(' ') && !line.startsWith('\t')) {
-      const host = trimmed.replace(/:$/, '');
-      inGithubSection = host === 'github.com';
-      continue;
-    }
-    if (!inGithubSection) {
-      continue;
-    }
-    const match = line.match(/^\s*(oauth_token|token):\s*(.+)$/);
-    if (!match) {
-      continue;
-    }
-    let token = match[2].split('#')[0].trim();
-    token = token.replace(/^['"]|['"]$/g, '');
-    if (token) {
-      return token;
-    }
-  }
-  return null;
-}
-
-/**
- * Cloud persistence handler interface.
- * Implement this to persist agent session data to cloud storage.
- */
-export interface CloudPersistenceHandler {
-  onSummary: (agentName: string, event: SummaryEvent) => Promise<void>;
-  onSessionEnd: (agentName: string, event: SessionEndEvent) => Promise<void>;
-  /** Optional cleanup method for tests and graceful shutdown */
-  destroy?: () => void;
-}
-
-/** Worker metadata stored in workers.json */
-interface WorkerMeta {
-  name: string;
-  cli: string;
-  task: string;
-  /** Optional team name this agent belongs to */
-  team?: string;
-  /** Optional user ID for per-user credential scoping */
-  userId?: string;
-  spawnedAt: number;
-  pid?: number;
-  logFile?: string;
-  /** Current model if known */
-  model?: string;
-  /** Working directory (repo name) the agent was spawned in */
-  cwd?: string;
-}
-
-/** Stored listener references for cleanup */
-interface ListenerBindings {
-  output?: (data: string) => void;
-  summary?: (event: SummaryEvent) => void;
-  sessionEnd?: (event: SessionEndEvent) => void;
-}
-
-/** Type alias for the wrapper - uses RelayPtyOrchestrator (relay-pty Rust binary) */
-type AgentWrapper = RelayPtyOrchestrator;
-
-interface ActiveWorker extends WorkerInfo {
-  pty: AgentWrapper;
-  logFile?: string;
-  listeners?: ListenerBindings;
-  userId?: string;
-}
-
-/** Callback for agent death notifications */
-export type OnAgentDeathCallback = (info: {
-  name: string;
-  exitCode: number | null;
-  agentId?: string;
-  resumeInstructions?: string;
-  /** Traceable error ID for support lookup */
-  errorId?: string;
-}) => void;
-
-/**
- * Ensure MCP permissions are pre-configured for the given CLI type.
- * This prevents MCP approval prompts from blocking agent initialization.
- *
- * For Claude Code: Creates/updates .claude/settings.local.json with:
- * - enableAllProjectMcpServers: true (auto-approve project MCP servers)
- * - permissions.allow: ["mcp__agent-relay__*"] (pre-approve all agent-relay MCP tools)
- *
- * For Cursor: Creates/updates .cursor/settings.json with MCP permissions
- * For Gemini: Creates/updates .gemini/settings.json with MCP permissions
- * For Windsurf: Creates/updates .windsurf/settings.json with MCP permissions
- * Other CLIs: May use CLI flags instead of config-based permissions
- *
- * @param projectRoot - The project root directory
- * @param cliType - The CLI type (claude, codex, gemini, cursor, etc.)
- * @param debug - Whether to log debug information
- */
-export function ensureMcpPermissions(projectRoot: string, cliType: string, debug = false): void {
-  // Determine settings path based on CLI type
-  interface McpPermissionConfig {
-    settingsDir: string;
-    settingsFile: string;
-    permissionKey?: string; // If different from 'permissions.allow'
-    enableAllKey?: string; // If supports enableAllProjectMcpServers
-    globalSettingsDir?: string; // For global settings that enable project MCP
-  }
-
-  const home = process.env.HOME || '';
-  const configMap: Record<string, McpPermissionConfig> = {
-    claude: {
-      // Use global settings for Claude
-      // enableAllProjectMcpServers enables project-local .mcp.json files
-      settingsDir: path.join(home, '.claude'),
-      settingsFile: 'settings.local.json',
-      permissionKey: 'permissions.allow',
-      enableAllKey: 'enableAllProjectMcpServers',
-    },
-    cursor: {
-      settingsDir: path.join(projectRoot, '.cursor'),
-      settingsFile: 'settings.json',
-      permissionKey: 'permissions.allow',
-    },
-    gemini: {
-      settingsDir: path.join(projectRoot, '.gemini'),
-      settingsFile: 'settings.json',
-      permissionKey: 'permissions.allow',
-    },
-    windsurf: {
-      settingsDir: path.join(projectRoot, '.windsurf'),
-      settingsFile: 'settings.json',
-      permissionKey: 'permissions.allow',
-    },
-    // Codex uses TOML config and --dangerously-bypass-approvals-and-sandbox flag
-    // OpenCode and Droid may not need config-based permissions
-  };
-
-  // Normalize CLI type
-  const normalizedCli = cliType.toLowerCase().replace(/^(claude|codex|gemini|cursor|agent|windsurf).*/, '$1');
-
-  // Map 'agent' (Cursor CLI) to 'cursor'
-  const effectiveCli = normalizedCli === 'agent' ? 'cursor' : normalizedCli;
-
-  const config = configMap[effectiveCli];
-  if (!config) {
-    // CLI doesn't use config-based MCP permissions (uses CLI flags instead)
-    if (debug) log.debug(`CLI ${cliType} uses flag-based permissions, skipping config setup`);
-    return;
-  }
-
-  const settingsPath = path.join(config.settingsDir, config.settingsFile);
-
-  try {
-    // Ensure settings directory exists
-    if (!fs.existsSync(config.settingsDir)) {
-      fs.mkdirSync(config.settingsDir, { recursive: true });
-    }
-
-    // Read existing settings or start fresh
-    let settings: Record<string, unknown> = {};
-    if (fs.existsSync(settingsPath)) {
-      try {
-        const content = fs.readFileSync(settingsPath, 'utf-8');
-        settings = JSON.parse(content);
-      } catch {
-        // Invalid JSON, start fresh
-        settings = {};
-      }
-    }
-
-    // Set enableAllProjectMcpServers if supported (Claude-specific)
-    if (config.enableAllKey && settings[config.enableAllKey] !== true) {
-      settings[config.enableAllKey] = true;
-      if (debug) log.debug(`Setting ${config.enableAllKey}: true`);
-    }
-
-    // Ensure permissions.allow includes agent-relay MCP
-    if (config.permissionKey) {
-      // Parse nested key (e.g., 'permissions.allow')
-      const keyParts = config.permissionKey.split('.');
-      let current: Record<string, unknown> = settings;
-
-      // Navigate/create nested structure
-      for (let i = 0; i < keyParts.length - 1; i++) {
-        const key = keyParts[i];
-        if (!current[key] || typeof current[key] !== 'object') {
-          current[key] = {};
-        }
-        current = current[key] as Record<string, unknown>;
-      }
-
-      // Ensure allow list exists
-      const finalKey = keyParts[keyParts.length - 1];
-      if (!Array.isArray(current[finalKey])) {
-        current[finalKey] = [];
-      }
-      const allowList = current[finalKey] as string[];
-
-      // Add agent-relay MCP permission if not already present
-      // Format: mcp__<serverName>__* approves all tools from that server
-      const agentRelayPermission = 'mcp__agent-relay__*';
-      if (!allowList.includes(agentRelayPermission)) {
-        allowList.push(agentRelayPermission);
-        if (debug) log.debug(`Added MCP permission: ${agentRelayPermission}`);
-      }
-    }
-
-    // Write updated settings
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-    if (debug) log.debug(`MCP permissions configured at ${settingsPath}`);
-  } catch (err) {
-    // Log but don't fail - this is a best-effort optimization
-    log.warn('Failed to pre-configure MCP permissions', {
-      cli: cliType,
-      error: err instanceof Error ? err.message : String(err),
-    });
-  }
-}
-
-/**
- * Get MCP tools reference for spawned agents.
- * Only included when MCP is configured for the project.
- */
-function getMcpToolsReference(): string {
-  return [
-    '## MCP Tools Available',
-    '',
-    'You have access to MCP tools for agent communication (recommended over file protocol):',
-    '- `relay_send(to, message)` - Send message to agent/channel',
-    '- `relay_spawn(name, cli, task)` - Create worker agent',
-    '- `relay_inbox()` - Check your messages',
-    '- `relay_who()` - List online agents',
-    '- `relay_release(name)` - Stop a worker agent',
-    '- `relay_status()` - Check connection status',
-    '',
-  ].join('\n');
-}
-
-/**
- * Get relay protocol instructions for a spawned agent.
- * This provides the agent with the communication protocol it needs to work with the relay.
- *
- * Uses the legacy outbox path (/tmp/relay-outbox/) which is symlinked to workspace paths.
- * This keeps agent instructions simple while supporting workspace isolation.
- *
- * @param agentName - Name of the agent
- * @param options - Configuration options
- * @param options.hasMcp - Whether MCP tools are available (based on .mcp.json existence)
- * @param options.includeWorkflowConventions - Include ACK/DONE workflow conventions (default: false)
- */
-function getRelayInstructions(agentName: string, options: { hasMcp?: boolean; includeWorkflowConventions?: boolean } = {}): string {
-  const { hasMcp = false, includeWorkflowConventions = false } = options;
-  // Get the outbox path template and replace variable with actual agent name
-  const outboxBase = getAgentOutboxTemplate(agentName);
-
-  const parts: string[] = [
-    '# Agent Relay Protocol',
-    '',
-    `You are agent "${agentName}" connected to Agent Relay for multi-agent coordination.`,
-    '',
-  ];
-
-  // Add MCP tools reference if available
-  if (hasMcp) {
-    parts.push(getMcpToolsReference());
-  }
-
-  parts.push(
-    '## Sending Messages',
-    '',
-    'Write a file to your outbox, then output the trigger:',
-    '',
-    '```bash',
-    `cat > ${outboxBase}/msg << 'EOF'`,
-    'TO: TargetAgent',
-    '',
-    'Your message here.',
-    'EOF',
-    '```',
-    '',
-    'Then output: `->relay-file:msg`',
-  );
-
-  // Only include ACK/DONE workflow conventions if explicitly requested
-  if (includeWorkflowConventions) {
-    parts.push(
-      '',
-      '## Communication Rules',
-      '',
-      '1. **ACK immediately** - When you receive a task:',
-      '```bash',
-      `cat > ${outboxBase}/ack << 'EOF'`,
-      'TO: Sender',
-      '',
-      'ACK: Brief description of task received',
-      'EOF',
-      '```',
-      'Then: `->relay-file:ack`',
-      '',
-      '2. **Report completion** - When done:',
-      '```bash',
-      `cat > ${outboxBase}/done << 'EOF'`,
-      'TO: Sender',
-      '',
-      'DONE: Brief summary of what was completed',
-      'EOF',
-      '```',
-      'Then: `->relay-file:done`',
-    );
-  }
-
-  parts.push(
-    '',
-    '## Message Format',
-    '',
-    '```',
-    'TO: Target',
-    'THREAD: optional-thread',
-    '',
-    'Message body (everything after blank line)',
-    '```',
-    '',
-    '| TO Value | Behavior |',
-    '|----------|----------|',
-    '| `AgentName` | Direct message |',
-    '| `*` | Broadcast to all |',
-    '| `#channel` | Channel message |',
-  );
-
-  return parts.join('\n');
-}
-
-/**
- * Check if the relay-pty binary is available.
- * Returns the path to the binary if found, null otherwise.
- * Uses shared utility from @agent-relay/utils.
- */
-function findRelayPtyBinary(): string | null {
-  return findRelayPtyBinaryUtil(__dirname);
-}
-
-/** Cached result of relay-pty binary check */
-let relayPtyBinaryPath: string | null | undefined;
-let relayPtyBinaryChecked = false;
-
-/**
- * Check if relay-pty binary is available (cached).
- * Returns true if the binary exists, false otherwise.
- */
-function hasRelayPtyBinary(): boolean {
-  if (!relayPtyBinaryChecked) {
-    relayPtyBinaryPath = findRelayPtyBinary();
-    relayPtyBinaryChecked = true;
-    if (process.env.DEBUG_SPAWN === '1') {
-      if (relayPtyBinaryPath) {
-        log.debug(`relay-pty binary found: ${relayPtyBinaryPath}`);
-      } else {
-        log.debug('relay-pty binary not found, will use PtyWrapper fallback');
-      }
-    }
-  }
-  return relayPtyBinaryPath !== null;
-}
-
-/** Options for AgentSpawner constructor */
-export interface AgentSpawnerOptions {
-  projectRoot: string;
-  /** Explicit socket path for daemon connection (if not provided, derived from projectRoot) */
-  socketPath?: string;
-  /** Explicit team directory for agent registration files (if not provided, derived from projectRoot) */
-  teamDir?: string;
-  tmuxSession?: string;
-  dashboardPort?: number;
-  /**
-   * Callback to mark an agent as spawning (before HELLO completes).
-   * Messages sent to this agent will be queued for delivery after registration.
-   */
-  onMarkSpawning?: (agentName: string) => void;
-  /**
-   * Callback to clear the spawning flag for an agent.
-   * Called when spawn fails or is cancelled.
-   */
-  onClearSpawning?: (agentName: string) => void;
-}
-
-export class AgentSpawner {
-  private static readonly ONLINE_THRESHOLD_MS = 30_000;
-  private activeWorkers: Map<string, ActiveWorker> = new Map();
-  private agentsPath: string;
-  private registryPath: string;
-  private projectRoot: string;
-  private socketPath?: string;
-  private logsDir: string;
-  private workersPath: string;
-  private dashboardPort?: number;
-  private onAgentDeath?: OnAgentDeathCallback;
-  private cloudPersistence?: CloudPersistenceHandler;
-  private policyService?: AgentPolicyService;
-  private policyEnforcementEnabled = false;
-  private onMarkSpawning?: (agentName: string) => void;
-  private onClearSpawning?: (agentName: string) => void;
-
-  /**
-   * Set of agent names currently being spawned.
-   * Prevents race conditions where concurrent spawn requests for the same agent
-   * could both pass the activeWorkers.has() check before either completes.
-   */
-  private spawningAgents: Set<string> = new Set();
-
-  constructor(projectRoot: string, _tmuxSession?: string, dashboardPort?: number);
-  constructor(options: AgentSpawnerOptions);
-  constructor(projectRootOrOptions: string | AgentSpawnerOptions, _tmuxSession?: string, dashboardPort?: number) {
-    // Handle both old and new constructor signatures
-    const options: AgentSpawnerOptions = typeof projectRootOrOptions === 'string'
-      ? { projectRoot: projectRootOrOptions, tmuxSession: _tmuxSession, dashboardPort }
-      : projectRootOrOptions;
-
-    const paths = getProjectPaths(options.projectRoot);
-    this.projectRoot = paths.projectRoot;
-    // Use explicit teamDir if provided (ensures spawner checks same files as daemon)
-    // This is critical in cloud workspaces where detectWorkspacePath may return different paths
-    const effectiveTeamDir = options.teamDir ?? paths.teamDir;
-    // Use connected-agents.json (live socket connections) instead of agents.json (historical registry)
-    // This ensures spawned agents have actual daemon connections for channel message delivery
-    this.agentsPath = path.join(effectiveTeamDir, 'connected-agents.json');
-    this.registryPath = path.join(effectiveTeamDir, 'agents.json');
-
-    // Debug: log path configuration
-    log.info(`AgentSpawner paths: projectRoot=${this.projectRoot} teamDir=${effectiveTeamDir} (explicit=${!!options.teamDir}) agentsPath=${this.agentsPath}`);
-    // Use explicit socketPath if provided (ensures spawned agents connect to same daemon)
-    // Otherwise derive from project paths
-    this.socketPath = options.socketPath ?? paths.socketPath;
-    this.logsDir = path.join(effectiveTeamDir, 'worker-logs');
-    this.workersPath = path.join(effectiveTeamDir, 'workers.json');
-    this.dashboardPort = options.dashboardPort;
-
-    // Store spawn tracking callbacks
-    this.onMarkSpawning = options.onMarkSpawning;
-    this.onClearSpawning = options.onClearSpawning;
-
-    // Ensure logs directory exists
-    fs.mkdirSync(this.logsDir, { recursive: true });
-
-    // Initialize policy service if enforcement is enabled
-    if (process.env.AGENT_POLICY_ENFORCEMENT === '1') {
-      this.policyEnforcementEnabled = true;
-      this.policyService = new AgentPolicyService({
-        projectRoot: this.projectRoot,
-        workspaceId: process.env.WORKSPACE_ID,
-        strictMode: process.env.AGENT_POLICY_STRICT === '1',
-      });
-      log.info('Policy enforcement enabled');
-    }
-
-    // Clean up orphaned relay-pty processes from previous daemon run
-    // This prevents Bug #8 (fails to restart) and Bug #9 (orphaned agents)
-    this.cleanupOrphanedWorkers();
-  }
-
-  /**
-   * Clean up orphaned relay-pty processes from a previous daemon run.
-   * Reads workers.json to find PIDs from the previous session and kills any
-   * that are still running. This ensures a clean slate after daemon restarts.
-   */
-  private cleanupOrphanedWorkers(): void {
-    if (!fs.existsSync(this.workersPath)) {
-      return;
-    }
-
-    try {
-      const raw = JSON.parse(fs.readFileSync(this.workersPath, 'utf-8'));
-      const workers: WorkerMeta[] = Array.isArray(raw?.workers) ? raw.workers : [];
-
-      if (workers.length === 0) {
-        return;
-      }
-
-      log.info(`Checking for orphaned workers from previous run (${workers.length} entries)`);
-      let orphansKilled = 0;
-
-      for (const worker of workers) {
-        if (!worker.pid) {
-          continue;
-        }
-
-        // Check if process is still running
-        let isRunning = false;
-        try {
-          process.kill(worker.pid, 0); // Signal 0 checks existence without killing
-          isRunning = true;
-        } catch {
-          // Process not running - that's fine
-        }
-
-        if (isRunning) {
-          // Verify it's a relay-pty process before killing
-          try {
-            const psOutput = execSync(`ps -p ${worker.pid} -o comm= 2>/dev/null || true`, {
-              encoding: 'utf-8',
-              timeout: 1000,
-            }).trim();
-
-            // Only kill if it's a relay-pty process or the CLI we spawned
-            if (psOutput.includes('relay-pty') || psOutput.includes(worker.cli)) {
-              log.warn(`Killing orphaned worker "${worker.name}" (PID: ${worker.pid})`);
-
-              // Try graceful termination first
-              try {
-                process.kill(worker.pid, 'SIGTERM');
-              } catch {
-                // Already dead or permission denied
-              }
-
-              // Give it a moment to exit gracefully
-              const pid = worker.pid; // Capture for closure
-              setTimeout(() => {
-                try {
-                  process.kill(pid, 0);
-                  // Still running - force kill
-                  process.kill(pid, 'SIGKILL');
-                  log.warn(`Force killed orphaned worker "${worker.name}" (PID: ${pid})`);
-                } catch {
-                  // Already dead - good
-                }
-              }, 500);
-
-              orphansKilled++;
-            } else {
-              log.debug(`PID ${worker.pid} is running but not relay-pty (${psOutput}), skipping`);
-            }
-          } catch (err) {
-            // ps command failed - be conservative and don't kill
-            log.debug(`Could not verify PID ${worker.pid}, skipping: ${err}`);
-          }
-        }
-      }
-
-      // Clear workers.json to start fresh
-      fs.writeFileSync(this.workersPath, JSON.stringify({ workers: [] }, null, 2));
-
-      if (orphansKilled > 0) {
-        log.info(`Cleaned up ${orphansKilled} orphaned worker(s) from previous run`);
-      }
-    } catch (err) {
-      log.warn(`Failed to clean up orphaned workers: ${err}`);
-    }
-  }
-
-  /**
-   * Set cloud policy fetcher for workspace-level policies
-   */
-  setCloudPolicyFetcher(fetcher: CloudPolicyFetcher): void {
-    if (this.policyService) {
-      // Recreate policy service with cloud fetcher
-      this.policyService = new AgentPolicyService({
-        projectRoot: this.projectRoot,
-        workspaceId: process.env.WORKSPACE_ID,
-        cloudFetcher: fetcher,
-        strictMode: process.env.AGENT_POLICY_STRICT === '1',
-      });
-    }
-  }
-
-  /**
-   * Get the policy service (for external access to policy checks)
-   */
-  getPolicyService(): AgentPolicyService | undefined {
-    return this.policyService;
-  }
-
-  private async fetchGhTokenFromCloud(): Promise<string | null> {
-    const cloudApiUrl = process.env.CLOUD_API_URL || process.env.AGENT_RELAY_CLOUD_URL;
-    const workspaceId = process.env.WORKSPACE_ID;
-    const workspaceToken = process.env.WORKSPACE_TOKEN;
-
-    if (!cloudApiUrl || !workspaceId || !workspaceToken) {
-      return null;
-    }
-
-    const normalizedUrl = cloudApiUrl.replace(/\/$/, '');
-    const url = `${normalizedUrl}/api/git/token?workspaceId=${encodeURIComponent(workspaceId)}`;
-
-    try {
-      // Use AbortController for timeout (5 seconds - don't block spawning)
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), 5000);
-
-      const response = await fetch(url, {
-        headers: {
-          Authorization: `Bearer ${workspaceToken}`,
-        },
-        signal: controller.signal,
-      });
-
-      clearTimeout(timeoutId);
-
-      if (!response.ok) {
-        log.warn(`Failed to fetch GH token from cloud: ${response.status} ${response.statusText}`);
-        return null;
-      }
-
-      const data = await response.json() as { userToken?: string | null; token?: string | null };
-      return data.userToken || data.token || null;
-    } catch (err) {
-      // Don't log timeout errors loudly - this is expected when cloud is unreachable
-      const message = err instanceof Error ? err.message : String(err);
-      if (message.includes('abort')) {
-        log.info('Cloud API timeout (5s) - using local auth');
-      } else {
-        log.warn('Failed to fetch GH token from cloud', { error: message });
-      }
-      return null;
-    }
-  }
-
-  private resolveGhTokenFromHostsFile(homeDir?: string): string | null {
-    const resolvedHome = homeDir || process.env.HOME;
-    const configHome = process.env.XDG_CONFIG_HOME || (resolvedHome ? path.join(resolvedHome, '.config') : undefined);
-    const candidates = new Set<string>();
-    if (configHome) {
-      candidates.add(path.join(configHome, 'gh', 'hosts.yml'));
-    }
-    if (resolvedHome) {
-      candidates.add(path.join(resolvedHome, '.config', 'gh', 'hosts.yml'));
-    }
-
-    for (const hostPath of candidates) {
-      if (!hostPath || !fs.existsSync(hostPath)) {
-        continue;
-      }
-      try {
-        const content = fs.readFileSync(hostPath, 'utf8');
-        const token = extractGhTokenFromHosts(content);
-        if (token) {
-          return token;
-        }
-      } catch {
-        continue;
-      }
-    }
-
-    return null;
-  }
-
-  private async resolveGhTokenFromGhCli(): Promise<string | null> {
-    // Check common gh CLI installation paths across platforms
-    const ghPathCandidates = [
-      '/usr/bin/gh',                    // Linux package managers
-      '/usr/local/bin/gh',              // Homebrew (Intel Mac), manual install
-      '/opt/homebrew/bin/gh',           // Homebrew (Apple Silicon Mac)
-      '/home/linuxbrew/.linuxbrew/bin/gh', // Linuxbrew
-    ];
-
-    const ghPath = ghPathCandidates.find((p) => fs.existsSync(p));
-    if (!ghPath) {
-      return null;
-    }
-
-    return await new Promise((resolve) => {
-      execFile(ghPath, ['auth', 'token', '--hostname', 'github.com'], { timeout: 5000 }, (err, stdout) => {
-        if (err) {
-          resolve(null);
-          return;
-        }
-        const token = stdout.trim();
-        resolve(token || null);
-      });
-    });
-  }
-
-  /**
-   * Resolve GitHub token using multiple fallback sources.
-   *
-   * Fallback order (same as git-credential-relay for consistency):
-   * 1. Environment - GH_TOKEN or GITHUB_TOKEN (fastest, set by entrypoint)
-   * 2. hosts.yml - gh CLI config file (~/.config/gh/hosts.yml)
-   * 3. gh CLI - execute `gh auth token` command
-   * 4. Cloud API - workspace-scoped token from Nango (requires network)
-   *
-   * Environment is checked first because:
-   * - It's the fastest (no I/O or network)
-   * - The entrypoint pre-fetches and caches GH_TOKEN at startup
-   * - This avoids delays when cloud API is slow/unreachable
-   */
-  private async resolveGhToken(homeDir?: string): Promise<string | null> {
-    // 1. Check environment variables first (fastest - set by entrypoint at startup)
-    const envToken = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
-    if (envToken) {
-      return envToken;
-    }
-
-    // 2. Parse gh CLI hosts.yml config file
-    const hostsToken = this.resolveGhTokenFromHostsFile(homeDir);
-    if (hostsToken) {
-      return hostsToken;
-    }
-
-    // 3. Execute gh CLI if available
-    const cliToken = await this.resolveGhTokenFromGhCli();
-    if (cliToken) {
-      return cliToken;
-    }
-
-    // 4. Try cloud API as last resort (may be slow or unreachable)
-    return await this.fetchGhTokenFromCloud();
-  }
-
-  /**
-   * Set the dashboard port (for nested spawn API calls).
-   * Called after the dashboard server starts and we know the actual port.
-   */
-  setDashboardPort(port: number): void {
-    log.info(`Dashboard port set to ${port} - nested spawns now enabled`);
-    this.dashboardPort = port;
-  }
-
-  /**
-   * Set callback for agent death notifications.
-   * Called when an agent exits unexpectedly (non-zero exit code).
-   */
-  setOnAgentDeath(callback: OnAgentDeathCallback): void {
-    this.onAgentDeath = callback;
-  }
-
-  /**
-   * Set cloud persistence handler for forwarding RelayPtyOrchestrator events.
-   * When set, 'summary' and 'session-end' events from spawned agents
-   * are forwarded to the handler for cloud persistence (PostgreSQL/Redis).
-   *
-   * Note: Enable via RELAY_CLOUD_ENABLED=true environment variable.
-   */
-  setCloudPersistence(handler: CloudPersistenceHandler): void {
-    this.cloudPersistence = handler;
-    log.info('Cloud persistence handler set');
-  }
-
-  /**
-   * Bind cloud persistence event handlers to a RelayPtyOrchestrator.
-   * Returns the listener references for cleanup.
-   */
-  private bindCloudPersistenceEvents(name: string, pty: AgentWrapper): Partial<ListenerBindings> {
-    if (!this.cloudPersistence) return {};
-
-    const summaryListener = async (event: SummaryEvent) => {
-      try {
-        await this.cloudPersistence!.onSummary(name, event);
-      } catch (err) {
-        log.error(`Cloud persistence summary error for ${name}`, { error: err instanceof Error ? err.message : String(err) });
-      }
-    };
-
-    const sessionEndListener = async (event: SessionEndEvent) => {
-      try {
-        await this.cloudPersistence!.onSessionEnd(name, event);
-      } catch (err) {
-        log.error(`Cloud persistence session-end error for ${name}`, { error: err instanceof Error ? err.message : String(err) });
-      }
-    };
-
-    pty.on('summary', summaryListener);
-    pty.on('session-end', sessionEndListener);
-
-    return { summary: summaryListener, sessionEnd: sessionEndListener };
-  }
-
-  /**
-   * Unbind all tracked listeners from a RelayPtyOrchestrator.
-   */
-  private unbindListeners(pty: AgentWrapper, listeners?: ListenerBindings): void {
-    if (!listeners) return;
-
-    if (listeners.output) {
-      pty.off('output', listeners.output);
-    }
-    if (listeners.summary) {
-      pty.off('summary', listeners.summary);
-    }
-    if (listeners.sessionEnd) {
-      pty.off('session-end', listeners.sessionEnd);
-    }
-  }
-
-  /**
-   * Spawn a new worker agent using relay-pty
-   */
-  async spawn(request: SpawnRequest): Promise<SpawnResult> {
-    const { name, cli, task, team, spawnerName, userId, includeWorkflowConventions, interactive, model: modelOverride } = request;
-    const debug = process.env.DEBUG_SPAWN === '1';
-
-    // Validate agent name to prevent path traversal attacks
-    if (name.includes('..') || name.includes('/') || name.includes('\\')) {
-      return {
-        success: false,
-        name,
-        error: `Invalid agent name: "${name}" contains path traversal characters`,
-      };
-    }
-
-    // Check if worker already exists in this spawner
-    if (this.activeWorkers.has(name)) {
-      return {
-        success: false,
-        name,
-        error: `Agent "${name}" is already running. Use a different name or release the existing agent first.`,
-      };
-    }
-
-    // Check if spawn is already in progress for this agent (prevents race conditions)
-    if (this.spawningAgents.has(name)) {
-      return {
-        success: false,
-        name,
-        error: `Agent "${name}" spawn is already in progress. Wait for it to complete or use a different name.`,
-      };
-    }
-
-    // Check if agent is already connected to daemon (prevents duplicate connection storms)
-    if (this.isAgentConnected(name)) {
-      return {
-        success: false,
-        name,
-        error: `Agent "${name}" is already connected to the daemon. Use a different name or wait for the existing agent to disconnect.`,
-      };
-    }
-
-    // Enforce agent limit based on plan (MAX_AGENTS is set by provisioner based on plan)
-    const maxAgents = parseInt(process.env.MAX_AGENTS ?? '', 10) || 10_000;
-    const currentAgentCount = this.activeWorkers.size;
-    if (currentAgentCount >= maxAgents) {
-      log.warn(`Agent limit reached: ${currentAgentCount}/${maxAgents}`);
-      return {
-        success: false,
-        name,
-        error: `Agent limit reached (${currentAgentCount}/${maxAgents}). Upgrade your plan for more agents.`,
-      };
-    }
-
-    // Policy enforcement: check if the spawner is authorized to spawn this agent
-    if (this.policyEnforcementEnabled && this.policyService && spawnerName) {
-      const decision = await this.policyService.canSpawn(spawnerName, name, cli);
-      if (!decision.allowed) {
-        log.warn(`Policy blocked spawn: ${spawnerName} -> ${name}: ${decision.reason}`);
-        return {
-          success: false,
-          name,
-          error: `Policy denied: ${decision.reason}`,
-          policyDecision: decision,
-        };
-      }
-      if (debug) {
-        log.debug(`Policy allowed spawn: ${spawnerName} -> ${name} (source: ${decision.policySource})`);
-      }
-    }
-
-    // Acquire spawn lock - prevents concurrent spawn attempts for same agent name
-    this.spawningAgents.add(name);
-    log.info(`Spawn lock acquired for ${name} (concurrent spawns: ${this.spawningAgents.size})`);
-
-    try {
-      // Parse CLI command and resolve actual command (e.g., cursor -> agent or cursor-agent)
-      const cliParts = cli.split(' ');
-      const rawCommandName = cliParts[0];
-      const commandName = resolveCli(rawCommandName);
-      const args = cliParts.slice(1);
-
-      if (commandName !== rawCommandName && debug) {
-        log.debug(`Mapped CLI '${rawCommandName}' -> '${commandName}'`);
-      }
-
-      // Resolve full path to avoid posix_spawnp failures
-      const command = resolveCommand(commandName);
-      if (debug) log.debug(`Resolved '${commandName}' -> '${command}'`);
-      if (command === commandName && !commandName.startsWith('/')) {
-        // Command wasn't resolved - it might not exist
-        log.warn(`Could not resolve path for '${commandName}', spawn may fail`);
-      }
-
-      // Track the effective model for this spawn.
-      // Model override from spawn request applies to ALL CLIs.
-      // CLI-specific blocks below may refine this (e.g., Claude agent profile lookup).
-      let spawnModel: string | undefined = modelOverride;
-
-      // Pre-configure MCP permissions for all supported CLIs
-      // This creates/updates CLI-specific settings files with agent-relay permissions
-      ensureMcpPermissions(this.projectRoot, commandName, debug);
-
-      // Add auto-accept flags for non-interactive agents (normal spawns, not setup terminals)
-      // When interactive=true (setup flows), we SKIP these flags so users can respond to prompts
-      const isClaudeCli = commandName.startsWith('claude');
-      const isCursorCli = commandName === 'agent' || rawCommandName === 'cursor' || rawCommandName === 'cursor-agent';
-
-      if (!interactive) {
-        // Add --dangerously-skip-permissions for Claude agents
-        if (isClaudeCli && !args.includes('--dangerously-skip-permissions')) {
-          args.push('--dangerously-skip-permissions');
-        }
-
-        // Add --force for Cursor agents (auto-approve tool usage in non-interactive mode)
-        if (isCursorCli && !args.includes('--force')) {
-          args.push('--force');
-        }
-      } else {
-        // Interactive mode: log that we're skipping auto-accept flags
-        if (debug) log.debug(`Interactive mode: skipping auto-accept flags for ${name}`);
-      }
-
-      // Apply agent config (model, --agent flag) from .claude/agents/ if available
-      // This ensures spawned agents respect their profile settings
-      let effectiveModel: string | undefined;
-
-      if (isClaudeCli) {
-        // Get agent config for model tracking and CLI variant selection
-        const agentConfig = findAgentConfig(name, this.projectRoot);
-        const modelFromProfile = agentConfig?.model?.trim();
-
-        // Map model to CLI variant (e.g., 'opus' -> 'claude:opus')
-        // This allows agent profiles to specify model preferences
-        const cliVariant = modelFromProfile
-          ? mapModelToCli(modelFromProfile)
-          : mapModelToCli(); // defaults to claude:sonnet
-
-        // Extract effective model name for logging and tracking
-        // Model override from spawn request takes precedence over agent profile
-        effectiveModel = modelOverride || modelFromProfile || 'opus';
-        spawnModel = effectiveModel;
-
-        // If model override provided, add --model before buildClaudeArgs so it takes precedence
-        if (modelOverride && !args.includes('--model')) {
-          args.push('--model', modelOverride);
-        }
-
-        const configuredArgs = buildClaudeArgs(name, args, this.projectRoot);
-        // Replace args with configured version (includes --model and --agent if found)
-        args.length = 0;
-        args.push(...configuredArgs);
-
-        // Cost tracking: log which model is being used
-        log.info(`Agent ${name}: model=${effectiveModel}, cli=${cli}, variant=${cliVariant}`);
-        if (debug) log.debug(`Applied agent config for ${name}: ${args.join(' ')}`);
-      }
-
-      // Add auto-accept flags for Codex and Gemini (only in non-interactive mode)
-      const isCodexCli = commandName.startsWith('codex');
-      const isGeminiCli = commandName === 'gemini';
-      const isOpenCodeCli = commandName === 'opencode' || rawCommandName === 'opencode';
-
-      if (!interactive) {
-        // Add --dangerously-bypass-approvals-and-sandbox for Codex agents
-        if (isCodexCli && !args.includes('--dangerously-bypass-approvals-and-sandbox')) {
-          args.push('--dangerously-bypass-approvals-and-sandbox');
-        }
-
-        // Add --yolo for Gemini agents (auto-accept all prompts)
-        if (isGeminiCli && !args.includes('--yolo')) {
-          args.push('--yolo');
-        }
-      }
-
-      // Pass model override to non-Claude CLIs via --model flag
-      // Claude handles this separately in its agent config block above
-      if (modelOverride && !isClaudeCli && !args.includes('--model') && !args.includes('-m')) {
-        args.push('--model', modelOverride);
-      }
-
-      // Check if MCP tools are available
-      // Must verify BOTH conditions (matching inbox hook behavior from commit 18bab59):
-      // 1. MCP config exists (user or project scope)
-      // 2. Relay daemon socket is accessible (daemon must be running)
-      // Without both, MCP context would be shown but tools wouldn't work
-      // Use the actual socket path from config (project-local .agent-relay/relay.sock)
-      // or fall back to environment variable
-      const relaySocket = this.socketPath || process.env.RELAY_SOCKET || path.join(this.projectRoot, '.agent-relay', 'relay.sock');
-      const projectMcpConfigPath = path.join(this.projectRoot, '.mcp.json');
-      const hasMcpConfig = fs.existsSync(projectMcpConfigPath);
-      let hasMcp = false;
-      // Check either user-scope or project-scope MCP config
-      if (hasMcpConfig) {
-        try {
-          hasMcp = fs.statSync(relaySocket).isSocket();
-        } catch {
-          // Socket doesn't exist or isn't accessible - daemon not running
-          hasMcp = false;
-        }
-      }
-      if (debug && hasMcp) log.debug(`MCP tools available for ${name} (MCP config found, socket ${relaySocket})`);
-
-      // Inject relay protocol instructions via CLI-specific system prompt
-      let relayInstructions = getRelayInstructions(name, { hasMcp, includeWorkflowConventions });
-
-      // Compose role-specific prompts if agent has a role defined in .claude/agents/
-      const agentConfigForRole = isClaudeCli ? findAgentConfig(name, this.projectRoot) : null;
-      if (agentConfigForRole?.role) {
-        const validRoles: AgentRole[] = ['planner', 'worker', 'reviewer', 'lead', 'shadow'];
-        const role = agentConfigForRole.role.toLowerCase() as AgentRole;
-        if (validRoles.includes(role)) {
-          try {
-            const composed = await composeForAgent(
-              { name, role },
-              this.projectRoot,
-              { taskDescription: task }
-            );
-            if (composed.content) {
-              relayInstructions = `${composed.content}\n\n---\n\n${relayInstructions}`;
-              if (debug) log.debug(`Composed role prompt for ${name} (role: ${role})`);
-            }
-          } catch (err: any) {
-            log.warn(`Failed to compose role prompt for ${name}: ${err.message}`);
-          }
-        }
-      }
-
-      if (isClaudeCli && !args.includes('--append-system-prompt')) {
-        args.push('--append-system-prompt', relayInstructions);
-      } else if (isCodexCli && !args.some(a => a.includes('developer_instructions'))) {
-        args.push('--config', `developer_instructions=${relayInstructions}`);
-      }
-
-      // Codex requires an initial prompt in TTY mode (unlike Claude which waits for input)
-      // Pass the task as the initial prompt, or a generic "ready" message if no task
-      if (isCodexCli) {
-        const initialPrompt = task || 'You are ready. Wait for messages from the relay system.';
-        args.push(initialPrompt);
-      }
-
-      // Cursor requires 'login' subcommand for interactive auth flows (setup terminals)
-      // Unlike Claude/Codex which auto-start auth, Cursor needs explicit 'agent login'
-      if (isCursorCli && interactive && !task) {
-        args.unshift('login');
-      }
-
-      if (debug) log.debug(`Spawning ${name} with: ${command} ${args.join(' ')}`);
-
-      // Create PtyWrapper config
-      // Use dashboardPort for nested spawns (API-based, works in non-TTY contexts)
-      // Fall back to callbacks only if no dashboardPort is not set
-      // Note: Spawned agents CAN spawn sub-workers intentionally - the parser is strict enough
-      // to avoid accidental spawns from documentation text (requires line start, PascalCase, known CLI)
-      // Resolve CWD relative to workspace root (parent of project root)
-      const cwdResult = resolveAgentCwd(this.projectRoot, request.cwd);
-      if ('error' in cwdResult) {
-        return { success: false, name, error: cwdResult.error };
-      }
-      const agentCwd = cwdResult.cwd;
-
-      // Log whether nested spawning will be enabled for this agent
-      log.info(`Spawning ${name}: dashboardPort=${this.dashboardPort || 'none'} (${this.dashboardPort ? 'nested spawns enabled' : 'nested spawns disabled'})`);
-
-      let userEnv: Record<string, string> | undefined;
-      if (userId) {
-        try {
-          const userDirService = getUserDirectoryService();
-          // Initialize provider directories so spawned agents can find credentials
-          userDirService.initializeUserEnvironment(userId);
-          userEnv = userDirService.getUserEnvironment(userId);
-        } catch (err) {
-          log.warn('Failed to resolve user environment, using default', {
-            userId,
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-
-      const mergedUserEnv = { ...(userEnv ?? {}) };
-      if (!mergedUserEnv.GH_TOKEN) {
-        const ghToken = await this.resolveGhToken(userEnv?.HOME);
-        if (ghToken) {
-          mergedUserEnv.GH_TOKEN = ghToken;
-        }
-      }
-      if (Object.keys(mergedUserEnv).length > 0) {
-        userEnv = mergedUserEnv;
-      }
-
-      if (debug) log.debug(`Socket path for ${name}: ${this.socketPath ?? 'undefined'}`);
-
-      // Require relay-pty binary
-      if (!hasRelayPtyBinary()) {
-        const checkedPaths = getLastSearchPaths();
-        const tracedError = createTraceableError('relay-pty binary not found', {
-          agentName: name,
-          cli,
-          callerDir: __dirname,
-          checkedPaths: checkedPaths.slice(0, 5), // First 5 paths for brevity
-          totalPathsChecked: checkedPaths.length,
-          hint: 'Set RELAY_PTY_BINARY env var to override, or reinstall: npm install agent-relay',
-        });
-        log.error(tracedError.logMessage);
-        if (debug) {
-          log.debug('All paths checked for relay-pty binary:');
-          checkedPaths.forEach((p, i) => log.debug(`  ${i + 1}. ${p}`));
-        }
-        return {
-          success: false,
-          name,
-          error: tracedError.userMessage,
-          errorId: tracedError.errorId,
-        };
-      }
-
-      // Common exit handler for both wrapper types
-      const onExitHandler = (code: number) => {
-        if (debug) log.debug(`Worker ${name} exited with code ${code}`);
-
-        // Get the agentId and clean up listeners before removing from active workers
-        const worker = this.activeWorkers.get(name);
-        const agentId = worker?.pty?.getAgentId?.();
-        if (worker?.listeners) {
-          this.unbindListeners(worker.pty, worker.listeners);
-        }
-
-        this.activeWorkers.delete(name);
-        try {
-          this.saveWorkersMetadata();
-        } catch (err) {
-          log.error('Failed to save metadata on exit', { error: err instanceof Error ? err.message : String(err) });
-        }
-
-        // Notify if agent died unexpectedly (non-zero exit)
-        if (code !== 0 && code !== null && this.onAgentDeath) {
-          const crashError = createTraceableError('Agent crashed unexpectedly', {
-            agentName: name,
-            exitCode: code,
-            cli,
-            agentId,
-          });
-          log.error(crashError.logMessage);
-          this.onAgentDeath({
-            name,
-            exitCode: code,
-            agentId,
-            errorId: crashError.errorId,
-            resumeInstructions: agentId
-              ? `To resume this agent's work, use: --resume ${agentId}`
-              : undefined,
-          });
-        }
-      };
-
-      // Common spawn/release handlers
-      const onSpawnHandler = this.dashboardPort ? undefined : async (workerName: string, workerCli: string, workerTask: string, workerCwd?: string) => {
-        if (debug) log.debug(`Nested spawn: ${workerName}`);
-        await this.spawn({
-          name: workerName,
-          cli: workerCli,
-          task: workerTask,
-          cwd: workerCwd,
-          userId,
-        });
-      };
-
-      const onReleaseHandler = this.dashboardPort ? undefined : async (workerName: string) => {
-        if (debug) log.debug(`Release request: ${workerName}`);
-        await this.release(workerName);
-      };
-
-      // Check if we should use OpenCodeWrapper with HTTP API mode
-      if (isOpenCodeCli) {
-        // OpenCodeApi reads OPENCODE_API_URL or OPENCODE_PORT from env, defaults to localhost:4096
-        const openCodeApi = new OpenCodeApi();
-        const serveAvailable = await openCodeApi.isAvailable() || process.env.OPENCODE_HTTP_MODE === '1';
-
-        // In cloud workspaces, auto-start opencode serve if not already running
-        // This keeps the HTTP API internal to the container (localhost:4096, not exposed)
-        const isCloudWorkspace = !!process.env.WORKSPACE_ID;
-        const shouldUseHttpApi = serveAvailable || isCloudWorkspace;
-
-        if (shouldUseHttpApi) {
-          if (debug) log.debug(`OpenCode: serve=${serveAvailable ? 'available' : 'will-auto-start'}, cloud=${isCloudWorkspace}, using OpenCodeWrapper for ${name}`);
-
-          const openCodeConfig: OpenCodeWrapperConfig = {
-            name,
-            command,
-            args,
-            socketPath: this.socketPath,
-            cwd: agentCwd,
-            dashboardPort: this.dashboardPort,
-            env: {
-              ...userEnv,
-              ...(spawnerName ? { AGENT_RELAY_SPAWNER: spawnerName } : {}),
-              ...(relaySocket ? { RELAY_SOCKET: relaySocket } : {}),
-              RELAY_AGENT_NAME: name,
-            },
-            httpApi: {
-              enabled: true,
-              fallbackToPty: true, // Allow fallback if HTTP becomes unavailable
-              // Auto-start opencode serve in cloud workspaces (internal to container)
-              autoStartServe: isCloudWorkspace && !serveAvailable,
-              waitForServeMs: 10000, // Give serve time to start in cloud
-            },
-            onSpawn: onSpawnHandler,
-            onRelease: onReleaseHandler,
-          };
-
-          const openCodeWrapper = new OpenCodeWrapper(openCodeConfig);
-
-          // Track listener references for proper cleanup
-          const listeners: ListenerBindings = {};
-
-          // Hook up output events for live log streaming
-          const outputListener = (data: string) => {
-            const broadcast = (global as any).__broadcastLogOutput;
-            if (broadcast) {
-              broadcast(name, data);
-            }
-          };
-          openCodeWrapper.on('output', outputListener);
-          listeners.output = outputListener;
-
-          // Handle exit events
-          openCodeWrapper.on('exit', (code: number) => {
-            onExitHandler(code);
-          });
-
-          // Mark agent as spawning BEFORE starting wrapper
-          if (this.onMarkSpawning) {
-            this.onMarkSpawning(name);
-            if (debug) log.debug(`Marked ${name} as spawning`);
-          }
-
-          await openCodeWrapper.start();
-          if (debug) log.debug(`OpenCodeWrapper started for ${name}, HTTP mode: ${openCodeWrapper.isHttpApiMode}`);
-
-          // Wait for the agent to register with the daemon
-          const registered = await this.waitForAgentRegistration(name, 30_000, 500);
-          if (!registered) {
-            const tracedError = createTraceableError('Agent registration timeout', {
-              agentName: name,
-              cli,
-              pid: openCodeWrapper.pid,
-              timeoutMs: 30_000,
-            });
-            log.error(tracedError.logMessage);
-            if (this.onClearSpawning) {
-              this.onClearSpawning(name);
-            }
-            await openCodeWrapper.kill();
-            return {
-              success: false,
-              name,
-              error: tracedError.userMessage,
-              errorId: tracedError.errorId,
-            };
-          }
-
-          // Send task to the newly spawned agent if provided
-          if (task && task.trim()) {
-            const ready = await openCodeWrapper.waitUntilReadyForMessages(20000, 100);
-            let taskSent = false;
-            if (ready) {
-              taskSent = await openCodeWrapper.injectTask(task, spawnerName || 'spawner');
-              if (!taskSent) {
-                log.warn(`Failed to inject task for ${name} via OpenCodeWrapper`);
-              } else if (debug) {
-                log.debug(`Task injected to ${name} via OpenCodeWrapper`);
-              }
-            } else {
-              log.warn(`OpenCodeWrapper ${name} not ready for task injection`);
-            }
-
-            // If task injection failed, kill the agent and return error
-            // An agent without its task is useless and will just sit idle
-            if (!taskSent) {
-              const tracedError = createTraceableError('Task injection failed', {
-                agentName: name,
-                cli,
-                taskLength: task.length,
-                ready,
-              });
-              log.error(`CRITICAL: ${tracedError.logMessage}`);
-              await openCodeWrapper.stop();
-              if (this.onClearSpawning) {
-                this.onClearSpawning(name);
-              }
-              return {
-                success: false,
-                name,
-                error: tracedError.userMessage,
-                errorId: tracedError.errorId,
-              };
-            }
-          }
-
-          // Track the worker (cast to AgentWrapper for type compatibility)
-          const workerInfo: ActiveWorker = {
-            name,
-            cli,
-            task,
-            team,
-            spawnerName,
-            userId,
-            spawnedAt: Date.now(),
-            pid: openCodeWrapper.pid,
-            pty: openCodeWrapper as unknown as AgentWrapper,
-            logFile: openCodeWrapper.logPath,
-            listeners,
-            model: spawnModel,
-            cwd: request.cwd,
-          };
-          this.activeWorkers.set(name, workerInfo);
-          this.saveWorkersMetadata();
-
-          const teamInfo = team ? ` [team: ${team}]` : '';
-          const shadowInfo = request.shadowOf ? ` [shadow of: ${request.shadowOf}]` : '';
-          log.info(`Spawned ${name} (${cli}) via OpenCodeWrapper${teamInfo}${shadowInfo} [HTTP mode: ${openCodeWrapper.isHttpApiMode}]`);
-
-          return {
-            success: true,
-            name,
-            pid: openCodeWrapper.pid,
-          };
-        }
-
-        // OpenCode serve not available and not in cloud workspace, fall through to RelayPtyOrchestrator
-        if (debug) log.debug(`OpenCode: serve not available, not cloud workspace, falling back to RelayPtyOrchestrator for ${name}`);
-      }
-
-      // Create RelayPtyOrchestrator (relay-pty Rust binary)
-      const ptyConfig: RelayPtyOrchestratorConfig = {
-        name,
-        command,
-        args,
-        socketPath: this.socketPath,
-        cwd: agentCwd,
-        dashboardPort: this.dashboardPort,
-        env: {
-          ...userEnv,
-          ...(spawnerName ? { AGENT_RELAY_SPAWNER: spawnerName } : {}),
-          // Pass socket path for MCP server discovery
-          // This allows the MCP server (started by Claude Code) to connect to the daemon
-          ...(relaySocket ? { RELAY_SOCKET: relaySocket } : {}),
-          // Pass agent name so MCP server knows its identity
-          RELAY_AGENT_NAME: name,
-        },
-        streamLogs: true,
-        shadowOf: request.shadowOf,
-        shadowSpeakOn: request.shadowSpeakOn,
-        skipContinuity: true,
-        onSpawn: onSpawnHandler,
-        onRelease: onReleaseHandler,
-        onExit: onExitHandler,
-        headless: true, // Force headless mode for spawned agents to enable task injection via stdin
-        // In cloud environments (WORKSPACE_ID set), limit CPU per agent to prevent
-        // one agent (e.g., running npm install) from starving others
-        // Default: 100% of one core per agent. Set AGENT_CPU_LIMIT to override.
-        cpuLimitPercent: process.env.WORKSPACE_ID
-          ? parseInt(process.env.AGENT_CPU_LIMIT || '100', 10)
-          : undefined,
-      };
-      const pty = new RelayPtyOrchestrator(ptyConfig);
-      if (debug) log.debug(`Using RelayPtyOrchestrator for ${name}`);
-
-      // Track listener references for proper cleanup
-      const listeners: ListenerBindings = {};
-
-      // Hook up output events for live log streaming
-      const outputListener = (data: string) => {
-        // Broadcast to any connected WebSocket clients via global function
-        const broadcast = (global as any).__broadcastLogOutput;
-        if (broadcast) {
-          broadcast(name, data);
-        }
-      };
-      pty.on('output', outputListener);
-      listeners.output = outputListener;
-
-      // Bind cloud persistence events (if enabled) and store references
-      const cloudListeners = this.bindCloudPersistenceEvents(name, pty);
-      if (cloudListeners.summary) listeners.summary = cloudListeners.summary;
-      if (cloudListeners.sessionEnd) listeners.sessionEnd = cloudListeners.sessionEnd;
-
-      // Mark agent as spawning BEFORE starting PTY
-      // This allows messages sent to this agent to be queued until HELLO completes
-      if (this.onMarkSpawning) {
-        this.onMarkSpawning(name);
-        if (debug) log.debug(`Marked ${name} as spawning`);
-      }
-
-      await pty.start();
-
-      if (debug) log.debug(`PTY started, pid: ${pty.pid}`);
-
-      // Cursor CLI shows "Press any key to log in..." prompt that blocks all progress
-      // Send a keystroke after startup to bypass this initial prompt
-      // Only do this for interactive/setup flows where auth is needed
-      // For normal spawns (already authenticated), this prompt won't appear
-      if (isCursorCli && interactive) {
-        // Wait a moment for CLI to initialize and show the prompt
-        await sleep(1500);
-        if (debug) log.debug(`Sending initial keystroke for Cursor setup to bypass "Press any key" prompt`);
-        try {
-          // Send Enter key to proceed past the initial prompt
-          await pty.write('\r');
-        } catch (err) {
-          log.warn(`Failed to send initial keystroke for Cursor: ${err}`);
-        }
-      }
-
-      // Wait for the agent to register with the daemon
-      const registered = await this.waitForAgentRegistration(name, 30_000, 500);
-      if (!registered) {
-        const tracedError = createTraceableError('Agent registration timeout', {
-          agentName: name,
-          cli,
-          pid: pty.pid,
-          timeoutMs: 30_000,
-        });
-        log.error(tracedError.logMessage);
-        // Clear spawning flag since spawn failed
-        if (this.onClearSpawning) {
-          this.onClearSpawning(name);
-        }
-        await pty.kill();
-        return {
-          success: false,
-          name,
-          error: tracedError.userMessage,
-          errorId: tracedError.errorId,
-        };
-      }
-
-      // Send task to the newly spawned agent if provided
-      // We do this AFTER registration AND after the orchestrator is FULLY ready for messages
-      // This includes: CLI started, CLI idle, socket connected, readyForMessages flag set
-      if (task && task.trim()) {
-        const maxRetries = 3;
-        const retryDelayMs = 2000;
-        let taskSent = false;
-
-        for (let attempt = 1; attempt <= maxRetries; attempt++) {
-          try {
-            // Wait for full orchestrator readiness (CLI + socket + internal flags)
-            if ('waitUntilReadyForMessages' in pty) {
-              const orchestrator = pty as RelayPtyOrchestrator;
-              const ready = await orchestrator.waitUntilReadyForMessages(20000, 100);
-              if (!ready) {
-                // Log retry attempts at DEBUG level to avoid terminal noise
-                log.debug(`Attempt ${attempt}/${maxRetries}: ${name} not ready for messages within timeout`);
-                if (attempt < maxRetries) {
-                  await sleep(retryDelayMs);
-                  continue;
-                }
-                log.error(`${name} failed to become ready after ${maxRetries} attempts - task may be lost`);
-                break;
-              }
-            } else if ('waitUntilCliReady' in pty) {
-              // Fallback for older wrapper types
-              await (pty as RelayPtyOrchestrator).waitUntilCliReady(15000, 100);
-            }
-
-            // Inject task via socket (relay-pty confirms write)
-            const success = await pty.injectTask(task, spawnerName || 'spawner');
-            if (success) {
-              taskSent = true;
-              if (debug) log.debug(`Task injected to ${name} (attempt ${attempt})`);
-              break;
-            } else {
-              // Delivery failed - safe to retry
-              throw new Error('Task injection returned false - delivery failed');
-            }
-          } catch (err: any) {
-            // Log retry attempts at DEBUG level to avoid terminal noise
-            // Only the final summary (if all attempts fail) is logged at ERROR level
-            log.debug(`Attempt ${attempt}/${maxRetries}: Error injecting task for ${name}: ${err.message}`);
-            if (attempt < maxRetries) {
-              await sleep(retryDelayMs);
-            }
-          }
-        }
-
-        if (!taskSent) {
-          const tracedError = createTraceableError('Task injection failed', {
-            agentName: name,
-            cli,
-            attempts: maxRetries,
-            taskLength: task.length,
-          });
-          log.error(`CRITICAL: ${tracedError.logMessage}`);
-          // Kill the agent since it's useless without its task - it will just sit idle
-          // Return an error so the caller knows the spawn effectively failed
-          await pty.stop();
-          this.activeWorkers.delete(name);
-          if (this.onClearSpawning) {
-            this.onClearSpawning(name);
-          }
-          return {
-            success: false,
-            name,
-            error: tracedError.userMessage,
-            errorId: tracedError.errorId,
-          };
-        }
-      }
-
-      // Track the worker
-      const workerInfo: ActiveWorker = {
-        name,
-        cli,
-        task,
-        team,
-        spawnerName,
-        userId,
-        spawnedAt: Date.now(),
-        pid: pty.pid,
-        pty,
-        logFile: pty.logPath,
-        listeners, // Store for cleanup
-        model: spawnModel,
-        cwd: request.cwd,
-      };
-      this.activeWorkers.set(name, workerInfo);
-      this.saveWorkersMetadata();
-
-      const teamInfo = team ? ` [team: ${team}]` : '';
-      const shadowInfo = request.shadowOf ? ` [shadow of: ${request.shadowOf}]` : '';
-      log.info(`Spawned ${name} (${cli})${teamInfo}${shadowInfo} [pid: ${pty.pid}]`);
-
-      return {
-        success: true,
-        name,
-        pid: pty.pid,
-      };
-    } catch (err: any) {
-      const tracedError = createTraceableError('Agent spawn failed', {
-        agentName: name,
-        cli,
-        task: task?.substring(0, 100),
-      }, err instanceof Error ? err : undefined);
-      log.error(tracedError.logMessage);
-      if (debug) log.debug('Full error', { error: err?.stack || String(err) });
-      // Clear spawning flag since spawn failed
-      if (this.onClearSpawning) {
-        this.onClearSpawning(name);
-      }
-      return {
-        success: false,
-        name,
-        error: tracedError.userMessage,
-        errorId: tracedError.errorId,
-      };
-    } finally {
-      // Always release spawn lock, even on success (agent is now tracked in activeWorkers)
-      this.spawningAgents.delete(name);
-      log.info(`Spawn lock released for ${name} (remaining: ${this.spawningAgents.size})`);
-    }
-  }
-
-  /** Role presets for shadow agents */
-  private static readonly ROLE_PRESETS: Record<string, SpeakOnTrigger[]> = {
-    reviewer: ['CODE_WRITTEN', 'REVIEW_REQUEST', 'EXPLICIT_ASK'],
-    auditor: ['SESSION_END', 'EXPLICIT_ASK'],
-    active: ['ALL_MESSAGES'],
-  };
-
-  /**
-   * Spawn a primary agent with its shadow agent
-   *
-   * Example usage:
-   * ```ts
-   * const result = await spawner.spawnWithShadow({
-   *   primary: { name: 'Lead', command: 'claude', task: 'Implement feature X' },
-   *   shadow: { name: 'Auditor', role: 'reviewer', speakOn: ['CODE_WRITTEN'] }
-   * });
-   * ```
-   */
-  async spawnWithShadow(request: SpawnWithShadowRequest): Promise<SpawnWithShadowResult> {
-    const { primary, shadow } = request;
-    const debug = process.env.DEBUG_SPAWN === '1';
-
-    // Resolve shadow speakOn triggers
-    let speakOn: SpeakOnTrigger[] = ['EXPLICIT_ASK']; // Default
-
-    // Check for role preset
-    if (shadow.role && AgentSpawner.ROLE_PRESETS[shadow.role.toLowerCase()]) {
-      speakOn = AgentSpawner.ROLE_PRESETS[shadow.role.toLowerCase()];
-    }
-
-    // Override with explicit speakOn if provided
-    if (shadow.speakOn && shadow.speakOn.length > 0) {
-      speakOn = shadow.speakOn;
-    }
-
-    // Build shadow task prompt
-    const defaultPrompt = `You are a shadow agent monitoring "${primary.name}". You receive copies of their messages. Your role: ${shadow.role || 'observer'}. Stay passive unless your triggers activate: ${speakOn.join(', ')}.`;
-    const shadowTask = shadow.prompt || defaultPrompt;
-
-    // Decide how to run the shadow (subagent for Claude/OpenCode primaries, process fallback otherwise)
-    let shadowSelection: Awaited<ReturnType<typeof selectShadowCli>> | null = null;
-    try {
-      shadowSelection = await selectShadowCli(primary.command || 'claude', {
-        preferredShadowCli: shadow.command,
-      });
-    } catch (err: any) {
-      log.warn(`Shadow CLI selection failed for ${shadow.name}: ${err.message}`);
-    }
-
-    if (debug) {
-      const mode = shadowSelection?.mode ?? 'unknown';
-      const cli = shadowSelection?.command ?? shadow.command ?? primary.command ?? 'claude';
-      log.debug(
-        `spawnWithShadow: primary=${primary.name}, shadow=${shadow.name}, mode=${mode}, cli=${cli}, speakOn=${speakOn.join(',')}`
-      );
-    }
-
-    // Step 1: Spawn primary agent
-    const primaryResult = await this.spawn({
-      name: primary.name,
-      cli: primary.command || 'claude',
-      task: primary.task || '',
-      team: primary.team,
-    });
-
-    if (!primaryResult.success) {
-      return {
-        success: false,
-        primary: primaryResult,
-        error: `Failed to spawn primary agent: ${primaryResult.error}`,
-      };
-    }
-
-    // Step 2: Wait for primary to register before spawning shadow
-    // The spawn() method already waits, but we add a small delay for stability
-    await sleep(1000);
-
-    // Subagent mode: no separate process needed
-    if (shadowSelection?.mode === 'subagent') {
-      log.info(
-        `Shadow ${shadow.name} will run as ${shadowSelection.cli} subagent inside ${primary.name} (no separate process)`
-      );
-      return {
-        success: true,
-        primary: primaryResult,
-        shadow: {
-          success: true,
-          name: shadow.name,
-        },
-      };
-    }
-
-    // No available shadow CLI - proceed without spawning a shadow process
-    if (!shadowSelection) {
-      log.warn(`No authenticated shadow CLI available; ${primary.name} will run without a shadow`);
-      return {
-        success: true,
-        primary: primaryResult,
-        error: 'Shadow spawn skipped: no authenticated shadow CLI available',
-      };
-    }
-
-    // Step 3: Spawn shadow agent with shadowOf and shadowSpeakOn
-    const shadowResult = await this.spawn({
-      name: shadow.name,
-      // Use the selected/validated CLI for process-mode shadows
-      cli: shadowSelection.command || shadow.command || primary.command || 'claude',
-      task: shadowTask,
-      shadowOf: primary.name,
-      shadowSpeakOn: speakOn,
-    });
-
-    if (!shadowResult.success) {
-      log.warn(`Shadow agent ${shadow.name} failed to spawn, primary ${primary.name} continues without shadow`);
-      return {
-        success: true, // Primary succeeded, overall operation is partial success
-        primary: primaryResult,
-        shadow: shadowResult,
-        error: `Shadow spawn failed: ${shadowResult.error}`,
-      };
-    }
-
-    log.info(`Spawned pair: ${primary.name} with shadow ${shadow.name} (speakOn: ${speakOn.join(',')})`);
-
-    return {
-      success: true,
-      primary: primaryResult,
-      shadow: shadowResult,
-    };
-  }
-
-  /**
-   * Release (terminate) a worker
-   */
-  async release(name: string): Promise<boolean> {
-    const worker = this.activeWorkers.get(name);
-    if (!worker) {
-      log.debug(`Worker ${name} not found`);
-      return false;
-    }
-
-    try {
-      // Unbind all listeners first to prevent memory leaks
-      this.unbindListeners(worker.pty, worker.listeners);
-
-      // Stop the pty process gracefully (handles auto-save internally)
-      await worker.pty.stop();
-
-      // Force kill if still running
-      if (worker.pty.isRunning) {
-        await worker.pty.kill();
-      }
-
-      this.activeWorkers.delete(name);
-      this.saveWorkersMetadata();
-      log.info(`Released ${name}`);
-
-      return true;
-    } catch (err: any) {
-      log.error(`Failed to release ${name}: ${err.message}`);
-      // Still unbind and remove from tracking
-      this.unbindListeners(worker.pty, worker.listeners);
-      this.activeWorkers.delete(name);
-      this.saveWorkersMetadata();
-      return false;
-    }
-  }
-
-  /**
-   * Release all workers
-   */
-  async releaseAll(): Promise<void> {
-    const workers = Array.from(this.activeWorkers.keys());
-    for (const name of workers) {
-      await this.release(name);
-    }
-  }
-
-  /**
-   * Get all active workers (returns WorkerInfo without pty reference)
-   */
-  getActiveWorkers(): WorkerInfo[] {
-    return Array.from(this.activeWorkers.values()).map((w) => ({
-      name: w.name,
-      cli: w.cli,
-      task: w.task,
-      team: w.team,
-      spawnerName: w.spawnerName,
-      spawnedAt: w.spawnedAt,
-      pid: w.pid,
-      model: w.model,
-      cwd: w.cwd,
-    }));
-  }
-
-  /**
-   * Check if a worker exists
-   */
-  hasWorker(name: string): boolean {
-    return this.activeWorkers.has(name);
-  }
-
-  /**
-   * Get worker info
-   */
-  getWorker(name: string): WorkerInfo | undefined {
-    const worker = this.activeWorkers.get(name);
-    if (!worker) return undefined;
-    return {
-      name: worker.name,
-      cli: worker.cli,
-      task: worker.task,
-      team: worker.team,
-      spawnedAt: worker.spawnedAt,
-      pid: worker.pid,
-      model: worker.model,
-      cwd: worker.cwd,
-    };
-  }
-
-  /**
-   * Get output logs from a worker
-   */
-  getWorkerOutput(name: string, limit?: number): string[] | null {
-    const worker = this.activeWorkers.get(name);
-    if (!worker) return null;
-    return worker.pty.getOutput(limit);
-  }
-
-  /**
-   * Get raw output from a worker
-   */
-  getWorkerRawOutput(name: string): string | null {
-    const worker = this.activeWorkers.get(name);
-    if (!worker) return null;
-    return worker.pty.getRawOutput();
-  }
-
-  /**
-   * Send input to a worker's PTY (for interactive terminal support)
-   * @param name - Worker name
-   * @param data - Input data to send (keystrokes, text, etc.)
-   * @returns true if input was sent, false if worker not found
-   */
-  sendWorkerInput(name: string, data: string): boolean {
-    const worker = this.activeWorkers.get(name);
-    if (!worker) return false;
-    worker.pty.write(data);
-    return true;
-  }
-
-  /**
-   * Switch the model of a running worker agent.
-   * Waits for the agent to be idle, then sends the CLI-specific model switch command.
-   *
-   * @param name - Worker name
-   * @param model - Target model identifier (e.g., 'opus', 'sonnet', 'haiku')
-   * @param timeoutMs - Max time to wait for agent idle (default: 30000)
-   * @returns Result of the model switch attempt
-   */
-  async setWorkerModel(
-    name: string,
-    model: string,
-    timeoutMs = 30000,
-  ): Promise<{ success: boolean; previousModel?: string; normalizedModel?: string; error?: string }> {
-    const worker = this.activeWorkers.get(name);
-    if (!worker) {
-      return { success: false, error: `Agent "${name}" not found` };
-    }
-
-    // Validate CLI supports model switching
-    if (!isModelSwitchSupported(worker.cli)) {
-      return { success: false, error: `CLI "${worker.cli}" does not support mid-session model switching` };
-    }
-
-    // Validate and normalize model name
-    const validation = validateModelForCli(worker.cli, model);
-    if (!validation.valid) {
-      return { success: false, error: validation.error };
-    }
-    const normalizedModel = validation.normalizedModel ?? model;
-
-    // Build the command using normalized model
-    const command = buildModelSwitchCommand(worker.cli, normalizedModel);
-    if (!command) {
-      return { success: false, error: `Failed to build model switch command for "${worker.cli}"` };
-    }
-
-    // Wait for agent idle via readiness detection
-    const pty = worker.pty;
-    if ('waitUntilReadyForMessages' in pty && typeof pty.waitUntilReadyForMessages === 'function') {
-      const ready = await pty.waitUntilReadyForMessages(timeoutMs, 200);
-      if (!ready) {
-        return {
-          success: false,
-          error: `Agent "${name}" did not become idle within ${timeoutMs}ms. The agent may be processing a task. Try again later.`,
-        };
-      }
-    } else {
-      log.warn(`PTY for ${name} does not support idle detection; sending model switch without waiting`);
-    }
-
-    // Send the command via write() (raw stdin)
-    try {
-      const previousModel = worker.model;
-      await pty.write(command);
-      worker.model = normalizedModel;
-      this.saveWorkersMetadata();
-
-      log.info(`Model switched for ${name}: ${previousModel ?? 'unknown'} -> ${normalizedModel}`);
-      return { success: true, previousModel, normalizedModel };
-    } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : String(err);
-      return { success: false, error: `Failed to send model switch command: ${message}` };
-    }
-  }
-
-  /**
-   * Wait for an agent to appear in the connected list and registry (connected-agents.json + agents.json).
-   */
-  private async waitForAgentRegistration(
-    name: string,
-    timeoutMs = 30_000,
-    pollIntervalMs = 500
-  ): Promise<boolean> {
-    const deadline = Date.now() + timeoutMs;
-    let pollCount = 0;
-
-    while (Date.now() < deadline) {
-      pollCount++;
-      const connected = this.isAgentConnected(name);
-      const recentlySeen = this.isAgentRecentlySeen(name);
-
-      // Log first few polls and every 10th poll after that
-      if (pollCount <= 3 || pollCount % 10 === 0) {
-        log.info(`Registration poll #${pollCount} for ${name}: connected=${connected} recentlySeen=${recentlySeen} agentsPath=${this.agentsPath}`);
-      }
-
-      if (connected && recentlySeen) {
-        log.info(`Agent ${name} registered after ${pollCount} polls`);
-        return true;
-      }
-
-      await sleep(pollIntervalMs);
-    }
-
-    log.info(`Registration timeout for ${name} after ${pollCount} polls`);
-    return false;
-  }
-
-  private isAgentRegistered(name: string): boolean {
-    return this.isAgentConnected(name) && this.isAgentRecentlySeen(name);
-  }
-
-  private isAgentConnected(name: string): boolean {
-    const debug = process.env.DEBUG_SPAWN === '1';
-    if (!this.agentsPath) {
-      if (debug) log.debug(`isAgentConnected(${name}): no agentsPath`);
-      return false;
-    }
-    if (!fs.existsSync(this.agentsPath)) {
-      if (debug) log.debug(`isAgentConnected(${name}): file not found: ${this.agentsPath}`);
-      return false;
-    }
-
-    try {
-      const raw = JSON.parse(fs.readFileSync(this.agentsPath, 'utf-8'));
-      // connected-agents.json format: { agents: string[], users: string[], updatedAt: number }
-      // agents is a string array of connected agent names (not objects)
-      const agents: string[] = Array.isArray(raw?.agents) ? raw.agents : [];
-      const updatedAt = typeof raw?.updatedAt === 'number' ? raw.updatedAt : 0;
-      const isFresh = Date.now() - updatedAt <= AgentSpawner.ONLINE_THRESHOLD_MS;
-
-      if (debug) {
-        log.debug(`isAgentConnected(${name}): path=${this.agentsPath} agents=${agents.join(',')} updatedAt=${updatedAt} isFresh=${isFresh}`);
-      }
-
-      if (!isFresh) return false;
-
-      // Case-insensitive check to match router behavior
-      const lowerName = name.toLowerCase();
-      return agents.some((a) => typeof a === 'string' && a.toLowerCase() === lowerName);
-    } catch (err: any) {
-      log.error('Failed to read connected-agents.json', { error: err.message, path: this.agentsPath });
-      return false;
-    }
-  }
-
-  private isAgentRecentlySeen(name: string): boolean {
-    if (!this.registryPath) return false;
-    if (!fs.existsSync(this.registryPath)) return false;
-
-    try {
-      const raw = JSON.parse(fs.readFileSync(this.registryPath, 'utf-8'));
-      const agents = Array.isArray(raw?.agents)
-        ? raw.agents
-        : typeof raw?.agents === 'object' && raw?.agents !== null
-          ? Object.values(raw.agents)
-          : [];
-      const lowerName = name.toLowerCase();
-      const agent = agents.find((entry: { name?: string; lastSeen?: string }) => typeof entry?.name === 'string' && entry.name.toLowerCase() === lowerName);
-      if (!agent?.lastSeen) return false;
-      return Date.now() - new Date(agent.lastSeen).getTime() <= AgentSpawner.ONLINE_THRESHOLD_MS;
-    } catch (err: any) {
-      log.error('Failed to read agents.json', { error: err.message });
-      return false;
-    }
-  }
-
-  /**
-   * Save workers metadata to disk for CLI access
-   */
-  private saveWorkersMetadata(): void {
-    try {
-      const workers: WorkerMeta[] = Array.from(this.activeWorkers.values()).map((w) => ({
-        name: w.name,
-        cli: w.cli,
-        task: w.task,
-        team: w.team,
-        userId: w.userId,
-        spawnedAt: w.spawnedAt,
-        pid: w.pid,
-        logFile: w.logFile,
-        model: w.model,
-        cwd: w.cwd,
-      }));
-
-      fs.writeFileSync(this.workersPath, JSON.stringify({ workers }, null, 2));
-    } catch (err: any) {
-      log.error('Failed to save workers metadata', { error: err.message });
-    }
-  }
-
-  /**
-   * Get path to logs directory
-   */
-  getLogsDir(): string {
-    return this.logsDir;
-  }
-
-  /**
-   * Get path to workers metadata file
-   */
-  getWorkersPath(): string {
-    return this.workersPath;
-  }
-}
-
-/**
- * Read workers metadata from disk (for CLI use)
- */
-export function readWorkersMetadata(projectRoot: string): WorkerMeta[] {
-  const paths = getProjectPaths(projectRoot);
-  const workersPath = path.join(paths.teamDir, 'workers.json');
-
-  if (!fs.existsSync(workersPath)) {
-    return [];
-  }
-
-  try {
-    const raw = JSON.parse(fs.readFileSync(workersPath, 'utf-8'));
-    return Array.isArray(raw?.workers) ? raw.workers : [];
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Get the worker logs directory path
- */
-export function getWorkerLogsDir(projectRoot: string): string {
-  const paths = getProjectPaths(projectRoot);
-  return path.join(paths.teamDir, 'worker-logs');
-}