@engine-room/after-effects-mcp 0.5.1 → 0.6.0

package/panel/client/main.js

@@ -23,12 +23,39 @@
   var $jsx = document.getElementById("jsx");
   var $reqs = document.getElementById("reqs");
   var $log = document.getElementById("log");
-  function setStatus(text, klass) {
-    $status.textContent = text;
-    $status.className = klass || "";
+  // The bridge runs as a hidden extension (issue #283), so this page's DOM is
+  // seen by nobody unless the manifest is flipped back to a visible Panel. What
+  // it shows is mirrored to the separate status panel (client/status.js) over
+  // a CEP event: the whole state, at most every 250ms, and at once when the
+  // status panel asks. The status panel never runs a bridge of its own.
+  // Event types are their own namespace, never an extension id.
+  var STATUS_EVENT = "games.engine-room.ae-mcp.event.status";
+  var STATUS_REQUEST = "games.engine-room.ae-mcp.event.status-request";
+  var mirror = { status: "", statusClass: "", port: "", portClass: "", ae: "", jsx: "", jsxClass: "", reqs: 0, log: [] };
+  var mirrorCs = null;
+  var mirrorTimer = null;
+  function publishNow() {
+    mirrorTimer = null;
+    if (!mirrorCs) return;
+    try {
+      var ev = new CSEvent(STATUS_EVENT, "APPLICATION");
+      ev.data = JSON.stringify(mirror);
+      mirrorCs.dispatchEvent(ev);
+    } catch (e) {}
+  }
+  function publish() {
+    if (mirrorCs && mirrorTimer === null) mirrorTimer = setTimeout(publishNow, 250);
   }
+  function setField(name, $el, text, klass) {
+    $el.textContent = text;
+    if (klass !== undefined) $el.className = klass;
+    mirror[name] = text;
+    if (klass !== undefined) mirror[name + "Class"] = klass;
+    publish();
+  }
+  function setStatus(text, klass) { setField("status", $status, text, klass || ""); }
   var __reqCount = 0;
-  function bumpReq() { __reqCount += 1; $reqs.textContent = String(__reqCount); }
+  function bumpReq() { __reqCount += 1; $reqs.textContent = String(__reqCount); mirror.reqs = __reqCount; publish(); }
   function log(level, msg) {
     var d = document.createElement("div");
     d.className = (level === "error" ? "err" : level === "warn" ? "warn" : "");
@@ -37,6 +64,9 @@
     $log.insertBefore(d, $log.firstChild);
     // Trim
     while ($log.childNodes.length > 80) $log.removeChild($log.lastChild);
+    mirror.log.unshift({ level: d.className, text: d.textContent });
+    if (mirror.log.length > 80) mirror.log.length = 80;
+    publish();
   }
 
   // CSInterface comes from the plain <script> tag before this one, so it needs
@@ -52,6 +82,13 @@
     cs = new CSInterface();
     extDir = cs.getSystemPath(SystemPath.EXTENSION);
     clientDir = path.join(extDir, "client");
+    // Only where CEP provides events: without them there is no status panel
+    // to tell, and nothing is scheduled.
+    if (window.__adobe_cep__ && window.__adobe_cep__.dispatchEvent && window.__adobe_cep__.addEventListener) {
+      mirrorCs = cs;
+      cs.addEventListener(STATUS_REQUEST, publishNow);
+      publish();
+    }
   } catch (e) {
     setStatus("cannot start — CSInterface is unavailable", "err");
     log("error", "new CSInterface() failed: " + e.message);
@@ -76,10 +113,9 @@
     }
   }
 
-  // The screenshot checks live in their own files so a Node test can require
-  // them without a DOM: there is no After Effects on a CI runner, and neither
-  // real image code nor stale-buffer bookkeeping should be written blind.
-  // Same failure discipline as ws above — say what is missing, name the fix.
+  // The panel's own modules live in their own files so a Node test can require
+  // them without a DOM. Same failure discipline as ws above — say what is
+  // missing, name the fix.
   //
   // The list is ordered by how much it is trusted, not by convenience.
   // clientDir comes from CSInterface and is what the shipped layout actually
@@ -100,45 +136,151 @@
     }
     throw new Error("could not load " + name + " from any of: " + failures.join("; "));
   }
-  var pngCodec, frameCacheModule, mogrtModule, contactSheetModule, frameReaderModule;
+  var panelHashModule;
   try {
-    pngCodec = requireSibling("pngcodec.js");
-    frameCacheModule = requireSibling("framecache.js");
-    mogrtModule = requireSibling("mogrt.js");
-    contactSheetModule = requireSibling("contactsheet.js");
-    frameReaderModule = requireSibling("framereader.js");
+    panelHashModule = requireSibling("panelhash.js");
   } catch (e) {
-    setStatus("cannot start — one of the panel's file-processing modules is missing", "err");
-    log("error", "loading the panel's file-processing modules from " + __dirname + " failed: " + e.message);
+    setStatus("cannot start — one of the panel's modules is missing", "err");
+    log("error", "loading the panel's modules from " + __dirname + " failed: " + e.message);
     log("error", "Quit After Effects, run the setup_panel tool, then reopen it.");
     return;
   }
-  var frameCache = frameCacheModule.createFrameCache();
+
+  // ---------- Which panel code is this? (issue #243) ----------
+  // Every file of this panel except bundle.jsx, hashed once, now: the files
+  // CEP loaded at launch are the ones this process runs until After Effects
+  // restarts, whatever setup_panel writes over them later. Reported on /health
+  // beside bundleHash, and the server's version gate needs both to match the
+  // panel it ships — bundleHash alone let a current bundle beside old client
+  // code through. The algorithm is panelhash.js, ported to the server as
+  // setup/panelHash.ts; the signature files a self-signed install adds are
+  // left out of both, so a signed install is a current install.
+  var loadedClientHash = panelHashModule.panelClientHash(extDir);
+  if (!loadedClientHash) log("warn", "could not hash the panel's own files in " + extDir + "; the MCP server cannot confirm this panel is current and will ask for it to be reinstalled");
 
   var bundlePath = path.join(extDir, "jsx", "bundle.jsx");
 
   // ---------- ExtendScript evalScript: serialized via Promise chain ----------
+  // `opts.gone`: asked when the call's turn comes, before anything is handed to
+  // After Effects. A reason (string) means the MCP server has already given up
+  // on the call — its deadline passed, or it closed the request — so the call
+  // is dropped instead of run late and out of order behind whatever held After
+  // Effects. A call already handed to evalScript is never touched. `opts.label`
+  // is the op, reported on /health while it runs (`evalBusy`); absent for the
+  // bundle load.
+  var DEADLINE_GRACE_MS = 1000;
+  // Milliseconds on a monotonic clock: no wall-clock change or sleep moves it.
+  function monoNow() {
+    if (typeof performance !== "undefined" && performance && typeof performance.now === "function") return performance.now();
+    if (typeof process !== "undefined" && process.hrtime) { var t = process.hrtime(); return t[0] * 1000 + t[1] / 1e6; }
+    return Date.now();
+  }
   var __evalChain = Promise.resolve();
