@extension.dev/mcp 5.3.1 → 5.5.0

package/dist/module.js

@@ -68,6 +68,7 @@ var eval_namespaceObject = {};
 __webpack_require__.r(eval_namespaceObject);
 __webpack_require__.d(eval_namespaceObject, {
     handler: ()=>eval_handler,
+    resolveDefaultEvalContext: ()=>resolveDefaultEvalContext,
     schema: ()=>eval_schema
 });
 var get_template_source_namespaceObject = {};
@@ -210,7 +211,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"5.3.1","El":{"OP":"^4.0.13"}}');
+var package_namespaceObject = JSON.parse('{"rE":"5.5.0","El":{"OP":"^4.0.13"}}');
 function scaffoldEnginePin(projectPath) {
     try {
         const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
@@ -623,6 +624,185 @@ function spawnExtensionCli(args, options) {
         }
     };
 }
+const sessions = new Map();
+function sessionKey(projectPath, browser) {
+    return `${node_path.resolve(projectPath)}::${browser}`;
+}
+function markerDir() {
+    return process.env.EXTENSION_MCP_SESSION_DIR || node_path.join(node_os.tmpdir(), "extension-dev-mcp-sessions");
+}
+function markerPath(projectPath, browser) {
+    const digest = node_crypto.createHash("sha1").update(sessionKey(projectPath, browser)).digest("hex").slice(0, 16);
+    return node_path.join(markerDir(), `${digest}.json`);
+}
+function removeSessionMarker(projectPath, browser) {
+    try {
+        node_fs.rmSync(markerPath(projectPath, browser), {
+            force: true
+        });
+    } catch  {}
+}
+function listSessionMarkers() {
+    let files;
+    try {
+        files = node_fs.readdirSync(markerDir());
+    } catch  {
+        return [];
+    }
+    const out = [];
+    for (const file of files)if (file.endsWith(".json")) try {
+        const parsed = JSON.parse(node_fs.readFileSync(node_path.join(markerDir(), file), "utf8"));
+        if ("string" == typeof parsed?.projectPath && "string" == typeof parsed?.browser) out.push(parsed);
+    } catch  {}
+    return out;
+}
+function registerSession(info) {
+    sessions.set(sessionKey(info.projectPath, info.browser), info);
+    try {
+        node_fs.mkdirSync(markerDir(), {
+            recursive: true
+        });
+        node_fs.writeFileSync(markerPath(info.projectPath, info.browser), JSON.stringify({
+            ...info,
+            projectPath: node_path.resolve(info.projectPath),
+            registeredAt: new Date().toISOString()
+        }));
+    } catch  {}
+}
+function getSession(projectPath, browser) {
+    return sessions.get(sessionKey(projectPath, browser));
+}
+function findSessionInfo(projectPath, browser) {
+    const inMemory = sessions.get(sessionKey(projectPath, browser));
+    if (inMemory) return inMemory;
+    const resolved = node_path.resolve(projectPath);
+    for (const marker of listSessionMarkers())if (node_path.resolve(marker.projectPath) === resolved && marker.browser === browser) return marker;
+}
+function removeSession(projectPath, browser) {
+    sessions.delete(sessionKey(projectPath, browser));
+}
+function listSessions() {
+    return Array.from(sessions.values());
+}
+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 liveProjectSessions(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const out = new Map();
+    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) {
+        if (pidAlive(session.pid)) out.set(session.browser, {
+            browser: session.browser,
+            pid: session.pid,
+            source: "registry"
+        });
+    }
+    for (const sighting of contractSightings(projectPath))if (void 0 !== sighting.pid && pidAlive(sighting.pid)) {
+        if (!out.has(sighting.browser)) out.set(sighting.browser, {
+            browser: sighting.browser,
+            pid: sighting.pid,
+            source: "contract"
+        });
+    }
+    return [
+        ...out.values()
+    ];
+}
+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 contractBoundPort(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"));
+        return "number" == typeof contract?.port && Number.isFinite(contract.port) ? contract.port : null;
+    } 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"
+    };
+}
 function readBuildSummary(projectPath, browser, since) {
     const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "build-summary.json");
     try {
@@ -678,6 +858,46 @@ function builtEntrypoints(distDir) {
     });
     return out;
 }
