lavish-axi 0.1.72 → 0.1.74

package/README.md

@@ -206,6 +206,7 @@ pnpm link
   In the annotation card, Enter queues the annotation, Shift+Enter inserts a newline, and Ctrl+Enter (Cmd+Enter on macOS) queues it and sends all queued prompts immediately. Escape closes the card, same as Cancel, but only while it is empty (no text, no attachment); with unsent text or an attachment present, Escape does nothing rather than risk discarding it.
   Cmd+I or Ctrl+I toggles between annotate and explore mode from either the browser chrome or the artifact iframe, including while focus is in a textarea or control.
 - **Agent presence** - The browser shows when no agent is listening, keeps queued feedback for the next successful `lavish-axi poll` send even across reloads, and keeps human feedback actions available while the agent is working because the server queues them for the next poll. An agent reply concludes delivered work and returns presence to waiting.
+  In a Herdr-managed pane, set `LAVISH_AXI_HERDR_CHIME=1` to show a Herdr request notification and play its chime once an indefinite poll enters the waiting state. Immediate queued feedback and timed debug polls do not trigger a notification. The integration is off unless both `LAVISH_AXI_HERDR_CHIME` and Herdr's `HERDR_ENV` session marker equal `1`; leaving either unset or using any other value opts out. Notification delivery runs without blocking feedback: if Herdr is unavailable, rejects the notification, stalls, or fails, the poll continues unchanged.
   Closing the last review tab while a poll is active starts a 10-second reconnect grace period. A reload or quick reconnect keeps an active poll waiting; if every review stays disconnected, the poll returns `browser_disconnected` without ending the resumable session, and the agent asks whether to reopen or end it instead of acting uninvited.
   The no-timeout poll always writes an immediate stderr banner so it is visibly not hung; it adds the periodic stderr wait ticks only in an interactive terminal, so when stderr is piped (as under agent harnesses) the captured output carries no tick noise. Stdout always stays reserved for the final response; if the poll is interrupted or times out before feedback arrives, re-run it because feedback remains queued until delivery. Poll delivery consumes the response, so read the complete response before truncating or filtering it.
   Codex-specific guidance keeps that poll attached to the active turn instead of hiding it in a background task, because completed background tasks may not resume the agent.
@@ -236,7 +237,7 @@ pnpm link
   Lavish changes only the browser view, so saved, standalone, and exported artifacts still render plain Mermaid.
 - **Server cleanup** - The detached server stops after the last session ends when nothing is connected, or after `LAVISH_AXI_IDLE_TIMEOUT_MS` (default 30 minutes) with no browser or poll connections.
   Set `LAVISH_AXI_IDLE_TIMEOUT_MS=0` or `off` to disable idle self-shutdown.
-- **Server upgrades** - One background server serves every session, so upgrading `lavish-axi` while reviews are open makes the next `lavish-axi <html-file>` replace that server. Only the review page for the artifact being opened reloads itself once the replacement answers - and not even that one while you have unsent annotation text open, which gets the same banner instead so the reload is yours to make. Every other open review page keeps working and shows a banner reading "Lavish was updated. This page is running the previous version.", with a Check and reload button and a Dismiss button, so no page you are reading reloads on its own. After `lavish-axi stop` those pages say Lavish was stopped and to reload after you start it again, and a restart that only picks up a local build says that rather than claiming an update.
+- **Server upgrades** - One background server serves every session, so upgrading `lavish-axi` while reviews are open makes the next `lavish-axi <html-file>` replace that server. Only the review page for the artifact being opened reloads itself once the replacement answers - and not even that one while you have unsent annotation text open, which gets the same banner instead so the reload is yours to make. Every other open review page keeps working and shows a banner reading "Lavish was updated. This page is running the previous version.", with a Check and reload button and a Dismiss button, so no page you are reading reloads on its own. After `lavish-axi stop` those pages say Lavish was stopped and to reload after you start it again, and a restart that only picks up a local build says that rather than claiming an update. An open review page whose server simply goes away - idle self-shutdown, a crash, a machine that slept - shows that same banner once reconnecting has failed for a few seconds, rather than retrying a dead server silently while looking fine; it clears itself if the server comes back, and dismissing it keeps it dismissed until then.
   A page still using the legacy event stream reloads once when it reconnects to the replacement server, moving itself onto the current transport without retaining an HTTP connection. If unsent annotation text is open, it shows the neutral server-restarted banner instead and waits for you to reload.
   Every **Check and reload** control asks the server whether it is running before it navigates; while nothing answers, the page stays where it is and says so, and a check that gets no answer at all says that instead of guessing.
   In-flight `lavish-axi poll` commands end with an interrupted-poll error and are safe to re-run; queued feedback is never lost, and annotation text you have typed but not queued yet survives the reload as described under **Live reload**.
