@agenticmail/enterprise 0.5.319 → 0.5.321

package/src/cli-agent.ts

@@ -10,7 +10,7 @@
  *   AGENTICMAIL_AGENT_ID  — Agent UUID from the enterprise DB
  *
  * Optional env vars:
- *   PORT                  — Health check HTTP port (default: 3000)
+ *   PORT                  — Health check HTTP port (default: 4100)
  *   AGENTICMAIL_MODEL     — Override model (e.g. "anthropic/claude-sonnet-4-20250514")
  *   AGENTICMAIL_THINKING  — Thinking level (e.g. "low", "medium", "high")
  *   ANTHROPIC_API_KEY     — Anthropic API key
@@ -26,6 +26,30 @@ import { beforeSpawn } from './engine/task-queue-before-spawn.js';
 import { afterSpawn, markInProgress } from './engine/task-queue-after-spawn.js';
 import { TaskPoller } from './engine/task-poller.js';
 
+// ─── Production Log Level Filter ─────────────────────────
+// Set LOG_LEVEL=warn to suppress info/debug console.log noise.
+// Levels: debug < info < warn < error (default: info)
+const _LOG_LEVEL = (process.env.LOG_LEVEL || 'info').toLowerCase();
+const _LOG_LEVELS: Record<string, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+const _LOG_THRESHOLD = _LOG_LEVELS[_LOG_LEVEL] ?? 1;
+const _origLog = console.log.bind(console);
+const _origWarn = console.warn.bind(console);
+if (_LOG_THRESHOLD > 1) {
+  // Suppress console.log (info level) — keep warn and error
+  console.log = function(...args: any[]) {
+    // Always allow critical prefixes through even at warn level
+    const first = typeof args[0] === 'string' ? args[0] : '';
+    if (first.includes('[error]') || first.includes('[fatal]') || first.includes('ERROR') || first.includes('FATAL')) {
+      _origLog(...args);
+    }
+    // Suppress everything else
+  };
+}
+if (_LOG_THRESHOLD > 2) {
+  // Suppress console.warn too — only errors
+  console.warn = function() {};
+}
+
 // ════════════════════════════════════════════════════════════
 // SYSTEM DEPENDENCY AUTO-INSTALLER
 // ════════════════════════════════════════════════════════════