+function engineSanitize(input) {
+    return input.toLowerCase().replace(/[^a-z0-9 ]/gi, "").trim().replace(/\s+/g, "-");
+}
+function newestZip(dir, since, match) {
+    try {
+        const fresh = node_fs.readdirSync(dir).filter((name)=>name.endsWith(".zip") && (!match || match(name))).map((name)=>{
+            const full = node_path.join(dir, name);
+            return {
+                full,
+                mtimeMs: node_fs.statSync(full).mtimeMs
+            };
+        }).filter((entry)=>entry.mtimeMs >= since).sort((a, b)=>b.mtimeMs - a.mtimeMs);
+        return fresh[0]?.full ?? null;
+    } catch  {
+        return null;
+    }
+}
+function engineZipBase(distDir, projectPath) {
+    let manifest = {};
+    try {
+        manifest = JSON.parse(node_fs.readFileSync(node_path.join(distDir, "manifest.json"), "utf8"));
+    } catch  {}
+    const rawName = "string" != typeof manifest.name || /^__MSG_.+__$/.test(manifest.name) ? node_path.basename(node_path.resolve(projectPath)) : manifest.name;
+    const version = "string" == typeof manifest.version && manifest.version ? manifest.version : "0.0.0";
+    return `${engineSanitize(rawName)}-${version}`;
+}
+function locateDistZip(projectPath, browser, zipFilename, since) {
+    const distDir = node_path.resolve(projectPath, "dist", browser);
+    const base = zipFilename ? engineSanitize(zipFilename) : engineZipBase(distDir, projectPath);
+    const expected = node_path.join(distDir, `${base}.zip`);
+    if (node_fs.existsSync(expected)) return expected;
+    return newestZip(distDir, since);
+}
+function locateSourceZip(projectPath, browser, since) {
+    const distDir = node_path.resolve(projectPath, "dist", browser);
+    const distRoot = node_path.resolve(projectPath, "dist");
+    const expected = node_path.join(distRoot, `${engineZipBase(distDir, projectPath)}-source.zip`);
+    if (node_fs.existsSync(expected)) return expected;
+    return newestZip(distRoot, since, (name)=>name.endsWith("-source.zip"));
+}
 const build_schema = {
     name: "extension_build",
     description: "Build a browser extension for production. Outputs to dist/<browser>/. Optionally creates .zip for store submission.",
@@ -816,6 +1036,8 @@ async function build_handler(args) {
         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 clobberedSessions = liveProjectSessions(args.projectPath).filter((session)=>session.browser === browser);
+    const warnings = clobberedSessions.map((session)=>`A live dev session (pid ${session.pid}) is running on this project for ${browser}, and this build wrote over its dist/${browser} output. The dev browser may now serve the production artifact instead of the dev build until the next recompile. Run extension_stop, or let dev recompile on the next source change, to resolve it.`);
     const cliArgs = [
         "build",
         args.projectPath,
@@ -858,6 +1080,9 @@ async function build_handler(args) {
                 manifestWarnings: preflight.warnings
             } : {},
             ...buildWarnings,
+            ...warnings.length ? {
+                warnings
+            } : {},
             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."
@@ -884,7 +1109,26 @@ async function build_handler(args) {
                     productionDivergence: divergence
                 } : {};
             })(),
+            ...warnings.length ? {
+                warnings
+            } : {},
             zip: args.zip ?? false,
+            ...args.zip ? (()=>{
+                const zipPath = locateDistZip(args.projectPath, browser, args.zipFilename, start);
+                return zipPath ? {
+                    zipPath
+                } : {
+                    zipPathNote: `zip: true was requested and the build succeeded, but no .zip file could be located in dist/${browser}. The engine may not have packaged it; check the build output below.`
+                };
+            })() : {},
+            ...args.zipSource ? (()=>{
+                const zipSourcePath = locateSourceZip(args.projectPath, browser, start);
+                return zipSourcePath ? {
+                    zipSourcePath
+                } : {
+                    zipSourcePathNote: "zipSource: true was requested and the build succeeded, but no *-source.zip file could be located in dist/. The engine may not have packaged it; check the build output below."
+                };
+            })() : {},
             duration,
             output: lastLines(out, 12)
         });
@@ -894,172 +1138,13 @@ async function build_handler(args) {
         success: false,
         browser,
         error: message.slice(0, 1200),
+        ...warnings.length ? {
+            warnings
+        } : {},
         duration,
         hint: "Check that the project has a valid src/manifest.json and its dependencies are installed (extension_dev auto-installs; build does not)."
     });
 }
-const sessions = new Map();
-function sessionKey(projectPath, browser) {
-    return `${node_path.resolve(projectPath)}::${browser}`;
-}
-function markerDir() {
-    return process.env.EXTENSION_MCP_SESSION_DIR || node_path.join(node_os.tmpdir(), "extension-dev-mcp-sessions");
-}
-function markerPath(projectPath, browser) {
-    const digest = node_crypto.createHash("sha1").update(sessionKey(projectPath, browser)).digest("hex").slice(0, 16);
-    return node_path.join(markerDir(), `${digest}.json`);
-}
-function removeSessionMarker(projectPath, browser) {
-    try {
-        node_fs.rmSync(markerPath(projectPath, browser), {
-            force: true
-        });
-    } catch  {}
-}
-function listSessionMarkers() {
-    let files;
-    try {
-        files = node_fs.readdirSync(markerDir());
-    } catch  {
-        return [];
-    }
-    const out = [];
-    for (const file of files)if (file.endsWith(".json")) try {
-        const parsed = JSON.parse(node_fs.readFileSync(node_path.join(markerDir(), file), "utf8"));
-        if ("string" == typeof parsed?.projectPath && "string" == typeof parsed?.browser) out.push(parsed);
-    } catch  {}
-    return out;
-}
-function registerSession(info) {
-    sessions.set(sessionKey(info.projectPath, info.browser), info);
-    try {
-        node_fs.mkdirSync(markerDir(), {
-            recursive: true
-        });
-        node_fs.writeFileSync(markerPath(info.projectPath, info.browser), JSON.stringify({
-            ...info,
-            projectPath: node_path.resolve(info.projectPath),
-            registeredAt: new Date().toISOString()
-        }));
-    } catch  {}
-}
-function getSession(projectPath, browser) {
-    return sessions.get(sessionKey(projectPath, browser));
-}
-function removeSession(projectPath, browser) {
-    sessions.delete(sessionKey(projectPath, browser));
-}
-function listSessions() {
-    return Array.from(sessions.values());
-}
-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 liveProjectSessions(projectPath) {
-    const resolved = node_path.resolve(projectPath);
-    const out = new Map();
-    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) {
-        if (pidAlive(session.pid)) out.set(session.browser, {
-            browser: session.browser,
-            pid: session.pid,
-            source: "registry"
-        });
-    }
-    for (const sighting of contractSightings(projectPath))if (void 0 !== sighting.pid && pidAlive(sighting.pid)) {
-        if (!out.has(sighting.browser)) out.set(sighting.browser, {
-            browser: sighting.browser,
-            pid: sighting.pid,
-            source: "contract"
-        });
-    }
-    return [
-        ...out.values()
-    ];
-}
-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 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.",
@@ -1380,7 +1465,8 @@ async function dev_handler(args) {
         browser,
         port: args.port,
         projectPath: args.projectPath,
-        command: "dev"
+        command: "dev",
+        noBrowser: Boolean(args.noBrowser)
     });
     child.on("exit", ()=>removeSession(args.projectPath, browser));
     await new Promise((resolve)=>setTimeout(resolve, 3000));
