@melaya/runner 1.1.67 → 1.1.69

package/dist/hostFiles.js

@@ -0,0 +1,90 @@
+/**
+ * Files this runner produced on the computer, reported to the Melaya desktop
+ * app (contract ComputerRunnerFileMessage, { type: "computer.file" }) so
+ * computer control can open them or pick them in a file dialog by handle.
+ *
+ * Only inside the desktop app (hostChannel.isHosted()); under `npx` every
+ * function here is a no-op. The path goes to the app's main process over the
+ * parentPort and never to the server: the app turns it into an opaque handle.
+ *
+ * Sources: Assistant turn output files (after assistantFiles.ts accepted them)
+ * and pipeline outputs written to MELAYA_OUTPUT_DIR during a run. Browser
+ * downloads are denied by the browser bridge (acceptDownloads: false), so there
+ * is nothing to report from there.
+ */
+import { lstatSync, readdirSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { isHosted, sendToHost } from "./hostChannel.js";
+/** Never offered to computer actions as a file handle. */
+const BLOCKED_EXT = new Set([
+    "exe", "msi", "bat", "cmd", "com", "scr", "ps1", "vbs", "js", "jse", "wsf", "hta", "lnk", "reg", "jar",
+    "dll", "app", "pkg", "dmg", "sh", "command", "py", "pyc",
+]);
+/** At most this many files per run, so a tool that writes thousands of files cannot flood the host. */
+export const MAX_REPORTED_PER_RUN = 25;
+function reportable(path) {
+    try {
+        const st = lstatSync(path);
+        if (!st.isFile() || st.isSymbolicLink() || st.size <= 0)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const ext = extname(path).slice(1).toLowerCase();
+    return !!ext && !BLOCKED_EXT.has(ext);
+}
+/** Report one file. Returns true when a message was sent. */
+export function reportHostFile(path, origin) {
+    if (!isHosted() || typeof path !== "string" || !path)
+        return false;
+    if (!reportable(path))
+        return false;
+    sendToHost({ type: "computer.file", path, name: basename(path), origin });
+    return true;
+}
+/**
+ * Files in `dir` (and one level of sub-folders) modified at or after `sinceMs`,
+ * newest first, capped. Pure apart from reading the folder.
+ */
+export function filesWrittenSince(dir, sinceMs, max = MAX_REPORTED_PER_RUN) {
+    const out = [];
+    const walk = (d, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = join(d, e.name);
+            if (e.isDirectory()) {
+                if (depth < 1)
+                    walk(p, depth + 1);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            try {
+                const m = lstatSync(p).mtimeMs;
+                // 2 s of slack for filesystems with coarse timestamps.
+                if (m >= sinceMs - 2000)
+                    out.push({ p, m });
+            }
+            catch { /* gone */ }
+        }
+    };
+    walk(dir, 0);
+    return out.sort((a, b) => b.m - a.m).slice(0, max).map((x) => x.p);
+}
+/** After a run: report the outputs it wrote. No-op outside the desktop app. */
+export function reportOutputsSince(dir, sinceMs) {
+    if (!isHosted() || !dir)
+        return 0;
+    let n = 0;
+    for (const p of filesWrittenSince(dir, sinceMs))
+        if (reportHostFile(p, "output"))
+            n++;
+    return n;
+}

package/dist/linkedinLogin.js

@@ -40,6 +40,7 @@
  */
 import { spawn } from "child_process";
 import chalk from "chalk";
+import { launchInstalledBrowser, ProvisionError } from "./browserProvisioner.js";
 const LOGIN_TIMEOUT_MS = 5 * 60_000; // 5 min for the user to finish typing
 const POLL_INTERVAL_MS = 750;
 // URL fragments that indicate "the user is logged in" — LinkedIn redirects
@@ -163,26 +164,21 @@ export async function runLinkedInLoginFlow(progress) {
     let browser = null;
     try {
         progress("Opening LinkedIn login window…");
+        // One provisioner for every headed flow (browserProvisioner.ts): installed
+        // Chrome, then Edge, then Brave. Downloading Chromium through npx is a
+        // CLI-only last resort; the desktop app gets a clear "install Chrome or
+        // Edge" instead (audit P1.4).
         try {
-            browser = await playwright.chromium.launch({
-                headless: false,
-                channel: "chrome",
+            ({ browser } = await launchInstalledBrowser((o) => playwright.chromium.launch(o), {
                 args: ["--disable-blink-features=AutomationControlled"],
-            });
+                progress,
+                downloadChromium: () => _installChromium(progress),
+            }));
         }
-        catch (chromeErr) {
-            progress(`System Chrome not available (${(chromeErr?.message || chromeErr).toString().split("\n")[0]}); ` +
-                `falling back to the bundled browser.`);
-            try {
-                await _installChromium(progress);
-            }
-            catch (e) {
-                return { ok: false, error: "chromium_install_failed", detail: e?.message };
-            }
-            browser = await playwright.chromium.launch({
-                headless: false,
-                args: ["--disable-blink-features=AutomationControlled"],
-            });
+        catch (e) {
+            if (e instanceof ProvisionError)
+                return { ok: false, error: "browser_not_installed", detail: e.instructions || e.message };
+            return { ok: false, error: "chromium_install_failed", detail: e?.message };
         }
         _activeLoginBrowser = browser;
         const context = await browser.newContext({

package/dist/lumaLogin.js

@@ -23,6 +23,7 @@
  */
 import { spawn } from "child_process";
 import chalk from "chalk";
+import { launchInstalledBrowser, ProvisionError } from "./browserProvisioner.js";
 const LOGIN_TIMEOUT_MS = 5 * 60_000;
 const POLL_INTERVAL_MS = 750;
 // Pages that mean "logged in to Luma". Luma's web app routes the user to
@@ -128,26 +129,19 @@ export async function runLumaLoginFlow(progress) {
     let browser = null;
     try {
         progress("Opening Luma login window…");
+        // Same provisioner as LinkedIn (browserProvisioner.ts): installed Chrome,
+        // Edge, Brave; npx Chromium download only from the CLI (audit P1.4).
         try {
-            browser = await playwright.chromium.launch({
-                headless: false,
-                channel: "chrome",
+            ({ browser } = await launchInstalledBrowser((o) => playwright.chromium.launch(o), {
                 args: ["--disable-blink-features=AutomationControlled"],
-            });
+                progress,
+                downloadChromium: () => _installChromium(progress),
+            }));
         }
-        catch (chromeErr) {
-            progress(`System Chrome not available (${(chromeErr?.message || chromeErr).toString().split("\n")[0]}); ` +
-                `falling back to the bundled browser.`);
-            try {
-                await _installChromium(progress);
-            }
-            catch (e) {
-                return { ok: false, error: "chromium_install_failed", detail: e?.message };
-            }
-            browser = await playwright.chromium.launch({
-                headless: false,
-                args: ["--disable-blink-features=AutomationControlled"],
-            });
+        catch (e) {
+            if (e instanceof ProvisionError)
+                return { ok: false, error: "browser_not_installed", detail: e.instructions || e.message };
+            return { ok: false, error: "chromium_install_failed", detail: e?.message };
         }
         _activeLoginBrowser = browser;
         const context = await browser.newContext({

package/dist/processTree.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Child process trees: spawn, track, and stop them for sure.
+ *
+ * A runner child (pipeline Python, Assistant host, RAG ingest, venv build) can
+ * start its own children (a CLI model provider, a browser, pip). Killing only
+ * the direct child leaves those grandchildren running after the runner exits.
+ *
+ * - POSIX: every tracked child is spawned as the leader of its own process
+ *   group (`detached: true`), so one signal to `-pid` reaches the whole tree.
+ * - Windows: `taskkill /PID <pid> /T` first (asks windowed processes such as
+ *   browsers to close), then `taskkill /PID <pid> /T /F` after the grace period.
+ *
+ * Every tracked child is also killed synchronously on process exit, so a crash
+ * or a `process.exit()` elsewhere does not leave orphans.
+ */
+import { spawn as rawSpawn, type ChildProcess } from "child_process";
+/** Track a child so shutdown (and process exit) stops its whole tree. Returns the child. */
+export declare function trackChild<T extends ChildProcess>(child: T): T;
+/** Live tracked children (for diagnostics and tests). */
+export declare function trackedChildren(): ChildProcess[];
+/**
+ * Drop-in replacement for child_process.spawn: the child leads its own process
+ * group on POSIX (unless the caller set `detached` itself) and is tracked.
+ * Windows keeps the default (detached there means a new console window).
+ */
+export declare const spawnTracked: typeof rawSpawn;
+/**
+ * Stop a child and every descendant: a graceful request first, then a forced
+ * kill once `graceMs` has passed. Resolves when the tree is gone (or the forced
+ * kill was issued). Never throws.
+ */
+export declare function terminateTree(child: ChildProcess, opts?: {
+    graceMs?: number;
+}): Promise<void>;
+/** Stop every tracked child tree, in parallel, within the grace period. */
+export declare function terminateAllTracked(opts?: {
+    graceMs?: number;
+}): Promise<number>;
+/** Last resort on process exit: synchronous forced kill of every tracked tree. */
+export declare function killAllTrackedSync(): void;
+export interface ShutdownStep {
+    name: string;
+    /** Upper bound for this step; the shutdown moves on when it passes. */
+    deadlineMs: number;
+    run: () => unknown | Promise<unknown>;
+}
+export interface ShutdownStepResult {
+    name: string;
+    outcome: "ok" | "timeout" | "error";
+    ms: number;
+    error?: string;
+}
+/** Run independent shutdown steps in parallel, each bounded by its own deadline. */
+export declare function runShutdownSteps(steps: ShutdownStep[]): Promise<ShutdownStepResult[]>;
+/** One line for logs: "runs ok 12ms, browsers timeout 3000ms". */
+export declare function formatShutdownResults(results: ShutdownStepResult[]): string;
+export declare function claimGracefulShutdown(): void;
+export declare function gracefulShutdownClaimed(): boolean;
+/** Run this child below normal priority for its whole life (fire-and-forget warm-ups). */
+export declare function lowerPriority(child: ChildProcess): ChildProcess;
+/** Mark a setup child; it runs below normal priority while setup is in background mode. */
+export declare function registerSetupChild(child: ChildProcess): ChildProcess;
+/** Background mode on: new setup children start below normal priority. */
+export declare function setSetupBackground(on: boolean): void;
+export declare function setupIsBackground(): boolean;

package/dist/processTree.js

@@ -0,0 +1,237 @@
+/**
+ * Child process trees: spawn, track, and stop them for sure.
+ *
+ * A runner child (pipeline Python, Assistant host, RAG ingest, venv build) can
+ * start its own children (a CLI model provider, a browser, pip). Killing only
+ * the direct child leaves those grandchildren running after the runner exits.
+ *
+ * - POSIX: every tracked child is spawned as the leader of its own process
+ *   group (`detached: true`), so one signal to `-pid` reaches the whole tree.
+ * - Windows: `taskkill /PID <pid> /T` first (asks windowed processes such as
+ *   browsers to close), then `taskkill /PID <pid> /T /F` after the grace period.
+ *
+ * Every tracked child is also killed synchronously on process exit, so a crash
+ * or a `process.exit()` elsewhere does not leave orphans.
+ */
+import { spawn as rawSpawn, spawnSync, execFile } from "child_process";
+import os from "os";
+const isWin = process.platform === "win32";
+const tracked = new Set();
+let exitHookInstalled = false;
+function alive(child) {
+    return child.exitCode === null && child.signalCode === null && typeof child.pid === "number";
+}
+/** Track a child so shutdown (and process exit) stops its whole tree. Returns the child. */
+export function trackChild(child) {
+    if (!child || typeof child.pid !== "number")
+        return child;
+    tracked.add(child);
+    const forget = () => { tracked.delete(child); };
+    child.once("exit", forget);
+    child.once("error", forget);
+    if (!exitHookInstalled) {
+        exitHookInstalled = true;
+        process.on("exit", killAllTrackedSync);
+    }
+    return child;
+}
+/** Live tracked children (for diagnostics and tests). */
+export function trackedChildren() {
+    return [...tracked].filter(alive);
+}
+/**
+ * Drop-in replacement for child_process.spawn: the child leads its own process
+ * group on POSIX (unless the caller set `detached` itself) and is tracked.
+ * Windows keeps the default (detached there means a new console window).
+ */
+export const spawnTracked = ((command, argsOrOptions, maybeOptions) => {
+    const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+    const given = ((Array.isArray(argsOrOptions) ? maybeOptions : argsOrOptions) ?? {});
+    const opts = { ...given };
+    if (!isWin && opts.detached === undefined)
+        opts.detached = true;
+    if (isWin && opts.windowsHide === undefined)
+        opts.windowsHide = true;
+    return trackChild(rawSpawn(command, args, opts));
+});
+function taskkill(pid, force) {
+    return new Promise((resolve) => {
+        const args = ["/PID", String(pid), "/T"];
+        if (force)
+            args.push("/F");
+        try {
+            execFile("taskkill", args, { windowsHide: true, timeout: 5000 }, () => resolve());
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+function signalTree(child, signal) {
+    const pid = child.pid;
+    if (typeof pid !== "number")
+        return;
+    // Group first (covers grandchildren); the plain pid when it does not lead a group.
+    try {
+        process.kill(-pid, signal);
+        return;
+    }
+    catch { /* not a group leader, or gone */ }
+    try {
+        process.kill(pid, signal);
+    }
+    catch { /* gone */ }
+}
+function waitExit(child, ms) {
+    if (!alive(child))
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (v) => { if (done)
+            return; done = true; clearTimeout(t); resolve(v); };
+        const t = setTimeout(() => finish(!alive(child)), ms);
+        child.once("exit", () => finish(true));
+    });
+}
+/**
+ * Stop a child and every descendant: a graceful request first, then a forced
+ * kill once `graceMs` has passed. Resolves when the tree is gone (or the forced
+ * kill was issued). Never throws.
+ */
+export async function terminateTree(child, opts = {}) {
+    const graceMs = Math.max(0, opts.graceMs ?? 2000);
+    const pid = child?.pid;
+    if (typeof pid !== "number")
+        return;
+    if (isWin) {
+        if (alive(child)) {
+            if (graceMs > 0) {
+                await taskkill(pid, false);
+                if (await waitExit(child, graceMs))
+                    return;
+            }
+            await taskkill(pid, true);
+            await waitExit(child, 1000);
+        }
+        return;
+    }
+    if (graceMs > 0 && alive(child)) {
+        signalTree(child, "SIGTERM");
+        await waitExit(child, graceMs);
+    }
+    // Always sweep the group: the leader may be gone while a grandchild ignored SIGTERM.
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch { /* group already empty */ }
+    if (alive(child)) {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch { /* gone */ }
+        await waitExit(child, 1000);
+    }
+}
+/** Stop every tracked child tree, in parallel, within the grace period. */
+export async function terminateAllTracked(opts = {}) {
+    const live = [...tracked];
+    await Promise.all(live.map((c) => terminateTree(c, opts)));
+    return live.length;
+}
+/** Last resort on process exit: synchronous forced kill of every tracked tree. */
+export function killAllTrackedSync() {
+    for (const child of tracked) {
+        const pid = child.pid;
+        if (typeof pid !== "number")
+            continue;
+        if (isWin) {
+            if (!alive(child))
+                continue;
+            try {
+                spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, timeout: 3000 });
+            }
+            catch { /* ignore */ }
+        }
+        else {
+            try {
+                process.kill(-pid, "SIGKILL");
+            }
+            catch { /* not a leader / gone */ }
+            if (alive(child)) {
+                try {
+                    process.kill(pid, "SIGKILL");
+                }
+                catch { /* gone */ }
+            }
+        }
+    }
+    tracked.clear();
+}
+/** Run independent shutdown steps in parallel, each bounded by its own deadline. */
+export async function runShutdownSteps(steps) {
+    return Promise.all(steps.map(async (s) => {
+        const t0 = Date.now();
+        let timer;
+        const deadline = new Promise((resolve) => { timer = setTimeout(() => resolve("timeout"), Math.max(0, s.deadlineMs)); });
+        try {
+            const r = await Promise.race([Promise.resolve().then(s.run).then(() => "ok"), deadline]);
+            return { name: s.name, outcome: r, ms: Date.now() - t0 };
+        }
+        catch (e) {
+            return { name: s.name, outcome: "error", ms: Date.now() - t0, error: String(e?.message || e).slice(0, 200) };
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }));
+}
+/** One line for logs: "runs ok 12ms, browsers timeout 3000ms". */
+export function formatShutdownResults(results) {
+    return results.map((r) => `${r.name} ${r.outcome} ${r.ms}ms`).join(", ");
+}
+// ── Graceful shutdown ownership ───────────────────────────────────────────
+// connection.ts owns the graceful shutdown once the socket exists; other
+// signal handlers (singleInstance.ts) must then not exit the process under it.
+let gracefulClaimed = false;
+export function claimGracefulShutdown() { gracefulClaimed = true; }
+export function gracefulShutdownClaimed() { return gracefulClaimed; }
+// ── Background priority ───────────────────────────────────────────────────
+// Setup work (dependency installs, warm-ups) runs below normal priority while
+// nobody waits for it; a request that must wait promotes it back to normal.
+let backgroundMode = false;
+const setupChildren = new Set();
+function applyPriority(pid, low) {
+    try {
+        os.setPriority(pid, low ? os.constants.priority.PRIORITY_BELOW_NORMAL : os.constants.priority.PRIORITY_NORMAL);
+    }
+    catch { /* not permitted (raising priority back needs privileges on POSIX) */ }
+}
+/** Run this child below normal priority for its whole life (fire-and-forget warm-ups). */
+export function lowerPriority(child) {
+    if (typeof child?.pid === "number")
+        applyPriority(child.pid, true);
+    return child;
+}
+/** Mark a setup child; it runs below normal priority while setup is in background mode. */
+export function registerSetupChild(child) {
+    const pid = child?.pid;
+    if (typeof pid !== "number")
+        return child;
+    setupChildren.add(child);
+    child.once("exit", () => setupChildren.delete(child));
+    child.once("error", () => setupChildren.delete(child));
+    if (backgroundMode)
+        applyPriority(pid, true);
+    return child;
+}
+/** Background mode on: new setup children start below normal priority. */
+export function setSetupBackground(on) {
+    if (backgroundMode === on)
+        return;
+    backgroundMode = on;
+    for (const c of setupChildren)
+        if (typeof c.pid === "number" && alive(c))
+            applyPriority(c.pid, on);
+}
+export function setupIsBackground() { return backgroundMode; }

package/dist/publishGate.js

@@ -125,20 +125,30 @@ export function classifyControlEffect(name) {
     const n = String(name || "").toLowerCase().trim();
     if (!n)
         return null;
+    // The verb lists are accent-free ("reinitialiser", "creer"), so a real
+    // label ("Réinitialiser", "Créer", full-width "ＤＥＬＥＴＥ") is also tried
+    // folded. Escalation only: the raw name is still tried as before.
+    const f = foldName(n);
+    const has = (p) => containsPhrase(n, p) || (f !== n && containsPhrase(f, p));
     for (const p of PURCHASE_VERBS)
-        if (containsPhrase(n, p))
+        if (has(p))
             return "purchase";
     for (const p of DESTRUCTIVE_VERBS)
-        if (containsPhrase(n, p))
+        if (has(p))
             return "destructive";
     for (const p of ACCOUNT_VERBS)
-        if (containsPhrase(n, p))
+        if (has(p))
             return "account_change";
     for (const p of PUBLISH_VERBS)
-        if (containsPhrase(n, p))
+        if (has(p))
             return "publish";
     return null;
 }
+/** Case, diacritics, full/half-width forms and curly apostrophes folded. */
+function foldName(s) {
+    return s.normalize("NFKD").replace(/[̀-ͯ]/g, "").normalize("NFKC").toLowerCase()
+        .replace(/[‘’ʼ]/g, "'").replace(/[\s 　]+/g, " ").trim();
+}
 /** Does this effect need approval in the given autonomy mode?
  *    safe          -> gate every consequential write
  *    payments_only -> gate purchases AND the two irreversible families

package/dist/pythonEnv.js

@@ -9,8 +9,8 @@
  * Idempotent: re-uses the venv if a marker file matches the current
  * shared-bundle version. Re-bootstraps when the bundle version changes.
  */
-import { spawn } from "child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
+import { spawnTracked, registerSetupChild, terminateTree } from "./processTree.js";
 import { createHash } from "crypto";
 import { join } from "path";
 import { homedir, platform } from "os";
@@ -387,10 +387,12 @@ function runProc(cmd, args, onLine, envExtra = {},
 // (which every run, RAG ingest and assistant boot sits behind).
 inactivityMs = 10 * 60_000) {
     return new Promise((resolve) => {
-        const child = spawn(cmd, args, {
+        // Tracked (shutdown stops pip/uv and their children) and, while the setup
+        // runs in the background, below normal priority (processTree.ts).
+        const child = registerSetupChild(spawnTracked(cmd, args, {
             stdio: ["ignore", "pipe", "pipe"],
             env: { ...process.env, ...envExtra },
-        });
+        }));
         let done = false;
         let timer;
         const finish = (code) => {
@@ -405,10 +407,7 @@ inactivityMs = 10 * 60_000) {
             if (timer)
                 clearTimeout(timer);
             timer = setTimeout(() => {
-                try {
-                    child.kill("SIGKILL");
-                }
-                catch { /* already gone */ }
+                void terminateTree(child, { graceMs: 0 });
                 onLine(`[runProc] no output for ${Math.round(inactivityMs / 60000)} min — killing '${cmd}'`);
                 finish(1);
             }, inactivityMs);

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 */ }
+}