transitions-refine 0.3.19 → 0.3.20

package/bin/cli.mjs

@@ -23,7 +23,8 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, realpathSyn
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
-import { get as httpGet } from "node:http";
+import { get as httpGet, request as httpRequest } from "node:http";
+import { AGENTS, findBin, resolveAgentCmd } from "../server/agent-resolve.mjs";
 
 const PKG_ROOT = fileURLToPath(new URL("..", import.meta.url));
 const CWD = process.cwd();
@@ -121,82 +122,9 @@ function dropSkill(name) {
 // prompt, stdout = JSON). To bill against the account the user ALREADY pays for,
 // we detect which agent is hosting this run and wire ITS CLI: a Claude Code user
 // gets `claude`, a Codex user gets `codex`, a Cursor user gets `cursor-agent`.
-// Detection is by each host's env markers; override with --agent <name> or by
-// exporting REFINE_AGENT_CMD yourself.
-const envHasPrefix = (p) => Object.keys(process.env).some((k) => k.startsWith(p));
-
-const AGENTS = [
-  {
-    key: "cursor",
-    label: "Cursor",
-    // Cursor's agent terminal exports CURSOR_AGENT.
-    host: () => Boolean(process.env.CURSOR_AGENT),
-    bins: [
-      "cursor-agent",
-      join(HOME, ".local/bin/cursor-agent"),
-      join(HOME, ".cursor/bin/cursor-agent"),
-    ],
-    // -p = headless/stdin, --force = auto-allow tool calls. The relay also
-    // auto-appends -p/--trust/--force for cursor-agent; we wire them up front so
-    // the printed command is the real one.
-    cmd: (bin) => `${bin} -p --force`,
-    canInstall: true,
-    auth: "run `cursor-agent` once to log in, or set CURSOR_API_KEY",
-  },
-  {
-    key: "claude",
-    label: "Claude Code",
-    // Claude Code exports CLAUDECODE=1 (+ CLAUDE_CODE_*) in its tools/terminals.
-    host: () => Boolean(process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT),
-    bins: [
-      "claude",
-      join(HOME, ".claude/local/claude"),
-      join(HOME, ".local/bin/claude"),
-    ],
-    // -p = headless print (prompt on stdin); skip-permissions so apply jobs can
-    // edit files without an interactive approval prompt.
-    cmd: (bin) => `${bin} -p --dangerously-skip-permissions`,
-    canInstall: false,
-    auth: "run `claude` once to sign in",
-  },
-  {
-    key: "codex",
-    label: "Codex",
-    // Codex exec exports CODEX_SANDBOX (+ CODEX_* friends) in its sandbox.
-    host: () => Boolean(process.env.CODEX_SANDBOX) || envHasPrefix("CODEX_"),
-    bins: ["codex", join(HOME, ".local/bin/codex")],
-    // `codex exec -` reads the prompt on stdin; workspace-write so apply jobs can
-    // edit files; skip-git-repo-check so a non-git project root doesn't error out.
-    cmd: (bin) => `${bin} exec --sandbox workspace-write --skip-git-repo-check -`,
-    canInstall: false,
-    auth: "run `codex` once to sign in, or set CODEX_API_KEY",
-  },
-];
-
-// Host-detection precedence. Claude/Codex export very specific markers; check
-// them BEFORE Cursor so a Claude Code or Codex session launched from inside a
-// Cursor terminal (which still carries CURSOR_*) is not mis-wired to cursor-agent.
-const HOST_PRECEDENCE = ["claude", "codex", "cursor"];
-
-function isRunnable(bin) {
-  try {
-    return spawnSync(bin, ["--version"], { stdio: "ignore" }).status === 0;
-  } catch {
-    return false;
-  }
-}
-
-function findBin(agent) {
-  return agent.bins.find(isRunnable) || null;
-}
-
-function detectHostAgent() {
-  for (const key of HOST_PRECEDENCE) {
-    const a = AGENTS.find((x) => x.key === key);
-    if (a && a.host()) return a;
-  }
-  return null;
-}
+// The agent table + (pure) detection live in server/agent-resolve.mjs, shared
+// with the relay so it can re-check and self-heal at runtime; the CLI only adds
+// the one thing the relay must not do — install the Cursor CLI.
 
 // Install the Cursor CLI (the only agent we can fetch non-interactively).
 function installCursorCli() {
@@ -215,50 +143,19 @@ function installCursorCli() {
   return findBin(AGENTS[0]);
 }
 
-// Decide which agent CLI the relay should spawn. Returns either
+// Decide which agent CLI the relay should spawn. Pure resolution is shared with
+// the relay (resolveAgentCmd); the CLI layers on the one side-effecting step the
+// relay must never do — installing the Cursor CLI when --llm is passed and
+// nothing else is available. Returns:
 //   { cmd, agent, source }          → wire this command (persistent LLM), or
 //   { cmd:null, agent?, reason }    → couldn't wire; caller prints guidance.
-// Precedence: explicit REFINE_AGENT_CMD → --agent <key> → host agent (same
-// subscription) → any installed agent → (with --llm) install cursor-agent.
 function resolveAgent({ wantLlm, forceKey }) {
-  if (process.env.REFINE_AGENT_CMD) {
-    return { cmd: process.env.REFINE_AGENT_CMD, source: "env" };
-  }
-
-  let target = null;
-  if (forceKey) {
-    target = AGENTS.find((a) => a.key === forceKey) || null;
-    if (!target) {
-      return { cmd: null, reason: `unknown --agent "${forceKey}" (use cursor | claude | codex)` };
-    }
-  }
-  if (!target) target = detectHostAgent();
-
-  if (target) {
-    let bin = findBin(target);
-    if (!bin && target.canInstall && wantLlm) bin = installCursorCli();
-    if (bin) return { cmd: target.cmd(bin), agent: target, source: forceKey ? "forced" : "host" };
-    return {
-      cmd: null,
-      agent: target,
-      reason:
-        `detected ${target.label} but its CLI isn't on PATH` +
-        (target.canInstall ? " — re-run with --llm to install it" : ` — install the ${target.label} CLI first`),
-    };
-  }
-
-  // No host detected (plain terminal): use any installed agent, in list order.
-  for (const a of AGENTS) {
-    const bin = findBin(a);
-    if (bin) return { cmd: a.cmd(bin), agent: a, source: "scan" };
-  }
-
-  // Nothing installed: only cursor-agent can be fetched non-interactively.
-  if (wantLlm) {
-    const bin = installCursorCli();
-    if (bin) return { cmd: AGENTS[0].cmd(bin), agent: AGENTS[0], source: "install" };
-  }
-  return { cmd: null, reason: "no agent CLI found" };
+  const r = resolveAgentCmd({ forceKey });
+  if (r.cmd || !wantLlm || !r.needsInstall) return r;
+  // wantLlm + the only fetchable CLI (cursor-agent) is missing → install it.
+  const bin = installCursorCli();
+  if (bin) return { cmd: AGENTS[0].cmd(bin), agent: AGENTS[0], source: "install" };
+  return r;
 }
 
 function log(msg) {
@@ -304,6 +201,47 @@ async function waitForHealth(port, totalMs = 6000) {
   return false;
 }
 
+// GET /health → parsed JSON, or null if unreachable / unparsable.
+function getHealth(port, timeoutMs = 800) {
+  return new Promise((resolveJson) => {
+    let done = false, body = "";
+    const finish = (v) => { if (!done) { done = true; resolveJson(v); } };
+    const req = httpGet({ host: "127.0.0.1", port: Number(port), path: "/health", timeout: timeoutMs }, (res) => {
+      if (res.statusCode < 200 || res.statusCode >= 500) { res.resume(); return finish(null); }
+      res.setEncoding("utf8");
+      res.on("data", (d) => (body += d));
+      res.on("end", () => { try { finish(JSON.parse(body)); } catch { finish(null); } });
+    });
+    req.on("timeout", () => { req.destroy(); finish(null); });
+    req.on("error", () => finish(null));
+  });
+}
+
+// Best-effort POST (no body). Resolves true on a 2xx.
+function postRelay(port, path, timeoutMs = 1500) {
+  return new Promise((resolveOk) => {
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolveOk(v); } };
+    const req = httpRequest({ host: "127.0.0.1", port: Number(port), path, method: "POST", timeout: timeoutMs }, (res) => {
+      res.resume();
+      finish(res.statusCode >= 200 && res.statusCode < 300);
+    });
+    req.on("timeout", () => { req.destroy(); finish(false); });
+    req.on("error", () => finish(false));
+    req.end();
+  });
+}
+
+// Wait until nothing answers on the port (a replaced relay has fully exited).
+async function waitForPortFree(port, totalMs = 4000) {
+  const deadline = Date.now() + totalMs;
+  while (Date.now() < deadline) {
+    if (!(await httpOk(port))) return true;
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  return false;
+}
+
 // Kill a previously-detached relay for this project (best effort).
 function stopDaemon({ silent = false } = {}) {
   let rec = null;
@@ -370,6 +308,20 @@ async function cmdLive(args) {
   const port = String(args.port || process.env.REFINE_RELAY_PORT || 7331);
   const page = findPage(args.page);
 
+  // 0) reconcile any relay already on this port. A stale, OLDER-version relay is
+  //    the classic "I updated but nothing changed" trap — npx serves a cached
+  //    build, or an old daemon lingers. Replace it so `live` always converges to
+  //    THIS version (and picks up fixes like agent self-heal).
+  const existing = await getHealth(port);
+  if (existing && existing.version && existing.version !== PKG_VERSION) {
+    log(`• replacing a stale relay on :${port} (v${existing.version} → v${PKG_VERSION})`);
+    await postRelay(port, "/shutdown");
+    stopDaemon({ silent: true });
+    if (!(await waitForPortFree(port))) {
+      log(`! the old relay on :${port} didn't exit — you may need to kill it manually.`);
+    }
+  }
+
   // 1) inject the script tag
   if (page) {
     injectTag(page, port);
@@ -397,6 +349,8 @@ async function cmdLive(args) {
   const wantLlm = Boolean(args.llm);
   const forceKey = typeof args.agent === "string" ? args.agent : null;
   const env = { ...process.env, REFINE_RELAY_PORT: port };
+  // Pass a forced --agent through so the relay's runtime self-heal honors it too.
+  if (forceKey) env.REFINE_AGENT = forceKey;
   const resolved = resolveAgent({ wantLlm, forceKey });
   if (resolved.cmd) {
     env.REFINE_AGENT_CMD = resolved.cmd;
@@ -532,4 +486,5 @@ if (isCliEntry()) {
   });
 }
 
-export { AGENTS, HOST_PRECEDENCE, detectHostAgent, resolveAgent, findBin };
+export { resolveAgent };
+export { AGENTS, HOST_PRECEDENCE, detectHostAgent, findBin } from "../server/agent-resolve.mjs";

package/demo.html

@@ -1399,6 +1399,22 @@
     .tl-gate-text { margin: 4px 0 0; max-width: 250px; font-size: 13px; font-weight: 400; line-height: 21px;
       color: #676767; text-wrap: pretty; }
     .tl-gate-text .tl-code { color: #4b4b4b; }
+    /* The relay's reason for not wiring a CLI (so a silent poller fallback is never
+       a mystery), plus a Reconnect that forces an immediate agent re-check. */
+    .tl-gate-reason { margin: 10px 0 0; max-width: 260px; font-size: 12px; line-height: 18px;
+      color: #9a9a9a; text-wrap: pretty; }
+    .tl-gate-recheck { margin-top: 12px; padding: 5px 12px; font: inherit; font-size: 12px; font-weight: 500;
+      color: #4b4b4b; background: rgba(0, 0, 0, 0.04); border: 1px solid rgba(0, 0, 0, 0.08);
+      border-radius: 8px; cursor: pointer;
+      transition: background 150ms ease-out, border-color 150ms ease-out, opacity 150ms ease-out; }
+    .tl-gate-recheck:hover { background: rgba(0, 0, 0, 0.07); border-color: rgba(0, 0, 0, 0.12); }
+    .tl-gate-recheck:disabled { opacity: 0.55; cursor: default; }
+    html[data-theme="dark"] .tl-gate-reason { color: #7e7e7e; }
+    html[data-theme="dark"] .tl-gate-recheck { color: #d4d4d4; background: rgba(255, 255, 255, 0.06);
+      border-color: rgba(255, 255, 255, 0.12); }
+    html[data-theme="dark"] .tl-gate-recheck:hover { background: rgba(255, 255, 255, 0.1);
+      border-color: rgba(255, 255, 255, 0.16); }
+    @media (prefers-reduced-motion: reduce) { .tl-gate-recheck { transition: none; } }
     @media (prefers-reduced-motion: reduce) {
       .tl-gate { animation: none !important; } }
     /* dot-matrix loader — ported from @dotmatrix/dotm-square-14
@@ -2473,6 +2489,14 @@
       if(!r.ok) throw new Error("relay POST /poller/stop failed ("+r.status+")");
       return r.json();
     }
+    // Ask the relay to re-resolve its agent CLI right now (bypassing its TTL).
+    // Backs the "Reconnect" affordance after the user installs / logs into a CLI.
+    async function relayRecheck(){
+      if(TX_MOCK) return { ok:true, agentCmd:true };
+      const r = await fetch(RELAY_URL+"/agent/recheck",{method:"POST"});
+      if(!r.ok) throw new Error("relay POST /agent/recheck failed ("+r.status+")");
+      return r.json();
+    }
 
     const REFINE_MODES=[
       {key:"llm",label:"Agent",desc:"Suggested edits from the agent using the Transitions.dev skill."},
@@ -2662,18 +2686,31 @@
     // Shared "Connect with your agent" copy — used by the full-panel gate and by
     // the Refine area when no live agent is connected, so both read identically.
     // `cliMissing` swaps the body to an install-first hint.
-    function AgentConnectBody({cliMissing}){
-      return cliMissing
-        ? h("p",{className:"tl-gate-text"},"Install an agent CLI, then run ",
-            h("code",{className:"tl-code"},"npx transitions-refine live"),
-            " (recommended) or ",h("code",{className:"tl-code"},"/refine live")," in your editor.")
-        : h("p",{className:"tl-gate-text"},
-            "Run ",h("code",{className:"tl-code"},"npx transitions-refine live"),
-            " in your project to start the relay with a persistent agent — works for hours, no chat loop. Or run ",
-            h("code",{className:"tl-code"},"/refine live"),
-            " in your editor if the relay is already up without an agent wired.");
+    function AgentConnectBody({cliMissing,reason,onReconnect}){
+      const[rechecking,setRechecking]=useState(false);
+      const recheck=async()=>{
+        if(!onReconnect||rechecking) return;
+        setRechecking(true);
+        try{ await onReconnect(); } finally { setRechecking(false); }
+      };
+      return h(React.Fragment,null,
+        cliMissing
+          ? h("p",{className:"tl-gate-text"},"Install an agent CLI, then run ",
+              h("code",{className:"tl-code"},"npx transitions-refine live"),
+              " (recommended) or ",h("code",{className:"tl-code"},"/refine live")," in your editor.")
+          : h("p",{className:"tl-gate-text"},
+              "Run ",h("code",{className:"tl-code"},"npx transitions-refine live"),
+              " in your project to start the relay with a persistent agent — works for hours, no chat loop. Or run ",
+              h("code",{className:"tl-code"},"/refine live"),
+              " in your editor if the relay is already up without an agent wired."),
+        // Surface WHY the relay couldn't wire a CLI (from /health agentReason) so a
+        // silent fall-back to poller mode is never a mystery. The relay self-heals
+        // on a TTL; Reconnect just forces an immediate re-check.
+        reason&&h("p",{className:"tl-gate-reason"},reason),
+        onReconnect&&h("button",{className:"tl-gate-recheck",disabled:rechecking,onClick:recheck},
+          rechecking?"Reconnecting…":"Reconnect agent"));
     }
-    function RefinePanel({open,onClose,phase,label,refineType,onType,suggestions,summary,error,appliedIds,onApply,onApplyAll,mode,onMode,llmAvailable,cliInstalled,onStart,lanes}){
+    function RefinePanel({open,onClose,phase,label,refineType,onType,suggestions,summary,error,appliedIds,onApply,onApplyAll,mode,onMode,llmAvailable,cliInstalled,agentReason,onReconnect,onStart,lanes}){
       // mount-on-open; keep mounted through the panel-reveal slide-out, then unmount
       const[render,setRender]=useState(open);
       const[panelOpen,setPanelOpen]=useState(false);
@@ -2783,7 +2820,7 @@
           // /refine live makes the agent available and Start scanning works again.
           return h("div",{className:"tl-refine-center"},
             h("div",{className:"tl-refine-unavail-title"},"Connect with your agent"),
-            h(AgentConnectBody,{cliMissing:cliInstalled===false}));
+            h(AgentConnectBody,{cliMissing:cliInstalled===false,reason:agentReason,onReconnect}));
         }
         const idleDescR = agentMode ? (REFINE_TYPES.find(t=>t.key===rt)||REFINE_TYPES[0]).desc : (rt==="replace"
           ? "Deterministic mode can't pick a recipe to replace the transition — switch to Agent mode for replacements."
@@ -3774,6 +3811,7 @@
       const[refineType,setRefineType]=useState("small"); // small | replace
       const[llmAvailable,setLlmAvailable]=useState(null); // null=unknown, true/false from /health
       const[cliInstalled,setCliInstalled]=useState(null); // null=unknown, true/false from /health
+      const[agentReason,setAgentReason]=useState(null); // why no CLI is wired (/health agentReason)
       // chatLoop = LLM served by the in-chat `/refine live` poll loop (pollerActive
       // and no wired REFINE_AGENT_CMD). This is the mode that bills agent turns
       // while idle, so the header shows a credit warning + Stop for it.
@@ -3797,6 +3835,7 @@
       const refreshHealth=useCallback(async()=>{
         try{const j=await relayHealth();setLlmAvailable(!!j.llmAvailable);
           setCliInstalled(j.cliInstalled==null?null:!!j.cliInstalled);
+          setAgentReason(j.agentReason||null);
           const loop=!!j.pollerActive&&!j.agentCmd;
           if(!stopPendingRef.current){chatLoopRef.current=loop;setChatLoop(loop);setLiveStopped(false);return j;}
           if(!j.pollerActive)sawPollerGoneRef.current=true;
@@ -3814,6 +3853,12 @@
         try{await relayStopLive();}catch{}
         refreshHealth();
       },[refreshHealth]);
+      // Force the relay to re-resolve its agent CLI now, then refresh health so the
+      // panel reflects a just-installed / just-logged-in agent without waiting.
+      const reconnectAgent=useCallback(async()=>{
+        try{await relayRecheck();}catch{}
+        await refreshHealth();
+      },[refreshHealth]);
       // Quiet auto-stop after the one-time grouping scan: in chat-loop mode the
       // loop has done its only needed job (the scan), so stop it to avoid idle
       // credit burn. Drains like a normal stop but shows no chip; the Refine area
@@ -4529,13 +4574,13 @@
             h(RefinePanel,{open:refineOpen,onClose:()=>setRefineOpen(false),phase:refinePhase,label:refineLabel,
               refineType,onType:changeRefineType,suggestions:refineSuggestions,summary:refineSummary,error:refineError,
               appliedIds,onApply:applySuggestion,onApplyAll:applyAllSuggestions,
-                    mode:refineMode,onMode:changeRefineMode,llmAvailable,cliInstalled,onStart:startScan,
+                    mode:refineMode,onMode:changeRefineMode,llmAvailable,cliInstalled,agentReason,onReconnect:reconnectAgent,onStart:startScan,
                     lanes:active?.effectiveTimings||[]}))
               : h("div",{className:"tl-panel-main"},
                   gate==="blocked" && h("div",{className:"tl-gate"},
                     h("div",{className:"tl-gate-col"},
                       h("div",{className:"tl-gate-title"},"Connect with your agent"),
-                      h(AgentConnectBody,{cliMissing:cliInstalled===false})))),
+                      h(AgentConnectBody,{cliMissing:cliInstalled===false,reason:agentReason,onReconnect:reconnectAgent})))),
             toast&&createPortal(
               h("div",{className:"tl-toast-wrap","data-tl-ui":"","aria-live":"polite"},
                 h("div",{className:cx("tl-toast",toast.closing&&"is-closing")},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transitions-refine",
-  "version": "0.3.19",
+  "version": "0.3.20",
   "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/agent-resolve.mjs

@@ -0,0 +1,141 @@
+// Shared agent-CLI resolution, used by BOTH:
+//   • bin/cli.mjs  — once, at `npx transitions-refine live` (may also install).
+//   • server/relay.mjs — repeatedly, at runtime, so the relay SELF-HEALS: if no
+//     agent was wired at boot (CLI not on PATH yet, not logged in, a startup
+//     race) the relay re-checks and auto-wires the moment one becomes available,
+//     instead of being stuck in /refine-live poller mode for its whole life.
+//
+// Everything here is PURE: detection by host env markers + a PATH scan, with no
+// install and no logging, so the relay can call it on a short TTL with no side
+// effects. Installation (Cursor CLI) stays in the CLI, which owns user prompts.
+
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const HOME = process.env.HOME || homedir();
+const envHasPrefix = (p, env) => Object.keys(env).some((k) => k.startsWith(p));
+
+// The agent CLIs we know how to drive headlessly. `host(env)` detects the agent
+// HOSTING this run (so Refine bills the subscription the user already has);
+// `bins` are probed in order; `cmd(bin)` builds the headless invocation.
+export const AGENTS = [
+  {
+    key: "cursor",
+    label: "Cursor",
+    host: (env) => Boolean(env.CURSOR_AGENT),
+    bins: [
+      "cursor-agent",
+      join(HOME, ".local/bin/cursor-agent"),
+      join(HOME, ".cursor/bin/cursor-agent"),
+    ],
+    cmd: (bin) => `${bin} -p --force`,
+    canInstall: true,
+    auth: "run `cursor-agent` once to log in, or set CURSOR_API_KEY",
+  },
+  {
+    key: "claude",
+    label: "Claude Code",
+    host: (env) => Boolean(env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT),
+    bins: [
+      "claude",
+      join(HOME, ".claude/local/claude"),
+      join(HOME, ".local/bin/claude"),
+    ],
+    cmd: (bin) => `${bin} -p --dangerously-skip-permissions`,
+    canInstall: false,
+    auth: "run `claude` once to sign in",
+  },
+  {
+    key: "codex",
+    label: "Codex",
+    host: (env) => Boolean(env.CODEX_SANDBOX) || envHasPrefix("CODEX_", env),
+    bins: ["codex", join(HOME, ".local/bin/codex")],
+    cmd: (bin) => `${bin} exec --sandbox workspace-write --skip-git-repo-check -`,
+    canInstall: false,
+    auth: "run `codex` once to sign in, or set CODEX_API_KEY",
+  },
+];
+
+// Host-detection precedence. Claude/Codex export very specific markers; check
+// them BEFORE Cursor so a Claude Code or Codex session launched from inside a
+// Cursor terminal (which still carries CURSOR_*) is not mis-wired to cursor-agent.
+export const HOST_PRECEDENCE = ["claude", "codex", "cursor"];
+
+// A bare `cursor-agent` goes interactive ("⚠ Workspace Trust Required", exit 1)
+// and `codex exec` needs a trailing `-` to read the prompt from stdin. Normalise
+// an externally-provided REFINE_AGENT_CMD so headless jobs don't silently fail.
+export function augmentAgentCmd(cmd) {
+  if (!cmd) return cmd;
+  if (/(^|\s|\/)codex(\s|$)/.test(cmd) && /(^|\s)exec(\s|$)/.test(cmd)) {
+    return /(^|\s)-(\s|$)/.test(cmd) ? cmd : `${cmd} -`;
+  }
+  if (!/(^|\s|\/)cursor-agent(\s|$)/.test(cmd)) return cmd;
+  const has = (...flags) =>
+    flags.some((f) => new RegExp(`(^|\\s)${f.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\s|$)`).test(cmd));
+  const extra = [];
+  if (!has("-p", "--print")) extra.push("-p");
+  if (!has("--trust")) extra.push("--trust");
+  if (!has("-f", "--force", "--yolo")) extra.push("--force");
+  return extra.length ? `${cmd} ${extra.join(" ")}` : cmd;
+}
+
+export function isRunnable(bin) {
+  try {
+    return spawnSync(bin, ["--version"], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function findBin(agent) {
+  return agent.bins.find(isRunnable) || null;
+}
+
+export function detectHostAgent(env = process.env) {
+  for (const key of HOST_PRECEDENCE) {
+    const a = AGENTS.find((x) => x.key === key);
+    if (a && a.host(env)) return a;
+  }
+  return null;
+}
+
+// Pure resolution — no install, no logging. Returns one of:
+//   { cmd, agent, source }                       → wire this command, or
+//   { cmd:null, agent?, reason, needsInstall? }   → couldn't wire (caller decides
+//                                                    whether to install / surface).
+// Precedence: explicit REFINE_AGENT_CMD → forced key → host agent → PATH scan.
+export function resolveAgentCmd({ env = process.env, forceKey = null } = {}) {
+  if (env.REFINE_AGENT_CMD) {
+    return { cmd: augmentAgentCmd(env.REFINE_AGENT_CMD), source: "env" };
+  }
+
+  let target = null;
+  if (forceKey) {
+    target = AGENTS.find((a) => a.key === forceKey) || null;
+    if (!target) {
+      return { cmd: null, reason: `unknown agent "${forceKey}" (use cursor | claude | codex)` };
+    }
+  }
+  if (!target) target = detectHostAgent(env);
+
+  if (target) {
+    const bin = findBin(target);
+    if (bin) return { cmd: target.cmd(bin), agent: target, source: forceKey ? "forced" : "host" };
+    return {
+      cmd: null,
+      agent: target,
+      needsInstall: target.canInstall,
+      reason:
+        `detected ${target.label} but its CLI isn't on PATH` +
+        (target.canInstall ? " — re-run with --llm to install it" : ` — install the ${target.label} CLI first`),
+    };
+  }
+
+  for (const a of AGENTS) {
+    const bin = findBin(a);
+    if (bin) return { cmd: a.cmd(bin), agent: a, source: "scan" };
+  }
+
+  return { cmd: null, reason: "no agent CLI found", needsInstall: true };
+}

package/server/relay.mjs

@@ -30,6 +30,7 @@ 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";
 import { buildInjectModule } from "./inject.mjs";
+import { resolveAgentCmd } from "./agent-resolve.mjs";
 
 const PORT = Number(process.env.REFINE_RELAY_PORT) || 7331;
 const AUTO = process.env.REFINE_AUTO !== "0";
@@ -40,30 +41,33 @@ 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
-// trio whenever the command is cursor-agent: -p (print/headless, reads the prompt
-// from stdin), --trust (trust the workspace without prompting; only valid with
-// --print), and --force (auto-allow tool calls so apply/scan don't hang on
-// approval). Append only the missing flags; leave non-cursor-agent commands alone.
-function augmentAgentCmd(cmd) {
-  if (!cmd) return cmd;
-  // `codex exec` reads the prompt from stdin ONLY when given a trailing `-`
-  // (the stdin marker). The relay always pipes the prompt on stdin, so without
-  // it Codex gets no prompt and exits 1. Append `-` when it's missing (a lone
-  // `-` token, not the dashes inside flags like `--sandbox`).
-  if (/(^|\s|\/)codex(\s|$)/.test(cmd) && /(^|\s)exec(\s|$)/.test(cmd)) {
-    return /(^|\s)-(\s|$)/.test(cmd) ? cmd : `${cmd} -`;
+// Self-healing agent wiring. Instead of freezing the agent at boot — which left
+// the relay stuck in /refine-live poller mode for its whole life if the CLI
+// wasn't runnable at that one instant (not logged in yet, not on PATH, a startup
+// race) — we re-resolve via the shared resolver on a short TTL. The moment an
+// agent CLI becomes available, the relay wires it; if one disappears, it unwires.
+// An explicit REFINE_AGENT_CMD still wins and is effectively pinned (the resolver
+// short-circuits on it). REFINE_AGENT carries a forced --agent choice from the CLI.
+const FORCE_AGENT = process.env.REFINE_AGENT || null;
+const AGENT_RECHECK_MS = Number(process.env.REFINE_AGENT_RECHECK_MS) || 5000;
+let _agent = { at: 0, cmd: null, source: null, reason: null, label: null };
+function agentInfo(force = false) {
+  if (force || _agent.at === 0 || now() - _agent.at >= AGENT_RECHECK_MS) {
+    const r = resolveAgentCmd({ forceKey: FORCE_AGENT });
+    const prev = _agent.cmd;
+    _agent = {
+      at: now(),
+      cmd: r.cmd || null,
+      source: r.source || null,
+      reason: r.reason || null,
+      label: (r.agent && r.agent.label) || null,
+    };
+    if (r.cmd && r.cmd !== prev) console.log(`✓ agent wired${r.source ? ` (${r.source})` : ""}: ${r.cmd}`);
+    else if (!r.cmd && prev) console.log(`• agent unwired — ${r.reason || "no agent CLI"}`);
   }
-  if (!/(^|\s|\/)cursor-agent(\s|$)/.test(cmd)) return cmd;
-  const has = (...flags) => flags.some((f) => new RegExp(`(^|\\s)${f.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\s|$)`).test(cmd));
-  const extra = [];
-  if (!has("-p", "--print")) extra.push("-p");
-  if (!has("--trust")) extra.push("--trust");
-  if (!has("-f", "--force", "--yolo")) extra.push("--force");
-  return extra.length ? `${cmd} ${extra.join(" ")}` : cmd;
+  return _agent;
 }
-const AGENT_CMD = augmentAgentCmd(process.env.REFINE_AGENT_CMD || null);
+const agentCmd = () => agentInfo().cmd;
 // Pin a fast model for scan jobs. Grouping is a structured task that doesn't
 // need a heavy reasoning model, and the user's *default* model may be a slow one
 // (Opus / GPT-5.5) — forcing a fast model here keeps the initial scan snappy.
@@ -160,7 +164,7 @@ let pollerStopped = false;
 // 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();
+const llmAvailable = () => Boolean(agentCmd()) || pollerActive();
 
 // Stop signal for the in-chat `/refine live` loop. Set by POST /poller/stop
 // (the panel's "Stop" button) or by the idle auto-stop; consumed by the next
@@ -181,7 +185,7 @@ const AGENT_BIN_CANDIDATES = [
   "/opt/homebrew/bin/cursor-agent",
 ];
 function cursorCliInstalled() {
-  if (AGENT_CMD) return true;
+  if (agentCmd()) return true;
   for (const p of AGENT_BIN_CANDIDATES) {
     try { if (existsSync(p)) return true; } catch {}
   }
@@ -547,6 +551,9 @@ function refineDeterministic(job) {
 async function answerJob(job) {
   job.status = "working";
   job.updatedAt = now();
+  // Snapshot the current wiring once for this job (the resolver is self-healing
+  // on a TTL; capturing avoids a mid-job change between the guard and the spawn).
+  const AGENT_CMD = agentCmd();
   const isApply = job.request?.kind === "apply";
   const isScan = job.request?.kind === "scan";
   const label = job.request?.label || job.request?.selector || "transition";
@@ -659,6 +666,7 @@ const server = createServer(async (req, res) => {
   if (method === "OPTIONS") return send(res, 204);
 
   if (method === "GET" && path === "/health") {
+    const ai = agentInfo();
     return send(res, 200, {
       ok: true,
       version: PKG_VERSION,
@@ -666,7 +674,12 @@ const server = createServer(async (req, res) => {
       llmAvailable: llmAvailable(),
       pollerActive: pollerActive(),
       pollerStopped,
-      agentCmd: Boolean(AGENT_CMD),
+      agentCmd: Boolean(ai.cmd),
+      // Why LLM mode isn't wired by a spawned CLI (panel surfaces this + offers a
+      // Reconnect that POSTs /agent/recheck). null when an agent IS wired.
+      agentSource: ai.source,
+      agentLabel: ai.label,
+      agentReason: ai.cmd ? null : ai.reason,
       cliInstalled: cursorCliInstalled(),
       jobs: jobs.size,
     });
@@ -704,7 +717,7 @@ const server = createServer(async (req, res) => {
       // External-poller-only mode: everything waits on GET /jobs/next.
     } else if (mode === "deterministic") {
       setImmediate(() => answerJob(job)); // in-process, off the response path
-    } else if (AGENT_CMD) {
+    } else if (agentCmd()) {
       setImmediate(() => answerJob(job)); // spawn the configured CLI once
     } else if (pollerActive()) {
       // A `/refine live` agent is polling — leave it pending for them to claim.
@@ -790,6 +803,23 @@ const server = createServer(async (req, res) => {
     return send(res, 200, { ok: true, stopping: wasActive });
   }
 
+  // POST /shutdown — let the CLI replace a stale relay cleanly. `live` calls this
+  // when it finds an older-version relay on the port (the npx-cache / lingering-
+  // daemon trap) so a re-run always converges to the current build.
+  if (method === "POST" && path === "/shutdown") {
+    send(res, 200, { ok: true, version: PKG_VERSION });
+    setTimeout(() => process.exit(0), 50);
+    return;
+  }
+
+  // POST /agent/recheck — force an immediate agent re-resolve, bypassing the TTL.
+  // Backs the panel's "Reconnect" affordance: after the user installs / logs into
+  // a CLI, this wires it right away instead of waiting out the recheck interval.
+  if (method === "POST" && path === "/agent/recheck") {
+    const ai = agentInfo(true);
+    return send(res, 200, { ok: true, agentCmd: Boolean(ai.cmd), agentLabel: ai.label, agentReason: ai.cmd ? null : ai.reason });
+  }
+
   // 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
@@ -861,11 +891,13 @@ const server = createServer(async (req, res) => {
 server.listen(PORT, () => {
   console.log(`refine relay listening on http://localhost:${PORT}`);
   console.log(`  timeline injectable at  http://localhost:${PORT}/inject.js`);
+  const ai = agentInfo();
   if (!AUTO) {
     console.log("  auto-answer OFF (REFINE_AUTO=0) — all jobs wait for a poller on GET /jobs/next");
-  } else if (AGENT_CMD) {
-    console.log(`  LLM jobs answered by spawning: ${AGENT_CMD}`);
+  } else if (ai.cmd) {
+    console.log(`  LLM jobs answered by spawning: ${ai.cmd}`);
   } else {
+    console.log(`  no agent CLI wired yet (${ai.reason || "none found"}) — re-checking every ${Math.round(AGENT_RECHECK_MS / 1000)}s.`);
     console.log("  LLM jobs wait for a live agent — run `/refine live` in Cursor/Codex.");
     console.log(`  live agent stays 'available' for ${Math.round(POLLER_TTL_MS / 1000)}s after its last poll.`);
     console.log("  Deterministic jobs answered in-process (nearest motion token).");