@agenticmail/enterprise 0.5.324 → 0.5.326

package/src/agent-tools/tools/microsoft/excel-vba.ts

@@ -299,7 +299,7 @@ export function createExcelAdvancedTools(config: MicrosoftToolsConfig, _options?
           const rangePath = `${base}/workbook/worksheets/${encodeURIComponent(ws)}/range(address='${params.range}')`;
 
           // Build format object
-          const format: any = {};
+          const _format: any = {};
           if (params.numberFormat) {
             // numberFormat needs to be an array matching the range dimensions
             await graph(token, `${rangePath}/format`, { method: 'PATCH', body: { columnWidth: null } }); // ensure format exists

package/src/agent-tools/tools/microsoft/excel.ts

@@ -68,7 +68,7 @@ export function createExcelTools(config: MicrosoftToolsConfig, _options?: ToolCr
           const base = itemPath(params);
           let rangePath: string;
           if (params.range) {
-            const ws = params.worksheet ? `/worksheets/${encodeURIComponent(params.worksheet)}` : '/worksheets';
+            const _ws = params.worksheet ? `/worksheets/${encodeURIComponent(params.worksheet)}` : '/worksheets';
             // If range contains !, it has sheet name embedded
             if (params.range.includes('!')) {
               rangePath = `${base}/workbook/worksheets/${encodeURIComponent(params.range.split('!')[0])}/range(address='${params.range.split('!')[1]}')`;

package/src/agent-tools/tools/microsoft/powerpoint.ts

@@ -44,7 +44,7 @@ export function createPowerPointTools(config: MicrosoftToolsConfig, _options?: T
           // Get slide count via preview
           let slideCount: number | null = null;
           try {
-            const preview = await graph(token, `${base}/preview`, { method: 'POST', body: {} });
+            const _preview = await graph(token, `${base}/preview`, { method: 'POST', body: {} });
             // Preview doesn't directly give count, but we can try thumbnails
             const thumbs = await graph(token, `${base}/thumbnails`);
             if (thumbs.value?.[0]) slideCount = Object.keys(thumbs.value[0]).filter((k: string) => k !== 'id').length;

package/src/agent-tools/tools/visual-memory/index.ts

@@ -14,7 +14,7 @@ import { calculateSimilarity as _calcSim } from './phash.js';
 import * as diff from './diff.js';
 
 // Session management
-let currentSessionId: number = 0;
+let _currentSessionId: number = 0;
 const activeSessions = new Map<string, number>();
 
 /**
@@ -53,7 +53,7 @@ export function createVisualMemoryTools(options: ToolCreationOptions): AnyAgentT
         },
         required: ['source'],
       },
-      async execute(toolCallId: string, params: any) {
+      async execute(_toolCallId: string, params: any) {
         try {
           let result: Awaited<ReturnType<typeof capture.captureFromScreenshot>>;
 
@@ -150,7 +150,7 @@ export function createVisualMemoryTools(options: ToolCreationOptions): AnyAgentT
         },
         required: [],
       },
-      async execute(toolCallId: string, params: any) {
+      async execute(_toolCallId: string, params: any) {
         try {
           const observations = await storage.queryObservations(agentId, {
             sessionId: params.sessionId,
@@ -197,7 +197,7 @@ export function createVisualMemoryTools(options: ToolCreationOptions): AnyAgentT
         },
         required: ['id1', 'id2'],
       },
-      async execute(toolCallId: string, params: any) {
+      async execute(_toolCallId: string, params: any) {
         try {
           const obs1 = await storage.getObservation(agentId, params.id1);
           const obs2 = await storage.getObservation(agentId, params.id2);
@@ -256,7 +256,7 @@ export function createVisualMemoryTools(options: ToolCreationOptions): AnyAgentT
         },
         required: ['beforeId', 'afterId'],
       },
-      async execute(toolCallId: string, params: any) {
+      async execute(_toolCallId: string, params: any) {
         try {
           const beforeObs = await storage.getObservation(agentId, params.beforeId);
           const afterObs = await storage.getObservation(agentId, params.afterId);
@@ -320,7 +320,7 @@ export function createVisualMemoryTools(options: ToolCreationOptions): AnyAgentT
         },
         required: ['targetId'],
       },
-      async execute(toolCallId: string, params: any) {
+      async execute(_toolCallId: string, params: any) {
         try {
           const targetObs = await storage.getObservation(agentId, params.targetId);
           if (!targetObs) {
@@ -384,7 +384,7 @@ export function createVisualMemoryTools(options: ToolCreationOptions): AnyAgentT
         },
         required: ['baselineId'],
       },
-      async execute(toolCallId: string, params: any) {
+      async execute(_toolCallId: string, params: any) {
         try {
           const baseline = await storage.getObservation(agentId, params.baselineId);
           if (!baseline) {
@@ -495,7 +495,7 @@ export function createVisualMemoryTools(options: ToolCreationOptions): AnyAgentT
         },
         required: ['observationId'],
       },
-      async execute(toolCallId: string, params: any) {
+      async execute(_toolCallId: string, params: any) {
         try {
           const observation = await storage.getObservation(agentId, params.observationId);
           if (!observation) {
@@ -550,7 +550,7 @@ export function createVisualMemoryTools(options: ToolCreationOptions): AnyAgentT
         properties: {},
         required: [],
       },
-      async execute(toolCallId: string, params: any) {
+      async execute(_toolCallId: string, _params: any) {
         try {
           const stats = await storage.getStoreStats(agentId);
           
@@ -608,7 +608,7 @@ export function createVisualMemoryTools(options: ToolCreationOptions): AnyAgentT
         },
         required: [],
       },
-      async execute(toolCallId: string, params: any) {
+      async execute(_toolCallId: string, params: any) {
         try {
           const store = await storage.loadStore(agentId);
           const sessionId = ++store.sessionCount;
@@ -647,7 +647,7 @@ export function createVisualMemoryTools(options: ToolCreationOptions): AnyAgentT
         },
         required: [],
       },
-      async execute(toolCallId: string, params: any) {
+      async execute(_toolCallId: string, params: any) {
         try {
           const sessionKey = `${agentId}-session`;
           const sessionId = params.sessionId || activeSessions.get(sessionKey) || 0;

package/src/agent-tools/tools/visual-memory/similarity.ts

@@ -4,8 +4,8 @@
  * Implements fast similarity search using perceptual hashes and filtering.
  */
 
-import { VisualObservation, SimilarityMatch, VisualQuery } from './types.js';
-import { calculateSimilarity, hammingDistance } from './phash.js';
+import { VisualObservation, SimilarityMatch } from './types.js';
+import { calculateSimilarity } from './phash.js';
 import { queryObservations } from './storage.js';
 
 /**

package/src/agent-tools/tools/visual-memory/storage.ts

@@ -486,7 +486,7 @@ export async function loadStore(agentId: string): Promise<VisualMemoryStore> {
 /**
  * Save store — no-op in enterprise (DB handles persistence).
  */
-export async function saveStore(_agentId: string, store: VisualMemoryStore): Promise<void> {
+export async function saveStore(_agentId: string, _store: VisualMemoryStore): Promise<void> {
   // DB-backed: no-op
 }
 

package/src/agenticmail/providers/imap.ts

@@ -62,7 +62,7 @@ export function detectImapSettings(email: string): { imapHost: string; imapPort:
   if (!domain) return null;
 
   // Check presets
-  for (const [key, preset] of Object.entries(IMAP_PRESETS)) {
+  for (const [key, _preset] of Object.entries(IMAP_PRESETS)) {
     if (domain.includes(key) || domain === 'gmail.com' || domain === 'outlook.com' || domain === 'hotmail.com') {
       if (domain === 'gmail.com' || domain.endsWith('.google.com')) return IMAP_PRESETS.gmail;
       if (domain === 'outlook.com' || domain === 'hotmail.com' || domain.endsWith('.onmicrosoft.com')) return IMAP_PRESETS.microsoft365;
@@ -83,7 +83,7 @@ export class ImapEmailProvider implements IEmailProvider {
 
   // IMAP connection (lazy-loaded to avoid bundling the dep if not used)
   private imapClient: any = null;
-  private smtpClient: any = null;
+  private _smtpClient: any = null;
 
   private getIdentity(): ImapEmailIdentity {
     if (!this.identity) throw new Error('Not connected — call connect() first');

package/src/browser/enterprise-compat.ts

@@ -267,7 +267,7 @@ export function createSubsystemLogger(name: string): SubsystemLogger {
     info: (...args: any[]) => console.log(prefix, ...args),
     warn: (...args: any[]) => console.warn(prefix, ...args),
     error: (...args: any[]) => console.error(prefix, ...args),
-    debug: (...args: any[]) => { /* silent in production */ },
+    debug: (..._args: any[]) => { /* silent in production */ },
     child: (sub: string) => createSubsystemLogger(`${name}:${sub}`),
   };
   return logger;

package/src/cli-agent.ts

@@ -2081,7 +2081,7 @@ Available tools: gmail_send (to, subject, body) or agenticmail_send (to, subject
       (global as any).__autonomyManager = autonomy;
 
       // Store autonomy ref for shutdown
-      const origShutdown = process.listeners('SIGTERM');
+      const _origShutdown = process.listeners('SIGTERM');
       process.on('SIGTERM', () => autonomy.stop());
       process.on('SIGINT', () => autonomy.stop());
     } catch (autoErr: any) {
@@ -2166,7 +2166,7 @@ Available tools: gmail_send (to, subject, body) or agenticmail_send (to, subject
 
 async function startCalendarPolling(
   agentId: string, config: any, runtime: any,
-  engineDb: any, memoryManager: any,
+  _engineDb: any, _memoryManager: any,
   sessionRouter?: any,
 ) {
   const emailConfig = config.emailConfig;
@@ -2341,7 +2341,7 @@ async function startCalendarPolling(
 // ─── Email System Prompt Builder ──────────────────────
 
 /** Build a schedule awareness block for system prompts */
-function buildScheduleContext(schedule?: { start: string; end: string; days: number[] }, timezone?: string): string {
+function _buildScheduleContext(schedule?: { start: string; end: string; days: number[] }, timezone?: string): string {
   if (!schedule) return '';
   const dayNames = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
   const workDays = schedule.days.map(d => dayNames[d]).join(', ');

package/src/cli-serve.ts

@@ -106,7 +106,7 @@ export async function runServe(_args: string[]) {
   await ensureSecrets();
 
   const JWT_SECRET = process.env.JWT_SECRET!;
-  const VAULT_KEY = process.env.AGENTICMAIL_VAULT_KEY!;
+  const _VAULT_KEY = process.env.AGENTICMAIL_VAULT_KEY!;
 
   if (!DATABASE_URL) {
     console.error('ERROR: DATABASE_URL is required.');

package/src/dashboard/docs/cluster.html

@@ -0,0 +1,285 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Cluster Management — AgenticMail Enterprise Docs</title>
+  <link rel="stylesheet" href="docs.css">
+</head>
+<body>
+<div class="docs-container">
+  <nav class="docs-nav"><a href="/dashboard">&larr; Back to Dashboard</a></nav>
+
+  <h1>Cluster Management</h1>
+  <p class="docs-subtitle">Scale your AI workforce across multiple machines — Mac Minis, VPS, cloud instances, or any combination.</p>
+
+  <div class="docs-toc">
+    <h4>Contents</h4>
+    <ul>
+      <li><a href="#overview">Overview</a></li>
+      <li><a href="#architecture">Architecture</a></li>
+      <li><a href="#adding-nodes">Adding Worker Nodes</a></li>
+      <li><a href="#manual">Method 1: Manual Registration</a></li>
+      <li><a href="#ssh">Method 2: SSH Deploy</a></li>
+      <li><a href="#script">Method 3: Setup Script</a></li>
+      <li><a href="#env-vars">Environment Variables</a></li>
+      <li><a href="#monitoring">Monitoring & Health</a></li>
+      <li><a href="#node-detail">Node Detail & Actions</a></li>
+      <li><a href="#load-balancing">Load Balancing</a></li>
+      <li><a href="#database">Database Sharing</a></li>
+      <li><a href="#networking">Networking Requirements</a></li>
+      <li><a href="#security">Security Considerations</a></li>
+      <li><a href="#edge-cases">Edge Cases & Troubleshooting</a></li>
+      <li><a href="#api">API Reference</a></li>
+    </ul>
+  </div>
+
+  <h2 id="overview">Overview</h2>
+  <p>The Cluster system enables <strong>horizontal scaling</strong> of your AI agent workforce. Instead of running all agents on a single machine, you can distribute them across multiple worker nodes — each running one or more agents that report back to a central dashboard.</p>
+  <p>This is useful when:</p>
+  <ul>
+    <li>You have more agents than a single machine can handle</li>
+    <li>You want geographic distribution (agents closer to users)</li>
+    <li>You need hardware isolation (GPU nodes for voice, separate machines for browser automation)</li>
+    <li>You want fault tolerance (agents survive if one machine goes down)</li>
+    <li>You're scaling from a single Mac Mini to a fleet of machines</li>
+  </ul>
+
+  <h2 id="architecture">Architecture</h2>
+  <div class="docs-diagram">
+    <pre>
+┌─────────────────────────────────────┐
+│         Control Plane               │
+│   (Enterprise Dashboard Server)     │
+│                                     │
+│  ┌──────────┐  ┌────────────────┐   │
+│  │ Dashboard │  │  Cluster API   │   │
+│  │   (UI)    │  │  (REST + SSE)  │   │
+│  └──────────┘  └────────────────┘   │
+│         │              │            │
+│  ┌──────────────────────────┐       │
+│  │     Shared Database      │       │
+│  │  (Postgres / Supabase)   │       │
+│  └──────────────────────────┘       │
+└─────────────┬───────────────────────┘
+              │ HTTP (heartbeat, status)
+     ┌────────┼────────┐
+     │        │        │
+┌────┴───┐ ┌──┴───┐ ┌──┴───┐
+│Worker 1│ │Worker│ │Worker│
+│Mac Mini│ │ VPS  │ │ AWS  │
+│Agent A │ │AgentB│ │AgentC│
+│Agent D │ │AgentE│ │AgentF│
+└────────┘ └──────┘ └──────┘
+    </pre>
+  </div>
+
+  <h3>Key Concepts</h3>
+  <table>
+    <tr><th>Term</th><th>Description</th></tr>
+    <tr><td><strong>Control Plane</strong></td><td>The central enterprise server running the dashboard, API, and database. One per deployment.</td></tr>
+    <tr><td><strong>Worker Node</strong></td><td>Any machine running one or more agent processes. Reports to the control plane via HTTP.</td></tr>
+    <tr><td><strong>Node ID</strong></td><td>Unique identifier for each worker node (e.g., "mac-mini-office", "aws-us-east-1").</td></tr>
+    <tr><td><strong>Heartbeat</strong></td><td>Periodic HTTP POST from worker to control plane (every 30 seconds). Proves the node is alive.</td></tr>
+    <tr><td><strong>Stale Threshold</strong></td><td>If no heartbeat received for 90 seconds, node is marked offline.</td></tr>
+    <tr><td><strong>Capabilities</strong></td><td>Tags describing what the node can do: "browser", "voice", "gpu", "docker".</td></tr>
+  </table>
+
+  <h2 id="adding-nodes">Adding Worker Nodes</h2>
+  <p>There are <strong>3 ways</strong> to add a worker node, all from the dashboard UI:</p>
+
+  <h3 id="manual">Method 1: Manual Registration</h3>
+  <p>Best for: Machines that already have AgenticMail installed and running.</p>
+  <ol>
+    <li>Go to <strong>Operations &gt; Cluster</strong> in the sidebar</li>
+    <li>Click <strong>Add Worker Node</strong></li>
+    <li>Select the <strong>Manual Registration</strong> tab</li>
+    <li>Enter the node name, host IP/hostname, and port</li>
+    <li>Click <strong>Test Connection</strong> to verify reachability</li>
+    <li>Click <strong>Add Node</strong></li>
+  </ol>
+  <p>The node will appear in the cluster and start receiving heartbeats when the agent process has <code>WORKER_NODE_ID</code> set.</p>
+
+  <h3 id="ssh">Method 2: SSH Deploy</h3>
+  <p>Best for: Fresh machines where you want the dashboard to handle everything.</p>
+  <ol>
+    <li>Click <strong>Add Worker Node</strong> &gt; <strong>Deploy via SSH</strong> tab</li>
+    <li>Enter the SSH host, username, and optionally paste a private key</li>
+    <li>Optionally specify which agent IDs to deploy</li>
+    <li>Click <strong>Deploy Worker</strong></li>
+  </ol>
+  <p>The dashboard will SSH into the machine, install Node.js, PM2, and AgenticMail, write the environment file, and start the agent processes. The node auto-registers on startup.</p>
+
+  <div class="docs-note">
+    <strong>Note:</strong> SSH deploy requires the dashboard server to have network access to the target machine on port 22. For cloud instances, make sure the security group allows SSH from the dashboard's IP.
+  </div>
+
+  <h3 id="script">Method 3: Setup Script</h3>
+  <p>Best for: Machines you can't SSH into from the dashboard (firewalled, air-gapped, or you prefer manual control).</p>
+  <ol>
+    <li>Click <strong>Add Worker Node</strong> &gt; <strong>Setup Script</strong> tab</li>
+    <li>Enter a name and port</li>
+    <li>Click <strong>Generate Setup Script</strong></li>
+    <li>Copy the script</li>
+    <li>SSH into the target machine yourself and paste/run the script</li>
+    <li>Edit <code>~/.agenticmail/worker.env</code> to set your <code>DATABASE_URL</code></li>
+    <li>Start agents with <code>pm2 start "agenticmail-enterprise agent --id &lt;ID&gt;"</code></li>
+  </ol>
+
+  <h2 id="env-vars">Environment Variables</h2>
+  <p>These environment variables control worker node behavior:</p>
+  <table>
+    <tr><th>Variable</th><th>Required</th><th>Description</th></tr>
+    <tr><td><code>ENTERPRISE_URL</code></td><td>Yes</td><td>Full URL of the control plane (e.g., <code>https://acme.agenticmail.io</code>)</td></tr>
+    <tr><td><code>WORKER_NODE_ID</code></td><td>Yes*</td><td>Unique node identifier. Triggers auto-registration on startup. <em>*Required for cluster mode.</em></td></tr>
+    <tr><td><code>WORKER_NAME</code></td><td>No</td><td>Human-readable name shown in dashboard. Defaults to system hostname.</td></tr>
+    <tr><td><code>WORKER_HOST</code></td><td>No</td><td>IP/hostname the control plane should use to reach this node. Defaults to "localhost".</td></tr>
+    <tr><td><code>WORKER_CAPABILITIES</code></td><td>No</td><td>Comma-separated capabilities: "browser,voice,gpu,docker"</td></tr>
+    <tr><td><code>DATABASE_URL</code></td><td>Yes</td><td>Same database as the control plane (shared Postgres)</td></tr>
+    <tr><td><code>PORT</code></td><td>No</td><td>Agent API port (default: 3101)</td></tr>
+    <tr><td><code>LOG_LEVEL</code></td><td>No</td><td>Set to "warn" for production noise suppression</td></tr>
+  </table>
+
+  <h2 id="monitoring">Monitoring & Health</h2>
+  <h3>Real-Time Status</h3>
+  <p>The Cluster page shows live status for every node via Server-Sent Events (SSE). No polling — updates appear instantly when:</p>
+  <ul>
+    <li>A node registers or re-registers</li>
+    <li>A heartbeat is received (every 30s)</li>
+    <li>A node goes offline (no heartbeat for 90s)</li>
+    <li>Node agent list changes</li>
+  </ul>
+
+  <h3>Node Statuses</h3>
+  <table>
+    <tr><th>Status</th><th>Color</th><th>Meaning</th></tr>
+    <tr><td>online</td><td style="color: #22c55e;">Green</td><td>Node is reachable and heartbeating normally</td></tr>
+    <tr><td>degraded</td><td style="color: #f59e0b;">Orange</td><td>Node is reachable but reporting issues</td></tr>
+    <tr><td>offline</td><td style="color: #6b7280;">Gray</td><td>No heartbeat for 90+ seconds</td></tr>
+  </table>
+
+  <h3>Stats Cards</h3>
+  <p>The top of the Cluster page shows aggregate stats:</p>
+  <ul>
+    <li><strong>Total Nodes</strong> — All registered nodes (online + offline)</li>
+    <li><strong>Online</strong> — Currently heartbeating nodes</li>
+    <li><strong>Running Agents</strong> — Total agents across all online nodes</li>
+    <li><strong>Total CPUs</strong> — Aggregate CPU cores across online nodes</li>
+    <li><strong>Total Memory</strong> — Aggregate RAM across online nodes</li>
+  </ul>
+
+  <h2 id="node-detail">Node Detail & Actions</h2>
+  <p>Click any node card to see full details:</p>
+  <ul>
+    <li><strong>Platform info</strong> — OS, architecture, CPU count, memory</li>
+    <li><strong>Agent list</strong> — All agents running on this node with names and roles</li>
+    <li><strong>Capabilities</strong> — What the node supports (browser, voice, etc.)</li>
+    <li><strong>Ping</strong> — Test connection from dashboard to node (shows latency)</li>
+    <li><strong>Restart Agents</strong> — Send restart signal to all agents on this node</li>
+  </ul>
+
+  <h2 id="load-balancing">Load Balancing</h2>
+  <p>When deploying a new agent, the system can automatically select the best node:</p>
+  <ul>
+    <li><strong>Least-loaded</strong> — Node with fewest running agents</li>
+    <li><strong>Capability-matching</strong> — If the agent needs "voice" or "browser", only nodes with those capabilities are considered</li>
+    <li><strong>API endpoint</strong>: <code>GET /api/engine/cluster/best-node?capabilities=voice,browser</code></li>
+  </ul>
+
+  <h2 id="database">Database Sharing</h2>
+  <p>All worker nodes <strong>must connect to the same database</strong> as the control plane. This is how agents share state, memory, tasks, and configuration.</p>
+  <div class="docs-note">
+    <strong>Recommended:</strong> Use a cloud-hosted PostgreSQL (Supabase, Neon, AWS RDS) accessible from all nodes. SQLite does NOT work for multi-node clusters.
+  </div>
+  <p>Connection pool settings are auto-optimized per node via the <code>smartDbConfig()</code> helper. Each node maintains its own small connection pool (3 connections max).</p>
+
+  <h2 id="networking">Networking Requirements</h2>
+  <table>
+    <tr><th>Direction</th><th>From</th><th>To</th><th>Port</th><th>Purpose</th></tr>
+    <tr><td>Outbound</td><td>Worker Node</td><td>Control Plane</td><td>3100 (or custom)</td><td>Heartbeats, status updates, task webhooks</td></tr>
+    <tr><td>Outbound</td><td>Worker Node</td><td>Database</td><td>5432 (Postgres)</td><td>Shared database connection</td></tr>
+    <tr><td>Inbound</td><td>Control Plane</td><td>Worker Node</td><td>3101 (or custom)</td><td>Health checks, ping, restart commands</td></tr>
+    <tr><td>Outbound</td><td>Control Plane</td><td>Worker Node</td><td>22 (SSH)</td><td>Only for SSH deploy method</td></tr>
+  </table>
+  <p>If nodes are behind NAT or firewalls, only outbound from worker to control plane is strictly required. The test-connection and restart features need inbound access.</p>
+
+  <h2 id="security">Security Considerations</h2>
+  <ul>
+    <li><strong>No authentication on cluster API (yet)</strong> — The heartbeat and status endpoints are unauthenticated for simplicity. Only expose the control plane's API behind a reverse proxy with authentication, or restrict by IP.</li>
+    <li><strong>SSH keys</strong> — For SSH deploy, keys are used once and not persisted. Prefer SSH agent forwarding or temporary keys.</li>
+    <li><strong>Database credentials</strong> — Each worker node needs <code>DATABASE_URL</code>. Use environment variables, never commit credentials.</li>
+    <li><strong>TLS</strong> — Use HTTPS between workers and control plane in production. Set <code>ENTERPRISE_URL=https://...</code>.</li>
+    <li><strong>Network segmentation</strong> — Place worker nodes and control plane on the same VPN/VPC for internal traffic.</li>
+  </ul>
+
+  <h2 id="edge-cases">Edge Cases & Troubleshooting</h2>
+
+  <h3>Node keeps showing "offline"</h3>
+  <ul>
+    <li>Check <code>ENTERPRISE_URL</code> is correct and reachable from the worker</li>
+    <li>Check <code>WORKER_NODE_ID</code> is set in the agent's environment</li>
+    <li>Check firewall rules — worker must be able to POST to <code>ENTERPRISE_URL/api/engine/cluster/heartbeat/...</code></li>
+    <li>Check agent logs: <code>pm2 logs agent-name</code></li>
+  </ul>
+
+  <h3>Duplicate node IDs</h3>
+  <p>If two machines use the same <code>WORKER_NODE_ID</code>, they'll overwrite each other's registration. Use unique IDs per machine.</p>
+
+  <h3>Agent appears on wrong node</h3>
+  <p>Each agent process reports its <code>WORKER_NODE_ID</code> on startup. If you move an agent between machines, restart it on the new machine — it will re-register under the new node.</p>
+
+  <h3>Control plane restarts</h3>
+  <p>All node data is persisted in the <code>cluster_nodes</code> database table. On restart, nodes load from DB as "offline" and transition to "online" when the next heartbeat arrives (within 30s).</p>
+
+  <h3>Worker restarts</h3>
+  <p>PM2 auto-restarts crashed agent processes. On restart, the agent re-registers with the control plane within seconds.</p>
+
+  <h3>Network partition</h3>
+  <p>If a worker loses connectivity to the control plane, it continues running agents normally. It just stops reporting status. When connectivity resumes, the next heartbeat restores the "online" status.</p>
+
+  <h3>Database failover</h3>
+  <p>All nodes connect to the same database. If the database goes down, all nodes are affected. Use a cloud provider with automatic failover (Supabase, Neon, RDS Multi-AZ).</p>
+
+  <h2 id="api">API Reference</h2>
+  <table>
+    <tr><th>Method</th><th>Endpoint</th><th>Description</th></tr>
+    <tr><td>GET</td><td><code>/api/engine/cluster/nodes</code></td><td>List all nodes + cluster stats</td></tr>
+    <tr><td>GET</td><td><code>/api/engine/cluster/nodes/:nodeId</code></td><td>Get specific node</td></tr>
+    <tr><td>POST</td><td><code>/api/engine/cluster/register</code></td><td>Register a worker node</td></tr>
+    <tr><td>POST</td><td><code>/api/engine/cluster/heartbeat/:nodeId</code></td><td>Worker heartbeat</td></tr>
+    <tr><td>DELETE</td><td><code>/api/engine/cluster/nodes/:nodeId</code></td><td>Remove a node</td></tr>
+    <tr><td>GET</td><td><code>/api/engine/cluster/best-node</code></td><td>Find best node for deployment</td></tr>
+    <tr><td>POST</td><td><code>/api/engine/cluster/test-connection</code></td><td>Test connectivity to a node</td></tr>
+    <tr><td>POST</td><td><code>/api/engine/cluster/deploy-via-ssh</code></td><td>Deploy worker via SSH</td></tr>
+    <tr><td>POST</td><td><code>/api/engine/cluster/nodes/:nodeId/restart</code></td><td>Restart agents on a node</td></tr>
+    <tr><td>GET</td><td><code>/api/engine/cluster/stream</code></td><td>SSE stream of cluster events</td></tr>
+  </table>
+
+  <h3>Register Node (POST /api/engine/cluster/register)</h3>
+  <pre>
+{
+  "nodeId": "mac-mini-office",    // Required, unique, 2-64 chars, alphanumeric + .-_
+  "name": "Office Mac Mini",       // Optional display name
+  "host": "192.168.1.50",          // Required, IP or hostname
+  "port": 3101,                    // Required, 1-65535
+  "platform": "darwin",            // Optional, auto-detected
+  "arch": "arm64",                 // Optional, auto-detected
+  "cpuCount": 10,                  // Optional, auto-detected
+  "memoryMb": 16384,               // Optional, auto-detected
+  "version": "0.5.324",            // Optional
+  "agents": ["agent-uuid-1"],      // Optional, list of agent IDs
+  "capabilities": ["browser", "voice"] // Optional
+}
+  </pre>
+
+  <h3>Heartbeat (POST /api/engine/cluster/heartbeat/:nodeId)</h3>
+  <pre>
+{
+  "agents": ["agent-uuid-1"],  // Current agent list
+  "cpuUsage": 0.45,            // Optional, 0-1
+  "memoryUsage": 0.62          // Optional, 0-1
+}
+  </pre>
+
+</div>
+</body>
+</html>