@extension.dev/mcp 4.7.0 → 4.9.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "extension-mcp",
       "source": "./",
       "description": "MCP tools for browser extension development: scaffold from 60+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox.",
-      "version": "4.7.0",
+      "version": "4.9.0",
       "category": "development",
       "author": {
         "name": "Cezar Augusto"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "extension-mcp",
   "description": "MCP tools for browser extension development: scaffold from 60+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox. Ships /extension, /extension-add, /extension-debug, and /extension-publish commands.",
-  "version": "4.7.0",
+  "version": "4.9.0",
   "author": {
     "name": "Cezar Augusto",
     "email": "boss@cezaraugusto.net",

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 4.9.0
+
+A second pass from the persona swarm, closing the gaps 4.8.0 left and the top
+new blockers it surfaced.
+
+- **Honest `extension_manifest_validate`.** It now scans the project source for
+  permission-gated `chrome.*`/`browser.*` calls and flags any the manifest does
+  not declare — an API used without its permission is `undefined` at runtime and
+  crashes the context, the exact case where validate used to report `valid:true`.
+  The headline is now honest (`valid:false` + `buildBlocking:true` on any error),
+  and it accepts singular `browser` as an alias for `browsers`.
+- **`extension_open` can navigate a tab.** Pass a `url` (Chromium, via CDP) to
+  drive a content-script test page, a `webNavigation` target, or the popup as a
+  page (`chrome-extension://<id>/popup.html`) — the loop the surface-only open
+  could not do. `target` is accepted as an alias for `surface`.
+- **`extension_stop` actually reaps the session.** It now terminates the dev CLI
+  and both browser families (gecko profile + chromium `--load-extension`, under
+  the project's dist) and refuses to report `stopped:true` while any survive.
+- **`extension_wait` won't lie about a dead session.** A `ready.json` whose pid
+  is dead now returns `status:"stale"` instead of `ready`, so you don't walk into
+  a reload/eval that fails with a misleading control-channel error.
+- **Dropped-channel errors name the real cause.** A `1006` / "no control channel"
+  now detects an exited dev server (stale ready.json + dead pid) and says so,
+  instead of asking "is the session started with allowControl?" when it was.
+- **`extension_doctor`** surfaces recent error-level logs as a `runtime-errors`
+  check (so a background throwing on every event isn't `healthy:true`), keeps the
+  project-local engine version in project mode, and flags when that engine
+  differs from a pinned `EXTENSION_MCP_CLI_VERSION`.
+- **`extension_build`** lists declared entrypoints in its success output, so a
+  content script no longer reads as "didn't build".
+- **`extension_create`** forces non-interactive git (`GIT_TERMINAL_PROMPT=0`) so a
+  credential prompt can't hang the template download, retries once on a transient
+  network/timeout failure (cleaning the partial dir first), reports a download
+  failure as such instead of "choose a valid template name", and warns when the
+  scaffold's `extension@latest` pin will win over your pinned CLI.
+- Eval/inspect error guidance now speaks MCP JSON args (`context`, `tab`, `url`)
+  instead of CLI flags.
+
+## 4.8.0
+
+Dev-session ergonomics hardened from a 30-persona agent walk of the toolchain.
+
+- **`allowEval` now implies `allowControl`.** Enabling eval on `extension_dev`
+  also opens the control channel, so a single `allowEval: true` unlocks
+  `extension_storage`/`reload`/`open`/`dom_inspect` too. `extension_dev` now
+  returns a `capabilities` block naming exactly which verbs the session unlocked,
+  ending the stop-and-restart loop that hit agents who passed one flag and not
+  the other.
+- **Session-aware browser default.** `extension_stop` (and the other
+  browser-scoped tools) resolve the browser from the one live session for the
+  project instead of assuming `chrome`. `extension_stop` also reaps the launched
+  browser's process tree and refuses to report `stopped: true` while a process
+  survives, fixing orphaned browsers (notably Firefox) after a stop.
+- **Forgiving argument names.** Common synonyms are accepted and normalized:
+  `path`/`dir` for `projectPath`, `name` for `projectName`, `template` for
+  `slug`, `code` for `expression`, and more, so a reasonable first guess no
+  longer 400s.
+- **`extension_manifest_validate`** accepts `projectPath` (it finds the
+  manifest) and probes path-valued fields (popup, service worker, icons, content
+  scripts) against disk, warning on dangling references instead of a false
+  all-clear.
+- **`extension_doctor`** inlines the dev session's own recorded errors so a build
+  or load failure no longer reads as healthy.
+- **`extension_inspect`** lists declared entrypoints (so a small content script
+  is not buried under assets) and warns when a store-listing promo image is
+  shipped inside the package.
+- **`extension_source_inspect`** on a Gecko session now names the working
+  alternatives (`extension_logs`, `extension_eval`) instead of pointing back at
+  the tool that just refused.
+
 ## 4.7.0
 
 `extension_deploy` now submits **through** extension.dev instead of driving a

package/dist/module.js

@@ -7,11 +7,11 @@ import node_path, { join } from "node:path";
 import { extensionCreate } from "extension-create";
 import node_os from "node:os";
 import cross_spawn from "cross-spawn";
+import { execFile, execFileSync } from "node:child_process";
 import { filterKeysForThisBrowser } from "browser-extension-manifest-fields";
 import ws from "ws";
 import node_http from "node:http";
 import { extensionInstall, extensionUninstall, getManagedBrowsersCacheRoot } from "extension-install";
-import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 var add_feature_namespaceObject = {};
 __webpack_require__.r(add_feature_namespaceObject);
@@ -199,7 +199,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"4.6.0","El":{"OP":"^4.0.11"}}');
+var package_namespaceObject = JSON.parse('{"rE":"4.8.0","El":{"OP":"^4.0.11"}}');
 function detectPackageManager(projectPath) {
     const byLockfile = [
         [
@@ -259,14 +259,27 @@ const create_schema = {
 async function create_handler(args) {
     const start = Date.now();
     const projectInput = args.parentDir ? node_path.resolve(args.parentDir, args.projectName) : args.projectName;
+    process.env.GIT_TERMINAL_PROMPT = "0";
+    if (void 0 === process.env.GIT_ASKPASS) process.env.GIT_ASKPASS = "";
     const logLines = [];
     const capture = (stream)=>(...parts)=>{
             const line = parts.map((p)=>"string" == typeof p ? p : String(p)).join(" ").trim();
             if (line) logLines.push("error" === stream ? `[error] ${line}` : line);
         };
     const logTail = (max = 20)=>logLines.slice(-max);
-    try {
-        const result = await extensionCreate(projectInput, {
+    const looksTransient = ()=>{
+        const blob = logLines.join("\n").toLowerCase();
+        return /timed out|timeout|etimedout|econnreset|rate limit|\b429\b|network|could not resolve host|terminal prompts disabled|authentication failed|early eof|rpc failed|remote end hung up/.test(blob);
+    };
+    const cleanPartial = ()=>{
+        try {
+            if (args.parentDir && node_fs.existsSync(projectInput)) node_fs.rmSync(projectInput, {
+                recursive: true,
+                force: true
+            });
+        } catch  {}
+    };
+    const attempt = ()=>extensionCreate(projectInput, {
             template: args.template ?? "typescript",
             install: args.install ?? true,
             logger: {
@@ -274,34 +287,53 @@ async function create_handler(args) {
                 error: capture("error")
             }
         });
-        const packageManager = result.depsInstalled ? detectPackageManager(result.projectPath) : "npm";
-        const runDev = `${packageManager} run dev`;
-        return JSON.stringify({
-            projectPath: result.projectPath,
-            projectName: result.projectName,
-            template: result.template,
-            depsInstalled: result.depsInstalled,
-            packageManager: result.depsInstalled ? packageManager : null,
-            duration: Date.now() - start,
-            nextSteps: result.depsInstalled ? [
-                `cd ${result.projectPath}`,
-                runDev
-            ] : [
-                `cd ${result.projectPath}`,
-                "npm install",
-                "npm run dev"
-            ],
-            ...result.depsInstalled ? {} : {
-                warnings: logTail()
-            }
-        });
-    } catch (err) {
-        return JSON.stringify({
-            error: err instanceof Error ? err.message : String(err),
+    const failure = (err, transient)=>JSON.stringify({
+            error: transient ? "Template download failed (network/timeout/rate-limit) — this is not a bad template name. Retry, or check connectivity/GitHub rate limits." : err instanceof Error ? err.message : String(err),
+            ...transient ? {
+                cause: err instanceof Error ? err.message : String(err)
+            } : {},
             duration: Date.now() - start,
             log: logTail()
         });
+    let result;
+    try {
+        result = await attempt();
+    } catch (err1) {
+        if (!looksTransient()) return failure(err1, false);
+        logLines.push("[retry] transient template-download failure; retrying once");
+        cleanPartial();
+        try {
+            result = await attempt();
+        } catch (err2) {
+            return failure(err2, looksTransient());
+        }
     }
+    const packageManager = result.depsInstalled ? detectPackageManager(result.projectPath) : "npm";
+    const runDev = `${packageManager} run dev`;
+    const pin = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
+    const engineWarning = pin && "latest" !== pin ? `The scaffold pins "extension": "latest"; the project-local engine wins over EXTENSION_MCP_CLI_VERSION=${pin}. Run \`(cd ${result.projectPath} && npm i -D extension@${pin})\` to match the pinned engine.` : void 0;
+    return JSON.stringify({
+        projectPath: result.projectPath,
+        projectName: result.projectName,
+        template: result.template,
+        depsInstalled: result.depsInstalled,
+        packageManager: result.depsInstalled ? packageManager : null,
+        duration: Date.now() - start,
+        nextSteps: result.depsInstalled ? [
+            `cd ${result.projectPath}`,
+            runDev
+        ] : [
+            `cd ${result.projectPath}`,
+            "npm install",
+            "npm run dev"
+        ],
+        ...engineWarning ? {
+            engineWarning
+        } : {},
+        ...result.depsInstalled ? {} : {
+            warnings: logTail()
+        }
+    });
 }
 const CACHE_DIR = node_path.join(node_os.homedir(), ".cache", "extension-js");
 const CACHE_FILE = node_path.join(CACHE_DIR, "templates-meta.json");
@@ -535,6 +567,34 @@ function spawnExtensionCli(args, options) {
     child.unref();
     return child;
 }
+function builtEntrypoints(distDir) {
+    let manifest;
+    try {
+        manifest = JSON.parse(node_fs.readFileSync(node_path.join(distDir, "manifest.json"), "utf8"));
+    } catch  {
+        return [];
+    }
+    const out = [];
+    const add = (role, ref)=>{
+        if ("string" != typeof ref) return;
+        out.push({
+            role,
+            path: ref,
+            present: node_fs.existsSync(node_path.join(distDir, ref.replace(/^\.?\//, "")))
+        });
+    };
+    const bg = manifest.background;
+    if (bg?.service_worker) add("background.service_worker", bg.service_worker);
+    if (Array.isArray(bg?.scripts)) bg.scripts.forEach((s)=>add("background.scripts", s));
+    const action = manifest.action || manifest.browser_action;
+    if (action?.default_popup) add("action.default_popup", action.default_popup);
+    const cs = manifest.content_scripts;
+    if (Array.isArray(cs)) cs.forEach((c, i)=>{
+        if (Array.isArray(c.js)) c.js.forEach((j)=>add(`content_scripts[${i}].js`, j));
+        if (Array.isArray(c.css)) c.css.forEach((s)=>add(`content_scripts[${i}].css`, s));
+    });
+    return out;
+}
 const build_schema = {
     name: "extension_build",
     description: "Build a browser extension for production. Outputs to dist/<browser>/. Optionally creates .zip for store submission.",
@@ -632,6 +692,7 @@ async function build_handler(args) {
     if (0 === code) {
         const size = out.match(/Size:\s*([\d.]+\s*[kKmMgG]?B)/)?.[1];
         const status = out.match(/Build Status:\s*(\w+)/)?.[1];
+        const entrypoints = builtEntrypoints(node_path.resolve(args.projectPath, "dist", browser));
         return JSON.stringify({
             success: true,
             browser,
@@ -641,6 +702,9 @@ async function build_handler(args) {
             ...status ? {
                 status
             } : {},
+            ...entrypoints.length ? {
+                entrypoints
+            } : {},
             zip: args.zip ?? false,
             duration,
             output: lastLines(out, 12)
@@ -769,7 +833,7 @@ const dev_schema = {
             allowEval: {
                 type: "boolean",
                 default: false,
-                description: "Additionally enable extension_eval (runs code in a context; writes a 0600 session token)"
+                description: "Enable extension_eval (runs code in a context; writes a 0600 session token). Implies allowControl, so a single allowEval: true also unlocks storage/reload/open/dom_inspect — you do not need to pass both."
             }
         },
         required: [
@@ -779,6 +843,7 @@ const dev_schema = {
 };
 async function dev_handler(args) {
     const browser = args.browser ?? "chrome";
+    const allowControl = Boolean(args.allowControl || args.allowEval);
     const cliArgs = [
         "dev",
         args.projectPath,
@@ -789,7 +854,7 @@ async function dev_handler(args) {
     if (args.noBrowser) cliArgs.push("--no-browser");
     if (false === args.polyfill) cliArgs.push("--polyfill", "false");
     cliArgs.push(...launchFlagArgs(args));
-    if (args.allowControl) cliArgs.push("--allow-control");
+    if (allowControl) cliArgs.push("--allow-control");
     if (args.allowEval) cliArgs.push("--allow-eval");
     const child = spawnExtensionCli(cliArgs, {
         projectDir: args.projectPath
@@ -812,13 +877,20 @@ async function dev_handler(args) {
     await new Promise((resolve)=>setTimeout(resolve, 3000));
     child.stdout?.off("data", collector);
     child.stderr?.off("data", collector);
+    const controlVerbs = "storage, reload, open, dom_inspect";
+    const capabilities = {
+        allowControl,
+        allowEval: Boolean(args.allowEval),
+        unlocked: allowControl ? args.allowEval ? `${controlVerbs}, eval` : controlVerbs : "none (read-only: logs, source_inspect, wait, doctor)"
+    };
     return JSON.stringify({
         pid,
         browser,
         port: args.port ?? 8080,
         projectPath: args.projectPath,
         status: "started",
-        hint: "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. When you are done, call extension_stop to shut down the dev server and browser.",
+        capabilities,
+        hint: "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. " + (allowControl ? `Control channel is ON: extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : "Control channel is OFF: extension_storage/reload/open/dom_inspect need allowControl: true, and extension_eval needs allowEval: true (which also implies allowControl). Restart extension_dev with the flag you need.") + " When you are done, call extension_stop to shut down the dev server and browser.",
         earlyOutput: denoiseEarlyOutput(earlyOutput).slice(0, 500)
     });
 }
@@ -1003,6 +1075,73 @@ async function preview_handler(args) {
         hint: "Call extension_stop when you are done to close the preview browser."
     });
 }
+function contractSightings(projectPath) {
+    const root = node_path.resolve(projectPath, "dist", "extension-js");
+    let dirs;
+    try {
+        dirs = node_fs.readdirSync(root);
+    } catch  {
+        return [];
+    }
+    const sightings = [];
+    for (const dir of dirs){
+        const readyPath = node_path.join(root, dir, "ready.json");
+        try {
+            const stat = node_fs.statSync(readyPath);
+            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
+            if (contract?.status !== "ready") continue;
+            sightings.push({
+                browser: dir,
+                mtimeMs: stat.mtimeMs,
+                pid: "number" == typeof contract.pid ? contract.pid : void 0
+            });
+        } catch  {}
+    }
+    return sightings;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function knownSessionBrowsers(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const browsers = [];
+    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) browsers.push(session.browser);
+    for (const sighting of contractSightings(projectPath))if (void 0 === sighting.pid || pidAlive(sighting.pid)) browsers.push(sighting.browser);
+    return Array.from(new Set(browsers));
+}
+function deadReadySession(projectPath) {
+    for (const sighting of contractSightings(projectPath))if (void 0 !== sighting.pid && !pidAlive(sighting.pid)) return {
+        browser: sighting.browser,
+        pid: sighting.pid
+    };
+    return null;
+}
+function resolveSessionBrowser(projectPath, explicit, fallback = "chromium") {
+    if (explicit) return {
+        browser: explicit,
+        source: "explicit"
+    };
+    const resolved = node_path.resolve(projectPath);
+    const mine = listSessions().filter((s)=>node_path.resolve(s.projectPath) === resolved);
+    if (mine.length > 0) return {
+        browser: mine[mine.length - 1].browser,
+        source: "session"
+    };
+    const sightings = contractSightings(projectPath).filter((s)=>void 0 === s.pid || pidAlive(s.pid)).sort((a, b)=>b.mtimeMs - a.mtimeMs);
+    if (sightings.length > 0) return {
+        browser: sightings[0].browser,
+        source: "contract"
+    };
+    return {
+        browser: fallback,
+        source: "fallback"
+    };
+}
 const stop_schema = {
     name: "extension_stop",
     description: "Stop a running dev, start, or preview session: terminates the dev server and the browser it launched. Counterpart to extension_dev/extension_start. Call it when you are done verifying so sessions do not accumulate.",
@@ -1015,8 +1154,7 @@ const stop_schema = {
             },
             browser: {
                 type: "string",
-                default: "chrome",
-                description: "Browser of the session to stop (matches the browser passed to extension_dev/extension_start)"
+                description: "Browser of the session to stop (matches the browser passed to extension_dev/extension_start). Defaults to the one live session for this project when omitted, instead of assuming chrome."
             },
             all: {
                 type: "boolean",
@@ -1027,6 +1165,37 @@ const stop_schema = {
         required: []
     }
 };
+function pgrepPids(pattern) {
+    try {
+        const out = execFileSync("pgrep", [
+            "-f",
+            pattern
+        ], {
+            encoding: "utf8"
+        });
+        return out.split("\n").map((s)=>parseInt(s.trim(), 10)).filter((n)=>Number.isInteger(n) && n > 0 && n !== process.pid);
+    } catch  {
+        return [];
+    }
+}
+function sessionProcessPids(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const pids = new Set();
+    for (const marker of [
+        `extension dev ${resolved}`,
+        node_path.join(resolved, "dist")
+    ])for (const pid of pgrepPids(marker))pids.add(pid);
+    return [
+        ...pids
+    ];
+}
+function reapSessionProcesses(projectPath) {
+    const pids = sessionProcessPids(projectPath);
+    for (const pid of pids)try {
+        process.kill(pid, "SIGKILL");
+    } catch  {}
+    return pids;
+}
 function isAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -1063,13 +1232,17 @@ function pidFromReadyContract(projectPath, browser) {
 async function stopOne(projectPath, browser) {
     const session = getSession(projectPath, browser);
     const pid = session?.pid ?? pidFromReadyContract(projectPath, browser);
-    if (null == pid) return {
-        projectPath,
-        browser,
-        pid: null,
-        stopped: false,
-        detail: "No known session for this project/browser (nothing registered in this server and no ready.json contract found)."
-    };
+    if (null == pid) {
+        const reaped = reapSessionProcesses(projectPath);
+        return {
+            projectPath,
+            browser,
+            pid: null,
+            stopped: 0 !== reaped.length,
+            reaped,
+            detail: 0 === reaped.length ? "No known session for this project/browser (nothing registered in this server and no ready.json contract found)." : `No dev pid on record, but reaped ${reaped.length} orphaned browser process(es) from the profile dir.`
+        };
+    }
     let detail;
     if (isAlive(pid)) {
         signal(pid, "SIGTERM");
@@ -1080,17 +1253,23 @@ async function stopOne(projectPath, browser) {
         }
         detail = isAlive(pid) ? "Sent SIGTERM and SIGKILL but the process still reports alive; it may be exiting." : "Terminated.";
     } else detail = "Process was already gone; cleaned up session records.";
+    const reaped = reapSessionProcesses(projectPath);
     removeSession(projectPath, browser);
     try {
         node_fs.rmSync(readyJsonPath(projectPath, browser), {
             force: true
         });
     } catch  {}
+    const survivors = sessionProcessPids(projectPath);
+    const stopped = !isAlive(pid) && 0 === survivors.length;
+    if (survivors.length) detail += ` Warning: ${survivors.length} browser process(es) still alive after reap (pids ${survivors.join(", ")}).`;
+    else if (reaped.length) detail += ` Reaped ${reaped.length} browser process(es).`;
     return {
         projectPath,
         browser,
         pid,
-        stopped: !isAlive(pid),
+        stopped,
+        reaped,
         detail
     };
 }
@@ -1110,7 +1289,8 @@ async function stop_handler(args) {
     if (!args.projectPath) return JSON.stringify({
         error: "projectPath is required unless all=true. Pass the same projectPath used with extension_dev/extension_start."
     });
-    const outcome = await stopOne(args.projectPath, args.browser ?? "chrome");
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    const outcome = await stopOne(args.projectPath, browser);
     return JSON.stringify(outcome);
 }
 const RAW_BASE = "https://raw.githubusercontent.com/extension-js/examples/main/examples";
@@ -1298,7 +1478,11 @@ const manifest_validate_schema = {
         properties: {
             manifestPath: {
                 type: "string",
-                description: "Path to manifest.json"
+                description: "Path to manifest.json. Or pass projectPath and the manifest is located for you."
+            },
+            projectPath: {
+                type: "string",
+                description: "Path to the extension project root; manifest.json is resolved from it (root or src/). Accepted in place of manifestPath."
             },
             browsers: {
                 type: "array",
@@ -1310,14 +1494,154 @@ const manifest_validate_schema = {
                     "firefox"
                 ],
                 description: "Browsers to validate against"
+            },
+            browser: {
+                type: "string",
+                description: "Single browser to validate against; alias for browsers:[browser] to match the other tools."
             }
         },
-        required: [
-            "manifestPath"
-        ]
+        required: []
+    }
+};
+function collectPathRefs(m) {
+    const refs = [];
+    const push = (v)=>{
+        if ("string" == typeof v) refs.push(v);
+    };
+    const action = m.action || m.browser_action;
+    if (action) {
+        push(action.default_popup);
+        if ("string" == typeof action.default_icon) push(action.default_icon);
+        else if (action.default_icon) Object.values(action.default_icon).forEach(push);
+    }
+    const bg = m.background;
+    if (bg) {
+        push(bg.service_worker);
+        push(bg.page);
+        if (Array.isArray(bg.scripts)) bg.scripts.forEach(push);
     }
+    if (m.icons) Object.values(m.icons).forEach(push);
+    const cs = m.content_scripts;
+    if (Array.isArray(cs)) for (const c of cs){
+        if (Array.isArray(c.js)) c.js.forEach(push);
+        if (Array.isArray(c.css)) c.css.forEach(push);
+    }
+    push(m.options_page);
+    const oui = m.options_ui;
+    if (oui) push(oui.page);
+    const sp = m.side_panel;
+    if (sp) push(sp.default_path);
+    const sa = m.sidebar_action;
+    if (sa) push(sa.default_panel);
+    const cuo = m.chrome_url_overrides;
+    if (cuo) Object.values(cuo).forEach(push);
+    return refs;
+}
+function fileResolvesSomewhere(ref, roots) {
+    if (!ref || ref.includes("*") || /^(https?:|data:)/i.test(ref)) return true;
+    const clean = ref.replace(/^\.?\//, "");
+    return roots.some((root)=>{
+        try {
+            return node_fs.existsSync(node_path.resolve(root, clean));
+        } catch  {
+            return false;
+        }
+    });
+}
+function findManifest(projectPath) {
+    for (const rel of [
+        "manifest.json",
+        node_path.join("src", "manifest.json")
+    ]){
+        const candidate = node_path.resolve(projectPath, rel);
+        if (node_fs.existsSync(candidate)) return candidate;
+    }
+    return null;
+}
+const API_PERMISSION = {
+    storage: "storage",
+    webNavigation: "webNavigation",
+    history: "history",
+    cookies: "cookies",
+    bookmarks: "bookmarks",
+    alarms: "alarms",
+    contextMenus: "contextMenus",
+    notifications: "notifications",
+    downloads: "downloads",
+    webRequest: "webRequest",
+    tabGroups: "tabGroups",
+    topSites: "topSites",
+    idle: "idle",
+    management: "management",
+    scripting: "scripting",
+    declarativeNetRequest: "declarativeNetRequest",
+    sessions: "sessions",
+    proxy: "proxy",
+    tts: "tts",
+    pageCapture: "pageCapture",
+    desktopCapture: "desktopCapture",
+    debugger: "debugger",
+    geolocation: "geolocation"
 };
+const HARD_APIS = new Set([
+    "history",
+    "cookies",
+    "bookmarks",
+    "webNavigation",
+    "downloads",
+    "webRequest",
+    "topSites",
+    "management",
+    "tabGroups",
+    "sessions",
+    "proxy",
+    "debugger",
+    "pageCapture",
+    "desktopCapture"
+]);
+function scanApiUsage(roots) {
+    const used = new Set();
+    let filesRead = 0;
+    const walk = (dir, depth)=>{
+        if (depth > 6 || filesRead > 300) return;
+        let entries;
+        try {
+            entries = node_fs.readdirSync(dir, {
+                withFileTypes: true
+            });
+        } catch  {
+            return;
+        }
+        for (const e of entries){
+            if ("node_modules" === e.name || "dist" === e.name || e.name.startsWith(".")) continue;
+            const full = node_path.join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(full, depth + 1);
+                continue;
+            }
+            if (!/\.(js|mjs|cjs|ts|tsx|jsx|svelte|vue)$/.test(e.name)) continue;
+            if (filesRead++ > 300) return;
+            let src;
+            try {
+                src = node_fs.readFileSync(full, "utf8");
+            } catch  {
+                continue;
+            }
+            const re = /\b(?:chrome|browser)\.(\w+)/g;
+            let m;
+            while(m = re.exec(src))if (API_PERMISSION[m[1]]) used.add(m[1]);
+        }
+    };
+    for (const root of new Set(roots))walk(root, 0);
+    return used;
+}
 async function manifest_validate_handler(args) {
+    if (!args.browsers && "string" == typeof args.browser) args = {
+        ...args,
+        browsers: [
+            args.browser
+        ]
+    };
     const browsers = args.browsers ?? [
         "chrome",
         "firefox"
@@ -1329,9 +1653,20 @@ async function manifest_validate_handler(args) {
         browserSupport: {},
         similarTemplates: []
     };
+    const manifestPath = args.manifestPath ?? (args.projectPath ? findManifest(args.projectPath) : null);
+    if (!manifestPath) return JSON.stringify({
+        valid: false,
+        errors: [
+            args.projectPath ? `No manifest.json found under ${args.projectPath} (looked in the root and src/).` : "Pass manifestPath (path to manifest.json) or projectPath (project root)."
+        ],
+        warnings: [],
+        browserSupport: {},
+        similarTemplates: []
+    });
+    const manifestDir = node_path.dirname(node_path.resolve(manifestPath));
     let manifest;
     try {
-        const raw = node_fs.readFileSync(node_path.resolve(args.manifestPath), "utf8");
+        const raw = node_fs.readFileSync(node_path.resolve(manifestPath), "utf8");
         manifest = JSON.parse(raw);
     } catch (err) {
         return JSON.stringify({
@@ -1347,6 +1682,25 @@ async function manifest_validate_handler(args) {
     if (!manifest.name) result.errors.push("Missing required field: name");
     if (!manifest.version) result.warnings.push("Missing field: version (required for store submission)");
     const chromiumManifest = filterKeysForThisBrowser(manifest, "chrome");
+    const roots = [
+        manifestDir,
+        node_path.join(manifestDir, "src"),
+        ..."src" === node_path.basename(manifestDir) ? [
+            node_path.dirname(manifestDir)
+        ] : []
+    ];
+    for (const ref of new Set(collectPathRefs(chromiumManifest)))if (!fileResolvesSomewhere(ref, roots)) result.warnings.push(`Referenced file "${ref}" was not found near the manifest — this is the kind of dangling reference extension_build fails on. Verify with extension_build.`);
+    const declaredPermSet = new Set([
+        ...chromiumManifest.permissions ?? [],
+        ...chromiumManifest.optional_permissions ?? []
+    ].filter((p)=>"string" == typeof p));
+    for (const api of scanApiUsage(roots)){
+        const perm = API_PERMISSION[api];
+        if (declaredPermSet.has(perm)) continue;
+        const base = `Code calls chrome.${api} but "${perm}" is not in permissions`;
+        if (HARD_APIS.has(api)) result.errors.push(`${base} — chrome.${api} is undefined without it and will crash the context at runtime.`);
+        else result.warnings.push(`${base}; it may be undefined at runtime — add "${perm}" if you use it.`);
+    }
     if (!chromiumManifest.manifest_version) result.errors.push('Missing manifest_version. Use "chromium:manifest_version": 3 and "firefox:manifest_version": 2 for cross-browser support.');
     const declaredPerms = [
         ...chromiumManifest.permissions ?? [],
@@ -1405,8 +1759,11 @@ async function manifest_validate_handler(args) {
                 surfaces: t.surfaces
             }));
     } catch  {}
-    if (0 === result.errors.length) result.valid = Object.values(result.browserSupport).every((b)=>b.supported);
-    return JSON.stringify(result);
+    result.valid = 0 === result.errors.length && Object.values(result.browserSupport).every((b)=>b.supported);
+    return JSON.stringify({
+        ...result,
+        buildBlocking: result.errors.length > 0
+    });
 }
 const inspect_schema = {
     name: "extension_inspect",
@@ -1525,9 +1882,46 @@ async function inspect_handler(args) {
     const sourcemapSize = byType.sourcemap?.size ?? 0;
     const buildType = sourcemapSize > 0 ? "development" : "production";
     const shippableSize = totalSize - sourcemapSize;
+    const sizeByPath = new Map(files.map((f)=>[
+            f.path,
+            f.size
+        ]));
+    const entrypoints = [];
+    const addEntry = (role, ref)=>{
+        if ("string" != typeof ref) return;
+        const size = sizeByPath.get(ref.replace(/^\.?\//, ""));
+        entrypoints.push({
+            role,
+            path: ref,
+            present: void 0 !== size,
+            ...void 0 !== size ? {
+                sizeFormatted: formatBytes(size)
+            } : {}
+        });
+    };
+    const bg = manifest.background;
+    if (bg?.service_worker) addEntry("background.service_worker", bg.service_worker);
+    if (Array.isArray(bg?.scripts)) bg.scripts.forEach((s)=>addEntry("background.scripts", s));
+    const actionField = manifest.action || manifest.browser_action;
+    if (actionField?.default_popup) addEntry("action.default_popup", actionField.default_popup);
+    const contentScripts = manifest.content_scripts;
+    if (Array.isArray(contentScripts)) contentScripts.forEach((c, i)=>{
+        if (Array.isArray(c.js)) c.js.forEach((j)=>addEntry(`content_scripts[${i}].js`, j));
+        if (Array.isArray(c.css)) c.css.forEach((s)=>addEntry(`content_scripts[${i}].css`, s));
+    });
+    const PROMO_RE = /(screenshot|promo|marquee|tile|banner|preview)[-_.]?\d*\.(png|jpe?g|webp|gif)$/i;
+    const sizeWarnings = [];
+    for (const f of files)if ("sourcemap" !== f.type) {
+        if (PROMO_RE.test(f.path)) sizeWarnings.push(`${f.path} (${formatBytes(f.size)}) looks like a store-listing promo image shipped inside the extension package — move it out of the bundled sources so it does not inflate the store zip.`);
+        else if ("image" === f.type && !f.path.includes("icon") && f.size > 51200 && shippableSize > 0 && f.size / shippableSize > 0.25) sizeWarnings.push(`${f.path} (${formatBytes(f.size)}) is ${Math.round(f.size / shippableSize * 100)}% of the shipped bundle — unusually large for a shipped asset.`);
+    }
     const result = {
         browser,
         distPath,
+        entrypoints,
+        ...sizeWarnings.length ? {
+            sizeWarnings
+        } : {},
         buildType,
         totalSize,
         totalSizeFormatted: formatBytes(totalSize),
@@ -1567,6 +1961,7 @@ async function inspect_handler(args) {
             hasManifest: node_fs.existsSync(manifestPath),
             hasIcons: files.some((f)=>"image" === f.type && f.path.includes("icon")),
             noSourceMaps: !files.some((f)=>"sourcemap" === f.type),
+            noPromoAssets: !files.some((f)=>PROMO_RE.test(f.path)),
             under10MB: totalSize < 10485760
         }
     };
@@ -2027,66 +2422,6 @@ function isCdpEndpoint(port) {
         });
     });
 }
-function contractSightings(projectPath) {
-    const root = node_path.resolve(projectPath, "dist", "extension-js");
-    let dirs;
-    try {
-        dirs = node_fs.readdirSync(root);
-    } catch  {
-        return [];
-    }
-    const sightings = [];
-    for (const dir of dirs){
-        const readyPath = node_path.join(root, dir, "ready.json");
-        try {
-            const stat = node_fs.statSync(readyPath);
-            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-            if (contract?.status !== "ready") continue;
-            sightings.push({
-                browser: dir,
-                mtimeMs: stat.mtimeMs,
-                pid: "number" == typeof contract.pid ? contract.pid : void 0
-            });
-        } catch  {}
-    }
-    return sightings;
-}
-function pidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    } catch  {
-        return false;
-    }
-}
-function knownSessionBrowsers(projectPath) {
-    const resolved = node_path.resolve(projectPath);
-    const browsers = [];
-    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) browsers.push(session.browser);
-    for (const sighting of contractSightings(projectPath))if (void 0 === sighting.pid || pidAlive(sighting.pid)) browsers.push(sighting.browser);
-    return Array.from(new Set(browsers));
-}
-function resolveSessionBrowser(projectPath, explicit, fallback = "chromium") {
-    if (explicit) return {
-        browser: explicit,
-        source: "explicit"
-    };
-    const resolved = node_path.resolve(projectPath);
-    const mine = listSessions().filter((s)=>node_path.resolve(s.projectPath) === resolved);
-    if (mine.length > 0) return {
-        browser: mine[mine.length - 1].browser,
-        source: "session"
-    };
-    const sightings = contractSightings(projectPath).filter((s)=>void 0 === s.pid || pidAlive(s.pid)).sort((a, b)=>b.mtimeMs - a.mtimeMs);
-    if (sightings.length > 0) return {
-        browser: sightings[0].browser,
-        source: "contract"
-    };
-    return {
-        browser: fallback,
-        source: "fallback"
-    };
-}
 const source_inspect_schema = {
     name: "extension_source_inspect",
     description: "Inspect a running extension's live state via Chrome DevTools Protocol: full HTML (with shadow DOM), DOM structure, content script injection, console messages, and CSS selector queries. Requires an active dev or start session.",
@@ -2157,8 +2492,8 @@ async function source_inspect_handler(args) {
     ]);
     const maxBytes = args.maxBytes ?? 262144;
     if (!isChromiumFamily(browser)) return JSON.stringify({
-        error: `Source inspection for ${browser} uses RDP (Remote Debug Protocol). Currently only Chromium CDP is supported.`,
-        hint: 'Pass browser: "chrome" (against a Chromium-family dev session).'
+        error: `Source inspection reads the live DOM over Chrome DevTools Protocol, which ${browser} (Gecko) does not expose. This is a capability limit, not a missing session.`,
+        hint: `For the ${browser} session, read runtime state with extension_logs, or extension_eval (context: "content"/"page") which works against Firefox over the control channel. To get CDP DOM inspection, run a Chromium-family dev session (extension_dev with browser: "chrome") in parallel.`
     });
     const resolved = await resolveCdpPort(args.projectPath, browser);
     if (!resolved) return JSON.stringify({
@@ -2634,10 +2969,13 @@ async function logs_handler(args) {
     return readFromFile(args, browser, limit);
 }
 function toMcpSpeak(text) {
-    return text.replace(/`?extension dev(?: [^\s`]*)? --browser[= ]([\w-]+) --allow-control`?/g, 'extension_dev with { browser: "$1", allowControl: true }').replace(/--allow-control/g, "allowControl: true (extension_dev)").replace(/--allow-eval/g, "allowEval: true (extension_dev)").replace(/--browser[= ]([\w-]+)/g, 'browser: "$1"').replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev");
+    return text.replace(/`?extension dev(?: [^\s`]*)? --browser[= ]([\w-]+) --allow-control`?/g, 'extension_dev with { browser: "$1", allowControl: true }').replace(/--allow-control/g, "allowControl: true (extension_dev)").replace(/--allow-eval/g, "allowEval: true (extension_dev)").replace(/--context[= ]([\w-]+)/g, 'context: "$1"').replace(/--tab[= ](\d+)/g, "tab: $1").replace(/--url[= ](\S+)/g, 'url: "$1"').replace(/--browser[= ]([\w-]+)/g, 'browser: "$1"').replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev");
 }
 function withSessionContext(message, projectPath) {
-    if (!/no active control channel/i.test(message)) return message;
+    const isControlError = /no active control channel|control channel refused|\b1006\b|no executor connected|is the session started with allowControl/i.test(message);
+    if (!isControlError) return message;
+    const dead = deadReadySession(projectPath);
+    if (dead) return `${message}\nLikely cause: the dev server has exited — ${dead.browser} ready.json still says ready but its pid ${dead.pid} is dead. Restart with extension_dev (this is not an allowControl problem); extension_doctor confirms.`;
     const running = knownSessionBrowsers(projectPath);
     if (0 === running.length) return message;
     return `${message} Active session browser(s) for this project: ${running.join(", ")} — pass that as \`browser\`, or restart it via extension_dev with allowControl: true if the control channel is off.`;
@@ -2878,6 +3216,64 @@ async function reload_handler(args) {
         })
     ], args.projectPath, args.timeout);
 }
+async function navigateToUrl(projectPath, browser, url) {
+    if (!isChromiumFamily(browser)) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "Unsupported",
+            message: `URL navigation drives a tab over Chrome DevTools Protocol, which ${browser} (Gecko) does not expose. On Firefox, drive the page via extension_eval (context: "page"/"content") or read extension_logs.`
+        }
+    });
+    const resolved = await resolveCdpPort(projectPath, browser);
+    if (!resolved) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "NoSession",
+            message: `No active dev session / CDP port for ${browser}. Start extension_dev and extension_wait for ready. ${CDP_PORT_MISSING_HINT}`
+        }
+    });
+    const cdp = new CDPClient();
+    try {
+        const targets = await CDPClient.discoverTargets(resolved.port);
+        const pageTargets = targets.filter((t)=>"page" === t.type && !String(t.url || "").startsWith("devtools://"));
+        if (0 === pageTargets.length) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NoTab",
+                message: "The dev browser has no open page tab to navigate. Trigger one (e.g. extension_open surface, or open the extension) first."
+            }
+        });
+        const target = pageTargets[0];
+        const browserWsUrl = await CDPClient.discoverBrowserWsUrl(resolved.port);
+        await cdp.connect(browserWsUrl);
+        const sessionId = await cdp.attachToTarget(String(target.id));
+        await cdp.navigate(sessionId, url);
+        await new Promise((r)=>setTimeout(r, 1200));
+        const meta = await cdp.getPageMeta(sessionId).catch(()=>({}));
+        return JSON.stringify({
+            ok: true,
+            navigated: url,
+            tab: {
+                id: target.id,
+                title: meta.title,
+                url: meta.url || url
+            },
+            hint: "Inspect it with extension_dom_inspect or extension_source_inspect (context: 'page')."
+        });
+    } catch (e) {
+        return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NavigateError",
+                message: e instanceof Error ? e.message : String(e)
+            }
+        });
+    } finally{
+        try {
+            cdp.disconnect();
+        } catch  {}
+    }
+}
 const open_schema = {
     name: "extension_open",
     description: "Open an extension surface or replay an event in a running session. 'popup'/'options'/'sidebar' open UI surfaces. 'action' triggers the toolbar action: opens the action's popup, or (no popup) replays chrome.action.onClicked. 'command' replays a chrome.commands.onCommand keyboard shortcut (pass `name`). NOTE: action/command replay invokes your listener WITHOUT a user gesture, so the gesture-derived activeTab grant does not apply (the result includes gesture:false and a warning when activeTab is declared). Requires the dev session to be started with allowControl: true (extension_dev). Wraps `extension open`.",
@@ -2903,6 +3299,10 @@ const open_schema = {
                 type: "string",
                 description: "For surface 'command': the chrome.commands name to trigger."
             },
+            url: {
+                type: "string",
+                description: "Navigate a real tab to this URL (Chromium only, via CDP) instead of opening a surface. Use for content-script/webNavigation test pages, or the popup as a page: chrome-extension://<id>/popup.html. Alternative to `surface`."
+            },
             browser: {
                 type: "string",
                 description: "Browser session to target. Defaults to the active dev session's browser for this project."
@@ -2913,13 +3313,20 @@ const open_schema = {
             }
         },
         required: [
-            "projectPath",
-            "surface"
+            "projectPath"
         ]
     }
 };
 async function open_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    if (args.url) return navigateToUrl(args.projectPath, browser, args.url);
+    if (!args.surface) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "BadRequest",
+            message: "Pass `surface` (popup/options/sidebar/action/command) to open a surface, or `url` to navigate a tab."
+        }
+    });
     const cli = [
         "open",
         args.surface,
@@ -3526,6 +3933,14 @@ async function deploy_handler(args) {
     });
 }
 const SAFE_CEILING_MS = 50000;
+function wait_isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch  {
+        return false;
+    }
+}
 const wait_schema = {
     name: "extension_wait",
     description: "Wait for a running dev or start session to be ready. Polls the ready.json contract file and returns structured status. A single call is bounded to ~50s to stay under the MCP client request timeout; if it returns status:'timeout', call it again to keep waiting (polling resumes on the same contract).",
@@ -3563,18 +3978,27 @@ async function wait_handler(args) {
         try {
             const raw = node_fs.readFileSync(readyPath, "utf8");
             const contract = JSON.parse(raw);
-            if ("ready" === contract.status) return JSON.stringify({
-                status: "ready",
-                command: contract.command,
-                browser: contract.browser,
-                port: contract.port,
-                pid: contract.pid,
-                distPath: contract.distPath,
-                manifestPath: contract.manifestPath,
-                compiledAt: contract.compiledAt,
-                startedAt: contract.startedAt,
-                waitDuration: Date.now() - start
-            });
+            if ("ready" === contract.status) {
+                if ("number" == typeof contract.pid && !wait_isAlive(contract.pid)) return JSON.stringify({
+                    status: "stale",
+                    message: `ready.json reports ready but its dev-server pid ${contract.pid} is dead — the session exited. Restart with extension_dev; extension_doctor will confirm.`,
+                    browser: contract.browser,
+                    pid: contract.pid,
+                    waitDuration: Date.now() - start
+                });
+                return JSON.stringify({
+                    status: "ready",
+                    command: contract.command,
+                    browser: contract.browser,
+                    port: contract.port,
+                    pid: contract.pid,
+                    distPath: contract.distPath,
+                    manifestPath: contract.manifestPath,
+                    compiledAt: contract.compiledAt,
+                    startedAt: contract.startedAt,
+                    waitDuration: Date.now() - start
+                });
+            }
             if ("error" === contract.status) return JSON.stringify({
                 status: "error",
                 message: contract.message,
@@ -4711,6 +5135,14 @@ async function detect_browsers_handler(args) {
         hint: missing.length ? `Missing browser(s): ${missing.map((d)=>d.browser).join(", ")}.${missing.some((d)=>MANAGED_INSTALLABLE.has(d.browser)) ? ` Use extension_install_browser to install ${missing.filter((d)=>MANAGED_INSTALLABLE.has(d.browser)).map((d)=>d.browser).join(", ")}.` : ""}` : "All requested browsers are available."
     });
 }
+function doctor_readReadyContract(projectPath, browser) {
+    try {
+        const raw = node_fs.readFileSync(node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json"), "utf8");
+        return JSON.parse(raw);
+    } catch  {
+        return null;
+    }
+}
 const doctor_schema = {
     name: "extension_doctor",
     description: "Diagnose a dev session end-to-end: ready contract, dev-server process, control-port agreement, control channel, eval token, executor, and browser liveness. Returns one {check, status, detail, remediation?} entry per leg in dependency order — a 'skip' names the check that blocked it and is NOT a pass. Run this first when any act tool (storage/reload/eval/open) errors unexpectedly. Wraps `extension doctor`. Call with no projectPath for a pre-flight environment check (node, extension CLI, template cache) before any project exists.",
@@ -4764,6 +5196,37 @@ async function environmentPreflight() {
         hint: "Pass projectPath to diagnose a live dev session end-to-end."
     });
 }
+function recentErrorLogs(projectPath, browser, max = 5) {
+    const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "logs.ndjson");
+    let lines;
+    try {
+        lines = node_fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+    } catch  {
+        return [];
+    }
+    const errs = [];
+    for (const line of lines){
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        } catch  {
+            continue;
+        }
+        if (ev && "error" === ev.level) {
+            const msg = Array.isArray(ev.args) ? ev.args.join(" ") : ev.message || ev.text || "";
+            if (msg) errs.push(String(msg).slice(0, 300));
+        }
+    }
+    return errs.slice(-max);
+}
+function projectEngineVersion(projectPath) {
+    try {
+        const p = node_path.resolve(projectPath, "node_modules", "extension", "package.json");
+        return JSON.parse(node_fs.readFileSync(p, "utf8")).version || null;
+    } catch  {
+        return null;
+    }
+}
 async function doctor_handler(args) {
     if (!args.projectPath) return environmentPreflight();
     const projectPath = args.projectPath;
@@ -4786,9 +5249,48 @@ async function doctor_handler(args) {
             if ("string" == typeof check.detail) check.detail = toMcpSpeak(check.detail);
             if ("string" == typeof check.remediation) check.remediation = toMcpSpeak(check.remediation);
         }
+        let healthy = 0 === code;
+        const contract = doctor_readReadyContract(projectPath, browser);
+        if (contract?.status === "error") {
+            healthy = false;
+            const detail = contract.errors && contract.errors.length ? contract.errors.join("; ") : contract.message || "The dev session recorded status: error in ready.json.";
+            checks.push({
+                check: "runtime-errors",
+                status: "fail",
+                detail: toMcpSpeak(detail),
+                remediation: "The build or extension load failed. Fix the reported error, let the dev server recompile, then re-run doctor."
+            });
+        } else {
+            const errs = recentErrorLogs(projectPath, browser);
+            if (errs.length) {
+                healthy = false;
+                checks.push({
+                    check: "runtime-errors",
+                    status: "fail",
+                    detail: `Recent error-level logs: ${errs.join(" | ")}`,
+                    remediation: "The extension is throwing at runtime. Inspect with extension_logs; a missing permission for a called chrome.* API is a common cause (extension_manifest_validate now checks this)."
+                });
+            }
+        }
+        const engineVersion = projectEngineVersion(projectPath);
+        if (engineVersion) {
+            const pin = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
+            const mismatch = "" !== pin && "latest" !== pin && !engineVersion.includes(pin);
+            checks.push({
+                check: "project-engine",
+                status: mismatch ? "warn" : "pass",
+                detail: `project-local extension@${engineVersion}${mismatch ? ` — but EXTENSION_MCP_CLI_VERSION=${pin}; the dev loop uses the project bin, not the pin` : ""}`,
+                ...mismatch ? {
+                    remediation: `Run \`(cd ${projectPath} && npm i -D extension@${pin})\` to match the pinned engine.`
+                } : {}
+            });
+        }
         return JSON.stringify({
             browser,
-            healthy: 0 === code,
+            ...engineVersion ? {
+                engineVersion
+            } : {},
+            healthy,
             checks
         });
     } catch  {
@@ -4835,6 +5337,56 @@ function checkPrimitive(path, value, schema, issues) {
         });
     }
 }
+const ARG_ALIASES = {
+    projectPath: [
+        "path",
+        "dir",
+        "projectDir",
+        "cwd"
+    ],
+    projectName: [
+        "name"
+    ],
+    parentDir: [
+        "parent",
+        "into"
+    ],
+    slug: [
+        "template",
+        "templateSlug"
+    ],
+    expression: [
+        "code",
+        "js",
+        "script"
+    ],
+    manifestPath: [
+        "manifest"
+    ],
+    surface: [
+        "view",
+        "target"
+    ]
+};
+function normalizeArgAliases(inputSchema, args) {
+    const schema = inputSchema;
+    const props = schema.properties ?? {};
+    const out = {
+        ...args
+    };
+    for (const [canonical, aliases] of Object.entries(ARG_ALIASES))if (canonical in props) {
+        if (void 0 === out[canonical]) {
+            for (const alias of aliases)if (!(alias in props)) {
+                if (void 0 !== out[alias]) {
+                    out[canonical] = out[alias];
+                    delete out[alias];
+                    break;
+                }
+            }
+        }
+    }
+    return out;
+}
 function validateToolInput(inputSchema, args) {
     const schema = inputSchema;
     const issues = [];
@@ -4933,7 +5485,8 @@ async function startServer() {
             ],
             isError: true
         };
-        const issues = validateToolInput(tool.schema.inputSchema, args ?? {});
+        const normalizedArgs = normalizeArgAliases(tool.schema.inputSchema, args ?? {});
+        const issues = validateToolInput(tool.schema.inputSchema, normalizedArgs);
         if (issues.length) return {
             content: [
                 {
@@ -4944,7 +5497,7 @@ async function startServer() {
             isError: true
         };
         try {
-            const result = await tool.handler(args ?? {});
+            const result = await tool.handler(normalizedArgs);
             return {
                 content: [
                     {

package/dist/src/lib/session-browser.d.ts

@@ -3,4 +3,8 @@ export interface ResolvedBrowser {
     source: "explicit" | "session" | "contract" | "fallback";
 }
 export declare function knownSessionBrowsers(projectPath: string): string[];
+export declare function deadReadySession(projectPath: string): {
+    browser: string;
+    pid: number;
+} | null;
 export declare function resolveSessionBrowser(projectPath: string, explicit: string | undefined, fallback?: string): ResolvedBrowser;

package/dist/src/lib/validate-input.d.ts

@@ -2,5 +2,6 @@ export interface InputIssue {
     path: string;
     message: string;
 }
+export declare function normalizeArgAliases(inputSchema: Record<string, unknown>, args: Record<string, unknown>): Record<string, unknown>;
 export declare function validateToolInput(inputSchema: Record<string, unknown>, args: Record<string, unknown>): InputIssue[];
 export declare function inputValidationError(toolName: string, issues: InputIssue[]): string;

package/dist/src/tools/manifest-validate.d.ts

@@ -8,6 +8,10 @@ export declare const schema: {
                 type: string;
                 description: string;
             };
+            projectPath: {
+                type: string;
+                description: string;
+            };
             browsers: {
                 type: string;
                 items: {
@@ -16,11 +20,17 @@ export declare const schema: {
                 default: string[];
                 description: string;
             };
+            browser: {
+                type: string;
+                description: string;
+            };
         };
-        required: string[];
+        required: never[];
     };
 };
 export declare function handler(args: {
-    manifestPath: string;
+    manifestPath?: string;
+    projectPath?: string;
+    browser?: string;
     browsers?: string[];
 }): Promise<string>;

package/dist/src/tools/open.d.ts

@@ -18,6 +18,10 @@ export declare const schema: {
                 type: string;
                 description: string;
             };
+            url: {
+                type: string;
+                description: string;
+            };
             browser: {
                 type: string;
                 description: string;
@@ -31,6 +35,7 @@ export declare const schema: {
     };
 };
 export declare function handler(args: ActArgs & {
-    surface: string;
+    surface?: string;
     name?: string;
+    url?: string;
 }): Promise<string>;

package/dist/src/tools/stop.d.ts

@@ -10,7 +10,6 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
                 description: string;
             };
             all: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "4.7.0",
+  "version": "4.9.0",
   "description": "MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor, Copilot, Codex) build, run, inspect, and publish browser extensions. 31 tools for scaffolding, live DOM inspection, log streaming, and store-ready builds across Chrome, Edge, Firefox, Safari, and every Chromium- or Gecko-based browser (Brave, Opera, Vivaldi, Yandex, Waterfox, LibreWolf). Powered by extension.dev and Extension.js.",
   "mcpName": "io.github.extensiondev/mcp",
   "license": "MIT",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://extension.dev",
-  "version": "4.7.0",
+  "version": "4.9.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@extension.dev/mcp",
-      "version": "4.7.0",
+      "version": "4.9.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"