lavish-axi 0.1.76 → 0.1.78

package/README.md

@@ -249,7 +249,8 @@ pnpm link
 - **Local-first state** - Session state stays under `~/.lavish-axi/` by default, or `LAVISH_AXI_STATE_DIR` when set.
 - **Diagnostic viewports** - `LAVISH_AXI_DIAGNOSTIC_VIEWPORTS` sets which viewport classes the layout-issue inbox tracks (`mobile`, `compact`, `desktop`; comma-separated, default all). Warnings whose class leaves the set are marked obsolete with an explicit reason instead of silently reading as fixed.
 - **Server port** - Set `LAVISH_AXI_PORT` to choose the server port; it defaults to `4387`.
-- **Network binding** - With Tailscale running, the review server automatically listens only on loopback (`127.0.0.1`) and this machine's Tailscale IPv4 address - never on `0.0.0.0` or every interface. The generated session link uses the machine's MagicDNS name, so it is the phone-ready URL to open from another device on the same tailnet. When Tailscale is absent or down, Lavish silently falls back to loopback-only and prints no phone URL. If Tailscale is running but MagicDNS is unavailable or its address cannot be bound after brief retries, Lavish visibly warns that phone access is unavailable and remains loopback-only. Binding beyond loopback exposes an unauthenticated server that can read and serve arbitrary local files to devices that can reach it, so the tailnet should be trusted. Any explicit `LAVISH_AXI_HOST` overrides automatic Tailscale binding; wildcard values are restricted to loopback, while a non-wildcard value selects that one concrete bind address. Each address is retried briefly, and if none can be bound Lavish falls back to loopback, warns that it is not reachable at the requested address, and points session links at loopback unless `LAVISH_AXI_LINK_HOST` explicitly overrides them - a locally reachable server beats no server at all. When an unavailable requested address returns, the next CLI invocation restarts the fallback server once to restore that listener. `LAVISH_AXI_LINK_HOST` controls the link host when automatic Tailscale binding is disabled.
+- **Network binding** - With Tailscale running, the review server automatically listens only on loopback (`127.0.0.1`) and this machine's Tailscale IPv4 address - never on `0.0.0.0` or every interface. The generated session link uses the machine's MagicDNS name, so it is the phone-ready URL to open from another device on the same tailnet. When Tailscale is absent or down, Lavish silently falls back to loopback-only and prints no phone URL. If Tailscale is running but MagicDNS is unavailable, Lavish visibly warns that phone access is unavailable and remains loopback-only. Binding beyond loopback exposes an unauthenticated server that can read and serve arbitrary local files to devices that can reach it, so the tailnet should be trusted. Any explicit `LAVISH_AXI_HOST` overrides automatic Tailscale binding; wildcard values are restricted to loopback, while a non-wildcard value selects that concrete bind address, and the server listens on loopback as well so every local CLI finds it whatever its own `LAVISH_AXI_HOST` says. An address that cannot be bound - the tailnet address while another process holds it, while Tailscale restarts, or an explicit hostname that temporarily does not resolve - is reported as `network_warning` in `lavish-axi <file>` output and logged to `server.log`; session links point at loopback meanwhile unless `LAVISH_AXI_LINK_HOST` overrides them, and the server keeps retrying that address in the background and immediately on the next CLI invocation. Once it binds, the warning clears and new session links use it again, with no restart. If no listener can bind, startup fails rather than claiming a reachable server. `LAVISH_AXI_LINK_HOST` controls the link host when automatic Tailscale binding is disabled.
+- **One server per port** - Agents on one machine can run with different `LAVISH_AXI_HOST` settings, or none, and still share one server: before starting one, the CLI looks for a running server on its configured host, loopback, and every other local address. A running server that was never asked to listen on the address a CLI's `LAVISH_AXI_HOST` names is replaced once by a server that listens on that address plus every address the old one served, keeping all sessions. Upgrade and network-change restarts keep every address the old server served in the same way, except an address that is no longer on this machine. Switching to an address the running server already serves, including loopback, reuses it, so run `lavish-axi stop` first to drop an address. Another server of the same installation (the same state directory) found on the same port at a different address is shut down through its own shutdown endpoint, after the kept server is made to serve that address too, so review links already handed out there keep working. A server belonging to another state directory that reports its installation identity is never used, replaced, or stopped: when it holds loopback or the configured address, the CLI fails with an error naming its state directory, so pick another `LAVISH_AXI_PORT`. Older servers that cannot report an identity are treated as belonging to this installation only at those control addresses, for upgrade compatibility.
 - **Allowed hosts** - To defend against DNS rebinding, the server rejects (`403`) any request whose `Host` header is missing or not one it answers to: loopback names plus the concrete Tailscale IPv4 address and MagicDNS name when the Tailscale listener is successfully bound. If you configure a reverse proxy or another intentional hostname, list it in `LAVISH_AXI_ALLOWED_HOSTS` (whitespace-separated). Behind a reverse proxy, the forwarded `X-Forwarded-Host` is validated against the same list, so add the public hostname there and have the proxy send it together with `X-Forwarded-Proto`. Set `LAVISH_AXI_ALLOWED_HOSTS` to `*` to disable the check entirely, only when the server sits behind your own authentication or proxy. Mutating routes also reject a present foreign `Origin` or `Referer` (`403`); header-less CLI control requests remain allowed where supported.
 - **Browser opening** - Set `LAVISH_AXI_NO_OPEN=1`, equivalent to `--no-open`, to create or resume a session without launching a browser window.
 
@@ -297,6 +298,7 @@ For flows, architecture, state, or sequence diagrams, open the diagram playbook
 | `lavish-axi poll`        | `--timeout-ms <ms>`         | Test/debug escape hatch only; agents should normally omit it and leave the long poll running.                                                                                                                                                                                                                                 |
 | `lavish-axi stop`        | `--port <port>`             | Shut down a server running on a non-default port.                                                                                                                                                                                                                                                                             |
 | `lavish-axi server`      | `--verbose`                 | Log session and watcher events to stderr; can also be enabled with `LAVISH_AXI_DEBUG=1`. Detached server output is appended with UTC timestamps to `~/.lavish-axi/server.log` (or `LAVISH_AXI_STATE_DIR/server.log`) for startup, shutdown-cause, and crash diagnostics.                                                      |
+| `lavish-axi server`      | `--also-listen <host>`      | Also listen on this concrete address (repeatable). The CLI passes it when it replaces a running server, so the replacement keeps every address the old one served; see One server per port.                                                                                                                                   |
 
 ## Development
 

package/dist/chrome-client.js

@@ -3129,9 +3129,9 @@ async function replaceArtifactFrame({ recoveryRetry = false } = {}) {
     return false;
   };
   // Keep whatever is on screen, then try again later. A begin-load can fail for reasons that
-  // clear on their own - the shared server is mid-restart, or its handoff map was reset by that
-  // restart and this chrome's one re-handshake landed in the same outage window. Giving up here
-  // is what leaves the review permanently unloaded.
+  // clear on their own - the shared server is mid-restart, or a handoff no begin-load had yet
+  // persisted was lost with that restart and this chrome's one re-handshake landed in the same
+  // outage window. Giving up here is what leaves the review permanently unloaded.
   const recoverLater = () => {
     preservePreviousLoad();
     if (requestSequence !== artifactLoadRequestSequence || ended) return false;

package/dist/cli.mjs

@@ -14,10 +14,12 @@ import {
   mkdirSync as mkdirSync2,
   openSync,
   readFileSync as readFileSync2,
-  realpathSync,
+  realpathSync as realpathSync2,
   writeFileSync as writeFileSync2
 } from "node:fs";
 import { access, readFile as readFile6, writeFile as writeFile4 } from "node:fs/promises";
+import { get as httpGet2 } from "node:http";
+import { isIP as isIP4 } from "node:net";
 import os4 from "node:os";
 import path8 from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
@@ -4400,8 +4402,13 @@ function parseJson(text) {
   }
 }
 
+// src/local-address.js
+import os2 from "node:os";
+
 // src/paths.js
+import { createHash } from "node:crypto";
 import { lookup as dnsLookup } from "node:dns/promises";
