@extension.dev/mcp 10.2.0 → 10.3.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 10.3.1
+
+The 10.3.0 tarball shipped two comments a stranger could read: an HTML
+comment in the popup markup naming a private package, and an eight line
+internal roadmap comment plus two inline script comments in the live
+preview sandbox page. Both were removed at source right after that
+release. This release exists to take them off the registry, because a
+published tarball cannot be edited in place.
+
+- The popup markup no longer names any private package.
+- `extensions/live-preview/chromium/sandbox/page-0.html` ships exactly
+  the markup it runs, with no comments at all.
+
+## 10.3.0
+
+Four fixes for places where a tool answered confidently about something it
+had not actually checked: a login refusal that never said where the slugs
+come from, a doctor report labelled with a browser that had no session, a
+preview probe that certified whatever was listening on the port, and a
+release gate that passed on a stale bundle.
+
+- `extension_auth login` refused a malformed `project` without saying
+  where the two slugs come from. Both the refusal and the input schema now
+  name the console address bar as the source: an existing project's page is
+  `console.extension.dev/<workspace>/<project>`, and a project that does
+  not exist yet is created at extension.dev/new first.
+- `extension_doctor` diagnoses the session that exists, not a hardcoded
+  default. The shared session resolver only counts contracts marked
+  "ready", which is exactly wrong for the tool you reach for when a session
+  failed: doctor fell back to chrome, labelled the report with it, read the
+  absent contract, and returned a healthy verdict over a session that had
+  errored. When there is no ready session, the browser with a contract on
+  disk wins, newest first and whatever its status.
+- `extension_preview_web` certifies the probe against the build the call
+  just minted instead of against the port. Anything can be listening on the
+  local preview port, and the old probe read `hostReachable` and
+  `previewLoadable` as true off whatever JSON came back, then echoed that
+  server's `identifier`, name and version into the envelope unmarked, which
+  made any local server a text channel into the agent's context. The name
+  and version must now match the `dist` manifest read off disk, and the
+  identifier is echoed only when it matches the derivation the real
+  middleware uses. A mismatch returns the status
+  `host-serving-different-artifact` with `previewLoadable: false`, and
+  anything the host claimed that could not be confirmed locally travels
+  clipped under `probe.hostReported`, named as the host's claim.
+- The release gate asserts the version the built bundle exports rather than
+  grepping the bundle for the version string. The grep greenwashed: the
+  bundle carries the pinned engine version and fifty-two `"version":"1.0.0"`
+  strings from the template corpus, so a release cut at any of those
+  numbers passed the gate over a stale `dist`. `dist/module.js` now exports
+  the manifest version it inlined at build time, and the gate reads it back
+  and compares.
+
 ## 10.2.0
 
 A production walk of the full share-and-publish loop, then a fix for every

package/README.md

@@ -127,7 +127,7 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | platform | `extension_shares` | List every link you have shared, and revoke one permanently |
 | platform | `extension_publish` | Publish a shareable preview to extension.dev |
 | platform | `extension_release_promote` | Promote a build to a release channel, headless |
-| platform | `extension_submit` | Submit for store review: Chrome, Firefox, Edge, Safari, through extension.dev |
+| platform | `extension_submit` | Submit for store review: Chrome, Firefox and Edge, through extension.dev |
 | platform | `extension_release_status` | Read release channels, recent builds, and store submission and review state |
 
 Browser-launching tools (`dev`, `start`) shell out to the `extension` CLI, the project's own `node_modules/.bin/extension` when present, otherwise `npx extension@<pinned>` at the version this package is verified against; everything else runs in-process.
@@ -142,7 +142,7 @@ That is a different job from shipping. Use `share` for the build you are holding
 
 ## From preview to store
 