@@ -1437,11 +1523,30 @@ async function dev_handler(args) {
         allowEval: Boolean(args.allowEval),
         unlocked: allowControl ? args.allowEval ? `${controlVerbs}, eval` : controlVerbs : "none (read-only: logs, source_inspect, wait, doctor)"
     };
+    const boundPort = contractBoundPort(args.projectPath, browser, spawnedAt);
+    if (null !== boundPort && boundPort !== args.port) registerSession({
+        pid,
+        browser,
+        port: boundPort,
+        projectPath: args.projectPath,
+        command: "dev",
+        noBrowser: Boolean(args.noBrowser)
+    });
+    const portReport = null !== boundPort ? {
+        port: boundPort,
+        ...void 0 !== args.port && args.port !== boundPort ? {
+            requestedPort: args.port,
+            portNote: `Requested port ${args.port} was not available; the dev server bound ${boundPort} (read from the engine's ready.json contract, the same source extension_wait reports).`
+        } : {}
+    } : {
+        requestedPort: args.port ?? 8080,
+        portNote: "The engine has not stamped its ready.json contract yet, so the bound port is not known at response time (a taken port makes the server bind the next free one). extension_wait reports the bound port from that contract once it lands; requestedPort above is only what was asked for."
+    };
     return JSON.stringify({
         ok: true,
         pid,
         browser,
-        port: args.port ?? 8080,
+        ...portReport,
         projectPath: args.projectPath,
         status: "started",
         ...replaced.length > 0 ? {
@@ -1451,7 +1556,7 @@ async function dev_handler(args) {
             } : {}
         } : {},
         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). To unlock them, call extension_dev again with the flag you need plus replace: true (it stops this session first); a plain second call is refused so the session does not fork.") + " When you are done, call extension_stop to shut down the dev server and browser.",
+        hint: args.noBrowser ? "Build-only session (noBrowser: true): no browser will launch, so no runtime will ever attach. extension_wait returns as soon as the first compile lands (compiled: true, browserAttached: false) instead of waiting out its budget; do not wait for a browser. The control verbs (storage/reload/open/dom_inspect/eval) need a live browser and will not work against this session. When you are done, call extension_stop to shut down the dev server." : "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). To unlock them, call extension_dev again with the flag you need plus replace: true (it stops this session first); a plain second call is refused so the session does not fork.") + " When you are done, call extension_stop to shut down the dev server and browser.",
         earlyOutput: denoiseEarlyOutput(earlyOutput).slice(0, 500),
         logPath
     });
@@ -1463,7 +1568,10 @@ function denoiseEarlyOutput(raw) {
         /^npm warn config/i,
         /V8: .*Invalid asm\.js/i,
         /^\(node:\d+\) V8:/i,
-        /Use `node --trace-warnings/i
+        /Use `node --trace-warnings/i,
+        /Invalid asm\.js:/i,
+        /Linking failure in asm\.js/i,
+        /Successfully compiled asm\.js/i
     ];
     return raw.split("\n").filter((line)=>!NOISE.some((re)=>re.test(line.trim()))).join("\n").replace(/\n{2,}/g, "\n").trimStart();
 }
