@extension.dev/mcp 5.6.1 → 6.0.0

package/dist/module.js

@@ -7,7 +7,8 @@ import node_path, { join } from "node:path";
 import { extensionCreate } from "extension-create";
 import node_os from "node:os";
 import cross_spawn from "cross-spawn";
-import node_crypto from "node:crypto";
+import node_crypto, { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { execFile, execFileSync } from "node:child_process";
 import { filterKeysForThisBrowser } from "browser-extension-manifest-fields";
 import ws_0 from "ws";
@@ -137,7 +138,8 @@ __webpack_require__.r(open_namespaceObject);
 __webpack_require__.d(open_namespaceObject, {
     clampPopupBounds: ()=>clampPopupBounds,
     handler: ()=>open_handler,
-    schema: ()=>open_schema
+    schema: ()=>open_schema,
+    sessionIsHeadless: ()=>sessionIsHeadless
 });
 var preview_namespaceObject = {};
 __webpack_require__.r(preview_namespaceObject);
@@ -220,7 +222,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"5.6.1","El":{"OP":"^4.0.15"}}');
+var package_namespaceObject = JSON.parse('{"rE":"5.7.0","El":{"OP":"4.0.16-canary.1784889479.74e12044"}}');
 function scaffoldEnginePin(projectPath) {
     try {
         const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
@@ -387,10 +389,85 @@ async function create_handler(args) {
         }
     });
 }
+const DEFAULT_MEDIA_ORIGIN = "https://media.extension.land";
+const DEFAULT_CHANNEL = "latest";
+const PINNED_COMMIT = "2d2ed9668cca002148d9eecd953a08b54d0bad9d";
+const CHANNEL_CACHE_TTL_MS = 300000;
+function mediaOrigin() {
+    return (process.env.EXTENSION_MEDIA_ORIGIN || "").trim() || DEFAULT_MEDIA_ORIGIN;
+}
+function channelName() {
+    return (process.env.EXTENSION_TEMPLATES_CHANNEL || "").trim() || DEFAULT_CHANNEL;
+}
+function pinnedCommitOverride() {
+    return (process.env.EXTENSION_TEMPLATES_COMMIT || "").trim();
+}
+function rawBaseForCommit(commit) {
+    return `https://raw.githubusercontent.com/extension-js/examples/${commit}`;
+}
+let releaseCache = null;
+let releaseCacheExpiresAt = 0;
+let releaseRequest = null;
+function releaseForCommit(origin, commit) {
+    return {
+        commit,
+        metaUrl: `${origin}/templates/${commit}/templates-meta.json`,
+        filesBaseUrl: `${origin}/templates/${commit}/files`
+    };
+}
+async function resolveRelease() {
+    const now = Date.now();
+    if (releaseCache && now < releaseCacheExpiresAt) return releaseCache;
+    if (releaseRequest) return releaseRequest;
+    const origin = mediaOrigin();
+    const override = pinnedCommitOverride();
+    if (override) {
+        releaseCache = releaseForCommit(origin, override);
+        releaseCacheExpiresAt = now + CHANNEL_CACHE_TTL_MS;
+        return releaseCache;
+    }
+    releaseRequest = (async ()=>{
+        try {
+            const pointerUrl = `${origin}/templates/${channelName()}.json`;
+            const response = await fetch(pointerUrl, {
+                headers: {
+                    Accept: "application/json"
+                }
+            });
+            if (!response.ok) return null;
+            const pointer = await response.json();
+            const commit = String(pointer?.commit || "").trim();
+            if (!commit) return null;
+            releaseCache = releaseForCommit(origin, commit);
+            releaseCacheExpiresAt = Date.now() + CHANNEL_CACHE_TTL_MS;
+            return releaseCache;
+        } catch  {
+            return null;
+        }
+    })();
+    try {
+        return await releaseRequest;
+    } finally{
+        releaseRequest = null;
+    }
+}
+async function templateMetaUrls() {
+    const urls = [];
+    const release = await resolveRelease();
+    if (release) urls.push(release.metaUrl);
+    urls.push(`${rawBaseForCommit(PINNED_COMMIT)}/templates-meta.json`);
+    return urls;
+}
+async function templateFileUrls(slug, relativePath) {
+    const urls = [];
+    const release = await resolveRelease();
+    if (release) urls.push(`${release.filesBaseUrl}/${slug}/${relativePath}`);
+    urls.push(`${rawBaseForCommit(PINNED_COMMIT)}/examples/${slug}/${relativePath}`);
+    return urls;
+}
 const CACHE_DIR = node_path.join(node_os.homedir(), ".cache", "extension-js");
 const CACHE_FILE = node_path.join(CACHE_DIR, "templates-meta.json");
 const CACHE_TTL_MS = 3600000;
-const TEMPLATES_META_URL = "https://github.com/extension-js/examples/releases/download/nightly/templates-meta.json";
 function isCacheValid() {
     try {
         const stat = node_fs.statSync(CACHE_FILE);
@@ -404,17 +481,22 @@ async function fetchTemplatesMeta() {
         const cached = JSON.parse(node_fs.readFileSync(CACHE_FILE, "utf8"));
         return cached;
     }
-    const response = await fetch(TEMPLATES_META_URL);
-    if (!response.ok) {
-        if (node_fs.existsSync(CACHE_FILE)) return JSON.parse(node_fs.readFileSync(CACHE_FILE, "utf8"));
-        throw new Error(`Failed to fetch templates-meta.json: ${response.status}`);
-    }
-    const data = await response.json();
-    node_fs.mkdirSync(CACHE_DIR, {
-        recursive: true
-    });
-    node_fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
-    return data;
+    let lastStatus = 0;
+    for (const url of (await templateMetaUrls()))try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            lastStatus = response.status;
+            continue;
+        }
+        const data = await response.json();
+        node_fs.mkdirSync(CACHE_DIR, {
+            recursive: true
+        });
+        node_fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2));
+        return data;
+    } catch  {}
+    if (node_fs.existsSync(CACHE_FILE)) return JSON.parse(node_fs.readFileSync(CACHE_FILE, "utf8"));
+    throw new Error(`Failed to fetch templates-meta.json (${lastStatus || "network error"}).`);
 }
 async function listTemplates(filters) {
     const meta = await fetchTemplatesMeta();
@@ -854,6 +936,180 @@ function resolveSessionBrowser(projectPath, explicit, fallback = "chrome") {
         source: "fallback"
     };
 }