+import { realpathSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { isIP } from "node:net";
 import os from "node:os";
@@ -4424,15 +4431,16 @@ function isWildcardHost(host) {
 function bindHost(env = process.env) {
   return env.LAVISH_AXI_HOST?.trim() || LOOPBACK_HOST;
 }
-function resolveListenHosts({ host, env = process.env, tailscale = null } = {}) {
+function resolveListenHosts({ host, env = process.env, tailscale = null, extraHosts = [] } = {}) {
   const envHost = env.LAVISH_AXI_HOST?.trim() || "";
   const autoTailscale = !envHost;
   const requested = host || bindHost(env);
   const primary = isWildcardHost(requested) ? LOOPBACK_HOST : requested || LOOPBACK_HOST;
-  const hosts = [primary];
+  const hosts = [primary, LOOPBACK_HOST];
   if (autoTailscale && tailscale?.ipv4 && tailscale.ipv4 !== primary && !isWildcardHost(tailscale.ipv4)) {
     hosts.push(tailscale.ipv4);
   }
+  hosts.push(...extraHosts);
   return sanitizeListenHosts(hosts);
 }
 function sanitizeListenHosts(hosts) {
@@ -4444,12 +4452,17 @@ function sanitizeListenHosts(hosts) {
   }
   return out.length ? out : [LOOPBACK_HOST];
 }
-async function resolveConcreteListenHosts(hosts, { lookup = dnsLookup } = {}) {
+async function resolveConcreteListenHosts(hosts, { lookup = dnsLookup, keepUnresolved = false } = {}) {
   const resolved = [];
   for (const host of hosts) {
-    const addresses = await lookup(host, { all: true, verbatim: true });
+    const addresses = await lookup(host, { all: true, verbatim: true }).catch((error) => {
+      if (keepUnresolved) return [];
+      throw error;
+    });
     if (!Array.isArray(addresses) || addresses.length === 0) {
-      throw new Error(`Listen host did not resolve: ${host}`);
+      if (!keepUnresolved) throw new Error(`Listen host did not resolve: ${host}`);
+      if (!resolved.includes(host)) resolved.push(host);
+      continue;
     }
     if (addresses.some(({ address: address2 }) => isWildcardHost(address2))) {
       throw new Error(`Listen host resolves to an all-interfaces address: ${host}`);
@@ -4482,6 +4495,17 @@ function stateDir() {
 function stateFile() {
   return path2.join(stateDir(), "state.json");
 }
+function stateId(file = stateFile()) {
+  const directory = path2.dirname(path2.resolve(file));
+  let canonicalDirectory;
+  try {
+    canonicalDirectory = realpathSync(directory);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    canonicalDirectory = directory;
+  }
+  return createHash("sha256").update(path2.join(canonicalDirectory, path2.basename(file))).digest("hex").slice(0, 16);
+}
 function serverLogFile() {
   return path2.join(stateDir(), "server.log");
 }
@@ -4492,6 +4516,29 @@ function defaultPort() {
   return Number(process.env.LAVISH_AXI_PORT || 4387);
 }
 
+// src/local-address.js
+function localInterfaceAddresses(interfaces = safeNetworkInterfaces()) {
+  const addresses = [];
+  for (const entries of Object.values(interfaces || {})) {
+    for (const entry of entries || []) {
+      const address = typeof entry?.address === "string" ? entry.address : "";
+      if (!address || isWildcardHost(address)) continue;
+      const family = entry.family === 4 ? "IPv4" : entry.family === 6 ? "IPv6" : entry.family;
+      if (family !== "IPv4" && family !== "IPv6") continue;
+      if (family === "IPv6" && /^fe[89ab]/i.test(address)) continue;
+      if (!addresses.includes(address)) addresses.push(address);
+    }
+  }
+  return addresses;
+}
+function safeNetworkInterfaces() {
+  try {
+    return os2.networkInterfaces();
+  } catch {
+    return {};
+  }
+}
+
 // src/plugin.js
 import { randomUUID } from "node:crypto";
 import {
@@ -4508,7 +4555,7 @@ import {
   writeFileSync
 } from "node:fs";
 import { createRequire } from "node:module";
-import os2 from "node:os";
+import os3 from "node:os";
 import path3 from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 var crossSpawn = createRequire(import.meta.url)("cross-spawn");
@@ -4549,7 +4596,7 @@ function computeVsCodePluginLocationsUpdate(settings, pluginRoot, pluginName) {
   updated["chat.pluginLocations"] = locations;
   return [updated, changed];
 }
-function resolveVsCodeSettingsFile(env = process.env, homeDir = os2.homedir(), platform = process.platform) {
+function resolveVsCodeSettingsFile(env = process.env, homeDir = os3.homedir(), platform = process.platform) {
   const platformPath = platform === "win32" ? path3.win32 : path3.posix;
   if (platform === "win32") {
     return platformPath.join(
@@ -4569,7 +4616,7 @@ function resolveVsCodeSettingsFile(env = process.env, homeDir = os2.homedir(), p
     "settings.json"
   );
 }
-function resolveCursorLocalPluginsDir(homeDir = os2.homedir()) {
+function resolveCursorLocalPluginsDir(homeDir = os3.homedir()) {
   return path3.join(homeDir, ".cursor", "plugins", "local");
 }
 function writeTextFileAtomically(file, content, operations = {}) {
@@ -4704,7 +4751,7 @@ import crypto6 from "node:crypto";
 import { EventEmitter } from "node:events";
 import { existsSync as existsSync2 } from "node:fs";
 import { readFile as readFile5, realpath as realpath3 } from "node:fs/promises";
-import { createServer } from "node:http";
+import { createServer, get as httpGet } from "node:http";
 import { isIP as isIP3 } from "node:net";
 import { homedir } from "node:os";
 import path7 from "node:path";
@@ -8126,22 +8173,6 @@ function serializeChatSync(session) {
   };
 }
 
-// src/local-address.js
-import os3 from "node:os";
-function isLocalAddressPresent(host) {
-  if (typeof host !== "string" || host === "") return false;
-  try {
-    for (const entries of Object.values(os3.networkInterfaces() || {})) {
-      for (const entry of entries || []) {
-        if (entry?.address === host) return true;
-      }
-    }
-  } catch {
-    return false;
-  }
-  return false;
-}
-
 // src/server-log.js
 function formatServerLogLine(line, now = /* @__PURE__ */ new Date()) {
   return `${now.toISOString()} ${line}`;
@@ -8298,6 +8329,21 @@ var SessionStore = class {
     this.artifactLoads = /* @__PURE__ */ new Map();
     this.chromeLoadContexts = /* @__PURE__ */ new Map();
   }
+  // The one reader of the active load. It exists because the load outlives the process that
+  // issued it: an upgrade restart replaces the server under a reviewer who never asked for it,
+  // and a load this store merely forgot is not a load that ended. Whether a token is still
+  // current is decided by `beginArtifactLoad` alone - nothing else may retire one.
+  #activeArtifactLoad(session) {
+    const cached = this.artifactLoads.get(session.key);
+    if (cached) return cached;
+    const restored = restoreArtifactLoad(session.artifact_load);
+    if (!restored) return void 0;
+    this.artifactLoads.set(session.key, restored);
+    if (!this.chromeLoadContexts.has(session.key)) {
+      this.chromeLoadContexts.set(session.key, restored.handoffToken);
+    }
+    return restored;
+  }
   async listSessions() {
     return this.runExclusive(async () => {
       const state = await this.readState();
@@ -8338,6 +8384,9 @@ var SessionStore = class {
       // must never silently drop unresolved warnings the user has not triaged yet.
       layout_warnings: normalizeStoredWarnings(existing.layout_warnings),
       artifact_revision: normalizeRevision(existing.artifact_revision),
+      // The reviewer's open tab is holding this token, so reopening the artifact must not retire
+      // it: only a newer `beginArtifactLoad` retires a load.
+      artifact_load: normalizeStoredArtifactLoad(existing.artifact_load),
       artifact_failures: Array.isArray(existing.artifact_failures) ? existing.artifact_failures : [],
       // Carried across a reopen on purpose: this list is what keeps a just-delivered
       // attachment out of the sweeper's reach, and re-opening the artifact during the
@@ -8492,7 +8541,7 @@ var SessionStore = class {
       }
       const chromeLoadToken = crypto4.randomBytes(24).toString("base64url");
       this.chromeLoadContexts.set(key, chromeLoadToken);
-      const activeLoad = this.artifactLoads.get(key);
+      const activeLoad = this.#activeArtifactLoad(session);
       return {
         session,
         chrome_load_token: chromeLoadToken,
@@ -8514,8 +8563,8 @@ var SessionStore = class {
       const parsedRequestSequence = Number(requestSequence);
       const normalizedRequestSequence = Number.isSafeInteger(parsedRequestSequence) && parsedRequestSequence > 0 ? parsedRequestSequence : 0;
       const normalizedHandoffToken = String(handoffToken || "");
+      const activeLoad = this.#activeArtifactLoad(session);
       const activeHandoffToken = this.chromeLoadContexts.get(key) || "";
-      const activeLoad = this.artifactLoads.get(key);
       const staleResult = (status) => ({
         session,
         stale: status,
@@ -8540,14 +8589,16 @@ var SessionStore = class {
       }
       const artifactRevision = normalizeRevision(session.artifact_revision) + 1;
       const artifactLoadToken = crypto4.randomBytes(24).toString("base64url");
-      this.artifactLoads.set(key, {
+      const load = {
         artifactRevision,
         artifactLoadToken,
         lastPassSequence: 0,
         requestId: normalizedRequestId,
         requestSequence: normalizedRequestSequence,
         handoffToken: normalizedHandoffToken
-      });
+      };
+      this.artifactLoads.set(key, load);
+      session.artifact_load = serializeArtifactLoad(load);
       session.artifact_revision = artifactRevision;
       session.updated_at = (/* @__PURE__ */ new Date()).toISOString();
       await this.writeState(state);
@@ -8561,7 +8612,7 @@ var SessionStore = class {
       if (!session) {
         return null;
       }
-      const load = this.artifactLoads.get(key);
+      const load = this.#activeArtifactLoad(session);
       const revision = parseRevisionValue(artifactRevision);
       const valid = Boolean(
         load && String(artifactLoadToken || "") && String(artifactLoadToken) === load.artifactLoadToken && revision === load.artifactRevision
@@ -8588,7 +8639,7 @@ var SessionStore = class {
         return null;
       }
       const revision = normalizeRevision(session.artifact_revision);
-      const load = this.artifactLoads.get(key);
+      const load = this.#activeArtifactLoad(session);
       const artifactLoadToken = String(payload?.artifact_load_token || payload?.artifactLoadToken || "");
       const reportedRevision = parseDiagnosticRevision(payload);
       const passSequence = parsePassSequence(payload);
@@ -8621,6 +8672,7 @@ var SessionStore = class {
         return { session, changed: false, warnings: serializeLayoutWarnings(warnings) };
       }
       session.layout_warnings = warnings;
+      session.artifact_load = serializeArtifactLoad(load);
       session.updated_at = at;
       await this.writeState(state);
       return { session, changed: true, warnings: serializeLayoutWarnings(warnings) };
@@ -8677,7 +8729,7 @@ var SessionStore = class {
       if (!session) {
         return null;
       }
-      const load = this.artifactLoads.get(key);
+      const load = this.#activeArtifactLoad(session);
       const artifactLoadToken = String(payload?.artifact_load_token || payload?.artifactLoadToken || "");
       const reportedRevision = parseDiagnosticRevision(payload);
       if (!load || artifactLoadToken !== load.artifactLoadToken || !reportedRevision.present || reportedRevision.value !== load.artifactRevision) {
@@ -8991,6 +9043,47 @@ function planLayoutWarningPrompt(warnings, prompt, revision) {
   }
   return { warningIds, expectedRevision, conflicts, queueIds, hadKnownWarning };
 }
+function serializeArtifactLoad(load) {
+  return {
+    artifact_load_token: load.artifactLoadToken,
+    artifact_revision: load.artifactRevision,
+    last_pass_sequence: load.lastPassSequence,
+    request_id: load.requestId,
+    request_sequence: load.requestSequence,
+    handoff_token: load.handoffToken
+  };
+}
+var STORED_ARTIFACT_LOAD_FIELDS = [
+  "artifact_load_token",
+  "artifact_revision",
+  "last_pass_sequence",
+  "request_id",
+  "request_sequence",
+  "handoff_token"
+];
+function restoreArtifactLoad(stored) {
+  if (!stored || typeof stored !== "object" || Array.isArray(stored)) return null;
+  if (STORED_ARTIFACT_LOAD_FIELDS.some((field) => !Object.hasOwn(stored, field))) return null;
+  const artifactLoadToken = stored.artifact_load_token;
+  const handoffToken = stored.handoff_token;
+  const requestId = stored.request_id;
+  if (typeof artifactLoadToken !== "string" || !artifactLoadToken) return null;
+  if (typeof handoffToken !== "string" || !handoffToken) return null;
+  if (typeof requestId !== "string") return null;
+  const artifactRevision = parseSequenceValue(stored.artifact_revision);
+  if (artifactRevision === 0) return null;
+  const lastPassSequence = parseSequenceValue(stored.last_pass_sequence);
+  const requestSequence = parseSequenceValue(stored.request_sequence);
+  if (artifactRevision === null || lastPassSequence === null || requestSequence === null) return null;
+  return { artifactRevision, artifactLoadToken, lastPassSequence, requestId, requestSequence, handoffToken };
+}
+function normalizeStoredArtifactLoad(stored) {
+  const restored = restoreArtifactLoad(stored);
+  return restored ? serializeArtifactLoad(restored) : null;
+}
+function parseSequenceValue(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
 function normalizeRevision(value) {
   const number = Number(value);
   return Number.isFinite(number) && number > 0 ? Math.trunc(number) : 0;
@@ -9584,6 +9677,8 @@ var DEFAULT_IDLE_TIMEOUT_MS = 30 * 6e4;
 var WHITEBOARD_CHANNEL_TOKEN_TTL_MS = 5 * 6e4;
 var NETWORK_RECONCILE_CACHE_MS = 1e3;
 var BIND_RETRY_DELAYS_MS = [100, 250, 500];
+var BIND_RECOVERY_DELAYS_MS = [1e3, 2e3, 5e3, 1e4, 3e4];
+var LOOPBACK_OWNER_PROBE_TIMEOUT_MS = 500;
 var WEBSOCKET_CLOSE_GRACE_MS = 250;
 var LIVE_EVENT_HEARTBEAT_MS = 3e4;
 var BROWSER_DISCONNECT_GRACE_MS = 1e4;
@@ -9694,6 +9789,8 @@ async function serve({
   allowedHosts,
   detectTailscale: detectTailscaleFn,
   lookupHost,
+  extraListenHosts = [],
+  bindRecoveryDelaysMs = BIND_RECOVERY_DELAYS_MS,
   whiteboardAssetsDir = defaultWhiteboardAssetsDir()
 } = {}) {
   const { WebSocket, WebSocketServer } = await import("ws");
@@ -9703,16 +9800,22 @@ async function serve({
   const detect = detectTailscaleFn === void 0 ? detectTailscale : detectTailscaleFn;
   const tailscale = !hosts?.length && autoTailscale && typeof detect === "function" ? await detect() : null;
   const requestedListenHosts = sanitizeListenHosts(
-    hosts?.length ? hosts : resolveListenHosts({ host, env, tailscale })
+    hosts?.length ? [...hosts, ...extraListenHosts] : resolveListenHosts({ host, env, tailscale, extraHosts: extraListenHosts })
   );
+  const lookupOptions = lookupHost ? { lookup: lookupHost } : {};
   const listenHosts = await resolveConcreteListenHosts(requestedListenHosts, {
-    ...lookupHost ? { lookup: lookupHost } : {}
+    ...lookupOptions,
+    keepUnresolved: true
   });
   const activeTailscaleNetwork = tailscaleNetworkKey(tailscale);
+  const serverStateId = stateId(stateFile2);
   let tailscalePhoneReady = false;
-  const absentRequestedHosts = [];
-  let networkWarning = typeof tailscale?.warning === "string" ? tailscale.warning : "";
+  let tailscaleDetectionWarning = typeof tailscale?.warning === "string" ? tailscale.warning : "";
+  const pendingBinds = /* @__PURE__ */ new Map();
   let resolvedLinkHost = linkHostName ?? resolveLinkHost({ env, tailscale, fallbackHost: host });
+  let idleTimer = null;
+  let attachmentSweepTimer = null;
+  let bindRecoveryTimer = null;
   const app = express();
   const store = new SessionStore(stateFile2);
   const events = new EventEmitter();
@@ -9730,7 +9833,7 @@ async function serve({
   const writeLog = typeof log === "function" ? log : (line) => process.stderr.write(`${serverStdioIsTimestamped() ? line : formatServerLogLine(line)}
 `);
   const logEvent = verbose ? (line) => writeLog(`[lavish] ${line}`) : null;
-  if (networkWarning) writeLog(`[lavish] WARNING: ${networkWarning}`);
+  if (tailscaleDetectionWarning) writeLog(`[lavish] WARNING: ${tailscaleDetectionWarning}`);
   let publicPort = port;
   let serverReady = false;
   let networkReconcileCheckedAt = 0;
@@ -9803,11 +9906,29 @@ async function serve({
     client.sendEvent("agent-presence", presenceEventData(key, presence, activePolls, deliveredFeedback));
     if (session?.status === "ended") client.sendEvent("ended", { ended_by: session.ended_by || null });
   }
-  function requestedBindIsRecoverable() {
-    return absentRequestedHosts.some((listenHost) => isLocalAddressPresent(listenHost));
+  function networkWarningField() {
+    const networkWarning = currentNetworkWarning();
+    return networkWarning ? { network_warning: networkWarning } : {};
+  }
+  function describeBindFailure(listenHost, error) {
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
+    const why = code === "EADDRINUSE" ? "EADDRINUSE: another process is already listening there" : code === "EADDRNOTAVAIL" ? "EADDRNOTAVAIL: that address is not on this machine right now" : code === "ENOTFOUND" || code === "EAI_AGAIN" ? `${code}: that name does not resolve right now` : code || (error instanceof Error ? error.message : String(error));
+    const address = `${hostForUrl(listenHost)}:${publicPort || port}`;
+    const reachable = `Lavish remains available on ${boundHosts.map((bound2) => hostForUrl(bound2)).join(", ") || "loopback"}`;
+    if (listenHost === tailscale?.ipv4) {
+      return `Tailscale binding failed for ${address} (${why}); there is no phone access and tailnet review links do not load. ${reachable} and keeps retrying the tailnet address in the background.`;
+    }
+    const fellBack = boundHosts.length > 0 && boundHosts.every((bound2) => bound2 === LOOPBACK_HOST);
+    return `Could not bind ${address} (${why}); ${fellBack ? "Lavish fell back to loopback and is" : "Lavish is"} not reachable at that address. ${reachable} and keeps retrying ${hostForUrl(listenHost)} in the background.`;
+  }
+  function currentNetworkWarning() {
+    return [
+      tailscaleDetectionWarning,
+      ...[...pendingBinds].map(([listenHost, error]) => describeBindFailure(listenHost, error))
+    ].filter(Boolean).join(" ");
   }
   async function reconcileNetwork() {
-    if (requestedBindIsRecoverable()) return true;
+    await retryPendingBinds();
     if (!(autoTailscale && typeof detect === "function")) return false;
     return reconcileTailscaleNetwork();
   }
@@ -9819,7 +9940,9 @@ async function serve({
         const detectedTailscale = await detect();
         const detectedNetwork = tailscaleNetworkKey(detectedTailscale);
         const stale = detectedNetwork !== activeTailscaleNetwork;
-        if (stale) networkWarning = typeof detectedTailscale?.warning === "string" ? detectedTailscale.warning : "";
+        if (stale) {
+          tailscaleDetectionWarning = typeof detectedTailscale?.warning === "string" ? detectedTailscale.warning : "";
+        }
         return stale;
       } catch {
         return false;
@@ -9957,10 +10080,20 @@ async function serve({
       return;
     }
     const networkStale = req.query.reconcile_network === "1" ? await reconcileNetwork() : false;
+    const networkWarning = currentNetworkWarning();
     res.json({
       ok: true,
       app: "lavish-axi",
       version,
+      state_id: serverStateId,
+      state_dir: path7.dirname(stateFile2),
+      // Where this process is listening and every address it was asked to serve (bound or still
+      // retrying). The CLI uses both to find one daemon per port whatever host it was configured
+      // with, and to tell a same-port daemon at another address apart from this one.
+      hosts: [...boundHosts],
+      // Configured names sit beside the addresses they resolved to, so a CLI that resolves the same
+      // name finds it served whichever form it compares.
+      requested_hosts: [.../* @__PURE__ */ new Set([...listenHosts, ...requestedListenHosts])],
       ...networkStale ? { network_stale: true } : {},
       ...networkWarning ? { network_warning: networkWarning } : {},
       listeners: [...activePolls].map(([key, holder]) => ({
@@ -9993,7 +10126,7 @@ async function serve({
           file,
           url: sessionUrl,
           status: "user-ended",
-          ...networkWarning ? { network_warning: networkWarning } : {}
+          ...networkWarningField()
         });
         return;
       }
@@ -10010,7 +10143,7 @@ async function serve({
         file,
         url,
         status: "opened",
-        ...networkWarning ? { network_warning: networkWarning } : {}
+        ...networkWarningField()
       });
     } catch (error) {
       next(error);
@@ -10998,20 +11131,37 @@ ${body}`
   const boundHosts = [];
   let boundPort = port;
   let lastBindError = null;
+  async function listenOnce(listenHost) {
+    const address = isIP3(listenHost) ? listenHost : (await resolveConcreteListenHosts([listenHost], lookupOptions))[0];
+    if (address !== listenHost) {
+      if (!listenHosts.includes(address)) listenHosts.push(address);
+      if (boundHosts.includes(address)) {
+        boundHosts.push(listenHost);
+        return;
+      }
+    }
+    const httpServer = await listenHttp(app, boundPort, address, (error) => {
+      writeLog(`[lavish] HTTP server error: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    if (shuttingDown) {
+      httpServer.close();
+      throw new Error("Lavish server is shutting down");
+    }
+    httpServer.on("upgrade", handleEventUpgrade);
+    if (boundPort === 0) boundPort = httpServer.address().port;
+    if (!publicPort) publicPort = boundPort;
+    httpServers.push(httpServer);
+    boundHosts.push(listenHost);
+    if (address !== listenHost) boundHosts.push(address);
+  }
   async function bindListener(listenHost) {
     let retryIndex = 0;
     while (true) {
       try {
-        const httpServer = await listenHttp(app, boundPort, listenHost, (error) => {
-          writeLog(`[lavish] HTTP server error: ${error instanceof Error ? error.message : String(error)}`);
-        });
-        httpServer.on("upgrade", handleEventUpgrade);
-        if (boundPort === 0) boundPort = httpServer.address().port;
-        httpServers.push(httpServer);
-        boundHosts.push(listenHost);
+        await listenOnce(listenHost);
         return null;
       } catch (error) {
-        if (retryIndex < BIND_RETRY_DELAYS_MS.length) {
+        if (!shuttingDown && retryIndex < BIND_RETRY_DELAYS_MS.length) {
           await new Promise((resolve) => setTimeout(resolve, BIND_RETRY_DELAYS_MS[retryIndex]));
           retryIndex += 1;
           continue;
@@ -11020,28 +11170,80 @@ ${body}`
       }
     }
   }
-  for (const listenHost of listenHosts) {
+  function applyNetworkState() {
+    tailscalePhoneReady = Boolean(tailscale?.ipv4 && boundHosts.includes(tailscale.ipv4));
+    if (linkHostName != null) {
+      resolvedLinkHost = linkHostName;
+    } else if (tailscalePhoneReady) {
+      resolvedLinkHost = resolveLinkHost({ env, tailscale, fallbackHost: host });
+    } else if (boundHosts.includes(listenHosts[0])) {
+      resolvedLinkHost = resolveLinkHost({ env, tailscale: null, fallbackHost: host });
+    } else {
+      resolvedLinkHost = resolveLinkHost({ env, tailscale: null, fallbackHost: LOOPBACK_HOST });
+    }
+    const servesHost = (candidate) => candidate !== tailscale?.ipv4 || tailscalePhoneReady;
+    const nextAllowedHostnames = buildAllowedHostnames({
+      host: requestedListenHosts[0],
+      hosts: [...requestedListenHosts.filter(servesHost), ...listenHosts.filter(servesHost), ...boundHosts],
+      linkHost: resolvedLinkHost,
+      allowedHosts: extraHosts
+    });
+    allowedHostnames.clear();
+    for (const allowedHostname of nextAllowedHostnames) allowedHostnames.add(allowedHostname);
+  }
+  let bindRecoveryInFlight = null;
+  async function retryPendingBinds() {
+    if (pendingBinds.size === 0 || shuttingDown) return;
+    if (!bindRecoveryInFlight) {
+      bindRecoveryInFlight = (async () => {
+        let bound2 = false;
+        for (const listenHost of [...pendingBinds.keys()]) {
+          if (shuttingDown) return;
+          try {
+            await listenOnce(listenHost);
+            pendingBinds.delete(listenHost);
+            bound2 = true;
+            writeLog(`[lavish] now listening on ${hostForUrl(listenHost)}:${boundPort} after an earlier bind failure.`);
+          } catch (error) {
+            if (!shuttingDown) pendingBinds.set(listenHost, error instanceof Error ? error : new Error(String(error)));
+          }
+        }
+        if (bound2) applyNetworkState();
+      })().finally(() => {
+        bindRecoveryInFlight = null;
+      });
+    }
+    await bindRecoveryInFlight;
+  }
+  let bindRecoveryAttempt = 0;
+  function scheduleBindRecovery() {
+    if (shuttingDown || pendingBinds.size === 0 || bindRecoveryTimer || !bindRecoveryDelaysMs.length) return;
+    const delay2 = bindRecoveryDelaysMs[Math.min(bindRecoveryAttempt, bindRecoveryDelaysMs.length - 1)];
+    bindRecoveryAttempt += 1;
+    bindRecoveryTimer = setTimeout(() => {
+      bindRecoveryTimer = null;
+      retryPendingBinds().catch(() => {
+      }).finally(() => scheduleBindRecovery());
+    }, delay2);
+    bindRecoveryTimer.unref?.();
+  }
+  const bindOrder = listenHosts.includes(LOOPBACK_HOST) ? [LOOPBACK_HOST, ...listenHosts.filter((listenHost) => listenHost !== LOOPBACK_HOST)] : listenHosts;
+  for (const listenHost of bindOrder) {
     const error = await bindListener(listenHost);
     if (!error) continue;
     lastBindError = error;
-    if (isAddressAbsentBindError(error)) absentRequestedHosts.push(listenHost);
-    if (listenHost === tailscale?.ipv4) {
-      networkWarning = "Tailscale binding failed; there is no phone access. Lavish remains available on loopback.";
-      writeLog(`[lavish] WARNING: ${networkWarning} Address: ${listenHost}:${boundPort}.`);
-    } else {
-      logEvent?.(`failed to bind ${listenHost}:${boundPort}: ${error.message}`);
+    if (listenHost === LOOPBACK_HOST && isAddressInUseBindError(error)) {
+      const owner = await probeLavishHealth(LOOPBACK_HOST, boundPort);
+      throw new Error(
+        owner ? `Another Lavish server (version ${owner.version || "unknown"}) already owns port ${boundPort} on ${LOOPBACK_HOST}; not starting a second one.` : `Loopback ${LOOPBACK_HOST}:${boundPort} is already in use; not starting a Lavish server on another address.`,
+        { cause: error }
+      );
     }
+    pendingBinds.set(listenHost, error);
   }
-  let loopbackFallback = false;
   if (httpServers.length === 0 && !listenHosts.includes(LOOPBACK_HOST)) {
     const error = await bindListener(LOOPBACK_HOST);
-    if (error) {
-      lastBindError = error;
-    } else {
-      loopbackFallback = true;
-      networkWarning = `Could not bind ${listenHosts.join(", ")}; Lavish fell back to loopback and is not reachable at that address.`;
-      writeLog(`[lavish] WARNING: ${networkWarning} Address: ${listenHosts[0]}:${boundPort}.`);
-    }
+    if (error) lastBindError = error;
   }
   if (httpServers.length === 0) {
     throw new Error(
@@ -11064,23 +11266,13 @@ ${body}`
     boundHosts.length = 0;
     throw error;
   }
-  if (loopbackFallback) {
-    resolvedLinkHost = linkHostName ?? resolveLinkHost({ env, tailscale: null, fallbackHost: LOOPBACK_HOST });
-  }
-  tailscalePhoneReady = Boolean(tailscale?.ipv4 && boundHosts.includes(tailscale.ipv4));
-  if (tailscale?.ipv4 && !tailscalePhoneReady) {
-    resolvedLinkHost = linkHostName ?? resolveLinkHost({ env, tailscale: null, fallbackHost: host });
-    const fallbackAllowedHostnames = buildAllowedHostnames({
-      host: requestedListenHosts[0],
-      hosts: [...requestedListenHosts.filter((requestedHost) => requestedHost !== tailscale.ipv4), ...boundHosts],
-      linkHost: resolvedLinkHost,
-      allowedHosts: extraHosts
-    });
-    allowedHostnames.clear();
-    for (const allowedHostname of fallbackAllowedHostnames) allowedHostnames.add(allowedHostname);
-  }
+  applyNetworkState();
   publicPort = httpServers[0].address().port;
+  for (const [listenHost, error] of pendingBinds) {
+    writeLog(`[lavish] WARNING: ${describeBindFailure(listenHost, error)}`);
+  }
   serverReady = true;
+  scheduleBindRecovery();
   function shutdown(reloadKey = "", reason = "", cause = "requested") {
     if (shuttingDown) return;
     shuttingDown = true;
@@ -11093,6 +11285,10 @@ ${body}`
       clearInterval(attachmentSweepTimer);
       attachmentSweepTimer = null;
     }
+    if (bindRecoveryTimer) {
+      clearTimeout(bindRecoveryTimer);
+      bindRecoveryTimer = null;
+    }
     const shutdownData = { reason };
     for (const [client, clientKey] of liveEventClients) {
       try {
@@ -11125,7 +11321,6 @@ ${body}`
       }
     }
   }
-  let idleTimer = null;
   function refreshIdleTimer() {
     if (idleTimer) {
       clearTimeout(idleTimer);
@@ -11165,7 +11360,6 @@ ${body}`
     return outstandingRepairBatches.has(key) ? BATCH_RELOAD_DEBOUNCE_MS : RELOAD_DEBOUNCE_MS;
   }
   const attachmentSweepEnabled = attachmentConfig.ttlMs != null || attachmentConfig.maxDiskBytes != null;
-  let attachmentSweepTimer = null;
   async function sweepAttachmentsNow() {
     try {
       const result = await store.runExclusive(async () => {
@@ -11238,8 +11432,36 @@ function tailscaleNetworkKey(tailscale) {
 ${tailscale.ipv4}
 ${tailscale.magicDnsName}`;
 }
-function isAddressAbsentBindError(error) {
-  return error instanceof Error && "code" in error && error.code === "EADDRNOTAVAIL";
+function isAddressInUseBindError(error) {
+  return error instanceof Error && "code" in error && error.code === "EADDRINUSE";
+}
+function probeLavishHealth(host, port) {
+  return new Promise((resolve) => {
+    const request = httpGet({ host, port, path: "/health", agent: false }, (response) => {
+      let body = "";
+      response.setEncoding("utf8");
+      response.on("data", (chunk) => {
+        body += chunk;
+        if (body.length > 64 * 1024) request.destroy();
+      });
+      response.on("end", () => {
+        request.destroy();
+        try {
+          const parsed = JSON.parse(body);
+          resolve(parsed && typeof parsed === "object" && parsed.app === "lavish-axi" ? parsed : null);
+        } catch {
+          resolve(null);
+        }
+      });
+      response.on("error", () => resolve(null));
+    });
+    request.setTimeout(LOOPBACK_OWNER_PROBE_TIMEOUT_MS, () => {
+      request.destroy();
+      resolve(null);
+    });
+    request.on("error", () => resolve(null));
+    request.on("close", () => resolve(null));
+  });
 }
 function wantsHtml(req) {
   const accept = String(req.get("accept") || "");
@@ -11995,7 +12217,7 @@ var AGENT_REPLY_INPUT_LIMIT_BYTES = AGENT_REPLY_JSON_LIMIT_BYTES - AGENT_REPLY_J
 var AGENT_REPLY_LIMIT_LABEL = "2 MB JSON request limit";
 var POLL_STATE_HEADER = "lavish-poll-state";
 var CODEX_POLL_WAKE_PATH_GUIDANCE = "Codex detected: completed background tasks may not resume Codex automatically, so keep the poll attached to the active turn.";
-var VERSION = "0.1.76";
+var VERSION = "0.1.78";
 function detectInvokingAgent(env = process.env) {
   return ["CODEX_SANDBOX", "CODEX_THREAD_ID"].some((key) => Object.hasOwn(env, key)) ? "codex" : "generic";
 }
@@ -12191,11 +12413,12 @@ function createOpenOutput({
   networkWarning = void 0
 }) {
   const selfPaintPrefix = selfPaintWarning ? `First fix the unpainted page surface flagged in self_paint_warning and save - Lavish live-reloads the artifact automatically, so you do not need to re-run \`lavish-axi ${file}\`. ` : "";
+  const networkPrefix = networkWarning ? "Lavish could not serve every address it was asked to (see network_warning): when you next message the user, tell them, because review links at that address will not load until it clears. " : "";
   return {
     session: { file, url, status },
     ...networkWarning ? { network_warning: networkWarning } : {},
     ...selfPaintWarning ? { self_paint_warning: selfPaintWarning } : {},
-    next_step: `${selfPaintPrefix}Do not respond to the user just yet. Now you must run \`lavish-axi poll ${file}\`. This command long-polls until the user sends feedback, ends the session, or leaves every review window disconnected past the reconnect grace period, and it stays silent the whole time - that is normal, never kill it. Layout issues the browser detects do not return this poll; they wait in the user's Layout issues inbox until the user queues them, then arrive as an ordinary tag "layout-warnings" prompt. Do not pass --timeout-ms during normal agent use. ${pollExecutionGuidance({ agent })} After applying feedback, run \`lavish-axi poll ${file} --agent-reply "<message for the user>"\` without --timeout-ms to show a concise response in Lavish Editor and wait for more feedback. ${POLL_AGENT_REPLY_RULE} ${POLL_AGENT_REPLY_NEXT_POINTER} If the user ends the session, stop polling and do not reopen it by re-running \`lavish-axi ${file}\` unless the user asks for further review or something genuinely important needs their visual attention - deliver routine updates directly in this conversation instead. When reopening is warranted, run \`lavish-axi ${file} --reopen\`.`
+    next_step: `${networkPrefix}${selfPaintPrefix}Do not respond to the user just yet. Now you must run \`lavish-axi poll ${file}\`. This command long-polls until the user sends feedback, ends the session, or leaves every review window disconnected past the reconnect grace period, and it stays silent the whole time - that is normal, never kill it. Layout issues the browser detects do not return this poll; they wait in the user's Layout issues inbox until the user queues them, then arrive as an ordinary tag "layout-warnings" prompt. Do not pass --timeout-ms during normal agent use. ${pollExecutionGuidance({ agent })} After applying feedback, run \`lavish-axi poll ${file} --agent-reply "<message for the user>"\` without --timeout-ms to show a concise response in Lavish Editor and wait for more feedback. ${POLL_AGENT_REPLY_RULE} ${POLL_AGENT_REPLY_NEXT_POINTER} If the user ends the session, stop polling and do not reopen it by re-running \`lavish-axi ${file}\` unless the user asks for further review or something genuinely important needs their visual attention - deliver routine updates directly in this conversation instead. When reopening is warranted, run \`lavish-axi ${file} --reopen\`.`
   };
 }
 function createUserEndedOpenOutput({ file, url, networkWarning = void 0 }) {
@@ -12843,7 +13066,9 @@ function generatedPasswordNote(password) {
 }
 async function stopCommand(args) {
   const port = Number(flagValue(args, "--port") || defaultPort());
-  const { baseUrl } = await findRunningServer(port);
+  const { baseUrl, duplicates, foreign } = await findRunningServer(port);
+  if (foreign) throw otherInstallationError(port, foreign);
+  await stopDuplicateServers(duplicates, { reason: "stop" });
   return shutdownServerOnPort(port, { baseUrl, currentVersion: VERSION });
 }
 async function shutdownServerOnPort(port, {
@@ -12852,20 +13077,20 @@ async function shutdownServerOnPort(port, {
   fetchHealth: healthFetcher = fetchHealth,
   requestShutdown: shutdownRequester = requestShutdown,
   waitForPortFree: portFreeWaiter = waitForPortFree,
-  killProcessOnPort: portKiller = killProcessOnPort,
-  processMatchesLavish = processOnPortMatchesLavish
+  killServerProcess = killLavishListener,
+  processMatchesLavish = listenerMatchesLavish
 } = {}) {
   const health = await healthFetcher(baseUrl);
   if (!health) {
     return { server: { status: "not-running", port } };
   }
-  if (!await canControlServerOnPort(port, health, processMatchesLavish)) {
+  if (!await canControlServerOnPort(baseUrl, health, processMatchesLavish)) {
     return { server: { status: "not-lavish", port } };
   }
   await shutdownRequester(baseUrl, { reason: "stop" });
   let freed = await portFreeWaiter(baseUrl, 3e3);
   if (!freed && shouldKillProcessOnPort(currentVersion, health)) {
-    portKiller(port);
+    if (!killServerProcess(baseUrl)) throw unidentifiedListenerError(baseUrl);
     freed = await portFreeWaiter(baseUrl, 3e3);
   }
   return { server: { status: freed ? "stopped" : "stopping", port } };
@@ -12956,7 +13181,7 @@ function registerVsCodePlugin(pluginRoot, pluginName) {
   const [updated, changed] = computeVsCodePluginLocationsUpdate(settings, pluginRoot, pluginName);
   if (!changed) return { client: "vscode", status: "current", detail: collapseHome(settingsFile) };
   try {
-    const writeTarget = hasSettingsFile ? realpathSync(settingsFile) : settingsFile;
+    const writeTarget = hasSettingsFile ? realpathSync2(settingsFile) : settingsFile;
     writeTextFileAtomically(writeTarget, `${JSON.stringify(updated, null, 2)}
 `);
   } catch (error) {
@@ -13071,7 +13296,7 @@ function copilotPluginSourcePath(record) {
 }
 function sameResolvedPath(left, right) {
   try {
-    return realpathSync(left) === realpathSync(right);
+    return realpathSync2(left) === realpathSync2(right);
   } catch {
     return path8.resolve(left) === path8.resolve(right);
   }
@@ -13163,7 +13388,13 @@ function deepEqual(a, b) {
 async function serverCommand(args) {
   const port = Number(flagValue(args, "--port") || defaultPort());
   const debug = args.includes("--verbose") || process.env.LAVISH_AXI_DEBUG === "1";
-  const server = await serve({ port, stateFile: stateFile(), version: VERSION, debug });
+  const server = await serve({
+    port,
+    stateFile: stateFile(),
+    version: VERSION,
+    debug,
+    extraListenHosts: flagValues(args, "--also-listen")
+  });
   await server.done;
   return "";
 }
@@ -13191,82 +13422,201 @@ async function assertHtmlFile(file) {
 function isHtmlPath(file) {
   return file.toLowerCase().endsWith(".html") || file.toLowerCase().endsWith(".htm");
 }
-function serverBaseUrls(port) {
-  const urls = [`http://${hostForUrl(clientHost())}:${port}`];
-  const loopback = `http://${hostForUrl(LOOPBACK_HOST)}:${port}`;
-  if (!urls.includes(loopback)) urls.push(loopback);
-  return urls;
-}
 var HEALTH_PROBE_TIMEOUT_MS = 500;
+var DEFAULT_HEALTH_TIMEOUT_MS = 2e3;
+var MAX_HEALTH_BODY_BYTES = 256 * 1024;
+var HEALTH_RECONCILE_TIMEOUT_MS = 3e3;
+function serverCandidateHosts() {
+  const hosts = [clientHost(), LOOPBACK_HOST];
+  for (const address of localInterfaceAddresses()) {
+    if (!hosts.includes(address)) hosts.push(address);
+  }
+  return hosts;
+}
+function serverBaseUrl(host, port) {
+  return `http://${hostForUrl(host)}:${port}`;
+}
+function isOwnedServer(entry, controlHosts) {
+  if (entry.health.app !== "lavish-axi") return false;
+  if (typeof entry.health.state_id === "string") return entry.health.state_id === stateId();
+  return controlHosts.has(entry.host);
+}
+function otherInstallationError(port, foreign) {
+  const dir = typeof foreign.health.state_dir === "string" ? foreign.health.state_dir : "an unknown state directory";
+  return new AxiError(
+    `Port ${port} is served by another Lavish installation at ${foreign.host} (state directory ${dir})`,
+    "SERVER_ERROR",
+    [`Set LAVISH_AXI_PORT to another port, or set LAVISH_AXI_STATE_DIR to ${dir} to use that installation`]
+  );
+}
 async function findRunningServer(port, { reconcileNetwork = false } = {}) {
-  const candidates = serverBaseUrls(port);
-  let foreign = null;
-  for (const baseUrl of candidates) {
-    const health = await probeHealth(baseUrl, { reconcileNetwork, timeoutMs: HEALTH_PROBE_TIMEOUT_MS });
-    if (!health) continue;
-    if (health.app === "lavish-axi") return { baseUrl, health };
-    if (!foreign) foreign = { baseUrl, health };
+  const controlHosts = /* @__PURE__ */ new Set([clientHost(), LOOPBACK_HOST]);
+  const probed = await Promise.all(
+    serverCandidateHosts().map(async (host) => {
+      const baseUrl = serverBaseUrl(host, port);
+      const health2 = await probeHealth(baseUrl, { reconcileNetwork: false, timeoutMs: HEALTH_PROBE_TIMEOUT_MS });
+      return health2 ? { host, baseUrl, health: health2 } : null;
+    })
+  );
+  const found = probed.filter((entry) => entry !== null);
+  const owned = found.filter((entry) => isOwnedServer(entry, controlHosts));
+  const foreign = found.find(
+    (entry) => controlHosts.has(entry.host) && entry.health.app === "lavish-axi" && !isOwnedServer(entry, controlHosts)
+  ) ?? null;
+  const chosen = owned[0];
+  if (!chosen) {
+    const other = found.find((entry) => controlHosts.has(entry.host));
+    return other ? { baseUrl: other.baseUrl, health: other.health, duplicates: [], foreign } : { baseUrl: serverBaseUrl(clientHost(), port), health: null, duplicates: [], foreign };
+  }
+  let health = chosen.health;
+  if (reconcileNetwork) {
+    health = await probeHealth(chosen.baseUrl, { reconcileNetwork: true, timeoutMs: HEALTH_RECONCILE_TIMEOUT_MS }) ?? health;
+  }
+  return { baseUrl: chosen.baseUrl, health, duplicates: ownedDuplicates(owned, chosen), foreign };
+}
+function ownedDuplicates(owned, chosen) {
+  const covered = /* @__PURE__ */ new Set([chosen.host, ...Array.isArray(chosen.health.hosts) ? chosen.health.hosts : []]);
+  const duplicates = [];
+  for (const entry of owned) {
+    if (entry === chosen || covered.has(entry.host)) continue;
+    duplicates.push(entry);
+    for (const host of Array.isArray(entry.health.hosts) ? entry.health.hosts : [entry.host]) covered.add(host);
+  }
+  return duplicates;
+}
+async function stopDuplicateServers(duplicates, { reloadKey = "", reason = "" } = {}) {
+  for (const duplicate of duplicates) {
+    await requestShutdown(duplicate.baseUrl, {
+      reloadKey,
+      reason: reason || serverReplacementReason(VERSION, duplicate.health)
+    });
+    await waitForPortFree(duplicate.baseUrl, 3e3);
   }
-  return foreign ?? { baseUrl: candidates[0], health: null };
+}
+async function adoptServer(baseUrl, duplicates, reloadKey) {
+  if (duplicates.length === 0) return baseUrl;
+  await stopDuplicateServers(duplicates, { reloadKey });
+  await probeHealth(baseUrl, { reconcileNetwork: true, timeoutMs: HEALTH_RECONCILE_TIMEOUT_MS });
+  return baseUrl;
+}
+async function requiredServerHosts(env = process.env) {
+  const envHost = env.LAVISH_AXI_HOST?.trim();
+  if (!envHost || isWildcardHost(envHost)) return [];
+  return resolveConcreteListenHosts([clientHost(env)], { keepUnresolved: true });
+}
+function missingServerHosts(healthBody, requiredHosts) {
+  if (!healthBody || !Array.isArray(healthBody.requested_hosts)) return [];
+  return requiredHosts.filter((host) => !healthBody.requested_hosts.includes(host));
+}
+function inheritedListenHosts(healthBodies, requiredHosts, inherited = [], localAddresses = localInterfaceAddresses()) {
+  const hosts = [...inherited];
+  for (const health of healthBodies) {
+    if (!health || !Array.isArray(health.requested_hosts)) continue;
+    for (const host of health.requested_hosts) {
+      if (host === LOOPBACK_HOST || requiredHosts.includes(host)) continue;
+      if (isIP4(host) && !localAddresses.includes(host)) continue;
+      if (!hosts.includes(host)) hosts.push(host);
+    }
+  }
+  return hosts;
+}
+function hostsToServe(requiredHosts, duplicates) {
+  return inheritedListenHosts(
+    duplicates.map((duplicate) => duplicate.health),
+    [],
+    requiredHosts
+  );
 }
 async function probeHealth(baseUrl, { reconcileNetwork, timeoutMs }) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const health = await Promise.race([
-      Promise.resolve().then(() => fetchHealth(baseUrl, { reconcileNetwork, timeoutMs, signal: controller.signal })).catch(() => null),
-      new Promise((resolve) => {
-        controller.signal.addEventListener("abort", () => resolve(null), { once: true });
-      })
-    ]);
-    return health && typeof health === "object" ? health : null;
-  } finally {
-    clearTimeout(timer);
-  }
+  const health = await fetchHealth(baseUrl, { reconcileNetwork, timeoutMs });
+  return health && typeof health === "object" ? health : null;
 }
 async function ensureServer({ forceRestart = false, reloadKey = "" } = {}) {
   const port = defaultPort();
-  const { baseUrl, health: existing } = await findRunningServer(port, { reconcileNetwork: true });
-  if (existing && !shouldRestartServer(VERSION, existing, forceRestart)) {
-    return baseUrl;
-  }
+  const requiredHosts = await requiredServerHosts();
+  const { baseUrl, health: existing, duplicates, foreign } = await findRunningServer(port, { reconcileNetwork: true });
+  if (foreign) throw otherInstallationError(port, foreign);
+  const missingHosts = existing?.app === "lavish-axi" ? missingServerHosts(existing, hostsToServe(requiredHosts, duplicates)) : [];
+  if (existing && !shouldRestartServer(VERSION, existing, forceRestart) && missingHosts.length === 0) {
+    return adoptServer(baseUrl, duplicates, reloadKey);
+  }
+  let alsoListen = inheritedListenHosts([existing, ...duplicates.map((duplicate) => duplicate.health)], requiredHosts);
+  let unidentified = "";
   if (existing) {
-    if (!await canControlServerOnPort(port, existing, processOnPortMatchesLavish)) {
+    if (!await canControlServerOnPort(baseUrl, existing, listenerMatchesLavish)) {
       throw new AxiError(`Port ${port} is occupied by a non-Lavish server`, "SERVER_ERROR", [
         `Stop the process using port ${port}, or set LAVISH_AXI_PORT to another port`
       ]);
     }
+    await stopDuplicateServers(duplicates, { reloadKey });
     await requestShutdown(baseUrl, { reloadKey, reason: serverReplacementReason(VERSION, existing, forceRestart) });
     const freed = await waitForPortFree(baseUrl, 2e3);
     if (!freed) {
       if (shouldKillProcessOnPort(VERSION, existing)) {
-        killProcessOnPort(port);
-        await waitForPortFree(baseUrl, 3e3);
+        if (killLavishListener(baseUrl)) await waitForPortFree(baseUrl, 3e3);
+        else unidentified = baseUrl;
       }
     }
   }
-  await startServer(port);
+  await startServer(port, { alsoListen });
   const replacedForNetwork = Boolean(existing) && existing.app === "lavish-axi" && existing.network_stale === true && !forceRestart && typeof existing.version === "string" && existing.version === VERSION;
   let networkRestarted = replacedForNetwork;
+  let raceRestarted = false;
   let deadline = Date.now() + 5e3;
   while (Date.now() < deadline) {
-    const { baseUrl: liveUrl, health } = await findRunningServer(port, { reconcileNetwork: true });
-    if (health && !shouldRestartServer(VERSION, health)) return liveUrl;
+    const {
+      baseUrl: liveUrl,
+      health,
+      duplicates: liveDuplicates,
+      foreign: liveForeign
+    } = await findRunningServer(port, { reconcileNetwork: true });
+    if (liveForeign) throw otherInstallationError(port, liveForeign);
+    const liveMissing = health?.app === "lavish-axi" ? missingServerHosts(health, hostsToServe(requiredHosts, liveDuplicates)) : [];
+    if (health && !shouldRestartServer(VERSION, health)) {
+      if (liveMissing.length === 0) return adoptServer(liveUrl, liveDuplicates, reloadKey);
+      if (raceRestarted) throw missingHostsError(port, liveMissing);
+    }
+    if (health?.app === "lavish-axi" && health.network_stale !== true && !raceRestarted) {
+      raceRestarted = true;
+      alsoListen = inheritedListenHosts(
+        [health, ...liveDuplicates.map((duplicate) => duplicate.health)],
+        requiredHosts,
+        alsoListen
+      );
+      await stopDuplicateServers(liveDuplicates, { reloadKey });
+      await requestShutdown(liveUrl, { reloadKey, reason: serverReplacementReason(VERSION, health) });
+      if (!await waitForPortFree(liveUrl, 3e3)) break;
+      await startServer(port, { alsoListen });
+      deadline = Date.now() + 5e3;
+      continue;
+    }
     if (health?.network_stale === true && health.app === "lavish-axi") {
-      if (networkRestarted) return liveUrl;
+      if (networkRestarted) {
+        if (liveMissing.length > 0) throw missingHostsError(port, liveMissing);
+        return adoptServer(liveUrl, liveDuplicates, reloadKey);
+      }
+      alsoListen = inheritedListenHosts([health], requiredHosts, alsoListen);
       await requestShutdown(liveUrl, { reloadKey, reason: "" });
       if (!await waitForPortFree(liveUrl, 3e3)) break;
-      await startServer(port);
+      await startServer(port, { alsoListen });
       networkRestarted = true;
       deadline = Date.now() + 5e3;
       continue;
     }
     await delay(100);
   }
+  if (unidentified) throw unidentifiedListenerError(unidentified);
   throw new AxiError("Lavish Editor server did not start", "SERVER_ERROR", [
     `Run \`lavish-axi server --port ${port}\` to inspect server startup`
   ]);
 }
+function missingHostsError(port, missingHosts) {
+  return new AxiError(
+    `The Lavish server on port ${port} does not serve ${missingHosts.join(", ")}, and replacing it did not stick`,
+    "SERVER_ERROR",
+    ["Run `lavish-axi stop`, then retry"]
+  );
+}
 function shouldRestartServer(currentVersion, healthBody, forceRestart = false) {
   if (!healthBody || typeof healthBody !== "object") return false;
   if (forceRestart && healthBody.app === "lavish-axi") return true;
@@ -13295,22 +13645,52 @@ function shouldKillProcessOnPort(currentVersion, healthBody) {
   if (healthBody.app !== "lavish-axi") return false;
   return healthBody.version !== currentVersion;
 }
-async function canControlServerOnPort(port, healthBody, processMatchesLavish) {
+async function canControlServerOnPort(baseUrl, healthBody, processMatchesLavish) {
   if (!healthBody || typeof healthBody !== "object") return false;
   if (healthBody.app === "lavish-axi") return true;
   if (typeof healthBody.version === "string" && healthBody.version !== "") return false;
-  return processMatchesLavish(port);
+  return processMatchesLavish(baseUrl);
 }
-async function fetchHealth(baseUrl, { reconcileNetwork = false, timeoutMs, signal } = {}) {
-  try {
-    const suffix = reconcileNetwork ? "?reconcile_network=1" : "";
-    const abortSignal = signal ?? (timeoutMs ? AbortSignal.timeout(timeoutMs) : void 0);
-    const response = await fetch(`${baseUrl}/health${suffix}`, abortSignal ? { signal: abortSignal } : {});
-    if (!response.ok) return null;
-    return await response.json();
-  } catch {
-    return null;
-  }
+function fetchHealth(baseUrl, { reconcileNetwork = false, timeoutMs = DEFAULT_HEALTH_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let request = null;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      request?.destroy();
+      resolve(value);
+    };
+    const abort = () => finish(null);
+    const timer = setTimeout(abort, timeoutMs);
+    try {
+      const url = new URL(`${baseUrl}/health${reconcileNetwork ? "?reconcile_network=1" : ""}`);
+      request = httpGet2(url, { agent: false }, (response) => {
+        let body = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          body += chunk;
+          if (body.length > MAX_HEALTH_BODY_BYTES) finish(null);
+        });
+        response.on("end", () => {
+          if (!response.statusCode || response.statusCode < 200 || response.statusCode >= 300) {
+            finish(null);
+            return;
+          }
+          try {
+            finish(JSON.parse(body));
+          } catch {
+            finish(null);
+          }
+        });
+        response.on("error", abort);
+      });
+      request.on("error", abort);
+    } catch {
+      abort();
+    }
+  });
 }
 async function requestShutdown(baseUrl, { reloadKey = "", reason = "" } = {}) {
   const body = {};
@@ -13333,40 +13713,45 @@ async function waitForPortFree(baseUrl, timeoutMs) {
   }
   return false;
 }
-function killProcessOnPort(port) {
+function lavishListenerPids(baseUrl) {
+  const { hostname, port } = new URL(baseUrl);
   try {
-    const result = spawnSync("lsof", ["-t", `-iTCP:${port}`, "-sTCP:LISTEN"], { encoding: "utf8" });
-    if (result.status !== 0) return;
-    for (const line of result.stdout.split("\n")) {
+    const listing = spawnSync("lsof", ["-t", `-iTCP@${hostname}:${port}`, "-sTCP:LISTEN"], { encoding: "utf8" });
+    if (listing.status !== 0) return [];
+    const pids = [];
+    for (const line of listing.stdout.split("\n")) {
       const pid = Number(line.trim());
-      if (Number.isInteger(pid) && pid > 0 && pid !== process.pid) {
-        try {
-          process.kill(pid, "SIGTERM");
-        } catch {
-        }
-      }
+      if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) continue;
+      const command = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
+      if (command.status === 0 && /lavish-axi/.test(command.stdout)) pids.push(pid);
     }
+    return pids;
   } catch {
+    return [];
   }
 }
-function processOnPortMatchesLavish(port) {
-  try {
-    const pids = spawnSync("lsof", ["-t", `-iTCP:${port}`, "-sTCP:LISTEN"], { encoding: "utf8" });
-    if (pids.status !== 0) return false;
-    for (const line of pids.stdout.split("\n")) {
-      const pid = Number(line.trim());
-      if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) continue;
-      const command = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
-      if (command.status === 0 && /lavish-axi/.test(command.stdout)) {
-        return true;
-      }
+function listenerMatchesLavish(baseUrl) {
+  return lavishListenerPids(baseUrl).length > 0;
+}
+function killLavishListener(baseUrl) {
+  const pids = lavishListenerPids(baseUrl);
+  for (const pid of pids) {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
     }
-  } catch {
-    return false;
   }
-  return false;
+  return pids.length > 0;
+}
+function unidentifiedListenerError(baseUrl) {
+  const { host } = new URL(baseUrl);
+  return new AxiError(
+    `The server at ${host} did not shut down, and no Lavish process listening there could be identified`,
+    "SERVER_ERROR",
+    [`Stop the process listening on ${host} yourself, or set LAVISH_AXI_PORT to another port`]
+  );
 }
-async function startServer(port) {
+async function startServer(port, { alsoListen = [] } = {}) {
   await ensureStateDir();
   const entry = resolveServerEntry();
   let logFd = null;
@@ -13375,7 +13760,9 @@ async function startServer(port) {
   } catch {
   }
   try {
-    const child = spawn(process.execPath, [entry, "server", "--port", String(port)], createServerSpawnOptions(logFd));
+    const args = [entry, "server", "--port", String(port)];
+    for (const host of alsoListen) args.push("--also-listen", host);
+    const child = spawn(process.execPath, args, createServerSpawnOptions(logFd));
     child.unref();
   } finally {
     if (logFd !== null) closeSync(logFd);
@@ -13497,6 +13884,20 @@ function flagValue(args, flag) {
   }
   return null;
 }
+function flagValues(args, flag) {
+  const values = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--") break;
+    if (arg === flag && args[i + 1]) {
+      values.push(args[i + 1]);
+      i += 1;
+    } else if (arg.startsWith(`${flag}=`) && arg.length > flag.length + 1) {
+      values.push(arg.slice(flag.length + 1));
+    }
+  }
+  return values;
+}
 function inspectValueFlag(args, flag) {
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -13700,11 +14101,11 @@ plugin: register the installed lavish-axi package as an Agent Plugin (agent-plug
 
 Both actions are explicit opt-in, idempotent, and repair a stale path after a reinstall.
 `,
-    server: `Usage: lavish-axi server [--port 4387] [--verbose]
+    server: `Usage: lavish-axi server [--port 4387] [--verbose] [--also-listen <host>...]
 
 Run the local Lavish Editor server. Pass --verbose (or set LAVISH_AXI_DEBUG=1) to log session and watcher events to stderr. Detached server output is appended to ~/.lavish-axi/server.log, or LAVISH_AXI_STATE_DIR/server.log when set, for startup and crash diagnostics.
 
-By default Lavish binds to 127.0.0.1 and, when Tailscale is running, this machine's Tailscale IPv4. Any explicit LAVISH_AXI_HOST overrides automatic Tailscale binding; wildcard values such as 0.0.0.0 or :: are restricted to loopback. An explicit non-wildcard LAVISH_AXI_HOST sets one bind address; binding beyond loopback exposes an unauthenticated server that can read and serve arbitrary local files to anything that can reach it, so only do so on a trusted network. With automatic binding enabled, a successfully bound Tailscale listener uses its MagicDNS name in generated session links; otherwise LAVISH_AXI_LINK_HOST can set the link hostname. See README's Allowed hosts section for Host allowlisting and LAVISH_AXI_ALLOWED_HOSTS. LAVISH_AXI_NO_OPEN=1 (or --no-open) suppresses the local browser launch.
+By default Lavish binds to 127.0.0.1 and, when Tailscale is running, this machine's Tailscale IPv4. Any explicit LAVISH_AXI_HOST overrides automatic Tailscale binding; wildcard values such as 0.0.0.0 or :: are restricted to loopback. An explicit non-wildcard LAVISH_AXI_HOST sets the bind address, and the server also listens on 127.0.0.1 so every local CLI finds it; --also-listen adds further concrete addresses (the CLI passes it when it replaces a server, to keep every address the old one served). An address that cannot be bound is retried in the background and reported as network_warning. Binding beyond loopback exposes an unauthenticated server that can read and serve arbitrary local files to anything that can reach it, so only do so on a trusted network. With automatic binding enabled, a successfully bound Tailscale listener uses its MagicDNS name in generated session links; otherwise LAVISH_AXI_LINK_HOST can set the link hostname. See README's Allowed hosts section for Host allowlisting and LAVISH_AXI_ALLOWED_HOSTS. LAVISH_AXI_NO_OPEN=1 (or --no-open) suppresses the local browser launch.
 `
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lavish-axi",
-  "version": "0.1.76",
+  "version": "0.1.78",
   "packageManager": "pnpm@11.1.1",
   "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
   "type": "module",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "lavish-axi",
-  "version": "0.1.76",
+  "version": "0.1.78",
   "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
   "author": {
     "name": "Kun Chen",

package/skills/lavish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lavish
-description: Turn complex or visual agent responses into rich, reviewable HTML artifacts the user can annotate and send feedback on, using the lavish-axi CLI. Use when about to give a plan, comparison, diagram, table, code diff, report, or anything easier to grasp visually than as prose.
+description: Turn complex or visual agent responses into rich, reviewable HTML artifacts (HTML files) the user can annotate and send feedback on, using the lavish-axi CLI. Use when about to give a plan, comparison, diagram, table, code diff, report, or anything easier to grasp visually than as prose.
 license: MIT
 metadata:
   author: Kun Chen (kunchenguid)
@@ -29,5 +29,5 @@ If lavish-axi output shows a follow-up command starting with `lavish-axi`, run i
 
 $ARGUMENTS
 
-If the request above is non-empty, the user invoked `/lavish` explicitly - fetch the current CLI guidance, then build that artifact.
+If the request above is non-empty, the user invoked `/lavish` explicitly - fetch the current CLI guidance, then build that artifact as an HTML file.
 If it is empty, infer what to visualize from the conversation.