agent-relay 2.3.13 → 2.4.0

package/packages/bridge/dist/spawner.js

@@ -1,1758 +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 } from '@agent-relay/wrapper';
-import { OpenCodeWrapper, OpenCodeApi } 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 } from '@agent-relay/policy';
-import { buildClaudeArgs, findAgentConfig } from '@agent-relay/config/agent-config';
-import { composeForAgent } from '@agent-relay/wrapper';
-import { getUserDirectoryService } from '@agent-relay/user-directory';
-// Logger instance for spawner (uses daemon log system instead of console)
-const log = createLogger('spawner');
-function extractGhTokenFromHosts(content) {
-    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;
-}
-/**
- * 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, cliType, debug = false) {
-    const home = process.env.HOME || '';
-    const configMap = {
-        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 = {};
-        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 = 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];
-            }
-            // Ensure allow list exists
-            const finalKey = keyParts[keyParts.length - 1];
-            if (!Array.isArray(current[finalKey])) {
-                current[finalKey] = [];
-            }
-            const allowList = current[finalKey];
-            // 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() {
-    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, options = {}) {
-    const { hasMcp = false, includeWorkflowConventions = false } = options;
-    // Get the outbox path template and replace variable with actual agent name
-    const outboxBase = getAgentOutboxTemplate(agentName);
-    const parts = [
-        '# 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() {
-    return findRelayPtyBinaryUtil(__dirname);
-}
-/** Cached result of relay-pty binary check */
-let relayPtyBinaryPath;
-let relayPtyBinaryChecked = false;
-/**
- * Check if relay-pty binary is available (cached).
- * Returns true if the binary exists, false otherwise.
- */
-function hasRelayPtyBinary() {
-    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;
-}
-export class AgentSpawner {
-    static ONLINE_THRESHOLD_MS = 30_000;
-    activeWorkers = new Map();
-    agentsPath;
-    registryPath;
-    projectRoot;
-    socketPath;
-    logsDir;
-    workersPath;
-    dashboardPort;
-    onAgentDeath;
-    cloudPersistence;
-    policyService;
-    policyEnforcementEnabled = false;
-    onMarkSpawning;
-    onClearSpawning;
-    /**
-     * 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.
-     */
-    spawningAgents = new Set();
-    constructor(projectRootOrOptions, _tmuxSession, dashboardPort) {
-        // Handle both old and new constructor signatures
-        const options = 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.
-     */
-    cleanupOrphanedWorkers() {
-        if (!fs.existsSync(this.workersPath)) {
-            return;
-        }
-        try {
-            const raw = JSON.parse(fs.readFileSync(this.workersPath, 'utf-8'));
-            const workers = 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) {
-        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() {
-        return this.policyService;
-    }
-    async fetchGhTokenFromCloud() {
-        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();
-            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;
-        }
-    }
-    resolveGhTokenFromHostsFile(homeDir) {
-        const resolvedHome = homeDir || process.env.HOME;
-        const configHome = process.env.XDG_CONFIG_HOME || (resolvedHome ? path.join(resolvedHome, '.config') : undefined);
-        const candidates = new Set();
-        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;
-    }
-    async resolveGhTokenFromGhCli() {
-        // 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
-     */
-    async resolveGhToken(homeDir) {
-        // 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) {
-        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) {
-        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) {
-        this.cloudPersistence = handler;
-        log.info('Cloud persistence handler set');
-    }
-    /**
-     * Bind cloud persistence event handlers to a RelayPtyOrchestrator.
-     * Returns the listener references for cleanup.
-     */
-    bindCloudPersistenceEvents(name, pty) {
-        if (!this.cloudPersistence)
-            return {};
-        const summaryListener = async (event) => {
-            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) => {
-            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.
-     */
-    unbindListeners(pty, listeners) {
-        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) {
-        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 = 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;
-            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 = ['planner', 'worker', 'reviewer', 'lead', 'shadow'];
-                const role = agentConfigForRole.role.toLowerCase();
-                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) {
-                        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;
-            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) => {
-                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, workerCli, workerTask, workerCwd) => {
-                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) => {
-                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 = {
-                        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 = {};
-                    // Hook up output events for live log streaming
-                    const outputListener = (data) => {
-                        const broadcast = global.__broadcastLogOutput;
-                        if (broadcast) {
-                            broadcast(name, data);
-                        }
-                    };
-                    openCodeWrapper.on('output', outputListener);
-                    listeners.output = outputListener;
-                    // Handle exit events
-                    openCodeWrapper.on('exit', (code) => {
-                        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 = {
-                        name,
-                        cli,
-                        task,
-                        team,
-                        spawnerName,
-                        userId,
-                        spawnedAt: Date.now(),
-                        pid: openCodeWrapper.pid,
-                        pty: openCodeWrapper,
-                        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 = {
-                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 = {};
-            // Hook up output events for live log streaming
-            const outputListener = (data) => {
-                // Broadcast to any connected WebSocket clients via global function
-                const broadcast = global.__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;
-                            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.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) {
-                        // 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 = {
-                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) {
-            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 */
-    static ROLE_PRESETS = {
-        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) {
-        const { primary, shadow } = request;
-        const debug = process.env.DEBUG_SPAWN === '1';
-        // Resolve shadow speakOn triggers
-        let speakOn = ['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 = null;
-        try {
-            shadowSelection = await selectShadowCli(primary.command || 'claude', {
-                preferredShadowCli: shadow.command,
-            });
-        }
-        catch (err) {
-            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) {
-        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) {
-            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() {
-        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() {
-        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) {
-        return this.activeWorkers.has(name);
-    }
-    /**
-     * Get worker info
-     */
-    getWorker(name) {
-        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, limit) {
-        const worker = this.activeWorkers.get(name);
-        if (!worker)
-            return null;
-        return worker.pty.getOutput(limit);
-    }
-    /**
-     * Get raw output from a worker
-     */
-    getWorkerRawOutput(name) {
-        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, data) {
-        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, model, timeoutMs = 30000) {
-        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) {
-            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).
-     */
-    async waitForAgentRegistration(name, timeoutMs = 30_000, pollIntervalMs = 500) {
-        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;
-    }
-    isAgentRegistered(name) {
-        return this.isAgentConnected(name) && this.isAgentRecentlySeen(name);
-    }
-    isAgentConnected(name) {
-        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 = 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) {
-            log.error('Failed to read connected-agents.json', { error: err.message, path: this.agentsPath });
-            return false;
-        }
-    }
-    isAgentRecentlySeen(name) {
-        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) => 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) {
-            log.error('Failed to read agents.json', { error: err.message });
-            return false;
-        }
-    }
-    /**
-     * Save workers metadata to disk for CLI access
-     */
-    saveWorkersMetadata() {
-        try {
-            const workers = 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) {
-            log.error('Failed to save workers metadata', { error: err.message });
-        }
-    }
-    /**
-     * Get path to logs directory
-     */
-    getLogsDir() {
-        return this.logsDir;
-    }
-    /**
-     * Get path to workers metadata file
-     */
-    getWorkersPath() {
-        return this.workersPath;
-    }
-}
-/**
- * Read workers metadata from disk (for CLI use)
- */
-export function readWorkersMetadata(projectRoot) {
-    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) {
-    const paths = getProjectPaths(projectRoot);
-    return path.join(paths.teamDir, 'worker-logs');
-}
-//# sourceMappingURL=spawner.js.map