+const CHROMIUM_FAMILY = new Set([
+    "chrome",
+    "chromium",
+    "edge",
+    "brave",
+    "opera",
+    "vivaldi",
+    "yandex",
+    "chromium-based"
+]);
+const GECKO_FAMILY = new Set([
+    "firefox",
+    "waterfox",
+    "librewolf",
+    "gecko-based",
+    "firefox-based"
+]);
+const WEBKIT_FAMILY = new Set([
+    "safari",
+    "webkit-based"
+]);
+function isChromiumFamily(browser) {
+    return CHROMIUM_FAMILY.has(browser);
+}
+function isGeckoFamily(browser) {
+    return GECKO_FAMILY.has(browser);
+}
+const CARRIER_DIR_NAME = "extension-dev-live-preview";
+const CARRIER_EXTENSION_ID = "ibppeifnekhjjjmpjfiobccjlicbmgcb";
+const MARKER_FILE = "managed-by-extension-dev-mcp.json";
+function deriveCarrierId(source) {
+    try {
+        const manifest = JSON.parse(node_fs.readFileSync(node_path.join(source, "manifest.json"), "utf-8"));
+        if (!manifest.key) return null;
+        const hash = createHash("sha256").update(Buffer.from(manifest.key, "base64")).digest();
+        return [
+            ...hash.subarray(0, 16)
+        ].map((byte)=>String.fromCharCode(97 + (byte >> 4)) + String.fromCharCode(97 + (15 & byte))).join("");
+    } catch  {
+        return null;
+    }
+}
+function carrierPath(projectPath) {
+    return node_path.join(projectPath, "extensions", CARRIER_DIR_NAME);
+}
+function removeCarrier(projectPath) {
+    const target = carrierPath(projectPath);
+    if (!node_fs.existsSync(target)) return {
+        removed: false,
+        path: target
+    };
+    if (!node_fs.existsSync(node_path.join(target, MARKER_FILE))) return {
+        removed: false,
+        path: target,
+        note: `extensions/${CARRIER_DIR_NAME} has no ${MARKER_FILE} marker, so it is not the carrier this tool placed and was left untouched.`
+    };
+    try {
+        node_fs.rmSync(target, {
+            recursive: true,
+            force: true
+        });
+    } catch (error) {
+        return {
+            removed: false,
+            path: target,
+            note: `Could not remove the carrier: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+    const parent = node_path.join(projectPath, "extensions");
+    try {
+        if (0 === node_fs.readdirSync(parent).length) node_fs.rmdirSync(parent);
+    } catch  {}
+    return {
+        removed: true,
+        path: target
+    };
+}
+function ensureCarrierIgnored(projectPath) {
+    if (!node_fs.existsSync(node_path.join(projectPath, ".git"))) return null;
+    const entry = `extensions/${CARRIER_DIR_NAME}/`;
+    const file = node_path.join(projectPath, ".gitignore");
+    let current = "";
+    try {
+        current = node_fs.readFileSync(file, "utf-8");
+    } catch  {}
+    const ignored = current.split("\n").map((line)=>line.trim()).some((line)=>line === entry || line === `extensions/${CARRIER_DIR_NAME}` || "extensions/" === line || "extensions" === line);
+    if (ignored) return null;
+    try {
+        const prefix = "" === current || current.endsWith("\n") ? "" : "\n";
+        node_fs.appendFileSync(file, `${prefix}\n# Extension.dev live-preview carrier: a local debug companion, not part of your extension.\n${entry}\n`);
+        return entry;
+    } catch  {
+        return null;
+    }
+}
+function findBundledCarrier(engine) {
+    let dir = node_path.dirname(fileURLToPath(import.meta.url));
+    for(let depth = 0; depth < 6; depth++){
+        const candidate = node_path.join(dir, "extensions", "live-preview", engine);
+        if (node_fs.existsSync(node_path.join(candidate, "manifest.json"))) return candidate;
+        const parent = node_path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    return null;
+}
+function materializeCarrier(projectPath, browser) {
+    if (!isChromiumFamily(browser)) return {
+        loaded: false,
+        note: `The live-preview carrier is Chromium-family only for now (requested: ${browser}). Firefox has no externally_connectable channel for web pages, so the carrier pairing cannot work there.`
+    };
+    const source = findBundledCarrier("chromium");
+    if (!source) return {
+        loaded: false,
+        note: "This install ships no bundled carrier payload (extensions/live-preview/chromium missing from the package)."
+    };
+    const target = carrierPath(projectPath);
+    const marker = node_path.join(target, MARKER_FILE);
+    if (node_fs.existsSync(target) && !node_fs.existsSync(marker)) return {
+        loaded: false,
+        path: target,
+        note: `A directory already exists at extensions/${CARRIER_DIR_NAME} without the ${MARKER_FILE} marker, so it is not managed by this tool and was left untouched. Remove or rename it to let extension_dev place the carrier there.`
+    };
+    const carrierId = deriveCarrierId(source);
+    try {
+        node_fs.rmSync(target, {
+            recursive: true,
+            force: true
+        });
+        node_fs.cpSync(source, target, {
+            recursive: true
+        });
+        const manifest = JSON.parse(node_fs.readFileSync(node_path.join(source, "manifest.json"), "utf-8"));
+        node_fs.writeFileSync(marker, `${JSON.stringify({
+            managedBy: "@extension.dev/mcp",
+            carrierVersion: manifest.version ?? "unknown",
+            note: "Safe to delete; extension_dev recreates it when carrier: true. extension_stop and extension_build remove it for you."
+        }, null, 2)}\n`);
+        const ignored = ensureCarrierIgnored(projectPath);
+        return {
+            loaded: true,
+            path: target,
+            ...ignored ? {
+                gitignored: ignored
+            } : {},
+            note: "Live-preview carrier placed in ./extensions; Extension.js loads it as a companion beside your extension. Open https://inspect.extension.dev/?session=live in the dev browser (any http://localhost origin works too) to watch the session's real-lane chrome.* trace on the Trace tab. It is a debug companion, never part of a release: extension_stop and extension_build remove it again" + (ignored ? `, and ${ignored} was added to .gitignore.` : "."),
+            limitations: [
+                "The trace shows calls a PAGE bridges to the carrier. Your extension's own chrome.* calls run directly in its contexts and never cross the carrier, so they do not appear.",
+                "Bridged calls run under the CARRIER's identity, not your extension's. The preview assumes a single active guest and does not namespace per-extension state, so storage, action/badge state, messaging delivery, offscreen documents and relative script paths belong to the carrier. Rows affected are badged carrier-scoped in the Trace tab.",
+                "Chromium-family only: Firefox has no externally_connectable channel for web pages."
+            ],
+            graduation: "The carrier lane is the SHARED real lane: bridged calls run as the carrier, by design (see limitations). Your guest is already loaded as ITSELF in this same session, so for its own storage, identity, badge and messaging (the isolated real thing), drive the guest directly instead of the carrier bridge: extension_storage, extension_eval and extension_dom_inspect against this projectPath all operate on the guest as itself. Start (or replace) this session with allowControl: true (or allowEval: true) to unlock them. Use the carrier bridge for the shared real-lane TRACE; use the control verbs for the guest's OWN state.",
+            ...carrierId ? {
+                bridgeProtocol: {
+                    carrierExtensionId: carrierId,
+                    allowedOrigins: "https://inspect.extension.dev, https://intelligence.extension.dev, https://themes.extension.dev, http://localhost/*, http://127.0.0.1/*",
+                    howTo: "From a page on an allowed origin, register your guest once with a 'session' message (it declares the permissions the carrier enforces), then send 'bridge' messages to run chrome.* for real; each one streams into the Trace tab. Use the EXACT dotted wire names the bridge dispatcher accepts: storage is storage.get/set/remove/clear with the AREA AS AN ARGUMENT, NOT storage.local.get.",
+                    example: [
+                        `const id = '${carrierId}'`,
+                        "const send = (msg) => new Promise((r) => chrome.runtime.sendMessage(id, msg, r))",
+                        "await send({ type: 'extensiondev:session', extensionId: 'my-guest', permissions: ['storage'] })",
+                        "await send({ type: 'extensiondev:bridge', request: { type: 'EXTENSION_BRIDGE_REQUEST', extensionId: 'my-guest', requestId: 'r1', api: 'storage.get', args: [null, 'local'] } })"
+                    ].join("\n")
+                }
+            } : {}
+        };
+    } catch (error) {
+        return {
+            loaded: false,
+            path: target,
+            note: `Could not place the carrier: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+}
 function readBuildSummary(projectPath, browser, since) {
     const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "build-summary.json");
     try {
@@ -1052,6 +1308,27 @@ function manifestDivergence(projectPath, browser) {
     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;
 }
+const MARKER_FILE_NAME = "managed-by-extension-dev-mcp.json";
+function carrierEntriesInDist(distDir, depth = 0) {
+    if (depth > 3) return [];
+    let entries;
+    try {
+        entries = node_fs.readdirSync(distDir, {
+            withFileTypes: true
+        });
+    } catch  {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries){
+        if (entry.name === CARRIER_DIR_NAME || entry.name === MARKER_FILE_NAME) {
+            found.push(node_path.join(distDir, entry.name));
+            continue;
+        }
+        if (entry.isDirectory()) found.push(...carrierEntriesInDist(node_path.join(distDir, entry.name), depth + 1));
+    }
+    return found;
+}
 async function validationPreflight(projectPath, browser) {
     try {
         const manifestValidate = await Promise.resolve().then(()=>({
@@ -1076,6 +1353,10 @@ async function validationPreflight(projectPath, browser) {
 async function build_handler(args) {
     const start = Date.now();
     const browser = args.browser ?? "chrome";
+    const carrierCleanup = removeCarrier(args.projectPath);
+    const carrierNotes = [];
+    if (carrierCleanup.removed) carrierNotes.push("Removed the Extension.dev live-preview carrier from ./extensions before building. It is a debug companion, not part of your extension; run extension_dev with carrier: true to get it back.");
+    else if (carrierCleanup.note) carrierNotes.push(carrierCleanup.note);
     const preflight = args.skipValidation ? null : await validationPreflight(args.projectPath, browser);
     if (preflight?.buildBlocking) return JSON.stringify({
         success: false,
@@ -1083,12 +1364,15 @@ async function build_handler(args) {
         browser,
         error: "Build refused: the manifest has errors that produce a broken extension even when the bundler succeeds.",
         errors: preflight.errors,
-        warnings: preflight.warnings,
+        warnings: [
+            ...carrierNotes,
+            ...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 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 warnings = carrierNotes.concat(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,
@@ -1118,7 +1402,21 @@ async function build_handler(args) {
                 buildWarningsTruncated: engineSummary.warnings_count
             } : {}
         } : {};
-        const entrypoints = builtEntrypoints(node_path.resolve(args.projectPath, "dist", browser));
+        const distDir = node_path.resolve(args.projectPath, "dist", browser);
+        const entrypoints = builtEntrypoints(distDir);
+        const contamination = carrierEntriesInDist(distDir);
+        if (contamination.length) return JSON.stringify({
+            success: false,
+            status: "contaminated",
+            browser,
+            buildExitCode: 0,
+            error: `The build output contains the Extension.dev live-preview carrier: ${contamination.join(", ")}. That is a local debug companion and must never ship. This artifact is not safe to submit.`,
+            ...warnings.length ? {
+                warnings
+            } : {},
+            duration,
+            hint: "Delete the listed paths from dist and build again. The carrier normally lives in ./extensions and is removed before every build."
+        });
         const missing = entrypoints.filter((e)=>!e.present);
         if (missing.length) return JSON.stringify({
             success: false,
@@ -1198,7 +1496,7 @@ async function build_handler(args) {
 }
 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.",
+    description: "Stop a running dev, start, or preview session: terminates the dev server and the browser it launched, and removes the live-preview carrier if extension_dev placed one. Counterpart to extension_dev/extension_start. Call it when you are done verifying so sessions do not accumulate.",
     inputSchema: {
         type: "object",
         properties: {
@@ -1219,6 +1517,12 @@ const stop_schema = {
         required: []
     }
 };
+function cleanCarrier(projectPath) {
+    const removal = removeCarrier(projectPath);
+    return removal.removed ? {
+        carrierRemoved: removal.path
+    } : {};
+}
 function pgrepPids(pattern) {
     try {
         const out = execFileSync("pgrep", [
@@ -1295,6 +1599,7 @@ async function stopOne(projectPath, browser) {
             pid: null,
             stopped: 0 !== reaped.length,
             reaped,
+            ...cleanCarrier(projectPath),
             detail: 0 === reaped.length ? "No known session for this project/browser (nothing registered in this server and no ready.json contract found)." : `No dev pid on record, but reaped ${reaped.length} orphaned browser process(es) from the profile dir.`
         };
     }
@@ -1326,7 +1631,8 @@ async function stopOne(projectPath, browser) {
         pid,
         stopped,
         reaped,
-        detail
+        detail,
+        ...cleanCarrier(projectPath)
     };
 }
 async function stop_handler(args) {
@@ -1458,6 +1764,11 @@ const dev_schema = {
                 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."
+            },
+            carrier: {
+                type: "boolean",
+                default: false,
+                description: "Load the bundled Extension.dev Live Preview carrier beside your extension (Chromium-family browsers only). It is placed in the project's ./extensions folder, which Extension.js auto-loads; allowlisted pages (inspect.extension.dev, localhost) can then pair with the session and stream its real-lane chrome.* trace. Writes extensions/extension-dev-live-preview/ into the project, gitignores it, and takes it back out on extension_stop or extension_build: it is a debug companion, never part of a release."
             }
         },
         required: [
@@ -1492,6 +1803,7 @@ async function dev_handler(args) {
             });
         }
     }
+    const carrier = args.carrier ? materializeCarrier(args.projectPath, browser) : null;
     const allowControl = Boolean(args.allowControl || args.allowEval);
     const cliArgs = [
         "dev",
@@ -1522,6 +1834,7 @@ async function dev_handler(args) {
     child.on("exit", ()=>removeSession(args.projectPath, browser));
     await new Promise((resolve)=>setTimeout(resolve, 3000));
     const earlyOutput = spawned.readOutput();
+    const cleanOutput = denoiseEarlyOutput(earlyOutput);
     if (null !== child.exitCode || null !== child.signalCode) {
         const code = child.exitCode;
         const signal = child.signalCode;
@@ -1534,12 +1847,12 @@ async function dev_handler(args) {
             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),
+            output: cleanOutput.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);
+    const compileFailed = /compiled with errors|✖✖✖|ERROR in |Module not found|NOT FOUND/i.test(cleanOutput);
     if (compileFailed) return JSON.stringify({
         ok: false,
         status: "compile-failed",
@@ -1547,12 +1860,12 @@ async function dev_handler(args) {
         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),
+        output: cleanOutput.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 exitStamp = args.noBrowser ? null : browserExitStamp(args.projectPath, browser, spawnedAt);
-    const profileLockHit = !args.noBrowser && /SingletonLock|ProcessSingleton|profile[^\n]*(in use|locked)|already (open|running)/i.test(earlyOutput);
+    const profileLockHit = !args.noBrowser && /SingletonLock|ProcessSingleton|profile[^\n]*(in use|locked)|already (open|running)/i.test(cleanOutput);
     if (exitStamp || profileLockHit) {
         const profileDir = node_path.join(args.projectPath, "dist", `extension-profile-${browser}`);
         return JSON.stringify({
@@ -1563,7 +1876,7 @@ async function dev_handler(args) {
             pid,
             ...exitStamp ?? {},
             error: `The dev server is running but the ${browser} browser it launched died during startup` + (profileLockHit ? " because its profile is locked by another browser instance." : "."),
-            output: denoiseEarlyOutput(earlyOutput).slice(0, 2000),
+            output: cleanOutput.slice(0, 2000),
             logPath,
             hint: `A locked profile means another session's browser still holds it: call extension_stop with this projectPath to kill that session, then start extension_dev again. If the lock survives a crash, remove ${profileDir} manually before retrying.`
         });
@@ -1600,6 +1913,9 @@ async function dev_handler(args) {
         ...portReport,
         projectPath: args.projectPath,
         status: "started",
+        ...carrier ? {
+            carrier
+        } : {},
         ...replaced.length > 0 ? {
             replacedSession: replaced[0],
             ...replaced.length > 1 ? {
@@ -1608,7 +1924,7 @@ async function dev_handler(args) {
         } : {},
         capabilities,
         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),
+        earlyOutput: cleanOutput.slice(0, 500),
         logPath
     });
 }
@@ -1617,6 +1933,8 @@ function denoiseEarlyOutput(raw) {
         /^npm warn Unknown project config/i,
         /This will stop working in the next major version of npm/i,
         /^npm warn config/i,
+        /^npm warn exec/i,
+        /The following package(s)? (was|were) not found and will be installed/i,
         /V8: .*Invalid asm\.js/i,
         /^\(node:\d+\) V8:/i,
         /Use `node --trace-warnings/i,
@@ -1860,7 +2178,6 @@ async function preview_handler(args) {
         logPath
     });
 }
-const RAW_BASE = "https://raw.githubusercontent.com/extension-js/examples/main/examples";
 const get_template_source_schema = {
     name: "extension_get_template_source",
     description: "Read source files from a template in the extension.dev template catalog. Use this to learn implementation patterns before building something similar.",
@@ -1908,14 +2225,17 @@ async function get_template_source_handler(args) {
     const fileContents = {};
     const errors = [];
     await Promise.all(args.files.map(async (filePath)=>{
-        const url = `${RAW_BASE}/${args.slug}/${filePath}`;
-        try {
+        const urls = await templateFileUrls(args.slug, filePath);
+        let lastStatus = 0;
+        for (const url of urls)try {
             const response = await fetch(url);
-            if (response.ok) fileContents[filePath] = await response.text();
-            else errors.push(`${filePath}: ${response.status}`);
-        } catch (err) {
-            errors.push(`${filePath}: ${err instanceof Error ? err.message : "fetch failed"}`);
-        }
+            if (response.ok) {
+                fileContents[filePath] = await response.text();
+                return;
+            }
+            lastStatus = response.status;
+        } catch  {}
+        errors.push(`${filePath}: ${lastStatus || "fetch failed"}`);
     }));
     return JSON.stringify({
         ...meta,
@@ -1925,33 +2245,6 @@ async function get_template_source_handler(args) {
         } : {}
     });
 }
-const CHROMIUM_FAMILY = new Set([
-    "chrome",
-    "chromium",
-    "edge",
-    "brave",
-    "opera",
-    "vivaldi",
-    "yandex",
-    "chromium-based"
-]);
-const GECKO_FAMILY = new Set([
-    "firefox",
-    "waterfox",
-    "librewolf",
-    "gecko-based",
-    "firefox-based"
-]);
-const WEBKIT_FAMILY = new Set([
-    "safari",
-    "webkit-based"
-]);
-function isChromiumFamily(browser) {
-    return CHROMIUM_FAMILY.has(browser);
-}
-function isGeckoFamily(browser) {
-    return GECKO_FAMILY.has(browser);
-}
 const CHROME_DESKTOP_ONLY_KEYS = [
     "file_browser_handlers",
     "file_system_provider_capabilities",
@@ -2186,11 +2479,13 @@ const HARD_APIS = new Set([
     "pageCapture",
     "desktopCapture"
 ]);
-function scanApiUsage(roots) {
+function scanApiUsage(roots, excluded = []) {
     const used = new Set();
+    const skip = new Set(excluded.map((d)=>node_path.resolve(d)));
     let filesRead = 0;
     const walk = (dir, depth)=>{
         if (depth > 6 || filesRead > 300) return;
+        if (skip.has(node_path.resolve(dir))) return;
         let entries;
         try {
             entries = node_fs.readdirSync(dir, {
@@ -2296,7 +2591,7 @@ async function manifest_validate_handler(args) {
         ...view.permissions ?? [],
         ...view.optional_permissions ?? []
     ])if ("string" == typeof p) declaredPermSet.add(p);
-    const usedApis = scanApiUsage(roots);
+    const usedApis = scanApiUsage(roots, roots.map((r)=>node_path.join(r, "extensions")));
     for (const api of usedApis){
         const perm = API_PERMISSION[api];
         if (declaredPermSet.has(perm)) continue;
@@ -4669,27 +4964,40 @@ async function reload_handler(args) {
         })
     ], args.projectPath, args.timeout);
 }
-async function pollForTarget(port, url, budgetMs) {
+async function pollForTarget(port, url, budgetMs, navigatedTargetId) {
     const deadline = Date.now() + budgetMs;
     const wanted = url.replace(/#.*$/, "");
+    let redirected = null;
     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
-                    };
-                }
+                if ("page" !== t.type) continue;
+                const title = "string" == typeof t.title ? t.title : void 0;
+                if (tUrl === wanted || tUrl.startsWith(wanted)) return {
+                    id: String(t.id),
+                    url: tUrl,
+                    title
+                };
+                if (navigatedTargetId && String(t.id) === navigatedTargetId && tUrl && "about:blank" !== tUrl && !tUrl.startsWith("chrome-error://")) redirected = {
+                    id: String(t.id),
+                    url: tUrl,
+                    title,
+                    redirectedFrom: url
+                };
             }
         } catch  {}
-        if (Date.now() >= deadline) return null;
+        if (Date.now() >= deadline) return redirected;
         await new Promise((r)=>setTimeout(r, 250));
     }
 }
+function isDisposableTab(tabUrl, destination) {
+    if (!tabUrl || "about:blank" === tabUrl) return true;
+    if (/^chrome:\/\/(newtab|new-tab-page)/.test(tabUrl)) return true;
+    const origin = destination.match(/^chrome-extension:\/\/[a-p]{32}\//)?.[0];
+    return Boolean(origin && tabUrl.startsWith(origin));
+}
 async function navigateToUrl(projectPath, browser, url, timeout) {
     if (!isChromiumFamily(browser)) return navigateToUrlViaBridge(projectPath, browser, url, timeout);
     const resolved = await resolveCdpPort(projectPath, browser);
@@ -4704,30 +5012,49 @@ async function navigateToUrl(projectPath, browser, url, timeout) {
     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."
-        });
+        const reusable = pageTargets.find((t)=>isDisposableTab(String(t.url ?? ""), url));
+        let navigatedTargetId;
+        let openedNewTab = false;
+        if (reusable) {
+            navigatedTargetId = String(reusable.id);
+            const sessionId = await cdp.attachToTarget(navigatedTargetId);
+            await cdp.navigate(sessionId, url);
+        } else {
+            const created = await cdp.sendCommand("Target.createTarget", {
+                url,
+                background: true
+            }).catch(()=>cdp.sendCommand("Target.createTarget", {
+                    url
+                }));
+            navigatedTargetId = "string" == typeof created?.targetId ? created.targetId : void 0;
+            openedNewTab = true;
+        }
+        const settled = await pollForTarget(resolved.port, url, 6000, navigatedTargetId);
+        if (!settled) {
+            const isExtensionPage = url.startsWith("chrome-extension://");
+            return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "NavigateFailed",
+                    message: `Navigation to ${url} did not produce a live page target. ${isExtensionPage ? "The URL may not exist in the extension bundle, or Chrome refused the navigation." : "The page may have failed to load, or the browser refused the navigation."}`
+                },
+                hint: isExtensionPage ? "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." : "Confirm the URL loads in a normal browser and that the dev session's browser has network access. Nothing about your extension bundle is implicated in a failed http(s) navigation."
+            });
+        }
         return JSON.stringify({
             ok: true,
             navigated: url,
+            ...openedNewTab ? {
+                openedNewTab: true
+            } : {},
+            ...settled.redirectedFrom ? {
+                redirected: {
+                    from: settled.redirectedFrom,
+                    to: settled.url
+                }
+            } : {},
             target: {
                 targetId: settled.id,
                 title: settled.title,
@@ -4980,6 +5307,39 @@ async function openSurfaceAsTab(projectPath, browser, surface) {
     } catch  {}
     return raw;
 }
+async function confirmSurfaceTarget(projectPath, browser, surface, raw) {
+    if (!isChromiumFamily(browser)) return raw;
+    const doc = surfaceDocument(projectPath, browser, surface);
+    if (!doc) return raw;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch  {
+        return raw;
+    }
+    if (parsed?.ok === false) return raw;
+    const resolved = await resolveCdpPort(projectPath, browser);
+    const extensionId = resolved ? await resolveExtensionId(projectPath, browser) : null;
+    if (!resolved || !extensionId) return raw;
+    const wanted = `chrome-extension://${extensionId}/${doc}`;
+    const settled = await pollForTarget(resolved.port, wanted, 3000);
+    if (settled) {
+        parsed.surfaceTarget = {
+            targetId: settled.id,
+            url: settled.url
+        };
+        return JSON.stringify(parsed);
+    }
+    return JSON.stringify({
+        ok: false,
+        error: {
+            name: "SurfaceDidNotOpen",
+            message: `The engine reported the ${surface} as opened, but no page target for ${wanted} appeared within 3s, so nothing is there to inspect.`
+        },
+        engineResult: parsed,
+        hint: `Retry with asTab: true to render ${doc} in a real tab, which works headed or headless. If you expected a window, check that the session is headed and that the surface is declared in the BUILT manifest.`
+    });
+}
 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; '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`.",
@@ -5031,6 +5391,11 @@ const open_schema = {
         ]
     }
 };
