@melaya/runner 1.1.29 → 1.1.31

package/dist/browserBridge.d.ts

@@ -12,6 +12,7 @@ export interface BrowserRunSpec {
     headless?: boolean;
     serverBase?: string;
     runAuthHeader?: string;
+    hitlMode?: string;
 }
 export interface BrowserBridge {
     url: string;
@@ -25,6 +26,11 @@ export interface BrowserBridge {
      *  releases leases, closes ONLY owned contexts, forgets the grant. */
     teardownRun(runId: string, reason: string): Promise<void>;
     teardownAll(reason: string): Promise<void>;
+    /** Tear down every per-turn bridge run belonging to an assistant session
+     *  (runId form `${sessionId}:${turnId}`). Called when a host process exits or
+     *  crashes so a turn that never sent its `done` frame does not leak its lease
+     *  and its enforceOnPage route handlers onto the user's still-open tab. */
+    teardownRunsForSession(sessionId: string, reason: string): Promise<void>;
     hasRun(runId: string): boolean;
     /**
      * Launch a headed browser as an interactive (grant-free, read-only-watch)

package/dist/browserBridge.js

@@ -39,6 +39,18 @@ import { SessionManager, SessionError, spaceUserDataDir, } from "./sessionManage
 import { ensureEngine } from "./browserProvisioner.js";
 import { runSandboxedScript } from "./codeWorker.js";
 import { classifyControlEffect, writeGatedInMode } from "./publishGate.js";
+// A wall-clock around a CDP command. Playwright's CDPSession.send has NO default
+// timeout, so a wedged/busy renderer means the promise NEVER settles (not a
+// rejection - no catch fires) and the lease op-chain queues every later op
+// behind it forever. Same stall class the screenshot path already bounds. Note
+// the underlying CDP command stays pending beneath the race; this only unblocks
+// the caller so the tool returns a typed error instead of hanging.
+function cdpRace(p, what, ms = 20_000) {
+    return Promise.race([
+        p,
+        new Promise((_, reject) => setTimeout(() => reject(new BridgeError("cdp_timeout", `${what} did not respond in ${ms}ms`)), ms)),
+    ]);
+}
 // ---------------------------------------------------------------------
 // Limits and constants
 // ---------------------------------------------------------------------
@@ -841,13 +853,13 @@ export async function startBrowserBridge(opts) {
     async function collectFromTarget(cdp, frameKey, frameOffset, viewport, out) {
         const STYLE_FILTER = ["display", "visibility", "opacity"];
         const [snap, ax] = await Promise.all([
-            cdp.send("DOMSnapshot.captureSnapshot", {
+            cdpRace(cdp.send("DOMSnapshot.captureSnapshot", {
                 computedStyles: STYLE_FILTER,
                 includePaintOrder: true,
-            }),
+            }), "DOMSnapshot.captureSnapshot", 30_000),
             (async () => {
                 await cdp.send("Accessibility.enable").catch(() => { });
-                return cdp.send("Accessibility.getFullAXTree", {});
+                return cdpRace(cdp.send("Accessibility.getFullAXTree", {}), "Accessibility.getFullAXTree", 30_000);
             })(),
         ]);
         const strings = snap.strings;
@@ -1046,7 +1058,7 @@ export async function startBrowserBridge(opts) {
             }
             try {
                 await localCdp.send("DOM.scrollIntoViewIfNeeded", { backendNodeId: binding.backendNodeId }).catch(() => { });
-                const bm = await localCdp.send("DOM.getBoxModel", { backendNodeId: binding.backendNodeId });
+                const bm = await cdpRace(localCdp.send("DOM.getBoxModel", { backendNodeId: binding.backendNodeId }), "DOM.getBoxModel");
                 const q = bm.model.content; // 4 corner points, viewport coords of the owning target
                 const cx = (q[0] + q[2] + q[4] + q[6]) / 4 + offset.x;
                 const cy = (q[1] + q[3] + q[5] + q[7]) / 4 + offset.y;
@@ -1088,8 +1100,47 @@ export async function startBrowserBridge(opts) {
      *  (button, a, [role=button], [type=submit]) and reads, in precedence order:
      *  aria-label, else innerText/textContent, else value, else title. Returns a
      *  lowercased + trimmed string (empty when nothing is readable). Never
-     *  throws: on any page error it returns "" so the caller treats it as
-     *  "no match" and runs the action normally. */
+     *  throws: on any page error it returns a SENTINEL (not "") so the caller can
+     *  fail closed, distinct from a real element that legitimately has no name. */
+    /** OWASP A06 (defense-in-depth) — server-side secret-field detection. Returns
+     *  true when the field the agent is about to type into (the focused element,
+     *  or the element at the resolved point) is a password / OTP / payment input.
+     *  The tool contract already forbids the agent from typing credentials; this
+     *  makes it an ENFORCED control, not just a prompt: input_text refuses and the
+     *  agent must hand off to the human. Fails OPEN (returns false) on a page read
+     *  error — the threat is the agent mistakenly typing a secret, not a hostile
+     *  page, and failing closed would let a page block all legitimate typing. */
+    async function isSecretFieldAtPoint(page, x, y) {
+        try {
+            return await page.evaluate(([px, py]) => {
+                const isSecret = (node) => {
+                    const el = node;
+                    if (!el || !el.tagName)
+                        return false;
+                    const tag = el.tagName.toLowerCase();
+                    if (tag !== "input" && tag !== "textarea")
+                        return false;
+                    const type = (el.getAttribute("type") || "").toLowerCase();
+                    if (type === "password")
+                        return true;
+                    const ac = (el.getAttribute("autocomplete") || "").toLowerCase();
+                    if (/(^|\s)(current-password|new-password|one-time-code|cc-number|cc-csc)(\s|$)/.test(ac))
+                        return true;
+                    const hay = [
+                        el.getAttribute("name"), el.getAttribute("id"),
+                        el.getAttribute("aria-label"), el.getAttribute("placeholder"),
+                    ].map((s) => (s || "").toLowerCase()).join(" ");
+                    return /pass(word|code)?|\botp\b|one.?time|\bcvv\b|\bcvc\b|card.?number|security.?code|\bpin\b|secret|seed.?phrase|recovery.?(code|phrase)/.test(hay);
+                };
+                const atPoint = document.elementFromPoint(px, py);
+                return isSecret(document.activeElement) || isSecret(atPoint);
+            }, [x, y]);
+        }
+        catch {
+            return false;
+        }
+    }
+    const NAME_READ_FAILED = " name_read_failed";
     async function readAccessibleNameAtPoint(page, x, y) {
         try {
             const raw = await page.evaluate(([px, py]) => {
@@ -1118,7 +1169,13 @@ export async function startBrowserBridge(opts) {
             return String(raw || "").toLowerCase().trim();
         }
         catch {
-            return "";
+            // SENTINEL, not "". A thrown page.evaluate (crashed frame, nav race, or a
+            // HOSTILE page that overrode elementFromPoint/innerText to throw) must NOT
+            // read as "benign control" — that is how a page could strip HITL from its
+            // own Buy button. The caller fails closed on this value; a real element
+            // with no name still returns "" and keeps the by-design fail-open for
+            // icon-only buttons.
+            return NAME_READ_FAILED;
         }
     }
     /** Stage a human approval on the server for a consequential click/tap and
@@ -1197,16 +1254,38 @@ export async function startBrowserBridge(opts) {
      *  normally (falls through to execution) when there is nothing to gate or
      *  the approval came back "approved". Applies to click/dblclick/tap only;
      *  callers must not invoke it for hover. */
-    async function enforcePublishGate(reg, page, kind, name, ref, mode) {
-        const escalated = classifyControlEffect(name);
+    async function enforcePublishGate(reg, page, kind, name, ref, mode, knownEffect) {
+        // Effect resolution, in order:
+        //  1. knownEffect — the action is a commit by CONSTRUCTION (browser_submit
+        //     submits a form; there is no reliable name to read), so the caller
+        //     names the effect directly. Previously submit passed name="" and was
+        //     never gated at all.
+        //  2. name read FAILED — fail CLOSED. An unreadable control in a gated mode
+        //     is treated as a purchase (the most-gated family, so it gates in both
+        //     safe and payments_only). This is what stops a hostile page from
+        //     throwing in the name reader to strip its own HITL card.
+        //  3. otherwise classify the name as before.
+        const escalated = knownEffect
+            ?? (name === NAME_READ_FAILED ? "purchase" : classifyControlEffect(name));
         if (!escalated)
-            return; // not a publish/purchase control: run normally.
+            return; // benign control (real element, no consequential verb): run normally.
         // Gate on the TURN's AUTONOMY MODE, NOT the grant ceiling: the ceiling is
         // always 'destructive' (it bounds what is possible), so a checkEffect gate
         // never fires. Autonomous => act; safe => gate every write; payments_only =>
         // gate only purchases. The mode arrives per act on the bridge body
         // (browser.py stamps hitl_mode); absent fails closed to safe.
-        if (!writeGatedInMode(escalated, mode))
+        //
+        // OWASP A01 — bind to the registered spec mode: the body may only TIGHTEN.
+        // A caller holding MEL_BROWSER_TOKEN could POST hitl_mode:"autonomous" to
+        // strip the gate; the registered (server-clamped) mode wins unless the body
+        // is MORE restrictive. Spec absent => defer to body (unchanged behavior).
+        const _modeRank = (m) => m === "autonomous" ? 2 : m === "payments_only" ? 1 : 0;
+        const specMode = reg.spec.hitlMode;
+        let effMode = mode;
+        if (specMode != null) {
+            effMode = mode != null && _modeRank(mode) < _modeRank(specMode) ? mode : specMode;
+        }
+        if (!writeGatedInMode(escalated, effMode))
             return;
         // Gated in this mode: stage a server approval so the card shows + the tool waits.
         let origin = "";
@@ -1468,6 +1547,14 @@ export async function startBrowserBridge(opts) {
                     if (text.length > 20_000)
                         throw new BridgeError("act_args_invalid", "text exceeds 20000 chars");
                     const pt = await resolveActionPoint(reg, rec, lease, args);
+                    // OWASP A06 — refuse to type into a password / OTP / payment field.
+                    // Typing a credential is never permitted, in any autonomy mode; the
+                    // agent must hand off to the human (browser_ask_user). Enforced here
+                    // on the runner, not just promised in the tool prompt.
+                    if (await isSecretFieldAtPoint(page, pt.x, pt.y)) {
+                        throw new BridgeError("secret_field_blocked", "refused: the target looks like a password / OTP / payment field. " +
+                            "Hand off to the human with browser_ask_user so they enter the secret; never type credentials.");
+                    }
                     await humanClick(page, pt.x, pt.y);
                     // Clear-then-type: select-all + humanized type preserves site key handlers.
                     await page.keyboard.press(process.platform === "darwin" ? "Meta+A" : "Control+A").catch(() => { });
@@ -1479,6 +1566,17 @@ export async function startBrowserBridge(opts) {
                     const key = String(args.key || "");
                     if (!/^[A-Za-z0-9+]{1,32}$/.test(key))
                         throw new BridgeError("act_args_invalid", `invalid key '${key}'`);
+                    // OWASP A01 — a commit key submits the focused form, exactly like
+                    // clicking a submit control; the server/extension transport already
+                    // classifies Enter/NumpadEnter as `publish` (browserEffects.ts
+                    // COMMIT_KEYS). Gate it here too so safe mode raises an approval card
+                    // instead of letting the model bypass the gate via "press Enter to
+                    // submit" — the very path the gated-submit error message used to
+                    // steer the model onto. Parity with the other transport, not new
+                    // friction. Fails closed to a `publish` effect by construction.
+                    if (key === "Enter" || key === "NumpadEnter") {
+                        await enforcePublishGate(reg, page, kind, "focused field", `press_key:${key}`, args.hitl_mode, "publish");
+                    }
                     await page.keyboard.press(key);
                     return { pressed: key };
                 }
@@ -1525,12 +1623,12 @@ export async function startBrowserBridge(opts) {
                         // Scope to the element's innerText via CDP object resolution.
                         const binding = sessions.resolveRef(lease, args.ref);
                         const cdp = await getCdp(rec, page);
-                        const resolved = await cdp.send("DOM.resolveNode", { backendNodeId: binding.backendNodeId });
-                        const result = await cdp.send("Runtime.callFunctionOn", {
+                        const resolved = await cdpRace(cdp.send("DOM.resolveNode", { backendNodeId: binding.backendNodeId }), "DOM.resolveNode");
+                        const result = await cdpRace(cdp.send("Runtime.callFunctionOn", {
                             objectId: resolved.object.objectId,
                             functionDeclaration: `function(){ return (this.innerText || this.textContent || "").trim(); }`,
                             returnByValue: true,
-                        });
+                        }), "Runtime.callFunctionOn");
                         text = String(result.result.value ?? "");
                     }
                     else {
@@ -1557,12 +1655,12 @@ export async function startBrowserBridge(opts) {
                     const binding = sessions.resolveRef(lease, args.ref);
                     const value = String(args.value ?? "");
                     const cdp = await getCdp(rec, page);
-                    const resolved = await cdp.send("DOM.resolveNode", { backendNodeId: binding.backendNodeId });
-                    await cdp.send("Runtime.callFunctionOn", {
+                    const resolved = await cdpRace(cdp.send("DOM.resolveNode", { backendNodeId: binding.backendNodeId }), "DOM.resolveNode");
+                    await cdpRace(cdp.send("Runtime.callFunctionOn", {
                         objectId: resolved.object.objectId,
                         functionDeclaration: `function(v){ this.value = v; this.dispatchEvent(new Event('input',{bubbles:true})); this.dispatchEvent(new Event('change',{bubbles:true})); }`,
                         arguments: [{ value }],
-                    });
+                    }), "Runtime.callFunctionOn");
                     return { selected: value };
                 }
                 case "wait": {
@@ -1577,7 +1675,9 @@ export async function startBrowserBridge(opts) {
                     // sees the submission. submit() is only the fallback for the few
                     // forms that predate it.
                     const ref = args.ref ? String(args.ref) : "";
-                    await enforcePublishGate(reg, page, kind, "", ref || "focused form", args.hitl_mode);
+                    // Submitting a form IS a write commit — gate it as `publish`
+                    // unconditionally, whatever the (unreadable) submit control is called.
+                    await enforcePublishGate(reg, page, kind, "", ref || "focused form", args.hitl_mode, "publish");
                     const FIND_AND_SUBMIT = "function(){ var el = this; var f = el && el.closest ? el.closest('form') : null; " +
                         "if (!f) return false; if (typeof f.requestSubmit === 'function') f.requestSubmit(); " +
                         "else f.submit(); return true; }";
@@ -1585,23 +1685,23 @@ export async function startBrowserBridge(opts) {
                     let submitted = false;
                     if (ref) {
                         const binding = sessions.resolveRef(lease, ref);
-                        const resolved = await cdp.send("DOM.resolveNode", { backendNodeId: binding.backendNodeId });
-                        const r = await cdp.send("Runtime.callFunctionOn", {
+                        const resolved = await cdpRace(cdp.send("DOM.resolveNode", { backendNodeId: binding.backendNodeId }), "DOM.resolveNode");
+                        const r = await cdpRace(cdp.send("Runtime.callFunctionOn", {
                             objectId: resolved.object.objectId,
                             functionDeclaration: FIND_AND_SUBMIT,
                             returnByValue: true,
-                        });
+                        }), "Runtime.callFunctionOn");
                         submitted = r.result?.value === true;
                     }
                     else {
                         // Evaluated as a string through CDP rather than page.evaluate so
                         // this file needs no DOM lib in its tsconfig.
-                        const r = await cdp.send("Runtime.evaluate", {
+                        const r = await cdpRace(cdp.send("Runtime.evaluate", {
                             returnByValue: true,
                             expression: "(function(){ var el = document.activeElement; var f = el && el.closest ? el.closest('form') : null; " +
                                 "if (!f) return false; if (typeof f.requestSubmit === 'function') f.requestSubmit(); " +
                                 "else f.submit(); return true; })()",
-                        });
+                        }), "Runtime.evaluate");
                         submitted = r.result?.value === true;
                     }
                     if (!submitted) {
@@ -1639,21 +1739,31 @@ export async function startBrowserBridge(opts) {
                     };
                     const name = await readAccessibleNameAtPoint(page, from.x, from.y);
                     await enforcePublishGate(reg, page, kind, name, String(args.ref ?? `${Math.round(from.x)},${Math.round(from.y)}`), args.hitl_mode);
+                    // Pure, declared before the try so `path.length` is in scope for the
+                    // return below.
+                    const path = buildDragPath(from, to, Math.round(moveMs / 25), moveMs, shape);
                     await page.mouse.move(from.x, from.y);
                     await page.mouse.down();
-                    // THE LONG PRESS. Button down, pointer still, nothing dispatched:
-                    // this interval is what the page uses to decide the item is picked
-                    // up, and it is the whole difference from a plain drag.
-                    await page.waitForTimeout(holdMs);
-                    const path = buildDragPath(from, to, Math.round(moveMs / 25), moveMs, shape);
-                    for (const p of path) {
-                        await page.mouse.move(p.x, p.y);
-                        await page.waitForTimeout(p.dwellMs);
+                    // Guarantee the button is released even if a move/wait throws mid-drag
+                    // (navigation, target detach). A left-pressed button turns every later
+                    // click into a drag-selection on the user's own headed browser, with
+                    // no visible cause. up() on an already-released button is harmless.
+                    try {
+                        // THE LONG PRESS. Button down, pointer still, nothing dispatched:
+                        // this interval is what the page uses to decide the item is picked
+                        // up, and it is the whole difference from a plain drag.
+                        await page.waitForTimeout(holdMs);
+                        for (const p of path) {
+                            await page.mouse.move(p.x, p.y);
+                            await page.waitForTimeout(p.dwellMs);
+                        }
+                        // Rest on the target before releasing: dragover-driven drop zones
+                        // need a frame or two at rest, and a release mid-motion misses them.
+                        await page.waitForTimeout(settleMs);
+                    }
+                    finally {
+                        await page.mouse.up().catch(() => { });
                     }
-                    // Rest on the target before releasing: dragover-driven drop zones
-                    // need a frame or two at rest, and a release mid-motion misses them.
-                    await page.waitForTimeout(settleMs);
-                    await page.mouse.up();
                     return {
                         from: { x: Math.round(from.x), y: Math.round(from.y) },
                         to: { x: Math.round(to.x), y: Math.round(to.y) },
@@ -2478,6 +2588,15 @@ export async function startBrowserBridge(opts) {
         registerRun,
         teardownRun,
         teardownAll,
+        async teardownRunsForSession(sessionId, reason) {
+            const prefix = `${sessionId}:`;
+            // Snapshot the keys first — teardownRun mutates byRunId. Idempotent, so a
+            // race with a normal turn-done teardown is harmless.
+            const ids = [...byRunId.keys()].filter((k) => k.startsWith(prefix));
+            for (const id of ids) {
+                await teardownRun(id, reason).catch(() => { });
+            }
+        },
         hasRun(runId) {
             return byRunId.has(runId);
         },

package/dist/cli.js

@@ -53,13 +53,25 @@ async function main() {
     const opts = program.opts();
     console.log(BANNER);
     // Detect Python
-    const python = await findPython();
-    if (!python) {
-        console.log(chalk.red("  ✗ Python not found in PATH"));
-        console.log(chalk.gray("    Install Python 3.11+ from https://python.org"));
+    const py = await findPython();
+    if (!py.ok) {
+        if (py.foundVersion) {
+            console.log(chalk.red(`  ✗ ${py.foundVersion} found, but Melaya needs Python 3.${PY_MIN_MINOR}–3.${PY_MAX_MINOR}`));
+            console.log(chalk.gray("    Python 3.13+ has no wheels yet for the assistant's Python deps (agentscope + native"));
+            console.log(chalk.gray("    extensions), so the runner's venv can't build and every assistant turn fails."));
+            console.log(chalk.gray("    Install a supported Python, then restart the runner:"));
+            console.log(chalk.gray("      macOS:   brew install python@3.12"));
+            console.log(chalk.gray("      Linux:   sudo apt install python3.12 python3.12-venv    (or: pyenv install 3.12)"));
+            console.log(chalk.gray("      Windows: winget install Python.Python.3.12"));
+        }
+        else {
+            console.log(chalk.red("  ✗ Python not found in PATH"));
+            console.log(chalk.gray("    Install Python 3.12 from https://python.org"));
+        }
         process.exit(1);
     }
-    console.log(chalk.green(`  ✓ Python: ${python}`));
+    const python = py.cmd;
+    console.log(chalk.green(`  ✓ Python: ${python} (3.${py.minor})`));
     // Detect local models
     const models = await detectModels();
     if (models.length === 0) {
@@ -81,17 +93,67 @@ async function main() {
         verbose: opts.verbose,
     });
 }
-async function findPython() {
+// Supported CPython range for the runner's venv. agentscope and its native
+// deps (tiktoken, numpy, pydantic-core, curl_cffi via scrapling, sentence-
+// transformers, …) only ship wheels for 3.10–3.12. Building the venv from a
+// 3.13 interpreter — which is now Homebrew's default `python3` — leaves those
+// deps unbuilt, so `import agentscope` fails the probe and every assistant /
+// pipeline turn dies with "agentscope import probe failed". So we must NOT
+// grab the first `python3` on PATH: we rank interpreters and pick a supported
+// minor, only reporting the unsupported one (with install guidance) if that's
+// all that exists. Bump PY_MAX_MINOR once the dep set is validated on a newer
+// CPython.
+const PY_MIN_MINOR = 10;
+const PY_MAX_MINOR = 12;
+async function probePyVersion(cmd) {
     const { execSync } = await import("child_process");
-    for (const cmd of ["python3", "python"]) {
-        try {
-            const version = execSync(`${cmd} --version`, { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] }).trim();
-            if (version.includes("Python 3."))
-                return cmd;
+    try {
+        const out = execSync(`"${cmd}" --version`, { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+        const m = out.match(/Python (\d+)\.(\d+)/);
+        if (!m)
+            return null;
+        return { major: Number(m[1]), minor: Number(m[2]) };
+    }
+    catch {
+        return null;
+    }
+}
+async function findPython() {
+    const candidates = [];
+    // 1. Explicit supported-minor binaries first, newest supported first. Homebrew
+    //    (`brew install python@3.12`) and pyenv both expose these names on PATH,
+    //    so this catches a supported interpreter even when bare `python3` is 3.13.
+    for (let m = PY_MAX_MINOR; m >= PY_MIN_MINOR; m--)
+        candidates.push(`python3.${m}`);
+    // 2. Common absolute install locations, in case PATH points `python3` at 3.13
+    //    but a supported keg is installed and simply not linked onto PATH.
+    for (let m = PY_MAX_MINOR; m >= PY_MIN_MINOR; m--) {
+        if (process.platform === "darwin") {
+            candidates.push(`/opt/homebrew/opt/python@3.${m}/bin/python3.${m}`, // Apple-silicon brew keg
+            `/usr/local/opt/python@3.${m}/bin/python3.${m}`, // Intel brew keg
+            `/opt/homebrew/bin/python3.${m}`, `/usr/local/bin/python3.${m}`);
         }
-        catch { /* not found */ }
+        else if (process.platform === "linux") {
+            candidates.push(`/usr/bin/python3.${m}`, `/usr/local/bin/python3.${m}`);
+        }
+    }
+    // 3. Generic names last — accepted only if they resolve into the supported range.
+    candidates.push("python3", "python");
+    let fallback; // a real 3.x that exists but is out of range
+    const seen = new Set();
+    for (const cmd of candidates) {
+        if (seen.has(cmd))
+            continue;
+        seen.add(cmd);
+        const v = await probePyVersion(cmd);
+        if (!v || v.major !== 3)
+            continue;
+        if (v.minor >= PY_MIN_MINOR && v.minor <= PY_MAX_MINOR)
+            return { ok: true, cmd, minor: v.minor };
+        if (!fallback)
+            fallback = `Python ${v.major}.${v.minor}`;
     }
-    return null;
+    return { ok: false, foundVersion: fallback };
 }
 // `melaya-runner copilot login` — GitHub Copilot device-flow sign-in, cached
 // locally. Handled before the runner arg-parse so it needs no --token.

package/dist/connection.js

@@ -820,6 +820,16 @@ export async function connect(opts) {
                         stderrTail.shift();
                 }
             });
+            proc.on("error", (err) => {
+                // Spawn failure (interpreter missing/EACCES) emits "error", never "exit".
+                // Mirror the failure path so the run resolves instead of crashing the runner.
+                activeProcesses.delete(payload.runId);
+                if (browserBridge && browserBridge.hasRun(payload.runId)) {
+                    browserBridge.teardownRun(payload.runId, "run_spawn_error").catch(() => { });
+                }
+                console.log(chalk.red(`  ✗ pipeline spawn failed: ${err?.message || err}`));
+                socket.emit("runner:runComplete", { runId: payload.runId, status: "failed" });
+            });
             proc.on("exit", (code) => {
                 activeProcesses.delete(payload.runId);
                 // Melaya Browser terminal path (plan Section 7): the pipeline
@@ -874,7 +884,28 @@ export async function connect(opts) {
             });
         }
         catch (e) {
-            console.log(chalk.red(`  ✗ Run failed: ${e.message}`));
+            // Name the cause. Every other failure branch emits an agent_message the
+            // user can read; this outer catch (shared-module fetch, file writes, grant
+            // plumbing) sent a bare status:"failed" with nothing on screen. `e.message`
+            // is undefined for a thrown string, so fall back to the value + type.
+            const reason = e?.message || String(e) || (e?.name ? `${e.name} error` : "unknown error");
+            console.log(chalk.red(`  ✗ Run failed: ${reason}`));
+            socket.emit("runner:event", {
+                run_id: payload.runId,
+                event_type: "agent_message",
+                project: payload.project,
+                replyId: `run-failed-${payload.runId}`,
+                replyName: "Runner",
+                replyRole: "system",
+                msg: {
+                    id: `run-failed-${payload.runId}`,
+                    name: "Runner",
+                    role: "system",
+                    content: [{ type: "text", text: `Run failed before it could start: ${reason}` }],
+                    metadata: { runStartError: true },
+                    timestamp: new Date().toISOString(),
+                },
+            });
             socket.emit("runner:runComplete", { runId: payload.runId, status: "failed" });
         }
     });
@@ -1423,8 +1454,24 @@ export async function connect(opts) {
                 // (e.g. the user added a connector) kills this host and spawns a REPLACEMENT
                 // under the same sid; if this late exit deleted the map entry blindly it
                 // would orphan the newcomer and make the next turn "session_not_found".
-                if (activeAssistants.get(sid) === session)
+                proc.on("error", (err) => {
+                    // A spawn that fails (python deleted post-check, EACCES/AV) emits "error"
+                    // and never "exit"; with no listener this took down the WHOLE runner.
+                    if (activeAssistants.get(sid) === session)
+                        activeAssistants.delete(sid);
+                    bootingAssistants.delete(sid);
+                    browserBridge?.teardownRunsForSession(sid, "assistant_spawn_error").catch(() => { });
+                    socket.emit("runner:assistant_event", { sessionId: sid, turnId: "", kind: "error", message: `assistant host spawn failed: ${err?.message || err}` });
+                });
+                const weOwned = activeAssistants.get(sid) === session;
+                if (weOwned)
                     activeAssistants.delete(sid);
+                // Tear down any per-turn bridge runs this host leaked (a turn that never
+                // sent `done` before the host exited/crashed) so its lease + enforceOnPage
+                // handlers don't linger on the user's open tab. Only if a replacement
+                // host hasn't already taken over the sid.
+                if (weOwned)
+                    browserBridge?.teardownRunsForSession(sid, `assistant_exit:${code}`).catch(() => { });
                 // A host we INTENTIONALLY killed for a config-drift reboot must NOT emit
                 // session_closed — that frame would fail the fresh boot's ready waiter
                 // (the server can't pre-mark it superseded here, the kill is runner-side).
@@ -1552,6 +1599,10 @@ export async function connect(opts) {
                             // frame POST path uses (ws/wss -> http/https).
                             serverBase: opts.serverUrl.replace(/^wss?:\/\//, (m) => (m === "wss://" ? "https://" : "http://")),
                             runAuthHeader: `Bearer ${opts.token}`,
+                            // OWASP A01 — bind the server-clamped turn mode into the spec so
+                            // the per-act bridge body can only TIGHTEN it, never loosen it via
+                            // a forged hitl_mode:"autonomous".
+                            hitlMode,
                         };
                         const { token } = bridge.registerRun(spec);
                         turnBridgeRunId = turnRunId;
@@ -1977,6 +2028,10 @@ export async function connect(opts) {
             proc.stderr.on("data", (data) => {
                 stderrBuf += data.toString("utf-8");
             });
+            proc.on("error", (err) => {
+                console.log(chalk.red(`  ✗ RAG ingest spawn failed: ${err?.message || err}`));
+                socket.emit("rag:ingest-result", { session_id: sid, ok: false, error: err?.message || String(err), store_path: storePath });
+            });
             proc.on("close", (code) => {
                 const ok = code === 0;
                 console.log(ok
@@ -2084,6 +2139,10 @@ export async function connect(opts) {
             let stderr = "";
             proc.stdout.on("data", (data) => { stdout += data.toString("utf-8"); });
             proc.stderr.on("data", (data) => { stderr += data.toString("utf-8"); });
+            proc.on("error", (err) => {
+                // Spawn failure emits "error", never "close"; resolve the retrieve so the UI stops spinning.
+                socket.emit("rag:retrieve-result", { session_id: sid, ok: false, results: [], error: err?.message || String(err) });
+            });
             proc.on("close", (code) => {
                 const jsonLine = stdout.split(/\r?\n/).map(s => s.trim()).filter(Boolean).reverse()[0] || "";
                 let parsed = null;

package/dist/lumaBrowserBridge.js

@@ -330,9 +330,13 @@ export async function startLumaBrowserBridge(opts) {
                 b = await playwright.chromium.launch({ headless: true, args: launchArgs });
             }
             browser = b;
-            browserLaunching = null;
             return b;
         })();
+        // Clear the cached promise on FAILURE too, or a single failed launch
+        // (bundled Chromium never installed) is cached and every later call returns
+        // the same stale rejection until the runner restarts — Luma writes stay
+        // broken even after the user fixes the browser. Mirrors browserBridge.ts:808.
+        browserLaunching.then(() => { browserLaunching = null; }, () => { browserLaunching = null; });
         return browserLaunching;
     }
     async function _readStorageState() {
@@ -403,6 +407,10 @@ export async function startLumaBrowserBridge(opts) {
                 };
                 if (init.body !== undefined)
                     fetchInit.body = init.body;
+                // Bound the in-page fetch: without a signal, a Cloudflare hold or a
+                // stalled response leaves this evaluate (and the /luma/forward tool
+                // call) hanging forever — a promise no catch can see.
+                fetchInit.signal = AbortSignal.timeout(30_000);
                 const r = await fetch(init.url, fetchInit);
                 const text = await r.text();
                 return { status: r.status, body: text };

package/dist/publishGate.d.ts

@@ -1,13 +1,14 @@
-/** Classify a control's accessible name into a consequential effect.
- *  Purchase wins on overlap. Returns null when nothing matches (the caller
- *  then runs the action normally, no gate). The name is lowercased + trimmed
- *  here so callers can pass a raw accessible name. */
-export declare function classifyControlEffect(name: string): "publish" | "purchase" | null;
-/** Does a detected consequential effect need approval in the given AUTONOMY
- *  mode? The single gate rule, driven by the turn's mode (NOT the grant ceiling,
- *  which is always 'destructive'):
- *    safe          -> gate every consequential write (publish AND purchase)
- *    payments_only -> gate only purchases
- *    autonomous    -> gate nothing (the user authorized end-to-end action)
- *  Unknown/absent fails closed to 'safe'. */
-export declare function writeGatedInMode(effect: "publish" | "purchase", mode: string | undefined): boolean;
+export type CommitEffect = "publish" | "purchase" | "account_change" | "destructive";
+export declare const PURCHASE_VERBS: readonly ["buy", "buy now", "pay", "pay now", "place order", "order", "checkout", "check out", "purchase", "subscribe", "donate", "confirm and pay", "complete purchase", "place bid", "add to cart", "proceed to payment", "comprar", "pagar", "pagar ahora", "finalizar compra", "realizar pedido", "suscribirse", "donar", "confirmar y pagar", "finalizar pedido", "assinar", "acheter", "payer", "commander", "passer commande", "s'abonner", "abonner", "faire un don", "valider le paiement", "proceder au paiement", "купить", "оплатить", "заказать", "подписаться", "оформить заказ", "खरीदें", "भुगतान करें", "ऑर्डर करें", "सब्सक्राइब करें", "bumili", "magbayad", "购买", "付款", "立即购买", "结算", "提交订单", "订阅", "充值"];
+export declare const DESTRUCTIVE_VERBS: readonly ["delete", "delete account", "remove", "erase", "wipe", "destroy", "discard", "revoke", "disconnect", "unlink", "deactivate", "close account", "terminate", "unsubscribe", "cancel subscription", "cancel plan", "archive", "trash", "reset", "restore defaults", "leave", "block", "ban", "uninstall", "clear all", "eliminar", "borrar", "quitar", "revocar", "desconectar", "desactivar", "cancelar suscripcion", "archivar", "restablecer", "excluir", "remover", "desativar", "cancelar assinatura", "arquivar", "redefinir", "supprimer", "effacer", "retirer", "revoquer", "deconnecter", "desactiver", "resilier", "archiver", "reinitialiser", "удалить", "стереть", "отключить", "отозвать", "деактивировать", "отменить подписку", "сбросить", "हटाएं", "डिलीट करें", "निकालें", "रद्द करें", "burahin", "alisin", "tanggalin", "删除", "移除", "清除", "销毁", "注销", "解绑", "取消订阅", "归档", "重置"];
+export declare const ACCOUNT_VERBS: readonly ["change password", "update password", "reset password", "change email", "update email", "enable two-factor", "disable two-factor", "add member", "invite", "invite member", "transfer ownership", "make admin", "grant access", "authorize", "authorise", "allow access", "connect account", "link account", "add payment method", "withdraw", "transfer", "send money", "cambiar contrasena", "invitar", "autorizar", "conceder acceso", "transferir", "retirar", "alterar senha", "convidar", "autorizar acesso", "changer le mot de passe", "inviter", "autoriser", "transferer", "retirer", "сменить пароль", "пригласить", "разрешить", "перевести", "вывести", "पासवर्ड बदलें", "आमंत्रित करें", "अनुमति दें", "mag-imbita", "payagan", "修改密码", "邀请", "授权", "允许", "转让", "提现", "转账"];
+export declare const PUBLISH_VERBS: readonly ["post", "comment", "reply", "send", "publish", "share", "tweet", "retweet", "repost", "submit", "post comment", "add comment", "leave a comment", "send message", "create", "save", "update", "apply", "confirm", "accept", "agree", "add", "upload", "book", "reserve", "sign", "sign up", "register", "follow", "like", "upvote", "download", "install", "deploy", "merge", "approve", "continue", "finish", "done", "next", "publicar", "comentar", "responder", "enviar", "compartir", "crear", "guardar", "actualizar", "aplicar", "confirmar", "aceptar", "anadir", "agregar", "seguir", "registrarse", "continuar", "criar", "salvar", "atualizar", "aceitar", "adicionar", "seguir", "continuar", "compartilhar", "publier", "commenter", "repondre", "envoyer", "partager", "creer", "enregistrer", "sauvegarder", "mettre a jour", "appliquer", "confirmer", "accepter", "ajouter", "suivre", "s'inscrire", "continuer", "valider", "опубликовать", "комментировать", "ответить", "отправить", "поделиться", "создать", "сохранить", "обновить", "применить", "подтвердить", "принять", "добавить", "подписаться", "продолжить", "зарегистрироваться", "पोस्ट करें", "टिप्पणी करें", "भेजें", "साझा करें", "बनाएं", "सहेजें", "अपडेट करें", "पुष्टि करें", "स्वीकार करें", "जोड़ें", "जारी रखें", "ipadala", "ibahagi", "gumawa", "i-save", "kumpirmahin", "tanggapin", "magdagdag", "magpatuloy", "sundan", "发布", "发送", "评论", "回复", "分享", "转发", "提交", "创建", "保存", "更新", "确认", "接受", "同意", "添加", "上传", "关注", "点赞", "继续", "注册", "完成"];
+/** Classify a control name into a consequential effect, or null when benign.
+ *  Precedence by blast radius: purchase, destructive, account_change, publish. */
+export declare function classifyControlEffect(name: string): CommitEffect | null;
+/** Does this effect need approval in the given autonomy mode?
+ *    safe          -> gate every consequential write
+ *    payments_only -> gate purchases AND the two irreversible families
+ *    autonomous    -> gate nothing
+ *  Unknown/absent -> safe (fail closed). */
+export declare function writeGatedInMode(effect: CommitEffect, mode: string | undefined): boolean;

package/dist/publishGate.js

@@ -1,102 +1,154 @@
-// packages/runner/src/publishGate.ts
+// Control-effect classifier for the RUNNER's browser bridge.
 //
-// Melaya Browser, Route 1 HITL publish gate: the runner-side mirror of the
-// phone's on-device `detectPublish` gate. The bridge is the only place that
-// sees the clicked control's TRUSTED accessible name (page text is untrusted,
-// so the server can only classify a raw "Post/Comment/Buy" click as
-// "message"). This module classifies that trusted name into a consequential
-// effect ("publish" | "purchase") so the bridge can escalate the effect from
-// its own read and stage a human approval when the grant does not permit the
-// action unattended.
+// PORTED from extension/src/protocol/publishGate.ts so the two gates agree
+// verb-for-verb (FROZEN CONTRACT). The runner previously carried an OLDER
+// 2-family list (publish/purchase, English only), so in Safe mode `create`,
+// `delete`, `save`, `confirm`, `transfer`, and every non-English label ran
+// UNATTENDED on the runner path — the exact gap the extension gate already
+// closed. This brings the runner to parity: four effect families, eight
+// locales.
 //
-// Pure classification only: no I/O, no Playwright. The bridge owns the
-// accessible-name read and the server approval call; this file just maps a
-// name string to an effect class using the frozen word lists.
-// ---------------------------------------------------------------------
-// Frozen effect vocabularies (phone detectPublish mirror)
-// ---------------------------------------------------------------------
-//
-// Each phrase is matched word-aware (word boundaries) so "reporter" does not
-// match "report" and "password" does not match "pass". Purchase wins on any
-// overlap with publish. Keep these lists in sync with the phone's
-// detectPublish word lists.
-const PURCHASE_PHRASES = [
-    "buy",
-    "buy now",
-    "pay",
-    "pay now",
-    "place order",
-    "order",
-    "checkout",
-    "check out",
-    "purchase",
-    "subscribe",
-    "donate",
-    "confirm and pay",
-    "complete purchase",
-    "place bid",
+// The runner reads a control's accessible NAME (readAccessibleNameAtPoint) and
+// classifies it here; it has no structural (submitLike) signal, so the caller
+// supplies a forced effect for actions that are commits by construction
+// (browser_submit) and fails closed when the name could not be read at all.
+export const PURCHASE_VERBS = [
+    // en
+    "buy", "buy now", "pay", "pay now", "place order", "order", "checkout",
+    "check out", "purchase", "subscribe", "donate", "confirm and pay",
+    "complete purchase", "place bid", "add to cart", "proceed to payment",
+    // es / pt
+    "comprar", "pagar", "pagar ahora", "finalizar compra", "realizar pedido",
+    "suscribirse", "donar", "confirmar y pagar", "finalizar pedido", "assinar",
+    // fr
+    "acheter", "payer", "commander", "passer commande", "s'abonner", "abonner",
+    "faire un don", "valider le paiement", "proceder au paiement",
+    // ru
+    "купить", "оплатить", "заказать", "подписаться", "оформить заказ",
+    // hi
+    "खरीदें", "भुगतान करें", "ऑर्डर करें", "सब्सक्राइब करें",
+    // tl
+    "bumili", "magbayad",
+    // zh
+    "购买", "付款", "立即购买", "结算", "提交订单", "订阅", "充值",
+];
+export const DESTRUCTIVE_VERBS = [
+    // en
+    "delete", "delete account", "remove", "erase", "wipe", "destroy", "discard",
+    "revoke", "disconnect", "unlink", "deactivate", "close account", "terminate",
+    "unsubscribe", "cancel subscription", "cancel plan", "archive", "trash",
+    "reset", "restore defaults", "leave", "block", "ban", "uninstall", "clear all",
+    // es / pt
+    "eliminar", "borrar", "quitar", "revocar", "desconectar", "desactivar",
+    "cancelar suscripcion", "archivar", "restablecer", "excluir", "remover",
+    "desativar", "cancelar assinatura", "arquivar", "redefinir",
+    // fr
+    "supprimer", "effacer", "retirer", "revoquer", "deconnecter", "desactiver",
+    "resilier", "archiver", "reinitialiser",
+    // ru
+    "удалить", "стереть", "отключить", "отозвать", "деактивировать", "отменить подписку", "сбросить",
+    // hi
+    "हटाएं", "डिलीट करें", "निकालें", "रद्द करें",
+    // tl
+    "burahin", "alisin", "tanggalin",
+    // zh
+    "删除", "移除", "清除", "销毁", "注销", "解绑", "取消订阅", "归档", "重置",
 ];
-const PUBLISH_PHRASES = [
-    "post",
-    "comment",
-    "reply",
-    "send",
-    "publish",
-    "share",
-    "tweet",
-    "retweet",
-    "repost",
-    "submit",
-    "post comment",
-    "add comment",
-    "leave a comment",
-    "send message",
+export const ACCOUNT_VERBS = [
+    // en
+    "change password", "update password", "reset password", "change email",
+    "update email", "enable two-factor", "disable two-factor", "add member",
+    "invite", "invite member", "transfer ownership", "make admin", "grant access",
+    "authorize", "authorise", "allow access", "connect account", "link account",
+    "add payment method", "withdraw", "transfer", "send money",
+    // es / pt
+    "cambiar contrasena", "invitar", "autorizar", "conceder acceso", "transferir",
+    "retirar", "alterar senha", "convidar", "autorizar acesso",
+    // fr
+    "changer le mot de passe", "inviter", "autoriser", "transferer", "retirer",
+    // ru
+    "сменить пароль", "пригласить", "разрешить", "перевести", "вывести",
+    // hi
+    "पासवर्ड बदलें", "आमंत्रित करें", "अनुमति दें",
+    // tl
+    "mag-imbita", "payagan",
+    // zh
+    "修改密码", "邀请", "授权", "允许", "转让", "提现", "转账",
+];
+export const PUBLISH_VERBS = [
+    // en — the original list, plus every write verb it was missing
+    "post", "comment", "reply", "send", "publish", "share", "tweet", "retweet",
+    "repost", "submit", "post comment", "add comment", "leave a comment",
+    "send message", "create", "save", "update", "apply", "confirm", "accept",
+    "agree", "add", "upload", "book", "reserve", "sign", "sign up", "register",
+    "follow", "like", "upvote", "download", "install", "deploy", "merge",
+    "approve", "continue", "finish", "done", "next",
+    // es / pt
+    "publicar", "comentar", "responder", "enviar", "compartir", "crear",
+    "guardar", "actualizar", "aplicar", "confirmar", "aceptar", "anadir",
+    "agregar", "seguir", "registrarse", "continuar", "criar", "salvar",
+    "atualizar", "aceitar", "adicionar", "seguir", "continuar", "compartilhar",
+    // fr
+    "publier", "commenter", "repondre", "envoyer", "partager", "creer",
+    "enregistrer", "sauvegarder", "mettre a jour", "appliquer", "confirmer",
+    "accepter", "ajouter", "suivre", "s'inscrire", "continuer", "valider",
+    // ru
+    "опубликовать", "комментировать", "ответить", "отправить", "поделиться",
+    "создать", "сохранить", "обновить", "применить", "подтвердить", "принять",
+    "добавить", "подписаться", "продолжить", "зарегистрироваться",
+    // hi
+    "पोस्ट करें", "टिप्पणी करें", "भेजें", "साझा करें", "बनाएं",
+    "सहेजें", "अपडेट करें", "पुष्टि करें", "स्वीकार करें", "जोड़ें", "जारी रखें",
+    // tl
+    "ipadala", "ibahagi", "gumawa", "i-save", "kumpirmahin", "tanggapin",
+    "magdagdag", "magpatuloy", "sundan",
+    // zh
+    "发布", "发送", "评论", "回复", "分享", "转发", "提交", "创建",
+    "保存", "更新", "确认", "接受", "同意", "添加", "上传", "关注",
+    "点赞", "继续", "注册", "完成",
 ];
-/** Escape a phrase for use inside a RegExp source. */
 function escapeRe(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-/** Word-aware containment: true when `phrase` appears in `name` bounded by
- *  non-word characters (or string ends) on both sides. Both are assumed
- *  already lowercased + trimmed. A phrase with internal spaces matches the
- *  same run of whitespace-separated words. */
+// Word-aware for Latin scripts; plain containment for CJK/Devanagari (no word
+// delimiters), which is the correct behaviour for those verb lists.
 function containsPhrase(name, phrase) {
-    // \b would not fire around non-ASCII, but the frozen phrases are all ASCII
-    // words, so an explicit non-word-char boundary on each side is sufficient
-    // and avoids the "reporter" != "report" / "password" != "pass" traps.
-    const re = new RegExp(`(?:^|[^a-z0-9])${escapeRe(phrase)}(?:$|[^a-z0-9])`, "i");
-    return re.test(name);
+    const p = phrase.trim().toLowerCase();
+    if (!p)
+        return false;
+    const escaped = p.split(/\s+/).map(escapeRe).join("\\s+");
+    return new RegExp(`(?:^|[^a-z0-9])${escaped}(?:$|[^a-z0-9])`, "i").test(name);
 }
-/** Classify a control's accessible name into a consequential effect.
- *  Purchase wins on overlap. Returns null when nothing matches (the caller
- *  then runs the action normally, no gate). The name is lowercased + trimmed
- *  here so callers can pass a raw accessible name. */
+/** Classify a control name into a consequential effect, or null when benign.
+ *  Precedence by blast radius: purchase, destructive, account_change, publish. */
 export function classifyControlEffect(name) {
     const n = String(name || "").toLowerCase().trim();
     if (!n)
         return null;
-    for (const phrase of PURCHASE_PHRASES) {
-        if (containsPhrase(n, phrase))
+    for (const p of PURCHASE_VERBS)
+        if (containsPhrase(n, p))
             return "purchase";
-    }
-    for (const phrase of PUBLISH_PHRASES) {
-        if (containsPhrase(n, phrase))
+    for (const p of DESTRUCTIVE_VERBS)
+        if (containsPhrase(n, p))
+            return "destructive";
+    for (const p of ACCOUNT_VERBS)
+        if (containsPhrase(n, p))
+            return "account_change";
+    for (const p of PUBLISH_VERBS)
+        if (containsPhrase(n, p))
             return "publish";
-    }
     return null;
 }
-/** Does a detected consequential effect need approval in the given AUTONOMY
- *  mode? The single gate rule, driven by the turn's mode (NOT the grant ceiling,
- *  which is always 'destructive'):
- *    safe          -> gate every consequential write (publish AND purchase)
- *    payments_only -> gate only purchases
- *    autonomous    -> gate nothing (the user authorized end-to-end action)
- *  Unknown/absent fails closed to 'safe'. */
+/** Does this effect need approval in the given autonomy mode?
+ *    safe          -> gate every consequential write
+ *    payments_only -> gate purchases AND the two irreversible families
+ *    autonomous    -> gate nothing
+ *  Unknown/absent -> safe (fail closed). */
 export function writeGatedInMode(effect, mode) {
-    const m = String(mode || "safe").toLowerCase();
+    const m = (mode || "safe").toLowerCase();
     if (m === "autonomous")
         return false;
     if (m === "payments_only")
-        return effect === "purchase";
+        return effect !== "publish";
     return true;
 }

package/dist/pythonEnv.js

@@ -10,7 +10,7 @@
  * shared-bundle version. Re-bootstraps when the bundle version changes.
  */
 import { spawn } from "child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "fs";
 import { createHash } from "crypto";
 import { join } from "path";
 import { homedir, platform } from "os";
@@ -19,6 +19,29 @@ const CACHE_DIR = join(homedir(), ".melaya-runner");
 const VENV_DIR = join(CACHE_DIR, "venv");
 const VENV_MARK = join(CACHE_DIR, "venv-version.txt");
 const AGENTSCOPE = join(CACHE_DIR, "agentscope");
+// Supported CPython range for the venv — MUST match cli.ts's findPython(). A
+// venv is a thin wrapper frozen to the interpreter that created it, so one
+// built from an unsupported minor (e.g. a pre-fix runner that grabbed
+// Homebrew's python3.13) can never install agentscope's deps and its import
+// probe always fails. We detect that from pyvenv.cfg and rebuild automatically.
+const PY_SUPPORTED_MIN = 10;
+const PY_SUPPORTED_MAX = 12;
+// The minor version a venv was built from, read from its pyvenv.cfg
+// (`version = 3.12.4`). Returns null if the file is missing/unparseable.
+function venvMinorVersion() {
+    try {
+        const cfg = readFileSync(join(VENV_DIR, "pyvenv.cfg"), "utf-8");
+        const m = cfg.match(/version(?:_info)?\s*=\s*3\.(\d+)/i);
+        return m ? Number(m[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function venvVersionSupported() {
+    const minor = venvMinorVersion();
+    return minor !== null && minor >= PY_SUPPORTED_MIN && minor <= PY_SUPPORTED_MAX;
+}
 // Explicit dependency list. The shared-bundle endpoint ships only
 // `*.py` files — no pyproject.toml — so `pip install -e
 // ~/.melaya-runner/agentscope` does NOT work (pip can't find a project
@@ -243,6 +266,11 @@ function venvIsValid(expectedVersion) {
         return false;
     if (!existsSync(VENV_MARK))
         return false;
+    // A venv built from an unsupported Python is never "valid", regardless of the
+    // marker — this forces the rebuild path (which recreates it from a supported
+    // interpreter) instead of self-healing a doomed venv.
+    if (!venvVersionSupported())
+        return false;
     try {
         const cached = readFileSync(VENV_MARK, "utf-8").trim();
         return cached === venvMarkerValue(expectedVersion);
@@ -251,13 +279,43 @@ function venvIsValid(expectedVersion) {
         return false;
     }
 }
-function runProc(cmd, args, onLine, envExtra = {}) {
+function runProc(cmd, args, onLine, envExtra = {}, 
+// INACTIVITY clock, not a flat one. A first-run bootstrap (venv + full dep
+// install + browser download) legitimately takes 10+ minutes, but it STREAMS
+// progress the whole time — so we bound silence, not duration. A black-holed
+// pip mirror or a stalled download produces no output; after this long with
+// nothing, kill the child and fail non-zero rather than hang ensurePythonEnv
+// (which every run, RAG ingest and assistant boot sits behind).
+inactivityMs = 10 * 60_000) {
     return new Promise((resolve) => {
         const child = spawn(cmd, args, {
             stdio: ["ignore", "pipe", "pipe"],
             env: { ...process.env, ...envExtra },
         });
+        let done = false;
+        let timer;
+        const finish = (code) => {
+            if (done)
+                return;
+            done = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(code);
+        };
+        const bump = () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                try {
+                    child.kill("SIGKILL");
+                }
+                catch { /* already gone */ }
+                onLine(`[runProc] no output for ${Math.round(inactivityMs / 60000)} min — killing '${cmd}'`);
+                finish(1);
+            }, inactivityMs);
+        };
         const chew = (b) => {
+            bump();
             for (const ln of b.toString().split("\n")) {
                 const t = ln.trimEnd();
                 if (t)
@@ -266,8 +324,9 @@ function runProc(cmd, args, onLine, envExtra = {}) {
         };
         child.stdout?.on("data", chew);
         child.stderr?.on("data", chew);
-        child.on("exit", (code) => resolve(code ?? 1));
-        child.on("error", () => resolve(1));
+        child.on("exit", (code) => finish(code ?? 1));
+        child.on("error", () => finish(1));
+        bump(); // start the clock
     });
 }
 /**
@@ -345,6 +404,28 @@ export async function ensurePythonEnv(systemPython, expectedVersion, onProgress
         };
     }
     mkdirSync(CACHE_DIR, { recursive: true });
+    // Step 0: heal a venv left behind by a runner that built it from an
+    // unsupported interpreter (the classic case: a pre-fix runner grabbed
+    // Homebrew's python3.13, so agentscope's deps never installed and the import
+    // probe fails forever). A venv's Python is frozen at creation, so the only
+    // fix is to delete and recreate it from `systemPython` — which the CLI now
+    // guarantees is a supported 3.10–3.12. Fully automatic: no "delete the venv
+    // and restart" by hand.
+    if (existsSync(venvPython()) && !venvVersionSupported()) {
+        const minor = venvMinorVersion();
+        onProgress(`existing venv is Python ${minor === null ? "unknown" : `3.${minor}`} ` +
+            `(unsupported — need 3.${PY_SUPPORTED_MIN}–3.${PY_SUPPORTED_MAX}); rebuilding it`);
+        try {
+            rmSync(VENV_DIR, { recursive: true, force: true });
+        }
+        catch (e) {
+            return {
+                ok: false,
+                pythonPath: systemPython,
+                reason: `could not remove the stale venv at ${VENV_DIR} (${e?.message}). Delete it manually and restart the runner.`,
+            };
+        }
+    }
     // Step 1: create the venv if missing.
     if (!existsSync(venvPython())) {
         onProgress(`creating venv at ${VENV_DIR} (one-time, ~5s)`);
@@ -408,19 +489,22 @@ export async function ensurePythonEnv(systemPython, expectedVersion, onProgress
     // identical whether the venv is fresh or already valid.
     await ensureNltkData(onProgress);
     await _resolveAndCacheCertBundle(onProgress);
-    writeFileSync(VENV_MARK, venvMarkerValue(expectedVersion), "utf-8");
     // sanity: confirm shortuuid + agentscope (via PYTHONPATH) resolve now.
     // Probe must mirror the spawn env so PYTHONPATH=CACHE_DIR points at
     // the cached agentscope source — without this the probe ImportError's
-    // even though the real spawn would work.
+    // even though the real spawn would work. The marker is written ONLY after
+    // 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 });
     if (probe !== 0) {
         return {
             ok: false,
             pythonPath: systemPython,
-            reason: "venv created but agentscope import probe failed. Delete ~/.melaya-runner/venv and restart the runner.",
+            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.`,
         };
     }
+    writeFileSync(VENV_MARK, venvMarkerValue(expectedVersion), "utf-8");
     onProgress(`✓ venv ready (python=${venvPython()})`);
     return { ok: true, pythonPath: venvPython() };
 }

package/package.json

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