agent-relay 7.1.1 → 8.0.2

package/dist/cli/lib/broker-lifecycle.js

@@ -0,0 +1,1467 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { HarnessDriverClient } from '@agent-relay/harness-driver';
+import { track } from '../telemetry/index.js';
+import { buildBundledAgentRelayMcpCommand } from './agent-relay-mcp-command.js';
+import { errorClassName } from './telemetry-helpers.js';
+const MAX_API_PORT_ATTEMPTS = 25;
+const MAX_DASHBOARD_PORT_ATTEMPTS = 25;
+const MAX_PORT = 65535;
+/** The broker writes this file with URL, port, API key, and PID. */
+const CONNECTION_FILENAME = 'connection.json';
+const STATUS_POLL_INTERVAL_MS = 500;
+const DETACHED_START_READY_TIMEOUT_MS = 10_000;
+function parseBrokerConnection(raw) {
+    try {
+        const conn = JSON.parse(raw);
+        if (typeof conn.url === 'string' &&
+            typeof conn.port === 'number' &&
+            typeof conn.api_key === 'string' &&
+            typeof conn.pid === 'number' &&
+            conn.pid > 0) {
+            return conn;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function readBrokerConnectionFromFs(fileSystem, dataDir) {
+    const connPath = path.join(dataDir, CONNECTION_FILENAME);
+    try {
+        const raw = fileSystem.readFileSync(connPath, 'utf-8');
+        return parseBrokerConnection(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the broker's connection.json file from the data directory.
+ * Returns null if the file doesn't exist or is invalid.
+ */
+export function readBrokerConnection(dataDir) {
+    return readBrokerConnectionFromFs(fs, dataDir);
+}
+function toErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function errorCode(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const code = err.code;
+    return typeof code === 'string' ? code : undefined;
+}
+/**
+ * Extract a human-meaningful detail string from an error, walking `err.cause`.
+ *
+ * Node's native `fetch()` throws `TypeError: fetch failed` for any network
+ * problem and stuffs the real reason (ECONNREFUSED, ENOTFOUND, AbortError,
+ * UND_ERR_CONNECT_TIMEOUT, …) into `err.cause`. Without unwrapping, every
+ * outbound HTTP failure looks identical to the user.
+ *
+ * Exported for testing.
+ */
+export function describeError(err) {
+    const top = toErrorMessage(err);
+    if (!(err instanceof Error) || !err.cause)
+        return top;
+    // Walk the cause chain and collect the deepest message + any error codes.
+    const codes = [];
+    let detail;
+    let cursor = err.cause;
+    let depth = 0;
+    while (cursor && depth < 5) {
+        const code = errorCode(cursor);
+        if (code && !codes.includes(code))
+            codes.push(code);
+        if (cursor instanceof Error && cursor.message) {
+            detail = cursor.message;
+        }
+        cursor = cursor instanceof Error ? cursor.cause : undefined;
+        depth += 1;
+    }
+    const parts = [top];
+    if (detail && detail !== top)
+        parts.push(detail);
+    if (codes.length > 0)
+        parts.push(`[${codes.join(', ')}]`);
+    return parts.join(' — ');
+}
+/**
+ * Pick the best `error_class` for telemetry. Prefer a network-style code from
+ * `err.cause` (ECONNREFUSED etc.) over the generic constructor name (TypeError)
+ * — a code is more actionable in PostHog and matches the schema's example
+ * values for `BrokerStartFailedEvent.error_class`.
+ *
+ * Exported for testing.
+ */
+export function classifyBrokerStartError(err) {
+    let cursor = err;
+    let depth = 0;
+    while (cursor && depth < 5) {
+        const code = errorCode(cursor);
+        if (code)
+            return code;
+        cursor = cursor instanceof Error ? cursor.cause : undefined;
+        depth += 1;
+    }
+    return errorClassName(err) ?? 'Error';
+}
+/** Exported for testing. */
+export function classifyBrokerStartStage(err, message, wantsDashboard) {
+    if (errorCode(err) === 'EADDRINUSE' && wantsDashboard)
+        return 'dashboard_port';
+    if (isBrokerAlreadyRunningError(message))
+        return 'already_running';
+    if (/fetch failed/i.test(message))
+        return 'connect';
+    if (/Broker did not report API port/i.test(message))
+        return 'spawn';
+    if (/Broker process exited with code/i.test(message))
+        return 'spawn';
+    if (/ENOENT/i.test(message) && /broker/i.test(message))
+        return 'resolve_binary';
+    return 'startup';
+}
+async function resolveApiPortWithFallback(startApiPort, maxAttempts, deps) {
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const candidatePort = startApiPort + attempt;
+        if (candidatePort > MAX_PORT) {
+            break;
+        }
+        const inUse = await deps.isPortInUse(candidatePort);
+        if (!inUse) {
+            if (attempt > 0) {
+                deps.warn(`API port ${startApiPort} is already in use; trying ${candidatePort}`);
+            }
+            return candidatePort;
+        }
+    }
+    throw new Error(`Failed to find an available API port near ${startApiPort}.`);
+}
+async function startBrokerWithPortFallback(paths, dashboardPort, deps, brokerName) {
+    // Resolve a free API port BEFORE spawning the broker.  This avoids
+    // spawning (and flocking) multiple --persist brokers during retry,
+    // which caused stale-flock "already running" errors.
+    const startApiPort = dashboardPort + 1;
+    const apiPort = await resolveApiPortWithFallback(startApiPort, MAX_API_PORT_ATTEMPTS, deps);
+    const candidate = await deps.createRelay(paths.projectRoot, apiPort, brokerName);
+    await candidate.getStatus();
+    return { relay: candidate, apiPort };
+}
+async function resolveDashboardPortWithFallback(dashboardPort, dashboardPortCandidates, deps) {
+    for (let attempt = 0; attempt < dashboardPortCandidates; attempt += 1) {
+        const candidatePort = dashboardPort + attempt;
+        const inUse = await deps.isPortInUse(candidatePort);
+        if (!inUse) {
+            if (attempt > 0) {
+                deps.warn(`Dashboard port ${dashboardPort} is already in use; trying ${candidatePort}`);
+            }
+            return candidatePort;
+        }
+    }
+    throw new Error(`Failed to find an available dashboard port near ${dashboardPort}.`);
+}
+function isBrokerAlreadyRunningError(message) {
+    return /another broker instance is already running in this directory/i.test(message);
+}
+function extractBrokerLockDir(message) {
+    const match = message.match(/another broker instance is already running in this directory \(([^)]+)\)/i);
+    return match?.[1] ?? null;
+}
+function reportAlreadyRunningError(message, dataDir, deps) {
+    const pid = readBrokerPid(dataDir, deps);
+    if (pid !== null && isProcessRunning(pid, deps)) {
+        deps.error(`Broker already running for this project (pid: ${pid}).`);
+    }
+    else {
+        const lockDir = extractBrokerLockDir(message);
+        if (lockDir) {
+            deps.error(`Broker already running for this project (lock: ${lockDir}).`);
+        }
+        else {
+            deps.error('Broker already running for this project.');
+        }
+    }
+    deps.error('Run `agent-relay status` to inspect it, then `agent-relay down` to stop it.');
+    deps.error('If it still fails, run `agent-relay down --force` to clear stale runtime files.');
+}
+function safeUnlink(filePath, deps) {
+    if (!deps.fs.existsSync(filePath))
+        return;
+    try {
+        deps.fs.unlinkSync(filePath);
+    }
+    catch {
+        // Best-effort cleanup.
+    }
+}
+function readBrokerPid(dataDir, _deps) {
+    const conn = readBrokerConnectionFromFs(_deps.fs, dataDir);
+    return conn?.pid ?? null;
+}
+function isProcessRunning(pid, deps) {
+    try {
+        deps.killProcess(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parsePsAuxLine(line) {
+    const fields = line.trim().split(/\s+/);
+    if (fields.length < 11 || fields[0] === 'USER') {
+        return null;
+    }
+    const pid = Number.parseInt(fields[1], 10);
+    if (Number.isNaN(pid) || pid <= 0) {
+        return null;
+    }
+    return {
+        pid,
+        command: fields.slice(10).join(' '),
+    };
+}
+function commandExecutableBasename(command) {
+    const executable = command.trim().split(/\s+/)[0] ?? '';
+    return path.basename(executable.replace(/^["']|["']$/g, ''));
+}
+function isBrokerExecutableCommand(command) {
+    const basename = commandExecutableBasename(command);
+    return basename === 'agent-relay-broker' || basename.startsWith('agent-relay-broker-');
+}
+function isForegroundBrokerCliCommand(command) {
+    if (command.includes('agent-relay-mcp')) {
+        return false;
+    }
+    if (!/(?:^|\s)up(?:\s|$)/.test(command) || !/(?:^|\s)--foreground(?:\s|=|$)/.test(command)) {
+        return false;
+    }
+    return /(?:^|\s)(?:\S*agent-relay(?:\.js)?|\S*agent-relay-[^\s]+)(?:\s|$)/.test(command);
+}
+function isBrokerProcessCommand(command) {
+    return isBrokerExecutableCommand(command) || isForegroundBrokerCliCommand(command);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function commandHasBrokerName(command, brokerName) {
+    const escapedName = escapeRegExp(brokerName);
+    return new RegExp(`(?:^|\\s)--name(?:\\s+|=)${escapedName}(?:\\s|$)`).test(command);
+}
+function commandHasProjectRoot(command, projectRoot) {
+    const escapedRoot = escapeRegExp(path.resolve(projectRoot));
+    return new RegExp(`(?:^|\\s|=|["'])${escapedRoot}(?:$|\\s|["']|${escapeRegExp(path.sep)})`).test(command);
+}
+async function processCwdMatchesProjectRoot(processInfo, projectRoot, deps) {
+    try {
+        const cwdDetails = await deps.execCommand(`lsof -nP -a -p ${processInfo.pid} -d cwd -Fn`);
+        return cwdDetails.stdout
+            .split('\n')
+            .filter((line) => line.startsWith('n'))
+            .some((line) => path.resolve(line.slice(1)) === projectRoot);
+    }
+    catch {
+        return false;
+    }
+}
+async function terminateProcess(pid, deps, force) {
+    try {
+        deps.killProcess(pid, 'SIGTERM');
+    }
+    catch {
+        return false;
+    }
+    const exited = await waitForProcessExit(pid, force ? 500 : 300, deps);
+    if (exited || !force) {
+        return exited;
+    }
+    try {
+        deps.killProcess(pid, 'SIGKILL');
+    }
+    catch {
+        return false;
+    }
+    return waitForProcessExit(pid, 500, deps);
+}
+async function killOrphanedBrokerProcesses(projectRoot, deps, options) {
+    let matchedCount = 0;
+    let killedCount = 0;
+    try {
+        const resolvedProjectRoot = path.resolve(projectRoot);
+        const brokerName = path.basename(resolvedProjectRoot) || 'project';
+        const candidates = [];
+        try {
+            const processList = await deps.execCommand('ps aux');
+            const relayProcesses = processList.stdout
+                .split('\n')
+                .map(parsePsAuxLine)
+                .filter((process) => process !== null)
+                .filter((process) => isBrokerProcessCommand(process.command));
+            const matchedPids = new Set();
+            for (const processInfo of relayProcesses) {
+                if (commandHasProjectRoot(processInfo.command, resolvedProjectRoot)) {
+                    candidates.push(processInfo);
+                    matchedPids.add(processInfo.pid);
+                }
+            }
+            for (const processInfo of relayProcesses) {
+                if (matchedPids.has(processInfo.pid)) {
+                    continue;
+                }
+                const cwdMatches = await processCwdMatchesProjectRoot(processInfo, resolvedProjectRoot, deps);
+                if (!cwdMatches)
+                    continue;
+                if (isBrokerExecutableCommand(processInfo.command) &&
+                    !commandHasBrokerName(processInfo.command, brokerName)) {
+                    continue;
+                }
+                candidates.push(processInfo);
+                matchedPids.add(processInfo.pid);
+            }
+        }
+        catch {
+            // Expected if ps is unavailable; fall through to no matches.
+        }
+        for (const { pid } of candidates) {
+            if (pid === deps.pid) {
+                continue;
+            }
+            matchedCount += 1;
+            deps.warn(`Killing orphaned broker process (pid: ${pid})`);
+            const killed = await terminateProcess(pid, deps, options?.force === true);
+            if (killed) {
+                killedCount += 1;
+            }
+            else if (options?.force === true) {
+                deps.warn(`Broker orphan process may still be running (pid: ${pid})`);
+            }
+        }
+    }
+    catch {
+        // Best-effort orphan cleanup.
+    }
+    return { matchedCount, killedCount };
+}
+function ensureBundledAgentRelayMcpCommand(deps) {
+    if (deps.env.AGENT_RELAY_MCP_COMMAND?.trim()) {
+        return;
+    }
+    const command = buildBundledAgentRelayMcpCommand(deps.execPath, deps.cliScript, deps.fs.existsSync);
+    if (command) {
+        deps.env.AGENT_RELAY_MCP_COMMAND = command;
+    }
+}
+async function waitForProcessExit(pid, timeoutMs, deps) {
+    const startedAt = deps.now();
+    while (deps.now() - startedAt < timeoutMs) {
+        if (!isProcessRunning(pid, deps)) {
+            return true;
+        }
+        await deps.sleep(100);
+    }
+    return false;
+}
+async function recoverHalfStartedBroker(paths, deps) {
+    deps.fs.mkdirSync(paths.dataDir, { recursive: true });
+    const readiness = await waitForBrokerReadiness(paths, deps, 0, true);
+    if (readiness.state === 'running') {
+        return 'running';
+    }
+    if (readiness.state === 'starting') {
+        deps.warn(`Broker process is running but the API is not ready; killing half-started broker (pid: ${readiness.conn.pid}).`);
+        const stopped = await terminateProcess(readiness.conn.pid, deps, true);
+        if (!stopped) {
+            deps.error(`Failed to stop half-started broker process (pid: ${readiness.conn.pid}). ` +
+                'Run `agent-relay down --force` to retry cleanup, or remove `.agentworkforce/relay/` after stopping the process.');
+            return 'blocked';
+        }
+        cleanupBrokerFiles(paths, deps);
+        return 'recovered';
+    }
+    const orphanCleanup = await killOrphanedBrokerProcesses(paths.projectRoot, deps, { force: true });
+    if (orphanCleanup.matchedCount > 0) {
+        if (orphanCleanup.killedCount < orphanCleanup.matchedCount) {
+            deps.error('Failed to stop all half-started broker processes. ' +
+                'Run `agent-relay down --force` to retry cleanup, or remove `.agentworkforce/relay/` after stopping the processes.');
+            return 'blocked';
+        }
+        cleanupBrokerFiles(paths, deps);
+        return 'recovered';
+    }
+    cleanupBrokerFiles(paths, deps);
+    return 'clear';
+}
+function cleanupBrokerFiles(paths, deps) {
+    const runtimePath = path.join(paths.dataDir, 'runtime.json');
+    const relaySockPath = path.join(paths.dataDir, 'relay.sock');
+    safeUnlink(path.join(paths.dataDir, CONNECTION_FILENAME), deps);
+    safeUnlink(relaySockPath, deps);
+    safeUnlink(runtimePath, deps);
+    // Clean up lock files and legacy pid files
+    try {
+        for (const file of deps.fs.readdirSync(paths.dataDir)) {
+            if (file.startsWith('broker-') && (file.endsWith('.lock') || file.endsWith('.pid'))) {
+                safeUnlink(path.join(paths.dataDir, file), deps);
+                continue;
+            }
+            if (!file.startsWith('mcp-identity-')) {
+                continue;
+            }
+            const pidMatch = file.match(/^mcp-identity-(\d+)/);
+            if (!pidMatch) {
+                continue;
+            }
+            const pid = Number.parseInt(pidMatch[1], 10);
+            if (!isProcessRunning(pid, deps)) {
+                safeUnlink(path.join(paths.dataDir, file), deps);
+            }
+        }
+    }
+    catch {
+        // Ignore read errors while cleaning up.
+    }
+}
+function childUpArgsForDetachedStart(options, deps) {
+    const args = cliUserArgs(deps).filter((arg) => !['--background', '--foreground'].some((name) => matchesCliOption(arg, name)));
+    if (options.dashboard === false && !args.includes('--no-dashboard')) {
+        args.push('--no-dashboard');
+    }
+    if (options.stateDir && !hasCliOption(args, '--state-dir')) {
+        args.push('--state-dir', path.resolve(options.stateDir));
+    }
+    if (options.workspaceKey && !hasCliOption(args, '--workspace-key')) {
+        args.push('--workspace-key', options.workspaceKey);
+    }
+    if (options.brokerName && !hasCliOption(args, '--broker-name')) {
+        args.push('--broker-name', options.brokerName);
+    }
+    if (options.verbose === true && !args.includes('--verbose')) {
+        args.push('--verbose');
+    }
+    if (options.dashboard === false && !args.includes('--foreground')) {
+        args.push('--foreground');
+    }
+    return args;
+}
+function cliUserArgs(deps) {
+    return hasEntrypointArgvSlot(deps) ? deps.argv.slice(2) : deps.argv.slice(1);
+}
+function detachedCliInvocation(deps, args) {
+    if (shouldReexecThroughScript(deps)) {
+        return { command: deps.execPath, args: [deps.cliScript, ...args] };
+    }
+    return { command: deps.execPath, args };
+}
+function hasEntrypointArgvSlot(deps) {
+    return isBundledBunExecutableEntrypoint(deps) || isCliScriptEntrypoint(deps);
+}
+function shouldReexecThroughScript(deps) {
+    return isCliScriptEntrypoint(deps) && !sameCliPath(deps.execPath, deps.cliScript);
+}
+function isCliScriptEntrypoint(deps) {
+    const cliScript = deps.cliScript.trim();
+    if (!cliScript) {
+        return false;
+    }
+    if (isBundledBunExecutableEntrypoint(deps)) {
+        return false;
+    }
+    if (sameCliPath(deps.execPath, cliScript)) {
+        return true;
+    }
+    return (path.isAbsolute(cliScript) ||
+        cliScript.includes('/') ||
+        cliScript.includes('\\') ||
+        /\.[cm]?js$/i.test(cliScript));
+}
+function isBundledBunExecutableEntrypoint(deps) {
+    // Bun --compile exposes argv[1] as a virtual path for the embedded executable.
+    return deps.argv[0] === 'bun' && deps.cliScript.startsWith('/$bunfs/root/');
+}
+function sameCliPath(left, right) {
+    return path.resolve(left) === path.resolve(right);
+}
+function hasCliOption(args, name) {
+    return args.some((arg) => matchesCliOption(arg, name));
+}
+function matchesCliOption(arg, name) {
+    return arg === name || arg.startsWith(`${name}=`);
+}
+async function checkBrokerReadiness(paths, deps, requireApi) {
+    const conn = readBrokerConnectionFromFs(deps.fs, paths.dataDir);
+    if (!conn || conn.pid <= 0) {
+        return { state: 'stopped' };
+    }
+    if (!isProcessRunning(conn.pid, deps)) {
+        safeUnlink(path.join(paths.dataDir, CONNECTION_FILENAME), deps);
+        return { state: 'stopped' };
+    }
+    if (!requireApi) {
+        return { state: 'running', conn };
+    }
+    const statusDetails = await readBrokerStatusDetails(conn);
+    if (statusDetails) {
+        return { state: 'running', conn, statusDetails };
+    }
+    return { state: 'starting', conn };
+}
+async function waitForBrokerReadiness(paths, deps, waitMs, requireApi) {
+    const deadline = deps.now() + waitMs;
+    let latest = await checkBrokerReadiness(paths, deps, requireApi);
+    while (latest.state !== 'running' && waitMs > 0 && deps.now() < deadline) {
+        await deps.sleep(Math.min(STATUS_POLL_INTERVAL_MS, Math.max(0, deadline - deps.now())));
+        latest = await checkBrokerReadiness(paths, deps, requireApi);
+    }
+    return latest;
+}
+function pickDashboardStaticDir(candidates, deps) {
+    const existingCandidates = Array.from(new Set(candidates)).filter((candidate) => deps.fs.existsSync(candidate));
+    if (existingCandidates.length === 0) {
+        return null;
+    }
+    const pageMarkerPriority = [
+        ['metrics.html', path.join('metrics', 'index.html')],
+        ['app.html'],
+        ['index.html'],
+    ];
+    for (const markerGroup of pageMarkerPriority) {
+        const withMarker = existingCandidates.find((candidate) => markerGroup.some((marker) => deps.fs.existsSync(path.join(candidate, marker))));
+        if (withMarker) {
+            return withMarker;
+        }
+    }
+    return existingCandidates[0];
+}
+function getHomeDashboardRoot(deps) {
+    const homeDir = deps.env.HOME || deps.env.USERPROFILE || os.homedir();
+    return path.join(homeDir, '.agentworkforce/relay', 'dashboard');
+}
+function getPriorDashboardRoot(deps) {
+    const homeDir = deps.env.HOME || deps.env.USERPROFILE || '';
+    if (!homeDir) {
+        return null;
+    }
+    return path.join(homeDir, '.relay', 'dashboard');
+}
+function getDashboardRootFromBinary(dashboardBinary, deps) {
+    if (!dashboardBinary || dashboardBinary.endsWith('.js') || dashboardBinary.endsWith('.ts')) {
+        return null;
+    }
+    const binaryDir = path.dirname(dashboardBinary);
+    if (path.basename(binaryDir) !== 'bin') {
+        return null;
+    }
+    const homeDir = deps.env.HOME || deps.env.USERPROFILE || '';
+    const resolvedBinaryDir = path.resolve(binaryDir);
+    const ignoredBinDirs = [
+        homeDir ? path.join(homeDir, '.local', 'bin') : null,
+        path.join('/usr/local', 'bin'),
+    ]
+        .filter((candidate) => Boolean(candidate))
+        .map((candidate) => path.resolve(candidate));
+    if (ignoredBinDirs.includes(resolvedBinaryDir)) {
+        return null;
+    }
+    return path.join(path.dirname(binaryDir), 'dashboard');
+}
+function resolveDashboardStaticDir(dashboardBinary, deps) {
+    const explicitStaticDir = deps.env.RELAY_DASHBOARD_STATIC_DIR ?? deps.env.STATIC_DIR;
+    if (explicitStaticDir && explicitStaticDir.trim()) {
+        return explicitStaticDir;
+    }
+    if (!dashboardBinary) {
+        return null;
+    }
+    if (dashboardBinary.endsWith('.js') || dashboardBinary.endsWith('.ts')) {
+        const dashboardServerOutDir = path.resolve(path.dirname(dashboardBinary), '..', 'out');
+        const siblingDashboardOutDir = path.resolve(path.dirname(dashboardBinary), '..', '..', 'dashboard', 'out');
+        return pickDashboardStaticDir([dashboardServerOutDir, siblingDashboardOutDir], deps);
+    }
+    // Installs place UI assets under the install dir (~/.agentworkforce/relay/dashboard/out
+    // by default, or next to a custom install's bin/ directory). ~/.relay/dashboard/out is
+    // read as a fallback for installs predating that move.
+    const installDashboardRoot = getDashboardRootFromBinary(dashboardBinary, deps);
+    const priorDashboardRoot = getPriorDashboardRoot(deps);
+    const candidates = [
+        installDashboardRoot ? path.join(installDashboardRoot, 'out') : null,
+        path.join(getHomeDashboardRoot(deps), 'out'),
+        priorDashboardRoot ? path.join(priorDashboardRoot, 'out') : null,
+    ].filter((candidate) => Boolean(candidate));
+    return pickDashboardStaticDir(candidates, deps);
+}
+function normalizeLocalhostRelayUrl(relayUrl) {
+    try {
+        const parsed = new URL(relayUrl);
+        if (parsed.hostname === 'localhost') {
+            parsed.hostname = '127.0.0.1';
+        }
+        return parsed.toString().replace(/\/+$/, '');
+    }
+    catch {
+        return relayUrl;
+    }
+}
+function getDefaultDashboardRelayUrl(apiPort) {
+    return normalizeLocalhostRelayUrl(`http://localhost:${apiPort}`);
+}
+function resolveDashboardRelayUrl(apiPort, deps) {
+    const explicitRelayUrl = deps.env.RELAY_DASHBOARD_RELAY_URL;
+    if (explicitRelayUrl && explicitRelayUrl.trim()) {
+        return normalizeLocalhostRelayUrl(explicitRelayUrl.trim());
+    }
+    return getDefaultDashboardRelayUrl(apiPort);
+}
+function isDebugLikeLoggingEnabled(deps) {
+    const rawLevel = String(deps.env.RUST_LOG ?? '').toLowerCase();
+    return rawLevel.includes('debug') || rawLevel.includes('trace');
+}
+function getDashboardSpawnEnv(deps, relayUrl, enableVerboseLogging, relayApiKey, brokerApiKey) {
+    const env = {
+        ...deps.env,
+        RELAY_URL: relayUrl,
+        VERBOSE: enableVerboseLogging || deps.env.VERBOSE === 'true' ? 'true' : deps.env.VERBOSE,
+    };
+    // Pass the workspace key so the dashboard can make Agent Relay calls
+    // (e.g. posting thread replies) without requiring a relaycast.json file.
+    if (relayApiKey) {
+        if (!env.RELAY_WORKSPACE_KEY) {
+            env.RELAY_WORKSPACE_KEY = relayApiKey;
+        }
+        if (!env.RELAY_API_KEY) {
+            env.RELAY_API_KEY = relayApiKey;
+        }
+    }
+    // Pass the broker API key so the dashboard can authenticate with the
+    // broker's HTTP API (e.g. /api/spawn, /api/spawned).
+    if (brokerApiKey) {
+        env.RELAY_BROKER_API_KEY = brokerApiKey;
+    }
+    return env;
+}
+function getDashboardSpawnArgs(paths, port, apiPort, dashboardBinary, relayUrl, enableVerboseLogging, deps) {
+    const args = ['--port', String(port), '--data-dir', paths.dataDir];
+    args.push('--relay-url', relayUrl);
+    const staticDir = resolveDashboardStaticDir(dashboardBinary, deps);
+    if (staticDir) {
+        args.push('--static-dir', staticDir);
+    }
+    if (enableVerboseLogging) {
+        args.push('--verbose');
+    }
+    return args;
+}
+function normalizeDashboardPath(rawDashboardPath) {
+    const trimmed = rawDashboardPath?.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith('/')) {
+        return trimmed;
+    }
+    return `/${trimmed}`;
+}
+function startDashboard(paths, port, apiPort, deps, enableVerboseLogging, dashboardBinaryOverride, relayApiKey, brokerApiKey) {
+    const dashboardBinary = dashboardBinaryOverride === undefined ? deps.findDashboardBinary() : dashboardBinaryOverride;
+    const relayUrl = resolveDashboardRelayUrl(apiPort, deps);
+    const shouldEnableVerbose = enableVerboseLogging || isDebugLikeLoggingEnabled(deps);
+    const args = getDashboardSpawnArgs(paths, port, apiPort, dashboardBinary, relayUrl, shouldEnableVerbose, deps);
+    const launchTarget = dashboardBinary
+        ? dashboardBinary.endsWith('.js')
+            ? `node ${dashboardBinary}`
+            : dashboardBinary
+        : 'npx --yes @agent-relay/dashboard-server@latest';
+    const spawnOpts = {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: getDashboardSpawnEnv(deps, relayUrl, shouldEnableVerbose, relayApiKey, brokerApiKey),
+    };
+    if (shouldEnableVerbose) {
+        deps.log(`[dashboard] Starting: ${launchTarget} ${args.join(' ')}`);
+    }
+    let child;
+    if (dashboardBinary) {
+        // If the binary is a .js file (local dev), run it with node
+        if (dashboardBinary.endsWith('.js')) {
+            child = deps.spawnProcess('node', [dashboardBinary, ...args], spawnOpts);
+        }
+        else {
+            child = deps.spawnProcess(dashboardBinary, args, spawnOpts);
+        }
+    }
+    else {
+        child = deps.spawnProcess('npx', ['--yes', '@agent-relay/dashboard-server@latest', ...args], spawnOpts);
+    }
+    // Capture stderr for error reporting
+    const childAny = child;
+    let stderrBuf = '';
+    const logChunk = (chunk, logger, prefix) => {
+        if (!shouldEnableVerbose) {
+            return;
+        }
+        const text = chunk.toString();
+        for (const line of text.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (trimmed) {
+                logger(`[dashboard] ${prefix}: ${trimmed}`);
+            }
+        }
+    };
+    childAny.stdout?.on?.('data', (chunk) => {
+        logChunk(chunk, deps.log, 'stdout');
+    });
+    childAny.stderr?.on?.('data', (chunk) => {
+        stderrBuf += chunk.toString();
+        logChunk(chunk, deps.warn, 'stderr');
+    });
+    // Report early crashes
+    childAny.on?.('exit', (...exitArgs) => {
+        const code = exitArgs[0];
+        const signal = exitArgs[1];
+        if (code !== null && code !== 0) {
+            deps.error(`Dashboard process exited with code ${code}`);
+            if (stderrBuf.trim()) {
+                deps.error(stderrBuf.trim().split('\n').slice(-5).join('\n'));
+            }
+        }
+        else if (signal && signal !== 'SIGINT' && signal !== 'SIGTERM') {
+            deps.error(`Dashboard process killed by signal ${signal}`);
+        }
+    });
+    return child;
+}
+async function resolveStartedDashboardPort(process, preferredPort, deps) {
+    return new Promise((resolve) => {
+        let resolved = false;
+        const processAny = process;
+        const detach = () => {
+            process.stdout?.off?.('data', extractPort);
+            process.stdout?.removeListener?.('data', extractPort);
+            process.stderr?.off?.('data', extractPort);
+            process.stderr?.removeListener?.('data', extractPort);
+            processAny.off?.('exit', handleExit);
+            processAny.removeListener?.('exit', handleExit);
+            clearTimeout(timer);
+        };
+        const timer = setTimeout(() => {
+            if (resolved)
+                return;
+            resolved = true;
+            detach();
+            deps.warn(`Dashboard did not report its bound port quickly; assuming requested port ${preferredPort}`);
+            resolve(preferredPort);
+        }, 3000);
+        const finalize = (port) => {
+            if (resolved)
+                return;
+            resolved = true;
+            detach();
+            resolve(port);
+        };
+        const handleExit = (...exitArgs) => {
+            const code = exitArgs[0];
+            const signal = exitArgs[1];
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            detach();
+            if (code !== null && code !== 0) {
+                deps.warn(`Dashboard exited before reporting its port (code: ${code}).`);
+            }
+            else if (signal && signal !== 'SIGINT' && signal !== 'SIGTERM') {
+                deps.warn(`Dashboard exited before reporting its port (signal: ${signal}).`);
+            }
+            else {
+                deps.warn('Dashboard exited before reporting its bound port.');
+            }
+            resolve(null);
+        };
+        const extractPort = (...chunkArgs) => {
+            const firstChunk = chunkArgs[0];
+            if (!firstChunk) {
+                return;
+            }
+            const chunk = Buffer.isBuffer(firstChunk)
+                ? firstChunk
+                : typeof firstChunk === 'string'
+                    ? Buffer.from(firstChunk)
+                    : Buffer.from(JSON.stringify(firstChunk));
+            const match = chunk.toString().match(/Server running at http:\/\/localhost:(\d+)/i);
+            if (!match?.[1]) {
+                return;
+            }
+            const parsed = Number.parseInt(match[1], 10);
+            if (!Number.isNaN(parsed)) {
+                finalize(parsed);
+            }
+        };
+        process.stdout?.on?.('data', extractPort);
+        process.stderr?.on?.('data', extractPort);
+        processAny.on?.('exit', handleExit);
+    });
+}
+/**
+ * Check if the cached dashboard UI assets match the installed dashboard-server
+ * binary version. If they are stale (or missing a version marker), re-download
+ * the latest assets from the relay-dashboard GitHub release.
+ */
+async function refreshDashboardAssetsIfStale(dashboardBinary, deps) {
+    if (!dashboardBinary || dashboardBinary.endsWith('.js') || dashboardBinary.endsWith('.ts')) {
+        // Dev mode or npx — skip
+        return;
+    }
+    // Get installed binary version (async to avoid blocking event loop)
+    let binaryVersion;
+    try {
+        const versionResult = await deps.execCommand(`${JSON.stringify(dashboardBinary)} --version`);
+        binaryVersion = versionResult.stdout.trim();
+    }
+    catch {
+        return; // Can't determine version — skip
+    }
+    if (!binaryVersion) {
+        return;
+    }
+    const targetDir = getDashboardRootFromBinary(dashboardBinary, deps) ?? getHomeDashboardRoot(deps);
+    const assetsDir = path.join(targetDir, 'out');
+    const versionFile = path.join(targetDir, '.version');
+    // Check if assets match the binary version
+    try {
+        const cachedVersion = deps.fs.readFileSync(versionFile, 'utf-8').trim();
+        if (cachedVersion === binaryVersion) {
+            return; // Up to date
+        }
+    }
+    catch {
+        // No version file — need to download if assets exist but are unversioned,
+        // or if assets don't exist at all
+        if (deps.fs.existsSync(assetsDir)) {
+            // Assets exist but no version marker — they're from an old install
+        }
+        else {
+            // No assets at all — need to download
+        }
+    }
+    deps.log(`Updating dashboard UI assets (${binaryVersion})...`);
+    const uiUrl = 'https://github.com/AgentWorkforce/relay-dashboard/releases/latest/download/dashboard-ui.tar.gz';
+    let tempDir;
+    let tempFile;
+    try {
+        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `dashboard-ui-${deps.pid}-`));
+        tempFile = path.join(tempDir, 'dashboard-ui.tar.gz');
+        // Download (async to avoid blocking event loop during network I/O)
+        await deps.execCommand(`curl -fsSL --max-time 30 ${JSON.stringify(uiUrl)} -o ${JSON.stringify(tempFile)}`);
+        // Verify it's a valid gzip
+        const header = Buffer.alloc(2);
+        const fd = fs.openSync(tempFile, 'r');
+        fs.readSync(fd, header, 0, 2, 0);
+        fs.closeSync(fd);
+        if (header[0] !== 0x1f || header[1] !== 0x8b) {
+            if (tempFile)
+                deps.fs.unlinkSync(tempFile);
+            return; // Not a valid gzip file
+        }
+        // Remove old assets and extract (async to avoid blocking event loop)
+        deps.fs.rmSync(assetsDir, { recursive: true, force: true });
+        deps.fs.mkdirSync(targetDir, { recursive: true });
+        await deps.execCommand(`tar -xzf ${JSON.stringify(tempFile)} -C ${JSON.stringify(targetDir)}`);
+        if (tempFile)
+            deps.fs.unlinkSync(tempFile);
+        // Write version marker only after confirming extraction succeeded
+        if (deps.fs.existsSync(path.join(assetsDir, 'index.html'))) {
+            deps.fs.writeFileSync(versionFile, binaryVersion);
+            deps.log(`Dashboard UI assets updated to ${binaryVersion}`);
+        }
+        else {
+            deps.warn('Dashboard UI extraction may be incomplete — skipping version marker');
+        }
+    }
+    catch {
+        // Best-effort — don't block startup
+        try {
+            if (tempFile)
+                deps.fs.unlinkSync(tempFile);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    finally {
+        try {
+            if (tempDir)
+                deps.fs.rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+async function startDashboardWithFallback(paths, dashboardPort, apiPort, deps, enableVerboseLogging, relayApiKey, brokerApiKey) {
+    const preferredBinary = deps.findDashboardBinary();
+    await refreshDashboardAssetsIfStale(preferredBinary, deps);
+    let process = startDashboard(paths, dashboardPort, apiPort, deps, enableVerboseLogging, preferredBinary, relayApiKey, brokerApiKey);
+    let port = await resolveStartedDashboardPort(process, dashboardPort, deps);
+    if (port === null && preferredBinary) {
+        deps.warn('Retrying dashboard startup using npx @agent-relay/dashboard-server@latest');
+        process = startDashboard(paths, dashboardPort, apiPort, deps, enableVerboseLogging, null, relayApiKey, brokerApiKey);
+        port = await resolveStartedDashboardPort(process, dashboardPort, deps);
+    }
+    return { process, port };
+}
+async function waitForDashboard(port, process, deps, isShuttingDown) {
+    for (let i = 0; i < 20; i++) {
+        await new Promise((r) => setTimeout(r, 500));
+        if (process.killed) {
+            if (!isShuttingDown()) {
+                deps.warn(`Warning: Dashboard process exited before becoming ready on port ${port}`);
+            }
+            return;
+        }
+        try {
+            const resp = await fetch(`http://localhost:${port}/health`);
+            if (resp.ok)
+                return; // Dashboard is up
+        }
+        catch {
+            // Not ready yet
+        }
+    }
+    if (!isShuttingDown()) {
+        deps.warn(`Warning: Dashboard not responding on port ${port} after 10s`);
+    }
+}
+async function discoverExistingBrokerApiPort(preferredApiPort, maxAttempts, deps) {
+    const attempts = Math.max(1, maxAttempts);
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        const candidatePort = preferredApiPort + attempt;
+        if (candidatePort > MAX_PORT) {
+            return preferredApiPort;
+        }
+        try {
+            const response = await fetch(`http://localhost:${candidatePort}/health`);
+            if (response.ok) {
+                if (attempt > 0) {
+                    deps.warn(`Detected existing broker API on port ${candidatePort}.`);
+                }
+                return candidatePort;
+            }
+        }
+        catch {
+            // Keep scanning.
+        }
+    }
+    return preferredApiPort;
+}
+async function shutdownUpResources(relay, dashboardProcess, dataDir, deps, ownsBroker) {
+    if (dashboardProcess && !dashboardProcess.killed) {
+        try {
+            dashboardProcess.kill('SIGTERM');
+        }
+        catch {
+            // Best-effort cleanup.
+        }
+    }
+    await relay.shutdown().catch(() => undefined);
+    if (ownsBroker) {
+        safeUnlink(path.join(dataDir, CONNECTION_FILENAME), deps);
+    }
+}
+// eslint-disable-next-line complexity
+export async function runUpCommand(options, deps) {
+    ensureBundledAgentRelayMcpCommand(deps);
+    if (options.background && options.foreground) {
+        deps.error('Cannot use --background and --foreground together.');
+        deps.exit(1);
+        return;
+    }
+    const paths = deps.getProjectPaths();
+    // --state-dir overrides where the broker writes state / connection files
+    if (options.stateDir) {
+        const resolved = path.resolve(options.stateDir);
+        paths.dataDir = resolved;
+        deps.env.AGENT_RELAY_STATE_DIR = resolved;
+    }
+    if (options.background || (options.dashboard === false && !options.foreground)) {
+        const preflight = await recoverHalfStartedBroker(paths, deps);
+        if (preflight === 'running') {
+            const pid = readBrokerPid(paths.dataDir, deps);
+            deps.error(pid
+                ? `Broker already running for this project (pid: ${pid}).`
+                : 'Broker already running for this project.');
+            deps.error('Run `agent-relay status` to inspect it, then `agent-relay down` to stop it.');
+            deps.exit(1);
+            return;
+        }
+        if (preflight === 'blocked') {
+            deps.exit(1);
+            return;
+        }
+        const args = childUpArgsForDetachedStart(options, deps);
+        const invocation = detachedCliInvocation(deps, args);
+        let child;
+        try {
+            child = deps.spawnProcess(invocation.command, invocation.args, {
+                detached: true,
+                stdio: 'ignore',
+                env: deps.env,
+            });
+        }
+        catch (err) {
+            deps.error(`Failed to start broker in background: ${describeError(err)}`);
+            deps.exit(1);
+            return;
+        }
+        child.unref?.();
+        const readiness = await waitForBrokerReadiness(paths, deps, DETACHED_START_READY_TIMEOUT_MS, true);
+        if (readiness.state !== 'running') {
+            const pid = readiness.state === 'starting' ? readiness.conn.pid : child.pid;
+            deps.error(pid
+                ? `Broker background start did not become ready within ${DETACHED_START_READY_TIMEOUT_MS / 1000}s (pid: ${pid}).`
+                : `Broker background start did not become ready within ${DETACHED_START_READY_TIMEOUT_MS / 1000}s.`);
+            if (readiness.state === 'starting') {
+                deps.error('Broker process is running, but the API did not become ready.');
+            }
+            deps.error('Run `agent-relay status --wait-for=10` for details, or `agent-relay down --force` to clean up.');
+            const cleanupPids = new Set();
+            if (typeof child.pid === 'number' && child.pid > 0) {
+                cleanupPids.add(child.pid);
+            }
+            if (readiness.state === 'starting') {
+                cleanupPids.add(readiness.conn.pid);
+            }
+            for (const cleanupPid of cleanupPids) {
+                deps.warn(`Cleaning up failed broker start (pid: ${cleanupPid})`);
+                const stopped = await terminateProcess(cleanupPid, deps, true);
+                if (!stopped) {
+                    deps.error(`Failed to stop half-started broker process (pid: ${cleanupPid}). ` +
+                        'Run `agent-relay down --force` to retry cleanup, or remove `.agentworkforce/relay/` after stopping the process.');
+                }
+            }
+            cleanupBrokerFiles(paths, deps);
+            deps.exit(1);
+            return;
+        }
+        deps.log('Broker started.');
+        deps.log(`Broker PID: ${readiness.conn.pid}`);
+        deps.log('Stop with: agent-relay down');
+        deps.exit(0);
+        return;
+    }
+    const wantsDashboard = options.dashboard !== false;
+    const requestedDashboardPort = Number.parseInt(options.port ?? '3888', 10) || 3888;
+    const shouldReuseExistingBroker = options.reuseExistingBroker === true;
+    const dashboardPort = wantsDashboard
+        ? await resolveDashboardPortWithFallback(requestedDashboardPort, MAX_DASHBOARD_PORT_ATTEMPTS, deps)
+        : requestedDashboardPort;
+    if (wantsDashboard && dashboardPort !== requestedDashboardPort) {
+        deps.warn(`Requested dashboard port ${requestedDashboardPort} is already in use; active dashboard will run on ${dashboardPort}.`);
+    }
+    deps.fs.mkdirSync(paths.dataDir, { recursive: true });
+    let existingPid = readBrokerPid(paths.dataDir, deps);
+    let ownsBroker = true;
+    let relay = null;
+    let apiPort = dashboardPort + 1;
+    let dashboardProcess;
+    const dashboardVerbose = Boolean(options.verbose) || isDebugLikeLoggingEnabled(deps);
+    let shuttingDown = false;
+    let sigintCount = 0;
+    let shutdownPromise;
+    const shutdownOnce = async () => {
+        if (!shutdownPromise) {
+            shuttingDown = true;
+            if (relay === null) {
+                shutdownPromise = Promise.resolve();
+            }
+            else {
+                shutdownPromise = shutdownUpResources(relay, dashboardProcess, paths.dataDir, deps, ownsBroker);
+            }
+        }
+        await shutdownPromise;
+    };
+    try {
+        if (existingPid !== null) {
+            if (isProcessRunning(existingPid, deps)) {
+                if (!shouldReuseExistingBroker || !wantsDashboard) {
+                    deps.error(`Broker already running for this project (pid: ${existingPid}).`);
+                    deps.error('Run `agent-relay status` to inspect it, then `agent-relay down` to stop it.');
+                    deps.exit(1);
+                    return;
+                }
+                apiPort = await discoverExistingBrokerApiPort(Math.max(1, apiPort), MAX_API_PORT_ATTEMPTS, deps);
+                const reusableRelay = await deps.createRelay(paths.projectRoot, apiPort);
+                try {
+                    await reusableRelay.getStatus();
+                }
+                catch {
+                    await reusableRelay.shutdown().catch(() => undefined);
+                    deps.warn(`Broker already running for this project (pid: ${existingPid}), but API port ${apiPort} is not responding.`);
+                    deps.warn('Treating this as stale broker state and starting a fresh broker.');
+                    safeUnlink(path.join(paths.dataDir, CONNECTION_FILENAME), deps);
+                    existingPid = null;
+                }
+                if (existingPid === null) {
+                    // fallthrough and start a fresh broker
+                }
+                else {
+                    relay = reusableRelay;
+                    ownsBroker = false;
+                    const dashboardRelayUrl = resolveDashboardRelayUrl(apiPort, deps);
+                    const expectedRelayUrl = getDefaultDashboardRelayUrl(apiPort);
+                    if (deps.env.RELAY_DASHBOARD_RELAY_URL &&
+                        deps.env.RELAY_DASHBOARD_RELAY_URL.trim() !== '' &&
+                        deps.env.RELAY_DASHBOARD_RELAY_URL.trim() !== expectedRelayUrl) {
+                        deps.warn(`RELAY_DASHBOARD_RELAY_URL is set to ${deps.env.RELAY_DASHBOARD_RELAY_URL.trim()}, ` +
+                            `but this session computed ${expectedRelayUrl}.`);
+                    }
+                    deps.log(`Relay API: ${dashboardRelayUrl}`);
+                    if (dashboardVerbose) {
+                        deps.log(`[dashboard] relay target resolved from config: ${dashboardRelayUrl}`);
+                    }
+                    deps.log(`Project: ${paths.projectRoot}`);
+                    deps.log('Mode: broker (stdio)');
+                    deps.log(`Workspace Key: ${relay.workspaceKey ?? 'unknown'}`);
+                    deps.log('Broker already running for this project; reusing existing broker.');
+                    if (wantsDashboard) {
+                        const brokerConn = readBrokerConnectionFromFs(deps.fs, paths.dataDir);
+                        const dashboardStart = await startDashboardWithFallback(paths, dashboardPort, apiPort, deps, dashboardVerbose, relay?.workspaceKey, brokerConn?.api_key);
+                        dashboardProcess = dashboardStart.process;
+                        const startedDashboardPort = dashboardStart.port;
+                        if (startedDashboardPort === null) {
+                            deps.warn('Dashboard failed to start. Check dashboard error logs above.');
+                        }
+                        else {
+                            if (startedDashboardPort !== dashboardPort) {
+                                deps.warn(`Dashboard port ${dashboardPort} was already in use, so dashboard started on ${startedDashboardPort}`);
+                            }
+                            const dashboardPath = normalizeDashboardPath(options.dashboardPath);
+                            const dashboardUrl = dashboardPath
+                                ? `http://localhost:${startedDashboardPort}${dashboardPath}`
+                                : `http://localhost:${startedDashboardPort}`;
+                            deps.log(`Dashboard: ${dashboardUrl}`);
+                            waitForDashboard(startedDashboardPort, dashboardProcess, deps, () => shuttingDown).catch(() => { });
+                        }
+                    }
+                    deps.onSignal('SIGINT', async () => {
+                        sigintCount += 1;
+                        if (shuttingDown) {
+                            if (sigintCount >= 2) {
+                                deps.warn('Force exiting...');
+                                deps.exit(130);
+                            }
+                            return;
+                        }
+                        deps.log('\nStopping...');
+                        await shutdownOnce();
+                        deps.exit(0);
+                    });
+                    deps.onSignal('SIGTERM', async () => {
+                        if (shuttingDown) {
+                            return;
+                        }
+                        await shutdownOnce();
+                        deps.exit(0);
+                    });
+                    await deps.holdOpen();
+                    return;
+                }
+            }
+            safeUnlink(path.join(paths.dataDir, CONNECTION_FILENAME), deps);
+            existingPid = null;
+        }
+        // If a workspace key was explicitly provided, inject it into the environment
+        // for both current tools and older compatibility paths.
+        if (options.workspaceKey) {
+            deps.env.RELAY_WORKSPACE_KEY = options.workspaceKey;
+            deps.env.RELAY_API_KEY = options.workspaceKey;
+        }
+        // Kill any orphaned broker processes for this project that lost their PID
+        // files (e.g. user deleted .agentworkforce/relay/ while broker was running).
+        await killOrphanedBrokerProcesses(paths.projectRoot, deps);
+        const started = await startBrokerWithPortFallback(paths, dashboardPort, deps, options.brokerName);
+        relay = started.relay;
+        apiPort = started.apiPort;
+        const dashboardRelayUrl = resolveDashboardRelayUrl(apiPort, deps);
+        const expectedRelayUrl = getDefaultDashboardRelayUrl(apiPort);
+        if (deps.env.RELAY_DASHBOARD_RELAY_URL &&
+            deps.env.RELAY_DASHBOARD_RELAY_URL.trim() !== '' &&
+            deps.env.RELAY_DASHBOARD_RELAY_URL.trim() !== expectedRelayUrl) {
+            deps.warn(`RELAY_DASHBOARD_RELAY_URL is set to ${deps.env.RELAY_DASHBOARD_RELAY_URL.trim()}, ` +
+                `but this session computed ${expectedRelayUrl}.`);
+        }
+        deps.log(`Relay API: ${dashboardRelayUrl}`);
+        if (dashboardVerbose) {
+            deps.log(`[dashboard] relay target resolved from config: ${dashboardRelayUrl}`);
+        }
+        deps.log(`Project: ${paths.projectRoot}`);
+        deps.log('Mode: broker (stdio)');
+        deps.log(`Workspace Key: ${relay.workspaceKey ?? 'unknown'}`);
+        deps.log('Broker started.');
+        if (wantsDashboard) {
+            const brokerConn = readBrokerConnectionFromFs(deps.fs, paths.dataDir);
+            const dashboardStart = await startDashboardWithFallback(paths, dashboardPort, apiPort, deps, dashboardVerbose, relay?.workspaceKey, brokerConn?.api_key);
+            dashboardProcess = dashboardStart.process;
+            const startedDashboardPort = dashboardStart.port;
+            if (startedDashboardPort === null) {
+                deps.warn('Dashboard failed to start. Check dashboard error logs above.');
+            }
+            else {
+                if (startedDashboardPort !== dashboardPort) {
+                    deps.warn(`Dashboard port ${dashboardPort} was already in use, so dashboard started on ${startedDashboardPort}`);
+                }
+                const dashboardPath = normalizeDashboardPath(options.dashboardPath);
+                const dashboardUrl = dashboardPath
+                    ? `http://localhost:${startedDashboardPort}${dashboardPath}`
+                    : `http://localhost:${startedDashboardPort}`;
+                deps.log(`Dashboard: ${dashboardUrl}`);
+                // Verify the dashboard is actually reachable (non-blocking)
+                waitForDashboard(startedDashboardPort, dashboardProcess, deps, () => shuttingDown).catch(() => { });
+            }
+        }
+        const teamsConfig = deps.loadTeamsConfig(paths.projectRoot);
+        const shouldSpawn = options.spawn === true ? true : options.spawn === false ? false : Boolean(teamsConfig?.autoSpawn);
+        if (shouldSpawn && teamsConfig && teamsConfig.agents.length > 0) {
+            if (wantsDashboard) {
+                deps.warn('Warning: auto-spawn from teams.json is skipped when dashboard mode manages the broker');
+            }
+            else {
+                for (const agent of teamsConfig.agents) {
+                    await relay.spawn({
+                        name: agent.name,
+                        cli: agent.cli,
+                        channels: ['general'],
+                        task: agent.task ?? '',
+                        team: teamsConfig.team,
+                    });
+                }
+            }
+        }
+        else if (options.spawn === true && !teamsConfig) {
+            deps.warn('Warning: --spawn specified but no teams.json found');
+        }
+        deps.onSignal('SIGINT', async () => {
+            sigintCount += 1;
+            if (shuttingDown) {
+                if (sigintCount >= 2) {
+                    deps.warn('Force exiting...');
+                    deps.exit(130);
+                }
+                return;
+            }
+            deps.log('\nStopping...');
+            await shutdownOnce();
+            deps.exit(0);
+        });
+        deps.onSignal('SIGTERM', async () => {
+            if (shuttingDown) {
+                return;
+            }
+            await shutdownOnce();
+            deps.exit(0);
+        });
+        await deps.holdOpen();
+    }
+    catch (err) {
+        await shutdownOnce();
+        const message = toErrorMessage(err);
+        const stage = classifyBrokerStartStage(err, message, wantsDashboard);
+        track('broker_start_failed', {
+            stage,
+            error_class: classifyBrokerStartError(err),
+        });
+        if (errorCode(err) === 'EADDRINUSE' && wantsDashboard) {
+            deps.error(`Dashboard port ${dashboardPort} is already in use.`);
+        }
+        else if (isBrokerAlreadyRunningError(message)) {
+            reportAlreadyRunningError(message, paths.dataDir, deps);
+        }
+        else {
+            deps.error(`Failed to start broker: ${describeError(err)}`);
+        }
+        deps.exit(1);
+    }
+}
+// eslint-disable-next-line complexity, max-depth
+export async function runDownCommand(options, deps) {
+    const paths = deps.getProjectPaths();
+    if (options.stateDir) {
+        paths.dataDir = path.resolve(options.stateDir);
+    }
+    const timeout = Number.parseInt(options.timeout ?? '5000', 10) || 5000;
+    if (options.all) {
+        deps.log('Stopping all agent-relay processes...');
+        try {
+            const { stdout } = await deps.execCommand('ps aux');
+            const pids = [];
+            for (const line of stdout.split('\n')) {
+                if (!line.includes('agent-relay') || !line.includes(' up') || line.includes('agent-relay-mcp')) {
+                    continue;
+                }
+                const fields = line.trim().split(/\s+/);
+                const pid = Number.parseInt(fields[1], 10);
+                if (!Number.isNaN(pid) && pid > 0 && pid !== deps.pid) {
+                    pids.push(pid);
+                }
+            }
+            for (const pid of pids) {
+                try {
+                    deps.killProcess(pid, 'SIGTERM');
+                }
+                catch {
+                    // Ignore dead pids.
+                }
+            }
+            if (options.force) {
+                await deps.sleep(2000);
+                for (const pid of pids) {
+                    // eslint-disable-next-line max-depth
+                    if (isProcessRunning(pid, deps)) {
+                        // eslint-disable-next-line max-depth
+                        try {
+                            deps.killProcess(pid, 'SIGKILL');
+                        }
+                        catch {
+                            // Ignore dead pids.
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            deps.error(`Error finding processes: ${toErrorMessage(err)}`);
+        }
+        cleanupBrokerFiles(paths, deps);
+        deps.log('Done');
+        return;
+    }
+    const conn = readBrokerConnectionFromFs(deps.fs, paths.dataDir);
+    if (!conn) {
+        if (options.force) {
+            await killOrphanedBrokerProcesses(paths.projectRoot, deps, { force: true });
+            cleanupBrokerFiles(paths, deps);
+            deps.log('Cleaned up (was not running)');
+        }
+        else {
+            deps.log('Not running');
+        }
+        return;
+    }
+    const pid = conn.pid;
+    if (!pid || pid <= 0) {
+        cleanupBrokerFiles(paths, deps);
+        deps.log('Cleaned up stale state (invalid connection file)');
+        return;
+    }
+    if (!isProcessRunning(pid, deps)) {
+        cleanupBrokerFiles(paths, deps);
+        deps.log('Cleaned up stale state (process was not running)');
+        return;
+    }
+    try {
+        deps.log(`Stopping broker (pid: ${pid})...`);
+        deps.killProcess(pid, 'SIGTERM');
+        const exited = await waitForProcessExit(pid, timeout, deps);
+        if (!exited) {
+            // eslint-disable-next-line max-depth
+            if (options.force) {
+                deps.log('Graceful shutdown timed out, forcing...');
+                // eslint-disable-next-line max-depth
+                try {
+                    deps.killProcess(pid, 'SIGKILL');
+                    await waitForProcessExit(pid, 2000, deps);
+                }
+                catch {
+                    // Ignore kill errors.
+                }
+            }
+            else {
+                deps.log(`Graceful shutdown timed out after ${timeout}ms. Use --force to kill.`);
+                return;
+            }
+        }
+        cleanupBrokerFiles(paths, deps);
+        deps.log('Stopped');
+    }
+    catch (err) {
+        const withCode = err;
+        if (withCode.code === 'ESRCH') {
+            cleanupBrokerFiles(paths, deps);
+            deps.log('Cleaned up stale state');
+            return;
+        }
+        deps.error(`Error stopping broker: ${toErrorMessage(err)}`);
+    }
+}
+export async function runStatusCommand(deps, options) {
+    const paths = deps.getProjectPaths();
+    if (options?.stateDir) {
+        paths.dataDir = path.resolve(options.stateDir);
+    }
+    const waitMs = parseWaitForMs(options?.waitFor, deps);
+    if (waitMs === null) {
+        return;
+    }
+    const readiness = await waitForBrokerReadiness(paths, deps, waitMs, waitMs > 0);
+    if (readiness.state === 'stopped') {
+        deps.log('Status: STOPPED');
+        if (waitMs > 0) {
+            deps.exit(1);
+        }
+        return;
+    }
+    if (readiness.state === 'starting') {
+        deps.log('Status: STARTING');
+        deps.log('Mode: broker (stdio)');
+        deps.log(`PID: ${readiness.conn.pid}`);
+        deps.log(`Project: ${paths.projectRoot}`);
+        deps.warn('Broker process is running, but the API did not become ready before timeout.');
+        deps.exit(1);
+        return;
+    }
+    deps.log('Status: RUNNING');
+    deps.log('Mode: broker (stdio)');
+    deps.log(`PID: ${readiness.conn.pid}`);
+    deps.log(`Project: ${paths.projectRoot}`);
+    // Query the running broker for additional status info
+    const statusDetails = readiness.statusDetails ?? (waitMs > 0 ? null : await readBrokerStatusDetails(readiness.conn));
+    if (statusDetails) {
+        const { status, session } = statusDetails;
+        if (typeof status.agent_count === 'number') {
+            deps.log(`Agents: ${status.agent_count}`);
+        }
+        if (typeof status.pending_delivery_count === 'number' && status.pending_delivery_count > 0) {
+            deps.log(`Pending deliveries: ${status.pending_delivery_count}`);
+        }
+        if (session?.workspace_key) {
+            deps.log(`Workspace Key: ${session.workspace_key}`);
+            deps.log(`Observer: https://agentrelay.com/observer?key=${session.workspace_key}`);
+        }
+    }
+}
+function parseWaitForMs(rawValue, deps) {
+    const rawWaitFor = rawValue?.trim();
+    if (rawWaitFor !== undefined && !/^\d+(?:\.\d+)?$/.test(rawWaitFor)) {
+        deps.error('--wait-for must be a non-negative number of seconds.');
+        deps.exit(1);
+        return null;
+    }
+    const waitSeconds = rawWaitFor === undefined ? 0 : Number.parseFloat(rawWaitFor);
+    return waitSeconds > 0 ? waitSeconds * 1000 : 0;
+}
+async function readBrokerStatusDetails(conn) {
+    const client = new HarnessDriverClient({ baseUrl: conn.url, apiKey: conn.api_key });
+    try {
+        const status = await client.getStatus();
+        const session = await client.getSession().catch(() => null);
+        return { status, session };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        client.disconnect();
+    }
+}
+//# sourceMappingURL=broker-lifecycle.js.map