@melaya/runner 1.1.67 → 1.1.69

package/dist/connection.js

@@ -13,9 +13,12 @@
 import { io } from "socket.io-client";
 import chalk from "chalk";
 import ora from "ora";
-import { spawn } from "child_process";
+// Every child spawned here leads its own process group (POSIX) and is tracked,
+// so shutdown and runner:kill stop the whole tree (audit P0.5).
+import { spawnTracked as spawn, terminateTree, terminateAllTracked, runShutdownSteps, formatShutdownResults, claimGracefulShutdown, killAllTrackedSync, setSetupBackground, lowerPriority, } from "./processTree.js";
+import { markStage } from "./startupTimings.js";
 import { writeFileSync, mkdirSync, existsSync, readFileSync, copyFileSync } from "fs";
-import { dirname, join } from "path";
+import { dirname, isAbsolute, join } from "path";
 import { fileURLToPath } from "url";
 import { tmpdir, homedir, hostname } from "os";
 import { createHash, createHmac, timingSafeEqual } from "crypto";
@@ -25,7 +28,7 @@ import { startLocalRelay, setActiveProject } from "./localRelay.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 import { ensureSharedModules, getSharedDir } from "./sharedVendor.js";
-import { detectModels } from "./detect.js";
+import { scanProviders, providerFingerprint } from "./detect.js";
 import { startLumaBrowserBridge } from "./lumaBrowserBridge.js";
 // Melaya Browser (plan Sections 3/4/7): the governed browser control
 // bridge + its runner-side grant verifier and engine discovery.