@@ -244,7 +245,7 @@ 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. `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 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.
 - **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.
 
@@ -289,7 +290,7 @@ For flows, architecture, state, or sequence diagrams, open the diagram playbook
 | `lavish-axi poll`        | `--agent-reply-file <path>` | When a longer reply is genuinely necessary, read Markdown from a file (`-` for stdin) so newlines survive quoting. Use blank-line paragraphs, `- ` / `1. ` lists, and `## ` headings so the Conversation panel renders it scannably. The Markdown subset is under Feedback controls. Cannot be combined with `--agent-reply`. |
 | `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 to `~/.lavish-axi/server.log` (or `LAVISH_AXI_STATE_DIR/server.log`) for startup and crash diagnostics.                                                                                           |
+| `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.                                                      |
 
 ## Development
 

package/dist/chrome-client.js

@@ -198,6 +198,16 @@ const layoutGateMaxHoldMs =
 let chromeOutdatedReason = "";
 let chromeOutdatedGeneration = 0;
 let outdatedReloadInFlight = false;
+// The live-event socket reconnects forever on a 5s cap. Silence there is indistinguishable from a
+// healthy idle stream, so a page whose server has gone away keeps rendering its last state and
+// tells the user nothing until they reload into a connection error. Past this many consecutive
+// failures the banner says so, with the health-probed reload the banner already offers.
+const LIVE_EVENT_UNREACHABLE_FAILURES = 5;
+let liveEventFailures = 0;
+// Only a banner this path raised may be hidden by this path: a `chrome-outdated` event means the
+// server was replaced, which a reconnect does not disprove.
+let unreachableBannerOwned = false;
+let unreachableDismissed = false;
 /** @type {{ selector: string, revision: number } | null} */
 let unrestorableDraftMiss = null;
 let retiredDrafts = loadRetiredDrafts();
@@ -3935,7 +3945,17 @@ endButton.onclick = () => {
 };
 handoffTakeoverButton.onclick = () => location.reload();
 if (outdatedReloadButton) outdatedReloadButton.onclick = () => reloadChromeForOutdatedBanner();