@@ -2307,6 +2415,9 @@ function walkDir(dir, base = "") {
                 else if ([
                     ".map"
                 ].includes(ext)) type = "sourcemap";
+                else if ([
+                    ".zip"
+                ].includes(ext)) type = "archive";
                 entries.push({
                     path: rel,
                     size: stat.size,
@@ -2347,7 +2458,8 @@ async function inspect_handler(args) {
     }
     const sourcemapSize = byType.sourcemap?.size ?? 0;
     const buildType = sourcemapSize > 0 ? "development" : "production";
-    const shippableSize = totalSize - sourcemapSize;
+    const archiveSize = byType.archive?.size ?? 0;
+    const shippableSize = totalSize - sourcemapSize - archiveSize;
     const sizeByPath = new Map(files.map((f)=>[
             f.path,
             f.size
@@ -2377,7 +2489,7 @@ 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) {
+    for (const f of files)if ("sourcemap" !== f.type && "archive" !== 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.`);
     }
@@ -2397,6 +2509,9 @@ async function inspect_handler(args) {
         ..."development" === buildType ? {
             note: `This dist contains ${formatBytes(sourcemapSize)} of sourcemaps and looks like a dev build; run extension_build for production sizes. shippableSize excludes sourcemaps.`
         } : {},
+        ...archiveSize > 0 ? {
+            archiveNote: `This dist contains ${formatBytes(archiveSize)} of .zip archive(s) (store packaging output, written into dist by zip builds). shippableSize excludes them so the packaged copy does not double-count the files it contains.`
+        } : {},
         manifest: {
             name: manifest.name,
             version: manifest.version,
@@ -2429,7 +2544,7 @@ async function inspect_handler(args) {
             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
+            under10MB: totalSize - archiveSize < 10485760
         }
     };
     return JSON.stringify(result);
@@ -3065,7 +3180,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). The entry for THIS dev session's extension (the project being served) is flagged ownExtension: true, with name and version resolved from the session's ready contract even when the browser exposes no identity. Other extensions resolve via the read-only Extensions domain when available; their contexts are never attached to or evaluated in, so an id that the domain does not describe stays id-only with a note saying why. 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: {
@@ -3083,6 +3198,47 @@ const list_extensions_schema = {
         ]
     }
 };
+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;
+}
+function readOwnIdentity(projectPath, browser) {
+    let contract;
+    try {
+        const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+        contract = JSON.parse(node_fs.readFileSync(file, "utf8"));
+    } catch  {
+        return null;
+    }
+    const distPath = "string" == typeof contract?.distPath ? contract.distPath : null;
+    const ids = [];
+    if (distPath) {
+        ids.push(unpackedExtensionId(distPath));
+        try {
+            const real = node_fs.realpathSync(distPath);
+            if (real !== distPath) ids.push(unpackedExtensionId(real));
+        } catch  {}
+    }
+    let name = "string" == typeof contract?.extensionName ? contract.extensionName : void 0;
+    let version = "string" == typeof contract?.extensionVersion ? contract.extensionVersion : void 0;
+    if ((!name || !version) && distPath) try {
+        const manifest = JSON.parse(node_fs.readFileSync(node_path.join(distPath, "manifest.json"), "utf8"));
+        if (!name && "string" == typeof manifest?.name && !manifest.name.startsWith("__MSG_")) name = manifest.name;
+        if (!version && "string" == typeof manifest?.version) version = manifest.version;
+    } catch  {}
+    if (0 === ids.length && !name) return null;
+    return {
+        ids,
+        name,
+        version
+    };
+}
+const UNRESOLVED_NOTE = "Identity unresolved: the browser's Extensions CDP domain returned nothing for this id, and other extensions' contexts are never attached to or evaluated in to read a manifest.";
 async function list_extensions_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
     if (!isChromiumFamily(browser)) return JSON.stringify({
@@ -3123,6 +3279,7 @@ async function list_extensions_handler(args) {
             });
             byId.set(id, list);
         }
+        const own = readOwnIdentity(args.projectPath, browser);
         const extensions = [];
         for (const [id, ctxTargets] of byId){
             const entry = {
@@ -3143,15 +3300,33 @@ async function list_extensions_handler(args) {
                     entry.source = "extensions-domain";
                 }
             } catch  {}
+            if (own?.ids.includes(id)) {
+                entry.ownExtension = true;
+                if (void 0 === entry.name && void 0 !== own.name) {
+                    entry.name = own.name;
+                    if (void 0 !== own.version) entry.version = own.version;
+                    entry.source = "session-contract";
+                }
+            }
             extensions.push(entry);
         }
-        extensions.sort((a, b)=>(a.name ?? a.id).localeCompare(b.name ?? b.id));
+        if (own?.name && !extensions.some((e)=>e.ownExtension)) {
+            const byName = extensions.filter((e)=>e.name === own.name);
+            if (1 === byName.length) byName[0].ownExtension = true;
+        }
+        for (const entry of extensions)if (void 0 === entry.name) entry.note = UNRESOLVED_NOTE;
+        extensions.sort((a, b)=>{
+            if ((a.ownExtension ?? false) !== (b.ownExtension ?? false)) return a.ownExtension ? -1 : 1;
+            return (a.name ?? a.id).localeCompare(b.name ?? b.id);
+        });
+        const ownEntry = extensions.find((e)=>e.ownExtension);
         return JSON.stringify({
             cdpPort,
             browser,
             count: extensions.length,
+            ownExtensionId: ownEntry?.id ?? null,
             extensions,
-            note: "Lists extensions that currently have at least one live context (service worker or open page). An MV3 service worker that has gone dormant with no open page may be absent until it wakes. Identity is read read-only via the Extensions domain; other extensions' contexts are never attached to or evaluated in."
+            note: "Lists extensions that currently have at least one live context (service worker or open page). An MV3 service worker that has gone dormant with no open page may be absent until it wakes. ownExtension marks the extension this dev session serves, identified from the session's ready contract. Other identity is read read-only via the Extensions domain; other extensions' contexts are never attached to or evaluated in."
         });
     } catch (error) {
         return JSON.stringify({
@@ -3483,7 +3658,7 @@ 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(/--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");
+    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(/Use --context page --tab <id>/g, 'Use context: "page" (targets the active tab; pass url or tab to pick another)').replace(/--context[= ](background|popup|options|sidebar|devtools|newtab|history|bookmarks|content|page)\b/g, 'context: "$1"').replace(/--tab[= ](\d+|<[\w-]+>)/g, "tab: $1").replace(/--url[= ]"([^"]+)"/g, 'url: "$1"').replace(/--url[= ](<[\w-]+>|\S*(?:\/\/|\*)\S*)/g, 'url: "$1"').replace(/--browser[= ]([\w]+-based|chrome|chromium|edge|brave|opera|vivaldi|yandex|firefox|waterfox|librewolf|safari)\b/g, 'browser: "$1"').replace(/--timeout[= ](\d+)/g, "timeout: $1").replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev").replace(/--tab\b/g, "`tab`").replace(/--url\b/g, "`url`").replace(/--context\b/g, "`context`").replace(/--browser\b/g, "`browser`").replace(/--timeout\b/g, "`timeout`");
 }
 function withSessionContext(message, projectPath) {
     const isControlError = /no active control channel|control channel refused|\b1006\b|no executor connected|is the session started with allowControl/i.test(message);
@@ -3536,7 +3711,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). 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`.",
+    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). Context default: on a Chromium session whose manifest is MV3 (the default template) the default is `page` (the active tab), because the MV3 background is a service worker whose CSP blocks eval, so a background default would fail on the most common path; on Firefox/MV2 sessions the default stays `background`. Pass `context: \"background\"` explicitly to target the worker anyway (on Chromium MV3 that returns the CSP explanation). 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). Use extension_dom_inspect with listTabs: true to enumerate {tabId,url,title}. Wraps `extension eval`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -3562,8 +3737,7 @@ const eval_schema = {
                     "content",
                     "page"
                 ],
-                default: "background",
-                description: "Which extension surface to evaluate in"
+                description: "Which extension surface to evaluate in. Default: `background`, EXCEPT on Chromium sessions whose manifest is MV3, where the default is `page` (the active tab) because the MV3 service worker CSP blocks eval; pass `context: \"background\"` explicitly to target the worker anyway."
             },
             url: {
                 type: "string",
@@ -3588,14 +3762,38 @@ const eval_schema = {
         ]
     }
 };
+function resolveDefaultEvalContext(projectPath, browser) {
+    if (!isChromiumFamily(browser)) return "background";
+    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 version = manifest["chromium:manifest_version"] ?? manifest.manifest_version;
+        if (3 === version) return "page";
+        if (2 === version) break;
+    }
+    return "background";
+}
 async function eval_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    const defaulted = !args.context && "page" === resolveDefaultEvalContext(args.projectPath, browser);
+    const context = defaulted ? "page" : args.context;
     const raw = await runActVerb([
         "eval",
         args.expression,
         args.projectPath,
         ...commonFlags({
             ...args,
+            context,
             browser
         })
     ], args.projectPath, args.timeout);
@@ -3606,6 +3804,15 @@ async function eval_handler(args) {
             return JSON.stringify(parsed);
         }
     } catch  {}
+    if (defaulted) try {
+        const parsed = JSON.parse(raw);
+        if (parsed && "object" == typeof parsed) {
+            parsed.defaultedContext = "page";
+            parsed.contextNote = 'No context given: defaulted to "page" (the active tab) because this Chromium session\'s MV3 background is a service worker whose CSP blocks eval. Pass context: "background" explicitly to target the worker (works on Firefox/MV2 builds).';
+            if (false === parsed.ok && /cannot access|chrome-extension:\/\/|chrome:\/\//i.test(JSON.stringify(parsed.error ?? ""))) parsed.hint = "The active tab is a browser or extension page that eval cannot reach. Navigate the dev browser to a regular web page, or pass url (match pattern) or tab to pick one; extension_dom_inspect with listTabs: true lists open tabs.";
+            return JSON.stringify(parsed);
+        }
+    } catch  {}
     return raw;
 }
 const storage_schema = {
@@ -3834,7 +4041,7 @@ async function navigateToUrl(projectPath, browser, url) {
         } catch  {}
     }
 }