-The platform tools connect agents to [extension.dev](https://extension.dev): `extension_auth` runs extension.dev's own device flow (you approve the code at [extension.dev/device](https://extension.dev/device), and GitHub is federated server-side, so no GitHub token ever reaches your machine) and stores a project-scoped token locally (never returned to the agent), `extension_publish` turns a build your project has already published into a shareable URL, and `extension_release_promote` promotes a tested build to a release channel from CI or an agent session, no browser required. `extension_submit` submits a built extension to the Chrome Web Store, Edge Add-ons, Firefox AMO, and the App Store for Safari through extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI, it defaults to a dry run and store credentials are never tool arguments. The two verbs are not interchangeable: `extension_publish` pushes to the extension.dev platform, `extension_submit` sends the build into a store's review queue, which is irreversible. After a real submission, `extension_release_status` reads the recorded outcome, per-store credential health, and review state from the project's public registry, so agents and CI can answer "was it approved?" without a console visit. Access tokens live at most 7 days; CI pipelines re-mint them from the console's Access tokens page.
+The platform tools connect agents to [extension.dev](https://extension.dev): `extension_auth` runs extension.dev's own device flow (you approve the code at [extension.dev/device](https://extension.dev/device), and GitHub is federated server-side, so no GitHub token ever reaches your machine) and stores a project-scoped token locally (never returned to the agent), `extension_publish` turns a build your project has already published into a shareable URL, and `extension_release_promote` promotes a tested build to a release channel from CI or an agent session, no browser required. `extension_submit` submits a built extension to the Chrome Web Store, Edge Add-ons, and Firefox AMO through extension.dev, which holds your store credentials and dispatches the release from your project's mirror CI, it defaults to a dry run and store credentials are never tool arguments. Safari and the App Store are one paid lane on the platform, so a free workspace is refused there and the other three stores are unaffected. The two verbs are not interchangeable: `extension_publish` pushes to the extension.dev platform, `extension_submit` sends the build into a store's review queue, which is irreversible. After a real submission, `extension_release_status` reads the recorded outcome, per-store credential health, and review state from the project's public registry, so agents and CI can answer "was it approved?" without a console visit. Access tokens live at most 7 days; CI pipelines re-mint them from the console's Access tokens page.
 
 ## The extension.dev stack
 

package/dist/module.d.ts

@@ -1 +1 @@
-export { startServer, runCli } from "./src/index";
+export { startServer, runCli, version } from "./src/index";

package/dist/module.js

@@ -582,7 +582,7 @@ __webpack_require__.d(wait_namespaceObject, {
     handler: ()=>wait_handler,
     schema: ()=>wait_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"10.2.0","El":{"OP":"4.0.20"}}');
+var package_namespaceObject = JSON.parse('{"rE":"10.3.1","El":{"OP":"4.0.20"}}');
 const ENVELOPE_SCHEMA = 1;
 const collectWarnings = (warnings)=>{
     if (!warnings) return [];
@@ -3530,6 +3530,26 @@ async function pollBootVerdict(projectPath, browser, options) {
         warnings: []
     };
 }
+const SYSTEM_PROFILE_ARG = "false";
+function holdsState(dir) {
+    try {
+        return node_fs.readdirSync(dir).length > 0;
+    } catch  {
+        return false;
+    }
+}
+function profileCarriesTabsOver(projectPath, browser, profileArg) {
+    const raw = "string" == typeof profileArg ? profileArg.trim() : "";
+    if (raw === SYSTEM_PROFILE_ARG) return true;
+    if (raw) return holdsState(node_path.resolve(projectPath, raw));
+    return holdsState(node_path.join(browserProfileRootDir(projectPath, browser), PERSISTED_PROFILE_DIR_NAME));
+}
+function sessionProfileReused(projectPath, browser) {
+    return findSessionInfo(projectPath, browser)?.profileReused === true;
+}
+function restoredTabWarning(url) {
+    return `No target was given and this session runs on a browser profile that already held a previous session's state, so ${url} may be a tab restored from that previous session rather than anything this run opened. Nothing here proves the page belongs to the extension you just started: pass url, or open a surface with extension_open, and inspect again.`;
+}
 function sweepCarriers(projectPaths) {
     const out = [];
     const seen = new Set();
@@ -3870,6 +3890,7 @@ function launchFlagArgs(args) {
     if (args.extensions?.length) cli.push("--extensions", args.extensions.join(","));
     return cli;
 }
+const REUSED_PROFILE_NOTE = "This session reuses a browser profile that already held a previous session's state, so the browser may restore that session's tabs alongside the extension. extension_inspect with no target ranks whatever is open and can land on one of them; it flags this session as profileReused for that reason. Pass url, or open the surface you mean with extension_open, before reading anything.";
 const dev_schema = {
     name: "extension_dev",
     description: "Run the extension while you edit it: dev build, hot module replacement, and a browser with the extension loaded. Reach for this first when the ask is \"run my extension\". ONLY this tool unlocks the control channel that extension_storage, extension_reload, extension_open and extension_dom_snapshot need (allowControl:true) and the eval channel that extension_eval needs (allowEval:true, which implies allowControl, so you never need to pass both). Use extension_start instead to run the production build in a browser. The result carries the process info that extension_wait and extension_inspect need.",
@@ -3954,6 +3975,7 @@ async function dev_handler(args) {
     }
     const carrier = args.carrier ? materializeCarrier(args.projectPath, browser) : null;
     const allowControl = Boolean(args.allowControl || args.allowEval);
+    const profileReused = profileCarriesTabsOver(args.projectPath, browser, args.profile);
     const cliArgs = [
         "dev",
         args.projectPath,
@@ -3979,7 +4001,8 @@ async function dev_handler(args) {
         port: args.port,
         projectPath: args.projectPath,
         command: "dev",
-        noBrowser: Boolean(args.noBrowser)
+        noBrowser: Boolean(args.noBrowser),
+        profileReused
     });
     child.on("exit", ()=>{
         removeSession(args.projectPath, browser, pid);
@@ -4104,7 +4127,8 @@ async function dev_handler(args) {
         port: boundPort,
         projectPath: args.projectPath,
         command: "dev",
-        noBrowser: Boolean(args.noBrowser)
+        noBrowser: Boolean(args.noBrowser),
+        profileReused
     });
     const portReport = null !== boundPort ? {
         port: boundPort,
@@ -4138,6 +4162,7 @@ async function dev_handler(args) {
         },
         warnings: [
             portNote,
+            profileReused && !args.noBrowser ? REUSED_PROFILE_NOTE : null,
             ...boot.warnings
         ],
         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_snapshot/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_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_snapshot 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."
@@ -4192,6 +4217,7 @@ async function start_handler(args) {
     if (args.noBrowser) cliArgs.push("--no-browser");
     cliArgs.push(...launchFlagArgs(args));
     const stale = removeCarrier(args.projectPath);
+    const profileReused = profileCarriesTabsOver(args.projectPath, browser, args.profile);
     const spawnedAt = Date.now();
     const spawned = spawnExtensionCli(cliArgs, {
         projectDir: args.projectPath
@@ -4203,7 +4229,8 @@ async function start_handler(args) {
         pid,
         browser,
         projectPath: args.projectPath,
-        command
+        command,
+        profileReused
     });
     child.on("exit", ()=>{
         removeSession(args.projectPath, browser, pid);
@@ -5742,6 +5769,7 @@ async function publish(options = {}) {
 }
 const ARTIFACT_ID = /^gen_(?:[0-9a-f]{32}|[0-9a-f]{64})$/;
 const ARTIFACT_ID_CANDIDATE = /gen_[0-9a-f]+/;
+const ZIP_URL_REDIRECT_NOTE = "zipUrl does not serve the archive itself: it answers 302 with a short-lived presigned storage URL in Location. Follow redirects when you fetch it (curl -L; fetch and most HTTP clients already do), because a client that does not follow them reads 0 bytes and reports the share as empty when it is not.";
 function parseArtifactRef(input) {
     const raw = String(input ?? "").trim();
     if (!raw) return null;
@@ -6305,6 +6333,14 @@ function safeHostBase(raw) {
         base: trimmed
     };
 }
+const HOST_CLAIM_MAX_CHARS = 120;
+function clipHostClaim(value) {
+    return value.length > HOST_CLAIM_MAX_CHARS ? value.slice(0, HOST_CLAIM_MAX_CHARS) : value;
+}
+function expectedPreviewIdentifier(name, distDir) {
+    const base = (name ?? node_path.basename(distDir)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "extension";
+    return base.startsWith("local-") ? base : `local-${base}`;
+}
 const SURFACE = {
     defaultOrigin: DEFAULT_PREVIEW_DEV_URL,
     scheme: (encoded)=>`preview://build/${encoded}`,
@@ -6434,7 +6470,7 @@ async function buildShare(projectPath, distDir, manifest, browser, verifyInBrows
             browserLoadable: null
         },
         record,
-        note: "Anyone with this link can open the build you just made, running in the emulator. No install, no sign-in, no dev server. They can also download the whole build as a zip from zipUrl, so the link hands over the built code. It stays live until expiresAt; DELETE revokeUrl with the same token to kill it sooner, and a revoked link stays dead. revokeUrl is the handle that pulls this link early. Re-sharing an unchanged build returns this same link rather than a second one, and only a revoked link is replaced by a different one, so " + (record.recorded ? `it was also written to ${record.path} (record.path), which lists every share from this project.` : `keep it: ${record.note}`) + " To find this link again later, or to pull it back once it has left this conversation, run extension_shares: it lists every link this token has shared with its live or dead state, and revokes one by artifactId or by pasting any of its URLs." + (record.warning ? ` ${record.warning}` : "")
+        note: "Anyone with this link can open the build you just made, running in the emulator. No install, no sign-in, no dev server. They can also download the whole build as a zip from zipUrl, so the link hands over the built code. It stays live until expiresAt; DELETE revokeUrl with the same token to kill it sooner, and a revoked link stays dead. revokeUrl is the handle that pulls this link early. Re-sharing an unchanged build returns this same link rather than a second one, and only a revoked link is replaced by a different one, so " + (record.recorded ? `it was also written to ${record.path} (record.path), which lists every share from this project.` : `keep it: ${record.note}`) + " To find this link again later, or to pull it back once it has left this conversation, run extension_shares: it lists every link this token has shared with its live or dead state, and revokes one by artifactId or by pasting any of its URLs." + (result.data.zipUrl ? ` ${ZIP_URL_REDIRECT_NOTE}` : "") + (record.warning ? ` ${record.warning}` : "")
     };
 }
 function detectSurfaces(manifest) {
@@ -6651,7 +6687,14 @@ async function preview_web_handler(args) {
             }
         });
         const contentType = res.headers.get("content-type") ?? "";
-        if (!res.ok || !contentType.includes("application/json")) return envelope_envelope({
+        let raw = null;
+        if (res.ok && contentType.includes("application/json")) try {
+            raw = await res.json();
+        } catch  {
+            raw = null;
+        }
+        const payload = raw && "object" == typeof raw && !Array.isArray(raw) ? raw : null;
+        if (!payload) return envelope_envelope({
             ok: true,
             command: preview_web_COMMAND,
             status: "host-not-serving-preview",
@@ -6670,7 +6713,62 @@ async function preview_web_handler(args) {
                 `${SURFACE.label} answered but not with a preview payload. On the deployed host ${SURFACE.fetchPath} does not exist, because it is dev-only. ${remedy}`
             ]
         });
-        const payload = await res.json();
+        const localName = "string" == typeof manifest.name ? manifest.name : null;
+        const localVersion = "string" == typeof manifest.version ? manifest.version : null;
+        const remoteName = "string" == typeof payload.manifest?.name ? payload.manifest.name : null;
+        const remoteVersion = "string" == typeof payload.version ? payload.version : null;
+        const remoteIdentifier = "string" == typeof payload.identifier ? payload.identifier : null;
+        const fileCount = Array.isArray(payload.files) ? payload.files.length : 0;
+        const matchesDist = (null === localName || remoteName === localName) && (null === localVersion || remoteVersion === localVersion);
+        if (!matchesDist) {
+            const hostReported = {
+                ...null !== remoteIdentifier ? {
+                    identifier: clipHostClaim(remoteIdentifier)
+                } : {},
+                ...null !== remoteName ? {
+                    name: clipHostClaim(remoteName)
+                } : {},
+                ...null !== remoteVersion ? {
+                    version: clipHostClaim(remoteVersion)
+                } : {}
+            };
+            return envelope_envelope({
+                ok: true,
+                command: preview_web_COMMAND,
+                status: "host-serving-different-artifact",
+                value: {
+                    ...result,
+                    hostReachable: true,
+                    previewLoadable: false,
+                    probe: {
+                        method: "server-fetch",
+                        provesBrowserLoad: false,
+                        matchesDist: false,
+                        fileCount,
+                        ...Object.keys(hostReported).length ? {
+                            hostReported
+                        } : {}
+                    }
+                },
+                hint,
+                warnings: [
+                    ...previewWarnings,
+                    `Something answered at ${hostBase}${SURFACE.fetchPath} but described a different artifact than the build this call minted, so previewLoadable stays false. probe.hostReported carries that host's own claims, clipped and unverified, not facts about your build; another local server on this port is the usual cause. ${remedy}`
+                ]
+            });
+        }
+        const identifierConfirmed = null !== remoteIdentifier && remoteIdentifier === expectedPreviewIdentifier(localName, distDir);
+        const unconfirmed = {
+            ...!identifierConfirmed && null !== remoteIdentifier ? {
+                identifier: clipHostClaim(remoteIdentifier)
+            } : {},
+            ...null === localName && null !== remoteName ? {
+                name: clipHostClaim(remoteName)
+            } : {},
+            ...null === localVersion && null !== remoteVersion ? {
+                version: clipHostClaim(remoteVersion)
+            } : {}
+        };
         return envelope_envelope({
             ok: true,
             command: preview_web_COMMAND,
@@ -6681,12 +6779,22 @@ async function preview_web_handler(args) {
                 previewLoadable: true,
                 previewLoadableLane: "local-dev-host",
                 probe: {
-                    identifier: payload.identifier,
-                    loadedName: payload.manifest?.name,
-                    loadedVersion: payload.version,
-                    fileCount: Array.isArray(payload.files) ? payload.files.length : 0,
+                    ...identifierConfirmed ? {
+                        identifier: remoteIdentifier
+                    } : {},
+                    ...null !== localName ? {
+                        loadedName: localName
+                    } : {},
+                    ...null !== localVersion ? {
+                        loadedVersion: localVersion
+                    } : {},
+                    fileCount,
                     method: "server-fetch",
-                    provesBrowserLoad: false
+                    provesBrowserLoad: false,
+                    matchesDist: true,
+                    ...Object.keys(unconfirmed).length ? {
+                        hostReported: unconfirmed
+                    } : {}
                 }
             },
             hint,
@@ -6930,6 +7038,7 @@ async function listShares(args) {
             } : {},
             status: localOnlyStatus(entry, completeness, liveFiltered, now)
         }));
+    const handsOutAZip = shares.some((share)=>Boolean(share.zipUrl)) || localOnly.some((entry)=>Boolean(entry.zipUrl));
     const liveCount = shares.filter((share)=>share.live).length;
     const ownership = {
         project: shares.filter((s)=>"project" === s.attribution.ownership).length,
@@ -6966,6 +7075,7 @@ async function listShares(args) {
         warnings: [
             "previewUrl and zipUrl are null for a share that is no longer live, because a revoked or expired link cannot resolve for anyone. revokeUrl stays on every row. Revocation is permanent: a revoked id is burned, and re-sharing that build mints a different link. Re-sharing a build that was NOT revoked returns its existing link instead.",
             "attribution.ownership says who the share belongs to and therefore who may revoke it: project means the owning workspace holds it and any member can pull it back, personal means one person holds it alone. attribution.credit names the publisher and is attribution only, granting and restricting nothing. A credit of \"CLI token ...\" means the platform could not resolve which human minted that token, and a credit of \"not recorded\" means it never knew; neither is a name, and neither should be reported as one.",
+            handsOutAZip ? ZIP_URL_REDIRECT_NOTE : null,
             truncatedNote
         ]
     });
@@ -9172,6 +9282,10 @@ async function inspectViaBridge(args, browser, include, maxBytes) {
         if (jsLooking.length) probeWarning = `Probes are CSS selectors run through querySelectorAll against the live page, NOT JavaScript expressions. ${jsLooking.map((s)=>`"${s}"`).join(", ")} parsed as selectors and will match nothing. To evaluate JS, use extension_eval.`;
     }
     const urlFilter = args.url ?? ("string" == typeof value.meta?.url ? value.meta.url : void 0);
+    if (!args.url && sessionProfileReused(args.projectPath, browser)) {
+        result.profileReused = true;
+        notes.push(restoredTabWarning(urlFilter ?? "the tab this read landed on"));
+    }
     if (include.has("console")) await collectGeckoConsole(args, browser, urlFilter, result, notes);
     if (args.deepDom) {
         const cap = maxBytes > 0 ? maxBytes : 65536;
@@ -9271,9 +9385,13 @@ async function inspect_handler(args) {
             }
             toolchainWarning = isEngineCompanionUrl(documentUrl) || isEngineCompanionUrl(target.url) ? `Inspected ${target.url}, which is rendered by the Extension.js toolchain's own companion extension, not by this project. Pass url, or open one of the extension's surfaces first (extension_open), then inspect again.` : `No url was given and only override pages were open, so this inspected ${target.url}. Unless this extension provides that override itself, this is the toolchain's welcome surface, not your extension: pass url or open a surface with extension_open.`;
         }
+        const profileReused = !args.url && sessionProfileReused(args.projectPath, browser);
         const result = {
             cdpPort,
             browser,
+            ...profileReused ? {
+                profileReused: true
+            } : {},
             target: {
                 id: target.id,
                 url: target.url,
@@ -9335,7 +9453,8 @@ async function inspect_handler(args) {
             value: result,
             warnings: [
                 "string" == typeof probeWarning ? probeWarning : null,
-                toolchainWarning
+                toolchainWarning,
+                profileReused ? restoredTabWarning(documentUrl || target.url) : null
             ]
         });
     } catch (err) {
@@ -11456,9 +11575,26 @@ function readContractForDiagnosis(projectPath, browser) {
         return null;
     }
 }
+function sightedContractBrowser(projectPath) {
+    let dirs;
+    try {
+        dirs = node_fs.readdirSync(sessionArtifactsRootDir(projectPath));
+    } catch  {
+        return null;
+    }
+    let best = null;
+    for (const dir of dirs)try {
+        const stat = node_fs.statSync(bridge_readyContractPath(projectPath, dir));
+        if (!best || stat.mtimeMs > best.mtimeMs) best = {
+            browser: dir,
+            mtimeMs: stat.mtimeMs
+        };
+    } catch  {}
+    return best ? best.browser : null;
+}
 const doctor_schema = {
     name: "extension_doctor",
-    description: "Diagnose a dev session end to end: ready contract, dev-server process, control-port agreement, control channel, eval token, executor, browser liveness. This returns one {check, status, detail, remediation?} per leg, in dependency order. Read a 'skip' as blocked, not as a pass: it names the check that blocked it. Run this first when any act tool (storage, reload, eval, open) errors unexpectedly. Call it with no projectPath for a pre-flight environment check (node, the Extension.js CLI, the template cache) before any project exists.",
+    description: "Diagnose a dev session end to end: ready contract, dev-server process, control-port agreement, control channel, eval token, executor, browser liveness. This returns one {check, status, detail, remediation?} per leg, in dependency order. Read a 'skip' as blocked, not as a pass: it names the check that blocked it. A session started without allowControl comes back ok:true with status 'read-only', not as an error: its control channel is off by choice. Run this first when any act tool (storage, reload, eval, open) errors unexpectedly. Call it with no projectPath for a pre-flight environment check (node, the Extension.js CLI, the template cache) before any project exists.",
     inputSchema: {
         type: "object",
         properties: {
@@ -11546,12 +11682,20 @@ function projectEngineVersion(projectPath) {
     }
 }
 function capabilityProbeChecks(parsed) {
-    return isEnvelope(parsed) ? parsed.value?.checks : parsed;
+    if (!isEnvelope(parsed)) return parsed;
+    const value = parsed.value;
+    if (Array.isArray(value)) return value;
+    return value?.checks;
+}
+const CONTROL_OFF_BY_CHOICE = /\bwas not started with --allow-control\b/i;
+function controlOffByChoiceLeg(checks) {
+    return checks.find((leg)=>"control-channel" === leg.check && "fail" === leg.status && "string" == typeof leg.detail && CONTROL_OFF_BY_CHOICE.test(leg.detail)) ?? null;
 }
 async function doctor_handler(args) {
     if (!args.projectPath) return environmentPreflight();
     const projectPath = args.projectPath;
-    const { browser } = resolveSessionBrowser(projectPath, args.browser);
+    const resolved = resolveSessionBrowser(projectPath, args.browser);
+    const browser = "fallback" === resolved.source ? sightedContractBrowser(projectPath) ?? resolved.browser : resolved.browser;
     const { code, stdout, stderr } = await runExtensionCli([
         "doctor",
         projectPath,
@@ -11576,8 +11720,10 @@ async function doctor_handler(args) {
     const out = stdout.trim();
     try {
         const parsed = JSON.parse(out);
-        const checks = capabilityProbeChecks(parsed);
-        if (!Array.isArray(checks)) throw new Error("not a check array");
+        const probed = capabilityProbeChecks(parsed);
+        if (!Array.isArray(probed)) throw new Error("not a check array");
+        const checks = probed;
+        const readOnlyLeg = controlOffByChoiceLeg(checks);
         for (const check of checks){
             if ("string" == typeof check.detail) check.detail = toMcpSpeak(check.detail);
             if ("string" == typeof check.remediation) check.remediation = toMcpSpeak(check.remediation);
@@ -11619,17 +11765,30 @@ async function doctor_handler(args) {
                 } : {}
             });
         }
+        const failures = checks.filter((leg)=>"fail" === leg.status);
+        const readOnly = null !== readOnlyLeg && 1 === failures.length && failures[0] === readOnlyLeg;
+        if (readOnly && readOnlyLeg) {
+            readOnlyLeg.status = "warn";
+            readOnlyLeg.detail = `read-only by choice: ${readOnlyLeg.detail}`;
+            readOnlyLeg.remediation = "Nothing failed. To unlock the control verbs, call extension_dev again with allowControl: true (or allowEval: true) plus replace: true, which stops this session first; a plain second call is refused so the session does not fork.";
+        }
         return envelope_envelope({
-            ok: healthy,
+            ok: healthy || readOnly,
             command: doctor_schema.name,
-            status: healthy ? "healthy" : "unhealthy",
+            status: healthy ? "healthy" : readOnly ? "read-only" : "unhealthy",
             value: {
                 browser,
                 ...engineVersion ? {
                     engineVersion
                 } : {},
+                ...readOnly ? {
+                    readOnly: true
+                } : {},
                 checks
-            }
+            },
+            ...readOnly ? {
+                hint: "This session is read-only because it was started without allowControl, not because anything is wrong: logs, inspect, wait and doctor all work, while storage, reload, open, dom_snapshot and eval stay locked."
+            } : {}
         });
     } catch  {
         const message = stderr.trim() || `extension exited with code ${code}`;
@@ -12321,7 +12480,7 @@ function resumePending(deviceCode, verificationUri) {
 }
 async function loginToProject(args) {
     const project = String(args.project || "").trim();
-    if (!/^[^/]+\/[^/]+$/.test(project)) return login_fail("BadRequest", "project must be in the form '<workspace>/<project>'.", "bad-request", "E_BAD_REQUEST");
+    if (!/^[^/]+\/[^/]+$/.test(project)) return login_fail("BadRequest", "project must be in the form '<workspace>/<project>'. The slug pair is the console address bar: an existing project's page is console.extension.dev/<workspace>/<project>. If the project does not exist yet, create it at extension.dev/new, then log in with the slugs the console shows.", "bad-request", "E_BAD_REQUEST");
     const apiCheck = safeApiBase(resolveApiBase(args.api), args.api);
     if (!apiCheck.ok) return login_fail("LoginConfigError", apiCheck.message, "login-failed", "E_AUTH_FAILED");
     const apiBase = apiCheck.base;
@@ -12562,7 +12721,7 @@ const auth_schema = {
             },
             project: {
                 type: "string",
-                description: "login: target project as '<workspace>/<project>'; the token is scoped to it."
+                description: "login: target project as '<workspace>/<project>'; the token is scoped to it. The slug pair is the console address bar: an existing project's page is console.extension.dev/<workspace>/<project>. Create one at extension.dev/new if none exists yet."
             },
             deviceCode: {
                 type: "string",
@@ -13461,4 +13620,5 @@ async function runCli(cmd, args) {
     log(`Unknown command: ${cmd}. Expected one of: login, logout, whoami, release.`);
     return 1;
 }
-export { runCli, startServer };
+var version_0 = package_namespaceObject.rE;
+export { runCli, startServer, version_0 as version };

package/dist/src/index.d.ts

@@ -1,3 +1,5 @@
+import { version } from "../package.json";
+export { version };
 export interface ToolModule {
     schema: {
         name: string;

package/dist/src/lib/artifacts-api.d.ts

@@ -13,6 +13,7 @@ export interface ArtifactPublisher {
     project: string | null;
     tokenId: string | null;
 }
+export declare const ZIP_URL_REDIRECT_NOTE = "zipUrl does not serve the archive itself: it answers 302 with a short-lived presigned storage URL in Location. Follow redirects when you fetch it (curl -L; fetch and most HTTP clients already do), because a client that does not follow them reads 0 bytes and reports the share as empty when it is not.";
 export interface ListedArtifact {
     artifactId: string;
     kind?: string;

package/dist/src/lib/profile-carryover.d.ts

@@ -0,0 +1,4 @@
+export declare const SYSTEM_PROFILE_ARG = "false";
+export declare function profileCarriesTabsOver(projectPath: string, browser: string, profileArg?: string): boolean;
+export declare function sessionProfileReused(projectPath: string, browser: string): boolean;
+export declare function restoredTabWarning(url: string): string;

package/dist/src/lib/types.d.ts

@@ -71,5 +71,6 @@ export interface ProcessInfo {
     projectPath: string;
     command: "dev" | "start" | "preview";
     noBrowser?: boolean;
+    profileReused?: boolean;
 }
 export type BrowserType = "chrome" | "edge" | "firefox" | "chromium-based" | "gecko-based";

package/extensions/live-preview/chromium/action/index.html

@@ -1,9 +1,6 @@
 <!DOCTYPE html><html lang="en"><head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <!-- Dark-only surface: signals the popup chrome up front so there is no
-         white flash before styles.css loads. The brand tokens live in
-         ./styles.css (synced with @extensiondev/ui), not inline here. -->
     <meta name="color-scheme" content="dark">
     <title>Extension.dev Live Preview</title>
   <link rel="stylesheet" href="/action/index.css"></head>

package/extensions/live-preview/chromium/sandbox/page-0.html

@@ -3,19 +3,8 @@
     <title>Extension preview host</title>
   </head>
   <body>
-    <!--
-      Sandbox execution surface for guest extension code.
-      Declared in manifest.json under chromium:sandbox.pages with a CSP
-      that allows unsafe-eval / blob: so guest code can run for real inside this
-      installed extension. This file exists so the sandbox reference resolves and
-      the build has a host page to mount; the full executor wiring (receiving a
-      guest PreviewSession and running its surfaces here) is the next increment.
-      Until then, guest surfaces still render through the creator-preview iframes.
-    -->
     <div id="preview-host-root"></div>
     <script>
-      // Signal the parent (the newtab runtime) that the sandbox host is mounted
-      // and ready to receive a guest preview to execute.
       if (window.parent) {
         window.parent.postMessage(
           { type: "EXTENSION_PREVIEW_HOST_READY" },

package/package.json

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

package/server.json

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