lavish-axi 0.1.71 → 0.1.73

package/README.md

@@ -236,7 +236,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 +244,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.
 
@@ -266,7 +266,7 @@ pnpm link
 | `lavish-axi setup plugin`       | Register the installed package as an [Agent Plugin](https://agent-plugins.org) in VS Code, Cursor, and GitHub Copilot CLI; opt-in, idempotent, no marketplace involved. Reload each client afterward.                                                                                                                                                     |
 | `lavish-axi server`             | Run the local Lavish Editor server.                                                                                                                                                                                                                                                                                                                       |
 
-Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `code`, `input`, `slides`.
+Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `code`, `input`, `explanation`, `slides`.
 One artifact often combines several playbooks, such as a plan that includes a comparison and a diagram, so agents must match against each `use_when` trigger and open every matching playbook before writing HTML.
 For flows, architecture, state, or sequence diagrams, open the diagram playbook for the recommended tooling and SVG guidance.
 
@@ -289,7 +289,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";
@@ -249,6 +249,38 @@ var PLAYBOOKS = [
       "End input paths with an obvious way for the user to send feedback back to the agent."
     ]
   },
+  {
+    id: "explanation",
+    use_when: "Explain an existing system, PR, incident, or decision to a reader who was not there - when the goal is understanding what is and why, not choosing a direction or inspecting a plan before implementation",
+    choose: [
+      "Use this when the reader needs to understand something that already exists: a PR's mechanism, an incident's root cause, an architecture, a past decision.",
+      "Use the plan playbook when the reader must inspect and approve an approach before implementation begins; use comparison when they must choose between options.",
+      "Combine with diagram for flows or architecture, table for evidence inventories, and code when the mechanism lives in specific lines."
+    ],
+    structure: [
+      "Lead with the one-sentence answer to the question the reader actually has, before any mechanism.",
+      "Then show only what changed or how it works - a flow or before/after of the relevant slice, not a diagram of the whole system.",
+      "Keep evidence (file paths, line references, links, commands) subordinate to the narrative: cited where a claim needs support, never inlined wholesale.",
+      "Make each claim its own section or annotation target so the reader can push back on exactly the part they disagree with.",
+      "End with what was deliberately left out and where to look next, not a summary that restates the piece."
+    ],
+    design_rules: [
+      "Define unfamiliar terms at first use; for the reader's starting point, follow the diagram playbook's assume-nothing rule rather than restating it here.",
+      "Name the question the explanation answers at the top, so the reader knows whether it is their question.",
+      "Put prose beside figures - inline SVG for the flow or before/after, HTML for the reasoning - per the diagram playbook.",
+      "Link evidence rather than pasting logs or diffs; inlined evidence buries the narrative and goes stale.",
+      "Distinguish verified claims (cited to files, commands, or links) from inference; label uncertain reasoning as a question."
+    ],
+    pitfalls: [
+      "Do not restate the PR body, diff, or ticket file-by-file; the source documents already exist and the reader can open them.",
+      "Do not bury the answer under a diagram of the entire system when the question is about one slice of it.",
+      "Do not present inferred reasoning as verified fact; cite or label it."
+    ],
+    lavish_notes: [
+      "A Lavish explanation should let the reader annotate the exact claim they doubt or want expanded.",
+      "When an explanation surfaces a disagreement, queue prompts that name the claim and the evidence gap."
+    ]
+  },
   {
     id: "slides",
     use_when: "Create a deliberate presentation when slides are requested",
@@ -7896,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);
@@ -9328,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;
@@ -9428,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),
@@ -9452,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();
@@ -9466,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}`);
@@ -9534,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;
@@ -9680,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",
@@ -9697,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 {
@@ -10553,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");
@@ -10564,8 +10653,8 @@ ${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 {
@@ -10574,26 +10663,63 @@ ${body}`
         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) {
@@ -10609,9 +10735,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;
@@ -10663,8 +10790,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?.();
@@ -10674,8 +10800,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 {
     }
@@ -10727,7 +10852,7 @@ ${body}`
     hosts: boundHosts,
     addresses: httpServers.map((server) => server.address()),
     close: async () => {
-      shutdown();
+      shutdown("", "", "close() called");
       await done;
     },
     done
@@ -10762,6 +10887,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");
@@ -11492,7 +11620,7 @@ 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 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.71";
+var VERSION = "0.1.73";
 function detectInvokingAgent(env = process.env) {
   return ["CODEX_SANDBOX", "CODEX_THREAD_ID"].some((key) => Object.hasOwn(env, key)) ? "codex" : "generic";
 }
@@ -11586,7 +11714,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) => ({
@@ -12272,7 +12400,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, {
@@ -12505,7 +12633,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)) {
@@ -12615,10 +12743,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;
   }
@@ -12638,15 +12798,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;
@@ -12692,10 +12853,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 {
@@ -12772,9 +12934,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 = (
@@ -13045,7 +13207,7 @@ Shut down the background Lavish Editor server. The server also stops itself when
 `,
     playbook: `Usage: lavish-axi playbook [playbook_id]
 
-List focused artifact guidance playbooks, or show one playbook by ID. Known IDs: diagram, table, comparison, plan, code, input, slides.
+List focused artifact guidance playbooks, or show one playbook by ID. Known IDs: diagram, table, comparison, plan, code, input, explanation, slides.
 
 ${PLAYBOOK_ROUTER_HELP}
 

package/dist/server.mjs

@@ -0,0 +1,59 @@
+#!/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();
+try {
+  await import("./cli.mjs");
+} catch (error) {
+  console.error(error);
+  process.exit(1);
+}

package/package.json

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