-function unpackedExtensionId(distPath) {
+function open_unpackedExtensionId(distPath) {
     const digest = node_crypto.createHash("sha256").update(distPath).digest();
     let id = "";
     for(let i = 0; i < 16; i++){
@@ -3845,7 +4052,7 @@ function unpackedExtensionId(distPath) {
 }
 async function resolveExtensionId(projectPath, browser) {
     const distPath = readDistPath(projectPath, browser);
-    const computed = distPath ? unpackedExtensionId(distPath) : null;
+    const computed = distPath ? open_unpackedExtensionId(distPath) : null;
     const resolved = await resolveCdpPort(projectPath, browser);
     if (!resolved) return computed;
     const ids = new Set();
@@ -3909,6 +4116,57 @@ function surfaceDocument(projectPath, browser, surface) {
     }
     return null;
 }
+const SURFACE_MANIFEST_KEYS = {
+    popup: "action.default_popup",
+    options: "options_ui.page (or options_page)",
+    sidebar: "side_panel.default_path (or sidebar_action.default_panel)",
+    newtab: "chrome_url_overrides.newtab",
+    history: "chrome_url_overrides.history",
+    bookmarks: "chrome_url_overrides.bookmarks"
+};
+function declaredSurfaces(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")
+    ];
+    const readable = candidates.some((file)=>{
+        try {
+            JSON.parse(node_fs.readFileSync(file, "utf8"));
+            return true;
+        } catch  {
+            return false;
+        }
+    });
+    if (!readable) return null;
+    return Object.keys(SURFACE_MANIFEST_KEYS).filter((s)=>null !== surfaceDocument(projectPath, browser, s));
+}
+function missingSurfaceError(projectPath, browser, surface, consequence) {
+    const declared = declaredSurfaces(projectPath, browser);
+    if (null === declared) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "NoSurfaceDocument",
+            message: `No readable manifest was found for this project (checked dist/${browser}, dist, src, and the project root), so the ${surface} document cannot be resolved.`
+        },
+        hint: "Check projectPath, or build the project first (extension_build)."
+    });
+    const key = SURFACE_MANIFEST_KEYS[surface] ?? surface;
+    const others = declared.filter((s)=>s !== surface);
+    const nextVerb = "popup" === surface ? 'To exercise the toolbar button of a popup-less extension, call extension_open with surface: "action", which replays chrome.action.onClicked. To give the extension a popup, set action.default_popup in the manifest and rebuild.' : `To add one, set ${key} in the manifest and rebuild.`;
+    return JSON.stringify({
+        ok: false,
+        error: {
+            name: "NoSurfaceDocument",
+            message: `This extension declares no ${surface}: nothing in its manifest sets ${key}, ${consequence}. That is how the extension is built, not a failure of the session or the tooling.`
+        },
+        ...others.length ? {
+            declaredSurfaces: others
+        } : {},
+        hint: (others.length ? `Surfaces this extension does declare: ${others.join(", ")}; extension_open can target those. ` : "The manifest declares no other UI surface documents either. ") + nextVerb
+    });
+}
 const POPUP_MIN = 25;
 const POPUP_MAX_WIDTH = 800;
 const POPUP_MAX_HEIGHT = 600;
