@extension.dev/mcp 4.8.0 → 5.1.0

package/dist/module.js

@@ -9,8 +9,9 @@ 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 ws_0 from "ws";
 import node_http from "node:http";
+import node_crypto from "node:crypto";
 import { extensionInstall, extensionUninstall, getManagedBrowsersCacheRoot } from "extension-install";
 import { promisify } from "node:util";
 var add_feature_namespaceObject = {};
@@ -53,6 +54,7 @@ var doctor_namespaceObject = {};
 __webpack_require__.r(doctor_namespaceObject);
 __webpack_require__.d(doctor_namespaceObject, {
     handler: ()=>doctor_handler,
+    recentErrorLogs: ()=>recentErrorLogs,
     schema: ()=>doctor_schema
 });
 var dom_inspect_namespaceObject = {};
@@ -130,6 +132,7 @@ __webpack_require__.d(manifest_validate_namespaceObject, {
 var open_namespaceObject = {};
 __webpack_require__.r(open_namespaceObject);
 __webpack_require__.d(open_namespaceObject, {
+    clampPopupBounds: ()=>clampPopupBounds,
     handler: ()=>open_handler,
     schema: ()=>open_schema
 });
@@ -199,7 +202,16 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"4.7.0","El":{"OP":"^4.0.11"}}');
+var package_namespaceObject = JSON.parse('{"rE":"4.9.0","El":{"OP":"^4.0.13"}}');
+function scaffoldEnginePin(projectPath) {
+    try {
+        const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
+        const spec = pkg?.devDependencies?.extension ?? pkg?.dependencies?.extension ?? null;
+        return "string" == typeof spec ? spec : null;
+    } catch  {
+        return null;
+    }
+}
 function detectPackageManager(projectPath) {
     const byLockfile = [
         [
@@ -238,7 +250,7 @@ const create_schema = {
             },
             parentDir: {
                 type: "string",
-                description: "Directory to create the project inside. Defaults to the MCP server's working directory, which may not be where you expect — pass this explicitly when you care where the project lands."
+                description: "Directory to create the project inside. Defaults to the MCP server's working directory, which may not be where you expect, pass this explicitly when you care where the project lands."
             },
             template: {
                 type: "string",
@@ -259,14 +271,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 +299,66 @@ 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 hasManifest = node_fs.existsSync(node_path.join(result.projectPath, "manifest.json")) || node_fs.existsSync(node_path.join(result.projectPath, "src", "manifest.json"));
+    if (!hasManifest) return JSON.stringify({
+        ok: false,
+        status: "incomplete",
+        projectPath: result.projectPath,
+        error: `The scaffold is incomplete: no manifest.json exists under ${result.projectPath} (checked the root and src/). Do not run extension_dev against it.`,
+        duration: Date.now() - start,
+        log: logTail(),
+        hint: "Delete the directory and retry extension_create; a template download interrupted mid-way can leave a partial tree."
+    });
+    const packageManager = result.packageManager || (result.depsInstalled ? detectPackageManager(result.projectPath) : "npm");
+    const runDev = `${packageManager} run dev`;
+    const addDev = (spec)=>"npm" === packageManager ? `npm i -D ${spec}` : "yarn" === packageManager ? `yarn add -D ${spec}` : `${packageManager} add -D ${spec}`;
+    const pin = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
+    const scaffoldPin = scaffoldEnginePin(result.projectPath);
+    const pinMatches = null !== scaffoldPin && "" !== pin && scaffoldPin.includes(pin);
+    const engineWarning = pin && "latest" !== pin && !pinMatches ? `The scaffold pins "extension": "${scaffoldPin ?? "unknown"}"; the project-local engine wins over EXTENSION_MCP_CLI_VERSION=${pin}. Run \`(cd ${result.projectPath} && ${addDev(`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}`,
+            `${packageManager} install`,
+            runDev
+        ],
+        ...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");
@@ -515,6 +572,9 @@ function runExtensionCli(args, options) {
 }
 function spawnExtensionCli(args, options) {
     const { command, prefixArgs } = resolveExtensionInvocation(options?.projectDir ?? options?.cwd);
+    const logDir = node_fs.mkdtempSync(node_path.join(node_os.tmpdir(), "extension-mcp-"));
+    const logPath = node_path.join(logDir, "session.log");
+    const fd = node_fs.openSync(logPath, "a");
     const child = cross_spawn(command, [
         ...prefixArgs,
         ...args
@@ -523,8 +583,8 @@ function spawnExtensionCli(args, options) {
         detached: true,
         stdio: [
             "ignore",
-            "pipe",
-            "pipe"
+            fd,
+            fd
         ],
         env: {
             ...process.env,
@@ -532,8 +592,74 @@ function spawnExtensionCli(args, options) {
             NO_COLOR: "1"
         }
     });
+    node_fs.closeSync(fd);
     child.unref();
-    return child;
+    return {
+        child,
+        logPath,
+        readOutput: ()=>{
+            try {
+                return node_fs.readFileSync(logPath, "utf8");
+            } catch  {
+                return "";
+            }
+        }
+    };
+}
+function readBuildSummary(projectPath, browser, since) {
+    const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "build-summary.json");
+    try {
+        const stat = node_fs.statSync(file);
+        if (stat.mtimeMs < since) return null;
+        const summary = JSON.parse(node_fs.readFileSync(file, "utf8"));
+        if (summary && "object" == typeof summary) return summary;
+    } catch  {}
+    return null;
+}
+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 (bg?.page) add("background.page", bg.page);
+    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 pageAction = manifest.page_action;
+    if (pageAction?.default_popup) add("page_action.default_popup", pageAction.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));
+    });
+    add("devtools_page", manifest.devtools_page);
+    add("options_page", manifest.options_page);
+    const optionsUi = manifest.options_ui;
+    if (optionsUi?.page) add("options_ui.page", optionsUi.page);
+    const sidePanel = manifest.side_panel;
+    if (sidePanel?.default_path) add("side_panel.default_path", sidePanel.default_path);
+    const sidebarAction = manifest.sidebar_action;
+    if (sidebarAction?.default_panel) add("sidebar_action.default_panel", sidebarAction.default_panel);
+    const overrides = manifest.chrome_url_overrides;
+    if (overrides) for (const [key, ref] of Object.entries(overrides))add(`chrome_url_overrides.${key}`, ref);
+    const dnr = manifest.declarative_net_request;
+    if (dnr && Array.isArray(dnr.rule_resources)) dnr.rule_resources.forEach((r, i)=>{
+        if (r && "object" == typeof r) add(`declarative_net_request[${i}].path`, r.path);
+    });
+    return out;
 }
 const build_schema = {
     name: "extension_build",
@@ -600,6 +726,11 @@ const build_schema = {
                 ],
                 default: "production",
                 description: "Bundler mode override (also sets NODE_ENV)"
+            },
+            skipValidation: {
+                type: "boolean",
+                default: false,
+                description: "Build even when extension_manifest_validate reports build-blocking errors. The build normally refuses, because a manifest error means the bundle it produces is broken in ways the bundler itself does not report."
             }
         },
         required: [
@@ -607,9 +738,67 @@ const build_schema = {
         ]
     }
 };
+function manifestDivergence(projectPath, browser) {
+    const read = (p)=>{
+        try {
+            return JSON.parse(node_fs.readFileSync(p, "utf8"));
+        } catch  {
+            return null;
+        }
+    };
+    const built = read(node_path.resolve(projectPath, "dist", browser, "manifest.json"));
+    const source = read(node_path.resolve(projectPath, "src", "manifest.json")) ?? read(node_path.resolve(projectPath, "manifest.json"));
+    if (!built || !source) return [];
+    const notes = [];
+    const listOf = (m, key)=>Array.isArray(m[key]) ? m[key].filter((x)=>"string" == typeof x) : [];
+    for (const key of [
+        "permissions",
+        "host_permissions",
+        "optional_permissions"
+    ]){
+        const lost = listOf(source, key).filter((p)=>!listOf(built, key).includes(p));
+        if (lost.length) notes.push(`The built manifest drops ${key}: ${lost.join(", ")}. The production build has narrower access than the source you tested in dev.`);
+    }
+    const sourceWar = source.web_accessible_resources;
+    const builtWar = built.web_accessible_resources;
+    if (Array.isArray(sourceWar) && sourceWar.length && !Array.isArray(builtWar)) notes.push("The built manifest has no web_accessible_resources although the source declares them. Anything injected into a page (scripting.insertCSS targets, injected scripts, images) will be blocked at runtime.");
+    return notes;
+}
+async function validationPreflight(projectPath, browser) {
+    try {
+        const manifestValidate = await Promise.resolve().then(()=>({
+                handler: manifest_validate_handler
+            }));
+        const parsed = JSON.parse(await manifestValidate.handler({
+            projectPath,
+            browsers: [
+                browser
+            ]
+        }));
+        return {
+            valid: Boolean(parsed.valid),
+            buildBlocking: Boolean(parsed.buildBlocking),
+            errors: Array.isArray(parsed.errors) ? parsed.errors : [],
+            warnings: Array.isArray(parsed.warnings) ? parsed.warnings : []
+        };
+    } catch  {
+        return null;
+    }
+}
 async function build_handler(args) {
     const start = Date.now();
     const browser = args.browser ?? "chrome";
+    const preflight = args.skipValidation ? null : await validationPreflight(args.projectPath, browser);
+    if (preflight?.buildBlocking) return JSON.stringify({
+        success: false,
+        status: "blocked",
+        browser,
+        error: "Build refused: the manifest has errors that produce a broken extension even when the bundler succeeds.",
+        errors: preflight.errors,
+        warnings: preflight.warnings,
+        duration: Date.now() - start,
+        hint: "Fix the errors above, then build again. Run extension_manifest_validate for the full report. To build anyway (for example to inspect the broken output), pass skipValidation: true."
+    });
     const cliArgs = [
         "build",
         args.projectPath,
@@ -632,6 +821,30 @@ 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 engineSummary = readBuildSummary(args.projectPath, browser, start);
+        const buildWarnings = engineSummary?.warnings?.length ? {
+            buildWarnings: engineSummary.warnings,
+            ..."number" == typeof engineSummary.warnings_count && engineSummary.warnings_count > engineSummary.warnings.length ? {
+                buildWarningsTruncated: engineSummary.warnings_count
+            } : {}
+        } : {};
+        const entrypoints = builtEntrypoints(node_path.resolve(args.projectPath, "dist", browser));
+        const missing = entrypoints.filter((e)=>!e.present);
+        if (missing.length) return JSON.stringify({
+            success: false,
+            status: "incomplete",
+            browser,
+            buildExitCode: 0,
+            error: `The build reported success but ${missing.length} declared entrypoint(s) are missing from dist/${browser}: ` + missing.map((m)=>`${m.role} -> ${m.path}`).join(", ") + ". The browser will refuse to load this build.",
+            entrypoints,
+            ...preflight?.warnings.length ? {
+                manifestWarnings: preflight.warnings
+            } : {},
+            ...buildWarnings,
+            duration,
+            output: lastLines(out, 12),
+            hint: "The bundler exited 0 but did not emit these files. Check that the manifest paths match what the build produces, and that nothing references a file outside the source tree."
+        });
         return JSON.stringify({
             success: true,
             browser,
@@ -641,6 +854,19 @@ async function build_handler(args) {
             ...status ? {
                 status
             } : {},
+            ...entrypoints.length ? {
+                entrypoints
+            } : {},
+            ...preflight?.warnings.length ? {
+                manifestWarnings: preflight.warnings
+            } : {},
+            ...buildWarnings,
+            ...(()=>{
+                const divergence = manifestDivergence(args.projectPath, browser);
+                return divergence.length ? {
+                    productionDivergence: divergence
+                } : {};
+            })(),
             zip: args.zip ?? false,
             duration,
             output: lastLines(out, 12)
@@ -769,7 +995,7 @@ const dev_schema = {
             allowEval: {
                 type: "boolean",
                 default: false,
-                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."
+                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: [
@@ -792,9 +1018,10 @@ async function dev_handler(args) {
     cliArgs.push(...launchFlagArgs(args));
     if (allowControl) cliArgs.push("--allow-control");
     if (args.allowEval) cliArgs.push("--allow-eval");
-    const child = spawnExtensionCli(cliArgs, {
+    const spawned = spawnExtensionCli(cliArgs, {
         projectDir: args.projectPath
     });
+    const { child, logPath } = spawned;
     const pid = child.pid;
     registerSession({
         pid,
@@ -804,15 +1031,37 @@ async function dev_handler(args) {
         command: "dev"
     });
     child.on("exit", ()=>removeSession(args.projectPath, browser));
-    let earlyOutput = "";
-    const collector = (data)=>{
-        earlyOutput += data.toString();
-    };
-    child.stdout?.on("data", collector);
-    child.stderr?.on("data", collector);
     await new Promise((resolve)=>setTimeout(resolve, 3000));
-    child.stdout?.off("data", collector);
-    child.stderr?.off("data", collector);
+    const earlyOutput = spawned.readOutput();
+    if (null !== child.exitCode || null !== child.signalCode) {
+        const code = child.exitCode;
+        const signal = child.signalCode;
+        return JSON.stringify({
+            ok: false,
+            status: "exited",
+            projectPath: args.projectPath,
+            browser,
+            pid,
+            exitCode: code,
+            signal,
+            error: `The dev server exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running, so extension_logs/wait/eval and the control verbs have nothing to attach to.`,
+            output: denoiseEarlyOutput(earlyOutput).slice(0, 2000),
+            logPath,
+            hint: "Read `output` above for the cause: a port already in use, a manifest the build rejects, or a missing browser binary are the common ones. Fix it and call extension_dev again; extension_doctor with this projectPath will also report what the last session recorded."
+        });
+    }
+    const compileFailed = /compiled with errors|✖✖✖|ERROR in |Module not found|NOT FOUND/i.test(earlyOutput);
+    if (compileFailed) return JSON.stringify({
+        ok: false,
+        status: "compile-failed",
+        projectPath: args.projectPath,
+        browser,
+        pid,
+        error: "The dev server started but the FIRST COMPILE FAILED, so the browser has nothing usable to load. The session is running; the extension is not.",
+        output: denoiseEarlyOutput(earlyOutput).slice(0, 2000),
+        logPath,
+        hint: "Fix the compile error in `output` above and save: the dev server is still running and will recompile. Do not call extension_wait yet, it will report ready for a build that failed."
+    });
     const controlVerbs = "storage, reload, open, dom_inspect";
     const capabilities = {
         allowControl,
@@ -820,6 +1069,7 @@ async function dev_handler(args) {
         unlocked: allowControl ? args.allowEval ? `${controlVerbs}, eval` : controlVerbs : "none (read-only: logs, source_inspect, wait, doctor)"
     };
     return JSON.stringify({
+        ok: true,
         pid,
         browser,
         port: args.port ?? 8080,
@@ -827,7 +1077,8 @@ async function dev_handler(args) {
         status: "started",
         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)
+        earlyOutput: denoiseEarlyOutput(earlyOutput).slice(0, 500),
+        logPath
     });
 }
 function denoiseEarlyOutput(raw) {
@@ -841,6 +1092,93 @@ function denoiseEarlyOutput(raw) {
     ];
     return raw.split("\n").filter((line)=>!NOISE.some((re)=>re.test(line.trim()))).join("\n").replace(/\n{2,}/g, "\n").trimStart();
 }
+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 browserExitStamp(projectPath, browser, since) {
+    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+    try {
+        const stat = node_fs.statSync(readyPath);
+        if (stat.mtimeMs < since) return null;
+        const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
+        const exited = contract?.code === "browser_exited" || contract?.browserExitCode !== void 0 || contract?.browserExitedAt !== void 0;
+        if (contract?.status === "error" && exited) return {
+            code: contract.code,
+            browserExitCode: contract.browserExitCode ?? null,
+            browserExitedAt: contract.browserExitedAt
+        };
+    } catch  {}
+    return null;
+}
+function resolveSessionBrowser(projectPath, explicit, fallback = "chrome") {
+    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).sort((a, b)=>b.mtimeMs - a.mtimeMs);
+    const live = sightings.filter((s)=>void 0 === s.pid || pidAlive(s.pid));
+    if (live.length > 0) return {
+        browser: live[0].browser,
+        source: "contract"
+    };
+    if (sightings.length > 0) return {
+        browser: sightings[0].browser,
+        source: "stale"
+    };
+    return {
+        browser: fallback,
+        source: "fallback"
+    };
+}
 const start_schema = {
     name: "extension_start",
     description: "Build the extension for production and immediately preview it in a browser. Combines build + preview in one step. No hot reload.",
@@ -905,9 +1243,11 @@ async function start_handler(args) {
     if (void 0 !== args.port) cliArgs.push("--port", String(args.port));
     if (args.noBrowser) cliArgs.push("--no-browser");
     cliArgs.push(...launchFlagArgs(args));
-    const child = spawnExtensionCli(cliArgs, {
+    const spawnedAt = Date.now();
+    const spawned = spawnExtensionCli(cliArgs, {
         projectDir: args.projectPath
     });
+    const { child, logPath } = spawned;
     const pid = child.pid;
     registerSession({
         pid,
@@ -916,22 +1256,47 @@ async function start_handler(args) {
         command: "start"
     });
     child.on("exit", ()=>removeSession(args.projectPath, browser));
-    let earlyOutput = "";
-    const collector = (data)=>{
-        earlyOutput += data.toString();
-    };
-    child.stdout?.on("data", collector);
-    child.stderr?.on("data", collector);
     await new Promise((resolve)=>setTimeout(resolve, 5000));
-    child.stdout?.off("data", collector);
-    child.stderr?.off("data", collector);
+    const earlyOutput = spawned.readOutput();
+    if (null !== child.exitCode || null !== child.signalCode) {
+        const code = child.exitCode;
+        const signal = child.signalCode;
+        return JSON.stringify({
+            ok: false,
+            status: "exited",
+            projectPath: args.projectPath,
+            browser,
+            pid,
+            exitCode: code,
+            signal,
+            error: `The preview server exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running.`,
+            output: earlyOutput.slice(0, 2000),
+            logPath,
+            hint: "Read `output` above for the cause: a failed production build, a port already in use, or a missing browser binary are the common ones. extension_build will surface a build error on its own."
+        });
+    }
+    const exitStamp = browserExitStamp(args.projectPath, browser, spawnedAt);
+    if (exitStamp) return JSON.stringify({
+        ok: false,
+        status: "browser-exited",
+        projectPath: args.projectPath,
+        browser,
+        pid,
+        ...exitStamp,
+        error: "The preview process is running but the browser it launched has exited (the extension may have been rejected or the browser crashed). The session cannot be driven.",
+        output: earlyOutput.slice(0, 2000),
+        logPath,
+        hint: "Read `output` above and extension_logs for the cause, then call extension_stop to clean up before retrying."
+    });
     return JSON.stringify({
+        ok: true,
         pid,
         browser,
         projectPath: args.projectPath,
         status: "started",
         hint: "Use extension_wait to check when the build and browser launch are complete. When you are done, call extension_stop to shut down the session.",
-        earlyOutput: earlyOutput.slice(0, 500)
+        earlyOutput: earlyOutput.slice(0, 500),
+        logPath
     });
 }
 const preview_schema = {
@@ -992,9 +1357,11 @@ async function preview_handler(args) {
     if (void 0 !== args.port) cliArgs.push("--port", String(args.port));
     if (args.noBrowser) cliArgs.push("--no-browser");
     cliArgs.push(...launchFlagArgs(args));
-    const child = spawnExtensionCli(cliArgs, {
+    const spawnedAt = Date.now();
+    const spawned = spawnExtensionCli(cliArgs, {
         projectDir: args.projectPath
     });
+    const { child, logPath } = spawned;
     const pid = child.pid;
     registerSession({
         pid,
@@ -1003,74 +1370,49 @@ async function preview_handler(args) {
         command: "preview"
     });
     child.on("exit", ()=>removeSession(args.projectPath, browser));
+    await new Promise((resolve)=>setTimeout(resolve, 5000));
+    const earlyOutput = spawned.readOutput();
+    if (null !== child.exitCode || null !== child.signalCode) {
+        const code = child.exitCode;
+        const signal = child.signalCode;
+        return JSON.stringify({
+            ok: false,
+            status: "exited",
+            projectPath: args.projectPath,
+            browser,
+            pid,
+            exitCode: code,
+            signal,
+            error: `The preview process exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). Nothing is running.`,
+            output: earlyOutput.slice(0, 2000),
+            logPath,
+            hint: "Read `output` above for the cause: a missing or broken dist/ (run extension_build first), or a missing browser binary are the common ones."
+        });
+    }
+    const exitStamp = browserExitStamp(args.projectPath, browser, spawnedAt);
+    if (exitStamp) return JSON.stringify({
+        ok: false,
+        status: "browser-exited",
+        projectPath: args.projectPath,
+        browser,
+        pid,
+        ...exitStamp,
+        error: "The preview process is running but the browser it launched has exited (the extension may have been rejected or the browser crashed). The session cannot be driven.",
+        output: earlyOutput.slice(0, 2000),
+        logPath,
+        hint: "Read `output` above and extension_logs for the cause, then call extension_stop to clean up before retrying."
+    });
     return JSON.stringify({
+        ok: true,
         pid,
         browser,
         projectPath: args.projectPath,
         status: "launched",
-        hint: "Call extension_stop when you are done to close the preview browser."
+        hint: "Call extension_stop when you are done to close the preview browser.",
+        earlyOutput: earlyOutput.slice(0, 500),
+        logPath
     });
 }
-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 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.",
@@ -1094,12 +1436,11 @@ const stop_schema = {
         required: []
     }
 };
-function profileProcessPids(projectPath, browser) {
-    const marker = node_path.resolve(projectPath, "dist", `extension-profile-${browser}`);
+function pgrepPids(pattern) {
     try {
         const out = execFileSync("pgrep", [
             "-f",
-            marker
+            pattern
         ], {
             encoding: "utf8"
         });
@@ -1108,8 +1449,19 @@ function profileProcessPids(projectPath, browser) {
         return [];
     }
 }
-function reapProfileProcesses(projectPath, browser) {
-    const pids = profileProcessPids(projectPath, browser);
+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  {}
@@ -1123,7 +1475,7 @@ function isAlive(pid) {
         return false;
     }
 }
-function signal(pid, sig) {
+function stop_signal(pid, sig) {
     try {
         process.kill(-pid, sig);
         return true;
@@ -1152,7 +1504,7 @@ async function stopOne(projectPath, browser) {
     const session = getSession(projectPath, browser);
     const pid = session?.pid ?? pidFromReadyContract(projectPath, browser);
     if (null == pid) {
-        const reaped = reapProfileProcesses(projectPath, browser);
+        const reaped = reapSessionProcesses(projectPath);
         return {
             projectPath,
             browser,
@@ -1164,22 +1516,22 @@ async function stopOne(projectPath, browser) {
     }
     let detail;
     if (isAlive(pid)) {
-        signal(pid, "SIGTERM");
+        stop_signal(pid, "SIGTERM");
         await new Promise((resolve)=>setTimeout(resolve, 1500));
         if (isAlive(pid)) {
-            signal(pid, "SIGKILL");
+            stop_signal(pid, "SIGKILL");
             await new Promise((resolve)=>setTimeout(resolve, 250));
         }
         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 = reapProfileProcesses(projectPath, browser);
+    const reaped = reapSessionProcesses(projectPath);
     removeSession(projectPath, browser);
     try {
         node_fs.rmSync(readyJsonPath(projectPath, browser), {
             force: true
         });
     } catch  {}
-    const survivors = profileProcessPids(projectPath, browser);
+    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).`;
@@ -1410,9 +1762,14 @@ const manifest_validate_schema = {
                 },
                 default: [
                     "chrome",
-                    "firefox"
+                    "firefox",
+                    "edge"
                 ],
                 description: "Browsers to validate against"
+            },
+            browser: {
+                type: "string",
+                description: "Single browser to validate against; alias for browsers:[browser] to match the other tools."
             }
         },
         required: []
@@ -1450,6 +1807,19 @@ function collectPathRefs(m) {
     if (sa) push(sa.default_panel);
     const cuo = m.chrome_url_overrides;
     if (cuo) Object.values(cuo).forEach(push);
+    const dnr = m.declarative_net_request;
+    if (dnr && Array.isArray(dnr.rule_resources)) {
+        for (const r of dnr.rule_resources)if (r && "object" == typeof r) push(r.path);
+    }
+    const storage = m.storage;
+    if (storage) push(storage.managed_schema);
+    push(m.devtools_page);
+    const pa = m.page_action;
+    if (pa) {
+        push(pa.default_popup);
+        if ("string" == typeof pa.default_icon) push(pa.default_icon);
+        else if (pa.default_icon) Object.values(pa.default_icon).forEach(push);
+    }
     return refs;
 }
 function fileResolvesSomewhere(ref, roots) {
@@ -1473,10 +1843,95 @@ function findManifest(projectPath) {
     }
     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 explicitBrowsers = Array.isArray(args.browsers) && args.browsers.length > 0;
     const browsers = args.browsers ?? [
         "chrome",
-        "firefox"
+        "firefox",
+        "edge"
     ];
     const result = {
         valid: true,
@@ -1521,19 +1976,46 @@ async function manifest_validate_handler(args) {
             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.`);
-    if (!chromiumManifest.manifest_version) result.errors.push('Missing manifest_version. Use "chromium:manifest_version": 3 and "firefox:manifest_version": 2 for cross-browser support.');
+    for (const ref of new Set(collectPathRefs(chromiumManifest)))if (!fileResolvesSomewhere(ref, roots)) result.errors.push(`Referenced file "${ref}" was not found near the manifest. extension_build fails on this dangling reference.`);
+    const defaultLocale = manifest.default_locale;
+    if ("string" == typeof defaultLocale && defaultLocale) {
+        const hasCatalog = roots.some((root)=>node_fs.existsSync(node_path.resolve(root, "_locales", defaultLocale, "messages.json")));
+        if (!hasCatalog) result.errors.push(`default_locale "${defaultLocale}" is declared but _locales/${defaultLocale}/messages.json was not found. The build fails on this; add the catalog or remove default_locale.`);
+    }
+    const iconMap = chromiumManifest.icons;
+    if (!iconMap || "string" != typeof iconMap["128"]) result.warnings.push('No 128x128 icon declared ("128" key in icons). The Chrome Web Store requires one for a store listing, and Edge Add-ons expects it too.');
+    const effectiveByBrowser = new Map();
+    for (const b of browsers)effectiveByBrowser.set(b, filterKeysForThisBrowser(manifest, b));
+    const declaredPermSet = new Set();
+    for (const view of [
+        chromiumManifest,
+        ...effectiveByBrowser.values()
+    ])for (const p of [
+        ...view.permissions ?? [],
+        ...view.optional_permissions ?? []
+    ])if ("string" == typeof p) declaredPermSet.add(p);
+    const usedApis = scanApiUsage(roots);
+    for (const api of usedApis){
+        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) {
+        if (2 !== chromiumManifest.manifest_version && 3 !== chromiumManifest.manifest_version) result.errors.push(`manifest_version must be 2 or 3, got ${JSON.stringify(chromiumManifest.manifest_version)}. No browser installs this manifest.`);
+    } else result.errors.push('Missing manifest_version. Use "chromium:manifest_version": 3 and "firefox:manifest_version": 2 for cross-browser support.');
     const declaredPerms = [
         ...chromiumManifest.permissions ?? [],
         ...chromiumManifest.optional_permissions ?? []
     ].filter((p)=>"string" == typeof p);
     for (const perm of declaredPerms)if (!(perm.includes("://") || perm.includes("*")) && "<all_urls>" !== perm) {
-        if (!KNOWN_PERMISSIONS.has(perm)) result.warnings.push(`Unrecognized permission "${perm}" — check for a typo (host/match patterns belong in host_permissions, not permissions).`);
+        if (!KNOWN_PERMISSIONS.has(perm)) result.warnings.push(`Unrecognized permission "${perm}", check for a typo (host/match patterns belong in host_permissions, not permissions).`);
     }
     for (const browser of browsers){
         const isChromium = isChromiumFamily(browser);
         const isFirefox = isGeckoFamily(browser);
-        const effective = filterKeysForThisBrowser(manifest, browser);
+        const effective = effectiveByBrowser.get(browser) ?? filterKeysForThisBrowser(manifest, browser);
         const issues = [];
         if (isChromium) {
             const mv = effective.manifest_version;
@@ -1555,6 +2037,17 @@ async function manifest_validate_handler(args) {
                 if (bg.service_worker && !bg.scripts) issues.push('Background service_worker declared but no firefox:scripts. Firefox uses "scripts" (array) instead of "service_worker".');
             }
         }
+        const effectivePerms = new Set([
+            ...effective.permissions ?? [],
+            ...effective.optional_permissions ?? []
+        ].filter((p)=>"string" == typeof p));
+        for (const api of usedApis){
+            const perm = API_PERMISSION[api];
+            if (effectivePerms.has(perm)) continue;
+            if (!declaredPermSet.has(perm)) continue;
+            const ns = isFirefox ? "browser" : "chrome";
+            issues.push(`Code calls ${ns}.${api} but the ${browser} build's permissions do not include "${perm}" (it is declared only under another target's prefixed key, e.g. chromium:permissions). This target crashes at runtime.`);
+        }
         result.browserSupport[browser] = {
             supported: 0 === issues.length,
             issues
@@ -1580,8 +2073,17 @@ 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);
+    for (const [browser, support] of Object.entries(result.browserSupport)){
+        if (support.supported) continue;
+        const issues = support.issues?.length ? support.issues.join("; ") : `${browser} is not supported by this manifest.`;
+        if (explicitBrowsers) result.errors.push(`${browser}: ${issues}`);
+        else result.warnings.push(`${browser} (not requested, checked by default): ${issues}`);
+    }
+    result.valid = 0 === result.errors.length;
+    return JSON.stringify({
+        ...result,
+        buildBlocking: result.errors.length > 0
+    });
 }
 const inspect_schema = {
     name: "extension_inspect",
@@ -1730,8 +2232,8 @@ async function inspect_handler(args) {
     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.`);
+        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,
@@ -1778,6 +2280,7 @@ async function inspect_handler(args) {
         storeReadiness: {
             hasManifest: node_fs.existsSync(manifestPath),
             hasIcons: files.some((f)=>"image" === f.type && f.path.includes("icon")),
+            has128Icon: "string" == typeof manifest.icons?.["128"],
             noSourceMaps: !files.some((f)=>"sourcemap" === f.type),
             noPromoAssets: !files.some((f)=>PROMO_RE.test(f.path)),
             under10MB: totalSize < 10485760
@@ -1799,7 +2302,7 @@ const COMMAND_TIMEOUT_MS = 15000;
 class CDPConnection {
     async connect(wsUrl) {
         return new Promise((resolve, reject)=>{
-            this.ws = new ws(wsUrl);
+            this.ws = new ws_0(wsUrl);
             this.ws.on("open", ()=>resolve());
             this.ws.on("message", (data)=>{
                 this.handleMessage(data.toString());
@@ -1868,7 +2371,7 @@ class CDPConnection {
     }
     async sendCommand(method, params = {}, sessionId) {
         return new Promise((resolve, reject)=>{
-            if (!this.ws || this.ws.readyState !== ws.OPEN) return reject(new Error("CDP WebSocket is not connected"));
+            if (!this.ws || this.ws.readyState !== ws_0.OPEN) return reject(new Error("CDP WebSocket is not connected"));
             const id = ++this.messageId;
             const message = {
                 id,
@@ -2259,7 +2762,7 @@ const source_inspect_schema = {
                 items: {
                     type: "string"
                 },
-                description: "CSS selectors to query — returns element counts and samples for each"
+                description: "CSS selectors to query, returns element counts and samples for each"
             },
             include: {
                 type: "array",
@@ -2311,7 +2814,7 @@ async function source_inspect_handler(args) {
     const maxBytes = args.maxBytes ?? 262144;
     if (!isChromiumFamily(browser)) return JSON.stringify({
         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.`
+        hint: `For the ${browser} session, read runtime state with extension_logs, or extension_eval / extension_dom_inspect (content/page, an open surface like popup/options/sidebar, or an override page like newtab) which work 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({
@@ -2393,7 +2896,11 @@ async function source_inspect_handler(args) {
         if (include.has("dom_snapshot")) result.domSnapshot = await cdp.getDomSnapshot(sessionId);
         if (include.has("console")) result.console = cdp.getConsoleSummary();
         if (include.has("extension_roots")) result.extensionRoots = await cdp.getExtensionRootMeta(sessionId);
-        if (args.probe?.length) result.probes = await cdp.probeSelectors(sessionId, args.probe);
+        if (args.probe?.length) {
+            result.probes = await cdp.probeSelectors(sessionId, args.probe);
+            const jsLooking = args.probe.filter((p)=>/^typeof\s|^(chrome|browser|window|document)\.|\(\)|=>|===/.test(p));
+            if (jsLooking.length) result.probeWarning = `Probes are CSS selectors run through querySelectorAll against the live page, NOT JavaScript expressions. ${jsLooking.map((s)=>`"${s}"`).join(", ")} parsed as selectors and will match nothing. To evaluate JS, use extension_eval.`;
+        }
         if (args.deepDom) {
             const closed = await cdp.getClosedShadowRoots(sessionId, maxBytes > 0 ? maxBytes : 65536);
             result.closedShadowRoots = closed;
@@ -2412,7 +2919,7 @@ async function source_inspect_handler(args) {
 }
 const list_extensions_schema = {
     name: "extension_list_extensions",
-    description: "List the extensions with a live context in the running dev browser via Chrome DevTools Protocol. Returns each extension's id, name, version, and live contexts (service worker, page). Identity is read read-only via the Extensions domain — other extensions' contexts are never attached to or evaluated in. A dormant MV3 service worker with no open page may be absent until it wakes. Chromium only (Firefox uses RDP, not yet supported). Requires an active dev or start session.",
+    description: "List the extensions with a live context in the running dev browser via Chrome DevTools Protocol. Returns each extension's id, name, version, and live contexts (service worker, page). Identity is read read-only via the Extensions domain, other extensions' contexts are never attached to or evaluated in. A dormant MV3 service worker with no open page may be absent until it wakes. Chromium only (Firefox uses RDP, not yet supported). Requires an active dev or start session.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2667,10 +3174,28 @@ function capRecent(events, limit) {
         truncated: true
     };
 }
-function summarize(events, source, browser, runId, limit, dropped) {
+function emptyReason(projectPath, browser) {
+    let contract;
+    try {
+        contract = JSON.parse(node_fs.readFileSync(node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json"), "utf8"));
+    } catch  {
+        return "No ready.json for this project/browser: no dev session has produced a build here, so there is nothing to log. Start one with extension_dev.";
+    }
+    if ("error" === contract.status) {
+        const errs = contract.errors;
+        return `The dev session recorded status:"error"${errs?.length ? ` (${errs.join("; ")})` : ""}, so the extension never ran. There are no logs because there was no working build, not because your code is silent.`;
+    }
+    if ("number" == typeof contract.pid) try {
+        process.kill(contract.pid, 0);
+    } catch  {
+        return `ready.json reports ready but its dev-server pid ${contract.pid} is dead: the session exited. Logs stop at the moment it died. Restart with extension_dev; extension_doctor will confirm.`;
+    }
+}
+function summarize(events, source, browser, runId, limit, dropped, projectPath, staleNote) {
     const matched = events.length;
     const { events: out, truncated } = capRecent(events, limit);
     const lastSeq = out.length ? out.reduce((m, e)=>"number" == typeof e.seq && e.seq > m ? e.seq : m, -1) : -1;
+    const reason = 0 === matched && projectPath ? emptyReason(projectPath, browser) : void 0;
     return JSON.stringify({
         ok: true,
         source,
@@ -2681,9 +3206,30 @@ function summarize(events, source, browser, runId, limit, dropped) {
         truncated,
         dropped: dropped || void 0,
         nextSince: lastSeq >= 0 ? lastSeq : void 0,
+        ...reason ? {
+            emptyReason: reason
+        } : {},
+        ...staleNote && matched > 0 ? {
+            stale: true,
+            warning: staleNote
+        } : {},
         events: out
     });
 }
+function staleFileNote(projectPath, browser, eventsRunId) {
+    let contract;
+    try {
+        contract = JSON.parse(node_fs.readFileSync(node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json"), "utf8"));
+    } catch  {
+        return "These events survive from a previous session: no ready.json exists for this project/browser now, so nothing current is producing logs.";
+    }
+    if ("number" == typeof contract.pid) try {
+        process.kill(contract.pid, 0);
+    } catch  {
+        return `These events are from a PAST run: the session that wrote them (pid ${contract.pid}) is dead. Nothing current is producing logs; do not read these as live output.`;
+    }
+    if (eventsRunId && contract.runId && String(contract.runId) !== eventsRunId) return `These events carry runId ${eventsRunId} but the current session is run ${String(contract.runId)}, which has written nothing yet. Do not read these as the current run's output.`;
+}
 async function readFromFile(args, browser, limit) {
     const file = logsFilePath(args.projectPath, browser);
     if (!node_fs.existsSync(file)) return JSON.stringify({
@@ -2707,13 +3253,13 @@ async function readFromFile(args, browser, limit) {
         }
         if (matches(event)) events.push(event);
     }
-    return summarize(events, "file", browser, runId, limit, 0);
+    return summarize(events, "file", browser, runId, limit, 0, args.projectPath, staleFileNote(args.projectPath, browser, runId));
 }
 async function readFromStream(args, browser, limit) {
     const ready = readReadyContract(args.projectPath, browser);
     if (!ready) {
         const running = knownSessionBrowsers(args.projectPath).filter((b)=>b !== browser);
-        const retarget = running.length ? `An active session exists for browser(s): ${running.join(", ")} — pass that as \`browser\`. Otherwise run` : "Run";
+        const retarget = running.length ? `An active session exists for browser(s): ${running.join(", ")}, pass that as \`browser\`. Otherwise run` : "Run";
         return JSON.stringify({
             error: `No active control channel found for ${browser}.`,
             hint: `${retarget} extension_dev (browser: ${browser}) and wait for it to be ready, then retry. For past logs without a live channel, call without follow.`
@@ -2729,7 +3275,7 @@ async function readFromStream(args, browser, limit) {
         const url = `ws://127.0.0.1:${ready.controlPort}${CONTROL_WS_PATH}`;
         let socket;
         try {
-            socket = new ws(url);
+            socket = new ws_0(url);
         } catch (err) {
             resolve(JSON.stringify({
                 error: `Could not open control channel at ${url}: ${err instanceof Error ? err.message : String(err)}`
@@ -2743,7 +3289,7 @@ async function readFromStream(args, browser, limit) {
             try {
                 socket.close();
             } catch  {}
-            resolve(summarize(events, "stream", browser, runId, limit, dropped));
+            resolve(summarize(events, "stream", browser, runId, limit, dropped, args.projectPath));
         };
         const timer = setTimeout(finish, followMs);
         socket.on("open", ()=>{
@@ -2787,13 +3333,16 @@ 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.`;
+    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.`;
 }
 function translateFrame(frame, projectPath) {
     if (!frame || false !== frame.ok) return frame;
@@ -2837,7 +3386,7 @@ function commonFlags(args) {
 }
 const eval_schema = {
     name: "extension_eval",
-    description: "Evaluate an expression in a running extension context. Requires the dev session to be started with allowEval: true (extension_dev; writes a 0600 session token the CLI reads). Chromium caveats: eval in the MV3 background/service_worker is blocked by CSP (use an MV2/Firefox build for that context), and context content/page/popup require a numeric `tab` id (a chrome.tabs id) — the `url` arg alone does not target a tab. To read a content-script DOM without a tab id, prefer extension_source_inspect (it auto-selects the active page and can navigate by url). Wraps `extension eval`.",
+    description: "Evaluate an expression in a running extension context. Requires the dev session to be started with allowEval: true (extension_dev; writes a 0600 session token the CLI reads). Targeting for context content/page: pass `url` to pick the matching tab, or omit both `url` and `tab` to use the ACTIVE tab; a numeric `tab` id is only needed to disambiguate. Extension surfaces (popup/options/sidebar/devtools) and override pages (newtab/history/bookmarks) evaluate over the in-bundle relay and need NO tab id; the surface must be OPEN (extension_open first; a closed surface returns an explicit error). Chromium caveat: eval in the MV3 background/service_worker is blocked by CSP (use an MV2/Firefox build for that context). Use extension_dom_inspect with listTabs: true to enumerate {tabId,url,title}. Wraps `extension eval`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2857,6 +3406,9 @@ const eval_schema = {
                     "options",
                     "sidebar",
                     "devtools",
+                    "newtab",
+                    "history",
+                    "bookmarks",
                     "content",
                     "page"
                 ],
@@ -2865,11 +3417,11 @@ const eval_schema = {
             },
             url: {
                 type: "string",
-                description: "For content/page: filters which matching document(s) to target, but does NOT by itself select a tab — a numeric `tab` id is still required on Chromium."
+                description: "For content/page: selects the target tab by url (match pattern, then substring fallback). Preferred over `tab`. You do not need a numeric id."
             },
             tab: {
                 type: "number",
-                description: "Numeric chrome.tabs id. Required for context content/page/popup on Chromium (the `url` arg does not substitute for it)."
+                description: "Numeric chrome.tabs id, for disambiguating when several tabs match. Optional: with neither `tab` nor `url`, content/page target the active tab."
             },
             browser: {
                 type: "string",
@@ -2888,7 +3440,7 @@ const eval_schema = {
 };
 async function eval_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
-    return runActVerb([
+    const raw = await runActVerb([
         "eval",
         args.expression,
         args.projectPath,
@@ -2897,6 +3449,14 @@ async function eval_handler(args) {
             browser
         })
     ], args.projectPath, args.timeout);
+    if ("content" === args.context) try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.ok === true && (null === parsed.value || void 0 === parsed.value)) {
+            parsed.note = "On Extension.js >= 4.0.14 a failed injection errors explicitly, so this null is the expression's real result. On OLDER engines (bug 61) it could mean the injection never ran; if this result looks wrong, check the engine version with extension_doctor, or verify with extension_logs or context:'page'.";
+            return JSON.stringify(parsed);
+        }
+    } catch  {}
+    return raw;
 }
 const storage_schema = {
     name: "extension_storage",
@@ -2976,6 +3536,13 @@ async function storage_handler(args) {
                 message: "storage set requires a value"
             }
         });
+        if (void 0 === args.key) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "BadRequest",
+                message: 'storage set requires `key` (string) and `value` args, one key per call. There is no bulk-object set: to seed {a: 1, b: 2}, call once with key: "a" and once with key: "b".'
+            }
+        });
         cli.push("--value", JSON.stringify(args.value));
     }
     if (args.context) cli.push("--context", args.context);
@@ -3031,9 +3598,266 @@ async function reload_handler(args) {
         })
     ], args.projectPath, args.timeout);
 }
+async function pollForTarget(port, url, budgetMs) {
+    const deadline = Date.now() + budgetMs;
+    const wanted = url.replace(/#.*$/, "");
+    for(;;){
+        try {
+            const targets = await CDPClient.discoverTargets(port);
+            for (const t of targets){
+                const tUrl = String(t.url ?? "");
+                if ("page" === t.type) {
+                    if (tUrl === wanted || tUrl.startsWith(wanted)) return {
+                        id: String(t.id),
+                        url: tUrl,
+                        title: "string" == typeof t.title ? t.title : void 0
+                    };
+                }
+            }
+        } catch  {}
+        if (Date.now() >= deadline) return null;
+        await new Promise((r)=>setTimeout(r, 250));
+    }
+}
+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);
+        const settled = await pollForTarget(resolved.port, url, 6000);
+        if (!settled) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NavigateFailed",
+                message: `Navigation to ${url} did not produce a live page target. The URL may not exist in the extension bundle, or Chrome refused the navigation.`
+            },
+            hint: "Confirm the path exists in the built dist (extension_build / extension_inspect list entrypoints). For an extension page, the path must match the BUILT manifest, which may differ from your source layout."
+        });
+        return JSON.stringify({
+            ok: true,
+            navigated: url,
+            target: {
+                targetId: settled.id,
+                title: settled.title,
+                url: settled.url
+            },
+            hint: "Inspect it with extension_dom_inspect or extension_source_inspect using url (context: 'page'), they resolve the tab themselves. `target.targetId` is a CDP target id, NOT a chrome.tabs id: do not pass it as `tab`. If you need a numeric tab id, call extension_dom_inspect with listTabs: true."
+        });
+    } catch (e) {
+        return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NavigateError",
+                message: e instanceof Error ? e.message : String(e)
+            }
+        });
+    } finally{
+        try {
+            cdp.disconnect();
+        } catch  {}
+    }
+}
+function unpackedExtensionId(distPath) {
+    const digest = node_crypto.createHash("sha256").update(distPath).digest();
+    let id = "";
+    for(let i = 0; i < 16; i++){
+        id += String.fromCharCode(97 + (digest[i] >> 4));
+        id += String.fromCharCode(97 + (0x0f & digest[i]));
+    }
+    return id;
+}
+async function resolveExtensionId(projectPath, browser) {
+    const distPath = readDistPath(projectPath, browser);
+    const computed = distPath ? unpackedExtensionId(distPath) : null;
+    const resolved = await resolveCdpPort(projectPath, browser);
+    if (!resolved) return computed;
+    const ids = new Set();
+    try {
+        for (const t of (await CDPClient.discoverTargets(resolved.port))){
+            const url = String(t.url ?? "");
+            if (!url.startsWith("chrome-extension://")) continue;
+            const id = url.slice(19).split("/")[0];
+            if (id) ids.add(id);
+        }
+    } catch  {}
+    if (computed && ids.has(computed)) return computed;
+    if (computed) return computed;
+    return 1 === ids.size ? [
+        ...ids
+    ][0] : null;
+}
+function declaredCommands(projectPath, browser) {
+    const candidates = [
+        node_path.join(projectPath, "dist", browser, "manifest.json"),
+        node_path.join(projectPath, "dist", "manifest.json"),
+        node_path.join(projectPath, "src", "manifest.json"),
+        node_path.join(projectPath, "manifest.json")
+    ];
+    for (const file of candidates)try {
+        const manifest = JSON.parse(node_fs.readFileSync(file, "utf8"));
+        const commands = manifest?.commands;
+        if (commands && "object" == typeof commands) return Object.keys(commands);
+        return [];
+    } catch  {
+        continue;
+    }
+    return null;
+}
+function readDistPath(projectPath, browser) {
+    try {
+        const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+        const contract = JSON.parse(node_fs.readFileSync(file, "utf8"));
+        return "string" == typeof contract?.distPath ? contract.distPath : null;
+    } catch  {
+        return null;
+    }
+}
+function surfaceDocument(projectPath, browser, surface) {
+    const candidates = [
+        node_path.join(projectPath, "dist", browser, "manifest.json"),
+        node_path.join(projectPath, "dist", "manifest.json"),
+        node_path.join(projectPath, "src", "manifest.json"),
+        node_path.join(projectPath, "manifest.json")
+    ];
+    for (const file of candidates){
+        let manifest;
+        try {
+            manifest = JSON.parse(node_fs.readFileSync(file, "utf8"));
+        } catch  {
+            continue;
+        }
+        const action = manifest.action ?? manifest.browser_action;
+        const ref = "popup" === surface || "action" === surface ? action?.default_popup : "options" === surface ? manifest.options_ui?.page ?? manifest.options_page : "sidebar" === surface ? manifest.side_panel?.default_path ?? manifest.sidebar_action?.default_panel : "newtab" === surface || "history" === surface || "bookmarks" === surface ? manifest.chrome_url_overrides?.[surface] : null;
+        if ("string" == typeof ref && ref) return ref.replace(/^\.?\//, "");
+    }
+    return null;
+}
+const POPUP_MIN = 25;
+const POPUP_MAX_WIDTH = 800;
+const POPUP_MAX_HEIGHT = 600;
+function clampPopupBounds(width, height) {
+    const w = Math.min(Math.max(Math.ceil(width), POPUP_MIN), POPUP_MAX_WIDTH);
+    const h = Math.min(Math.max(Math.ceil(height), POPUP_MIN), POPUP_MAX_HEIGHT);
+    return {
+        width: w,
+        height: h,
+        clamped: w !== Math.ceil(width) || h !== Math.ceil(height)
+    };
+}
+async function applyPopupBounds(projectPath, browser, targetId) {
+    const resolved = await resolveCdpPort(projectPath, browser);
+    if (!resolved) return null;
+    const cdp = new CDPClient();
+    try {
+        const ws = await CDPClient.discoverBrowserWsUrl(resolved.port);
+        await cdp.connect(ws);
+        const sessionId = await cdp.attachToTarget(targetId);
+        const measured = await cdp.evaluate(sessionId, `(() => {
+        const de = document.documentElement, b = document.body;
+        if (!de || !b) return null;
+        const prev = de.style.width;
+        de.style.width = "fit-content";
+        const w = Math.max(de.getBoundingClientRect().width, b.getBoundingClientRect().width);
+        const h = Math.max(de.getBoundingClientRect().height, b.getBoundingClientRect().height, b.scrollHeight);
+        de.style.width = prev;
+        return { w: Math.ceil(w), h: Math.ceil(h) };
+      })()`);
+        if (!measured || "number" != typeof measured.w || "number" != typeof measured.h || measured.w <= 0 || measured.h <= 0) return null;
+        const bounds = clampPopupBounds(measured.w, measured.h);
+        const win = await cdp.sendCommand("Browser.getWindowForTarget", {
+            targetId
+        });
+        if ("number" != typeof win?.windowId) return null;
+        await cdp.sendCommand("Browser.setWindowBounds", {
+            windowId: win.windowId,
+            bounds: {
+                width: bounds.width,
+                height: bounds.height
+            }
+        });
+        const after = await cdp.sendCommand("Browser.getWindowBounds", {
+            windowId: win.windowId
+        });
+        if (after?.bounds?.width !== bounds.width || after?.bounds?.height !== bounds.height) return null;
+        return bounds;
+    } catch  {
+        return null;
+    } finally{
+        try {
+            cdp.disconnect();
+        } catch  {}
+    }
+}
+async function openSurfaceAsTab(projectPath, browser, surface) {
+    const doc = surfaceDocument(projectPath, browser, surface);
+    if (!doc) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "NoSurfaceDocument",
+            message: `The manifest declares no document for surface "${surface}", so there is no page to render as a tab.`
+        },
+        hint: "Check the manifest: popup needs action.default_popup, options needs options_ui.page or options_page, sidebar needs side_panel.default_path."
+    });
+    const id = await resolveExtensionId(projectPath, browser);
+    if (!id) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "NoExtensionId",
+            message: "Could not resolve the extension id from the live session's CDP targets."
+        },
+        hint: `Confirm the session is ready (extension_wait). ${CDP_PORT_MISSING_HINT}`
+    });
+    const url = `chrome-extension://${id}/${doc}`;
+    const raw = await navigateToUrl(projectPath, browser, url);
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.ok) {
+            parsed.renderedAsTab = {
+                surface,
+                document: doc,
+                extensionId: id
+            };
+            let popupBounds = null;
+            if (("popup" === surface || "action" === surface) && "string" == typeof parsed.target?.targetId) {
+                popupBounds = await applyPopupBounds(projectPath, browser, parsed.target.targetId);
+                if (popupBounds) parsed.renderedAsTab.popupBounds = popupBounds;
+            }
+            parsed.hint = `Rendered the ${surface} document in a real tab, which is how you inspect a surface headlessly. ` + (popupBounds ? `The window was resized to the popup's content size (${popupBounds.width}x${popupBounds.height}${popupBounds.clamped ? ", clamped to Chrome's 25x25-800x600 popup bounds" : ""}), approximating real popup rendering. This resizes the WHOLE browser window for the session. It is the same page with the same extension APIs, but window.close() closes the tab. ` : "It is the same page with the same extension APIs, but it is NOT hosted in a popup window: no popup sizing, and window.close() closes the tab. ") + `Inspect it with extension_dom_inspect context: '${surface}' (include: ['html']), or extension_source_inspect with this url. ` + "Do NOT pass this chrome-extension:// url to extension_dom_inspect or extension_eval as a tab target: script injection cannot reach extension pages, only the surface context or CDP can.";
+            return JSON.stringify(parsed);
+        }
+    } catch  {}
+    return raw;
+}
 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`.",
+    description: "Open an extension surface or replay an event in a running session. 'popup'/'options'/'sidebar' open UI surfaces; 'newtab'/'history'/'bookmarks' open the extension's chrome_url_overrides page in a tab. '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`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -3047,15 +3871,27 @@ const open_schema = {
                     "popup",
                     "options",
                     "sidebar",
+                    "newtab",
+                    "history",
+                    "bookmarks",
                     "action",
                     "command"
                 ],
-                description: "Which surface to open or event to replay. 'action' triggers the toolbar action; 'command' replays a keyboard-shortcut command (requires `name`)."
+                description: "Which surface to open or event to replay. 'newtab'/'history'/'bookmarks' open the matching chrome_url_overrides page. 'action' triggers the toolbar action; 'command' replays a keyboard-shortcut command (requires `name`)."
             },
             name: {
                 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`."
+            },
+            asTab: {
+                type: "boolean",
+                default: false,
+                description: "For surface popup/options/sidebar: render the surface's document in a real tab (chrome-extension://<id>/<doc>) instead of opening a real popup window. This is how you inspect a surface HEADLESSLY, where no window exists to host a popup. Applied automatically as a fallback when a headless session refuses to open the surface. Same page and APIs, but no popup sizing and window.close() closes the tab."
+            },
             browser: {
                 type: "string",
                 description: "Browser session to target. Defaults to the active dev session's browser for this project."
@@ -3066,13 +3902,41 @@ 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);
+    const AS_TAB_SURFACES = [
+        "popup",
+        "options",
+        "sidebar",
+        "newtab",
+        "history",
+        "bookmarks"
+    ];
+    if (args.asTab && args.surface && AS_TAB_SURFACES.includes(args.surface)) return openSurfaceAsTab(args.projectPath, browser, args.surface);
+    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."
+        }
+    });
+    if ("command" === args.surface) {
+        const declared = declaredCommands(args.projectPath, browser);
+        if (declared && args.name && !declared.includes(args.name)) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "UnknownCommand",
+                message: `"${args.name}" is not declared in the manifest's \`commands\`, so triggering it can only ever be a no-op.`
+            },
+            declaredCommands: declared,
+            hint: declared.length ? `Declared commands are: ${declared.join(", ")}. Check for a typo, or add "${args.name}" to the manifest.` : "This manifest declares no commands at all. Add a `commands` block, rebuild, then retry."
+        });
+    }
     const cli = [
         "open",
         args.surface,
@@ -3090,8 +3954,18 @@ async function open_handler(args) {
     ].includes(args.surface)) try {
         const parsed = JSON.parse(raw);
         const msg = String(parsed?.error?.message ?? "");
-        if (parsed?.ok === false && !parsed.hint && /active browser window|no active|headless/i.test(msg)) {
-            parsed.hint = "The dev browser is running headless (EXTENSION_HEADLESS), which has no visible window to attach a popup/sidebar to. Relaunch a headed dev session to open UI surfaces.";
+        if (parsed?.ok === false && /active browser window|no active|headless|user gesture/i.test(msg)) {
+            if (AS_TAB_SURFACES.includes(args.surface) && isChromiumFamily(browser)) {
+                const fallback = await openSurfaceAsTab(args.projectPath, browser, args.surface);
+                try {
+                    const parsedFallback = JSON.parse(fallback);
+                    if (parsedFallback?.ok) {
+                        parsedFallback.note = "The dev browser is headless (EXTENSION_HEADLESS), which has no window to attach a popup/sidebar to, so the surface was rendered as a tab instead. Pass asTab: false and relaunch headed for a real popup window.";
+                        return JSON.stringify(parsedFallback);
+                    }
+                } catch  {}
+            }
+            if (!parsed.hint) parsed.hint = /user gesture/i.test(msg) ? "This surface can only open from a real user gesture, which headless automation cannot produce. Retry with asTab: true to render the surface document in a tab instead." : "The dev browser is running headless (EXTENSION_HEADLESS), which has no visible window to attach a popup/sidebar to. Retry with asTab: true to render the surface document in a tab, or relaunch a headed dev session for a real popup window.";
             return JSON.stringify(parsed);
         }
     } catch  {}
@@ -3109,7 +3983,16 @@ const dom_inspect_schema = {
             },
             tab: {
                 type: "number",
-                description: "Tab id (required for content/page; omit for surfaces)"
+                description: "Numeric chrome.tabs id, for disambiguating when several tabs match. Optional: with neither `tab` nor `url`, content/page target the active tab."
+            },
+            url: {
+                type: "string",
+                description: "For content/page: selects the target tab by url (match pattern, then substring fallback). Preferred over `tab`."
+            },
+            listTabs: {
+                type: "boolean",
+                default: false,
+                description: "Enumerate open tabs as {tabId,url,title} and return, ignoring the other args. The discovery path when you need an explicit numeric tab id."
             },
             context: {
                 type: "string",
@@ -3119,10 +4002,13 @@ const dom_inspect_schema = {
                     "popup",
                     "options",
                     "sidebar",
-                    "devtools"
+                    "devtools",
+                    "newtab",
+                    "history",
+                    "bookmarks"
                 ],
                 default: "content",
-                description: "content/page (needs tab) or an OPEN extension surface (popup/options/sidebar/devtools)"
+                description: "content/page (targets `url`, else the active tab), an OPEN extension surface (popup/options/sidebar/devtools), or an override page (newtab/history/bookmarks)"
             },
             include: {
                 type: "array",
@@ -3143,8 +4029,11 @@ const dom_inspect_schema = {
                 default: 262144
             },
             withConsole: {
-                type: "number",
-                description: "Also include the last N console lines for the target (DOM + recent console in one call)"
+                type: [
+                    "number",
+                    "boolean"
+                ],
+                description: "Also include recent console lines for the target (DOM + console in one call). A number is how many lines; true means 50."
             },
             browser: {
                 type: "string",
@@ -3161,30 +4050,28 @@ const dom_inspect_schema = {
     }
 };
 async function dom_inspect_handler(args) {
-    const surfaces = [
-        "popup",
-        "options",
-        "sidebar",
-        "devtools"
-    ];
-    const isSurface = !!args.context && surfaces.includes(args.context);
-    if (!isSurface && null == args.tab) return JSON.stringify({
-        ok: false,
-        error: {
-            name: "BadRequest",
-            message: "content/page inspect requires a numeric tab id (chrome.tabs id, not a CDP target id)."
-        },
-        hint: "To inspect a content script's DOM without hunting for a tab id, use extension_source_inspect (it auto-selects the active page and can navigate via its url arg). Use extension_dom_inspect with context popup/options/sidebar/devtools for an open surface (no tab needed)."
-    });
+    const withConsole = true === args.withConsole ? 50 : false === args.withConsole ? void 0 : args.withConsole;
+    if (args.listTabs) return runActVerb([
+        "inspect",
+        args.projectPath,
+        "--list-tabs",
+        "--browser",
+        resolveSessionBrowser(args.projectPath, args.browser).browser,
+        ...null != args.timeout ? [
+            "--timeout",
+            String(args.timeout)
+        ] : []
+    ], args.projectPath, args.timeout);
     const cli = [
         "inspect",
         args.projectPath
     ];
     if (null != args.tab) cli.push("--tab", String(args.tab));
+    if (args.url) cli.push("--url", args.url);
     if (args.context) cli.push("--context", args.context);
     if (args.include?.length) cli.push("--include", args.include.join(","));
     if (null != args.maxBytes) cli.push("--max-bytes", String(args.maxBytes));
-    if (null != args.withConsole) cli.push("--with-console", String(args.withConsole));
+    if (null != withConsole) cli.push("--with-console", String(withConsole));
     cli.push("--browser", resolveSessionBrowser(args.projectPath, args.browser).browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
     return runActVerb(cli, args.projectPath, args.timeout);
@@ -3624,61 +4511,251 @@ const deploy_schema = {
 };
 function deploy_fail(name, message) {
     return JSON.stringify({
-        ok: false,
-        error: {
-            name,
-            message
-        }
+        ok: false,
+        error: {
+            name,
+            message
+        }
+    });
+}
+async function deploy_handler(args) {
+    const token = resolveToken();
+    if (!token) return deploy_fail("DeployAuthError", "No token. Run extension_login, or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard under project settings -> Access tokens).");
+    const browsers = (Array.isArray(args.browsers) ? args.browsers : []).map((b)=>String(b).trim().toLowerCase()).filter(Boolean);
+    if (0 === browsers.length) return deploy_fail("DeployInputError", 'browsers is required (e.g. ["chrome","firefox","edge"]).');
+    const buildSha = String(args.buildSha || "").trim();
+    if (!buildSha) return deploy_fail("DeployInputError", "buildSha is required (the built commit to submit).");
+    const apiCheck = safeApiBase(String(args.api || process.env.EXTENSION_DEV_API_URL || deploy_DEFAULT_API));
+    if (!apiCheck.ok) return deploy_fail("DeployConfigError", apiCheck.message);
+    const url = `${apiCheck.base}/api/cli/stores/submit`;
+    const dryRun = false !== args.dryRun;
+    const body = {
+        browsers,
+        buildSha,
+        dryRun
+    };
+    if (args.channel) body.channel = String(args.channel).trim();
+    if (args.version) body.version = String(args.version).trim();
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${token}`,
+                "content-type": "application/json"
+            },
+            body: JSON.stringify(body)
+        });
+    } catch (err) {
+        return deploy_fail("DeployNetworkError", `Could not reach ${url}: ${err?.message || err}`);
+    }
+    const text = await res.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    } catch  {
+        data = {
+            message: text
+        };
+    }
+    if (!res.ok) return deploy_fail("DeployError", `submit failed (${res.status}): ${data?.message || text || "unknown error"}`);
+    return JSON.stringify({
+        mode: "platform",
+        dryRun,
+        ...data
+    });
+}
+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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectPath: {
+                type: "string",
+                description: "Path to the extension project root. Omit for a pre-flight environment check with no project."
+            },
+            browser: {
+                type: "string",
+                description: "Browser session to diagnose. Defaults to the active dev session's browser for this project."
+            }
+        }
+    }
+};
+async function environmentPreflight() {
+    const checks = [];
+    const nodeMajor = Number(process.versions.node.split(".")[0]);
+    checks.push({
+        check: "node",
+        status: nodeMajor >= 20 ? "pass" : "fail",
+        detail: `Node ${process.versions.node} on ${process.platform}/${process.arch}`,
+        remediation: nodeMajor >= 20 ? void 0 : "Extension.js needs Node >= 20.18."
+    });
+    const { code, stdout, stderr } = await runExtensionCli([
+        "--version"
+    ], {
+        timeoutMs: 60000
+    });
+    const cliVersion = stdout.trim() || stderr.trim();
+    checks.push({
+        check: "extension-cli",
+        status: 0 === code ? "pass" : "fail",
+        detail: 0 === code ? `extension CLI resolvable (${cliVersion})` : "extension CLI could not be resolved",
+        remediation: 0 === code ? void 0 : "Install locally (npm i -D extension) or rely on npx; check network access to the npm registry."
+    });
+    const cacheFile = node_path.join(node_os.homedir(), ".cache", "extension-js", "templates-meta.json");
+    const cacheExists = node_fs.existsSync(cacheFile);
+    checks.push({
+        check: "template-cache",
+        status: cacheExists ? "pass" : "warn",
+        detail: cacheExists ? `Template catalog cached at ${cacheFile}` : "Template catalog not cached yet (first extension_list_templates will fetch it)"
+    });
+    const healthy = checks.every((c)=>"fail" !== c.status);
+    return JSON.stringify({
+        mode: "environment",
+        healthy,
+        checks,
+        hint: "Pass projectPath to diagnose a live dev session end-to-end."
     });
 }
-async function deploy_handler(args) {
-    const token = resolveToken();
-    if (!token) return deploy_fail("DeployAuthError", "No token. Run extension_login, or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard under project settings -> Access tokens).");
-    const browsers = (Array.isArray(args.browsers) ? args.browsers : []).map((b)=>String(b).trim().toLowerCase()).filter(Boolean);
-    if (0 === browsers.length) return deploy_fail("DeployInputError", 'browsers is required (e.g. ["chrome","firefox","edge"]).');
-    const buildSha = String(args.buildSha || "").trim();
-    if (!buildSha) return deploy_fail("DeployInputError", "buildSha is required (the built commit to submit).");
-    const apiCheck = safeApiBase(String(args.api || process.env.EXTENSION_DEV_API_URL || deploy_DEFAULT_API));
-    if (!apiCheck.ok) return deploy_fail("DeployConfigError", apiCheck.message);
-    const url = `${apiCheck.base}/api/cli/stores/submit`;
-    const dryRun = false !== args.dryRun;
-    const body = {
-        browsers,
-        buildSha,
-        dryRun
-    };
-    if (args.channel) body.channel = String(args.channel).trim();
-    if (args.version) body.version = String(args.version).trim();
-    let res;
+function safeStringify(value) {
     try {
-        res = await fetch(url, {
-            method: "POST",
-            headers: {
-                authorization: `Bearer ${token}`,
-                "content-type": "application/json"
-            },
-            body: JSON.stringify(body)
-        });
-    } catch (err) {
-        return deploy_fail("DeployNetworkError", `Could not reach ${url}: ${err?.message || err}`);
+        return JSON.stringify(value) ?? String(value);
+    } catch  {
+        return String(value);
     }
-    const text = await res.text();
-    let data;
+}
+function recentErrorLogs(projectPath, browser, max = 5) {
+    const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "logs.ndjson");
+    let lines;
     try {
-        data = JSON.parse(text);
+        lines = node_fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
     } catch  {
-        data = {
-            message: text
-        };
+        return [];
     }
-    if (!res.ok) return deploy_fail("DeployError", `submit failed (${res.status}): ${data?.message || text || "unknown error"}`);
-    return JSON.stringify({
-        mode: "platform",
-        dryRun,
-        ...data
+    const errs = [];
+    for (const line of lines){
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        } catch  {
+            continue;
+        }
+        if (!ev || "error" !== ev.level) continue;
+        const parts = Array.isArray(ev.messageParts) ? ev.messageParts : Array.isArray(ev.args) ? ev.args : null;
+        let msg = parts ? parts.map((p)=>"string" == typeof p ? p : safeStringify(p)).join(" ") : ev.message || ev.text || "";
+        if (!msg && ev.errorName) msg = ev.stack ? `${ev.errorName}: ${ev.stack}` : ev.errorName;
+        msg = msg.replace(/\s+/g, " ").trim();
+        if (msg) errs.push(msg.slice(0, 300));
+    }
+    return [
+        ...new Set(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;
+    const { browser } = resolveSessionBrowser(projectPath, args.browser);
+    const { code, stdout, stderr } = await runExtensionCli([
+        "doctor",
+        projectPath,
+        "--browser",
+        browser,
+        "--output",
+        "json"
+    ], {
+        cwd: projectPath
     });
+    const out = stdout.trim();
+    try {
+        const checks = JSON.parse(out);
+        if (!Array.isArray(checks)) throw new Error("not a check array");
+        for (const check of checks){
+            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 browserExited = "browser_exited" === contract.code || void 0 !== contract.browserExitCode;
+            const detail = browserExited ? `The ${browser} browser for this session exited unexpectedly${null != contract.browserExitCode ? ` (exit code ${contract.browserExitCode})` : ""}; the extension may have been rejected or the browser crashed. The session cannot be driven.` : 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: browserExited ? "Read extension_logs and the session log for the rejection cause, call extension_stop to clean up, then relaunch." : "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 chrome.* API called without its permission is a common cause: extension_manifest_validate catches a permission MISSING FROM permissions[], but it does not model host-permission scope (e.g. webRequest with no matching host_permissions) or gesture requirements (e.g. activeTab without a user gesture), so a valid:true there does not rule those out."
+                });
+            }
+        }
+        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,
+            ...engineVersion ? {
+                engineVersion
+            } : {},
+            healthy,
+            checks
+        });
+    } catch  {
+        const message = stderr.trim() || `extension exited with code ${code}`;
+        return JSON.stringify({
+            ok: false,
+            error: {
+                name: "CliError",
+                message: toMcpSpeak(message),
+                hint: "extension doctor requires a recent extension CLI, the project's local install may predate it."
+            }
+        });
+    }
 }
 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).",
@@ -3712,22 +4789,43 @@ async function wait_handler(args) {
     const readyPath = node_path.resolve(args.projectPath, "dist", "extension-js", browser, "ready.json");
     const start = Date.now();
     const pollInterval = 1000;
+    let sawCompiledButUnattached = false;
     while(Date.now() - start < timeout){
         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
+                });
+                const attached = "attached" === contract.runtime || "string" == typeof contract.executorAttachedAt;
+                if (!attached) {
+                    await new Promise((r)=>setTimeout(r, pollInterval));
+                    sawCompiledButUnattached = true;
+                    continue;
+                }
+                const runtimeErrors = recentErrorLogs(args.projectPath, browser, 3);
+                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,
+                    ...runtimeErrors.length ? {
+                        runtimeErrors,
+                        warning: `Compiled and attached, but the extension is throwing at runtime (${runtimeErrors.length} recent error event${1 === runtimeErrors.length ? "" : "s"} above). Check extension_logs (level: error) or extension_doctor before trusting this session.`
+                    } : {}
+                });
+            }
             if ("error" === contract.status) return JSON.stringify({
                 status: "error",
                 message: contract.message,
@@ -3739,13 +4837,20 @@ async function wait_handler(args) {
         } catch  {}
         await new Promise((resolve)=>setTimeout(resolve, pollInterval));
     }
+    if (sawCompiledButUnattached) return JSON.stringify({
+        status: "compiled-not-attached",
+        message: `The extension compiled, but the runtime executor never attached within ${timeout}ms. The build is fine; the browser side is not connected, so extension_eval/storage/reload/open will fail with "no executor connected".`,
+        readyPath,
+        waitDuration: Date.now() - start,
+        hint: "This is usually transient: call extension_wait again. If it persists, stop and restart the session with extension_dev (a restart reliably reattaches); extension_doctor reports the executor leg."
+    });
     return JSON.stringify({
         status: "timeout",
         message: `Extension not ready after ${timeout}ms this call`,
         readyPath,
         waitDuration: Date.now() - start,
         clamped: clamped ? `requested ${requested}ms was clamped to ${SAFE_CEILING_MS}ms to stay under the MCP client request timeout` : void 0,
-        hint: "Still building — call extension_wait again to keep waiting (it resumes polling the same contract). If it never readies, check the dev process with extension_doctor."
+        hint: "Still building, call extension_wait again to keep waiting (it resumes polling the same contract). If it never readies, check the dev process with extension_doctor."
     });
 }
 const add_feature_schema = {
@@ -4864,135 +5969,27 @@ 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.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            projectPath: {
-                type: "string",
-                description: "Path to the extension project root. Omit for a pre-flight environment check with no project."
-            },
-            browser: {
-                type: "string",
-                description: "Browser session to diagnose. Defaults to the active dev session's browser for this project."
-            }
-        }
-    }
-};
-async function environmentPreflight() {
-    const checks = [];
-    const nodeMajor = Number(process.versions.node.split(".")[0]);
-    checks.push({
-        check: "node",
-        status: nodeMajor >= 20 ? "pass" : "fail",
-        detail: `Node ${process.versions.node} on ${process.platform}/${process.arch}`,
-        remediation: nodeMajor >= 20 ? void 0 : "Extension.js needs Node >= 20.18."
-    });
-    const { code, stdout, stderr } = await runExtensionCli([
-        "--version"
-    ], {
-        timeoutMs: 60000
-    });
-    const cliVersion = stdout.trim() || stderr.trim();
-    checks.push({
-        check: "extension-cli",
-        status: 0 === code ? "pass" : "fail",
-        detail: 0 === code ? `extension CLI resolvable (${cliVersion})` : "extension CLI could not be resolved",
-        remediation: 0 === code ? void 0 : "Install locally (npm i -D extension) or rely on npx; check network access to the npm registry."
-    });
-    const cacheFile = node_path.join(node_os.homedir(), ".cache", "extension-js", "templates-meta.json");
-    const cacheExists = node_fs.existsSync(cacheFile);
-    checks.push({
-        check: "template-cache",
-        status: cacheExists ? "pass" : "warn",
-        detail: cacheExists ? `Template catalog cached at ${cacheFile}` : "Template catalog not cached yet (first extension_list_templates will fetch it)"
-    });
-    const healthy = checks.every((c)=>"fail" !== c.status);
-    return JSON.stringify({
-        mode: "environment",
-        healthy,
-        checks,
-        hint: "Pass projectPath to diagnose a live dev session end-to-end."
-    });
-}
-async function doctor_handler(args) {
-    if (!args.projectPath) return environmentPreflight();
-    const projectPath = args.projectPath;
-    const { browser } = resolveSessionBrowser(projectPath, args.browser);
-    const { code, stdout, stderr } = await runExtensionCli([
-        "doctor",
-        projectPath,
-        "--browser",
-        browser,
-        "--output",
-        "json"
-    ], {
-        cwd: projectPath
-    });
-    const out = stdout.trim();
-    try {
-        const checks = JSON.parse(out);
-        if (!Array.isArray(checks)) throw new Error("not a check array");
-        for (const check of checks){
-            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."
-            });
-        }
-        return JSON.stringify({
-            browser,
-            healthy,
-            checks
-        });
-    } catch  {
-        const message = stderr.trim() || `extension exited with code ${code}`;
-        return JSON.stringify({
-            ok: false,
-            error: {
-                name: "CliError",
-                message: toMcpSpeak(message),
-                hint: "extension doctor requires a recent extension CLI — the project's local install may predate it."
-            }
-        });
-    }
-}
 function typeOf(value) {
     if (Array.isArray(value)) return "array";
     if (null === value) return "null";
     return typeof value;
 }
 function checkPrimitive(path, value, schema, issues) {
-    if (schema.type && [
-        "string",
-        "number",
-        "boolean"
-    ].includes(schema.type)) {
-        if (typeOf(value) !== schema.type) return void issues.push({
+    const allowed = void 0 === schema.type ? [] : Array.isArray(schema.type) ? schema.type : [
+        schema.type
+    ];
+    const primitives = allowed.filter((t)=>[
+            "string",
+            "number",
+            "boolean"
+        ].includes(t));
+    if (primitives.length > 0 && primitives.length === allowed.length) {
+        if (!primitives.includes(typeOf(value))) return void issues.push({
             path,
-            message: `expected ${schema.type}, got ${typeOf(value)}`
+            message: `expected ${primitives.join(" or ")}, got ${typeOf(value)}`
         });
     }
-    if ("array" === schema.type) {
+    if (allowed.includes("array")) {
         if (!Array.isArray(value)) return void issues.push({
             path,
             message: `expected array, got ${typeOf(value)}`
@@ -5035,7 +6032,28 @@ const ARG_ALIASES = {
         "manifest"
     ],
     surface: [
-        "view"
+        "view",
+        "target"
+    ],
+    timeout: [
+        "timeoutMs",
+        "timeoutMillis"
+    ],
+    limit: [
+        "lines",
+        "count",
+        "max",
+        "maxLines"
+    ],
+    tab: [
+        "tabId"
+    ],
+    url: [
+        "href",
+        "pageUrl"
+    ],
+    browser: [
+        "browserName"
     ]
 };
 function normalizeArgAliases(inputSchema, args) {