-if (outdatedDismissButton) outdatedDismissButton.onclick = () => setChromeOutdated(false);
+if (outdatedDismissButton) {
+  outdatedDismissButton.onclick = () => {
+    // A dismissed unreachable banner stays dismissed until the stream actually recovers; without
+    // this the next failed reconnect puts it straight back on screen.
+    if (unreachableBannerOwned) {
+      unreachableBannerOwned = false;
+      unreachableDismissed = true;
+    }
+    setChromeOutdated(false);
+  };
+}
 document.addEventListener("mousedown", (event) => {
   const target = /** @type {Node} */ (event.target);
   if (!moreMenu.hidden && !moreWrap.contains(target)) setMenuOpen(moreButton, moreMenu, false);
@@ -3998,6 +4018,12 @@ function connectLiveEvents() {
   const socket = new WebSocket(protocol + "//" + location.host + "/events/" + encodeURIComponent(key));
   socket.addEventListener("open", () => {
     eventReconnectDelayMs = 500;
+    liveEventFailures = 0;
+    unreachableDismissed = false;
+    if (unreachableBannerOwned) {
+      unreachableBannerOwned = false;
+      setChromeOutdated(false);
+    }
     refreshLayoutWarnings();
   });
   socket.addEventListener("message", (message) => {
@@ -4009,11 +4035,23 @@ function connectLiveEvents() {
     }
   });
   socket.addEventListener("close", () => {
+    liveEventFailures += 1;
+    noteLiveEventsUnreachable();
     setTimeout(connectLiveEvents, eventReconnectDelayMs);
     eventReconnectDelayMs = Math.min(eventReconnectDelayMs * 2, 5000);
   });
 }
 
+// Raise the existing banner once the stream has been down long enough to mean it, and never
+// against an ended session or a banner someone else owns. Reconnecting retires it.
+function noteLiveEventsUnreachable() {
+  if (liveEventFailures < LIVE_EVENT_UNREACHABLE_FAILURES) return;
+  if (ended || unreachableDismissed || unreachableBannerOwned) return;
+  if (outdatedBanner && !outdatedBanner.hidden) return;
+  unreachableBannerOwned = true;
+  setChromeOutdated(true, "");
+}
+
 events.set("reload", () => {
   resetFrame().then((reloaded) => {
     if (reloaded) refreshWhiteboardSource();

package/dist/cli.mjs

@@ -18,7 +18,7 @@ import {
   writeFileSync as writeFileSync2
 } from "node:fs";
 import { access, readFile as readFile6, writeFile as writeFile4 } from "node:fs/promises";
-import os3 from "node:os";
+import os4 from "node:os";
 import path8 from "node:path";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 import { AxiError, installSessionStartHooks, RESERVED_COMMANDS, runAxiCli } from "axi-sdk-js";
@@ -7928,6 +7928,31 @@ 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}`;
+}
+var STDIO_STAMPED = /* @__PURE__ */ Symbol.for("lavish-axi.stdio-timestamped");
+function serverStdioIsTimestamped() {
+  return Boolean(globalThis[STDIO_STAMPED]);
+}
+
 // src/html-transform.js
 function injectLavishSdk(html, key, artifactRevision, artifactLoadToken = "") {
   const revisionNumber = Number(artifactRevision);
@@ -9360,8 +9385,9 @@ var designAssetUrls = {
 var DEFAULT_IDLE_TIMEOUT_MS = 30 * 6e4;
 var WHITEBOARD_CHANNEL_TOKEN_TTL_MS = 5 * 6e4;
 var NETWORK_RECONCILE_CACHE_MS = 1e3;
-var TAILSCALE_BIND_RETRY_DELAYS_MS = [100, 250, 500];
+var BIND_RETRY_DELAYS_MS = [100, 250, 500];
 var WEBSOCKET_CLOSE_GRACE_MS = 250;
+var LIVE_EVENT_HEARTBEAT_MS = 3e4;
 var BROWSER_DISCONNECT_GRACE_MS = 1e4;
 var ARTIFACT_CONTENT_SECURITY_POLICY = "sandbox allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads";
 var ATTACHMENT_SWEEP_INTERVAL_MS = 60 * 6e4;
@@ -9460,6 +9486,7 @@ async function serve({
   debug = false,
   log = null,
   pollHeartbeatMs = 15e3,
+  liveEventHeartbeatMs = LIVE_EVENT_HEARTBEAT_MS,
   browserDisconnectGraceMs = BROWSER_DISCONNECT_GRACE_MS,
   idleTimeoutMs = resolveIdleTimeoutMs(),
   host = bindHost(env),
@@ -9484,6 +9511,7 @@ async function serve({
   });
   const activeTailscaleNetwork = tailscaleNetworkKey(tailscale);
   let tailscalePhoneReady = false;
+  const absentRequestedHosts = [];
   let networkWarning = typeof tailscale?.warning === "string" ? tailscale.warning : "";
   let resolvedLinkHost = linkHostName ?? resolveLinkHost({ env, tailscale, fallbackHost: host });
   const app = express();
@@ -9498,7 +9526,7 @@ async function serve({
   const outstandingRepairBatches = /* @__PURE__ */ new Set();
   const diagnosticViewportClasses = resolveDiagnosticViewportClasses();
   const verbose = debug || env.LAVISH_AXI_DEBUG === "1";
-  const writeLog = typeof log === "function" ? log : (line) => process.stderr.write(`${line}
+  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}`);
@@ -9566,6 +9594,14 @@ async function serve({
     client.sendEvent("agent-presence", { state: computePresence(key, activePolls, deliveredFeedback) });
     if (session?.status === "ended") client.sendEvent("ended", { ended_by: session.ended_by || null });
   }
+  function requestedBindIsRecoverable() {
+    return absentRequestedHosts.some((listenHost) => isLocalAddressPresent(listenHost));
+  }
+  async function reconcileNetwork() {
+    if (requestedBindIsRecoverable()) return true;
+    if (!(autoTailscale && typeof detect === "function")) return false;
+    return reconcileTailscaleNetwork();
+  }
   async function reconcileTailscaleNetwork() {
     if (Date.now() - networkReconcileCheckedAt < NETWORK_RECONCILE_CACHE_MS) return cachedNetworkStale;
     if (networkReconcilePromise) return networkReconcilePromise;
@@ -9712,7 +9748,7 @@ async function serve({
       res.status(503).json({ ok: false, app: "lavish-axi", version });
       return;
     }
-    const networkStale = req.query.reconcile_network === "1" && autoTailscale && typeof detect === "function" ? await reconcileTailscaleNetwork() : false;
+    const networkStale = req.query.reconcile_network === "1" ? await reconcileNetwork() : false;
     res.json({
       ok: true,
       app: "lavish-axi",
@@ -9729,7 +9765,7 @@ async function serve({
     const reloadKey = String(req.body?.reload_key || "");
     const reason = SHUTDOWN_REASONS.has(String(req.body?.reason || "")) ? String(req.body.reason) : "";
     res.json({ status: "shutting-down" });
-    setImmediate(() => shutdown(reloadKey, reason));
+    setImmediate(() => shutdown(reloadKey, reason, "shutdown-request"));
   });
   app.post("/api/sessions", async (req, res, next) => {
     try {
@@ -9808,7 +9844,7 @@ async function serve({
       const streamHeartbeat = timeoutMs === null;
       let heartbeat = null;
       if (streamHeartbeat) {
-        res.status(200).type("application/json");
+        res.status(200).type("application/json").set("Lavish-Poll-State", "listening");
         res.write(" ");
         heartbeat = setInterval(() => {
           if (!res.writableEnded) res.write(" ");
@@ -10585,6 +10621,27 @@ ${body}`
       };
       webSocket.on("error", () => {
       });
+      if (liveEventHeartbeatMs != null && liveEventHeartbeatMs > 0) {
+        let awaitingPong = false;
+        const heartbeat = setInterval(() => {
+          if (awaitingPong) {
+            logEvent?.(`event WebSocket heartbeat missed session=${key}, terminating`);
+            webSocket.terminate();
+            return;
+          }
+          awaitingPong = true;
+          try {
+            webSocket.ping();
+          } catch {
+            webSocket.terminate();
+          }
+        }, liveEventHeartbeatMs);
+        heartbeat.unref?.();
+        webSocket.on("pong", () => {
+          awaitingPong = false;
+        });
+        webSocket.once("close", () => clearInterval(heartbeat));
+      }
       const cleanup = attachLiveEventClient(client, key, (remove) => webSocket.once("close", remove));
       sendInitialLiveEventState(client, key, cleanup).catch((error) => {
         client.close(1011, "Failed to initialize live events");
@@ -10596,36 +10653,75 @@ ${body}`
   const httpServers = [];
   const boundHosts = [];
   let boundPort = port;
-  for (const listenHost of listenHosts) {
-    const retryDelays = listenHost === tailscale?.ipv4 ? TAILSCALE_BIND_RETRY_DELAYS_MS : [];
+  let lastBindError = null;
+  async function bindListener(listenHost) {
     let retryIndex = 0;
     while (true) {
       try {
-        const httpServer = await listenHttp(app, boundPort, listenHost);
+        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);
-        break;
+        return null;
       } catch (error) {
-        if (httpServers.length === 0) throw error;
-        if (retryIndex < retryDelays.length) {
-          await new Promise((resolve) => setTimeout(resolve, retryDelays[retryIndex]));
+        if (retryIndex < BIND_RETRY_DELAYS_MS.length) {
+          await new Promise((resolve) => setTimeout(resolve, BIND_RETRY_DELAYS_MS[retryIndex]));
           retryIndex += 1;
           continue;
         }
-        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 instanceof Error ? error.message : error}`);
-        }
-        break;
+        return error instanceof Error ? error : new Error(String(error));
       }
     }
   }