@@ -3967,14 +4225,7 @@ async function applyPopupBounds(projectPath, browser, targetId) {
 }
 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."
-    });
+    if (!doc) return missingSurfaceError(projectPath, browser, surface, "so there is no page to render as a tab");
     const id = await resolveExtensionId(projectPath, browser);
     if (!id) return JSON.stringify({
         ok: false,
@@ -4087,6 +4338,10 @@ async function open_handler(args) {
             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."
         });
     }
+    if ("popup" === args.surface) {
+        const declared = declaredSurfaces(args.projectPath, browser);
+        if (declared && !declared.includes("popup")) return missingSurfaceError(args.projectPath, browser, "popup", "so there is no popup to open");
+    }
     const cli = [
         "open",
         args.surface,
@@ -4110,20 +4365,38 @@ async function open_handler(args) {
                 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.";
+                        parsedFallback.note = "The dev browser is headless (EXTENSION_HEADLESS=1), and a real popup/sidebar window can only open in a headed session, so the surface was rendered as a tab instead. For the real window, start a headed session: extension_dev with replace: true, with EXTENSION_HEADLESS=0 (or unset) in the environment, then open the surface again without asTab.";
                         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.";
+            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=1), and a popup/sidebar window needs a headed session. Retry with asTab: true to render the surface document in a tab, or start a headed session for the real window: extension_dev with replace: true, with EXTENSION_HEADLESS=0 (or unset) in the environment.";
             return JSON.stringify(parsed);
         }
     } catch  {}
     return raw;
 }
+const TARGET_ID_NOTE = "targetId is a CDP target id, NOT a chrome.tabs id: do not pass it as `tab`. Target a tab with `tabUrl` (URL substring) or `url`; if you need a numeric tab id, call extension_dom_inspect with listTabs: true.";
+function filterPageTargets(raw) {
+    return raw.filter((t)=>"page" === t.type && !String(t.url ?? "").startsWith("devtools://")).map((t)=>({
+            targetId: String(t.id),
+            type: String(t.type),
+            url: String(t.url ?? ""),
+            title: String(t.title ?? "")
+        }));
+}
+async function listPageTargets(port) {
+    return filterPageTargets(await CDPClient.discoverTargets(port));
+}
+function matchTargetsByUrl(targets, needle) {
+    const wanted = needle.toLowerCase();
+    const byUrl = targets.filter((t)=>t.url.toLowerCase().includes(wanted));
+    if (byUrl.length > 0) return byUrl;
+    return targets.filter((t)=>t.title.toLowerCase().includes(wanted));
+}
 const dom_inspect_schema = {
     name: "extension_dom_inspect",
-    description: "Inspect a page/content-script DOM via the agent bridge (CDP-free, localhost). Returns a structured snapshot (counts, extension roots, open shadow roots, optional capped HTML). Requires the dev session to be started with allowControl: true (extension_dev). For closed shadow roots or deep CDP inspection use extension_source_inspect. Wraps `extension inspect`.",
+    description: "Inspect a page/content-script DOM via the agent bridge (CDP-free, localhost). Returns a structured snapshot (counts, extension roots, open shadow roots, optional capped HTML). Target a tab by `tabUrl` (case-insensitive URL substring resolved against the browser's live page targets; zero or several matches return the candidates instead of guessing), by `url`, or by numeric `tab`. Discover what is open with listTargets: true (CDP targetIds) or listTabs: true (numeric chrome.tabs ids). Requires the dev session to be started with allowControl: true (extension_dev). For closed shadow roots or deep CDP inspection use extension_source_inspect. Wraps `extension inspect`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -4139,6 +4412,15 @@ const dom_inspect_schema = {
                 type: "string",
                 description: "For content/page: selects the target tab by url (match pattern, then substring fallback). Preferred over `tab`."
             },
+            tabUrl: {
+                type: "string",
+                description: "Target the tab whose URL contains this substring (case-insensitive; titles are checked only when no url matches). Resolved against the live browser's CDP page targets BEFORE inspecting: exactly one match proceeds; zero or several matches return the candidate targets (targetId/url/title) so you can narrow, never a guess. Chromium sessions only; on Firefox use `url`/`tab`. Alternative to `url`."
+            },
+            listTargets: {
+                type: "boolean",
+                default: false,
+                description: "Enumerate the browser's CDP page targets as {targetId,url,title,type} and return, ignoring the other args. The discovery path for `tabUrl`. targetId is a CDP target id, NOT a numeric chrome.tabs id (for those use listTabs)."
+            },
             listTabs: {
                 type: "boolean",
                 default: false,
@@ -4199,8 +4481,55 @@ const dom_inspect_schema = {
         ]
     }
 };