@@ -375,7 +399,7 @@ export async function runAgent(_args: string[]) {
   const DATABASE_URL = process.env.DATABASE_URL;
   const JWT_SECRET = process.env.JWT_SECRET;
   const AGENT_ID = process.env.AGENTICMAIL_AGENT_ID;
-  const PORT = parseInt(process.env.PORT || '3000', 10);
+  const PORT = parseInt(process.env.PORT || '4100', 10);
 
   if (!DATABASE_URL) { console.error('ERROR: DATABASE_URL is required'); process.exit(1); }
   if (!JWT_SECRET) { console.error('ERROR: JWT_SECRET is required'); process.exit(1); }
@@ -650,6 +674,9 @@ export async function runAgent(_args: string[]) {
   // ─── Real-Time Status Reporting ─────────────────────────
   // Report status to the enterprise server (separate process)
   const ENTERPRISE_URL = process.env.ENTERPRISE_URL || 'http://localhost:3100';
+
+  // Notify enterprise SSE subscribers when tasks change (standalone agent → enterprise webhook)
+  taskQueue.webhookUrl = `${ENTERPRISE_URL}/api/engine/task-pipeline/webhook`;
   const _reportStatus = (update: any) => {
     fetch(`${ENTERPRISE_URL}/api/engine/agent-status/${AGENT_ID}`, {
       method: 'POST',
@@ -739,7 +766,7 @@ export async function runAgent(_args: string[]) {
         const session = await runtime.spawnSession({
           agentId,
           message: `[System — Task Recovery] You have a stuck task to complete:\n\nTask: ${task.title}\nID: ${task.id}\nCategory: ${task.category}\nPriority: ${task.priority}\nDescription: ${task.description}\n\nPlease complete this task now.`,
-          model: task.model || undefined,
+          model: (task.model || undefined) as any,
         });
         if (session?.id) {
           sessionRouter.register({
@@ -892,6 +919,79 @@ export async function runAgent(_args: string[]) {
 
   app.get('/ready', (c) => c.json({ ready: true, agentId: AGENT_ID }));
 
+  // General config reload endpoint — called by enterprise server when ANY config changes
+  // Supports: db-access, permissions, config, guardrails, budget, all
+  app.post('/reload-db-access', async (c) => c.redirect('/reload?scope=db-access', 307));
+  app.post('/reload', async (c) => {
+    const scope = c.req.query('scope') || 'all';
+    const reloaded: string[] = [];
+
+    try {
+      // 1. Database connections
+      if (scope === 'all' || scope === 'db-access') {
+        const dbManager = (runtime as any).config?.databaseManager;
+        if (dbManager && engineDb) {
+          await dbManager.setDb(engineDb);
+          reloaded.push('db-access');
+        }
+      }
+
+      // 2. Permission profiles
+      if (scope === 'all' || scope === 'permissions') {
+        try {
+          const { permissionEngine } = await import('./engine/routes.js');
+          await permissionEngine.setDb(engineDb);
+          reloaded.push('permissions');
+        } catch { /* non-fatal */ }
+      }
+
+      // 3. Agent config (re-read from managed_agents table)
+      if (scope === 'all' || scope === 'config') {
+        try {
+          const row = await engineDb.get<any>('SELECT * FROM managed_agents WHERE id = $1', [agentId]);
+          if (row) {
+            const config = typeof row.config === 'string' ? JSON.parse(row.config) : row.config;
+            const managed = routes.lifecycle.getAgent(agentId);
+            if (managed) {
+              Object.assign(managed.config, config);
+              managed.updatedAt = row.updated_at;
+              if (row.display_name) { managed.name = row.display_name; managed.displayName = row.display_name; }
+              reloaded.push('config');
+            }
+          }
+        } catch { /* non-fatal */ }
+      }
+
+      // 4. Budget config
+      if (scope === 'all' || scope === 'budget') {
+        try {
+          const row = await engineDb.get<any>('SELECT budget_config FROM managed_agents WHERE id = $1', [agentId]);
+          if (row?.budget_config) {
+            const managed = routes.lifecycle.getAgent(agentId);
+            if (managed) {
+              managed.budgetConfig = typeof row.budget_config === 'string' ? JSON.parse(row.budget_config) : row.budget_config;
+              reloaded.push('budget');
+            }
+          }
+        } catch { /* non-fatal */ }
+      }
+
+      // 5. Guardrails
+      if (scope === 'all' || scope === 'guardrails') {
+        try {
+          const { guardrails } = await import('./engine/routes.js');
+          await (guardrails as any).loadFromDb?.();
+          reloaded.push('guardrails');
+        } catch { /* non-fatal */ }
+      }
+
+      console.log(`[agent] Config reloaded: ${reloaded.join(', ') || 'nothing to reload'} (scope: ${scope})`);
+      return c.json({ ok: true, reloaded, scope });
+    } catch (e: any) {
+      return c.json({ ok: false, error: e.message, reloaded }, 500);
+    }
+  });
+
   // Mount runtime API if available
   if (runtimeApp) {
     app.route('/api/runtime', runtimeApp);
@@ -1105,7 +1205,7 @@ export async function runAgent(_args: string[]) {
 
       if (isMessagingSource) {
         // Build messaging-specific system prompt
-        const { buildScheduleInfo } = await import('./system-prompts/google/index.js');
+        const { buildScheduleInfo } = await import('./system-prompts/index.js');
         const sendToolName = ctx.source === 'whatsapp' ? 'whatsapp_send'
           : 'telegram_send';
         const platformName = ctx.source === 'whatsapp' ? 'WhatsApp'
@@ -1140,7 +1240,7 @@ export async function runAgent(_args: string[]) {
           `- "${sendToolName}" is ALREADY LOADED — do NOT call request_tools, do NOT search for tools, do NOT use grep. Just call ${sendToolName} directly.`,
           `- NEVER use google_chat_send_message — this is ${platformName}.`,
           `- Keep messages concise and conversational — this is a chat, not an email.`,
-          `- No markdown formatting — plain text only.`,
+          `- ABSOLUTELY NO MARKDOWN. No **, no ##, no *, no bullet lists, no code blocks. Plain text ONLY. Write like a human texting — short paragraphs separated by line breaks. This is non-negotiable.`,
           `- For simple greetings/questions, reply in ONE tool call. Do not overthink.`,
           '',
           `DEPENDENCY & TOOL MANAGEMENT:`,
@@ -1172,7 +1272,7 @@ export async function runAgent(_args: string[]) {
                 if (dp.sudoPassword) {
                   lines.push(`- You HAVE ${elevatedLabel} access. The system password is pre-configured — install_dependency handles it automatically. You do NOT need to ask the user for it.`);
                 } else {
-                  lines.push(`- You HAVE ${elevatedLabel} access. ${os === 'win32' ? 'Elevated commands should work if the agent process is running as admin.' : 'No password set — works if NOPASSWD is configured or credentials are cached.'}`);
+                  lines.push(`- You HAVE ${elevatedLabel} access. ${process.platform === 'win32' ? 'Elevated commands should work if the agent process is running as admin.' : 'No password set — works if NOPASSWD is configured or credentials are cached.'}`);
                 }
               } else {
                 lines.push('- You do NOT have elevated/admin access. Commands requiring admin privileges (sudo on Mac/Linux, admin on Windows) will fail.');
@@ -1199,7 +1299,7 @@ export async function runAgent(_args: string[]) {
         ].filter(Boolean).join('\n');
 
       } else {
-        const { buildGoogleChatPrompt, buildScheduleInfo } = await import('./system-prompts/google/index.js');
+        const { buildGoogleChatPrompt, buildScheduleInfo } = await import('./system-prompts/index.js');
         systemPrompt = buildGoogleChatPrompt({
           agent: { name: agentName, role: identity?.role || 'professional', personality: identity?.personality },
           schedule: buildScheduleInfo(agentSchedule, agentTimezone),
@@ -2143,7 +2243,7 @@ async function startCalendarPolling(
           const identity = config.identity || {};
 
           try {
-            const { buildMeetJoinPrompt, buildScheduleInfo } = await import('./system-prompts/google/index.js');
+            const { buildMeetJoinPrompt, buildScheduleInfo } = await import('./system-prompts/index.js');
 
             const managerEmail = (config as any)?.manager?.email || '';
             const agentEmail = config?.identity?.email || (config as any)?.email || '';

package/src/cli-serve.ts

@@ -138,6 +138,29 @@ export async function runServe(_args: string[]) {
   await server.start();
   console.log(`AgenticMail Enterprise server running on :${PORT}`);
 
+  // Start prevent-sleep if configured
+  try {
+    const { startPreventSleep } = await import('./engine/screen-unlock.js');
+    const adminDb = (server as any).getAdminDb?.() || (server as any).adminDb;
+    if (adminDb) {
+      const settings = await adminDb.getSettings?.().catch(() => null);
+      const screenAccess = settings?.securityConfig?.screenAccess;
+      if (screenAccess?.enabled && screenAccess?.preventSleep) {
+        startPreventSleep();
+        console.log('[startup] Prevent-sleep enabled — system will stay awake while agents are active');
+      }
+    }
+  } catch {}
+
+  // ─── Auto-configure system persistence ──────────────────
+  // Ensures the server auto-starts on reboot, crash-recovers with backoff,
+  // and log rotation is in place. Runs once — idempotent.
+  try {
+    await setupSystemPersistence();
+  } catch (e: any) {
+    console.warn('[startup] System persistence setup skipped: ' + e.message);
+  }
+
   // Auto-start cloudflared if tunnel token is present
   const tunnelToken = process.env.CLOUDFLARED_TOKEN;
   if (tunnelToken) {
@@ -172,3 +195,120 @@ export async function runServe(_args: string[]) {
     }
   }
 }
+
+// ─── System Persistence ─────────────────────────────────
+// Automatically sets up PM2 startup, log rotation, and process saving.
+// Idempotent — safe to run on every boot.
+
+async function setupSystemPersistence(): Promise<void> {
+  const { execSync, spawnSync } = await import('child_process');
+  const { existsSync: exists, writeFileSync, mkdirSync } = await import('fs');
+  const { join: pathJoin } = await import('path');
+  const platform = process.platform;
+
+  // Only works if running under PM2
+  if (!process.env.PM2_HOME && !process.env.pm_id) {
+    // Not running under PM2 — skip (user is running directly via node/npx)
+    return;
+  }
+
+  const markerDir = pathJoin(homedir(), '.agenticmail');
+  const markerFile = pathJoin(markerDir, '.persistence-configured');
+
+  // Check if already configured (avoid running pm2 commands every boot)
+  if (exists(markerFile)) {
+    // Already configured — just save current process list silently
+    try { execSync('pm2 save --silent', { timeout: 10000, stdio: 'ignore' }); } catch {}
+    return;
+  }
+
+  console.log('[startup] Configuring system persistence (one-time setup)...');
+
+  // 1. Set up PM2 startup — auto-start on boot
+  // pm2 startup outputs the command needed (may require sudo on Linux)
+  try {
+    if (platform === 'darwin') {
+      // macOS: launchd — pm2 startup creates plist and loads it
+      const result = spawnSync('pm2', ['startup', 'launchd', '--silent'], {
+        timeout: 15000, stdio: 'pipe', encoding: 'utf-8',
+      });
+      // If it outputs a sudo command, try running it
+      const output = (result.stdout || '') + (result.stderr || '');
+      const sudoMatch = output.match(/sudo\s+env\s+.*pm2\s+startup.*/);
+      if (sudoMatch) {
+        // Can't run sudo without password — log the command for the user
+        console.log('[startup] PM2 startup requires sudo. Run this once:');
+        console.log('  ' + sudoMatch[0]);
+      } else {
+        console.log('[startup] PM2 startup configured (launchd)');
+      }
+      // Try loading the plist if it exists
+      const plistPath = pathJoin(homedir(), 'Library', 'LaunchAgents', `pm2.${process.env.USER || 'user'}.plist`);
+      if (exists(plistPath)) {
+        try { execSync(`launchctl load -w "${plistPath}"`, { timeout: 5000, stdio: 'ignore' }); } catch {}
+      }
+    } else if (platform === 'linux') {
+      // Linux: systemd (Debian/Ubuntu/RHEL/Pi)
+      const result = spawnSync('pm2', ['startup', 'systemd', '--silent'], {
+        timeout: 15000, stdio: 'pipe', encoding: 'utf-8',
+      });
+      const output = (result.stdout || '') + (result.stderr || '');
+      const sudoMatch = output.match(/sudo\s+env\s+.*pm2\s+startup.*/);
+      if (sudoMatch) {
+        // Try running it — if we have sudo access
+        try {
+          execSync(sudoMatch[0], { timeout: 15000, stdio: 'ignore' });
+          console.log('[startup] PM2 startup configured (systemd)');
+        } catch {
+          console.log('[startup] PM2 startup requires root. Run this once:');
+          console.log('  ' + sudoMatch[0]);
+        }
+      } else {
+        console.log('[startup] PM2 startup configured (systemd)');
+      }
+    } else if (platform === 'win32') {
+      // Windows: use pm2-windows-startup
+      try {
+        execSync('npm list -g pm2-windows-startup', { timeout: 10000, stdio: 'ignore' });
+      } catch {
+        console.log('[startup] Installing pm2-windows-startup...');
+        try {
+          execSync('npm install -g pm2-windows-startup', { timeout: 60000, stdio: 'ignore' });
+          execSync('pm2-startup install', { timeout: 15000, stdio: 'ignore' });
+          console.log('[startup] PM2 startup configured (Windows Service)');
+        } catch (e: any) {
+          console.warn('[startup] Could not install pm2-windows-startup: ' + e.message);
+        }
+      }
+    }
+  } catch (e: any) {
+    console.warn('[startup] PM2 startup setup: ' + e.message);
+  }
+
+  // 2. Install log rotation (if not already present)
+  try {
+    const moduleList = execSync('pm2 ls --silent 2>/dev/null || true', { timeout: 10000, encoding: 'utf-8' });
+    if (!moduleList.includes('pm2-logrotate')) {
+      console.log('[startup] Installing pm2-logrotate...');
+      execSync('pm2 install pm2-logrotate --silent', { timeout: 60000, stdio: 'ignore' });
+      // Configure: 10MB max, keep 5 rotated files, compress
+      execSync('pm2 set pm2-logrotate:max_size 10M --silent', { timeout: 5000, stdio: 'ignore' });
+      execSync('pm2 set pm2-logrotate:retain 5 --silent', { timeout: 5000, stdio: 'ignore' });
+      execSync('pm2 set pm2-logrotate:compress true --silent', { timeout: 5000, stdio: 'ignore' });
+      console.log('[startup] Log rotation configured (10MB, 5 files)');
+    }
+  } catch {}
+
+  // 3. Save current process list for resurrection on reboot
+  try {
+    execSync('pm2 save --silent', { timeout: 10000, stdio: 'ignore' });
+    console.log('[startup] Process list saved');
+  } catch {}
+
+  // 4. Write marker file so we don't repeat this setup
+  try {
+    if (!exists(markerDir)) mkdirSync(markerDir, { recursive: true });
+    writeFileSync(markerFile, new Date().toISOString() + '\n' + `platform=${platform}\n`, { mode: 0o600 });
+    console.log('[startup] System persistence configured successfully');
+  } catch {}
+}

package/src/dashboard/app.js

@@ -156,7 +156,8 @@ function App() {
   const [selectedOrgId, setSelectedOrgId] = useState('');
   const [selectedOrg, setSelectedOrg] = useState(null);
   const [orgVersion, setOrgVersion] = useState(0);
-  const onOrgChange = useCallback((id, org) => { setSelectedOrgId(id); setSelectedOrg(org); setOrgVersion(v => v + 1); }, []);
+  const [companyName, setCompanyName] = useState((window.__EM_BRANDING__ && window.__EM_BRANDING__.companyName) || '');
+  const onOrgChange = useCallback((id, org) => { setSelectedOrgId(id); setSelectedOrg(org); setOrgVersion(v => v + 1); if (org && org.name) setCompanyName(org.name); }, []);
 
   // Check if already authenticated via cookie on mount, and check setup state
   useEffect(() => {
@@ -189,6 +190,11 @@ function App() {
             if (window.__transportEncryption) await window.__transportEncryption.waitForReady();
           }
         } catch {}
+        // Fetch company name for sidebar
+        try {
+          var s = await apiCall('/settings');
+          if (s && s.name) setCompanyName(s.name);
+        } catch {}
         setAuthed(true);
         setAuthChecked(true);
       }).catch(() => setAuthChecked(true));
@@ -457,7 +463,7 @@ function App() {
   const PageComponent = canAccessPage ? (pages[page] || DashboardPage) : null;
   const sidebarClass = 'sidebar' + (sidebarPinned ? ' expanded' : sidebarHovered ? ' hover-expanded' : '') + (mobileMenuOpen ? ' mobile-open' : '');
 
-  return h(AppContext.Provider, { value: { toast, toasts, user, theme, setPage, permissions, impersonating, startImpersonation, stopImpersonation, selectedOrgId, selectedOrg, onOrgChange } },
+  return h(AppContext.Provider, { value: { toast, toasts, user, theme, setPage, permissions, impersonating, startImpersonation, stopImpersonation, selectedOrgId, selectedOrg, onOrgChange, companyName, setCompanyName } },
     h('div', { className: 'app-layout' },
       // Mobile hamburger
       h('button', { className: 'mobile-hamburger', onClick: () => setMobileMenuOpen(true) },
@@ -473,7 +479,7 @@ function App() {
       h('div', { className: sidebarClass, onMouseEnter: onSidebarEnter, onMouseLeave: onSidebarLeave },
         h('div', { className: 'sidebar-brand' },
           h('img', { src: (window.__EM_BRANDING__ && window.__EM_BRANDING__.logo) || '/dashboard/assets/logo.png', alt: 'AgenticMail', style: { width: 28, height: 28, objectFit: 'contain' } }),
-          h('div', { className: 'sidebar-brand-text' }, h('h2', null, (window.__EM_BRANDING__ && window.__EM_BRANDING__.companyName) || 'AgenticMail'), h('span', null, 'Enterprise')),
+          h('div', { className: 'sidebar-brand-text' }, h('h2', null, companyName || 'AgenticMail'), h('span', null, 'Enterprise')),
           h('button', { className: 'sidebar-toggle' + (sidebarPinned ? ' pinned' : ''), onClick: toggleSidebarPin, title: sidebarPinned ? 'Unpin sidebar' : 'Pin sidebar' }, sidebarPinned ? I.chevronLeft() : I.panelLeft())
         ),
         h('div', { className: 'sidebar-nav' },

package/src/dashboard/components/knowledge-link.js

@@ -62,3 +62,18 @@ export var AGENT_TAB_DOCS = {
   deployment: 'agent-deployment',
   'memory-transfer': 'memory-transfer',
 };
+
+/** Map of settings tab IDs to doc filenames */
+export var SETTINGS_TAB_DOCS = {
+  general: 'settings',
+  models: 'settings',
+  'api-keys': 'settings',
+  authentication: 'settings',
+  platform: 'settings',
+  email: 'settings',
+  deployments: 'settings',
+  'security-system': 'settings-security',
+  'tool-security': 'settings-tool-security',
+  network: 'settings-network',
+  integrations: 'settings',
+};

package/src/dashboard/components/settings-help.js

@@ -138,7 +138,8 @@ export var SETTINGS_HELP = {
           h('li', null, h('strong', null, 'Rate Limiting'), ' \u2014 Limits how many times each tool can be called per minute per agent. Prevents any single agent from overwhelming the system. Adjust limits per tool type in the table.'),
           h('li', null, h('strong', null, 'Circuit Breaker'), ' \u2014 Automatically pauses a tool that keeps failing (after 5 consecutive errors). Waits 30 seconds before retrying. Prevents error cascading when an external service is down.'),
           h('li', null, h('strong', null, 'Telemetry'), ' \u2014 Collects performance metrics: call duration, success rates, and output sizes. Useful for identifying slow tools or agents using resources inefficiently.')
-        )
+        ),
+        h('p', { style: { marginTop: 12 } }, h('a', { href: '/docs/settings-tool-security', style: { fontSize: 12 } }, 'View full Tool Security documentation \u2192'))
       );
     }
   },
@@ -163,7 +164,8 @@ export var SETTINGS_HELP = {
           h('li', null, h('strong', null, 'Rate Limiting'), ' \u2014 Limits API requests per IP per minute. Protects against abuse and denial-of-service. "Skip Paths" excludes health-check endpoints.'),
           h('li', null, h('strong', null, 'HTTPS Enforcement'), ' \u2014 Forces all connections to use encrypted HTTPS. Highly recommended for production.'),
           h('li', null, h('strong', null, 'Security Headers'), ' \u2014 Browser security policies: HSTS forces HTTPS, X-Frame-Options prevents clickjacking, Content-Type-Options prevents MIME sniffing. The defaults are recommended for most deployments.')
-        )
+        ),
+        h('p', { style: { marginTop: 12 } }, h('a', { href: '/docs/settings-network', style: { fontSize: 12 } }, 'View full Network & Firewall documentation \u2192'))
       );
     }
   },

package/src/dashboard/docs/agent-deployment.html

@@ -162,12 +162,39 @@
 <h3 id="local">Local (In-Process)</h3>
 <p>For development and single-server deployments:</p>
 <ul>
-  <li><strong>Port</strong> — HTTP port the agent listens on.</li>
+  <li><strong>Port</strong> — HTTP port the agent listens on. Validated in real-time (see below).</li>
   <li><strong>Host</strong> — Hostname or IP (default: localhost).</li>
   <li><strong>Process Manager</strong> — PM2 (with install detection), systemd, Manual, or In-Process (embedded).</li>
   <li><strong>Process Name</strong> — PM2/systemd service name for lifecycle management.</li>
   <li><strong>Working Directory</strong> — Auto-detected or manually specified.</li>
 </ul>
+
+<h4>Port Validation</h4>
+<p>When you enter a port number, the system automatically checks whether it's available before allowing you to save:</p>
+<div class="card">
+  <table>
+    <thead><tr><th>Indicator</th><th>Meaning</th></tr></thead>
+    <tbody>
+      <tr><td><strong style="color:var(--success)">Green border + checkmark</strong></td><td>Port is available — you can save and deploy.</td></tr>
+      <tr><td><strong style="color:var(--danger)">Red border + error</strong></td><td>Port is already in use — save is blocked. The error shows which process is using it (e.g., "Port 3100 is in use by node (PID 12345)").</td></tr>
+    </tbody>
+  </table>
+</div>
+<ul>
+  <li><strong>Debounced</strong> — Validation triggers 500ms after you stop typing, preventing excessive API calls.</li>
+  <li><strong>Bind test</strong> — Uses <code>net.createServer()</code> to attempt binding the port. This is the most reliable availability check.</li>
+  <li><strong>Process identification</strong> — If the port is in use, the system runs <code>lsof</code> (macOS/Linux) or <code>netstat</code> (Windows) to identify the process name and PID.</li>
+  <li><strong>Save blocked</strong> — You cannot save deployment configuration while a port conflict exists.</li>
+</ul>
+
+<div class="card">
+  <h3>API Reference</h3>
+  <pre><code>POST /system/check-port
+Body: { "port": 4100 }
+Response (available): { "available": true, "port": 3102 }
+Response (in use):    { "available": false, "port": 3102, "process": "node (PID 12345)" }</code></pre>
+</div>
+
 <div class="tip">
   <strong>Tip:</strong> PM2 availability is auto-detected. If PM2 isn't installed, the dashboard offers a one-click "Install PM2" button.
 </div>
@@ -268,6 +295,11 @@ Response: { "agentId": "...", "assigned": ["kb-1", "kb-2"], "count": 2 }</code><
   <p>The agent process may have crashed. Check logs on the deployment platform. Common causes: missing environment variables, incorrect model configuration, or insufficient memory.</p>
 </div>
 
+<div class="card">
+  <h3>Port is in use — can't save</h3>
+  <p>The port validation detected another process using the port. Either change the port number or stop the conflicting process. The error message shows the process name and PID — you can stop it with <code>kill &lt;PID&gt;</code> or choose a different port. Common conflicts: another agent already running on that port, or a development server.</p>
+</div>
+
 <div class="card">
   <h3>Delete confirmation name doesn't match</h3>
   <p>The typed name must match exactly (case-insensitive) with the agent's display name. Check the agent name shown in the header.</p>