@melaya/runner 1.1.33 → 1.1.35

package/dist/cli.js

@@ -52,6 +52,19 @@ async function main() {
         .parse(process.argv);
     const opts = program.opts();
     console.log(BANNER);
+    // Single-instance guard: refuse to start if another runner is already running
+    // on this machine. Two runners for one user fight over a single server-side
+    // session (connect/disconnect churn, turns landing on the wrong host), so we
+    // stop the second launch up front rather than let them compete. A stale lock
+    // from a crashed runner is reclaimed automatically.
+    const { acquireSingleInstanceLock } = await import("./singleInstance.js");
+    const lock = acquireSingleInstanceLock();
+    if (!lock.ok) {
+        console.log(chalk.red(`  ✗ A Melaya runner is already running on this machine (pid ${lock.ownerPid}).`));
+        console.log(chalk.gray("    Only one runner can run per machine. Stop the other one first"));
+        console.log(chalk.gray(`    (e.g. \`kill ${lock.ownerPid}\`, or close its terminal), then start again.`));
+        process.exit(1);
+    }
     // Detect Python. Fast path: a supported host interpreter (3.10–3.12). If the
     // host only has an unsupported/newer Python (Homebrew now ships 3.13/3.14 as
     // `python3`) — or none at all — we PROVISION a managed CPython 3.12 via uv, so

package/dist/pythonEnv.js

@@ -496,12 +496,38 @@ export async function ensurePythonEnv(systemPython, expectedVersion, onProgress
     // this passes, so a half-built venv is never cached as valid: the next
     // launch re-enters this rebuild path and self-heals instead of returning a
     // broken venv as ok.
-    const probe = await runProc(venvPython(), ["-c", "import shortuuid, agentscope, anthropic, openai"], onProgress, { PYTHONPATH: CACHE_DIR });
+    // Importing the in-house agentscope eagerly loads its full submodule tree
+    // (model/tool/rag/embedding/…), so it drags in every third-party dep at load
+    // time. A single broken wheel therefore surfaces here as an "agentscope"
+    // failure even though our package is fine. Import each name in turn and, on
+    // the FIRST failure, emit a machine-parseable PROBE_FAIL line naming the exact
+    // module + error — captured below so the reason names the real culprit instead
+    // of the useless "agentscope import failed" (which sent every Mac 3.14→3.12
+    // dep breakage back as an unactionable message).
+    let probeErr = "";
+    const probe = await runProc(venvPython(), ["-c",
+        "import sys\n" +
+            "for _m in ('shortuuid','agentscope','anthropic','openai'):\n" +
+            "    try:\n" +
+            "        __import__(_m)\n" +
+            "    except Exception as _e:\n" +
+            "        import traceback\n" +
+            "        sys.stderr.write('PROBE_FAIL module=%s %s: %s\\n' % (_m, type(_e).__name__, _e))\n" +
+            "        traceback.print_exc()\n" +
+            "        sys.exit(1)\n",
+    ], (line) => {
+        if (/^PROBE_FAIL /.test(line))
+            probeErr = line.replace(/^PROBE_FAIL\s+/, "").trim();
+        onProgress(line);
+    }, { PYTHONPATH: CACHE_DIR });
     if (probe !== 0) {
+        const where = venvMinorVersion() === null ? "" : `Python 3.${venvMinorVersion()} `;
         return {
             ok: false,
             pythonPath: systemPython,
-            reason: `agentscope import probe failed on the ${venvMinorVersion() === null ? "" : `Python 3.${venvMinorVersion()} `}venv — the deps above did not import. See the pip lines above for the cause; the venv will be rebuilt on next launch.`,
+            reason: probeErr
+                ? `${where}venv import probe failed — ${probeErr}. Importing agentscope loads its whole dependency tree, so this is the dep that broke (not agentscope itself). See the traceback above; the venv will be rebuilt on next launch.`
+                : `agentscope import probe failed on the ${where}venv — a dependency did not import. See the lines above; the venv will be rebuilt on next launch.`,
         };
     }
     writeFileSync(VENV_MARK, venvMarkerValue(expectedVersion), "utf-8");

package/dist/singleInstance.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Single-instance guard for the runner.
+ *
+ * Two `@melaya/runner` processes for the same user fight over one server-side
+ * session: the server routes an assistant/pipeline turn to ONE socket, so a
+ * second runner produces connect/disconnect churn, split state, and turns that
+ * land on the wrong host. This lock makes a second launch on the same machine
+ * refuse up front ("can't start if another is already open") instead of quietly
+ * competing.
+ *
+ * Machine-scoped by design: it prevents the common footgun (double-launching on
+ * one box). It does NOT stop a runner on a *different* machine — that's a
+ * legitimate multi-device case, and the server's own per-user limit + the
+ * session reattach logic handle cross-machine arbitration.
+ *
+ * The lock is a small JSON file holding the owning pid. A stale lock (owner pid
+ * no longer alive — e.g. a hard kill that skipped cleanup) is reclaimed
+ * automatically, so a crash never permanently blocks the next start.
+ */
+export type LockResult = {
+    ok: true;
+} | {
+    ok: false;
+    ownerPid: number;
+};
+/**
+ * Try to acquire the machine-wide runner lock. Returns {ok:true} and installs
+ * process-exit cleanup on success; {ok:false, ownerPid} if a live runner
+ * already holds it. A stale lock (dead owner) is reclaimed.
+ */
+export declare function acquireSingleInstanceLock(): LockResult;

package/dist/singleInstance.js

@@ -0,0 +1,116 @@
+/**
+ * Single-instance guard for the runner.
+ *
+ * Two `@melaya/runner` processes for the same user fight over one server-side
+ * session: the server routes an assistant/pipeline turn to ONE socket, so a
+ * second runner produces connect/disconnect churn, split state, and turns that
+ * land on the wrong host. This lock makes a second launch on the same machine
+ * refuse up front ("can't start if another is already open") instead of quietly
+ * competing.
+ *
+ * Machine-scoped by design: it prevents the common footgun (double-launching on
+ * one box). It does NOT stop a runner on a *different* machine — that's a
+ * legitimate multi-device case, and the server's own per-user limit + the
+ * session reattach logic handle cross-machine arbitration.
+ *
+ * The lock is a small JSON file holding the owning pid. A stale lock (owner pid
+ * no longer alive — e.g. a hard kill that skipped cleanup) is reclaimed
+ * automatically, so a crash never permanently blocks the next start.
+ */
+import { mkdirSync, readFileSync, unlinkSync, openSync, writeSync, closeSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const CACHE_DIR = join(homedir(), ".melaya-runner");
+const LOCK_PATH = join(CACHE_DIR, "runner.lock");
+function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        // Signal 0 does not send a signal — it only checks the process exists.
+        // Throws ESRCH if gone, EPERM if alive but owned by another user (still
+        // "alive" for our purposes). Works on Windows too.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code === "EPERM";
+    }
+}
+/**
+ * Try to acquire the machine-wide runner lock. Returns {ok:true} and installs
+ * process-exit cleanup on success; {ok:false, ownerPid} if a live runner
+ * already holds it. A stale lock (dead owner) is reclaimed.
+ */
+export function acquireSingleInstanceLock() {
+    mkdirSync(CACHE_DIR, { recursive: true });
+    const writeOwn = () => {
+        // O_EXCL create: fails if the file already exists, which makes the
+        // check-and-claim atomic against another runner racing to start.
+        const fd = openSync(LOCK_PATH, "wx");
+        try {
+            writeSync(fd, JSON.stringify({ pid: process.pid, startedAt: Date.now() }));
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+    try {
+        writeOwn();
+    }
+    catch (e) {
+        if (e?.code !== "EEXIST")
+            throw e;
+        // A lock exists — is its owner still alive?
+        let ownerPid = 0;
+        try {
+            ownerPid = Number(JSON.parse(readFileSync(LOCK_PATH, "utf-8"))?.pid) || 0;
+        }
+        catch {
+            ownerPid = 0;
+        }
+        if (ownerPid && ownerPid !== process.pid && pidAlive(ownerPid)) {
+            return { ok: false, ownerPid };
+        }
+        // Stale (dead owner) or unreadable — reclaim it.
+        try {
+            unlinkSync(LOCK_PATH);
+        }
+        catch { /* someone else may have just cleaned it */ }
+        try {
+            writeOwn();
+        }
+        catch (e2) {
+            // Lost a reclaim race to another starting runner.
+            if (e2?.code === "EEXIST") {
+                let pid2 = 0;
+                try {
+                    pid2 = Number(JSON.parse(readFileSync(LOCK_PATH, "utf-8"))?.pid) || 0;
+                }
+                catch {
+                    pid2 = 0;
+                }
+                return { ok: false, ownerPid: pid2 || -1 };
+            }
+            throw e2;
+        }
+    }
+    // Release the lock on every normal or signalled exit. Only unlink if WE still
+    // own it, so a reclaimed-after-crash successor never deletes the live owner's.
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        try {
+            const held = Number(JSON.parse(readFileSync(LOCK_PATH, "utf-8"))?.pid) || 0;
+            if (held === process.pid)
+                unlinkSync(LOCK_PATH);
+        }
+        catch { /* already gone */ }
+    };
+    process.on("exit", release);
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.on(sig, () => { release(); process.exit(0); });
+    }
+    return { ok: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melaya/runner",
-  "version": "1.1.33",
+  "version": "1.1.35",
   "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
   "license": "UNLICENSED",
   "private": false,