+async function cdpPortOrError(projectPath, browser, feature) {
+    if (!isChromiumFamily(browser)) return {
+        error: JSON.stringify({
+            ok: false,
+            error: {
+                name: "Unsupported",
+                message: `${feature} reads the browser's CDP page targets, which ${browser} (Gecko) does not expose. Target the tab with \`url\` or \`tab\` instead, and discover tabs with listTabs: true (agent bridge, works on every browser).`
+            }
+        })
+    };
+    const resolved = await resolveCdpPort(projectPath, browser);
+    if (!resolved) return {
+        error: JSON.stringify({
+            ok: false,
+            error: {
+                name: "NoSession",
+                message: `No active dev session / CDP port for ${browser}, so ${feature} has no browser to ask. Start extension_dev and extension_wait for ready. ${CDP_PORT_MISSING_HINT}`
+            }
+        })
+    };
+    return {
+        port: resolved.port
+    };
+}
 async function dom_inspect_handler(args) {
     const withConsole = true === args.withConsole ? 50 : false === args.withConsole ? void 0 : args.withConsole;
+    if (args.listTargets) {
+        const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+        const cdp = await cdpPortOrError(args.projectPath, browser, "listTargets");
+        if ("error" in cdp) return cdp.error;
+        try {
+            const targets = await listPageTargets(cdp.port);
+            return JSON.stringify({
+                ok: true,
+                browser,
+                targets,
+                note: TARGET_ID_NOTE
+            });
+        } catch (e) {
+            return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "CdpError",
+                    message: `Could not list page targets: ${e instanceof Error ? e.message : String(e)}`
+                },
+                hint: "Confirm the session is ready (extension_wait), then retry. listTabs: true is the CDP-free alternative."
+            });
+        }
+    }
     if (args.listTabs) return runActVerb([
         "inspect",
         args.projectPath,
@@ -4212,19 +4541,78 @@ async function dom_inspect_handler(args) {
             String(args.timeout)
         ] : []
     ], args.projectPath, args.timeout);
+    let targetUrl = args.url;
+    let resolvedTarget = null;
+    if (args.tabUrl) {
+        if (null != args.tab || args.url) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "BadRequest",
+                message: "Pass ONE tab selector: `tabUrl` (URL substring, resolved against live targets), `url` (engine-side match), or `tab` (numeric chrome.tabs id), not several."
+            }
+        });
+        const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+        const cdp = await cdpPortOrError(args.projectPath, browser, "tabUrl");
+        if ("error" in cdp) return cdp.error;
+        let targets;
+        try {
+            targets = await listPageTargets(cdp.port);
+        } catch (e) {
+            return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "CdpError",
+                    message: `Could not list page targets to resolve tabUrl: ${e instanceof Error ? e.message : String(e)}`
+                },
+                hint: "Confirm the session is ready (extension_wait), then retry, or target with `url`/`tab` instead."
+            });
+        }
+        const matches = matchTargetsByUrl(targets, args.tabUrl);
+        if (0 === matches.length) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NoMatchingTarget",
+                message: `No open page target's url (or title) contains "${args.tabUrl}" (case-insensitive).`
+            },
+            availableTargets: targets,
+            hint: `Pick one from availableTargets and retry with a \`tabUrl\` substring of its url, or open the page first (extension_open with \`url\`). ${TARGET_ID_NOTE}`
+        });
+        if (matches.length > 1) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "AmbiguousTabUrl",
+                message: `${matches.length} page targets match "${args.tabUrl}"; refusing to guess which tab you mean.`
+            },
+            matchingTargets: matches,
+            hint: `Narrow \`tabUrl\` to a longer substring that matches exactly one url in matchingTargets. ${TARGET_ID_NOTE}`
+        });
+        resolvedTarget = matches[0];
+        targetUrl = resolvedTarget.url;
+    }
     const cli = [
         "inspect",
         args.projectPath
     ];
     if (null != args.tab) cli.push("--tab", String(args.tab));
-    if (args.url) cli.push("--url", args.url);
+    if (targetUrl) cli.push("--url", targetUrl);
     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 != 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);
+    const raw = await runActVerb(cli, args.projectPath, args.timeout);
+    if (!resolvedTarget) return raw;
+    try {
+        const parsed = JSON.parse(raw);
+        parsed.resolvedTarget = {
+            ...resolvedTarget,
+            matchedBy: "tabUrl"
+        };
+        return JSON.stringify(parsed);
+    } catch  {
+        return raw;
+    }
 }
 function credentialsPath() {
     if ("win32" === process.platform) {
@@ -5227,6 +5615,8 @@ async function doctor_handler(args) {
     }
 }
 const SAFE_CEILING_MS = 50000;
+const DEFAULT_TIMEOUT_MS = 45000;
+const MIN_TIMEOUT_MS = 1000;
 function wait_isAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -5237,7 +5627,7 @@ function wait_isAlive(pid) {
 }
 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).",
