@extension.dev/mcp 9.0.0 → 10.0.0

package/dist/module.js

@@ -579,7 +579,7 @@ __webpack_require__.d(wait_namespaceObject, {
     handler: ()=>wait_handler,
     schema: ()=>wait_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"9.0.0","El":{"OP":"4.0.16-canary.1784889479.74e12044"}}');
+var package_namespaceObject = JSON.parse('{"rE":"10.0.0","El":{"OP":"4.0.17"}}');
 function credentialsPath() {
     if ("win32" === process.platform) {
         const base = process.env.APPDATA || process.env.LOCALAPPDATA || node_path.join(node_os.homedir(), "AppData", "Roaming");
@@ -1109,6 +1109,38 @@ function parseBuildIndex(json) {
     }
     return out;
 }
+const ENVELOPE_SCHEMA = 1;
+const collectWarnings = (warnings)=>{
+    if (!warnings) return [];
+    const kept = [];
+    for (const warning of warnings){
+        if ("string" != typeof warning) continue;
+        const text = warning.trim();
+        if (text && !kept.includes(text)) kept.push(text);
+    }
+    return kept;
+};
+function envelopeObject(init) {
+    const frame = {
+        schema: ENVELOPE_SCHEMA,
+        ok: init.ok,
+        command: init.command,
+        status: init.status,
+        value: void 0 === init.value ? null : init.value,
+        error: init.error ?? null,
+        warnings: collectWarnings(init.warnings)
+    };
+    if (void 0 !== init.truncated) frame.truncated = init.truncated;
+    if ("string" == typeof init.hint && init.hint) frame.hint = init.hint;
+    return frame;
+}
+function envelope(init) {
+    return JSON.stringify(envelopeObject(init));
+}
+function isEnvelope(frame) {
+    return !!frame && "object" == typeof frame && frame.schema === ENVELOPE_SCHEMA;
+}
+const COMMAND = "extension_create";
 function scaffoldEnginePin(projectPath) {
     try {
         const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
@@ -1146,7 +1178,7 @@ function detectPackageManager(projectPath) {
 }
 const create_schema = {
     name: "extension_create",
-    description: "Create a new browser extension project from a template in the extension.dev catalog. extension_templates lists what is available. The scaffolder may initialize a git repository in the new project; the result's defaultsApplied block reports whether it did, along with every other decision made without being asked.",
+    description: "Create a browser extension project from a template in the extension.dev catalog. Call extension_templates first to see what is available. The scaffolder may initialize a git repository in the new project. Read the result's defaultsApplied block for that, and for every other decision made without being asked.",
     inputSchema: {
         type: "object",
         properties: {
@@ -1205,13 +1237,31 @@ async function create_handler(args) {
                 error: capture("error")
             }
         });
-    const failure = (err, transient)=>JSON.stringify({
-            error: transient ? "Template download failed (network/timeout/rate-limit). This is not a bad template name. Retry, or check connectivity/GitHub rate limits." : err instanceof Error ? err.message : String(err),
-            ...transient ? {
-                cause: err instanceof Error ? err.message : String(err)
-            } : {},
-            duration: Date.now() - start,
-            log: logTail()
+    const failure = (err, transient)=>transient ? envelope({
+            ok: false,
+            command: COMMAND,
+            status: "template-fetch-failed",
+            error: {
+                code: "E_TEMPLATE_FETCH",
+                message: "Template download failed (network/timeout/rate-limit). This is not a bad template name. Retry, or check connectivity/GitHub rate limits."
+            },
+            value: {
+                cause: err instanceof Error ? err.message : String(err),
+                duration: Date.now() - start,
+                log: logTail()
+            }
+        }) : envelope({
+            ok: false,
+            command: COMMAND,
+            status: "scaffold-failed",
+            error: {
+                code: "E_SCAFFOLD_FAILED",
+                message: err instanceof Error ? err.message : String(err)
+            },
+            value: {
+                duration: Date.now() - start,
+                log: logTail()
+            }
         });
     let result;
     try {
@@ -1227,13 +1277,19 @@ 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 JSON.stringify({
+    if (!hasManifest) return envelope({
         ok: false,
-        status: "incomplete",
-        projectPath: result.projectPath,
-        error: `The scaffold is incomplete: no manifest.json exists under ${result.projectPath} (checked the root and src/). Do not run extension_dev against it.`,
-        duration: Date.now() - start,
-        log: logTail(),
+        command: COMMAND,
+        status: "scaffold-incomplete",
+        error: {
+            code: "E_SCAFFOLD_INCOMPLETE",
+            message: `The scaffold is incomplete: no manifest.json exists under ${result.projectPath} (checked the root and src/). Do not run extension_dev against it.`
+        },
+        value: {
+            projectPath: result.projectPath,
+            duration: Date.now() - start,
+            log: logTail()
+        },
         hint: "Delete the directory and retry extension_create; a template download interrupted mid-way can leave a partial tree."
     });
     const packageManager = result.packageManager || (result.depsInstalled ? detectPackageManager(result.projectPath) : "npm");
@@ -1249,41 +1305,44 @@ async function create_handler(args) {
     const deployUrl = `${wwwOrigin}${(0, paths_0.wwwNewPath)({
         template: result.template
     })}`;
-    return JSON.stringify({
-        resolvedPath: result.projectPath,
-        projectPath: result.projectPath,
-        projectName: result.projectName,
-        template: result.template,
-        depsInstalled: result.depsInstalled,
-        packageManager: result.depsInstalled ? packageManager : null,
-        deployUrl,
-        defaultsApplied: {
-            parentDir: args.parentDir ? `${resolvedParent} (explicit)` : `${resolvedParent} (default: the MCP server process cwd, not yours; pass parentDir to choose)`,
-            ...void 0 === args.template ? {
-                template: "typescript (default; call extension_templates to pick another, e.g. javascript for plain JS)"
-            } : {},
-            packageManager: `${packageManager} (auto-detected by the scaffolder, not asked)`,
-            browser: "chrome (default: extension_dev and extension_build target chrome unless you pass browser)",
-            gitInit
+    return envelope({
+        ok: true,
+        command: COMMAND,
+        status: "created",
+        value: {
+            resolvedPath: result.projectPath,
+            projectPath: result.projectPath,
+            projectName: result.projectName,
+            template: result.template,
+            depsInstalled: result.depsInstalled,
+            packageManager: result.depsInstalled ? packageManager : null,
+            deployUrl,
+            defaultsApplied: {
+                parentDir: args.parentDir ? `${resolvedParent} (explicit)` : `${resolvedParent} (default: the MCP server process cwd, not yours; pass parentDir to choose)`,
+                ...void 0 === args.template ? {
+                    template: "typescript (default; call extension_templates to pick another, e.g. javascript for plain JS)"
+                } : {},
+                packageManager: `${packageManager} (auto-detected by the scaffolder, not asked)`,
+                browser: "chrome (default: extension_dev and extension_build target chrome unless you pass browser)",
+                gitInit
+            },
+            duration: Date.now() - start,
+            nextSteps: [
+                ...result.depsInstalled ? [
+                    `cd ${result.projectPath}`,
+                    runDev
+                ] : [
+                    `cd ${result.projectPath}`,
+                    `${packageManager} install`,
+                    runDev
+                ],
+                `To ship: extension_create scaffolds and runs locally, it does not host. Open ${deployUrl} to deploy this template to the web.`
+            ]
         },
-        duration: Date.now() - start,
-        nextSteps: [
-            ...result.depsInstalled ? [
-                `cd ${result.projectPath}`,
-                runDev
-            ] : [
-                `cd ${result.projectPath}`,
-                `${packageManager} install`,
-                runDev
-            ],
-            `To ship: extension_create scaffolds and runs locally, it does not host. Open ${deployUrl} to deploy this template to the web.`
-        ],
-        ...engineWarning ? {
-            engineWarning
-        } : {},
-        ...result.depsInstalled ? {} : {
-            warnings: logTail()
-        }
+        warnings: [
+            engineWarning,
+            ...result.depsInstalled ? [] : logTail()
+        ]
     });
 }
 const DEFAULT_MEDIA_ORIGIN = "https://media.extension.land";
@@ -1479,15 +1538,27 @@ async function searchTemplates(args) {
             repositoryUrl: t.repositoryUrl,
             downloads: t.downloads
         }));
-    return JSON.stringify({
-        count: results.length,
-        templates: results
+    return envelope({
+        ok: true,
+        command: "extension_templates",
+        status: "listed",
+        value: {
+            count: results.length,
+            templates: results
+        }
     });
 }
+const get_template_source_COMMAND = "extension_templates";
 async function readTemplateSource(args) {
     const template = await getTemplateBySlug(args.slug);
-    if (!template) return JSON.stringify({
-        error: `Template '${args.slug}' not found in the catalog`,
+    if (!template) return envelope({
+        ok: false,
+        command: get_template_source_COMMAND,
+        status: "template-not-found",
+        error: {
+            code: "E_TEMPLATE_NOT_FOUND",
+            message: `Template '${args.slug}' not found in the catalog`
+        },
         hint: 'Use extension_templates with action: "list" to see available templates.'
     });
     const meta = {
@@ -1500,9 +1571,14 @@ async function readTemplateSource(args) {
         keyFiles: template.keyFiles,
         repositoryUrl: template.repositoryUrl
     };
-    if (!args.files?.length) return JSON.stringify({
-        ...meta,
-        files: template.files.map((f)=>stripTemplatePathPrefix(template.slug, f)),
+    if (!args.files?.length) return envelope({
+        ok: true,
+        command: get_template_source_COMMAND,
+        status: "file-list",
+        value: {
+            ...meta,
+            files: template.files.map((f)=>stripTemplatePathPrefix(template.slug, f))
+        },
         hint: "Pass specific file paths in the files parameter to read their contents."
     });
     const fileContents = {};
@@ -1520,17 +1596,24 @@ async function readTemplateSource(args) {
         } catch  {}
         errors.push(`${filePath}: ${lastStatus || "fetch failed"}`);
     }));
-    return JSON.stringify({
-        ...meta,
-        fileContents,
-        ...errors.length ? {
-            errors
-        } : {}
+    return envelope({
+        ok: 0 === errors.length,
+        command: get_template_source_COMMAND,
+        status: errors.length ? "partial" : "read",
+        error: errors.length ? {
+            code: "E_TEMPLATE_FETCH",
+            message: `${errors.length} of ${errors.length + Object.keys(fileContents).length} file(s) could not be read from the template.`
+        } : null,
+        value: {
+            ...meta,
+            fileContents
+        },
+        warnings: errors
     });
 }
 const templates_schema = {
     name: "extension_templates",
-    description: "Browse the extension.dev template catalog. action:'list' (default) searches and filters it and returns metadata per template; action:'source' reads one template's files by `slug`, for learning a pattern before building something similar. `framework` is the UI framework ONLY, never the language: TypeScript and JavaScript templates live under slugs ('typescript', 'content-typescript'), shadcn is a React variant ('sidebar-shadcn'), and provider AIs are tagged 'ai' ('ai-chatgpt', 'ai-claude'). Reach those with query/tags/slug.",
+    description: "Browse the extension.dev template catalog. Pass action:'list' (the default) to search and filter it and get metadata per template. Pass action:'source' with a `slug` to read one template's files, for learning a pattern before building something similar. Read `framework` as the UI framework only, never the language: TypeScript and JavaScript templates live under slugs ('typescript', 'content-typescript'), shadcn is a React variant ('sidebar-shadcn'), and provider AIs carry the 'ai' tag ('ai-chatgpt', 'ai-claude'). Reach those through query, tags or slug.",
     inputSchema: {
         type: "object",
         properties: {
@@ -1595,9 +1678,14 @@ const templates_schema = {
 };
 async function templates_handler(args) {
     if ((args.action ?? "list") === "source" || !args.action && args.slug) {
-        if (!args.slug) return JSON.stringify({
+        if (!args.slug) return envelope({
             ok: false,
-            error: "action 'source' needs a slug.",
+            command: "extension_templates",
+            status: "bad-request",
+            error: {
+                code: "E_BAD_REQUEST",
+                message: "action 'source' needs a slug."
+            },
             hint: 'Call extension_templates with action: "list" to find one.'
         });
         return readTemplateSource({
@@ -1938,21 +2026,6 @@ function deadReadySession(projectPath) {
     };
     return null;
 }
-function browserExitStamp(projectPath, browser, since) {
-    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
-    try {
-        const stat = node_fs.statSync(readyPath);
-        if (stat.mtimeMs < since) return null;
-        const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-        const exited = contract?.code === "browser_exited" || contract?.browserExitCode !== void 0 || contract?.browserExitedAt !== void 0;
-        if (contract?.status === "error" && exited) return {
-            code: contract.code,
-            browserExitCode: contract.browserExitCode ?? null,
-            browserExitedAt: contract.browserExitedAt
-        };
-    } catch  {}
-    return null;
-}
 function contractBoundPort(projectPath, browser, since) {
     const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
     try {
@@ -2192,6 +2265,7 @@ function materializeCarrier(projectPath, browser) {
         };
     }
 }
+const build_COMMAND = "extension_build";
 function readBuildSummary(projectPath, browser, since) {
     const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "build-summary.json");
     try {
@@ -2289,7 +2363,7 @@ function locateSourceZip(projectPath, browser, since) {
 }
 const build_schema = {
     name: "extension_build",
-    description: "Build a browser extension for production. Outputs to dist/<browser>/. Optionally creates .zip for store submission.",
+    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.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2398,11 +2472,12 @@ async function validationPreflight(projectPath, browser) {
                 browser
             ]
         }));
+        const value = parsed?.value ?? {};
         return {
-            valid: Boolean(parsed.valid),
-            buildBlocking: Boolean(parsed.buildBlocking),
-            errors: Array.isArray(parsed.errors) ? parsed.errors : [],
-            warnings: Array.isArray(parsed.warnings) ? parsed.warnings : []
+            valid: Boolean(value.valid),
+            buildBlocking: Boolean(value.buildBlocking),
+            errors: Array.isArray(value.errors) ? value.errors : [],
+            warnings: Array.isArray(value.warnings) ? value.warnings : []
         };
     } catch  {
         return null;
@@ -2416,17 +2491,23 @@ async function build_handler(args) {
     if (carrierCleanup.removed) carrierNotes.push("Removed the Extension.dev live-preview carrier from ./extensions before building. It is a debug companion, not part of your extension; run extension_dev with carrier: true to get it back.");
     else if (carrierCleanup.note) carrierNotes.push(carrierCleanup.note);
     const preflight = args.skipValidation ? null : await validationPreflight(args.projectPath, browser);
-    if (preflight?.buildBlocking) return JSON.stringify({
-        success: false,
-        status: "blocked",
-        browser,
-        error: "Build refused: the manifest has errors that produce a broken extension even when the bundler succeeds.",
-        errors: preflight.errors,
+    if (preflight?.buildBlocking) return envelope({
+        ok: false,
+        command: build_COMMAND,
+        status: "manifest-blocked",
+        error: {
+            code: "E_MANIFEST_BLOCKING",
+            message: "Build refused: the manifest has errors that produce a broken extension even when the bundler succeeds."
+        },
+        value: {
+            browser,
+            errors: preflight.errors,
+            duration: Date.now() - start
+        },
         warnings: [
             ...carrierNotes,
             ...preflight.warnings
         ],
-        duration: Date.now() - start,
         hint: "Fix the errors above, then build again. Run extension_manifest_validate for the full report. To build anyway (for example to inspect the broken output), pass skipValidation: true."
     });
     const clobberedSessions = liveProjectSessions(args.projectPath).filter((session)=>session.browser === browser);
@@ -2454,107 +2535,268 @@ async function build_handler(args) {
         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 buildWarnings = engineSummary?.warnings?.length ? {
-            buildWarnings: engineSummary.warnings,
-            ..."number" == typeof engineSummary.warnings_count && engineSummary.warnings_count > engineSummary.warnings.length ? {
-                buildWarningsTruncated: engineSummary.warnings_count
-            } : {}
-        } : {};
+        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 JSON.stringify({
-            success: false,
-            status: "contaminated",
-            browser,
-            buildExitCode: 0,
-            error: `The build output contains the Extension.dev live-preview carrier: ${contamination.join(", ")}. That is a local debug companion and must never ship. This artifact is not safe to submit.`,
-            ...warnings.length ? {
-                warnings
-            } : {},
-            duration,
+        if (contamination.length) return 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.`
+            },
+            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."
         });
         const missing = entrypoints.filter((e)=>!e.present);
-        if (missing.length) return JSON.stringify({
-            success: false,
-            status: "incomplete",
-            browser,
-            buildExitCode: 0,
-            error: `The build reported success but ${missing.length} declared entrypoint(s) are missing from dist/${browser}: ` + missing.map((m)=>`${m.role} -> ${m.path}`).join(", ") + ". The browser will refuse to load this build.",
-            entrypoints,
-            ...preflight?.warnings.length ? {
-                manifestWarnings: preflight.warnings
-            } : {},
-            ...buildWarnings,
-            ...warnings.length ? {
-                warnings
-            } : {},
-            duration,
-            output: lastLines(out, 12),
+        if (missing.length) return envelope({
+            ok: false,
+            command: build_COMMAND,
+            status: "entrypoint-missing",
+            error: {
+                code: "E_ENTRYPOINT_MISSING",
+                message: `The build reported success but ${missing.length} declared entrypoint(s) are missing from dist/${browser}: ` + missing.map((m)=>`${m.role} -> ${m.path}`).join(", ") + ". The browser will refuse to load this build."
+            },
+            value: {
+                browser,
+                buildExitCode: 0,
+                entrypoints,
+                duration,
+                output: lastLines(out, 12)
+            },
+            warnings: [
+                ...warnings,
+                ...preflight?.warnings ?? [],
+                ...buildWarnings
+            ],
             hint: "The bundler exited 0 but did not emit these files. Check that the manifest paths match what the build produces, and that nothing references a file outside the source tree."
         });
-        return JSON.stringify({
-            success: true,
-            browser,
-            ...size ? {
-                size
-            } : {},
-            ...status ? {
-                status
-            } : {},
-            ...entrypoints.length ? {
-                entrypoints
-            } : {},
-            ...preflight?.warnings.length ? {
-                manifestWarnings: preflight.warnings
-            } : {},
-            ...buildWarnings,
-            ...(()=>{
-                const divergence = manifestDivergence(args.projectPath, browser);
-                return divergence.length ? {
+        const zipNotes = [];
+        const zipPath = args.zip ? locateDistZip(args.projectPath, browser, args.zipFilename, start) : null;
+        if (args.zip && !zipPath) zipNotes.push(`zip: true was requested and the build succeeded, but no .zip file could be located in dist/${browser}. The engine may not have packaged it; check the build output below.`);
+        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({
+            ok: true,
+            command: build_COMMAND,
+            status: "built",
+            value: {
+                browser,
+                ...size ? {
+                    size
+                } : {},
+                ...status ? {
+                    engineBuildStatus: status
+                } : {},
+                ...entrypoints.length ? {
+                    entrypoints
+                } : {},
+                ...void 0 !== buildWarningsTruncated ? {
+                    buildWarningsTruncated
+                } : {},
+                ...divergence.length ? {
                     productionDivergence: divergence
-                } : {};
-            })(),
-            ...warnings.length ? {
-                warnings
-            } : {},
-            zip: args.zip ?? false,
-            ...args.zip ? (()=>{
-                const zipPath = locateDistZip(args.projectPath, browser, args.zipFilename, start);
-                return zipPath ? {
+                } : {},
+                zip: args.zip ?? false,
+                ...zipPath ? {
                     zipPath
-                } : {
-                    zipPathNote: `zip: true was requested and the build succeeded, but no .zip file could be located in dist/${browser}. The engine may not have packaged it; check the build output below.`
-                };
-            })() : {},
-            ...args.zipSource ? (()=>{
-                const zipSourcePath = locateSourceZip(args.projectPath, browser, start);
-                return zipSourcePath ? {
+                } : {},
+                ...zipSourcePath ? {
                     zipSourcePath
-                } : {
-                    zipSourcePathNote: "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."
-                };
-            })() : {},
-            duration,
-            output: lastLines(out, 12)
+                } : {},
+                duration,
+                output: lastLines(out, 12)
+            },
+            warnings: [
+                ...warnings,
+                ...preflight?.warnings ?? [],
+                ...buildWarnings,
+                ...zipNotes
+            ]
         });
     }
     const message = stderr.trim() || out || `extension build exited with code ${code}`;
-    return JSON.stringify({
-        success: false,
-        browser,
-        error: message.slice(0, 1200),
-        ...warnings.length ? {
-            warnings
-        } : {},
-        duration,
+    return envelope({
+        ok: false,
+        command: build_COMMAND,
+        status: "build-failed",
+        error: {
+            code: "E_BUILD_FAILED",
+            message: message.slice(0, 1200)
+        },
+        value: {
+            browser,
+            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)."
     });
 }
+const NOISE = [
+    /^npm warn Unknown project config/i,
+    /This will stop working in the next major version of npm/i,
+    /^npm warn config/i,
+    /^npm warn exec/i,
+    /The following package(s)? (was|were) not found and will be installed/i,
+    /V8: .*Invalid asm\.js/i,
+    /^\(node:\d+\) V8:/i,
+    /Use `node --trace-warnings/i,
+    /Invalid asm\.js:/i,
+    /Linking failure in asm\.js/i,
+    /Successfully compiled asm\.js/i
+];
+function denoiseCliLog(raw) {
+    return raw.split("\n").filter((line)=>!NOISE.some((re)=>re.test(line.trim()))).join("\n").replace(/\n{2,}/g, "\n").trimStart();
+}
+function legacyCompileScrape(cleanOutput) {
+    return /compiled with errors|✖✖✖|ERROR in |Module not found|NOT FOUND/i.test(cleanOutput);
+}
+function legacyProfileLockScrape(cleanOutput) {
+    return /SingletonLock|ProcessSingleton|profile[^\n]*(in use|locked)|already (open|running)/i.test(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 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 stat = node_fs.statSync(file);
+        const contract = JSON.parse(node_fs.readFileSync(file, "utf8"));
+        if (!contract || "object" != typeof contract) return null;
+        return {
+            contract,
+            fresh: stat.mtimeMs >= since
+        };
+    } catch  {
+        return null;
+    }
+}
+function speaksMachineContract(contract) {
+    return !!contract && "object" == typeof contract && 1 === contract.schema;
+}
+function profileLockOwner(contract) {
+    const owner = contract.profileLockOwner;
+    if (!owner || "object" != typeof owner) return null;
+    const { host, pid } = owner;
+    return {
+        ...host ? {
+            host
+        } : {},
+        ...null != pid ? {
+            pid
+        } : {}
+    };
+}
+function contractVerdict(reading, noBrowser) {
+    const { contract, fresh } = reading;
+    if (!fresh) return null;
+    if ("error" !== contract.status) return null;
+    if (!noBrowser && contract.code === PROFILE_LOCKED_CODE) return {
+        kind: "profile-locked",
+        owner: profileLockOwner(contract),
+        message: "string" == typeof contract.message ? contract.message : void 0,
+        lockedAt: "string" == typeof contract.profileLockedAt ? contract.profileLockedAt : void 0
+    };
+    const browserExited = "browser_exited" === contract.code || void 0 !== contract.browserExitCode || void 0 !== contract.browserExitedAt;
+    if (!noBrowser && browserExited) return {
+        kind: "browser-exited",
+        stamp: {
+            code: contract.code,
+            browserExitCode: contract.browserExitCode ?? null,
+            browserExitedAt: contract.browserExitedAt
+        }
+    };
+    return {
+        kind: "compile-failed",
+        message: contract.message,
+        compileErrors: Array.isArray(contract.errors) ? contract.errors : []
+    };
+}
+async function pollBootVerdict(projectPath, browser, options) {
+    const { child, readOutput, budgetMs, since } = options;
+    const noBrowser = Boolean(options.noBrowser);
+    const intervalMs = options.intervalMs ?? 250;
+    const deadline = Date.now() + budgetMs;
+    let contractSeen = null;
+    for(;;){
+        if (null !== child.exitCode || null !== child.signalCode) return {
+            verdict: {
+                kind: "exited",
+                exitCode: child.exitCode,
+                signal: child.signalCode
+            },
+            machineContract: speaksMachineContract(contractSeen?.contract),
+            output: denoiseCliLog(readOutput()),
+            warnings: []
+        };
+        contractSeen = readContract(projectPath, browser, since) ?? contractSeen;
+        if (contractSeen) {
+            const verdict = contractVerdict(contractSeen, noBrowser);
+            if (verdict) return {
+                verdict,
+                machineContract: speaksMachineContract(contractSeen.contract),
+                output: denoiseCliLog(readOutput()),
+                warnings: []
+            };
+        }
+        if (Date.now() >= deadline) break;
+        await new Promise((resolve)=>setTimeout(resolve, Math.min(intervalMs, Math.max(deadline - Date.now(), 1))));
+    }
+    const machineContract = speaksMachineContract(contractSeen?.contract);
+    const output = denoiseCliLog(readOutput());
+    if (machineContract) return {
+        verdict: {
+            kind: "alive"
+        },
+        machineContract,
+        output,
+        warnings: []
+    };
+    if (legacyCompileScrape(output)) return {
+        verdict: {
+            kind: "compile-failed",
+            compileErrors: []
+        },
+        machineContract,
+        output,
+        warnings: [
+            LEGACY_FIDELITY_WARNING
+        ]
+    };
+    if (!noBrowser && legacyProfileLockScrape(output)) return {
+        verdict: {
+            kind: "profile-locked",
+            owner: null
+        },
+        machineContract,
+        output,
+        warnings: [
+            LEGACY_FIDELITY_WARNING
+        ]
+    };
+    return {
+        verdict: {
+            kind: "alive"
+        },
+        machineContract,
+        output,
+        warnings: []
+    };
+}
 const stop_schema = {
     name: "extension_stop",
-    description: "Stop a session that extension_dev or extension_start is running: terminates the server and the browser it launched, and removes the live-preview carrier if extension_dev placed one. Covers extension_start build:false too, which the registry still records as a preview session. Call it when you are done verifying so sessions do not accumulate.",
+    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.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2698,22 +2940,47 @@ 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 JSON.stringify({
-            stopped: [],
-            message: "No sessions registered in this server and no session markers on disk. Nothing to stop."
+        if (0 === candidates.size) return 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."
         });
         const outcomes = [];
         for (const c of candidates.values())outcomes.push(await stopOne(c.projectPath, c.browser));
-        return JSON.stringify({
-            stopped: outcomes
+        return envelope({
+            ok: outcomes.every((o)=>o.stopped),
+            command: stop_schema.name,
+            status: "stopped-all",
+            value: {
+                stopped: outcomes
+            },
+            warnings: outcomes.map((o)=>o.stopped ? null : o.detail)
         });
     }
-    if (!args.projectPath) return JSON.stringify({
-        error: "projectPath is required unless all=true. Pass the same projectPath used with extension_dev/extension_start."
+    if (!args.projectPath) return envelope({
+        ok: false,
+        command: stop_schema.name,
+        status: "bad-request",
+        error: {
+            code: "E_BAD_REQUEST",
+            message: "projectPath is required unless all=true. Pass the same projectPath used with extension_dev/extension_start."
+        }
     });
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     const outcome = await stopOne(args.projectPath, browser);
-    return JSON.stringify(outcome);
+    return envelope({
+        ok: outcome.stopped,
+        command: stop_schema.name,
+        status: null === outcome.pid ? "not-found" : outcome.stopped ? "stopped" : "still-alive",
+        value: outcome,
+        warnings: [
+            outcome.stopped ? null : outcome.detail
+        ]
+    });
 }
 const LAUNCH_FLAG_SCHEMA = {
     profile: {
@@ -2761,7 +3028,7 @@ function launchFlagArgs(args) {
 }
 const dev_schema = {
     name: "extension_dev",
-    description: "Run the extension WHILE YOU EDIT IT: dev build, hot module replacement, and a browser with it loaded. The default answer to \"run my extension\". Only this tool can unlock the control channel that extension_storage/reload/open/dom_snapshot need (allowControl) and that extension_eval needs (allowEval). For the production build in a browser instead, use extension_start. Returns process info for extension_wait and extension_inspect.",
+    description: "Run the extension while you edit it: dev build, hot module replacement, and a browser with the extension loaded. Reach for this first when the ask is \"run my extension\". ONLY this tool unlocks the control channel that extension_storage, extension_reload, extension_open and extension_dom_snapshot need (allowControl:true) and the eval channel that extension_eval needs (allowEval:true, which implies allowControl, so you never need to pass both). Use extension_start instead to run the production build in a browser. The result carries the process info that extension_wait and extension_inspect need.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2815,15 +3082,21 @@ async function dev_handler(args) {
     if (existing.length > 0) {
         if (!args.replace) {
             const listed = existing.map((s)=>`pid ${s.pid} (${s.browser})`).join(", ");
-            return JSON.stringify({
+            return envelope({
                 ok: false,
+                command: dev_schema.name,
                 status: "session-exists",
-                projectPath: args.projectPath,
-                sessions: existing.map((s)=>({
-                        pid: s.pid,
-                        browser: s.browser
-                    })),
-                error: `A dev session is already running for this project (${listed}). Starting another would fork the session: both browsers contend for the same profile and the new one dies on the profile lock.`,
+                error: {
+                    code: "E_SESSION_EXISTS",
+                    message: `A dev session is already running for this project (${listed}). Starting another would fork the session: both browsers contend for the same profile and the new one dies on the profile lock.`
+                },
+                value: {
+                    projectPath: args.projectPath,
+                    sessions: existing.map((s)=>({
+                            pid: s.pid,
+                            browser: s.browser
+                        }))
+                },
                 hint: "Call extension_stop with this projectPath first, or pass replace: true to have extension_dev stop the old session before starting the new one."
             });
         }
@@ -2864,55 +3137,101 @@ async function dev_handler(args) {
         noBrowser: Boolean(args.noBrowser)
     });
     child.on("exit", ()=>removeSession(args.projectPath, browser));
-    await new Promise((resolve)=>setTimeout(resolve, 3000));
-    const earlyOutput = spawned.readOutput();
-    const cleanOutput = denoiseEarlyOutput(earlyOutput);
-    if (null !== child.exitCode || null !== child.signalCode) {
-        const code = child.exitCode;
-        const signal = child.signalCode;
-        return JSON.stringify({
+    const boot = await pollBootVerdict(args.projectPath, browser, {
+        child,
+        readOutput: spawned.readOutput,
+        budgetMs: 3000,
+        since: spawnedAt,
+        noBrowser: Boolean(args.noBrowser)
+    });
+    const cleanOutput = boot.output;
+    const session = {
+        projectPath: args.projectPath,
+        browser,
+        pid,
+        logPath
+    };
+    if ("exited" === boot.verdict.kind) {
+        const { exitCode: code, signal } = boot.verdict;
+        return envelope({
             ok: false,
+            command: dev_schema.name,
             status: "exited",
-            projectPath: args.projectPath,
-            browser,
-            pid,
-            exitCode: code,
-            signal,
-            error: `The dev server exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running, so extension_logs/wait/eval and the control verbs have nothing to attach to.`,
-            output: cleanOutput.slice(0, 2000),
-            logPath,
-            hint: "Read `output` above for the cause: a port already in use, a manifest the build rejects, or a missing browser binary are the common ones. Fix it and call extension_dev again; extension_doctor with this projectPath will also report what the last session recorded."
+            error: {
+                code: "E_SESSION_EXITED",
+                message: `The dev server exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running, so extension_logs/wait/eval and the control verbs have nothing to attach to.`
+            },
+            value: {
+                ...session,
+                exitCode: code,
+                signal,
+                output: cleanOutput.slice(0, 2000)
+            },
+            hint: "Read `value.output` above for the cause: a port already in use, a manifest the build rejects, or a missing browser binary are the common ones. Fix it and call extension_dev again; extension_doctor with this projectPath will also report what the last session recorded.",
+            warnings: boot.warnings
         });
     }
-    const compileFailed = /compiled with errors|✖✖✖|ERROR in |Module not found|NOT FOUND/i.test(cleanOutput);
-    if (compileFailed) return JSON.stringify({
-        ok: false,
-        status: "compile-failed",
-        projectPath: args.projectPath,
-        browser,
-        pid,
-        error: "The dev server started but the FIRST COMPILE FAILED, so the browser has nothing usable to load. The session is running; the extension is not.",
-        output: cleanOutput.slice(0, 2000),
-        logPath,
-        hint: "Fix the compile error in `output` above and save: the dev server is still running and will recompile. Do not call extension_wait yet, it will report ready for a build that failed."
-    });
-    const exitStamp = args.noBrowser ? null : browserExitStamp(args.projectPath, browser, spawnedAt);
-    const profileLockHit = !args.noBrowser && /SingletonLock|ProcessSingleton|profile[^\n]*(in use|locked)|already (open|running)/i.test(cleanOutput);
-    if (exitStamp || profileLockHit) {
-        const profileDir = node_path.join(args.projectPath, "dist", `extension-profile-${browser}`);
-        return JSON.stringify({
+    if ("compile-failed" === boot.verdict.kind) {
+        const { compileErrors } = boot.verdict;
+        return envelope({
             ok: false,
-            status: "browser-exited",
-            projectPath: args.projectPath,
-            browser,
-            pid,
-            ...exitStamp ?? {},
-            error: `The dev server is running but the ${browser} browser it launched died during startup` + (profileLockHit ? " because its profile is locked by another browser instance." : "."),
-            output: cleanOutput.slice(0, 2000),
-            logPath,
-            hint: `A locked profile means another session's browser still holds it: call extension_stop with this projectPath to kill that session, then start extension_dev again. If the lock survives a crash, remove ${profileDir} manually before retrying.`
+            command: dev_schema.name,
+            status: "compile-failed",
+            error: {
+                code: "E_FIRST_COMPILE",
+                message: boot.verdict.message ?? "The dev server started but the first compile failed, so the browser has nothing usable to load. The session is running; the extension is not."
+            },
+            value: {
+                ...session,
+                compileErrors,
+                ...compileErrors.length ? {} : {
+                    output: cleanOutput.slice(0, 2000)
+                }
+            },
+            hint: "Fix the compile error listed in `value.compileErrors` and save: the dev server is still running and will recompile. Do not call extension_wait yet, it will report ready for a build that failed.",
+            warnings: boot.warnings
         });
     }
+    const profileDir = node_path.join(args.projectPath, "dist", `extension-profile-${browser}`);
+    if ("profile-locked" === boot.verdict.kind) {
+        const { owner, lockedAt } = boot.verdict;
+        return envelope({
+            ok: false,
+            command: dev_schema.name,
+            status: "profile-locked",
+            error: {
+                code: "E_PROFILE_LOCKED",
+                message: boot.verdict.message ?? `The dev server is running but the ${browser} browser it launched died during startup because its profile is locked by another browser instance` + (owner?.pid ? ` (pid ${owner.pid}${owner.host ? ` on ${owner.host}` : ""})` : "") + "."
+            },
+            value: {
+                ...session,
+                profileDir,
+                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.`,
+            warnings: boot.warnings
+        });
+    }
+    if ("browser-exited" === boot.verdict.kind) return envelope({
+        ok: false,
+        command: dev_schema.name,
+        status: "browser-exited",
+        error: {
+            code: "E_BROWSER_EXITED",
+            message: `The dev server is running but the ${browser} browser it launched died during startup.`
+        },
+        value: {
+            ...session,
+            ...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.`,
+        warnings: boot.warnings
+    });
     const controlVerbs = "storage, reload, open, dom_snapshot";
     const capabilities = {
         allowControl,
@@ -2931,54 +3250,43 @@ async function dev_handler(args) {
     const portReport = null !== boundPort ? {
         port: boundPort,
         ...void 0 !== args.port && args.port !== boundPort ? {
-            requestedPort: args.port,
-            portNote: `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).`
+            requestedPort: args.port
         } : {}
     } : {
-        requestedPort: args.port ?? 8080,
-        portNote: "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."
+        requestedPort: args.port ?? 8080
     };
-    return JSON.stringify({
+    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({
         ok: true,
-        pid,
-        browser,
-        ...portReport,
-        projectPath: args.projectPath,
+        command: dev_schema.name,
         status: "started",
-        ...carrier ? {
-            carrier
-        } : {},
-        ...replaced.length > 0 ? {
-            replacedSession: replaced[0],
-            ...replaced.length > 1 ? {
-                replacedSessions: replaced
-            } : {}
-        } : {},
-        capabilities,
-        hint: args.noBrowser ? "Build-only session (noBrowser: true): no browser will launch, so no runtime will ever attach. extension_wait returns as soon as the first compile lands (compiled: true, browserAttached: false) instead of waiting out its budget; do not wait for a browser. The control verbs (storage/reload/open/dom_snapshot/eval) need a live browser and will not work against this session. When you are done, call extension_stop to shut down the dev server." : "Use extension_wait to check when the extension is fully loaded, then extension_inspect to inspect the live state. " + (allowControl ? `Control channel is ON: extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : "Control channel is OFF: extension_storage/reload/open/dom_snapshot need allowControl: true, and extension_eval needs allowEval: true (which also implies allowControl). To unlock them, call extension_dev again with the flag you need plus replace: true (it stops this session first); a plain second call is refused so the session does not fork.") + " When you are done, call extension_stop to shut down the dev server and browser.",
-        earlyOutput: cleanOutput.slice(0, 500),
-        logPath
+        value: {
+            pid,
+            browser,
+            ...portReport,
+            projectPath: args.projectPath,
+            ...carrier ? {
+                carrier
+            } : {},
+            ...replaced.length > 0 ? {
+                replacedSession: replaced[0],
+                ...replaced.length > 1 ? {
+                    replacedSessions: replaced
+                } : {}
+            } : {},
+            capabilities,
+            logPath
+        },
+        warnings: [
+            portNote,
+            ...boot.warnings
+        ],
+        hint: args.noBrowser ? "Build-only session (noBrowser: true): no browser will launch, so no runtime will ever attach. extension_wait returns as soon as the first compile lands (compiled: true, browserAttached: false) instead of waiting out its budget; do not wait for a browser. The control verbs (storage/reload/open/dom_snapshot/eval) need a live browser and will not work against this session. When you are done, call extension_stop to shut down the dev server." : "Use extension_wait to check when the extension is fully loaded, then extension_inspect to inspect the live state. " + (allowControl ? `Control channel is ON: extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : "Control channel is OFF: extension_storage/reload/open/dom_snapshot need allowControl: true, and extension_eval needs allowEval: true (which also implies allowControl). To unlock them, call extension_dev again with the flag you need plus replace: true (it stops this session first); a plain second call is refused so the session does not fork.") + " When you are done, call extension_stop to shut down the dev server and browser."
     });
 }
-function denoiseEarlyOutput(raw) {
-    const NOISE = [
-        /^npm warn Unknown project config/i,
-        /This will stop working in the next major version of npm/i,
-        /^npm warn config/i,
-        /^npm warn exec/i,
-        /The following package(s)? (was|were) not found and will be installed/i,
-        /V8: .*Invalid asm\.js/i,
-        /^\(node:\d+\) V8:/i,
-        /Use `node --trace-warnings/i,
-        /Invalid asm\.js:/i,
-        /Linking failure in asm\.js/i,
-        /Successfully compiled asm\.js/i
-    ];
-    return raw.split("\n").filter((line)=>!NOISE.some((re)=>re.test(line.trim()))).join("\n").replace(/\n{2,}/g, "\n").trimStart();
-}
 const start_schema = {
     name: "extension_start",
-    description: "Run the PRODUCTION build in a browser: builds the project, then serves it and launches. No hot module replacement and no control channel, so your edits are not picked up and extension_eval/storage/reload/open/dom_snapshot cannot attach to this session. Use extension_dev while writing code; use this to check what actually ships. Pass build:false to launch on an existing dist/<browser> without rebuilding.",
+    description: "Run the PRODUCTION build in a browser: build the project, serve it, and launch. There is no hot module replacement and no control channel, so your edits are not picked up and extension_eval, extension_storage, extension_reload, extension_open and extension_dom_snapshot cannot attach to this session. Use extension_dev while writing code, and this to check what actually ships. Pass build:false to launch an existing dist/<browser> without rebuilding.",
     inputSchema: {
         type: "object",
         properties: {
@@ -3037,54 +3345,106 @@ async function start_handler(args) {
         command
     });
     child.on("exit", ()=>removeSession(args.projectPath, browser));
-    await new Promise((resolve)=>setTimeout(resolve, 5000));
-    const earlyOutput = spawned.readOutput();
-    if (null !== child.exitCode || null !== child.signalCode) {
-        const code = child.exitCode;
-        const signal = child.signalCode;
-        return JSON.stringify({
+    const boot = await pollBootVerdict(args.projectPath, browser, {
+        child,
+        readOutput: spawned.readOutput,
+        budgetMs: 5000,
+        since: spawnedAt,
+        noBrowser: Boolean(args.noBrowser)
+    });
+    const cleanOutput = boot.output;
+    const session = {
+        projectPath: args.projectPath,
+        browser,
+        pid,
+        logPath
+    };
+    if ("exited" === boot.verdict.kind) {
+        const { exitCode: code, signal } = boot.verdict;
+        return envelope({
             ok: false,
+            command: start_schema.name,
             status: "exited",
-            projectPath: args.projectPath,
-            browser,
-            pid,
-            exitCode: code,
-            signal,
-            error: `The ${command} process exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running.`,
-            output: earlyOutput.slice(0, 2000),
-            logPath,
-            hint: building ? "Read `output` above for the cause: a failed production build, a port already in use, or a missing browser binary are the common ones. extension_build will surface a build error on its own." : "Read `output` above for the cause: a missing or broken dist/ (run extension_build first, or drop build:false), or a missing browser binary are the common ones."
+            error: {
+                code: "E_SESSION_EXITED",
+                message: `The ${command} process exited during startup (${signal ? `signal ${signal}` : `exit code ${code}`}). No session is running.`
+            },
+            value: {
+                ...session,
+                exitCode: code,
+                signal,
+                output: cleanOutput.slice(0, 2000)
+            },
+            hint: building ? "Read `value.output` above for the cause: a failed production build, a port already in use, or a missing browser binary are the common ones. extension_build will surface a build error on its own." : "Read `value.output` above for the cause: a missing or broken dist/ (run extension_build first, or drop build:false), or a missing browser binary are the common ones.",
+            warnings: boot.warnings
         });
     }
-    const exitStamp = browserExitStamp(args.projectPath, browser, spawnedAt);
-    if (exitStamp) return JSON.stringify({
-        ok: false,
-        status: "browser-exited",
-        projectPath: args.projectPath,
-        browser,
-        pid,
-        ...exitStamp,
-        error: `The ${command} process is running but the browser it launched has exited (the extension may have been rejected or the browser crashed). The session cannot be driven.`,
-        output: earlyOutput.slice(0, 2000),
-        logPath,
-        hint: "Read `output` above and extension_logs for the cause, then call extension_stop to clean up before retrying."
-    });
-    return JSON.stringify({
+    if ("compile-failed" === boot.verdict.kind) {
+        const { compileErrors } = boot.verdict;
+        return envelope({
+            ok: false,
+            command: start_schema.name,
+            status: "compile-failed",
+            error: {
+                code: "E_FIRST_COMPILE",
+                message: boot.verdict.message ?? `The ${command} process is running but the build failed, so the browser has nothing usable to load.`
+            },
+            value: {
+                ...session,
+                buildErrors: compileErrors,
+                ...compileErrors.length ? {} : {
+                    output: cleanOutput.slice(0, 2000)
+                }
+            },
+            hint: "Fix the build error listed in `value.buildErrors`, then call extension_start again. extension_build reports the same failure on its own.",
+            warnings: boot.warnings
+        });
+    }
+    if ("browser-exited" === boot.verdict.kind || "profile-locked" === boot.verdict.kind) {
+        const stamp = "browser-exited" === boot.verdict.kind ? boot.verdict.stamp : {};
+        return envelope({
+            ok: false,
+            command: start_schema.name,
+            status: boot.verdict.kind,
+            error: {
+                code: "profile-locked" === boot.verdict.kind ? "E_PROFILE_LOCKED" : "E_BROWSER_EXITED",
+                message: `The ${command} process is running but the browser it launched has exited (the extension may have been rejected or the browser crashed). The session cannot be driven.`
+            },
+            value: {
+                ...session,
+                ...stamp,
+                output: cleanOutput.slice(0, 2000)
+            },
+            hint: "Read `value.output` above and extension_logs for the cause, then call extension_stop to clean up before retrying.",
+            warnings: boot.warnings
+        });
+    }
+    return envelope({
         ok: true,
-        pid,
-        browser,
-        projectPath: args.projectPath,
+        command: start_schema.name,
         status: building ? "started" : "launched",
+        value: {
+            pid,
+            browser,
+            projectPath: args.projectPath,
+            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.",
-        earlyOutput: earlyOutput.slice(0, 500),
-        logPath
+        warnings: boot.warnings
     });
 }
 function toMcpSpeak(text) {
     return text.replace(/`?extension dev(?: [^\s`]*)? --browser[= ]([\w-]+) --allow-control`?/g, 'extension_dev with { browser: "$1", allowControl: true }').replace(/--allow-control/g, "allowControl: true (extension_dev)").replace(/--allow-eval/g, "allowEval: true (extension_dev)").replace(/Use --context page --tab <id>/g, 'Use context: "page" (targets the active tab; pass url or tab to pick another)').replace(/--context[= ](background|popup|options|sidebar|devtools|newtab|history|bookmarks|content|page)\b/g, 'context: "$1"').replace(/--tab[= ](\d+|<[\w-]+>)/g, "tab: $1").replace(/--url[= ]"([^"]+)"/g, 'url: "$1"').replace(/--url[= ](<[\w-]+>|\S*(?:\/\/|\*)\S*)/g, 'url: "$1"').replace(/--browser[= ]([\w]+-based|chrome|chromium|edge|brave|opera|vivaldi|yandex|firefox|waterfox|librewolf|safari)\b/g, 'browser: "$1"').replace(/--timeout[= ](\d+)/g, "timeout: $1").replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev").replace(/--tab\b/g, "`tab`").replace(/--url\b/g, "`url`").replace(/--context\b/g, "`context`").replace(/--browser\b/g, "`browser`").replace(/--timeout\b/g, "`timeout`");
 }
-function withSessionContext(message, projectPath) {
-    const isControlError = /no active control channel|control channel refused|\b1006\b|no executor connected|is the session started with allowControl/i.test(message);
+const CONTROL_CODES = new Set([
+    "E_CONTROL_DENIED",
+    "E_CONTROL_UNAVAILABLE",
+    "E_NO_CONTROL_CHANNEL",
+    "E_NOT_ATTACHED",
+    "E_SESSION_NOT_FOUND"
+]);
+function withSessionContext(message, projectPath, code) {
+    const isControlError = code ? CONTROL_CODES.has(code) : /no active control channel|control channel refused|\b1006\b|no executor connected|is the session started with allowControl/i.test(message);
     if (!isControlError) return message;
     const dead = deadReadySession(projectPath);
     if (dead) return `${message}\nLikely cause: the dev server has exited, ${dead.browser} ready.json still says ready but its pid ${dead.pid} is dead. Restart with extension_dev (this is not an allowControl problem); extension_doctor confirms.`;
@@ -3094,12 +3454,61 @@ function withSessionContext(message, projectPath) {
 }
 function translateFrame(frame, projectPath) {
     if (!frame || false !== frame.ok) return frame;
-    if (frame.error && "string" == typeof frame.error.message) frame.error.message = withSessionContext(toMcpSpeak(frame.error.message), projectPath);
+    if (frame.error && "string" == typeof frame.error.message) frame.error.message = withSessionContext(toMcpSpeak(frame.error.message), projectPath, "string" == typeof frame.error.code ? frame.error.code : void 0);
     if ("string" == typeof frame.error?.hint) frame.error.hint = toMcpSpeak(frame.error.hint);
     if ("string" == typeof frame.hint) frame.hint = toMcpSpeak(frame.hint);
     return frame;
 }
-async function runActVerb(args, projectPath, timeoutMs) {
+const VERB_TOOL = {
+    eval: "extension_eval",
+    inspect: "extension_dom_snapshot",
+    open: "extension_open",
+    reload: "extension_reload",
+    storage: "extension_storage"
+};
+const LEGACY_CODES = {
+    BadRequest: "E_BAD_REQUEST",
+    CliError: "E_CLI",
+    NoSession: "E_NO_SESSION"
+};
+function wrapLegacyFrame(frame, command) {
+    const { ok, value, truncated, error, hint, note, notes, warning, ...extras } = frame;
+    const raw = error ?? {};
+    const name = "string" == typeof raw.name ? raw.name : void 0;
+    const wrapped = envelopeObject({
+        ok: true === ok,
+        command,
+        status: true === ok ? "ok" : "failed",
+        value: void 0 === value ? null : value,
+        error: true === ok ? null : {
+            code: "string" == typeof raw.code && raw.code ? raw.code : name && LEGACY_CODES[name] || "E_CLI",
+            message: "string" == typeof raw.message ? raw.message : "command failed",
+            ...name ? {
+                name
+            } : {},
+            ...void 0 !== raw.engine ? {
+                engine: raw.engine
+            } : {}
+        },
+        ...true === truncated ? {
+            truncated: true
+        } : {},
+        ..."string" == typeof hint ? {
+            hint
+        } : {},
+        warnings: [
+            "string" == typeof note ? note : null,
+            "string" == typeof warning ? warning : null,
+            ...Array.isArray(notes) ? notes.map((n)=>String(n)) : []
+        ]
+    });
+    return {
+        ...extras,
+        ...wrapped
+    };
+}
+async function runActVerb(args, projectPath, timeoutMs, tool) {
+    const command = tool ?? VERB_TOOL[args[0]] ?? "extension_act";
     const { code, stdout, stderr } = await runExtensionCli([
         ...args,
         "--output",
@@ -3110,19 +3519,44 @@ async function runActVerb(args, projectPath, timeoutMs) {
     });
     const out = stdout.trim();
     if (out) try {
-        const frame = JSON.parse(out);
-        if (frame && false === frame.ok) return JSON.stringify(translateFrame(frame, projectPath));
-        return out;
+        const frame = translateFrame(JSON.parse(out), projectPath);
+        if (isEnvelope(frame)) {
+            frame.command = command;
+            if (!Array.isArray(frame.warnings)) frame.warnings = [];
+            return JSON.stringify(frame);
+        }
+        if (frame && "object" == typeof frame) return JSON.stringify(wrapLegacyFrame(frame, command));
     } catch  {}
     const message = stderr.trim() || `extension exited with code ${code}`;
-    return JSON.stringify({
+    return envelope({
         ok: false,
+        command,
+        status: "cli-failed",
         error: {
+            code: "E_CLI",
             name: "CliError",
             message: withSessionContext(toMcpSpeak(message), projectPath)
         }
     });
 }
+function addWarning(frame, text) {
+    if ("string" != typeof text || !text.trim()) return;
+    if (!Array.isArray(frame.warnings)) frame.warnings = [];
+    if (!frame.warnings.includes(text)) frame.warnings.push(text);
+}
+function actFrameJson(frame) {
+    return JSON.stringify(frame);
+}
+function patchValue(frame, patch) {
+    const current = frame.value;
+    if (current && "object" == typeof current && !Array.isArray(current)) return void Object.assign(current, patch);
+    frame.value = null == current ? {
+        ...patch
+    } : {
+        result: current,
+        ...patch
+    };
+}
 function commonFlags(args) {
     const flags = [];
     if (args.context) flags.push("--context", args.context);
@@ -3609,7 +4043,7 @@ function isCdpEndpoint(port) {
         });
     });
 }
-async function listBridgeTabs(projectPath, browser, timeout) {
+async function listBridgeTabs(projectPath, browser, timeout, tool = "extension_dom_snapshot") {
     const raw = await runActVerb([
         "inspect",
         projectPath,
@@ -3620,7 +4054,7 @@ async function listBridgeTabs(projectPath, browser, timeout) {
             "--timeout",
             String(timeout)
         ] : []
-    ], projectPath, timeout);
+    ], projectPath, timeout, tool);
     let parsed;
     try {
         parsed = JSON.parse(raw);
@@ -3662,7 +4096,7 @@ async function pollForBridgeTab(projectPath, browser, url, budgetMs) {
         await new Promise((r)=>setTimeout(r, 250));
     }
 }
-async function navigateToUrlViaBridge(projectPath, browser, url, timeout) {
+async function navigateToUrlViaBridge(projectPath, browser, url, timeout, tool = "extension_open") {
     const expression = `(async () => { const api = typeof browser !== "undefined" ? browser : chrome; const tabs = await api.tabs.query({ active: true, currentWindow: true }); const active = tabs && tabs[0]; const tab = active && active.id != null ? await api.tabs.update(active.id, { url: ${JSON.stringify(url)} }) : await api.tabs.create({ url: ${JSON.stringify(url)} }); return { tabId: tab && tab.id != null ? tab.id : null }; })()`;
     const raw = await runActVerb([
         "eval",
@@ -3676,32 +4110,39 @@ async function navigateToUrlViaBridge(projectPath, browser, url, timeout) {
             "--timeout",
             String(timeout)
         ] : []
-    ], projectPath, timeout);
+    ], projectPath, timeout, tool);
     try {
         const parsed = JSON.parse(raw);
-        if (parsed?.ok === false) {
-            if (!parsed.hint) parsed.hint = "On this browser family URL navigation rides the agent bridge (a background eval of tabs.update), so the dev session must be started with allowEval: true (extension_dev).";
-            return JSON.stringify(parsed);
-        }
+        if (parsed?.ok === false) return actFrameJson(parsed.hint ? parsed : {
+            ...parsed,
+            hint: "On this browser family URL navigation rides the agent bridge (a background eval of tabs.update), so the dev session must be started with allowEval: true (extension_dev)."
+        });
     } catch  {
         return raw;
     }
     const settled = await pollForBridgeTab(projectPath, browser, url, null != timeout ? Math.min(timeout, 6000) : 6000);
-    if (!settled) return JSON.stringify({
+    if (!settled) return envelope({
         ok: false,
+        command: tool,
+        status: "navigate-failed",
         error: {
+            code: "E_NAVIGATE_FAILED",
             name: "NavigateFailed",
             message: `Navigation to ${url} did not produce a tab reporting that URL. The URL may not exist, or the browser refused the navigation (Firefox rejects privileged about:/chrome: URLs and other extensions' moz-extension: pages).`
         },
         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 JSON.stringify({
+    return envelope({
         ok: true,
-        navigated: url,
-        tab: {
-            tabId: settled.tabId,
-            url: settled.url,
-            title: settled.title
+        command: tool,
+        status: "navigated",
+        value: {
+            navigated: url,
+            tab: {
+                tabId: settled.tabId,
+                url: settled.url,
+                title: settled.title
+            }
         },
         hint: "Inspect it with extension_dom_snapshot or extension_eval using url or this numeric tab id (context: 'page'/'content')."
     });
@@ -3763,9 +4204,12 @@ 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 JSON.stringify({
+    if (!resolved) return envelope({
         ok: false,
+        command: open_schema.name,
+        status: "no-session",
         error: {
+            code: "E_NO_SESSION",
             name: "NoSession",
             message: `No active dev session / CDP port for ${browser}. Start extension_dev and extension_wait for ready. ${CDP_PORT_MISSING_HINT}`
         }
@@ -3796,38 +4240,48 @@ 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 JSON.stringify({
+            return envelope({
                 ok: false,
+                command: open_schema.name,
+                status: "navigate-failed",
                 error: {
+                    code: "E_NAVIGATE_FAILED",
                     name: "NavigateFailed",
                     message: `Navigation to ${url} did not produce a live page target. ${isExtensionPage ? "The URL may not exist in the extension bundle, or Chrome refused the navigation." : "The page may have failed to load, or the browser refused the navigation."}`
                 },
                 hint: isExtensionPage ? "Confirm the path exists in the built dist (extension_build / extension_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 JSON.stringify({
+        return envelope({
             ok: true,
-            navigated: url,
-            ...openedNewTab ? {
-                openedNewTab: true
-            } : {},
-            ...settled.redirectedFrom ? {
-                redirected: {
-                    from: settled.redirectedFrom,
-                    to: settled.url
+            command: open_schema.name,
+            status: "navigated",
+            value: {
+                navigated: url,
+                ...openedNewTab ? {
+                    openedNewTab: true
+                } : {},
+                ...settled.redirectedFrom ? {
+                    redirected: {
+                        from: settled.redirectedFrom,
+                        to: settled.url
+                    }
+                } : {},
+                target: {
+                    targetId: settled.id,
+                    title: settled.title,
+                    url: settled.url
                 }
-            } : {},
-            target: {
-                targetId: settled.id,
-                title: settled.title,
-                url: settled.url
             },
             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 JSON.stringify({
+        return envelope({
             ok: false,
+            command: open_schema.name,
+            status: "navigate-failed",
             error: {
+                code: "E_NAVIGATE_ERROR",
                 name: "NavigateError",
                 message: e instanceof Error ? e.message : String(e)
             }
@@ -3941,9 +4395,12 @@ function declaredSurfaces(projectPath, browser) {
 }
 function missingSurfaceError(projectPath, browser, surface, consequence) {
     const declared = declaredSurfaces(projectPath, browser);
-    if (null === declared) return JSON.stringify({
+    if (null === declared) return envelope({
         ok: false,
+        command: open_schema.name,
+        status: "no-manifest",
         error: {
+            code: "E_MANIFEST_NOT_FOUND",
             name: "NoSurfaceDocument",
             message: `No readable manifest was found for this project (checked dist/${browser}, dist, src, and the project root), so the ${surface} document cannot be resolved.`
         },
@@ -3952,15 +4409,18 @@ 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 JSON.stringify({
+    return envelope({
         ok: false,
+        command: open_schema.name,
+        status: "no-surface",
         error: {
+            code: "E_NO_SURFACE_DOCUMENT",
             name: "NoSurfaceDocument",
             message: `This extension declares no ${surface}: nothing in its manifest sets ${key}, ${consequence}. That is how the extension is built, not a failure of the session or the tooling.`
         },
-        ...others.length ? {
+        value: others.length ? {
             declaredSurfaces: others
-        } : {},
+        } : null,
         hint: (others.length ? `Surfaces this extension does declare: ${others.join(", ")}; extension_open can target those. ` : "The manifest declares no other UI surface documents either. ") + nextVerb
     });
 }
@@ -4027,9 +4487,12 @@ async function openSurfaceAsTab(projectPath, browser, surface) {
     let extensionId = null;
     if (isChromiumFamily(browser)) {
         extensionId = await resolveExtensionId(projectPath, browser);
-        if (!extensionId) return JSON.stringify({
+        if (!extensionId) return envelope({
             ok: false,
+            command: open_schema.name,
+            status: "no-extension-id",
             error: {
+                code: "E_NO_EXTENSION_ID",
                 name: "NoExtensionId",
                 message: "Could not resolve the extension id from the live session's CDP targets."
             },
@@ -4038,9 +4501,12 @@ async function openSurfaceAsTab(projectPath, browser, surface) {
         url = `chrome-extension://${extensionId}/${doc}`;
     } else {
         const base = await resolveBridgeBaseUrl(projectPath, browser);
-        if (!base) return JSON.stringify({
+        if (!base) return envelope({
             ok: false,
+            command: open_schema.name,
+            status: "no-extension-id",
             error: {
+                code: "E_NO_EXTENSION_ID",
                 name: "NoExtensionId",
                 message: "Could not resolve the extension's moz-extension:// base URL from the live session (a background eval of runtime.getURL)."
             },
@@ -4053,18 +4519,22 @@ async function openSurfaceAsTab(projectPath, browser, surface) {
     try {
         const parsed = JSON.parse(raw);
         if (parsed?.ok) {
-            parsed.renderedAsTab = {
+            const renderedAsTab = {
                 surface,
                 document: doc,
                 extensionId
             };
+            patchValue(parsed, {
+                renderedAsTab
+            });
+            const target = parsed.value?.target ?? parsed.target;
             let popupBounds = null;
-            if (("popup" === surface || "action" === surface) && "string" == typeof parsed.target?.targetId) {
-                popupBounds = await applyPopupBounds(projectPath, browser, parsed.target.targetId);
-                if (popupBounds) parsed.renderedAsTab.popupBounds = popupBounds;
+            if (("popup" === surface || "action" === surface) && "string" == typeof target?.targetId) {
+                popupBounds = await applyPopupBounds(projectPath, browser, target.targetId);
+                if (popupBounds) renderedAsTab.popupBounds = popupBounds;
             }
             parsed.hint = `Rendered the ${surface} document in a real tab, which is how you inspect a surface headlessly. ` + (popupBounds ? `The window was resized to the popup's content size (${popupBounds.width}x${popupBounds.height}${popupBounds.clamped ? ", clamped to Chrome's 25x25-800x600 popup bounds" : ""}), approximating real popup rendering. This resizes the WHOLE browser window for the session. It is the same page with the same extension APIs, but window.close() closes the tab. ` : "It is the same page with the same extension APIs, but it is NOT hosted in a popup window: no popup sizing, and window.close() closes the tab. ") + `Inspect it with extension_dom_snapshot context: '${surface}' (include: ['html']), or extension_inspect with this url. ` + "Do NOT pass this extension-page url to extension_dom_snapshot or extension_eval as a tab target: script injection cannot reach extension pages, only the surface context or CDP can.";
-            return JSON.stringify(parsed);
+            return actFrameJson(parsed);
         }
     } catch  {}
     return raw;
@@ -4086,25 +4556,32 @@ async function confirmSurfaceTarget(projectPath, browser, surface, raw) {
     const wanted = `chrome-extension://${extensionId}/${doc}`;
     const settled = await pollForTarget(resolved.port, wanted, 3000);
     if (settled) {
-        parsed.surfaceTarget = {
-            targetId: settled.id,
-            url: settled.url
-        };
-        return JSON.stringify(parsed);
+        patchValue(parsed, {
+            surfaceTarget: {
+                targetId: settled.id,
+                url: settled.url
+            }
+        });
+        return actFrameJson(parsed);
     }
-    return JSON.stringify({
+    return envelope({
         ok: false,
+        command: open_schema.name,
+        status: "surface-did-not-open",
         error: {
+            code: "E_SURFACE_DID_NOT_OPEN",
             name: "SurfaceDidNotOpen",
             message: `The engine reported the ${surface} as opened, but no page target for ${wanted} appeared within 3s, so nothing is there to inspect.`
         },
-        engineResult: parsed,
+        value: {
+            engineResult: parsed
+        },
         hint: `Retry with asTab: true to render ${doc} in a real tab, which works headed or headless. If you expected a window, check that the session is headed and that the surface is declared in the BUILT manifest.`
     });
 }
 const open_schema = {
     name: "extension_open",
-    description: "Open an extension surface or replay an event in a running session. popup/options/sidebar open UI surfaces; newtab/history/bookmarks open the matching chrome_url_overrides page in a tab. 'action' triggers the toolbar action, opening its popup or replaying chrome.action.onClicked when there is none; 'command' replays a chrome.commands.onCommand shortcut (pass `name`). NOTE: action/command replay invokes your listener WITHOUT a user gesture, so the gesture-derived activeTab grant does not apply (the result reports gesture:false and warns when activeTab is declared). Requires the session to have been started with allowControl: true (extension_dev).",
+    description: "Open an extension surface, or replay an event, in a running session. Pass surface:'popup', 'options' or 'sidebar' to open a UI surface, or 'newtab', 'history' or 'bookmarks' to open the matching chrome_url_overrides page in a tab. Pass surface:'action' to trigger the toolbar action, which opens its popup or replays chrome.action.onClicked when there is none. Pass surface:'command' with `name` to replay a chrome.commands.onCommand shortcut. Note that action and command replay invoke your listener without a user gesture, so the gesture-derived activeTab grant does not apply; the result reports gesture:false and warns when activeTab is declared. Start the session with allowControl:true (extension_dev).",
     inputSchema: {
         type: "object",
         properties: {
@@ -4161,22 +4638,30 @@ 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 JSON.stringify({
+    if (!args.surface) return envelope({
         ok: false,
+        command: open_schema.name,
+        status: "bad-request",
         error: {
+            code: "E_BAD_REQUEST",
             name: "BadRequest",
             message: "Pass `surface` (popup/options/sidebar/action/command) to open a surface, or `url` to navigate a tab."
         }
     });
     if ("command" === args.surface) {
         const declared = declaredCommands(args.projectPath, browser);
-        if (declared && args.name && !declared.includes(args.name)) return JSON.stringify({
+        if (declared && args.name && !declared.includes(args.name)) return envelope({
             ok: false,
+            command: open_schema.name,
+            status: "unknown-command",
             error: {
+                code: "E_UNKNOWN_COMMAND",
                 name: "UnknownCommand",
                 message: `"${args.name}" is not declared in the manifest's \`commands\`, so triggering it can only ever be a no-op.`
             },
-            declaredCommands: declared,
+            value: {
+                declaredCommands: declared
+            },
             hint: declared.length ? `Declared commands are: ${declared.join(", ")}. Check for a typo, or add "${args.name}" to the manifest.` : "This manifest declares no commands at all. Add a `commands` block, rebuild, then retry."
         });
     }
@@ -4192,7 +4677,7 @@ async function open_handler(args) {
     if ("command" === args.surface && args.name) cli.push("--name", args.name);
     cli.push("--browser", browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
-    const raw = await runActVerb(cli, args.projectPath, args.timeout);
+    const raw = await runActVerb(cli, args.projectPath, args.timeout, open_schema.name);
     const headless = sessionIsHeadless();
     if (headless && [
         "popup",
@@ -4201,19 +4686,21 @@ async function open_handler(args) {
     ].includes(args.surface)) try {
         const parsed = JSON.parse(raw);
         const msg = String(parsed?.error?.message ?? "");
-        if (parsed?.ok === false && /active browser window|no active|headless|user gesture/i.test(msg)) {
+        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);
+        if (parsed?.ok === false && refusedWindow) {
             if (AS_TAB_SURFACES.includes(args.surface)) {
                 const fallback = await openSurfaceAsTab(args.projectPath, browser, args.surface);
                 try {
                     const parsedFallback = JSON.parse(fallback);
                     if (parsedFallback?.ok) {
-                        parsedFallback.note = `The dev browser is headless, and a real popup/sidebar window can only open in a headed session, so the surface was rendered as a tab instead. For the real window, ${HEADED_RELAUNCH}, then open the surface again without asTab.`;
-                        return JSON.stringify(parsedFallback);
+                        addWarning(parsedFallback, `The dev browser is headless, and a real popup/sidebar window can only open in a headed session, so the surface was rendered as a tab instead. For the real window, ${HEADED_RELAUNCH}, then open the surface again without asTab.`);
+                        return actFrameJson(parsedFallback);
                     }
                 } catch  {}
             }
             if (!parsed.hint) parsed.hint = /user gesture/i.test(msg) ? "This surface can only open from a real user gesture, which headless automation cannot produce. Retry with asTab: true to render the surface document in a tab instead." : `The dev browser is running headless, and a popup/sidebar window needs a headed session. Retry with asTab: true to render the surface document in a tab, or for the real window, ${HEADED_RELAUNCH}.`;
-            return JSON.stringify(parsed);
+            return actFrameJson(parsed);
         }
     } catch  {}
     return AS_TAB_SURFACES.includes(args.surface) ? confirmSurfaceTarget(args.projectPath, browser, args.surface, raw) : raw;
@@ -4543,6 +5030,7 @@ function recordSharedPreview(projectPath, entry) {
         } : {}
     };
 }
+const preview_web_COMMAND = "extension_preview_web";
 const DEFAULT_PREVIEW_DEV_URL = "http://localhost:3110";
 const SURFACE = {
     defaultOrigin: DEFAULT_PREVIEW_DEV_URL,
@@ -4634,7 +5122,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. 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. This is 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 only resolves on this machine. To reach anyone who is not at this machine, pass share:true and hand out the public link it returns. extension_shares lists and revokes every link shared this way, so one does not vanish with this response.",
+    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.",
     inputSchema: {
         type: "object",
         properties: {
@@ -4698,41 +5186,61 @@ async function preview_web_handler(args) {
             buildResult = JSON.parse(raw);
         } catch  {
             buildResult = {
-                success: false,
+                ok: false,
                 raw
             };
         }
-        if (!buildResult || true !== buildResult.success) return JSON.stringify({
+        if (!buildResult || true !== buildResult.ok) return envelope({
             ok: false,
-            stage: "build",
-            error: "The build failed, so there is nothing to preview. See buildResult for the cause.",
-            buildResult
+            command: preview_web_COMMAND,
+            status: "build-failed",
+            error: {
+                code: "E_BUILD_FAILED",
+                message: "The build failed, so there is nothing to preview. See buildResult for the cause."
+            },
+            value: {
+                stage: "build",
+                buildResult
+            }
         });
     }
     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 JSON.stringify({
+    if (!node_fs.existsSync(manifestPath)) return envelope({
         ok: false,
-        stage: "resolve-dist",
-        distDir,
-        error: `No manifest.json in ${distDir}. Build the project first (build:true), or pass distPath to an already-built directory.`
+        command: preview_web_COMMAND,
+        status: "no-dist",
+        error: {
+            code: "E_NO_DIST",
+            message: `No manifest.json in ${distDir}. Build the project first (build:true), or pass distPath to an already-built directory.`
+        },
+        value: {
+            stage: "resolve-dist",
+            distDir
+        }
     });
     let manifest = {};
     try {
         manifest = JSON.parse(node_fs.readFileSync(manifestPath, "utf8"));
     } catch (err) {
-        return JSON.stringify({
+        return envelope({
             ok: false,
-            stage: "resolve-dist",
-            distDir,
-            error: `manifest.json in ${distDir} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+            command: preview_web_COMMAND,
+            status: "bad-dist-manifest",
+            error: {
+                code: "E_BAD_MANIFEST",
+                message: `manifest.json in ${distDir} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+            },
+            value: {
+                stage: "resolve-dist",
+                distDir
+            }
         });
     }
     const encoded = Buffer.from(distDir).toString("base64url");
     const internalUrl = SURFACE.scheme(encoded);
     const deepLink = `${hostBase}/?url=${encodeURIComponent(internalUrl)}`;
     const result = {
-        ok: true,
         deepLink,
         distDir,
         manifest: {
@@ -4745,9 +5253,10 @@ async function preview_web_handler(args) {
             built: true
         } : {
             built: false
-        },
-        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 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 previewWarnings = [];
     if (args.open) {
         const sessionBrowser = args.openIn ?? browser;
         const navRaw = await navigateToUrl(args.projectPath, sessionBrowser, deepLink);
@@ -4762,10 +5271,17 @@ async function preview_web_handler(args) {
         }
         result.opened = opened;
         result.openedIn = sessionBrowser;
-        if (true !== opened.ok) result.openHint = "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 (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 JSON.stringify(result);
+    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, {
@@ -4774,37 +5290,62 @@ async function preview_web_handler(args) {
             }
         });
         const contentType = res.headers.get("content-type") ?? "";
-        if (!res.ok || !contentType.includes("application/json")) return JSON.stringify({
-            ...result,
-            hostReachable: true,
-            previewLoadable: false,
-            probe: {
-                status: res.status,
-                contentType,
-                note: `${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.`
-            }
+        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 JSON.stringify({
-            ...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
-            }
+        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 JSON.stringify({
-            ...result,
-            hostReachable: false,
-            previewLoadable: false,
-            probe: {
-                error: err instanceof Error ? err.message : String(err),
-                note: `Could not reach ${SURFACE.label} at ${hostBase}. Start it with '${SURFACE.devCommand}', then open deepLink.`
-            }
+        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.`
+            ]
         });
     }
 }
@@ -4972,7 +5513,7 @@ async function revokeArtifact(options) {
 const LOGIN_HINT = "Run extension_auth (action: login), or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard).";
 const shares_schema = {
     name: "extension_shares",
-    description: "List and revoke the public preview links this token has shared (what extension_preview_web share:true hands out). action:'list' (default) returns every artifact the logged-in project owns with its artifactId, name, version, live/dead state, createdAt, expiresAt, revokedAt, size, previewUrl, zipUrl and revokeUrl, so a link whose response you lost is findable again. Each row carries owner and sharedBy as the platform returned them plus an attribution block: attribution.ownership is 'project' when the workspace holds the share and any member can revoke it, 'personal' when one person holds it alone, 'unknown' when no owner was disclosed; attribution.credit names the publisher for credit only, never access, and reads 'CLI token <id>' or 'not recorded' when no person can be named. action:'revoke' kills one by artifactId or by pasting any of its URLs, and is PERMANENT. Pass projectPath to reconcile against the project's own append-only .extension.dev/shared-previews.json (read-only, never rewritten): a share made on another machine shows as remoteOnly, a record with no live artifact as localOnly. Needs the same token as sharing (extension_auth or EXTENSION_DEV_TOKEN); without one, listing still returns the local record with a login hint.",
+    description: "List and revoke the public preview links this token has shared, which is what extension_preview_web share:true hands out. Pass action:'list' (the default) for every artifact the logged-in project owns, with its artifactId, name, version, live or dead state, createdAt, expiresAt, revokedAt, size, previewUrl, zipUrl and revokeUrl, so a link whose response you lost is findable again. Each row carries owner and sharedBy as the platform returned them. Read attribution.ownership for who may revoke a share: 'project' means the workspace holds it and any member can pull it back, 'personal' means one person holds it alone, 'unknown' means no owner was disclosed. Read attribution.credit as credit only, never access; it names the publisher, and reads 'CLI token <id>' or 'not recorded' when no person can be named. Pass action:'revoke' with an artifactId, or with any URL of the share, to kill one permanently. Pass projectPath to reconcile against the project's own append-only .extension.dev/shared-previews.json, which is read and never rewritten: a share made on another machine shows as remoteOnly, a record with no live artifact as localOnly. This needs the same token as sharing (extension_auth or EXTENSION_DEV_TOKEN); without one, listing still returns the local record with a login hint.",
     inputSchema: {
         type: "object",
         properties: {
@@ -5099,23 +5640,29 @@ async function listShares(args) {
     });
     if (!listing.ok) {
         const isAuth = "SharesAuthError" === listing.error.name;
-        return JSON.stringify({
+        return envelope({
             ok: true,
-            action: "list",
-            server: {
-                listed: false,
-                errorName: listing.error.name,
-                reason: listing.error.message,
-                ...isAuth ? {
-                    loginHint: LOGIN_HINT
-                } : {}
+            command: "extension_shares",
+            status: "listed-local-only",
+            value: {
+                action: "list",
+                server: {
+                    listed: false,
+                    errorName: listing.error.name,
+                    reason: listing.error.message,
+                    ...isAuth ? {
+                        loginHint: LOGIN_HINT
+                    } : {}
+                },
+                shares: [],
+                localOnly: (local?.entries ?? []).map((entry)=>({
+                        ...entry
+                    })),
+                localRecord
             },
-            shares: [],
-            localOnly: (local?.entries ?? []).map((entry)=>({
-                    ...entry
-                })),
-            localRecord,
-            note: isAuth ? `The platform was not asked, so live and dead cannot be told apart here. ${LOGIN_HINT} localOnly is this project's own record of every link it ever shared, revoke handles included.` : "The platform could not be reached, so localOnly below is this project's own record and not a statement about what is still live."
+            warnings: [
+                isAuth ? `The platform was not asked, so live and dead cannot be told apart here. ${LOGIN_HINT} localOnly is this project's own record of every link it ever shared, revoke handles included.` : "The platform could not be reached, so localOnly below is this project's own record and not a statement about what is still live."
+            ]
         });
     }
     const now = Date.now();
@@ -5153,37 +5700,50 @@ async function listShares(args) {
         personal: shares.filter((s)=>"personal" === s.attribution.ownership).length,
         unknown: shares.filter((s)=>"unknown" === s.attribution.ownership).length
     };
-    return JSON.stringify({
+    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({
         ok: true,
-        action: "list",
-        server: {
-            listed: true,
-            count: listing.data.count,
-            matched: listing.data.matched,
-            limit: listing.data.limit,
-            truncated: listing.data.truncated,
-            scanned: listing.data.scanned,
-            ownership,
-            ...listing.data.truncated ? {
-                truncatedNote: `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.`
-            } : {}
+        command: "extension_shares",
+        status: "listed",
+        value: {
+            action: "list",
+            server: {
+                listed: true,
+                count: listing.data.count,
+                matched: listing.data.matched,
+                limit: listing.data.limit,
+                truncated: listing.data.truncated,
+                scanned: listing.data.scanned,
+                ownership,
+                ...truncatedNote ? {
+                    truncatedNote
+                } : {}
+            },
+            shares,
+            ...local ? {
+                localOnly
+            } : {},
+            localRecord
         },
-        shares,
-        ...local ? {
-            localOnly
-        } : {},
-        localRecord,
-        message: `${liveCount} of ${shares.length} listed shares still resolve${local ? `; ${localOnly.length} local record ${1 === localOnly.length ? "entry has" : "entries have"} no artifact behind them` : ""}. Revoke one with action:"revoke" and its artifactId or any of its URLs.`,
-        note: "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.",
-        attributionNote: "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."
+        hint: `${liveCount} of ${shares.length} listed shares still resolve${local ? `; ${localOnly.length} local record ${1 === localOnly.length ? "entry has" : "entries have"} no 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.",
+            "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 JSON.stringify({
+    if (!ref) return envelope({
         ok: false,
-        action: "revoke",
+        command: "extension_shares",
+        status: "bad-request",
+        value: {
+            action: "revoke"
+        },
         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."
         }
@@ -5199,34 +5759,43 @@ 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 JSON.stringify({
+        return envelope({
             ok: false,
-            action: "revoke",
-            artifactId: ref,
+            command: "extension_shares",
+            status: "revoke-failed",
+            value: {
+                action: "revoke",
+                artifactId: ref
+            },
             error: {
+                code: isAuth ? "E_AUTH_REQUIRED" : "E_PLATFORM",
                 name: result.error.name,
                 message: result.error.message
             },
             ...isAuth ? {
-                loginHint: LOGIN_HINT
+                hint: LOGIN_HINT
             } : {},
-            ...recordNote ? {
+            warnings: [
                 recordNote
-            } : {}
+            ]
         });
     }
-    return JSON.stringify({
+    return envelope({
         ok: true,
-        action: "revoke",
-        artifactId: ref,
-        revoked: result.data.revoked,
-        ...result.data.revokedAt ? {
-            revokedAt: result.data.revokedAt
-        } : {},
-        ...recordNote ? {
+        command: "extension_shares",
+        status: "revoked",
+        value: {
+            action: "revoke",
+            artifactId: ref,
+            revoked: result.data.revoked,
+            ...result.data.revokedAt ? {
+                revokedAt: result.data.revokedAt
+            } : {}
+        },
+        warnings: [
+            "The link is dead for everyone, permanently: the zip is deleted and the id is burned, so it can never resolve again. Sharing the same build later returns a different link, and anyone holding the old one gets nothing.",
             recordNote
-        } : {},
-        note: "The link is dead for everyone, permanently: the zip is deleted and the id is burned, so it can never resolve again. Sharing the same build later returns a different link, and anyone holding the old one gets nothing."
+        ]
     });
 }
 async function shares_handler(args) {
@@ -5259,6 +5828,7 @@ async function shares_handler(args) {
         } : {}
     });
 }
+const manifest_validate_COMMAND = "extension_manifest_validate";
 const CHROME_DESKTOP_ONLY_KEYS = [
     "file_browser_handlers",
     "file_system_provider_capabilities",
@@ -5352,7 +5922,7 @@ const KNOWN_PERMISSIONS = new Set([
 ]);
 const manifest_validate_schema = {
     name: "extension_manifest_validate",
-    description: "Validate a manifest.json file for correctness across browsers. Reports missing fields, invalid permissions, and cross-browser compatibility issues.",
+    description: "Validate a manifest.json across browsers. This reports missing fields, invalid permissions, dangling file references, and cross-browser compatibility issues. Read buildBlocking for the errors that make extension_build refuse.",
     inputSchema: {
         type: "object",
         properties: {
@@ -5552,29 +6122,51 @@ async function manifest_validate_handler(args) {
         similarTemplates: []
     };
     const manifestPath = args.manifestPath ?? (args.projectPath ? findManifest(args.projectPath) : null);
-    if (!manifestPath) return JSON.stringify({
-        valid: false,
-        errors: [
+    if (!manifestPath) {
+        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)."
-        ],
-        warnings: [],
-        browserSupport: {},
-        similarTemplates: []
-    });
+        ];
+        return envelope({
+            ok: false,
+            command: manifest_validate_COMMAND,
+            status: "manifest-not-found",
+            error: {
+                code: "E_MANIFEST_NOT_FOUND",
+                message: errors[0]
+            },
+            value: {
+                valid: false,
+                errors,
+                browserSupport: {},
+                similarTemplates: []
+            },
+            warnings: []
+        });
+    }
     const manifestDir = node_path.dirname(node_path.resolve(manifestPath));
     let manifest;
     try {
         const raw = node_fs.readFileSync(node_path.resolve(manifestPath), "utf8");
         manifest = JSON.parse(raw);
     } catch (err) {
-        return JSON.stringify({
-            valid: false,
-            errors: [
-                `Cannot read manifest: ${err instanceof Error ? err.message : err}`
-            ],
-            warnings: [],
-            browserSupport: {},
-            similarTemplates: []
+        const errors = [
+            `Cannot read manifest: ${err instanceof Error ? err.message : err}`
+        ];
+        return envelope({
+            ok: false,
+            command: manifest_validate_COMMAND,
+            status: "manifest-unreadable",
+            error: {
+                code: "E_BAD_MANIFEST",
+                message: errors[0]
+            },
+            value: {
+                valid: false,
+                errors,
+                browserSupport: {},
+                similarTemplates: []
+            },
+            warnings: []
         });
     }
     if (!manifest.name) result.errors.push("Missing required field: name");
@@ -5694,9 +6286,15 @@ async function manifest_validate_handler(args) {
         else result.warnings.push(`${browser} (not requested, checked by default): ${issues}`);
     }
     result.valid = 0 === result.errors.length;
-    return JSON.stringify({
-        ...result,
-        buildBlocking: result.errors.length > 0
+    return envelope({
+        ok: result.valid,
+        command: manifest_validate_COMMAND,
+        status: result.valid ? "valid" : "invalid",
+        value: {
+            ...result,
+            buildBlocking: result.errors.length > 0
+        },
+        warnings: result.warnings
     });
 }
 const CHROME_THEME_COLOR_KEYS = {
@@ -6304,9 +6902,10 @@ function resolveChromeTheme(theme) {
         caveats
     };
 }
+const theme_verify_COMMAND = "extension_theme_verify";
 const theme_verify_schema = {
     name: "extension_theme_verify",
-    description: "Verify a Chrome theme manifest before it ships. Settles the four-leg WYSIWYG contract (app-shows == manifest-says == chrome-paints, plus chrome-accepts) as far as is possible headless: it derives every color current Chrome would paint from the manifest (the transcribed Chromium resolver) and classifies any problem as D1 fabrication, D3 parity gap, or D4 acceptance gap (keys Chrome silently discards: dead legacy, incognito, unknown, out-of-range). Verification only: it never authors or mutates a theme. The app-rendered and real-pixel legs need a browser and come back as needsAttended pointing at the assert:theme and install-parity harnesses, never as passed.",
+    description: "Verify a Chrome theme manifest before it ships. This settles the four-leg WYSIWYG contract (app-shows == manifest-says == chrome-paints, plus chrome-accepts) as far as is possible headless: it derives every color current Chrome would paint from the manifest through the transcribed Chromium resolver, and classifies each problem as D1 fabrication, D3 parity gap, or D4 acceptance gap (keys Chrome silently discards: dead legacy, incognito, unknown, out-of-range). It verifies only, and never authors or mutates a theme. The app-rendered and real-pixel legs need a browser, so they come back as needsAttended pointing at the assert:theme and install-parity harnesses, never as passed.",
     inputSchema: {
         type: "object",
         properties: {
@@ -6369,9 +6968,12 @@ async function theme_verify_handler(args) {
         try {
             text = await promises.readFile(abs, "utf8");
         } catch  {
-            return JSON.stringify({
+            return envelope({
                 ok: false,
+                command: theme_verify_COMMAND,
+                status: "bad-input",
                 error: {
+                    code: "E_BAD_REQUEST",
                     name: "InputError",
                     message: `Cannot read ${abs}`
                 }
@@ -6380,18 +6982,24 @@ async function theme_verify_handler(args) {
         try {
             raw = JSON.parse(text);
         } catch (err) {
-            return JSON.stringify({
+            return envelope({
                 ok: false,
+                command: theme_verify_COMMAND,
+                status: "bad-input",
                 error: {
+                    code: "E_BAD_REQUEST",
                     name: "InputError",
                     message: `${abs} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
                 }
             });
         }
     } else {
-        if (!args.manifest) return JSON.stringify({
+        if (!args.manifest) return envelope({
             ok: false,
+            command: theme_verify_COMMAND,
+            status: "bad-request",
             error: {
+                code: "E_BAD_REQUEST",
                 name: "InputError",
                 message: "Pass `manifest` (an object) or `manifestPath` (a file path)."
             }
@@ -6403,9 +7011,12 @@ async function theme_verify_handler(args) {
     try {
         ({ manifest, theme } = coerceInput(raw));
     } catch (err) {
-        return JSON.stringify({
+        return envelope({
             ok: false,
+            command: theme_verify_COMMAND,
+            status: "bad-input",
             error: {
+                code: "E_BAD_REQUEST",
                 name: "InputError",
                 message: err instanceof Error ? err.message : String(err)
             }
@@ -6504,74 +7115,77 @@ 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 JSON.stringify({
+    return envelope({
         ok: true,
-        tool: "extension_theme_verify",
-        verdict,
-        needsAttended: true,
-        summary: {
-            errors: grammarErrors.length,
-            warnings: findings.filter((f)=>"warn" === f.severity).length,
-            advisories: findings.filter((f)=>"info" === f.severity).length,
-            byClass: {
-                D1: findings.filter((f)=>"D1" === f.class).length,
-                D3: findings.filter((f)=>"D3" === f.class).length,
-                D4: findings.filter((f)=>"D4" === f.class).length
-            }
-        },
-        legs: {
-            appShows: {
-                status: "needs-attended",
-                detail: "Not run here (needs a browser). The app self-verifies app == resolve(manifest) via the seed door.",
-                how: attended[0].how
-            },
-            manifestSays: {
-                status: hasError ? "invalid" : "verified",
-                name,
-                version,
-                grammar: {
-                    nameValid,
-                    versionValid,
-                    errors: grammarErrors
-                },
-                declared: {
-                    colors: Object.keys(declaredColors),
-                    tints: Object.keys(declaredTints),
-                    images: Object.keys(declaredImages),
-                    properties: Object.keys(declaredProps)
+        command: theme_verify_COMMAND,
+        status: verdict,
+        value: {
+            needsAttended: true,
+            summary: {
+                errors: grammarErrors.length,
+                warnings: findings.filter((f)=>"warn" === f.severity).length,
+                advisories: findings.filter((f)=>"info" === f.severity).length,
+                byClass: {
+                    D1: findings.filter((f)=>"D1" === f.class).length,
+                    D3: findings.filter((f)=>"D3" === f.class).length,
+                    D4: findings.filter((f)=>"D4" === f.class).length
                 }
             },
-            chromePaints: {
-                resolver: {
-                    status: "reported",
-                    detail: "Headless proxy: every color current stable Chrome derives from this manifest.",
-                    resolved
-                },
-                realPaint: {
+            legs: {
+                appShows: {
                     status: "needs-attended",
-                    how: attended[1].how
+                    detail: "Not run here (needs a browser). The app self-verifies app == resolve(manifest) via the seed door.",
+                    how: attended[0].how
+                },
+                manifestSays: {
+                    status: hasError ? "invalid" : "verified",
+                    name,
+                    version,
+                    grammar: {
+                        nameValid,
+                        versionValid,
+                        errors: grammarErrors
+                    },
+                    declared: {
+                        colors: Object.keys(declaredColors),
+                        tints: Object.keys(declaredTints),
+                        images: Object.keys(declaredImages),
+                        properties: Object.keys(declaredProps)
+                    }
+                },
+                chromePaints: {
+                    resolver: {
+                        status: "reported",
+                        detail: "Headless proxy: every color current stable Chrome derives from this manifest.",
+                        resolved
+                    },
+                    realPaint: {
+                        status: "needs-attended",
+                        how: attended[1].how
+                    }
+                },
+                chromeAccepts: {
+                    status: "reported",
+                    detail: "Static analysis of what Chrome parses but discards (the D4 acceptance gap).",
+                    discarded: findings.filter((f)=>"chrome-accepts" === f.leg).map((f)=>({
+                            key: f.key,
+                            detail: f.detail
+                        })),
+                    live: {
+                        status: "needs-attended",
+                        how: attended[2].how
+                    }
                 }
             },
-            chromeAccepts: {
-                status: "reported",
-                detail: "Static analysis of what Chrome parses but discards (the D4 acceptance gap).",
-                discarded: findings.filter((f)=>"chrome-accepts" === f.leg).map((f)=>({
-                        key: f.key,
-                        detail: f.detail
-                    })),
-                live: {
-                    status: "needs-attended",
-                    how: attended[2].how
-                }
-            }
-        },
-        findings,
-        attended
+            findings,
+            attended
+        }
     });
 }
+const analyze_COMMAND = "extension_analyze";
 const analyze_schema = {
     name: "extension_analyze",
-    description: "Analyze a BUILT extension on disk: file sizes, declared entry points, permissions, bundle composition, and store-readiness checks. Static only, reads dist/<browser> from the filesystem and never touches a browser. The extension must be built first (extension_build). For a RUNNING extension's live DOM and console use extension_inspect.",
+    description: "Analyze a BUILT extension on disk: file sizes, declared entry points, permissions, bundle composition, and store-readiness checks. This is static only: it reads dist/<browser> from the filesystem and never touches a browser, so build first with extension_build. Use extension_inspect for a running extension's live DOM and console.",
     inputSchema: {
         type: "object",
         properties: {
@@ -6663,8 +7277,14 @@ 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 JSON.stringify({
-        error: `Build output not found at ${distPath}. Run extension_build first.`,
+    if (!node_fs.existsSync(distPath)) return envelope({
+        ok: false,
+        command: analyze_COMMAND,
+        status: "no-dist",
+        error: {
+            code: "E_NO_DIST",
+            message: `Build output not found at ${distPath}. Run extension_build first.`
+        },
         hint: `Use extension_build with browser: "${browser}" to build the extension.`
     });
     const files = walkDir(distPath);
@@ -6720,25 +7340,18 @@ async function analyze_handler(args) {
         if (PROMO_RE.test(f.path)) sizeWarnings.push(`${f.path} (${formatBytes(f.size)}) looks like a store-listing promo image shipped inside the extension package, move it out of the bundled sources so it does not inflate the store zip.`);
         else if ("image" === f.type && !f.path.includes("icon") && f.size > 51200 && shippableSize > 0 && f.size / shippableSize > 0.25) sizeWarnings.push(`${f.path} (${formatBytes(f.size)}) is ${Math.round(f.size / shippableSize * 100)}% of the shipped bundle, unusually large for a shipped asset.`);
     }
+    const note = "development" === buildType ? `This dist contains ${formatBytes(sourcemapSize)} of sourcemaps and looks like a dev build; run extension_build for production sizes. shippableSize excludes sourcemaps.` : void 0;
+    const archiveNote = archiveSize > 0 ? `This dist contains ${formatBytes(archiveSize)} of .zip archive(s) (store packaging output, written into dist by zip builds). shippableSize excludes them so the packaged copy does not double-count the files it contains.` : void 0;
     const result = {
         browser,
         distPath,
         entrypoints,
-        ...sizeWarnings.length ? {
-            sizeWarnings
-        } : {},
         buildType,
         totalSize,
         totalSizeFormatted: formatBytes(totalSize),
         shippableSize,
         shippableSizeFormatted: formatBytes(shippableSize),
         fileCount: files.length,
-        ..."development" === buildType ? {
-            note: `This dist contains ${formatBytes(sourcemapSize)} of sourcemaps and looks like a dev build; run extension_build for production sizes. shippableSize excludes sourcemaps.`
-        } : {},
-        ...archiveSize > 0 ? {
-            archiveNote: `This dist contains ${formatBytes(archiveSize)} of .zip archive(s) (store packaging output, written into dist by zip builds). shippableSize excludes them so the packaged copy does not double-count the files it contains.`
-        } : {},
         manifest: {
             name: manifest.name,
             version: manifest.version,
@@ -6774,7 +7387,17 @@ async function analyze_handler(args) {
             under10MB: totalSize - archiveSize < 10485760
         }
     };
-    return JSON.stringify(result);
+    return envelope({
+        ok: true,
+        command: analyze_COMMAND,
+        status: "analyzed",
+        value: result,
+        warnings: [
+            ...sizeWarnings,
+            note,
+            archiveNote
+        ]
+    });
 }
 function rdp_define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
@@ -7013,6 +7636,7 @@ async function rdpCollectConsoleMessages(port, options) {
         return messages;
     });
 }
+const TOOL = "extension_inspect";
 function buildBridgeInspectExpression(opts) {
     const parts = [
         "const out = {};"
@@ -7090,7 +7714,7 @@ async function collectGeckoDeepDom(args, browser, urlFilter, cap, result, notes)
             "--timeout",
             String(args.timeout)
         ] : []
-    ], args.projectPath, args.timeout);
+    ], args.projectPath, args.timeout, TOOL);
     let parsed;
     try {
         parsed = JSON.parse(raw);
@@ -7130,11 +7754,11 @@ async function collectGeckoConsole(args, browser, urlFilter, result, notes) {
 async function inspectViaBridge(args, browser, include, maxBytes) {
     const notes = [];
     if (args.url) {
-        const listed = await listBridgeTabs(args.projectPath, browser, args.timeout);
+        const listed = await listBridgeTabs(args.projectPath, browser, args.timeout, "extension_inspect");
         if ("error" in listed) return listed.error;
         const already = listed.tabs.some((t)=>t.url.includes(args.url));
         if (!already) {
-            const nav = await navigateToUrlViaBridge(args.projectPath, browser, args.url, args.timeout);
+            const nav = await navigateToUrlViaBridge(args.projectPath, browser, args.url, args.timeout, "extension_inspect");
             try {
                 if (JSON.parse(nav)?.ok !== true) return nav;
             } catch  {
@@ -7167,7 +7791,7 @@ async function inspectViaBridge(args, browser, include, maxBytes) {
             "--timeout",
             String(args.timeout)
         ] : []
-    ], args.projectPath, args.timeout);
+    ], args.projectPath, args.timeout, TOOL);
     let parsed;
     try {
         parsed = JSON.parse(raw);
@@ -7188,7 +7812,7 @@ async function inspectViaBridge(args, browser, include, maxBytes) {
                 "--timeout",
                 String(args.timeout)
             ] : []
-        ], args.projectPath, args.timeout);
+        ], args.projectPath, args.timeout, TOOL);
         try {
             parsed = JSON.parse(raw);
         } catch  {
@@ -7196,9 +7820,12 @@ 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 JSON.stringify({
+        else if (parsed?.ok === true) return envelope({
             ok: false,
+            command: TOOL,
+            status: "inspect-failed",
             error: {
+                code: "E_BRIDGE",
                 name: "InspectFailed",
                 message: String(parsed?.value?.error ?? "the content-script inspect returned nothing")
             },
@@ -7224,10 +7851,11 @@ async function inspectViaBridge(args, browser, include, maxBytes) {
     }
     if (include.has("dom_snapshot") && value.domSnapshot) result.domSnapshot = value.domSnapshot;
     if (include.has("extension_roots") && void 0 !== value.extensionRoots) result.extensionRoots = value.extensionRoots;
+    let probeWarning = null;
     if (value.probes) {
         result.probes = value.probes;
         const jsLooking = (args.probe ?? []).filter((p)=>/^typeof\s|^(chrome|browser|window|document)\.|\(\)|=>|===/.test(p));
-        if (jsLooking.length) result.probeWarning = `Probes are CSS selectors run through querySelectorAll against the live page, NOT JavaScript expressions. ${jsLooking.map((s)=>`"${s}"`).join(", ")} parsed as selectors and will match nothing. To evaluate JS, use extension_eval.`;
+        if (jsLooking.length) probeWarning = `Probes are CSS selectors run through querySelectorAll against the live page, NOT JavaScript expressions. ${jsLooking.map((s)=>`"${s}"`).join(", ")} parsed as selectors and will match nothing. To evaluate JS, use extension_eval.`;
     }
     const urlFilter = args.url ?? ("string" == typeof value.meta?.url ? value.meta.url : void 0);
     if (include.has("console")) await collectGeckoConsole(args, browser, urlFilter, result, notes);
@@ -7235,12 +7863,20 @@ async function inspectViaBridge(args, browser, include, maxBytes) {
         const cap = maxBytes > 0 ? maxBytes : 65536;
         await collectGeckoDeepDom(args, browser, urlFilter, cap, result, notes);
     }
-    if (notes.length) result.notes = notes;
-    return JSON.stringify(result);
+    return envelope({
+        ok: true,
+        command: TOOL,
+        status: "inspected",
+        value: result,
+        warnings: [
+            ...notes,
+            probeWarning
+        ]
+    });
 }
 const inspect_schema = {
     name: "extension_inspect",
-    description: "DEEP inspection of a RUNNING extension over the browser's debugger protocol: full HTML including shadow DOM, DOM structure, content-script injection, console messages, and CSS selector queries (`probe`). The ONLY tool that pierces CLOSED shadow roots (`deepDom`), runs selector probes, and NAVIGATES a tab to `url` before reading it. It reads a web or override page and picks the first inspectable target (or the first whose url contains `url`); it cannot address an extension surface by name and takes no chrome.tabs id. To choose WHICH tab or which OPEN surface (popup/options/sidebar/devtools) to read, or to enumerate what is open, use extension_dom_snapshot. For a built extension's files and sizes on disk use extension_analyze. Chromium rides Chrome DevTools Protocol (needs the session's debug port, not allowControl). Firefox is fully paired: summary/meta/html/dom_snapshot/extension_roots/probes ride the agent bridge (needs allowEval: true), console rides the RDP watcher replay (engine 4.0.15+), and deepDom needs an MV2 session with host permissions for the target url (Firefox MV3 background CSP blocks bridge evals). Requires an active dev or start session.",
+    description: "Inspect a running extension deeply over the browser's debugger protocol: full HTML including shadow DOM, DOM structure, content-script injection, console messages, and CSS selector queries through `probe`. This is the ONLY tool that pierces closed shadow roots (deepDom), runs selector probes, and navigates a tab to `url` before reading it. It reads a web or override page and picks the first inspectable target, or the first whose url contains `url`; it cannot address an extension surface by name and takes no chrome.tabs id. Use extension_dom_snapshot to choose which tab or which open surface (popup, options, sidebar, devtools) to read, or to enumerate what is open. Use extension_analyze for a built extension's files and sizes on disk. Chromium rides the Chrome DevTools Protocol and needs the session's debug port, not allowControl. Firefox is fully paired: summary, meta, html, dom_snapshot, extension_roots and probes ride the agent bridge and need allowEval:true, console rides the RDP watcher replay on engine 4.0.15 and later, and deepDom needs an MV2 session with host permissions for the target url, because the Firefox MV3 background CSP blocks bridge evals. This requires an active dev or start session.",
     inputSchema: {
         type: "object",
         properties: {
@@ -7303,8 +7939,14 @@ 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 JSON.stringify({
-        error: "No active dev session found. Cannot connect to Chrome DevTools Protocol.",
+    if (!resolved) return envelope({
+        ok: false,
+        command: inspect_schema.name,
+        status: "no-session",
+        error: {
+            code: "E_NO_SESSION",
+            message: "No active dev session found. Cannot connect to Chrome DevTools Protocol."
+        },
         hint: `Start a dev session first with extension_dev, then use extension_wait to confirm it is ready. ${CDP_PORT_MISSING_HINT}`
     });
     const cdpPort = resolved.port;
@@ -7321,14 +7963,22 @@ 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 JSON.stringify({
-                cdpPort,
-                browser,
-                warning: chromeOnly ? "No inspectable page targets found. Only internal chrome:// pages are open; open the extension's surface (or pass a url to navigate a tab) first." : "No inspectable page targets found. The extension may not have opened a page yet.",
-                allTargets: allTargets.map((t)=>({
-                        type: t.type,
-                        url: t.url?.slice(0, 100)
-                    }))
+            return envelope({
+                ok: false,
+                command: inspect_schema.name,
+                status: "no-inspectable-target",
+                error: {
+                    code: "E_NO_TARGET",
+                    message: chromeOnly ? "No inspectable page targets found. Only internal chrome:// pages are open; open the extension's surface (or pass a url to navigate a tab) first." : "No inspectable page targets found. The extension may not have opened a page yet."
+                },
+                value: {
+                    cdpPort,
+                    browser,
+                    allTargets: allTargets.map((t)=>({
+                            type: t.type,
+                            url: t.url?.slice(0, 100)
+                        }))
+                }
             });
         }
         const target = args.url ? pageTargets.find((t)=>t.url.includes(args.url)) ?? pageTargets[0] : pageTargets[0];
@@ -7392,11 +8042,29 @@ async function inspect_handler(args) {
             result.closedShadowRoots = closed;
             result.deepDom = true;
         }
-        return JSON.stringify(result);
+        const probeWarning = result.probeWarning;
+        delete result.probeWarning;
+        return envelope({
+            ok: true,
+            command: inspect_schema.name,
+            status: "inspected",
+            value: result,
+            warnings: [
+                "string" == typeof probeWarning ? probeWarning : null
+            ]
+        });
     } catch (err) {
-        return JSON.stringify({
-            error: `CDP inspection failed: ${err instanceof Error ? err.message : err}`,
-            cdpPort,
+        return envelope({
+            ok: false,
+            command: inspect_schema.name,
+            status: "cdp-failed",
+            error: {
+                code: "E_CDP",
+                message: `CDP inspection failed: ${err instanceof Error ? err.message : err}`
+            },
+            value: {
+                cdpPort
+            },
             hint: "Ensure a dev session is running. The browser may have closed or the CDP port may have changed."
         });
     } finally{
@@ -7405,7 +8073,7 @@ async function inspect_handler(args) {
 }
 const list_extensions_schema = {
     name: "extension_list_extensions",
-    description: "List the extensions in the running dev browser: id, name, version, and (on Chromium) live contexts. THIS session's own extension is flagged ownExtension: true, with name and version from the ready contract even when the browser exposes no identity. Chromium rides the Chrome DevTools Protocol, so an entry needs at least one live context (a dormant MV3 service worker may be absent until it wakes). Firefox rides the RDP root actor (listAddons, engine 4.0.15+), so entries are INSTALLED add-ons regardless of contexts, marked temporarilyInstalled where relevant, and carry none. Either way other extensions' contexts are never attached to or evaluated in. Requires an active dev or start session.",
+    description: "List the extensions in the running dev browser: id, name, version, and, on Chromium, live contexts. This session's own extension carries ownExtension:true, with name and version from the ready contract even when the browser exposes no identity. Chromium rides the Chrome DevTools Protocol, so an entry needs at least one live context, and a dormant MV3 service worker may be absent until it wakes. Firefox rides the RDP root actor (listAddons, engine 4.0.15 and later), so entries are installed add-ons regardless of contexts, are marked temporarilyInstalled where relevant, and carry no contexts. Other extensions' contexts are never attached to or evaluated in. This requires an active dev or start session.",
     inputSchema: {
         type: "object",
         properties: {
@@ -7461,13 +8129,25 @@ 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 JSON.stringify({
-        error: `Listing extensions for ${browser} is not supported: no debugging-protocol pairing exists for this browser family.`,
+    if (!isChromiumFamily(browser)) return envelope({
+        ok: false,
+        command: list_extensions_schema.name,
+        status: "unsupported-browser",
+        error: {
+            code: "E_UNSUPPORTED_BROWSER",
+            message: `Listing extensions for ${browser} is not supported: no debugging-protocol pairing exists for this browser family.`
+        },
         hint: "Target a Chromium-family (CDP) or Firefox-family (RDP) dev session."
     });
     const resolved = await resolveCdpPort(args.projectPath, browser);
-    if (!resolved) return JSON.stringify({
-        error: "No active dev session found. Cannot connect to Chrome DevTools Protocol.",
+    if (!resolved) return envelope({
+        ok: false,
+        command: list_extensions_schema.name,
+        status: "no-session",
+        error: {
+            code: "E_NO_SESSION",
+            message: "No active dev session found. Cannot connect to Chrome DevTools Protocol."
+        },
         hint: `Start a dev session first with extension_dev, then use extension_wait to confirm it is ready. ${CDP_PORT_MISSING_HINT}`
     });
     const cdpPort = resolved.port;
@@ -7540,17 +8220,30 @@ async function list_extensions_handler(args) {
             return (a.name ?? a.id).localeCompare(b.name ?? b.id);
         });
         const ownEntry = extensions.find((e)=>e.ownExtension);
-        return JSON.stringify({
-            cdpPort,
-            browser,
-            count: extensions.length,
-            ownExtensionId: ownEntry?.id ?? null,
-            extensions,
-            note: "Lists extensions that currently have at least one live context (service worker or open page). An MV3 service worker that has gone dormant with no open page may be absent until it wakes. ownExtension marks the extension this dev session serves, identified from the session's ready contract. Other identity is read read-only via the Extensions domain; other extensions' contexts are never attached to or evaluated in."
+        return envelope({
+            ok: true,
+            command: list_extensions_schema.name,
+            status: "listed",
+            value: {
+                cdpPort,
+                browser,
+                count: extensions.length,
+                ownExtensionId: ownEntry?.id ?? null,
+                extensions
+            },
+            warnings: [
+                "Lists extensions that currently have at least one live context (service worker or open page). An MV3 service worker that has gone dormant with no open page may be absent until it wakes. ownExtension marks the extension this dev session serves, identified from the session's ready contract. Other identity is read read-only via the Extensions domain; other extensions' contexts are never attached to or evaluated in."
+            ]
         });
     } catch (error) {
-        return JSON.stringify({
-            error: `Failed to list extensions: ${error.message}`
+        return envelope({
+            ok: false,
+            command: list_extensions_schema.name,
+            status: "cdp-failed",
+            error: {
+                code: "E_CDP",
+                message: `Failed to list extensions: ${error.message}`
+            }
         });
     } finally{
         cdp.disconnect();
@@ -7558,8 +8251,14 @@ async function list_extensions_handler(args) {
 }
 async function listGeckoExtensions(projectPath, browser) {
     const resolved = await resolveRdpPort(projectPath, browser);
-    if (!resolved) return JSON.stringify({
-        error: "No active dev session with a Firefox debugger server (RDP) found.",
+    if (!resolved) return envelope({
+        ok: false,
+        command: list_extensions_schema.name,
+        status: "no-session",
+        error: {
+            code: "E_NO_SESSION",
+            message: "No active dev session with a Firefox debugger server (RDP) found."
+        },
         hint: `Start a dev session first with extension_dev, then use extension_wait to confirm it is ready. ${RDP_PORT_MISSING_HINT}`
     });
     const rdpPort = resolved.port;
@@ -7606,17 +8305,30 @@ async function listGeckoExtensions(projectPath, browser) {
             return (a.name ?? a.id).localeCompare(b.name ?? b.id);
         });
         const ownEntry = extensions.find((e)=>e.ownExtension);
-        return JSON.stringify({
-            rdpPort,
-            browser,
-            count: extensions.length,
-            ownExtensionId: ownEntry?.id ?? null,
-            extensions,
-            note: "Lists INSTALLED add-ons via the RDP root actor (listAddons), regardless of whether a context is currently live, so entries carry no contexts. temporarilyInstalled marks temporary loads; ownExtension marks the extension this dev session serves, matched from the session's ready contract. Add-ons are never attached to or evaluated in."
+        return envelope({
+            ok: true,
+            command: list_extensions_schema.name,
+            status: "listed",
+            value: {
+                rdpPort,
+                browser,
+                count: extensions.length,
+                ownExtensionId: ownEntry?.id ?? null,
+                extensions
+            },
+            warnings: [
+                "Lists INSTALLED add-ons via the RDP root actor (listAddons), regardless of whether a context is currently live, so entries carry no contexts. temporarilyInstalled marks temporary loads; ownExtension marks the extension this dev session serves, matched from the session's ready contract. Add-ons are never attached to or evaluated in."
+            ]
         });
     } catch (error) {
-        return JSON.stringify({
-            error: `Failed to list extensions over RDP: ${error.message}`
+        return envelope({
+            ok: false,
+            command: list_extensions_schema.name,
+            status: "rdp-failed",
+            error: {
+                code: "E_RDP",
+                message: `Failed to list extensions over RDP: ${error.message}`
+            }
         });
     }
 }
@@ -7672,7 +8384,7 @@ function makeFilter(args) {
 }
 const logs_schema_schema = {
     name: "extension_logs",
-    description: "Read or stream logs from every context of a running dev session (service worker, content scripts, popup, options, sidebar, devtools, pages) in one ordered timeline. Reads the same agent-bridge plane as the `extension logs` CLI: a one-shot returns the most recent matching lines from logs.ndjson; `follow:true` collects from the live control channel for a bounded window. Requires an active `extension dev` session.",
+    description: "Read or stream logs from every context of a running dev session (service worker, content scripts, popup, options, sidebar, devtools, pages) in one ordered timeline. This reads the same agent-bridge plane as the `extension logs` CLI: a one-shot returns the most recent matching lines from logs.ndjson, and follow:true collects from the live control channel for a bounded window. This requires an active extension_dev session.",
     inputSchema: {
         type: "object",
         properties: {
@@ -7749,6 +8461,7 @@ const logs_schema_schema = {
         ]
     }
 };
+const logs_TOOL = "extension_logs";
 function logsFilePath(projectPath, browser) {
     return node_path.resolve(projectPath, "dist", "extension-js", browser, "logs.ndjson");
 }
@@ -7798,24 +8511,26 @@ function summarize(events, source, browser, runId, limit, dropped, projectPath,
     const { events: out, truncated } = capRecent(events, limit);
     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;
-    return JSON.stringify({
+    const stale = Boolean(staleNote) && matched > 0;
+    return envelope({
         ok: true,
-        source,
-        browser,
-        runId: runId || void 0,
-        matched,
-        count: out.length,
-        truncated,
-        dropped: dropped || void 0,
-        nextSince: lastSeq >= 0 ? lastSeq : void 0,
-        ...reason ? {
-            emptyReason: reason
-        } : {},
-        ...staleNote && matched > 0 ? {
-            stale: true,
-            warning: staleNote
-        } : {},
-        events: out
+        command: logs_TOOL,
+        status: 0 === matched ? "empty" : stale ? "stale" : "read",
+        value: {
+            source,
+            browser,
+            runId: runId || void 0,
+            matched,
+            count: out.length,
+            truncated,
+            dropped: dropped || void 0,
+            nextSince: lastSeq >= 0 ? lastSeq : void 0,
+            events: out
+        },
+        warnings: [
+            reason ?? null,
+            stale ? staleNote ?? null : null
+        ]
     });
 }
 function staleFileNote(projectPath, browser, eventsRunId) {
@@ -7838,8 +8553,14 @@ function staleFileNote(projectPath, browser, eventsRunId) {
 }
 async function readFromFile(args, browser, limit) {
     const file = logsFilePath(args.projectPath, browser);
-    if (!node_fs.existsSync(file)) return JSON.stringify({
-        error: `No logs found at ${file}.`,
+    if (!node_fs.existsSync(file)) return envelope({
+        ok: false,
+        command: logs_TOOL,
+        status: "no-log-file",
+        error: {
+            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."
     });
     const matches = makeFilter(args);
@@ -7866,8 +8587,14 @@ async function readFromStream(args, browser, limit) {
     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 JSON.stringify({
-            error: `No active control channel found for ${browser}.`,
+        return envelope({
+            ok: false,
+            command: logs_TOOL,
+            status: "no-control-channel",
+            error: {
+                code: "E_NO_CONTROL_CHANNEL",
+                message: `No active control channel found for ${browser}.`
+            },
             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.`
         });
     }
@@ -7883,8 +8610,14 @@ async function readFromStream(args, browser, limit) {
         try {
             socket = new ws_0(url);
         } catch (err) {
-            resolve(JSON.stringify({
-                error: `Could not open control channel at ${url}: ${err instanceof Error ? err.message : String(err)}`
+            resolve(envelope({
+                ok: false,
+                command: logs_TOOL,
+                status: "control-channel-failed",
+                error: {
+                    code: "E_CONTROL_CHANNEL",
+                    message: `Could not open control channel at ${url}: ${err instanceof Error ? err.message : String(err)}`
+                }
             }));
             return;
         }
@@ -7924,8 +8657,14 @@ async function readFromStream(args, browser, limit) {
             if (settled) return;
             settled = true;
             clearTimeout(timer);
-            resolve(JSON.stringify({
-                error: `Control channel error at ${url}.`,
+            resolve(envelope({
+                ok: false,
+                command: logs_TOOL,
+                status: "control-channel-failed",
+                error: {
+                    code: "E_CONTROL_CHANNEL",
+                    message: `Control channel error at ${url}.`
+                },
                 hint: "The dev session may have stopped or the control port changed. Re-check with extension_wait."
             }));
         });
@@ -7940,7 +8679,7 @@ async function logs_handler(args) {
 }
 const eval_schema = {
     name: "extension_eval",
-    description: "Evaluate an expression in a running extension context. Requires the session to have been started with allowEval: true (extension_dev; writes a 0600 session token). Context defaults to `background`, EXCEPT on a Chromium MV3 session (the default template) where it is `page`, the active tab, because the MV3 service worker CSP blocks eval; pass context:'background' to target the worker anyway and get that explanation back. For content/page, pass `url` to pick the tab or omit both `url` and `tab` for the ACTIVE tab; a numeric `tab` only disambiguates. Extension surfaces (popup/options/sidebar/devtools) and override pages evaluate over the in-bundle relay and need NO tab id, but must be OPEN (extension_open first; a closed one returns an explicit error). extension_dom_snapshot with listTabs: true enumerates {tabId,url,title}.",
+    description: "Evaluate an expression in a running extension context. Start the session with allowEval:true (extension_dev), which writes a 0600 session token. Context defaults to 'background', except on a Chromium MV3 session (the default template) where it defaults to 'page', the active tab, because the MV3 service worker CSP blocks eval; pass context:'background' to target the worker anyway and get that explanation back. For content and page, pass `url` to pick the tab, or omit both `url` and `tab` for the active tab; a numeric `tab` only disambiguates. Extension surfaces (popup, options, sidebar, devtools) and override pages evaluate over the in-bundle relay and need no tab id, but must already be open: open one with extension_open first, because a closed one returns an explicit error. Call extension_dom_snapshot with listTabs:true to enumerate {tabId, url, title}.",
     inputSchema: {
         type: "object",
         properties: {
@@ -8016,28 +8755,32 @@ async function eval_handler(args) {
             context,
             browser
         })
-    ], args.projectPath, args.timeout);
+    ], args.projectPath, args.timeout, eval_schema.name);
     if ("content" === args.context) try {
         const parsed = JSON.parse(raw);
         if (parsed?.ok === true && (null === parsed.value || void 0 === parsed.value)) {
-            parsed.note = "On Extension.js >= 4.0.14 a failed injection errors explicitly, so this null is the expression's real result. On OLDER engines (bug 61) it could mean the injection never ran; if this result looks wrong, check the engine version with extension_doctor, or verify with extension_logs or context:'page'.";
-            return JSON.stringify(parsed);
+            addWarning(parsed, "On Extension.js >= 4.0.14 a failed injection errors explicitly, so this null is the expression's real result. On OLDER engines (bug 61) it could mean the injection never ran; if this result looks wrong, check the engine version with extension_doctor, or verify with extension_logs or context:'page'.");
+            return actFrameJson(parsed);
         }
     } catch  {}
     if (defaulted) try {
         const parsed = JSON.parse(raw);
         if (parsed && "object" == typeof parsed) {
-            parsed.defaultedContext = "page";
-            parsed.contextNote = 'No context given: defaulted to "page" (the active tab) because this Chromium session\'s MV3 background is a service worker whose CSP blocks eval. Pass context: "background" explicitly to target the worker (works on Firefox/MV2 builds).';
-            if (false === parsed.ok && /cannot access|chrome-extension:\/\/|chrome:\/\//i.test(JSON.stringify(parsed.error ?? ""))) parsed.hint = "The active tab is a browser or extension page that eval cannot reach. Navigate the dev browser to a regular web page, or pass url (match pattern) or tab to pick one; extension_dom_snapshot with listTabs: true lists open tabs.";
-            return JSON.stringify(parsed);
+            patchValue(parsed, {
+                defaultedContext: "page"
+            });
+            addWarning(parsed, 'No context given: defaulted to "page" (the active tab) because this Chromium session\'s MV3 background is a service worker whose CSP blocks eval. Pass context: "background" explicitly to target the worker (works on Firefox/MV2 builds).');
+            const code = "string" == typeof parsed.error?.code ? parsed.error.code : "";
+            const unreachable = "E_TARGET_NOT_FOUND" === code || /cannot access|chrome-extension:\/\/|chrome:\/\//i.test(JSON.stringify(parsed.error ?? ""));
+            if (false === parsed.ok && unreachable) parsed.hint = "The active tab is a browser or extension page that eval cannot reach. Navigate the dev browser to a regular web page, or pass url (match pattern) or tab to pick one; extension_dom_snapshot with listTabs: true lists open tabs.";
+            return actFrameJson(parsed);
         }
     } catch  {}
     return raw;
 }
 const storage_schema = {
     name: "extension_storage",
-    description: "Read or write chrome.storage in a running extension. Requires the session to have been started with allowControl: true (extension_dev).",
+    description: "Read or write chrome.storage in a running extension. Start the session with allowControl:true (extension_dev). Set one key per call: there is no bulk-object set.",
     inputSchema: {
         type: "object",
         properties: {
@@ -8097,16 +8840,22 @@ 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 JSON.stringify({
+        if (void 0 === args.value) return envelope({
             ok: false,
+            command: storage_schema.name,
+            status: "bad-request",
             error: {
+                code: "E_BAD_REQUEST",
                 name: "BadRequest",
                 message: "storage set requires a value"
             }
         });
-        if (void 0 === args.key) return JSON.stringify({
+        if (void 0 === args.key) return envelope({
             ok: false,
+            command: storage_schema.name,
+            status: "bad-request",
             error: {
+                code: "E_BAD_REQUEST",
                 name: "BadRequest",
                 message: 'storage set requires `key` (string) and `value` args, one key per call. There is no bulk-object set: to seed {a: 1, b: 2}, call once with key: "a" and once with key: "b".'
             }
@@ -8116,11 +8865,11 @@ async function storage_handler(args) {
     if (args.context) cli.push("--context", args.context);
     cli.push("--browser", browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
-    return runActVerb(cli, args.projectPath, args.timeout);
+    return runActVerb(cli, args.projectPath, args.timeout, storage_schema.name);
 }
 const reload_schema = {
     name: "extension_reload",
-    description: "Reload a running extension (background) or a tab. Requires the session to have been started with allowControl: true (extension_dev).",
+    description: "Reload a running extension's background context, or a tab. Start the session with allowControl:true (extension_dev).",
     inputSchema: {
         type: "object",
         properties: {
@@ -8155,7 +8904,7 @@ async function reload_handler(args) {
             ...args,
             browser
         })
-    ], args.projectPath, args.timeout);
+    ], args.projectPath, args.timeout, reload_schema.name);
 }
 const TARGET_ID_NOTE = "targetId is a CDP target id, NOT a chrome.tabs id: do not pass it as `tab`. Target a tab with `tabUrl` (URL substring) or `url`; if you need a numeric tab id, call extension_dom_snapshot with listTabs: true.";
 function filterPageTargets(raw) {
@@ -8178,7 +8927,7 @@ function matchTargetsByUrl(targets, needle) {
 const RDP_ACTOR_NOTE = "actor is an RDP tab descriptor actor id, NOT a chrome.tabs id: do not pass it as `tab`. Target a tab with `tabUrl` (URL substring) or `url`; if you need a numeric tab id, call extension_dom_snapshot with listTabs: true.";
 const dom_snapshot_schema = {
     name: "extension_dom_snapshot",
-    description: "Take a SHALLOW structured DOM snapshot of ONE CHOSEN surface through the agent bridge (CDP-free, localhost): element counts, extension roots, OPEN shadow roots, optional byte-capped HTML, optional recent console lines. This is the SURFACE PICKER: the only tool that reads an OPEN extension surface by name (`context`: popup/options/sidebar/devtools) or an override page, the only one that takes a numeric chrome.tabs id, and the only one that enumerates what is open (listTargets for CDP targetIds and RDP tab actors, listTabs for numeric tab ids). An ambiguous `tabUrl` returns the candidates instead of guessing. It does NOT pierce closed shadow roots, run selector probes, or navigate: for those, and for a deep read of an already-open web page, use extension_inspect. Requires the session to have been started with allowControl: true (extension_dev).",
+    description: "Take a shallow structured DOM snapshot of one chosen surface through the agent bridge (no CDP, localhost only): element counts, extension roots, open shadow roots, optional byte-capped HTML, and optional recent console lines. This is the SURFACE PICKER: the only tool that reads an open extension surface by name (`context`: popup, options, sidebar, devtools) or an override page, the only one that takes a numeric chrome.tabs id, and the only one that enumerates what is open (listTargets for CDP targetIds and RDP tab actors, listTabs for numeric tab ids). An ambiguous `tabUrl` returns the candidates instead of guessing. It does not pierce closed shadow roots, run selector probes, or navigate: use extension_inspect for those, and for a deep read of an already-open web page. Start the session with allowControl:true (extension_dev).",
     inputSchema: {
         type: "object",
         properties: {
@@ -8256,9 +9005,12 @@ const dom_snapshot_schema = {
 };
 async function cdpPortOrError(projectPath, browser, feature) {
     if (!isChromiumFamily(browser)) return {
-        error: JSON.stringify({
+        error: envelope({
             ok: false,
+            command: dom_snapshot_schema.name,
+            status: "unsupported-browser",
             error: {
+                code: "E_UNSUPPORTED_BROWSER",
                 name: "Unsupported",
                 message: `${feature} reads the browser's CDP page targets, which ${browser} (Gecko) does not expose. Target the tab with \`url\` or \`tab\` instead, and discover tabs with listTabs: true (agent bridge, works on every browser).`
             }
@@ -8266,9 +9018,12 @@ async function cdpPortOrError(projectPath, browser, feature) {
     };
     const resolved = await resolveCdpPort(projectPath, browser);
     if (!resolved) return {
-        error: JSON.stringify({
+        error: envelope({
             ok: false,
+            command: dom_snapshot_schema.name,
+            status: "no-session",
             error: {
+                code: "E_NO_SESSION",
                 name: "NoSession",
                 message: `No active dev session / CDP port for ${browser}, so ${feature} has no browser to ask. Start extension_dev and extension_wait for ready. ${CDP_PORT_MISSING_HINT}`
             }
@@ -8284,34 +9039,46 @@ 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 JSON.stringify({
+            if (!resolved) return envelope({
                 ok: false,
+                command: dom_snapshot_schema.name,
+                status: "no-session",
                 error: {
+                    code: "E_NO_SESSION",
                     name: "NoSession",
                     message: `No active dev session with a Firefox debugger server (RDP) for ${browser}, so listTargets has no browser to ask. Start extension_dev and extension_wait for ready. ${RDP_PORT_MISSING_HINT}`
                 }
             });
             try {
                 const tabs = await rdpListTabs(resolved.port);
-                return JSON.stringify({
+                return envelope({
                     ok: true,
-                    browser,
-                    transport: "rdp",
-                    targets: tabs.map((t)=>({
-                            actor: String(t.actor ?? ""),
-                            type: "tab",
-                            url: String(t.url ?? ""),
-                            title: String(t.title ?? ""),
-                            ...true === t.selected ? {
-                                selected: true
-                            } : {}
-                        })),
-                    note: RDP_ACTOR_NOTE
+                    command: dom_snapshot_schema.name,
+                    status: "listed-targets",
+                    value: {
+                        browser,
+                        transport: "rdp",
+                        targets: tabs.map((t)=>({
+                                actor: String(t.actor ?? ""),
+                                type: "tab",
+                                url: String(t.url ?? ""),
+                                title: String(t.title ?? ""),
+                                ...true === t.selected ? {
+                                    selected: true
+                                } : {}
+                            }))
+                    },
+                    warnings: [
+                        RDP_ACTOR_NOTE
+                    ]
                 });
             } catch (e) {
-                return JSON.stringify({
+                return envelope({
                     ok: false,
+                    command: dom_snapshot_schema.name,
+                    status: "rdp-failed",
                     error: {
+                        code: "E_RDP",
                         name: "RdpError",
                         message: `Could not list tab targets over RDP: ${e instanceof Error ? e.message : String(e)}`
                     },
@@ -8323,16 +9090,25 @@ async function dom_snapshot_handler(args) {
         if ("error" in cdp) return cdp.error;
         try {
             const targets = await listPageTargets(cdp.port);
-            return JSON.stringify({
+            return envelope({
                 ok: true,
-                browser,
-                targets,
-                note: TARGET_ID_NOTE
+                command: dom_snapshot_schema.name,
+                status: "listed-targets",
+                value: {
+                    browser,
+                    targets
+                },
+                warnings: [
+                    TARGET_ID_NOTE
+                ]
             });
         } catch (e) {
-            return JSON.stringify({
+            return envelope({
                 ok: false,
+                command: dom_snapshot_schema.name,
+                status: "cdp-failed",
                 error: {
+                    code: "E_CDP",
                     name: "CdpError",
                     message: `Could not list page targets: ${e instanceof Error ? e.message : String(e)}`
                 },
@@ -8350,14 +9126,17 @@ async function dom_snapshot_handler(args) {
             "--timeout",
             String(args.timeout)
         ] : []
-    ], args.projectPath, args.timeout);
+    ], args.projectPath, args.timeout, dom_snapshot_schema.name);
     let targetUrl = args.url;
     let targetTab = args.tab;
     let resolvedTarget = null;
     if (args.tabUrl) {
-        if (null != args.tab || args.url) return JSON.stringify({
+        if (null != args.tab || args.url) return envelope({
             ok: false,
+            command: dom_snapshot_schema.name,
+            status: "bad-request",
             error: {
+                code: "E_BAD_REQUEST",
                 name: "BadRequest",
                 message: "Pass ONE tab selector: `tabUrl` (URL substring, resolved against live targets), `url` (engine-side match), or `tab` (numeric chrome.tabs id), not several."
             }
@@ -8370,9 +9149,12 @@ async function dom_snapshot_handler(args) {
             try {
                 targets = await listPageTargets(cdp.port);
             } catch (e) {
-                return JSON.stringify({
+                return envelope({
                     ok: false,
+                    command: dom_snapshot_schema.name,
+                    status: "cdp-failed",
                     error: {
+                        code: "E_CDP",
                         name: "CdpError",
                         message: `Could not list page targets to resolve tabUrl: ${e instanceof Error ? e.message : String(e)}`
                     },
@@ -8380,22 +9162,32 @@ async function dom_snapshot_handler(args) {
                 });
             }
             const matches = matchTargetsByUrl(targets, args.tabUrl);
-            if (0 === matches.length) return JSON.stringify({
+            if (0 === matches.length) return envelope({
                 ok: false,
+                command: dom_snapshot_schema.name,
+                status: "no-matching-target",
                 error: {
+                    code: "E_NO_MATCHING_TARGET",
                     name: "NoMatchingTarget",
                     message: `No open page target's url (or title) contains "${args.tabUrl}" (case-insensitive).`
                 },
-                availableTargets: targets,
+                value: {
+                    availableTargets: targets
+                },
                 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 JSON.stringify({
+            if (matches.length > 1) return envelope({
                 ok: false,
+                command: dom_snapshot_schema.name,
+                status: "ambiguous-target",
                 error: {
+                    code: "E_AMBIGUOUS_TARGET",
                     name: "AmbiguousTabUrl",
                     message: `${matches.length} page targets match "${args.tabUrl}"; refusing to guess which tab you mean.`
                 },
-                matchingTargets: matches,
+                value: {
+                    matchingTargets: matches
+                },
                 hint: `Narrow \`tabUrl\` to a longer substring that matches exactly one url in matchingTargets. ${TARGET_ID_NOTE}`
             });
             resolvedTarget = {
@@ -8406,22 +9198,32 @@ 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 JSON.stringify({
+            if (0 === matches.length) return envelope({
                 ok: false,
+                command: dom_snapshot_schema.name,
+                status: "no-matching-target",
                 error: {
+                    code: "E_NO_MATCHING_TARGET",
                     name: "NoMatchingTarget",
                     message: `No open tab's url (or title) contains "${args.tabUrl}" (case-insensitive).`
                 },
-                availableTabs: listed.tabs,
+                value: {
+                    availableTabs: listed.tabs
+                },
                 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 JSON.stringify({
+            if (matches.length > 1) return envelope({
                 ok: false,
+                command: dom_snapshot_schema.name,
+                status: "ambiguous-target",
                 error: {
+                    code: "E_AMBIGUOUS_TARGET",
                     name: "AmbiguousTabUrl",
                     message: `${matches.length} tabs match "${args.tabUrl}"; refusing to guess which tab you mean.`
                 },
-                matchingTabs: matches,
+                value: {
+                    matchingTabs: matches
+                },
                 hint: "Narrow `tabUrl` to a longer substring that matches exactly one url in matchingTabs, or pass its numeric tabId as `tab`."
             });
             resolvedTarget = {
@@ -8443,22 +9245,24 @@ async function dom_snapshot_handler(args) {
     if (null != withConsole) cli.push("--with-console", String(withConsole));
     cli.push("--browser", resolveSessionBrowser(args.projectPath, args.browser).browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
-    const raw = await runActVerb(cli, args.projectPath, args.timeout);
+    const raw = await runActVerb(cli, args.projectPath, args.timeout, dom_snapshot_schema.name);
     if (!resolvedTarget) return raw;
     try {
         const parsed = JSON.parse(raw);
-        parsed.resolvedTarget = {
-            ...resolvedTarget,
-            matchedBy: "tabUrl"
-        };
-        return JSON.stringify(parsed);
+        patchValue(parsed, {
+            resolvedTarget: {
+                ...resolvedTarget,
+                matchedBy: "tabUrl"
+            }
+        });
+        return actFrameJson(parsed);
     } catch  {
         return raw;
     }
 }
 const publish_schema = {
     name: "extension_publish",
-    description: "Publish the project your stored token is scoped to (extension_auth, or EXTENSION_DEV_TOKEN) to extension.dev and return its shareable URL. This is what \"deploy\" or \"ship\" an extension usually means; extension_submit is the separate store-review path. The target is the token's project: there is no projectPath and no local file is uploaded. For a PUBLIC project the URL is the canonical public page and ttlHours does not apply; for a PRIVATE one it is a fresh time-limited share link (?share=) whose lifetime is ttlHours.",
+    description: "Publish the project your stored token is scoped to (extension_auth, or EXTENSION_DEV_TOKEN) to extension.dev, and return its shareable URL. This is what \"deploy\" or \"ship\" an extension usually means; extension_submit is the separate store-review path. The target is the token's project: there is no projectPath, and no local file is uploaded. For a public project the URL is the canonical public page and ttlHours does not apply. For a private one it is a fresh time-limited share link (?share=) whose lifetime is ttlHours.",
     inputSchema: {
         type: "object",
         properties: {
@@ -8475,10 +9279,13 @@ const publish_schema = {
         required: []
     }
 };
-function fail(name, message) {
-    return JSON.stringify({
+function fail(name, message, status, code) {
+    return envelope({
         ok: false,
+        command: "extension_publish",
+        status,
         error: {
+            code,
             name,
             message
         }
@@ -8486,13 +9293,13 @@ function fail(name, message) {
 }
 async function publish_handler(args) {
     const token = resolveToken();
-    if (!token) return fail("PublishAuthError", "No token. Run extension_auth (action: login), or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard).");
+    if (!token) return fail("PublishAuthError", "No token. Run extension_auth (action: login), or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard).", "auth-required", "E_AUTH_REQUIRED");
     if (null != args.ttlHours) {
         const t = Number(args.ttlHours);
-        if (!Number.isInteger(t) || t < 1 || t > 168) return fail("PublishBadRequest", "ttlHours must be an integer between 1 and 168.");
+        if (!Number.isInteger(t) || t < 1 || t > 168) return fail("PublishBadRequest", "ttlHours must be an integer between 1 and 168.", "bad-request", "E_BAD_REQUEST");
     }
     if (null != args.buildSha && "" !== args.buildSha) {
-        if (!/^[0-9a-f]{7,40}$/i.test(args.buildSha)) return fail("PublishBadRequest", "buildSha must be a 7-40 character hex git sha.");
+        if (!/^[0-9a-f]{7,40}$/i.test(args.buildSha)) return fail("PublishBadRequest", "buildSha must be a 7-40 character hex git sha.", "bad-request", "E_BAD_REQUEST");
     }
     const result = await publish({
         ttlHours: args.ttlHours,
@@ -8500,9 +9307,20 @@ async function publish_handler(args) {
         api: args.api,
         token
     });
-    if (!result.ok) return JSON.stringify(result);
+    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
+        }
+    });
     const data = result.data;
-    if (null != args.ttlHours && "public" === data.visibility) data.note = "ttlHours was ignored: this is a public project, whose share URL is its canonical public page.";
+    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.";
+    let buildNote = null;
     const ref = resolveProjectRef();
     if (ref) {
         const buildsUrl = registryFileUrl(ref, "builds/index.json");
@@ -8524,15 +9342,24 @@ async function publish_handler(args) {
                 if (null == data.version && served.version) data.version = served.version;
                 if (null == data.channel && served.channel) data.channel = served.channel;
                 data.registryUrl = buildsUrl;
-                if (!pinned && null == args.buildSha) data.buildNote = "buildSha/builtAt/version describe the newest successful build in the project's registry index, which is what the share link serves. Pin buildSha to serve a specific build.";
+                if (!pinned && null == args.buildSha) buildNote = "buildSha/builtAt/version describe the newest successful build in the project's registry index, which is what the share link serves. Pin buildSha to serve a specific build.";
             }
         }
     }
-    return JSON.stringify(data);
+    return envelope({
+        ok: true,
+        command: "extension_publish",
+        status: "published",
+        value: data,
+        warnings: [
+            note,
+            buildNote
+        ]
+    });
 }
 const release_promote_schema = {
     name: "extension_release_promote",
-    description: "Promote a built extension to a release channel (stable, preview, beta, ...) on extension.dev, headless. This WRITES: it is the only verb that changes what a channel points at. Auth-gated by your stored login (extension_auth) or a release token in EXTENSION_DEV_TOKEN, minted and revoked under project settings -> Access tokens; tokens live at most 7 days, so CI must re-mint before expiry. The project comes from the token. Use extension_release_status to find a valid buildId. Cutting a version-bump PR is not available headlessly (it writes to your source repo and needs an interactive login).",
+    description: "Promote a built extension to a release channel (stable, preview, beta, …) on extension.dev, headless. This WRITES: it is the only verb that changes what a channel points at. It is auth-gated by your stored login (extension_auth) or a release token in EXTENSION_DEV_TOKEN, minted and revoked under project settings, Access tokens. Tokens live at most 7 days, so CI must re-mint before expiry. The project comes from the token. Call extension_release_status to find a valid buildId. Cutting a version-bump PR is not available headlessly, because it writes to your source repo and needs an interactive login.",
     inputSchema: {
         type: "object",
         properties: {
@@ -8571,10 +9398,13 @@ const release_promote_schema = {
         ]
     }
 };
-function release_promote_fail(name, message) {
-    return JSON.stringify({
+function release_promote_fail(name, message, status, code) {
+    return envelope({
         ok: false,
+        command: "extension_release_promote",
+        status,
         error: {
+            code,
             name,
             message
         }
@@ -8582,12 +9412,12 @@ function release_promote_fail(name, message) {
 }
 async function release_promote_handler(args) {
     const token = resolveToken();
-    if (!token) return release_promote_fail("ReleaseAuthError", "No token. Set EXTENSION_DEV_TOKEN to a release token (create one in the extension.dev dashboard under project settings -> Access tokens; tokens live at most 7 days, so CI must re-mint before expiry), or run extension_auth (action: login).");
+    if (!token) return release_promote_fail("ReleaseAuthError", "No token. Set EXTENSION_DEV_TOKEN to a release token (create one in the extension.dev dashboard under project settings -> Access tokens; tokens live at most 7 days, so CI must re-mint before expiry), or run extension_auth (action: login).", "auth-required", "E_AUTH_REQUIRED");
     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.");
+    if (!buildId || !channel) return release_promote_fail("ReleaseInputError", "buildId and channel are required.", "bad-request", "E_BAD_REQUEST");
     const apiCheck = safeApiBase(resolveApiBase(args.api));
-    if (!apiCheck.ok) return release_promote_fail("ReleaseConfigError", apiCheck.message);
+    if (!apiCheck.ok) return release_promote_fail("ReleaseConfigError", apiCheck.message, "bad-config", "E_CONFIG");
     const url = `${apiCheck.base}/api/cli/release/promote`;
     const body = {
         buildId,
@@ -8608,7 +9438,7 @@ async function release_promote_handler(args) {
             body: JSON.stringify(body)
         });
     } catch (err) {
-        return release_promote_fail("ReleaseNetworkError", `Could not reach ${url}: ${err?.message || err}`);
+        return release_promote_fail("ReleaseNetworkError", `Could not reach ${url}: ${err?.message || err}`, "network-failed", "E_NETWORK");
     }
     const text = await res.text();
     let data;
@@ -8622,10 +9452,11 @@ async function release_promote_handler(args) {
     if (!res.ok) {
         const code = "string" == typeof data?.code ? data.code : void 0;
         const enrich = {};
+        let hint = "";
         const ref = resolveProjectRef();
         if (404 === res.status || "UNKNOWN_BUILD" === code) {
             enrich.buildsPageUrl = consoleProjectUrl(ref, "builds", args.api);
-            enrich.hint = "Run extension_release_status to see this project's channels, their promoted shas, and recent builds.";
+            hint = "Run extension_release_status to see this project's channels, their promoted shas, and recent builds.";
             if (ref) {
                 const channelsUrl = registryFileUrl(ref, "channels.json");
                 const channelsRes = await fetchRegistryJson(channelsUrl, fetch, {
@@ -8642,16 +9473,20 @@ async function release_promote_handler(args) {
                 }
             }
         }
-        return JSON.stringify({
+        return envelope({
             ok: false,
+            command: "extension_release_promote",
+            status: "promote-failed",
             error: {
+                code: "E_PLATFORM",
                 name: "ReleaseError",
                 message: `promote failed (${res.status}): ${data?.message || text || "unknown error"}`,
                 ...code ? {
-                    code
+                    platformCode: code
                 } : {}
             },
-            ...enrich
+            value: enrich,
+            hint
         });
     }
     const promotedRef = resolveProjectRef();
@@ -8666,21 +9501,29 @@ async function release_promote_handler(args) {
             publicBuildUrl
         } : {}
     } : data;
-    return JSON.stringify(enriched);
+    return envelope({
+        ok: true,
+        command: "extension_release_promote",
+        status: "promoted",
+        value: enriched
+    });
 }
-function release_list_fail(name, message, extra) {
-    return JSON.stringify({
+function release_list_fail(name, message, status, code, extra) {
+    return envelope({
         ok: false,
+        command: "extension_release_status",
+        status,
+        value: extra ?? {},
         error: {
+            code,
             name,
             message
-        },
-        ...extra ?? {}
+        }
     });
 }
 async function readReleases(args) {
     const ref = resolveProjectRef(args);
-    if (!ref) return release_list_fail("ReleaseListInputError", "No project to list. Run extension_auth (action: login), which names the project, or pass workspace + project explicitly.");
+    if (!ref) return release_list_fail("ReleaseListInputError", "No project to list. Run extension_auth (action: login), which names the project, or pass workspace + project explicitly.", "auth-required", "E_AUTH_REQUIRED");
     const channelsUrl = registryFileUrl(ref, "channels.json");
     const metaUrl = registryFileUrl(ref, "meta.json");
     const buildsUrl = registryFileUrl(ref, "builds/index.json");
@@ -8699,7 +9542,7 @@ async function readReleases(args) {
         })
     ]);
     const buildsPageUrl = consoleProjectUrl(ref, "builds", args.api);
-    if (!channelsRes.ok && !metaRes.ok && !buildsRes.ok) return release_list_fail("ReleaseListNotFound", `No registry data for ${ref.workspace}/${ref.project} (${channelsUrl} returned ${channelsRes.status ?? "no response"}). The project may have no builds yet, or the workspace/project slugs may be wrong. If it is private, make sure extension_auth covers this exact project (a token scoped elsewhere cannot read it). The console Builds page is the authoritative view: ${buildsPageUrl}`, {
+    if (!channelsRes.ok && !metaRes.ok && !buildsRes.ok) return release_list_fail("ReleaseListNotFound", `No registry data for ${ref.workspace}/${ref.project} (${channelsUrl} returned ${channelsRes.status ?? "no response"}). The project may have no builds yet, or the workspace/project slugs may be wrong. If it is private, make sure extension_auth covers this exact project (a token scoped elsewhere cannot read it). The console Builds page is the authoritative view: ${buildsPageUrl}`, "unavailable", "E_PLATFORM", {
         workspace: ref.workspace,
         project: ref.project,
         registryUrl: channelsUrl,
@@ -8720,31 +9563,37 @@ async function readReleases(args) {
             ...b,
             publicUrl: userlandProjectUrl(ref, userland.UserlandProjectPage.build(b.sha), args.api)
         }));
-    const result = {
+    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({
         ok: true,
-        workspace: ref.workspace,
-        project: ref.project,
-        ...meta?.name ? {
-            name: meta.name
-        } : {},
-        ...meta?.visibility ? {
-            visibility: meta.visibility
-        } : {},
-        channels: channelsWithUrls,
-        recentBuilds: buildsWithUrls,
-        registryUrl: channelsUrl,
-        buildsPageUrl,
-        ...publicProjectUrl ? {
-            publicProjectUrl
-        } : {},
-        ...publicProjectUrl ? {
-            publicUrlNote: 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."
-        } : {},
-        message: promotable.length > 0 || recentBuilds.length > 0 ? `Promotable shas: channels currently pin ${promotable.length > 0 ? promotable.join(", ") : "none"}; recent builds add ${recentBuilds.filter((b)=>"success" === b.status).map((b)=>b.sha).join(", ") || "none"}. Use one of these as buildId/buildSha for promote/deploy/publish.` : `No channels or builds are recorded on the registry yet for ${ref.workspace}/${ref.project}. Push a commit to produce a build, then check ${buildsPageUrl}.`
-    };
-    if (!channelsRes.ok) result.channelsUnavailable = `channels.json unreadable: ${channelsRes.message}`;
-    if (!buildsRes.ok) result.buildsUnavailable = `builds/index.json unreadable: ${buildsRes.message}`;
-    return JSON.stringify(result);
+        command: "extension_release_status",
+        status: "read",
+        value: {
+            workspace: ref.workspace,
+            project: ref.project,
+            ...meta?.name ? {
+                name: meta.name
+            } : {},
+            ...meta?.visibility ? {
+                visibility: meta.visibility
+            } : {},
+            channels: channelsWithUrls,
+            recentBuilds: buildsWithUrls,
+            registryUrl: channelsUrl,
+            buildsPageUrl,
+            ...publicProjectUrl ? {
+                publicProjectUrl
+            } : {}
+        },
+        hint: promotable.length > 0 || recentBuilds.length > 0 ? `Promotable shas: channels currently pin ${promotable.length > 0 ? promotable.join(", ") : "none"}; recent builds add ${recentBuilds.filter((b)=>"success" === b.status).map((b)=>b.sha).join(", ") || "none"}. Use one of these as buildId/buildSha for promote/deploy/publish.` : `No channels or builds are recorded on the registry yet for ${ref.workspace}/${ref.project}. Push a commit to produce a build, then check ${buildsPageUrl}.`,
+        warnings: [
+            publicUrlNote,
+            channelsUnavailable,
+            buildsUnavailable
+        ]
+    });
 }
 const KNOWN_STORES = [
     "chrome",
@@ -8830,19 +9679,22 @@ function normalizeStoresStatus(json) {
     }
     return out;
 }
-function store_status_fail(name, message, extra) {
-    return JSON.stringify({
+function store_status_fail(name, message, status, code, extra) {
+    return envelope({
         ok: false,
+        command: "extension_release_status",
+        status,
+        value: extra ?? {},
         error: {
+            code,
             name,
             message
-        },
-        ...extra ?? {}
+        }
     });
 }
 async function readStores(args) {
     const ref = resolveProjectRef(args);
-    if (!ref) return store_status_fail("StoreStatusInputError", "No project to inspect. Run extension_auth (action: login), which names the project, or pass workspace + project explicitly.");
+    if (!ref) return store_status_fail("StoreStatusInputError", "No project to inspect. Run extension_auth (action: login), which names the project, or pass workspace + project explicitly.", "auth-required", "E_AUTH_REQUIRED");
     const healthUrl = registryFileUrl(ref, "stores/health.json");
     const statusUrl = registryFileUrl(ref, "stores/status.json");
     const submissionsUrl = registryFileUrl(ref, "stores/submissions.json");
@@ -8861,7 +9713,7 @@ async function readStores(args) {
             api: args.api
         })
     ]);
-    if (!healthRes.ok && !statusRes.ok && !submissionsRes.ok) return store_status_fail("StoreStatusNotFound", `No store data on the registry for ${ref.workspace}/${ref.project} (${healthUrl} returned ${healthRes.status ?? "no response"}). The project may have no stores configured yet, be private (private registry data needs a share token), or the workspace/project slugs may be wrong. Configure stores at ${consoleStoresUrl}/new; the console Stores page is the authoritative view: ${consoleStoresUrl}`, {
+    if (!healthRes.ok && !statusRes.ok && !submissionsRes.ok) return store_status_fail("StoreStatusNotFound", `No store data on the registry for ${ref.workspace}/${ref.project} (${healthUrl} returned ${healthRes.status ?? "no response"}). The project may have no stores configured yet, be private (private registry data needs a share token), or the workspace/project slugs may be wrong. Configure stores at ${consoleStoresUrl}/new; the console Stores page is the authoritative view: ${consoleStoresUrl}`, "unavailable", "E_PLATFORM", {
         workspace: ref.workspace,
         project: ref.project,
         registryUrls: {
@@ -8917,33 +9769,41 @@ async function readStores(args) {
         if (review?.status) tail.push(`review ${review.status}${review.checkedAt ? ` (checked ${review.checkedAt})` : ""}`);
         return tail.length > 0 ? `${head}; ${tail.join("; ")}` : head;
     });
-    const result = {
+    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({
         ok: true,
-        workspace: ref.workspace,
-        project: ref.project,
-        stores: rows,
-        ...status.lastSubmission ? {
-            lastSubmission: status.lastSubmission
-        } : {},
-        ...status.lastPollAt ? {
-            lastPollAt: status.lastPollAt
-        } : {},
-        registryUrls: {
-            health: healthUrl,
-            status: statusUrl,
-            submissions: submissionsUrl
+        command: "extension_release_status",
+        status: "read",
+        value: {
+            workspace: ref.workspace,
+            project: ref.project,
+            stores: rows,
+            ...status.lastSubmission ? {
+                lastSubmission: status.lastSubmission
+            } : {},
+            ...status.lastPollAt ? {
+                lastPollAt: status.lastPollAt
+            } : {},
+            registryUrls: {
+                health: healthUrl,
+                status: statusUrl,
+                submissions: submissionsUrl
+            },
+            consoleStoresUrl
         },
-        consoleStoresUrl,
-        message: `${summaryParts.join(". ")}. This is the registry's recorded state (submissions and the review poller write it); the store dashboards are authoritative and may be ahead of it.`
-    };
-    if (!healthRes.ok) result.healthUnavailable = `stores/health.json unreadable: ${healthRes.message}`;
-    if (!statusRes.ok) result.statusUnavailable = `stores/status.json unreadable: ${statusRes.message}`;
-    if (!submissionsRes.ok && 404 !== submissionsRes.status) result.submissionsUnavailable = `stores/submissions.json unreadable: ${submissionsRes.message}`;
-    return JSON.stringify(result);
+        hint: `${summaryParts.join(". ")}. This is the registry's recorded state (submissions and the review poller write it); the store dashboards are authoritative and may be ahead of it.`,
+        warnings: [
+            healthUnavailable,
+            statusUnavailable,
+            submissionsUnavailable
+        ]
+    });
 }
 const release_status_schema = {
     name: "extension_release_status",
-    description: "Read where a project stands on extension.dev, from the public registry (registry.extension.land). Read-only: it dispatches nothing and promotes nothing. include:'releases' returns the release channels (channel -> promoted build sha), recent builds, and a public build-page URL for each, which is how you find a valid sha for extension_release_promote, extension_submit, or extension_publish. include:'stores' returns the per-store picture after an extension_submit (chrome, firefox, edge, safari): configured or not, the last credential health check, the last recorded submission, and the latest review status, read from stores/health.json, stores/status.json and stores/submissions.json. Both are included by default. Defaults to the logged-in project (extension_auth); pass workspace + project to read another. Private projects work when your stored login covers them. Registry state can lag the store dashboards by up to a polling interval.",
+    description: "Read where a project stands on extension.dev, from the public registry (registry.extension.land). This is read-only: it dispatches nothing and promotes nothing. Pass include:'releases' for the release channels (channel to promoted build sha), recent builds, and a public build-page URL for each, which is how you find a valid sha for extension_release_promote, extension_submit or extension_publish. Pass include:'stores' for the per-store picture after an extension_submit (chrome, firefox, edge, safari): configured or not, the last credential health check, the last recorded submission, and the latest review status, read from stores/health.json, stores/status.json and stores/submissions.json. Both are included by default. This defaults to the logged-in project (extension_auth); pass workspace and project to read another. Private projects work when your stored login covers them. Registry state can lag the store dashboards by up to a polling interval.",
     inputSchema: {
         type: "object",
         properties: {
@@ -8979,13 +9839,16 @@ function parse(raw) {
     try {
         return JSON.parse(raw);
     } catch  {
-        return {
+        return envelopeObject({
             ok: false,
+            command: "extension_release_status",
+            status: "unavailable",
             error: {
+                code: "E_PARSE",
                 name: "ParseError",
                 message: raw
             }
-        };
+        });
     }
 }
 async function release_status_handler(args) {
@@ -9006,14 +9869,19 @@ async function release_status_handler(args) {
         releases,
         stores
     ].filter(Boolean);
-    return JSON.stringify({
-        ok: sections.some((section)=>true === section.ok),
-        ...releases ? {
-            releases
-        } : {},
-        ...stores ? {
-            stores
-        } : {}
+    const ok = sections.some((section)=>true === section.ok);
+    return envelope({
+        ok,
+        command: "extension_release_status",
+        status: ok ? "read" : "unavailable",
+        value: {
+            ...releases ? {
+                releases
+            } : {},
+            ...stores ? {
+                stores
+            } : {}
+        }
     });
 }
 function storeMdWarnings(browsers, cwd) {
@@ -9044,7 +9912,7 @@ function storeMdWarnings(browsers, cwd) {
 }
 const submit_schema = {
     name: "extension_submit",
-    description: "SUBMIT FOR REVIEW: send a built extension to the Chrome Web Store, Firefox AMO, Edge Add-ons and/or the App Store (Safari) THROUGH extension.dev, which holds your store credentials and dispatches from your project's mirror CI. Store review only. It does NOT push a build to the extension.dev platform and does NOT make a shareable link: that is extension_publish, which is what \"deploy\" or \"ship\" an extension almost always means. Reach for this only when the ask is explicitly a store submission. DEFAULTS TO A DRY RUN that dispatches nothing: the platform verifies auth, project, build and store workflow, and this tool adds each store's credential-health verdict; trust those per-store rows over the platform's bare preflight line, which does not check store health. dryRun:false actually submits, which is irreversible and enters store review. The project comes from your token (extension_auth or EXTENSION_DEV_TOKEN; tokens live at most 7 days, so CI must re-mint from the console's Access tokens page). Store credentials are never arguments and no local file is uploaded. extension_release_status lists valid shas and, after a real submission, reads the recorded outcome and review state.",
+    description: "Submit a built extension for store REVIEW through extension.dev, which holds your store credentials and dispatches from your project's mirror CI: the Chrome Web Store, Firefox AMO, Edge Add-ons and the App Store (Safari). This is store review only. It does not push a build to the extension.dev platform, and it does not make a shareable link: that is extension_publish, which is what \"deploy\" or \"ship\" an extension almost always means. Reach for this only when the ask is explicitly a store submission. It defaults to a dry run that dispatches nothing: the platform verifies auth, project, build and store workflow, and this tool adds each store's credential-health verdict. Trust those per-store rows over the platform's bare preflight line, which does not check store health. Pass dryRun:false to actually submit, which is irreversible and enters store review. The project comes from your token (extension_auth or EXTENSION_DEV_TOKEN; tokens live at most 7 days, so CI must re-mint from the console's Access tokens page). Store credentials are never arguments, and no local file is uploaded. Call extension_release_status for valid shas, and, after a real submission, for the recorded outcome and review state.",
     inputSchema: {
         type: "object",
         properties: {
@@ -9086,10 +9954,13 @@ const submit_schema = {
         ]
     }
 };
-function submit_fail(name, message) {
-    return JSON.stringify({
+function submit_fail(name, message, status, code) {
+    return envelope({
         ok: false,
+        command: "extension_submit",
+        status,
         error: {
+            code,
             name,
             message
         }
@@ -9097,13 +9968,13 @@ function submit_fail(name, message) {
 }
 async function submit_handler(args) {
     const token = resolveToken();
-    if (!token) return submit_fail("SubmitAuthError", "No token. Run extension_auth (action: login), or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard under project settings -> Access tokens; tokens live at most 7 days, so CI must re-mint before expiry).");
+    if (!token) return submit_fail("SubmitAuthError", "No token. Run extension_auth (action: login), or set EXTENSION_DEV_TOKEN (create one in the extension.dev dashboard under project settings -> Access tokens; tokens live at most 7 days, so CI must re-mint before expiry).", "auth-required", "E_AUTH_REQUIRED");
     const browsers = (Array.isArray(args.browsers) ? args.browsers : []).map((b)=>String(b).trim().toLowerCase()).filter(Boolean);
-    if (0 === browsers.length) return submit_fail("SubmitInputError", 'browsers is required (e.g. ["chrome","firefox","edge","safari"]).');
+    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).");
+    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));
-    if (!apiCheck.ok) return submit_fail("SubmitConfigError", apiCheck.message);
+    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;
     const body = {
@@ -9125,7 +9996,7 @@ async function submit_handler(args) {
             body: JSON.stringify(body)
         });
     } catch (err) {
-        return submit_fail("SubmitNetworkError", `Could not reach ${url}: ${err?.message || err}`);
+        return submit_fail("SubmitNetworkError", `Could not reach ${url}: ${err?.message || err}`, "network-failed", "E_NETWORK");
     }
     const text = await res.text();
     let data;
@@ -9136,7 +10007,7 @@ async function submit_handler(args) {
             message: text
         };
     }
-    if (!res.ok) return submit_fail("SubmitError", `${dryRun ? "preflight" : "submit"} failed (${res.status}): ${data?.message || text || "unknown error"}`);
+    if (!res.ok) return submit_fail("SubmitError", `${dryRun ? "preflight" : "submit"} failed (${res.status}): ${data?.message || text || "unknown error"}`, "submit-failed", "E_PLATFORM");
     const warnings = Array.isArray(data?.warnings) ? [
         ...data.warnings
     ] : [];
@@ -9146,6 +10017,13 @@ async function submit_handler(args) {
         dryRun,
         ...data
     };
+    delete result.ok;
+    delete result.warnings;
+    delete result.message;
+    let ok = data?.ok !== false;
+    let message = "string" == typeof data?.message ? data.message : "";
+    let channelNote = null;
+    let statusNote = null;
     if (dryRun) {
         const ref = resolveProjectRef();
         const consoleStoresUrl = consoleProjectUrl(ref, "stores", args.api);
@@ -9213,18 +10091,28 @@ async function submit_handler(args) {
         if (actionable.length > 0) summaryParts.push(`Preflight passed for ${actionable.join(", ")}: the platform verified auth, the project, build ${data?.buildId ?? buildSha}, and the store workflow, and the store credentials passed their last health check.`);
         for (const p of blocked)summaryParts.push(`${p.browser}: ${"unknown" === p.configured ? "cannot be verified" : "NOT actionable"} - ${p.reason}`);
         summaryParts.push(storeModeNote);
-        result.ok = actionable.length > 0;
+        ok = actionable.length > 0;
         result.preflight = preflight;
         result.channel = resolvedChannel;
         result.channelDefaulted = channelDefaulted;
-        if (channelDefaulted) result.channelNote = `channel: ${resolvedChannel} (default)`;
+        if (channelDefaulted) channelNote = `channel: ${resolvedChannel} (default)`;
         result.consoleStoresUrl = consoleStoresUrl;
         if ("string" == typeof data?.message) result.platformMessage = data.message;
-        result.message = summaryParts.join(" ");
-    }
-    if (!dryRun) result.statusNote = "Track this submission with extension_release_status: it reads the recorded outcome, per-store credential health, and review state from the public registry.";
-    if (warnings.length > 0) result.warnings = warnings;
-    return JSON.stringify(result);
+        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({
+        ok,
+        command: "extension_submit",
+        status: dryRun ? "preflight" : "submitted",
+        value: result,
+        hint: message,
+        warnings: [
+            ...warnings,
+            channelNote,
+            statusNote
+        ]
+    });
 }
 const ENGINE_COMPANION_IDS = new Set([
     "kgdaecdpfkikjncaalnmmnjjfpofkcbl",
@@ -9293,7 +10181,7 @@ function doctor_readReadyContract(projectPath, browser) {
 }
 const doctor_schema = {
     name: "extension_doctor",
-    description: "Diagnose a dev session end-to-end: ready contract, dev-server process, control-port agreement, control channel, eval token, executor, browser liveness. Returns one {check, status, detail, remediation?} per leg in dependency order; a 'skip' names the check that blocked it and is NOT a pass. Run this first when any act tool (storage/reload/eval/open) errors unexpectedly. Call with no projectPath for a pre-flight environment check (node, extension CLI, template cache) before any project exists.",
+    description: "Diagnose a dev session end to end: ready contract, dev-server process, control-port agreement, control channel, eval token, executor, browser liveness. This returns one {check, status, detail, remediation?} per leg, in dependency order. Read a 'skip' as blocked, not as a pass: it names the check that blocked it. Run this first when any act tool (storage, reload, eval, open) errors unexpectedly. Call it with no projectPath for a pre-flight environment check (node, the Extension.js CLI, the template cache) before any project exists.",
     inputSchema: {
         type: "object",
         properties: {
@@ -9337,16 +10225,21 @@ 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 JSON.stringify({
-        mode: "environment",
-        healthy,
-        checks,
+    return envelope({
+        ok: healthy,
+        command: doctor_schema.name,
+        status: healthy ? "healthy" : "unhealthy",
+        value: {
+            mode: "environment",
+            checks
+        },
         hint: "Pass projectPath to diagnose a live dev session end-to-end."
     });
 }
 function safeStringify(value) {
     try {
-        return JSON.stringify(value) ?? String(value);
+        const text = JSON.stringify(value);
+        return text ?? String(value);
     } catch  {
         return String(value);
     }
@@ -9402,7 +10295,8 @@ async function doctor_handler(args) {
     });
     const out = stdout.trim();
     try {
-        const checks = JSON.parse(out);
+        const parsed = JSON.parse(out);
+        const checks = isEnvelope(parsed) ? parsed.value?.checks : parsed;
         if (!Array.isArray(checks)) throw new Error("not a check array");
         for (const check of checks){
             if ("string" == typeof check.detail) check.detail = toMcpSpeak(check.detail);
@@ -9445,23 +10339,30 @@ async function doctor_handler(args) {
                 } : {}
             });
         }
-        return JSON.stringify({
-            browser,
-            ...engineVersion ? {
-                engineVersion
-            } : {},
-            healthy,
-            checks
+        return envelope({
+            ok: healthy,
+            command: doctor_schema.name,
+            status: healthy ? "healthy" : "unhealthy",
+            value: {
+                browser,
+                ...engineVersion ? {
+                    engineVersion
+                } : {},
+                checks
+            }
         });
     } catch  {
         const message = stderr.trim() || `extension exited with code ${code}`;
-        return JSON.stringify({
+        return envelope({
             ok: false,
+            command: doctor_schema.name,
+            status: "cli-failed",
             error: {
+                code: "E_CLI",
                 name: "CliError",
-                message: toMcpSpeak(message),
-                hint: "extension doctor requires a recent extension CLI, the project's local install may predate it."
-            }
+                message: toMcpSpeak(message)
+            },
+            hint: "extension doctor requires a recent extension CLI, the project's local install may predate it."
         });
     }
 }
@@ -9478,7 +10379,7 @@ function wait_isAlive(pid) {
 }
 const wait_schema = {
     name: "extension_wait",
-    description: "Wait for a running dev or start session to be ready. Polls the ready.json contract and reports compiled (the compiler finished), browserAttached (the runtime executor connected), and guestLoaded (the browser's OWN target list shows your extension). guestLoaded is the trustworthy load signal: it catches a silently rejected --load-extension that leaves ready.json stamped attached with empty logs; it is null when it could not be checked (no CDP port, e.g. a gecko session). Every result reports budgetMs and elapsedMs; on status:'timeout' call again to keep waiting on the same contract. In a noBrowser session it returns as soon as the compile lands instead of waiting for a browser that will never attach. Ports come from the contract, so they match what the server actually bound.",
+    description: "Wait for a running dev or start session to be ready. This polls the ready.json contract and reports compiled (the compiler finished), browserAttached (the runtime executor connected), and guestLoaded (the browser's own target list shows your extension). Read guestLoaded as the trustworthy load signal: it catches a silently rejected --load-extension that leaves ready.json stamped attached with empty logs. It is null when it could not be checked, for example a gecko session with no CDP port. Every result reports budgetMs and elapsedMs; on status 'timeout', call again to keep waiting on the same contract. In a noBrowser session this returns as soon as the compile lands, instead of waiting for a browser that will never attach. Ports come from the contract, so they match what the server actually bound.",
     inputSchema: {
         type: "object",
         properties: {
@@ -9516,31 +10417,42 @@ async function wait_handler(args) {
             const contract = JSON.parse(raw);
             lastContractStatus = contract.status;
             if ("ready" === contract.status) {
-                if ("number" == typeof contract.pid && !wait_isAlive(contract.pid)) return JSON.stringify({
+                if ("number" == typeof contract.pid && !wait_isAlive(contract.pid)) return envelope({
+                    ok: false,
+                    command: wait_schema.name,
                     status: "stale",
-                    message: `ready.json reports ready but its dev-server pid ${contract.pid} is dead, the session exited. Restart with extension_dev; extension_doctor will confirm.`,
-                    browser: contract.browser,
-                    pid: contract.pid,
-                    budgetMs,
-                    elapsedMs: Date.now() - start
+                    error: {
+                        code: "E_STALE_CONTRACT",
+                        message: `ready.json reports ready but its dev-server pid ${contract.pid} is dead, the session exited. Restart with extension_dev; extension_doctor will confirm.`
+                    },
+                    value: {
+                        browser: contract.browser,
+                        pid: contract.pid,
+                        budgetMs,
+                        elapsedMs: Date.now() - start
+                    }
                 });
                 const attached = "attached" === contract.runtime || "string" == typeof contract.executorAttachedAt;
-                if (!attached && buildOnly) return JSON.stringify({
+                if (!attached && buildOnly) return envelope({
+                    ok: true,
+                    command: wait_schema.name,
                     status: "ready",
-                    buildOnly: true,
-                    compiled: true,
-                    browserAttached: false,
-                    message: "Build-only session (noBrowser): the extension compiled and the dev server is live, but no browser was launched, so browserAttached will never become true. Do not call extension_wait again to wait for a browser. The control verbs (storage/reload/open/dom_snapshot/eval) need a live browser and will not work against this session.",
-                    command: contract.command,
-                    browser: contract.browser,
-                    port: contract.port,
-                    pid: contract.pid,
-                    distPath: contract.distPath,
-                    manifestPath: contract.manifestPath,
-                    compiledAt: contract.compiledAt,
-                    startedAt: contract.startedAt,
-                    budgetMs,
-                    elapsedMs: Date.now() - start
+                    value: {
+                        buildOnly: true,
+                        compiled: true,
+                        browserAttached: false,
+                        sessionCommand: contract.command,
+                        browser: contract.browser,
+                        port: contract.port,
+                        pid: contract.pid,
+                        distPath: contract.distPath,
+                        manifestPath: contract.manifestPath,
+                        compiledAt: contract.compiledAt,
+                        startedAt: contract.startedAt,
+                        budgetMs,
+                        elapsedMs: Date.now() - start
+                    },
+                    hint: "Build-only session (noBrowser): the extension compiled and the dev server is live, but no browser was launched, so browserAttached will never become true. Do not call extension_wait again to wait for a browser. The control verbs (storage/reload/open/dom_snapshot/eval) need a live browser and will not work against this session."
                 });
                 if (!attached) {
                     await new Promise((r)=>setTimeout(r, pollInterval));
@@ -9552,72 +10464,98 @@ 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 JSON.stringify({
+                return envelope({
+                    ok: true,
+                    command: wait_schema.name,
                     status: "ready",
-                    compiled: true,
-                    browserAttached: true,
-                    guestLoaded: guestCheck.checked ? guestCheck.loaded : null,
-                    ...guestCheck.checked ? {
-                        guestIds: guestCheck.guestIds
-                    } : {
-                        guestLoadNote: guestCheck.reason
+                    value: {
+                        compiled: true,
+                        browserAttached: true,
+                        guestLoaded: guestCheck.checked ? guestCheck.loaded : null,
+                        ...guestCheck.checked ? {
+                            guestIds: guestCheck.guestIds
+                        } : {
+                            guestLoadNote: guestCheck.reason
+                        },
+                        sessionCommand: contract.command,
+                        browser: contract.browser,
+                        port: contract.port,
+                        pid: contract.pid,
+                        distPath: contract.distPath,
+                        manifestPath: contract.manifestPath,
+                        compiledAt: contract.compiledAt,
+                        startedAt: contract.startedAt,
+                        budgetMs,
+                        elapsedMs: Date.now() - start,
+                        ...runtimeErrors.length ? {
+                            runtimeErrors
+                        } : {}
                     },
-                    command: contract.command,
-                    browser: contract.browser,
-                    port: contract.port,
-                    pid: contract.pid,
-                    distPath: contract.distPath,
-                    manifestPath: contract.manifestPath,
-                    compiledAt: contract.compiledAt,
-                    startedAt: contract.startedAt,
-                    budgetMs,
-                    elapsedMs: Date.now() - start,
-                    ...runtimeErrors.length ? {
-                        runtimeErrors
-                    } : {},
-                    ...warnings.length ? {
-                        warning: warnings.join(" ")
-                    } : {}
+                    warnings
                 });
             }
-            if ("error" === contract.status) return JSON.stringify({
-                status: "error",
-                message: contract.message,
-                errors: contract.errors,
-                code: contract.code,
-                browser: contract.browser,
-                budgetMs,
-                elapsedMs: Date.now() - start
+            if ("error" === contract.status) return envelope({
+                ok: false,
+                command: wait_schema.name,
+                status: "contract-error",
+                error: {
+                    code: contract.code ? `E_${String(contract.code).toUpperCase()}` : "E_CONTRACT_ERROR",
+                    message: contract.message ?? "The dev server stamped its ready contract with an error.",
+                    contractCode: contract.code
+                },
+                value: {
+                    errors: contract.errors,
+                    browser: contract.browser,
+                    budgetMs,
+                    elapsedMs: Date.now() - start
+                }
             });
         } catch  {}
         await new Promise((resolve)=>setTimeout(resolve, pollInterval));
     }
-    if (sawCompiledButUnattached) return JSON.stringify({
+    if (sawCompiledButUnattached) return envelope({
+        ok: false,
+        command: wait_schema.name,
         status: "compiled-not-attached",
-        compiled: true,
-        browserAttached: false,
-        message: `The extension compiled, but the runtime executor never attached within this call's ${budgetMs}ms budget. The build is fine; the browser side is not connected, so extension_eval/storage/reload/open will fail with "no executor connected".`,
-        readyPath,
-        budgetMs,
-        elapsedMs: Date.now() - start,
+        error: {
+            code: "E_NOT_ATTACHED",
+            message: `The extension compiled, but the runtime executor never attached within this call's ${budgetMs}ms budget. The build is fine; the browser side is not connected, so extension_eval/storage/reload/open will fail with "no executor connected".`
+        },
+        value: {
+            compiled: true,
+            browserAttached: false,
+            readyPath,
+            budgetMs,
+            elapsedMs: Date.now() - start
+        },
         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 JSON.stringify({
+    return envelope({
+        ok: false,
+        command: wait_schema.name,
         status: "timeout",
-        compiled: false,
-        browserAttached: false,
-        message: "starting" === lastContractStatus ? `Not ready after ${budgetMs}ms this call: the dev server stamped its contract (status: starting) but the first compile has not landed yet.` : `Not ready after ${budgetMs}ms this call: no ready contract was observed at ${readyPath}, so neither the compile nor a browser attach has been seen.`,
-        readyPath,
-        budgetMs,
-        elapsedMs: Date.now() - start,
-        clamped: clamped ? `requested ${requested}ms was clamped to ${SAFE_CEILING_MS}ms to stay under the MCP client request timeout` : void 0,
+        error: {
+            code: "E_WAIT_TIMEOUT",
+            message: "starting" === lastContractStatus ? `Not ready after ${budgetMs}ms this call: the dev server stamped its contract (status: starting) but the first compile has not landed yet.` : `Not ready after ${budgetMs}ms this call: no ready contract was observed at ${readyPath}, so neither the compile nor a browser attach has been seen.`
+        },
+        value: {
+            compiled: false,
+            browserAttached: false,
+            readyPath,
+            budgetMs,
+            elapsedMs: Date.now() - start
+        },
+        warnings: [
+            clamped ? `requested ${requested}ms was clamped to ${SAFE_CEILING_MS}ms to stay under the MCP client request timeout` : null
+        ],
         hint: "Still building, call extension_wait again to keep waiting (it resumes polling the same contract). If it never readies, check the dev process with extension_doctor."
     });
 }
+const add_feature_COMMAND = "extension_add_feature";
 const EXAMPLES_TREE_BASE = `https://github.com/extension-js/examples/tree/${PINNED_COMMIT}/examples`;
 const add_feature_schema = {
     name: "extension_add_feature",
-    description: "Plan a new feature surface for an existing extension. Returns step-by-step instructions, the manifest additions to make, and reference templates from the extension.dev catalog. Does not modify files; apply the returned plan yourself.",
+    description: "Plan a new feature surface for an existing extension. This returns step-by-step instructions, the manifest additions to make, and reference templates from the extension.dev catalog. It modifies no files: apply the returned plan yourself.",
     inputSchema: {
         type: "object",
         properties: {
@@ -9769,13 +10707,25 @@ 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 JSON.stringify({
-        error: `No manifest.json found at ${manifestPath}`,
+    if (!node_fs.existsSync(manifestPath)) return envelope({
+        ok: false,
+        command: add_feature_COMMAND,
+        status: "manifest-not-found",
+        error: {
+            code: "E_MANIFEST_NOT_FOUND",
+            message: `No manifest.json found at ${manifestPath}`
+        },
         hint: "Ensure projectPath points to an extension project root with src/manifest.json"
     });
     const templateSlug = FEATURE_TEMPLATE_MAP[args.feature]?.[framework];
-    if (!templateSlug) return JSON.stringify({
-        error: `No reference template for feature "${args.feature}" with framework "${framework}"`
+    if (!templateSlug) return envelope({
+        ok: false,
+        command: add_feature_COMMAND,
+        status: "no-reference-template",
+        error: {
+            code: "E_NO_REFERENCE_TEMPLATE",
+            message: `No reference template for feature "${args.feature}" with framework "${framework}"`
+        }
     });
     const template = await getTemplateBySlug(templateSlug);
     const referenceFiles = template?.keyFiles ?? template?.files ?? [];
@@ -9850,29 +10800,40 @@ async function add_feature_handler(args) {
         hint: "Background service worker / script"
     });
     const conflicts = filesToCreate.filter((f)=>node_fs.existsSync(node_path.join(projectPath, f.path)));
-    return JSON.stringify({
-        feature: args.feature,
-        framework,
-        referenceTemplate: {
-            slug: templateSlug,
-            repositoryUrl: `${EXAMPLES_TREE_BASE}/${templateSlug}`,
-            referenceFiles: referenceFiles.filter((f)=>f.includes(featureDir) || f.includes("manifest"))
+    const conflictHint = `Warning: ${conflicts.length} file(s) already exist and would be overwritten.`;
+    return envelope({
+        ok: true,
+        command: add_feature_COMMAND,
+        status: conflicts.length ? "planned-with-conflicts" : "planned",
+        value: {
+            feature: args.feature,
+            framework,
+            referenceTemplate: {
+                slug: templateSlug,
+                repositoryUrl: `${EXAMPLES_TREE_BASE}/${templateSlug}`,
+                referenceFiles: referenceFiles.filter((f)=>f.includes(featureDir) || f.includes("manifest"))
+            },
+            manifestUpdates,
+            filesToCreate: filesToCreate.map((f)=>({
+                    ...f,
+                    exists: node_fs.existsSync(node_path.join(projectPath, f.path))
+                })),
+            conflicts: conflicts.map((c)=>c.path),
+            instructions: [
+                `1. Add these fields to your src/manifest.json:\n${JSON.stringify(manifestUpdates, null, 2)}`,
+                "2. Create the following files in your project:",
+                ...filesToCreate.map((f)=>`   - ${f.path} (${f.hint})`),
+                "sidebar" === args.feature ? "3. Add background.ts to handle sidebar open: chromium uses chrome.sidePanel.setPanelBehavior, firefox uses browser.sidebarAction.open()" : "",
+                `4. Reference template source: ${EXAMPLES_TREE_BASE}/${templateSlug}/src`,
+                "5. Run npm run dev to test"
+            ].filter(Boolean)
         },
-        manifestUpdates,
-        filesToCreate: filesToCreate.map((f)=>({
-                ...f,
-                exists: node_fs.existsSync(node_path.join(projectPath, f.path))
-            })),
-        conflicts: conflicts.map((c)=>c.path),
-        instructions: [
-            `1. Add these fields to your src/manifest.json:\n${JSON.stringify(manifestUpdates, null, 2)}`,
-            "2. Create the following files in your project:",
-            ...filesToCreate.map((f)=>`   - ${f.path} (${f.hint})`),
-            "sidebar" === args.feature ? "3. Add background.ts to handle sidebar open: chromium uses chrome.sidePanel.setPanelBehavior, firefox uses browser.sidebarAction.open()" : "",
-            `4. Reference template source: ${EXAMPLES_TREE_BASE}/${templateSlug}/src`,
-            "5. Run npm run dev to test"
-        ].filter(Boolean),
-        hint: conflicts.length ? `Warning: ${conflicts.length} file(s) already exist and would be overwritten.` : "No conflicts detected. Safe to create all files."
+        warnings: conflicts.length ? [
+            conflictHint
+        ] : [],
+        ...conflicts.length ? {} : {
+            hint: "No conflicts detected. Safe to create all files."
+        }
     });
 }
 async function requestDeviceCode(args) {
@@ -9969,10 +10930,14 @@ async function pollDeviceToken(args) {
 }
 const FIRST_CALL_BUDGET_MS = 8000;
 const RESUME_BUDGET_MS = 22000;
-function login_fail(name, message) {
-    return JSON.stringify({
+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({
         ok: false,
+        command: "extension_auth",
+        status,
         error: {
+            code,
             name,
             message
         }
@@ -9980,52 +10945,78 @@ function login_fail(name, message) {
 }
 function success(creds) {
     const expiresAt = creds.expiresAt ? new Date(1000 * creds.expiresAt).toISOString() : null;
-    return JSON.stringify({
+    return envelope({
         ok: true,
+        command: "extension_auth",
         status: "logged-in",
-        workspaceSlug: creds.workspaceSlug,
-        projectSlug: creds.projectSlug,
-        expiresAt,
-        tokenTtlNote: tokenTtlNote(creds.workspaceSlug, creds.projectSlug),
-        message: `Logged in to ${creds.workspaceSlug}/${creds.projectSlug}. extension_publish can now use the stored token. The token expires ${expiresAt ?? "within 7 days"}: extension.dev CLI tokens live at most 7 days, so CI must re-mint before then (console: project settings -> Access tokens).`
+        value: {
+            workspaceSlug: creds.workspaceSlug,
+            projectSlug: creds.projectSlug,
+            expiresAt
+        },
+        hint: `Logged in to ${creds.workspaceSlug}/${creds.projectSlug}. extension_publish can now use the stored token. The token expires ${expiresAt ?? "within 7 days"}: extension.dev CLI tokens live at most 7 days, so CI must re-mint before then (console: project settings -> Access tokens).`,
+        warnings: [
+            tokenTtlNote(creds.workspaceSlug, creds.projectSlug)
+        ]
     });
 }
 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 JSON.stringify({
+    return envelope({
         ok: false,
-        status: "authorization_pending",
-        userCode: start.userCode,
-        verificationUri: start.verificationUri,
-        ...hasCompleteLink ? {
-            verificationUriComplete: complete
-        } : {},
-        deviceCode: start.deviceCode,
-        tokenTtlNote: "Once authorized, the minted token lives at most 7 days (server-enforced); CI must re-mint before expiry (console: project settings -> Access tokens).",
-        message
+        command: "extension_auth",
+        status: "authorization-pending",
+        error: {
+            code: "E_AUTH_PENDING",
+            message
+        },
+        value: {
+            userCode: start.userCode,
+            verificationUri: start.verificationUri,
+            ...hasCompleteLink ? {
+                verificationUriComplete: complete
+            } : {},
+            deviceCode: start.deviceCode,
+            legacyStatus: "authorization_pending"
+        },
+        hint: message,
+        warnings: [
+            PENDING_TTL_NOTE
+        ]
     });
 }
 function resumePending(deviceCode, verificationUri) {
-    return JSON.stringify({
+    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({
         ok: false,
-        status: "authorization_pending",
-        verificationUri,
-        deviceCode,
-        tokenTtlNote: "Once authorized, the minted token lives at most 7 days (server-enforced); CI must re-mint before expiry (console: project settings -> Access tokens).",
-        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.`
+        command: "extension_auth",
+        status: "authorization-pending",
+        error: {
+            code: "E_AUTH_PENDING",
+            message
+        },
+        value: {
+            verificationUri,
+            deviceCode,
+            legacyStatus: "authorization_pending"
+        },
+        hint: message,
+        warnings: [
+            PENDING_TTL_NOTE
+        ]
     });
 }
 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>'.");
+    if (!/^[^/]+\/[^/]+$/.test(project)) return login_fail("BadRequest", "project must be in the form '<workspace>/<project>'.", "bad-request", "E_BAD_REQUEST");
     const apiBase = resolveApiBase(args.api);
     let config;
     try {
         config = await fetchLoginConfig(apiBase);
     } catch (err) {
-        return login_fail("LoginConfigError", err?.message || "Could not load login config.");
+        return login_fail("LoginConfigError", err?.message || "Could not load login config.", "login-failed", "E_AUTH_FAILED");
     }
     if (args.deviceCode) {
         const poll = await pollDeviceToken({
@@ -10037,9 +11028,9 @@ async function loginToProject(args) {
             budgetMs: RESUME_BUDGET_MS
         });
         if (poll.ok) return success(poll.creds);
-        if ("expired" === poll.reason) return login_fail("LoginExpired", "The device code expired. Run extension_auth (action: login) again to restart.");
-        if ("denied" === poll.reason) return login_fail("LoginDenied", "Authorization was denied at extension.dev/device.");
-        if ("error" === poll.reason) return login_fail("LoginError", poll.message || "Device login failed.");
+        if ("expired" === poll.reason) return login_fail("LoginExpired", "The device code expired. Run extension_auth (action: login) again to restart.", "login-expired", "E_AUTH_EXPIRED");
+        if ("denied" === poll.reason) return login_fail("LoginDenied", "Authorization was denied at extension.dev/device.", "login-denied", "E_AUTH_DENIED");
+        if ("error" === poll.reason) return login_fail("LoginError", poll.message || "Device login failed.", "login-failed", "E_AUTH_FAILED");
         return resumePending(String(args.deviceCode), config.verificationUri);
     }
     let start;
@@ -10050,7 +11041,7 @@ async function loginToProject(args) {
             project
         });
     } catch (err) {
-        return login_fail("LoginStartError", err?.message || "Could not start the device flow.");
+        return login_fail("LoginStartError", err?.message || "Could not start the device flow.", "login-failed", "E_AUTH_FAILED");
     }
     const poll = await pollDeviceToken({
         apiBase,
@@ -10061,7 +11052,7 @@ async function loginToProject(args) {
         budgetMs: FIRST_CALL_BUDGET_MS
     });
     if (poll.ok) return success(poll.creds);
-    if ("denied" === poll.reason) return login_fail("LoginDenied", "Authorization was denied at extension.dev/device.");
+    if ("denied" === poll.reason) return login_fail("LoginDenied", "Authorization was denied at extension.dev/device.", "login-denied", "E_AUTH_DENIED");
     return login_pending({
         deviceCode: start.deviceCode,
         userCode: start.userCode,
@@ -10071,10 +11062,12 @@ async function loginToProject(args) {
 }
 async function readIdentity() {
     const creds = readCredentials();
-    if (!creds) return JSON.stringify({
+    if (!creds) return envelope({
         ok: true,
+        command: "extension_auth",
         status: "logged-out",
-        message: "No stored credentials. Run extension_auth (action: login) to authenticate."
+        value: {},
+        hint: "No stored credentials. Run extension_auth (action: login) to authenticate."
     });
     const now = Math.floor(Date.now() / 1000);
     const expired = Boolean(creds.expiresAt && creds.expiresAt <= now);
@@ -10082,28 +11075,36 @@ async function readIdentity() {
     const effectiveDefaultApi = resolveApiBase();
     const apiDiverges = Boolean(recordedApi) && recordedApi !== effectiveDefaultApi;
     const envTokenSet = Boolean(String(process.env.EXTENSION_DEV_TOKEN || "").trim());
-    const messageParts = [];
-    messageParts.push(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.`);
-    if (apiDiverges) messageParts.push(`This login was minted via ${recordedApi}, but authenticated tools do not read that recorded value: they target ${effectiveDefaultApi} unless given an api argument.`);
-    if (envTokenSet) messageParts.push("EXTENSION_DEV_TOKEN is set and takes precedence over this stored login for authenticated tools; this report describes only the stored login.");
-    return JSON.stringify({
+    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}, but authenticated tools do not read that recorded value: they target ${effectiveDefaultApi} unless given an api argument.` : 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,
+        apiDivergesNote,
+        envTokenNote
+    ].filter(Boolean).join(" ");
+    return envelope({
         ok: true,
+        command: "extension_auth",
         status: expired ? "expired" : "logged-in",
-        workspaceSlug: creds.workspaceSlug,
-        projectSlug: creds.projectSlug,
-        ...recordedApi ? {
-            apiRecordedAtLogin: recordedApi
-        } : {},
-        apiDefault: effectiveDefaultApi,
-        provider: creds.provider ?? "extensiondev",
-        expiresAt: creds.expiresAt ? new Date(1000 * creds.expiresAt).toISOString() : null,
-        expiresInSeconds: creds.expiresAt ? creds.expiresAt - now : null,
-        expired,
-        ...envTokenSet ? {
-            envTokenOverride: true
-        } : {},
-        tokenTtlNote: tokenTtlNote(creds.workspaceSlug, creds.projectSlug),
-        message: messageParts.join(" ")
+        value: {
+            workspaceSlug: creds.workspaceSlug,
+            projectSlug: creds.projectSlug,
+            ...recordedApi ? {
+                apiRecordedAtLogin: recordedApi
+            } : {},
+            apiDefault: effectiveDefaultApi,
+            provider: creds.provider ?? "extensiondev",
+            expiresAt: creds.expiresAt ? new Date(1000 * creds.expiresAt).toISOString() : null,
+            expiresInSeconds: creds.expiresAt ? creds.expiresAt - now : null,
+            expired
+        },
+        hint: message,
+        warnings: [
+            tokenTtlNote(creds.workspaceSlug, creds.projectSlug),
+            apiDivergesNote,
+            envTokenNote
+        ]
     });
 }
 async function clearLocalCredentials() {
@@ -10113,18 +11114,20 @@ async function clearLocalCredentials() {
         project: creds.projectSlug
     }, "settings/access-tokens") : null;
     const result = clearCredentials();
-    return JSON.stringify({
+    return envelope({
         ok: true,
-        cleared: result.cleared,
-        ...result.cleared && revokeUrl ? {
-            revokeUrl
-        } : {},
-        message: result.cleared ? revokeUrl ? `Local credentials removed. The token stays valid server-side until it expires; revoke it now at ${revokeUrl} (takes about a minute to propagate).` : "Local credentials removed. The token stays valid server-side until it expires; revoke it from the project's access-tokens page if needed." : "No stored credentials to remove."
+        command: "extension_auth",
+        status: result.cleared ? "logged-out" : "nothing-to-clear",
+        value: {
+            cleared: result.cleared,
+            revokeUrl: result.cleared && revokeUrl ? revokeUrl : null
+        },
+        hint: result.cleared ? revokeUrl ? `Local credentials removed. The token stays valid server-side until it expires; revoke it now at ${revokeUrl} (takes about a minute to propagate).` : "Local credentials removed. The token stays valid server-side until it expires; revoke it from the project's access-tokens page if needed." : "No stored credentials to remove."
     });
 }
 const auth_schema = {
     name: "extension_auth",
-    description: "Sign this machine in to extension.dev, report that login, or clear it. action:'status' (default) names the workspace/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. action:'login' is two-phase: 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. action:'logout' deletes the local credentials only; the token stays valid server-side until 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. 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: {
@@ -10444,12 +11447,17 @@ async function detectBrowsers(browsers) {
     }
     const available = detected.filter((d)=>"not_found" !== d.source);
     const missing = detected.filter((d)=>"not_found" === d.source);
-    return JSON.stringify({
-        detected,
-        managed,
-        summary: {
-            available: available.map((d)=>d.browser),
-            missing: missing.map((d)=>d.browser)
+    return envelope({
+        ok: true,
+        command: "extension_browsers",
+        status: "detected",
+        value: {
+            detected,
+            managed,
+            summary: {
+                available: available.map((d)=>d.browser),
+                missing: missing.map((d)=>d.browser)
+            }
         },
         hint: missing.length ? `Missing browser(s): ${missing.map((d)=>d.browser).join(", ")}.${missing.some((d)=>MANAGED_INSTALLABLE.has(d.browser)) ? ` Use extension_browsers with action: "install" to install ${missing.filter((d)=>MANAGED_INSTALLABLE.has(d.browser)).map((d)=>d.browser).join(", ")}.` : ""}` : "All requested browsers are available."
     });
@@ -10496,11 +11504,16 @@ async function listManagedBrowsers() {
             });
         }
     }
-    return JSON.stringify({
-        cacheRoot,
-        cacheExists: existsSync(cacheRoot),
-        installed,
-        availableToInstall: BROWSER_NAMES.filter((b)=>!installed.some((i)=>i.browser === b)),
+    return envelope({
+        ok: true,
+        command: "extension_browsers",
+        status: "listed",
+        value: {
+            cacheRoot,
+            cacheExists: existsSync(cacheRoot),
+            installed,
+            availableToInstall: BROWSER_NAMES.filter((b)=>!installed.some((i)=>i.browser === b))
+        },
         hint: 0 === installed.length ? "No managed browsers found. Use extension_browsers with action: \"install\" to install one, or use a system-installed browser." : `${installed.length} managed browser(s) found. Use extension_browsers with action: "detect" for a full system scan.`
     });
 }
@@ -10510,51 +11523,78 @@ async function installManagedBrowser(browser) {
         await extensionInstall({
             browser
         });
-        return JSON.stringify({
+        return envelope({
+            ok: true,
+            command: "extension_browsers",
             status: "installed",
-            browser,
-            duration: Date.now() - start,
+            value: {
+                browser,
+                duration: Date.now() - start
+            },
             hint: `Browser "${browser}" is now available. Use extension_dev or extension_start with browser: "${browser}".`
         });
     } catch (err) {
-        return JSON.stringify({
-            status: "error",
-            browser,
-            message: err instanceof Error ? err.message : String(err),
-            duration: Date.now() - start,
+        return envelope({
+            ok: false,
+            command: "extension_browsers",
+            status: "install-failed",
+            value: {
+                browser,
+                duration: Date.now() - start
+            },
+            error: {
+                code: "E_BROWSER_INSTALL",
+                message: err instanceof Error ? err.message : String(err)
+            },
             hint: "edge" === browser ? "Edge installation on Linux may require elevated privileges. Try using Chrome or Chromium instead." : "Check network connectivity and disk space. You can also install browsers manually."
         });
     }
 }
 async function uninstallManagedBrowser(args) {
     const start = Date.now();
-    if (!args.browser && !args.all) return JSON.stringify({
-        status: "error",
-        message: "Provide a browser to remove, or set all: true."
+    if (!args.browser && !args.all) return envelope({
+        ok: false,
+        command: "extension_browsers",
+        status: "bad-request",
+        error: {
+            code: "E_BAD_REQUEST",
+            message: "Provide a browser to remove, or set all: true."
+        }
     });
     try {
         await extensionUninstall({
             browser: args.browser,
             all: args.all
         });
-        return JSON.stringify({
+        return envelope({
+            ok: true,
+            command: "extension_browsers",
             status: "uninstalled",
-            target: args.all ? "all" : args.browser,
-            duration: Date.now() - start,
+            value: {
+                target: args.all ? "all" : args.browser,
+                duration: Date.now() - start
+            },
             hint: 'Use extension_browsers with action: "list" to confirm what remains in the managed cache.'
         });
     } catch (err) {
-        return JSON.stringify({
-            status: "error",
-            target: args.all ? "all" : args.browser,
-            message: err instanceof Error ? err.message : String(err),
-            duration: Date.now() - start
+        return envelope({
+            ok: false,
+            command: "extension_browsers",
+            status: "uninstall-failed",
+            value: {
+                target: args.all ? "all" : args.browser,
+                duration: Date.now() - start
+            },
+            error: {
+                code: "E_BROWSER_UNINSTALL",
+                message: err instanceof Error ? err.message : String(err)
+            }
         });
     }
 }
 const browsers_schema = {
     name: "extension_browsers",
-    description: "Find, install, and remove the browsers extension tooling can launch. action:'detect' (default) scans BOTH system-installed and managed browsers and reports each one's binary path, version, engine, and debugger support. action:'list' reports only the managed cache this tool downloads into, with sizes on disk. action:'install' downloads a managed binary: ~580-625 MB in one blocking call, so allow a generous client timeout. action:'uninstall' removes managed binaries and never touches a system install.",
+    description: "Find, install and remove the browsers Extension.js tooling can launch. Pass action:'detect' (the default) to scan both system-installed and managed browsers, and report each one's binary path, version, engine and debugger support. Pass action:'list' for the managed cache this tool downloads into, with sizes on disk. Pass action:'install' to download a managed binary: 580 to 625 MB in one blocking call, so allow a generous client timeout. Pass action:'uninstall' to remove managed binaries; it never touches a system install.",
     inputSchema: {
         type: "object",
         properties: {
@@ -10594,10 +11634,14 @@ async function browsers_handler(args) {
     const action = args.action ?? "detect";
     if ("list" === action) return listManagedBrowsers();
     if ("install" === action) {
-        if (!args.browser) return JSON.stringify({
+        if (!args.browser) return envelope({
             ok: false,
-            status: "error",
-            message: "action 'install' needs a browser: one of chrome, chromium, edge, firefox."
+            command: "extension_browsers",
+            status: "bad-request",
+            error: {
+                code: "E_BAD_REQUEST",
+                message: "action 'install' needs a browser: one of chrome, chromium, edge, firefox."
+            }
         });
         return installManagedBrowser(args.browser);
     }
@@ -10759,11 +11803,16 @@ function describeToolArgs(inputSchema) {
     };
 }
 function inputValidationError(toolName, issues, inputSchema) {
-    return JSON.stringify({
+    return envelope({
         ok: false,
+        command: toolName,
+        status: "invalid-arguments",
         error: {
+            code: "E_INPUT_VALIDATION",
             name: "InputValidationError",
-            message: `Invalid arguments for ${toolName}: ${issues.map((i)=>`${i.path}: ${i.message}`).join("; ")}`,
+            message: `Invalid arguments for ${toolName}: ${issues.map((i)=>`${i.path}: ${i.message}`).join("; ")}`
+        },
+        value: {
             issues,
             ...inputSchema ? {
                 args: describeToolArgs(inputSchema)
@@ -10826,9 +11875,17 @@ async function startServer() {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify({
-                        error: `Unknown tool: ${name}`,
-                        availableTools: tools.map((t)=>t.schema.name)
+                    text: envelope({
+                        ok: false,
+                        command: name,
+                        status: "unknown-tool",
+                        error: {
+                            code: "E_UNKNOWN_TOOL",
+                            message: `Unknown tool: ${name}`
+                        },
+                        value: {
+                            availableTools: tools.map((t)=>t.schema.name)
+                        }
                     })
                 }
             ],
@@ -10860,9 +11917,15 @@ async function startServer() {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({
-                            error: err instanceof Error ? err.message : String(err),
-                            tool: name
+                        text: envelope({
+                            ok: false,
+                            command: name,
+                            status: "internal-error",
+                            error: {
+                                code: "E_INTERNAL",
+                                name: err instanceof Error ? err.name : "Error",
+                                message: err instanceof Error ? err.message : String(err)
+                            }
                         })
                     }
                 ],