@@ -43,6 +46,33 @@ import { VAULT_HOST_CAPABILITY, VaultHostProcess, VaultRegistry, VaultService, a
 // Obsidian app bridge: App ops through the user's running Obsidian (CLI /
 // Local REST API); the REST key stays in ~/.melaya-runner/vaults.
 import { ObsidianAppBridge } from "./obsidianApp.js";
+// Desktop app host channel: state changes for the app's tray and web UI (no-op under npx).
+import { hostStatus, isHosted, hostProgress, sendToHost } from "./hostChannel.js";
+// Desktop app: files this runner wrote are offered to computer control as handles (no-op under npx).
+import { reportHostFile, reportOutputsSince } from "./hostFiles.js";
+// Computer control: computer:command / computer:stop relayed to the desktop app
+// executor (or the CLI computer host); capabilities reported on connect.
+import { attachComputerRelay } from "./computerRelay.js";
+// Model rediscovery while connected (audit P2.3): every 15 min, and skipped
+// when the provider fingerprint (credential/cache file mtimes + local server
+// ports) is unchanged since the last scan, unless that scan is older than
+// MODEL_REFRESH_MAX_SKIP_MS (LM Studio / Ollama model lists can change with
+// the port still open).
+const MODEL_REFRESH_MS = 15 * 60_000;
+const MODEL_REFRESH_MAX_SKIP_MS = 60 * 60_000;
+// Background setup (audit P1.5): module download, Python dependencies, Claude
+// version probe, Python import warm-up. Starts only once the runner has been
+// online and idle (no runs, no Assistant boot) for BG_SETUP_IDLE_MS, at below-
+// normal priority. A request that needs it first does the work itself (same
+// singleflight), and is told when it waits on setup already in flight.
+const BG_SETUP_IDLE_MS = 15_000;
+const BG_SETUP_CHECK_MS = 5_000;
+// Shutdown budget (audit P0.5): every subsystem gets its own deadline and they
+// run in parallel; the slowest bound (SHUTDOWN_STEP_MS) plus the final sweep
+// stays inside the desktop app's 5 s hard exit (cli.ts stopHosted).
+const SHUTDOWN_STEP_MS = 3_000;
+const SHUTDOWN_CHILD_GRACE_MS = 2_000;
+const SHUTDOWN_SWEEP_MS = 800;
 // Same ceiling the builder enforces on RunRequest.trigger (48 KB UTF-8 of the
 // compact JSON) and the server dispatch route re-checks (Buffer.byteLength).
 const MAX_TRIGGER_JSON_BYTES = 48 * 1024;
@@ -117,6 +147,58 @@ const ASSISTANT_IDLE_MS = 15 * 60 * 1000;
 const ASSISTANT_STDOUT_MAX_CARRY = 64 * 1024 * 1024;
 export async function connect(opts) {
     const spinner = ora("Connecting to Melaya...").start();
+    const print = (line) => {
+        if (spinner.isSpinning) {
+            spinner.clear();
+            console.log(line);
+            spinner.render();
+        }
+        else
+            console.log(line);
+    };
+    // ── Python, resolved after the socket connects (audit P1.2) ─────────────
+    // Requests that need Python await it here; most of the time it is already
+    // resolved by the time the first request arrives.
+    let resolvedPython = typeof opts.pythonPath === "string" ? opts.pythonPath : null;
+    const pythonPromise = Promise.resolve(opts.pythonPath).then((p) => { resolvedPython = p; return p; });
+    const getPython = async () => {
+        if (resolvedPython)
+            return resolvedPython;
+        if (opts.verbose)
+            print(chalk.gray("  [python] waiting for the interpreter to be resolved"));
+        const p = await pythonPromise;
+        if (!p)
+            throw new Error("No supported Python (3.10-3.12) is available on this computer yet. Install Python 3.12, then restart the runner.");
+        return p;
+    };
+    // ── Background setup state (audit P1.5) ──────────────────────────────────
+    let bgSetup = null;
+    let bgSetupStep = "";
+    let foregroundDemand = false;
+    let lastActivityAt = Date.now();
+    let bgReadyResolve = () => { };
+    const bgReady = new Promise((r) => { bgReadyResolve = r; });
+    /** A request needs Python / the runtime now: setup work stops being background. */
+    const demandRuntime = (what) => {
+        lastActivityAt = Date.now();
+        if (!foregroundDemand) {
+            foregroundDemand = true;
+            bgReadyResolve();
+            // Assistant hosts read MEL_CLAUDE_CODE_VERSION; resolve it now if the
+            // background setup has not (defined below; only called from handlers).
+            void _detectClaudeCodeVersion();
+        }
+        setSetupBackground(false);
+        if (bgSetup && bgSetupStep) {
+            print(chalk.hex("#7C6FF0")(`  ⏳ ${what} waits for the one-time setup to finish (${bgSetupStep})…`));
+            hostProgress("running", bgSetupStep, true);
+        }
+    };
+    /** The interpreter for a request the user is waiting on. */
+    const foregroundPython = async (what) => {
+        demandRuntime(what);
+        return getPython();
+    };
     // Connect to the /api/v1/runner NAMESPACE on the existing Socket.IO server.
     // The `path` must match the server's Socket.IO HTTP path (/api/v1/events).
     // The namespace is specified in the URL suffix, not the path option.
@@ -129,6 +211,10 @@ export async function connect(opts) {
         reconnectionDelay: 2000,
         reconnectionAttempts: Infinity,
     });
+    const computerRelay = attachComputerRelay(socket, { verbose: opts.verbose, deps: { log: (l) => console.log(chalk.gray(l)) } });
+    // Browser engine discovery (cached promise, loads Playwright) overlaps the
+    // handshake instead of delaying runner:hello after it.
+    void discoverEngines().catch(() => { });
     let relay = null;
     // ── Disconnect diagnostics (transport-close root-cause) ──────────────
     // A "transport close" disconnect can be a NETWORK blip OR the Node event loop
@@ -185,7 +271,7 @@ export async function connect(opts) {
             }
             if (!localVersion)
                 throw new Error("runner python runtime still setting up");
-            const env = await ensurePythonEnv(opts.pythonPath, localVersion, (m) => vaultLog(`venv: ${m}`));
+            const env = await ensurePythonEnv(await getPython(), localVersion, (m) => vaultLog(`venv: ${m}`));
             if (!env.ok)
                 throw new Error(`venv bootstrap failed: ${env.reason}`);
             const script = findVaultHostScript(__dirname);
@@ -264,13 +350,17 @@ export async function connect(opts) {
     // it as MEL_CLAUDE_CODE_VERSION, which every assistant host inherits. Without
     // it each host ran a blocking `claude --version` (slow on Windows, through a
     // .cmd shim) on its first model call. Fixed argv, no user input.
+    let _claudeVersionStarted = false;
     const _detectClaudeCodeVersion = async () => {
-        if (process.env.MEL_CLAUDE_CODE_VERSION)
+        if (process.env.MEL_CLAUDE_CODE_VERSION || _claudeVersionStarted)
             return;
+        _claudeVersionStarted = true;
         const out = await new Promise((resolve) => {
             let buf = "";
             try {
                 const p = spawn("claude", ["--version"], { shell: process.platform === "win32", stdio: ["ignore", "pipe", "ignore"] });
+                if (!foregroundDemand)
+                    lowerPriority(p);
                 const timer = setTimeout(() => { try {
                     p.kill();
                 }
@@ -291,51 +381,59 @@ export async function connect(opts) {
         if (_assistantPrewarmed)
             return;
         _assistantPrewarmed = true;
+        const step = (s) => { bgSetupStep = s; hostProgress("running", s); };
+        let outcome = "done";
         void _detectClaudeCodeVersion();
         try {
             const { getLocalSharedVersion } = await import("./sharedVendor.js");
             let localVersion = getLocalSharedVersion();
             const freshSetup = !localVersion;
             if (!localVersion) {
-                // FIRST LAUNCH: no shared bundle on disk yet. Download it now, on
-                // connect, so the venv is built UP-FRONT instead of making the user wait
-                // 1-2 min mid-chat on their first assistant/pipeline run. Shown to the
-                // user (not verbose-gated) — a silent multi-minute pause reads as "stuck"
-                // and users leave; a clear one-time-setup line keeps their trust.
-                console.log(chalk.hex("#7C6FF0")("\n  ⚙ First-time setup: preparing your local AI runtime (one-time)…"));
-                console.log(chalk.gray("    downloading runtime modules…"));
+                // FIRST LAUNCH: no shared bundle on disk yet. Download it now (the
+                // runner has been idle since it came online) so the venv is built
+                // before the first assistant/pipeline run instead of making the user
+                // wait 1-2 min mid-chat. Shown to the user (not verbose-gated): a
+                // silent multi-minute pause reads as "stuck" and users leave.
+                print(chalk.hex("#7C6FF0")("\n  ⚙ First-time setup: preparing your local AI runtime (one-time, in the background)…"));
+                print(chalk.gray("    downloading runtime modules…"));
+                step("downloading runtime modules");
                 try {
                     await ensureSharedModules(opts.serverUrl, "latest", opts.token);
                     localVersion = getLocalSharedVersion();
                 }
                 catch (e) {
-                    console.log(chalk.gray(`    setup deferred (${e?.message || e}) — it will finish on your first run`));
+                    print(chalk.gray(`    setup deferred (${e?.message || e}) — it will finish on your first run`));
+                    outcome = "failed";
                     return;
                 }
-                if (!localVersion)
+                if (!localVersion) {
+                    outcome = "failed";
                     return;
+                }
             }
             const { ensurePythonEnv, getCertBundlePath } = await import("./pythonEnv.js");
             if (freshSetup)
-                console.log(chalk.gray("    installing Python dependencies (~1-2 min)…"));
-            const envResult = await ensurePythonEnv(opts.pythonPath, localVersion, (m) => { if (opts.verbose)
-                console.log(chalk.gray(`  [assistant prewarm] ${m}`)); });
+                print(chalk.gray("    installing Python dependencies (~1-2 min)…"));
+            step(freshSetup ? "installing Python dependencies" : "checking Python dependencies");
+            const envResult = await ensurePythonEnv(await getPython(), localVersion, (m) => { if (opts.verbose)
+                print(chalk.gray(`  [assistant prewarm] ${m}`)); });
+            if (!envResult.ok)
+                outcome = "failed";
             if (freshSetup) {
-                console.log(envResult.ok
+                print(envResult.ok
                     ? chalk.green("  ✓ Local AI runtime ready — your first chat will start instantly\n")
                     : chalk.yellow(`  ⚠ runtime setup did not finish (${envResult.reason || "unknown"}); it will retry on your first run\n`));
             }
             else if (opts.verbose) {
-                console.log(chalk.gray("  [assistant prewarm] ready"));
+                print(chalk.gray("  [assistant prewarm] ready"));
             }
             // ALSO pre-import the heavy Python stack so the first real run/chat
-            // doesn't pay the ~6s cold `import shared.runtime.registry`. Spawn it
-            // detached + fire-and-forget with the SAME PYTHONPATH/env a real
-            // pipeline spawn uses (see the runner:run handler below) so `shared.*`
-            // resolves; this heats the OS file cache + bytecode. Never blocks
-            // connect, never throws — swallow everything. Only when a shared
-            // bundle exists locally (mirror the ensurePythonEnv guard above).
-            if (envResult.ok) {
+            // doesn't pay the ~6s cold `import shared.runtime.registry`. Spawned
+            // fire-and-forget at below-normal priority with the SAME PYTHONPATH/env a
+            // real pipeline spawn uses (see the runner:run handler below) so
+            // `shared.*` resolves; this heats the OS file cache + bytecode. Skipped
+            // once a request has already started using the runtime.
+            if (envResult.ok && !foregroundDemand) {
                 try {
                     const sharedDir = getSharedDir();
                     if (existsSync(sharedDir)) {
@@ -348,10 +446,11 @@ export async function connect(opts) {
                             ...(certBundle ? { SSL_CERT_FILE: certBundle, REQUESTS_CA_BUNDLE: certBundle } : {}),
                         };
                         const warmChild = spawn(envResult.pythonPath, ["-c", "import shared.runtime.registry"], { env: warmEnv, stdio: "ignore" });
+                        lowerPriority(warmChild);
                         warmChild.on("error", () => { });
                         warmChild.on("exit", (code) => {
                             if (code === 0 && opts.verbose) {
-                                console.log(chalk.gray("  [assistant prewarm] import-warmed"));
+                                print(chalk.gray("  [assistant prewarm] import-warmed"));
                             }
                         });
                         warmChild.unref();
@@ -361,36 +460,92 @@ export async function connect(opts) {
             }
         }
         catch (e) {
+            outcome = "failed";
             if (opts.verbose)
-                console.log(chalk.gray(`  [assistant prewarm] skipped: ${e?.message || e}`));
+                print(chalk.gray(`  [assistant prewarm] skipped: ${e?.message || e}`));
+        }
+        finally {
+            bgSetupStep = "";
+            hostProgress(outcome);
         }
     };
-    // Models were detected ONCE at startup, so a model a CLI added later (e.g.
-    // gpt-6-astra landing in ~/.codex/models_cache.json after the runner started,
-    // 2026-10-03) never reached the picker until a runner restart. Re-detect every
-    // 5 minutes and push the list when it changed. File reads only (plus the
-    // Claude model list call), no subprocess.
+    // Start the background setup once the runner is online and has been idle
+    // (no runs, no Assistant host booting or live) for BG_SETUP_IDLE_MS. When a
+    // request needs the runtime first, it does the work itself and this never
+    // runs (the request path already ensured the same things).
+    const _runtimeIdle = () => activeProcesses.size === 0 && activeAssistants.size === 0 && bootingAssistants.size === 0;
+    let bgTimer = null;
+    const scheduleBackgroundSetup = () => {
+        if (bgSetup || bgTimer || foregroundDemand)
+            return;
+        lastActivityAt = Date.now();
+        bgTimer = setInterval(() => {
+            if (bgSetup || foregroundDemand) {
+                if (bgTimer)
+                    clearInterval(bgTimer);
+                bgTimer = null;
+                return;
+            }
+            if (!_runtimeIdle()) {
+                lastActivityAt = Date.now();
+                return;
+            }
+            if (Date.now() - lastActivityAt < BG_SETUP_IDLE_MS)
+                return;
+            if (bgTimer)
+                clearInterval(bgTimer);
+            bgTimer = null;
+            setSetupBackground(true);
+            bgSetup = _prewarmAssistantEnv().finally(() => {
+                setSetupBackground(false);
+                bgReadyResolve();
+            });
+        }, BG_SETUP_CHECK_MS);
+        bgTimer.unref?.();
+    };
+    // ── Model list: initial (cached) list on connect, fresh discovery later ──
+    // cli.ts connects with the last good list from disk and publishes the fresh
+    // scan through publishModels(). While connected, rescan every 15 min, and
+    // only when the provider fingerprint changed (credential/cache file mtimes,
+    // local server ports) or the last scan is over an hour old. Authenticated
+    // network calls inside a scan are cached per credential (detect.ts).
+    const publishModels = (models) => {
+        if (JSON.stringify(models) === JSON.stringify(opts.models))
+            return;
+        opts.models = models;
+        if (socket.connected)
+            socket.emit("runner:models", models);
+        if (opts.verbose)
+            print(chalk.gray(`  [models] published: ${models.length} model(s)`));
+    };
     let modelRefresh = null;
+    let lastFingerprint = "";
+    let lastScanAt = Date.now();
+    void providerFingerprint().then((f) => { lastFingerprint = f; }).catch(() => { });
     const startModelRefresh = () => {
         if (modelRefresh)
             return;
         modelRefresh = setInterval(async () => {
             try {
-                const fresh = await detectModels();
-                if (JSON.stringify(fresh) === JSON.stringify(opts.models))
+                const fp = await providerFingerprint();
+                if (fp === lastFingerprint && Date.now() - lastScanAt < MODEL_REFRESH_MAX_SKIP_MS) {
+                    if (opts.verbose)
+                        print(chalk.gray("  [models] unchanged, rescan skipped"));
                     return;
-                opts.models = fresh;
-                if (socket.connected)
-                    socket.emit("runner:models", fresh);
-                if (opts.verbose)
-                    console.log(chalk.gray(`  [models] refreshed: ${fresh.length} model(s)`));
+                }
+                const scan = await scanProviders();
+                lastFingerprint = fp;
+                lastScanAt = Date.now();
+                publishModels(scan.models);
             }
             catch { /* keep the last good list */ }
-        }, 5 * 60_000);
+        }, MODEL_REFRESH_MS);
         modelRefresh.unref?.();
     };
     socket.on("connect", async () => {
         spinner.succeed(chalk.green("Connected to Melaya"));
+        markStage("socket_connected");
+        hostStatus("online");
         connectedAt = Date.now();
         peakLagMs = 0; // fresh window each connection so the disconnect line reflects THIS session
         // New socket lifetime → new generation. Grants minted for an earlier
@@ -451,16 +606,17 @@ export async function connect(opts) {
                 console.log(chalk.gray(`  [relay] Listening on 127.0.0.1:${relay.port} (nonce: ${relay.nonce})`));
             }
         }
+        markStage("online");
         // Start the Luma browser bridge if a saved session exists. Best-
         // effort — failure here means Luma POSTs fall back to aiohttp
         // (which 403s under the bot rule) but reads still work.
         await _ensureLumaBridge();
-        // Pre-warm the assistant Python env in the BACKGROUND so the first chat
-        // message doesn't pay the venv check + one-time NLTK/cert self-heal inline
-        // (the biggest chunk of "◆ Assistant session … takes forever to spawn").
-        // We warm with the version already on disk so it hits the cache instead of
-        // reinstalling; skipped on a fresh runner (no bundle yet) to avoid churn.
-        void _prewarmAssistantEnv();
+        // Pre-warm the runtime (modules, Python deps, Claude version, Python
+        // imports) so the first chat message doesn't pay it inline, but only once
+        // the runner has been idle for a while and at below-normal priority, so it
+        // does not compete with the first screen (audit P1.5). A request that
+        // arrives first does the work itself.
+        scheduleBackgroundSetup();
         console.log(chalk.gray("  Waiting for pipeline runs...\n"));
     });
     // A runner that never connects is invisible to the funnel: last_seen stays
@@ -475,9 +631,18 @@ export async function connect(opts) {
             void import("./installReport.js").then((m) => m.reportInstallFailure(authRejected ? "socket_auth_rejected" : "socket_unreachable", { token: opts.token, server: opts.serverUrl })).catch(() => { });
         }
         if (authRejected) {
+            hostStatus("error", "This computer's runner token was revoked or is invalid. Connect this computer again.", "token_rejected");
             console.log(chalk.yellow("  Token may be expired or revoked. Generate a new one in Settings → Connectors."));
             setTimeout(() => process.exit(1), 300); // let the beacon leave the box
         }
+        else if (isHosted() && /invalid|expired|revoked|token required/i.test(err.message)) {
+            // Desktop app: the handshake's token errors are final too; the app asks for a new token.
+            hostStatus("error", "This computer's runner token was revoked or is invalid. Connect this computer again.", "token_rejected");
+            setTimeout(() => process.exit(1), 300);
+        }
+        else {
+            hostStatus(connectedAt ? "reconnecting" : "starting", "Can't reach Melaya right now. Retrying.");
+        }
     });
     socket.on("disconnect", (reason) => {
         const upS = connectedAt ? Math.round((Date.now() - connectedAt) / 1000) : 0;
@@ -498,9 +663,11 @@ export async function connect(opts) {
             browserBridge.teardownAll(`socket_disconnect:${reason}`).catch(() => { });
         }
         if (reason === "io server disconnect") {
+            hostStatus("error", "Melaya closed the connection: this computer was disconnected from your account, or stopped answering.", "server_disconnect");
             console.log(chalk.red("  Server closed the connection. Check your token."));
             process.exit(1);
         }
+        hostStatus("reconnecting");
     });
     // ── Melaya Browser: grant public key delivery (plan Section 0.6) ──────
     // The server pushes its current EdDSA grant-verification public keys
@@ -744,7 +911,7 @@ export async function connect(opts) {
             // ModuleNotFoundError. The venv is created lazily on first run
             // and reused until sharedVersion changes.
             const { ensurePythonEnv } = await import("./pythonEnv.js");
-            const envResult = await ensurePythonEnv(opts.pythonPath, payload.sharedVersion, (msg) => {
+            const envResult = await ensurePythonEnv(await foregroundPython("This run"), payload.sharedVersion, (msg) => {
                 console.log(chalk.gray(`  [venv] ${msg}`));
                 // Surface bootstrap progress to the FE so the launching
                 // animation reflects the real state instead of staying on a
@@ -1121,6 +1288,7 @@ export async function connect(opts) {
                 });
             }
             // Spawn Python subprocess (uses the bootstrapped venv python).
+            const runStartedAt = Date.now();
             const proc = spawn(pipelinePython, ["-u", join(runDir, "main.py")], {
                 cwd: runDir,
                 env,
@@ -1162,6 +1330,7 @@ export async function connect(opts) {
             });
             proc.on("exit", (code) => {
                 activeProcesses.delete(payload.runId);
+                reportOutputsSince(env.MELAYA_OUTPUT_DIR, runStartedAt);
                 // Melaya Browser terminal path (plan Section 7): the pipeline
                 // process exited, so revoke the grant, cancel in-flight browser
                 // ops, release leases, and close ONLY owned browsers. Idempotent.
@@ -1305,7 +1474,7 @@ export async function connect(opts) {
             await ensureSharedModules(opts.serverUrl, sharedVersion, opts.token);
             // Dedicated venv with agentscope + anthropic + openai installed.
             const { ensurePythonEnv } = await import("./pythonEnv.js");
-            const envResult = await ensurePythonEnv(opts.pythonPath, sharedVersion, (msg) => {
+            const envResult = await ensurePythonEnv(await foregroundPython("This strategy"), sharedVersion, (msg) => {
                 console.log(chalk.gray(`  [venv] ${msg}`));
                 socket.emit("runner:event", {
                     run_id: runId,
@@ -1491,6 +1660,7 @@ export async function connect(opts) {
                 // and ships it inline on the crew dispatch payload.
                 ...(cfg.credentials ?? {}),
             };
+            const runStartedAt = Date.now();
             const proc = spawn(envResult.pythonPath, ["-u", join(runDir, "main.py")], {
                 cwd: runDir,
                 env,
@@ -1518,6 +1688,7 @@ export async function connect(opts) {
             });
             proc.on("exit", (code) => {
                 activeProcesses.delete(runId);
+                reportOutputsSince(env.MELAYA_OUTPUT_DIR, runStartedAt);
                 const status = code === 0 ? "done" : "failed";
                 if (status === "failed" && stderrTail.length > 0) {
                     const tail = stderrTail.slice(-15).join("\n");
@@ -1621,6 +1792,9 @@ export async function connect(opts) {
                                 const r = readTurnFile(st, parsed.path);
                                 if (r.ok)
                                     socket.emit("runner:assistant_event", { sessionId: session.sid, turnId: String(parsed.turnId), kind: "file", ...r.file });
+                                // Accepted (inside this turn's dir): also offer it to computer control in the desktop app.
+                                if (r.ok)
+                                    reportHostFile(isAbsolute(String(parsed.path)) ? String(parsed.path) : join(st.dir, String(parsed.path)), "output");
                                 else if (opts.verbose)
                                     console.log(chalk.gray(`  [assistant] output file not relayed (${r.reason})`));
                             }
@@ -1924,12 +2098,17 @@ export async function connect(opts) {
             return;
         if (!payload?.userId || !payload?.configHash)
             return;
+        // Booting a spare host is heavy: wait until the background setup ran (idle)
+        // or a request already brought the runtime up (audit P1.5).
+        await bgReady;
+        if (warmSpare || _prewarmInFlight)
+            return;
         try {
             const sharedVersion = String(payload.sharedVersion ?? "latest");
             await ensureSharedModules(opts.serverUrl, sharedVersion, opts.token);
             _dropSpareOnOlderBundle();
             const { ensurePythonEnv } = await import("./pythonEnv.js");
-            const envResult = await ensurePythonEnv(opts.pythonPath, sharedVersion, (m) => { if (opts.verbose)
+            const envResult = await ensurePythonEnv(await getPython(), sharedVersion, (m) => { if (opts.verbose)
                 console.log(chalk.gray(`  [assistant prewarm] ${m}`)); });
             if (!envResult.ok)
                 return;
@@ -2033,7 +2212,7 @@ export async function connect(opts) {
             await ensureSharedModules(opts.serverUrl, sharedVersion, opts.token);
             _dropSpareOnOlderBundle();
             const { ensurePythonEnv } = await import("./pythonEnv.js");
-            const envResult = await ensurePythonEnv(opts.pythonPath, sharedVersion, (m) => { if (opts.verbose)
+            const envResult = await ensurePythonEnv(await foregroundPython("This chat"), sharedVersion, (m) => { if (opts.verbose)
                 console.log(chalk.gray(`  [assistant venv] ${m}`)); });
             if (!envResult.ok) {
                 emitEv({ kind: "error", message: `python env failed: ${envResult.reason}` });
@@ -2479,7 +2658,7 @@ export async function connect(opts) {
             // Reuse the same venv as runner:run — agentscope.rag + ollama +
             // qdrant-client land here.
             const { ensurePythonEnv } = await import("./pythonEnv.js");
-            const env = await ensurePythonEnv(opts.pythonPath, payload.sharedVersion, (m) => emitProgress("venv", { message: m }));
+            const env = await ensurePythonEnv(await foregroundPython("This request"), payload.sharedVersion, (m) => emitProgress("venv", { message: m }));
             if (!env.ok) {
                 emitProgress("error", { error: `venv bootstrap failed: ${env.reason}` });
                 socket.emit("rag:ingest-result", {
@@ -2685,7 +2864,7 @@ export async function connect(opts) {
                 return;
             }
             const { ensurePythonEnv } = await import("./pythonEnv.js");
-            const env = await ensurePythonEnv(opts.pythonPath, payload.sharedVersion);
+            const env = await ensurePythonEnv(await foregroundPython("This request"), payload.sharedVersion);
             if (!env.ok) {
                 socket.emit("rag:retrieve-result", {
                     session_id: sid,
@@ -2802,7 +2981,7 @@ export async function connect(opts) {
                 reply(false, undefined, "runner is still setting up its Python runtime — try again in a moment");
                 return;
             }
-            const env = await ensurePythonEnv(opts.pythonPath, localVersion, (m) => { if (opts.verbose)
+            const env = await ensurePythonEnv(await foregroundPython("This request"), localVersion, (m) => { if (opts.verbose)
                 console.log(chalk.gray(`  [db-test venv] ${m}`)); });
             if (!env.ok) {
                 reply(false, undefined, `venv bootstrap failed: ${env.reason}`);
@@ -2923,7 +3102,7 @@ export async function connect(opts) {
                 reply({ error: "runner python runtime still setting up" });
                 return;
             }
-            const env = await ensurePythonEnv(opts.pythonPath, localVersion, (m) => { if (opts.verbose)
+            const env = await ensurePythonEnv(await foregroundPython("This request"), localVersion, (m) => { if (opts.verbose)
                 console.log(chalk.gray(`  [backlink-fetch venv] ${m}`)); });
             if (!env.ok) {
                 reply({ error: `venv bootstrap failed: ${env.reason}` });
@@ -3014,6 +3193,9 @@ export async function connect(opts) {
             const outcome = await runLinkedInLoginFlow(emitProgress);
             console.log(describeOutcome(outcome));
             socket.emit("linkedin:login-result", { session_id: sid, ...outcome });
+            // Desktop app: no Chrome / Edge to sign in with is something only the user can fix.
+            if (outcome.error === "browser_not_installed")
+                sendToHost({ type: "notice", code: "browser_not_installed" });
         }
         catch (e) {
             const msg = e?.message || "linkedin_login_unhandled_error";
@@ -3042,6 +3224,8 @@ export async function connect(opts) {
             const outcome = await runLumaLoginFlow(emitProgress);
             console.log(describeOutcome(outcome));
             socket.emit("luma:login-result", { session_id: sid, ...outcome });
+            if (outcome.error === "browser_not_installed")
+                sendToHost({ type: "notice", code: "browser_not_installed" });
             // Successful sign-in just wrote a fresh storage-state.json. If the
             // bridge is already up, force the next forward to re-read state
             // from disk; if it isn't up (first sign-in on this runner), boot
@@ -3092,7 +3276,8 @@ export async function connect(opts) {
     socket.on("runner:kill", (data) => {
         const proc = activeProcesses.get(data.runId);
         if (proc) {
-            proc.kill("SIGTERM");
+            // The whole tree: a run's own children (CLI providers, browsers) too.
+            void terminateTree(proc, { graceMs: SHUTDOWN_CHILD_GRACE_MS });
             activeProcesses.delete(data.runId);
             console.log(chalk.yellow(`  ■ Killed run ${data.runId.slice(0, 10)}...`));
         }
@@ -3141,38 +3326,70 @@ export async function connect(opts) {
     // script that fetches `localhost:1234`/`11434` and POSTs each SSE
     // line back as an HTTP callback to the cloud server. Same pattern
     // as the BacktestOptimizer dispatch.
-    // ── Graceful shutdown ──────────────────────────────────────────────
-    const cleanup = () => {
-        console.log(chalk.gray("\n  Shutting down..."));
-        for (const [id, proc] of activeProcesses) {
-            proc.kill("SIGTERM");
+    // ── Graceful shutdown (audit P0.5) ─────────────────────────────────
+    // Every subsystem is awaited under its own deadline, in parallel: runs and
+    // Assistant hosts (whole process trees), browsers, the Luma bridge, the
+    // vault host, the computer relay, the local relay. A final sweep stops any
+    // tracked child still alive (venv builds, warm-ups), then the socket closes.
+    // Bounded well inside the desktop app's 5 s hard exit. A second Ctrl+C (or
+    // SIGTERM) during shutdown forces the exit at once; the process "exit" hook
+    // in processTree.ts still kills every tracked tree on the way out.
+    let shuttingDown = false;
+    const shutdown = async () => {
+        const t0 = Date.now();
+        if (modelRefresh) {
+            clearInterval(modelRefresh);
+            modelRefresh = null;
+        }
+        if (bgTimer) {
+            clearInterval(bgTimer);
+            bgTimer = null;
+        }
+        const runs = [...activeProcesses.entries()];
+        for (const [id] of runs)
             socket.emit("runner:runComplete", { runId: id, status: "failed" });
-        }
-        for (const [, s] of activeAssistants) {
-            try {
-                s.proc.kill("SIGTERM");
-            }
-            catch { /* noop */ }
-        }
+        activeProcesses.clear();
+        const hosts = [...activeAssistants.values()].map((s) => s.proc);
+        if (warmSpare)
+            hosts.push(warmSpare.proc);
         activeAssistants.clear();
-        // Melaya Browser terminal path (plan Section 7): shut the bridge down,
-        // which cancels in-flight ops, releases every lease, and closes ONLY
-        // owned browsers (attached user browsers are merely disconnected).
-        if (browserBridge) {
-            browserBridge.shutdown().catch(() => { });
-        }
-        relay?.close();
-        // Best-effort Chromium teardown. The bridge's shutdown is async but
-        // we can't await inside a SIGINT handler — fire and forget; the
-        // process.exit below kills any lingering child processes anyway.
-        if (lumaBridge) {
-            lumaBridge.shutdown().catch(() => { });
-        }
+        warmSpare = null;
+        const results = await runShutdownSteps([
+            { name: "runs", deadlineMs: SHUTDOWN_STEP_MS, run: () => Promise.all(runs.map(([, p]) => terminateTree(p, { graceMs: SHUTDOWN_CHILD_GRACE_MS }))) },
+            { name: "assistant_hosts", deadlineMs: SHUTDOWN_STEP_MS, run: () => Promise.all(hosts.map((p) => terminateTree(p, { graceMs: SHUTDOWN_CHILD_GRACE_MS }))) },
+            // Melaya Browser terminal path (plan Section 7): cancels in-flight ops,
+            // releases every lease, closes ONLY owned browsers (attached user
+            // browsers are merely disconnected).
+            { name: "browsers", deadlineMs: SHUTDOWN_STEP_MS, run: () => browserBridge?.shutdown() },
+            { name: "luma_browser", deadlineMs: SHUTDOWN_STEP_MS, run: () => lumaBridge?.shutdown() },
+            { name: "vaults", deadlineMs: SHUTDOWN_STEP_MS, run: () => vaultService.stop() },
+            { name: "computer", deadlineMs: SHUTDOWN_STEP_MS, run: () => computerRelay.dispose() },
+            { name: "relay", deadlineMs: SHUTDOWN_STEP_MS, run: () => relay?.close() },
+        ]);
+        // Anything still tracked (venv build, warm-up, vault host, helper): stop the trees now.
+        const swept = await runShutdownSteps([
+            { name: "children", deadlineMs: SHUTDOWN_SWEEP_MS + 500, run: () => terminateAllTracked({ graceMs: SHUTDOWN_SWEEP_MS }) },
+        ]);
+        const line = `shutdown ${Date.now() - t0}ms: ${formatShutdownResults([...results, ...swept])}`;
+        if (opts.verbose)
+            console.log(chalk.gray(`  ${line}`));
+        sendToHost({ type: "log", level: "info", line });
         socket.disconnect();
-        process.exit(0);
     };
+    const cleanup = () => {
+        if (shuttingDown) {
+            // Second signal: stop waiting.
+            killAllTrackedSync();
+            process.exit(0);
+        }
+        shuttingDown = true;
+        console.log(chalk.gray("\n  Shutting down..."));
+        void shutdown().catch(() => { }).finally(() => process.exit(0));
+    };
+    claimGracefulShutdown();
     process.on("SIGINT", cleanup);
     process.on("SIGTERM", cleanup);
+    return { publishModels, print };
 }
 export function verifySignature(content, signature, runnerToken) {
     if (!content || !signature || !runnerToken)