@extension.dev/mcp 10.1.0 → 10.2.0

package/dist/module.js

@@ -8,6 +8,7 @@ import { extensionCreate } from "extension-create";
 import node_os from "node:os";
 import cross_spawn from "cross-spawn";
 import node_crypto, { createHash } from "node:crypto";
+import { CLOSE_BAD_HELLO, CLOSE_BAD_INSTANCE, CLOSE_CONTROL_UNAVAILABLE, CLOSE_SLOW_CONSUMER, CONTROL_ENVELOPE_VERSION, CONTROL_WS_PATH, buildSummaryPath, logsPath, matchesLogQuery, readLogEvents, readReadyContract, readyContractPath as bridge_readyContractPath, sessionArtifactsRootDir } from "extension-develop/bridge";
 import { fileURLToPath } from "node:url";
 import { execFile, execFileSync } from "node:child_process";
 import ws_0 from "ws";
@@ -431,6 +432,7 @@ __webpack_require__.d(browsers_namespaceObject, {
 var build_namespaceObject = {};
 __webpack_require__.r(build_namespaceObject);
 __webpack_require__.d(build_namespaceObject, {
+    BUNDLE_ID_PATTERN: ()=>BUNDLE_ID_PATTERN,
     handler: ()=>build_handler,
     schema: ()=>build_schema
 });
@@ -481,6 +483,7 @@ __webpack_require__.d(list_extensions_namespaceObject, {
 var logs_namespaceObject = {};
 __webpack_require__.r(logs_namespaceObject);
 __webpack_require__.d(logs_namespaceObject, {
+    controlRefusal: ()=>controlRefusal,
     handler: ()=>logs_handler,
     schema: ()=>logs_schema_schema
 });
@@ -579,7 +582,7 @@ __webpack_require__.d(wait_namespaceObject, {
     handler: ()=>wait_handler,
     schema: ()=>wait_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"10.1.0","El":{"OP":"4.0.17"}}');
+var package_namespaceObject = JSON.parse('{"rE":"10.2.0","El":{"OP":"4.0.20"}}');
 const ENVELOPE_SCHEMA = 1;
 const collectWarnings = (warnings)=>{
     if (!warnings) return [];
@@ -605,7 +608,7 @@ function envelopeObject(init) {
     if ("string" == typeof init.hint && init.hint) frame.hint = init.hint;
     return frame;
 }
-function envelope(init) {
+function envelope_envelope(init) {
     return JSON.stringify(envelopeObject(init));
 }
 function sessionCommandSinceEnvelopeOwnsCommand(contract) {
@@ -769,7 +772,7 @@ async function spawnFailedEnvelope(command, spawned) {
         await new Promise((resolve)=>setTimeout(resolve, 25));
         cause = spawned.spawnError?.() ?? null;
     }
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command,
         status: "spawn-failed",
@@ -865,7 +868,11 @@ function tokenTtlNote(workspaceSlug, projectSlug) {
 function resolveApiBase(api) {
     return String(api || process.env.EXTENSION_DEV_API_URL || DEFAULT_API).replace(/\/+$/, "");
 }
-function safeApiBase(raw) {
+function isExtensionDevHost(hostname) {
+    const host = hostname.toLowerCase().replace(/\.+$/, "");
+    return "extension.dev" === host || host.endsWith(".extension.dev");
+}
+function safeApiBase(raw, callerSupplied) {
     let parsed;
     try {
         parsed = new URL(raw);
@@ -880,6 +887,11 @@ function safeApiBase(raw) {
         ok: false,
         message: `Refusing to send the access token to ${raw}: use https (http is allowed only for localhost).`
     };
+    const fromCaller = String(callerSupplied || "").trim();
+    if (fromCaller && !isLocalhost && !isExtensionDevHost(parsed.hostname)) return {
+        ok: false,
+        message: `Refusing to send the access token to ${raw}: an api argument may only name an extension.dev host or a local dev server. To use a self-hosted platform, set EXTENSION_DEV_API_URL where the server is launched instead of passing it per call.`
+    };
     return {
         ok: true,
         base: `${parsed.origin}${parsed.pathname}`.replace(/\/+$/, "")
@@ -1081,7 +1093,7 @@ class RegistryAccessTokens {
                 status: "no-credential"
             };
         }
-        const check = safeApiBase(resolveApiBase(apiHint || creds?.api));
+        const check = safeApiBase(resolveApiBase(apiHint || creds?.api), apiHint);
         if (!check.ok) return {
             status: "denied",
             message: check.message
@@ -1415,7 +1427,7 @@ async function create_handler(args) {
                 error: capture("error")
             }
         });
-    const failure = (err, transient)=>transient ? envelope({
+    const failure = (err, transient)=>transient ? envelope_envelope({
             ok: false,
             command: COMMAND,
             status: "template-fetch-failed",
@@ -1428,7 +1440,7 @@ async function create_handler(args) {
                 duration: Date.now() - start,
                 log: logTail()
             }
-        }) : envelope({
+        }) : envelope_envelope({
             ok: false,
             command: COMMAND,
             status: "scaffold-failed",
@@ -1455,7 +1467,7 @@ async function create_handler(args) {
         }
     }
     const hasManifest = node_fs.existsSync(node_path.join(result.projectPath, "manifest.json")) || node_fs.existsSync(node_path.join(result.projectPath, "src", "manifest.json"));
-    if (!hasManifest) return envelope({
+    if (!hasManifest) return envelope_envelope({
         ok: false,
         command: COMMAND,
         status: "scaffold-incomplete",
@@ -1483,7 +1495,7 @@ async function create_handler(args) {
     const deployUrl = `${wwwOrigin}${(0, paths_0.wwwNewPath)({
         template: result.template
     })}`;
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: COMMAND,
         status: "created",
@@ -1525,7 +1537,7 @@ async function create_handler(args) {
 }
 const DEFAULT_MEDIA_ORIGIN = "https://media.extension.land";
 const DEFAULT_CHANNEL = "latest";
-const PINNED_COMMIT = "2d2ed9668cca002148d9eecd953a08b54d0bad9d";
+const PINNED_COMMIT = "520a8ede767fe1937c7184f4857408caf9c5934f";
 const CHANNEL_CACHE_TTL_MS = 300000;
 function mediaOrigin() {
     return (process.env.EXTENSION_MEDIA_ORIGIN || "").trim() || DEFAULT_MEDIA_ORIGIN;
@@ -1733,7 +1745,7 @@ async function searchTemplates(args) {
             repositoryUrl: t.repositoryUrl,
             downloads: t.downloads
         }));
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_templates",
         status: "listed",
@@ -1746,7 +1758,7 @@ async function searchTemplates(args) {
 const get_template_source_COMMAND = "extension_templates";
 async function readTemplateSource(args) {
     const template = await getTemplateBySlug(args.slug);
-    if (!template) return envelope({
+    if (!template) return envelope_envelope({
         ok: false,
         command: get_template_source_COMMAND,
         status: "template-not-found",
@@ -1766,7 +1778,7 @@ async function readTemplateSource(args) {
         keyFiles: template.keyFiles,
         repositoryUrl: template.repositoryUrl
     };
-    if (!args.files?.length) return envelope({
+    if (!args.files?.length) return envelope_envelope({
         ok: true,
         command: get_template_source_COMMAND,
         status: "file-list",
@@ -1791,7 +1803,7 @@ async function readTemplateSource(args) {
         } catch  {}
         errors.push(`${filePath}: ${lastStatus || "fetch failed"}`);
     }));
-    return envelope({
+    return envelope_envelope({
         ok: 0 === errors.length,
         command: get_template_source_COMMAND,
         status: errors.length ? "partial" : "read",
@@ -1873,7 +1885,7 @@ const templates_schema = {
 };
 async function templates_handler(args) {
     if ((args.action ?? "list") === "source" || !args.action && args.slug) {
-        if (!args.slug) return envelope({
+        if (!args.slug) return envelope_envelope({
             ok: false,
             command: "extension_templates",
             status: "bad-request",
@@ -1957,14 +1969,239 @@ const LAUNCH_BROWSER = {
     enum: LAUNCHABLE_BROWSERS,
     default: "chrome"
 };
+const OUTPUT_JSON_FLOOR = {
+    act: "3.18.1",
+    doctor: "4.0.11",
+    dev: "4.0.17",
+    build: "4.0.17"
+};
+const VERDICT_TTL_MS = 60000;
+const PROBE_TIMEOUT_MS = 20000;
+const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+function decompose(version) {
+    const match = SEMVER.exec(version.trim());
+    if (!match) return null;
+    return {
+        release: [
+            Number(match[1]),
+            Number(match[2]),
+            Number(match[3])
+        ],
+        prerelease: match[4] ? match[4].split(".") : []
+    };
+}
+function parseVersion(text) {
+    for (const line of text.split("\n")){
+        const candidate = line.trim();
+        if (candidate) {
+            if (decompose(candidate)) return candidate.replace(/^v/, "");
+        }
+    }
+    return null;
+}
+function compareNumericIdentifiers(a, b) {
+    const left = a.replace(/^0+(?=\d)/, "");
+    const right = b.replace(/^0+(?=\d)/, "");
+    if (left.length !== right.length) return left.length < right.length ? -1 : 1;
+    if (left === right) return 0;
+    return left < right ? -1 : 1;
+}
+function compareVersions(a, b) {
+    const left = decompose(a);
+    const right = decompose(b);
+    if (!left || !right) return null;
+    for(let i = 0; i < 3; i += 1)if (left.release[i] !== right.release[i]) return left.release[i] < right.release[i] ? -1 : 1;
+    if (!left.prerelease.length && !right.prerelease.length) return 0;
+    if (!left.prerelease.length) return 1;
+    if (!right.prerelease.length) return -1;
+    const length = Math.max(left.prerelease.length, right.prerelease.length);
+    for(let i = 0; i < length; i += 1){
+        const one = left.prerelease[i];
+        const other = right.prerelease[i];
+        if (void 0 === one) return -1;
+        if (void 0 === other) return 1;
+        const oneIsNumeric = /^\d+$/.test(one);
+        const otherIsNumeric = /^\d+$/.test(other);
+        if (oneIsNumeric && otherIsNumeric) {
+            const ordering = compareNumericIdentifiers(one, other);
+            if (0 !== ordering) return ordering;
+            continue;
+        }
+        if (oneIsNumeric !== otherIsNumeric) return oneIsNumeric ? -1 : 1;
+        if (one !== other) return one < other ? -1 : 1;
+    }
+    return 0;
+}
+const verdicts = new Map();
+function invocationKey(command, prefixArgs) {
+    return [
+        command,
+        ...prefixArgs
+    ].join("\0");
+}
+const NPX_PIN = /^extension@(.+)$/;
+function parseCapabilities(stdout) {
+    for (const line of stdout.split("\n")){
+        const candidate = line.trim();
+        if (!candidate.startsWith("{")) continue;
+        let frame;
+        try {
+            frame = JSON.parse(candidate);
+        } catch  {
+            continue;
+        }
+        if (!frame || "object" != typeof frame) continue;
+        const envelope = frame;
+        if (1 !== envelope.schema) continue;
+        if (true !== envelope.ok) continue;
+        if ("capabilities" !== envelope.command) continue;
+        const value = envelope.value;
+        if (!value || "object" != typeof value) continue;
+        const version = "string" == typeof value.version ? parseVersion(value.version) : null;
+        const roster = value.outputJsonCommands;
+        if (version && Array.isArray(roster)) {
+            if (roster.every((name)=>"string" == typeof name)) return {
+                version,
+                outputJsonCommands: roster
+            };
+        }
+    }
+    return null;
+}
+async function resolvedEngineFacts(projectPath) {
+    const { command, prefixArgs } = resolveExtensionInvocation(projectPath);
+    const key = invocationKey(command, prefixArgs);
+    const cached = verdicts.get(key);
+    if (cached && cached.expiresAt > Date.now()) return {
+        version: cached.version,
+        outputJsonCommands: cached.outputJsonCommands
+    };
+    const remember = (found)=>{
+        verdicts.set(key, {
+            ...found,
+            expiresAt: Date.now() + VERDICT_TTL_MS
+        });
+        return found;
+    };
+    for (const arg of prefixArgs){
+        const pin = NPX_PIN.exec(arg);
+        const pinned = pin ? parseVersion(pin[1]) : null;
+        if (pinned) return remember({
+            version: pinned,
+            outputJsonCommands: null
+        });
+    }
+    try {
+        const probe = await runExtensionCli([
+            "capabilities"
+        ], {
+            cwd: projectPath,
+            timeoutMs: PROBE_TIMEOUT_MS
+        });
+        if (0 === probe.code) {
+            const answered = parseCapabilities(probe.stdout ?? "");
+            if (answered) return remember(answered);
+        }
+    } catch  {}
+    try {
+        const probe = await runExtensionCli([
+            "--version"
+        ], {
+            cwd: projectPath,
+            timeoutMs: PROBE_TIMEOUT_MS
+        });
+        if (0 !== probe.code) return remember({
+            version: null,
+            outputJsonCommands: null
+        });
+        return remember({
+            version: parseVersion(probe.stdout ?? "") ?? parseVersion(probe.stderr ?? ""),
+            outputJsonCommands: null
+        });
+    } catch  {
+        return remember({
+            version: null,
+            outputJsonCommands: null
+        });
+    }
+}
+const ROSTER_NAMES = {
+    act: [
+        "eval",
+        "inspect",
+        "open",
+        "reload",
+        "storage"
+    ],
+    doctor: [
+        "doctor"
+    ],
+    dev: [
+        "dev"
+    ],
+    build: [
+        "build"
+    ]
+};
+async function outputJsonVerdict(command, projectPath) {
+    const floor = OUTPUT_JSON_FLOOR[command];
+    let engine;
+    try {
+        engine = await resolvedEngineFacts(projectPath);
+    } catch  {
+        return {
+            supported: null,
+            version: null,
+            floor
+        };
+    }
+    const roster = engine.outputJsonCommands;
+    if (roster) return {
+        supported: ROSTER_NAMES[command].every((name)=>roster.includes(name)),
+        version: engine.version,
+        floor
+    };
+    const version = engine.version;
+    if (null === version) return {
+        supported: null,
+        version: null,
+        floor
+    };
+    const ordering = compareVersions(version, floor);
+    if (null === ordering) return {
+        supported: null,
+        version,
+        floor
+    };
+    return {
+        supported: ordering >= 0,
+        version,
+        floor
+    };
+}
+const UNKNOWN_OUTPUT_FLAG = /unknown option[^\n]*--output\b/i;
+function refusedTheOutputFlag(stderr) {
+    return UNKNOWN_OUTPUT_FLAG.test(stderr);
+}
+async function outputFlagRefusalMessage(command, cliName, projectPath) {
+    const verdict = await outputJsonVerdict(command, projectPath);
+    const preamble = `The Extension.js resolved for this project refused \`--output json\` on \`extension ${cliName}\`.`;
+    const why = "You did not pass that flag: this server adds it so it can read a structured result instead of parsing a report written for a human, and unlike `build` there is no second source it can fall back to here, so it cannot simply drop it.";
+    if (false === verdict.supported) return `${preamble} It reports ${verdict.version}, and that flag only reached \`extension ${cliName}\` in ${verdict.floor}. ${why} Upgrade the project's Extension.js to ${verdict.floor} or newer and run this again.`;
+    if (true === verdict.supported) return `${preamble} It reports ${verdict.version}, which is at or above ${verdict.floor}, the release where that flag reached \`extension ${cliName}\`, so the binary being run is not the version it claims to be. ${why} Check the project's node_modules/.bin/extension and reinstall it, rather than upgrading a version that already looks new enough.`;
+    return `${preamble} Its version could not be read, so the cause cannot be confirmed, but that flag only reached \`extension ${cliName}\` in ${verdict.floor} and a refusal is what an engine below that does. ${why} Check the project's Extension.js install and bring it to ${verdict.floor} or newer.`;
+}
 const sessions = new Map();
 const registrationStamps = new Map();
 function sessionKey(projectPath, browser) {
     return `${node_path.resolve(projectPath)}::${browser}`;
 }
-function markerDir() {
+function sessionStateDir() {
     return process.env.EXTENSION_MCP_SESSION_DIR || node_path.join(node_os.tmpdir(), "extension-dev-mcp-sessions");
 }
+function markerDir() {
+    return sessionStateDir();
+}
 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`);
@@ -2047,8 +2284,29 @@ function removeSession(projectPath, browser, pid) {
 function listSessions() {
     return Array.from(sessions.values());
 }
+function sessionPathHint(file) {
+    return `Looked at ${file} (the session-state layout this MCP's pinned engine publishes). If the project runs an older Extension.js, its layout may differ and this path will never appear.`;
+}
+function profilesRootDir(projectPath) {
+    return node_path.join(sessionArtifactsRootDir(projectPath), "profiles");
+}
+function browserProfileRootDir(projectPath, browser) {
+    return node_path.join(profilesRootDir(projectPath), `${browser}-profile`);
+}
+const PERSISTED_PROFILE_DIR_NAME = "dev";
+function profileRemediation(input) {
+    const { projectPath, browser, profile } = input;
+    const raw = "string" == typeof profile ? profile.trim() : "";
+    if ("false" === raw.toLowerCase()) return `This session was launched with profile:"false", so it runs your real ${browser} profile and there is no Extension.js profile directory to remove. Quit the ${browser} window that holds it and start again.`;
+    if (raw.length > 0) {
+        const explicit = node_path.isAbsolute(raw) ? raw : node_path.resolve(projectPath, raw);
+        return `This session was launched against the profile you passed, ${explicit}. Close whatever still holds it, or remove that directory, before retrying.`;
+    }
+    const root = browserProfileRootDir(projectPath, browser);
+    return `The engine keeps this session's profile in a directory inside ${root}, one per run: "${PERSISTED_PROFILE_DIR_NAME}" when the profile is persisted, otherwise three random words drawn fresh on every start, which no caller can predict. List ${root} to see which run directories exist and remove the one the stuck browser holds, or remove ${root} entirely once no session is running.`;
+}
 function contractSightings(projectPath) {
-    const root = node_path.resolve(projectPath, "dist", "extension-js");
+    const root = sessionArtifactsRootDir(projectPath);
     let dirs;
     try {
         dirs = node_fs.readdirSync(root);
@@ -2057,7 +2315,7 @@ function contractSightings(projectPath) {
     }
     const sightings = [];
     for (const dir of dirs){
-        const readyPath = node_path.join(root, dir, "ready.json");
+        const readyPath = bridge_readyContractPath(projectPath, dir);
         try {
             const stat = node_fs.statSync(readyPath);
             const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
@@ -2126,7 +2384,7 @@ function deadReadySession(projectPath) {
     return null;
 }
 function contractBoundPort(projectPath, browser, since) {
-    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+    const readyPath = bridge_readyContractPath(projectPath, browser);
     try {
         const stat = node_fs.statSync(readyPath);
         if (stat.mtimeMs < since) return null;
@@ -2189,9 +2447,18 @@ function isChromiumFamily(browser) {
 function isGeckoFamily(browser) {
     return GECKO_FAMILY.has(browser);
 }
+function insideRepository(projectPath) {
+    let current = node_path.resolve(projectPath);
+    for(;;){
+        if (node_fs.existsSync(node_path.join(current, ".git"))) return true;
+        const parent = node_path.dirname(current);
+        if (parent === current) return false;
+        current = parent;
+    }
+}
 function ensureProjectIgnored(projectPath, options) {
     const entry = options.entry;
-    if (!node_fs.existsSync(node_path.join(projectPath, ".git"))) return {
+    if (!insideRepository(projectPath)) return {
         state: "not-a-repo",
         entry
     };
@@ -2223,6 +2490,56 @@ function ensureProjectIgnored(projectPath, options) {
         };
     }
 }
+const placedHere = new Set();
+function recordDir() {
+    return node_path.join(sessionStateDir(), "carriers");
+}
+function recordPath(resolved) {
+    const digest = node_crypto.createHash("sha1").update(resolved).digest("hex").slice(0, 16);
+    return node_path.join(recordDir(), `${digest}.json`);
+}
+function rememberCarrier(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    placedHere.add(resolved);
+    try {
+        node_fs.mkdirSync(recordDir(), {
+            recursive: true
+        });
+        node_fs.writeFileSync(recordPath(resolved), `${JSON.stringify({
+            projectPath: resolved,
+            pid: process.pid,
+            placedAt: new Date().toISOString()
+        })}\n`);
+    } catch  {}
+}
+function forgetCarrier(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    placedHere.delete(resolved);
+    try {
+        node_fs.rmSync(recordPath(resolved), {
+            force: true
+        });
+    } catch  {}
+}
+function carriersPlacedHere() {
+    return [
+        ...placedHere
+    ];
+}
+function rememberedCarriers() {
+    let files;
+    try {
+        files = node_fs.readdirSync(recordDir());
+    } catch  {
+        return [];
+    }
+    const out = [];
+    for (const file of files)if (file.endsWith(".json")) try {
+        const parsed = JSON.parse(node_fs.readFileSync(node_path.join(recordDir(), file), "utf8"));
+        if ("string" == typeof parsed.projectPath && parsed.projectPath) out.push(parsed.projectPath);
+    } catch  {}
+    return out;
+}
 const CARRIER_DIR_NAME = "extension-dev-live-preview";
 const CARRIER_EXTENSION_ID = "ibppeifnekhjjjmpjfiobccjlicbmgcb";
 const MARKER_FILE = "managed-by-extension-dev-mcp.json";
@@ -2241,16 +2558,78 @@ function deriveCarrierId(source) {
 function carrierPath(projectPath) {
     return node_path.join(projectPath, "extensions", CARRIER_DIR_NAME);
 }
+function relativeFiles(dir, base = dir, depth = 0) {
+    if (depth > 4) return null;
+    let entries;
+    try {
+        entries = node_fs.readdirSync(dir, {
+            withFileTypes: true
+        });
+    } catch  {
+        return null;
+    }
+    const out = [];
+    for (const entry of entries){
+        const full = node_path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            const nested = relativeFiles(full, base, depth + 1);
+            if (null === nested) return null;
+            out.push(...nested);
+            continue;
+        }
+        out.push(node_path.relative(base, full));
+        if (out.length > 500) return null;
+    }
+    return out;
+}
+function claimCarrier(target) {
+    if (node_fs.existsSync(node_path.join(target, MARKER_FILE))) return {
+        ours: true,
+        how: "marker"
+    };
+    if (deriveCarrierId(target) === CARRIER_EXTENSION_ID) return {
+        ours: true,
+        how: "payload"
+    };
+    if (node_fs.existsSync(node_path.join(target, "manifest.json"))) return {
+        ours: false,
+        how: "foreign"
+    };
+    const source = findBundledCarrier("chromium");
+    const bundled = source ? relativeFiles(source) : null;
+    const present = relativeFiles(target);
+    if (!bundled || !present) return {
+        ours: false,
+        how: "foreign"
+    };
+    const known = new Set(bundled);
+    return present.every((file)=>known.has(file)) ? {
+        ours: true,
+        how: "partial"
+    } : {
+        ours: false,
+        how: "foreign"
+    };
+}
+const RECOVERY_NOTE = {
+    payload: `Its ${MARKER_FILE} marker was missing, but its manifest key derives the carrier's own extension id ${CARRIER_EXTENSION_ID}, which only this package's payload has, so it was recognised as ours and taken back.`,
+    partial: `Its ${MARKER_FILE} marker was missing and it holds no manifest, but every file in it belongs to the bundled carrier payload, so it was recognised as a half-written copy of ours and taken back.`
+};
+const FOREIGN_NOTE = `extensions/${CARRIER_DIR_NAME} has no ${MARKER_FILE} marker, does not carry the carrier's own manifest key, and holds files this package never ships, so it is not the carrier this tool placed and was left untouched. Nothing here deletes a directory this tool did not write: rename it or move it out of ./extensions yourself if you want the carrier to live at that path.`;
 function removeCarrier(projectPath) {
     const target = carrierPath(projectPath);
-    if (!node_fs.existsSync(target)) return {
-        removed: false,
-        path: target
-    };
-    if (!node_fs.existsSync(node_path.join(target, MARKER_FILE))) return {
+    if (!node_fs.existsSync(target)) {
+        forgetCarrier(projectPath);
+        return {
+            removed: false,
+            path: target
+        };
+    }
+    const claim = claimCarrier(target);
+    if (!claim.ours) return {
         removed: false,
         path: target,
-        note: `extensions/${CARRIER_DIR_NAME} has no ${MARKER_FILE} marker, so it is not the carrier this tool placed and was left untouched.`
+        note: FOREIGN_NOTE
     };
     try {
         node_fs.rmSync(target, {
@@ -2264,13 +2643,17 @@ function removeCarrier(projectPath) {
             note: `Could not remove the carrier: ${error instanceof Error ? error.message : String(error)}`
         };
     }
+    forgetCarrier(projectPath);
     const parent = node_path.join(projectPath, "extensions");
     try {
         if (0 === node_fs.readdirSync(parent).length) node_fs.rmdirSync(parent);
     } catch  {}
     return {
         removed: true,
-        path: target
+        path: target,
+        ..."marker" === claim.how ? {} : {
+            note: RECOVERY_NOTE[claim.how]
+        }
     };
 }
 function ensureCarrierIgnored(projectPath) {
@@ -2308,10 +2691,14 @@ function materializeCarrier(projectPath, browser) {
     };
     const target = carrierPath(projectPath);
     const marker = node_path.join(target, MARKER_FILE);
-    if (node_fs.existsSync(target) && !node_fs.existsSync(marker)) return {
+    const claim = node_fs.existsSync(target) ? claimCarrier(target) : {
+        ours: true,
+        how: "marker"
+    };
+    if (!claim.ours) return {
         loaded: false,
         path: target,
-        note: `A directory already exists at extensions/${CARRIER_DIR_NAME} without the ${MARKER_FILE} marker, so it is not managed by this tool and was left untouched. Remove or rename it to let extension_dev place the carrier there.`
+        note: `A directory already exists at extensions/${CARRIER_DIR_NAME} that this tool did not place: no ${MARKER_FILE} marker, no carrier manifest key, and files this package never ships. It was left untouched. Rename it or move it out of ./extensions to let extension_dev place the carrier there.`
     };
     const carrierId = deriveCarrierId(source);
     try {
@@ -2328,6 +2715,7 @@ function materializeCarrier(projectPath, browser) {
             carrierVersion: manifest.version ?? "unknown",
             note: "Safe to delete; extension_dev recreates it when carrier: true. extension_stop and extension_build remove it for you."
         }, null, 2)}\n`);
+        rememberCarrier(projectPath);
         const ignored = ensureCarrierIgnored(projectPath);
         return {
             loaded: true,
@@ -2335,7 +2723,7 @@ function materializeCarrier(projectPath, browser) {
             ...ignored ? {
                 gitignored: ignored
             } : {},
-            note: "Live-preview carrier placed in ./extensions; Extension.js loads it as a companion beside your extension. Open https://preview.extension.dev/?session=live in the dev browser (any http://localhost origin works too) to watch the session's real-lane chrome.* trace on the Trace tab. It is a debug companion, never part of a release: extension_stop and extension_build remove it again" + (ignored ? `, and ${ignored} was added to .gitignore.` : "."),
+            note: "Live-preview carrier placed in ./extensions; Extension.js loads it as a companion beside your extension. Open https://preview.extension.dev/ in the dev browser, load a build from this machine, and switch the lane toggle to Real to watch the session's real-lane chrome.* trace on the Trace tab. It is a debug companion, never part of a release: extension_stop and extension_build remove it again" + (ignored ? `, and ${ignored} was added to .gitignore.` : "."),
             limitations: [
                 "The trace shows calls a PAGE bridges to the carrier. Your extension's own chrome.* calls run directly in its contexts and never cross the carrier, so they do not appear.",
                 "Bridged calls run under the CARRIER's identity, not your extension's. The preview assumes a single active guest and does not namespace per-extension state, so storage, action/badge state, messaging delivery, offscreen documents and relative script paths belong to the carrier. Rows affected are badged carrier-scoped in the Trace tab.",
@@ -2345,7 +2733,7 @@ function materializeCarrier(projectPath, browser) {
             ...carrierId ? {
                 bridgeProtocol: {
                     carrierExtensionId: carrierId,
-                    allowedOrigins: "https://preview.extension.dev, https://code.extension.dev, https://themes.extension.dev, http://localhost/*, http://127.0.0.1/*",
+                    allowedOrigins: "https://preview.extension.dev, https://code.extension.dev, https://themes.extension.dev, and those same apps' dev servers on http://localhost and http://127.0.0.1 (ports 3103, 3104, 3110, 3111). The carrier checks the sender's origin, so a page on any other localhost port is refused.",
                     howTo: "From a page on an allowed origin, register your guest once with a 'session' message (it declares the permissions the carrier enforces), then send 'bridge' messages to run chrome.* for real; each one streams into the Trace tab. Use the EXACT dotted wire names the bridge dispatcher accepts: storage is storage.get/set/remove/clear with the AREA AS AN ARGUMENT, NOT storage.local.get.",
                     example: [
                         `const id = '${carrierId}'`,
@@ -2364,16 +2752,115 @@ function materializeCarrier(projectPath, browser) {
         };
     }
 }
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const EOCD_MIN_LENGTH = 22;
+const MAX_COMMENT_LENGTH = 0xffff;
+const MAX_DIRECTORY_BYTES = 33554432;
+const UNREADABLE = {
+    names: [],
+    readable: false
+};
+function readZipEntryNames(zipPath) {
+    let handle = null;
+    try {
+        const size = node_fs.statSync(zipPath).size;
+        if (size < EOCD_MIN_LENGTH) return UNREADABLE;
+        handle = node_fs.openSync(zipPath, "r");
+        const tailLength = Math.min(size, MAX_COMMENT_LENGTH + EOCD_MIN_LENGTH);
+        const tail = Buffer.alloc(tailLength);
+        node_fs.readSync(handle, tail, 0, tailLength, size - tailLength);
+        let eocd = -1;
+        for(let at = tail.length - EOCD_MIN_LENGTH; at >= 0; at -= 1)if (tail.readUInt32LE(at) === EOCD_SIGNATURE) {
+            eocd = at;
+            break;
+        }
+        if (eocd < 0) return UNREADABLE;
+        const expected = tail.readUInt16LE(eocd + 10);
+        const directoryBytes = tail.readUInt32LE(eocd + 12);
+        const directoryOffset = tail.readUInt32LE(eocd + 16);
+        if (0xffff === expected || 0xffffffff === directoryBytes || 0xffffffff === directoryOffset || directoryBytes > MAX_DIRECTORY_BYTES || directoryOffset + directoryBytes > size) return UNREADABLE;
+        if (0 === directoryBytes) return {
+            names: [],
+            readable: 0 === expected
+        };
+        const directory = Buffer.alloc(directoryBytes);
+        node_fs.readSync(handle, directory, 0, directoryBytes, directoryOffset);
+        const names = [];
+        let at = 0;
+        while(at + 46 <= directory.length){
+            if (directory.readUInt32LE(at) !== CENTRAL_SIGNATURE) return UNREADABLE;
+            const nameLength = directory.readUInt16LE(at + 28);
+            const extraLength = directory.readUInt16LE(at + 30);
+            const commentLength = directory.readUInt16LE(at + 32);
+            const nameStart = at + 46;
+            if (nameStart + nameLength > directory.length) return UNREADABLE;
+            names.push(directory.subarray(nameStart, nameStart + nameLength).toString("utf8"));
+            at = nameStart + nameLength + extraLength + commentLength;
+        }
+        return {
+            names,
+            readable: names.length === expected
+        };
+    } catch  {
+        return UNREADABLE;
+    } finally{
+        if (null !== handle) try {
+            node_fs.closeSync(handle);
+        } catch  {}
+    }
+}
 const build_COMMAND = "extension_build";
 function readBuildSummary(projectPath, browser, since) {
-    const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "build-summary.json");
+    const file = buildSummaryPath(projectPath, browser);
     try {
         const stat = node_fs.statSync(file);
-        if (stat.mtimeMs < since) return null;
-        const summary = JSON.parse(node_fs.readFileSync(file, "utf8"));
-        if (summary && "object" == typeof summary) return summary;
+        if (stat.mtimeMs >= since) {
+            const summary = JSON.parse(node_fs.readFileSync(file, "utf8"));
+            if (summary && "object" == typeof summary) return {
+                file,
+                summary
+            };
+        }
     } catch  {}
-    return null;
+    return {
+        file,
+        summary: null
+    };
+}
+function readEngineOutput(stdout, stderr) {
+    let frame = null;
+    const rest = [];
+    for (const line of stdout.split("\n")){
+        const text = line.trim();
+        if (!frame && text.startsWith("{")) {
+            let parsed = null;
+            try {
+                parsed = JSON.parse(text);
+            } catch  {}
+            if (isEnvelope(parsed)) {
+                frame = parsed;
+                continue;
+            }
+        }
+        rest.push(line);
+    }
+    const narration = [
+        rest.join("\n").trim(),
+        stderr.trim()
+    ].filter(Boolean).join("\n");
+    return {
+        frame,
+        narration
+    };
+}
+function engineSummaries(frame) {
+    const value = frame?.value;
+    if (!value || !Array.isArray(value.summaries)) return [];
+    return value.summaries.filter((entry)=>Boolean(entry) && "object" == typeof entry);
+}
+function summaryForBrowser(summaries, browser) {
+    return summaries.find((entry)=>entry.browser === browser) ?? summaries[0] ?? null;
 }
 function builtEntrypoints(distDir) {
     let manifest;
@@ -2462,7 +2949,7 @@ function locateSourceZip(projectPath, browser, since) {
 }
 const build_schema = {
     name: "extension_build",
-    description: "Build a browser extension for production. The output lands in dist/<browser>/. Pass zip:true to also package a .zip for store submission. The build refuses a manifest with build-blocking errors unless you pass skipValidation:true, because such a manifest yields a broken bundle the bundler itself never flags.",
+    description: "Build a browser extension for production. The output lands in dist/<browser>/. Pass zip:true to also package a .zip for store submission. With browser:'safari' the build converts the extension into a macOS app through Xcode, and bundleId sets the identifier it ships under. The build refuses a manifest with build-blocking errors unless you pass skipValidation:true, because such a manifest yields a broken bundle the bundler itself never flags.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2506,6 +2993,24 @@ const build_schema = {
                 type: "boolean",
                 default: false,
                 description: "Build even when extension_manifest_validate reports build-blocking errors. The build normally refuses: a manifest error yields a broken bundle the bundler itself never flags."
+            },
+            appName: {
+                type: "string",
+                description: "Safari targets only: name of the generated macOS app, which also names the Xcode scheme and the .app on disk. Defaults to the manifest name."
+            },
+            bundleId: {
+                type: "string",
+                description: "Safari targets only: a reverse-DNS bundle identifier you own, such as com.acme.readinglist. Without one the app is packaged under a generated dev.extensionjs.* identifier derived from the app name, which every project built from the same template shares, and the first team to register it takes it."
+            },
+            macOsOnly: {
+                type: "boolean",
+                default: true,
+                description: "Safari targets only: generate a macOS-only Xcode project. Pass false for a universal project that also targets iOS and iPadOS, which is what you want if the extension ships on iPhone or iPad."
+            },
+            forceRegenerate: {
+                type: "boolean",
+                default: false,
+                description: "Safari targets only: regenerate the Xcode project even when the engine considers it up to date. Use it when an earlier packaging run left the project broken."
             }
         },
         required: [
@@ -2513,6 +3018,11 @@ const build_schema = {
         ]
     }
 };
+const SAFARI_VENDORS = new Set([
+    "safari",
+    "webkit-based"
+]);
+const BUNDLE_ID_PATTERN = /^[A-Za-z][A-Za-z0-9-]*(\.[A-Za-z][A-Za-z0-9-]*)+$/;
 function manifestDivergence(projectPath, browser) {
     const read = (p)=>{
         try {
@@ -2540,23 +3050,58 @@ function manifestDivergence(projectPath, browser) {
     return notes;
 }
 const MARKER_FILE_NAME = "managed-by-extension-dev-mcp.json";
-function carrierEntriesInDist(distDir, depth = 0) {
-    if (depth > 3) return [];
+function namesCarrier(entryName) {
+    return entryName === CARRIER_DIR_NAME || entryName === MARKER_FILE_NAME;
+}
+function carrierEntriesInZip(zipPath) {
+    const listing = readZipEntryNames(zipPath);
+    if (!listing.readable) return {
+        paths: [],
+        unchecked: [
+            zipPath
+        ]
+    };
+    const hits = listing.names.filter((name)=>name.split("/").some(namesCarrier)).map((name)=>`${zipPath} -> ${name}`);
+    return {
+        paths: hits,
+        unchecked: []
+    };
+}
+function carrierContamination(dir, depth = 0) {
+    if (depth > 4) return {
+        paths: [],
+        unchecked: []
+    };
     let entries;
     try {
-        entries = node_fs.readdirSync(distDir, {
+        entries = node_fs.readdirSync(dir, {
             withFileTypes: true
         });
     } catch  {
-        return [];
+        return {
+            paths: [],
+            unchecked: []
+        };
     }
-    const found = [];
+    const found = {
+        paths: [],
+        unchecked: []
+    };
+    const absorb = (other)=>{
+        found.paths.push(...other.paths);
+        found.unchecked.push(...other.unchecked);
+    };
     for (const entry of entries){
-        if (entry.name === CARRIER_DIR_NAME || entry.name === MARKER_FILE_NAME) {
-            found.push(node_path.join(distDir, entry.name));
+        const full = node_path.join(dir, entry.name);
+        if (namesCarrier(entry.name)) {
+            found.paths.push(full);
             continue;
         }
-        if (entry.isDirectory()) found.push(...carrierEntriesInDist(node_path.join(distDir, entry.name), depth + 1));
+        if (entry.isDirectory()) {
+            absorb(carrierContamination(full, depth + 1));
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith(".zip")) absorb(carrierEntriesInZip(full));
     }
     return found;
 }
@@ -2585,12 +3130,61 @@ async function validationPreflight(projectPath, browser) {
 async function build_handler(args) {
     const start = Date.now();
     const browser = args.browser ?? "chrome";
+    const safari = SAFARI_VENDORS.has(browser);
+    const safariOnly = [
+        [
+            "appName",
+            args.appName
+        ],
+        [
+            "bundleId",
+            args.bundleId
+        ],
+        [
+            "macOsOnly",
+            args.macOsOnly
+        ],
+        [
+            "forceRegenerate",
+            true === args.forceRegenerate ? true : void 0
+        ]
+    ].filter(([, value])=>void 0 !== value).map(([name])=>name);
+    if (safariOnly.length > 0 && !safari) return envelope_envelope({
+        ok: false,
+        command: build_COMMAND,
+        status: "safari-only-option",
+        error: {
+            code: "E_SAFARI_ONLY_OPTION",
+            message: `${safariOnly.join(", ")} configure the Safari web-extension conversion and mean nothing for a ${browser} build. Nothing was built, so the options were not silently ignored.`
+        },
+        value: {
+            browser,
+            options: safariOnly,
+            duration: Date.now() - start
+        },
+        hint: `Pass browser: "safari" to package a Safari app, or drop these options to build for ${browser}.`
+    });
+    if (void 0 !== args.bundleId && !BUNDLE_ID_PATTERN.test(args.bundleId)) return envelope_envelope({
+        ok: false,
+        command: build_COMMAND,
+        status: "invalid-bundle-id",
+        error: {
+            code: "E_INVALID_BUNDLE_ID",
+            message: `bundleId ${JSON.stringify(args.bundleId)} is not a reverse-DNS identifier, so Xcode would reject it. Expected two or more dot-separated segments of letters, digits and hyphens, each starting with a letter.`
+        },
+        value: {
+            browser,
+            bundleId: args.bundleId,
+            duration: Date.now() - start
+        },
+        hint: 'Use an identifier under a domain you own, for example "com.acme.readinglist".'
+    });
     const carrierCleanup = removeCarrier(args.projectPath);
     const carrierNotes = [];
     if (carrierCleanup.removed) carrierNotes.push("Removed the Extension.dev live-preview carrier from ./extensions before building. It is a debug companion, not part of your extension; run extension_dev with carrier: true to get it back.");
     else if (carrierCleanup.note) carrierNotes.push(carrierCleanup.note);
     const preflight = args.skipValidation ? null : await validationPreflight(args.projectPath, browser);
-    if (preflight?.buildBlocking) return envelope({
+    if (preflight?.buildBlocking) return envelope_envelope({
         ok: false,
         command: build_COMMAND,
         status: "manifest-blocked",
@@ -2623,40 +3217,63 @@ async function build_handler(args) {
     if (args.polyfill) cliArgs.push("--polyfill");
     if (args.silent) cliArgs.push("--silent");
     if (args.mode) cliArgs.push("--mode", args.mode);
-    const { code, stdout, stderr } = await runExtensionCli(cliArgs, {
+    if (args.appName) cliArgs.push("--app-name", args.appName);
+    if (args.bundleId) cliArgs.push("--bundle-id", args.bundleId);
+    if (void 0 !== args.macOsOnly) cliArgs.push("--macos-only", String(args.macOsOnly));
+    if (args.forceRegenerate) cliArgs.push("--force-regenerate");
+    const spawn = {
         cwd: args.projectPath,
         timeoutMs: 180000
-    });
+    };
+    const verdict = await outputJsonVerdict("build", args.projectPath);
+    const engineKnownTooOld = false === verdict.supported;
+    let attempt = engineKnownTooOld ? await runExtensionCli(cliArgs, spawn) : await runExtensionCli([
+        ...cliArgs,
+        "--output",
+        "json"
+    ], spawn);
+    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.`);
     const duration = Date.now() - start;
-    const out = (stdout ?? "").trim();
+    const engine = readEngineOutput(stdout ?? "", stderr ?? "");
+    const out = engine.narration;
     const lastLines = (text, n)=>text.split("\n").slice(-n).join("\n");
     if (0 === code) {
-        const size = out.match(/Size:\s*([\d.]+\s*[kKmMgG]?B)/)?.[1];
-        const status = out.match(/Build Status:\s*(\w+)/)?.[1];
-        const engineSummary = readBuildSummary(args.projectPath, browser, start);
+        const inlineSummary = summaryForBrowser(engineSummaries(engine.frame), browser);
+        const persisted = inlineSummary ? null : readBuildSummary(args.projectPath, browser, start);
+        const engineSummary = inlineSummary ?? persisted?.summary ?? null;
+        const summaryPathNote = persisted && !persisted.summary ? `This build reported no summary of its own, and no summary from this run was found on disk either, so the byte totals and the engine's structured warnings are missing from the result below. The extension that was built is unaffected. ${sessionPathHint(persisted.file)}` : null;
+        const status = engine.frame?.status;
         const buildWarnings = engineSummary?.warnings?.length ? engineSummary.warnings : [];
         const buildWarningsTruncated = buildWarnings.length && "number" == typeof engineSummary?.warnings_count && engineSummary.warnings_count > buildWarnings.length ? engineSummary.warnings_count : void 0;
         const distDir = node_path.resolve(args.projectPath, "dist", browser);
         const entrypoints = builtEntrypoints(distDir);
-        const contamination = carrierEntriesInDist(distDir);
-        if (contamination.length) return envelope({
+        const contamination = carrierContamination(node_path.resolve(args.projectPath, "dist"));
+        const uncheckedNote = contamination.unchecked.length ? `Could not read the entry table of ${contamination.unchecked.join(", ")}, so those archives were not checked for the live-preview carrier. Unpack and check them yourself before submitting.` : null;
+        if (contamination.paths.length) return envelope_envelope({
             ok: false,
             command: build_COMMAND,
             status: "carrier-in-dist",
             error: {
                 code: "E_CARRIER_IN_DIST",
-                message: `The build output contains the Extension.dev live-preview carrier: ${contamination.join(", ")}. That is a local debug companion and must never ship. This artifact is not safe to submit.`
+                message: `The build output contains the Extension.dev live-preview carrier: ${contamination.paths.join(", ")}. That is a local debug companion and must never ship. This artifact is not safe to submit.`
             },
             value: {
                 browser,
                 buildExitCode: 0,
                 duration
             },
-            warnings,
-            hint: "Delete the listed paths from dist and build again. The carrier normally lives in ./extensions and is removed before every build."
+            warnings: [
+                ...warnings,
+                uncheckedNote
+            ],
+            hint: "Delete the listed paths from dist and build again. The carrier lives in ./extensions and is taken back before every build run through this tool, so an entry inside a zip means that archive was packed by something else, usually 'extension build --zip-source' driven straight at the engine while a dev session had the carrier in place."
         });
         const missing = entrypoints.filter((e)=>!e.present);
-        if (missing.length) return envelope({
+        if (missing.length) return envelope_envelope({
             ok: false,
             command: build_COMMAND,
             status: "entrypoint-missing",
@@ -2684,18 +3301,36 @@ async function build_handler(args) {
         const zipSourcePath = args.zipSource ? locateSourceZip(args.projectPath, browser, start) : null;
         if (args.zipSource && !zipSourcePath) zipNotes.push("zipSource: true was requested and the build succeeded, but no *-source.zip file could be located in dist/. The engine may not have packaged it; check the build output below.");
         const divergence = manifestDivergence(args.projectPath, browser);
-        return envelope({
+        const safariIdentity = safari ? engineSummary?.safari ?? null : null;
+        const derivedBundleIdNote = safariIdentity?.bundleIdDerived === true ? `The Safari app was packaged under the generated bundle identifier ${safariIdentity.bundleId ?? "the engine derived for you"}, which the engine derived from your app name rather than one you chose. It is fine for running the app locally. Every project built from the same template derives the same identifier, and Apple binds one permanently to the first team that registers it, so whoever submits first takes it and everyone after is locked out. Rebuild with bundleId set to a reverse-DNS identifier under a domain you own, which regenerates the Xcode project, and do it before your first submission: afterwards a new identifier is a new extension carrying none of your users.` : null;
+        const safariIdentityMissingNote = safari && !safariIdentity ? `The build succeeded but reported no Safari app identity, so this run cannot tell you which bundle identifier the app carries. Either the packager did not run (a non-macOS host, or Xcode missing, skips packaging and leaves a plain bundle in dist/${browser}), or the engine installed in this project predates the reporting contract. Check the build output below, and run extension_doctor if you expected an app.` : null;
+        return envelope_envelope({
             ok: true,
             command: build_COMMAND,
             status: "built",
             value: {
                 browser,
-                ...size ? {
-                    size
+                ...safariIdentity ? {
+                    safariApp: safariIdentity
+                } : {},
+                ..."string" == typeof engineSummary?.output_path ? {
+                    outputPath: engineSummary.output_path
+                } : {},
+                ..."number" == typeof engineSummary?.total_bytes ? {
+                    totalBytes: engineSummary.total_bytes
+                } : {},
+                ..."number" == typeof engineSummary?.total_assets ? {
+                    totalAssets: engineSummary.total_assets
+                } : {},
+                ..."number" == typeof engineSummary?.largest_asset_bytes ? {
+                    largestAssetBytes: engineSummary.largest_asset_bytes
                 } : {},
                 ...status ? {
                     engineBuildStatus: status
                 } : {},
+                ...engineRefusedJsonOutput ? {
+                    engineRejectedJsonOutput: true
+                } : {},
                 ...entrypoints.length ? {
                     entrypoints
                 } : {},
@@ -2719,12 +3354,17 @@ async function build_handler(args) {
                 ...warnings,
                 ...preflight?.warnings ?? [],
                 ...buildWarnings,
-                ...zipNotes
+                ...zipNotes,
+                uncheckedNote,
+                derivedBundleIdNote,
+                safariIdentityMissingNote,
+                summaryPathNote
             ]
         });
     }
-    const message = stderr.trim() || out || `extension build exited with code ${code}`;
-    return envelope({
+    const engineFailure = "string" == typeof engine.frame?.error?.message ? engine.frame.error.message.trim() : "";
+    const message = engineFailure || stderr.trim() || out || `extension build exited with code ${code}`;
+    return envelope_envelope({
         ok: false,
         command: build_COMMAND,
         status: "build-failed",
@@ -2737,7 +3377,7 @@ async function build_handler(args) {
             duration
         },
         warnings,
-        hint: "Check that the project has a valid src/manifest.json and its dependencies are installed (extension_dev auto-installs; build does not)."
+        hint: "Check that the project has a valid src/manifest.json. Missing dependencies are installed by the build itself, so a failure here is usually the manifest, a compile error, or a Safari toolchain the host does not have."
     });
 }
 const MERGED_FD_CHATTER = [
@@ -2764,12 +3404,9 @@ function legacyProfileLockScrape(cleanOutput) {
 }
 const LEGACY_FIDELITY_WARNING = "This session ran a CLI that does not stamp the machine contract, so the boot verdict was read from the dev server's output instead of its ready contract. Diagnostics are less precise: compile errors come back as a text tail rather than a list. Upgrade the project's extension dependency to get the precise verdict.";
 const READY_STAMP_PROFILE_LOCKED_CODE = "profile_locked";
-function readyContractPath(projectPath, browser) {
-    return node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
-}
 function readContract(projectPath, browser, since) {
     try {
-        const file = readyContractPath(projectPath, browser);
+        const file = bridge_readyContractPath(projectPath, browser);
         const stat = node_fs.statSync(file);
         const contract = JSON.parse(node_fs.readFileSync(file, "utf8"));
         if (!contract || "object" != typeof contract) return null;
@@ -2893,6 +3530,71 @@ async function pollBootVerdict(projectPath, browser, options) {
         warnings: []
     };
 }
+function sweepCarriers(projectPaths) {
+    const out = [];
+    const seen = new Set();
+    for (const projectPath of projectPaths){
+        const resolved = node_path.resolve(projectPath);
+        if (!seen.has(resolved)) {
+            seen.add(resolved);
+            try {
+                const removal = removeCarrier(resolved);
+                if (!removal.removed && !removal.note) continue;
+                out.push({
+                    projectPath: resolved,
+                    ...removal
+                });
+            } catch (error) {
+                out.push({
+                    projectPath: resolved,
+                    removed: false,
+                    path: carrierPath(resolved),
+                    note: `Could not remove the carrier: ${error instanceof Error ? error.message : String(error)}`
+                });
+            }
+        }
+    }
+    return out;
+}
+function sweepCarriersPlacedHere() {
+    try {
+        return sweepCarriers(carriersPlacedHere());
+    } catch  {
+        return [];
+    }
+}
+const EXIT_SIGNALS = [
+    "SIGINT",
+    "SIGTERM",
+    "SIGHUP"
+];
+let carrier_exit_installed = [];
+function installCarrierExitCleanup() {
+    if (carrier_exit_installed.length) return;
+    const onExit = ()=>{
+        sweepCarriersPlacedHere();
+    };
+    process.on("exit", onExit);
+    carrier_exit_installed.push({
+        event: "exit",
+        handler: onExit
+    });
+    for (const signal of EXIT_SIGNALS){
+        const onSignal = ()=>{
+            sweepCarriersPlacedHere();
+            process.removeListener(signal, onSignal);
+            carrier_exit_installed = carrier_exit_installed.filter((entry)=>entry.handler !== onSignal);
+            if (0 === process.listenerCount(signal)) try {
+                process.kill(process.pid, signal);
+            } catch  {}
+        };
+        process.on(signal, onSignal);
+        carrier_exit_installed.push({
+            event: signal,
+            handler: onSignal
+        });
+    }
+}
 const stop_schema = {
     name: "extension_stop",
     description: "Stop a session that extension_dev or extension_start is running: terminate the server and the browser it launched, and remove the live-preview carrier if extension_dev placed one. This covers extension_start build:false too, which the registry records as a preview session. Call it when you are done verifying, so sessions do not accumulate.",
@@ -2907,7 +3609,7 @@ const stop_schema = {
             all: {
                 type: "boolean",
                 default: false,
-                description: "Stop every known session across projects and browsers, found from this server's registry AND the on-disk markers earlier runs left, so it still works after an MCP restart. projectPath/browser are then ignored."
+                description: "Stop every known session across projects and browsers, found from this server's registry AND the on-disk markers earlier runs left, so it still works after an MCP restart. It also takes back every live-preview carrier still recorded on this machine, including one in a project whose session was never stopped. projectPath/browser are then ignored."
             }
         },
         required: []
@@ -2973,7 +3675,7 @@ function sessionProcessPids(projectPath) {
         const escaped = escapeRegex(form);
         const patterns = [
             `extension[^ ]* (dev|start|preview) ${escaped}`,
-            `${escaped}${escapeRegex(node_path.sep)}dist${escapeRegex(node_path.sep)}extension-profile-`
+            `${escapeRegex(profilesRootDir(form))}${escapeRegex(node_path.sep)}`
         ];
         for (const pattern of patterns)for (const pid of pgrepPids(pattern))pids.add(pid);
     }
@@ -3009,12 +3711,9 @@ function stop_signal(pid, sig) {
         }
     }
 }
-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 raw = node_fs.readFileSync(bridge_readyContractPath(projectPath, browser), "utf8");
         const contract = JSON.parse(raw);
         return "number" == typeof contract.pid ? contract.pid : null;
     } catch  {
@@ -3051,7 +3750,7 @@ async function stopOne(projectPath, browser) {
     removeSession(projectPath, browser);
     removeSessionMarker(projectPath, browser);
     try {
-        node_fs.rmSync(readyJsonPath(projectPath, browser), {
+        node_fs.rmSync(bridge_readyContractPath(projectPath, browser), {
             force: true
         });
     } catch  {}
@@ -3077,28 +3776,36 @@ async function stop_handler(args) {
             const key = `${node_path.resolve(m.projectPath)}::${m.browser}`;
             if (!candidates.has(key)) candidates.set(key, m);
         }
-        if (0 === candidates.size) return envelope({
+        const outcomes = [];
+        for (const c of candidates.values())outcomes.push(await stopOne(c.projectPath, c.browser));
+        const visited = new Set(outcomes.map((outcome)=>node_path.resolve(outcome.projectPath)));
+        const carriers = sweepCarriers(rememberedCarriers().filter((p)=>!visited.has(node_path.resolve(p))));
+        if (0 === candidates.size && 0 === carriers.length) return envelope_envelope({
             ok: true,
             command: stop_schema.name,
             status: "nothing-to-stop",
             value: {
                 stopped: []
             },
-            hint: "No sessions registered in this server and no session markers on disk. Nothing to stop."
+            hint: "No sessions registered in this server, no session markers on disk, and no carrier left in any project this machine recorded. Nothing to stop."
         });
-        const outcomes = [];
-        for (const c of candidates.values())outcomes.push(await stopOne(c.projectPath, c.browser));
-        return envelope({
+        return envelope_envelope({
             ok: outcomes.every((o)=>o.stopped),
             command: stop_schema.name,
             status: "stopped-all",
             value: {
-                stopped: outcomes
+                stopped: outcomes,
+                ...carriers.length ? {
+                    carriersSwept: carriers
+                } : {}
             },
-            warnings: outcomes.map((o)=>o.stopped ? null : o.detail)
+            warnings: [
+                ...outcomes.map((o)=>o.stopped ? null : o.detail),
+                ...carriers.map((c)=>c.removed ? `Took the live-preview carrier back out of ${c.projectPath}, which had no session left to stop it.` : `Left the carrier in ${c.projectPath} alone: ${c.note ?? "unknown reason"}`)
+            ]
         });
     }
-    if (!args.projectPath) return envelope({
+    if (!args.projectPath) return envelope_envelope({
         ok: false,
         command: stop_schema.name,
         status: "bad-request",
@@ -3109,7 +3816,7 @@ async function stop_handler(args) {
     });
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     const outcome = await stopOne(args.projectPath, browser);
-    return envelope({
+    return envelope_envelope({
         ok: outcome.stopped,
         command: stop_schema.name,
         status: null === outcome.pid ? "not-found" : outcome.stopped ? "stopped" : "still-alive",
@@ -3219,7 +3926,7 @@ async function dev_handler(args) {
     if (existing.length > 0) {
         if (!args.replace) {
             const listed = existing.map((s)=>`pid ${s.pid} (${s.browser})`).join(", ");
-            return envelope({
+            return envelope_envelope({
                 ok: false,
                 command: dev_schema.name,
                 status: "session-exists",
@@ -3277,6 +3984,9 @@ async function dev_handler(args) {
     child.on("exit", ()=>{
         removeSession(args.projectPath, browser, pid);
         removeSessionMarker(args.projectPath, browser, pid);
+        if (carrier) try {
+            removeCarrier(args.projectPath);
+        } catch  {}
     });
     const boot = await pollBootVerdict(args.projectPath, browser, {
         child,
@@ -3294,7 +4004,7 @@ async function dev_handler(args) {
     };
     if ("exited" === boot.verdict.kind) {
         const { exitCode: code, signal } = boot.verdict;
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: dev_schema.name,
             status: "exited",
@@ -3314,7 +4024,7 @@ async function dev_handler(args) {
     }
     if ("compile-failed" === boot.verdict.kind) {
         const { compileErrors } = boot.verdict;
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: dev_schema.name,
             status: "compile-failed",
@@ -3333,10 +4043,16 @@ async function dev_handler(args) {
             warnings: boot.warnings
         });
     }
-    const profileDir = node_path.join(args.projectPath, "dist", `extension-profile-${browser}`);
+    const usesManagedProfile = "string" != typeof args.profile || 0 === args.profile.trim().length;
+    const profileRootDir = usesManagedProfile ? browserProfileRootDir(args.projectPath, browser) : null;
+    const profileAdvice = profileRemediation({
+        projectPath: args.projectPath,
+        browser,
+        profile: args.profile
+    });
     if ("profile-locked" === boot.verdict.kind) {
         const { owner, lockedAt } = boot.verdict;
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: dev_schema.name,
             status: "profile-locked",
@@ -3346,18 +4062,20 @@ async function dev_handler(args) {
             },
             value: {
                 ...session,
-                profileDir,
+                ...profileRootDir ? {
+                    profileRootDir
+                } : {},
                 owner,
                 ...lockedAt ? {
                     lockedAt
                 } : {},
                 output: cleanOutput.slice(0, 2000)
             },
-            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.`,
+            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, clear it by hand before retrying. ${profileAdvice}`,
             warnings: boot.warnings
         });
     }
-    if ("browser-exited" === boot.verdict.kind) return envelope({
+    if ("browser-exited" === boot.verdict.kind) return envelope_envelope({
         ok: false,
         command: dev_schema.name,
         status: "browser-exited",
@@ -3370,7 +4088,7 @@ async function dev_handler(args) {
             ...boot.verdict.stamp,
             output: cleanOutput.slice(0, 2000)
         },
-        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.`,
+        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, clear it by hand before retrying. ${profileAdvice}`,
         warnings: boot.warnings
     });
     const controlVerbs = "storage, reload, open, dom_snapshot";
@@ -3397,7 +4115,7 @@ async function dev_handler(args) {
         requestedPort: args.port ?? 8080
     };
     const portNote = null !== boundPort ? void 0 !== args.port && args.port !== boundPort ? `Requested port ${args.port} was not available; the dev server bound ${boundPort} (read from the engine's ready.json contract, the same source extension_wait reports).` : null : "The engine has not stamped its ready.json contract yet, so the bound port is not known at response time (a taken port makes the server bind the next free one). extension_wait reports the bound port from that contract once it lands; requestedPort above is only what was asked for.";
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: dev_schema.name,
         status: "started",
@@ -3473,6 +4191,7 @@ async function start_handler(args) {
     if (void 0 !== args.port) cliArgs.push("--port", String(args.port));
     if (args.noBrowser) cliArgs.push("--no-browser");
     cliArgs.push(...launchFlagArgs(args));
+    const stale = removeCarrier(args.projectPath);
     const spawnedAt = Date.now();
     const spawned = spawnExtensionCli(cliArgs, {
         projectDir: args.projectPath
@@ -3506,7 +4225,7 @@ async function start_handler(args) {
     };
     if ("exited" === boot.verdict.kind) {
         const { exitCode: code, signal } = boot.verdict;
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: start_schema.name,
             status: "exited",
@@ -3526,7 +4245,7 @@ async function start_handler(args) {
     }
     if ("compile-failed" === boot.verdict.kind) {
         const { compileErrors } = boot.verdict;
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: start_schema.name,
             status: "compile-failed",
@@ -3547,7 +4266,7 @@ async function start_handler(args) {
     }
     if ("browser-exited" === boot.verdict.kind || "profile-locked" === boot.verdict.kind) {
         const stamp = "browser-exited" === boot.verdict.kind ? boot.verdict.stamp : {};
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: start_schema.name,
             status: boot.verdict.kind,
@@ -3564,7 +4283,7 @@ async function start_handler(args) {
             warnings: boot.warnings
         });
     }
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: start_schema.name,
         status: building ? "started" : "launched",
@@ -3575,7 +4294,10 @@ async function start_handler(args) {
             logPath
         },
         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.",
-        warnings: boot.warnings
+        warnings: [
+            ...boot.warnings,
+            stale.removed && "Removed a Live Preview carrier left behind by an earlier dev session, so it was not loaded beside your extension here."
+        ]
     });
 }
 function toMcpSpeak(text) {
@@ -3685,8 +4407,19 @@ async function runActVerb(args, projectPath, timeoutMs, tool) {
         }
         if (frame && "object" == typeof frame) return JSON.stringify(wrapLegacyFrame(frame, command));
     } catch  {}
+    if (refusedTheOutputFlag(stderr ?? "")) return envelope_envelope({
+        ok: false,
+        command,
+        status: "engine-too-old",
+        error: {
+            code: "E_ENGINE_TOO_OLD",
+            name: "CliError",
+            message: await outputFlagRefusalMessage("act", args[0], projectPath)
+        },
+        hint: "extension_doctor reports the project's engine version next to the one this server pins."
+    });
     const message = stderr.trim() || `extension exited with code ${code}`;
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command,
         status: "cli-failed",
@@ -4140,7 +4873,7 @@ class CDPClient extends CDPConnection {
 async function resolveContractPort(projectPath, browser, field, options) {
     const waitMs = options?.waitMs ?? 20000;
     const graceMs = options?.graceMs ?? 2500;
-    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+    const readyPath = bridge_readyContractPath(projectPath, browser);
     const deadline = Date.now() + waitMs;
     let contractSeen = false;
     let contractSeenAt = null;
@@ -4209,6 +4942,10 @@ const ENGINE_COMPANION_IDS = new Set([
     CARRIER_EXTENSION_ID
 ]);
 const EXTENSION_URL = /^chrome-extension:\/\/([a-p]{32})\//i;
+function isEngineCompanionUrl(url) {
+    const match = EXTENSION_URL.exec(String(url ?? ""));
+    return match ? ENGINE_COMPANION_IDS.has(match[1].toLowerCase()) : false;
+}
 async function verifyGuestLoaded(projectPath, browser, options) {
     let cdpPort;
     try {
@@ -4339,7 +5076,7 @@ async function navigateToUrlViaBridge(projectPath, browser, url, timeout, tool =
         return raw;
     }
     const settled = await pollForBridgeTab(projectPath, browser, url, null != timeout ? Math.min(timeout, 6000) : 6000);
-    if (!settled) return envelope({
+    if (!settled) return envelope_envelope({
         ok: false,
         command: tool,
         status: "navigate-failed",
@@ -4350,7 +5087,7 @@ async function navigateToUrlViaBridge(projectPath, browser, url, timeout, tool =
         },
         hint: "Confirm the URL, or discover open tabs with extension_dom_snapshot listTabs: true. For an extension page, the path must match the BUILT manifest."
     });
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: tool,
         status: "navigated",
@@ -4422,7 +5159,7 @@ function isDisposableTab(tabUrl, destination) {
 async function navigateToUrl(projectPath, browser, url, timeout) {
     if (!isChromiumFamily(browser)) return navigateToUrlViaBridge(projectPath, browser, url, timeout);
     const resolved = await resolveCdpPort(projectPath, browser);
-    if (!resolved) return envelope({
+    if (!resolved) return envelope_envelope({
         ok: false,
         command: open_schema.name,
         status: "no-session",
@@ -4458,7 +5195,7 @@ async function navigateToUrl(projectPath, browser, url, timeout) {
         const settled = await pollForTarget(resolved.port, url, 6000, navigatedTargetId);
         if (!settled) {
             const isExtensionPage = url.startsWith("chrome-extension://");
-            return envelope({
+            return envelope_envelope({
                 ok: false,
                 command: open_schema.name,
                 status: "navigate-failed",
@@ -4470,7 +5207,7 @@ async function navigateToUrl(projectPath, browser, url, timeout) {
                 hint: isExtensionPage ? "Confirm the path exists in the built dist (extension_build / extension_analyze list entrypoints). For an extension page, the path must match the BUILT manifest, which may differ from your source layout." : "Confirm the URL loads in a normal browser and that the dev session's browser has network access. Nothing about your extension bundle is implicated in a failed http(s) navigation."
             });
         }
-        return envelope({
+        return envelope_envelope({
             ok: true,
             command: open_schema.name,
             status: "navigated",
@@ -4494,7 +5231,7 @@ async function navigateToUrl(projectPath, browser, url, timeout) {
             hint: "Inspect it with extension_dom_snapshot or extension_inspect using url (context: 'page'), they resolve the tab themselves. `target.targetId` is a CDP target id, NOT a chrome.tabs id: do not pass it as `tab`. If you need a numeric tab id, call extension_dom_snapshot with listTabs: true."
         });
     } catch (e) {
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: open_schema.name,
             status: "navigate-failed",
@@ -4569,7 +5306,7 @@ function declaredCommands(projectPath, browser) {
 }
 function readDistPath(projectPath, browser) {
     try {
-        const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+        const file = bridge_readyContractPath(projectPath, browser);
         const contract = JSON.parse(node_fs.readFileSync(file, "utf8"));
         return "string" == typeof contract?.distPath ? contract.distPath : null;
     } catch  {
@@ -4624,7 +5361,7 @@ function declaredSurfaces(projectPath, browser) {
 }
 function missingSurfaceError(projectPath, browser, surface, consequence) {
     const declared = declaredSurfaces(projectPath, browser);
-    if (null === declared) return envelope({
+    if (null === declared) return envelope_envelope({
         ok: false,
         command: open_schema.name,
         status: "no-manifest",
@@ -4638,7 +5375,7 @@ function missingSurfaceError(projectPath, browser, surface, consequence) {
     const key = SURFACE_MANIFEST_KEYS[surface] ?? surface;
     const others = declared.filter((s)=>s !== surface);
     const nextVerb = "popup" === surface ? 'To exercise the toolbar button of a popup-less extension, call extension_open with surface: "action", which replays chrome.action.onClicked. To give the extension a popup, set action.default_popup in the manifest and rebuild.' : `To add one, set ${key} in the manifest and rebuild.`;
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: open_schema.name,
         status: "no-surface",
@@ -4716,7 +5453,7 @@ async function openSurfaceAsTab(projectPath, browser, surface) {
     let extensionId = null;
     if (isChromiumFamily(browser)) {
         extensionId = await resolveExtensionId(projectPath, browser);
-        if (!extensionId) return envelope({
+        if (!extensionId) return envelope_envelope({
             ok: false,
             command: open_schema.name,
             status: "no-extension-id",
@@ -4730,7 +5467,7 @@ async function openSurfaceAsTab(projectPath, browser, surface) {
         url = `chrome-extension://${extensionId}/${doc}`;
     } else {
         const base = await resolveBridgeBaseUrl(projectPath, browser);
-        if (!base) return envelope({
+        if (!base) return envelope_envelope({
             ok: false,
             command: open_schema.name,
             status: "no-extension-id",
@@ -4793,7 +5530,7 @@ async function confirmSurfaceTarget(projectPath, browser, surface, raw) {
         });
         return actFrameJson(parsed);
     }
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: open_schema.name,
         status: "surface-did-not-open",
@@ -4867,7 +5604,7 @@ async function open_handler(args) {
         "bookmarks"
     ];
     if (args.asTab && args.surface && AS_TAB_SURFACES.includes(args.surface)) return openSurfaceAsTab(args.projectPath, browser, args.surface);
-    if (!args.surface) return envelope({
+    if (!args.surface) return envelope_envelope({
         ok: false,
         command: open_schema.name,
         status: "bad-request",
@@ -4879,7 +5616,7 @@ async function open_handler(args) {
     });
     if ("command" === args.surface) {
         const declared = declaredCommands(args.projectPath, browser);
-        if (declared && args.name && !declared.includes(args.name)) return envelope({
+        if (declared && args.name && !declared.includes(args.name)) return envelope_envelope({
             ok: false,
             command: open_schema.name,
             status: "unknown-command",
@@ -4916,7 +5653,7 @@ async function open_handler(args) {
         const parsed = JSON.parse(raw);
         const msg = String(parsed?.error?.message ?? "");
         const code = "string" == typeof parsed?.error?.code ? parsed.error.code : "";
-        const refusedWindow = "E_NO_TARGET" === code || /active browser window|no active|headless|user gesture/i.test(msg);
+        const refusedWindow = "E_TARGET_NOT_FOUND" === code || /active browser window|no active|headless|user gesture/i.test(msg);
         if (parsed?.ok === false && refusedWindow) {
             if (AS_TAB_SURFACES.includes(args.surface)) {
                 const fallback = await openSurfaceAsTab(args.projectPath, browser, args.surface);
@@ -4950,7 +5687,7 @@ async function publish(options = {}) {
         }
     };
     const doFetch = options.fetchImpl ?? fetch;
-    const apiCheck = safeApiBase(resolveApiBase(options.api));
+    const apiCheck = safeApiBase(resolveApiBase(options.api), options.api);
     if (!apiCheck.ok) return {
         ok: false,
         error: {
@@ -5003,15 +5740,207 @@ async function publish(options = {}) {
         data
     };
 }
+const ARTIFACT_ID = /^gen_(?:[0-9a-f]{32}|[0-9a-f]{64})$/;
+const ARTIFACT_ID_CANDIDATE = /gen_[0-9a-f]+/;
+function parseArtifactRef(input) {
+    const raw = String(input ?? "").trim();
+    if (!raw) return null;
+    if (ARTIFACT_ID.test(raw)) return raw;
+    let parsed = null;
+    try {
+        parsed = new URL(raw);
+    } catch  {
+        parsed = null;
+    }
+    if (parsed) {
+        const fromQuery = parsed.searchParams.get("preview");
+        if (fromQuery && ARTIFACT_ID.test(fromQuery.trim())) return fromQuery.trim();
+        const segments = parsed.pathname.split("/").filter(Boolean);
+        for(let i = segments.length - 1; i >= 0; i -= 1){
+            const raw = segments[i];
+            if (!raw) continue;
+            const segment = decodeURIComponent(raw);
+            if (ARTIFACT_ID.test(segment)) return segment;
+        }
+    }
+    const loose = ARTIFACT_ID_CANDIDATE.exec(raw);
+    return loose && ARTIFACT_ID.test(loose[0]) ? loose[0] : null;
+}
+function wwwRevokeUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    } catch  {
+        return value;
+    }
+    if ("extension.dev" !== parsed.hostname.toLowerCase()) return value;
+    parsed.hostname = "www.extension.dev";
+    return parsed.toString();
+}
+function authError(name) {
+    return {
+        ok: false,
+        error: {
+            name,
+            message: "No token. Run extension_auth (action: login), or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard)."
+        }
+    };
+}
+async function readBody(res) {
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    } catch  {
+        return {
+            message: text
+        };
+    }
+}
+async function listArtifacts(options = {}) {
+    const token = options.token ?? resolveToken();
+    if (!token) return authError("SharesAuthError");
+    const apiCheck = safeApiBase(resolveApiBase(options.api), options.api);
+    if (!apiCheck.ok) return {
+        ok: false,
+        error: {
+            name: "SharesConfigError",
+            message: apiCheck.message
+        }
+    };
+    const url = new URL(`${apiCheck.base}/api/artifacts`);
+    if (null != options.limit) url.searchParams.set("limit", String(options.limit));
+    if (options.liveOnly) url.searchParams.set("status", "live");
+    const doFetch = options.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await doFetch(url.toString(), {
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/json",
+                ...identityHeaders("extension_shares")
+            }
+        });
+    } catch (err) {
+        return {
+            ok: false,
+            error: {
+                name: "SharesNetworkError",
+                message: `Could not reach ${url.toString()}: ${err?.message || err}`
+            }
+        };
+    }
+    const data = await readBody(res);
+    if (401 === res.status) return authError("SharesAuthError");
+    if (!res.ok) return {
+        ok: false,
+        error: {
+            name: "SharesListError",
+            status: res.status,
+            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 ? {
+            ...artifact,
+            revokeUrl: wwwRevokeUrl(artifact.revokeUrl)
+        } : artifact) : [];
+    const num = (value, fallback)=>"number" == typeof value && Number.isFinite(value) ? value : fallback;
+    return {
+        ok: true,
+        data: {
+            artifacts,
+            count: num(data.count, artifacts.length),
+            matched: num(data.matched, artifacts.length),
+            limit: num(data.limit, artifacts.length),
+            truncated: true === data.truncated,
+            truncatedReported: "boolean" == typeof data.truncated,
+            scanned: num(data.scanned, 0)
+        }
+    };
+}
+async function revokeArtifact(options) {
+    const token = options.token ?? resolveToken();
+    if (!token) return authError("SharesAuthError");
+    const apiCheck = safeApiBase(resolveApiBase(options.api), options.api);
+    if (!apiCheck.ok) return {
+        ok: false,
+        error: {
+            name: "SharesConfigError",
+            message: apiCheck.message
+        }
+    };
+    const url = `${apiCheck.base}/api/artifacts/${encodeURIComponent(options.artifactId)}`;
+    const doFetch = options.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await doFetch(url, {
+            method: "DELETE",
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/json",
+                ...identityHeaders("extension_shares")
+            }
+        });
+    } catch (err) {
+        return {
+            ok: false,
+            error: {
+                name: "SharesNetworkError",
+                message: `Could not reach ${url}: ${err?.message || err}`
+            }
+        };
+    }
+    const data = await readBody(res);
+    if (401 === res.status) return authError("SharesAuthError");
+    if (404 === res.status) return {
+        ok: false,
+        error: {
+            name: "SharesNotFoundError",
+            status: 404,
+            message: `The platform has no live share ${options.artifactId} for this token. It may already be revoked, already expired, owned by a different project than the one this token is scoped to, or a teammate's personal share, which belongs to that person alone and no project token can revoke.`
+        }
+    };
+    if (!res.ok) return {
+        ok: false,
+        error: {
+            name: "SharesRevokeError",
+            status: res.status,
+            message: `Revoking ${options.artifactId} failed (${res.status}): ${data?.message || "unknown error"}`
+        }
+    };
+    return {
+        ok: true,
+        data: {
+            artifactId: options.artifactId,
+            revoked: true === data.revoked,
+            ..."string" == typeof data.revokedAt ? {
+                revokedAt: data.revokedAt
+            } : {}
+        }
+    };
+}
 const IGNORED_SEGMENTS = new Set([
     "node_modules",
     ".git",
     ".DS_Store",
     "__MACOSX"
 ]);
+const IGNORED_FILES = /^\.env(\..*)?$|\.(pem|key|p12|pfx|keystore)$/i;
 const TEXTUAL = /\.(json|js|mjs|cjs|ts|tsx|jsx|html|htm|css|svg|txt|md|map)$/i;
 const MAX_FILES = 2000;
 const MAX_CONTENT_CHARS = 67108864;
+function encodeFile(relativePath, bytes) {
+    if (TEXTUAL.test(relativePath)) {
+        const text = bytes.toString("utf8");
+        if (Buffer.from(text, "utf8").equals(bytes)) return {
+            content: text,
+            encoding: "utf8"
+        };
+    }
+    return {
+        content: bytes.toString("base64"),
+        encoding: "base64"
+    };
+}
 function collectDistFiles(distDir) {
     const files = [];
     const walk = (dir)=>{
@@ -5026,12 +5955,13 @@ function collectDistFiles(distDir) {
                 continue;
             }
             if (!entry.isFile()) continue;
+            if (IGNORED_FILES.test(entry.name)) continue;
             const relative = node_path.relative(distDir, absolute).split(node_path.sep).join("/");
             const bytes = node_fs.readFileSync(absolute);
-            const encoding = TEXTUAL.test(relative) ? "utf8" : "base64";
+            const { content, encoding } = encodeFile(relative, bytes);
             files.push({
                 path: relative,
-                content: bytes.toString(encoding),
+                content,
                 encoding
             });
         }
@@ -5048,7 +5978,7 @@ async function uploadPreview(options) {
             message: "No token. Run extension_auth (action: login), or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard)."
         }
     };
-    const apiCheck = safeApiBase(resolveApiBase(options.api));
+    const apiCheck = safeApiBase(resolveApiBase(options.api), options.api);
     if (!apiCheck.ok) return {
         ok: false,
         error: {
@@ -5083,13 +6013,17 @@ async function uploadPreview(options) {
         }
     };
     const totalChars = files.reduce((sum, file)=>sum + file.content.length, 0);
-    if (totalChars > MAX_CONTENT_CHARS) return {
-        ok: false,
-        error: {
-            name: "PreviewTooLargeError",
-            message: `${options.distDir} is too large to share (over ${Math.floor(MAX_CONTENT_CHARS / 1048576)}MB). Build without source maps, or trim the bundled assets.`
-        }
-    };
+    if (totalChars > MAX_CONTENT_CHARS) {
+        const encodedBytes = files.reduce((sum, file)=>sum + Buffer.byteLength(file.content, file.encoding), 0);
+        const mb = (value)=>(value / 1048576).toFixed(1);
+        return {
+            ok: false,
+            error: {
+                name: "PreviewTooLargeError",
+                message: `${options.distDir} is too large to share: ${mb(encodedBytes)}MB of files. A shared preview holds about ${mb(MAX_CONTENT_CHARS)}MB of text, and roughly ${mb(3 * MAX_CONTENT_CHARS / 4)}MB when the build is mostly images, fonts or wasm, which travel base64-encoded. Trim the bundled assets, or build without source maps if yours are large.`
+            }
+        };
+    }
     const name = "string" == typeof options.manifest.name && options.manifest.name.trim() ? options.manifest.name : node_path.basename(options.distDir);
     const version = "string" == typeof options.manifest.version ? options.manifest.version : void 0;
     const doFetch = options.fetchImpl ?? fetch;
@@ -5100,6 +6034,7 @@ async function uploadPreview(options) {
             headers: {
                 authorization: `Bearer ${token}`,
                 "content-type": "application/json",
+                "x-extensiondev-origin": "mcp",
                 ...identityHeaders("extension_preview_web")
             },
             body: JSON.stringify({
@@ -5153,14 +6088,14 @@ async function uploadPreview(options) {
             artifactId,
             previewUrl,
             zipUrl: "string" == typeof data.zipUrl ? data.zipUrl : void 0,
-            revokeUrl: "string" == typeof data.revokeUrl ? data.revokeUrl : void 0,
+            revokeUrl: "string" == typeof data.revokeUrl ? wwwRevokeUrl(data.revokeUrl) : void 0,
             expiresAt: "string" == typeof data.expiresAt ? data.expiresAt : void 0
         }
     };
 }
 const SHARE_STATE_DIR = ".extension.dev";
 const SHARE_RECORD_FILE = "shared-previews.json";
-const FILE_NOTE = "Every preview link shared from this project. revokeUrl is the only handle that kills a link before expiresAt, and the platform mints a new id on every share, so a lost revokeUrl cannot be recovered. Safe to delete once every link below has expired.";
+const FILE_NOTE = "Every preview link shared from this project. revokeUrl is the handle that kills a link before expiresAt. Losing it is recoverable: run extension_shares to list every share this token owns, each with its revokeUrl. Re-sharing an unchanged build returns the same link rather than a new one, and only a revoked link is replaced. Safe to delete once every link below has expired.";
 const IGNORE_COMMENT = "# Extension.dev local state: revoke handles for shared previews, not part of your extension.";
 function sharedPreviewsPath(projectPath) {
     return node_path.join(projectPath, SHARE_STATE_DIR, SHARE_RECORD_FILE);
@@ -5233,7 +6168,7 @@ function recordSharedPreview(projectPath, entry) {
         return {
             recorded: false,
             path: file,
-            note: `Could not write the share record to ${file}: ${error instanceof Error ? error.message : String(error)}. The revokeUrl in this response is then the only copy, so keep it: re-sharing mints a new link and leaves this one live until expiresAt.`
+            note: `Could not write the share record to ${file}: ${error instanceof Error ? error.message : String(error)}. Keep the revokeUrl in this response, or run extension_shares later to list every share this token owns with its revokeUrl.`
         };
     }
     const ignore = ensureProjectIgnored(projectPath, {
@@ -5259,8 +6194,117 @@ function recordSharedPreview(projectPath, entry) {
         } : {}
     };
 }
+const MAX_HOPS = 4;
+function allows(allowOrigin, origin) {
+    if (!allowOrigin) return false;
+    const value = allowOrigin.trim();
+    return "*" === value || value.toLowerCase() === origin.toLowerCase();
+}
+async function probeShareCors(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const origin = options.origin;
+    let url = options.zipUrl;
+    let redirects = 0;
+    const verdict = (extra)=>({
+            checkedUrl: options.zipUrl,
+            origin,
+            finalUrl: url,
+            finalStatus: 0,
+            redirects,
+            allowOrigin: null,
+            ...extra
+        });
+    for(let hop = 0; hop < MAX_HOPS; hop++){
+        const controller = new AbortController();
+        let res;
+        try {
+            res = await doFetch(url, {
+                method: "GET",
+                redirect: "manual",
+                signal: controller.signal,
+                headers: {
+                    origin,
+                    "sec-fetch-mode": "cors"
+                }
+            });
+        } catch (err) {
+            return verdict({
+                ok: false,
+                reason: `Could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`
+            });
+        }
+        try {
+            await res.body?.cancel();
+        } catch  {
+            controller.abort();
+        }
+        const status = res.status;
+        const allowOrigin = res.headers.get("access-control-allow-origin");
+        if (status >= 300 && status < 400) {
+            const location = res.headers.get("location");
+            if (!location) return verdict({
+                ok: false,
+                finalStatus: status,
+                allowOrigin,
+                reason: `${url} answered ${status} with no Location, so the download goes nowhere.`
+            });
+            url = new URL(location, url).toString();
+            redirects += 1;
+            continue;
+        }
+        if (status >= 400) return verdict({
+            ok: false,
+            finalStatus: status,
+            allowOrigin,
+            reason: `The build's zip answered ${status}, so the link has nothing to render.`
+        });
+        if (!allows(allowOrigin, origin)) return verdict({
+            ok: false,
+            finalStatus: status,
+            allowOrigin,
+            reason: `${url} answered ${status} but with ` + (allowOrigin ? `access-control-allow-origin: ${allowOrigin}, which does not cover ${origin}` : "no access-control-allow-origin header") + `. A browser at ${origin} will refuse to read it, so the link opens to an error even though this fetch succeeded.` + (redirects > 0 ? " The header has to be on this response, not on the redirect that led here." : "")
+        });
+        return verdict({
+            ok: true,
+            finalStatus: status,
+            allowOrigin,
+            reason: `A browser at ${origin} can read the build's zip: the final response after ${redirects} redirect(s) answered ${status} with access-control-allow-origin: ${allowOrigin}.`
+        });
+    }
+    return verdict({
+        ok: false,
+        reason: `The build's zip redirected more than ${MAX_HOPS} times, so nothing could be read from it.`
+    });
+}
 const preview_web_COMMAND = "extension_preview_web";
 const DEFAULT_PREVIEW_DEV_URL = "http://localhost:3110";
+const LOCAL_HOSTS = new Set([
+    "localhost",
+    "127.0.0.1",
+    "[::1]",
+    "::1"
+]);
+function safeHostBase(raw) {
+    const trimmed = String(raw || "").replace(/\/+$/, "");
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    } catch  {
+        return {
+            ok: false,
+            message: `hostUrl is not a URL: ${raw}. Leave it unset to use ${DEFAULT_PREVIEW_DEV_URL}.`
+        };
+    }
+    const isLocal = LOCAL_HOSTS.has(parsed.hostname) || parsed.hostname.endsWith(".localhost") || "preview.extension.dev" === parsed.hostname;
+    if (!isLocal) return {
+        ok: false,
+        message: `Refusing to use ${raw} as the preview host: hostUrl may only name a local preview dev server. Leave it unset to use ${DEFAULT_PREVIEW_DEV_URL}, or pass share:true for a link that needs no local server.`
+    };
+    return {
+        ok: true,
+        base: trimmed
+    };
+}
 const SURFACE = {
     defaultOrigin: DEFAULT_PREVIEW_DEV_URL,
     scheme: (encoded)=>`preview://build/${encoded}`,
@@ -5268,7 +6312,58 @@ const SURFACE = {
     devCommand: "pnpm --filter preview.extension.dev dev",
     label: "preview.extension.dev"
 };
-async function buildShare(projectPath, distDir, manifest, browser) {
+const PREVIEW_APP_LOCATIONS = [
+    [
+        "apps",
+        "web",
+        "preview.extension.dev"
+    ],
+    [
+        "apps",
+        "preview.extension.dev"
+    ],
+    [
+        "preview.extension.dev"
+    ]
+];
+function previewDevCheckout(startPaths) {
+    const seen = new Set();
+    for (const start of startPaths){
+        let dir;
+        try {
+            dir = node_path.resolve(start);
+        } catch  {
+            continue;
+        }
+        for(let depth = 0; depth < 8; depth++){
+            if (seen.has(dir)) break;
+            seen.add(dir);
+            for (const location of PREVIEW_APP_LOCATIONS){
+                const manifest = node_path.join(dir, ...location, "package.json");
+                try {
+                    const parsed = JSON.parse(node_fs.readFileSync(manifest, "utf8"));
+                    if (parsed.name === SURFACE.label) return dir;
+                } catch  {}
+            }
+            const parent = node_path.dirname(dir);
+            if (parent === dir) break;
+            dir = parent;
+        }
+    }
+    return null;
+}
+function localLaneRemedy(checkout) {
+    const shareOut = "Pass share:true for a link that needs no local server and opens for anyone.";
+    return checkout ? `Start it with '${SURFACE.devCommand}' in ${checkout}. ${shareOut}` : `${SURFACE.label} is a private app of the extension.dev monorepo and no npm install of this server can start it, so the default lane cannot resolve on this machine. ${shareOut}`;
+}
+function previewOriginOf(previewUrl) {
+    try {
+        return new URL(previewUrl).origin;
+    } catch  {
+        return null;
+    }
+}
+async function buildShare(projectPath, distDir, manifest, browser, verifyInBrowserTerms) {
     const result = await uploadPreview({
         distDir,
         manifest,
@@ -5287,6 +6382,11 @@ async function buildShare(projectPath, distDir, manifest, browser) {
             } : {}
         };
     }
+    const origin = previewOriginOf(result.data.previewUrl);
+    const browserCheck = verifyInBrowserTerms && result.data.zipUrl && origin ? await probeShareCors({
+        zipUrl: result.data.zipUrl,
+        origin
+    }) : null;
     const sharedAt = new Date().toISOString();
     const record = recordSharedPreview(projectPath, {
         sharedAt,
@@ -5327,8 +6427,14 @@ async function buildShare(projectPath, distDir, manifest, browser) {
         } : {},
         serves: "uploaded-local-build",
         localBuildUploaded: true,
+        ...browserCheck ? {
+            browserLoadable: browserCheck.ok,
+            browserCheck
+        } : {
+            browserLoadable: null
+        },
         record,
-        note: "Anyone with this link can open the build you just made, running in the emulator. No install, no sign-in, no dev server. They can also download the whole build as a zip from zipUrl, so the link hands over the built code. It stays live until expiresAt; DELETE revokeUrl with the same token to kill it sooner, and a revoked link stays dead. revokeUrl is the only handle that pulls this link early and re-sharing mints a different one, so " + (record.recorded ? `it was also written to ${record.path} (record.path), which lists every share from this project.` : `keep it: ${record.note}`) + " To find this link again later, or to pull it back once it has left this conversation, run extension_shares: it lists every link this token has shared with its live or dead state, and revokes one by artifactId or by pasting any of its URLs." + (record.warning ? ` ${record.warning}` : "")
+        note: "Anyone with this link can open the build you just made, running in the emulator. No install, no sign-in, no dev server. They can also download the whole build as a zip from zipUrl, so the link hands over the built code. It stays live until expiresAt; DELETE revokeUrl with the same token to kill it sooner, and a revoked link stays dead. revokeUrl is the handle that pulls this link early. Re-sharing an unchanged build returns this same link rather than a second one, and only a revoked link is replaced by a different one, so " + (record.recorded ? `it was also written to ${record.path} (record.path), which lists every share from this project.` : `keep it: ${record.note}`) + " To find this link again later, or to pull it back once it has left this conversation, run extension_shares: it lists every link this token has shared with its live or dead state, and revokes one by artifactId or by pasting any of its URLs." + (record.warning ? ` ${record.warning}` : "")
     };
 }
 function detectSurfaces(manifest) {
@@ -5351,7 +6457,7 @@ function detectSurfaces(manifest) {
 }
 const preview_web_schema = {
     name: "extension_preview_web",
-    description: "Preview an in-progress extension in the web emulator, with no real browser. This builds the project (unless build:false), points preview.extension.dev at dist/<browser> over the dev-only preview://build scheme, and returns a deep link plus a loadability check. Use it as the author's door for a local build: it renders your build and carries the Emulated/Real lane toggle and the Trace tab, but the deep link resolves only on this machine. Pass share:true to get a public link that reaches anyone. Call extension_shares to list and revoke every link shared this way, so one never vanishes with this response.",
+    description: "Preview an in-progress extension in the web emulator, with no real browser. This builds the project (unless build:false) and previews dist/<browser>. Pass share:true unless you are working inside the extension.dev monorepo: it uploads the build and returns a link anyone can open, with no install, sign-in or dev server, and it is the only lane that works from an npm install of this server. Sharing also serves the build as a zip, so it hands over the built code; read the share property before using it. The default lane instead returns a deep link over the dev-only preview://build scheme, which resolves only against a preview.extension.dev dev server on this machine, so it is for people developing extension.dev itself. Call extension_shares to list and revoke every link shared this way, so one never vanishes with this response.",
     inputSchema: {
         type: "object",
         properties: {
@@ -5378,7 +6484,7 @@ const preview_web_schema = {
             probe: {
                 type: "boolean",
                 default: true,
-                description: "Fetch the surface's dev middleware first to confirm the artifact loads."
+                description: "Fetch the surface's dev middleware first to confirm the artifact loads on the local host. With share:true it also checks the shared link the way a browser would, following the zip's redirects and asserting the final response allows the preview origin, and reports that as share.browserLoadable."
             },
             open: {
                 type: "boolean",
@@ -5393,7 +6499,7 @@ const preview_web_schema = {
             share: {
                 type: "boolean",
                 default: false,
-                description: "Upload the built dist and return a public link (share.previewUrl) that renders those exact bytes for anyone: no install, sign-in or dev server. It also serves the build as a zip (share.zipUrl), so sharing hands over the code. Needs a token scoped to an extension.dev project (extension_auth or EXTENSION_DEV_TOKEN); without one you get a login hint and the local preview still succeeds. Live until share.expiresAt; DELETE share.revokeUrl to kill it sooner. Revocation is permanent and re-sharing mints a different link, so each share is also appended to the project's gitignored .extension.dev/shared-previews.json."
+                description: "Upload the built dist and return a public link (share.previewUrl) that renders those exact bytes for anyone: no install, sign-in or dev server. It also serves the build as a zip (share.zipUrl), so sharing hands over the code. Needs a token scoped to an extension.dev project (extension_auth or EXTENSION_DEV_TOKEN); without one you get a login hint and the local preview still succeeds. Live until share.expiresAt; DELETE share.revokeUrl to kill it sooner. Revocation is permanent, and re-sharing an unchanged build returns the same link unless it was revoked, so each share is also appended to the project's gitignored .extension.dev/shared-previews.json."
             }
         },
         required: [
@@ -5403,7 +6509,21 @@ const preview_web_schema = {
 };
 async function preview_web_handler(args) {
     const browser = args.browser ?? "chrome";
-    const hostBase = (args.hostUrl ?? SURFACE.defaultOrigin).replace(/\/+$/, "");
+    const host = safeHostBase(args.hostUrl ?? SURFACE.defaultOrigin);
+    if (!host.ok) return envelope_envelope({
+        ok: false,
+        command: preview_web_COMMAND,
+        status: "bad-host-url",
+        error: {
+            code: "E_BAD_HOST_URL",
+            message: host.message
+        },
+        value: {
+            stage: "resolve-host",
+            hostUrl: args.hostUrl
+        }
+    });
+    const hostBase = host.base;
     const shouldBuild = args.distPath ? false : false !== args.build;
     let buildResult = null;
     if (shouldBuild) {
@@ -5419,7 +6539,7 @@ async function preview_web_handler(args) {
                 raw
             };
         }
-        if (!buildResult || true !== buildResult.ok) return envelope({
+        if (!buildResult || true !== buildResult.ok) return envelope_envelope({
             ok: false,
             command: preview_web_COMMAND,
             status: "build-failed",
@@ -5435,7 +6555,7 @@ async function preview_web_handler(args) {
     }
     const distDir = args.distPath ? node_path.resolve(args.distPath) : node_path.resolve(args.projectPath, "dist", browser);
     const manifestPath = node_path.join(distDir, "manifest.json");
-    if (!node_fs.existsSync(manifestPath)) return envelope({
+    if (!node_fs.existsSync(manifestPath)) return envelope_envelope({
         ok: false,
         command: preview_web_COMMAND,
         status: "no-dist",
@@ -5452,7 +6572,7 @@ async function preview_web_handler(args) {
     try {
         manifest = JSON.parse(node_fs.readFileSync(manifestPath, "utf8"));
     } catch (err) {
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: preview_web_COMMAND,
             status: "bad-dist-manifest",
@@ -5484,7 +6604,12 @@ async function preview_web_handler(args) {
             built: false
         }
     };
-    const hint = `Open deepLink in a browser to see the extension render in ${SURFACE.label}'s emulator. It must be running (${SURFACE.devCommand}). Once it renders, the Trace tab shows every chrome.* call it makes, and the lane toggle switches between the emulated backend and a real carrier-equipped browser.`;
+    const checkout = previewDevCheckout([
+        args.projectPath,
+        process.cwd()
+    ]);
+    const remedy = localLaneRemedy(checkout);
+    const hint = `Open deepLink in a browser to see the extension render in ${SURFACE.label}'s emulator, where the Trace tab shows every chrome.* call it makes and the lane toggle switches between the emulated backend and a real carrier-equipped browser. It needs that surface's dev server running on this machine. ${remedy}`;
     const previewWarnings = [];
     if (args.open) {
         const sessionBrowser = args.openIn ?? browser;
@@ -5494,250 +6619,122 @@ async function preview_web_handler(args) {
             opened = JSON.parse(navRaw);
         } catch  {
             opened = {
-                ok: false,
-                raw: navRaw
-            };
-        }
-        result.opened = opened;
-        result.openedIn = sessionBrowser;
-        if (true !== opened.ok) previewWarnings.push("Could not open the preview in a browser. This needs a live dev session (run extension_dev, then extension_wait for ready). The deepLink above still works if you open it yourself.");
-    }
-    if (args.share) result.share = await buildShare(args.projectPath, distDir, manifest, browser);
-    if (false === args.probe) return envelope({
-        ok: true,
-        command: preview_web_COMMAND,
-        status: "previewed",
-        value: result,
-        hint,
-        warnings: previewWarnings
-    });
-    const probeUrl = `${hostBase}${SURFACE.fetchPath}?url=${encodeURIComponent(internalUrl)}`;
-    try {
-        const res = await fetch(probeUrl, {
-            headers: {
-                accept: "application/json"
-            }
-        });
-        const contentType = res.headers.get("content-type") ?? "";
-        if (!res.ok || !contentType.includes("application/json")) return envelope({
-            ok: true,
-            command: preview_web_COMMAND,
-            status: "host-not-serving-preview",
-            value: {
-                ...result,
-                hostReachable: true,
-                previewLoadable: false,
-                probe: {
-                    status: res.status,
-                    contentType
-                }
-            },
-            hint,
-            warnings: [
-                ...previewWarnings,
-                `${SURFACE.label} answered but not with a preview payload. On the deployed host ${SURFACE.fetchPath} does not exist (dev-only); run a local dev server (${SURFACE.devCommand}) to use web preview.`
-            ]
-        });
-        const payload = await res.json();
-        return envelope({
-            ok: true,
-            command: preview_web_COMMAND,
-            status: "previewed",
-            value: {
-                ...result,
-                hostReachable: true,
-                previewLoadable: true,
-                probe: {
-                    identifier: payload.identifier,
-                    loadedName: payload.manifest?.name,
-                    loadedVersion: payload.version,
-                    fileCount: Array.isArray(payload.files) ? payload.files.length : 0
-                }
-            },
-            hint,
-            warnings: previewWarnings
-        });
-    } catch (err) {
-        return envelope({
-            ok: true,
-            command: preview_web_COMMAND,
-            status: "host-unreachable",
-            value: {
-                ...result,
-                hostReachable: false,
-                previewLoadable: false,
-                probe: {
-                    error: err instanceof Error ? err.message : String(err)
-                }
-            },
-            hint,
-            warnings: [
-                ...previewWarnings,
-                `Could not reach ${SURFACE.label} at ${hostBase}. Start it with '${SURFACE.devCommand}', then open deepLink.`
-            ]
-        });
-    }
-}
-const ARTIFACT_ID = /^gen_[0-9a-f]{32}$/;
-const ARTIFACT_ID_ANYWHERE = /gen_[0-9a-f]{32}/;
-function parseArtifactRef(input) {
-    const raw = String(input ?? "").trim();
-    if (!raw) return null;
-    if (ARTIFACT_ID.test(raw)) return raw;
-    let parsed = null;
-    try {
-        parsed = new URL(raw);
-    } catch  {
-        parsed = null;
-    }
-    if (parsed) {
-        const fromQuery = parsed.searchParams.get("preview");
-        if (fromQuery && ARTIFACT_ID.test(fromQuery.trim())) return fromQuery.trim();
-        const segments = parsed.pathname.split("/").filter(Boolean);
-        for(let i = segments.length - 1; i >= 0; i -= 1){
-            const segment = decodeURIComponent(segments[i]);
-            if (ARTIFACT_ID.test(segment)) return segment;
-        }
-    }
-    const loose = ARTIFACT_ID_ANYWHERE.exec(raw);
-    return loose ? loose[0] : null;
-}
-function authError(name) {
-    return {
-        ok: false,
-        error: {
-            name,
-            message: "No token. Run extension_auth (action: login), or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard)."
-        }
-    };
-}
-async function readBody(res) {
-    const text = await res.text();
-    try {
-        return JSON.parse(text);
-    } catch  {
-        return {
-            message: text
-        };
-    }
-}
-async function listArtifacts(options = {}) {
-    const token = options.token ?? resolveToken();
-    if (!token) return authError("SharesAuthError");
-    const apiCheck = safeApiBase(resolveApiBase(options.api));
-    if (!apiCheck.ok) return {
-        ok: false,
-        error: {
-            name: "SharesConfigError",
-            message: apiCheck.message
-        }
-    };
-    const url = new URL(`${apiCheck.base}/api/artifacts`);
-    if (null != options.limit) url.searchParams.set("limit", String(options.limit));
-    if (options.liveOnly) url.searchParams.set("status", "live");
-    const doFetch = options.fetchImpl ?? fetch;
-    let res;
-    try {
-        res = await doFetch(url.toString(), {
-            headers: {
-                authorization: `Bearer ${token}`,
-                accept: "application/json",
-                ...identityHeaders("extension_shares")
-            }
-        });
-    } catch (err) {
-        return {
-            ok: false,
-            error: {
-                name: "SharesNetworkError",
-                message: `Could not reach ${url.toString()}: ${err?.message || err}`
-            }
-        };
-    }
-    const data = await readBody(res);
-    if (401 === res.status) return authError("SharesAuthError");
-    if (!res.ok) return {
-        ok: false,
-        error: {
-            name: "SharesListError",
-            status: res.status,
-            message: `Listing shares failed (${res.status}): ${data?.message || "unknown error"}`
-        }
-    };
-    const artifacts = Array.isArray(data.artifacts) ? data.artifacts : [];
-    const num = (value, fallback)=>"number" == typeof value && Number.isFinite(value) ? value : fallback;
-    return {
-        ok: true,
-        data: {
-            artifacts,
-            count: num(data.count, artifacts.length),
-            matched: num(data.matched, artifacts.length),
-            limit: num(data.limit, artifacts.length),
-            truncated: true === data.truncated,
-            scanned: num(data.scanned, 0)
-        }
-    };
-}
-async function revokeArtifact(options) {
-    const token = options.token ?? resolveToken();
-    if (!token) return authError("SharesAuthError");
-    const apiCheck = safeApiBase(resolveApiBase(options.api));
-    if (!apiCheck.ok) return {
-        ok: false,
-        error: {
-            name: "SharesConfigError",
-            message: apiCheck.message
+                ok: false,
+                raw: navRaw
+            };
         }
-    };
-    const url = `${apiCheck.base}/api/artifacts/${encodeURIComponent(options.artifactId)}`;
-    const doFetch = options.fetchImpl ?? fetch;
-    let res;
+        result.opened = opened;
+        result.openedIn = sessionBrowser;
+        if (true !== opened.ok) previewWarnings.push("Could not open the preview in a browser. This needs a live dev session (run extension_dev, then extension_wait for ready). The deepLink above still works if you open it yourself.");
+    }
+    if (args.share) {
+        const share = await buildShare(args.projectPath, distDir, manifest, browser, false !== args.probe);
+        result.share = share;
+        if (true === share.ok && false === share.browserLoadable) {
+            const check = share.browserCheck;
+            previewWarnings.push(`The link uploaded, but it will not render for anyone: ${check?.reason ?? "its zip is not readable from the preview origin."} Do not hand this link out as working until that is fixed.`);
+        }
+    }
+    if (false === args.probe) return envelope_envelope({
+        ok: true,
+        command: preview_web_COMMAND,
+        status: "previewed",
+        value: result,
+        hint,
+        warnings: previewWarnings
+    });
+    const probeUrl = `${hostBase}${SURFACE.fetchPath}?url=${encodeURIComponent(internalUrl)}`;
     try {
-        res = await doFetch(url, {
-            method: "DELETE",
+        const res = await fetch(probeUrl, {
             headers: {
-                authorization: `Bearer ${token}`,
-                accept: "application/json",
-                ...identityHeaders("extension_shares")
+                accept: "application/json"
             }
         });
+        const contentType = res.headers.get("content-type") ?? "";
+        if (!res.ok || !contentType.includes("application/json")) return envelope_envelope({
+            ok: true,
+            command: preview_web_COMMAND,
+            status: "host-not-serving-preview",
+            value: {
+                ...result,
+                hostReachable: true,
+                previewLoadable: false,
+                probe: {
+                    status: res.status,
+                    contentType
+                }
+            },
+            hint,
+            warnings: [
+                ...previewWarnings,
+                `${SURFACE.label} answered but not with a preview payload. On the deployed host ${SURFACE.fetchPath} does not exist, because it is dev-only. ${remedy}`
+            ]
+        });
+        const payload = await res.json();
+        return envelope_envelope({
+            ok: true,
+            command: preview_web_COMMAND,
+            status: "previewed",
+            value: {
+                ...result,
+                hostReachable: true,
+                previewLoadable: true,
+                previewLoadableLane: "local-dev-host",
+                probe: {
+                    identifier: payload.identifier,
+                    loadedName: payload.manifest?.name,
+                    loadedVersion: payload.version,
+                    fileCount: Array.isArray(payload.files) ? payload.files.length : 0,
+                    method: "server-fetch",
+                    provesBrowserLoad: false
+                }
+            },
+            hint,
+            warnings: previewWarnings
+        });
     } catch (err) {
-        return {
+        const shared = result.share;
+        if (args.share && shared?.ok === true) return envelope_envelope({
+            ok: true,
+            command: preview_web_COMMAND,
+            status: "shared",
+            value: {
+                ...result,
+                hostReachable: false,
+                previewLoadable: false,
+                probe: {
+                    error: err instanceof Error ? err.message : String(err)
+                }
+            },
+            hint: "share.previewUrl is live and needs no local server. The deepLink lane is separate: it only resolves against a preview.extension.dev dev server on this machine, and none answered.",
+            warnings: [
+                ...previewWarnings,
+                `The share link works; only the local ${SURFACE.label} dev lane at ${hostBase} is unreachable, which is expected outside the extension.dev monorepo.`
+            ]
+        });
+        return envelope_envelope({
             ok: false,
+            command: preview_web_COMMAND,
+            status: "host-unreachable",
             error: {
-                name: "SharesNetworkError",
-                message: `Could not reach ${url}: ${err?.message || err}`
-            }
-        };
+                code: "E_PREVIEW_HOST_UNREACHABLE",
+                message: `Nothing is serving ${SURFACE.label} at ${hostBase}, so deepLink has nothing to open. ${remedy}`
+            },
+            value: {
+                ...result,
+                hostReachable: false,
+                previewLoadable: false,
+                probe: {
+                    error: err instanceof Error ? err.message : String(err)
+                }
+            },
+            hint,
+            warnings: [
+                ...previewWarnings,
+                `Could not reach ${SURFACE.label} at ${hostBase}. ${remedy}`
+            ]
+        });
     }
-    const data = await readBody(res);
-    if (401 === res.status) return authError("SharesAuthError");
-    if (404 === res.status) return {
-        ok: false,
-        error: {
-            name: "SharesNotFoundError",
-            status: 404,
-            message: `The platform has no live share ${options.artifactId} for this token. It may already be revoked, already expired, owned by a different project than the one this token is scoped to, or a teammate's personal share, which belongs to that person alone and no project token can revoke.`
-        }
-    };
-    if (!res.ok) return {
-        ok: false,
-        error: {
-            name: "SharesRevokeError",
-            status: res.status,
-            message: `Revoking ${options.artifactId} failed (${res.status}): ${data?.message || "unknown error"}`
-        }
-    };
-    return {
-        ok: true,
-        data: {
-            artifactId: options.artifactId,
-            revoked: true === data.revoked,
-            ..."string" == typeof data.revokedAt ? {
-                revokedAt: data.revokedAt
-            } : {}
-        }
-    };
 }
 const LOGIN_HINT = "Run extension_auth (action: login), or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard).";
 const shares_schema = {
@@ -5839,8 +6836,9 @@ function localIndex(entries) {
     }
     return index;
 }
-function localOnlyStatus(entry, truncated, liveFiltered, now) {
-    if (truncated) return "unknown: the platform list was cut short, so this share may simply be past the returned window.";
+function localOnlyStatus(entry, completeness, liveFiltered, now) {
+    if ("cut" === completeness) return "unknown: the platform list was cut short, so this share may simply be past the returned window.";
+    if ("unsaid" === completeness) return "unknown: the platform did not say whether that list was whole, so this share may simply be past the returned window.";
     const expiresAt = entry.expiresAt ? Date.parse(entry.expiresAt) : NaN;
     if (Number.isFinite(expiresAt) && expiresAt <= now) return "expired: its own expiresAt has passed, and the platform no longer lists it.";
     if (liveFiltered) return 'not in this live-only listing: the platform was asked for live shares only, so this one may be expired or revoked rather than not owned. Rerun with status:"all" to tell.';
@@ -5871,7 +6869,7 @@ async function listShares(args) {
     });
     if (!listing.ok) {
         const isAuth = "SharesAuthError" === listing.error.name;
-        return envelope({
+        return envelope_envelope({
             ok: true,
             command: "extension_shares",
             status: "listed-local-only",
@@ -5887,7 +6885,10 @@ async function listShares(args) {
                 },
                 shares: [],
                 localOnly: (local?.entries ?? []).map((entry)=>({
-                        ...entry
+                        ...entry,
+                        ...entry.revokeUrl ? {
+                            revokeUrl: wwwRevokeUrl(entry.revokeUrl)
+                        } : {}
                     })),
                 localRecord
             },
@@ -5921,9 +6922,13 @@ async function listShares(args) {
             } : {}
         };
     });
+    const completeness = listing.data.truncatedReported ? listing.data.truncated ? "cut" : "whole" : "unsaid";
     const localOnly = (local?.entries ?? []).filter((entry)=>!seen.has(entry.artifactId)).map((entry)=>({
             ...entry,
-            status: localOnlyStatus(entry, listing.data.truncated, liveFiltered, now)
+            ...entry.revokeUrl ? {
+                revokeUrl: wwwRevokeUrl(entry.revokeUrl)
+            } : {},
+            status: localOnlyStatus(entry, completeness, liveFiltered, now)
         }));
     const liveCount = shares.filter((share)=>share.live).length;
     const ownership = {
@@ -5931,8 +6936,8 @@ async function listShares(args) {
         personal: shares.filter((s)=>"personal" === s.attribution.ownership).length,
         unknown: shares.filter((s)=>"unknown" === s.attribution.ownership).length
     };
-    const truncatedNote = listing.data.truncated ? `This is not the whole set: ${listing.data.count} of ${listing.data.matched} matched shares came back at limit ${listing.data.limit}. truncated also goes true when the server spent its budget working out which shares you are entitled to see, so matched is a floor and not a total. Raise limit (max 200) or pass status:"live" to narrow it, and do not read a missing share as revoked.` : null;
-    return envelope({
+    const truncatedNote = "cut" === completeness ? `This is not the whole set: ${listing.data.count} of ${listing.data.matched} matched shares came back at limit ${listing.data.limit}. truncated also goes true when the server spent its budget working out which shares you are entitled to see, so matched is a floor and not a total. Raise limit (max 200) or pass status:"live" to narrow it, and do not read a missing share as revoked.` : "unsaid" === completeness ? `This listing cannot be called whole: the platform returned no truncated field, so whether ${listing.data.count} shares are all of them is unstated. A share missing from it is unaccounted for rather than dead, and no missing share is reported as revoked or unowned here.` : null;
+    return envelope_envelope({
         ok: true,
         command: "extension_shares",
         status: "listed",
@@ -5944,6 +6949,7 @@ async function listShares(args) {
                 matched: listing.data.matched,
                 limit: listing.data.limit,
                 truncated: listing.data.truncated,
+                truncatedReported: listing.data.truncatedReported,
                 scanned: listing.data.scanned,
                 ownership,
                 ...truncatedNote ? {
@@ -5958,25 +6964,29 @@ async function listShares(args) {
         },
         hint: `${liveCount} of ${shares.length} listed shares still resolve${local ? `; ${localOnly.length} local record ${1 === localOnly.length ? "entry is" : "entries are"} ${liveFiltered ? 'not in this live-only listing (possibly dead rather than not owned; rerun with status:"all" to tell)' : "without an artifact behind them"}` : ""}. Revoke one with action:"revoke" and its artifactId or any of its URLs.`,
         warnings: [
-            "previewUrl and zipUrl are null for a share that is no longer live, because a revoked or expired link cannot resolve for anyone. revokeUrl stays on every row. Revocation is permanent: a revoked id is burned and re-sharing the same build mints a different link.",
+            "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.",
             truncatedNote
         ]
     });
 }
 async function revokeShare(args) {
-    const ref = parseArtifactRef(args.artifactId || args.url || "");
-    if (!ref) return envelope({
+    const supplied = String(args.artifactId || args.url || "").trim();
+    const ref = parseArtifactRef(supplied);
+    if (!ref) return envelope_envelope({
         ok: false,
         command: "extension_shares",
         status: "bad-request",
         value: {
-            action: "revoke"
+            action: "revoke",
+            ...supplied ? {
+                ref: supplied
+            } : {}
         },
         error: {
             code: "E_BAD_REQUEST",
             name: "SharesInputError",
-            message: "Nothing to revoke. Pass artifactId (a gen_... id) or url (the previewUrl, zipUrl, viewUrl, or revokeUrl of the share). Run action:\"list\" to see both."
+            message: supplied ? `The reference is malformed and nothing was sent to the platform: no share id could be read out of ${JSON.stringify(supplied.length > 200 ? `${supplied.slice(0, 200)}...` : supplied)}. A share id is gen_ followed by exactly 64 lowercase hex characters (32 on shares minted before 2026-07-30), and a url revokes only when it contains one whole. Check the ref for a copy-paste cut, or run action:"list" and copy the exact artifactId.` : 'Nothing to revoke. Pass artifactId (a gen_... id) or url (the previewUrl, zipUrl, viewUrl, or revokeUrl of the share). Run action:"list" to see both.'
         }
     });
     const result = await revokeArtifact({
@@ -5990,7 +7000,7 @@ async function revokeShare(args) {
     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;
     if (!result.ok) {
         const isAuth = "SharesAuthError" === result.error.name;
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: "extension_shares",
             status: "revoke-failed",
@@ -6011,7 +7021,7 @@ async function revokeShare(args) {
             ]
         });
     }
-    if (true !== result.data.revoked) return envelope({
+    if (true !== result.data.revoked) return envelope_envelope({
         ok: true,
         command: "extension_shares",
         status: "revoke-unconfirmed",
@@ -6028,7 +7038,7 @@ async function revokeShare(args) {
             recordNote
         ]
     });
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_shares",
         status: "revoked",
@@ -6374,7 +7384,7 @@ async function manifest_validate_handler(args) {
         const errors = [
             args.projectPath ? `No manifest.json found under ${args.projectPath} (looked in the root and src/).` : "Pass manifestPath (path to manifest.json) or projectPath (project root)."
         ];
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: manifest_validate_COMMAND,
             status: "manifest-not-found",
@@ -6400,7 +7410,7 @@ async function manifest_validate_handler(args) {
         const errors = [
             `Cannot read manifest: ${err instanceof Error ? err.message : err}`
         ];
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: manifest_validate_COMMAND,
             status: "manifest-unreadable",
@@ -6535,7 +7545,7 @@ async function manifest_validate_handler(args) {
         else result.warnings.push(`${browser} (not requested, checked by default): ${issues}`);
     }
     result.valid = 0 === result.errors.length;
-    return envelope({
+    return envelope_envelope({
         ok: result.valid,
         command: manifest_validate_COMMAND,
         status: result.valid ? "valid" : "invalid",
@@ -7217,7 +8227,7 @@ async function theme_verify_handler(args) {
         try {
             text = await promises.readFile(abs, "utf8");
         } catch  {
-            return envelope({
+            return envelope_envelope({
                 ok: false,
                 command: theme_verify_COMMAND,
                 status: "bad-input",
@@ -7231,7 +8241,7 @@ async function theme_verify_handler(args) {
         try {
             raw = JSON.parse(text);
         } catch (err) {
-            return envelope({
+            return envelope_envelope({
                 ok: false,
                 command: theme_verify_COMMAND,
                 status: "bad-input",
@@ -7243,7 +8253,7 @@ async function theme_verify_handler(args) {
             });
         }
     } else {
-        if (!args.manifest) return envelope({
+        if (!args.manifest) return envelope_envelope({
             ok: false,
             command: theme_verify_COMMAND,
             status: "bad-request",
@@ -7260,7 +8270,7 @@ async function theme_verify_handler(args) {
     try {
         ({ manifest, theme } = coerceInput(raw));
     } catch (err) {
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: theme_verify_COMMAND,
             status: "bad-input",
@@ -7364,7 +8374,7 @@ async function theme_verify_handler(args) {
             how: "a Chrome theme is an unpacked extension: extension_dev then extension_logs on the exported theme dir (headless, focus-safe)"
         }
     ];
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: theme_verify_COMMAND,
         status: verdict,
@@ -7526,7 +8536,7 @@ function formatBytes(bytes) {
 async function analyze_handler(args) {
     const browser = args.browser ?? "chrome";
     const distPath = node_path.resolve(args.projectPath, "dist", browser);
-    if (!node_fs.existsSync(distPath)) return envelope({
+    if (!node_fs.existsSync(distPath)) return envelope_envelope({
         ok: false,
         command: analyze_COMMAND,
         status: "no-dist",
@@ -7636,7 +8646,7 @@ async function analyze_handler(args) {
             under10MB: totalSize - archiveSize < 10485760
         }
     };
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: analyze_COMMAND,
         status: "analyzed",
@@ -8124,7 +9134,7 @@ async function inspectViaBridge(args, browser, include, maxBytes) {
         }
         const frame = Array.isArray(parsed?.value?.frames) ? parsed.value.frames[0] : null;
         if (parsed?.ok === true && frame && "object" == typeof frame) value = frame;
-        else if (parsed?.ok === true) return envelope({
+        else if (parsed?.ok === true) return envelope_envelope({
             ok: false,
             command: TOOL,
             status: "inspect-failed",
@@ -8167,7 +9177,7 @@ async function inspectViaBridge(args, browser, include, maxBytes) {
         const cap = maxBytes > 0 ? maxBytes : 65536;
         await collectGeckoDeepDom(args, browser, urlFilter, cap, result, notes);
     }
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: TOOL,
         status: "inspected",
@@ -8188,7 +9198,7 @@ async function inspect_handler(args) {
     const maxBytes = args.maxBytes ?? 262144;
     if (!isChromiumFamily(browser)) return inspectViaBridge(args, browser, include, maxBytes);
     const resolved = await resolveCdpPort(args.projectPath, browser);
-    if (!resolved) return envelope({
+    if (!resolved) return envelope_envelope({
         ok: false,
         command: inspect_schema_schema.name,
         status: "no-session",
@@ -8212,7 +9222,7 @@ async function inspect_handler(args) {
         const pageTargets = allTargets.filter((t)=>"page" === t.type && !t.url.startsWith("devtools://") && (!t.url.startsWith("chrome://") || isOverridePage(t.url)));
         if (0 === pageTargets.length) {
             const chromeOnly = allTargets.some((t)=>"page" === t.type && t.url.startsWith("chrome://"));
-            return envelope({
+            return envelope_envelope({
                 ok: false,
                 command: inspect_schema_schema.name,
                 status: "no-inspectable-target",
@@ -8231,7 +9241,17 @@ async function inspect_handler(args) {
             });
         }
         const isExtensionSurface = (u)=>u.startsWith("chrome-extension://") || u.startsWith("moz-extension://");
-        const target = args.url ? pageTargets.find((t)=>t.url.includes(args.url)) ?? pageTargets.find((t)=>!isExtensionSurface(t.url)) ?? pageTargets[0] : pageTargets[0];
+        const defaultRank = (u)=>{
+            if (isEngineCompanionUrl(u)) return 3;
+            if (isOverridePage(u)) return 2;
+            if (isExtensionSurface(u)) return 0;
+            return 1;
+        };
+        const target = args.url ? pageTargets.find((t)=>t.url.includes(args.url)) ?? pageTargets.find((t)=>!isExtensionSurface(t.url)) ?? pageTargets[0] : pageTargets.map((t, index)=>({
+                t,
+                index,
+                rank: defaultRank(t.url)
+            })).sort((a, b)=>a.rank - b.rank || a.index - b.index)[0].t;
         const browserWsUrl = await CDPClient.discoverBrowserWsUrl(cdpPort);
         await cdp.connect(browserWsUrl);
         const sessionId = await cdp.attachToTarget(target.id);
@@ -8240,13 +9260,27 @@ async function inspect_handler(args) {
             await cdp.navigate(sessionId, args.url);
             await new Promise((r)=>setTimeout(r, 1500));
         } else await new Promise((r)=>setTimeout(r, 500));
+        let documentUrl = "";
+        let toolchainWarning = null;
+        if (!args.url && defaultRank(target.url) >= 2) {
+            try {
+                const href = await cdp.evaluate(sessionId, "location.href");
+                documentUrl = "string" == typeof href ? href : "";
+            } catch  {
+                documentUrl = "";
+            }
+            toolchainWarning = isEngineCompanionUrl(documentUrl) || isEngineCompanionUrl(target.url) ? `Inspected ${target.url}, which is rendered by the Extension.js toolchain's own companion extension, not by this project. Pass url, or open one of the extension's surfaces first (extension_open), then inspect again.` : `No url was given and only override pages were open, so this inspected ${target.url}. Unless this extension provides that override itself, this is the toolchain's welcome surface, not your extension: pass url or open a surface with extension_open.`;
+        }
         const result = {
             cdpPort,
             browser,
             target: {
                 id: target.id,
                 url: target.url,
-                title: target.title
+                title: target.title,
+                ...documentUrl && documentUrl !== target.url ? {
+                    documentUrl
+                } : {}
             },
             targets: pageTargets.map((t)=>({
                     id: t.id,
@@ -8294,17 +9328,18 @@ async function inspect_handler(args) {
         }
         const probeWarning = result.probeWarning;
         delete result.probeWarning;
-        return envelope({
+        return envelope_envelope({
             ok: true,
             command: inspect_schema_schema.name,
             status: "inspected",
             value: result,
             warnings: [
-                "string" == typeof probeWarning ? probeWarning : null
+                "string" == typeof probeWarning ? probeWarning : null,
+                toolchainWarning
             ]
         });
     } catch (err) {
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: inspect_schema_schema.name,
             status: "cdp-failed",
@@ -8347,8 +9382,7 @@ function list_extensions_unpackedExtensionId(distPath) {
 function readOwnIdentity(projectPath, browser) {
     let contract;
     try {
-        const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
-        contract = JSON.parse(node_fs.readFileSync(file, "utf8"));
+        contract = JSON.parse(node_fs.readFileSync(bridge_readyContractPath(projectPath, browser), "utf8"));
     } catch  {
         return null;
     }
@@ -8379,7 +9413,7 @@ const UNRESOLVED_NOTE = "Identity unresolved: the browser's Extensions CDP domai
 async function list_extensions_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
     if (isGeckoFamily(browser)) return listGeckoExtensions(args.projectPath, browser);
-    if (!isChromiumFamily(browser)) return envelope({
+    if (!isChromiumFamily(browser)) return envelope_envelope({
         ok: false,
         command: list_extensions_schema.name,
         status: "unsupported-browser",
@@ -8390,7 +9424,7 @@ async function list_extensions_handler(args) {
         hint: "Target a Chromium-family (CDP) or Firefox-family (RDP) dev session."
     });
     const resolved = await resolveCdpPort(args.projectPath, browser);
-    if (!resolved) return envelope({
+    if (!resolved) return envelope_envelope({
         ok: false,
         command: list_extensions_schema.name,
         status: "no-session",
@@ -8470,7 +9504,7 @@ async function list_extensions_handler(args) {
             return (a.name ?? a.id).localeCompare(b.name ?? b.id);
         });
         const ownEntry = extensions.find((e)=>e.ownExtension);
-        return envelope({
+        return envelope_envelope({
             ok: true,
             command: list_extensions_schema.name,
             status: "listed",
@@ -8486,7 +9520,7 @@ async function list_extensions_handler(args) {
             ]
         });
     } catch (error) {
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: list_extensions_schema.name,
             status: "cdp-failed",
@@ -8501,7 +9535,7 @@ async function list_extensions_handler(args) {
 }
 async function listGeckoExtensions(projectPath, browser) {
     const resolved = await resolveRdpPort(projectPath, browser);
-    if (!resolved) return envelope({
+    if (!resolved) return envelope_envelope({
         ok: false,
         command: list_extensions_schema.name,
         status: "no-session",
@@ -8555,7 +9589,7 @@ async function listGeckoExtensions(projectPath, browser) {
             return (a.name ?? a.id).localeCompare(b.name ?? b.id);
         });
         const ownEntry = extensions.find((e)=>e.ownExtension);
-        return envelope({
+        return envelope_envelope({
             ok: true,
             command: list_extensions_schema.name,
             status: "listed",
@@ -8571,7 +9605,7 @@ async function listGeckoExtensions(projectPath, browser) {
             ]
         });
     } catch (error) {
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: list_extensions_schema.name,
             status: "rdp-failed",
@@ -8582,57 +9616,23 @@ async function listGeckoExtensions(projectPath, browser) {
         });
     }
 }
-const CONTROL_WS_PATH = "/extjs-control";
-const LEVEL_ORDER = [
-    "error",
-    "warn",
-    "info",
-    "debug",
-    "trace"
-];
-function levelRank(level) {
-    const l = "log" === level ? "info" : level;
-    const i = LEVEL_ORDER.indexOf(l);
-    return -1 === i ? LEVEL_ORDER.length : i;
-}
-function makeUrlMatcher(pattern) {
-    const hasGlob = pattern.includes("*");
-    let re = null;
-    if (hasGlob) {
-        const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
-        re = new RegExp(escaped);
-    }
-    return (event)=>{
-        const candidates = [
-            event.url,
-            event.hostname
-        ].filter((v)=>"string" == typeof v);
-        if (0 === candidates.length) return false;
-        return candidates.some((c)=>re ? re.test(c) : c.includes(pattern));
-    };
-}
+const CLOSE_REFUSAL_FLOOR = 4000;
+const DEFAULT_LIMIT = 200;
+const DEFAULT_FOLLOW_MS = 4000;
+const MIN_FOLLOW_MS = 500;
+const MAX_FOLLOW_MS = 15000;
 function makeFilter(args) {
-    const minLevel = String(args.level || "all").toLowerCase();
-    const rawContexts = Array.isArray(args.context) ? args.context : "string" == typeof args.context ? args.context.split(",") : null;
-    const contexts = rawContexts && rawContexts.length ? new Set(rawContexts.map((c)=>c.trim()).filter(Boolean)) : null;
-    const sinceSeq = null != args.since ? Number(args.since) : null;
-    const urlMatches = args.url ? makeUrlMatcher(args.url) : null;
-    const tabId = null != args.tab ? Number(args.tab) : null;
-    return (event)=>{
-        if (!event || "object" != typeof event) return false;
-        if ("header" === event.type) return false;
-        if (args.signalsOnly && "dx.signal" !== event.eventType) return false;
-        if (contexts && !contexts.has(event.context)) return false;
-        if ("off" === minLevel) {
-            if ("dx.signal" !== event.eventType) return false;
-        } else if ("all" !== minLevel) {
-            if (levelRank(event.level) > levelRank(minLevel)) return false;
-        }
-        if (null != sinceSeq && Number.isFinite(sinceSeq) && "number" == typeof event.seq && event.seq <= sinceSeq) return false;
-        if (urlMatches && !urlMatches(event)) return false;
-        if (null != tabId && Number.isFinite(tabId) && event.tabId !== tabId) return false;
-        return true;
-    };
+    const level = String(args.level || "all").toLowerCase();
+    const loggingOff = "off" === level;
+    const query = {
+        context: args.context,
+        level: loggingOff ? "all" : level,
+        signalsOnly: Boolean(args.signalsOnly) || loggingOff,
+        since: args.since,
+        url: args.url,
+        tab: args.tab
+    };
+    return (event)=>matchesLogQuery(event, query);
 }
 const logs_schema_schema = {
     name: "extension_logs",
@@ -8702,12 +9702,12 @@ const logs_schema_schema = {
             },
             followMs: {
                 type: "number",
-                default: 4000,
-                description: "How long to collect live frames when follow=true (clamped 500–15000ms)."
+                default: DEFAULT_FOLLOW_MS,
+                description: `How long to collect live frames when follow=true (clamped ${MIN_FOLLOW_MS}–${MAX_FOLLOW_MS}ms).`
             },
             limit: {
                 type: "number",
-                default: 200,
+                default: DEFAULT_LIMIT,
                 description: "How many of the most recent events to return."
             }
         },
@@ -8717,23 +9717,6 @@ const logs_schema_schema = {
     }
 };
 const logs_TOOL = "extension_logs";
-function logsFilePath(projectPath, browser) {
-    return node_path.resolve(projectPath, "dist", "extension-js", browser, "logs.ndjson");
-}
-function readReadyContract(projectPath, browser) {
-    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
-    try {
-        const c = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-        if ("number" != typeof c.controlPort || !c.instanceId) return null;
-        return {
-            controlPort: c.controlPort,
-            instanceId: String(c.instanceId),
-            runId: String(c.runId || "")
-        };
-    } catch  {
-        return null;
-    }
-}
 function capRecent(events, limit) {
     if (events.length <= limit) return {
         events,
@@ -8747,9 +9730,9 @@ function capRecent(events, limit) {
 function emptyReason(projectPath, browser) {
     let contract;
     try {
-        contract = JSON.parse(node_fs.readFileSync(node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json"), "utf8"));
+        contract = JSON.parse(node_fs.readFileSync(bridge_readyContractPath(projectPath, browser), "utf8"));
     } catch  {
-        return "No ready.json for this project/browser: no dev session has produced a build here, so there is nothing to log. Start one with extension_dev.";
+        return `No ready.json for this project/browser: no dev session has produced a build here, so there is nothing to log. Start one with extension_dev. ${sessionPathHint(bridge_readyContractPath(projectPath, browser))}`;
     }
     if ("error" === contract.status) {
         const errs = contract.errors;
@@ -8767,7 +9750,7 @@ function summarize(events, source, browser, runId, limit, dropped, projectPath,
     const lastSeq = out.length ? out.reduce((m, e)=>"number" == typeof e.seq && e.seq > m ? e.seq : m, -1) : -1;
     const reason = 0 === matched && projectPath ? emptyReason(projectPath, browser) : void 0;
     const stale = Boolean(staleNote) && matched > 0;
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: logs_TOOL,
         status: 0 === matched ? "empty" : stale ? "stale" : "read",
@@ -8792,7 +9775,7 @@ function summarize(events, source, browser, runId, limit, dropped, projectPath,
 function staleFileNote(projectPath, browser, eventsRunId) {
     let contract;
     try {
-        contract = JSON.parse(node_fs.readFileSync(node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json"), "utf8"));
+        contract = JSON.parse(node_fs.readFileSync(bridge_readyContractPath(projectPath, browser), "utf8"));
     } catch  {
         return "These events survive from a previous session: no ready.json exists for this project/browser now, so nothing current is producing logs.";
     }
@@ -8808,8 +9791,8 @@ function staleFileNote(projectPath, browser, eventsRunId) {
     if (eventsRunId && liveIds.length > 0 && !liveIds.includes(eventsRunId)) return `These events carry runId ${eventsRunId} but the current session is run ${liveIds.join(" / ")}, which has written nothing yet. Do not read these as the current run's output.`;
 }
 async function readFromFile(args, browser, limit) {
-    const file = logsFilePath(args.projectPath, browser);
-    if (!node_fs.existsSync(file)) return envelope({
+    const file = logsPath(args.projectPath, browser);
+    if (!node_fs.existsSync(file)) return envelope_envelope({
         ok: false,
         command: logs_TOOL,
         status: "no-log-file",
@@ -8817,7 +9800,7 @@ async function readFromFile(args, browser, limit) {
             code: "E_LOGS_MISSING",
             message: `No logs found at ${file}.`
         },
-        hint: "Start a dev session first (extension_dev), or pass browser to match it. For live frames before any line is written, use follow:true."
+        hint: `Start a dev session first (extension_dev), or pass browser to match it. For live frames before any line is written, use follow:true. ${sessionPathHint(file)}`
     });
     const matches = makeFilter(args);
     const lines = node_fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
@@ -8838,12 +9821,47 @@ async function readFromFile(args, browser, limit) {
     }
     return summarize(events, "file", browser, runId, limit, 0, args.projectPath, staleFileNote(args.projectPath, browser, runId));
 }
+function controlRefusal(closeCode, reason, url, sentVersion) {
+    if (!Number.isFinite(closeCode) || closeCode < CLOSE_REFUSAL_FLOOR) return;
+    const said = reason.trim();
+    const preamble = `The dev server refused the control channel at ${url}: close code ${closeCode}${said ? ` ("${said}")` : ""}.`;
+    if (closeCode === CLOSE_BAD_HELLO) return {
+        code: "E_CONTROL_ENVELOPE",
+        status: "control-channel-refused",
+        message: `${preamble} That code is the broker rejecting the hello frame itself. This MCP dialed as a consumer with control envelope version ${sentVersion}, the version its pinned Extension.js speaks, and the role is one the broker always accepts, so the envelope version is the part that differs: the engine installed in this project is older or newer and speaks a different one. The session may be logging normally even though this read returned nothing.`,
+        hint: "Update the project's Extension.js so its control envelope matches this MCP's pinned engine, or read the file instead by calling extension_logs without follow. extension_doctor reports both versions."
+    };
+    if (closeCode === CLOSE_BAD_INSTANCE) return {
+        code: "E_STALE_CONTRACT",
+        status: "control-channel-stale",
+        message: `${preamble} That code means the instanceId this MCP sent belongs to a PREVIOUS dev session: the ready.json it read is stale, so the dev server was replaced after that file was written. Nothing here is a version problem, and the engine is not at fault; the session that is running now has an instance this read never named.`,
+        hint: "Wait for the current session to publish its contract with extension_wait and retry, or start one with extension_dev if none is running. extension_stop clears a contract left behind by a session that has gone away."
+    };
+    if (closeCode === CLOSE_CONTROL_UNAVAILABLE) return {
+        code: "E_NO_CONTROL_CHANNEL",
+        status: "control-channel-unavailable",
+        message: `${preamble} That code means the broker has no control channel to hand out: the session was started without allowControl, so it turns controlling clients away. Following logs is a read, not a control operation, so a session that refuses this connection cannot be streamed at all until it is relaunched.`,
+        hint: "Relaunch the session with extension_dev and allowControl: true, or read the file instead by calling extension_logs without follow."
+    };
+    if (closeCode === CLOSE_SLOW_CONSUMER) return {
+        code: "E_CONTROL_CHANNEL",
+        status: "control-channel-dropped",
+        message: `${preamble} That code means this reader fell far enough behind that the broker dropped it to protect itself. The session, the engine version and the control envelope are all fine: the log volume simply outran this follow window, and whatever came back stops at the moment of the drop rather than at the end of the window.`,
+        hint: "Narrow the query before following again (level, context, url or tab), lower followMs, or read the completed file by calling extension_logs without follow."
+    };
+    return {
+        code: "E_CONTROL_CHANNEL",
+        status: "control-channel-refused",
+        message: `${preamble} That code is an application-level refusal this MCP does not recognise, so the broker's own reason above is the whole diagnosis. It dialed as a consumer with control envelope version ${sentVersion}, the version its pinned Extension.js speaks; an engine newer than the pin can refuse for reasons this release has never seen.`,
+        hint: "Read the file instead by calling extension_logs without follow, and compare the engine versions with extension_doctor."
+    };
+}
 async function readFromStream(args, browser, limit) {
     const ready = readReadyContract(args.projectPath, browser);
     if (!ready) {
         const running = knownSessionBrowsers(args.projectPath).filter((b)=>b !== browser);
         const retarget = running.length ? `An active session exists for browser(s): ${running.join(", ")}, pass that as \`browser\`. Otherwise run` : "Run";
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: logs_TOOL,
             status: "no-control-channel",
@@ -8854,7 +9872,7 @@ async function readFromStream(args, browser, limit) {
             hint: `${retarget} extension_dev (browser: ${browser}) and wait for it to be ready, then retry. For past logs without a live channel, call without follow.`
         });
     }
-    const followMs = Math.min(Math.max(args.followMs ?? 4000, 500), 15000);
+    const followMs = Math.min(Math.max(args.followMs ?? DEFAULT_FOLLOW_MS, MIN_FOLLOW_MS), MAX_FOLLOW_MS);
     const matches = makeFilter(args);
     const events = [];
     let dropped = 0;
@@ -8866,7 +9884,7 @@ async function readFromStream(args, browser, limit) {
         try {
             socket = new ws_0(url);
         } catch (err) {
-            resolve(envelope({
+            resolve(envelope_envelope({
                 ok: false,
                 command: logs_TOOL,
                 status: "control-channel-failed",
@@ -8892,7 +9910,7 @@ async function readFromStream(args, browser, limit) {
             try {
                 socket.send(JSON.stringify({
                     type: "hello",
-                    v: 1,
+                    v: CONTROL_ENVELOPE_VERSION,
                     role: "consumer",
                     instanceId: ready.instanceId
                 }));
@@ -8922,7 +9940,7 @@ async function readFromStream(args, browser, limit) {
             try {
                 socket.close();
             } catch  {}
-            resolve(envelope({
+            resolve(envelope_envelope({
                 ok: false,
                 command: logs_TOOL,
                 status: "control-channel-failed",
@@ -8933,12 +9951,33 @@ async function readFromStream(args, browser, limit) {
                 hint: "The dev session may have stopped or the control port changed. Re-check with extension_wait."
             }));
         });
-        socket.on("close", finish);
+        socket.on("close", (code, reason)=>{
+            if (settled) return;
+            const refusal = controlRefusal(code, reason?.toString() ?? "", url, CONTROL_ENVELOPE_VERSION);
+            if (!refusal) return void finish();
+            if (events.length > 0 || dropped > 0) {
+                streamNote = refusal.message;
+                finish();
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            resolve(envelope_envelope({
+                ok: false,
+                command: logs_TOOL,
+                status: refusal.status,
+                error: {
+                    code: refusal.code,
+                    message: refusal.message
+                },
+                hint: refusal.hint
+            }));
+        });
     });
 }
 async function logs_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
-    const limit = args.limit && args.limit > 0 ? args.limit : 200;
+    const limit = args.limit && args.limit > 0 ? args.limit : DEFAULT_LIMIT;
     if (args.follow) return readFromStream(args, browser, limit);
     return readFromFile(args, browser, limit);
 }
@@ -9106,7 +10145,7 @@ async function storage_handler(args) {
     if (args.area) cli.push("--area", args.area);
     if (args.key) cli.push("--key", args.key);
     if ("set" === args.action) {
-        if (void 0 === args.value) return envelope({
+        if (void 0 === args.value) return envelope_envelope({
             ok: false,
             command: storage_schema.name,
             status: "bad-request",
@@ -9116,7 +10155,7 @@ async function storage_handler(args) {
                 message: "storage set requires a value"
             }
         });
-        if (void 0 === args.key) return envelope({
+        if (void 0 === args.key) return envelope_envelope({
             ok: false,
             command: storage_schema.name,
             status: "bad-request",
@@ -9271,7 +10310,7 @@ const dom_snapshot_schema = {
 };
 async function cdpPortOrError(projectPath, browser, feature) {
     if (!isChromiumFamily(browser)) return {
-        error: envelope({
+        error: envelope_envelope({
             ok: false,
             command: dom_snapshot_schema.name,
             status: "unsupported-browser",
@@ -9284,7 +10323,7 @@ async function cdpPortOrError(projectPath, browser, feature) {
     };
     const resolved = await resolveCdpPort(projectPath, browser);
     if (!resolved) return {
-        error: envelope({
+        error: envelope_envelope({
             ok: false,
             command: dom_snapshot_schema.name,
             status: "no-session",
@@ -9305,7 +10344,7 @@ async function dom_snapshot_handler(args) {
         const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
         if (isGeckoFamily(browser)) {
             const resolved = await resolveRdpPort(args.projectPath, browser);
-            if (!resolved) return envelope({
+            if (!resolved) return envelope_envelope({
                 ok: false,
                 command: dom_snapshot_schema.name,
                 status: "no-session",
@@ -9317,7 +10356,7 @@ async function dom_snapshot_handler(args) {
             });
             try {
                 const tabs = await rdpListTabs(resolved.port);
-                return envelope({
+                return envelope_envelope({
                     ok: true,
                     command: dom_snapshot_schema.name,
                     status: "listed-targets",
@@ -9339,7 +10378,7 @@ async function dom_snapshot_handler(args) {
                     ]
                 });
             } catch (e) {
-                return envelope({
+                return envelope_envelope({
                     ok: false,
                     command: dom_snapshot_schema.name,
                     status: "rdp-failed",
@@ -9356,7 +10395,7 @@ async function dom_snapshot_handler(args) {
         if ("error" in cdp) return cdp.error;
         try {
             const targets = await listPageTargets(cdp.port);
-            return envelope({
+            return envelope_envelope({
                 ok: true,
                 command: dom_snapshot_schema.name,
                 status: "listed-targets",
@@ -9369,7 +10408,7 @@ async function dom_snapshot_handler(args) {
                 ]
             });
         } catch (e) {
-            return envelope({
+            return envelope_envelope({
                 ok: false,
                 command: dom_snapshot_schema.name,
                 status: "cdp-failed",
@@ -9397,7 +10436,7 @@ async function dom_snapshot_handler(args) {
     let targetTab = args.tab;
     let resolvedTarget = null;
     if (args.tabUrl) {
-        if (null != args.tab || args.url) return envelope({
+        if (null != args.tab || args.url) return envelope_envelope({
             ok: false,
             command: dom_snapshot_schema.name,
             status: "bad-request",
@@ -9415,7 +10454,7 @@ async function dom_snapshot_handler(args) {
             try {
                 targets = await listPageTargets(cdp.port);
             } catch (e) {
-                return envelope({
+                return envelope_envelope({
                     ok: false,
                     command: dom_snapshot_schema.name,
                     status: "cdp-failed",
@@ -9428,7 +10467,7 @@ async function dom_snapshot_handler(args) {
                 });
             }
             const matches = matchTargetsByUrl(targets, args.tabUrl);
-            if (0 === matches.length) return envelope({
+            if (0 === matches.length) return envelope_envelope({
                 ok: false,
                 command: dom_snapshot_schema.name,
                 status: "no-matching-target",
@@ -9442,7 +10481,7 @@ async function dom_snapshot_handler(args) {
                 },
                 hint: `Pick one from availableTargets and retry with a \`tabUrl\` substring of its url, or open the page first (extension_open with \`url\`). ${TARGET_ID_NOTE}`
             });
-            if (matches.length > 1) return envelope({
+            if (matches.length > 1) return envelope_envelope({
                 ok: false,
                 command: dom_snapshot_schema.name,
                 status: "ambiguous-target",
@@ -9464,7 +10503,7 @@ async function dom_snapshot_handler(args) {
             const listed = await listBridgeTabs(args.projectPath, browser, args.timeout);
             if ("error" in listed) return listed.error;
             const matches = matchTabsByUrl(listed.tabs, args.tabUrl);
-            if (0 === matches.length) return envelope({
+            if (0 === matches.length) return envelope_envelope({
                 ok: false,
                 command: dom_snapshot_schema.name,
                 status: "no-matching-target",
@@ -9478,7 +10517,7 @@ async function dom_snapshot_handler(args) {
                 },
                 hint: "Pick one from availableTabs and retry with a `tabUrl` substring of its url, or open the page first (extension_open with `url`)."
             });
-            if (matches.length > 1) return envelope({
+            if (matches.length > 1) return envelope_envelope({
                 ok: false,
                 command: dom_snapshot_schema.name,
                 status: "ambiguous-target",
@@ -9546,7 +10585,7 @@ const publish_schema = {
     }
 };
 function fail(name, message, status, code) {
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: "extension_publish",
         status,
@@ -9573,16 +10612,22 @@ async function publish_handler(args) {
         api: args.api,
         token
     });
-    if (!result.ok) return envelope({
-        ok: false,
-        command: "extension_publish",
-        status: "publish-failed",
-        error: {
-            code: "E_PLATFORM",
-            name: result.error.name,
-            message: result.error.message
-        }
-    });
+    if (!result.ok) {
+        const projectMissing = /\(404\)/.test(result.error.message);
+        return envelope_envelope({
+            ok: false,
+            command: "extension_publish",
+            status: "publish-failed",
+            error: {
+                code: "E_PLATFORM",
+                name: result.error.name,
+                message: result.error.message
+            },
+            ...projectMissing ? {
+                hint: "The token's project does not exist on the host this call targeted. Run extension_auth (action: status) to see which workspace/project the token is scoped to, create that project first (import a repo or a template at extension.dev/new), or run extension_auth (action: login) against a project that exists there."
+            } : {}
+        });
+    }
     const data = result.data;
     let note = null;
     if (null != args.ttlHours && "public" === data.visibility) note = "ttlHours was ignored: this is a public project, whose share URL is its canonical public page.";
@@ -9627,7 +10672,7 @@ async function publish_handler(args) {
             }
         }
     }
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_publish",
         status: "published",
@@ -9680,7 +10725,7 @@ const release_promote_schema = {
     }
 };
 function release_promote_fail(name, message, status, code) {
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: "extension_release_promote",
         status,
@@ -9697,7 +10742,7 @@ async function release_promote_handler(args) {
     const buildId = String(args.buildId || "").trim();
     const channel = String(args.channel || "").trim();
     if (!buildId || !channel) return release_promote_fail("ReleaseInputError", "buildId and channel are required.", "bad-request", "E_BAD_REQUEST");
-    const apiCheck = safeApiBase(resolveApiBase(args.api));
+    const apiCheck = safeApiBase(resolveApiBase(args.api), args.api);
     if (!apiCheck.ok) return release_promote_fail("ReleaseConfigError", apiCheck.message, "bad-config", "E_CONFIG");
     const url = `${apiCheck.base}/api/cli/release/promote`;
     const body = {
@@ -9754,7 +10799,7 @@ async function release_promote_handler(args) {
                 }
             }
         }
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: "extension_release_promote",
             status: "promote-failed",
@@ -9782,7 +10827,7 @@ async function release_promote_handler(args) {
             publicBuildUrl
         } : {}
     } : data;
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_release_promote",
         status: "promoted",
@@ -9790,7 +10835,7 @@ async function release_promote_handler(args) {
     });
 }
 function release_list_fail(name, message, status, code, extra) {
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: "extension_release_status",
         status,
@@ -9847,7 +10892,7 @@ async function readReleases(args) {
     const publicUrlNote = publicProjectUrl ? isPrivate ? "publicUrl links open only for workspace members. This project is private, so an outside recipient needs a share link from extension_publish." : "publicUrl links are the public build pages: no login needed, and they carry the per-browser downloads and the run locally instructions." : null;
     const channelsUnavailable = channelsRes.ok ? null : `channels.json unreadable: ${channelsRes.message}`;
     const buildsUnavailable = buildsRes.ok ? null : `builds/index.json unreadable: ${buildsRes.message}`;
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_release_status",
         status: "read",
@@ -9961,7 +11006,7 @@ function normalizeStoresStatus(json) {
     return out;
 }
 function store_status_fail(name, message, status, code, extra) {
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: "extension_release_status",
         status,
@@ -10053,7 +11098,7 @@ async function readStores(args) {
     const healthUnavailable = healthRes.ok ? null : `stores/health.json unreadable: ${healthRes.message}`;
     const statusUnavailable = statusRes.ok ? null : `stores/status.json unreadable: ${statusRes.message}`;
     const submissionsUnavailable = submissionsRes.ok || 404 === submissionsRes.status ? null : `stores/submissions.json unreadable: ${submissionsRes.message}`;
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_release_status",
         status: "read",
@@ -10151,7 +11196,7 @@ async function release_status_handler(args) {
         stores
     ].filter(Boolean);
     const ok = sections.some((section)=>true === section.ok);
-    return envelope({
+    return envelope_envelope({
         ok,
         command: "extension_release_status",
         status: ok ? "read" : "unavailable",
@@ -10240,7 +11285,7 @@ const submit_schema = {
     }
 };
 function submit_fail(name, message, status, code) {
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: "extension_submit",
         status,
@@ -10258,7 +11303,7 @@ async function submit_handler(args) {
     if (0 === browsers.length) return submit_fail("SubmitInputError", 'browsers is required (e.g. ["chrome","firefox","edge","safari"]).', "bad-request", "E_BAD_REQUEST");
     const buildSha = String(args.buildSha || "").trim();
     if (!buildSha) return submit_fail("SubmitInputError", "buildSha is required (the built commit to submit).", "bad-request", "E_BAD_REQUEST");
-    const apiCheck = safeApiBase(resolveApiBase(args.api));
+    const apiCheck = safeApiBase(resolveApiBase(args.api), args.api);
     if (!apiCheck.ok) return submit_fail("SubmitConfigError", apiCheck.message, "bad-config", "E_CONFIG");
     const url = `${apiCheck.base}/api/cli/stores/submit`;
     const dryRun = false !== args.dryRun;
@@ -10390,7 +11435,7 @@ async function submit_handler(args) {
         message = summaryParts.join(" ");
     }
     if (!dryRun) statusNote = "Track this submission with extension_release_status: it reads the recorded outcome, per-store credential health, and review state from the public registry.";
-    return envelope({
+    return envelope_envelope({
         ok,
         command: "extension_submit",
         status: dryRun ? "preflight" : "submitted",
@@ -10403,9 +11448,9 @@ async function submit_handler(args) {
         ]
     });
 }
-function doctor_readReadyContract(projectPath, browser) {
+function readContractForDiagnosis(projectPath, browser) {
     try {
-        const raw = node_fs.readFileSync(node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json"), "utf8");
+        const raw = node_fs.readFileSync(bridge_readyContractPath(projectPath, browser), "utf8");
         return JSON.parse(raw);
     } catch  {
         return null;
@@ -10457,7 +11502,7 @@ async function environmentPreflight() {
         detail: cacheExists ? `Template catalog cached at ${cacheFile}` : "Template catalog not cached yet (extension_templates will fetch it)"
     });
     const healthy = checks.every((c)=>"fail" !== c.status);
-    return envelope({
+    return envelope_envelope({
         ok: healthy,
         command: doctor_schema.name,
         status: healthy ? "healthy" : "unhealthy",
@@ -10477,22 +11522,11 @@ function safeStringify(value) {
     }
 }
 function recentErrorLogs(projectPath, browser, max = 5) {
-    const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "logs.ndjson");
-    let lines;
-    try {
-        lines = node_fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
-    } catch  {
-        return [];
-    }
     const errs = [];
-    for (const line of lines){
-        let ev;
-        try {
-            ev = JSON.parse(line);
-        } catch  {
-            continue;
-        }
-        if (!ev || "error" !== ev.level) continue;
+    for (const event of readLogEvents(projectPath, browser, {
+        level: "error"
+    })){
+        const ev = event;
         const parts = Array.isArray(ev.messageParts) ? ev.messageParts : Array.isArray(ev.args) ? ev.args : null;
         let msg = parts ? parts.map((p)=>"string" == typeof p ? p : safeStringify(p)).join(" ") : ev.message || ev.text || "";
         if (!msg && ev.errorName) msg = ev.stack ? `${ev.errorName}: ${ev.stack}` : ev.errorName;
@@ -10528,6 +11562,17 @@ async function doctor_handler(args) {
     ], {
         cwd: projectPath
     });
+    if (refusedTheOutputFlag(stderr ?? "")) return envelope_envelope({
+        ok: false,
+        command: doctor_schema.name,
+        status: "engine-too-old",
+        error: {
+            code: "E_ENGINE_TOO_OLD",
+            name: "CliError",
+            message: await outputFlagRefusalMessage("doctor", "doctor", projectPath)
+        },
+        hint: "Until then, extension_logs without follow still reads this project's log file, and the session's ready.json still records how the last build ended."
+    });
     const out = stdout.trim();
     try {
         const parsed = JSON.parse(out);
@@ -10538,7 +11583,7 @@ async function doctor_handler(args) {
             if ("string" == typeof check.remediation) check.remediation = toMcpSpeak(check.remediation);
         }
         let healthy = 0 === code;
-        const contract = doctor_readReadyContract(projectPath, browser);
+        const contract = readContractForDiagnosis(projectPath, browser);
         if (contract?.status === "error") {
             healthy = false;
             const browserExited = "browser_exited" === contract.code || void 0 !== contract.browserExitCode;
@@ -10574,7 +11619,7 @@ async function doctor_handler(args) {
                 } : {}
             });
         }
-        return envelope({
+        return envelope_envelope({
             ok: healthy,
             command: doctor_schema.name,
             status: healthy ? "healthy" : "unhealthy",
@@ -10588,7 +11633,8 @@ async function doctor_handler(args) {
         });
     } catch  {
         const message = stderr.trim() || `extension exited with code ${code}`;
-        return envelope({
+        const cliReport = toMcpSpeak(out).trim().slice(0, 4000);
+        return envelope_envelope({
             ok: false,
             command: doctor_schema.name,
             status: "cli-failed",
@@ -10597,7 +11643,13 @@ async function doctor_handler(args) {
                 name: "CliError",
                 message: toMcpSpeak(message)
             },
-            hint: "extension doctor requires a recent extension CLI, the project's local install may predate it."
+            value: {
+                browser,
+                ...cliReport ? {
+                    cliReport
+                } : {}
+            },
+            hint: cliReport ? "cliReport is the doctor's own output, unparsed: read the failing checks and remediations there." : "extension doctor requires a recent extension CLI, the project's local install may predate it."
         });
     }
 }
@@ -10641,7 +11693,7 @@ async function wait_handler(args) {
     const requested = args.timeoutMs ?? args.timeout ?? DEFAULT_TIMEOUT_MS;
     const budgetMs = Math.min(Math.max(requested, MIN_TIMEOUT_MS), SAFE_CEILING_MS);
     const clamped = requested > SAFE_CEILING_MS;
-    const readyPath = node_path.resolve(args.projectPath, "dist", "extension-js", browser, "ready.json");
+    const readyPath = bridge_readyContractPath(args.projectPath, browser);
     const buildOnly = findSessionInfo(args.projectPath, browser)?.noBrowser === true;
     const since = sessionSinceMs(args.projectPath, browser);
     const start = Date.now();
@@ -10663,7 +11715,7 @@ async function wait_handler(args) {
             }
             lastContractStatus = contract.status;
             if ("ready" === contract.status) {
-                if ("number" == typeof contract.pid && !wait_isAlive(contract.pid)) return envelope({
+                if ("number" == typeof contract.pid && !wait_isAlive(contract.pid)) return envelope_envelope({
                     ok: false,
                     command: wait_schema.name,
                     status: "stale",
@@ -10679,7 +11731,7 @@ async function wait_handler(args) {
                     }
                 });
                 const attached = "attached" === contract.runtime || "string" == typeof contract.executorAttachedAt;
-                if (!attached && buildOnly) return envelope({
+                if (!attached && buildOnly) return envelope_envelope({
                     ok: true,
                     command: wait_schema.name,
                     status: "ready",
@@ -10710,7 +11762,7 @@ async function wait_handler(args) {
                 const warnings = [];
                 if (runtimeErrors.length) warnings.push(`Compiled and attached, but the extension is throwing at runtime (${runtimeErrors.length} recent error event${1 === runtimeErrors.length ? "" : "s"} above). Check extension_logs (level: error) or extension_doctor before trusting this session.`);
                 if (guestCheck.checked && !guestCheck.loaded) warnings.push("The engine reports the runtime attached, but the browser's own target list shows no chrome-extension:// target for your extension, only the engine companion. This is the signature of a silently rejected --load-extension (extension.js BUGS_TO_FIX §83): the CLI and ready.json cannot see it, and the control verbs will fail against a guest that is not there. Check the manifest and extension_logs.");
-                return envelope({
+                return envelope_envelope({
                     ok: true,
                     command: wait_schema.name,
                     status: "ready",
@@ -10740,7 +11792,7 @@ async function wait_handler(args) {
                     warnings
                 });
             }
-            if ("error" === contract.status) return envelope({
+            if ("error" === contract.status) return envelope_envelope({
                 ok: false,
                 command: wait_schema.name,
                 status: "contract-error",
@@ -10759,7 +11811,7 @@ async function wait_handler(args) {
         } catch  {}
         await new Promise((resolve)=>setTimeout(resolve, pollInterval));
     }
-    if (sawCompiledButUnattached) return envelope({
+    if (sawCompiledButUnattached) return envelope_envelope({
         ok: false,
         command: wait_schema.name,
         status: "compiled-not-attached",
@@ -10776,7 +11828,7 @@ 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."
     });
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: wait_schema.name,
         status: "timeout",
@@ -10954,7 +12006,7 @@ async function add_feature_handler(args) {
     const projectPath = node_path.resolve(args.projectPath);
     const srcDir = node_path.join(projectPath, "src");
     const manifestPath = node_path.join(srcDir, "manifest.json");
-    if (!node_fs.existsSync(manifestPath)) return envelope({
+    if (!node_fs.existsSync(manifestPath)) return envelope_envelope({
         ok: false,
         command: add_feature_COMMAND,
         status: "manifest-not-found",
@@ -10965,7 +12017,7 @@ async function add_feature_handler(args) {
         hint: "Ensure projectPath points to an extension project root with src/manifest.json"
     });
     const templateSlug = FEATURE_TEMPLATE_MAP[args.feature]?.[framework];
-    if (!templateSlug) return envelope({
+    if (!templateSlug) return envelope_envelope({
         ok: false,
         command: add_feature_COMMAND,
         status: "no-reference-template",
@@ -11048,7 +12100,7 @@ async function add_feature_handler(args) {
     });
     const conflicts = filesToCreate.filter((f)=>node_fs.existsSync(node_path.join(projectPath, f.path)));
     const conflictHint = `Warning: ${conflicts.length} file(s) already exist and would be overwritten.`;
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: add_feature_COMMAND,
         status: conflicts.length ? "planned-with-conflicts" : "planned",
@@ -11191,7 +12243,7 @@ const FIRST_CALL_BUDGET_MS = 8000;
 const RESUME_BUDGET_MS = 22000;
 const PENDING_TTL_NOTE = "Once authorized, the minted token lives at most 7 days (server-enforced); CI must re-mint before expiry (console: project settings -> Access tokens).";
 function login_fail(name, message, status, code) {
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: "extension_auth",
         status,
@@ -11204,7 +12256,7 @@ function login_fail(name, message, status, code) {
 }
 function success(creds) {
     const expiresAt = creds.expiresAt ? new Date(1000 * creds.expiresAt).toISOString() : null;
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_auth",
         status: "logged-in",
@@ -11223,7 +12275,7 @@ 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_auth (action: 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_auth (action: login) again with this deviceCode and the same project.`;
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: "extension_auth",
         status: "authorization-pending",
@@ -11248,7 +12300,7 @@ function login_pending(start) {
 }
 function resumePending(deviceCode, verificationUri) {
     const 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_auth (action: login) again with this same deviceCode and the same project.`;
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: "extension_auth",
         status: "authorization-pending",
@@ -11270,7 +12322,7 @@ function resumePending(deviceCode, verificationUri) {
 async function loginToProject(args) {
     const project = String(args.project || "").trim();
     if (!/^[^/]+\/[^/]+$/.test(project)) return login_fail("BadRequest", "project must be in the form '<workspace>/<project>'.", "bad-request", "E_BAD_REQUEST");
-    const apiCheck = safeApiBase(resolveApiBase(args.api));
+    const apiCheck = safeApiBase(resolveApiBase(args.api), args.api);
     if (!apiCheck.ok) return login_fail("LoginConfigError", apiCheck.message, "login-failed", "E_AUTH_FAILED");
     const apiBase = apiCheck.base;
     let config;
@@ -11323,9 +12375,92 @@ async function loginToProject(args) {
         verificationUriComplete: start.verificationUriComplete
     });
 }
-async function readIdentity() {
+const server_identity_DEFAULT_TIMEOUT_MS = 5000;
+async function askServerIdentity(args) {
+    const fetchImpl = args.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(()=>controller.abort(), args.timeoutMs ?? server_identity_DEFAULT_TIMEOUT_MS);
+    try {
+        const res = await fetchImpl(`${args.apiBase.replace(/\/+$/, "")}/api/cli/whoami`, {
+            headers: {
+                authorization: `Bearer ${args.token}`,
+                accept: "application/json"
+            },
+            signal: controller.signal
+        });
+        if (200 === res.status) {
+            const data = await res.json().catch(()=>null);
+            const login = String(data?.login || "").trim();
+            if (!login) return {
+                kind: "unavailable",
+                detail: "the server answered 200 without a login"
+            };
+            return {
+                kind: "confirmed",
+                login,
+                live: data?.live === true
+            };
+        }
+        if (401 === res.status) return {
+            kind: "refused"
+        };
+        return {
+            kind: "unavailable",
+            detail: `the server answered ${res.status}, which is not a verdict on this credential`
+        };
+    } catch (error) {
+        return {
+            kind: "unavailable",
+            detail: error?.message || "network error"
+        };
+    } finally{
+        clearTimeout(timer);
+    }
+}
+function describeServer(check, api) {
+    if ("confirmed" === check.kind) return {
+        status: "logged-in",
+        note: `The server at ${api} confirms this token: it resolves to ${check.login} and is live there.`,
+        warning: null,
+        value: {
+            verdict: "confirmed",
+            api,
+            login: check.login,
+            live: check.live
+        }
+    };
+    if ("refused" === check.kind) return {
+        status: "refused-by-server",
+        note: `The server at ${api} refused this credential: it does not resolve to an identity there (expired, revoked, or minted for another environment). The workspace/project above is only what the local file claims. Run extension_auth (action: login) to re-authenticate.`,
+        warning: null,
+        value: {
+            verdict: "refused",
+            api
+        }
+    };
+    if ("unavailable" === check.kind) return {
+        status: "logged-in",
+        note: null,
+        warning: `Could not verify this login with the server at ${api} (${check.detail}). The identity above is the local file's claim only, not server-confirmed.`,
+        value: {
+            verdict: "unavailable",
+            api,
+            detail: check.detail
+        }
+    };
+    return {
+        status: "expired",
+        note: null,
+        warning: null,
+        value: {
+            verdict: "not-asked",
+            detail: check.detail
+        }
+    };
+}
+async function readIdentity(deps) {
     const creds = readCredentials();
-    if (!creds) return envelope({
+    if (!creds) return envelope_envelope({
         ok: true,
         command: "extension_auth",
         status: "logged-out",
@@ -11337,19 +12472,39 @@ async function readIdentity() {
     const recordedApi = String(creds.api || "").trim();
     const effectiveDefaultApi = resolveApiBase();
     const apiDiverges = Boolean(recordedApi) && recordedApi !== effectiveDefaultApi;
+    const askApi = recordedApi || effectiveDefaultApi;
     const envTokenSet = Boolean(String(process.env.EXTENSION_DEV_TOKEN || "").trim());
+    let check;
+    if (expired) check = {
+        kind: "not-asked",
+        detail: "the stored token has already expired locally"
+    };
+    else {
+        const safe = safeApiBase(askApi);
+        check = safe.ok ? await askServerIdentity({
+            apiBase: safe.base,
+            token: creds.token,
+            fetchImpl: deps?.fetchImpl
+        }) : {
+            kind: "unavailable",
+            detail: safe.message
+        };
+    }
+    const server = describeServer(check, askApi);
     const identityNote = expired ? "The stored token has expired. Run extension_auth (action: login) to refresh it." : `Logged in as ${creds.workspaceSlug}/${creds.projectSlug}, per the token extension_auth stored on this machine. That token is what scopes the identity: it does not follow the current working directory or project folder.`;
     const apiDivergesNote = apiDiverges ? `This login was minted via ${recordedApi}: access grants for private registry reads use that recorded base when no api argument is given, while other authenticated tools target ${effectiveDefaultApi} unless given one.` : null;
     const envTokenNote = envTokenSet ? "EXTENSION_DEV_TOKEN is set and takes precedence over this stored login for authenticated tools; this report describes only the stored login." : null;
     const message = [
         identityNote,
+        server.note,
+        server.warning,
         apiDivergesNote,
         envTokenNote
     ].filter(Boolean).join(" ");
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_auth",
-        status: expired ? "expired" : "logged-in",
+        status: expired ? "expired" : server.status,
         value: {
             workspaceSlug: creds.workspaceSlug,
             projectSlug: creds.projectSlug,
@@ -11360,11 +12515,13 @@ async function readIdentity() {
             provider: creds.provider ?? "extensiondev",
             expiresAt: creds.expiresAt ? new Date(1000 * creds.expiresAt).toISOString() : null,
             expiresInSeconds: creds.expiresAt ? creds.expiresAt - now : null,
-            expired
+            expired,
+            server: server.value
         },
         hint: message,
         warnings: [
             tokenTtlNote(creds.workspaceSlug, creds.projectSlug),
+            server.warning,
             apiDivergesNote,
             envTokenNote
         ]
@@ -11377,7 +12534,7 @@ async function clearLocalCredentials() {
         project: creds.projectSlug
     }, "settings/access-tokens") : null;
     const result = clearCredentials();
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_auth",
         status: result.cleared ? "logged-out" : "nothing-to-clear",
@@ -11390,7 +12547,7 @@ async function clearLocalCredentials() {
 }
 const auth_schema = {
     name: "extension_auth",
-    description: "Sign this machine in to extension.dev, report that login, or clear it. Pass action:'status' (the default) to name the workspace and project the stored token is scoped to and when it expires, never the token itself; that identity comes from the stored token alone, and does not change with the current working directory or whichever project folder you are in. Pass action:'login' for a two-phase flow: call with `project` to get a code plus a URL the user authorizes at extension.dev/device, then call again with the returned `deviceCode`. GitHub federation happens server-side, so no GitHub token lands on this machine. Minted tokens live at most 7 days, server-enforced, so CI must re-mint before expiry on the console's project settings, Access tokens page. Pass action:'logout' to delete the local credentials only; the token stays valid server-side until it is revoked at the URL the response returns.",
+    description: "Sign this machine in to extension.dev, report that login, or clear it. Pass action:'status' (the default) to name the workspace and project the stored token is scoped to and when it expires, never the token itself; that identity comes from the stored token alone, and does not change with the current working directory or whichever project folder you are in. Status also asks the platform's whoami endpoint whether that credential actually resolves there: the answer is reported as confirmed, refused-by-server, or unverified when the server cannot be reached, so a local file claiming a login the server would refuse is never reported as simply logged in. Pass action:'login' for a two-phase flow: call with `project` to get a code plus a URL the user authorizes at extension.dev/device, then call again with the returned `deviceCode`. GitHub federation happens server-side, so no GitHub token lands on this machine. Minted tokens live at most 7 days, server-enforced, so CI must re-mint before expiry on the console's project settings, Access tokens page. Pass action:'logout' to delete the local credentials only; the token stays valid server-side until it is revoked at the URL the response returns.",
     inputSchema: {
         type: "object",
         properties: {
@@ -11710,7 +12867,7 @@ async function detectBrowsers(browsers) {
     }
     const available = detected.filter((d)=>"not_found" !== d.source);
     const missing = detected.filter((d)=>"not_found" === d.source);
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_browsers",
         status: "detected",
@@ -11767,7 +12924,7 @@ async function listManagedBrowsers() {
             });
         }
     }
-    return envelope({
+    return envelope_envelope({
         ok: true,
         command: "extension_browsers",
         status: "listed",
@@ -11786,7 +12943,7 @@ async function installManagedBrowser(browser) {
         await extensionInstall({
             browser
         });
-        return envelope({
+        return envelope_envelope({
             ok: true,
             command: "extension_browsers",
             status: "installed",
@@ -11797,7 +12954,7 @@ async function installManagedBrowser(browser) {
             hint: `Browser "${browser}" is now available. Use extension_dev or extension_start with browser: "${browser}".`
         });
     } catch (err) {
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: "extension_browsers",
             status: "install-failed",
@@ -11815,7 +12972,7 @@ async function installManagedBrowser(browser) {
 }
 async function uninstallManagedBrowser(args) {
     const start = Date.now();
-    if (!args.browser && !args.all) return envelope({
+    if (!args.browser && !args.all) return envelope_envelope({
         ok: false,
         command: "extension_browsers",
         status: "bad-request",
@@ -11829,7 +12986,7 @@ async function uninstallManagedBrowser(args) {
             browser: args.browser,
             all: args.all
         });
-        return envelope({
+        return envelope_envelope({
             ok: true,
             command: "extension_browsers",
             status: "uninstalled",
@@ -11840,7 +12997,7 @@ async function uninstallManagedBrowser(args) {
             hint: 'Use extension_browsers with action: "list" to confirm what remains in the managed cache.'
         });
     } catch (err) {
-        return envelope({
+        return envelope_envelope({
             ok: false,
             command: "extension_browsers",
             status: "uninstall-failed",
@@ -11897,7 +13054,7 @@ async function browsers_handler(args) {
     const action = args.action ?? "detect";
     if ("list" === action) return listManagedBrowsers();
     if ("install" === action) {
-        if (!args.browser) return envelope({
+        if (!args.browser) return envelope_envelope({
             ok: false,
             command: "extension_browsers",
             status: "bad-request",
@@ -12066,7 +13223,7 @@ function describeToolArgs(inputSchema) {
     };
 }
 function inputValidationError(toolName, issues, inputSchema) {
-    return envelope({
+    return envelope_envelope({
         ok: false,
         command: toolName,
         status: "invalid-arguments",
@@ -12113,9 +13270,30 @@ const tools = [
     browsers_namespaceObject,
     doctor_namespaceObject
 ];
+function toolResultFrame(result) {
+    let refused = false;
+    try {
+        const parsed = JSON.parse(result);
+        refused = isEnvelope(parsed) && false === parsed.ok;
+    } catch  {
+        refused = false;
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: result
+            }
+        ],
+        ...refused ? {
+            isError: true
+        } : {}
+    };
+}
 const toolMap = new Map();
 for (const tool of tools)toolMap.set(tool.schema.name, tool);
 async function startServer() {
+    installCarrierExitCleanup();
     const server = new Server({
         name: "extension-dev",
         version: package_namespaceObject.rE
@@ -12138,7 +13316,7 @@ async function startServer() {
             content: [
                 {
                     type: "text",
-                    text: envelope({
+                    text: envelope_envelope({
                         ok: false,
                         command: name,
                         status: "unknown-tool",
@@ -12167,20 +13345,13 @@ async function startServer() {
         };
         try {
             const result = await tool.handler(normalizedArgs);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: result
-                    }
-                ]
-            };
+            return toolResultFrame(result);
         } catch (err) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: envelope({
+                        text: envelope_envelope({
                             ok: false,
                             command: name,
                             status: "internal-error",