transitions-refine 0.3.13 → 0.3.14

package/.agents/skills/refine-live/SKILL.md

@@ -54,6 +54,19 @@ The relay reports the agent as "available" for ~120s after your last poll, so
 short pauses keep you live. A successful job always resets idle, so an active
 session never backs off.
 
+0. **Announce yourself once, before the first poll.** The relay keeps a *sticky*
+   Stop latch: after a panel **Stop** (or the idle auto-stop) it answers every
+   `GET /jobs/next` with `{"stop": true}` until a new agent explicitly resumes —
+   so a stopped session can't silently come back. Clear the latch a single time
+   at startup, then begin polling:
+
+   ```bash
+   curl -s -X POST http://localhost:7331/poller/start
+   ```
+
+   Do **not** call this again mid-loop (it would defeat a user's Stop). Only on a
+   fresh `/refine live`.
+
 1. **Claim the next job (long-poll).** This call blocks up to ~25s, then returns.
 
    ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transitions-refine",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "description": "Live, agent-driven Refine panel for CSS/Motion transitions — injects a timeline + Refine UI and runs transitions.dev suggestions via your coding agent.",
   "type": "module",
   "bin": {

package/server/live-refine-loop.mjs

@@ -446,6 +446,10 @@ async function pollOnce() {
 
 async function loop() {
   log(`live refine loop → ${RELAY} (workspace: ${WORKSPACE})`);
+  // Announce ourselves so the relay clears any prior Stop latch — otherwise a
+  // relay that's still "stopped" from a previous panel Stop would answer our
+  // first poll with {stop:true} and we'd exit immediately.
+  try { await post("/poller/start", {}); } catch {}
   // eslint-disable-next-line no-constant-condition
   while (true) {
     try {

package/server/relay.mjs

@@ -91,13 +91,6 @@ const PENDING_TIMEOUT_MS = Number(process.env.REFINE_PENDING_TIMEOUT_MS) || 1200
 // to stop (it returns {stop:true} from /jobs/next). 0 disables. Only the chat
 // loop is affected — a wired REFINE_AGENT_CMD never polls /jobs/next.
 const POLLER_IDLE_STOP_MS = Number(process.env.REFINE_POLLER_IDLE_STOP_MS) || 600000;
-// After a Stop (manual or idle), hold the poller "stopped" for this long: every
-// GET /jobs/next keeps getting {stop:true} and /health reports the poller
-// inactive. Without it, a single straggler poll fired right after the stop
-// (an agent mid-backoff, or one that batches a poll before exiting) re-registers
-// as live and the panel flips "Live" back on a few seconds later. A genuine
-// re-run of `/refine live` after the window resumes normally.
-const STOP_GRACE_MS = Number(process.env.REFINE_STOP_GRACE_MS) || 5000;
 
 /** @type {Map<string, Job>} */
 const jobs = new Map();
@@ -106,10 +99,14 @@ const now = () => Date.now();
 // When did a `/refine live` agent last poll? Used to know if LLM mode can be
 // served by a live editor agent (vs. needing REFINE_AGENT_CMD).
 let lastPollAt = 0;
-// While now() < stoppedUntil the relay holds a just-issued Stop (see STOP_GRACE_MS):
-// the poller reports inactive and every /jobs/next answers {stop:true}.
-let stoppedUntil = 0;
-const pollerActive = () => now() >= stoppedUntil && now() - lastPollAt < POLLER_TTL_MS;
+// Stop latch. Set by POST /poller/stop (and idle auto-stop); cleared ONLY by an
+// explicit POST /poller/start (a fresh `/refine live` / agent loop announcing
+// itself). While latched the poller reports inactive and every GET /jobs/next
+// answers {stop:true}, so a loop that ignores the stop — or keeps polling /
+// re-polls — can never silently revive the session. This is what makes the
+// panel's Stop button stick instead of flipping "Live" back on seconds later.
+let pollerStopped = false;
+const pollerActive = () => !pollerStopped && now() - lastPollAt < POLLER_TTL_MS;
 const llmAvailable = () => Boolean(AGENT_CMD) || pollerActive();
 
 // Stop signal for the in-chat `/refine live` loop. Set by POST /poller/stop
@@ -663,32 +660,31 @@ const server = createServer(async (req, res) => {
 
   // GET /jobs/next — long-poll claimed by a `/refine live` agent (LLM jobs).
   if (method === "GET" && path === "/jobs/next") {
-    // Stop-grace window: a Stop was just issued, so keep telling every poller to
-    // exit and don't count these polls as live (we deliberately do NOT update
-    // lastPollAt here). This stops a straggler poll from reviving the session.
-    // A pending job still wins so we never drop real work on the stop edge.
-    if (now() < stoppedUntil && !nextPendingLlm()) {
+    // Stopped latch: a Stop was issued and not yet resumed. Keep telling every
+    // poller to exit and report inactive (don't touch lastPollAt) until a fresh
+    // POST /poller/start. A pending job still wins so we never drop real work.
+    if (pollerStopped && !nextPendingLlm()) {
       return send(res, 200, { stop: true });
     }
     lastPollAt = now();
     if (!lastJobAt) lastJobAt = now(); // seed idle window on the loop's first poll
-    // Stop signal (manual Stop button or idle auto-stop) → tell the loop to exit.
-    // A pending job always wins so we never drop real work on the stop edge.
+    // Idle auto-stop (or a leftover stopRequested) → latch stopped + tell the
+    // loop to exit. A pending job always wins so we never drop real work.
     if ((stopRequested || (POLLER_IDLE_STOP_MS && now() - lastJobAt >= POLLER_IDLE_STOP_MS)) && !nextPendingLlm()) {
       stopRequested = false;
+      pollerStopped = true; // latch until an explicit /poller/start
       lastJobAt = 0;
       lastPollAt = 0; // loop is exiting → report it inactive immediately on /health
-      stoppedUntil = now() + STOP_GRACE_MS; // hold the stop so re-polls can't revive it
       return send(res, 200, { stop: true });
     }
     const deadline = now() + LONGPOLL_MS;
     const attempt = () => {
       if (res.writableEnded) return;
-      if ((stopRequested || now() < stoppedUntil) && !nextPendingLlm()) {
+      if (stopRequested && !nextPendingLlm()) {
         stopRequested = false;
+        pollerStopped = true; // latch until an explicit /poller/start
         lastJobAt = 0;
         lastPollAt = 0; // loop is exiting → report it inactive immediately on /health
-        stoppedUntil = now() + STOP_GRACE_MS; // hold the stop so re-polls can't revive it
         return send(res, 200, { stop: true });
       }
       const job = nextPendingLlm();
@@ -709,11 +705,23 @@ const server = createServer(async (req, res) => {
   if (method === "POST" && path === "/poller/stop") {
     const wasActive = now() - lastPollAt < POLLER_TTL_MS;
     stopRequested = true;
+    pollerStopped = true; // latch: stays stopped until POST /poller/start
     lastPollAt = 0; // report inactive immediately; a straggler poll won't revive it
-    stoppedUntil = now() + STOP_GRACE_MS; // hold the stop through the grace window
     return send(res, 200, { ok: true, stopping: wasActive });
   }
 
+  // POST /poller/start — a fresh `/refine live` agent (or loop) announces itself
+  // and clears the Stop latch so its polls count as live again. Without this an
+  // explicit re-run couldn't resume, since a latched relay tells every poll to
+  // stop. Call it once at loop startup, before the first GET /jobs/next.
+  if (method === "POST" && path === "/poller/start") {
+    pollerStopped = false;
+    stopRequested = false;
+    lastJobAt = now();
+    lastPollAt = now();
+    return send(res, 200, { ok: true });
+  }
+
   const m = path.match(/^\/jobs\/([^/]+)(?:\/(status|result|error))?$/);
   if (m) {
     const job = jobs.get(m[1]);