@melaya/runner 1.1.68 → 1.1.70

package/dist/sharedVendor.js

@@ -13,6 +13,7 @@ import { homedir, setPriority } from "os";
 import { spawn } from "child_process";
 import { createHash, createHmac, timingSafeEqual } from "crypto";
 import { venvPython } from "./pythonEnv.js";
+import { trackChild } from "./processTree.js";
 const CACHE_DIR = join(homedir(), ".melaya-runner");
 const SHARED_DIR = join(CACHE_DIR, "shared");
 const VERSION_FILE = join(CACHE_DIR, "shared-version.txt");
@@ -162,7 +163,8 @@ function precompileInBackground() {
         const dirs = ["shared", "agentscope", "crews"].map((d) => join(CACHE_DIR, d)).filter((d) => existsSync(d));
         if (!dirs.length)
             return;
-        const child = spawn(py, ["-m", "compileall", "-q", "-j", "2", ...dirs], { stdio: "ignore", windowsHide: true, detached: false });
+        // Tracked: runner shutdown stops it instead of leaving it compiling.
+        const child = trackChild(spawn(py, ["-m", "compileall", "-q", "-j", "2", ...dirs], { stdio: "ignore", windowsHide: true, detached: false }));
         child.on("error", () => { });
         if (child.pid) {
             try {

package/dist/singleInstance.js

@@ -20,6 +20,7 @@
 import { mkdirSync, readFileSync, unlinkSync, openSync, writeSync, closeSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { gracefulShutdownClaimed } from "./processTree.js";
 const CACHE_DIR = join(homedir(), ".melaya-runner");
 const LOCK_PATH = join(CACHE_DIR, "runner.lock");
 function pidAlive(pid) {
@@ -110,7 +111,15 @@ export function acquireSingleInstanceLock() {
     };
     process.on("exit", release);
     for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
-        process.on(sig, () => { release(); process.exit(0); });
+        // Once connection.ts owns a graceful shutdown (SIGINT/SIGTERM), let it
+        // finish: it exits on its own and "exit" above releases the lock then, so
+        // a successor cannot start while this runner's children are still stopping.
+        process.on(sig, () => {
+            if (sig !== "SIGHUP" && gracefulShutdownClaimed())
+                return;
+            release();
+            process.exit(0);
+        });
     }
     return { ok: true };
 }

package/dist/startupCache.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Last good startup facts, so the next start can connect at once:
+ * ~/.melaya-runner/startup-cache.json holds the last published model list and
+ * the Python interpreter that worked. The runner connects with these, then
+ * publishes fresh discovery through `runner:models` when it lands.
+ *
+ * Model names only (no credentials, no tokens). A missing or malformed file
+ * reads as empty; writes are best-effort and atomic (temp file + rename).
+ */
+import type { DetectedModel } from "./detect.js";
+export interface StartupCache {
+    models?: DetectedModel[];
+    modelsAt?: number;
+    python?: {
+        cmd: string;
+        minor: number;
+        provisioned?: boolean;
+    };
+}
+export declare function startupCachePath(dir?: string): string;
+export declare function readStartupCache(path?: string): StartupCache;
+export declare function writeStartupCache(patch: StartupCache, path?: string): void;

package/dist/startupCache.js

@@ -0,0 +1,45 @@
+/**
+ * Last good startup facts, so the next start can connect at once:
+ * ~/.melaya-runner/startup-cache.json holds the last published model list and
+ * the Python interpreter that worked. The runner connects with these, then
+ * publishes fresh discovery through `runner:models` when it lands.
+ *
+ * Model names only (no credentials, no tokens). A missing or malformed file
+ * reads as empty; writes are best-effort and atomic (temp file + rename).
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const PROVIDERS = new Set(["lmstudio", "ollama", "claude_code", "codex", "github_copilot"]);
+export function startupCachePath(dir = join(homedir(), ".melaya-runner")) {
+    return join(dir, "startup-cache.json");
+}
+export function readStartupCache(path = startupCachePath()) {
+    try {
+        const j = JSON.parse(readFileSync(path, "utf-8"));
+        const out = {};
+        if (Array.isArray(j.models)) {
+            out.models = j.models
+                .filter((m) => m && PROVIDERS.has(String(m.provider)) && typeof m.name === "string" && m.name.length > 0 && m.name.length < 200)
+                .slice(0, 500);
+            out.modelsAt = Number(j.modelsAt) || 0;
+        }
+        if (j.python && typeof j.python.cmd === "string" && Number.isInteger(j.python.minor)) {
+            out.python = { cmd: j.python.cmd, minor: j.python.minor, ...(j.python.provisioned ? { provisioned: true } : {}) };
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+export function writeStartupCache(patch, path = startupCachePath()) {
+    try {
+        const next = { ...readStartupCache(path), ...patch };
+        mkdirSync(join(path, ".."), { recursive: true });
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(next), { encoding: "utf-8", mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch { /* best-effort: the next start just discovers again */ }
+}

package/dist/startupTimings.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Startup stage timestamps: where the time goes between process start and a
+ * runner that is online with its models and Python ready.
+ *
+ * Stages (first mark wins, epoch ms):
+ *   process_start     the Node process began (performance.timeOrigin)
+ *   config            options parsed and the token is in hand
+ *   socket_connected  the Socket.IO handshake succeeded
+ *   online            hello sent, relay up: the server can route work here
+ *   python_ready      a supported Python interpreter is resolved
+ *   discovery_done    the local model scan finished and was published
+ *
+ * The socket no longer waits for Python or discovery, so the last two usually
+ * land after `online`. Reported to the desktop app (log line + a "timings"
+ * host message) and printed with --diagnostics.
+ */
+export declare const STARTUP_STAGES: readonly ["process_start", "config", "socket_connected", "online", "python_ready", "discovery_done"];
+export type StartupStage = (typeof STARTUP_STAGES)[number];
+/** Record a stage once. Later marks of the same stage are ignored. */
+export declare function markStage(stage: StartupStage, at?: number): void;
+/** Called after every new stage mark. Returns an unsubscribe function. */
+export declare function onStage(cb: (stage: StartupStage, at: number) => void): () => void;
+export declare function stageMarked(stage: StartupStage): boolean;
+/** True once every stage has been recorded. */
+export declare function startupComplete(): boolean;
+/** Epoch timestamps and offsets from process start, in stage order. */
+export declare function startupTimings(): {
+    at: Partial<Record<StartupStage, number>>;
+    sinceStartMs: Partial<Record<StartupStage, number>>;
+};
+/** Human-readable timeline, one stage per line. */
+export declare function formatStartupTimings(): string;
+/** Test seam. */
+export declare function _resetStartupTimings(): void;

package/dist/startupTimings.js

@@ -0,0 +1,81 @@
+/**
+ * Startup stage timestamps: where the time goes between process start and a
+ * runner that is online with its models and Python ready.
+ *
+ * Stages (first mark wins, epoch ms):
+ *   process_start     the Node process began (performance.timeOrigin)
+ *   config            options parsed and the token is in hand
+ *   socket_connected  the Socket.IO handshake succeeded
+ *   online            hello sent, relay up: the server can route work here
+ *   python_ready      a supported Python interpreter is resolved
+ *   discovery_done    the local model scan finished and was published
+ *
+ * The socket no longer waits for Python or discovery, so the last two usually
+ * land after `online`. Reported to the desktop app (log line + a "timings"
+ * host message) and printed with --diagnostics.
+ */
+import { sendToHost } from "./hostChannel.js";
+export const STARTUP_STAGES = ["process_start", "config", "socket_connected", "online", "python_ready", "discovery_done"];
+const marks = new Map();
+const listeners = new Set();
+function processStart() {
+    const origin = typeof performance !== "undefined" && performance.timeOrigin ? performance.timeOrigin : 0;
+    return Math.round(origin || Date.now() - process.uptime() * 1000);
+}
+/** Record a stage once. Later marks of the same stage are ignored. */
+export function markStage(stage, at = Date.now()) {
+    if (!marks.has("process_start"))
+        marks.set("process_start", processStart());
+    if (marks.has(stage))
+        return;
+    marks.set(stage, at);
+    const start = marks.get("process_start");
+    sendToHost({ type: "log", level: "info", line: `startup: ${stage} +${Math.max(0, at - start)}ms` });
+    sendToHost({ type: "timings", stages: startupTimings().sinceStartMs });
+    for (const l of listeners) {
+        try {
+            l(stage, at);
+        }
+        catch { /* listener errors never matter */ }
+    }
+}
+/** Called after every new stage mark. Returns an unsubscribe function. */
+export function onStage(cb) {
+    listeners.add(cb);
+    return () => { listeners.delete(cb); };
+}
+export function stageMarked(stage) {
+    return marks.has(stage);
+}
+/** True once every stage has been recorded. */
+export function startupComplete() {
+    return STARTUP_STAGES.every((s) => marks.has(s));
+}
+/** Epoch timestamps and offsets from process start, in stage order. */
+export function startupTimings() {
+    if (!marks.has("process_start"))
+        marks.set("process_start", processStart());
+    const start = marks.get("process_start");
+    const at = {};
+    const sinceStartMs = {};
+    for (const s of STARTUP_STAGES) {
+        const v = marks.get(s);
+        if (v === undefined)
+            continue;
+        at[s] = v;
+        sinceStartMs[s] = Math.max(0, v - start);
+    }
+    return { at, sinceStartMs };
+}
+/** Human-readable timeline, one stage per line. */
+export function formatStartupTimings() {
+    const { sinceStartMs } = startupTimings();
+    return STARTUP_STAGES
+        .map((s) => `${s.padEnd(17)} ${sinceStartMs[s] === undefined ? "pending" : `+${sinceStartMs[s]}ms`}`)
+        .join("\n");
+}
+/** Test seam. */
+export function _resetStartupTimings() {
+    marks.clear();
+    listeners.clear();
+}

package/dist/uvBootstrap.js

@@ -18,7 +18,8 @@
 import { existsSync, mkdirSync, writeFileSync, chmodSync, rmSync, readdirSync, statSync, copyFileSync } from "fs";
 import { join } from "path";
 import { homedir, platform, arch } from "os";
-import { spawn, execSync } from "child_process";
+import { execFile } from "child_process";
+import { spawnTracked as spawn, registerSetupChild, terminateTree } from "./processTree.js";
 const CACHE_DIR = join(homedir(), ".melaya-runner");
 const BIN_DIR = join(CACHE_DIR, "bin");
 const isWin = platform() === "win32";
@@ -40,27 +41,28 @@ function assetName() {
         return a === "arm64" ? "uv-aarch64-pc-windows-msvc.zip" : "uv-x86_64-pc-windows-msvc.zip";
     return null;
 }
-function tryExec(cmd) {
-    try {
-        return execSync(cmd, { encoding: "utf-8", timeout: 8000, stdio: ["pipe", "pipe", "pipe"] }).trim() || null;
-    }
-    catch {
-        return null;
-    }
-}
+// PATH lookup without a shell or a blocking subprocess: Python provisioning
+// now runs after the socket connects, so nothing here may stall the event loop.
 function findOnPath(bin) {
-    const out = tryExec(isWin ? `where ${bin}` : `command -v ${bin}`);
-    if (!out)
-        return null;
-    const first = out.split(/\r?\n/)[0].trim();
-    return first || null;
+    const sep = isWin ? ";" : ":";
+    for (const dir of (process.env.PATH || process.env.Path || "").split(sep)) {
+        if (!dir)
+            continue;
+        const cand = join(dir, bin);
+        try {
+            if (existsSync(cand) && statSync(cand).isFile())
+                return cand;
+        }
+        catch { /* unreadable dir */ }
+    }
+    return null;
 }
 // Inactivity-bounded child runner (mirrors pythonEnv.runProc): a managed-CPython
 // download legitimately takes a while but streams progress, so we bound silence.
 function run(cmd, args, onLine, opts = {}) {
     const inactivityMs = opts.inactivityMs ?? 5 * 60_000;
     return new Promise((resolve) => {
-        const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...opts.env }, cwd: opts.cwd });
+        const child = registerSetupChild(spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...opts.env }, cwd: opts.cwd }));
         let done = false;
         let timer;
         const finish = (c) => { if (done)
@@ -69,10 +71,7 @@ function run(cmd, args, onLine, opts = {}) {
         const bump = () => {
             if (timer)
                 clearTimeout(timer);
-            timer = setTimeout(() => { try {
-                child.kill("SIGKILL");
-            }
-            catch { /* gone */ } onLine(`(no output for ${Math.round(inactivityMs / 60000)}m — killed ${cmd})`); finish(1); }, inactivityMs);
+            timer = setTimeout(() => { void terminateTree(child, { graceMs: 0 }); onLine(`(no output for ${Math.round(inactivityMs / 60000)}m — killed ${cmd})`); finish(1); }, inactivityMs);
         };
         const chew = (b) => { bump(); for (const ln of b.toString().split("\n")) {
             const t = ln.trimEnd();
@@ -88,11 +87,14 @@ function run(cmd, args, onLine, opts = {}) {
 }
 function capture(cmd, args, env = {}) {
     return new Promise((resolve) => {
-        let out = "";
-        const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...env } });
-        child.stdout?.on("data", (b) => { out += b.toString(); });
-        child.on("exit", () => resolve(out.trim()));
-        child.on("error", () => resolve(""));
+        try {
+            execFile(cmd, args, { env: { ...process.env, ...env }, timeout: 30_000, windowsHide: true, encoding: "utf-8" }, (err, stdout) => {
+                resolve(err ? "" : String(stdout || "").trim());
+            });
+        }
+        catch {
+            resolve("");
+        }
     });
 }
 // Extract the downloaded uv archive. uv ships .tar.gz for macOS/Linux and .zip
@@ -223,6 +225,12 @@ export async function provisionPython(version, onLine) {
     const uv = await ensureUv(onLine);
     if (!uv)
         return null;
+    // Fast path: a Python of this version uv already knows (provisioned on an
+    // earlier start): no install step, no network.
+    // --system: never a virtual environment that happens to be active or in cwd.
+    const known = await capture(uv, ["python", "find", "--system", version], { UV_SYSTEM_CERTS: "1" });
+    if (known && existsSync(known))
+        return known;
     onLine(`installing a managed Python ${version} (one-time; ~30-60s)`);
     // UV_SYSTEM_CERTS makes uv verify against the OS trust store instead of its
     // bundled webpki roots — required behind TLS-intercepting proxies/antivirus

package/dist/vaults.js

@@ -21,6 +21,7 @@
 import { createPublicKey, verify as cryptoVerify, randomBytes } from "crypto";
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, watch as fsWatch, writeFileSync, } from "fs";
 import { spawn } from "child_process";
+import { trackChild } from "./processTree.js";
 import { homedir, platform as osPlatform } from "os";
 import path from "path";
 import { Readable } from "stream";
@@ -482,7 +483,8 @@ export class VaultHostProcess {
             return this.starting;
         this.starting = (async () => {
             const l = await this.o.launch();
-            const p = spawn(l.pythonPath, ["-u", l.scriptPath], { env: l.env, cwd: l.cwd, stdio: ["pipe", "pipe", "pipe"] });
+            // Tracked: runner shutdown stops it even if stop()'s delayed kill never fires.
+            const p = trackChild(spawn(l.pythonPath, ["-u", l.scriptPath], { env: l.env, cwd: l.cwd, stdio: ["pipe", "pipe", "pipe"] }));
             // EPIPE after a crash surfaces here; the exit handler does the cleanup.
             p.stdin?.on("error", () => { });
             p.stdout?.setEncoding("utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melaya/runner",
-  "version": "1.1.68",
+  "version": "1.1.70",
   "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
   "license": "Apache-2.0",
   "author": "Melaya Labs LLC",