lavish-axi 0.1.74 → 0.1.75

package/README.md

@@ -205,7 +205,7 @@ pnpm link
 - **Keyboard shortcuts** - In the chrome composer, Enter sends queued prompts and Shift+Enter inserts a newline.
   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.
+- **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. A supervisor-owned process listener is shown as an external listener rather than an idle captain turn.
   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.
@@ -286,6 +286,8 @@ For flows, architecture, state, or sequence diagrams, open the diagram playbook
 | `lavish-axi share`       | `--update-key <key>`        | The secret returned when the page was published; required to republish or unpublish it.                                                                                                                                                                                                                                       |
 | `lavish-axi share`       | `--unpublish`               | Replace a published page with a locked placeholder (ht-ml.app cannot delete); takes `--site` and `--update-key` and no file.                                                                                                                                                                                                  |
 | `lavish-axi share`       | `--token <t>`               | Attach an optional bearer token (`LAVISH_AXI_HTML_APP_TOKEN`) when creating a page; never required, and rejected on a republish or `--unpublish`, where the `update_key` is the credential.                                                                                                                                   |
+| `lavish-axi poll`        | `--owner <label>`           | Identify the process listening for this session; the non-empty label appears in the home session listing. `none` is reserved for sessions without a listener. A second concurrent poll is refused instead of silently returning `waiting`.                                                                                    |
+| `lavish-axi poll`        | `--takeover`                | Explicitly displace the current poll listener. The displaced poll exits with typed `LISTENER_REPLACED`; without this flag, the new poll fails with typed `LISTENER_ACTIVE`.                                                                                                                                                   |
 | `lavish-axi poll`        | `--agent-reply "..."`       | Show a concise agent reply in the existing browser chat, conclude delivered work, and return presence to waiting before polling again. Keep replies concise by default.                                                                                                                                                       |
 | `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.                                                                                                                                                                                                                                 |

package/dist/chrome-client.js

@@ -988,12 +988,14 @@ function syncChat(chat, revision) {
 }
 
 function setAgentPresence(state) {
-  agentPresence = state === "listening" || state === "working" ? state : "waiting";
+  agentPresence = state === "listening" || state === "external" || state === "working" ? state : "waiting";
   updateSendState();
   renderSheetSummary();
   if (presenceBanner) presenceBanner.hidden = ended || agentPresence !== "waiting";
 
-  if (agentPresence !== "working") {
+  // A supervisor-owned process-only listener is busy on the agent's behalf. It must not make the
+  // composer look like an idle captain turn while the owning agent is offline.
+  if (agentPresence !== "working" && agentPresence !== "external") {
     if (workingBubble) workingBubble.remove();
     workingBubble = null;
     return;
@@ -1209,6 +1211,7 @@ function sheetSummary() {
   }
   if (unreadAgentReply) return { text: unreadAgentReply, accent: false, unread: true };
   if (agentPresence === "working") return { text: "Agent is working…", accent: false, unread: false };
+  if (agentPresence === "external") return { text: "External listener active", accent: false, unread: false };
   if (agentPresence === "listening") return { text: "Agent listening", accent: false, unread: false };
   return { text: "Agent not listening", accent: false, unread: false };
 }
@@ -4075,7 +4078,7 @@ events.set("chat-sync", (data) => {
   rememberChatAckIds(data.ack_ids);
   syncChat(data.chat || [], data.chat_revision);
 });
-events.set("agent-presence", (data) => setAgentPresence(data.state));
+events.set("agent-presence", (data) => setAgentPresence(data.mode === "external-listener" ? "external" : data.state));
 events.set("layout-warnings", (data) => setLayoutWarnings(data.warnings || []));
 events.set("ended", () => markSessionEnded());
 connectLiveEvents();

package/dist/cli.mjs

@@ -9392,6 +9392,7 @@ 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;
 var SHUTDOWN_REASONS = /* @__PURE__ */ new Set(["upgrade", "local-build", "stop"]);
+var AGENT_LISTENER_LABEL = "agent-listener";
 var RELOAD_DEBOUNCE_MS = 100;
 var BATCH_RELOAD_DEBOUNCE_MS = 900;
 function defaultWhiteboardAssetsDir() {
@@ -9520,8 +9521,10 @@ async function serve({
   const watchers = /* @__PURE__ */ new Map();
   const activePolls = /* @__PURE__ */ new Map();
   const deliveredFeedback = /* @__PURE__ */ new Set();
+  const pollOwnershipLock = new AsyncMutex();
   const liveEventClients = /* @__PURE__ */ new Map();
   const browserDisconnectTimers = /* @__PURE__ */ new Map();
+  const browserDisconnectPending = /* @__PURE__ */ new Set();
   const whiteboardChannelSecret = crypto6.randomBytes(32);
   const outstandingRepairBatches = /* @__PURE__ */ new Set();
   const diagnosticViewportClasses = resolveDiagnosticViewportClasses();
@@ -9544,7 +9547,10 @@ async function serve({
   events.on("reload", (key) => broadcastLiveEvent("reload", key));
   events.on("agent-reply", (key, entry) => broadcastLiveEvent("agent-reply", key, entry));
   events.on("chat-sync", (key, session) => broadcastLiveEvent("chat-sync", key, serializeChatSync(session)));
-  events.on("agent-presence", (key, state) => broadcastLiveEvent("agent-presence", key, { state }));
+  events.on(
+    "agent-presence",
+    (key, state) => broadcastLiveEvent("agent-presence", key, presenceEventData(key, state, activePolls, deliveredFeedback))
+  );
   events.on("layout-warnings", (key, warnings) => broadcastLiveEvent("layout-warnings", key, { warnings }));
   events.on("ended", (key, endedBy) => broadcastLiveEvent("ended", key, { ended_by: endedBy || null }));
   function hasLiveEventClient(key) {
@@ -9564,13 +9570,17 @@ async function serve({
     if (shuttingDown || hasLiveEventClient(key) || !activePolls.has(key)) return;
     const timer = setTimeout(() => {
       browserDisconnectTimers.delete(key);
-      if (!hasLiveEventClient(key) && activePolls.has(key)) events.emit("browser-disconnected", key);
+      if (!hasLiveEventClient(key) && activePolls.has(key)) {
+        browserDisconnectPending.add(key);
+        events.emit("browser-disconnected", key);
+      }
     }, browserDisconnectGraceMs);
     timer.unref?.();
     browserDisconnectTimers.set(key, timer);
   }
   function attachLiveEventClient(client, key, onClose) {
     clearBrowserDisconnectTimer(key);
+    browserDisconnectPending.delete(key);
     liveEventClients.set(client, key);
     refreshIdleTimer();
     let cleanedUp = false;
@@ -9591,7 +9601,8 @@ async function serve({
       return;
     }
     client.sendEvent("chat-sync", serializeChatSync(session));
-    client.sendEvent("agent-presence", { state: computePresence(key, activePolls, deliveredFeedback) });
+    const presence = computePresence(key, activePolls, deliveredFeedback);
+    client.sendEvent("agent-presence", presenceEventData(key, presence, activePolls, deliveredFeedback));
     if (session?.status === "ended") client.sendEvent("ended", { ended_by: session.ended_by || null });
   }
   function requestedBindIsRecoverable() {
@@ -9627,7 +9638,6 @@ async function serve({
   function finishFeedbackDelivery(key, result) {
     if (result.status !== "feedback") return;
     markFeedbackDelivered(key, activePolls, deliveredFeedback, events);
-    if (result.session_ended) clearFeedbackDelivery(key, activePolls, deliveredFeedback, events);
   }
   async function restoreClosedFeedback(key, result) {
     if (result.status !== "feedback") return;
@@ -9754,7 +9764,11 @@ async function serve({
       app: "lavish-axi",
       version,
       ...networkStale ? { network_stale: true } : {},
-      ...networkWarning ? { network_warning: networkWarning } : {}
+      ...networkWarning ? { network_warning: networkWarning } : {},
+      listeners: [...activePolls].map(([key, holder]) => ({
+        key,
+        label: listenerLabel(holder)
+      }))
     });
   });
   let shutdownResolve;
@@ -9804,13 +9818,44 @@ async function serve({
       next(error);
     }
   });
-  app.get("/api/poll", async (req, res, next) => {
-    let requestClosed = Boolean(req.destroyed);
+  async function publishAgentReply(key, text) {
+    const session = await store.addAgentReply(key, text);
+    if (!session) return null;
+    const lastEntry = session.chat?.at(-1);
+    const entry = serializeChat([
+      lastEntry?.role === "agent" ? lastEntry : { role: "agent", text, at: session.updated_at }
+    ])[0];
+    events.emit("agent-reply", key, entry);
+    events.emit("chat-sync", key, session);
+    clearFeedbackDelivery(key, activePolls, deliveredFeedback, events);
+    return session;
+  }
+  const handlePoll = async (req, res, next) => {
+    const takeover = req.query.takeover === "1";
+    const agentReply = req.method === "POST" && req.body?.agent_reply !== void 0 ? String(req.body.agent_reply) : null;
+    if (takeover && req.method !== "POST") {
+      res.status(405).json({ error: "poll takeover requires POST" });
+      return;
+    }
+    if (req.method === "POST" && (agentReply === null ? !takeover : !agentReply.trim())) {
+      res.status(405).json({ error: "POST /api/poll requires agent_reply or takeover=1" });
+      return;
+    }
+    let requestClosed = Boolean(req.aborted || req.method !== "POST" && req.destroyed);
     let cleanupPoll = null;
+    let claimedHolder = null;
     const onRequestClose = () => {
+      if (req.method === "POST" && !req.aborted) return;
       requestClosed = true;
       cleanupPoll?.();
     };
+    const onResponseClose = () => {
+      if (req.method === "POST" && !res.writableEnded) {
+        requestClosed = true;
+        cleanupPoll?.();
+      }
+    };
+    res.on("close", onResponseClose);
     const detachRequestClose = () => req.off("close", onRequestClose);
     req.on("close", onRequestClose);
     try {
@@ -9824,20 +9869,86 @@ async function serve({
       };
       const file = await canonicalFile(String(req.query.file || ""));
       const key = sessionKey(file);
+      const ownerValue = typeof req.query.owner === "string" ? req.query.owner.trim() : "";
+      if (ownerValue.toLowerCase() === "none" || ownerValue.startsWith("-")) {
+        detachRequestClose();
+        res.status(400).json({
+          status: "error",
+          code: "VALIDATION_ERROR",
+          error: "--owner none is reserved; pass a different listener label"
+        });
+        return;
+      }
+      const owner = ownerValue || null;
+      if (hasPresentOriginOrReferer(req) && !isSameOriginRequest(req, allowedHostnames, allowAnyHostname)) {
+        detachRequestClose();
+        res.status(403).json({ error: "cross-origin poll takeover rejected" });
+        return;
+      }
+      const { holder, previousPresence, conflict, missing } = await pollOwnershipLock.runExclusive(async () => {
+        const currentHolder = activePolls.get(key);
+        if (currentHolder && !takeover) return { conflict: listenerConflict(currentHolder, "LISTENER_ACTIVE") };
+        const nextHolder = { key, owner, startedAt: Date.now(), replaced: false, replace: null };
+        claimedHolder = nextHolder;
+        const priorPresence = presenceSignature(key, activePolls, deliveredFeedback);
+        if (currentHolder) {
+          currentHolder.replaced = true;
+          activePolls.set(key, nextHolder);
+          currentHolder.replace?.();
+        } else {
+          activePolls.set(key, nextHolder);
+        }
+        deliveredFeedback.delete(key);
+        if (agentReply !== null) {
+          const session = await publishAgentReply(key, agentReply);
+          if (!session) {
+            activePolls.delete(key);
+            return { missing: true };
+          }
+        }
+        return { holder: nextHolder, previousPresence: priorPresence };
+      });
+      if (conflict) {
+        detachRequestClose();
+        res.status(409).json(conflict);
+        return;
+      }
+      if (missing) {
+        detachRequestClose();
+        res.status(404).json({ error: "session not found" });
+        return;
+      }
       const timeoutMs = req.query.timeoutMs === void 0 ? null : Math.max(0, Math.min(Number(req.query.timeoutMs || 0), 2147483647));
       const immediate = await store.takeFeedback(key);
       if (immediate.status !== "waiting") {
-        if (requestClosed || req.destroyed || res.writableEnded) {
+        if (holder.replaced) {
           await restoreClosedFeedback(key, immediate);
           detachRequestClose();
+          res.json(listenerConflict(holder, "LISTENER_REPLACED"));
+          releasePollListener(holder, activePolls, deliveredFeedback, events);
+          return;
+        }
+        if (requestClosed || res.writableEnded) {
+          await restoreClosedFeedback(key, immediate);
+          releasePollListener(holder, activePolls, deliveredFeedback, events);
+          detachRequestClose();
           return;
         }
         finishFeedbackDelivery(key, immediate);
+        releasePollListener(holder, activePolls, deliveredFeedback, events);
+        if (immediate.session_ended) clearFeedbackDelivery(key, activePolls, deliveredFeedback, events);
         detachRequestClose();
         res.json(immediate);
         return;
       }
-      if (requestClosed || req.destroyed || res.writableEnded) {
+      if (holder.replaced) {
+        detachRequestClose();
+        res.json(listenerConflict(holder, "LISTENER_REPLACED"));
+        releasePollListener(holder, activePolls, deliveredFeedback, events);
+        return;
+      }
+      if (requestClosed || res.writableEnded) {
+        releasePollListener(holder, activePolls, deliveredFeedback, events);
         detachRequestClose();
         return;
       }
@@ -9851,7 +9962,6 @@ async function serve({
         }, pollHeartbeatMs);
         heartbeat.unref?.();
       }
-      setPollActive(key, activePolls, deliveredFeedback, events, true);
       refreshIdleTimer();
       let timer = null;
       let cleaned = false;
@@ -9864,19 +9974,45 @@ async function serve({
         events.off("feedback", onFeedback);
         events.off("ended", onFeedback);
         events.off("browser-disconnected", onBrowserDisconnected);
-        setPollActive(key, activePolls, deliveredFeedback, events, false);
-        if (!activePolls.has(key)) clearBrowserDisconnectTimer(key);
+        releasePollListener(holder, activePolls, deliveredFeedback, events);
+        if (!activePolls.has(key)) {
+          clearBrowserDisconnectTimer(key);
+          browserDisconnectPending.delete(key);
+        }
         refreshIdleTimer();
         cleanupPoll = null;
         detachRequestClose();
+        res.off("close", onResponseClose);
       };
+      const respondReplacement = () => {
+        if (responding || res.writableEnded) return;
+        responding = true;
+        try {
+          const replacement = listenerConflict(holder, "LISTENER_REPLACED");
+          if (streamHeartbeat) res.end(JSON.stringify(replacement));
+          else res.json(replacement);
+        } finally {
+          cleanup();
+        }
+      };
+      holder.replace = respondReplacement;
       const respond = async (forcedResult = null) => {
         if (responding || res.writableEnded) return;
         responding = true;
+        let finalSessionEnded = false;
         try {
           const result = await store.takeFeedback(key);
           const responseResult = forcedResult && result.status === "waiting" ? forcedResult : result;
-          if (requestClosed || req.destroyed || res.writableEnded) {
+          finalSessionEnded = responseResult?.session_ended === true;
+          if (holder.replaced) {
+            if (responseResult.status !== "waiting") await restoreClosedFeedback(key, responseResult);
+            if (!requestClosed && !res.writableEnded) {
+              if (streamHeartbeat) res.end(JSON.stringify(listenerConflict(holder, "LISTENER_REPLACED")));
+              else res.json(listenerConflict(holder, "LISTENER_REPLACED"));
+            }
+            return;
+          }
+          if (requestClosed || res.writableEnded) {
             await restoreClosedFeedback(key, responseResult);
             return;
           }
@@ -9888,6 +10024,7 @@ async function serve({
           }
         } finally {
           cleanup();
+          if (finalSessionEnded) clearFeedbackDelivery(key, activePolls, deliveredFeedback, events);
         }
       };
       const onFeedback = (changedKey) => {
@@ -9904,17 +10041,33 @@ async function serve({
       events.on("ended", onFeedback);
       events.on("browser-disconnected", onBrowserDisconnected);
       cleanupPoll = cleanup;
-      if (requestClosed || req.destroyed || res.writableEnded) {
+      if (holder.replaced) {
+        respondReplacement();
+        return;
+      }
+      if (requestClosed || res.writableEnded) {
         cleanup();
         return;
       }
+      if (browserDisconnectPending.has(key)) {
+        browserDisconnectPending.delete(key);
+        onBrowserDisconnected(key);
+        return;
+      }
+      const nextPresence = presenceSignature(key, activePolls, deliveredFeedback);
+      if (nextPresence !== previousPresence) {
+        events.emit("agent-presence", key, computePresence(key, activePolls, deliveredFeedback));
+      }
       timer = timeoutMs === null ? null : setTimeout(() => respond().catch(handleRespondError), timeoutMs);
     } catch (error) {
       cleanupPoll?.();
+      if (claimedHolder) releasePollListener(claimedHolder, activePolls, deliveredFeedback, events);
       detachRequestClose();
       next(error);
     }
-  });
+  };
+  app.get("/api/poll", handlePoll);
+  app.post("/api/poll", handlePoll);
   app.post("/api/:key/prompts", async (req, res, next) => {
     try {
       if (!isSameOriginRequest(req, allowedHostnames, allowAnyHostname)) {
@@ -10066,18 +10219,11 @@ async function serve({
   });
   app.post("/api/:key/agent-reply", async (req, res, next) => {
     try {
-      const text = String(req.body?.text || "");
-      const session = await store.addAgentReply(req.params.key, text);
+      const session = await publishAgentReply(req.params.key, String(req.body?.text || ""));
       if (!session) {
         res.status(404).json({ error: "session not found" });
         return;
       }
-      const entry = serializeChat([
-        session.chat?.at(-1)?.role === "agent" ? session.chat.at(-1) : { role: "agent", text, at: session.updated_at }
-      ])[0];
-      events.emit("agent-reply", req.params.key, entry);
-      events.emit("chat-sync", req.params.key, session);
-      clearFeedbackDelivery(req.params.key, activePolls, deliveredFeedback, events);
       res.json({ status: "sent" });
     } catch (error) {
       next(error);
@@ -11107,19 +11253,23 @@ function hasLiveReloadRootOptIn(html) {
   if (/<html\b[^>]*\sdata-lavish-live-reload-root(?:[\s=>/]|$)[^>]*>/i.test(searchableHtml)) return true;
   return /<meta\b(?=[^>]*name=["']lavish-live-reload["'])(?=[^>]*content=["']root["'])[^>]*>/i.test(searchableHtml);
 }
-function setPollActive(key, activePolls, deliveredFeedback, events, active) {
-  const previousPresence = computePresence(key, activePolls, deliveredFeedback);
-  const count = activePolls.get(key) || 0;
-  const nextCount = active ? count + 1 : Math.max(0, count - 1);
-  if (nextCount === count) return;
-  if (nextCount === 0) {
-    activePolls.delete(key);
-  } else {
-    activePolls.set(key, nextCount);
-  }
-  if (active && count === 0) deliveredFeedback.delete(key);
-  const nextPresence = computePresence(key, activePolls, deliveredFeedback);
-  if (nextPresence !== previousPresence) events.emit("agent-presence", key, nextPresence);
+function releasePollListener(holder, activePolls, deliveredFeedback, events) {
+  if (activePolls.get(holder.key) !== holder) return;
+  const previousPresence = computePresence(holder.key, activePolls, deliveredFeedback);
+  activePolls.delete(holder.key);
+  const nextPresence = computePresence(holder.key, activePolls, deliveredFeedback);
+  if (nextPresence !== previousPresence) events.emit("agent-presence", holder.key, nextPresence);
+}
+function listenerLabel(holder) {
+  return holder.owner || AGENT_LISTENER_LABEL;
+}
+function listenerConflict(holder, code) {
+  return {
+    status: "error",
+    code,
+    error: code === "LISTENER_ACTIVE" ? "Lavish Editor already has an active poll listener" : "Lavish Editor poll listener was replaced",
+    holder: { label: listenerLabel(holder), age_ms: Math.max(0, Date.now() - holder.startedAt) }
+  };
 }
 function markFeedbackDelivered(key, activePolls, deliveredFeedback, events) {
   const previousPresence = computePresence(key, activePolls, deliveredFeedback);
@@ -11138,9 +11288,21 @@ function clearFeedbackDelivery(key, activePolls, deliveredFeedback, events) {
   }
 }
 function computePresence(key, activePolls, deliveredFeedback) {
-  if (activePolls.has(key)) return "listening";
   if (deliveredFeedback.has(key)) return "working";
-  return "waiting";
+  return activePolls.has(key) ? "listening" : "waiting";
+}
+function presenceSignature(key, activePolls, deliveredFeedback) {
+  return `${computePresence(key, activePolls, deliveredFeedback)}:${presenceMode(key, activePolls, deliveredFeedback)}`;
+}
+function presenceMode(key, activePolls, deliveredFeedback) {
+  if (deliveredFeedback.has(key)) return "agent-busy";
+  const holder = activePolls.get(key);
+  if (!holder) return "waiting-on-captain";
+  return holder.owner ? "external-listener" : "agent-listener";
+}
+function presenceEventData(key, state, activePolls, deliveredFeedback) {
+  const mode = presenceMode(key, activePolls, deliveredFeedback);
+  return mode === "waiting-on-captain" ? { state } : { state, mode };
 }
 function chromeIcon(paths, size = 16, strokeWidth = 1.7) {
   return `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="${strokeWidth}" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${paths}</svg>`;
@@ -11621,14 +11783,14 @@ var POLL_SEND_AND_END_RULE = "`Send & End` ends the session. Its final feedback
 var POLL_AGENT_REPLY_RULE = "Keep the reply concise. Only when a longer reply is genuinely necessary, use Markdown structure - blank-line paragraphs, `- ` / `1. ` lists, `## ` headings - so it renders scannably instead of a wall of text, and pass that body with `--agent-reply-file <path>` (`-` reads stdin) so newlines survive quoting.";
 var POLL_AGENT_REPLY_HELP_POINTER = "The Conversation panel's Markdown subset is in README's Feedback controls bullet.";
 var POLL_AGENT_REPLY_NEXT_POINTER = "The Conversation panel's Markdown subset is in `lavish-axi poll --help` and README.";
