transitions-refine 0.3.13 → 0.3.15

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.15",
   "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

@@ -25,7 +25,7 @@
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { refineTimings, DURATION_TOKENS, SCALE_TOKENS, BLUR_TOKENS, SMOOTH_OUT } from "./motion-tokens.mjs";
@@ -33,6 +33,12 @@ import { buildInjectModule } from "./inject.mjs";
 
 const PORT = Number(process.env.REFINE_RELAY_PORT) || 7331;
 const AUTO = process.env.REFINE_AUTO !== "0";
+// Own package version, surfaced on /health so you can verify which relay build is
+// actually running (npx caches — a stale relay is the usual "fix didn't work").
+let PKG_VERSION = "0.0.0";
+try {
+  PKG_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version || PKG_VERSION;
+} catch {}
 
 // A bare `cursor-agent` goes interactive: it prints "⚠ Workspace Trust Required"
 // and exits 1, so every headless refine/scan/apply job fails. Force the headless
@@ -91,13 +97,13 @@ 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;
+// While the Stop latch is held, a genuinely new `/refine live` session can resume
+// itself implicitly: only after polling has been *quiet* this long (the old loop
+// actually died) do we treat the next poll as a fresh session and auto-resume.
+// Must exceed a looping agent's poll gap, so an agent that ignores Stop and keeps
+// polling can never clear the latch — it just keeps getting {stop:true}. (An
+// updated agent also resumes explicitly via POST /poller/start, no wait needed.)
+const STOP_QUIET_MS = Number(process.env.REFINE_STOP_QUIET_MS) || 15000;
 
 /** @type {Map<string, Job>} */
 const jobs = new Map();
@@ -106,10 +112,17 @@ 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;
+// When did a poll last arrive *while latched*? Used to detect that the old loop
+// went quiet so a genuinely new session (or re-run) can auto-resume.
+let lastStoppedPollAt = 0;
+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
@@ -599,9 +612,11 @@ const server = createServer(async (req, res) => {
   if (method === "GET" && path === "/health") {
     return send(res, 200, {
       ok: true,
+      version: PKG_VERSION,
       auto: AUTO,
       llmAvailable: llmAvailable(),
       pollerActive: pollerActive(),
+      pollerStopped,
       agentCmd: Boolean(AGENT_CMD),
       cliInstalled: cursorCliInstalled(),
       jobs: jobs.size,
@@ -663,32 +678,43 @@ 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()) {
-      return send(res, 200, { stop: true });
+    // Stopped latch: a Stop was issued and not yet resumed. Keep telling every
+    // poller to exit and report inactive until either an explicit POST
+    // /poller/start, or polling goes quiet for STOP_QUIET_MS (the old loop died)
+    // and a new poll arrives — only then is it a genuinely fresh session.
+    // A pending job always wins so we never drop real work on the edge.
+    if (pollerStopped && !nextPendingLlm()) {
+      if (lastStoppedPollAt && now() - lastStoppedPollAt >= STOP_QUIET_MS) {
+        // Quiet gap → the previous loop is gone. This poll is a fresh session.
+        pollerStopped = false;
+        lastStoppedPollAt = 0;
+        // fall through to normal handling below (counts as live again)
+      } else {
+        lastStoppedPollAt = now(); // a poller is still hammering us → hold the latch
+        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 /poller/start or a quiet gap
+      lastStoppedPollAt = 0;
       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 /poller/start or a quiet gap
+        lastStoppedPollAt = 0;
         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 +735,25 @@ 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 /poller/start or a quiet gap
+    lastStoppedPollAt = 0;
     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 would have to wait out the quiet window. Call it once at loop
+  // startup, before the first GET /jobs/next.
+  if (method === "POST" && path === "/poller/start") {
+    pollerStopped = false;
+    lastStoppedPollAt = 0;
+    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]);