@extension.dev/mcp 5.2.0 → 5.3.1

package/dist/module.js

@@ -7,11 +7,11 @@ import node_path, { join } from "node:path";
 import { extensionCreate } from "extension-create";
 import node_os from "node:os";
 import cross_spawn from "cross-spawn";
+import node_crypto from "node:crypto";
 import { execFile, execFileSync } from "node:child_process";
 import { filterKeysForThisBrowser } from "browser-extension-manifest-fields";
 import ws_0 from "ws";
 import node_http from "node:http";
-import node_crypto from "node:crypto";
 import { extensionInstall, extensionUninstall, getManagedBrowsersCacheRoot } from "extension-install";
 import { promisify } from "node:util";
 var add_feature_namespaceObject = {};
@@ -149,6 +149,12 @@ __webpack_require__.d(tools_publish_namespaceObject, {
     handler: ()=>publish_handler,
     schema: ()=>publish_schema
 });
+var release_list_namespaceObject = {};
+__webpack_require__.r(release_list_namespaceObject);
+__webpack_require__.d(release_list_namespaceObject, {
+    handler: ()=>release_list_handler,
+    schema: ()=>release_list_schema
+});
 var release_promote_namespaceObject = {};
 __webpack_require__.r(release_promote_namespaceObject);
 __webpack_require__.d(release_promote_namespaceObject, {
@@ -177,7 +183,8 @@ var stop_namespaceObject = {};
 __webpack_require__.r(stop_namespaceObject);
 __webpack_require__.d(stop_namespaceObject, {
     handler: ()=>stop_handler,
-    schema: ()=>stop_schema
+    schema: ()=>stop_schema,
+    stopOne: ()=>stopOne
 });
 var storage_namespaceObject = {};
 __webpack_require__.r(storage_namespaceObject);
@@ -203,7 +210,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"5.2.0","El":{"OP":"^4.0.13"}}');
+var package_namespaceObject = JSON.parse('{"rE":"5.3.1","El":{"OP":"^4.0.13"}}');
 function scaffoldEnginePin(projectPath) {
     try {
         const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
@@ -241,17 +248,17 @@ function detectPackageManager(projectPath) {
 }
 const create_schema = {
     name: "extension_create",
-    description: "Create a new browser extension project from a template in the extension.dev template catalog. Use extension_list_templates to see available options.",
+    description: "Create a new browser extension project from a template in the extension.dev template catalog. Use extension_list_templates to see available options. The scaffolder may initialize a git repository in the new project; the result's defaultsApplied block reports whether it did, along with every other decision made without being asked.",
     inputSchema: {
         type: "object",
         properties: {
             projectName: {
                 type: "string",
-                description: "Name of the extension project (used as directory name)"
+                description: "Name of the extension project (used as directory name). Alias: name."
             },
             parentDir: {
                 type: "string",
-                description: "Directory to create the project inside. Defaults to the MCP server's working directory, which may not be where you expect, pass this explicitly when you care where the project lands."
+                description: "Directory to create the project inside. Defaults to the MCP server process cwd (NOT the caller's cwd), which may not be where you expect; pass this explicitly when you care where the project lands. Aliases: parent, into."
             },
             template: {
                 type: "string",
@@ -338,12 +345,21 @@ async function create_handler(args) {
     const scaffoldPin = scaffoldEnginePin(result.projectPath);
     const pinMatches = null !== scaffoldPin && "" !== pin && scaffoldPin.includes(pin);
     const engineWarning = pin && "latest" !== pin && !pinMatches ? `The scaffold pins "extension": "${scaffoldPin ?? "unknown"}"; the project-local engine wins over EXTENSION_MCP_CLI_VERSION=${pin}. Run \`(cd ${result.projectPath} && ${addDev(`extension@${pin}`)})\` to match the pinned engine.` : void 0;
+    const resolvedParent = args.parentDir ? node_path.resolve(args.parentDir) : process.cwd();
+    const gitInit = node_fs.existsSync(node_path.join(result.projectPath, ".git"));
     return JSON.stringify({
+        resolvedPath: result.projectPath,
         projectPath: result.projectPath,
         projectName: result.projectName,
         template: result.template,
         depsInstalled: result.depsInstalled,
         packageManager: result.depsInstalled ? packageManager : null,
+        defaultsApplied: {
+            parentDir: args.parentDir ? `${resolvedParent} (explicit)` : `${resolvedParent} (default: the MCP server process cwd, not yours; pass parentDir to choose)`,
+            packageManager: `${packageManager} (auto-detected by the scaffolder, not asked)`,
+            browser: "chrome (default: extension_dev and extension_build target chrome unless you pass browser)",
+            gitInit
+        },
         duration: Date.now() - start,
         nextSteps: result.depsInstalled ? [
             `cd ${result.projectPath}`,
@@ -882,216 +898,59 @@ async function build_handler(args) {
         hint: "Check that the project has a valid src/manifest.json and its dependencies are installed (extension_dev auto-installs; build does not)."
     });
 }
-const process_manager_sessions = new Map();
+const sessions = new Map();
 function sessionKey(projectPath, browser) {
     return `${node_path.resolve(projectPath)}::${browser}`;
 }
-function registerSession(info) {
-    process_manager_sessions.set(sessionKey(info.projectPath, info.browser), info);
-}
-function getSession(projectPath, browser) {
-    return process_manager_sessions.get(sessionKey(projectPath, browser));
+function markerDir() {
+    return process.env.EXTENSION_MCP_SESSION_DIR || node_path.join(node_os.tmpdir(), "extension-dev-mcp-sessions");
 }
-function removeSession(projectPath, browser) {
-    process_manager_sessions.delete(sessionKey(projectPath, browser));
+function markerPath(projectPath, browser) {
+    const digest = node_crypto.createHash("sha1").update(sessionKey(projectPath, browser)).digest("hex").slice(0, 16);
+    return node_path.join(markerDir(), `${digest}.json`);
 }
-function listSessions() {
-    return Array.from(process_manager_sessions.values());
+function removeSessionMarker(projectPath, browser) {
+    try {
+        node_fs.rmSync(markerPath(projectPath, browser), {
+            force: true
+        });
+    } catch  {}
 }
-const LAUNCH_FLAG_SCHEMA = {
-    profile: {
-        type: "string",
-        description: 'Browser profile path, or "false" to reuse the default user profile. Omit for a fresh throwaway profile.'
-    },
-    startingUrl: {
-        type: "string",
-        description: "URL the browser opens on launch"
-    },
-    chromiumBinary: {
-        type: "string",
-        description: "Path to a custom Chromium-based binary (overrides browser)"
-    },
-    geckoBinary: {
-        type: "string",
-        description: "Path to a custom Gecko/Firefox binary (overrides browser)"
-    },
-    host: {
-        type: "string",
-        description: "Dev server bind host. Use 0.0.0.0 for Docker or devcontainers. Defaults to 127.0.0.1"
-    },
-    publicHost: {
-        type: "string",
-        description: "Connectable host the browser dials for HMR and reload when it differs from the bind host"
-    },
-    extensions: {
-        type: "array",
-        items: {
-            type: "string"
-        },
-        description: "Companion extension paths or store URLs to load alongside the project"
+function listSessionMarkers() {
+    let files;
+    try {
+        files = node_fs.readdirSync(markerDir());
+    } catch  {
+        return [];
     }
-};
-function launchFlagArgs(args) {
-    const cli = [];
-    if (void 0 !== args.profile) cli.push("--profile", args.profile);
-    if (args.startingUrl) cli.push("--starting-url", args.startingUrl);
-    if (args.chromiumBinary) cli.push("--chromium-binary", args.chromiumBinary);
-    if (args.geckoBinary) cli.push("--gecko-binary", args.geckoBinary);
-    if (args.host) cli.push("--host", args.host);
-    if (args.publicHost) cli.push("--public-host", args.publicHost);
-    if (args.extensions?.length) cli.push("--extensions", args.extensions.join(","));
-    return cli;
+    const out = [];
+    for (const file of files)if (file.endsWith(".json")) try {
+        const parsed = JSON.parse(node_fs.readFileSync(node_path.join(markerDir(), file), "utf8"));
+        if ("string" == typeof parsed?.projectPath && "string" == typeof parsed?.browser) out.push(parsed);
+    } catch  {}
+    return out;
 }
-const dev_schema = {
-    name: "extension_dev",
-    description: "Start the extension development server with hot module replacement. Launches a browser with the extension loaded. Returns process info for use with extension_wait and extension_source_inspect.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            projectPath: {
-                type: "string",
-                description: "Path to the extension project root"
-            },
-            browser: {
-                type: "string",
-                enum: [
-                    "chrome",
-                    "chromium",
-                    "edge",
-                    "brave",
-                    "opera",
-                    "vivaldi",
-                    "yandex",
-                    "firefox",
-                    "waterfox",
-                    "librewolf",
-                    "safari",
-                    "chromium-based",
-                    "gecko-based",
-                    "firefox-based",
-                    "webkit-based"
-                ],
-                default: "chrome"
-            },
-            port: {
-                type: "number",
-                description: "Dev server port (0 for auto-assign)"
-            },
-            noBrowser: {
-                type: "boolean",
-                default: false,
-                description: "Start dev server without launching browser"
-            },
-            polyfill: {
-                type: "boolean",
-                default: true,
-                description: "Apply cross-browser polyfill"
-            },
-            ...LAUNCH_FLAG_SCHEMA,
-            allowControl: {
-                type: "boolean",
-                default: false,
-                description: "Enable the agent-bridge control channel so extension_storage/reload/open/dom_inspect work against this session"
-            },
-            allowEval: {
-                type: "boolean",
-                default: false,
-                description: "Enable extension_eval (runs code in a context; writes a 0600 session token). Implies allowControl, so a single allowEval: true also unlocks storage/reload/open/dom_inspect. You do not need to pass both."
-            }
-        },
-        required: [
-            "projectPath"
-        ]
-    }
-};
-async function dev_handler(args) {
-    const browser = args.browser ?? "chrome";
-    const allowControl = Boolean(args.allowControl || args.allowEval);
-    const cliArgs = [
-        "dev",
-        args.projectPath,
-        "--browser",
-        browser
-    ];
-    if (void 0 !== args.port) cliArgs.push("--port", String(args.port));
-    if (args.noBrowser) cliArgs.push("--no-browser");
-    if (false === args.polyfill) cliArgs.push("--polyfill", "false");
-    cliArgs.push(...launchFlagArgs(args));
-    if (allowControl) cliArgs.push("--allow-control");
-    if (args.allowEval) cliArgs.push("--allow-eval");
-    const spawned = spawnExtensionCli(cliArgs, {
-        projectDir: args.projectPath
-    });
-    const { child, logPath } = spawned;
-    const pid = child.pid;
-    registerSession({
-        pid,
-        browser,
-        port: args.port,
-        projectPath: args.projectPath,
-        command: "dev"
-    });
-    child.on("exit", ()=>removeSession(args.projectPath, browser));
-    await new Promise((resolve)=>setTimeout(resolve, 3000));
-    const earlyOutput = spawned.readOutput();
-    if (null !== child.exitCode || null !== child.signalCode) {
-        const code = child.exitCode;
-        const signal = child.signalCode;
-        return JSON.stringify({
-            ok: false,
-            status: "exited",
-            projectPath: args.projectPath,
-            browser,
-            pid,
-            exitCode: code,
-            signal,
-            error: `The dev server exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running, so extension_logs/wait/eval and the control verbs have nothing to attach to.`,
-            output: denoiseEarlyOutput(earlyOutput).slice(0, 2000),
-            logPath,
-            hint: "Read `output` above for the cause: a port already in use, a manifest the build rejects, or a missing browser binary are the common ones. Fix it and call extension_dev again; extension_doctor with this projectPath will also report what the last session recorded."
+function registerSession(info) {
+    sessions.set(sessionKey(info.projectPath, info.browser), info);
+    try {
+        node_fs.mkdirSync(markerDir(), {
+            recursive: true
         });
-    }
-    const compileFailed = /compiled with errors|✖✖✖|ERROR in |Module not found|NOT FOUND/i.test(earlyOutput);
-    if (compileFailed) return JSON.stringify({
-        ok: false,
-        status: "compile-failed",
-        projectPath: args.projectPath,
-        browser,
-        pid,
-        error: "The dev server started but the FIRST COMPILE FAILED, so the browser has nothing usable to load. The session is running; the extension is not.",
-        output: denoiseEarlyOutput(earlyOutput).slice(0, 2000),
-        logPath,
-        hint: "Fix the compile error in `output` above and save: the dev server is still running and will recompile. Do not call extension_wait yet, it will report ready for a build that failed."
-    });
-    const controlVerbs = "storage, reload, open, dom_inspect";
-    const capabilities = {
-        allowControl,
-        allowEval: Boolean(args.allowEval),
-        unlocked: allowControl ? args.allowEval ? `${controlVerbs}, eval` : controlVerbs : "none (read-only: logs, source_inspect, wait, doctor)"
-    };
-    return JSON.stringify({
-        ok: true,
-        pid,
-        browser,
-        port: args.port ?? 8080,
-        projectPath: args.projectPath,
-        status: "started",
-        capabilities,
-        hint: "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. " + (allowControl ? `Control channel is ON: extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : "Control channel is OFF: extension_storage/reload/open/dom_inspect need allowControl: true, and extension_eval needs allowEval: true (which also implies allowControl). Restart extension_dev with the flag you need.") + " When you are done, call extension_stop to shut down the dev server and browser.",
-        earlyOutput: denoiseEarlyOutput(earlyOutput).slice(0, 500),
-        logPath
-    });
+        node_fs.writeFileSync(markerPath(info.projectPath, info.browser), JSON.stringify({
+            ...info,
+            projectPath: node_path.resolve(info.projectPath),
+            registeredAt: new Date().toISOString()
+        }));
+    } catch  {}
 }
-function denoiseEarlyOutput(raw) {
-    const NOISE = [
-        /^npm warn Unknown project config/i,
-        /This will stop working in the next major version of npm/i,
-        /^npm warn config/i,
-        /V8: .*Invalid asm\.js/i,
-        /^\(node:\d+\) V8:/i,
-        /Use `node --trace-warnings/i
-    ];
-    return raw.split("\n").filter((line)=>!NOISE.some((re)=>re.test(line.trim()))).join("\n").replace(/\n{2,}/g, "\n").trimStart();
+function getSession(projectPath, browser) {
+    return sessions.get(sessionKey(projectPath, browser));
+}
+function removeSession(projectPath, browser) {
+    sessions.delete(sessionKey(projectPath, browser));
+}
+function listSessions() {
+    return Array.from(sessions.values());
 }
 function contractSightings(projectPath) {
     const root = node_path.resolve(projectPath, "dist", "extension-js");
@@ -1132,6 +991,27 @@ function knownSessionBrowsers(projectPath) {
     for (const sighting of contractSightings(projectPath))if (void 0 === sighting.pid || pidAlive(sighting.pid)) browsers.push(sighting.browser);
     return Array.from(new Set(browsers));
 }
+function liveProjectSessions(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const out = new Map();
+    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) {
+        if (pidAlive(session.pid)) out.set(session.browser, {
+            browser: session.browser,
+            pid: session.pid,
+            source: "registry"
+        });
+    }
+    for (const sighting of contractSightings(projectPath))if (void 0 !== sighting.pid && pidAlive(sighting.pid)) {
+        if (!out.has(sighting.browser)) out.set(sighting.browser, {
+            browser: sighting.browser,
+            pid: sighting.pid,
+            source: "contract"
+        });
+    }
+    return [
+        ...out.values()
+    ];
+}
 function deadReadySession(projectPath) {
     for (const sighting of contractSightings(projectPath))if (void 0 !== sighting.pid && !pidAlive(sighting.pid)) return {
         browser: sighting.browser,
@@ -1180,9 +1060,9 @@ function resolveSessionBrowser(projectPath, explicit, fallback = "chrome") {
         source: "fallback"
     };
 }
-const start_schema = {
-    name: "extension_start",
-    description: "Build the extension for production and immediately preview it in a browser. Combines build + preview in one step. No hot reload.",
+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.",
     inputSchema: {
         type: "object",
         properties: {
@@ -1192,58 +1072,303 @@ const start_schema = {
             },
             browser: {
                 type: "string",
-                enum: [
-                    "chrome",
-                    "chromium",
-                    "edge",
-                    "brave",
-                    "opera",
-                    "vivaldi",
-                    "yandex",
-                    "firefox",
-                    "waterfox",
-                    "librewolf",
-                    "safari",
-                    "chromium-based",
-                    "gecko-based",
-                    "firefox-based",
-                    "webkit-based"
-                ],
-                default: "chrome"
+                description: "Browser of the session to stop (matches the browser passed to extension_dev/extension_start). Defaults to the one live session for this project when omitted, instead of assuming chrome."
             },
-            polyfill: {
+            all: {
                 type: "boolean",
-                default: true,
-                description: "Apply cross-browser polyfill"
-            },
-            port: {
+                default: false,
+                description: "Stop every known session, across projects and browsers. Discovers sessions from this server's registry AND the on-disk session markers earlier runs left, so it still finds sessions after an MCP restart or after a dev child exited out from under the registry. When true, projectPath/browser are ignored."
+            }
+        },
+        required: []
+    }
+};
+function pgrepPids(pattern) {
+    try {
+        const out = execFileSync("pgrep", [
+            "-f",
+            pattern
+        ], {
+            encoding: "utf8"
+        });
+        return out.split("\n").map((s)=>parseInt(s.trim(), 10)).filter((n)=>Number.isInteger(n) && n > 0 && n !== process.pid);
+    } catch  {
+        return [];
+    }
+}
+function sessionProcessPids(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const pids = new Set();
+    for (const marker of [
+        `extension dev ${resolved}`,
+        node_path.join(resolved, "dist")
+    ])for (const pid of pgrepPids(marker))pids.add(pid);
+    return [
+        ...pids
+    ];
+}
+function reapSessionProcesses(projectPath) {
+    const pids = sessionProcessPids(projectPath);
+    for (const pid of pids)try {
+        process.kill(pid, "SIGKILL");
+    } catch  {}
+    return pids;
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function stop_signal(pid, sig) {
+    try {
+        process.kill(-pid, sig);
+        return true;
+    } catch  {
+        try {
+            process.kill(pid, sig);
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+}
+function readyJsonPath(projectPath, browser) {
+    return node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+}
+function pidFromReadyContract(projectPath, browser) {
+    try {
+        const raw = node_fs.readFileSync(readyJsonPath(projectPath, browser), "utf8");
+        const contract = JSON.parse(raw);
+        return "number" == typeof contract.pid ? contract.pid : null;
+    } catch  {
+        return null;
+    }
+}
+async function stopOne(projectPath, browser) {
+    const session = getSession(projectPath, browser);
+    const pid = session?.pid ?? pidFromReadyContract(projectPath, browser);
+    if (null == pid) {
+        const reaped = reapSessionProcesses(projectPath);
+        removeSessionMarker(projectPath, browser);
+        return {
+            projectPath,
+            browser,
+            pid: null,
+            stopped: 0 !== reaped.length,
+            reaped,
+            detail: 0 === reaped.length ? "No known session for this project/browser (nothing registered in this server and no ready.json contract found)." : `No dev pid on record, but reaped ${reaped.length} orphaned browser process(es) from the profile dir.`
+        };
+    }
+    let detail;
+    if (isAlive(pid)) {
+        stop_signal(pid, "SIGTERM");
+        await new Promise((resolve)=>setTimeout(resolve, 1500));
+        if (isAlive(pid)) {
+            stop_signal(pid, "SIGKILL");
+            await new Promise((resolve)=>setTimeout(resolve, 250));
+        }
+        detail = isAlive(pid) ? "Sent SIGTERM and SIGKILL but the process still reports alive; it may be exiting." : "Terminated.";
+    } else detail = "Process was already gone; cleaned up session records.";
+    const reaped = reapSessionProcesses(projectPath);
+    removeSession(projectPath, browser);
+    removeSessionMarker(projectPath, browser);
+    try {
+        node_fs.rmSync(readyJsonPath(projectPath, browser), {
+            force: true
+        });
+    } catch  {}
+    const survivors = sessionProcessPids(projectPath);
+    const stopped = !isAlive(pid) && 0 === survivors.length;
+    if (survivors.length) detail += ` Warning: ${survivors.length} browser process(es) still alive after reap (pids ${survivors.join(", ")}).`;
+    else if (reaped.length) detail += ` Reaped ${reaped.length} browser process(es).`;
+    return {
+        projectPath,
+        browser,
+        pid,
+        stopped,
+        reaped,
+        detail
+    };
+}
+async function stop_handler(args) {
+    if (args.all) {
+        const candidates = new Map();
+        for (const s of listSessions())candidates.set(`${node_path.resolve(s.projectPath)}::${s.browser}`, s);
+        for (const m of listSessionMarkers()){
+            const key = `${node_path.resolve(m.projectPath)}::${m.browser}`;
+            if (!candidates.has(key)) candidates.set(key, m);
+        }
+        if (0 === candidates.size) return JSON.stringify({
+            stopped: [],
+            message: "No sessions registered in this server and no session markers on disk. Nothing to stop."
+        });
+        const outcomes = [];
+        for (const c of candidates.values())outcomes.push(await stopOne(c.projectPath, c.browser));
+        return JSON.stringify({
+            stopped: outcomes
+        });
+    }
+    if (!args.projectPath) return JSON.stringify({
+        error: "projectPath is required unless all=true. Pass the same projectPath used with extension_dev/extension_start."
+    });
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    const outcome = await stopOne(args.projectPath, browser);
+    return JSON.stringify(outcome);
+}
+const LAUNCH_FLAG_SCHEMA = {
+    profile: {
+        type: "string",
+        description: 'Browser profile path, or "false" to reuse the default user profile. Omit for a fresh throwaway profile.'
+    },
+    startingUrl: {
+        type: "string",
+        description: "URL the browser opens on launch"
+    },
+    chromiumBinary: {
+        type: "string",
+        description: "Path to a custom Chromium-based binary (overrides browser)"
+    },
+    geckoBinary: {
+        type: "string",
+        description: "Path to a custom Gecko/Firefox binary (overrides browser)"
+    },
+    host: {
+        type: "string",
+        description: "Dev server bind host. Use 0.0.0.0 for Docker or devcontainers. Defaults to 127.0.0.1"
+    },
+    publicHost: {
+        type: "string",
+        description: "Connectable host the browser dials for HMR and reload when it differs from the bind host"
+    },
+    extensions: {
+        type: "array",
+        items: {
+            type: "string"
+        },
+        description: "Companion extension paths or store URLs to load alongside the project"
+    }
+};
+function launchFlagArgs(args) {
+    const cli = [];
+    if (void 0 !== args.profile) cli.push("--profile", args.profile);
+    if (args.startingUrl) cli.push("--starting-url", args.startingUrl);
+    if (args.chromiumBinary) cli.push("--chromium-binary", args.chromiumBinary);
+    if (args.geckoBinary) cli.push("--gecko-binary", args.geckoBinary);
+    if (args.host) cli.push("--host", args.host);
+    if (args.publicHost) cli.push("--public-host", args.publicHost);
+    if (args.extensions?.length) cli.push("--extensions", args.extensions.join(","));
+    return cli;
+}
+const dev_schema = {
+    name: "extension_dev",
+    description: "Start the extension development server with hot module replacement. Launches a browser with the extension loaded. Returns process info for use with extension_wait and extension_source_inspect.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectPath: {
+                type: "string",
+                description: "Path to the extension project root"
+            },
+            browser: {
+                type: "string",
+                enum: [
+                    "chrome",
+                    "chromium",
+                    "edge",
+                    "brave",
+                    "opera",
+                    "vivaldi",
+                    "yandex",
+                    "firefox",
+                    "waterfox",
+                    "librewolf",
+                    "safari",
+                    "chromium-based",
+                    "gecko-based",
+                    "firefox-based",
+                    "webkit-based"
+                ],
+                default: "chrome"
+            },
+            port: {
                 type: "number",
-                description: "Server port (0 for auto-assign)"
+                description: "Dev server port (0 for auto-assign)"
             },
             noBrowser: {
                 type: "boolean",
                 default: false,
-                description: "Build and serve without launching a browser"
+                description: "Start dev server without launching browser"
             },
-            ...LAUNCH_FLAG_SCHEMA
+            polyfill: {
+                type: "boolean",
+                default: true,
+                description: "Apply cross-browser polyfill"
+            },
+            ...LAUNCH_FLAG_SCHEMA,
+            replace: {
+                type: "boolean",
+                default: false,
+                description: "Stop any live session already running for this projectPath before starting; the result then reports it as replacedSession. Without it, extension_dev refuses to start over a live session instead of silently forking it (two sessions fight over the browser profile and the newer browser dies on the profile lock)."
+            },
+            allowControl: {
+                type: "boolean",
+                default: false,
+                description: "Enable the agent-bridge control channel so extension_storage/reload/open/dom_inspect work against this session"
+            },
+            allowEval: {
+                type: "boolean",
+                default: false,
+                description: "Enable extension_eval (runs code in a context; writes a 0600 session token). Implies allowControl, so a single allowEval: true also unlocks storage/reload/open/dom_inspect. You do not need to pass both."
+            }
         },
         required: [
             "projectPath"
         ]
     }
 };
-async function start_handler(args) {
+async function dev_handler(args) {
     const browser = args.browser ?? "chrome";
+    const existing = liveProjectSessions(args.projectPath);
+    const replaced = [];
+    if (existing.length > 0) {
+        if (!args.replace) {
+            const listed = existing.map((s)=>`pid ${s.pid} (${s.browser})`).join(", ");
+            return JSON.stringify({
+                ok: false,
+                status: "session-exists",
+                projectPath: args.projectPath,
+                sessions: existing.map((s)=>({
+                        pid: s.pid,
+                        browser: s.browser
+                    })),
+                error: `A dev session is already running for this project (${listed}). Starting another would fork the session: both browsers contend for the same profile and the new one dies on the profile lock.`,
+                hint: "Call extension_stop with this projectPath first, or pass replace: true to have extension_dev stop the old session before starting the new one."
+            });
+        }
+        for (const s of existing){
+            await stopOne(args.projectPath, s.browser);
+            replaced.push({
+                pid: s.pid,
+                browser: s.browser
+            });
+        }
+    }
+    const allowControl = Boolean(args.allowControl || args.allowEval);
     const cliArgs = [
-        "start",
+        "dev",
         args.projectPath,
         "--browser",
         browser
     ];
-    if (false === args.polyfill) cliArgs.push("--polyfill", "false");
     if (void 0 !== args.port) cliArgs.push("--port", String(args.port));
     if (args.noBrowser) cliArgs.push("--no-browser");
+    if (false === args.polyfill) cliArgs.push("--polyfill", "false");
     cliArgs.push(...launchFlagArgs(args));
+    if (allowControl) cliArgs.push("--allow-control");
+    if (args.allowEval) cliArgs.push("--allow-eval");
     const spawnedAt = Date.now();
     const spawned = spawnExtensionCli(cliArgs, {
         projectDir: args.projectPath
@@ -1253,11 +1378,12 @@ async function start_handler(args) {
     registerSession({
         pid,
         browser,
+        port: args.port,
         projectPath: args.projectPath,
-        command: "start"
+        command: "dev"
     });
     child.on("exit", ()=>removeSession(args.projectPath, browser));
-    await new Promise((resolve)=>setTimeout(resolve, 5000));
+    await new Promise((resolve)=>setTimeout(resolve, 3000));
     const earlyOutput = spawned.readOutput();
     if (null !== child.exitCode || null !== child.signalCode) {
         const code = child.exitCode;
@@ -1270,39 +1396,80 @@ async function start_handler(args) {
             pid,
             exitCode: code,
             signal,
-            error: `The preview server exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running.`,
-            output: earlyOutput.slice(0, 2000),
+            error: `The dev server exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running, so extension_logs/wait/eval and the control verbs have nothing to attach to.`,
+            output: denoiseEarlyOutput(earlyOutput).slice(0, 2000),
             logPath,
-            hint: "Read `output` above for the cause: a failed production build, a port already in use, or a missing browser binary are the common ones. extension_build will surface a build error on its own."
+            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 exitStamp = browserExitStamp(args.projectPath, browser, spawnedAt);
-    if (exitStamp) return JSON.stringify({
+    const compileFailed = /compiled with errors|✖✖✖|ERROR in |Module not found|NOT FOUND/i.test(earlyOutput);
+    if (compileFailed) return JSON.stringify({
         ok: false,
-        status: "browser-exited",
+        status: "compile-failed",
         projectPath: args.projectPath,
         browser,
         pid,
-        ...exitStamp,
-        error: "The preview process is running but the browser it launched has exited (the extension may have been rejected or the browser crashed). The session cannot be driven.",
-        output: earlyOutput.slice(0, 2000),
+        error: "The dev server started but the FIRST COMPILE FAILED, so the browser has nothing usable to load. The session is running; the extension is not.",
+        output: denoiseEarlyOutput(earlyOutput).slice(0, 2000),
         logPath,
-        hint: "Read `output` above and extension_logs for the cause, then call extension_stop to clean up before retrying."
+        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);
+    if (exitStamp || profileLockHit) {
+        const profileDir = node_path.join(args.projectPath, "dist", `extension-profile-${browser}`);
+        return JSON.stringify({
+            ok: false,
+            status: "browser-exited",
+            projectPath: args.projectPath,
+            browser,
+            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),
+            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.`
+        });
+    }
+    const controlVerbs = "storage, reload, open, dom_inspect";
+    const capabilities = {
+        allowControl,
+        allowEval: Boolean(args.allowEval),
+        unlocked: allowControl ? args.allowEval ? `${controlVerbs}, eval` : controlVerbs : "none (read-only: logs, source_inspect, wait, doctor)"
+    };
     return JSON.stringify({
         ok: true,
         pid,
         browser,
+        port: args.port ?? 8080,
         projectPath: args.projectPath,
         status: "started",
-        hint: "Use extension_wait to check when the build and browser launch are complete. When you are done, call extension_stop to shut down the session.",
-        earlyOutput: earlyOutput.slice(0, 500),
+        ...replaced.length > 0 ? {
+            replacedSession: replaced[0],
+            ...replaced.length > 1 ? {
+                replacedSessions: replaced
+            } : {}
+        } : {},
+        capabilities,
+        hint: "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. " + (allowControl ? `Control channel is ON: extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : "Control channel is OFF: extension_storage/reload/open/dom_inspect need allowControl: true, and extension_eval needs allowEval: true (which also implies allowControl). To unlock them, call extension_dev again with the flag you need plus replace: true (it stops this session first); a plain second call is refused so the session does not fork.") + " When you are done, call extension_stop to shut down the dev server and browser.",
+        earlyOutput: denoiseEarlyOutput(earlyOutput).slice(0, 500),
         logPath
     });
 }
-const preview_schema = {
-    name: "extension_preview",
-    description: "Preview a production-built extension in a browser. Uses dist/ output directly. The extension must be built first with extension_build.",
+function denoiseEarlyOutput(raw) {
+    const NOISE = [
+        /^npm warn Unknown project config/i,
+        /This will stop working in the next major version of npm/i,
+        /^npm warn config/i,
+        /V8: .*Invalid asm\.js/i,
+        /^\(node:\d+\) V8:/i,
+        /Use `node --trace-warnings/i
+    ];
+    return raw.split("\n").filter((line)=>!NOISE.some((re)=>re.test(line.trim()))).join("\n").replace(/\n{2,}/g, "\n").trimStart();
+}
+const start_schema = {
+    name: "extension_start",
+    description: "Build the extension for production and immediately preview it in a browser. Combines build + preview in one step. No hot reload.",
     inputSchema: {
         type: "object",
         properties: {
@@ -1331,6 +1498,11 @@ const preview_schema = {
                 ],
                 default: "chrome"
             },
+            polyfill: {
+                type: "boolean",
+                default: true,
+                description: "Apply cross-browser polyfill"
+            },
             port: {
                 type: "number",
                 description: "Server port (0 for auto-assign)"
@@ -1338,7 +1510,7 @@ const preview_schema = {
             noBrowser: {
                 type: "boolean",
                 default: false,
-                description: "Serve the preview without launching a browser"
+                description: "Build and serve without launching a browser"
             },
             ...LAUNCH_FLAG_SCHEMA
         },
@@ -1347,14 +1519,15 @@ const preview_schema = {
         ]
     }
 };
-async function preview_handler(args) {
+async function start_handler(args) {
     const browser = args.browser ?? "chrome";
     const cliArgs = [
-        "preview",
+        "start",
         args.projectPath,
         "--browser",
         browser
     ];
+    if (false === args.polyfill) cliArgs.push("--polyfill", "false");
     if (void 0 !== args.port) cliArgs.push("--port", String(args.port));
     if (args.noBrowser) cliArgs.push("--no-browser");
     cliArgs.push(...launchFlagArgs(args));
@@ -1368,7 +1541,7 @@ async function preview_handler(args) {
         pid,
         browser,
         projectPath: args.projectPath,
-        command: "preview"
+        command: "start"
     });
     child.on("exit", ()=>removeSession(args.projectPath, browser));
     await new Promise((resolve)=>setTimeout(resolve, 5000));
@@ -1384,186 +1557,149 @@ async function preview_handler(args) {
             pid,
             exitCode: code,
             signal,
-            error: `The preview process exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). Nothing is running.`,
+            error: `The preview server exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running.`,
             output: earlyOutput.slice(0, 2000),
             logPath,
-            hint: "Read `output` above for the cause: a missing or broken dist/ (run extension_build first), or a missing browser binary are the common ones."
+            hint: "Read `output` above for the cause: a failed production build, a port already in use, or a missing browser binary are the common ones. extension_build will surface a build error on its own."
         });
     }
     const exitStamp = browserExitStamp(args.projectPath, browser, spawnedAt);
     if (exitStamp) return JSON.stringify({
         ok: false,
-        status: "browser-exited",
-        projectPath: args.projectPath,
-        browser,
-        pid,
-        ...exitStamp,
-        error: "The preview process is running but the browser it launched has exited (the extension may have been rejected or the browser crashed). The session cannot be driven.",
-        output: earlyOutput.slice(0, 2000),
-        logPath,
-        hint: "Read `output` above and extension_logs for the cause, then call extension_stop to clean up before retrying."
-    });
-    return JSON.stringify({
-        ok: true,
-        pid,
-        browser,
-        projectPath: args.projectPath,
-        status: "launched",
-        hint: "Call extension_stop when you are done to close the preview browser.",
-        earlyOutput: earlyOutput.slice(0, 500),
-        logPath
-    });
-}
-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.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            projectPath: {
-                type: "string",
-                description: "Path to the extension project root"
-            },
-            browser: {
-                type: "string",
-                description: "Browser of the session to stop (matches the browser passed to extension_dev/extension_start). Defaults to the one live session for this project when omitted, instead of assuming chrome."
-            },
-            all: {
-                type: "boolean",
-                default: false,
-                description: "Stop every session this server started, across projects and browsers. When true, projectPath/browser are ignored."
-            }
-        },
-        required: []
-    }
-};
-function pgrepPids(pattern) {
-    try {
-        const out = execFileSync("pgrep", [
-            "-f",
-            pattern
-        ], {
-            encoding: "utf8"
-        });
-        return out.split("\n").map((s)=>parseInt(s.trim(), 10)).filter((n)=>Number.isInteger(n) && n > 0 && n !== process.pid);
-    } catch  {
-        return [];
-    }
-}
-function sessionProcessPids(projectPath) {
-    const resolved = node_path.resolve(projectPath);
-    const pids = new Set();
-    for (const marker of [
-        `extension dev ${resolved}`,
-        node_path.join(resolved, "dist")
-    ])for (const pid of pgrepPids(marker))pids.add(pid);
-    return [
-        ...pids
-    ];
-}
-function reapSessionProcesses(projectPath) {
-    const pids = sessionProcessPids(projectPath);
-    for (const pid of pids)try {
-        process.kill(pid, "SIGKILL");
-    } catch  {}
-    return pids;
-}
-function isAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    } catch  {
-        return false;
-    }
-}
-function stop_signal(pid, sig) {
-    try {
-        process.kill(-pid, sig);
-        return true;
-    } catch  {
-        try {
-            process.kill(pid, sig);
-            return true;
-        } catch  {
-            return false;
-        }
-    }
-}
-function readyJsonPath(projectPath, browser) {
-    return node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
-}
-function pidFromReadyContract(projectPath, browser) {
-    try {
-        const raw = node_fs.readFileSync(readyJsonPath(projectPath, browser), "utf8");
-        const contract = JSON.parse(raw);
-        return "number" == typeof contract.pid ? contract.pid : null;
-    } catch  {
-        return null;
-    }
-}
-async function stopOne(projectPath, browser) {
-    const session = getSession(projectPath, browser);
-    const pid = session?.pid ?? pidFromReadyContract(projectPath, browser);
-    if (null == pid) {
-        const reaped = reapSessionProcesses(projectPath);
-        return {
-            projectPath,
-            browser,
-            pid: null,
-            stopped: 0 !== reaped.length,
-            reaped,
-            detail: 0 === reaped.length ? "No known session for this project/browser (nothing registered in this server and no ready.json contract found)." : `No dev pid on record, but reaped ${reaped.length} orphaned browser process(es) from the profile dir.`
-        };
-    }
-    let detail;
-    if (isAlive(pid)) {
-        stop_signal(pid, "SIGTERM");
-        await new Promise((resolve)=>setTimeout(resolve, 1500));
-        if (isAlive(pid)) {
-            stop_signal(pid, "SIGKILL");
-            await new Promise((resolve)=>setTimeout(resolve, 250));
-        }
-        detail = isAlive(pid) ? "Sent SIGTERM and SIGKILL but the process still reports alive; it may be exiting." : "Terminated.";
-    } else detail = "Process was already gone; cleaned up session records.";
-    const reaped = reapSessionProcesses(projectPath);
-    removeSession(projectPath, browser);
-    try {
-        node_fs.rmSync(readyJsonPath(projectPath, browser), {
-            force: true
-        });
-    } catch  {}
-    const survivors = sessionProcessPids(projectPath);
-    const stopped = !isAlive(pid) && 0 === survivors.length;
-    if (survivors.length) detail += ` Warning: ${survivors.length} browser process(es) still alive after reap (pids ${survivors.join(", ")}).`;
-    else if (reaped.length) detail += ` Reaped ${reaped.length} browser process(es).`;
-    return {
-        projectPath,
+        status: "browser-exited",
+        projectPath: args.projectPath,
         browser,
         pid,
-        stopped,
-        reaped,
-        detail
-    };
+        ...exitStamp,
+        error: "The preview process is running but the browser it launched has exited (the extension may have been rejected or the browser crashed). The session cannot be driven.",
+        output: earlyOutput.slice(0, 2000),
+        logPath,
+        hint: "Read `output` above and extension_logs for the cause, then call extension_stop to clean up before retrying."
+    });
+    return JSON.stringify({
+        ok: true,
+        pid,
+        browser,
+        projectPath: args.projectPath,
+        status: "started",
+        hint: "Use extension_wait to check when the build and browser launch are complete. When you are done, call extension_stop to shut down the session.",
+        earlyOutput: earlyOutput.slice(0, 500),
+        logPath
+    });
 }
-async function stop_handler(args) {
-    if (args.all) {
-        const sessions = listSessions();
-        if (0 === sessions.length) return JSON.stringify({
-            stopped: [],
-            message: "No sessions registered in this server."
-        });
-        const outcomes = [];
-        for (const s of sessions)outcomes.push(await stopOne(s.projectPath, s.browser));
+const preview_schema = {
+    name: "extension_preview",
+    description: "Preview a production-built extension in a browser. Uses dist/ output directly. The extension must be built first with extension_build.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectPath: {
+                type: "string",
+                description: "Path to the extension project root"
+            },
+            browser: {
+                type: "string",
+                enum: [
+                    "chrome",
+                    "chromium",
+                    "edge",
+                    "brave",
+                    "opera",
+                    "vivaldi",
+                    "yandex",
+                    "firefox",
+                    "waterfox",
+                    "librewolf",
+                    "safari",
+                    "chromium-based",
+                    "gecko-based",
+                    "firefox-based",
+                    "webkit-based"
+                ],
+                default: "chrome"
+            },
+            port: {
+                type: "number",
+                description: "Server port (0 for auto-assign)"
+            },
+            noBrowser: {
+                type: "boolean",
+                default: false,
+                description: "Serve the preview without launching a browser"
+            },
+            ...LAUNCH_FLAG_SCHEMA
+        },
+        required: [
+            "projectPath"
+        ]
+    }
+};
+async function preview_handler(args) {
+    const browser = args.browser ?? "chrome";
+    const cliArgs = [
+        "preview",
+        args.projectPath,
+        "--browser",
+        browser
+    ];
+    if (void 0 !== args.port) cliArgs.push("--port", String(args.port));
+    if (args.noBrowser) cliArgs.push("--no-browser");
+    cliArgs.push(...launchFlagArgs(args));
+    const spawnedAt = Date.now();
+    const spawned = spawnExtensionCli(cliArgs, {
+        projectDir: args.projectPath
+    });
+    const { child, logPath } = spawned;
+    const pid = child.pid;
+    registerSession({
+        pid,
+        browser,
+        projectPath: args.projectPath,
+        command: "preview"
+    });
+    child.on("exit", ()=>removeSession(args.projectPath, browser));
+    await new Promise((resolve)=>setTimeout(resolve, 5000));
+    const earlyOutput = spawned.readOutput();
+    if (null !== child.exitCode || null !== child.signalCode) {
+        const code = child.exitCode;
+        const signal = child.signalCode;
         return JSON.stringify({
-            stopped: outcomes
+            ok: false,
+            status: "exited",
+            projectPath: args.projectPath,
+            browser,
+            pid,
+            exitCode: code,
+            signal,
+            error: `The preview process exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). Nothing is running.`,
+            output: earlyOutput.slice(0, 2000),
+            logPath,
+            hint: "Read `output` above for the cause: a missing or broken dist/ (run extension_build first), or a missing browser binary are the common ones."
         });
     }
-    if (!args.projectPath) return JSON.stringify({
-        error: "projectPath is required unless all=true. Pass the same projectPath used with extension_dev/extension_start."
+    const exitStamp = browserExitStamp(args.projectPath, browser, spawnedAt);
+    if (exitStamp) return JSON.stringify({
+        ok: false,
+        status: "browser-exited",
+        projectPath: args.projectPath,
+        browser,
+        pid,
+        ...exitStamp,
+        error: "The preview process is running but the browser it launched has exited (the extension may have been rejected or the browser crashed). The session cannot be driven.",
+        output: earlyOutput.slice(0, 2000),
+        logPath,
+        hint: "Read `output` above and extension_logs for the cause, then call extension_stop to clean up before retrying."
+    });
+    return JSON.stringify({
+        ok: true,
+        pid,
+        browser,
+        projectPath: args.projectPath,
+        status: "launched",
+        hint: "Call extension_stop when you are done to close the preview browser.",
+        earlyOutput: earlyOutput.slice(0, 500),
+        logPath
     });
-    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
-    const outcome = await stopOne(args.projectPath, browser);
-    return JSON.stringify(outcome);
 }
 const RAW_BASE = "https://raw.githubusercontent.com/extension-js/examples/main/examples";
 const get_template_source_schema = {
@@ -4327,6 +4463,109 @@ async function publish(options = {}) {
         data
     };
 }
+const REGISTRY_BASE_DEFAULT = "https://registry.extension.land";
+const CONSOLE_BASE = "https://console.extension.dev";
+function registryBase() {
+    const fromEnv = String(process.env.EXTENSION_DEV_REGISTRY_URL || "").trim();
+    return (fromEnv || REGISTRY_BASE_DEFAULT).replace(/\/+$/, "");
+}
+function resolveProjectRef(overrides) {
+    const workspace = String(overrides?.workspace || "").trim();
+    const project = String(overrides?.project || "").trim();
+    if (workspace && project) return {
+        workspace,
+        project
+    };
+    const creds = readCredentials();
+    const ws = workspace || String(creds?.workspaceSlug || "").trim();
+    const proj = project || String(creds?.projectSlug || "").trim();
+    if (!ws || !proj) return null;
+    return {
+        workspace: ws,
+        project: proj
+    };
+}
+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}`;
+}
+async function fetchRegistryJson(url, fetchImpl = fetch) {
+    let res;
+    try {
+        res = await fetchImpl(url);
+    } catch (err) {
+        return {
+            ok: false,
+            message: `Could not reach ${url}: ${err?.message || err}`
+        };
+    }
+    if (!res.ok) return {
+        ok: false,
+        status: res.status,
+        message: `${url} returned ${res.status}`
+    };
+    try {
+        const text = await res.text();
+        return {
+            ok: true,
+            json: JSON.parse(text)
+        };
+    } catch  {
+        return {
+            ok: false,
+            message: `${url} did not return valid JSON`
+        };
+    }
+}
+function parseChannels(json) {
+    if (!json || "object" != typeof json || Array.isArray(json)) return [];
+    const out = [];
+    for (const [channel, raw] of Object.entries(json)){
+        if (!raw || "object" != typeof raw) continue;
+        const row = raw;
+        const description = "string" == typeof row.description ? row.description : void 0;
+        const promotedAtField = "string" == typeof row.promotedAt && row.promotedAt ? row.promotedAt : void 0;
+        const fromDescription = description?.match(/\bon (\d{4}-\d{2}-\d{2}T[0-9:.]+Z?)/)?.[1];
+        const entry = {
+            channel,
+            sha: String(row.sha ?? "")
+        };
+        if (row.buildId) entry.buildId = String(row.buildId);
+        if (row.version) entry.version = String(row.version);
+        const promotedAt = promotedAtField || fromDescription;
+        if (promotedAt) entry.promotedAt = promotedAt;
+        if (description) entry.description = description;
+        out.push(entry);
+    }
+    return out;
+}
+function parseBuildIndex(json) {
+    const items = json?.items;
+    if (!Array.isArray(items)) return [];
+    const out = [];
+    for (const raw of items){
+        if (!raw || "object" != typeof raw) continue;
+        const row = raw;
+        const sha = String(row.shortSha ?? row.sha ?? row.id ?? row.buildId ?? "").trim();
+        if (!sha) continue;
+        const entry = {
+            sha
+        };
+        if (row.commit) entry.commit = String(row.commit);
+        if (row.channel) entry.channel = String(row.channel);
+        if (row.buildEnv) entry.buildEnv = String(row.buildEnv);
+        if (row.status) entry.status = String(row.status);
+        if (row.version) entry.version = String(row.version);
+        if ("string" == typeof row.message) entry.message = row.message.split("\n", 1)[0];
+        if (row.timestamp) entry.timestamp = String(row.timestamp);
+        if (Array.isArray(row.browsers)) entry.browsers = row.browsers.map((b)=>String(b)).filter(Boolean);
+        out.push(entry);
+    }
+    return out;
+}
 const publish_schema = {
     name: "extension_publish",
     description: "Publish the project your stored token is scoped to (from extension_login, or EXTENSION_DEV_TOKEN) to extension.dev and return its shareable URL. The publish target is the token's project -- there is no projectPath, the local files are not uploaded. For a PUBLIC project the URL is the canonical public page and ttlHours does not apply; for a PRIVATE project it is a fresh time-limited share link (?share=) whose lifetime is ttlHours. Posts to the platform's CLI publish endpoint. Besides extension_login this is the only tool that talks to the hosted platform.",
@@ -4377,6 +4616,28 @@ async function publish_handler(args) {
     if (!result.ok) return JSON.stringify(result);
     const data = result.data;
     if (null != args.ttlHours && "public" === data.visibility) data.note = "ttlHours was ignored: this is a public project, whose share URL is its canonical public page.";
+    const ref = resolveProjectRef();
+    if (ref) {
+        const buildsUrl = registryFileUrl(ref, "builds/index.json");
+        const buildsRes = await fetchRegistryJson(buildsUrl);
+        if (buildsRes.ok) {
+            const items = parseBuildIndex(buildsRes.json);
+            const pinned = args.buildSha ? items.find((item)=>{
+                const short = String(args.buildSha).slice(0, 7).toLowerCase();
+                return item.sha.toLowerCase() === short || String(item.commit ?? "").toLowerCase().startsWith(short);
+            }) : void 0;
+            const newestSuccess = items.filter((item)=>"success" === item.status).sort((a, b)=>String(b.timestamp ?? "").localeCompare(String(a.timestamp ?? "")))[0];
+            const served = pinned ?? newestSuccess;
+            if (served) {
+                if (null == data.buildSha) data.buildSha = served.sha;
+                if (null == data.builtAt && served.timestamp) data.builtAt = served.timestamp;
+                if (null == data.version && served.version) data.version = served.version;
+                if (null == data.channel && served.channel) data.channel = served.channel;
+                data.registryUrl = buildsUrl;
+                if (!pinned && null == args.buildSha) data.buildNote = "buildSha/builtAt/version describe the newest successful build in the project's registry index, which is what the share link serves. Pin buildSha to serve a specific build.";
+            }
+        }
+    }
     return JSON.stringify(data);
 }
 const release_promote_DEFAULT_API = "https://www.extension.dev";
@@ -4472,9 +4733,111 @@ async function release_promote_handler(args) {
             message: text
         };
     }
-    if (!res.ok) return release_promote_fail("ReleaseError", `promote failed (${res.status}): ${data?.message || text || "unknown error"}`);
+    if (!res.ok) {
+        const code = "string" == typeof data?.code ? data.code : void 0;
+        const enrich = {};
+        const ref = resolveProjectRef();
+        if (404 === res.status || "UNKNOWN_BUILD" === code) {
+            enrich.buildsPageUrl = consoleProjectUrl(ref, "builds");
+            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");
+                const channelsRes = await fetchRegistryJson(channelsUrl);
+                if (channelsRes.ok) {
+                    const rows = parseChannels(channelsRes.json).filter((c)=>c.sha);
+                    enrich.validChannelShas = Object.fromEntries(rows.map((c)=>[
+                            c.channel,
+                            c.sha
+                        ]));
+                    enrich.registryChannelsUrl = channelsUrl;
+                }
+            }
+        }
+        return JSON.stringify({
+            ok: false,
+            error: {
+                name: "ReleaseError",
+                message: `promote failed (${res.status}): ${data?.message || text || "unknown error"}`,
+                ...code ? {
+                    code
+                } : {}
+            },
+            ...enrich
+        });
+    }
     return JSON.stringify(data);
 }
+const release_list_schema = {
+    name: "extension_release_list",
+    description: "List the project's release channels (channel -> promoted build sha) and recent builds from the public registry (registry.extension.land), so you can pick a valid buildSha for extension_release_promote, extension_deploy, or extension_publish. Read-only, no dispatch. Defaults to the logged-in project (extension_login); pass workspace + project to inspect another public project. Also returns the registry URLs it read and the console Builds page URL.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            workspace: {
+                type: "string",
+                description: "Workspace slug override (defaults to the stored login's workspace)."
+            },
+            project: {
+                type: "string",
+                description: "Project slug override (defaults to the stored login's project)."
+            }
+        },
+        required: []
+    }
+};
+function release_list_fail(name, message, extra) {
+    return JSON.stringify({
+        ok: false,
+        error: {
+            name,
+            message
+        },
+        ...extra ?? {}
+    });
+}
+async function release_list_handler(args) {
+    const ref = resolveProjectRef(args);
+    if (!ref) return release_list_fail("ReleaseListInputError", "No project to list. Run extension_login (the stored login names the project), or pass workspace + project explicitly.");
+    const channelsUrl = registryFileUrl(ref, "channels.json");
+    const metaUrl = registryFileUrl(ref, "meta.json");
+    const buildsUrl = registryFileUrl(ref, "builds/index.json");
+    const [channelsRes, metaRes, buildsRes] = await Promise.all([
+        fetchRegistryJson(channelsUrl),
+        fetchRegistryJson(metaUrl),
+        fetchRegistryJson(buildsUrl)
+    ]);
+    const buildsPageUrl = consoleProjectUrl(ref, "builds");
+    if (!channelsRes.ok && !metaRes.ok && !buildsRes.ok) return release_list_fail("ReleaseListNotFound", `No registry data for ${ref.workspace}/${ref.project} (${channelsUrl} returned ${channelsRes.status ?? "no response"}). The project may have no builds yet, be private (private registry data needs a share token), or the workspace/project slugs may be wrong. The console Builds page is the authoritative view: ${buildsPageUrl}`, {
+        workspace: ref.workspace,
+        project: ref.project,
+        registryUrl: channelsUrl,
+        buildsPageUrl
+    });
+    const channels = channelsRes.ok ? parseChannels(channelsRes.json) : [];
+    const recentBuilds = buildsRes.ok ? parseBuildIndex(buildsRes.json) : [];
+    recentBuilds.sort((a, b)=>String(b.timestamp ?? "").localeCompare(String(a.timestamp ?? "")));
+    const meta = metaRes.ok ? metaRes.json : void 0;
+    const promotable = Array.from(new Set(channels.map((c)=>c.sha).filter(Boolean)));
+    const result = {
+        ok: true,
+        workspace: ref.workspace,
+        project: ref.project,
+        ...meta?.name ? {
+            name: meta.name
+        } : {},
+        ...meta?.visibility ? {
+            visibility: meta.visibility
+        } : {},
+        channels,
+        recentBuilds,
+        registryUrl: channelsUrl,
+        buildsPageUrl,
+        message: promotable.length > 0 || recentBuilds.length > 0 ? `Promotable shas: channels currently pin ${promotable.length > 0 ? promotable.join(", ") : "none"}; recent builds add ${recentBuilds.filter((b)=>"success" === b.status).map((b)=>b.sha).join(", ") || "none"}. Use one of these as buildId/buildSha for promote/deploy/publish.` : `No channels or builds are recorded on the registry yet for ${ref.workspace}/${ref.project}. Push a commit to produce a build, then check ${buildsPageUrl}.`
+    };
+    if (!channelsRes.ok) result.channelsUnavailable = `channels.json unreadable: ${channelsRes.message}`;
+    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");
@@ -4598,13 +4961,86 @@ async function deploy_handler(args) {
             message: text
         };
     }
-    if (!res.ok) return deploy_fail("DeployError", `submit failed (${res.status}): ${data?.message || text || "unknown error"}`);
-    const warnings = storeMdWarnings(browsers, process.cwd());
+    if (!res.ok) return deploy_fail("DeployError", `${dryRun ? "preflight" : "submit"} failed (${res.status}): ${data?.message || text || "unknown error"}`);
+    const warnings = Array.isArray(data?.warnings) ? [
+        ...data.warnings
+    ] : [];
+    warnings.push(...storeMdWarnings(browsers, process.cwd()));
     const result = {
         mode: "platform",
         dryRun,
         ...data
     };
+    if (dryRun) {
+        const ref = resolveProjectRef();
+        const consoleStoresUrl = consoleProjectUrl(ref, "stores");
+        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;
+        let channelRows = null;
+        if (ref) {
+            const [healthRes, channelsRes] = await Promise.all([
+                fetchRegistryJson(registryFileUrl(ref, "stores/health.json")),
+                fetchRegistryJson(registryFileUrl(ref, "channels.json"))
+            ]);
+            if (healthRes.ok) {
+                const stores = healthRes.json?.stores;
+                health = stores && "object" == typeof stores ? stores : null;
+                if (!health) healthUnreadable = "stores/health.json had no stores map";
+            } else healthUnreadable = healthRes.message;
+            if (channelsRes.ok) channelRows = parseChannels(channelsRes.json);
+        } else healthUnreadable = "no stored workspace/project to look up (run extension_login)";
+        const preflight = browsers.map((browser)=>{
+            if (!health) return {
+                browser,
+                ok: false,
+                configured: "unknown",
+                publishMode: "unknown",
+                reason: `Store configuration could not be read (${healthUnreadable}); verify the ${browser} store in the console before submitting.`
+            };
+            const row = health[browser];
+            if (!row) return {
+                browser,
+                ok: false,
+                configured: false,
+                publishMode: "unknown",
+                reason: `No ${browser} store is configured on this project; a real submission for ${browser} would fail. Configure it at ${consoleStoresUrl}.`
+            };
+            if (true !== row.ok) return {
+                browser,
+                ok: false,
+                configured: false,
+                publishMode: "unknown",
+                reason: String(row.message || "").trim() || `The ${browser} store failed its last credential health check.`
+            };
+            return {
+                browser,
+                ok: true,
+                configured: true,
+                publishMode: "unknown"
+            };
+        });
+        const actionable = preflight.filter((p)=>p.ok).map((p)=>p.browser);
+        const blocked = preflight.filter((p)=>!p.ok);
+        const channelDefaulted = !String(args.channel || "").trim();
+        const resolvedChannel = String(data?.channel || "").trim() || (channelDefaulted ? "stable" : String(args.channel).trim());
+        if (channelRows) {
+            const exists = channelRows.some((r)=>r.channel === resolvedChannel || r.channel.endsWith(`-${resolvedChannel}`));
+            if (!exists) warnings.push(`Channel "${resolvedChannel}"${channelDefaulted ? " (the default)" : ""} does not exist in this project's channels.json (existing: ${channelRows.map((r)=>r.channel).join(", ") || "none"}), so a real submission from it has no promoted build to serve. Promote a build there first (extension_release_promote) or pass an existing channel.`);
+        }
+        const summaryParts = [];
+        if (actionable.length > 0) summaryParts.push(`Preflight passed for ${actionable.join(", ")}: the platform verified auth, the project, build ${data?.buildId ?? buildSha}, and the store workflow, and the store credentials passed their last health check.`);
+        for (const p of blocked)summaryParts.push(`${p.browser}: ${"unknown" === p.configured ? "cannot be verified" : "NOT actionable"} - ${p.reason}`);
+        summaryParts.push(storeModeNote);
+        result.ok = actionable.length > 0;
+        result.preflight = preflight;
+        result.channel = resolvedChannel;
+        result.channelDefaulted = channelDefaulted;
+        if (channelDefaulted) result.channelNote = `channel: ${resolvedChannel} (default)`;
+        result.consoleStoresUrl = consoleStoresUrl;
+        if ("string" == typeof data?.message) result.platformMessage = data.message;
+        result.message = summaryParts.join(" ");
+    }
     if (warnings.length > 0) result.warnings = warnings;
     return JSON.stringify(result);
 }
@@ -5370,13 +5806,28 @@ function success(creds) {
     });
 }
 function login_pending(start) {
+    const complete = String(start.verificationUriComplete || "").trim();
+    const hasCompleteLink = complete.length > 0 && complete !== start.verificationUri;
+    const message = hasCompleteLink ? `Open ${complete} and approve (code ${start.userCode} is pre-filled), then call extension_login again with this deviceCode (and the same project). If the page asks for a code, enter ${start.userCode} at ${start.verificationUri}.` : `Open ${start.verificationUri} and enter code ${start.userCode}, then call extension_login again with this deviceCode (and the same project).`;
     return JSON.stringify({
         ok: false,
         status: "authorization_pending",
         userCode: start.userCode,
         verificationUri: start.verificationUri,
+        ...hasCompleteLink ? {
+            verificationUriComplete: complete
+        } : {},
         deviceCode: start.deviceCode,
-        message: `Open ${start.verificationUri} and enter code ${start.userCode}, then call extension_login again with this deviceCode (and the same project).`
+        message
+    });
+}
+function resumePending(deviceCode, verificationUri) {
+    return JSON.stringify({
+        ok: false,
+        status: "authorization_pending",
+        verificationUri,
+        deviceCode,
+        message: `Still waiting for authorization. The one-click link and code from the previous response are still valid: open that link (or enter the code at ${verificationUri}), then call extension_login again with this same deviceCode (and the same project).`
     });
 }
 async function login_handler(args) {
@@ -5403,11 +5854,7 @@ async function login_handler(args) {
             if ("expired" === poll.reason) return login_fail("LoginExpired", "The device code expired. Run extension_login again to restart.");
             if ("denied" === poll.reason) return login_fail("LoginDenied", "Authorization was denied at extension.dev/device.");
             if ("error" === poll.reason) return login_fail("LoginError", poll.message || "Device login failed.");
-            return login_pending({
-                deviceCode: String(args.deviceCode),
-                userCode: "(see the previous response)",
-                verificationUri: config.verificationUri
-            });
+            return resumePending(String(args.deviceCode), config.verificationUri);
         }
         let start;
         try {
@@ -5432,7 +5879,8 @@ async function login_handler(args) {
         return login_pending({
             deviceCode: start.deviceCode,
             userCode: start.userCode,
-            verificationUri: start.verificationUri
+            verificationUri: start.verificationUri,
+            verificationUriComplete: start.verificationUriComplete
         });
     }
     if (args.deviceCode) {
@@ -5445,11 +5893,7 @@ async function login_handler(args) {
         if (!poll.ok) {
             if ("expired" === poll.reason) return login_fail("LoginExpired", "The device code expired. Run extension_login again to restart.");
             if ("denied" === poll.reason) return login_fail("LoginDenied", "Authorization was denied on GitHub.");
-            return login_pending({
-                deviceCode: String(args.deviceCode),
-                userCode: "(see the previous response)",
-                verificationUri: "https://github.com/login/device"
-            });
+            return resumePending(String(args.deviceCode), "https://github.com/login/device");
         }
         try {
             const creds = await exchangeAndPersist({
@@ -6102,6 +6546,12 @@ const ARG_ALIASES = {
     ],
     browser: [
         "browserName"
+    ],
+    buildSha: [
+        "buildId"
+    ],
+    buildId: [
+        "buildSha"
     ]
 };
 function normalizeArgAliases(inputSchema, args) {
@@ -6145,13 +6595,33 @@ function validateToolInput(inputSchema, args) {
     }
     return issues;
 }
-function inputValidationError(toolName, issues) {
+function describeToolArgs(inputSchema) {
+    const schema = inputSchema;
+    const props = schema.properties ?? {};
+    const required = schema.required ?? [];
+    const optional = Object.keys(props).filter((k)=>!required.includes(k));
+    const aliases = {};
+    for (const [canonical, list] of Object.entries(ARG_ALIASES)){
+        if (!(canonical in props)) continue;
+        const usable = list.filter((alias)=>!(alias in props));
+        if (usable.length) aliases[canonical] = usable;
+    }
+    return {
+        required,
+        optional,
+        aliases
+    };
+}
+function inputValidationError(toolName, issues, inputSchema) {
     return JSON.stringify({
         ok: false,
         error: {
             name: "InputValidationError",
             message: `Invalid arguments for ${toolName}: ${issues.map((i)=>`${i.path}: ${i.message}`).join("; ")}`,
-            issues
+            issues,
+            ...inputSchema ? {
+                args: describeToolArgs(inputSchema)
+            } : {}
         }
     });
 }
@@ -6175,6 +6645,7 @@ const tools = [
     open_namespaceObject,
     dom_inspect_namespaceObject,
     tools_publish_namespaceObject,
+    release_list_namespaceObject,
     release_promote_namespaceObject,
     deploy_namespaceObject,
     wait_namespaceObject,
@@ -6227,7 +6698,7 @@ async function startServer() {
             content: [
                 {
                     type: "text",
-                    text: inputValidationError(name, issues)
+                    text: inputValidationError(name, issues, tool.schema.inputSchema)
                 }
             ],
             isError: true