-var POLL_VALUE_FLAGS = ["--agent-reply", "--agent-reply-file", "--timeout-ms"];
+var POLL_VALUE_FLAGS = ["--agent-reply", "--agent-reply-file", "--timeout-ms", "--owner"];
 var AGENT_REPLY_JSON_LIMIT_BYTES = 2 * 1024 * 1024;
-var AGENT_REPLY_JSON_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ text: "" }));
+var AGENT_REPLY_JSON_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ agent_reply: "" }));
 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.74";
+var VERSION = "0.1.75";
 function detectInvokingAgent(env = process.env) {
   return ["CODEX_SANDBOX", "CODEX_THREAD_ID"].some((key) => Object.hasOwn(env, key)) ? "codex" : "generic";
 }
@@ -11771,7 +11933,8 @@ function createHomeOutput({ bin, sessions, includeSessions = true, agent = "gene
         file: session.file,
         status: session.status,
         url: session.url,
-        pending_prompts: session.pending_prompts || 0
+        pending_prompts: session.pending_prompts || 0,
+        listener: session.listener || "none"
       }))
     } : {},
     visual_guidance: [
@@ -11891,14 +12054,24 @@ async function pollCommand(args) {
   if (!file) {
     throw new AxiError("HTML file path is required", "VALIDATION_ERROR", ["Run `lavish-axi poll <html-file>`"]);
   }
+  const ownerFlag = inspectValueFlag(args, "--owner");
+  const owner = ownerFlag.present ? String(ownerFlag.value || "").trim() : null;
+  if (ownerFlag.present && (!owner || owner.startsWith("-") || owner.toLowerCase() === "none")) {
+    throw new AxiError(
+      owner?.toLowerCase() === "none" ? "--owner none is reserved" : "--owner requires a non-empty label",
+      "VALIDATION_ERROR",
+      ["Pass `--owner <label>` to identify the process listening for feedback"]
+    );
+  }
+  const takeover = args.includes("--takeover");
   const agentReply = await resolveAgentReply(args);
   const absolute = await canonicalFile(file);
   const baseUrl = await ensureServer();
-  if (agentReply) {
-    await postJson(`${baseUrl}/api/${sessionKey(absolute)}/agent-reply`, { text: agentReply });
-  }
   const timeoutMs = flagValue(args, "--timeout-ms");
-  const timeoutQuery = timeoutMs ? `&timeoutMs=${encodeURIComponent(timeoutMs)}` : "";
+  const query = new URLSearchParams({ file: absolute });
+  if (timeoutMs) query.set("timeoutMs", timeoutMs);
+  if (owner) query.set("owner", owner);
+  if (takeover) query.set("takeover", "1");
   const onPollSignal = (signal) => {
     process.stderr.write(`
 ${pollInterruptedText(absolute)}
@@ -11914,13 +12087,25 @@ ${pollInterruptedText(absolute)}
     narrateTicks: shouldNarratePollWaitTicks({ isTTY: process.stderr.isTTY })
   });
   try {
-    const response = await fetchJson(`${baseUrl}/api/poll?file=${encodeURIComponent(absolute)}${timeoutQuery}`, {
-      retries: 3,
-      retryDelayMs: 500,
+    const request = agentReply || takeover ? {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(agentReply ? { agent_reply: agentReply } : {})
+    } : {};
+    const response = await fetchJson(`${baseUrl}/api/poll?${query}`, {
+      ...request,
+      // Poll ownership is claimed before the response is available. Retrying a transport failure
+      // can leave the first claim alive and make the retry reject itself as LISTENER_ACTIVE.
+      retries: 0,
       onResponse: (pollResponse) => {
         if (pollResponse.headers.get(POLL_STATE_HEADER) === "listening") notifyHerdrPollReady();
       }
     });
+    if (response.code === "LISTENER_REPLACED") {
+      throw new AxiError("Lavish Editor poll listener was replaced by a takeover", "LISTENER_REPLACED", [
+        `Re-run lavish-axi poll ${absolute} only if you intend to take over listening`
+      ]);
+    }
     return createPollOutput({ file: absolute, response, agent: detectInvokingAgent(process.env) });
   } finally {
     waitReporter?.stop();
@@ -12779,7 +12964,12 @@ async function serverCommand(args) {
 }
 async function visibleSessions() {
   const store = new SessionStore(stateFile());
-  return (await store.listSessions()).filter((session) => session.status !== "ended");
+  const sessions = (await store.listSessions()).filter((session) => session.status !== "ended");
+  const { health } = await findRunningServer(defaultPort());
+  const listeners = new Map(
+    Array.isArray(health?.listeners) ? health.listeners.filter((listener) => listener && typeof listener.key === "string").map((listener) => [listener.key, listener.label || "agent-listener"]) : []
+  );
+  return sessions.map((session) => ({ ...session, listener: listeners.get(session.key) || "none" }));
 }
 async function assertHtmlFile(file) {
   if (!isHtmlPath(file)) {
@@ -13002,11 +13192,15 @@ function createServerSpawnOptions(logFd = null) {
     env: { ...process.env, LAVISH_AXI_NO_OPEN: "1" }
   };
 }
-async function fetchJson(url, { retries = 0, retryDelayMs = 250, onResponse = null } = {}) {
+async function fetchJson(url, { retries = 0, retryDelayMs = 250, onResponse = null, method = "GET", headers, body } = {}) {
   let response;
   for (let attempt = 0; attempt <= retries; attempt += 1) {
     try {
-      response = await fetch(url);
+      response = await fetch(url, {
+        method,
+        ...headers ? { headers } : {},
+        ...body === void 0 ? {} : { body }
+      });
       break;
     } catch (error) {
       if (error instanceof AxiError) throw error;
@@ -13016,6 +13210,22 @@ async function fetchJson(url, { retries = 0, retryDelayMs = 250, onResponse = nu
   }
   if (!response) throw serverConnectionError();
   if (!response.ok) {
+    let payload = null;
+    try {
+      payload = await response.json();
+    } catch {
+    }
+    if (payload?.code) {
+      const holder = payload.code.startsWith("LISTENER_") && payload.holder;
+      const holderDetail = holder && typeof holder.label === "string" && Number.isFinite(holder.age_ms) ? ` (current listener: ${holder.label}; active for ${Math.max(0, holder.age_ms)}ms)` : "";
+      const error = new AxiError(
+        `${payload.error || `Lavish Editor request failed: ${response.status}`}${holderDetail}`,
+        payload.code,
+        ["Use --takeover only when you intend to displace the current listener"]
+      );
+      if (holder) Object.assign(error, { holder });
+      throw error;
+    }
     throw new AxiError(`Lavish Editor request failed: ${response.status}`, "SERVER_ERROR");
   }
   onResponse?.(response);
@@ -13114,7 +13324,7 @@ async function readAgentReplyStream(stream) {
     chunks.push(chunk);
   }
   const text = Buffer.concat(chunks, bytes).toString("utf8");
-  if (Buffer.byteLength(JSON.stringify({ text })) > AGENT_REPLY_JSON_LIMIT_BYTES) {
+  if (Buffer.byteLength(JSON.stringify({ agent_reply: text })) > AGENT_REPLY_JSON_LIMIT_BYTES) {
     throw agentReplyTooLargeError();
   }
   return text;
@@ -13197,7 +13407,7 @@ function createTopLevelHelp({ agent = "generic" } = {}) {
 Usage:
   lavish-axi
   lavish-axi <html-file> [--no-open] [--no-gate] [--reopen]
-  lavish-axi poll <html-file> [--agent-reply "..."] [--agent-reply-file <path>]
+  lavish-axi poll <html-file> [--owner <label>] [--takeover] [--agent-reply "..."] [--agent-reply-file <path>]
   lavish-axi end <html-file>
   lavish-axi export <html-file> [--out <path>]
   lavish-axi share <html-file> [--private | --password <pw>] [--token <t>]
@@ -13221,7 +13431,9 @@ function createCommandHelp({ agent = "generic" } = {}) {
 
 Open or resume a Lavish Editor review session for an HTML artifact. Use --no-open when you need to ensure the server/session exists without opening another browser window. Use --no-gate to skip the open-time layout curtain for this browser open. If the user explicitly ended the session from the browser, this refuses to reopen it and returns guidance instead - pass --reopen to force it open when the user asks for further review or something important needs their visual attention. Sessions ended by the agent (\`lavish-axi end\`) reopen normally without the flag.
 `,
-    poll: `Usage: lavish-axi poll <html-file> [--agent-reply "..."] [--agent-reply-file <path>]
+    poll: `Usage: lavish-axi poll <html-file> [--owner <label>] [--takeover] [--agent-reply "..."] [--agent-reply-file <path>]
+
+This command exclusively long-polls for queued user prompts. Pass --owner <label> to make the active listener visible in session listings; --takeover displaces an existing listener, which receives LISTENER_REPLACED. A second poll without --takeover fails with LISTENER_ACTIVE instead of silently returning waiting.
 
 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.
 

package/package.json

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