+  for (const listenHost of listenHosts) {
+    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}`);
+    }
+  }
+  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 (httpServers.length === 0) {
-    throw new Error("Lavish server failed to bind any address");
+    throw new Error(
+      `Lavish server failed to bind any address${lastBindError ? `: ${lastBindError.message}` : ""}`,
+      lastBindError ? { cause: lastBindError } : void 0
+    );
+  }
+  if (!boundHosts.includes(LOOPBACK_HOST) && !boundHosts.includes(listenHosts[0])) {
+    const error = new Error(
+      `Lavish server failed to bind a control-channel address${lastBindError ? `: ${lastBindError.message}` : ""}`,
+      lastBindError ? { cause: lastBindError } : void 0
+    );
+    await Promise.all(
+      httpServers.splice(0).map(
+        (httpServer) => new Promise((resolve) => {
+          httpServer.close(() => resolve(void 0));
+        })
+      )
+    );
+    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) {
@@ -10641,9 +10737,10 @@ ${body}`
   }
   publicPort = httpServers[0].address().port;
   serverReady = true;
-  function shutdown(reloadKey = "", reason = "") {
+  function shutdown(reloadKey = "", reason = "", cause = "requested") {
     if (shuttingDown) return;
     shuttingDown = true;
+    writeLog(`[lavish] shutting down: ${cause}${reason ? ` (reason=${reason})` : ""}`);
     if (idleTimer) {
       clearTimeout(idleTimer);
       idleTimer = null;
@@ -10695,8 +10792,7 @@ ${body}`
     idleTimer = setTimeout(() => {
       idleTimer = null;
       if (!shuttingDown && liveEventClients.size === 0 && activePolls.size === 0) {
-        logEvent?.(`idle for ${idleTimeoutMs}ms with no connections, shutting down`);
-        shutdown();
+        shutdown("", "", `idle-timeout after ${idleTimeoutMs}ms with no connections`);
       }
     }, idleTimeoutMs);
     idleTimer.unref?.();
@@ -10706,8 +10802,7 @@ ${body}`
     try {
       const sessions = await store.listSessions();
       if (sessions.every((session) => session.status === "ended")) {
-        logEvent?.("last open session ended with no live connections, shutting down");
-        setImmediate(shutdown);
+        setImmediate(() => shutdown("", "", "last open session ended with no live connections"));
       }
     } catch {
     }
@@ -10759,21 +10854,26 @@ ${body}`
     hosts: boundHosts,
     addresses: httpServers.map((server) => server.address()),
     close: async () => {
-      shutdown();
+      shutdown("", "", "close() called");
       await done;
     },
     done
   };
 }
-function listenHttp(app, port, host) {
+function listenHttp(app, port, host, onRuntimeError) {
   return new Promise((resolve, reject) => {
     const server = createServer(app);
+    let listening = false;
     const onError = (error) => {
-      server.off("listening", onListening);
-      reject(error);
+      if (!listening) {
+        server.off("listening", onListening);
+        reject(error);
+        return;
+      }
+      onRuntimeError?.(error);
     };
     const onListening = () => {
-      server.off("error", onError);
+      listening = true;
       const address = server.address();
       if (address && typeof address === "object" && isWildcardHost(address.address)) {
         server.close(() => reject(new Error(`Refusing all-interfaces listener at ${address.address}`)));
@@ -10781,7 +10881,7 @@ function listenHttp(app, port, host) {
       }
       resolve(server);
     };
-    server.once("error", onError);
+    server.on("error", onError);
     server.once("listening", onListening);
     server.listen({ port, host });
   });
@@ -10794,6 +10894,9 @@ function tailscaleNetworkKey(tailscale) {
 ${tailscale.ipv4}
 ${tailscale.magicDnsName}`;
 }
+function isAddressAbsentBindError(error) {
+  return error instanceof Error && "code" in error && error.code === "EADDRNOTAVAIL";
+}
 function wantsHtml(req) {
   const accept = String(req.get("accept") || "");
   return accept.toLowerCase().includes("text/html");
@@ -11523,14 +11626,57 @@ var AGENT_REPLY_JSON_LIMIT_BYTES = 2 * 1024 * 1024;
 var AGENT_REPLY_JSON_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ text: "" }));
 var AGENT_REPLY_INPUT_LIMIT_BYTES = AGENT_REPLY_JSON_LIMIT_BYTES - AGENT_REPLY_JSON_ENVELOPE_BYTES;
 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.72";
