agent-relay 2.0.12 → 2.0.14

package/packages/wrapper/dist/relay-pty-orchestrator.js

@@ -19,7 +19,7 @@ import { spawn } from 'node:child_process';
 import { createConnection } from 'node:net';
 import { createHash } from 'node:crypto';
 import { join, dirname } from 'node:path';
-import { existsSync, unlinkSync, mkdirSync, symlinkSync, lstatSync, rmSync, watch, readdirSync } from 'node:fs';
+import { existsSync, unlinkSync, mkdirSync, symlinkSync, lstatSync, rmSync, watch, readdirSync, readlinkSync, writeFileSync, appendFileSync } from 'node:fs';
 import { getProjectPaths } from '@agent-relay/config/project-namespace';
 import { fileURLToPath } from 'node:url';
 // Get the directory where this module is located
@@ -63,6 +63,8 @@ export class RelayPtyOrchestrator extends BaseWrapper {
     isInteractive = false;
     // Injection state
     pendingInjections = new Map();
+    // Pending SendEnter requests (for stuck input recovery)
+    pendingSendEnter = new Map();
     backpressureActive = false;
     readyForMessages = false;
     // Adaptive throttle for message queue - adjusts delay based on success/failure
@@ -168,17 +170,39 @@ export class RelayPtyOrchestrator extends BaseWrapper {
     }
     /**
      * Debug log - only outputs when debug is enabled
+     * Writes to log file to avoid polluting TUI output
      */
     log(message) {
         if (this.config.debug) {
-            console.log(`[relay-pty-orchestrator:${this.config.name}] ${message}`);
+            const logLine = `${new Date().toISOString()} [relay-pty-orchestrator:${this.config.name}] ${message}\n`;
+            try {
+                const logDir = dirname(this._logPath);
+                if (!existsSync(logDir)) {
+                    mkdirSync(logDir, { recursive: true });
+                }
+                appendFileSync(this._logPath, logLine);
+            }
+            catch {
+                // Fallback to stderr if file write fails (only during init before _logPath is set)
+            }
         }
     }
     /**
      * Error log - always outputs (errors are important)
+     * Writes to log file to avoid polluting TUI output
      */
     logError(message) {
-        console.error(`[relay-pty-orchestrator:${this.config.name}] ERROR: ${message}`);
+        const logLine = `${new Date().toISOString()} [relay-pty-orchestrator:${this.config.name}] ERROR: ${message}\n`;
+        try {
+            const logDir = dirname(this._logPath);
+            if (!existsSync(logDir)) {
+                mkdirSync(logDir, { recursive: true });
+            }
+            appendFileSync(this._logPath, logLine);
+        }
+        catch {
+            // Fallback to stderr if file write fails (only during init before _logPath is set)
+        }
     }
     /**
      * Get the outbox path for this agent (for documentation purposes)
@@ -239,22 +263,82 @@ export class RelayPtyOrchestrator extends BaseWrapper {
                 if (!existsSync(linkParent)) {
                     mkdirSync(linkParent, { recursive: true });
                 }
-                if (existsSync(linkPath)) {
+                // Remove existing path if it exists (file, symlink, or directory)
+                // Use lstatSync instead of existsSync to detect broken symlinks
+                // (existsSync returns false for broken symlinks, but the symlink itself still exists)
+                let pathExists = false;
+                try {
+                    lstatSync(linkPath);
+                    pathExists = true;
+                }
+                catch {
+                    // Path doesn't exist at all - proceed to create symlink
+                }
+                if (pathExists) {
                     try {
                         const stats = lstatSync(linkPath);
-                        if (stats.isSymbolicLink() || stats.isFile()) {
+                        if (stats.isSymbolicLink()) {
+                            // Handle both valid and broken symlinks
+                            try {
+                                const currentTarget = readlinkSync(linkPath);
+                                if (currentTarget === targetPath) {
+                                    // Symlink already points to correct target, no need to recreate
+                                    this.log(` Symlink already exists and is correct: ${linkPath} -> ${targetPath}`);
+                                    return;
+                                }
+                            }
+                            catch {
+                                // Broken symlink (target doesn't exist) - remove it
+                                this.log(` Removing broken symlink: ${linkPath}`);
+                            }
+                            unlinkSync(linkPath);
+                        }
+                        else if (stats.isFile()) {
                             unlinkSync(linkPath);
                         }
                         else if (stats.isDirectory()) {
+                            // Force remove directory - this is critical for fixing existing directories
                             rmSync(linkPath, { recursive: true, force: true });
+                            // Verify removal succeeded using lstatSync to catch broken symlinks
+                            try {
+                                lstatSync(linkPath);
+                                throw new Error(`Failed to remove existing directory: ${linkPath}`);
+                            }
+                            catch (err) {
+                                if (err.code !== 'ENOENT') {
+                                    throw err; // Re-throw if it's not a "doesn't exist" error
+                                }
+                                // Path successfully removed
+                            }
                         }
                     }
-                    catch {
-                        // Ignore cleanup errors
+                    catch (err) {
+                        // Log cleanup errors instead of silently ignoring them
+                        this.logError(` Failed to clean up existing path ${linkPath}: ${err.message}`);
+                        throw err; // Re-throw to prevent symlink creation on failed cleanup
+                    }
+                }
+                // Create the symlink
+                try {
+                    symlinkSync(targetPath, linkPath);
+                    // Verify symlink was created correctly
+                    if (!existsSync(linkPath)) {
+                        throw new Error(`Symlink creation failed: ${linkPath}`);
+                    }
+                    const verifyStats = lstatSync(linkPath);
+                    if (!verifyStats.isSymbolicLink()) {
+                        throw new Error(`Created path is not a symlink: ${linkPath}`);
                     }
+                    const verifyTarget = readlinkSync(linkPath);
+                    if (verifyTarget !== targetPath) {
+                        throw new Error(`Symlink points to wrong target: expected ${targetPath}, got ${verifyTarget}`);
+                    }
+                    this.log(` Created symlink: ${linkPath} -> ${targetPath}`);
+                }
+                catch (err) {
+                    this.logError(` Failed to create symlink ${linkPath} -> ${targetPath}: ${err.message}`);
+                    throw err;
                 }
-                symlinkSync(targetPath, linkPath);
-                this.log(` Created symlink: ${linkPath} -> ${targetPath}`);
             };
             // In workspace mode, create symlinks so agents can use canonical path
             if (this._workspaceId) {
@@ -276,6 +360,25 @@ export class RelayPtyOrchestrator extends BaseWrapper {
         catch (err) {
             this.logError(` Failed to set up outbox: ${err.message}`);
         }
+        // Write MCP identity file so MCP servers can discover their agent name
+        // This is needed because Claude Code may not pass through env vars to MCP server processes
+        try {
+            const projectPaths = getProjectPaths(this.config.cwd);
+            const identityDir = join(projectPaths.dataDir);
+            if (!existsSync(identityDir)) {
+                mkdirSync(identityDir, { recursive: true });
+            }
+            // Write a per-process identity file (using PPID so MCP server finds parent's identity)
+            const identityPath = join(identityDir, `mcp-identity-${process.pid}`);
+            writeFileSync(identityPath, this.config.name, 'utf-8');
+            this.log(` Wrote MCP identity file: ${identityPath}`);
+            // Also write a simple identity file (for single-agent scenarios)
+            const simpleIdentityPath = join(identityDir, 'mcp-identity');
+            writeFileSync(simpleIdentityPath, this.config.name, 'utf-8');
+        }
+        catch (err) {
+            this.logError(` Failed to write MCP identity file: ${err.message}`);
+        }
         // Find relay-pty binary
         const binaryPath = this.findRelayPtyBinary();
         if (!binaryPath) {
@@ -318,6 +421,11 @@ export class RelayPtyOrchestrator extends BaseWrapper {
         this.stopQueueMonitor();
         this.stopProtocolMonitor();
         this.stopPeriodicReminder();
+        // Clear socket reconnect timer
+        if (this.socketReconnectTimer) {
+            clearTimeout(this.socketReconnectTimer);
+            this.socketReconnectTimer = undefined;
+        }
         // Unregister from memory monitor
         this.memoryMonitor.unregister(this.config.name);
         if (this.memoryAlertHandler) {
@@ -432,6 +540,7 @@ export class RelayPtyOrchestrator extends BaseWrapper {
                 ...process.env,
                 ...this.config.env,
                 AGENT_RELAY_NAME: this.config.name,
+                RELAY_AGENT_NAME: this.config.name, // MCP server uses this env var
                 AGENT_RELAY_OUTBOX: this._canonicalOutboxPath, // Agents use this for outbox path
                 TERM: 'xterm-256color',
             },
@@ -847,6 +956,15 @@ export class RelayPtyOrchestrator extends BaseWrapper {
      */
     attemptSocketConnection(timeout) {
         return new Promise((resolve, reject) => {
+            // Clean up any existing socket before creating new one
+            // This prevents orphaned sockets with stale event handlers
+            if (this.socket) {
+                // Remove all listeners to prevent the old socket's 'close' event
+                // from triggering another reconnect cycle
+                this.socket.removeAllListeners();
+                this.socket.destroy();
+                this.socket = undefined;
+            }
             const timer = setTimeout(() => {
                 reject(new Error('Socket connection timeout'));
             }, timeout);
@@ -860,9 +978,18 @@ export class RelayPtyOrchestrator extends BaseWrapper {
                 this.socketConnected = false;
                 reject(err);
             });
+            // Handle 'end' event - server closed its write side (half-close)
+            this.socket.on('end', () => {
+                this.socketConnected = false;
+                this.log(` Socket received end (server closed write side)`);
+            });
             this.socket.on('close', () => {
                 this.socketConnected = false;
                 this.log(` Socket closed`);
+                // Auto-reconnect if not intentionally stopped
+                if (this.running && !this.isGracefulStop) {
+                    this.scheduleSocketReconnect();
+                }
             });
             // Handle incoming data (responses)
             let buffer = '';
@@ -895,6 +1022,55 @@ export class RelayPtyOrchestrator extends BaseWrapper {
         }
         this.pendingInjections.clear();
     }
+    /** Timer for socket reconnection */
+    socketReconnectTimer;
+    /** Current reconnection attempt count */
+    socketReconnectAttempt = 0;
+    /**
+     * Schedule a socket reconnection attempt with exponential backoff
+     */
+    scheduleSocketReconnect() {
+        const maxAttempts = this.config.socketReconnectAttempts ?? 3;
+        // Clear any existing timer
+        if (this.socketReconnectTimer) {
+            clearTimeout(this.socketReconnectTimer);
+            this.socketReconnectTimer = undefined;
+        }
+        if (this.socketReconnectAttempt >= maxAttempts) {
+            this.logError(` Socket reconnect failed after ${maxAttempts} attempts`);
+            // Reset counter for future reconnects (processMessageQueue can trigger new cycle)
+            this.socketReconnectAttempt = 0;
+            // Note: socketReconnectTimer is already undefined, allowing processMessageQueue
+            // to trigger a new reconnection cycle when new messages arrive
+            return;
+        }
+        this.socketReconnectAttempt++;
+        const delay = Math.min(1000 * Math.pow(2, this.socketReconnectAttempt - 1), 10000); // Max 10s
+        this.log(` Scheduling socket reconnect in ${delay}ms (attempt ${this.socketReconnectAttempt}/${maxAttempts})`);
+        this.socketReconnectTimer = setTimeout(async () => {
+            // Clear timer reference now that callback is executing
+            this.socketReconnectTimer = undefined;
+            if (!this.running || this.isGracefulStop) {
+                return;
+            }
+            try {
+                const timeout = this.config.socketConnectTimeoutMs ?? 5000;
+                await this.attemptSocketConnection(timeout);
+                this.log(` Socket reconnected successfully`);
+                this.socketReconnectAttempt = 0; // Reset on success
+                // Process any queued messages that were waiting
+                if (this.messageQueue.length > 0 && !this.isInjecting) {
+                    this.log(` Processing ${this.messageQueue.length} queued messages after reconnect`);
+                    this.processMessageQueue();
+                }
+            }
+            catch (err) {
+                this.logError(` Socket reconnect attempt ${this.socketReconnectAttempt} failed: ${err.message}`);
+                // Schedule another attempt
+                this.scheduleSocketReconnect();
+            }
+        }, delay);
+    }
     /**
      * Send a request to the socket and optionally wait for response
      */
@@ -942,6 +1118,12 @@ export class RelayPtyOrchestrator extends BaseWrapper {
                 case 'shutdown_ack':
                     this.log(` Shutdown acknowledged`);
                     break;
+                case 'send_enter_result':
+                    // Handle SendEnter result (stuck input recovery)
+                    this.handleSendEnterResult(response).catch((err) => {
+                        this.logError(` Error handling send_enter result: ${err.message}`);
+                    });
+                    break;
             }
         }
         catch (err) {
@@ -1024,7 +1206,6 @@ export class RelayPtyOrchestrator extends BaseWrapper {
                 this.log(` Message ${pending.shortId} NOT found in output after delivery`);
                 // Check if we should retry
                 if (pending.retryCount < INJECTION_CONSTANTS.MAX_RETRIES - 1) {
-                    this.log(` Retrying injection (attempt ${pending.retryCount + 2}/${INJECTION_CONSTANTS.MAX_RETRIES})`);
                     clearTimeout(pending.timeout);
                     this.pendingInjections.delete(response.id);
                     // Wait before retry with backoff
@@ -1044,37 +1225,54 @@ export class RelayPtyOrchestrator extends BaseWrapper {
                         pending.resolve(true);
                         return;
                     }
-                    // Re-inject by sending another socket request
-                    // The original promise will be resolved when this retry completes
-                    // Prepend [RETRY] to help agent notice this is a retry
-                    const retryBody = pending.originalBody.startsWith('[RETRY]')
-                        ? pending.originalBody
-                        : `[RETRY] ${pending.originalBody}`;
-                    const retryRequest = {
-                        type: 'inject',
-                        id: response.id,
-                        from: pending.from,
-                        body: retryBody,
-                        priority: 1, // Higher priority for retries
-                    };
-                    // Create new pending entry with incremented retry count
-                    const newTimeout = setTimeout(() => {
-                        this.logError(` Retry timeout for ${pending.shortId}`);
-                        this.pendingInjections.delete(response.id);
-                        pending.resolve(false);
-                    }, 30000);
-                    this.pendingInjections.set(response.id, {
-                        ...pending,
-                        timeout: newTimeout,
-                        retryCount: pending.retryCount + 1,
-                        originalBody: retryBody, // Use retry body for subsequent retries
-                    });
-                    this.sendSocketRequest(retryRequest).catch((err) => {
-                        this.logError(` Retry request failed: ${err.message}`);
-                        clearTimeout(newTimeout);
-                        this.pendingInjections.delete(response.id);
-                        pending.resolve(false);
-                    });
+                    // On first retry attempt (retryCount === 0), try SendEnter first
+                    // This handles the case where message content was written but Enter wasn't processed
+                    if (pending.retryCount === 0) {
+                        this.log(` Trying SendEnter first for ${pending.shortId} (stuck input recovery)`);
+                        // Send just the Enter key
+                        const sendEnterRequest = {
+                            type: 'send_enter',
+                            id: response.id,
+                        };
+                        // Track this SendEnter request for verification
+                        const sendEnterTimeout = setTimeout(() => {
+                            this.logError(` SendEnter timeout for ${pending.shortId}`);
+                            this.pendingSendEnter.delete(response.id);
+                            // Fall back to full retry after SendEnter timeout
+                            this.doFullRetry(response.id, pending);
+                        }, 5000); // 5 second timeout for SendEnter
+                        this.pendingSendEnter.set(response.id, {
+                            resolve: (verified) => {
+                                if (verified) {
+                                    // SendEnter worked!
+                                    this.injectionMetrics.successWithRetry++;
+                                    this.injectionMetrics.total++;
+                                    pending.resolve(true);
+                                }
+                                else {
+                                    // SendEnter didn't work, do full retry
+                                    this.doFullRetry(response.id, pending);
+                                }
+                            },
+                            timeout: sendEnterTimeout,
+                            from: pending.from,
+                            shortId: pending.shortId,
+                            retryCount: pending.retryCount,
+                            originalBody: pending.originalBody,
+                            originalResolve: pending.resolve,
+                        });
+                        this.sendSocketRequest(sendEnterRequest).catch((err) => {
+                            this.logError(` SendEnter request failed: ${err.message}`);
+                            clearTimeout(sendEnterTimeout);
+                            this.pendingSendEnter.delete(response.id);
+                            // Fall back to full retry
+                            this.doFullRetry(response.id, pending);
+                        });
+                    }
+                    else {
+                        // On subsequent retries (retryCount > 0), do full retry directly
+                        this.doFullRetry(response.id, pending);
+                    }
                 }
                 else {
                     // Max retries exceeded
@@ -1107,6 +1305,77 @@ export class RelayPtyOrchestrator extends BaseWrapper {
         }
         // queued/injecting are intermediate states - wait for final status
     }
+    /**
+     * Handle SendEnter result (stuck input recovery)
+     * Called when relay-pty responds to a SendEnter request
+     */
+    async handleSendEnterResult(response) {
+        this.log(` handleSendEnterResult: id=${response.id.substring(0, 8)} success=${response.success}`);
+        const pendingEnter = this.pendingSendEnter.get(response.id);
+        if (!pendingEnter) {
+            this.log(` No pending SendEnter found for ${response.id.substring(0, 8)}`);
+            return;
+        }
+        clearTimeout(pendingEnter.timeout);
+        this.pendingSendEnter.delete(response.id);
+        if (!response.success) {
+            this.log(` SendEnter failed for ${pendingEnter.shortId}, will try full retry`);
+            pendingEnter.resolve(false);
+            return;
+        }
+        // SendEnter succeeded - wait and verify
+        this.log(` SendEnter sent for ${pendingEnter.shortId}, waiting to verify...`);
+        await sleep(150); // Give time for Enter to be processed
+        // Verify the message appeared in output
+        const verified = await verifyInjection(pendingEnter.shortId, pendingEnter.from, async () => this.getCleanOutput());
+        if (verified) {
+            this.log(` Message ${pendingEnter.shortId} verified after SendEnter ✓`);
+            pendingEnter.resolve(true);
+        }
+        else {
+            this.log(` Message ${pendingEnter.shortId} still not verified after SendEnter, will try full retry`);
+            pendingEnter.resolve(false);
+        }
+    }
+    /**
+     * Do a full retry with message content (used when SendEnter fails or for subsequent retries)
+     */
+    doFullRetry(messageId, pending) {
+        this.log(` Doing full retry for ${pending.shortId} (attempt ${pending.retryCount + 2}/${INJECTION_CONSTANTS.MAX_RETRIES})`);
+        // Re-inject by sending another socket request
+        // Prepend [RETRY] to help agent notice this is a retry
+        const retryBody = pending.originalBody.startsWith('[RETRY]')
+            ? pending.originalBody
+            : `[RETRY] ${pending.originalBody}`;
+        const retryRequest = {
+            type: 'inject',
+            id: messageId,
+            from: pending.from,
+            body: retryBody,
+            priority: 1, // Higher priority for retries
+        };
+        // Create new pending entry with incremented retry count
+        const newTimeout = setTimeout(() => {
+            this.logError(` Retry timeout for ${pending.shortId}`);
+            this.pendingInjections.delete(messageId);
+            pending.resolve(false);
+        }, 30000);
+        this.pendingInjections.set(messageId, {
+            resolve: pending.resolve,
+            reject: pending.reject,
+            timeout: newTimeout,
+            from: pending.from,
+            shortId: pending.shortId,
+            retryCount: pending.retryCount + 1,
+            originalBody: retryBody,
+        });
+        this.sendSocketRequest(retryRequest).catch((err) => {
+            this.logError(` Full retry request failed: ${err.message}`);
+            clearTimeout(newTimeout);
+            this.pendingInjections.delete(messageId);
+            pending.resolve(false);
+        });
+    }
     /**
      * Handle backpressure notification
      */
@@ -1180,12 +1449,42 @@ export class RelayPtyOrchestrator extends BaseWrapper {
      * Process queued messages
      */
     async processMessageQueue() {
-        if (!this.readyForMessages || this.backpressureActive || this.isInjecting) {
-            return;
+        // Debug: Log blocking conditions when queue has messages
+        if (this.messageQueue.length > 0) {
+            if (!this.readyForMessages) {
+                this.log(` Queue blocked: readyForMessages=false (queue=${this.messageQueue.length})`);
+                return;
+            }
+            if (this.backpressureActive) {
+                this.log(` Queue blocked: backpressure active (queue=${this.messageQueue.length})`);
+                return;
+            }
+            if (this.isInjecting) {
+                // Already injecting - the finally block will process next message
+                // But add a safety timeout in case injection gets stuck
+                const elapsed = this.injectionStartTime > 0 ? Date.now() - this.injectionStartTime : 0;
+                if (elapsed > 35000) {
+                    this.logError(` Injection stuck for ${elapsed}ms, forcing reset`);
+                    this.isInjecting = false;
+                    this.injectionStartTime = 0;
+                }
+                return;
+            }
         }
         if (this.messageQueue.length === 0) {
             return;
         }
+        // Proactively reconnect socket if disconnected and we have messages to send
+        if (!this.socketConnected && !this.socketReconnectTimer) {
+            this.log(` Socket disconnected, triggering reconnect before processing queue`);
+            this.scheduleSocketReconnect();
+            return; // Wait for reconnection to complete
+        }
+        if (!this.socketConnected) {
+            // Reconnection in progress, wait for it
+            this.log(` Queue waiting: socket reconnecting (queue=${this.messageQueue.length})`);
+            return;
+        }
         // Check if agent is in editor mode - delay injection if so
         const idleResult = this.idleDetector.checkIdle();
         if (idleResult.inEditorMode) {
@@ -1244,6 +1543,18 @@ export class RelayPtyOrchestrator extends BaseWrapper {
         this.log(` Queue length after add: ${this.messageQueue.length}`);
         this.processMessageQueue();
     }
+    /**
+     * Override handleIncomingChannelMessage to trigger queue processing.
+     * Without this override, channel messages would be queued but processMessageQueue()
+     * would never be called, causing messages to get stuck until the queue monitor runs.
+     */
+    handleIncomingChannelMessage(from, channel, body, envelope) {
+        this.log(` === CHANNEL MESSAGE RECEIVED: ${envelope.id.substring(0, 8)} from ${from} on ${channel} ===`);
+        this.log(` Body preview: ${body?.substring(0, 100) ?? '(no body)'}...`);
+        super.handleIncomingChannelMessage(from, channel, body, envelope);
+        this.log(` Queue length after add: ${this.messageQueue.length}`);
+        this.processMessageQueue();
+    }
     // =========================================================================
     // Queue monitor - Detect and process stuck messages
     // =========================================================================
@@ -1841,6 +2152,10 @@ Then output: \`->relay-file:spawn\`
      */
     async kill() {
         this.isGracefulStop = true; // Mark as intentional to prevent crash broadcast
+        if (this.socketReconnectTimer) {
+            clearTimeout(this.socketReconnectTimer);
+            this.socketReconnectTimer = undefined;
+        }
         if (this.relayPtyProcess && !this.relayPtyProcess.killed) {
             this.relayPtyProcess.kill('SIGKILL');
         }

package/packages/wrapper/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/wrapper",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "description": "CLI agent wrappers for Agent Relay - tmux, pty integration",
   "type": "module",
   "main": "dist/index.js",
@@ -30,11 +30,11 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@agent-relay/api-types": "2.0.12",
-    "@agent-relay/protocol": "2.0.12",
-    "@agent-relay/config": "2.0.12",
-    "@agent-relay/continuity": "2.0.12",
-    "@agent-relay/resiliency": "2.0.12"
+    "@agent-relay/api-types": "2.0.14",
+    "@agent-relay/protocol": "2.0.14",
+    "@agent-relay/config": "2.0.14",
+    "@agent-relay/continuity": "2.0.14",
+    "@agent-relay/resiliency": "2.0.14"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

package/scripts/demos/README.md

@@ -0,0 +1,79 @@
+# Multi-Agent Negotiation Demos
+
+Two demos showcasing agents with competing priorities negotiating limited resources using the full agent-relay system.
+
+## Prerequisites
+
+```bash
+# Build agent-relay and link globally
+cd /path/to/relay
+npm run build
+npm link
+
+# Verify
+agent-relay --version
+
+# Ensure claude CLI is authenticated
+claude --version
+```
+
+## The Demos
+
+### 1. Server Capacity (Emergency)
+
+**Scenario**: Black Friday traffic spike. 3 services compete for 10 emergency server slots.
+
+```bash
+./scripts/demos/server-capacity.sh
+```
+
+---
+
+### 2. Sprint Planning
+
+**Scenario**: 50 story points available, 85 requested. Product Lead facilitates.
+
+```bash
+./scripts/demos/sprint-planning.sh
+```
+
+---
+
+## Running a Demo
+
+### Step 1: Start Relay Daemon
+
+```bash
+agent-relay up --dashboard
+```
+
+Open http://localhost:3888 to watch the conversation.
+
+### Step 2: Run Setup Script
+
+```bash
+./scripts/demos/server-capacity.sh
+```
+
+This creates a prompt file in `/tmp/agent-relay-demos/`.
+
+### Step 3: Start Agents
+
+```bash
+# Terminal 2
+agent-relay -n WebAPI claude
+# Say: Read /tmp/agent-relay-demos/server-capacity.md - you are WebAPI. Join #incident channel.
+
+# Terminal 3
+agent-relay -n BatchJobs claude
+# Say: Read /tmp/agent-relay-demos/server-capacity.md - you are BatchJobs. Join #incident channel.
+
+# Terminal 4
+agent-relay -n Analytics claude
+# Say: Read /tmp/agent-relay-demos/server-capacity.md - you are Analytics. Join #incident channel.
+```
+
+## What You'll See
+
+- **Dashboard**: Agents connect, messages flow in real-time
+- **Terminals**: Agents negotiate, propose allocations, vote on outcomes