+    description: "Wait for a running dev or start session to be ready. Polls the ready.json contract file and returns structured status with two separate facts: compiled (the compiler finished) and browserAttached (the extension's runtime connected from a live browser). Every result reports budgetMs (this call's wait budget) and elapsedMs; on status:'timeout' call again to keep waiting (polling resumes on the same contract). In a noBrowser (build-only) session it returns as soon as the compile lands instead of waiting for a browser that will never attach. Ports in the result come from the ready contract, so they always match what the dev server actually bound.",
     inputSchema: {
         type: "object",
         properties: {
@@ -5249,10 +5639,14 @@ const wait_schema = {
                 type: "string",
                 description: "Browser to check readiness for. Defaults to the active dev session's browser for this project."
             },
+            timeoutMs: {
+                type: "number",
+                default: DEFAULT_TIMEOUT_MS,
+                description: `Wait budget in milliseconds for this call. Default ${DEFAULT_TIMEOUT_MS}; clamped to ${MIN_TIMEOUT_MS}-${SAFE_CEILING_MS} (the ceiling keeps one call under the MCP client's 60s request timeout). On timeout the result reports elapsedMs plus what was observed (compiled, browserAttached); call again to keep waiting, polling resumes on the same contract.`
+            },
             timeout: {
                 type: "number",
-                default: 45000,
-                description: "Requested wait in milliseconds. Clamped to ~50s per call so it never exceeds the MCP client request timeout; call again to keep waiting for slower builds."
+                description: "Deprecated alias of timeoutMs, kept for callers that already pass it. timeoutMs wins when both are given."
             }
         },
         required: [
@@ -5262,26 +5656,47 @@ const wait_schema = {
 };
 async function wait_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
-    const requested = args.timeout ?? 45000;
-    const timeout = Math.min(Math.max(requested, 1000), SAFE_CEILING_MS);
+    const requested = args.timeoutMs ?? args.timeout ?? DEFAULT_TIMEOUT_MS;
+    const budgetMs = Math.min(Math.max(requested, MIN_TIMEOUT_MS), SAFE_CEILING_MS);
     const clamped = requested > SAFE_CEILING_MS;
     const readyPath = node_path.resolve(args.projectPath, "dist", "extension-js", browser, "ready.json");
+    const buildOnly = findSessionInfo(args.projectPath, browser)?.noBrowser === true;
     const start = Date.now();
     const pollInterval = 1000;
     let sawCompiledButUnattached = false;
-    while(Date.now() - start < timeout){
+    let lastContractStatus = null;
+    while(Date.now() - start < budgetMs){
         try {
             const raw = node_fs.readFileSync(readyPath, "utf8");
             const contract = JSON.parse(raw);
+            lastContractStatus = contract.status;
             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
+                    budgetMs,
+                    elapsedMs: Date.now() - start
                 });
                 const attached = "attached" === contract.runtime || "string" == typeof contract.executorAttachedAt;
+                if (!attached && buildOnly) return JSON.stringify({
+                    status: "ready",
+                    buildOnly: true,
+                    compiled: true,
+                    browserAttached: false,
+                    message: "Build-only session (noBrowser): the extension compiled and the dev server is live, but no browser was launched, so browserAttached will never become true. Do not call extension_wait again to wait for a browser. The control verbs (storage/reload/open/dom_inspect/eval) need a live browser and will not work against this session.",
+                    command: contract.command,
+                    browser: contract.browser,
+                    port: contract.port,
+                    pid: contract.pid,
+                    distPath: contract.distPath,
+                    manifestPath: contract.manifestPath,
+                    compiledAt: contract.compiledAt,
+                    startedAt: contract.startedAt,
+                    budgetMs,
+                    elapsedMs: Date.now() - start
+                });
                 if (!attached) {
                     await new Promise((r)=>setTimeout(r, pollInterval));
                     sawCompiledButUnattached = true;
@@ -5290,6 +5705,8 @@ async function wait_handler(args) {
                 const runtimeErrors = recentErrorLogs(args.projectPath, browser, 3);
                 return JSON.stringify({
                     status: "ready",
+                    compiled: true,
+                    browserAttached: true,
                     command: contract.command,
                     browser: contract.browser,
                     port: contract.port,
@@ -5298,7 +5715,8 @@ async function wait_handler(args) {
                     manifestPath: contract.manifestPath,
                     compiledAt: contract.compiledAt,
                     startedAt: contract.startedAt,
-                    waitDuration: Date.now() - start,
+                    budgetMs,
+                    elapsedMs: 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.`
@@ -5311,23 +5729,30 @@ async function wait_handler(args) {
                 errors: contract.errors,
                 code: contract.code,
                 browser: contract.browser,
-                waitDuration: Date.now() - start
+                budgetMs,
+                elapsedMs: Date.now() - start
             });
         } 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".`,
+        compiled: true,
+        browserAttached: false,
+        message: `The extension compiled, but the runtime executor never attached within this call's ${budgetMs}ms budget. 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,
+        budgetMs,
+        elapsedMs: 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`,
+        compiled: false,
+        browserAttached: false,
+        message: "starting" === lastContractStatus ? `Not ready after ${budgetMs}ms this call: the dev server stamped its contract (status: starting) but the first compile has not landed yet.` : `Not ready after ${budgetMs}ms this call: no ready contract was observed at ${readyPath}, so neither the compile nor a browser attach has been seen.`,
         readyPath,
-        waitDuration: Date.now() - start,
+        budgetMs,
+        elapsedMs: 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."
     });
@@ -5936,7 +6361,7 @@ async function login_handler(args) {
 }
 const whoami_schema = {
     name: "extension_whoami",
-    description: "Report the locally stored extension.dev login (workspace/project and token expiry) without revealing the token. Returns logged-out status when no credentials are stored.",
+    description: "Report the identity carried by the locally stored extension.dev token that extension_login minted (workspace/project scoped), plus its expiry, without revealing the token. The identity comes from that stored token alone; it does not change with the current working directory or whichever project folder you are in. Returns logged-out status when no credentials are stored.",
     inputSchema: {
         type: "object",
         properties: {}
@@ -5961,7 +6386,7 @@ async function whoami_handler() {
         expiresAt: creds.expiresAt ? new Date(1000 * creds.expiresAt).toISOString() : null,
         expiresInSeconds: creds.expiresAt ? creds.expiresAt - now : null,
         expired,
-        message: expired ? "Stored token has expired. Run extension_login to refresh it." : `Logged in to ${creds.workspaceSlug}/${creds.projectSlug}.`
+        message: expired ? "The stored token has expired. Run extension_login to refresh it." : `Logged in as ${creds.workspaceSlug}/${creds.projectSlug}, per the token extension_login stored on this machine. That token is what scopes the identity: it does not follow the current working directory or project folder.`
     });
 }
 const logout_schema = {