@extension.dev/mcp 10.10.10 → 10.10.12

package/dist/module.js

@@ -247,7 +247,7 @@ __webpack_require__.d(workspace_create_namespaceObject, {
     handler: ()=>workspace_create_handler,
     schema: ()=>workspace_create_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"10.10.10","El":{"OP":"4.1.31"}}');
+var package_namespaceObject = JSON.parse('{"rE":"10.10.12","El":{"OP":"4.1.31"}}');
 const ENVELOPE_SCHEMA = 1;
 const collectWarnings = (warnings)=>{
     if (!warnings) return [];
@@ -301,8 +301,24 @@ function descendantPids(pid) {
         return [];
     }
 }
+function killWindowsTree(pid) {
+    try {
+        execFileSync("taskkill", [
+            "/PID",
+            String(pid),
+            "/T",
+            "/F"
+        ], {
+            stdio: "ignore"
+        });
+        return true;
+    } catch  {
+        return false;
+    }
+}
 function killTree(pid, signal) {
     if (!pid) return;
+    if ("win32" === process.platform) return void killWindowsTree(pid);
     for (const target of [
         ...descendantPids(pid).reverse(),
         pid
@@ -1148,6 +1164,21 @@ function safeApiBase(raw, callerSupplied) {
         base: `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, "")
     };
 }
+function readJsonObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || "object" != typeof parsed || Array.isArray(parsed)) return {
+            problem: "not a JSON object"
+        };
+        return {
+            value: parsed
+        };
+    } catch (err) {
+        return {
+            problem: err instanceof Error ? err.message : String(err)
+        };
+    }
+}
 async function fetchLoginConfig(apiBase, fetchImpl = fetch) {
     const res = await fetchImpl(`${apiBase}/api/cli/login/config`, {
         headers: {
@@ -1155,7 +1186,9 @@ async function fetchLoginConfig(apiBase, fetchImpl = fetch) {
         }
     });
     if (!res.ok) throw new Error(`Could not fetch login config from ${apiBase} (${res.status}).`);
-    const data = await res.json().catch(()=>({}));
+    const read = readJsonObject(await res.text());
+    if ("problem" in read) throw new Error(`The login config at ${apiBase}/api/cli/login/config answered ${res.status} but could not be read (${read.problem}), so what this platform supports is unknown.`);
+    const data = read.value;
     return {
         deviceCodeUrl: String(data.deviceCodeUrl || "/api/cli/device/code"),
         deviceTokenUrl: String(data.deviceTokenUrl || "/api/cli/device/token"),
@@ -1625,6 +1658,23 @@ function userlandProjectUrl(ref, page = "", apiHint) {
         return "";
     }
 }
+function channelsShapeProblem(json) {
+    if (!json || "object" != typeof json || Array.isArray(json)) return "the body is not a channels map";
+    const bad = Object.entries(json).find(([, row])=>!row || "object" != typeof row);
+    return bad ? `channel ${bad[0]} is not an object` : null;
+}
+function buildIndexShapeProblem(json) {
+    const items = json?.items;
+    return Array.isArray(items) ? null : "the body has no items list";
+}
+function requireShape(read, problem) {
+    if (!read.ok) return read;
+    const why = problem(read.json);
+    return why ? {
+        ok: false,
+        message: `answered 200 but ${why}`
+    } : read;
+}
 async function readJson(url, res) {
     try {
         const text = await res.text();
@@ -2317,7 +2367,7 @@ const SESSION_BROWSER = {
 };
 const CALL_TIMEOUT = {
     type: "number",
-    description: "Command timeout in ms (default 5000)"
+    description: "Command timeout in ms. When omitted, the default depends on the route: 30000 through the dev session's control channel, 10000 over the Firefox debugger protocol, and 15000 per command over the Chromium debug port."
 };
 const API_BASE = {
     type: "string",
@@ -4709,7 +4759,10 @@ function writeMarkerBestEffort(info, registeredAtMs) {
             serverPid: process.pid,
             registeredAt: new Date(registeredAtMs).toISOString()
         }));
-    } catch  {}
+        return null;
+    } catch (error) {
+        return `The session marker could not be written to ${markerDir()} (${error instanceof Error ? error.message : String(error)}), so if this server restarts, extension_stop (all: true) and the fork guard will not see this session; stop it by projectPath and browser, or by its pid ${info.pid}.`;
+    }
 }
 function registerSession(info) {
     const key = sessionKey(info.projectPath, info.browser);
@@ -4720,7 +4773,7 @@ function registerSession(info) {
         at
     });
     process_manager_sessions.set(key, info);
-    writeMarkerBestEffort(info, at);
+    return writeMarkerBestEffort(info, at);
 }
 function sessionSinceMs(projectPath, browser) {
     const stamp = registrationStamps.get(sessionKey(projectPath, browser));
@@ -4752,7 +4805,53 @@ function listSessions() {
     return Array.from(process_manager_sessions.values());
 }
 const PLAUSIBLE_SESSION_BINARY = /chrom|edge|brave|opera|vivaldi|yandex|firefox|waterfox|librewolf|zen|floorp|safari|node|electron|extension/i;
+function readWindowsProcessTable() {
+    try {
+        const out = execFileSync("powershell", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "[Console]::OutputEncoding = [Text.Encoding]::UTF8; Get-CimInstance Win32_Process | ForEach-Object { \"$($_.ProcessId)`t$($_.Name)`t$($_.CommandLine)\" }"
+        ], {
+            encoding: "utf8",
+            windowsHide: true,
+            maxBuffer: 67108864
+        });
+        const rows = [];
+        for (const line of out.split(/\r?\n/)){
+            const [pidText, name = "", ...rest] = line.split("\t");
+            const pid = Number.parseInt(pidText ?? "", 10);
+            if (Number.isInteger(pid) && pid > 0) rows.push({
+                pid,
+                name,
+                commandLine: rest.join("\t")
+            });
+        }
+        return rows.length ? rows : null;
+    } catch  {
+        return null;
+    }
+}
+function windowsImageName(pid) {
+    try {
+        const out = execFileSync("tasklist", [
+            "/FI",
+            `PID eq ${pid}`,
+            "/FO",
+            "CSV",
+            "/NH"
+        ], {
+            encoding: "utf8",
+            windowsHide: true
+        });
+        const match = /^"([^"]+)","(\d+)"/m.exec(out);
+        return match && Number(match[2]) === pid ? match[1] : "";
+    } catch  {
+        return "";
+    }
+}
 function processCommand(pid) {
+    if ("win32" === process.platform) return windowsImageName(pid);
     try {
         const cmdline = node_fs.readFileSync(`/proc/${pid}/cmdline`, "utf8");
         const argv0 = cmdline.split("\0")[0];
@@ -6200,8 +6299,8 @@ async function build_handler(args) {
     const engineRefusedJsonOutput = !engineKnownTooOld && 0 !== attempt.code && refusedTheOutputFlag(attempt.stderr ?? "");
     if (engineRefusedJsonOutput) attempt = await runExtensionCli(cliArgs, spawn);
     const { code, stdout, stderr } = attempt;
-    if (engineRefusedJsonOutput) warnings.push("The Extension.js installed in this project is older than the one this server expects: it rejected --output json on build, so the build was run a second time without that flag and the result was read from the build summary the engine writes into dist/extension-js/. The extension that came out is exactly the same one. Upgrade the project's Extension.js to get the richer report back, including the Safari app identity and the byte totals from the run that just happened, and to stop paying for the second build.");
-    else if (engineKnownTooOld) warnings.push(`The Extension.js installed in this project is older than the one this server expects: it reports ${verdict.version}, and --output json only reached extension build in ${verdict.floor}, so the build was run without that flag and the result was read from the build summary the engine writes into dist/extension-js/. The extension that came out is exactly the same one, and nothing was built twice. Upgrade the project's Extension.js to get the richer report back, including the Safari app identity and the byte totals from the run that just happened.`);
+    if (engineRefusedJsonOutput) warnings.push("The Extension.js installed in this project is older than the one this server expects: it rejected --output json on build, so the build was run a second time without that flag and the result comes from the build summary the engine writes into dist/extension-js/ when this run left one there (a separate warning names the path when it did not). The extension that came out is exactly the same one. Upgrade the project's Extension.js to get the richer report back, including the Safari app identity and the byte totals from the run that just happened, and to stop paying for the second build.");
+    else if (engineKnownTooOld) warnings.push(`The Extension.js installed in this project is older than the one this server expects: it reports ${verdict.version}, and --output json only reached extension build in ${verdict.floor}, so the build was run without that flag and the result comes from the build summary the engine writes into dist/extension-js/ when this run left one there (a separate warning names the path when it did not). The extension that came out is exactly the same one, and nothing was built twice. Upgrade the project's Extension.js to get the richer report back, including the Safari app identity and the byte totals from the run that just happened.`);
     const duration = Date.now() - start;
     const engine = readEngineOutput(stdout ?? "", stderr ?? "");
     const out = engine.narration;
@@ -6710,7 +6809,13 @@ function cleanCarrier(projectPath) {
         carrierNote: `${removal.note} The carrier is still at ${removal.path}; the engine loads ./extensions, so remove it by hand before the next run.`
     } : {};
 }
-function pgrepPids(pattern) {
+function pgrepPids(pattern, windowsTable) {
+    if ("win32" === process.platform) {
+        const table = windowsTable ? windowsTable() : readWindowsProcessTable();
+        if (!table) return null;
+        const matcher = new RegExp(pattern, "i");
+        return table.filter((row)=>row.pid !== process.pid && matcher.test(row.commandLine)).map((row)=>row.pid);
+    }
     try {
         const out = execFileSync("pgrep", [
             "-f",
@@ -6763,8 +6868,13 @@ function sessionProcessPids(projectPath, hints = {
 }) {
     const pids = new Set();
     let verified = true;
+    let table;
+    const windowsTable = ()=>{
+        if (void 0 === table) table = readWindowsProcessTable();
+        return table;
+    };
     const found = (pattern)=>{
-        const hits = pgrepPids(pattern);
+        const hits = pgrepPids(pattern, windowsTable);
         if (null === hits) {
             verified = false;
             return [];
@@ -6788,14 +6898,31 @@ function sessionProcessPids(projectPath, hints = {
         verified
     };
 }
-function reapSessionProcesses(projectPath, hints = {
+async function reapSessionProcesses(projectPath, hints = {
     pids: []
 }) {
     const { pids } = sessionProcessPids(projectPath, hints);
-    for (const pid of pids)try {
-        process.kill(pid, "SIGKILL");
-    } catch  {}
-    return pids;
+    if (0 === pids.length) return {
+        reaped: [],
+        unconfirmed: []
+    };
+    for (const pid of pids){
+        if ("win32" === process.platform) {
+            killWindowsTree(pid);
+            continue;
+        }
+        try {
+            process.kill(pid, "SIGKILL");
+        } catch  {}
+    }
+    await new Promise((resolve)=>setTimeout(resolve, 250));
+    const reaped = [];
+    const unconfirmed = [];
+    for (const pid of pids)("dead" === pidState(pid) ? reaped : unconfirmed).push(pid);
+    return {
+        reaped,
+        unconfirmed
+    };
 }
 function isAlive(pid) {
     try {
@@ -6806,6 +6933,7 @@ function isAlive(pid) {
     }
 }
 function stop_signal(pid, sig) {
+    if ("win32" === process.platform) return killWindowsTree(pid);
     try {
         process.kill(-pid, sig);
         return true;
@@ -6832,16 +6960,21 @@ async function stopOne(projectPath, browser) {
     const pid = session?.pid ?? pidFromReadyContract(projectPath, browser);
     const hints = contractProcessHints(projectPath, browser);
     if (null == pid) {
-        const reaped = reapSessionProcesses(projectPath, hints);
+        const { reaped, unconfirmed } = await reapSessionProcesses(projectPath, hints);
         removeSessionMarker(projectPath, browser);
+        let detail;
+        detail = unconfirmed.length ? `No dev pid on record. Killed orphaned browser process(es) from the profile dir, but ${unconfirmed.length} still report alive 250 ms later (pids ${unconfirmed.join(", ")})${reaped.length ? `; ${reaped.length} confirmed gone` : ""}.` : reaped.length ? `No dev pid on record, but reaped ${reaped.length} orphaned browser process(es) from the profile dir, each confirmed gone.` : "No known session for this project/browser (nothing registered in this server and no ready.json contract found).";
         return {
             projectPath,
             browser,
             pid: null,
-            stopped: 0 !== reaped.length,
+            stopped: reaped.length > 0 && 0 === unconfirmed.length,
             reaped,
+            ...unconfirmed.length ? {
+                reapUnconfirmed: unconfirmed
+            } : {},
             ...cleanCarrier(projectPath),
-            detail: 0 === reaped.length ? "No known session for this project/browser (nothing registered in this server and no ready.json contract found)." : `No dev pid on record, but reaped ${reaped.length} orphaned browser process(es) from the profile dir.`
+            detail
         };
     }
     let detail;
@@ -6875,7 +7008,7 @@ async function stopOne(projectPath, browser) {
         }
         detail = isAlive(pid) ? "Sent SIGTERM and SIGKILL but the process still reports alive; it may be exiting." : "Terminated.";
     }
-    const reaped = reapSessionProcesses(projectPath, hints);
+    const { reaped } = await reapSessionProcesses(projectPath, hints);
     const { pids: survivors, verified } = sessionProcessPids(projectPath, hints);
     const dead = "dead" === pidState(pid);
     const stopped = dead && verified && 0 === survivors.length;
@@ -7157,7 +7290,7 @@ async function dev_handler(args) {
         return spawnFailedEnvelope(dev_schema.name, spawned);
     }
     const pid = child.pid;
-    registerSession({
+    let markerWarning = registerSession({
         pid,
         browser,
         port: args.port,
@@ -7351,7 +7484,7 @@ async function dev_handler(args) {
         unlocked: allowControl ? args.allowEval ? `${controlVerbs}, eval` : controlVerbs : "none (read-only: logs, inspect, wait, doctor)"
     };
     const boundPort = contractBoundPort(args.projectPath, browser, spawnedAt);
-    if (null !== boundPort && boundPort !== args.port) registerSession({
+    if (null !== boundPort && boundPort !== args.port) markerWarning = registerSession({
         pid,
         browser,
         port: boundPort,
@@ -7395,7 +7528,8 @@ async function dev_handler(args) {
         warnings: [
             portNote,
             profileReused && !args.noBrowser ? REUSED_PROFILE_NOTE : null,
-            ...boot.warnings
+            ...boot.warnings,
+            markerWarning
         ],
         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 ? controlBound ? `Control channel is ON (port ${control.port} per ready.json): extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : control.unavailableReason ? `Control was requested, but the engine reports no control port (${control.unavailableReason}), so extension_${controlVerbs.split(", ").join("/extension_")} will be refused until the session is relaunched.` : `Control was requested; ready.json has not stamped the control port yet, so extension_wait is what confirms extension_${controlVerbs.split(", ").join("/extension_")} will work.` : "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."
     });
@@ -7420,12 +7554,12 @@ const start_schema = {
             },
             port: {
                 type: "number",
-                description: "Server port (0 for auto-assign)"
+                description: "Passed to the engine as --port (0 for auto-assign). A production start serves nothing over it today; it matters only to a toolchain that reads it."
             },
             noBrowser: {
                 type: "boolean",
                 default: false,
-                description: "Serve without launching a browser"
+                description: "Build (or, with build:false, check the dist) without launching a browser. A production start serves nothing, so with no browser the engine process ends once the build does; read the result with extension_build rather than a session."
             },
             outputPath: {
                 type: "string",
@@ -7457,6 +7591,26 @@ async function start_handler(args) {
     }
     const building = false !== args.build && !outputPath;
     const command = building ? "start" : "preview";
+    if ("safari" === browser || "webkit-based" === browser) return envelope_envelope({
+        ok: false,
+        command: start_schema.name,
+        status: "unsupported-browser",
+        error: {
+            code: "E_UNSUPPORTED_BROWSER",
+            message: `The engine's ${command} verb does not run Safari; extension_dev builds, packages and opens the Safari app.`
+        },
+        hint: "Use extension_dev with browser: \"safari\", or extension_build with browser: \"safari\" for the packaged app."
+    });
+    if (!building && (args.host || args.publicHost)) return envelope_envelope({
+        ok: false,
+        command: start_schema.name,
+        status: "bad-request",
+        error: {
+            code: "E_BAD_REQUEST",
+            message: "host and publicHost are not options of the engine's preview verb, which build: false and outputPath run; they apply only when start builds."
+        },
+        hint: "Drop host and publicHost, or let extension_start build (build: true, no outputPath)."
+    });
     const cliArgs = [
         command,
         args.projectPath,
@@ -7477,7 +7631,7 @@ async function start_handler(args) {
     const { child, logPath } = spawned;
     if (void 0 === child.pid) return spawnFailedEnvelope(start_schema.name, spawned);
     const pid = child.pid;
-    registerSession({
+    const markerWarning = registerSession({
         pid,
         browser,
         projectPath: args.projectPath,
@@ -7607,16 +7761,19 @@ async function start_handler(args) {
     return envelope_envelope({
         ok: true,
         command: start_schema.name,
-        status: building ? "started" : "launched",
+        status: "started",
         value: {
             pid,
             browser,
             projectPath: args.projectPath,
-            logPath
+            logPath,
+            verb: command,
+            observed: "the engine process was alive 5 s after it was spawned"
         },
-        hint: building ? "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." : "Call extension_stop when you are done to close the preview browser.",
+        hint: building ? "The engine process was alive 5 s after spawn, which is all this answer knows; extension_wait reads whether the build landed. When you are done, call extension_stop to shut the session down." : "The engine's preview process was alive 5 s after spawn, which is all this answer knows: whether a browser shows the extension is not read here. Call extension_stop when you are done.",
         warnings: [
             ...boot.warnings,
+            markerWarning,
             stale.removed && "Removed a Live Preview carrier left behind by an earlier dev session, so it was not loaded beside your extension here.",
             !stale.removed && stale.note && /Could not remove/i.test(stale.note) && `${stale.note} A Live Preview carrier is still in ./extensions and the engine loads that folder, so this run has the debug companion beside your extension.`
         ]
@@ -7719,11 +7876,21 @@ async function runActVerb(args, projectPath, timeoutMs, tool) {
         "json",
         ...args.slice(separatorAt)
     ];
-    const { code, stdout, stderr } = await runExtensionCli(cliArgs, {
+    const { code, stdout, stderr, timedOut, signal } = await runExtensionCli(cliArgs, {
         cwd: projectPath,
         timeoutMs
     });
     const out = stdout.trim();
+    if (timedOut) return envelope_envelope({
+        ok: false,
+        command,
+        status: "cli-timeout",
+        error: {
+            code: "E_CLI",
+            name: "CliTimeout",
+            message: `This server stopped the extension CLI after ${timeoutMs ?? 30000} ms (${signal ?? "a signal"}) before it answered. The ${args[0]} verb may already have acted; read the state it changes before repeating it.`
+        }
+    });
     if (out) try {
         const frame = translateFrame(JSON.parse(out), projectPath, browserFlag(args));
         if (isEnvelope(frame)) {
@@ -7744,6 +7911,16 @@ async function runActVerb(args, projectPath, timeoutMs, tool) {
         },
         hint: "extension_doctor reports the project's engine version next to the one this server pins."
     });
+    if (0 === code && out) return envelope_envelope({
+        ok: false,
+        command,
+        status: "cli-unreadable",
+        error: {
+            code: "E_CLI",
+            name: "CliUnreadable",
+            message: `The extension CLI exited 0 but its answer could not be read as JSON (${out.slice(0, 200)}). The ${args[0]} verb may have acted; read the state it changes before repeating it.`
+        }
+    });
     const message = stderr.trim() || `extension exited with code ${code}`;
     return envelope_envelope({
         ok: false,
@@ -9003,6 +9180,10 @@ const WORKER_TARGET_TYPES = new Set([
     "background_page",
     "worker"
 ]);
+const BACKGROUND_TARGET_TYPES = new Set([
+    "service_worker",
+    "background_page"
+]);
 async function readExtensionWorkerTargets(port, extensionId) {
     try {
         const origin = `chrome-extension://${extensionId}/`;
@@ -9079,6 +9260,11 @@ async function findExtensionPageTargets(port, wantedUrl) {
     const read = await readExtensionPageTargets(port, wantedUrl);
     return "targets" in read ? read.targets : [];
 }
+function remoteValueNote(result) {
+    if (!result) return;
+    if ("undefined" === result.type) return "the expression returned undefined, which is answered as null";
+    if ("string" == typeof result.unserializableValue) return `the expression returned ${result.unserializableValue}${"bigint" === result.type ? " (a BigInt)" : ""}, which JSON cannot carry, so value holds it as the string "${result.unserializableValue}"`;
+}
 function readRemoteValue(result) {
     if (!result) return null;
     if ("value" in result) return result.value;
@@ -9122,9 +9308,13 @@ async function evaluateOnExtensionPage(port, targetId, expression, timeoutMs) {
             thrown: true,
             message: describeException(response.exceptionDetails)
         };
+        const note = remoteValueNote(response?.result);
         return {
             ok: true,
-            value: readRemoteValue(response?.result)
+            value: readRemoteValue(response?.result),
+            ...note ? {
+                note
+            } : {}
         };
     } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -9361,11 +9551,18 @@ async function openDevToolsPanel(port, options) {
                 reloadedInspected = false;
             }
         }
+        let lastEvaluateError = null;
         const evaluate = async (expression)=>await cdp.sendCommand("Runtime.evaluate", {
                 expression,
                 returnByValue: true,
                 awaitPromise: true
-            }, sessionId).catch(()=>null);
+            }, sessionId).catch((err)=>{
+                lastEvaluateError = err instanceof Error ? err.message : String(err);
+                return null;
+            });
+        let registryAnswered = false;
+        let registryError = null;
+        let devtoolsPageLoaded = false;
         const wantedId = "string" == typeof options.panelTitle && options.panelTitle ? `${panelIdPrefix(options.extensionId)}${options.panelTitle}` : null;
         const prefix = panelIdPrefix(options.extensionId);
         let panels = [];
@@ -9375,7 +9572,11 @@ async function openDevToolsPanel(port, options) {
         while(!panelId && Date.now() < deadline){
             const response = await evaluate(PANEL_IDS_EXPRESSION);
             const ids = response?.result?.value;
+            if (response?.exceptionDetails) registryError = response.exceptionDetails.exception?.description ?? response.exceptionDetails.text ?? "the registry read threw";
+            else if (!response) registryError = lastEvaluateError ?? "the registry read did not answer";
+            if (!devtoolsPageLoaded) devtoolsPageLoaded = (await listTargets().catch(()=>[])).some((t)=>"iframe" === t.type && String(t.url ?? "").startsWith(options.devtoolsPageUrl));
             if (Array.isArray(ids)) {
+                registryAnswered = true;
                 panels = ids.map(String);
                 panelId = panels.find((id)=>wantedId ? id === wantedId : id.startsWith(prefix)) ?? null;
             }
@@ -9398,7 +9599,11 @@ async function openDevToolsPanel(port, options) {
             stage: "panel",
             devtoolsTargetId,
             panels,
-            reason: wantedId ? `no panel with id ${wantedId} registered within ${budgetMs}ms` : `no panel from ${prefix} registered within ${budgetMs}ms`
+            devtoolsPageLoaded,
+            ...!registryAnswered && registryError ? {
+                registryUnreadable: registryError
+            } : {},
+            reason: registryAnswered ? devtoolsPageLoaded ? wantedId ? `no panel with id ${wantedId} registered within ${budgetMs}ms` : `no panel from ${prefix} registered within ${budgetMs}ms` : `the devtools page ${options.devtoolsPageUrl} never appeared as a frame within ${budgetMs}ms, so nothing could register a panel` : `the DevTools panel registry could not be read (${registryError ?? "no answer"}), so whether a panel registered is unknown`
         };
         reached = "panel";
         const framesBefore = new Set((await listTargets().catch(()=>[])).filter((t)=>"iframe" === t.type && String(t.url ?? "").startsWith(`${prefix}/`)).map((t)=>t.id));
@@ -9412,15 +9617,31 @@ async function openDevToolsPanel(port, options) {
         };
         reached = "show";
         let panelTarget = null;
+        let panelTargetInferred = false;
+        let panelFrameCandidates = 0;
         const showDeadline = Date.now() + 3000;
-        while(!panelTarget && Date.now() < showDeadline){
+        for(;;){
             const frames = (await listTargets().catch(()=>[])).filter((t)=>"iframe" === t.type && String(t.url ?? "").startsWith(`${prefix}/`) && !String(t.url ?? "").startsWith(options.devtoolsPageUrl));
-            const fresh = frames.find((t)=>!framesBefore.has(t.id)) ?? frames[0];
-            if (fresh) panelTarget = {
-                targetId: fresh.id,
-                url: String(fresh.url)
-            };
-            else await sleep(200);
+            panelFrameCandidates = frames.length;
+            const fresh = frames.find((t)=>!framesBefore.has(t.id));
+            if (fresh) {
+                panelTarget = {
+                    targetId: fresh.id,
+                    url: String(fresh.url)
+                };
+                break;
+            }
+            if (Date.now() >= showDeadline) {
+                if (1 === frames.length) {
+                    panelTarget = {
+                        targetId: frames[0].id,
+                        url: String(frames[0].url)
+                    };
+                    panelTargetInferred = true;
+                }
+                break;
+            }
+            await sleep(200);
         }
         return {
             opened: true,
@@ -9428,6 +9649,10 @@ async function openDevToolsPanel(port, options) {
             panelId,
             panelTitle: panelTitleFromId(panelId, options.extensionId),
             panelTarget,
+            ...panelTargetInferred ? {
+                panelTargetInferred
+            } : {},
+            panelFrameCandidates,
             panels,
             reloadedInspected
         };
@@ -10354,7 +10579,7 @@ async function openDevToolsSurface(args, browser) {
             error: {
                 code: "E_SURFACE_DID_NOT_OPEN",
                 name: "PanelDidNotRegister",
-                message: "panel" === outcome.stage ? `DevTools opened on ${inspected.url} and ${doc} loaded in it, but ${outcome.reason}.${registered.length ? ` Panels this extension did register: ${registered.map((id)=>id.slice(`chrome-extension://${extensionId}`.length)).join(", ")}.` : ""}` : `DevTools opened on ${inspected.url} and the panel registered, but ${outcome.reason}.`
+                message: "panel" === outcome.stage ? `DevTools opened on ${inspected.url}${false === outcome.devtoolsPageLoaded ? "" : ` and ${doc} loaded in it`}, but ${outcome.reason}.${registered.length ? ` Panels this extension did register: ${registered.map((id)=>id.slice(`chrome-extension://${extensionId}`.length)).join(", ")}.` : ""}` : `DevTools opened on ${inspected.url} and the panel registered, but ${outcome.reason}.`
             },
             value: {
                 inspected: {
@@ -10364,7 +10589,7 @@ async function openDevToolsSurface(args, browser) {
                 devtoolsTargetId: outcome.devtoolsTargetId ?? null,
                 panels: outcome.panels ?? []
             },
-            hint: args.panel && registered.length ? `No panel is titled "${args.panel}"; pass one of the registered titles as \`panel\`, or omit it for the first.` : `The devtools page registers panels with chrome.devtools.panels.create; extension_logs (context: ['devtools']) shows what ${doc} wrote or threw. An extension that creates its panel only when the page reports to it (Preact Devtools does, through its content script) needs the page loaded with DevTools already open: retry with reload: true, and waitMs for a longer wait. DevTools stays open on the tab.`
+            hint: "panel" === outcome.stage && outcome.registryUnreadable ? "This browser build's DevTools frontend did not answer the panel-registry read this server uses, so the panel may well exist; open DevTools by hand in a headed session to see it, and extension_logs (context: ['devtools']) reads the devtools page either way." : args.panel && registered.length ? `No panel is titled "${args.panel}"; pass one of the registered titles as \`panel\`, or omit it for the first.` : `The devtools page registers panels with chrome.devtools.panels.create; extension_logs (context: ['devtools']) shows what ${doc} wrote or threw. An extension that creates its panel only when the page reports to it (Preact Devtools does, through its content script) needs the page loaded with DevTools already open: retry with reload: true, and waitMs for a longer wait. DevTools stays open on the tab.`
         });
     }
     const panelUrl = outcome.panelTarget?.url ?? null;
@@ -10394,8 +10619,10 @@ async function openDevToolsSurface(args, browser) {
             ...true !== args.reload || outcome.reloadedInspected ? [] : [
                 "reload: true was asked for, but the inspected tab could not be reloaded (the attach or Page.reload failed), so the panel was read without a reload."
             ],
-            ...outcome.panelTarget ? [] : [
-                "The panel is shown but its document target had not appeared within 3s; call extension_open surface: \"devtools\" again once it loads to get its url."
+            ...outcome.panelTarget ? outcome.panelTargetInferred ? [
+                "No new panel frame appeared after showPanel; the one frame of this extension already inside DevTools was taken as the panel, which is an inference, not a match."
+            ] : [] : [
+                (outcome.panelFrameCandidates ?? 0) > 1 ? `The panel is shown but ${outcome.panelFrameCandidates} frames of this extension sit inside DevTools and none appeared after showPanel, so which one is the panel is unknown; its url is not given.` : "The panel is shown but its document target had not appeared within 3s; call extension_open surface: \"devtools\" again once it loads to get its url."
             ]
         ],
         hint: panelUrl ? `DevTools is open on ${inspected.url} with the "${outcome.panelTitle}" panel shown. Read the panel with extension_eval context: "page", url: "${panelUrl}" (over CDP, with chrome.devtools available); context: "devtools" reads the devtools page itself (${doc}), the hidden document that registered the panel. The panel is an iframe inside DevTools, not a tab, so extension_dom_snapshot and extension_inspect do not reach it.` : `DevTools is open on ${inspected.url} with the "${outcome.panelTitle}" panel shown. context: "devtools" on extension_eval reads the devtools page itself (${doc}).`
@@ -10734,15 +10961,29 @@ async function listArtifacts(options = {}) {
             message: `Listing shares failed (${res.status}): ${data?.message || "unknown error"}`
         }
     };
-    const artifacts = Array.isArray(data.artifacts) ? data.artifacts.map((artifact)=>artifact && "string" == typeof artifact.revokeUrl ? {
+    if (!Array.isArray(data.artifacts)) return {
+        ok: false,
+        error: {
+            name: "SharesListError",
+            status: res.status,
+            message: `Listing shares answered ${res.status} without an artifacts list, so which shares exist is unknown.`
+        }
+    };
+    const rows = data.artifacts;
+    const valid = rows.filter((artifact)=>artifact && "string" == typeof artifact.artifactId);
+    const malformedRows = rows.length - valid.length;
+    const artifacts = valid.map((artifact)=>"string" == typeof artifact.revokeUrl ? {
             ...artifact,
             revokeUrl: wwwRevokeUrl(artifact.revokeUrl)
-        } : artifact) : [];
+        } : artifact);
     const num = (value, fallback)=>"number" == typeof value && Number.isFinite(value) ? value : fallback;
     return {
         ok: true,
         data: {
             artifacts,
+            ...malformedRows ? {
+                malformedRows
+            } : {},
             count: num(data.count, artifacts.length),
             matched: num(data.matched, artifacts.length),
             limit: num(data.limit, artifacts.length),
@@ -12312,7 +12553,8 @@ async function listShares(args) {
             "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
+            truncatedNote,
+            listing.data.malformedRows ? `${listing.data.malformedRows} row(s) of the platform's listing carried no artifact id and were left out, so the list may be short by that many.` : null
         ]
     });
 }
@@ -12382,7 +12624,7 @@ async function revokeShare(args) {
     });
     const local = args.projectPath ? readSharedPreviews(args.projectPath) : void 0;
     const entry = local ? localIndex(local.entries).get(ref) : void 0;
-    const recordNote = local ? entry ? `${local.path} still lists this share as its own append-only history and was not rewritten, so the entry stays with its original sharedAt. The platform is the truth for whether a link resolves.` : `${local.path} has no entry for this share, so it was made from another machine or another checkout.` : void 0;
+    const recordNote = local ? local.unreadable ? `${local.path} exists but could not be parsed, so whether this project recorded the share is unknown.` : entry ? `${local.path} still lists this share as its own append-only history and was not rewritten, so the entry stays with its original sharedAt. The platform is the truth for whether a link resolves.` : `${local.path} has no entry for this share, so it was made from another machine or another checkout.` : void 0;
     if (!result.ok) {
         if (result.held) return platformHoldEnvelope({
             command: "extension_shares",
@@ -12727,7 +12969,13 @@ function verdictSentence(verdict) {
     return `${parts.join(", ")}.`;
 }
 function logs_filter_readLogEvents(projectPath, browser, query) {
-    return readLogEvents(engineProjectRoot(projectPath), browser, query);
+    return readLogEvents(engineProjectRoot(projectPath), browser, query).filter((event)=>"string" != typeof event.type);
+}
+function readLogDropped(projectPath, browser) {
+    return readLogEvents(engineProjectRoot(projectPath), browser, {}).reduce((sum, event)=>{
+        const record = event;
+        return "gap" === record.type && "number" == typeof record.dropped ? sum + record.dropped : sum;
+    }, 0);
 }
 function makeFilter(args) {
     const level = String(args.level || "all").toLowerCase();
@@ -13046,6 +13294,11 @@ async function readFromStream(args, browser, limit) {
     let connectedAt = Date.now();
     let replayed = 0;
     let liveCount = 0;
+    const startedAt = Date.now();
+    let opened = false;
+    let readySeen = false;
+    let bufferedFrom;
+    let evicted;
     return await new Promise((resolve)=>{
         let settled = false;
         const url = `ws://127.0.0.1:${ready.controlPort}${CONTROL_WS_PATH}`;
@@ -13072,14 +13325,27 @@ async function readFromStream(args, browser, limit) {
             try {
                 socket.close();
             } catch  {}
-            resolve(summarize(events, "stream", browser, runId, limit, dropped, args.projectPath, void 0, streamNote, {
+            resolve(summarize(events, "stream", browser, runId, limit, dropped, args.projectPath, void 0, [
+                streamNote,
+                opened && !readySeen ? "The control channel opened but the broker never sent its ready frame, so whether the replay covered the run is unknown." : null,
+                "number" == typeof evicted && evicted > 0 ? `The broker's ring had already evicted ${evicted} older event(s) before this read${"number" == typeof bufferedFrom ? ` (it holds from seq ${bufferedFrom})` : ""}; read the file (call without follow) for those.` : null
+            ].filter((note)=>Boolean(note)).join(" ") || void 0, {
                 replayed,
                 live: liveCount,
-                followMs
+                followMs,
+                opened,
+                readySeen,
+                ..."number" == typeof bufferedFrom ? {
+                    bufferedFrom
+                } : {},
+                ..."number" == typeof evicted ? {
+                    evicted
+                } : {}
             }));
         };
         const timer = setTimeout(finish, followMs);
         socket.on("open", ()=>{
+            opened = true;
             connectedAt = Date.now();
             try {
                 socket.send(JSON.stringify({
@@ -13097,8 +13363,12 @@ async function readFromStream(args, browser, limit) {
             } catch  {
                 return;
             }
-            if ("ready" === frame.type && frame.runId) runId = String(frame.runId);
-            else if ("log" === frame.type && frame.event) {
+            if ("ready" === frame.type) {
+                readySeen = true;
+                if (frame.runId) runId = String(frame.runId);
+                if ("number" == typeof frame.bufferedFrom) bufferedFrom = frame.bufferedFrom;
+                if ("number" == typeof frame.evicted) evicted = frame.evicted;
+            } else if ("log" === frame.type && frame.event) {
                 if (matches(frame.event)) {
                     events.push(frame.event);
                     const at = Number(frame.event.timestamp);
@@ -13133,7 +13403,12 @@ async function readFromStream(args, browser, limit) {
         socket.on("close", (code, reason)=>{
             if (settled) return;
             const refusal = controlRefusal(code, reason?.toString() ?? "", url, CONTROL_ENVELOPE_VERSION);
-            if (!refusal) return void finish();
+            if (!refusal) {
+                const elapsed = Date.now() - startedAt;
+                if (elapsed < followMs - 250) streamNote = `The control channel closed after ${Math.round(elapsed / 1000)} s of the ${Math.round(followMs / 1000)} s window (close code ${code}${reason?.length ? `, "${reason.toString()}"` : ""}), so this is a partial read; the dev session may have stopped or restarted. Re-check with extension_wait.`;
+                finish();
+                return;
+            }
             if (events.length > 0 || dropped > 0) {
                 streamNote = refusal.message;
                 finish();
@@ -13310,6 +13585,19 @@ function parseClauses(raw) {
         const context = void 0 === clause.context ? void 0 : Array.isArray(clause.context) ? clause.context.map(String) : [
             String(clause.context)
         ];
+        if (void 0 !== context) try {
+            makeFilter({
+                context
+            })({
+                context: "background",
+                level: "info",
+                seq: 0,
+                ts: 0
+            });
+        } catch (error) {
+            issues.push(`${at}.context: ${error instanceof Error ? error.message : String(error)}`);
+            return;
+        }
         const since = void 0 === clause.since ? void 0 : Number(clause.since);
         if (void 0 !== since && !Number.isFinite(since)) return void issues.push(`${at}.since must be a number, the seq cursor to read from`);
         const ignore = void 0 === clause.ignore ? void 0 : Array.isArray(clause.ignore) ? clause.ignore.map(String) : [
@@ -13916,6 +14204,12 @@ function assertConsoleErrorsEmpty(clause, stage) {
         errors: kept.slice(0, 20),
         runId
     });
+    const droppedLines = readLogDropped(stage.projectPath, stage.browser);
+    if (droppedLines > 0) return inconclusiveCheck(id, subject, `No error-level log event${scope} among the ${all.length} event(s) that reached the file in run ${runId || "(unnamed)"}, but the writer dropped ${droppedLines} line(s) when it fell behind, and any of them may have been an error.`, "Read extension_logs with follow: true while driving the extension, which streams lines the file writer dropped, then assert again.", {
+        events: all.length,
+        dropped: droppedLines,
+        runId
+    });
     return passCheck(id, subject, `No error-level log event${scope} among ${all.length} event(s) in run ${runId || "(unnamed)"}${ignored.length && errors.length ? `, and ${errors.length} matched an ignore entry and were not counted` : ""}${foreignErrors ? `; ${foreignErrors} browser-relayed error(s) from other origins were not counted` : ""}.`, {
         events: all.length,
         ignored: errors.length - kept.length,
@@ -16367,8 +16661,17 @@ function closedShadowWalkerCode(cap) {
     })();
   `;
 }
+function matchPatternRegexSource(pattern) {
+    if ("<all_urls>" === pattern) return "^(https?|file|ftp):";
+    const m = /^(\*|https?|file|ftp|wss?):\/\/([^/]*)(\/.*)?$/.exec(pattern);
+    if (!m) return "^" + pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$";
+    const scheme = "*" === m[1] ? "https?" : m[1];
+    const host = "*" === m[2] ? "[^/]*" : m[2].startsWith("*.") ? "([^/]*\\.)?" + m[2].slice(2).replace(/[.]/g, "\\.") : m[2].replace(/[.]/g, "\\.");
+    const pathPart = (m[3] ?? "/").replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return "^" + scheme + "://" + host + pathPart + "$";
+}
 function executeScriptExpression(urlFilter, code, tabId) {
-    const pick = "number" == typeof tabId ? `tabs.find(function (t) { return t.id === ${tabId}; })` : urlFilter ? `tabs.find(function (t) { return String(t.url || "").toLowerCase().indexOf(${JSON.stringify(urlFilter.toLowerCase())}) !== -1; })` : "(tabs.find(function (t) { return t.active; }) || tabs[0])";
+    const pick = "number" == typeof tabId ? `tabs.find(function (t) { return t.id === ${tabId}; })` : urlFilter ? /\*|<all_urls>/.test(urlFilter) ? `tabs.find(function (t) { return new RegExp(${JSON.stringify(matchPatternRegexSource(urlFilter))}).test(String(t.url || "")); })` : `tabs.find(function (t) { return String(t.url || "").toLowerCase().indexOf(${JSON.stringify(urlFilter.toLowerCase())}) !== -1; })` : "(tabs.find(function (t) { return t.active; }) || tabs[0])";
     return `browser.tabs.query({}).then(function (tabs) {
     var tab = ${pick};
     if (!tab) return { error: "no matching tab" };
@@ -17043,6 +17346,7 @@ async function listGeckoExtensions(projectPath, browser) {
             const temporary = extensions.filter((e)=>e.temporarilyInstalled);
             if (1 === temporary.length) {
                 temporary[0].ownExtension = true;
+                temporary[0].ownExtensionInferred = true;
                 if (void 0 === temporary[0].name && own?.name !== void 0) {
                     temporary[0].name = own.name;
                     if (void 0 !== own.version) temporary[0].version = own.version;
@@ -17064,9 +17368,13 @@ async function listGeckoExtensions(projectPath, browser) {
                 browser,
                 count: extensions.length,
                 ownExtensionId: ownEntry?.id ?? null,
+                ...ownEntry?.ownExtensionInferred ? {
+                    ownExtensionInferred: true
+                } : {},
                 extensions
             },
             warnings: [
+                ownEntry?.ownExtensionInferred ? `No installed add-on carries this session's name${own?.name ? ` ("${own.name}")` : ""}, so ${ownEntry.id} is marked ownExtension only because it is the one temporary install. That is an inference: if this project's add-on failed to install, it may be another temporary add-on such as the engine's companion. extension_logs shows whether the install succeeded.` : null,
                 "Lists INSTALLED add-ons via the RDP root actor (listAddons), regardless of whether a context is currently live, so entries carry no contexts. temporarilyInstalled marks temporary loads; ownExtension marks the extension this dev session serves, matched from the session's ready contract. Add-ons are never attached to or evaluated in."
             ]
         });
@@ -17147,7 +17455,7 @@ function readRelayFrame(value) {
 }
 const eval_schema = {
     name: "extension_eval",
-    description: "Evaluate an expression in a running extension context. Start the session with allowEval:true (extension_dev), which writes a 0600 session token; without that token every route of this tool, the debug port included, answers eval-disabled. Context defaults to 'background', except on a Chromium MV3 session (the default template) where it defaults to 'page', the active tab, because the MV3 service worker CSP blocks eval; pass context:'background' to target the worker anyway and get that explanation back. For content and page, pass `url` to pick the tab, or omit both `url` and `tab` for the active tab; a numeric `tab` only disambiguates. Extension surfaces (popup, options, sidebar, devtools) and override pages (newtab, history, bookmarks) need no tab id but must already be open: open one with extension_open first, because a closed one returns an explicit error. On a Chromium MV3 session those pages, and context:'page' with a chrome-extension:// url, evaluate over CDP, the inspector path the extension page CSP does not govern; elsewhere they evaluate over the in-bundle relay. On Firefox a document whose content security policy forbids eval (the extension's own pages, or a site's) is evaluated over the debugger protocol instead, which takes one expression; a page inside the extension that is no declared surface (pages/*) is reached the same way by context:'page' and its moz-extension:// url once a tab shows it. Call extension_dom_snapshot with listTabs:true to enumerate {tabId, url, title}.",
+    description: "Evaluate an expression in a running extension context. Start the session with allowEval:true (extension_dev), which writes a 0600 session token; without that token every route of this tool, the debug port included, answers eval-disabled. Context defaults to 'background', except on a Chromium MV3 session (the default template) where it defaults to 'page', the active tab; pass context:'background' to evaluate in the service worker, which on Chromium goes over the debug port. Debug-port evaluates run with a user gesture, so gesture-gated APIs (permissions.request, sidePanel.open) can succeed here and still fail when the extension's own code calls them. For content and page, pass `url` to pick the tab, or omit both `url` and `tab` for the active tab; a numeric `tab` only disambiguates. Extension surfaces (popup, options, sidebar, devtools) and override pages (newtab, history, bookmarks) need no tab id but must already be open: open one with extension_open first, because a closed one returns an explicit error. On a Chromium MV3 session those pages, and context:'page' with a chrome-extension:// url, evaluate over CDP, the inspector path the extension page CSP does not govern; elsewhere they evaluate over the in-bundle relay. On Firefox a document whose content security policy forbids eval (the extension's own pages, or a site's) is evaluated over the debugger protocol instead, which takes one expression; a page inside the extension that is no declared surface (pages/*) is reached the same way by context:'page' and its moz-extension:// url once a tab shows it. Call extension_dom_snapshot with listTabs:true to enumerate {tabId, url, title}.",
     inputSchema: {
         type: "object",
         properties: {
@@ -17257,23 +17565,24 @@ async function evaluateOnChromiumExtensionPage(args, browser, context, resolved)
         });
         const workersRead = await readExtensionWorkerTargets(resolved.port, extensionId);
         if ("unreadable" in workersRead) return eval_targetsUnreadable(workersRead.unreadable);
-        let workers = workersRead.targets;
+        let workers = workersRead.targets.filter((t)=>BACKGROUND_TARGET_TYPES.has(t.type));
         const wakeWarnings = [];
         if (0 === workers.length) {
             const wake = await wakeExtensionWorker(resolved.port, extensionId);
-            if (!wake.woken) return envelope_envelope({
+            const woken = wake.woken ? wake.targets.filter((t)=>BACKGROUND_TARGET_TYPES.has(t.type)) : [];
+            if (!wake.woken || !(woken.length > 0)) return envelope_envelope({
                 ok: false,
                 command: eval_schema.name,
                 status: "no-target",
                 error: {
                     code: "E_NO_TARGET",
                     name: "NoTarget",
-                    message: `No running background for chrome-extension://${extensionId}/: Chrome stops an idle MV3 service worker and lists no target for it, and starting it through ServiceWorker.startWorker did not bring one back: ${wake.reason}.`
+                    message: `No running background for chrome-extension://${extensionId}/: Chrome stops an idle MV3 service worker and lists no target for it, and starting it through ServiceWorker.startWorker did not bring one back: ${wake.woken ? "only dedicated workers were listed, which are not the background" : wake.reason}.`
                 },
                 hint: "Check the extension declares a background (extension_manifest_validate), then wake it with an event it listens to (extension_reload, open a surface with extension_open, navigate a matching tab) and retry. extension_logs (context: ['background']) holds what it wrote before it idled."
             });
-            workers = wake.targets;
-            wakeWarnings.push("The background worker was idle (Chrome stops an MV3 service worker after about 30 s without events) and was started through ServiceWorker.startWorker before evaluating; state it held before idling is gone unless it was persisted.");
+            workers = woken;
+            wakeWarnings.push("No running background worker was listed, so it was started through ServiceWorker.startWorker before evaluating. Chrome stops an idle MV3 service worker after about 30 s without events, but a worker that never started looks the same here, so this does not say it idled; any in-memory state from an earlier run of it is gone unless it was persisted.");
         }
         const target = workers[0];
         const outcome = await evaluateOnExtensionPage(resolved.port, target.targetId, args.expression, args.timeout);
@@ -17294,6 +17603,7 @@ async function evaluateOnChromiumExtensionPage(args, browser, context, resolved)
             status: "evaluated",
             value: outcome.value,
             warnings: [
+                outcome.note ?? null,
                 ...wakeWarnings,
                 ...workers.length > 1 ? [
                     `${workers.length} background targets match the extension; evaluated in ${target.type} ${target.targetId}.`
@@ -17376,7 +17686,10 @@ async function evaluateOnChromiumExtensionPage(args, browser, context, resolved)
         command: eval_schema.name,
         status: "evaluated",
         value: outcome.value,
-        warnings,
+        warnings: [
+            ...warnings,
+            outcome.note ?? null
+        ],
         hint: `Evaluated over CDP in ${target.url} (target ${target.targetId}), the inspector path the extension page CSP does not govern. The result is serialized by value, so return plain data rather than DOM nodes; a promise is awaited before returning.`
     });
 }
@@ -17451,9 +17764,12 @@ async function evaluateOnWebTarget(args, matches, url, browser) {
         command: eval_schema.name,
         status: "evaluated",
         value: outcome.value,
-        warnings: live.length > 1 ? [
-            `${live.length} tabs match ${url}; evaluated in ${target.url} (target ${target.targetId}). Narrow the url to pick another.`
-        ] : [],
+        warnings: [
+            ...live.length > 1 ? [
+                `${live.length} tabs match ${url}; evaluated in ${target.url} (target ${target.targetId}). Narrow the url to pick another.`
+            ] : [],
+            outcome.note ?? null
+        ],
         hint: `Evaluated over CDP in ${target.url} (target ${target.targetId}), the page's main world through the inspector, which the site's CSP and Trusted Types do not govern. Pass context: "content" for the extension's isolated world instead.`
     });
 }
@@ -17589,13 +17905,14 @@ async function evaluatePastSurfaceCsp(args, context, run) {
     return direct;
 }
 const sameDocumentUrl = (a, b)=>String(a ?? "").replace(/[?#].*$/, "") === b.replace(/[?#].*$/, "");
-function tabByUrl(tabs, url) {
+function tabByUrl(tabs, url, seen) {
     const exact = tabs.filter((tab)=>sameDocumentUrl(tab.url, url));
     const covered = exact.length ? exact : tabs.filter((tab)=>matchPatternCovers(url, String(tab.url ?? "")));
     const candidates = covered.length ? covered : tabs.filter((tab)=>String(tab.url ?? "").includes(url));
+    if (seen) seen.matched = candidates.length;
     return candidates.find((tab)=>true === tab.selected) ?? candidates[0];
 }
-async function evaluateInGeckoTab(args, browser, select, missing) {
+async function evaluateInGeckoTab(args, browser, select, missing, seen) {
     const resolved = await resolveRdpPort(args.projectPath, browser, {
         waitMs: 3000,
         graceMs: 1000
@@ -17625,7 +17942,11 @@ async function evaluateInGeckoTab(args, browser, select, missing) {
         ok: true,
         command: eval_schema.name,
         status: "ok",
-        value: void 0 === outcome.value ? null : outcome.value
+        value: void 0 === outcome.value ? null : outcome.value,
+        warnings: [
+            `Evaluated in the tab showing ${outcome.tab.url || "an unknown url"}${outcome.tab.title ? ` ("${outcome.tab.title}")` : ""}.`,
+            seen && seen.matched > 1 ? `${seen.matched} open tabs matched the url; the selected one (or the first) was used. Narrow the url to pick another.` : null
+        ]
     });
     if ("TargetNotFound" === outcome.name) return envelope_envelope({
         ok: false,
@@ -17649,16 +17970,18 @@ async function evaluateInGeckoTab(args, browser, select, missing) {
         },
         hint: "The expression returned a promise that is still pending; pass a larger timeout to wait for it."
     });
+    const lost = "EvalLost" === outcome.name;
+    const unsupported = "Unsupported" === outcome.name;
     return envelope_envelope({
         ok: false,
         command: eval_schema.name,
-        status: "eval-failed",
+        status: lost ? "eval-lost" : unsupported ? "eval-unsupported" : "eval-failed",
         error: {
             code: "E_EVAL",
             name: outcome.name,
             message: outcome.message
         },
-        hint: "The expression threw inside the document. It ran over the debugger protocol, which the document's content security policy does not govern, so this is the expression's own error."
+        hint: lost ? "The document navigated or closed before the expression answered, so it may have run in part; read the page's state before repeating it." : unsupported ? "The debugger protocol could not evaluate in that tab, so the expression never ran. extension_dom_snapshot reads the page without eval." : "The expression threw inside the document. It ran over the debugger protocol, which the document's content security policy does not govern, so this is the expression's own error."
     });
 }
 function backgroundRouteRefusedStatements(args, browser, context, raw) {
@@ -17675,7 +17998,10 @@ async function evaluatePagePastSiteCsp(args, browser, context, raw) {
     if (!args.url && null != args.tab) return null;
     if (!isSingleExpression(args.expression)) return notOneExpression();
     const url = args.url;
-    return evaluateInGeckoTab(args, browser, url ? (tabs)=>tabByUrl(tabs, url) : (tabs)=>tabs.find((tab)=>true === tab.selected), url ? `No open tab matches url: ${url}` : "No tab is selected in the dev browser.");
+    const seen = {
+        matched: 0
+    };
+    return evaluateInGeckoTab(args, browser, url ? (tabs)=>tabByUrl(tabs, url, seen) : (tabs)=>tabs.find((tab)=>true === tab.selected), url ? `No open tab matches url: ${url}` : "No tab is selected in the dev browser.", seen);
 }
 async function evaluateThroughExecuteScript(args, browser, context, raw) {
     if ("page" !== context && "content" !== context) return null;
@@ -17835,13 +18161,10 @@ async function eval_handler(args) {
     if (defaulted) try {
         const parsed = JSON.parse(raw);
         if (parsed && "object" == typeof parsed) {
-            patchValue(parsed, {
-                defaultedContext: "page"
-            });
-            addWarning(parsed, 'No context given: defaulted to "page" (the active tab) because this Chromium session\'s MV3 background is a service worker whose CSP blocks eval. Pass context: "background" explicitly to target the worker (works on Firefox/MV2 builds).');
+            addWarning(parsed, 'No context given: defaulted to "page" (the active tab). Pass context: "background" to evaluate in the service worker, which this tool reaches over the debug port.');
             const code = "string" == typeof parsed.error?.code ? parsed.error.code : "";
-            const unreachable = "E_TARGET_NOT_FOUND" === code || /cannot access|chrome-extension:\/\/|chrome:\/\//i.test(JSON.stringify(parsed.error ?? ""));
-            if (false === parsed.ok && unreachable) parsed.hint = "The active tab is a browser or extension page that eval cannot reach. Navigate the dev browser to a regular web page, or pass url (match pattern) or tab to pick one; extension_dom_snapshot with listTabs: true lists open tabs.";
+            const unreachable = "E_TARGET_NOT_FOUND" === code || /cannot access|chrome-extension:\/\/|chrome:\/\/|no active tab|missing host permission/i.test(JSON.stringify(parsed.error ?? ""));
+            if (false === parsed.ok && unreachable) parsed.hint = "The active tab could not be reached: it is a browser or extension page, a site outside the extension's host permissions, or there is no active tab. Navigate the dev browser to a page the extension may script, or pass url (match pattern) or tab to pick one; extension_dom_snapshot with listTabs: true lists open tabs.";
             return actFrameJson(parsed);
         }
     } catch  {}
@@ -18549,7 +18872,8 @@ async function publish_handler(args) {
             ref,
             api: args.api
         });
-        if (buildsRes.ok) {
+        if (buildsRes.ok && buildIndexShapeProblem(buildsRes.json)) buildNote = `The project's build index at ${buildsUrl} answered but ${buildIndexShapeProblem(buildsRes.json)}, so buildSha, version and builtAt were not filled in from it.`;
+        else if (buildsRes.ok) {
             const items = parseBuildIndex(buildsRes.json);
             if (args.buildSha) {
                 const pin = String(args.buildSha).toLowerCase();
@@ -18571,13 +18895,18 @@ async function publish_handler(args) {
                 }
             } else {
                 const newestSuccess = items.filter(isSuccessfulBuild).sort((a, b)=>String(b.timestamp ?? "").localeCompare(String(a.timestamp ?? "")))[0];
-                if (newestSuccess) {
-                    if (null == data.buildSha) data.buildSha = newestSuccess.sha;
-                    if (null == data.builtAt && newestSuccess.timestamp) data.builtAt = newestSuccess.timestamp;
-                    if (null == data.version && newestSuccess.version) data.version = newestSuccess.version;
-                    if (null == data.channel && newestSuccess.channel) data.channel = newestSuccess.channel;
+                const platformSha = "string" == typeof data.buildSha && data.buildSha ? String(data.buildSha).toLowerCase() : null;
+                const served = platformSha ? items.find((item)=>item.sha.toLowerCase().startsWith(platformSha) || platformSha.startsWith(item.sha.toLowerCase())) : 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;
+                    buildNote = platformSha ? `builtAt/version are read from the index row of build ${served.sha}, the build the platform says the link serves.` : "The platform named no build for this link; buildSha/builtAt/version describe the newest successful build in the project's registry index, which is what an unpinned link is expected to serve. Pin buildSha to serve a specific build.";
+                } else if (platformSha) {
                     data.registryUrl = buildsUrl;
-                    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.";
+                    buildNote = `The platform says the link serves build ${data.buildSha}, which the project's registry index does not list, so builtAt and version were not filled in from another build.`;
                 }
             }
         }
@@ -18845,7 +19174,7 @@ async function release_promote_handler(args) {
                     api: args.api
                 });
                 if (channelsRes.ok) {
-                    const rows = parseChannels(channelsRes.json).filter((c)=>c.sha);
+                    const rows = channelsShapeProblem(channelsRes.json) ? [] : parseChannels(channelsRes.json).filter((c)=>c.sha);
                     enrich.validChannelShas = Object.fromEntries(rows.map((c)=>[
                             c.channel,
                             c.sha
@@ -19192,7 +19521,7 @@ async function readReleases(args) {
     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([
+    const [channelsRaw, metaRes, buildsRaw] = await Promise.all([
         fetchRegistryJson(channelsUrl, fetch, {
             ref,
             api: args.api
@@ -19206,6 +19535,8 @@ async function readReleases(args) {
             api: args.api
         })
     ]);
+    const channelsRes = requireShape(channelsRaw, channelsShapeProblem);
+    const buildsRes = requireShape(buildsRaw, buildIndexShapeProblem);
     const buildsPageUrl = consoleProjectUrl(ref, "builds", args.api);
     const heldRead = [
         channelsRes,
@@ -19730,7 +20061,7 @@ async function submit_handler(args) {
                 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);
+            if (channelsRes.ok && !channelsShapeProblem(channelsRes.json)) channelRows = parseChannels(channelsRes.json);
         } else healthUnreadable = "no stored workspace/project to look up (run extension_auth)";
         const preflight = browsers.map((browser)=>{
             if (!health) return {
@@ -20360,6 +20691,36 @@ async function wait_handler(args) {
                 continue;
             }
             lastContractStatus = contract.status;
+            if ("build" === contract.command) return envelope_envelope({
+                ok: false,
+                command: wait_schema.name,
+                status: "no-session",
+                error: {
+                    code: "E_NO_SESSION",
+                    message: `${readyPath} is the contract a finished extension_build left (command: build), not a running session, so there is nothing to wait for.`
+                },
+                value: {
+                    readyPath,
+                    budgetMs,
+                    elapsedMs: Date.now() - start
+                },
+                hint: "Start a session with extension_dev (or extension_start), then call extension_wait."
+            });
+            if ("stopped" === contract.status) return envelope_envelope({
+                ok: false,
+                command: wait_schema.name,
+                status: "stopped",
+                error: {
+                    code: "E_SESSION_EXITED",
+                    message: `${readyPath} records status: stopped; that session was stopped and nothing will become ready.`
+                },
+                value: {
+                    readyPath,
+                    budgetMs,
+                    elapsedMs: Date.now() - start
+                },
+                hint: "Start a session with extension_dev, then call extension_wait."
+            });
             if ("ready" === contract.status) {
                 if ("number" == typeof contract.pid && !wait_isAlive(contract.pid)) return envelope_envelope({
                     ok: false,
@@ -20431,7 +20792,7 @@ async function wait_handler(args) {
                 if (!attached && ("start" === contract.command || "preview" === contract.command)) return envelope_envelope({
                     ok: true,
                     command: wait_schema.name,
-                    status: "launched",
+                    status: "build-ready",
                     value: {
                         compiled: true,
                         browserAttached: false,
@@ -20537,6 +20898,26 @@ async function wait_handler(args) {
         ],
         hint: "This is usually transient: call extension_wait again. If it persists, stop and restart the session with extension_dev (a restart reliably reattaches); extension_doctor reports the executor leg."
     });
+    if (null === lastContractStatus && !contractUnreadable && !staleContractNote && !findSessionInfo(args.projectPath, browser)) return envelope_envelope({
+        ok: false,
+        command: wait_schema.name,
+        status: "no-session",
+        error: {
+            code: "E_NO_SESSION",
+            message: `No ${browser} session is known for ${args.projectPath}: this server registered none and no contract appeared at ${readyPath} in ${budgetMs} ms.`
+        },
+        value: {
+            compiled: false,
+            browserAttached: false,
+            readyPath,
+            budgetMs,
+            elapsedMs: Date.now() - start
+        },
+        warnings: [
+            clampNote
+        ],
+        hint: "Check projectPath and browser, or start a session with extension_dev, then call extension_wait."
+    });
     return envelope_envelope({
         ok: false,
         command: wait_schema.name,
@@ -23011,7 +23392,9 @@ async function runCli(cmd, args) {
             } catch  {
                 parsed = null;
             }
-            return parsed?.ok === false ? 1 : 0;
+            if (parsed?.ok === true) return 0;
+            if (null === parsed || "object" != typeof parsed) log("The promote answer above could not be read as an envelope, so whether the channel moved is unknown; check extension_release_list before retrying.");
+            return 1;
         }
         log("Usage: extension-mcp release promote --build <sha> --channel <channel>");
         return 1;