-  function evalScript(script) {
+  var __evalPending = 0;
+  var __evalRunning = null;
+  function evalScript(script, opts) {
+    opts = opts || {};
+    __evalPending += 1;
     var p = __evalChain.then(function () {
+      // One turn of the event loop first, so Node reads the sockets that closed
+      // while ExtendScript held this thread — a request read only once AE let
+      // go may already have been abandoned — and `gone` sees it.
+      return opts.gone ? new Promise(function (r) { setTimeout(r, 0); }) : null;
+    }).then(function () {
+      var why = opts.gone ? opts.gone() : null;
+      if (why) {
+        var gone = new Error("dropped before it ran: " + why);
+        gone.code = "REQUEST_CLOSED";
+        throw gone;
+      }
       return new Promise(function (resolve, reject) {
+        __evalRunning = { op: opts.label || "script", since: Date.now() };
         cs.evalScript(script, function (raw) {
-          if (raw === "EvalScript error.") return reject(new Error("ExtendScript eval failed (syntax or runtime)"));
+          __evalRunning = null;
+          if (raw === "EvalScript error.") {
+            // The bundle load (no label) is a whole file, and there this
+            // answer is what a parse or runtime error in it looks like.
+            if (!opts.label) return reject(new Error("ExtendScript eval failed (syntax or runtime)"));
+            // An op is one fixed line whose own failures come back as JSON, so
+            // this bare answer is most often After Effects declining to run it
+            // while the user has it held. The server words it per op.
+            var refused = new Error("After Effects answered \"EvalScript error.\" for " + opts.label +
+              " — most often it declined to run it while busy (a dialog, a menu, a text edit, a preview " +
+              "or a render). Read back before re-sending.");
+            refused.code = "EVAL_SCRIPT_ERROR";
+            return reject(refused);
+          }
           resolve(raw);
         });
       });
     });
+    var settle = function () { __evalPending -= 1; };
+    p.then(settle, settle);
     // Keep the chain alive even on rejection so subsequent calls aren't blocked.
     __evalChain = p.catch(function () { return null; });
     return p;
   }
 
+  function evalBusyNow() {
+    return __evalRunning ? { op: __evalRunning.op, ms: Date.now() - __evalRunning.since } : null;
+  }
+
+  // ---------- The bundle's one global (issue #185) ----------
+  // After Effects runs every extension's evalScript, File > Scripts, ScriptUI
+  // panels and osascript in one shared ExtendScript engine. The bundle keeps
+  // everything in a closure and publishes only `__AEMCP` (scripts/bundle-jsx.mjs),
+  // so another script can no longer replace `dispatch` or `OPS` under us. It can
+  // still delete or overwrite `__AEMCP` itself, so every op checks it is ours
+  // first and answers NS_MISSING — before running anything — when it is not.
+  var NS_MISSING = "__AEMCP_MISSING__";
+  var NS_READY = "(typeof __AEMCP === 'object' && __AEMCP !== null && " +
+    "__AEMCP.id === 'games.engine-room.ae-mcp' && typeof __AEMCP.call === 'function')";
+
+  // U+2028 and U+2029 are legal raw inside JSON but are line terminators in an
+  // ES3 string literal, and JSON.stringify leaves them raw — so a text layer or
+  // run_jsx script containing one became an unterminated literal and the whole
+  // op died as "EvalScript error." (issue #163). Escaped in the JSON text, they
+  // survive both the literal and ExtendScript's JSON.parse as the same
+  // characters; the literal is escaped too, as a second line of defence.
+  function escapeLineSeparators(json) {
+    return json.replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+  }
+
+  function opScript(payload) {
+    // JSON.stringify on the panel side, JSON.parse on the ExtendScript side.
+    var literal = escapeLineSeparators(JSON.stringify(escapeLineSeparators(payload)));
+    return NS_READY + " ? __AEMCP.call(" + literal + ") : '" + NS_MISSING + "'";
+  }
+
+  // One reload for however many ops found the namespace gone at once.
+  var __healing = null;
+  function healNamespace(op) {
+    if (!__healing) {
+      log("warn", "__AEMCP is missing or not ours (another script in After Effects' shared engine " +
+        "replaced it) — reloading bundle.jsx before " + op);
+      __healing = loadJsxBundle({ sameAsRunning: true }).then(
+        function () { __healing = null; setStatus("ready", "ok"); },
+        function (e) { __healing = null; throw e; }
+      );
+    }
+    return __healing;
+  }
+
   // Run an op through the dispatch table. Returns parsed JS object.
-  function runOp(op, args) {
+  // `gone` (optional): see evalScript — the op is dropped unrun once it answers a reason.
+  function runOp(op, args, gone) {
     var payload = JSON.stringify({ op: op, args: args || {} });
-    // Use \uXXXX-safe JSON pass: JSON.stringify on the panel side, JSON.parse on ExtendScript side.
-    var script = "JSON.stringify(dispatch(" + JSON.stringify(payload) + "))";
-    return evalScript(script).then(function (raw) {
+    var evalOpts = { label: op, gone: gone };
+    return evalScript(opScript(payload), evalOpts).then(function (raw) {
+      if (raw !== NS_MISSING) return raw;
+      // Nothing ran: NS_MISSING is answered instead of the op, so sending it
+      // again after the reload cannot run it twice.
+      return healNamespace(op).then(function () { return evalScript(opScript(payload), evalOpts); });
+    }).then(function (raw) {
+      if (raw === NS_MISSING) {
+        throw new Error("The AE MCP bundle is not loaded in After Effects (__AEMCP missing even after reloading " +
+          "bundle.jsx). Nothing ran. Restart After Effects.");
+      }
       if (raw === "undefined" || raw === undefined || raw === null) {
         throw new Error("ExtendScript returned undefined for op " + op);
       }
@@ -161,7 +303,12 @@
             sourceText: parsed.sourceText,
             sourceName: parsed.sourceName,
             rawLine: parsed.rawLine,
-            lineCount: parsed.lineCount
+            lineCount: parsed.lineCount,
+            // `_run_jsx` (stage 6) leaves the mapping to the server and sends
+            // these instead. Absent on every other failure, and JSON drops an
+            // undefined, so they never reach the server unless they were set.
+            wrapperLine: parsed.wrapperLine,
+            libraryIndex: parsed.libraryIndex
           };
         }
         throw err;
@@ -170,6 +317,25 @@
     });
   }
 
+  // ---------- What this panel supports ----------
+  // Reported on /health as `capabilities` (issue #220). Since issue #243 the
+  // server has no other path for any of these, and its version gate refuses a
+  // panel that is not the one it ships; the list is what that gate falls back
+  // on when it has no shipped panel to hash, so it must name everything the
+  // server relies on:
+  //   project-path — `_project_path` answers the .aep's path with no project
+  //                  walk, so the server reads and writes house-style.md itself.
+  //   server-images — `_screenshot_frame`, `_screenshot_layer` and
+  //                  `_export_mogrt` reach the bundle untouched and answer with
+  //                  file paths; the server reads the PNGs and patches the
+  //                  .mogrt itself.
+  //   server-run-jsx — `_run_jsx` runs a script the server assembled, and a
+  //                  failure carries `wrapperLine`/`libraryIndex` (forwarded
+  //                  above) for the server to map onto the caller's file.
+  //   server-drives-jobs — a chunked run_batch is handed back with
+  //                  `driver: "server"`, and the server sends each chunk.
+  var PANEL_CAPABILITIES = ["project-path", "server-images", "server-run-jsx", "server-drives-jobs"];
+
   // ---------- Load bundle.jsx ----------
   // Hash of the bundle *actually evaluated into ExtendScript*, reported on
   // /health. The server compares it against the bundle it ships to decide
@@ -189,25 +355,43 @@
     }
   }
 