+var VERSION = "0.1.74";
 function detectInvokingAgent(env = process.env) {
   return ["CODEX_SANDBOX", "CODEX_THREAD_ID"].some((key) => Object.hasOwn(env, key)) ? "codex" : "generic";
 }
 function shouldNarratePollWaitTicks({ isTTY }) {
   return Boolean(isTTY);
 }
+function herdrPollChimeEnabled(env = process.env) {
+  return env.HERDR_ENV === "1" && env.LAVISH_AXI_HERDR_CHIME === "1";
+}
+function notifyHerdrPollReady({ env = process.env, runner = spawn } = {}) {
+  if (!herdrPollChimeEnabled(env)) return false;
+  try {
+    const child = runner(
+      "herdr",
+      [
+        "notification",
+        "show",
+        "Lavish review ready",
+        "--body",
+        "The artifact is open and Lavish is polling for your feedback.",
+        "--sound",
+        "request"
+      ],
+      { stdio: "ignore" }
+    );
+    const kill = () => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        return;
+      }
+    };
+    const timer = setTimeout(kill, 2e3);
+    timer.unref();
+    const cleanup = () => {
+      clearTimeout(timer);
+      process.off("exit", kill);
+    };
+    child.on("error", () => {
+    });
+    child.once("close", cleanup);
+    process.once("exit", kill);
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
 function pollExecutionGuidance({ agent = "generic" } = {}) {
   const sharedGuidance = POLL_WAKE_PATH_RULES.join(" ");
   const agentGuidance = agent === "codex" ? ` ${CODEX_POLL_WAKE_PATH_GUIDANCE}` : "";
@@ -11618,7 +11764,7 @@ function telemetryCommandName(argv) {
 }
 function createHomeOutput({ bin, sessions, includeSessions = true, agent = "generic" }) {
   return {
-    bin: collapseHomeDirectory(bin, os3.homedir()),
+    bin: collapseHomeDirectory(bin, os4.homedir()),
     description: DESCRIPTION,
     ...includeSessions ? {
       sessions: sessions.map((session) => ({
@@ -11770,7 +11916,10 @@ ${pollInterruptedText(absolute)}
   try {
     const response = await fetchJson(`${baseUrl}/api/poll?file=${encodeURIComponent(absolute)}${timeoutQuery}`, {
       retries: 3,
-      retryDelayMs: 500
+      retryDelayMs: 500,
+      onResponse: (pollResponse) => {
+        if (pollResponse.headers.get(POLL_STATE_HEADER) === "listening") notifyHerdrPollReady();
+      }
     });
     return createPollOutput({ file: absolute, response, agent: detectInvokingAgent(process.env) });
   } finally {
@@ -12304,7 +12453,7 @@ function generatedPasswordNote(password) {
 }
 async function stopCommand(args) {
   const port = Number(flagValue(args, "--port") || defaultPort());
-  const baseUrl = `http://${hostForUrl(clientHost())}:${port}`;
+  const { baseUrl } = await findRunningServer(port);
   return shutdownServerOnPort(port, { baseUrl, currentVersion: VERSION });
 }
 async function shutdownServerOnPort(port, {
@@ -12537,7 +12686,7 @@ function sameResolvedPath(left, right) {
     return path8.resolve(left) === path8.resolve(right);
   }
 }
-function resolveHookHomeDir(env = process.env, fallback = os3.homedir()) {
+function resolveHookHomeDir(env = process.env, fallback = os4.homedir()) {
   return env.HOME || fallback;
 }
 function resolveCopilotHookDir(env = process.env, homeDir = resolveHookHomeDir(env)) {
@@ -12647,10 +12796,42 @@ 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;
+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 };
+  }
+  return foreign ?? { baseUrl: candidates[0], health: null };
+}
+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);
+  }
+}
 async function ensureServer({ forceRestart = false, reloadKey = "" } = {}) {
   const port = defaultPort();
-  const baseUrl = `http://${hostForUrl(clientHost())}:${port}`;
-  const existing = await fetchHealth(baseUrl, { reconcileNetwork: true });
+  const { baseUrl, health: existing } = await findRunningServer(port, { reconcileNetwork: true });
   if (existing && !shouldRestartServer(VERSION, existing, forceRestart)) {
     return baseUrl;
   }
@@ -12670,15 +12851,16 @@ async function ensureServer({ forceRestart = false, reloadKey = "" } = {}) {
     }
   }
   await startServer(port);
-  let networkRestarted = false;
+  const replacedForNetwork = Boolean(existing) && existing.app === "lavish-axi" && existing.network_stale === true && !forceRestart && typeof existing.version === "string" && existing.version === VERSION;
+  let networkRestarted = replacedForNetwork;
   let deadline = Date.now() + 5e3;
   while (Date.now() < deadline) {
-    const health = await fetchHealth(baseUrl, { reconcileNetwork: true });
-    if (health && !shouldRestartServer(VERSION, health)) return baseUrl;
+    const { baseUrl: liveUrl, health } = await findRunningServer(port, { reconcileNetwork: true });
+    if (health && !shouldRestartServer(VERSION, health)) return liveUrl;
     if (health?.network_stale === true && health.app === "lavish-axi") {
-      if (networkRestarted) return baseUrl;
-      await requestShutdown(baseUrl, { reloadKey, reason: "" });
-      if (!await waitForPortFree(baseUrl, 3e3)) break;
+      if (networkRestarted) return liveUrl;
+      await requestShutdown(liveUrl, { reloadKey, reason: "" });
+      if (!await waitForPortFree(liveUrl, 3e3)) break;
       await startServer(port);
       networkRestarted = true;
       deadline = Date.now() + 5e3;
@@ -12724,10 +12906,11 @@ async function canControlServerOnPort(port, healthBody, processMatchesLavish) {
   if (typeof healthBody.version === "string" && healthBody.version !== "") return false;
   return processMatchesLavish(port);
 }
-async function fetchHealth(baseUrl, { reconcileNetwork = false } = {}) {
+async function fetchHealth(baseUrl, { reconcileNetwork = false, timeoutMs, signal } = {}) {
   try {
     const suffix = reconcileNetwork ? "?reconcile_network=1" : "";
-    const response = await fetch(`${baseUrl}/health${suffix}`);
+    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 {
@@ -12804,9 +12987,9 @@ async function startServer(port) {
   }
 }
 function resolveServerEntry() {
-  const binEntry = fileURLToPath4(new URL("../bin/lavish-axi.js", import.meta.url));
-  if (existsSync3(binEntry)) return binEntry;
-  return fileURLToPath4(import.meta.url);
+  const sourceEntry = fileURLToPath4(new URL("../bin/lavish-axi-server.js", import.meta.url));
+  if (existsSync3(sourceEntry)) return sourceEntry;
+  return fileURLToPath4(new URL("./server.mjs", import.meta.url));
 }
 function createServerSpawnOptions(logFd = null) {
   const stdio = (
@@ -12819,7 +13002,7 @@ function createServerSpawnOptions(logFd = null) {
     env: { ...process.env, LAVISH_AXI_NO_OPEN: "1" }
   };
 }
-async function fetchJson(url, { retries = 0, retryDelayMs = 250 } = {}) {
+async function fetchJson(url, { retries = 0, retryDelayMs = 250, onResponse = null } = {}) {
   let response;
   for (let attempt = 0; attempt <= retries; attempt += 1) {
     try {
@@ -12835,6 +13018,7 @@ async function fetchJson(url, { retries = 0, retryDelayMs = 250 } = {}) {
   if (!response.ok) {
     throw new AxiError(`Lavish Editor request failed: ${response.status}`, "SERVER_ERROR");
   }
+  onResponse?.(response);
   try {
     return await response.json();
   } catch {
@@ -13039,7 +13223,7 @@ Open or resume a Lavish Editor review session for an HTML artifact. Use --no-ope
 `,
     poll: `Usage: lavish-axi poll <html-file> [--agent-reply "..."] [--agent-reply-file <path>]
 
-This command long-polls indefinitely for queued user prompts. It stays silent while it waits - that is normal, never kill it. Browser-detected layout issues do NOT return this poll: they are filed passively in the user's Layout issues inbox and arrive as an ordinary tag "layout-warnings" prompt only after the user selects them and queues the fixes. Warning lifecycle: an issue stays unresolved and counted while queued, becomes recurring if a newer artifact revision still shows it, and is resolved only after a newer artifact load plus a complete diagnostic pass at the same viewport no longer detects it. A failed or incomplete pass preserves it as unverified rather than clearing it. The only response that arrives without user action is artifact_failures - a fatal failure that made the review surface itself unusable. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. ${pollExecutionGuidance({ agent })} Use --agent-reply after applying prior feedback to display a concise response in Lavish Editor before waiting again. ${POLL_AGENT_REPLY_RULE} ${POLL_AGENT_REPLY_HELP_POINTER} Do not combine --agent-reply with --agent-reply-file.
+This command long-polls indefinitely for queued user prompts. It stays silent while it waits - that is normal, never kill it. Browser-detected layout issues do NOT return this poll: they are filed passively in the user's Layout issues inbox and arrive as an ordinary tag "layout-warnings" prompt only after the user selects them and queues the fixes. Warning lifecycle: an issue stays unresolved and counted while queued, becomes recurring if a newer artifact revision still shows it, and is resolved only after a newer artifact load plus a complete diagnostic pass at the same viewport no longer detects it. A failed or incomplete pass preserves it as unverified rather than clearing it. The only response that arrives without user action is artifact_failures - a fatal failure that made the review surface itself unusable. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. In a Herdr-managed pane, set LAVISH_AXI_HERDR_CHIME=1 to request attention when the poll has entered its waiting state; unset it or use any other value to keep the current silent behavior. Notification failures never interrupt the poll. ${pollExecutionGuidance({ agent })} Use --agent-reply after applying prior feedback to display a concise response in Lavish Editor before waiting again. ${POLL_AGENT_REPLY_RULE} ${POLL_AGENT_REPLY_HELP_POINTER} Do not combine --agent-reply with --agent-reply-file.
 
 Examples:
   lavish-axi poll report.html --agent-reply "Renamed the payment step."

package/dist/server.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+// src/server-log.js
+function formatServerLogLine(line, now = /* @__PURE__ */ new Date()) {
+  return `${now.toISOString()} ${line}`;
+}
+var STDIO_STAMPED = /* @__PURE__ */ Symbol.for("lavish-axi.stdio-timestamped");
+function serverStdioIsTimestamped() {
+  return Boolean(globalThis[STDIO_STAMPED]);
+}
+function createTimestampedWrite(write, now = () => /* @__PURE__ */ new Date()) {
+  let atLineStart = true;
+  return function timestampedWrite(chunk, encoding, callback) {
+    let enc = encoding;
+    let cb = callback;
+    if (typeof encoding === "function") {
+      cb = encoding;
+      enc = void 0;
+    }
+    const str = chunkToString(chunk, enc);
+    let out = "";
+    for (let i = 0; i < str.length; i += 1) {
+      if (atLineStart) {
+        out += formatServerLogLine("", now());
+        atLineStart = false;
+      }
+      const ch = str[i];
+      out += ch;
+      if (ch === "\n") atLineStart = true;
+    }
+    return write(out, enc, cb);
+  };
+}
+function installServerStdioTimestamps() {
+  if (serverStdioIsTimestamped()) return;
+  globalThis[STDIO_STAMPED] = true;
+  process.stdout.write = createTimestampedWrite(process.stdout.write.bind(process.stdout));
+  process.stderr.write = createTimestampedWrite(process.stderr.write.bind(process.stderr));
+}
+function chunkToString(chunk, encoding) {
+  if (typeof chunk === "string") return chunk;
+  if (Buffer.isBuffer(chunk)) {
+    const bufferEncoding = (
+      /** @type {BufferEncoding} */
+      typeof encoding === "string" ? encoding : "utf8"
+    );
+    return chunk.toString(bufferEncoding);
+  }
+  return String(chunk);
+}
+
+// bin/lavish-axi-server.js
+installServerStdioTimestamps();
+var fatalExitScheduled = false;
+function handleFatalServerError(kind, error) {
+  const detail = error instanceof Error ? error.stack || error.message : String(error);
+  console.error(`[lavish] ${kind}: ${detail}`);
+  if (fatalExitScheduled) return;
+  fatalExitScheduled = true;
+  process.exitCode = 1;
+  setImmediate(() => process.exit(1));
+}
+process.on("uncaughtException", (error) => handleFatalServerError("uncaught exception", error));
+try {
+  await import("./cli.mjs");
+} catch (error) {
+  handleFatalServerError("server startup failed", error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lavish-axi",
-  "version": "0.1.72",
+  "version": "0.1.74",
   "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.72",
+  "version": "0.1.74",
   "description": "HTML is the new markdown. Lavish is the new editor for your HTML artifacts.",
   "author": {
     "name": "Kun Chen",