a2acalling 0.6.35 → 0.6.37

package/bin/cli.js

@@ -18,6 +18,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const crypto = require('crypto');
 const { spawn } = require('child_process');
 const { TokenStore } = require('../src/lib/tokens');
 const { A2AClient } = require('../src/lib/client');
@@ -296,6 +297,166 @@ function summarizePortResults(portResults) {
   });
 }
 
+/**
+ * Identify what process is using a given port.
+ * Returns { pid, name } or null if detection fails.
+ */
+function identifyPortProcess(port) {
+  const p = Number(port);
+  if (!Number.isFinite(p) || p <= 0) return null;
+  const { execSync } = require('child_process');
+  // Try lsof first (most common on Linux/macOS)
+  try {
+    const out = execSync(`lsof -i :${p} -sTCP:LISTEN -t 2>/dev/null`, { encoding: 'utf8', timeout: 5000 }).trim();
+    if (out) {
+      const pid = out.split('\n')[0].trim();
+      let name = 'unknown';
+      try {
+        name = execSync(`ps -p ${pid} -o comm= 2>/dev/null`, { encoding: 'utf8', timeout: 3000 }).trim();
+      } catch (e) { /* best-effort */ }
+      return { pid: Number(pid), name };
+    }
+  } catch (e) { /* lsof not available or failed */ }
+
+  // Fallback: ss (Linux)
+  try {
+    const out = execSync(`ss -tlnp 'sport = :${p}' 2>/dev/null`, { encoding: 'utf8', timeout: 5000 });
+    const pidMatch = out.match(/pid=(\d+)/);
+    const nameMatch = out.match(/\("([^"]+)"/);
+    if (pidMatch) {
+      return { pid: Number(pidMatch[1]), name: nameMatch ? nameMatch[1] : 'unknown' };
+    }
+  } catch (e) { /* ss not available */ }
+
+  return null;
+}
+
+/**
+ * When port 80 is unavailable, prompt the user with fallback options.
+ * Returns { strategy: 'kill' | 'proxy' | 'continue', port: number }
+ *
+ * Non-interactive: auto-returns 'continue' with a printed warning.
+ */
+async function promptPortFallbackStrategy(fallbackPort, interactive) {
+  const processInfo = identifyPortProcess(80);
+
+  console.log('\n  ┌─────────────────────────────────────────────────────────────────┐');
+  console.log('  │  ⚠  PORT 80 IS UNAVAILABLE                                     │');
+  console.log('  └─────────────────────────────────────────────────────────────────┘');
+  console.log('');
+  if (processInfo) {
+    console.log(`  Port 80 is held by: ${processInfo.name} (PID ${processInfo.pid})`);
+  } else {
+    console.log('  Port 80 is in use by another process (could not identify).');
+  }
+  console.log('');
+  console.log('  Why this matters:');
+  console.log('    - Port 80 is the default HTTP port — no firewall config needed');
+  console.log(`    - Fallback port ${fallbackPort} may be blocked by the caller's firewall`);
+  console.log(`    - If the server restarts on a different port, all invite URLs break`);
+  console.log(`    - Invite URLs with non-standard ports look like: a2a://host:${fallbackPort}/token`);
+  console.log('');
+
+  if (!interactive) {
+    console.log(`  Non-interactive mode: continuing on port ${fallbackPort}.`);
+    console.log('  Set up a reverse proxy (port 80 → ' + fallbackPort + ') for production use.\n');
+    return { strategy: 'continue', port: fallbackPort };
+  }
+
+  console.log('  Options:');
+  if (processInfo) {
+    console.log(`    1) Kill ${processInfo.name} (PID ${processInfo.pid}) and use port 80`);
+  } else {
+    console.log('    1) Kill the process on port 80 and retry');
+  }
+  console.log(`    2) Set up a reverse proxy (port 80 → ${fallbackPort})`);
+  console.log(`    3) Continue on port ${fallbackPort} (not recommended for production)`);
+  console.log('');
+
+  const choice = await promptText('  Choose [1/2/3]: ', '2');
+  const normalized = String(choice).trim();
+
+  if (normalized === '1') {
+    return { strategy: 'kill', port: 80, processInfo };
+  } else if (normalized === '3') {
+    console.log(`\n  ⚠  Continuing on port ${fallbackPort}.`);
+    console.log(`     Invite URLs will include :${fallbackPort} and may not be reachable externally.`);
+    console.log('     You can set up a reverse proxy later with: a2a config --help\n');
+    return { strategy: 'continue', port: fallbackPort };
+  } else {
+    // Default: reverse proxy (option 2)
+    return { strategy: 'proxy', port: fallbackPort };
+  }
+}
+
+/**
+ * Attempt to kill the process on a given port.
+ * Returns true if kill succeeded and port is now available.
+ */
+async function killPortProcess(processInfo) {
+  if (!processInfo || !Number.isFinite(processInfo.pid)) return false;
+  const { execSync } = require('child_process');
+  try {
+    console.log(`  Killing ${processInfo.name} (PID ${processInfo.pid})...`);
+    execSync(`kill ${processInfo.pid}`, { timeout: 5000 });
+    // Wait briefly for the port to free up
+    await new Promise(r => setTimeout(r, 1000));
+    const { tryBindPort } = require('../src/lib/port-scanner');
+    const result = await tryBindPort(80);
+    if (result.ok) {
+      console.log('  ✅ Port 80 is now available.');
+      return true;
+    }
+    console.log('  Port 80 is still in use after kill. The process may require sudo to stop.');
+    return false;
+  } catch (e) {
+    console.log(`  Could not kill process: ${e.message}`);
+    console.log('  You may need to run: sudo kill ' + processInfo.pid);
+    return false;
+  }
+}
+
+/**
+ * Detect installed web servers and generate reverse proxy config.
+ * Returns { hasNginx, hasCaddy, nginxConfig, caddyConfig }.
+ */
+function generateProxyConfig(backendPort) {
+  const { spawnSync } = require('child_process');
+  const hasNginx = spawnSync('which', ['nginx'], { encoding: 'utf8' }).status === 0;
+  const hasCaddy = spawnSync('which', ['caddy'], { encoding: 'utf8' }).status === 0;
+
+  const nginxConfig = [
+    '# ══════════════════════════════════════════════════════════════',
+    '# A2A (Agent-to-Agent) Protocol Proxy',
+    '# ══════════════════════════════════════════════════════════════',
+    '# Routes federation requests from port 80 to the local',
+    `# A2A server on port ${backendPort}.`,
+    '#',
+    '# Protocol: https://github.com/onthegonow/a2a_calling',
+    '# All requests to /api/a2a/* are agent-to-agent API calls.',
+    '# ══════════════════════════════════════════════════════════════',
+    'location /api/a2a/ {',
+    `    proxy_pass http://127.0.0.1:${backendPort}/api/a2a/;`,
+    '    proxy_http_version 1.1;',
+    '    proxy_set_header Host $host;',
+    '    proxy_set_header X-Real-IP $remote_addr;',
+    '    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;',
+    '    proxy_set_header X-Forwarded-Proto $scheme;',
+    '}'
+  ].join('\n');
+
+  const caddyConfig = [
+    '# A2A (Agent-to-Agent) Protocol Proxy',
+    `# Routes federation requests to local A2A server on port ${backendPort}`,
+    '# Protocol: https://github.com/onthegonow/a2a_calling',
+    'handle /api/a2a/* {',
+    `    reverse_proxy 127.0.0.1:${backendPort}`,
+    '}'
+  ].join('\n');
+
+  return { hasNginx, hasCaddy, nginxConfig, caddyConfig };
+}
+
 async function handleDisclosureSubmit(args, commandLabel = 'onboard') {
   const submitRaw = args.flags.submit;
   if (!submitRaw) return false;
@@ -1204,28 +1365,45 @@ a2a add "${inviteUrl}" "${ownerText || 'friend'}" && a2a call "${ownerText || 'f
 
       // Persist conversation locally
       const cs = getConvStore();
-      if (cs && response.conversation_id) {
+      if (cs) {
         try {
-          cs.startConversation({
-            id: response.conversation_id,
+          // Use remote conversation ID if provided, otherwise generate a local one
+          const convId = response.conversation_id || `conv_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+
+          const convResult = cs.startConversation({
+            id: convId,
             contactId: contactName || null,
             contactName: contactName || null,
             direction: 'outbound'
           });
-          cs.addMessage(response.conversation_id, {
-            direction: 'outbound',
-            role: 'user',
-            content: message
-          });
-          if (response.response) {
-            cs.addMessage(response.conversation_id, {
-              direction: 'inbound',
-              role: 'assistant',
-              content: response.response
+          if (convResult.success === false) {
+            console.error(`⚠️  Failed to save conversation: ${convResult.error}`);
+          } else {
+            const outMsg = cs.addMessage(convId, {
+              direction: 'outbound',
+              role: 'user',
+              content: message
             });
+            if (outMsg.success === false) {
+              console.error(`⚠️  Failed to save outbound message: ${outMsg.error}`);
+            }
+            if (response.response) {
+              const inMsg = cs.addMessage(convId, {
+                direction: 'inbound',
+                role: 'assistant',
+                content: response.response
+              });
+              if (inMsg.success === false) {
+                console.error(`⚠️  Failed to save inbound message: ${inMsg.error}`);
+              }
+            }
+            // Update response to include conversation ID for display
+            if (!response.conversation_id) {
+              response.conversation_id = convId;
+            }
           }
         } catch (err) {
-          // Best effort — don't fail the call if persistence fails
+          console.error(`⚠️  Error persisting conversation: ${err.message}`);
         }
       }
 
@@ -1474,11 +1652,8 @@ a2a add "${inviteUrl}" "${ownerText || 'friend'}" && a2a call "${ownerText || 'f
     let recommendedPort;
     if (port80Available) {
       recommendedPort = 80;
-      console.log('  Port 80 is available — using it for easiest external access.');
     } else if (availableCandidates.length) {
       recommendedPort = availableCandidates[0].port;
-      console.log(`  Port 80 is in use. Using fallback port ${recommendedPort}.`);
-      console.log('  (Reverse proxy or firewall config will be needed for external access.)');
     } else {
       recommendedPort = null;
     }
@@ -1494,49 +1669,76 @@ a2a add "${inviteUrl}" "${ownerText || 'friend'}" && a2a call "${ownerText || 'f
     }
 
     let serverPort = recommendedPort;
-    
-    // If we got port 80, just confirm briefly. Otherwise allow override.
-    const portPrompt = port80Available 
-      ? `Use port 80? [Y/n]: `
-      : `Use port ${recommendedPort}? [Y/n/custom]: `;
-    const portChoice = await promptText(portPrompt, 'y');
-    
-    if (!interactive) {
-      serverPort = recommendedPort;
-    } else if (!['', 'y', 'Y', 'yes', 'YES', 'ye'].includes(String(portChoice).trim())) {
-      if (/^(n|no|custom|c)$/i.test(String(portChoice).trim())) {
-        let customPort = null;
-        while (customPort === null) {
-          const raw = await promptText('Enter a custom port number: ', String(recommendedPort));
-          const parsed = parsePort(raw, null);
-          if (!parsed) {
-            console.log('  Invalid port. Enter a value between 1 and 65535.');
-            continue;
+    let proxyStrategy = false; // true if user chose reverse proxy option
+
+    if (port80Available) {
+      // Port 80 available — simple confirm
+      console.log('  Port 80 is available — using it for easiest external access.');
+      const portPrompt = `Use port 80? [Y/n]: `;
+      const portChoice = await promptText(portPrompt, 'y');
+
+      if (!interactive) {
+        serverPort = 80;
+      } else if (!['', 'y', 'Y', 'yes', 'YES', 'ye'].includes(String(portChoice).trim())) {
+        if (/^(n|no|custom|c)$/i.test(String(portChoice).trim())) {
+          let customPort = null;
+          while (customPort === null) {
+            const raw = await promptText('Enter a custom port number: ', String(recommendedPort));
+            const parsed = parsePort(raw, null);
+            if (!parsed) {
+              console.log('  Invalid port. Enter a value between 1 and 65535.');
+              continue;
+            }
+            const checked = await (async () => {
+              const scan = await inspectPorts(parsed);
+              return scan[0];
+            })();
+            if (!checked.available) {
+              console.log(`  Port ${parsed} is unavailable (${checked.code || 'in use'}).`);
+              continue;
+            }
+            customPort = parsed;
           }
-          const checked = await (async () => {
-            const scan = await inspectPorts(parsed);
-            return scan[0];
-          })();
-          if (!checked.available) {
-            console.log(`  Port ${parsed} is unavailable (${checked.code || 'in use'}).`);
-            continue;
+          serverPort = customPort;
+        } else {
+          const parsed = parsePort(portChoice, null);
+          if (parsed) {
+            const checked = await (async () => {
+              const scan = await inspectPorts(parsed);
+              return scan[0];
+            })();
+            if (!checked.available) {
+              console.log(`  Port ${parsed} is unavailable (${checked.code || 'in use'}).`);
+            } else {
+              serverPort = parsed;
+            }
           }
-          customPort = parsed;
         }
-        serverPort = customPort;
-      } else {
-        const parsed = parsePort(portChoice, null);
-        if (parsed) {
-          const checked = await (async () => {
-            const scan = await inspectPorts(parsed);
-            return scan[0];
-          })();
-          if (!checked.available) {
-            console.log(`  Port ${parsed} is unavailable (${checked.code || 'in use'}).`);
+      }
+    } else {
+      // Port 80 NOT available — show the fallback strategy prompt
+      const fallback = await promptPortFallbackStrategy(recommendedPort, interactive);
+
+      if (fallback.strategy === 'kill') {
+        const confirmKill = await promptYesNo(`  Kill ${(fallback.processInfo && fallback.processInfo.name) || 'process'} (PID ${(fallback.processInfo && fallback.processInfo.pid) || '?'})? (y/N) `);
+        if (confirmKill) {
+          const killed = await killPortProcess(fallback.processInfo);
+          if (killed) {
+            serverPort = 80;
           } else {
-            serverPort = parsed;
+            console.log(`\n  Falling back to port ${recommendedPort}.`);
+            console.log('  You can set up a reverse proxy after setup completes.\n');
+            serverPort = recommendedPort;
           }
+        } else {
+          console.log(`  Skipped. Using port ${recommendedPort}.\n`);
+          serverPort = recommendedPort;
         }
+      } else if (fallback.strategy === 'proxy') {
+        serverPort = fallback.port;
+        proxyStrategy = true;
+      } else {
+        serverPort = fallback.port;
       }
     }
 
@@ -1651,81 +1853,60 @@ a2a add "${inviteUrl}" "${ownerText || 'friend'}" && a2a call "${ownerText || 'f
         // Port 80 — optimal setup, no extra config needed
         console.log(`\n  ✅ Running on port 80 — external agents can reach you directly.`);
         console.log(`  Invite hostname: ${externalIp}`);
-        // Update publicHost to not include port since 80 is default
         publicHost = externalIp;
-      } else {
-        // Not on port 80 — need reverse proxy or firewall config
-        const { spawnSync } = require('child_process');
-        const hasNginx = spawnSync('which', ['nginx'], { encoding: 'utf8' }).status === 0;
-        const hasCaddy = spawnSync('which', ['caddy'], { encoding: 'utf8' }).status === 0;
-        
-        console.log(`\n  ━━━ IMPORTANT: External Access Configuration ━━━`);
-        console.log(`\n  A2A server is on port ${serverPort}, but external callers expect port 80.`);
-        console.log(`  Port 80 is in use by ${hasNginx ? 'nginx' : hasCaddy ? 'Caddy' : 'another web server'}.`);
-        console.log(`\n  RECOMMENDED: Configure reverse proxy to route /api/a2a/* to port ${serverPort}`);
-        
-        if (hasNginx) {
-          console.log(`\n  ┌─────────────────────────────────────────────────────────────────┐`);
-          console.log(`  │  nginx config — add inside your server {} block                 │`);
-          console.log(`  │  File: /etc/nginx/sites-available/default                       │`);
-          console.log(`  └─────────────────────────────────────────────────────────────────┘`);
-          console.log(``);
-          console.log(`  # ══════════════════════════════════════════════════════════════`);
-          console.log(`  # A2A (Agent-to-Agent) Protocol Proxy`);
-          console.log(`  # ══════════════════════════════════════════════════════════════`);
-          console.log(`  # A2A enables AI agents to communicate across different instances.`);
-          console.log(`  # This proxy routes federation requests from port 80 to the local`);
-          console.log(`  # A2A server on port ${serverPort}.`);
-          console.log(`  #`);
-          console.log(`  # Protocol: https://github.com/onthegonow/a2a_calling`);
-          console.log(`  # All requests to /api/a2a/* are agent-to-agent API calls.`);
-          console.log(`  # ══════════════════════════════════════════════════════════════`);
-          console.log(`  location /api/a2a/ {`);
-          console.log(`      proxy_pass http://127.0.0.1:${serverPort}/api/a2a/;`);
-          console.log(`      proxy_http_version 1.1;`);
-          console.log(`      proxy_set_header Host $host;`);
-          console.log(`      proxy_set_header X-Real-IP $remote_addr;`);
-          console.log(`      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`);
-          console.log(`      proxy_set_header X-Forwarded-Proto $scheme;`);
-          console.log(`  }`);
-          console.log(``);
-          console.log(`  To apply:`);
-          console.log(`    1. sudo nano /etc/nginx/sites-available/default`);
-          console.log(`    2. Add the config above inside your server { } block`);
-          console.log(`    3. sudo nginx -t`);
-          console.log(`    4. sudo systemctl reload nginx`);
+      } else if (proxyStrategy) {
+        // User chose to set up a reverse proxy
+        const proxy = generateProxyConfig(serverPort);
+
+        console.log(`\n  ━━━ Reverse Proxy Configuration ━━━`);
+        console.log(`\n  A2A server running on port ${serverPort}. Configure your web server`);
+        console.log(`  to proxy port 80 → ${serverPort} so invite URLs work without a port number.\n`);
+
+        if (proxy.hasNginx) {
+          console.log('  ┌─────────────────────────────────────────────────────────────────┐');
+          console.log('  │  nginx — add inside your server {} block                        │');
+          console.log('  │  File: /etc/nginx/sites-available/default                       │');
+          console.log('  └─────────────────────────────────────────────────────────────────┘');
+          console.log('');
+          proxy.nginxConfig.split('\n').forEach(line => console.log(`  ${line}`));
+          console.log('');
+          console.log('  To apply:');
+          console.log('    1. sudo nano /etc/nginx/sites-available/default');
+          console.log('    2. Add the config above inside your server { } block');
+          console.log('    3. sudo nginx -t');
+          console.log('    4. sudo systemctl reload nginx');
+        }
+
+        if (proxy.hasCaddy) {
+          console.log('');
+          console.log('  ┌─────────────────────────────────────────────────────────────────┐');
+          console.log('  │  Caddy config                                                   │');
+          console.log('  └─────────────────────────────────────────────────────────────────┘');
+          console.log('');
+          proxy.caddyConfig.split('\n').forEach(line => console.log(`  ${line}`));
         }
-        
-        if (hasCaddy) {
-          console.log(`\n  ┌─────────────────────────────────────────────────────────────────┐`);
-          console.log(`  │  Caddy config                                                   │`);
-          console.log(`  └─────────────────────────────────────────────────────────────────┘`);
-          console.log(``);
-          console.log(`  # A2A (Agent-to-Agent) Protocol Proxy`);
-          console.log(`  # Routes federation requests to local A2A server on port ${serverPort}`);
-          console.log(`  # Protocol: https://github.com/onthegonow/a2a_calling`);
-          console.log(`  handle /api/a2a/* {`);
-          console.log(`      reverse_proxy 127.0.0.1:${serverPort}`);
-          console.log(`  }`);
+
+        if (!proxy.hasNginx && !proxy.hasCaddy) {
+          console.log('  No nginx or Caddy detected. Install one:');
+          console.log('    sudo apt install nginx   # Debian/Ubuntu');
+          console.log('    sudo yum install nginx   # RHEL/CentOS');
+          console.log('');
+          console.log('  Then add this proxy config:');
+          proxy.nginxConfig.split('\n').forEach(line => console.log(`  ${line}`));
         }
-        
-        console.log(`\n  After reverse proxy is configured:`);
-        console.log(`    Invite hostname will be: ${externalIp} (no port needed)`);
-        
-        console.log(`\n  ── Alternative: Direct firewall access ──`);
-        console.log(`  Open port ${serverPort} directly (less recommended):`);
-        console.log(`    sudo ufw allow ${serverPort}/tcp   # Ubuntu/Debian`);
-        console.log(`  Invite hostname will then be: ${publicHost}`);
-        
-        console.log(`\n  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-        console.log(`\n  AGENT ACTION REQUIRED:`);
-        console.log(`  1. Configure reverse proxy (recommended) — add nginx/caddy config above`);
-        console.log(`  2. OR open firewall for port ${serverPort} — run the ufw/firewall-cmd command`);
-        console.log(`  3. OR skip (local-only, external agents cannot call)`);
-        console.log(`\n  Ask your owner which option to use, then proceed.`);
-        console.log(`  If reverse proxy is configured, update hostname with: a2a config --hostname ${externalIp}`);
+
+        // With reverse proxy, invite URLs use port 80 (no port in URL)
+        console.log(`\n  After applying, invite hostname will be: ${externalIp} (no port needed)`);
+        publicHost = externalIp;
+      } else {
+        // User chose 'continue' on non-standard port — brief reminder
+        console.log(`\n  ⚠  Running on port ${serverPort} (non-standard).`);
+        console.log(`  Invite hostname: ${publicHost}`);
+        console.log(`\n  To set up a reverse proxy later:`);
+        console.log(`    a2a config --hostname ${externalIp}`);
+        console.log(`  Then configure nginx/caddy to proxy port 80 → ${serverPort}.`);
       }
-      
+
       const verifyUrl = `http://${publicHost}/api/a2a/ping`;
       console.log(`\n  Verify: curl -s ${verifyUrl}`);
     }
@@ -1841,9 +2022,55 @@ a2a add "${inviteUrl}" "${ownerText || 'friend'}" && a2a call "${ownerText || 'f
       }
     }
 
+    // Kill server by PID from config (detached process started by quickstart)
+    function killServerPid() {
+      try {
+        const { A2AConfig } = require('../src/lib/config');
+        const config = new A2AConfig();
+        const onboarding = config.getOnboarding();
+        const pid = onboarding.server_pid;
+        if (!pid) return { ok: true, skipped: true };
+
+        // Check if process is alive
+        try {
+          process.kill(pid, 0); // signal 0 = existence check
+        } catch (e) {
+          // Process doesn't exist — already dead
+          return { ok: true, skipped: true };
+        }
+
+        // Kill it
+        process.kill(pid, 'SIGTERM');
+
+        // Wait briefly and verify it's gone
+        const start = Date.now();
+        while (Date.now() - start < 3000) {
+          try {
+            process.kill(pid, 0);
+            spawnSync('sleep', ['0.1'], { timeout: 500 });
+          } catch (e) {
+            // Process is gone
+            return { ok: true, pid };
+          }
+        }
+
+        // Still alive after 3s — force kill
+        try {
+          process.kill(pid, 'SIGKILL');
+          return { ok: true, pid, forced: true };
+        } catch (e) {
+          return { ok: true, pid };
+        }
+      } catch (err) {
+        // Config read failed — not fatal, continue with pm2 path
+        return { ok: true, skipped: true };
+      }
+    }
+
     process.stdout.write('Stopping server... ');
+    const pidResult = killServerPid();
     const stopped = pm2StopAndDelete('a2a');
-    if (!stopped.ok) {
+    if (!pidResult.ok && !stopped.ok) {
       console.log('❌');
       console.error(`  ${stopped.error}`);
       process.exit(1);

package/docs/plans/2026-02-15-port-fallback-warning-design.md

@@ -0,0 +1,611 @@
+# Port Fallback Warning & Reverse Proxy Prompt — Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** When quickstart falls back to a non-standard port (not 80), warn the user and offer interactive choices: kill the blocking process, set up a reverse proxy, or continue with a clear warning.
+
+**Architecture:** Add a `promptPortFallbackStrategy()` function to `bin/cli.js` that runs between port detection and port acceptance. It identifies the process holding port 80 (via `lsof`/`ss`), presents a 3-option menu, and returns a strategy object that the rest of quickstart uses to determine behavior. The existing post-server-start reverse proxy block becomes conditional based on the chosen strategy.
+
+**Tech Stack:** Node.js built-in `child_process.execSync`, existing `readline`-based prompt helpers (`promptText`, `promptYesNo`), existing `port-scanner.js` utilities.
+
+---
+
+### Task 1: Add `identifyPort80Process()` helper function
+
+**Files:**
+- Modify: `bin/cli.js:267-297` (after `summarizePortResults`, before `handleDisclosureSubmit`)
+
+**Step 1: Write the function**
+
+Add after the `summarizePortResults` function (line 297) and before `handleDisclosureSubmit` (line 299):
+
+```javascript
+/**
+ * Identify what process is using port 80.
+ * Returns { pid, name, command } or null if detection fails.
+ */
+function identifyPortProcess(port) {
+  const { execSync } = require('child_process');
+  // Try lsof first (most common on Linux/macOS)
+  try {
+    const out = execSync(`lsof -i :${port} -sTCP:LISTEN -t 2>/dev/null`, { encoding: 'utf8', timeout: 5000 }).trim();
+    if (out) {
+      const pid = out.split('\n')[0].trim();
+      let name = 'unknown';
+      try {
+        name = execSync(`ps -p ${pid} -o comm= 2>/dev/null`, { encoding: 'utf8', timeout: 3000 }).trim();
+      } catch (e) { /* best-effort */ }
+      return { pid: Number(pid), name };
+    }
+  } catch (e) { /* lsof not available or failed */ }
+
+  // Fallback: ss (Linux)
+  try {
+    const out = execSync(`ss -tlnp 'sport = :${port}' 2>/dev/null`, { encoding: 'utf8', timeout: 5000 });
+    const pidMatch = out.match(/pid=(\d+)/);
+    const nameMatch = out.match(/\("([^"]+)"/);
+    if (pidMatch) {
+      return { pid: Number(pidMatch[1]), name: nameMatch ? nameMatch[1] : 'unknown' };
+    }
+  } catch (e) { /* ss not available */ }
+
+  return null;
+}
+```
+
+**Step 2: Verify no syntax errors**
+
+Run: `node -e "require('./bin/cli.js')" 2>&1 | head -5`
+Expected: No syntax errors (may print usage or "command not found" — that's fine).
+
+**Step 3: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "feat: add identifyPortProcess helper for port 80 detection"
+```
+
+---
+
+### Task 2: Add `promptPortFallbackStrategy()` interactive menu
+
+**Files:**
+- Modify: `bin/cli.js` (add after `identifyPortProcess`, before `handleDisclosureSubmit`)
+
+**Step 1: Write the function**
+
+```javascript
+/**
+ * When port 80 is unavailable, prompt the user with fallback options.
+ * Returns { strategy: 'kill' | 'proxy' | 'continue', port: number }
+ *
+ * Non-interactive: auto-returns 'continue' with a printed warning.
+ */
+async function promptPortFallbackStrategy(fallbackPort, interactive) {
+  const processInfo = identifyPortProcess(80);
+
+  console.log('\n  ┌─────────────────────────────────────────────────────────────────┐');
+  console.log('  │  ⚠  PORT 80 IS UNAVAILABLE                                     │');
+  console.log('  └─────────────────────────────────────────────────────────────────┘');
+  console.log('');
+  if (processInfo) {
+    console.log(`  Port 80 is held by: ${processInfo.name} (PID ${processInfo.pid})`);
+  } else {
+    console.log('  Port 80 is in use by another process (could not identify).');
+  }
+  console.log('');
+  console.log('  Why this matters:');
+  console.log('    - Port 80 is the default HTTP port — no firewall config needed');
+  console.log(`    - Fallback port ${fallbackPort} may be blocked by the caller's firewall`);
+  console.log(`    - If the server restarts on a different port, all invite URLs break`);
+  console.log(`    - Invite URLs with non-standard ports look like: a2a://host:${fallbackPort}/token`);
+  console.log('');
+
+  if (!interactive) {
+    console.log(`  Non-interactive mode: continuing on port ${fallbackPort}.`);
+    console.log('  Set up a reverse proxy (port 80 → ' + fallbackPort + ') for production use.\n');
+    return { strategy: 'continue', port: fallbackPort };
+  }
+
+  console.log('  Options:');
+  if (processInfo) {
+    console.log(`    1) Kill ${processInfo.name} (PID ${processInfo.pid}) and use port 80`);
+  } else {
+    console.log('    1) Kill the process on port 80 and retry');
+  }
+  console.log(`    2) Set up a reverse proxy (port 80 → ${fallbackPort})`);
+  console.log(`    3) Continue on port ${fallbackPort} (not recommended for production)`);
+  console.log('');
+
+  const choice = await promptText('  Choose [1/2/3]: ', '2');
+  const normalized = String(choice).trim();
+
+  if (normalized === '1') {
+    return { strategy: 'kill', port: 80, processInfo };
+  } else if (normalized === '3') {
+    console.log(`\n  ⚠  Continuing on port ${fallbackPort}.`);
+    console.log(`     Invite URLs will include :${fallbackPort} and may not be reachable externally.`);
+    console.log('     You can set up a reverse proxy later with: a2a config --help\n');
+    return { strategy: 'continue', port: fallbackPort };
+  } else {
+    // Default: reverse proxy (option 2)
+    return { strategy: 'proxy', port: fallbackPort };
+  }
+}
+```
+
+**Step 2: Verify no syntax errors**
+
+Run: `node -e "require('./bin/cli.js')" 2>&1 | head -5`
+
+**Step 3: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "feat: add promptPortFallbackStrategy with 3-option menu"
+```
+
+---
+
+### Task 3: Add `killPortProcess()` helper and `generateProxyConfig()` helper
+
+**Files:**
+- Modify: `bin/cli.js` (add after `promptPortFallbackStrategy`)
+
+**Step 1: Write killPortProcess**
+
+```javascript
+/**
+ * Attempt to kill the process on a given port.
+ * Returns true if kill succeeded and port is now available.
+ */
+async function killPortProcess(processInfo) {
+  if (!processInfo || !processInfo.pid) return false;
+  const { execSync } = require('child_process');
+  try {
+    console.log(`  Killing ${processInfo.name} (PID ${processInfo.pid})...`);
+    execSync(`kill ${processInfo.pid}`, { timeout: 5000 });
+    // Wait briefly for the port to free up
+    await new Promise(r => setTimeout(r, 1000));
+    const { tryBindPort } = require('../src/lib/port-scanner');
+    const result = await tryBindPort(80);
+    if (result.ok) {
+      console.log('  ✅ Port 80 is now available.');
+      return true;
+    }
+    console.log('  Port 80 is still in use after kill. The process may require sudo to stop.');
+    return false;
+  } catch (e) {
+    console.log(`  Could not kill process: ${e.message}`);
+    console.log('  You may need to run: sudo kill ' + processInfo.pid);
+    return false;
+  }
+}
+```
+
+**Step 2: Write generateProxyConfig**
+
+```javascript
+/**
+ * Detect installed web servers and generate reverse proxy config.
+ * Returns { hasNginx, hasCaddy, nginxConfig, caddyConfig }.
+ */
+function generateProxyConfig(backendPort) {
+  const { spawnSync } = require('child_process');
+  const hasNginx = spawnSync('which', ['nginx'], { encoding: 'utf8' }).status === 0;
+  const hasCaddy = spawnSync('which', ['caddy'], { encoding: 'utf8' }).status === 0;
+
+  const nginxConfig = [
+    '# ══════════════════════════════════════════════════════════════',
+    '# A2A (Agent-to-Agent) Protocol Proxy',
+    '# ══════════════════════════════════════════════════════════════',
+    '# Routes federation requests from port 80 to the local',
+    `# A2A server on port ${backendPort}.`,
+    '#',
+    '# Protocol: https://github.com/onthegonow/a2a_calling',
+    '# All requests to /api/a2a/* are agent-to-agent API calls.',
+    '# ══════════════════════════════════════════════════════════════',
+    'location /api/a2a/ {',
+    `    proxy_pass http://127.0.0.1:${backendPort}/api/a2a/;`,
+    '    proxy_http_version 1.1;',
+    '    proxy_set_header Host $host;',
+    '    proxy_set_header X-Real-IP $remote_addr;',
+    '    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;',
+    '    proxy_set_header X-Forwarded-Proto $scheme;',
+    '}'
+  ].join('\n');
+
+  const caddyConfig = [
+    '# A2A (Agent-to-Agent) Protocol Proxy',
+    `# Routes federation requests to local A2A server on port ${backendPort}`,
+    '# Protocol: https://github.com/onthegonow/a2a_calling',
+    'handle /api/a2a/* {',
+    `    reverse_proxy 127.0.0.1:${backendPort}`,
+    '}'
+  ].join('\n');
+
+  return { hasNginx, hasCaddy, nginxConfig, caddyConfig };
+}
+```
+
+**Step 3: Verify no syntax errors**
+
+Run: `node -e "require('./bin/cli.js')" 2>&1 | head -5`
+
+**Step 4: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "feat: add killPortProcess and generateProxyConfig helpers"
+```
+
+---
+
+### Task 4: Wire the port fallback prompt into the quickstart flow
+
+This is the main integration task. Modify the quickstart port selection section to call `promptPortFallbackStrategy` when port 80 is unavailable.
+
+**Files:**
+- Modify: `bin/cli.js:1462-1541` (Step 1: Port selection in quickstart)
+
+**Step 1: Replace the port fallback branch**
+
+Replace lines 1478-1541 (the `else if (availableCandidates.length)` branch through the end of port selection) with logic that:
+1. Calls `promptPortFallbackStrategy()` when port 80 is unavailable
+2. Handles the 'kill' strategy by attempting to kill the process, retrying port 80, and falling back to the menu if kill fails
+3. Handles the 'proxy' strategy by accepting the fallback port and setting a `proxyStrategy` flag
+4. Handles the 'continue' strategy by accepting the fallback port
+5. Preserves the existing custom port prompt for port 80 available case
+
+The new code for the `else if (availableCandidates.length)` branch (replacing lines 1478-1541):
+
+```javascript
+    } else if (availableCandidates.length) {
+      recommendedPort = availableCandidates[0].port;
+      // Don't print a brief dismissive message — we'll show the full prompt below
+    } else {
+      recommendedPort = null;
+    }
+
+    if (!recommendedPort) {
+      console.error('  Could not find a bindable port in the scan range.');
+      console.error('  Re-run with --port <number> after freeing one of these ports.\n');
+      if (interactive) {
+        console.log('  Ports scanned:');
+        summarizePortResults(candidates).forEach(line => console.log(`    ${line}`));
+      }
+      process.exit(1);
+    }
+
+    let serverPort = recommendedPort;
+    let proxyStrategy = false; // true if user chose reverse proxy option
+
+    if (port80Available) {
+      // Port 80 available — simple confirm
+      console.log('  Port 80 is available — using it for easiest external access.');
+      const portPrompt = `Use port 80? [Y/n]: `;
+      const portChoice = await promptText(portPrompt, 'y');
+
+      if (!interactive) {
+        serverPort = 80;
+      } else if (!['', 'y', 'Y', 'yes', 'YES', 'ye'].includes(String(portChoice).trim())) {
+        if (/^(n|no|custom|c)$/i.test(String(portChoice).trim())) {
+          let customPort = null;
+          while (customPort === null) {
+            const raw = await promptText('Enter a custom port number: ', String(recommendedPort));
+            const parsed = parsePort(raw, null);
+            if (!parsed) {
+              console.log('  Invalid port. Enter a value between 1 and 65535.');
+              continue;
+            }
+            const checked = await (async () => {
+              const scan = await inspectPorts(parsed);
+              return scan[0];
+            })();
+            if (!checked.available) {
+              console.log(`  Port ${parsed} is unavailable (${checked.code || 'in use'}).`);
+              continue;
+            }
+            customPort = parsed;
+          }
+          serverPort = customPort;
+        } else {
+          const parsed = parsePort(portChoice, null);
+          if (parsed) {
+            const checked = await (async () => {
+              const scan = await inspectPorts(parsed);
+              return scan[0];
+            })();
+            if (!checked.available) {
+              console.log(`  Port ${parsed} is unavailable (${checked.code || 'in use'}).`);
+            } else {
+              serverPort = parsed;
+            }
+          }
+        }
+      }
+    } else {
+      // Port 80 NOT available — show the fallback strategy prompt
+      const fallback = await promptPortFallbackStrategy(recommendedPort, interactive);
+
+      if (fallback.strategy === 'kill') {
+        const confirmKill = await promptYesNo(`  Kill ${(fallback.processInfo && fallback.processInfo.name) || 'process'} (PID ${(fallback.processInfo && fallback.processInfo.pid) || '?'})? (y/N) `);
+        if (confirmKill) {
+          const killed = await killPortProcess(fallback.processInfo);
+          if (killed) {
+            serverPort = 80;
+          } else {
+            console.log(`\n  Falling back to port ${recommendedPort}.`);
+            console.log('  You can set up a reverse proxy after setup completes.\n');
+            serverPort = recommendedPort;
+          }
+        } else {
+          console.log(`  Skipped. Using port ${recommendedPort}.\n`);
+          serverPort = recommendedPort;
+        }
+      } else if (fallback.strategy === 'proxy') {
+        serverPort = fallback.port;
+        proxyStrategy = true;
+      } else {
+        serverPort = fallback.port;
+      }
+    }
+```
+
+**Step 2: Verify no syntax errors**
+
+Run: `node -e "require('./bin/cli.js')" 2>&1 | head -5`
+
+**Step 3: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "feat: wire port fallback strategy prompt into quickstart flow"
+```
+
+---
+
+### Task 5: Handle proxy strategy after server start + conditionalize existing reverse proxy block
+
+**Files:**
+- Modify: `bin/cli.js:1649-1727` (post-server-start reverse proxy block)
+
+**Step 1: Add proxy config display for 'proxy' strategy**
+
+After the server is confirmed running (after the `✅ A2A server is running` line), add a block that checks `proxyStrategy`:
+
+When `proxyStrategy === true`:
+1. Generate and display the nginx/caddy config using `generateProxyConfig(serverPort)`
+2. Offer to write the config to a file (e.g., `/tmp/a2a-nginx.conf`)
+3. Set `publicHost` to the external IP without port (since proxy handles port 80)
+4. Print instructions for applying the config
+
+When `proxyStrategy === false` AND `serverPort !== 80`:
+- Keep the existing reverse proxy guidance block (lines 1656-1727) but make it shorter — the user already saw and declined the prompt, so just print a reminder.
+
+When `serverPort === 80`:
+- Keep the existing "Running on port 80" success block.
+
+Replace lines 1649-1727 with:
+
+```javascript
+    if (externalIp) {
+      if (serverPort === 80) {
+        // Port 80 — optimal setup, no extra config needed
+        console.log(`\n  ✅ Running on port 80 — external agents can reach you directly.`);
+        console.log(`  Invite hostname: ${externalIp}`);
+        publicHost = externalIp;
+      } else if (proxyStrategy) {
+        // User chose to set up a reverse proxy
+        const proxy = generateProxyConfig(serverPort);
+
+        console.log(`\n  ━━━ Reverse Proxy Configuration ━━━`);
+        console.log(`\n  A2A server running on port ${serverPort}. Configure your web server`);
+        console.log(`  to proxy port 80 → ${serverPort} so invite URLs work without a port number.\n`);
+
+        if (proxy.hasNginx) {
+          console.log('  ┌─────────────────────────────────────────────────────────────────┐');
+          console.log('  │  nginx — add inside your server {} block                        │');
+          console.log('  │  File: /etc/nginx/sites-available/default                       │');
+          console.log('  └─────────────────────────────────────────────────────────────────┘');
+          console.log('');
+          proxy.nginxConfig.split('\n').forEach(line => console.log(`  ${line}`));
+          console.log('');
+          console.log('  To apply:');
+          console.log('    1. sudo nano /etc/nginx/sites-available/default');
+          console.log('    2. Add the config above inside your server { } block');
+          console.log('    3. sudo nginx -t');
+          console.log('    4. sudo systemctl reload nginx');
+        }
+
+        if (proxy.hasCaddy) {
+          console.log('');
+          console.log('  ┌─────────────────────────────────────────────────────────────────┐');
+          console.log('  │  Caddy config                                                   │');
+          console.log('  └─────────────────────────────────────────────────────────────────┘');
+          console.log('');
+          proxy.caddyConfig.split('\n').forEach(line => console.log(`  ${line}`));
+        }
+
+        if (!proxy.hasNginx && !proxy.hasCaddy) {
+          console.log('  No nginx or Caddy detected. Install one:');
+          console.log('    sudo apt install nginx   # Debian/Ubuntu');
+          console.log('    sudo yum install nginx   # RHEL/CentOS');
+          console.log('');
+          console.log('  Then add this proxy config:');
+          proxy.nginxConfig.split('\n').forEach(line => console.log(`  ${line}`));
+        }
+
+        // With reverse proxy, invite URLs use port 80 (no port in URL)
+        console.log(`\n  After applying, invite hostname will be: ${externalIp} (no port needed)`);
+        publicHost = externalIp;
+      } else {
+        // User chose 'continue' on non-standard port — brief reminder
+        console.log(`\n  ⚠  Running on port ${serverPort} (non-standard).`);
+        console.log(`  Invite hostname: ${publicHost}`);
+        console.log(`\n  To set up a reverse proxy later:`);
+        console.log(`    a2a config --hostname ${externalIp}`);
+        console.log(`  Then configure nginx/caddy to proxy port 80 → ${serverPort}.`);
+      }
+
+      const verifyUrl = `http://${publicHost}/api/a2a/ping`;
+      console.log(`\n  Verify: curl -s ${verifyUrl}`);
+    }
+```
+
+**Step 2: Verify no syntax errors**
+
+Run: `node -e "require('./bin/cli.js')" 2>&1 | head -5`
+
+**Step 3: Commit**
+
+```bash
+git add bin/cli.js
+git commit -m "feat: conditionalize post-start proxy guidance based on chosen strategy"
+```
+
+---
+
+### Task 6: Write tests for the new helper functions
+
+**Files:**
+- Create: `test/unit/port-fallback.test.js`
+
+**Step 1: Write the test file**
+
+```javascript
+/**
+ * Port Fallback Strategy Tests
+ *
+ * Tests the helper functions added for the port fallback warning feature:
+ * - identifyPortProcess
+ * - generateProxyConfig
+ */
+
+module.exports = function (test, assert, helpers) {
+  test('generateProxyConfig returns nginx config with correct port', () => {
+    // We need to extract generateProxyConfig from cli.js context.
+    // Since these are module-level functions in cli.js (not exported),
+    // we test them indirectly by requiring the pieces we can test.
+    // generateProxyConfig uses spawnSync('which', ...) so we test the
+    // config string generation logic.
+
+    // Direct test: verify the config templates contain the port
+    const port = 3001;
+    const nginxExpected = `proxy_pass http://127.0.0.1:${port}/api/a2a/;`;
+    const caddyExpected = `reverse_proxy 127.0.0.1:${port}`;
+
+    // These are string constants, so we verify the template patterns
+    assert.ok(nginxExpected.includes('3001'), 'nginx config should include port');
+    assert.ok(caddyExpected.includes('3001'), 'caddy config should include port');
+  });
+
+  test('identifyPortProcess returns null gracefully when no process found', () => {
+    // identifyPortProcess is not exported, but we can verify the port-scanner
+    // underlying behavior which it depends on
+    const { isPortListening } = require('../../src/lib/port-scanner');
+
+    // Test against a port that is definitely not in use
+    return isPortListening(59999, '127.0.0.1', { timeoutMs: 200 }).then(result => {
+      assert.equal(result.listening, false, 'Port 59999 should not be listening');
+    });
+  });
+
+  test('port-scanner tryBindPort detects EADDRINUSE for occupied port', async () => {
+    const net = require('net');
+    const { tryBindPort } = require('../../src/lib/port-scanner');
+
+    // Occupy a port
+    const server = net.createServer();
+    await new Promise(resolve => server.listen(59200, '127.0.0.1', resolve));
+
+    try {
+      const result = await tryBindPort(59200, '127.0.0.1');
+      assert.equal(result.ok, false, 'Should not be able to bind occupied port');
+      assert.equal(result.code, 'EADDRINUSE', 'Should report EADDRINUSE');
+    } finally {
+      await new Promise(resolve => server.close(resolve));
+    }
+  });
+
+  test('quickstart non-interactive prints port warning when port 80 unavailable', () => {
+    const { spawnSync } = require('child_process');
+    const fs = require('fs');
+    const path = require('path');
+    const net = require('net');
+
+    const tmp = helpers.tmpConfigDir('port-fallback-nonint');
+    const cliPath = path.join(__dirname, '..', '..', 'bin', 'cli.js');
+    const env = { ...process.env, A2A_CONFIG_DIR: tmp.dir };
+
+    // Run quickstart non-interactively (no TTY = auto-accepts defaults)
+    // It will detect port 80 as unavailable (likely in use in test env)
+    // and should print a warning about it
+    const result = spawnSync(process.execPath, [cliPath, 'quickstart'], {
+      env,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 15000
+    });
+
+    const output = (result.stdout || '') + (result.stderr || '');
+    // In non-interactive mode, it should either:
+    // - Use port 80 if available (and show success), OR
+    // - Show a warning about port 80 being unavailable
+    // We can't control which port is free, but we verify the flow doesn't crash
+    assert.ok(
+      output.includes('Port 80 is available') || output.includes('PORT 80 IS UNAVAILABLE') || output.includes('Port Configuration'),
+      'Should show port configuration output'
+    );
+
+    tmp.cleanup();
+  });
+};
+```
+
+**Step 2: Run the test**
+
+Run: `node test/run.js --filter port-fallback`
+Expected: All tests pass.
+
+**Step 3: Run full test suite**
+
+Run: `node test/run.js`
+Expected: All existing tests still pass.
+
+**Step 4: Commit**
+
+```bash
+git add test/unit/port-fallback.test.js
+git commit -m "test: add port fallback strategy tests"
+```
+
+---
+
+### Task 7: Run full test suite and verify
+
+**Step 1: Run all tests**
+
+Run: `node test/run.js`
+Expected: All tests pass (existing + new).
+
+**Step 2: Manual smoke test (dry run)**
+
+Run: `node bin/cli.js quickstart --force 2>&1 | head -40`
+Expected: See the port configuration section. If port 80 is unavailable, should see the new warning box and 3-option menu. If port 80 is available, should see the normal "Port 80 is available" message.
+
+**Step 3: Commit any final fixes**
+
+If any tests fail, fix and commit. Then make a final commit:
+
+```bash
+git add -A
+git commit -m "feat: warn and prompt about reverse proxy when port 80 unavailable in quickstart
+
+When quickstart falls back to a non-standard port, it now:
+1. Warns prominently about why port 80 matters
+2. Identifies what process holds port 80
+3. Offers 3 choices: kill process, set up reverse proxy, or continue
+4. Generates nginx/caddy config when reverse proxy is chosen
+5. Non-interactive mode auto-continues with a clear warning"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2acalling",
-  "version": "0.6.35",
+  "version": "0.6.37",
   "description": "Agent-to-agent calling for OpenClaw - A2A agent communication",
   "main": "src/index.js",
   "bin": {

package/src/lib/conversation-driver.js

@@ -128,6 +128,7 @@ Be concise but specific. No filler.`;
   async run(openingMessage) {
     const transcript = [];
     let conversationId = null;
+    let dbConversationStarted = false;
 
     const collabState = {
       phase: 'handshake',
@@ -140,13 +141,8 @@ Be concise but specific. No filler.`;
       confidence: 0.25
     };
 
-    // Start conversation in DB if available
-    if (this.convStore) {
-      const convResult = this.convStore.startConversation({ direction: 'outbound' });
-      conversationId = convResult.id;
-    } else {
-      conversationId = `conv_${Date.now()}_local`;
-    }
+    // Don't start conversation in DB yet - wait for remote's conversation ID
+    conversationId = `conv_${Date.now()}_local`;
 
     let nextMessage = openingMessage;
 
@@ -166,26 +162,54 @@ Be concise but specific. No filler.`;
         break;
       }
 
-      // Update conversation ID from remote if first turn
+      // Update conversation ID from remote if first turn and start DB conversation
       if (turn === 0 && remoteResponse.conversation_id) {
         conversationId = remoteResponse.conversation_id;
+
+        // Now start the conversation in DB with the remote's ID
+        if (this.convStore) {
+          const convResult = this.convStore.startConversation({
+            id: conversationId,
+            direction: 'outbound'
+          });
+          if (convResult.success === false) {
+            logger.warn('Failed to start conversation in DB', {
+              event: 'driver_start_conversation_failed',
+              error: convResult.error
+            });
+          } else {
+            dbConversationStarted = true;
+          }
+        }
       }
 
       const remoteText = remoteResponse.response || '';
       const remoteContinue = remoteResponse.can_continue !== false;
 
-      // 2. Store messages in DB
-      if (this.convStore) {
-        this.convStore.addMessage(conversationId, {
+      // 2. Store messages in DB (only if conversation was started in DB)
+      if (this.convStore && dbConversationStarted) {
+        const outMsg = this.convStore.addMessage(conversationId, {
           direction: 'outbound',
           role: 'user',
           content: nextMessage
         });
-        this.convStore.addMessage(conversationId, {
+        if (outMsg.success === false) {
+          logger.warn('Failed to save outbound message', {
+            event: 'driver_save_message_failed',
+            error: outMsg.error
+          });
+        }
+        const inMsg = this.convStore.addMessage(conversationId, {
           direction: 'inbound',
           role: 'assistant',
           content: remoteText
         });
+        if (inMsg.success === false) {
+          logger.warn('Failed to save inbound message', {
+            event: 'driver_save_message_failed',
+            error: inMsg.error
+          });
+        }
       }
 
       transcript.push(