+function sessionIsHeadless() {
+    if (/^(1|true)$/i.test(process.env.EXTENSION_HEADLESS ?? "")) return true;
+    return /(^|\s|=)-{1,2}headless\b/i.test(process.env.EXTENSION_BROWSER_FLAGS ?? "");
+}
+const HEADED_RELAUNCH = "start a headed session: extension_dev with replace: true, and in the environment set EXTENSION_HEADLESS=0 AND clear EXTENSION_BROWSER_FLAGS (it may carry --headless=new, which keeps the window hidden even with EXTENSION_HEADLESS=0)";
 async function open_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     if (args.url) return navigateToUrl(args.projectPath, browser, args.url, args.timeout);
@@ -5075,7 +5440,7 @@ async function open_handler(args) {
     cli.push("--browser", browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
     const raw = await runActVerb(cli, args.projectPath, args.timeout);
-    const headless = /^(1|true)$/i.test(process.env.EXTENSION_HEADLESS ?? "");
+    const headless = sessionIsHeadless();
     if (headless && [
         "popup",
         "action",
@@ -5089,16 +5454,16 @@ async function open_handler(args) {
                 try {
                     const parsedFallback = JSON.parse(fallback);
                     if (parsedFallback?.ok) {
-                        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.";
+                        parsedFallback.note = `The dev browser is headless, 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, ${HEADED_RELAUNCH}, 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=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.";
+            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, and a popup/sidebar window needs a headed session. Retry with asTab: true to render the surface document in a tab, or for the real window, ${HEADED_RELAUNCH}.`;
             return JSON.stringify(parsed);
         }
     } catch  {}
-    return raw;
+    return AS_TAB_SURFACES.includes(args.surface) ? confirmSurfaceTarget(args.projectPath, browser, args.surface, raw) : 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) {
@@ -5480,11 +5845,78 @@ function readValidCredentials(nowSeconds = Math.floor(Date.now() / 1000)) {
     if (creds.expiresAt && creds.expiresAt <= nowSeconds) return null;
     return creds;
 }
-const REGISTRY_BASE_DEFAULT = "https://registry.extension.land";
-const CONSOLE_BASE = "https://console.extension.dev";
+const PROD_ORIGINS = {
+    www: "https://www.extension.dev",
+    console: "https://console.extension.dev",
+    inspect: "https://inspect.extension.dev",
+    templates: "https://templates.extension.dev",
+    intelligence: "https://intelligence.extension.dev",
+    registry: "https://registry.extension.land",
+    media: "https://media.extension.land"
+};
+const DEV_LOCALHOST_ORIGINS = {
+    www: "http://localhost:3100",
+    console: "http://console.extension.localhost",
+    inspect: "http://inspect.extension.localhost",
+    templates: "http://templates.extension.localhost",
+    intelligence: "http://intelligence.extension.localhost",
+    registry: "https://registry.extension.land",
+    media: "https://media.extension.land"
+};
+function strip(value) {
+    return String(value ?? "").trim().replace(/\/+$/, "");
+}
+function isLocalOrigin(url) {
+    const raw = strip(url);
+    if (!raw) return false;
+    let host;
+    try {
+        host = new URL(raw).hostname;
+    } catch  {
+        return false;
+    }
+    return "localhost" === host || "127.0.0.1" === host || "::1" === host || "[::1]" === host || "extension.localhost" === host || host.endsWith(".extension.localhost");
+}
+function resolveOrigins(overrides = {}, opts = {}) {
+    const devLike = isLocalOrigin(overrides.www) || isLocalOrigin(overrides.console) || isLocalOrigin(opts.hint);
+    const base = devLike ? DEV_LOCALHOST_ORIGINS : PROD_ORIGINS;
+    const pick = (key)=>strip(overrides[key]) || base[key];
+    return {
+        www: pick("www"),
+        console: pick("console"),
+        inspect: pick("inspect"),
+        templates: pick("templates"),
+        intelligence: pick("intelligence"),
+        registry: pick("registry"),
+        media: pick("media")
+    };
+}
+const seg = (value)=>encodeURIComponent(String(value));
+function urls_paths_join(base, sub) {
+    if (!sub) return base;
+    return `${base}/${sub.replace(/^\/+/, "")}`;
+}
+function consoleProjectPath(ref, page = "") {
+    return urls_paths_join(`/${seg(ref.workspace)}/${seg(ref.project)}`, page);
+}
+PROD_ORIGINS.registry;
+function mcpOrigins(apiHint) {
+    const www = String(apiHint || process.env.EXTENSION_DEV_API_URL || "").trim() || void 0;
+    return resolveOrigins({
+        www,
+        console: process.env.EXTENSION_DEV_CONSOLE_URL,
+        inspect: process.env.EXTENSION_DEV_INSPECT_URL,
+        registry: process.env.EXTENSION_DEV_REGISTRY_URL,
+        media: process.env.EXTENSION_MEDIA_ORIGIN
+    }, {
+        hint: www
+    });
+}
+function consoleBase(apiHint) {
+    return mcpOrigins(apiHint).console;
+}
 function registryBase() {
-    const fromEnv = String(process.env.EXTENSION_DEV_REGISTRY_URL || "").trim();
-    return (fromEnv || REGISTRY_BASE_DEFAULT).replace(/\/+$/, "");
+    return mcpOrigins().registry;
 }
 function resolveProjectRef(overrides) {
     const workspace = String(overrides?.workspace || "").trim();
@@ -5505,9 +5937,10 @@ function resolveProjectRef(overrides) {
 function registryFileUrl(ref, file) {
     return `${registryBase()}/${encodeURIComponent(ref.workspace)}/${encodeURIComponent(ref.project)}/_extension-dev/${file}`;
 }
-function consoleProjectUrl(ref, page) {
-    if (!ref) return `${CONSOLE_BASE}`;
-    return `${CONSOLE_BASE}/${encodeURIComponent(ref.workspace)}/${encodeURIComponent(ref.project)}/${page}`;
+function consoleProjectUrl(ref, page, apiHint) {
+    const base = consoleBase(apiHint);
+    if (!ref) return base;
+    return `${base}${consoleProjectPath(ref, page)}`;
 }
 async function fetchRegistryJson(url, fetchImpl = fetch) {
     let res;
@@ -5583,12 +6016,12 @@ function parseBuildIndex(json) {
     }
     return out;
 }
-const DEFAULT_API = "https://www.extension.dev";
+const DEFAULT_API = PROD_ORIGINS.www;
 function tokenTtlNote(workspaceSlug, projectSlug) {
     const tokensUrl = workspaceSlug && projectSlug ? consoleProjectUrl({
         workspace: workspaceSlug,
         project: projectSlug
-    }, "settings/access-tokens") : CONSOLE_BASE;
+    }, "settings/access-tokens") : consoleBase();
     return `extension.dev CLI tokens live at most 7 days (server-enforced). CI pipelines must re-mint before expiry on the console's Access tokens page: ${tokensUrl}`;
 }
 function resolveApiBase(api) {
@@ -5829,7 +6262,6 @@ async function publish_handler(args) {
     }
     return JSON.stringify(data);
 }
-const release_promote_DEFAULT_API = "https://www.extension.dev";
 const release_promote_schema = {
     name: "extension_release_promote",
     description: "Promote a built extension to a release channel (e.g. stable, preview, beta) on extension.dev, headless. Auth-gated: uses your stored login (extension_login) or a release token in EXTENSION_DEV_TOKEN (mint and revoke it in the dashboard under project settings -> Access tokens; tokens live at most 7 days, so CI must re-mint before expiry). Posts to the platform's CLI release endpoint; the project is identified by the token. Cutting a version-bump PR is not available headlessly (it writes to your source repo and needs an interactive login).",
@@ -5889,7 +6321,7 @@ async function release_promote_handler(args) {
     const buildId = String(args.buildId || "").trim();
     const channel = String(args.channel || "").trim();
     if (!buildId || !channel) return release_promote_fail("ReleaseInputError", "buildId and channel are required.");
-    const apiCheck = safeApiBase(String(args.api || process.env.EXTENSION_DEV_API_URL || release_promote_DEFAULT_API));
+    const apiCheck = safeApiBase(resolveApiBase(args.api));
     if (!apiCheck.ok) return release_promote_fail("ReleaseConfigError", apiCheck.message);
     const url = `${apiCheck.base}/api/cli/release/promote`;
     const body = {
@@ -5927,7 +6359,7 @@ async function release_promote_handler(args) {
         const enrich = {};
         const ref = resolveProjectRef();
         if (404 === res.status || "UNKNOWN_BUILD" === code) {
-            enrich.buildsPageUrl = consoleProjectUrl(ref, "builds");
+            enrich.buildsPageUrl = consoleProjectUrl(ref, "builds", args.api);
             enrich.hint = "Run extension_release_list to see this project's channels, their promoted shas, and recent builds.";
             if (ref) {
                 const channelsUrl = registryFileUrl(ref, "channels.json");
@@ -6027,7 +6459,6 @@ async function release_list_handler(args) {
     if (!buildsRes.ok) result.buildsUnavailable = `builds/index.json unreadable: ${buildsRes.message}`;
     return JSON.stringify(result);
 }
-const deploy_DEFAULT_API = "https://www.extension.dev";
 function storeMdWarnings(browsers, cwd) {
     const wantsFirefox = browsers.includes("firefox");
     const wantsEdge = browsers.includes("edge");
@@ -6056,7 +6487,7 @@ function storeMdWarnings(browsers, cwd) {
 }
 const deploy_schema = {
     name: "extension_deploy",
-    description: "Submit a built extension to the Chrome Web Store, Firefox AMO, and/or Edge Add-ons THROUGH extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI. DEFAULTS TO A DRY RUN (preflight - dispatches nothing): the platform side verifies auth, the project, that the build exists, and the store workflow, and this tool then adds the per-store verdict from each store's public credential-health record; trust the per-store rows in the result over the platform's bare preflight line, which does not check store health. Pass dryRun:false to actually submit, which is irreversible and enters store review. The target project is identified by your token (extension_login or a release token in EXTENSION_DEV_TOKEN; tokens live at most 7 days, so CI must re-mint from the console's Access tokens page). Store credentials are never tool arguments and local files are not uploaded. Pass browsers + buildSha (extension_release_list lists valid shas); after a real submission, extension_store_status reads the recorded outcome and review state. Posts to the platform's CLI store-submission endpoint.",
+    description: "Submit a built extension to the Chrome Web Store, Firefox AMO, Edge Add-ons, and/or the App Store (Safari) THROUGH extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI. DEFAULTS TO A DRY RUN (preflight - dispatches nothing): the platform side verifies auth, the project, that the build exists, and the store workflow, and this tool then adds the per-store verdict from each store's public credential-health record; trust the per-store rows in the result over the platform's bare preflight line, which does not check store health. Pass dryRun:false to actually submit, which is irreversible and enters store review. The target project is identified by your token (extension_login or a release token in EXTENSION_DEV_TOKEN; tokens live at most 7 days, so CI must re-mint from the console's Access tokens page). Store credentials are never tool arguments and local files are not uploaded. Pass browsers + buildSha (extension_release_list lists valid shas); after a real submission, extension_store_status reads the recorded outcome and review state. Posts to the platform's CLI store-submission endpoint.",
     inputSchema: {
         type: "object",
         properties: {
@@ -6067,7 +6498,8 @@ const deploy_schema = {
                     enum: [
                         "chrome",
                         "firefox",
-                        "edge"
+                        "edge",
+                        "safari"
                     ]
                 },
                 description: "Stores to submit to."
@@ -6113,10 +6545,10 @@ 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; tokens live at most 7 days, so CI must re-mint before expiry).");
     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"]).');
+    if (0 === browsers.length) return deploy_fail("DeployInputError", 'browsers is required (e.g. ["chrome","firefox","edge","safari"]).');
     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));
+    const apiCheck = safeApiBase(resolveApiBase(args.api));
     if (!apiCheck.ok) return deploy_fail("DeployConfigError", apiCheck.message);
     const url = `${apiCheck.base}/api/cli/stores/submit`;
     const dryRun = false !== args.dryRun;
@@ -6161,7 +6593,7 @@ async function deploy_handler(args) {
     };
     if (dryRun) {
         const ref = resolveProjectRef();
-        const consoleStoresUrl = consoleProjectUrl(ref, "stores");
+        const consoleStoresUrl = consoleProjectUrl(ref, "stores", args.api);
         const storeModeNote = `Store publish mode (draft / skip-publish / live) is not readable with the CLI token, so it cannot be verified from here; check per-store settings at ${consoleStoresUrl}.`;
         let health = null;
         let healthUnreadable = null;
@@ -6236,11 +6668,12 @@ async function deploy_handler(args) {
 const KNOWN_STORES = [
     "chrome",
     "firefox",
-    "edge"
+    "edge",
+    "safari"
 ];
 const store_status_schema = {
     name: "extension_store_status",
-    description: "Report the project's browser-store state after an extension_deploy submission: per store (chrome, firefox, edge) whether it is configured, its latest credential health check, the last recorded submission (version, status, store URL, submitted-at), and the latest review status. Reads the project's public registry (registry.extension.land: stores/health.json, stores/status.json, stores/submissions.json) - read-only, dispatches nothing, no auth needed for public projects. Defaults to the logged-in project (extension_login); pass workspace + project to inspect another public project. Registry state can lag the store dashboards by up to a polling interval.",
+    description: "Report the project's browser-store state after an extension_deploy submission: per store (chrome, firefox, edge, safari) whether it is configured, its latest credential health check, the last recorded submission (version, status, store URL, submitted-at), and the latest review status. Reads the project's public registry (registry.extension.land: stores/health.json, stores/status.json, stores/submissions.json) - read-only, dispatches nothing, no auth needed for public projects. Defaults to the logged-in project (extension_login); pass workspace + project to inspect another public project. Registry state can lag the store dashboards by up to a polling interval.",
     inputSchema: {
         type: "object",
         properties: {
@@ -6436,6 +6869,63 @@ async function store_status_handler(args) {
     if (!submissionsRes.ok && 404 !== submissionsRes.status) result.submissionsUnavailable = `stores/submissions.json unreadable: ${submissionsRes.message}`;
     return JSON.stringify(result);
 }
+const ENGINE_COMPANION_IDS = new Set([
+    "kgdaecdpfkikjncaalnmmnjjfpofkcbl",
+    CARRIER_EXTENSION_ID
+]);
+const EXTENSION_URL = /^chrome-extension:\/\/([a-p]{32})\//i;
+async function verifyGuestLoaded(projectPath, browser, options) {
+    let cdpPort;
+    try {
+        const resolved = await resolveCdpPort(projectPath, browser, {
+            waitMs: options?.waitMs ?? 0
+        });
+        if (!resolved) return {
+            checked: false,
+            loaded: false,
+            guestTargets: [],
+            guestIds: [],
+            reason: "No CDP port in the session's ready contract, so the browser's target list could not be queried (a headless Chromium session still exposes one; a gecko/Firefox session does not)."
+        };
+        cdpPort = resolved.port;
+        const timeoutMs = options?.timeoutMs ?? 3000;
+        const targets = await Promise.race([
+            CDPClient.discoverTargets(cdpPort),
+            new Promise((_, reject)=>setTimeout(()=>reject(new Error(`CDP /json timed out after ${timeoutMs}ms`)), timeoutMs))
+        ]);
+        const guestTargets = [];
+        for (const t of targets){
+            const match = EXTENSION_URL.exec(String(t.url ?? ""));
+            if (!match) continue;
+            const id = match[1].toLowerCase();
+            if (!ENGINE_COMPANION_IDS.has(id)) guestTargets.push({
+                id,
+                type: String(t.type),
+                url: String(t.url)
+            });
+        }
+        const guestIds = [
+            ...new Set(guestTargets.map((t)=>t.id))
+        ];
+        return {
+            checked: true,
+            loaded: guestTargets.length > 0,
+            guestTargets,
+            guestIds,
+            cdpPort,
+            reason: guestTargets.length > 0 ? `The browser lists ${guestIds.length} extension target${1 === guestIds.length ? "" : "s"} that are not the engine companion (${guestIds.join(", ")}), so the guest is loaded.` : "The browser's target list has no chrome-extension:// target other than the engine's devtools companion. On Chrome this is the signature of a silently rejected --load-extension (extension.js BUGS_TO_FIX §83): the CLI and ready.json cannot see it."
+        };
+    } catch (err) {
+        return {
+            checked: false,
+            loaded: false,
+            guestTargets: [],
+            guestIds: [],
+            cdpPort,
+            reason: `Could not query the browser's target list${cdpPort ? ` on CDP port ${cdpPort}` : ""}: ${err?.message ?? String(err)}.`
+        };
+    }
+}
 function doctor_readReadyContract(projectPath, browser) {
     try {
         const raw = node_fs.readFileSync(node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json"), "utf8");
@@ -6631,7 +7121,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 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.",
+    description: "Wait for a running dev or start session to be ready. Polls the ready.json contract file and returns structured status with these facts: compiled (the compiler finished), browserAttached (the engine's runtime executor connected), and for a browser session guestLoaded (the browser's OWN target list actually shows your extension). guestLoaded is the trustworthy load signal: it catches a silently rejected --load-extension that leaves ready.json stamped attached with empty logs (extension.js BUGS_TO_FIX §83); it is null when it could not be checked (no CDP port, e.g. a gecko session). 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: {
@@ -6707,10 +7197,20 @@ async function wait_handler(args) {
                     continue;
                 }
                 const runtimeErrors = recentErrorLogs(args.projectPath, browser, 3);
+                const guestCheck = await verifyGuestLoaded(args.projectPath, browser);
+                const warnings = [];
+                if (runtimeErrors.length) warnings.push(`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 (guestCheck.checked && !guestCheck.loaded) warnings.push("The engine reports the runtime attached, but the browser's own target list shows no chrome-extension:// target for your extension, only the engine companion. This is the signature of a silently rejected --load-extension (extension.js BUGS_TO_FIX §83): the CLI and ready.json cannot see it, and the control verbs will fail against a guest that is not there. Check the manifest and extension_logs.");
                 return JSON.stringify({
                     status: "ready",
                     compiled: true,
                     browserAttached: true,
+                    guestLoaded: guestCheck.checked ? guestCheck.loaded : null,
+                    ...guestCheck.checked ? {
+                        guestIds: guestCheck.guestIds
+                    } : {
+                        guestLoadNote: guestCheck.reason
+                    },
                     command: contract.command,
                     browser: contract.browser,
                     port: contract.port,
@@ -6722,8 +7222,10 @@ async function wait_handler(args) {
                     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.`
+                        runtimeErrors
+                    } : {},
+                    ...warnings.length ? {
+                        warning: warnings.join(" ")
                     } : {}
                 });
             }
@@ -7422,7 +7924,10 @@ const logout_schema = {
 };
 async function logout_handler() {
     const creds = readCredentials();
-    const revokeUrl = creds?.workspaceSlug && creds?.projectSlug ? `https://console.extension.dev/${creds.workspaceSlug}/${creds.projectSlug}/settings/access-tokens` : null;
+    const revokeUrl = creds?.workspaceSlug && creds?.projectSlug ? consoleProjectUrl({
+        workspace: creds.workspaceSlug,
+        project: creds.projectSlug
+    }, "settings/access-tokens") : null;
     const result = clearCredentials();
     return JSON.stringify({
         ok: true,