-  function loadJsxBundle() {
+  // `opts.sameAsRunning`: the automatic heal, which must re-load the code this
+  // panel is already running and nothing newer. Between setup_panel and the
+  // next After Effects launch the installed bundle.jsx is newer than this
+  // main.js; loading it would mix the two and move `loadedBundleHash` onto the
+  // new hash, so the version gate would call a stale panel current. The heal
+  // refuses instead and the running hash keeps saying "restart needed".
+  // `/reload-jsx` is the dev route and loads whatever is on disk.
+  function loadJsxBundle(opts) {
     setStatus("Loading bundle.jsx…");
     if (!fs.existsSync(bundlePath)) {
       setStatus("bundle.jsx missing", "err");
       log("error", "bundle.jsx not found at " + bundlePath + " — run `npm run build:jsx`");
-      throw new Error("bundle.jsx missing");
+      return Promise.reject(new Error("bundle.jsx missing"));
+    }
+    var diskHash = hashFile(bundlePath);
+    if (opts && opts.sameAsRunning && loadedBundleHash && diskHash !== loadedBundleHash) {
+      setStatus("restart After Effects", "err");
+      return Promise.reject(new Error(
+        "The AE MCP bundle was removed from After Effects' shared script engine by another script, and the " +
+        "installed bundle.jsx is a newer version than this running panel, so it cannot be reloaded in place. " +
+        "Nothing ran. Restart After Effects."));
     }
     // Use $.evalFile from ExtendScript side so paths work cross-platform.
-    var loadScript = "$.evalFile(" + JSON.stringify(bundlePath) + "); typeof dispatch === 'function' ? 'ok' : 'no-dispatch';";
-    return new Promise(function (resolve, reject) {
-      cs.evalScript(loadScript, function (raw) {
-        if (raw === "ok") {
-          loadedBundleHash = hashFile(bundlePath);
-          $jsx.textContent = "loaded";
-          $jsx.className = "ok";
-          resolve();
-        }
-        else { $jsx.textContent = "fail: " + raw; $jsx.className = "err"; reject(new Error("dispatch not defined after loading bundle.jsx: " + raw)); }
-      });
+    // Through the evalScript mutex like every other call: the heal triggers
+    // this while ops are queued, and a load must not interleave with one.
+    var loadScript = "$.evalFile(" + JSON.stringify(bundlePath) + "); " + NS_READY + " ? 'ok' : 'no-namespace';";
+    return evalScript(loadScript).then(function (raw) {
+      if (raw === "ok") {
+        loadedBundleHash = diskHash;
+        setField("jsx", $jsx, "loaded", "ok");
+        return;
+      }
+      setField("jsx", $jsx, "fail: " + raw, "err");
+      throw new Error("__AEMCP not defined after loading bundle.jsx: " + raw);
+    }, function (e) {
+      setField("jsx", $jsx, "fail: " + e.message, "err");
+      throw e;
     });
   }
 
@@ -312,11 +496,12 @@
   //
   //   port          the port to bind. Default 7777. 0 binds an ephemeral port,
   //                 which is what the offline tests use.
-  //   allowPortWalk when the port is held by another AE MCP panel, move to the
-  //                 next free one instead of waiting for it. For people who run
-  //                 two After Effects instances at once. Off by default: on one
-  //                 machine the holder is a zombie, and walking around it is
-  //                 what issue #92 was.
+  //   allowPortWalk when the port is held by another AE MCP panel, or by
+  //                 something that accepts connections and never answers, move
+  //                 to the next free one instead of waiting for it. For people
+  //                 who run two After Effects instances at once. Off by default:
+  //                 on one machine the holder is a zombie or a busy panel, and
+  //                 walking around it is what issue #92 was.
   //
   // Anything unreadable is logged and ignored; the defaults are what shipped.
   var DEFAULT_PORT = 7777;
@@ -345,573 +530,70 @@
     return cfg;
   }
 
-  // ---------- WS broadcast ----------
+  // ---------- Event socket ----------
+  // /events is still served (see startServers): the MCP server reads its
+  // reopening as a sign that After Effects restarted. No job events are sent
+  // on it since issue #243 — the server drives every batch itself.
   var wsClients = new Set();
-  function broadcast(eventObj) {
-    var str = JSON.stringify(eventObj);
-    wsClients.forEach(function (c) {
-      try { if (c.readyState === 1) c.send(str); } catch (e) {}
-    });
-  }
-
-  // ---------- Vision: read PNG and base64-encode (for screenshot_* ops) ----------
-  // Deciding when After Effects has finished writing a frame is issue #45, and
-  // it lives in framereader.js so a unit test can drive it with a file it grows
-  // by hand. What matters here: `waitForCompletePng` resolves only with bytes
-  // that parse end-to-end as a PNG, deletes the temp file on every path, and
-  // rejects with FRAME_INCOMPLETE or RENDER_TIMEOUT — never with one message
-  // covering both.
-  var waitForCompletePng = frameReaderModule.waitForCompletePng;
-  var dressFrameError = frameReaderModule.dressFrameError;
-  var frameError = frameReaderModule.frameError;
-  var unlinkQuietly = frameReaderModule.unlinkQuietly;
-
-  function sha256(bytes) {
-    return crypto.createHash("sha256").update(bytes).digest("hex");
-  }
-
-  // Downsampling happens in ExtendScript via the comp's resolutionFactor, so
-  // the file on disk is already the right size by the time we get here.
-  //
-  // What is *not* already right is the bit depth: a 16-bit project renders
-  // 16-bit-per-channel PNGs, which many decoders refuse outright. pngcodec
-  // converts those to 8-bit, tells us when the frame is entirely transparent,
-  // and hands back the decoded samples so a frame can be recognised if After
-  // Effects serves the same buffer again for a different request.
-  function readPngFrame(file) {
-    // waitForCompletePng owns the temp file and removes it on every path,
-    // success or failure. A file left behind is one a later read could find,
-    // which is how a corrupt frame would start coming back for free.
-    return waitForCompletePng(file).then(function (buf) {
-      var norm;
-      try {
-        norm = pngCodec.normalizePng(buf);
-      } catch (e) {
-        // The completeness gate above guarantees this file ends in a well-formed
-        // IEND, so a truncation error here would mean the gate is broken. Refuse
-        // rather than ship: "never report success for work that didn't happen"
-        // outranks the fallback below.
-        if (/truncated PNG/.test(e.message)) {
-          throw frameError("FRAME_INCOMPLETE", "the file passed the completeness check and then failed to parse (" + e.message + ")");
-        }
-        // A complete PNG this parser cannot read is still a PNG the client
-        // might. Ship it unchanged rather than throwing away a render that did
-        // happen — but say so, and fall back to hashing the file so the stale
-        // check survives.
-        log("warn", "could not normalise the frame (" + e.message + "); sending it unconverted");
-        var dims = pngDimensions(buf);
-        return {
-          buffer: buf,
-          width: dims ? dims.width : null,
-          height: dims ? dims.height : null,
-          empty: false,
-          hash: sha256(buf),
-          warning: "This frame could not be normalised to 8-bit (" + e.message +
-            ") and was sent exactly as After Effects wrote it. If it fails to decode, " +
-            "that is why.",
-        };
-      }
-      if (norm.empty) {
-        return { empty: true, width: norm.width, height: norm.height };
-      }
-      if (norm.converted) {
-        log("info", "converted a " + norm.bitDepth + "-bit frame to 8-bit (" +
-          buf.length + " -> " + norm.buffer.length + " bytes)");
-      }
-      return {
-        buffer: norm.buffer,
-        width: norm.width,
-        height: norm.height,
-        empty: false,
-        converted: norm.converted,
-        sourceBitDepth: norm.bitDepth,
-        // Decoded samples, kept only so the contact sheet can composite them
-        // without decoding the same PNG a second time. Null on the passthrough
-        // path, where the pixels were never interpreted.
-        pixels: norm.decoded ? norm.hashInput : null,
-        channels: norm.channels,
-        hash: sha256(norm.hashInput),
-        // The pixels could not be read, so "empty" was never evaluated and the
-        // hash is of the compressed stream. Both are still better than nothing;
-        // saying which is what stops a later reader trusting the wrong one.
-        warning: norm.passthrough
-          ? "This frame's pixels were not inspected (" + norm.passthrough +
-            "), so it was sent exactly as After Effects wrote it."
-          : undefined,
-      };
-    });
-  }
-
-  // Read the true pixel dimensions out of the PNG's IHDR chunk rather than
-  // computing them, so what we report is always what the client received.
-  function pngDimensions(buf) {
-    if (buf.length < 24) return null;
-    if (buf.readUInt32BE(12) !== 0x49484452) return null; // "IHDR"
-    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
-  }
-
-  // ---------- Rendering one frame, with one bounded retry ----------
-  function renderFrameOnce(op, args) {
-    return runOp(op, args).then(function (info) {
-      return readPngFrame(info.path).then(function (img) {
-        return { info: info, img: img };
-      });
-    });
-  }
 
-  /**
-   * Render a frame, and re-render exactly once if what came back was corrupt.
-   *
-   * Safe to repeat, which is the only reason this is here. Both screenshot ops
-   * are read-only: `screenshot_frame` renders to a temp file, `screenshot_layer`
-   * additionally solos a layer and restores every solo state in a `finally`.
-   * Neither leaves anything in the project, so a second run is
-   * indistinguishable from one run — this is not `run_jsx`, where re-running a
-   * script that already had its side effects duplicates them (issue #43).
-   *
-   * Only on FRAME_INCOMPLETE, never on RENDER_TIMEOUT. A timeout has already
-   * spent the 120s budget; a second one would take the op past the server's
-   * 300s ceiling and turn a precise "the render did not finish" into a bridge
-   * timeout, whose remedy ("do not restart anything, wait") is a different
-   * remedy for a different problem. A corrupt read, by contrast, fails within
-   * FRAME_STALL_MS, and the evidence in #45 is that a retry sometimes succeeds
-   * — a light comp returned one truncated frame and then rendered.
-   *
-   * The temp file of a failed attempt is deleted before the retry (in
-   * `waitForCompletePng`), and ExtendScript names a fresh one per call, so a
-   * retry can never be handed the previous attempt's bytes.
-   */
-  function renderFrameWithRetry(op, args) {
-    return renderFrameOnce(op, args).catch(function (first) {
-      if (first.code !== "FRAME_INCOMPLETE") throw dressFrameError(first, 1);
-      log("warn", op + ": " + first.detail + " — re-rendering once");
-      return renderFrameOnce(op, args).catch(function (second) {
-        throw dressFrameError(second, 2);
-      });
-    });
+  // ---------- Batches in flight ----------
+  // A chunked run_batch is handed back to the server (`driver: "server"`),
+  // which sends each `_continue_job` itself, so progress, cancel and the
+  // job's state are the server's. Each chunk opens and closes its own undo
+  // group inside one evalScript (issue #69). Only what /reload-jsx needs is
+  // kept here: the job table lives in the bundle's closure, so a reload would
+  // drop each of these mid-run, and /reload-jsx reads this to refuse instead
+  // (issue #163). Jobs are tracked as their chunks pass through, and one no
+  // chunk has reached for SERVER_JOB_IDLE_MS is taken for a batch whose server
+  // stopped (it died), so it no longer blocks a reload.
+  var jobsInFlight = {};
+  var SERVER_JOB_IDLE_MS = 10 * 60 * 1000;
+
+  function trackServerJob(jobId, total) {
+    jobsInFlight[jobId] = { attempted: 0, total: (typeof total === "number") ? total : null, seenAt: Date.now() };
   }
 
-  // ---------- Stale render detection ----------
-  // The request identity a render is expected to be unique to. Built from what
-  // ExtendScript resolved, not from the arguments, so a defaulted time or
-  // downsample is compared as the value actually rendered.
-  function frameKey(op, info) {
-    var layer = (info.layerId === undefined || info.layerId === null) ? "-" : info.layerId;
-    return [op, info.compId, layer, Number(info.time).toFixed(6), info.downsample].join("|");
-  }
-  function frameLabel(op, info) {
-    return "comp " + info.compId +
-      ((info.layerId === undefined || info.layerId === null) ? "" : " layer " + info.layerId) +
-      " @ " + Number(info.time).toFixed(3) + "s downsample " + info.downsample;
-  }
-  // An error rather than a warning attached to the image, because an agent that
-  // can see the picture will believe the picture. It carries the whole
-  // workaround: there is nothing this panel can do to make the render happen.
-  function staleFrameError(label, match, bytes) {
-    var ago = Math.max(1, Math.round(match.ageMs / 1000));
-    var err = new Error(
-      "Stale frame: After Effects returned pixels identical to an earlier, different " +
-      "request (" + match.label + ", " + match.bytes + " bytes, " + ago + "s ago), so this " +
-      "image is not a picture of " + label + " (" + bytes + " bytes) and has not been sent.\n" +
-      "\n" +
-      "What to do next:\n" +
-      "1. Wait a few seconds — back-to-back screenshots trigger this far more often.\n" +
-      "2. Retry with a higher `downsample` (6 has worked where 3-4 stayed stale).\n" +
-      "3. If it repeats, verify the animation by reading keyframes (get_keyframes / " +
-      "get_layer_full) instead. That is exact; a picture is not.\n" +
-      "\n" +
-      "Do NOT start disabling layers to make the render succeed: this is a limit of the " +
-      "panel's render path, not a problem with the project. If those two frames really " +
-      "are identical — a static comp — a different `downsample` will render a different " +
-      "number of pixels and confirm it."
-    );
-    err.code = "STALE_FRAME";
-    return err;
-  }
-
-  // ---------- Long job continuation loop ----------
-  // Each turn of this loop is one evalScript, and each one now opens and closes
-  // its own undo group inside itself — a group cannot span two calls, because
-  // After Effects discards one that does (issue #69). So the chunk size is not
-  // only a pacing knob any more: it decides how many undo steps a long batch
-  // costs the user. It comes off the job envelope so the JSX side owns the
-  // number and the two cannot drift.
-  function driveJob(jobId, progressToken, chunkSize) {
-    var totalGuess = null;
-    var size = chunkSize || 25;
-    function step() {
-      return runOp("_continue_job", { jobId: jobId, chunkSize: size }).then(function (res) {
-        if (res.total) totalGuess = res.total;
-        if (!res.done) {
-          broadcast({ type: "progress", jobId: jobId, progress: res.progress, total: res.total, message: "running" });
-          // Yield to UI so AE stays responsive.
-          return new Promise(function (r) { setTimeout(r, 0); }).then(step);
-        }
-        if (res.failed) {
-          // A failed job reaches the server as an error string and nothing else,
-          // so what the batch cost has to travel inside it or it is lost: the
-          // ops before the failure are applied and stay applied.
-          var failedMsg = (res.error || "batch failed") + (res.note ? " || " + res.note : "");
-          broadcast({ type: "error", jobId: jobId, error: failedMsg });
-          return { done: true, failed: true, jobId: jobId, error: res.error, results: res.results, errors: res.errors, atIndex: res.atIndex, undoSteps: res.undoSteps, note: res.note };
-        }
-        // `undoSteps` is the measured number of undo groups the batch opened,
-        // and `diff` is the batch's own before/after — both are only ever seen
-        // by the agent if they are carried on this event.
-        broadcast({
-          type: "complete",
-          jobId: jobId,
-          result: {
-            results: res.results,
-            errors: res.errors,
-            total: res.total || totalGuess,
-            cancelled: !!res.cancelled,
-            undoSteps: res.undoSteps,
-            undoGroupName: res.undoGroupName,
-            note: res.note,
-            diff: res.diff,
-          },
-        });
-        return {
-          done: true, jobId: jobId,
-          results: res.results, errors: res.errors,
-          total: res.total || totalGuess, cancelled: !!res.cancelled,
-          undoSteps: res.undoSteps, undoGroupName: res.undoGroupName,
-          note: res.note, diff: res.diff,
-        };
-      });
-    }
-    return step();
-  }
-
-  // ---------- Motion Graphics template thumbnail ----------
-  // ExtendScript can render the poster frame but cannot rewrite a zip, so the
-  // JSX side hands back a PNG path and the archive surgery happens here.
-  //
-  // A failed patch is reported on an otherwise successful result, never thrown:
-  // the .mogrt is already written and valid at this point, and throwing away a
-  // successful export because its thumbnail could not be improved would be the
-  // worse trade. The result says plainly that the thumbnail is still AE's.
-  function patchMogrtThumbnail(info) {
-    // The same completeness gate the screenshot path uses. The poster frame is
-    // written by the same asynchronous `saveFrameToPng`, so a half-written one
-    // is just as possible here — and it would be resampled into the template's
-    // thumbnail rather than merely displayed.
-    // It takes the poster file with it, on success and on failure alike.
-    return waitForCompletePng(info.posterPngPath).then(function (poster) {
-      var patched = mogrtModule.patchThumbnail(fs.readFileSync(info.path), poster);
-      // Write via a sibling temp file and rename, so an interrupted write
-      // cannot leave a half-rewritten template where a valid one used to be.
-      var tmp = info.path + ".tmp-thumb";
-      fs.writeFileSync(tmp, patched.buffer);
-      fs.renameSync(tmp, info.path);
-      return {
-        patched: true,
-        posterTime: info.posterTime,
-        width: patched.width,
-        height: patched.height,
-        sourceWidth: patched.sourceWidth,
-        sourceHeight: patched.sourceHeight,
-        letterboxed: patched.letterboxed || undefined,
-      };
-    }).catch(function (e) {
-      unlinkQuietly(info.posterPngPath);
-      log("warn", "could not patch the .mogrt thumbnail: " + e.message);
-      return {
-        patched: false,
-        posterTime: info.posterTime,
-        reason: "The template exported correctly, but its thumbnail could not be replaced (" +
-          e.message + "). It still shows the one After Effects wrote.",
-      };
-    });
-  }
-
-  // ---------- Contact sheet ----------
-  //
-  // ExtendScript renders every requested time and hands back one temp path per
-  // tile; everything from here on is pixels, which `packages/jsx` has no way to
-  // touch. One tile that fails is drawn as a marked block rather than dropped —
-  // the sheet has to keep mapping onto the times that were asked for, or an
-  // agent counting frames left to right reads the wrong one as the right one.
-
-  /** One line, for a note inside a tile rather than a whole error message. */
-  function shortReason(err) {
-    var s = err && err.detail ? err.detail : (err && err.message ? err.message : String(err));
-    return String(s).split("\n")[0];
+  function noteServerChunk(jobId, res) {
+    var j = jobsInFlight[jobId];
+    if (!j) return;
+    if (!res || res.done) { delete jobsInFlight[jobId]; return; }
+    if (typeof res.progress === "number") j.attempted = res.progress;
+    if (typeof res.total === "number") j.total = res.total;
+    j.seenAt = Date.now();
   }
 
-  function readSheetTile(info, tile) {
-    if (tile.error) {
-      return Promise.resolve({ time: tile.time, status: "failed", note: tile.error });
-    }
-    return readPngFrame(tile.path).then(function (img) {
-      return { time: tile.time, status: "ok", img: img };
-    }, function (err) {
-      if (err.code !== "FRAME_INCOMPLETE") {
-        return { time: tile.time, status: "failed", note: shortReason(err) };
-      }
-      // The same bounded retry the single-frame path gets, and safe for the same
-      // reason — but re-rendering only this one time. The already-derived
-      // downsample is passed explicitly so the per-tile factor cannot drift from
-      // the rest of the sheet.
-      log("warn", "contact sheet tile at " + tile.time + "s: " + shortReason(err) + " — re-rendering once");
-      return runOp("screenshot_frame", {
-        compId: info.compId,
-        time: tile.time,
-        downsample: info.downsample,
-      }).then(function (retry) {
-        return readPngFrame(retry.path).then(function (img) {
-          return { time: tile.time, status: "ok", img: img };
-        });
-      }).catch(function (again) {
-        return { time: tile.time, status: "failed", note: shortReason(again) };
-      });
-    });
-  }
-
-  function finishContactSheet(info, read) {
-    var i;
-    var ds = info.downsample;
-    // Pass one: classify. Every `match` is computed before any `remember`, so a
-    // sheet's own tiles cannot collide with each other through the cache.
-    var seen = {};
-    for (i = 0; i < read.length; i++) {
-      var t = read[i];
-      if (t.status !== "ok") continue;
-      if (t.img.empty) { t.status = "empty"; t.img = null; continue; }
-      var ident = { compId: info.compId, layerId: null, time: t.time, downsample: ds };
-      t.key = frameKey("screenshot_frame", ident);
-      var match = frameCache.match(t.key, t.img.hash);
-      if (match) {
-        // Pixels identical to an *earlier, different* request are the #29 stale
-        // buffer, and a tile of them is not a picture of this time. Mark the
-        // block rather than showing it: an agent that can see a frame believes
-        // the frame.
-        t.status = "stale";
-        t.note = "identical to " + match.label + ", rendered " +
-          Math.max(1, Math.round(match.ageMs / 1000)) + "s earlier";
-        t.img = null;
-        continue;
-      }
-      // Two tiles of one sheet matching each other is what a static comp looks
-      // like — the caller asked for several times on purpose, and refusing the
-      // second would be a false alarm on a correct answer. Flagged, not refused.
-      if (seen[t.img.hash] !== undefined) {
-        t.note = "pixel-identical to the " + contactSheetModule.formatTime(seen[t.img.hash]) +
-          " tile — nothing changed between them";
-      } else {
-        seen[t.img.hash] = t.time;
-      }
-    }
-
-    var specs = [];
-    var ok = 0;
-    for (i = 0; i < read.length; i++) {
-      var r = read[i];
-      var spec = { time: r.time, status: r.status, note: r.note };
-      if (r.status === "ok") {
-        var px = r.img.pixels;
-        var channels = r.img.channels;
-        if (!px) {
-          // The passthrough path never interpreted the pixels. A sheet needs
-          // them, so decode strictly here; a frame that cannot be decoded
-          // becomes a marked block rather than a wrong one.
-          try {
-            var dec = pngCodec.decodePng8(r.img.buffer);
-            px = dec.pixels;
-            channels = dec.channels;
-          } catch (e) {
-            // Both records move together: `spec` is what gets drawn, `r` is what
-            // the cache loop below reads, and a frame that is not delivered must
-            // not be remembered as if it were.
-            spec.status = "failed";
-            r.status = "failed";
-            spec.note = "the frame could not be decoded for tiling (" + e.message + ")";
-          }
-        }
-        if (spec.status === "ok") {
-          spec.pixels = px;
-          spec.channels = channels;
-          spec.width = r.img.width;
-          spec.height = r.img.height;
-          ok++;
-        }
-      }
-      specs.push(spec);
-    }
-
-    if (!ok) {
-      var why = [];
-      for (i = 0; i < specs.length; i++) {
-        why.push(contactSheetModule.formatTime(specs[i].time) + ": " + specs[i].status +
-          (specs[i].note ? " (" + specs[i].note + ")" : ""));
-      }
-      var dead = new Error(
-        "No tile of the contact sheet rendered, so there is no sheet to send. Per time:\n" +
-        why.join("\n") + "\n\n" +
-        "A sheet of coloured blocks is not a screenshot. Retry at a higher `downsample`, " +
-        "or screenshot the shot precomps one at a time; if it repeats, read keyframes " +
-        "(get_keyframes / get_layer_full) instead."
-      );
-      dead.code = "CONTACT_SHEET_FAILED";
-      throw dead;
-    }
-
-    // The expected cell size, used only for the cells with no picture. A tile
-    // that rendered is the authority on its own dimensions.
-    var sheet = contactSheetModule.composeContactSheet(specs, {
-      cellWidth: Math.round(info.width / ds),
-      cellHeight: Math.round(info.height / ds),
-    });
-
-    // Only what is actually being delivered goes into the cache.
-    for (i = 0; i < read.length; i++) {
-      if (read[i].status === "ok" && read[i].key) {
-        frameCache.remember(read[i].key, read[i].img.hash, {
-          label: frameLabel("screenshot_frame", { compId: info.compId, time: read[i].time, downsample: ds }),
-          bytes: read[i].img.buffer.length,
-        });
-      }
-    }
-
-    var bad = [];
-    for (i = 0; i < sheet.tiles.length; i++) {
-      if (sheet.tiles[i].status !== "ok") {
-        bad.push(sheet.tiles[i].label + (sheet.tiles[i].note ? " — " + sheet.tiles[i].note : ""));
-      }
+  function jobsInFlightText() {
+    var parts = [];
+    var now = Date.now();
+    for (var id in jobsInFlight) {
+      if (!jobsInFlight.hasOwnProperty(id)) continue;
+      var j = jobsInFlight[id];
+      if (now - j.seenAt > SERVER_JOB_IDLE_MS) continue;
+      parts.push(id + " (" + j.attempted + " of " + (j.total === null ? "?" : j.total) + " ops attempted" +
+        ", driven by the MCP server)");
     }
-
-    return {
-      contactSheet: true,
-      width: sheet.width,
-      height: sheet.height,
-      cols: sheet.cols,
-      rows: sheet.rows,
-      cellWidth: sheet.cellWidth,
-      cellHeight: sheet.cellHeight,
-      fullWidth: info.width,
-      fullHeight: info.height,
-      downsample: ds,
-      compId: info.compId,
-      tiles: sheet.tiles,
-      mimeType: "image/png",
-      base64: sheet.buffer.toString("base64"),
-      bytes: sheet.buffer.length,
-      // Named and counted, because a sheet that looks complete and is not is the
-      // same class of lie as a swallowed error.
-      warning: bad.length
-        ? bad.length + " of " + sheet.tiles.length + " tiles are marked blocks, not frames: " + bad.join("; ")
-        : undefined,
-    };
-  }
-
-  function renderContactSheet(args) {
-    return runOp("screenshot_frame", args).then(function (info) {
-      var jsxTiles = info.tiles || [];
-      // Sequentially: `evalScript` is a mutex anyway, a per-tile retry re-enters
-      // ExtendScript, and reading them in order keeps the panel log legible.
-      var read = [];
-      var chain = Promise.resolve();
-      for (var i = 0; i < jsxTiles.length; i++) {
-        chain = chain.then(function (tile) {
-          return function () {
-            return readSheetTile(info, tile).then(function (res) { read.push(res); });
-          };
-        }(jsxTiles[i]));
-      }
-      return chain.then(function () { return finishContactSheet(info, read); });
-    });
+    return parts.join(", ");
   }
 
-  // ---------- Op handler with vision/job specialization ----------
-  function handleOp(op, args, progressToken) {
-    // Export writes the .mogrt; the thumbnail it wants is a second file that
-    // has to be folded into it afterwards.
-    if (op === "export_mogrt") {
-      return runOp(op, args).then(function (info) {
-        if (!info || !info.posterPngPath) return info;
-        return patchMogrtThumbnail(info).then(function (thumbnail) {
-          var out = {};
-          for (var k in info) { if (info.hasOwnProperty(k) && k !== "posterPngPath") out[k] = info[k]; }
-          out.thumbnail = thumbnail;
-          // The file changed size when the thumbnail was replaced, and the
-          // reported number has to be the one on disk.
-          try { out.bytes = fs.statSync(info.path).size; } catch (e) {}
-          return out;
-        });
-      });
-    }
-    // Vision ops: run JSX, then read PNG and base64-encode on Node side.
-    if (op === "screenshot_frame" || op === "screenshot_layer") {
-      if (op === "screenshot_frame" && args && args.times && args.times.length) {
-        return renderContactSheet(args);
-      }
-      return renderFrameWithRetry(op, args).then(function (r) {
-        var info = r.info;
-        var img = r.img;
-        // A frame with nothing in it is a fact about the composition, not a
-        // failure — and the ~5KB PNG that encodes it is the one decoders
-        // reject. Report it, cheaply, instead of shipping an image nobody can
-        // read and calling that a successful screenshot.
-        if (img.empty) {
-          return {
-            empty: true,
-            width: img.width,
-            height: img.height,
-            fullWidth: info.width,
-            fullHeight: info.height,
-            downsample: info.downsample,
-            time: info.time,
-            compId: info.compId,
-            layerId: info.layerId,
-            reason: "Every pixel of this frame is fully transparent — the frame is empty. " +
-              "No image was sent because there is nothing in it to see. Usually this means " +
-              "the time is outside the layers' in/out points, the layers are disabled or " +
-              "have zero opacity, or the wrong comp was addressed.",
-          };
-        }
-        // Only a frame that read cleanly ever reaches the cache. A corrupt read
-        // is rejected above and never remembered — before the completeness gate
-        // existed, a truncated file was hashed and recorded here, so the next
-        // truncation at the same byte count was reported as a stale buffer and
-        // the real fault was hidden behind the wrong diagnosis.
-        var key = frameKey(op, info);
-        var match = frameCache.match(key, img.hash);
-        if (match) throw staleFrameError(frameLabel(op, info), match, img.buffer.length);
-        frameCache.remember(key, img.hash, { label: frameLabel(op, info), bytes: img.buffer.length });
-        return {
-          // Dimensions come from the PNG itself, not from arithmetic on the
-          // comp size, so they cannot disagree with the image sent.
-          width: img.width,
-          height: img.height,
-          fullWidth: info.width,
-          fullHeight: info.height,
-          downsample: info.downsample,
-          time: info.time,
-          compId: info.compId,
-          layerId: info.layerId,
-          mimeType: "image/png",
-          base64: img.buffer.toString("base64"),
-          bytes: img.buffer.length,
-          // Only present when the frame was not 8-bit as rendered, so the
-          // metadata stays quiet on the ordinary path.
-          converted: img.converted ? true : undefined,
-          sourceBitDepth: img.converted ? img.sourceBitDepth : undefined,
-          warning: img.warning,
-        };
-      });
-    }
-    // Long batches: returns {jobId, async, total}. We kick off background drive
-    // and return the jobId immediately.
+  // ---------- Op handler ----------
+  // Everything goes to the bundle as sent. Screenshots, the .mogrt thumbnail,
+  // the house style's file I/O and run_jsx's assembly are the server's (issue
+  // #220), and the copies of that work that used to live here are gone (issue
+  // #243). What is left is bookkeeping for /reload-jsx.
+  function handleOp(op, args, gone) {
     if (op === "run_batch") {
-      return runOp(op, args).then(function (res) {
+      // The driver flag is the server's word to this panel, never an op
+      // argument: ExtendScript does not see it.
+      if (args && args.__driver !== undefined) {
+        var stripped = {};
+        for (var ak in args) { if (args.hasOwnProperty(ak) && ak !== "__driver") stripped[ak] = args[ak]; }
+        args = stripped;
+      }
+      return runOp(op, args, gone).then(function (res) {
         if (res && res.async && res.jobId) {
-          driveJob(res.jobId, progressToken, res.chunkSize).catch(function (e) {
-            broadcast({ type: "error", jobId: res.jobId, error: e.message });
-          });
+          trackServerJob(res.jobId, res.total);
           // The undo fields ride out with the envelope so the agent is told the
-          // batch will be several steps *before* it goes and says otherwise —
-          // the final count arrives much later, on the completion event.
+          // batch will be several steps *before* it goes and says otherwise.
           return {
             jobId: res.jobId,
             async: true,
@@ -920,19 +602,40 @@
             undoStepsEstimate: res.undoStepsEstimate,
             undoGroupName: res.undoGroupName,
             note: res.note,
+            aeWarnings: res.aeWarnings,
+            driver: "server",
           };
         }
         return res; // small batch: inline result already
       });
     }
-    return runOp(op, args);
+    // One chunk of a batch: passed through untouched, watched only for
+    // /reload-jsx.
+    if (op === "_continue_job" && args && jobsInFlight[args.jobId]) {
+      var cj = args.jobId;
+      return runOp(op, args, gone).then(function (res) {
+        noteServerChunk(cj, res);
+        return res;
+      }, function (e) {
+        noteServerChunk(cj, null);
+        throw e;
+      });
+    }
+    return runOp(op, args, gone);
   }
 
   // ---------- HTTP server ----------
   function startHttp(port) {
     return new Promise(function (resolve, reject) {
       var server = http.createServer(function (req, res) {
+        // When the request arrived, on a clock no wall-clock change moves.
+        var receivedAt = monoNow();
         var url = req.url || "/";
+        // Only /reload-jsx takes a query (`?force=1`); every other route is
+        // still matched on the whole url, as before.
+        var qAt = url.indexOf("?");
+        var route = qAt < 0 ? url : url.slice(0, qAt);
+        var query = qAt < 0 ? "" : url.slice(qAt + 1);
 
         // No CORS headers, deliberately: nothing that legitimately calls this
         // bridge is a web page (issue #106).
@@ -953,10 +656,22 @@
             port: addr && addr.port ? addr.port : port,
             bundleLoaded: true,
             bundleHash: loadedBundleHash,
+            // Every other file of this panel, hashed at launch (issue #243). The
+            // server's gate needs both hashes to match the panel it ships.
+            clientHash: loadedClientHash,
             // The gate exists, never anything about the token. Absent on a
             // pre-#106 panel, which is how the server tells "needs a token"
             // from "too old to want one".
             auth: true,
+            // What this panel can do (issue #220). The server's gate reads it
+            // only when it has no shipped panel to compare the hashes with.
+            capabilities: PANEL_CAPABILITIES,
+            // The script handed to After Effects with no answer yet, or null.
+            // The server's busy guard reads it after a timeout: answered here
+            // with this set, After Effects is still on that script. (While
+            // ExtendScript holds this thread, /health is not answered at all.)
+            evalBusy: evalBusyNow(),
+            evalQueued: Math.max(0, __evalPending - (__evalRunning ? 1 : 0)),
             ts: Date.now()
           }));
           return;
@@ -990,12 +705,49 @@
 
           if (url === "/op") {
             bumpReq();
-            handleOp(body.op, body.args, body.progressToken)
+            // Queued behind a stuck call, an op would otherwise still run once
+            // After Effects frees up — late, out of order, after the agent was
+            // told it timed out. So it is dropped at its turn once the server
+            // has given up on it. The server sends its own timeout as
+            // `timeoutMs` (relative), and the panel runs the same span from
+            // the request's arrival on a monotonic clock — arrival is after
+            // the server started its timer, so this deadline is never earlier
+            // than the server's, and DEADLINE_GRACE_MS on top makes a dropped
+            // call only ever one the server already reported as timed out.
+            // It needs no socket event to reach this thread in time; the
+            // request closing is a second signal. No `timeoutMs` (an older
+            // server): only the close is checked.
+            var replied = false;
+            var closedEarly = false;
+            res.on("close", function () { if (!replied) closedEarly = true; });
+            var limitMs = typeof body.timeoutMs === "number" && isFinite(body.timeoutMs) && body.timeoutMs > 0 ? body.timeoutMs : null;
+            var gone = function () {
+              var over = limitMs === null ? 0 : monoNow() - receivedAt - limitMs;
+              if (limitMs !== null && over > DEADLINE_GRACE_MS) {
+                return "the MCP server's deadline for it passed " + Math.round(over / 1000) +
+                  "s ago while it was queued behind another call";
+              }
+              if (closedEarly || (req.socket && req.socket.destroyed)) {
+                return "the MCP server closed its request (it gave up waiting) while it was queued behind another call";
+              }
+              return null;
+            };
+            handleOp(body.op, body.args, gone)
               .then(function (result) {
+                replied = true;
                 res.statusCode = 200; res.setHeader("content-type", "application/json");
                 res.end(JSON.stringify({ ok: true, result: result }));
               })
               .catch(function (err) {
+                replied = true;
+                if (err && err.code === "REQUEST_CLOSED") {
+                  log("warn", body.op + " was not run, " + err.message.replace(/^dropped before it ran: /, "") +
+                    " — dropped rather than run late.");
+                  // No answer: the server has already reported this call as
+                  // timed out, and nothing it could read here would be newer.
+                  try { res.destroy(); } catch (e) {}
+                  return;
+                }
                 log("error", body.op + ": " + err.message);
                 res.statusCode = 500; res.setHeader("content-type", "application/json");
                 // `code` marks a failure the panel diagnosed itself rather than
@@ -1019,8 +771,25 @@
             return;
           }
 
-          if (url === "/reload-jsx") {
+          if (route === "/reload-jsx") {
             // Dev-only: re-evalFile the bundle. Useful while editing .jsx without restarting AE.
+            // A reload replaces the bundle's job table, so every batch in flight
+            // stops mid-run with part of it applied (issue #163). Refused while
+            // one runs; `?force=1` reloads anyway, and the batch then reports
+            // exactly what had landed.
+            var busy = jobsInFlightText();
+            if (busy && !/(^|&)force=1(&|$)/.test(query)) {
+              res.statusCode = 409;
+              res.setHeader("content-type", "application/json");
+              res.end(JSON.stringify({
+                ok: false,
+                code: "batch_in_flight",
+                error: "Not reloaded: a run_batch is still running — " + busy + ". Reloading the bundle now " +
+                  "would stop it mid-run with part of it applied. Wait for it to finish (await_job), or cancel " +
+                  "it (cancel_job), then reload. POST /reload-jsx?force=1 reloads anyway.",
+              }));
+              return;
+            }
             loadJsxBundle()
               .then(function () { res.statusCode = 200; res.end(JSON.stringify({ ok: true })); })
               .catch(function (e) { res.statusCode = 500; res.end(JSON.stringify({ ok: false, error: e.message })); });
@@ -1047,13 +816,20 @@
 
   // Never rejects: every outcome is a classification the caller acts on.
   //   panel  — another AE MCP panel; its health body is attached
-  //   other  — something answered, but not as the panel
-  //   silent — accepted the connection and said nothing, or errored
+  //   other  — something answered over HTTP, but not as the panel
+  //   silent — accepted the connection and said nothing at all. The one case
+  //            that can be a panel whose After Effects is busy (issue #288)
+  //   gone   — the connection was refused: the holder exited after the bind
+  //            failed, so the port has just come free
+  //   odd    — anything else: it hung up, spoke something other than HTTP, or
+  //            started an answer and stalled. A panel does none of these
   function identifyHolder(port) {
     return new Promise(function (resolve) {
       var done = false;
+      var answering = false;
       function finish(r) { if (!done) { done = true; resolve(r); } }
       var req = http.get({ host: "127.0.0.1", port: port, path: "/health", timeout: 1500 }, function (res) {
+        answering = true;
         var bufs = [];
         res.on("data", function (c) { bufs.push(c); });
         res.on("end", function () {
@@ -1062,16 +838,26 @@
           if (res.statusCode === 200 && isOurHealth(body)) finish({ kind: "panel", health: body });
           else finish({ kind: "other", detail: "answered HTTP " + res.statusCode + (body ? " with an unfamiliar body" : " with no JSON") });
         });
-        res.on("error", function (e) { finish({ kind: "silent", detail: e.message }); });
+        res.on("error", function (e) { finish({ kind: "odd", detail: e.message }); });
+      });
+      req.on("timeout", function () {
+        var said = answering ? "started an answer and stalled" : "accepted the connection but did not answer within 1.5s";
+        finish({ kind: answering ? "odd" : "silent", detail: said });
+        req.destroy();
+      });
+      req.on("error", function (e) {
+        finish({ kind: e.code === "ECONNREFUSED" ? "gone" : "odd", detail: e.message });
       });
-      req.on("timeout", function () { req.destroy(); finish({ kind: "silent", detail: "accepted the connection but did not answer within 1.5s" }); });
-      req.on("error", function (e) { finish({ kind: "silent", detail: e.message }); });
     });
   }
 
   // 7777 through 7799 was the old ceiling; kept as a distance so a configured
   // start port walks the same number of steps.
   var WALK_LIMIT = 22;
+  var MAX_PORT = 65535;
+  // A port that refuses connections and will not bind is not free after all
+  // (a socket bound and not listening), so this is a few tries, not a wait.
+  var GONE_RETRIES = 3;
 
   /**
    * Bind the configured port, and decide what to do when it is taken.
@@ -1080,23 +866,34 @@
    * whatever it got to the port file. On one machine nothing else ever holds
    * 7777, so the thing being walked around was always a previous instance of
    * this same panel — a CEPHtmlEngine that lingered across an After Effects
-   * relaunch, or a second panel window — and the walk routed round it in
+   * relaunch, or a second After Effects — and the walk routed round it in
    * silence, leaving the port file as a second source of truth that could
    * disagree with the socket. Four incidents in a week (issue #92).
    *
    * So the holder is identified first. If it is one of us, this panel does not
    * move: it says so in its status and log, and retries the bind on an interval
    * so it takes the port over the moment the other one exits, with no restart.
-   * If it is something else, or answers nothing, the walk happens as before —
-   * loudly, naming the holder and the port chosen, because that is the one
-   * case where the port file legitimately says something other than 7777.
-   * `allowPortWalk` in config.json opts back into walking past our own panel,
-   * for people who really run two After Effects instances.
+   * If it is something else, the walk happens as before — loudly, naming the
+   * holder and the port chosen, because that is the one case where the port
+   * file legitimately says something other than 7777.
+   *
+   * A holder that accepts the connection and then says nothing is treated as
+   * ours (issue #288). /health goes unanswered while ExtendScript holds a
+   * panel's thread, so a silent holder is most often a panel whose After Effects
+   * is busy, and walking past it is the same drift as above. The panel keeps
+   * trying the bind and re-asks every time. Only silence counts: a holder that
+   * hangs up or speaks something other than HTTP walks like any other stranger.
+   * `allowPortWalk` in config.json opts back into walking past both, for people
+   * who really run two After Effects instances.
    */
   function startServers(cfg) {
     var startPort = cfg.port;
     var retryMs = cfg.bindRetryMs;
-    var waits = 0;
+    // One count each: a holder can go from silent to answering between retries,
+    // and each kind of wait has its own first-time explanation to give.
+    var panelWaits = 0;
+    var silentWaits = 0;
+    var goneRetries = 0;
 
     function bindWith(p) {
       return startHttp(p).then(function (server) {
@@ -1128,8 +925,13 @@
 
     function walk(p, tries, why) {
       var next = p + 1;
-      if (tries >= WALK_LIMIT) {
-        throw new Error("ports " + startPort + " through " + p + " are all in use — nothing free to bind. Last holder: " + why);
+      // There is no port past 65535: asking for one made listen() throw a
+      // RangeError that named no port the user had configured (issue #260).
+      var offTheTop = next > MAX_PORT;
+      if (tries >= WALK_LIMIT || offTheTop) {
+        throw new Error("ports " + startPort + " through " + p + " are all in use — nothing free to bind" +
+          (offTheTop ? " (" + MAX_PORT + " is the highest port there is; set a lower \"port\" in " + configFile + ")" : "") +
+          ". Last holder: " + why);
       }
       log("warn", "port " + p + " is held by " + why + " — moving to port " + next + ". " +
         "The MCP server finds this port through the port file; if tool calls fail on " + p +
@@ -1143,7 +945,7 @@
         ? String(holder.health.bundleHash).slice(0, 12)
         : "no bundleHash — a panel older than 0.3";
       setStatus("waiting — port " + p + " is held by another AE MCP panel", "warn");
-      if (waits === 0) {
+      if (panelWaits === 0) {
         log("warn", "port " + p + " is already held by another AE MCP panel (bundle " + hash + ", " +
           (same ? "the same version as this one" : "a DIFFERENT version from this one") + "). " +
           "Not moving to another port: that would leave the port file pointing at whichever panel bound last, " +
@@ -1153,10 +955,26 @@
           "panel process is still running: quit After Effects fully, check Activity Monitor / Task Manager for a " +
           "leftover CEPHtmlEngine, and reopen it. To run two After Effects at once instead, set " +
           "\"allowPortWalk\": true in " + configFile + ".");
-      } else if (waits % 30 === 0) {
-        log("info", "still waiting for port " + p + " (" + waits + " attempts)");
+      } else if (panelWaits % 30 === 0) {
+        log("info", "still waiting for port " + p + " (" + panelWaits + " attempts)");
+      }
+      panelWaits += 1;
+      return new Promise(function (r) { setTimeout(r, retryMs); }).then(function () { return attempt(p, 0); });
+    }
+
+    function waitForSilentHolder(p, holder) {
+      setStatus("waiting — port " + p + " is held by something that does not answer", "warn");
+      if (silentWaits === 0) {
+        log("warn", "port " + p + " is held by something that did not identify itself (" + holder.detail + "). " +
+          "Not moving to another port: an AE MCP panel does not answer while After Effects is busy with a script, " +
+          "and moving would leave two panels and a port file pointing at the wrong one (issues #92, #288).");
+        log("warn", "Retrying the bind every " + (retryMs / 1000) + "s; this panel takes the port the moment it " +
+          "is free, with no restart. If this persists and nothing is busy, another program holds port " + p + ": " +
+          "set a different \"port\" in " + configFile + ", or \"allowPortWalk\": true to move past it.");
+      } else if (silentWaits % 30 === 0) {
+        log("info", "still waiting for port " + p + " (" + silentWaits + " attempts)");
       }
-      waits += 1;
+      silentWaits += 1;
       return new Promise(function (r) { setTimeout(r, retryMs); }).then(function () { return attempt(p, 0); });
     }
 
@@ -1170,6 +988,13 @@
             }
             return waitForHolder(p, holder);
           }
+          if (holder.kind === "silent" && !cfg.allowPortWalk) return waitForSilentHolder(p, holder);
+          // The holder left between the failed bind and the question. Walking
+          // now would be the #92 drift, on a port nothing holds any more.
+          if (holder.kind === "gone" && goneRetries < GONE_RETRIES) {
+            goneRetries += 1;
+            return new Promise(function (r) { setTimeout(r, retryMs); }).then(function () { return attempt(p, tries); });
+          }
           var why = holder.kind === "other"
             ? "something that is not an AE MCP panel (" + holder.detail + ")"
             : "something that did not identify itself (" + holder.detail + ")";
@@ -1181,7 +1006,7 @@
   }
 
   // ---------- Shutdown ----------
-  // When the panel window closes or After Effects quits, give the port back and
+  // When the bridge extension unloads (After Effects quits), give the port back and
   // take this panel's port-file entry with it. A panel that exits cleanly must
   // not leave a file naming a port nobody listens on — that is the other half
   // of how the port file came to disagree with the socket (issue #92). A
@@ -1203,11 +1028,65 @@
     window.addEventListener("unload", shutdown);
   }
 
+  // ---------- A host with no user in it (issue #288) ----------
+  // CEP loads this extension into every process that calls itself AEFT, and two
+  // of those are hidden render engines with no window and no project of the
+  // user's: `aerendercore -m -livelink`, which Premiere's Dynamic Link starts,
+  // and `aerendercore -noui`, which aerender starts, render_queue included. A
+  // bridge there takes the port, and every tool call lands in an After Effects
+  // the user cannot see.
+  //
+  // Measured on 26.5 in both engines: app.isUISuppressed is true, and false in
+  // a normal After Effects at launch, with a project opened by file, and during
+  // suppressed dialogs; it is read-only. app.isRenderEngine is false in both
+  // engines, so it does not answer this. CEP's host environment and capabilities
+  // are identical in all three.
+  //
+  // A version without the property answers "interactive" at once and boots as
+  // it always has. Nothing is bound before this resolves, so an engine too busy
+  // to answer at all stays unbound. "EvalScript error." is not an answer: a busy
+  // engine can say it too, and booting on it would put the bridge in that
+  // engine. So it is asked again, and only a host that gives no answer through
+  // every try boots as normal. Failing open there is deliberate: a host that
+  // still refuses scripts also refuses the bundle load, which fails the boot
+  // before anything binds, so the load is the backstop.
+  //
+  // "headless" is asked twice, a second apart, and a host that says it and then
+  // cannot be asked again counts as headless. No transient true has been
+  // measured in a normal After Effects, but one would cost the user the bridge
+  // until a restart, while the recheck costs a real engine one second of a
+  // process nobody is waiting on. The first "interactive" is taken as final, so
+  // a normal launch pays nothing for any of this.
+  var HEADLESS_CHECK = "app.isUISuppressed === true ? 'headless' : 'interactive'";
+  var HEADLESS_TRIES = 5;
+  var HEADLESS_RETRY_MS = 1000;
+  function isHeadlessHost() {
+    function ask(tries, saidHeadless) {
+      function again(said) {
+        if (tries <= 1) {
+          if (!said) log("warn", "After Effects gave no answer to the render engine check, so the bridge is starting as normal.");
+          return said;
+        }
+        return new Promise(function (r) { setTimeout(r, HEADLESS_RETRY_MS); })
+          .then(function () { return ask(tries - 1, said); });
+      }
+      return evalScript(HEADLESS_CHECK, { label: "render engine check" }).then(
+        function (raw) {
+          if (raw === "interactive") return false;
+          if (raw !== "headless") return again(saidHeadless);
+          return saidHeadless ? true : again(true);
+        },
+        function () { return again(saidHeadless); }
+      );
+    }
+    return ask(HEADLESS_TRIES, false);
+  }
+
   // ---------- Boot sequence ----------
   setStatus("Starting…");
   try {
     var host = cs.getHostEnvironment();
-    $ae.textContent = (host && host.appName ? host.appName : "AE") + " " + (host && host.appVersion ? host.appVersion : "");
+    setField("ae", $ae, (host && host.appName ? host.appName : "AE") + " " + (host && host.appVersion ? host.appVersion : ""));
   } catch (e) {}
 
   var config = readConfig();
@@ -1215,18 +1094,29 @@
     log("info", "read " + config.source + ": port " + config.port + (config.allowPortWalk ? ", allowPortWalk on" : ""));
   }
 
-  loadJsxBundle()
-    .then(function () { return startServers(config); })
-    .then(function (s) {
-      running = s;
-      // The only write of the port file, and only with the port actually bound.
-      writePortFile(s.port);
-      $port.textContent = String(s.port);
-      $port.className = "ok";
-      setStatus("ready", "ok");
-      log("info", "Bridge listening on http://127.0.0.1:" + s.port +
-        (s.port !== config.port && config.port !== 0 ? " (configured port " + config.port + " was taken — see above)" : ""));
-      log("info", "Calls are authenticated: the MCP server reads this session's token from " + tokenFile(s.port) + ".");
+  function bootBridge() {
+    return loadJsxBundle()
+      .then(function () { return startServers(config); })
+      .then(announceBridge);
+  }
+
+  function announceBridge(s) {
+    running = s;
+    // The only write of the port file, and only with the port actually bound.
+    writePortFile(s.port);
+    setField("port", $port, String(s.port), "ok");
+    setStatus("ready", "ok");
+    log("info", "Bridge listening on http://127.0.0.1:" + s.port +
+      (s.port !== config.port && config.port !== 0 ? " (configured port " + config.port + " was taken — see above)" : ""));
+    log("info", "Calls are authenticated: the MCP server reads this session's token from " + tokenFile(s.port) + ".");
+  }
+
+  isHeadlessHost()
+    .then(function (headless) {
+      if (!headless) return bootBridge();
+      // No port, no port file, no token, no bundle in the engine.
+      setStatus("not started — this is a render engine, not After Effects", "warn");
+      log("info", "This host is a hidden render engine (Premiere Dynamic Link or aerender), so the bridge stays off here.");
     })
     .catch(function (e) {
       setStatus("failed", "err");