clawpad 0.3.4 → 0.3.6

package/bin/clawpad.js

@@ -6,11 +6,13 @@ const fs = require("fs");
 const os = require("os");
 const net = require("net");
 const readline = require("readline");
+const WebSocket = require("ws"); // Added for Relay Tunnel
 
 // ─── Constants ───────────────────────────────────────────
 const DEFAULT_PORT = 3333;
 const GATEWAY_DEFAULT_PORT = 18789;
 const ROOT_DIR = path.resolve(__dirname, "..");
+const RELAY_SERVER_URL = "wss://relay.clawpad.io"; // Default Production Relay
 const LOCALHOST_PROBE_HOSTS = ["127.0.0.1", "::1"];
 const FORCE_KILL_GRACE_MS = 1500;
 const FORCE_KILL_VERIFY_MS = 4000;
@@ -26,41 +28,316 @@ const QMD_INSTALL_SCRIPT_URL =
 // ─── Arg Parsing ─────────────────────────────────────────
 const args = process.argv.slice(2);
 
-if (args.includes("--help") || args.includes("-h")) {
-  printHelp();
-  process.exit(0);
-}
-
-const portIdx = Math.max(args.indexOf("-p"), args.indexOf("--port"));
-let port =
-  portIdx !== -1 && args[portIdx + 1]
-    ? parseInt(args[portIdx + 1], 10)
-    : parseInt(process.env.PORT || String(DEFAULT_PORT), 10);
-const portExplicit = portIdx !== -1 || Boolean(process.env.PORT);
-
-const shouldOpen = !args.includes("--no-open");
-const shouldSetup = args.includes("--setup");
-const shouldIntegrate = !args.includes("--no-integrate");
-const autoYes = args.includes("--yes");
-const noPrompt = args.includes("--no-prompt");
-const forcePort = args.includes("--force");
-const migrateArg = args.find((arg) => arg === "--migrate" || arg.startsWith("--migrate="));
-let migrateMode = null;
-if (migrateArg) {
-  if (migrateArg.includes("=")) {
-    migrateMode = migrateArg.split("=")[1] || "move";
-  } else {
-    const idx = args.indexOf("--migrate");
-    const next = idx !== -1 ? args[idx + 1] : null;
-    migrateMode = next && !next.startsWith("-") ? next : "move";
+// Handle Cloud Share Command
+if (args[0] === "share") {
+  startShare(args.slice(1));
+} else {
+  // Normal Launcher Logic
+  runLauncher(args);
+}
+
+function normalizeListenHost(input) {
+  const raw = String(input ?? "").trim();
+  if (!raw) return "localhost";
+  if (raw.startsWith("http://") || raw.startsWith("https://")) {
+    try {
+      const parsed = new URL(raw);
+      return parsed.hostname || "localhost";
+    } catch {
+      return "localhost";
+    }
+  }
+  return raw.replace(/^\[/, "").replace(/\]$/, "");
+}
+
+function isWildcardHost(host) {
+  return host === "0.0.0.0" || host === "::";
+}
+
+function formatHostForUrl(host) {
+  if (!host) return "localhost";
+  if (host.includes(":") && !host.startsWith("[") && !host.endsWith("]")) {
+    return `[${host}]`;
+  }
+  return host;
+}
+
+function getWindowsStateDirCandidates() {
+  if (process.platform !== "win32") return [];
+  const candidates = [
+    process.env.APPDATA ? path.join(process.env.APPDATA, "OpenClaw") : null,
+    process.env.APPDATA ? path.join(process.env.APPDATA, "openclaw") : null,
+    process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, "OpenClaw") : null,
+    process.env.LOCALAPPDATA ? path.join(process.env.LOCALAPPDATA, "openclaw") : null,
+    path.join(os.homedir(), "AppData", "Roaming", "OpenClaw"),
+    path.join(os.homedir(), "AppData", "Roaming", "openclaw"),
+  ].filter(Boolean);
+  return [...new Set(candidates.map((candidate) => path.resolve(candidate)))];
+}
+
+function getPrimaryLanIpv4() {
+  const interfaces = os.networkInterfaces();
+  for (const entries of Object.values(interfaces)) {
+    if (!Array.isArray(entries)) continue;
+    for (const info of entries) {
+      if (!info) continue;
+      if (info.family !== "IPv4") continue;
+      if (info.internal) continue;
+      if (info.address.startsWith("169.254.")) continue;
+      return info.address;
+    }
+  }
+  return null;
+}
+
+function normalizeToken(raw) {
+  if (typeof raw !== "string") return undefined;
+  const trimmed = raw.trim();
+  return trimmed || undefined;
+}
+
+function normalizeScopes(raw) {
+  const scopes = new Set();
+  const parts = [];
+  if (typeof raw === "string") {
+    parts.push(...raw.split(/[,\s]+/g));
+  } else if (Array.isArray(raw)) {
+    for (const item of raw) {
+      if (typeof item === "string") {
+        parts.push(...item.split(/[,\s]+/g));
+      }
+    }
+  }
+  for (const part of parts) {
+    const normalized = String(part || "").trim().toLowerCase();
+    if (normalized) scopes.add(normalized);
+  }
+  return scopes;
+}
+
+function scoreScopes(scopes) {
+  if (scopes.has("operator.admin")) return 100;
+  if (scopes.has("operator.write")) return 90;
+  if (scopes.has("operator.read")) return 20;
+  return 10;
+}
+
+function extractTokenFromEntry(entry) {
+  if (typeof entry === "string") {
+    return normalizeToken(entry);
   }
+  if (!entry || typeof entry !== "object") {
+    return undefined;
+  }
+  if (entry.enabled === false) {
+    return undefined;
+  }
+  return normalizeToken(
+    entry.token ??
+      entry.value ??
+      entry.accessToken ??
+      entry.access_token ??
+      entry.bearer ??
+      entry.secret,
+  );
+}
+
+function selectGatewayAuthToken(auth) {
+  if (!auth || typeof auth !== "object") return undefined;
+
+  const candidates = [];
+  const directToken = normalizeToken(auth.token);
+  if (directToken) {
+    const directScopes = normalizeScopes(auth.scopes ?? auth.scope);
+    candidates.push({
+      token: directToken,
+      score: directScopes.size > 0 ? scoreScopes(directScopes) + 30 : 50,
+      priority: 0,
+    });
+  }
+
+  const tokenEntries = Array.isArray(auth.tokens) ? auth.tokens : [];
+  for (let index = 0; index < tokenEntries.length; index += 1) {
+    const entry = tokenEntries[index];
+    const token = extractTokenFromEntry(entry);
+    if (!token) continue;
+    const entryScopes =
+      entry && typeof entry === "object"
+        ? normalizeScopes(entry.scopes ?? entry.scope)
+        : new Set();
+    candidates.push({
+      token,
+      score: entryScopes.size > 0 ? scoreScopes(entryScopes) : 25,
+      priority: index + 1,
+    });
+  }
+
+  if (candidates.length === 0) return undefined;
+  candidates.sort((a, b) => b.score - a.score || a.priority - b.priority);
+  return candidates[0].token;
 }
 
-const pagesDirIdx = args.indexOf("--pages-dir");
-if (pagesDirIdx !== -1 && args[pagesDirIdx + 1]) {
-  process.env.CLAWPAD_PAGES_DIR = args[pagesDirIdx + 1];
+// ─── Cloud Share Logic ──────────────────────────────────
+async function startShare(shareArgs) {
+  console.log(`
+  ┌─────────────────────────────────────┐
+  │         ClawPad Cloud Share         │
+  └─────────────────────────────────────┘
+  `);
+
+  const gateway = await detectGateway();
+  if (!gateway) {
+    console.error("  ❌ No OpenClaw Gateway detected. Is it running?");
+    process.exit(1);
+  }
+  console.log(`  🔗 Local Gateway: ${gateway.url}`);
+
+  const tokenArg = shareArgs.find(arg => arg.startsWith("--token="));
+  const token = tokenArg ? tokenArg.split("=")[1] : process.env.CLAWPAD_RELAY_TOKEN;
+
+  if (!token) {
+    console.error("  ❌ No Relay Token provided.");
+    console.error("     Use --token=<your_token> or set CLAWPAD_RELAY_TOKEN env var.");
+    console.error("     Get your token at https://app.clawpad.io/settings");
+    process.exit(1);
+  }
+
+  const relayUrl = process.env.CLAWPAD_RELAY_URL || RELAY_SERVER_URL;
+  connectRelay(relayUrl, token, gateway.url);
+}
+
+function connectRelay(relayUrl, token, gatewayWsUrl) {
+  console.log(`  ☁️  Connecting to Relay: ${relayUrl}...`);
+
+  const tunnelUrl = `${relayUrl}?type=agent&token=${token}`;
+  const ws = new WebSocket(tunnelUrl);
+  let gatewayWs = null;
+  let reconnectTimer = null;
+
+  const cleanup = () => {
+    if (gatewayWs) {
+      gatewayWs.terminate();
+      gatewayWs = null;
+    }
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  };
+
+  ws.on("open", () => {
+    console.log("  ✅ Connected to Cloud Relay.");
+    console.log("     Your agent is now accessible via app.clawpad.io");
+    
+    // Connect to Local Gateway
+    gatewayWs = new WebSocket(gatewayWsUrl);
+    
+    gatewayWs.on("open", () => {
+      console.log("  🔗 Connected to Local Gateway.");
+    });
+
+    gatewayWs.on("message", (data) => {
+      // Forward Gateway -> Relay
+      // SECURITY: Here we could inspect 'data' if needed, but it's encrypted JSON-RPC usually.
+      // We rely on 'tools.allow' policy for security.
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(data);
+      }
+    });
+
+    gatewayWs.on("error", (err) => {
+      console.error("  ⚠️ Local Gateway Error:", err.message);
+    });
+
+    gatewayWs.on("close", () => {
+      console.log("  ⚠️ Local Gateway Disconnected. Reconnecting in 5s...");
+      setTimeout(() => {
+        if (ws.readyState === WebSocket.OPEN) {
+           // Re-establish local connection logic could go here or just let it fail until next message
+           // Ideally we close the tunnel or try to reconnect local
+           ws.close(); // Force full reconnect cycle
+        }
+      }, 5000);
+    });
+  });
+
+  ws.on("message", (data) => {
+    // Forward Relay -> Gateway
+    // SECURITY: Intercept dangerous calls here if we parse JSON-RPC
+    if (gatewayWs && gatewayWs.readyState === WebSocket.OPEN) {
+      gatewayWs.send(data);
+    }
+  });
+
+  ws.on("error", (err) => {
+    console.error("  ❌ Relay Connection Error:", err.message);
+  });
+
+  ws.on("close", () => {
+    console.log("  ❌ Disconnected from Relay. Reconnecting in 5s...");
+    cleanup();
+    reconnectTimer = setTimeout(() => connectRelay(relayUrl, token, gatewayWsUrl), 5000);
+  });
+}
+
+// ─── Normal Launcher Logic ──────────────────────────────
+async function runLauncher(args) {
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const portIdx = Math.max(args.indexOf("-p"), args.indexOf("--port"));
+  let port =
+    portIdx !== -1 && args[portIdx + 1]
+      ? parseInt(args[portIdx + 1], 10)
+      : parseInt(process.env.PORT || String(DEFAULT_PORT), 10);
+  const portExplicit = portIdx !== -1 || Boolean(process.env.PORT);
+  const hostIdx = Math.max(args.indexOf("-H"), args.indexOf("--host"));
+  const listenHost =
+    hostIdx !== -1 && args[hostIdx + 1]
+      ? normalizeListenHost(args[hostIdx + 1])
+      : normalizeListenHost(process.env.CLAWPAD_HOST || "localhost");
+
+  const shouldOpen = !args.includes("--no-open");
+  const shouldSetup = args.includes("--setup");
+  const shouldIntegrate = !args.includes("--no-integrate");
+  const autoYes = args.includes("--yes");
+  const noPrompt = args.includes("--no-prompt");
+  const forcePort = args.includes("--force");
+  const migrateArg = args.find((arg) => arg === "--migrate" || arg.startsWith("--migrate="));
+  let migrateMode = null;
+  if (migrateArg) {
+    if (migrateArg.includes("=")) {
+      migrateMode = migrateArg.split("=")[1] || "move";
+    } else {
+      const idx = args.indexOf("--migrate");
+      const next = idx !== -1 ? args[idx + 1] : null;
+      migrateMode = next && !next.startsWith("-") ? next : "move";
+    }
+  }
+
+  const pagesDirIdx = args.indexOf("--pages-dir");
+  if (pagesDirIdx !== -1 && args[pagesDirIdx + 1]) {
+    process.env.CLAWPAD_PAGES_DIR = args[pagesDirIdx + 1];
+  }
+  const hasExplicitPagesDir = Boolean(process.env.CLAWPAD_PAGES_DIR);
+
+  main(
+    port,
+    portExplicit,
+    shouldOpen,
+    shouldSetup,
+    shouldIntegrate,
+    autoYes,
+    noPrompt,
+    forcePort,
+    migrateMode,
+    hasExplicitPagesDir,
+    listenHost,
+  );
 }
-const hasExplicitPagesDir = Boolean(process.env.CLAWPAD_PAGES_DIR);
 
 // ─── Help ────────────────────────────────────────────────
 function printHelp() {
@@ -68,26 +345,33 @@ function printHelp() {
   ClawPad — The workspace for OpenClaw
 
   Usage:
-    clawpad [options]
+    clawpad [command] [options]
 
-  Options:
+  Commands:
+    start (default)     Start the local workspace UI
+    share               Connect this agent to ClawPad Cloud
+
+  Options (start):
     -p, --port <port>   Port to listen on (default: ${DEFAULT_PORT})
+    -H, --host <host>   Host/interface to bind (default: localhost)
     --no-open           Don't auto-open the browser
     --pages-dir <dir>   Override docs directory (default: auto)
-    --migrate[=mode]    Migrate legacy docs (mode: move|copy)
     --setup             Open setup onboarding flow on launch
-    --no-integrate      Skip OpenClaw integration prompt
     --yes               Auto-approve integration steps
-    --no-prompt         Disable integration prompt (skip changes)
     --force             Kill any process using the selected port
     -h, --help          Show this help message
 
+  Options (share):
+    --token <token>     Relay token from app.clawpad.io
+
   Examples:
     clawpad                 Start on port ${DEFAULT_PORT}
     clawpad -p 4000         Start on port 4000
+    clawpad --host 0.0.0.0  Allow LAN access from other devices
     clawpad --no-open       Start without opening browser
     clawpad --setup         Start and open setup onboarding
     clawpad --yes           Auto-integrate with OpenClaw if detected
+    clawpad share --token=abc  Connect to cloud
 `);
 }
 
@@ -112,6 +396,7 @@ async function detectGateway() {
   if (process.env.OPENCLAW_GATEWAY_URL) {
     return {
       url: process.env.OPENCLAW_GATEWAY_URL,
+      token: normalizeToken(process.env.OPENCLAW_GATEWAY_TOKEN),
       source: "env",
     };
   }
@@ -124,6 +409,10 @@ async function detectGateway() {
     explicitConfig ? resolveUserPath(explicitConfig) : null,
     stateDir ? path.join(resolveUserPath(stateDir), "openclaw.json") : null,
     stateDir ? path.join(resolveUserPath(stateDir), "clawdbot.json") : null,
+    ...getWindowsStateDirCandidates().flatMap((dir) => [
+      path.join(dir, "openclaw.json"),
+      path.join(dir, "clawdbot.json"),
+    ]),
     path.join(os.homedir(), ".openclaw", "openclaw.json"),
     path.join(os.homedir(), ".clawdbot", "clawdbot.json"),
   ].filter(Boolean);
@@ -136,7 +425,7 @@ async function detectGateway() {
         const host = normalizeHost(config.gateway?.bind ?? config.gateway?.host ?? config.host ?? "127.0.0.1");
         return {
           url: `ws://${host}:${gwPort}`,
-          token: config.gateway?.auth?.token,
+          token: selectGatewayAuthToken(config.gateway?.auth),
           source: path.basename(configPath),
         };
       }
@@ -361,6 +650,104 @@ async function killPortListeners(port) {
   return { killedAny: true, verifiedFree };
 }
 
+function readProcessCommand(pid) {
+  try {
+    return execSync(`ps -o command= -p ${pid}`, {
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+  } catch {
+    return "";
+  }
+}
+
+function readProcessInfo(pid) {
+  if (process.platform === "win32") {
+    return null;
+  }
+
+  try {
+    const output = execSync(`ps -o ppid=,command= -p ${pid}`, {
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+      .toString()
+      .trim();
+
+    if (!output) return null;
+    const match = output.match(/^(\d+)\s+([\s\S]+)$/);
+    if (!match) return null;
+
+    const ppid = Number(match[1]);
+    const command = match[2].trim();
+    const parentCommand = Number.isFinite(ppid) && ppid > 0 ? readProcessCommand(ppid) : "";
+
+    return {
+      pid: Number(pid),
+      ppid,
+      command,
+      parentCommand,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function isLikelyClawpadListener(info) {
+  if (!info) return false;
+  const command = String(info.command || "").toLowerCase();
+  const parentCommand = String(info.parentCommand || "").toLowerCase();
+
+  if (command.includes("clawpad") || parentCommand.includes("clawpad")) {
+    return true;
+  }
+
+  if (
+    command.includes(".next/standalone/server.js") &&
+    (parentCommand.includes("clawpad") || command.includes("node_modules/clawpad"))
+  ) {
+    return true;
+  }
+
+  if (command.includes("next-server") && parentCommand.includes("clawpad")) {
+    return true;
+  }
+
+  return false;
+}
+
+async function maybeReplaceExistingClawpadListener(port) {
+  if (process.env.CLAWPAD_DISABLE_AUTO_PORT_REPLACE === "1") {
+    return { attempted: false, reason: "disabled" };
+  }
+
+  if (process.platform === "win32") {
+    return { attempted: false, reason: "unsupported-platform" };
+  }
+
+  const pids = listListeningPids(port);
+  if (pids.length === 0) {
+    return { attempted: false, reason: "no-listener" };
+  }
+
+  const infos = pids.map((pid) => readProcessInfo(pid)).filter(Boolean);
+  if (infos.length === 0) {
+    return { attempted: false, reason: "no-process-info" };
+  }
+
+  const allClawpad = infos.every((info) => isLikelyClawpadListener(info));
+  if (!allClawpad) {
+    return { attempted: false, reason: "non-clawpad-listener" };
+  }
+
+  const kill = await killPortListeners(port);
+  return {
+    attempted: true,
+    infos,
+    ...kill,
+  };
+}
+
 function resolveUserPath(input) {
   if (!input || !input.trim()) return input;
   if (input.startsWith("~")) {
@@ -548,6 +935,12 @@ function resolveOpenClawStateDir() {
   if (override && override.trim()) {
     return resolveUserPath(override);
   }
+  const windowsCandidate = getWindowsStateDirCandidates().find((candidate) =>
+    fs.existsSync(candidate),
+  );
+  if (windowsCandidate) {
+    return windowsCandidate;
+  }
   return path.join(os.homedir(), ".openclaw");
 }
 
@@ -566,9 +959,14 @@ function findOpenClawConfigPath() {
     return fs.existsSync(resolved) ? resolved : null;
   }
   const stateDir = resolveOpenClawStateDir();
+  const windowsStateDirs = getWindowsStateDirCandidates();
   const candidates = [
     path.join(stateDir, "openclaw.json"),
     path.join(stateDir, "clawdbot.json"),
+    ...windowsStateDirs.flatMap((dir) => [
+      path.join(dir, "openclaw.json"),
+      path.join(dir, "clawdbot.json"),
+    ]),
     path.join(os.homedir(), ".openclaw", "openclaw.json"),
     path.join(os.homedir(), ".clawdbot", "clawdbot.json"),
   ];
@@ -908,16 +1306,31 @@ function applyIntegrationConfig(config, pagesDir, qmdPath) {
 
   next.agents = next.agents || {};
   next.agents.defaults = next.agents.defaults || {};
-  const memory = next.agents.defaults.memory || {};
-  const memoryQmd = memory.qmd || {};
-  next.agents.defaults.memory = {
-    ...memory,
-    backend: "qmd",
-    qmd: {
-      ...memoryQmd,
-      ...(qmdPath ? { bin: qmdPath } : {}),
-    },
-  };
+
+  // OpenClaw 2026+ no longer recognizes agents.defaults.memory.
+  // Only write this legacy key when explicitly forced.
+  const hasLegacyMemoryKey =
+    next.agents.defaults.memory &&
+    typeof next.agents.defaults.memory === "object";
+  const shouldWriteLegacyMemory =
+    process.env.CLAWPAD_FORCE_LEGACY_MEMORY === "1";
+
+  if (shouldWriteLegacyMemory) {
+    const memory = next.agents.defaults.memory || {};
+    const memoryQmd = memory.qmd || {};
+    next.agents.defaults.memory = {
+      ...memory,
+      backend: "qmd",
+      qmd: {
+        ...memoryQmd,
+        ...(qmdPath ? { bin: qmdPath } : {}),
+      },
+    };
+  } else if (hasLegacyMemoryKey) {
+    // If a prior ClawPad version wrote this legacy key but it's not forced now,
+    // remove it to avoid OpenClaw config validation errors on modern versions.
+    delete next.agents.defaults.memory;
+  }
 
   const memorySearch = next.agents.defaults.memorySearch || {};
   const extraPaths = Array.isArray(memorySearch.extraPaths) ? [...memorySearch.extraPaths] : [];
@@ -939,11 +1352,20 @@ function needsIntegrationPatch(config, pagesDir, qmdPath) {
   const pluginEnabled = entry?.enabled === true;
   const extraPaths = config?.agents?.defaults?.memorySearch?.extraPaths;
   const hasExtraPath = Array.isArray(extraPaths) && extraPaths.includes(pagesDir);
+  const hasLegacyMemoryKey = Boolean(
+    config?.agents?.defaults?.memory &&
+      typeof config.agents.defaults.memory === "object",
+  );
+  const forceLegacyMemory = process.env.CLAWPAD_FORCE_LEGACY_MEMORY === "1";
+
   const memoryBackend = config?.agents?.defaults?.memory?.backend;
   const configuredQmdBin = config?.agents?.defaults?.memory?.qmd?.bin;
   const qmdConfigured = memoryBackend === "qmd" && (!qmdPath || configuredQmdBin === qmdPath);
 
-  return !(pluginEnabled && configuredPages === pagesDir && hasExtraPath && qmdConfigured);
+  const memoryReady = forceLegacyMemory ? qmdConfigured : true;
+  const memoryCleanupNeeded = hasLegacyMemoryKey && !forceLegacyMemory;
+
+  return !(pluginEnabled && configuredPages === pagesDir && hasExtraPath && memoryReady && !memoryCleanupNeeded);
 }
 
 async function integrateWithOpenClaw(pagesDir, qmdPath) {
@@ -953,6 +1375,22 @@ async function integrateWithOpenClaw(pagesDir, qmdPath) {
   const { configPath, config } = loadOpenClawConfig();
   const pluginInstalled = isPluginInstalled(config);
   const workspaceDir = resolveWorkspaceDir(config);
+  const hasLegacyMemoryKey = Boolean(
+    config?.agents?.defaults?.memory &&
+      typeof config.agents.defaults.memory === "object",
+  );
+
+  // Always clean the deprecated memory key for modern OpenClaw installs.
+  // This prevents "config invalid" states that can break gateway UX.
+  if (hasLegacyMemoryKey && process.env.CLAWPAD_FORCE_LEGACY_MEMORY !== "1") {
+    try {
+      delete config.agents.defaults.memory;
+      writeOpenClawConfig(configPath, config);
+      console.log("  ✅ Removed deprecated OpenClaw key: agents.defaults.memory");
+    } catch (err) {
+      console.warn(`  ⚠️  Failed to clean deprecated OpenClaw memory key: ${err?.message || err}`);
+    }
+  }
 
   const workspaceManagerSkill = ensureBundledSkillInstalled(workspaceDir, "workspace-manager");
   if (workspaceManagerSkill.installed) {
@@ -1083,16 +1521,41 @@ function openBrowser(url) {
 }
 
 // ─── Main ────────────────────────────────────────────────
-async function main() {
+async function main(
+  port,
+  portExplicit,
+  shouldOpen,
+  shouldSetup,
+  shouldIntegrate,
+  autoYes,
+  noPrompt,
+  forcePort,
+  migrateMode,
+  hasExplicitPagesDir,
+  listenHost,
+) {
   printBanner();
 
   if (!Number.isFinite(port) || port <= 0) {
     console.error(`  ❌ Invalid port: ${port}`);
     process.exit(1);
   }
+  if (!listenHost) {
+    console.error("  ❌ Invalid host.");
+    process.exit(1);
+  }
 
   if (await isPortInUse(port)) {
-    if (forcePort) {
+    if (!forcePort) {
+      const replaceResult = await maybeReplaceExistingClawpadListener(port);
+      if (replaceResult.attempted && replaceResult.killedAny && replaceResult.verifiedFree) {
+        console.log(`  ♻️  Replaced existing ClawPad listener on port ${port}.`);
+      } else if (replaceResult.attempted && replaceResult.killedAny && !replaceResult.verifiedFree) {
+        console.error(`  ❌ Found an existing ClawPad listener on port ${port} but could not free it.`);
+      }
+    }
+
+    if (forcePort && (await isPortInUse(port))) {
       const forceResult = await killPortListeners(port);
       if (forceResult.killedAny && forceResult.verifiedFree) {
         console.log(`  ✅ Cleared existing listeners on port ${port}.`);
@@ -1249,8 +1712,18 @@ async function main() {
     port = nextPort;
     const runningPort = nextPort;
     const setupPath = shouldSetup || setupSignalCreated ? "/setup" : "";
-    const url = `http://localhost:${port}${setupPath}`;
-    console.log(`  🚀 Starting ClawPad at ${url}\n`);
+    const browserHost = isWildcardHost(listenHost) ? "localhost" : listenHost;
+    const localUrl = `http://${formatHostForUrl(browserHost)}:${port}${setupPath}`;
+    console.log(`  🚀 Starting ClawPad at ${localUrl}`);
+    if (isWildcardHost(listenHost)) {
+      const lanIp = getPrimaryLanIpv4();
+      if (lanIp) {
+        console.log(`  🌐 Network URL: http://${lanIp}:${port}${setupPath}`);
+      } else {
+        console.log("  🌐 Network URL unavailable (no LAN IPv4 detected)");
+      }
+    }
+    console.log("");
 
     let sawAddrInUse = false;
     const childStartedAt = Date.now();
@@ -1260,7 +1733,7 @@ async function main() {
       env: {
         ...process.env,
         PORT: String(port),
-        HOSTNAME: "localhost",
+        HOSTNAME: listenHost,
       },
     });
 
@@ -1276,7 +1749,7 @@ async function main() {
 
     if (shouldOpen) {
       clearOpenTimer();
-      openTimer = setTimeout(() => openBrowser(url), 2000);
+      openTimer = setTimeout(() => openBrowser(localUrl), 2000);
     }
 
     server.on("error", (err) => {