@agent-native/core 0.31.2 → 0.32.1

package/dist/server/core-routes-plugin.js

@@ -1,4 +1,4 @@
-import { getH3App, awaitBootstrap, markDefaultPluginProvided, } from "./framework-request-handler.js";
+import { getH3App, awaitBootstrap, markDefaultPluginProvided, trackPluginInit, } from "./framework-request-handler.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
 import { defineEventHandler, setResponseStatus, setResponseHeader, getMethod, getHeader, getCookie, setCookie, deleteCookie, getRequestURL, } from "h3";
 import path from "node:path";
@@ -47,6 +47,7 @@ import { isEnvVarWriteAllowed } from "./env-var-writes.js";
 import { llmConnectionTrackingProperties } from "../shared/llm-connection.js";
 import { mountBrowserSessionRoutes } from "../browser-sessions/routes.js";
 import { mountDbAdminRoutes } from "../db-admin/routes.js";
+import { DEFAULT_SSR_CACHE_CONTROL, EMPTY_SPECULATION_RULES, } from "../shared/cache-control.js";
 /**
  * The base path prefix for all framework-level routes.
  * All agent-native core routes live under this namespace to avoid
@@ -251,292 +252,343 @@ export function createCoreRoutesPlugin(options = {}) {
         markDefaultPluginProvided(nitroApp, "core-routes");
         // No-op when called from inside the bootstrap (auto-mount path).
         // Otherwise wait so other default plugins finish mounting first.
-        await awaitBootstrap(nitroApp);
-        // Restore env vars from the settings table. On serverless, .env
-        // writes don't persist across invocations — the DB is the durable
-        // store. Only set keys that are currently empty so explicit env
-        // vars (Netlify dashboard, process-level) always win.
-        //
-        // GATED: only rehydrate into `process.env` on local-dev SQLite (or
-        // with the explicit single-tenant opt-in). On a shared-DB hosted
-        // multi-tenant deploy the `persisted-env-vars` row is deployment-wide
-        // global state — pushing user-supplied values into `process.env` from
-        // it would let any one tenant's writes (or a stale dev seed) leak
-        // into every other tenant's process. The opt-out scrub of legacy
-        // BUILDER_* values still runs unconditionally so existing rows on
-        // multi-tenant deploys self-heal, but new env-var writes never land
-        // in `process.env` outside the allowed contexts.
+        let resolveInit = () => { };
+        let rejectInit = () => { };
+        const initPromise = new Promise((resolve, reject) => {
+            resolveInit = resolve;
+            rejectInit = reject;
+        });
+        trackPluginInit(nitroApp, initPromise, {
+            paths: [FRAMEWORK_ROUTE_PREFIX, "/.well-known"],
+        });
         try {
-            const persisted = (await getSetting("persisted-env-vars"));
-            if (persisted) {
-                const builderKeys = new Set(BUILDER_ENV_KEYS);
-                const writesAllowed = isEnvVarWriteAllowed();
-                let scrubbed = 0;
-                for (const [k, v] of Object.entries(persisted)) {
-                    if (builderKeys.has(k)) {
-                        scrubbed++;
-                        continue;
-                    }
-                    if (writesAllowed && typeof v === "string" && !process.env[k]) {
-                        process.env[k] = v;
-                    }
-                }
-                if (scrubbed > 0) {
-                    try {
-                        const cleaned = {};
-                        for (const [k, v] of Object.entries(persisted)) {
-                            if (!builderKeys.has(k))
-                                cleaned[k] = v;
+            await awaitBootstrap(nitroApp);
+            // Restore env vars from the settings table. On serverless, .env
+            // writes don't persist across invocations — the DB is the durable
+            // store. Only set keys that are currently empty so explicit env
+            // vars (Netlify dashboard, process-level) always win.
+            //
+            // GATED: only rehydrate into `process.env` on local-dev SQLite (or
+            // with the explicit single-tenant opt-in). On a shared-DB hosted
+            // multi-tenant deploy the `persisted-env-vars` row is deployment-wide
+            // global state — pushing user-supplied values into `process.env` from
+            // it would let any one tenant's writes (or a stale dev seed) leak
+            // into every other tenant's process. The opt-out scrub of legacy
+            // BUILDER_* values still runs unconditionally so existing rows on
+            // multi-tenant deploys self-heal, but new env-var writes never land
+            // in `process.env` outside the allowed contexts.
+            try {
+                const persisted = (await getSetting("persisted-env-vars"));
+                if (persisted) {
+                    const builderKeys = new Set(BUILDER_ENV_KEYS);
+                    const writesAllowed = isEnvVarWriteAllowed();
+                    let scrubbed = 0;
+                    for (const [k, v] of Object.entries(persisted)) {
+                        if (builderKeys.has(k)) {
+                            scrubbed++;
+                            continue;
+                        }
+                        if (writesAllowed && typeof v === "string" && !process.env[k]) {
+                            process.env[k] = v;
                         }
-                        await putSetting("persisted-env-vars", cleaned);
-                        console.warn(`[core] Removed ${scrubbed} legacy BUILDER_* key(s) from persisted-env-vars (cross-tenant leak fix).`);
                     }
-                    catch {
-                        // Couldn't rewrite the row — the skip-on-rehydrate above
-                        // is the load-bearing protection. We'll try again next boot.
+                    if (scrubbed > 0) {
+                        try {
+                            const cleaned = {};
+                            for (const [k, v] of Object.entries(persisted)) {
+                                if (!builderKeys.has(k))
+                                    cleaned[k] = v;
+                            }
+                            await putSetting("persisted-env-vars", cleaned);
+                            console.warn(`[core] Removed ${scrubbed} legacy BUILDER_* key(s) from persisted-env-vars (cross-tenant leak fix).`);
+                        }
+                        catch {
+                            // Couldn't rewrite the row — the skip-on-rehydrate above
+                            // is the load-bearing protection. We'll try again next boot.
+                        }
                     }
                 }
             }
-        }
-        catch {
-            // DB not ready yet — skip
-        }
-        // Honor Builder disconnect. Nitro's dev env-runner preserves
-        // `process.env` across `.env` file reloads inside the same worker, so
-        // deleting BUILDER_PRIVATE_KEY in the disconnect handler can bleed
-        // back through an env-runner restart. We persist a
-        // `builder-disconnected` flag in SQL and scrub BUILDER_* on every
-        // plugin init while the flag is set. The flag is cleared by the
-        // Builder cli-auth callback when the user re-connects.
-        try {
-            const disconnected = (await getSetting("builder-disconnected"));
-            if (disconnected) {
-                for (const key of BUILDER_ENV_KEYS) {
-                    delete process.env[key];
-                }
-            }
-        }
-        catch {
-            // DB not ready — skip; the disconnect flag will be enforced on the
-            // next plugin boot once the settings table is reachable.
-        }
-        // Register framework-level secrets (OPENAI_API_KEY for composer voice
-        // transcription, etc.). Each registration is guarded so templates that
-        // already registered the same key win.
-        registerFrameworkSecrets();
-        registerBuiltinProviders();
-        registerBuiltinNotificationChannels();
-        try {
-            const { createObservabilityHandler } = await import("../observability/routes.js");
-            const { ensureObservabilityTables } = await import("../observability/store.js");
-            ensureObservabilityTables().catch(() => { });
-            getH3App(nitroApp).use(`${FRAMEWORK_ROUTE_PREFIX}/observability`, createObservabilityHandler());
-        }
-        catch {
-            // Observability module not available — skip
-        }
-        const P = FRAMEWORK_ROUTE_PREFIX;
-        // Security response headers — emitted on every framework response.
-        // Mounted before route handlers so 4xx/5xx error pages also carry the
-        // headers. Routes that need to relax a specific header (e.g. the tools
-        // /render route allowing same-origin framing) override via setResponseHeader.
-        const { createSecurityHeadersMiddleware } = await import("./security-headers.js");
-        getH3App(nitroApp).use(createSecurityHeadersMiddleware());
-        // CORS for framework routes. Desktop tray apps (Tauri/Electron) run on
-        // their own dev origin (e.g. localhost:1420) and make credentialed
-        // requests against the template's server at a different port. We echo
-        // the exact origin + Allow-Credentials so same-site localhost ports
-        // can cross-send cookies.
-        const allowlist = readCorsAllowedOrigins();
-        getH3App(nitroApp).use(defineEventHandler((event) => {
-            const pathname = stripAppBasePath(event.url?.pathname ??
-                String(event.node?.req?.url ?? event.path ?? "/").split("?")[0]);
-            if (!pathname.startsWith(P) && !pathname.startsWith("/api/"))
-                return;
-            const readRequestHeader = (name) => {
-                const lower = name.toLowerCase();
-                const raw = event.node?.req?.headers?.[lower] ??
-                    event.node?.req?.headers?.[name];
-                if (Array.isArray(raw))
-                    return raw[0];
-                if (typeof raw === "string")
-                    return raw;
-                return getHeader(event, name) ?? undefined;
-            };
-            const origin = readRequestHeader("origin");
-            const method = getMethod(event);
-            const requestedHeaders = readRequestHeader("access-control-request-headers");
-            const requestedHeaderNames = String(requestedHeaders ?? "")
-                .toLowerCase()
-                .split(",")
-                .map((header) => header.trim());
-            const mcpEmbedCorsRequest = isMcpEmbedCorsOrigin(origin) &&
-                (requestedHeaderNames.includes(EMBED_TARGET_HEADER.toLowerCase()) ||
-                    requestedHeaderNames.includes(EMBED_TRANSPLANT_HEADER) ||
-                    Boolean(readRequestHeader(EMBED_TARGET_HEADER)) ||
-                    Boolean(readRequestHeader(EMBED_TRANSPLANT_HEADER)) ||
-                    Boolean(readRequestHeader("authorization")));
-            // Decide whether this origin is allowed. We never fall back to the
-            // first allowlist entry — that previously echoed `Access-Control-
-            // Allow-Origin: <unrelated-allowed-origin>` for disallowed callers,
-            // which is permissive enough that some clients followed through.
-            const allowedOrigin = mcpEmbedCorsRequest
-                ? origin
-                : getAllowedCorsOrigin(origin, {
-                    allowedOrigins: allowlist,
-                    allowAnyOriginWhenNoAllowlist: false,
-                    allowLocalhostWhenNoAllowlist: true,
-                });
-            // Reject preflights from disallowed cross-origin callers BEFORE
-            // returning 204. Previously the OPTIONS short-circuit returned 204
-            // with no ACAO header, which the browser then treats as a CORS
-            // failure — but also short-circuited any further checks. Now we
-            // explicitly 403 disallowed cross-origin preflights.
-            if (method === "OPTIONS") {
-                if (origin && !allowedOrigin) {
-                    setResponseStatus(event, 403);
-                    return "";
-                }
-                if (allowedOrigin) {
-                    setResponseHeader(event, "Access-Control-Allow-Origin", allowedOrigin);
-                    setResponseHeader(event, "Vary", "Origin");
-                    if (shouldAllowMcpEmbedCredentials(allowedOrigin)) {
-                        setResponseHeader(event, "Access-Control-Allow-Credentials", "true");
+            catch {
+                // DB not ready yet — skip
+            }
+            // Honor Builder disconnect. Nitro's dev env-runner preserves
+            // `process.env` across `.env` file reloads inside the same worker, so
+            // deleting BUILDER_PRIVATE_KEY in the disconnect handler can bleed
+            // back through an env-runner restart. We persist a
+            // `builder-disconnected` flag in SQL and scrub BUILDER_* on every
+            // plugin init while the flag is set. The flag is cleared by the
+            // Builder cli-auth callback when the user re-connects.
+            try {
+                const disconnected = (await getSetting("builder-disconnected"));
+                if (disconnected) {
+                    for (const key of BUILDER_ENV_KEYS) {
+                        delete process.env[key];
                     }
-                    setResponseHeader(event, "Access-Control-Allow-Methods", "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS");
-                    setResponseHeader(event, "Access-Control-Allow-Headers", MCP_EMBED_CORS_ALLOW_HEADERS);
                 }
-                setResponseStatus(event, 204);
-                return "";
-            }
-            // Non-preflight requests: only set CORS response headers when we
-            // have an allowed origin. Same-origin / no-origin requests fall
-            // through without explicit CORS headers (browser treats them as
-            // same-origin by default).
-            if (!allowedOrigin)
-                return;
-            setResponseHeader(event, "Access-Control-Allow-Origin", allowedOrigin);
-            setResponseHeader(event, "Vary", "Origin");
-            if (shouldAllowMcpEmbedCredentials(allowedOrigin)) {
-                setResponseHeader(event, "Access-Control-Allow-Credentials", "true");
             }
-            setResponseHeader(event, "Access-Control-Allow-Methods", "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS");
-            setResponseHeader(event, "Access-Control-Allow-Headers", MCP_EMBED_CORS_ALLOW_HEADERS);
-        }));
-        // Defense-in-depth CSRF check for state-changing /_agent-native/* routes.
-        // Mounted AFTER the CORS layer so disallowed-origin OPTIONS preflights
-        // 403 first (rather than being rejected on a stale cookie heuristic).
-        // See `csrf.ts` for the threat model and allowlist.
-        const { createCsrfMiddleware } = await import("./csrf.js");
-        getH3App(nitroApp).use(createCsrfMiddleware(P));
-        // Demo-mode status — read by the client fetch interceptor and the
-        // Demo mode settings toggle. `forced` reflects the DEMO_MODE env (a
-        // hosted demo deployment); `enabled` ORs that with the per-user
-        // application_state toggle. No request-context dependency: the env case
-        // needs nothing, and the per-user case resolves the session straight
-        // off the request cookie via getSession(event).
-        getH3App(nitroApp).use(`${P}/demo/status`, defineEventHandler(async (event) => {
-            const { isDemoModeForced } = await import("../demo/config.js");
-            const forced = isDemoModeForced();
-            if (forced)
-                return { enabled: true, forced: true };
+            catch {
+                // DB not ready — skip; the disconnect flag will be enforced on the
+                // next plugin boot once the settings table is reachable.
+            }
+            // Register framework-level secrets (OPENAI_API_KEY for composer voice
+            // transcription, etc.). Each registration is guarded so templates that
+            // already registered the same key win.
+            registerFrameworkSecrets();
+            registerBuiltinProviders();
+            registerBuiltinNotificationChannels();
             try {
-                const session = await getSession(event);
-                const email = session?.email;
-                if (!email)
-                    return { enabled: false, forced: false };
-                const { appStateGet } = await import("../application-state/store.js");
-                const state = await appStateGet(email, "demo-mode");
-                return {
-                    enabled: state?.enabled === true,
-                    forced: false,
-                };
+                const { createObservabilityHandler } = await import("../observability/routes.js");
+                const { ensureObservabilityTables } = await import("../observability/store.js");
+                ensureObservabilityTables().catch(() => { });
+                getH3App(nitroApp).use(`${FRAMEWORK_ROUTE_PREFIX}/observability`, createObservabilityHandler());
             }
             catch {
-                return { enabled: false, forced: false };
-            }
-        }));
-        // Polling
-        getH3App(nitroApp).use(`${P}/poll`, createPollHandler());
-        // SSE
-        if (!options.disableSSE) {
-            const sseRoute = options.sseRoute ?? `${P}/events`;
-            getH3App(nitroApp).use(sseRoute, createPollEventsHandler());
-        }
-        // Ping
-        if (!options.disablePing) {
-            getH3App(nitroApp).use(`${P}/ping`, defineEventHandler(() => ({
-                message: process.env.PING_MESSAGE ?? "pong",
-            })));
-        }
-        mountBrowserSessionRoutes(nitroApp, { routePrefix: P });
-        // Dev-mode DB admin (Supabase-Studio-like). Mounted unconditionally; every
-        // handler self-gates on dev + localhost (the authoritative gate lives in
-        // db-admin/routes.ts), so on a deployed / production app it always 403s.
-        mountDbAdminRoutes(nitroApp, { routePrefix: P });
-        const resolveBuilderOwnerContext = async (event, mode) => resolveBuilderOwnerContextForRequest(event, { anonymousOwner: options.anonymousOwner }, mode);
-        getH3App(nitroApp).use(`${P}/builder/status`, defineEventHandler(async (event) => {
-            const envStatus = getBuilderBrowserStatusForEvent(event);
-            const ownerContext = await resolveBuilderOwnerContext(event);
-            const userEmail = ownerContext.email;
-            const withConnectToken = (status) => {
-                if (!userEmail)
-                    return status;
-                const previewOrigin = getBuilderBrowserOriginForEvent(event);
-                const callbackOrigin = getBuilderCliAuthCallbackOriginForEvent(event);
-                const statusWithConnectToken = {
-                    ...status,
-                    connectUrl: appendBuilderConnectToken(status.connectUrl, userEmail),
-                };
-                // Direct cli-auth only works when the callback lands on the same
-                // deployment that minted the signed state. Builder/Fusion previews
-                // often need a gateway callback origin; in that case use the
-                // /builder/connect trampoline so it can write the pending-connect
-                // row that the gateway callback validates against.
-                if (previewOrigin.replace(/\/+$/, "") !==
-                    callbackOrigin.replace(/\/+$/, "")) {
-                    return statusWithConnectToken;
-                }
-                const cliAuthUrl = buildBuilderCliAuthUrl(callbackOrigin, signBuilderCallbackState(userEmail), { previewOrigin });
-                return {
-                    ...statusWithConnectToken,
-                    cliAuthUrl,
+                // Observability module not available — skip
+            }
+            const P = FRAMEWORK_ROUTE_PREFIX;
+            // Security response headers — emitted on every framework response.
+            // Mounted before route handlers so 4xx/5xx error pages also carry the
+            // headers. Routes that need to relax a specific header (e.g. the tools
+            // /render route allowing same-origin framing) override via setResponseHeader.
+            const { createSecurityHeadersMiddleware } = await import("./security-headers.js");
+            getH3App(nitroApp).use(createSecurityHeadersMiddleware());
+            // CORS for framework routes. Desktop tray apps (Tauri/Electron) run on
+            // their own dev origin (e.g. localhost:1420) and make credentialed
+            // requests against the template's server at a different port. We echo
+            // the exact origin + Allow-Credentials so same-site localhost ports
+            // can cross-send cookies.
+            const allowlist = readCorsAllowedOrigins();
+            getH3App(nitroApp).use(defineEventHandler((event) => {
+                const pathname = stripAppBasePath(event.url?.pathname ??
+                    String(event.node?.req?.url ?? event.path ?? "/").split("?")[0]);
+                if (!pathname.startsWith(P) && !pathname.startsWith("/api/"))
+                    return;
+                const readRequestHeader = (name) => {
+                    const lower = name.toLowerCase();
+                    const raw = event.node?.req?.headers?.[lower] ??
+                        event.node?.req?.headers?.[name];
+                    if (Array.isArray(raw))
+                        return raw[0];
+                    if (typeof raw === "string")
+                        return raw;
+                    return getHeader(event, name) ?? undefined;
                 };
-            };
-            // Pass the user's active orgId so status reads can fall back to
-            // org-scoped credentials and branch project IDs. Without it, an
-            // admin's org-scope OAuth result is invisible to every other org
-            // member's status poller and the UI would show "not connected" forever
-            // even though the chat actually resolves the org-shared credential.
-            let orgId = null;
-            if (!ownerContext.anonymous) {
+                const origin = readRequestHeader("origin");
+                const method = getMethod(event);
+                const requestedHeaders = readRequestHeader("access-control-request-headers");
+                const requestedHeaderNames = String(requestedHeaders ?? "")
+                    .toLowerCase()
+                    .split(",")
+                    .map((header) => header.trim());
+                const mcpEmbedCorsRequest = isMcpEmbedCorsOrigin(origin) &&
+                    (requestedHeaderNames.includes(EMBED_TARGET_HEADER.toLowerCase()) ||
+                        requestedHeaderNames.includes(EMBED_TRANSPLANT_HEADER) ||
+                        Boolean(readRequestHeader(EMBED_TARGET_HEADER)) ||
+                        Boolean(readRequestHeader(EMBED_TRANSPLANT_HEADER)) ||
+                        Boolean(readRequestHeader("authorization")));
+                // Decide whether this origin is allowed. We never fall back to the
+                // first allowlist entry — that previously echoed `Access-Control-
+                // Allow-Origin: <unrelated-allowed-origin>` for disallowed callers,
+                // which is permissive enough that some clients followed through.
+                const allowedOrigin = mcpEmbedCorsRequest
+                    ? origin
+                    : getAllowedCorsOrigin(origin, {
+                        allowedOrigins: allowlist,
+                        allowAnyOriginWhenNoAllowlist: false,
+                        allowLocalhostWhenNoAllowlist: true,
+                    });
+                // Reject preflights from disallowed cross-origin callers BEFORE
+                // returning 204. Previously the OPTIONS short-circuit returned 204
+                // with no ACAO header, which the browser then treats as a CORS
+                // failure — but also short-circuited any further checks. Now we
+                // explicitly 403 disallowed cross-origin preflights.
+                if (method === "OPTIONS") {
+                    if (origin && !allowedOrigin) {
+                        setResponseStatus(event, 403);
+                        return "";
+                    }
+                    if (allowedOrigin) {
+                        setResponseHeader(event, "Access-Control-Allow-Origin", allowedOrigin);
+                        setResponseHeader(event, "Vary", "Origin");
+                        if (shouldAllowMcpEmbedCredentials(allowedOrigin)) {
+                            setResponseHeader(event, "Access-Control-Allow-Credentials", "true");
+                        }
+                        setResponseHeader(event, "Access-Control-Allow-Methods", "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS");
+                        setResponseHeader(event, "Access-Control-Allow-Headers", MCP_EMBED_CORS_ALLOW_HEADERS);
+                    }
+                    setResponseStatus(event, 204);
+                    return "";
+                }
+                // Non-preflight requests: only set CORS response headers when we
+                // have an allowed origin. Same-origin / no-origin requests fall
+                // through without explicit CORS headers (browser treats them as
+                // same-origin by default).
+                if (!allowedOrigin)
+                    return;
+                setResponseHeader(event, "Access-Control-Allow-Origin", allowedOrigin);
+                setResponseHeader(event, "Vary", "Origin");
+                if (shouldAllowMcpEmbedCredentials(allowedOrigin)) {
+                    setResponseHeader(event, "Access-Control-Allow-Credentials", "true");
+                }
+                setResponseHeader(event, "Access-Control-Allow-Methods", "GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS");
+                setResponseHeader(event, "Access-Control-Allow-Headers", MCP_EMBED_CORS_ALLOW_HEADERS);
+            }));
+            // Defense-in-depth CSRF check for state-changing /_agent-native/* routes.
+            // Mounted AFTER the CORS layer so disallowed-origin OPTIONS preflights
+            // 403 first (rather than being rejected on a stale cookie heuristic).
+            // See `csrf.ts` for the threat model and allowlist.
+            const { createCsrfMiddleware } = await import("./csrf.js");
+            getH3App(nitroApp).use(createCsrfMiddleware(P));
+            // Demo-mode status — read by the client fetch interceptor and the
+            // Demo mode settings toggle. `forced` reflects the DEMO_MODE env (a
+            // hosted demo deployment); `enabled` ORs that with the per-user
+            // application_state toggle. No request-context dependency: the env case
+            // needs nothing, and the per-user case resolves the session straight
+            // off the request cookie via getSession(event).
+            getH3App(nitroApp).use(`${P}/demo/status`, defineEventHandler(async (event) => {
+                const { isDemoModeForced } = await import("../demo/config.js");
+                const forced = isDemoModeForced();
+                if (forced)
+                    return { enabled: true, forced: true };
                 try {
-                    const { getOrgContext } = await import("../org/context.js");
-                    const orgCtx = await getOrgContext(event);
-                    orgId = orgCtx.orgId ?? null;
+                    const session = await getSession(event);
+                    const email = session?.email;
+                    if (!email)
+                        return { enabled: false, forced: false };
+                    const { appStateGet } = await import("../application-state/store.js");
+                    const state = await appStateGet(email, "demo-mode");
+                    return {
+                        enabled: state?.enabled === true,
+                        forced: false,
+                    };
                 }
                 catch {
-                    /* org module not present in this template — keep userEmail-only */
+                    return { enabled: false, forced: false };
                 }
-            }
-            return runWithRequestContext({ userEmail, orgId }, async () => {
-                const projectId = await resolveBuilderBranchProjectId();
-                const requestStatus = {
-                    ...envStatus,
-                    builderEnabled: !!projectId,
-                    branchProjectIdConfigured: !!projectId,
-                    branchProjectId: projectId || undefined,
+            }));
+            // Polling
+            getH3App(nitroApp).use(`${P}/poll`, createPollHandler());
+            // SSE
+            if (!options.disableSSE) {
+                const sseRoute = options.sseRoute ?? `${P}/events`;
+                getH3App(nitroApp).use(sseRoute, createPollEventsHandler());
+            }
+            // Ping
+            if (!options.disablePing) {
+                getH3App(nitroApp).use(`${P}/ping`, defineEventHandler(() => ({
+                    message: process.env.PING_MESSAGE ?? "pong",
+                })));
+            }
+            getH3App(nitroApp).use(`${P}/speculation-rules.json`, defineEventHandler((event) => {
+                // `createH3SSRHandler` points the Speculation-Rules response header
+                // here to prevent Cloudflare Speed Brain from injecting its own
+                // edge prefetch rules. Keep this route public and side-effect free:
+                // browsers may request it while parsing any SSR HTML document.
+                setResponseHeader(event, "content-type", "application/speculationrules+json; charset=utf-8");
+                setResponseHeader(event, "cache-control", DEFAULT_SSR_CACHE_CONTROL);
+                return EMPTY_SPECULATION_RULES;
+            }));
+            mountBrowserSessionRoutes(nitroApp, { routePrefix: P });
+            // Dev-mode DB admin (Supabase-Studio-like). Mounted unconditionally; every
+            // handler self-gates on dev + localhost (the authoritative gate lives in
+            // db-admin/routes.ts), so on a deployed / production app it always 403s.
+            mountDbAdminRoutes(nitroApp, { routePrefix: P });
+            const resolveBuilderOwnerContext = async (event, mode) => resolveBuilderOwnerContextForRequest(event, { anonymousOwner: options.anonymousOwner }, mode);
+            getH3App(nitroApp).use(`${P}/builder/status`, defineEventHandler(async (event) => {
+                const envStatus = getBuilderBrowserStatusForEvent(event);
+                const ownerContext = await resolveBuilderOwnerContext(event);
+                const userEmail = ownerContext.email;
+                const withConnectToken = (status) => {
+                    if (!userEmail)
+                        return status;
+                    const previewOrigin = getBuilderBrowserOriginForEvent(event);
+                    const callbackOrigin = getBuilderCliAuthCallbackOriginForEvent(event);
+                    const statusWithConnectToken = {
+                        ...status,
+                        connectUrl: appendBuilderConnectToken(status.connectUrl, userEmail),
+                    };
+                    // Direct cli-auth only works when the callback lands on the same
+                    // deployment that minted the signed state. Builder/Fusion previews
+                    // often need a gateway callback origin; in that case use the
+                    // /builder/connect trampoline so it can write the pending-connect
+                    // row that the gateway callback validates against.
+                    if (previewOrigin.replace(/\/+$/, "") !==
+                        callbackOrigin.replace(/\/+$/, "")) {
+                        return statusWithConnectToken;
+                    }
+                    const cliAuthUrl = buildBuilderCliAuthUrl(callbackOrigin, signBuilderCallbackState(userEmail), { previewOrigin });
+                    return {
+                        ...statusWithConnectToken,
+                        cliAuthUrl,
+                    };
                 };
-                // Surface a recent OAuth callback failure before reporting a
-                // deployment fallback as "connected"; otherwise a failed personal
-                // connect attempt on a deploy that also has BUILDER_PRIVATE_KEY set
-                // looks successful even though the user's credentials were not saved.
-                try {
-                    if (userEmail) {
-                        const errKey = `builder-connect-error:${userEmail}`;
-                        const errRow = await getSetting(errKey);
-                        if (errRow && typeof errRow.message === "string") {
-                            await deleteSetting(errKey).catch(() => { });
+                // Pass the user's active orgId so status reads can fall back to
+                // org-scoped credentials and branch project IDs. Without it, an
+                // admin's org-scope OAuth result is invisible to every other org
+                // member's status poller and the UI would show "not connected" forever
+                // even though the chat actually resolves the org-shared credential.
+                let orgId = null;
+                if (!ownerContext.anonymous) {
+                    try {
+                        const { getOrgContext } = await import("../org/context.js");
+                        const orgCtx = await getOrgContext(event);
+                        orgId = orgCtx.orgId ?? null;
+                    }
+                    catch {
+                        /* org module not present in this template — keep userEmail-only */
+                    }
+                }
+                return runWithRequestContext({ userEmail, orgId }, async () => {
+                    const projectId = await resolveBuilderBranchProjectId();
+                    const requestStatus = {
+                        ...envStatus,
+                        builderEnabled: !!projectId,
+                        branchProjectIdConfigured: !!projectId,
+                        branchProjectId: projectId || undefined,
+                    };
+                    // Surface a recent OAuth callback failure before reporting a
+                    // deployment fallback as "connected"; otherwise a failed personal
+                    // connect attempt on a deploy that also has BUILDER_PRIVATE_KEY set
+                    // looks successful even though the user's credentials were not saved.
+                    try {
+                        if (userEmail) {
+                            const errKey = `builder-connect-error:${userEmail}`;
+                            const errRow = await getSetting(errKey);
+                            if (errRow && typeof errRow.message === "string") {
+                                await deleteSetting(errKey).catch(() => { });
+                                return withConnectToken({
+                                    ...requestStatus,
+                                    configured: false,
+                                    privateKeyConfigured: false,
+                                    publicKeyConfigured: false,
+                                    userId: undefined,
+                                    orgName: undefined,
+                                    orgKind: undefined,
+                                    connectError: {
+                                        message: errRow.message,
+                                        at: typeof errRow.at === "number"
+                                            ? errRow.at
+                                            : Date.now(),
+                                    },
+                                });
+                            }
+                        }
+                    }
+                    catch {
+                        // settings store unavailable — fall through
+                    }
+                    // Read request-scoped Builder credentials first; deploy env is only
+                    // the fallback. This keeps a root/local BUILDER_PRIVATE_KEY from
+                    // blocking a user from connecting their own Builder account.
+                    try {
+                        const { resolveBuilderCredentials, resolveBuilderCredentialSource, getBuilderCredentialAuthFailure, } = await import("./credential-provider.js");
+                        const [creds, credentialSource] = await Promise.all([
+                            resolveBuilderCredentials(),
+                            resolveBuilderCredentialSource(),
+                        ]);
+                        const authFailure = await getBuilderCredentialAuthFailure(creds);
+                        if (authFailure) {
                             return withConnectToken({
                                 ...requestStatus,
                                 configured: false,
@@ -545,1551 +597,1533 @@ export function createCoreRoutesPlugin(options = {}) {
                                 userId: undefined,
                                 orgName: undefined,
                                 orgKind: undefined,
-                                connectError: {
-                                    message: errRow.message,
-                                    at: typeof errRow.at === "number"
-                                        ? errRow.at
-                                        : Date.now(),
+                                credentialSource: credentialSource ?? undefined,
+                                // Surface durable credential rejection separately from
+                                // one-shot cli-auth callback failures. The reconnect UI keeps
+                                // polling through authError while the user chooses a new
+                                // Builder space; connectError means the active callback itself
+                                // failed and should stop the flow.
+                                authError: {
+                                    message: authFailure.message,
+                                    at: authFailure.at,
                                 },
                             });
                         }
+                        if (creds.privateKey && creds.publicKey) {
+                            return withConnectToken({
+                                ...requestStatus,
+                                configured: true,
+                                privateKeyConfigured: true,
+                                publicKeyConfigured: !!creds.publicKey,
+                                userId: creds.userId || envStatus.userId,
+                                orgName: creds.orgName || envStatus.orgName,
+                                orgKind: creds.orgKind || envStatus.orgKind,
+                                credentialSource: credentialSource ?? undefined,
+                            });
+                        }
                     }
-                }
-                catch {
-                    // settings store unavailable — fall through
-                }
-                // Read request-scoped Builder credentials first; deploy env is only
-                // the fallback. This keeps a root/local BUILDER_PRIVATE_KEY from
-                // blocking a user from connecting their own Builder account.
-                try {
-                    const { resolveBuilderCredentials, resolveBuilderCredentialSource, getBuilderCredentialAuthFailure, } = await import("./credential-provider.js");
-                    const [creds, credentialSource] = await Promise.all([
-                        resolveBuilderCredentials(),
-                        resolveBuilderCredentialSource(),
-                    ]);
-                    const authFailure = await getBuilderCredentialAuthFailure(creds);
-                    if (authFailure) {
-                        return withConnectToken({
-                            ...requestStatus,
-                            configured: false,
-                            privateKeyConfigured: false,
-                            publicKeyConfigured: false,
-                            userId: undefined,
-                            orgName: undefined,
-                            orgKind: undefined,
-                            credentialSource: credentialSource ?? undefined,
-                            // Surface durable credential rejection separately from
-                            // one-shot cli-auth callback failures. The reconnect UI keeps
-                            // polling through authError while the user chooses a new
-                            // Builder space; connectError means the active callback itself
-                            // failed and should stop the flow.
-                            authError: {
-                                message: authFailure.message,
-                                at: authFailure.at,
-                            },
-                        });
+                    catch {
+                        // Secrets table not ready — fall through to env status
                     }
-                    if (creds.privateKey && creds.publicKey) {
-                        return withConnectToken({
-                            ...requestStatus,
-                            configured: true,
-                            privateKeyConfigured: true,
-                            publicKeyConfigured: !!creds.publicKey,
-                            userId: creds.userId || envStatus.userId,
-                            orgName: creds.orgName || envStatus.orgName,
-                            orgKind: creds.orgKind || envStatus.orgKind,
-                            credentialSource: credentialSource ?? undefined,
-                        });
+                    // Honor legacy disconnect flag for existing deployments.
+                    try {
+                        const disconnected = await getSetting("builder-disconnected");
+                        if (disconnected) {
+                            return withConnectToken({
+                                ...requestStatus,
+                                configured: false,
+                                privateKeyConfigured: false,
+                                publicKeyConfigured: false,
+                                userId: undefined,
+                                orgName: undefined,
+                                orgKind: undefined,
+                            });
+                        }
+                    }
+                    catch {
+                        // DB not reachable
+                    }
+                    // No env, no per-user creds → not configured. Both authenticated
+                    // and unauthenticated callers see "not connected" so they can
+                    // run through the OAuth flow.
+                    return withConnectToken({
+                        ...requestStatus,
+                        configured: false,
+                        privateKeyConfigured: false,
+                        publicKeyConfigured: false,
+                        userId: undefined,
+                        orgName: undefined,
+                        orgKind: undefined,
+                    });
+                });
+            }));
+            // How long a pending-connect row is valid. Must be long enough for
+            // the user to complete the Builder CLI-auth flow, but short enough
+            // that a stale row from an abandoned attempt doesn't accept a new
+            // callback minutes later.
+            const BUILDER_CONNECT_PENDING_TTL_MS = 10 * 60 * 1000; // 10 min
+            // Decide whether a /builder/connect navigation originated from this
+            // app's own UI (allowed) or from a foreign origin (cross-site CSRF
+            // attempt — rejected). Sec-Fetch-Site is the modern signal:
+            //   - "same-origin": user clicked Connect from our own pages — allow
+            //   - "none": typed in URL bar / bookmark / browser extension — allow
+            //   - "same-site" / "cross-site" / missing-but-with-foreign-Origin
+            //     all map to reject.
+            // For older browsers without Sec-Fetch-* we fall back to Origin and
+            // then Referer, comparing against the request's resolved origin.
+            function isSameOriginConnect(event) {
+                const fetchSite = getHeader(event, "sec-fetch-site");
+                if (fetchSite === "same-origin" || fetchSite === "none")
+                    return true;
+                if (fetchSite)
+                    return false; // browser told us it's cross-site/same-site
+                const expected = getBuilderBrowserOriginForEvent(event).replace(/\/+$/, "");
+                const origin = getHeader(event, "origin");
+                if (origin)
+                    return origin.replace(/\/+$/, "") === expected;
+                const referer = getHeader(event, "referer");
+                if (referer) {
+                    try {
+                        return new URL(referer).origin === expected;
+                    }
+                    catch {
+                        return false;
                     }
                 }
-                catch {
-                    // Secrets table not ready — fall through to env status
+                // No Sec-Fetch-Site, no Origin, no Referer — pre-2020 browser
+                // making a top-level navigation. Allow; cookies are still
+                // session-bound so the worst case degrades to the prior behavior.
+                return true;
+            }
+            // Lightweight 302 to the Builder CLI-auth URL. Lets clients do
+            // `window.open('/_agent-native/builder/connect', '_blank')` synchronously
+            // inside a click handler, avoiding the popup-blocker downgrade that
+            // happens when an await sits before window.open.
+            //
+            // CSRF protection here is layered because session cookies are
+            // SameSite=None;Secure (so the editor iframe can ride along) — that
+            // means a session cookie alone does NOT prevent cross-origin
+            // window.open from initiating a connect flow on the victim's behalf:
+            //   1. Signed connect token from /builder/status — proves the opener
+            //      could read same-origin JSON, which cross-site attackers cannot.
+            //      This covers local/embedded browsers that conservatively label a
+            //      legitimate popup navigation as same-site/cross-site.
+            //   2. Sec-Fetch-Site header fallback — modern browsers stamp every
+            //      request with the navigation context. We allow `same-origin` or
+            //      `none` (typed/bookmark/extension); cross-site / same-site without
+            //      a valid connect token are rejected.
+            //   3. Pending row keyed by session email + bound nonce — the callback
+            //      requires both a valid session and a one-time row that this
+            //      handler wrote during the same flow. Without the same-origin
+            //      gate or connect token above, an attacker could prime the row from
+            //      cross-site and then trick the victim into hitting a callback URL
+            //      with attacker-controlled p-key/api-key, hijacking the victim's
+            //      account.
+            getH3App(nitroApp).use(`${P}/builder/connect`, defineEventHandler(async (event) => {
+                const ownerContext = await resolveBuilderOwnerContext(event, "connect");
+                const ownerEmail = ownerContext.email;
+                if (!ownerEmail) {
+                    setResponseStatus(event, 401);
+                    return { error: "Authentication required" };
                 }
-                // Honor legacy disconnect flag for existing deployments.
+                const requestUrl = new URL(`${event.url?.pathname || "/"}${event.url?.search || ""}`, getBuilderBrowserOriginForEvent(event));
+                const connectToken = requestUrl.searchParams.get(BUILDER_CONNECT_PARAM);
+                const connectTokenOwner = verifyBuilderConnectTokenAndGetOwner(connectToken);
+                const connectTracking = getBuilderConnectTrackingParams(requestUrl.searchParams);
+                // The token must both be well-formed AND minted for the current
+                // session owner. Without the owner check, an attacker holding any
+                // valid signed token could trick a victim into hitting this route
+                // with that token to bypass the cross-origin gate.
+                const hasValidConnectToken = Boolean(connectTokenOwner) && connectTokenOwner === ownerEmail;
+                // Same-origin gate. Sec-Fetch-Site remains the fast path; the signed
+                // connect token is the compatibility path for legitimate embedded or
+                // local desktop popups stamped as same-site/cross-site by the browser.
+                if (!isSameOriginConnect(event) && !hasValidConnectToken) {
+                    const crossOriginMessage = connectToken
+                        ? "This Builder connect link is expired or belongs to a different deployment. Close this popup and click Connect account again."
+                        : "Builder connect opened without a fresh signed link. Close this popup and click Connect account again.";
+                    await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
+                        ...builderConnectTrackingProperties(connectTracking),
+                        reason: "cross_origin",
+                        stage: "connect",
+                        has_connect_token: Boolean(connectToken),
+                        has_valid_connect_token: false,
+                        connect_token_owner_matches_context: false,
+                        sec_fetch_site: getHeader(event, "sec-fetch-site") ?? null,
+                    });
+                    await putSetting(`builder-connect-error:${ownerEmail}`, {
+                        message: crossOriginMessage,
+                        at: Date.now(),
+                    }).catch(() => { });
+                    console.warn("[builder-connect] rejected cross-origin connect", {
+                        hasConnectToken: Boolean(connectToken),
+                        secFetchSite: getHeader(event, "sec-fetch-site") ?? null,
+                        origin: getHeader(event, "origin") ?? null,
+                        referer: getHeader(event, "referer") ?? null,
+                    });
+                    setResponseStatus(event, 403);
+                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
+                    return createBuilderBrowserCallbackErrorPage(crossOriginMessage, {
+                        title: "Couldn't start Builder connection",
+                        body: "The connect popup did not include a valid signed link for this app.",
+                        closeHint: "Close this popup, refresh the app, and try Connect account again.",
+                        parentOrigin: getBuilderBrowserOriginForEvent(event),
+                    });
+                }
+                // Clear any prior failure row from a previous attempt — otherwise
+                // useBuilderStatus polling sees the stale error and aborts the
+                // new attempt before it can complete.
                 try {
-                    const disconnected = await getSetting("builder-disconnected");
-                    if (disconnected) {
-                        return withConnectToken({
-                            ...requestStatus,
-                            configured: false,
-                            privateKeyConfigured: false,
-                            publicKeyConfigured: false,
-                            userId: undefined,
-                            orgName: undefined,
-                            orgKind: undefined,
-                        });
-                    }
+                    await deleteSetting(`builder-connect-error:${ownerEmail}`);
                 }
                 catch {
-                    // DB not reachable
-                }
-                // No env, no per-user creds → not configured. Both authenticated
-                // and unauthenticated callers see "not connected" so they can
-                // run through the OAuth flow.
-                return withConnectToken({
-                    ...requestStatus,
-                    configured: false,
-                    privateKeyConfigured: false,
-                    publicKeyConfigured: false,
-                    userId: undefined,
-                    orgName: undefined,
-                    orgKind: undefined,
-                });
-            });
-        }));
-        // How long a pending-connect row is valid. Must be long enough for
-        // the user to complete the Builder CLI-auth flow, but short enough
-        // that a stale row from an abandoned attempt doesn't accept a new
-        // callback minutes later.
-        const BUILDER_CONNECT_PENDING_TTL_MS = 10 * 60 * 1000; // 10 min
-        // Decide whether a /builder/connect navigation originated from this
-        // app's own UI (allowed) or from a foreign origin (cross-site CSRF
-        // attempt — rejected). Sec-Fetch-Site is the modern signal:
-        //   - "same-origin": user clicked Connect from our own pages — allow
-        //   - "none": typed in URL bar / bookmark / browser extension — allow
-        //   - "same-site" / "cross-site" / missing-but-with-foreign-Origin
-        //     all map to reject.
-        // For older browsers without Sec-Fetch-* we fall back to Origin and
-        // then Referer, comparing against the request's resolved origin.
-        function isSameOriginConnect(event) {
-            const fetchSite = getHeader(event, "sec-fetch-site");
-            if (fetchSite === "same-origin" || fetchSite === "none")
-                return true;
-            if (fetchSite)
-                return false; // browser told us it's cross-site/same-site
-            const expected = getBuilderBrowserOriginForEvent(event).replace(/\/+$/, "");
-            const origin = getHeader(event, "origin");
-            if (origin)
-                return origin.replace(/\/+$/, "") === expected;
-            const referer = getHeader(event, "referer");
-            if (referer) {
+                    // No prior error row — fine
+                }
+                // Store a short-lived pending row. If the DB is unavailable we
+                // surface a popup-renderable error page that signals the parent
+                // via BroadcastChannel, rather than letting the popup show raw
+                // JSON and the parent poll for 5 minutes.
                 try {
-                    return new URL(referer).origin === expected;
+                    await putSetting(`builder-pending-connect:${ownerEmail}`, {
+                        expiresAt: Date.now() + BUILDER_CONNECT_PENDING_TTL_MS,
+                        tracking: connectTracking,
+                    });
                 }
-                catch {
-                    return false;
+                catch (err) {
+                    await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
+                        ...builderConnectTrackingProperties(connectTracking),
+                        reason: "pending_storage_unavailable",
+                        stage: "connect",
+                    });
+                    const msg = "Could not initiate Builder connect — storage unavailable. Try again.";
+                    console.error("[builder] Could not store pending-connect state:", err?.message ?? err);
+                    // Best-effort: also write the error row so the parent's
+                    // /builder/status poll picks it up if BroadcastChannel doesn't.
+                    await putSetting(`builder-connect-error:${ownerEmail}`, {
+                        message: msg,
+                        at: Date.now(),
+                    }).catch(() => { });
+                    setResponseStatus(event, 503);
+                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
+                    return createBuilderBrowserCallbackErrorPage(msg, {
+                        parentOrigin: getBuilderBrowserOriginForEvent(event),
+                    });
                 }
-            }
-            // No Sec-Fetch-Site, no Origin, no Referer — pre-2020 browser
-            // making a top-level navigation. Allow; cookies are still
-            // session-bound so the worst case degrades to the prior behavior.
-            return true;
-        }
-        // Lightweight 302 to the Builder CLI-auth URL. Lets clients do
-        // `window.open('/_agent-native/builder/connect', '_blank')` synchronously
-        // inside a click handler, avoiding the popup-blocker downgrade that
-        // happens when an await sits before window.open.
-        //
-        // CSRF protection here is layered because session cookies are
-        // SameSite=None;Secure (so the editor iframe can ride along) — that
-        // means a session cookie alone does NOT prevent cross-origin
-        // window.open from initiating a connect flow on the victim's behalf:
-        //   1. Signed connect token from /builder/status — proves the opener
-        //      could read same-origin JSON, which cross-site attackers cannot.
-        //      This covers local/embedded browsers that conservatively label a
-        //      legitimate popup navigation as same-site/cross-site.
-        //   2. Sec-Fetch-Site header fallback — modern browsers stamp every
-        //      request with the navigation context. We allow `same-origin` or
-        //      `none` (typed/bookmark/extension); cross-site / same-site without
-        //      a valid connect token are rejected.
-        //   3. Pending row keyed by session email + bound nonce — the callback
-        //      requires both a valid session and a one-time row that this
-        //      handler wrote during the same flow. Without the same-origin
-        //      gate or connect token above, an attacker could prime the row from
-        //      cross-site and then trick the victim into hitting a callback URL
-        //      with attacker-controlled p-key/api-key, hijacking the victim's
-        //      account.
-        getH3App(nitroApp).use(`${P}/builder/connect`, defineEventHandler(async (event) => {
-            const ownerContext = await resolveBuilderOwnerContext(event, "connect");
-            const ownerEmail = ownerContext.email;
-            if (!ownerEmail) {
-                setResponseStatus(event, 401);
-                return { error: "Authentication required" };
-            }
-            const requestUrl = new URL(`${event.url?.pathname || "/"}${event.url?.search || ""}`, getBuilderBrowserOriginForEvent(event));
-            const connectToken = requestUrl.searchParams.get(BUILDER_CONNECT_PARAM);
-            const connectTokenOwner = verifyBuilderConnectTokenAndGetOwner(connectToken);
-            const connectTracking = getBuilderConnectTrackingParams(requestUrl.searchParams);
-            // The token must both be well-formed AND minted for the current
-            // session owner. Without the owner check, an attacker holding any
-            // valid signed token could trick a victim into hitting this route
-            // with that token to bypass the cross-origin gate.
-            const hasValidConnectToken = Boolean(connectTokenOwner) && connectTokenOwner === ownerEmail;
-            // Same-origin gate. Sec-Fetch-Site remains the fast path; the signed
-            // connect token is the compatibility path for legitimate embedded or
-            // local desktop popups stamped as same-site/cross-site by the browser.
-            if (!isSameOriginConnect(event) && !hasValidConnectToken) {
-                const crossOriginMessage = connectToken
-                    ? "This Builder connect link is expired or belongs to a different deployment. Close this popup and click Connect account again."
-                    : "Builder connect opened without a fresh signed link. Close this popup and click Connect account again.";
-                await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
+                await trackBuilderLifecycle(event, "builder connect started", ownerEmail, {
                     ...builderConnectTrackingProperties(connectTracking),
-                    reason: "cross_origin",
                     stage: "connect",
-                    has_connect_token: Boolean(connectToken),
-                    has_valid_connect_token: false,
-                    connect_token_owner_matches_context: false,
-                    sec_fetch_site: getHeader(event, "sec-fetch-site") ?? null,
-                });
-                await putSetting(`builder-connect-error:${ownerEmail}`, {
-                    message: crossOriginMessage,
-                    at: Date.now(),
-                }).catch(() => { });
-                console.warn("[builder-connect] rejected cross-origin connect", {
-                    hasConnectToken: Boolean(connectToken),
-                    secFetchSite: getHeader(event, "sec-fetch-site") ?? null,
-                    origin: getHeader(event, "origin") ?? null,
-                    referer: getHeader(event, "referer") ?? null,
-                });
-                setResponseStatus(event, 403);
-                setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                return createBuilderBrowserCallbackErrorPage(crossOriginMessage, {
-                    title: "Couldn't start Builder connection",
-                    body: "The connect popup did not include a valid signed link for this app.",
-                    closeHint: "Close this popup, refresh the app, and try Connect account again.",
-                    parentOrigin: getBuilderBrowserOriginForEvent(event),
+                    connect_token_owner_matches_context: !connectTokenOwner || connectTokenOwner === ownerEmail,
                 });
-            }
-            // Clear any prior failure row from a previous attempt — otherwise
-            // useBuilderStatus polling sees the stale error and aborts the
-            // new attempt before it can complete.
-            try {
-                await deleteSetting(`builder-connect-error:${ownerEmail}`);
-            }
-            catch {
-                // No prior error row — fine
-            }
-            // Store a short-lived pending row. If the DB is unavailable we
-            // surface a popup-renderable error page that signals the parent
-            // via BroadcastChannel, rather than letting the popup show raw
-            // JSON and the parent poll for 5 minutes.
-            try {
-                await putSetting(`builder-pending-connect:${ownerEmail}`, {
-                    expiresAt: Date.now() + BUILDER_CONNECT_PENDING_TTL_MS,
+                setBuilderConnectOwnerCookie(event, ownerEmail);
+                // The primary UI now opens the signed Builder /cli-auth URL directly
+                // from /builder/status. Keep this legacy trampoline working for older
+                // clients, but still send it to Builder immediately and include signed
+                // callback state so the callback does not depend on popup cookies.
+                const cliAuthUrl = buildBuilderCliAuthUrl(getBuilderCliAuthCallbackOriginForEvent(event), signBuilderCallbackState(ownerEmail), {
+                    previewOrigin: getBuilderBrowserOriginForEvent(event),
                     tracking: connectTracking,
                 });
-            }
-            catch (err) {
-                await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
-                    ...builderConnectTrackingProperties(connectTracking),
-                    reason: "pending_storage_unavailable",
-                    stage: "connect",
+                setResponseStatus(event, 302);
+                setResponseHeader(event, "Location", cliAuthUrl);
+                return "";
+            }));
+            getH3App(nitroApp).use(`${P}/builder/run`, defineEventHandler(async (event) => {
+                if (getMethod(event) !== "POST") {
+                    setResponseStatus(event, 405);
+                    return { error: "Method not allowed" };
+                }
+                const body = await readBody(event).catch(() => ({}));
+                const prompt = typeof body?.prompt === "string" ? body.prompt : "";
+                if (!prompt.trim()) {
+                    setResponseStatus(event, 400);
+                    return { error: "prompt is required" };
+                }
+                const session = await getSession(event).catch(() => null);
+                if (!session?.email) {
+                    setResponseStatus(event, 401);
+                    return { error: "Authentication required" };
+                }
+                const userEmail = session.email;
+                let orgId = null;
+                try {
+                    const orgCtx = await getOrgContext(event);
+                    orgId = orgCtx.orgId ?? null;
+                }
+                catch {
+                    /* org module not present in this template — keep userEmail-only */
+                }
+                // Wrap in runWithRequestContext so resolveBuilderCredential() inside
+                // runBuilderAgent() resolves per-user app_secrets rather than falling
+                // through to process.env — the same pattern the /builder/status endpoint
+                // uses. Without this, per-user Builder keys stored in app_secrets are
+                // invisible to the run path and the call throws "Builder keys are not
+                // configured" even though the status endpoint correctly reports configured=true.
+                return runWithRequestContext({ userEmail, orgId }, async () => {
+                    const projectId = await resolveBuilderBranchProjectId();
+                    if (!projectId) {
+                        setResponseStatus(event, 403);
+                        return {
+                            error: "Builder branch creation is not available for this organization yet.",
+                        };
+                    }
+                    const { resolveBuilderCredential: resolveBuilderCred } = await import("./credential-provider.js");
+                    const builderUserId = (await resolveBuilderCred("BUILDER_USER_ID")) || undefined;
+                    // Server-controlled projectId — don't let clients target arbitrary
+                    // Builder projects with our private key. When this feature graduates
+                    // past the hardcoded preview, the projectId will come from
+                    // workspace/org config, still resolved server-side.
+                    try {
+                        const result = await runBuilderAgent({
+                            prompt,
+                            projectId,
+                            branchName: typeof body?.branchName === "string"
+                                ? body.branchName
+                                : undefined,
+                            userEmail,
+                            userId: builderUserId,
+                        });
+                        return result;
+                    }
+                    catch (e) {
+                        setResponseStatus(event, 500);
+                        return {
+                            error: e instanceof Error ? e.message : "Builder run failed",
+                        };
+                    }
                 });
-                const msg = "Could not initiate Builder connect — storage unavailable. Try again.";
-                console.error("[builder] Could not store pending-connect state:", err?.message ?? err);
-                // Best-effort: also write the error row so the parent's
-                // /builder/status poll picks it up if BroadcastChannel doesn't.
-                await putSetting(`builder-connect-error:${ownerEmail}`, {
-                    message: msg,
-                    at: Date.now(),
-                }).catch(() => { });
-                setResponseStatus(event, 503);
-                setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                return createBuilderBrowserCallbackErrorPage(msg, {
-                    parentOrigin: getBuilderBrowserOriginForEvent(event),
+            }));
+            // Branch-creation waitlist signup. Used by ConnectBuilderCard when the
+            // current request has no Builder branch project configured — instead of
+            // the raw 403 from /builder/run, the card surfaces a waitlist CTA that
+            // POSTs here. Recorded as a tracking event so PostHog/Mixpanel/etc.
+            // capture demand without us standing up new storage.
+            getH3App(nitroApp).use(`${P}/builder/branch-waitlist`, defineEventHandler(async (event) => {
+                if (getMethod(event) !== "POST") {
+                    setResponseStatus(event, 405);
+                    return { error: "Method not allowed" };
+                }
+                const session = await getSession(event).catch(() => null);
+                if (!session?.email) {
+                    setResponseStatus(event, 401);
+                    return { error: "Authentication required" };
+                }
+                await trackBuilderLifecycle(event, "builder branch waitlist joined", session.email, {
+                    stage: "waitlist",
                 });
-            }
-            await trackBuilderLifecycle(event, "builder connect started", ownerEmail, {
-                ...builderConnectTrackingProperties(connectTracking),
-                stage: "connect",
-                connect_token_owner_matches_context: !connectTokenOwner || connectTokenOwner === ownerEmail,
-            });
-            setBuilderConnectOwnerCookie(event, ownerEmail);
-            // The primary UI now opens the signed Builder /cli-auth URL directly
-            // from /builder/status. Keep this legacy trampoline working for older
-            // clients, but still send it to Builder immediately and include signed
-            // callback state so the callback does not depend on popup cookies.
-            const cliAuthUrl = buildBuilderCliAuthUrl(getBuilderCliAuthCallbackOriginForEvent(event), signBuilderCallbackState(ownerEmail), {
-                previewOrigin: getBuilderBrowserOriginForEvent(event),
-                tracking: connectTracking,
-            });
-            setResponseStatus(event, 302);
-            setResponseHeader(event, "Location", cliAuthUrl);
-            return "";
-        }));
-        getH3App(nitroApp).use(`${P}/builder/run`, defineEventHandler(async (event) => {
-            if (getMethod(event) !== "POST") {
-                setResponseStatus(event, 405);
-                return { error: "Method not allowed" };
-            }
-            const body = await readBody(event).catch(() => ({}));
-            const prompt = typeof body?.prompt === "string" ? body.prompt : "";
-            if (!prompt.trim()) {
-                setResponseStatus(event, 400);
-                return { error: "prompt is required" };
-            }
-            const session = await getSession(event).catch(() => null);
-            if (!session?.email) {
-                setResponseStatus(event, 401);
-                return { error: "Authentication required" };
-            }
-            const userEmail = session.email;
-            let orgId = null;
-            try {
-                const orgCtx = await getOrgContext(event);
-                orgId = orgCtx.orgId ?? null;
-            }
-            catch {
-                /* org module not present in this template — keep userEmail-only */
-            }
-            // Wrap in runWithRequestContext so resolveBuilderCredential() inside
-            // runBuilderAgent() resolves per-user app_secrets rather than falling
-            // through to process.env — the same pattern the /builder/status endpoint
-            // uses. Without this, per-user Builder keys stored in app_secrets are
-            // invisible to the run path and the call throws "Builder keys are not
-            // configured" even though the status endpoint correctly reports configured=true.
-            return runWithRequestContext({ userEmail, orgId }, async () => {
-                const projectId = await resolveBuilderBranchProjectId();
-                if (!projectId) {
-                    setResponseStatus(event, 403);
-                    return {
-                        error: "Builder branch creation is not available for this organization yet.",
-                    };
+                return { ok: true };
+            }));
+            getH3App(nitroApp).use(`${P}/builder/callback`, defineEventHandler(async (event) => {
+                if (getMethod(event) !== "GET") {
+                    setResponseStatus(event, 405);
+                    return { error: "Method not allowed" };
                 }
-                const { resolveBuilderCredential: resolveBuilderCred } = await import("./credential-provider.js");
-                const builderUserId = (await resolveBuilderCred("BUILDER_USER_ID")) || undefined;
-                // Server-controlled projectId — don't let clients target arbitrary
-                // Builder projects with our private key. When this feature graduates
-                // past the hardcoded preview, the projectId will come from
-                // workspace/org config, still resolved server-side.
+                // A real session or a template-approved anonymous owner is required;
+                // the pending-row check below (combined with the same-origin gate on
+                // /builder/connect) blocks CSRF and callback replay.
+                const ownerContext = await resolveBuilderOwnerContext(event, "callback");
+                const ownerEmail = ownerContext.email;
+                // Diagnostic: log the resolver's inputs for debugging "No active
+                // connect flow found" reports. Reveals session-vs-state owner
+                // mismatches and missing/forged _an_state without leaking the
+                // signed token itself.
                 try {
-                    const result = await runBuilderAgent({
-                        prompt,
-                        projectId,
-                        branchName: typeof body?.branchName === "string"
-                            ? body.branchName
-                            : undefined,
-                        userEmail,
-                        userId: builderUserId,
-                    });
-                    return result;
+                    const debugSearch = new URLSearchParams((event.url?.search || "").replace(/^\?/, ""));
+                    const stateRaw = debugSearch.get(BUILDER_STATE_PARAM);
+                    const stateOwnerProbe = verifyBuilderCallbackStateAndGetOwner(stateRaw);
+                    const session = await getSession(event).catch(() => null);
+                    console.log(`[builder-callback] resolved-owner=${ownerEmail ?? "(none)"} session-email=${session?.email ?? "(none)"} state-owner=${stateOwnerProbe ?? "(none)"} state-present=${Boolean(stateRaw)} anon=${ownerContext.anonymous} host=${getHeader(event, "host") ?? "(none)"} sec-fetch-site=${getHeader(event, "sec-fetch-site") ?? "(none)"} origin=${getHeader(event, "origin") ?? "(none)"} referer=${getHeader(event, "referer") ?? "(none)"}`);
                 }
-                catch (e) {
-                    setResponseStatus(event, 500);
-                    return {
-                        error: e instanceof Error ? e.message : "Builder run failed",
-                    };
+                catch {
+                    // Diagnostic logging is best-effort; do not break the callback.
                 }
-            });
-        }));
-        // Branch-creation waitlist signup. Used by ConnectBuilderCard when the
-        // current request has no Builder branch project configured — instead of
-        // the raw 403 from /builder/run, the card surfaces a waitlist CTA that
-        // POSTs here. Recorded as a tracking event so PostHog/Mixpanel/etc.
-        // capture demand without us standing up new storage.
-        getH3App(nitroApp).use(`${P}/builder/branch-waitlist`, defineEventHandler(async (event) => {
-            if (getMethod(event) !== "POST") {
-                setResponseStatus(event, 405);
-                return { error: "Method not allowed" };
-            }
-            const session = await getSession(event).catch(() => null);
-            if (!session?.email) {
-                setResponseStatus(event, 401);
-                return { error: "Authentication required" };
-            }
-            await trackBuilderLifecycle(event, "builder branch waitlist joined", session.email, {
-                stage: "waitlist",
-            });
-            return { ok: true };
-        }));
-        getH3App(nitroApp).use(`${P}/builder/callback`, defineEventHandler(async (event) => {
-            if (getMethod(event) !== "GET") {
-                setResponseStatus(event, 405);
-                return { error: "Method not allowed" };
-            }
-            // A real session or a template-approved anonymous owner is required;
-            // the pending-row check below (combined with the same-origin gate on
-            // /builder/connect) blocks CSRF and callback replay.
-            const ownerContext = await resolveBuilderOwnerContext(event, "callback");
-            const ownerEmail = ownerContext.email;
-            // Diagnostic: log the resolver's inputs for debugging "No active
-            // connect flow found" reports. Reveals session-vs-state owner
-            // mismatches and missing/forged _an_state without leaking the
-            // signed token itself.
-            try {
-                const debugSearch = new URLSearchParams((event.url?.search || "").replace(/^\?/, ""));
-                const stateRaw = debugSearch.get(BUILDER_STATE_PARAM);
-                const stateOwnerProbe = verifyBuilderCallbackStateAndGetOwner(stateRaw);
-                const session = await getSession(event).catch(() => null);
-                console.log(`[builder-callback] resolved-owner=${ownerEmail ?? "(none)"} session-email=${session?.email ?? "(none)"} state-owner=${stateOwnerProbe ?? "(none)"} state-present=${Boolean(stateRaw)} anon=${ownerContext.anonymous} host=${getHeader(event, "host") ?? "(none)"} sec-fetch-site=${getHeader(event, "sec-fetch-site") ?? "(none)"} origin=${getHeader(event, "origin") ?? "(none)"} referer=${getHeader(event, "referer") ?? "(none)"}`);
-            }
-            catch {
-                // Diagnostic logging is best-effort; do not break the callback.
-            }
-            if (!ownerEmail) {
-                setResponseStatus(event, 401);
-                return { error: "Authentication required" };
-            }
-            clearBuilderConnectOwnerCookie(event);
-            const requestUrl = new URL(`${event.url?.pathname || "/"}${event.url?.search || ""}`, getOrigin(event));
-            let connectTracking = getBuilderConnectTrackingParams(requestUrl.searchParams);
-            // postMessage from the callback success/error pages must target the
-            // original preview opener, not the callback server. On the fallback
-            // path the callback is served from the env-configured gateway while
-            // the opener lives on the preview origin. Three sources of opener
-            // origin, in priority order:
-            //   1. `_an_opener` — written into the callback URL's query by
-            //      buildBuilderCliAuthUrl when cli-auth's allow-list forced
-            //      preview_url onto the gateway. Survives Builder's redirect
-            //      verbatim (Builder preserves redirect_url's query string).
-            //   2. `preview-url` — Builder echoes the top-level preview_url back
-            //      as a query param on the callback. Reflects the gateway on
-            //      the fallback path, but matches the opener on the happy path.
-            //   3. The event's own origin — last-resort fallback.
-            const openerOriginFromQuery = requestUrl.searchParams.get(BUILDER_OPENER_PARAM);
-            const callbackParentOrigin = resolveSafePreviewUrl(openerOriginFromQuery, event) ||
-                resolveSafePreviewUrl(requestUrl.searchParams.get("preview-url"), event) ||
-                getBuilderBrowserOriginForEvent(event);
-            const callbackStateOwner = verifyBuilderCallbackStateAndGetOwner(requestUrl.searchParams.get(BUILDER_STATE_PARAM));
-            const hasValidCallbackState = callbackStateOwner === ownerEmail;
-            // Verify either:
-            //   1. the signed callback state embedded in redirect_url by
-            //      /builder/status (primary flow), or
-            //   2. the server-side pending-connect row written by the legacy
-            //      /builder/connect trampoline.
-            //
-            // For the pending-row path, delete must succeed before we proceed;
-            // otherwise a DB blip
-            // leaves the row in place and the same callback URL can be
-            // replayed against the same session for up to 10 minutes (the
-            // TTL window). Treat a delete failure as a hard failure: the
-            // user retries, the next /builder/connect call rewrites the
-            // pending row.
-            let pendingValid = hasValidCallbackState;
-            let pendingError = null;
-            try {
-                const pending = (await getSetting(`builder-pending-connect:${ownerEmail}`));
-                if (pending?.tracking) {
-                    connectTracking = {
-                        signupSource: connectTracking.signupSource ?? pending.tracking.signupSource,
-                        agentNativeFlow: connectTracking.agentNativeFlow ??
-                            pending.tracking.agentNativeFlow,
-                        agentNativeConnectSource: connectTracking.agentNativeConnectSource ??
-                            pending.tracking.agentNativeConnectSource,
-                    };
+                if (!ownerEmail) {
+                    setResponseStatus(event, 401);
+                    return { error: "Authentication required" };
                 }
-                if (pending &&
-                    typeof pending.expiresAt === "number" &&
-                    Date.now() < pending.expiresAt) {
-                    try {
-                        await deleteSetting(`builder-pending-connect:${ownerEmail}`);
-                        pendingValid = true;
+                clearBuilderConnectOwnerCookie(event);
+                const requestUrl = new URL(`${event.url?.pathname || "/"}${event.url?.search || ""}`, getOrigin(event));
+                let connectTracking = getBuilderConnectTrackingParams(requestUrl.searchParams);
+                // postMessage from the callback success/error pages must target the
+                // original preview opener, not the callback server. On the fallback
+                // path the callback is served from the env-configured gateway while
+                // the opener lives on the preview origin. Three sources of opener
+                // origin, in priority order:
+                //   1. `_an_opener` — written into the callback URL's query by
+                //      buildBuilderCliAuthUrl when cli-auth's allow-list forced
+                //      preview_url onto the gateway. Survives Builder's redirect
+                //      verbatim (Builder preserves redirect_url's query string).
+                //   2. `preview-url` — Builder echoes the top-level preview_url back
+                //      as a query param on the callback. Reflects the gateway on
+                //      the fallback path, but matches the opener on the happy path.
+                //   3. The event's own origin — last-resort fallback.
+                const openerOriginFromQuery = requestUrl.searchParams.get(BUILDER_OPENER_PARAM);
+                const callbackParentOrigin = resolveSafePreviewUrl(openerOriginFromQuery, event) ||
+                    resolveSafePreviewUrl(requestUrl.searchParams.get("preview-url"), event) ||
+                    getBuilderBrowserOriginForEvent(event);
+                const callbackStateOwner = verifyBuilderCallbackStateAndGetOwner(requestUrl.searchParams.get(BUILDER_STATE_PARAM));
+                const hasValidCallbackState = callbackStateOwner === ownerEmail;
+                // Verify either:
+                //   1. the signed callback state embedded in redirect_url by
+                //      /builder/status (primary flow), or
+                //   2. the server-side pending-connect row written by the legacy
+                //      /builder/connect trampoline.
+                //
+                // For the pending-row path, delete must succeed before we proceed;
+                // otherwise a DB blip
+                // leaves the row in place and the same callback URL can be
+                // replayed against the same session for up to 10 minutes (the
+                // TTL window). Treat a delete failure as a hard failure: the
+                // user retries, the next /builder/connect call rewrites the
+                // pending row.
+                let pendingValid = hasValidCallbackState;
+                let pendingError = null;
+                try {
+                    const pending = (await getSetting(`builder-pending-connect:${ownerEmail}`));
+                    if (pending?.tracking) {
+                        connectTracking = {
+                            signupSource: connectTracking.signupSource ?? pending.tracking.signupSource,
+                            agentNativeFlow: connectTracking.agentNativeFlow ??
+                                pending.tracking.agentNativeFlow,
+                            agentNativeConnectSource: connectTracking.agentNativeConnectSource ??
+                                pending.tracking.agentNativeConnectSource,
+                        };
                     }
-                    catch (err) {
-                        if (!hasValidCallbackState) {
-                            pendingError =
-                                "Could not consume pending-connect token (storage error). Please retry.";
-                            console.error("[builder] deleteSetting failed for pending-connect — refusing to proceed (replay risk):", err?.message ?? err);
+                    if (pending &&
+                        typeof pending.expiresAt === "number" &&
+                        Date.now() < pending.expiresAt) {
+                        try {
+                            await deleteSetting(`builder-pending-connect:${ownerEmail}`);
+                            pendingValid = true;
+                        }
+                        catch (err) {
+                            if (!hasValidCallbackState) {
+                                pendingError =
+                                    "Could not consume pending-connect token (storage error). Please retry.";
+                                console.error("[builder] deleteSetting failed for pending-connect — refusing to proceed (replay risk):", err?.message ?? err);
+                            }
                         }
                     }
                 }
-            }
-            catch {
-                // DB temporarily unavailable — treat as missing.
-            }
-            if (pendingError) {
-                await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
-                    ...builderConnectTrackingProperties(connectTracking),
-                    reason: "pending_consume_storage_error",
-                    stage: "callback",
-                });
-                // Best-effort signal to the parent's poll loop, then render the
-                // popup-friendly error page so the BroadcastChannel notify fires.
-                await putSetting(`builder-connect-error:${ownerEmail}`, {
-                    message: pendingError,
-                    at: Date.now(),
-                }).catch(() => { });
-                setResponseStatus(event, 503);
-                setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                return createBuilderBrowserCallbackErrorPage(pendingError, {
-                    parentOrigin: callbackParentOrigin,
-                });
-            }
-            if (!pendingValid) {
-                // Diagnostic: log the exact reason pendingValid is false so we can
-                // distinguish "state didn't validate" from "no pending row" in
-                // production "No active connect flow found" reports.
-                console.warn(`[builder-callback] pending-invalid owner=${ownerEmail} has-state-param=${Boolean(requestUrl.searchParams.get(BUILDER_STATE_PARAM))} state-validated=${hasValidCallbackState} pending-error=${pendingError ?? "(none)"}`);
-                await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
-                    ...builderConnectTrackingProperties(connectTracking),
-                    reason: hasValidCallbackState
-                        ? "callback_state_unexpectedly_rejected"
-                        : "missing_pending_connect",
-                    stage: "callback",
-                    has_callback_state: Boolean(requestUrl.searchParams.get(BUILDER_STATE_PARAM)),
-                });
-                const msg = "No active connect flow found. Restart the Builder connect flow from Settings.";
-                // Write an error signal so the polling loop in the parent tab
-                // terminates quickly instead of waiting 5 minutes for the timeout.
-                try {
+                catch {
+                    // DB temporarily unavailable — treat as missing.
+                }
+                if (pendingError) {
+                    await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
+                        ...builderConnectTrackingProperties(connectTracking),
+                        reason: "pending_consume_storage_error",
+                        stage: "callback",
+                    });
+                    // Best-effort signal to the parent's poll loop, then render the
+                    // popup-friendly error page so the BroadcastChannel notify fires.
+                    await putSetting(`builder-connect-error:${ownerEmail}`, {
+                        message: pendingError,
+                        at: Date.now(),
+                    }).catch(() => { });
+                    setResponseStatus(event, 503);
+                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
+                    return createBuilderBrowserCallbackErrorPage(pendingError, {
+                        parentOrigin: callbackParentOrigin,
+                    });
+                }
+                if (!pendingValid) {
+                    // Diagnostic: log the exact reason pendingValid is false so we can
+                    // distinguish "state didn't validate" from "no pending row" in
+                    // production "No active connect flow found" reports.
+                    console.warn(`[builder-callback] pending-invalid owner=${ownerEmail} has-state-param=${Boolean(requestUrl.searchParams.get(BUILDER_STATE_PARAM))} state-validated=${hasValidCallbackState} pending-error=${pendingError ?? "(none)"}`);
+                    await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
+                        ...builderConnectTrackingProperties(connectTracking),
+                        reason: hasValidCallbackState
+                            ? "callback_state_unexpectedly_rejected"
+                            : "missing_pending_connect",
+                        stage: "callback",
+                        has_callback_state: Boolean(requestUrl.searchParams.get(BUILDER_STATE_PARAM)),
+                    });
+                    const msg = "No active connect flow found. Restart the Builder connect flow from Settings.";
+                    // Write an error signal so the polling loop in the parent tab
+                    // terminates quickly instead of waiting 5 minutes for the timeout.
+                    try {
+                        await putSetting(`builder-connect-error:${ownerEmail}`, {
+                            message: msg,
+                            at: Date.now(),
+                        });
+                    }
+                    catch {
+                        // DB unavailable — parent will time out naturally.
+                    }
+                    setResponseStatus(event, 403);
+                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
+                    return createBuilderBrowserCallbackErrorPage(msg, {
+                        parentOrigin: callbackParentOrigin,
+                    });
+                }
+                const privateKey = requestUrl.searchParams.get("p-key");
+                const publicKey = requestUrl.searchParams.get("api-key");
+                if (!privateKey || !publicKey) {
+                    await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
+                        ...builderConnectTrackingProperties(connectTracking),
+                        reason: "missing_credentials",
+                        stage: "callback",
+                    });
+                    // Render the popup-friendly error page (and write a status row)
+                    // instead of bare JSON, so the parent tab's poll loop terminates
+                    // immediately via BroadcastChannel rather than hanging until the
+                    // 5-minute timeout.
+                    const msg = "Builder didn't return credentials. Restart the connect flow from settings.";
                     await putSetting(`builder-connect-error:${ownerEmail}`, {
                         message: msg,
                         at: Date.now(),
+                    }).catch(() => { });
+                    setResponseStatus(event, 400);
+                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
+                    return createBuilderBrowserCallbackErrorPage(msg, {
+                        parentOrigin: callbackParentOrigin,
+                    });
+                }
+                const userId = requestUrl.searchParams.get("user-id");
+                const orgName = requestUrl.searchParams.get("org-name");
+                const orgKind = requestUrl.searchParams.get("kind");
+                // Store per-user in app_secrets so each user's Builder connection
+                // is independent. No more shared env vars that the last connector
+                // overwrites.
+                //
+                // Failure handling: a silent catch here (returning the success page
+                // anyway) was Midhun's bug on 2026-04-28 — popup said "yay", parent
+                // window polled `/builder/status` for 5 minutes seeing
+                // configured:false, never got a real error. Now we surface the
+                // failure two ways: (a) a settings row that the next /builder/status
+                // poll picks up, and (b) postMessage from the error page itself,
+                // wired into the popup HTML, so the parent stops polling immediately.
+                let writeError = null;
+                try {
+                    const { writeBuilderCredentials } = await import("./credential-provider.js");
+                    // Resolve the user's active org / role so the credentials land
+                    // at org scope when an owner/admin is connecting (everyone in
+                    // the org auto-resolves them on next chat call). Members and
+                    // users with no active org silently fall back to user scope.
+                    // Failure to read org context is non-fatal — we just keep the
+                    // legacy per-user behaviour for that connection.
+                    let orgId = null;
+                    let role = null;
+                    if (!ownerContext.anonymous) {
+                        try {
+                            const { getOrgContext } = await import("../org/context.js");
+                            const orgCtx = await getOrgContext(event);
+                            orgId = orgCtx.orgId ?? null;
+                            role = orgCtx.role ?? null;
+                        }
+                        catch {
+                            /* org module not present in this template — keep user scope */
+                        }
+                    }
+                    const target = await writeBuilderCredentials(ownerEmail, { privateKey, publicKey, userId, orgName, orgKind }, { orgId, role });
+                    console.log(`[builder-connect] wrote credentials email=${ownerEmail} requestOrgId=${orgId ?? "(none)"} role=${role ?? "(none)"} scope=${target.scope} scopeId=${target.scopeId}`);
+                }
+                catch (err) {
+                    writeError = err?.message ?? String(err);
+                    console.error("[builder] Failed to persist Builder credentials:", writeError);
+                }
+                if (writeError) {
+                    await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
+                        ...builderConnectTrackingProperties(connectTracking),
+                        reason: "credential_write_failed",
+                        stage: "callback",
+                    });
+                    // Best-effort signal to /builder/status. If putSetting also fails
+                    // (entire DB unreachable) the popup's postMessage still notifies
+                    // the parent. If both fail the parent times out at 5min as today.
+                    try {
+                        await putSetting(`builder-connect-error:${ownerEmail}`, {
+                            message: writeError,
+                            at: Date.now(),
+                        });
+                    }
+                    catch (settingsErr) {
+                        console.error("[builder] Couldn't even record connect-error to settings:", settingsErr?.message ?? settingsErr);
+                    }
+                    setResponseStatus(event, 500);
+                    setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
+                    return createBuilderBrowserCallbackErrorPage(writeError, {
+                        parentOrigin: callbackParentOrigin,
                     });
                 }
+                // Clear any legacy disconnect flag and any prior connect-error row
+                // (so a successful retry doesn't surface the previous failure).
+                try {
+                    await deleteSetting("builder-disconnected");
+                }
                 catch {
-                    // DB unavailable — parent will time out naturally.
+                    // DB not ready — proceed
                 }
-                setResponseStatus(event, 403);
-                setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                return createBuilderBrowserCallbackErrorPage(msg, {
-                    parentOrigin: callbackParentOrigin,
+                try {
+                    await deleteSetting(`builder-connect-error:${ownerEmail}`);
+                }
+                catch {
+                    // No prior error row — fine
+                }
+                const previewUrl = resolveBuilderCallbackReturnUrl({
+                    event,
+                    openerOrigin: openerOriginFromQuery,
+                    previewUrl: requestUrl.searchParams.get("preview-url"),
                 });
-            }
-            const privateKey = requestUrl.searchParams.get("p-key");
-            const publicKey = requestUrl.searchParams.get("api-key");
-            if (!privateKey || !publicKey) {
-                await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
+                await trackBuilderLifecycle(event, "builder connect succeeded", ownerEmail, {
                     ...builderConnectTrackingProperties(connectTracking),
-                    reason: "missing_credentials",
                     stage: "callback",
+                    has_preview_url: Boolean(previewUrl),
+                    org_kind: orgKind || undefined,
                 });
-                // Render the popup-friendly error page (and write a status row)
-                // instead of bare JSON, so the parent tab's poll loop terminates
-                // immediately via BroadcastChannel rather than hanging until the
-                // 5-minute timeout.
-                const msg = "Builder didn't return credentials. Restart the connect flow from settings.";
-                await putSetting(`builder-connect-error:${ownerEmail}`, {
-                    message: msg,
-                    at: Date.now(),
-                }).catch(() => { });
-                setResponseStatus(event, 400);
                 setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                return createBuilderBrowserCallbackErrorPage(msg, {
+                // The parent (opener) is the original preview surface that started the
+                // connect flow, NOT the callback server's own origin — when the
+                // env-configured gateway is used as the callback fallback (because
+                // Builder rejects the preview host), the callback server and the
+                // opener live on different origins, and postMessage to the gateway
+                // origin would be dropped by the preview opener. callbackParentOrigin
+                // is the precomputed best-available opener origin (`_an_opener` →
+                // `preview-url` → event origin).
+                return createBuilderBrowserCallbackPage(previewUrl, {
                     parentOrigin: callbackParentOrigin,
                 });
-            }
-            const userId = requestUrl.searchParams.get("user-id");
-            const orgName = requestUrl.searchParams.get("org-name");
-            const orgKind = requestUrl.searchParams.get("kind");
-            // Store per-user in app_secrets so each user's Builder connection
-            // is independent. No more shared env vars that the last connector
-            // overwrites.
-            //
-            // Failure handling: a silent catch here (returning the success page
-            // anyway) was Midhun's bug on 2026-04-28 — popup said "yay", parent
-            // window polled `/builder/status` for 5 minutes seeing
-            // configured:false, never got a real error. Now we surface the
-            // failure two ways: (a) a settings row that the next /builder/status
-            // poll picks up, and (b) postMessage from the error page itself,
-            // wired into the popup HTML, so the parent stops polling immediately.
-            let writeError = null;
-            try {
-                const { writeBuilderCredentials } = await import("./credential-provider.js");
-                // Resolve the user's active org / role so the credentials land
-                // at org scope when an owner/admin is connecting (everyone in
-                // the org auto-resolves them on next chat call). Members and
-                // users with no active org silently fall back to user scope.
-                // Failure to read org context is non-fatal — we just keep the
-                // legacy per-user behaviour for that connection.
+            }));
+            // POST /_agent-native/builder/disconnect — revoke the user's per-user
+            // or org-scoped Builder credentials in app_secrets. Deploy-level env
+            // credentials are never mutated here; if env is configured it remains as
+            // the fallback after request-scoped credentials are removed.
+            getH3App(nitroApp).use(`${P}/builder/disconnect`, defineEventHandler(async (event) => {
+                if (getMethod(event) !== "POST") {
+                    setResponseStatus(event, 405);
+                    return { error: "Method not allowed" };
+                }
+                const session = await getSession(event).catch(() => null);
+                if (!session?.email) {
+                    setResponseStatus(event, 401);
+                    return { error: "unauthorized" };
+                }
+                const { deleteBuilderCredentials } = await import("./credential-provider.js");
+                // Mirror the connect-side scope decision so disconnect undoes
+                // exactly what connect wrote: owner/admin connections land at
+                // org scope and tear down at org scope; member or no-org
+                // connections stay user-scoped on both ends. Symmetric, so a
+                // single Disconnect press always reverses what the same user's
+                // Connect press did.
                 let orgId = null;
                 let role = null;
-                if (!ownerContext.anonymous) {
-                    try {
-                        const { getOrgContext } = await import("../org/context.js");
-                        const orgCtx = await getOrgContext(event);
-                        orgId = orgCtx.orgId ?? null;
-                        role = orgCtx.role ?? null;
-                    }
-                    catch {
-                        /* org module not present in this template — keep user scope */
-                    }
-                }
-                const target = await writeBuilderCredentials(ownerEmail, { privateKey, publicKey, userId, orgName, orgKind }, { orgId, role });
-                console.log(`[builder-connect] wrote credentials email=${ownerEmail} requestOrgId=${orgId ?? "(none)"} role=${role ?? "(none)"} scope=${target.scope} scopeId=${target.scopeId}`);
-            }
-            catch (err) {
-                writeError = err?.message ?? String(err);
-                console.error("[builder] Failed to persist Builder credentials:", writeError);
-            }
-            if (writeError) {
-                await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
-                    ...builderConnectTrackingProperties(connectTracking),
-                    reason: "credential_write_failed",
-                    stage: "callback",
-                });
-                // Best-effort signal to /builder/status. If putSetting also fails
-                // (entire DB unreachable) the popup's postMessage still notifies
-                // the parent. If both fail the parent times out at 5min as today.
                 try {
-                    await putSetting(`builder-connect-error:${ownerEmail}`, {
-                        message: writeError,
-                        at: Date.now(),
-                    });
+                    const { getOrgContext } = await import("../org/context.js");
+                    const orgCtx = await getOrgContext(event);
+                    orgId = orgCtx.orgId ?? null;
+                    role = orgCtx.role ?? null;
                 }
-                catch (settingsErr) {
-                    console.error("[builder] Couldn't even record connect-error to settings:", settingsErr?.message ?? settingsErr);
+                catch {
+                    /* org module not present — keep user scope */
                 }
-                setResponseStatus(event, 500);
-                setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-                return createBuilderBrowserCallbackErrorPage(writeError, {
-                    parentOrigin: callbackParentOrigin,
-                });
-            }
-            // Clear any legacy disconnect flag and any prior connect-error row
-            // (so a successful retry doesn't surface the previous failure).
-            try {
-                await deleteSetting("builder-disconnected");
-            }
-            catch {
-                // DB not ready — proceed
-            }
-            try {
-                await deleteSetting(`builder-connect-error:${ownerEmail}`);
-            }
-            catch {
-                // No prior error row — fine
-            }
-            const previewUrl = resolveBuilderCallbackReturnUrl({
-                event,
-                openerOrigin: openerOriginFromQuery,
-                previewUrl: requestUrl.searchParams.get("preview-url"),
-            });
-            await trackBuilderLifecycle(event, "builder connect succeeded", ownerEmail, {
-                ...builderConnectTrackingProperties(connectTracking),
-                stage: "callback",
-                has_preview_url: Boolean(previewUrl),
-                org_kind: orgKind || undefined,
-            });
-            setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
-            // The parent (opener) is the original preview surface that started the
-            // connect flow, NOT the callback server's own origin — when the
-            // env-configured gateway is used as the callback fallback (because
-            // Builder rejects the preview host), the callback server and the
-            // opener live on different origins, and postMessage to the gateway
-            // origin would be dropped by the preview opener. callbackParentOrigin
-            // is the precomputed best-available opener origin (`_an_opener` →
-            // `preview-url` → event origin).
-            return createBuilderBrowserCallbackPage(previewUrl, {
-                parentOrigin: callbackParentOrigin,
-            });
-        }));
-        // POST /_agent-native/builder/disconnect — revoke the user's per-user
-        // or org-scoped Builder credentials in app_secrets. Deploy-level env
-        // credentials are never mutated here; if env is configured it remains as
-        // the fallback after request-scoped credentials are removed.
-        getH3App(nitroApp).use(`${P}/builder/disconnect`, defineEventHandler(async (event) => {
-            if (getMethod(event) !== "POST") {
-                setResponseStatus(event, 405);
-                return { error: "Method not allowed" };
-            }
-            const session = await getSession(event).catch(() => null);
-            if (!session?.email) {
-                setResponseStatus(event, 401);
-                return { error: "unauthorized" };
-            }
-            const { deleteBuilderCredentials } = await import("./credential-provider.js");
-            // Mirror the connect-side scope decision so disconnect undoes
-            // exactly what connect wrote: owner/admin connections land at
-            // org scope and tear down at org scope; member or no-org
-            // connections stay user-scoped on both ends. Symmetric, so a
-            // single Disconnect press always reverses what the same user's
-            // Connect press did.
-            let orgId = null;
-            let role = null;
-            try {
-                const { getOrgContext } = await import("../org/context.js");
-                const orgCtx = await getOrgContext(event);
-                orgId = orgCtx.orgId ?? null;
-                role = orgCtx.role ?? null;
-            }
-            catch {
-                /* org module not present — keep user scope */
-            }
-            try {
-                await deleteBuilderCredentials(session.email, { orgId, role });
-            }
-            catch (err) {
-                await trackBuilderLifecycle(event, "builder disconnect failed", session.email, {
-                    reason: "credential_delete_failed",
-                });
-                setResponseStatus(event, 500);
-                return {
-                    ok: false,
-                    error: "Could not remove Builder credentials — your connection is unchanged. Please retry.",
-                    cause: err instanceof Error ? err.message : String(err),
-                };
-            }
-            await trackBuilderLifecycle(event, "builder disconnect succeeded", session.email);
-            return { ok: true };
-        }));
-        // Proxy to Builder's agents-run API for background code changes.
-        getH3App(nitroApp).use(`${P}/builder/agents-run`, defineEventHandler(async (event) => {
-            if (getMethod(event) !== "POST") {
-                setResponseStatus(event, 405);
-                return { error: "Method not allowed" };
-            }
-            const session = await getSession(event).catch(() => null);
-            if (!session?.email) {
-                setResponseStatus(event, 401);
-                return { error: "unauthorized" };
-            }
-            return runWithRequestContext({ userEmail: session.email, orgId: session.orgId ?? undefined }, async () => {
-                const { resolveBuilderCredentials: resolveCreds } = await import("./credential-provider.js");
-                const creds = await resolveCreds();
-                if (!creds.privateKey || !creds.publicKey) {
-                    setResponseStatus(event, 400);
+                try {
+                    await deleteBuilderCredentials(session.email, { orgId, role });
+                }
+                catch (err) {
+                    await trackBuilderLifecycle(event, "builder disconnect failed", session.email, {
+                        reason: "credential_delete_failed",
+                    });
+                    setResponseStatus(event, 500);
                     return {
-                        error: "Builder not connected. Connect Builder in Setup to use background agent.",
+                        ok: false,
+                        error: "Could not remove Builder credentials — your connection is unchanged. Please retry.",
+                        cause: err instanceof Error ? err.message : String(err),
                     };
                 }
-                const body = (await readBody(event));
-                if (!body?.userMessage) {
-                    setResponseStatus(event, 400);
-                    return { error: "userMessage is required" };
+                await trackBuilderLifecycle(event, "builder disconnect succeeded", session.email);
+                return { ok: true };
+            }));
+            // Proxy to Builder's agents-run API for background code changes.
+            getH3App(nitroApp).use(`${P}/builder/agents-run`, defineEventHandler(async (event) => {
+                if (getMethod(event) !== "POST") {
+                    setResponseStatus(event, 405);
+                    return { error: "Method not allowed" };
                 }
-                const apiHost = process.env.BUILDER_API_HOST || "https://api.builder.io";
-                try {
-                    const res = await fetch(`${apiHost}/agents/run?apiKey=${encodeURIComponent(creds.publicKey)}`, {
-                        method: "POST",
-                        headers: {
-                            "Content-Type": "application/json",
-                            Authorization: `Bearer ${creds.privateKey}`,
-                        },
-                        body: JSON.stringify({
-                            userMessage: {
-                                userPrompt: body.userMessage,
+                const session = await getSession(event).catch(() => null);
+                if (!session?.email) {
+                    setResponseStatus(event, 401);
+                    return { error: "unauthorized" };
+                }
+                return runWithRequestContext({ userEmail: session.email, orgId: session.orgId ?? undefined }, async () => {
+                    const { resolveBuilderCredentials: resolveCreds } = await import("./credential-provider.js");
+                    const creds = await resolveCreds();
+                    if (!creds.privateKey || !creds.publicKey) {
+                        setResponseStatus(event, 400);
+                        return {
+                            error: "Builder not connected. Connect Builder in Setup to use background agent.",
+                        };
+                    }
+                    const body = (await readBody(event));
+                    if (!body?.userMessage) {
+                        setResponseStatus(event, 400);
+                        return { error: "userMessage is required" };
+                    }
+                    const apiHost = process.env.BUILDER_API_HOST || "https://api.builder.io";
+                    try {
+                        const res = await fetch(`${apiHost}/agents/run?apiKey=${encodeURIComponent(creds.publicKey)}`, {
+                            method: "POST",
+                            headers: {
+                                "Content-Type": "application/json",
+                                Authorization: `Bearer ${creds.privateKey}`,
                             },
-                            branchName: body.branchName,
-                        }),
-                    });
-                    if (!res.ok) {
-                        const err = await res.text().catch(() => "Unknown error");
-                        setResponseStatus(event, res.status);
+                            body: JSON.stringify({
+                                userMessage: {
+                                    userPrompt: body.userMessage,
+                                },
+                                branchName: body.branchName,
+                            }),
+                        });
+                        if (!res.ok) {
+                            const err = await res.text().catch(() => "Unknown error");
+                            setResponseStatus(event, res.status);
+                            return {
+                                error: redactValues(err, [
+                                    creds.privateKey,
+                                    creds.publicKey,
+                                ]),
+                            };
+                        }
+                        return await res.json();
+                    }
+                    catch (err) {
+                        setResponseStatus(event, 500);
                         return {
-                            error: redactValues(err, [creds.privateKey, creds.publicKey]),
+                            error: redactValues(err?.message || "Failed to reach Builder agents-run API", [creds.privateKey, creds.publicKey]),
                         };
                     }
-                    return await res.json();
-                }
-                catch (err) {
-                    setResponseStatus(event, 500);
-                    return {
-                        error: redactValues(err?.message || "Failed to reach Builder agents-run API", [creds.privateKey, creds.publicKey]),
-                    };
-                }
-            });
-        }));
-        // Env key management — framework keys are always included
-        const frameworkEnvKeys = [
-            { key: "ENABLE_BUILDER", label: "Enable Builder.io features" },
+                });
+            }));
+            // Env key management — framework keys are always included
+            const frameworkEnvKeys = [
+                { key: "ENABLE_BUILDER", label: "Enable Builder.io features" },
+                {
+                    key: "AGENT_ENGINE_PREFER_BYO_KEY",
+                    label: "Prefer BYO LLM key over Builder gateway (default: false — gateway wins)",
+                },
+                ...Object.values(PROVIDER_ENV_META).map(({ envVar, label }) => ({
+                    key: envVar,
+                    label,
+                })),
+            ];
             {
-                key: "AGENT_ENGINE_PREFER_BYO_KEY",
-                label: "Prefer BYO LLM key over Builder gateway (default: false — gateway wins)",
-            },
-            ...Object.values(PROVIDER_ENV_META).map(({ envVar, label }) => ({
-                key: envVar,
-                label,
-            })),
-        ];
-        {
-            const envKeys = [...frameworkEnvKeys, ...(options.envKeys ?? [])];
-            // Onboarding form fields are resolved per-request so late-registered
-            // steps (and template overrides) are picked up without a restart.
-            // Builder CLI auth writes scoped Builder credentials through the
-            // credential provider, never through the deploy-global env sink.
-            const collectOnboardingKeys = () => {
-                const keys = new Set();
-                for (const step of listOnboardingSteps()) {
-                    for (const method of step.methods) {
-                        if (method.kind === "form") {
-                            for (const field of method.payload.fields) {
-                                if (field?.key)
-                                    keys.add(field.key);
+                const envKeys = [...frameworkEnvKeys, ...(options.envKeys ?? [])];
+                // Onboarding form fields are resolved per-request so late-registered
+                // steps (and template overrides) are picked up without a restart.
+                // Builder CLI auth writes scoped Builder credentials through the
+                // credential provider, never through the deploy-global env sink.
+                const collectOnboardingKeys = () => {
+                    const keys = new Set();
+                    for (const step of listOnboardingSteps()) {
+                        for (const method of step.methods) {
+                            if (method.kind === "form") {
+                                for (const field of method.payload.fields) {
+                                    if (field?.key)
+                                        keys.add(field.key);
+                                }
                             }
                         }
                     }
-                }
-                return keys;
-            };
-            getH3App(nitroApp).use(`${P}/env-status`, defineEventHandler(async (event) => {
-                const session = await getSession(event).catch(() => null);
-                const userEmail = session?.email;
-                let orgId;
-                if (userEmail) {
-                    try {
-                        const orgCtx = await getOrgContext(event);
-                        orgId = orgCtx.orgId ?? undefined;
+                    return keys;
+                };
+                getH3App(nitroApp).use(`${P}/env-status`, defineEventHandler(async (event) => {
+                    const session = await getSession(event).catch(() => null);
+                    const userEmail = session?.email;
+                    let orgId;
+                    if (userEmail) {
+                        try {
+                            const orgCtx = await getOrgContext(event);
+                            orgId = orgCtx.orgId ?? undefined;
+                        }
+                        catch {
+                            /* org module not present in this template */
+                        }
+                    }
+                    const canUseDeployEnv = await runWithRequestContext({ userEmail, orgId }, () => canUseDeployCredentialFallbackForRequest());
+                    return envKeys.map((cfg) => {
+                        const isProviderKey = PROVIDER_ENV_VAR_KEYS.has(cfg.key);
+                        return {
+                            key: cfg.key,
+                            label: cfg.label,
+                            required: cfg.required ?? false,
+                            configured: !!process.env[cfg.key] && (!isProviderKey || canUseDeployEnv),
+                            ...(cfg.helpText ? { helpText: cfg.helpText } : {}),
+                        };
+                    });
+                }));
+                getH3App(nitroApp).use(`${P}/env-vars`, defineEventHandler(async (event) => {
+                    if (getMethod(event) !== "POST") {
+                        setResponseStatus(event, 405);
+                        return { error: "Method not allowed" };
+                    }
+                    // Env vars are deployment-wide globals, not per-tenant. On any
+                    // shared-DB multi-tenant deploy, allowing authenticated users to
+                    // write here lets one tenant overwrite Stripe / OpenAI / Sentry
+                    // keys for every other tenant. Disable the endpoint outside of
+                    // local-dev SQLite or an explicit single-tenant opt-in, and
+                    // direct callers to the per-org credential store instead.
+                    if (!isEnvVarWriteAllowed()) {
+                        setResponseStatus(event, 403);
+                        return {
+                            error: "env-vars endpoint disabled on multi-tenant deployments. Use saveCredential(key, value, { userEmail, orgId, scope: 'org' }) to store per-org credentials.",
+                        };
+                    }
+                    const body = await readBody(event);
+                    const { vars } = body;
+                    if (!Array.isArray(vars) || vars.length === 0) {
+                        setResponseStatus(event, 400);
+                        return { error: "vars array required" };
+                    }
+                    const allowedKeys = new Set([
+                        ...envKeys.map((k) => k.key),
+                        ...collectOnboardingKeys(),
+                    ]);
+                    const blockedEnvVarWriteKeys = new Set(BUILDER_ENV_KEYS);
+                    const isWritableEnvKey = (key) => allowedKeys.has(key) && !blockedEnvVarWriteKeys.has(key);
+                    const filtered = vars.filter((v) => typeof v.key === "string" &&
+                        isWritableEnvKey(v.key) &&
+                        typeof v.value === "string" &&
+                        v.value.trim().length > 0);
+                    if (filtered.length === 0) {
+                        setResponseStatus(event, 400);
+                        const rejectedEmpty = vars.some((v) => typeof v.key === "string" &&
+                            isWritableEnvKey(v.key) &&
+                            (typeof v.value !== "string" || v.value.trim().length === 0));
+                        return {
+                            error: rejectedEmpty
+                                ? "Env values must be non-empty — refusing to clear a saved key"
+                                : "No recognized env keys in request",
+                        };
+                    }
+                    // Write to .env file. When inside a workspace, write to the
+                    // workspace root .env so keys are shared across every app. The
+                    // per-app .env still wins at load time if it also defines a key.
+                    try {
+                        const scope = body?.scope ?? "auto";
+                        const workspaceRoot = findWorkspaceRoot(process.cwd());
+                        const envPath = scope === "app"
+                            ? path.join(process.cwd(), ".env")
+                            : workspaceRoot
+                                ? path.join(workspaceRoot, ".env")
+                                : path.join(process.cwd(), ".env");
+                        await upsertEnvFile(envPath, filtered);
+                    }
+                    catch {
+                        // Edge runtime — skip file write
+                    }
+                    // Update process.env immediately
+                    for (const { key, value } of filtered) {
+                        process.env[key] = value;
+                    }
+                    // Persist to settings table for serverless cold-start recovery.
+                    try {
+                        const envMap = {};
+                        for (const { key, value } of filtered)
+                            envMap[key] = value;
+                        const existing = (await getSetting("persisted-env-vars")) ?? {};
+                        await putSetting("persisted-env-vars", {
+                            ...existing,
+                            ...envMap,
+                        });
+                    }
+                    catch {
+                        // DB not ready yet — skip
+                    }
+                    return { saved: filtered.map((v) => v.key) };
+                }));
+            }
+            // GET /_agent-native/agent-engine/status — reports whether an engine
+            // is configured (settings row, settings+env, or auto-detected from env).
+            // The agent-chat UI uses this to skip the onboarding gate for providers
+            // not in the env-status list (OpenRouter, Groq, Ollama, …).
+            getH3App(nitroApp).use(`${P}/agent-engine/status`, defineEventHandler(async (event) => {
+                try {
+                    const session = await getSession(event).catch(() => null);
+                    const userEmail = session?.email;
+                    let orgId;
+                    if (userEmail) {
+                        try {
+                            const orgCtx = await getOrgContext(event);
+                            orgId = orgCtx.orgId ?? undefined;
+                        }
+                        catch {
+                            /* org module not present in this template */
+                        }
+                    }
+                    const stored = (await getSetting("agent-engine"));
+                    if (isAgentEngineSettingConfigured(stored)) {
+                        const engine = stored.engine;
+                        const entry = getAgentEngineEntry(engine);
+                        return {
+                            configured: true,
+                            engine,
+                            model: stored.model ?? entry?.defaultModel ?? DEFAULT_MODEL,
+                            source: "settings",
+                        };
+                    }
+                    const envEntry = process.env.AGENT_ENGINE
+                        ? getAgentEngineEntry(process.env.AGENT_ENGINE)
+                        : undefined;
+                    if (envEntry) {
+                        if (!isAgentEnginePackageInstalled(envEntry)) {
+                            return { configured: false };
+                        }
+                        return {
+                            configured: true,
+                            engine: envEntry.name,
+                            model: envEntry.defaultModel ?? DEFAULT_MODEL,
+                            source: "env",
+                            envVar: "AGENT_ENGINE",
+                        };
+                    }
+                    // Per-user app_secrets — a user who connected Builder (or pasted
+                    // their own provider key) may not have any deploy-level env vars
+                    // set, so check their per-user secret store before reporting "no
+                    // engine configured" and re-showing the onboarding gate.
+                    const detectedFromUser = await runWithRequestContext({ userEmail, orgId }, () => detectEngineFromUserSecrets());
+                    if (detectedFromUser?.name === "builder") {
+                        return {
+                            configured: true,
+                            engine: detectedFromUser.name,
+                            model: detectedFromUser.defaultModel ?? DEFAULT_MODEL,
+                            source: "app_secrets",
+                            envVar: detectedFromUser.requiredEnvVars[0],
+                        };
+                    }
+                    if (stored && typeof stored.engine === "string") {
+                        const entry = getAgentEngineEntry(stored.engine);
+                        if (entry &&
+                            (await runWithRequestContext({ userEmail, orgId }, () => isStoredEngineUsableForRequest(stored, entry)))) {
+                            return {
+                                configured: true,
+                                engine: stored.engine,
+                                model: stored.model ?? entry.defaultModel ?? DEFAULT_MODEL,
+                                source: "env",
+                                envVar: entry.requiredEnvVars[0],
+                            };
+                        }
+                    }
+                    if (detectedFromUser) {
+                        return {
+                            configured: true,
+                            engine: detectedFromUser.name,
+                            model: detectedFromUser.defaultModel ?? DEFAULT_MODEL,
+                            source: "app_secrets",
+                            envVar: detectedFromUser.requiredEnvVars[0],
+                        };
                     }
-                    catch {
-                        /* org module not present in this template */
+                    const canUseDeployEnv = await runWithRequestContext({ userEmail, orgId }, () => canUseDeployCredentialFallbackForRequest());
+                    const detected = canUseDeployEnv ? detectEngineFromEnv() : null;
+                    if (detected) {
+                        return {
+                            configured: true,
+                            engine: detected.name,
+                            model: detected.defaultModel ?? DEFAULT_MODEL,
+                            source: "env",
+                            envVar: detected.requiredEnvVars[0],
+                        };
                     }
                 }
-                const canUseDeployEnv = await runWithRequestContext({ userEmail, orgId }, () => canUseDeployCredentialFallbackForRequest());
-                return envKeys.map((cfg) => {
-                    const isProviderKey = PROVIDER_ENV_VAR_KEYS.has(cfg.key);
-                    return {
-                        key: cfg.key,
-                        label: cfg.label,
-                        required: cfg.required ?? false,
-                        configured: !!process.env[cfg.key] && (!isProviderKey || canUseDeployEnv),
-                        ...(cfg.helpText ? { helpText: cfg.helpText } : {}),
-                    };
-                });
+                catch { }
+                return { configured: false };
             }));
-            getH3App(nitroApp).use(`${P}/env-vars`, defineEventHandler(async (event) => {
+            // POST /_agent-native/agent-engine/disconnect — clear the agent-engine
+            // setting. Env vars are left alone so the next chat turn falls back to
+            // resolveEngine's env/default resolution.
+            getH3App(nitroApp).use(`${P}/agent-engine/disconnect`, defineEventHandler(async (event) => {
                 if (getMethod(event) !== "POST") {
                     setResponseStatus(event, 405);
                     return { error: "Method not allowed" };
                 }
-                // Env vars are deployment-wide globals, not per-tenant. On any
-                // shared-DB multi-tenant deploy, allowing authenticated users to
-                // write here lets one tenant overwrite Stripe / OpenAI / Sentry
-                // keys for every other tenant. Disable the endpoint outside of
-                // local-dev SQLite or an explicit single-tenant opt-in, and
-                // direct callers to the per-org credential store instead.
-                if (!isEnvVarWriteAllowed()) {
-                    setResponseStatus(event, 403);
-                    return {
-                        error: "env-vars endpoint disabled on multi-tenant deployments. Use saveCredential(key, value, { userEmail, orgId, scope: 'org' }) to store per-org credentials.",
-                    };
+                const session = await getSession(event).catch(() => null);
+                if (!session?.email) {
+                    setResponseStatus(event, 401);
+                    return { error: "unauthorized" };
                 }
-                const body = await readBody(event);
-                const { vars } = body;
-                if (!Array.isArray(vars) || vars.length === 0) {
-                    setResponseStatus(event, 400);
-                    return { error: "vars array required" };
+                try {
+                    await deleteSetting("agent-engine");
+                    return { ok: true };
                 }
-                const allowedKeys = new Set([
-                    ...envKeys.map((k) => k.key),
-                    ...collectOnboardingKeys(),
-                ]);
-                const blockedEnvVarWriteKeys = new Set(BUILDER_ENV_KEYS);
-                const isWritableEnvKey = (key) => allowedKeys.has(key) && !blockedEnvVarWriteKeys.has(key);
-                const filtered = vars.filter((v) => typeof v.key === "string" &&
-                    isWritableEnvKey(v.key) &&
-                    typeof v.value === "string" &&
-                    v.value.trim().length > 0);
-                if (filtered.length === 0) {
-                    setResponseStatus(event, 400);
-                    const rejectedEmpty = vars.some((v) => typeof v.key === "string" &&
-                        isWritableEnvKey(v.key) &&
-                        (typeof v.value !== "string" || v.value.trim().length === 0));
+                catch (err) {
+                    setResponseStatus(event, 500);
                     return {
-                        error: rejectedEmpty
-                            ? "Env values must be non-empty — refusing to clear a saved key"
-                            : "No recognized env keys in request",
+                        ok: false,
+                        error: err instanceof Error ? err.message : String(err),
                     };
                 }
-                // Write to .env file. When inside a workspace, write to the
-                // workspace root .env so keys are shared across every app. The
-                // per-app .env still wins at load time if it also defines a key.
-                try {
-                    const scope = body?.scope ?? "auto";
-                    const workspaceRoot = findWorkspaceRoot(process.cwd());
-                    const envPath = scope === "app"
-                        ? path.join(process.cwd(), ".env")
-                        : workspaceRoot
-                            ? path.join(workspaceRoot, ".env")
-                            : path.join(process.cwd(), ".env");
-                    await upsertEnvFile(envPath, filtered);
-                }
-                catch {
-                    // Edge runtime — skip file write
-                }
-                // Update process.env immediately
-                for (const { key, value } of filtered) {
-                    process.env[key] = value;
-                }
-                // Persist to settings table for serverless cold-start recovery.
-                try {
-                    const envMap = {};
-                    for (const { key, value } of filtered)
-                        envMap[key] = value;
-                    const existing = (await getSetting("persisted-env-vars")) ?? {};
-                    await putSetting("persisted-env-vars", { ...existing, ...envMap });
-                }
-                catch {
-                    // DB not ready yet — skip
-                }
-                return { saved: filtered.map((v) => v.key) };
             }));
-        }
-        // GET /_agent-native/agent-engine/status — reports whether an engine
-        // is configured (settings row, settings+env, or auto-detected from env).
-        // The agent-chat UI uses this to skip the onboarding gate for providers
-        // not in the env-status list (OpenRouter, Groq, Ollama, …).
-        getH3App(nitroApp).use(`${P}/agent-engine/status`, defineEventHandler(async (event) => {
-            try {
+            // GET/PUT/DELETE /_agent-native/agent-loop-settings — org/user-scoped
+            // ceiling for tool-calling loop iterations before the agent asks whether
+            // it should keep going.
+            getH3App(nitroApp).use(`${P}/agent-loop-settings`, defineEventHandler(async (event) => {
                 const session = await getSession(event).catch(() => null);
-                const userEmail = session?.email;
-                let orgId;
-                if (userEmail) {
-                    try {
-                        const orgCtx = await getOrgContext(event);
-                        orgId = orgCtx.orgId ?? undefined;
-                    }
-                    catch {
-                        /* org module not present in this template */
-                    }
+                if (!session?.email) {
+                    setResponseStatus(event, 401);
+                    return { error: "unauthorized" };
                 }
-                const stored = (await getSetting("agent-engine"));
-                if (isAgentEngineSettingConfigured(stored)) {
-                    const engine = stored.engine;
-                    const entry = getAgentEngineEntry(engine);
-                    return {
-                        configured: true,
-                        engine,
-                        model: stored.model ?? entry?.defaultModel ?? DEFAULT_MODEL,
-                        source: "settings",
-                    };
+                const orgCtx = await getOrgContext(event).catch(() => null);
+                const orgId = orgCtx?.orgId ?? session.orgId ?? null;
+                const ctx = { userEmail: session.email, orgId };
+                const canUpdate = await canUpdateAgentLoopSettings(session.email, orgId);
+                const withContext = async () => ({
+                    ...(await readAgentLoopSettings(ctx)),
+                    canUpdate,
+                    orgId,
+                    orgName: orgCtx?.orgName ?? null,
+                    role: orgCtx?.role ?? null,
+                });
+                const method = getMethod(event);
+                if (method === "GET") {
+                    return withContext();
                 }
-                const envEntry = process.env.AGENT_ENGINE
-                    ? getAgentEngineEntry(process.env.AGENT_ENGINE)
-                    : undefined;
-                if (envEntry) {
-                    if (!isAgentEnginePackageInstalled(envEntry)) {
-                        return { configured: false };
+                if (method === "PUT") {
+                    if (!canUpdate) {
+                        setResponseStatus(event, 403);
+                        return {
+                            error: orgId
+                                ? "Only organization owners and admins can change the agent step limit."
+                                : "You cannot change the agent step limit.",
+                        };
                     }
+                    const body = await readBody(event).catch(() => ({}));
+                    const validation = validateMaxIterationsInput(body?.maxIterations);
+                    if (validation.ok === false) {
+                        setResponseStatus(event, 400);
+                        return { error: validation.error };
+                    }
+                    const updated = await writeAgentLoopSettings(ctx, validation.value);
                     return {
-                        configured: true,
-                        engine: envEntry.name,
-                        model: envEntry.defaultModel ?? DEFAULT_MODEL,
-                        source: "env",
-                        envVar: "AGENT_ENGINE",
-                    };
-                }
-                // Per-user app_secrets — a user who connected Builder (or pasted
-                // their own provider key) may not have any deploy-level env vars
-                // set, so check their per-user secret store before reporting "no
-                // engine configured" and re-showing the onboarding gate.
-                const detectedFromUser = await runWithRequestContext({ userEmail, orgId }, () => detectEngineFromUserSecrets());
-                if (detectedFromUser?.name === "builder") {
-                    return {
-                        configured: true,
-                        engine: detectedFromUser.name,
-                        model: detectedFromUser.defaultModel ?? DEFAULT_MODEL,
-                        source: "app_secrets",
-                        envVar: detectedFromUser.requiredEnvVars[0],
+                        ...updated,
+                        canUpdate,
+                        orgId,
+                        orgName: orgCtx?.orgName ?? null,
+                        role: orgCtx?.role ?? null,
                     };
                 }
-                if (stored && typeof stored.engine === "string") {
-                    const entry = getAgentEngineEntry(stored.engine);
-                    if (entry &&
-                        (await runWithRequestContext({ userEmail, orgId }, () => isStoredEngineUsableForRequest(stored, entry)))) {
+                if (method === "DELETE") {
+                    if (!canUpdate) {
+                        setResponseStatus(event, 403);
                         return {
-                            configured: true,
-                            engine: stored.engine,
-                            model: stored.model ?? entry.defaultModel ?? DEFAULT_MODEL,
-                            source: "env",
-                            envVar: entry.requiredEnvVars[0],
+                            error: orgId
+                                ? "Only organization owners and admins can reset the agent step limit."
+                                : "You cannot reset the agent step limit.",
                         };
                     }
-                }
-                if (detectedFromUser) {
-                    return {
-                        configured: true,
-                        engine: detectedFromUser.name,
-                        model: detectedFromUser.defaultModel ?? DEFAULT_MODEL,
-                        source: "app_secrets",
-                        envVar: detectedFromUser.requiredEnvVars[0],
-                    };
-                }
-                const canUseDeployEnv = await runWithRequestContext({ userEmail, orgId }, () => canUseDeployCredentialFallbackForRequest());
-                const detected = canUseDeployEnv ? detectEngineFromEnv() : null;
-                if (detected) {
+                    const updated = await resetAgentLoopSettings(ctx);
                     return {
-                        configured: true,
-                        engine: detected.name,
-                        model: detected.defaultModel ?? DEFAULT_MODEL,
-                        source: "env",
-                        envVar: detected.requiredEnvVars[0],
+                        ...updated,
+                        canUpdate,
+                        orgId,
+                        orgName: orgCtx?.orgName ?? null,
+                        role: orgCtx?.role ?? null,
                     };
                 }
-            }
-            catch { }
-            return { configured: false };
-        }));
-        // POST /_agent-native/agent-engine/disconnect — clear the agent-engine
-        // setting. Env vars are left alone so the next chat turn falls back to
-        // resolveEngine's env/default resolution.
-        getH3App(nitroApp).use(`${P}/agent-engine/disconnect`, defineEventHandler(async (event) => {
-            if (getMethod(event) !== "POST") {
                 setResponseStatus(event, 405);
                 return { error: "Method not allowed" };
-            }
-            const session = await getSession(event).catch(() => null);
-            if (!session?.email) {
-                setResponseStatus(event, 401);
-                return { error: "unauthorized" };
-            }
-            try {
-                await deleteSetting("agent-engine");
-                return { ok: true };
-            }
-            catch (err) {
-                setResponseStatus(event, 500);
+            }));
+            // ─── Usage & cost summary ────────────────────────────────────────
+            // GET /_agent-native/usage?sinceDays=30
+            // Returns spend broken down by label, model, app, and day for the
+            // current user. Powers the Usage section in the agent settings panel.
+            getH3App(nitroApp).use(`${P}/usage`, defineEventHandler(async (event) => {
+                const session = await getSession(event).catch(() => null);
+                if (!session?.email) {
+                    setResponseStatus(event, 401);
+                    return { error: "unauthorized" };
+                }
+                const sinceDaysParam = new URL(`${event.url?.pathname || "/"}${event.url?.search || ""}`, "http://x").searchParams.get("sinceDays");
+                const sinceDays = Math.max(1, Math.min(365, Number(sinceDaysParam) || 30));
+                const { getUsageSummary, usageBillingForEngine } = await import("../usage/store.js");
+                const [summary, engineName] = await Promise.all([
+                    getUsageSummary({
+                        ownerEmail: session.email,
+                        sinceMs: Date.now() - sinceDays * 86_400_000,
+                    }),
+                    detectUsageEngineName(event, session.email),
+                ]);
                 return {
-                    ok: false,
-                    error: err instanceof Error ? err.message : String(err),
+                    ...summary,
+                    billing: usageBillingForEngine(engineName),
                 };
-            }
-        }));
-        // GET/PUT/DELETE /_agent-native/agent-loop-settings — org/user-scoped
-        // ceiling for tool-calling loop iterations before the agent asks whether
-        // it should keep going.
-        getH3App(nitroApp).use(`${P}/agent-loop-settings`, defineEventHandler(async (event) => {
-            const session = await getSession(event).catch(() => null);
-            if (!session?.email) {
-                setResponseStatus(event, 401);
-                return { error: "unauthorized" };
-            }
-            const orgCtx = await getOrgContext(event).catch(() => null);
-            const orgId = orgCtx?.orgId ?? session.orgId ?? null;
-            const ctx = { userEmail: session.email, orgId };
-            const canUpdate = await canUpdateAgentLoopSettings(session.email, orgId);
-            const withContext = async () => ({
-                ...(await readAgentLoopSettings(ctx)),
-                canUpdate,
-                orgId,
-                orgName: orgCtx?.orgName ?? null,
-                role: orgCtx?.role ?? null,
-            });
-            const method = getMethod(event);
-            if (method === "GET") {
-                return withContext();
-            }
-            if (method === "PUT") {
-                if (!canUpdate) {
-                    setResponseStatus(event, 403);
-                    return {
-                        error: orgId
-                            ? "Only organization owners and admins can change the agent step limit."
-                            : "You cannot change the agent step limit.",
-                    };
+            }));
+            // ─── File upload primitive ──────────────────────────────────────
+            // GET  /_agent-native/file-upload/status — report active provider
+            // POST /_agent-native/file-upload        — upload a file, return { url }
+            getH3App(nitroApp).use(`${P}/file-upload/status`, defineEventHandler(async (event) => {
+                const active = getActiveFileUploadProvider();
+                // resolveBuilderPrivateKey() reads per-user credentials from app_secrets
+                // (DB), which requires request context (AsyncLocalStorage) to know which
+                // user to scope by. Without runWithRequestContext() the ALS store is empty
+                // and it falls back to process.env only — missing OAuth-connected users.
+                const session = await getSession(event).catch(() => null);
+                const userEmail = session?.email;
+                let builderConfigured = !!process.env.BUILDER_PRIVATE_KEY;
+                try {
+                    const { resolveBuilderPrivateKey } = await import("./credential-provider.js");
+                    const resolve = () => resolveBuilderPrivateKey().then((k) => !!k);
+                    builderConfigured = userEmail
+                        ? await runWithRequestContext({ userEmail }, resolve)
+                        : await resolve();
                 }
-                const body = await readBody(event).catch(() => ({}));
-                const validation = validateMaxIterationsInput(body?.maxIterations);
-                if (validation.ok === false) {
-                    setResponseStatus(event, 400);
-                    return { error: validation.error };
+                catch {
+                    // fall back to env check above
                 }
-                const updated = await writeAgentLoopSettings(ctx, validation.value);
+                // When the builder builtin is selected via env var, its sync
+                // isConfigured() doesn't reflect per-user OAuth credentials. Use the
+                // async builderConfigured check so the status accurately represents
+                // whether this specific user can actually upload (thread 7 fix).
+                const isBuilderEnvActive = active?.id === "builder";
+                const configured = isBuilderEnvActive
+                    ? builderConfigured
+                    : !!active || builderConfigured;
+                const activeProvider = isBuilderEnvActive
+                    ? builderConfigured
+                        ? { id: "builder", name: "Builder.io" }
+                        : null
+                    : active
+                        ? { id: active.id, name: active.name }
+                        : builderConfigured
+                            ? { id: "builder", name: "Builder.io" }
+                            : null;
                 return {
-                    ...updated,
-                    canUpdate,
-                    orgId,
-                    orgName: orgCtx?.orgName ?? null,
-                    role: orgCtx?.role ?? null,
+                    configured,
+                    activeProvider,
+                    providers: listFileUploadProviders().map((p) => ({
+                        id: p.id,
+                        name: p.name,
+                        configured: p.isConfigured(),
+                    })),
+                    builderConfigured,
                 };
-            }
-            if (method === "DELETE") {
-                if (!canUpdate) {
-                    setResponseStatus(event, 403);
-                    return {
-                        error: orgId
-                            ? "Only organization owners and admins can reset the agent step limit."
-                            : "You cannot reset the agent step limit.",
-                    };
+            }));
+            getH3App(nitroApp).use(`${P}/file-upload`, defineEventHandler(async (event) => {
+                if (getMethod(event) !== "POST") {
+                    setResponseStatus(event, 405);
+                    return { error: "Method not allowed" };
                 }
-                const updated = await resetAgentLoopSettings(ctx);
+                const parts = await readMultipartFormData(event);
+                const filePart = parts?.find((p) => p.name === "file");
+                if (!filePart?.data) {
+                    setResponseStatus(event, 400);
+                    return { error: "No file uploaded" };
+                }
+                const session = await getSession(event);
+                if (!session?.email) {
+                    setResponseStatus(event, 401);
+                    return { error: "Unauthorized" };
+                }
+                const userEmail = session.email;
+                const result = await runWithRequestContext({ userEmail }, () => uploadFile({
+                    data: filePart.data,
+                    filename: filePart.filename,
+                    mimeType: filePart.type,
+                    ownerEmail: userEmail,
+                }));
+                if (result) {
+                    setResponseStatus(event, 201);
+                    return result;
+                }
+                setResponseStatus(event, 503);
                 return {
-                    ...updated,
-                    canUpdate,
-                    orgId,
-                    orgName: orgCtx?.orgName ?? null,
-                    role: orgCtx?.role ?? null,
+                    error: "No file upload provider configured. Connect Builder.io in Settings → File uploads, or register a provider.",
                 };
-            }
-            setResponseStatus(event, 405);
-            return { error: "Method not allowed" };
-        }));
-        // ─── Usage & cost summary ────────────────────────────────────────
-        // GET /_agent-native/usage?sinceDays=30
-        // Returns spend broken down by label, model, app, and day for the
-        // current user. Powers the Usage section in the agent settings panel.
-        getH3App(nitroApp).use(`${P}/usage`, defineEventHandler(async (event) => {
-            const session = await getSession(event).catch(() => null);
-            if (!session?.email) {
-                setResponseStatus(event, 401);
-                return { error: "unauthorized" };
-            }
-            const sinceDaysParam = new URL(`${event.url?.pathname || "/"}${event.url?.search || ""}`, "http://x").searchParams.get("sinceDays");
-            const sinceDays = Math.max(1, Math.min(365, Number(sinceDaysParam) || 30));
-            const { getUsageSummary, usageBillingForEngine } = await import("../usage/store.js");
-            const [summary, engineName] = await Promise.all([
-                getUsageSummary({
-                    ownerEmail: session.email,
-                    sinceMs: Date.now() - sinceDays * 86_400_000,
-                }),
-                detectUsageEngineName(event, session.email),
-            ]);
-            return {
-                ...summary,
-                billing: usageBillingForEngine(engineName),
-            };
-        }));
-        // ─── File upload primitive ──────────────────────────────────────
-        // GET  /_agent-native/file-upload/status — report active provider
-        // POST /_agent-native/file-upload        — upload a file, return { url }
-        getH3App(nitroApp).use(`${P}/file-upload/status`, defineEventHandler(async (event) => {
-            const active = getActiveFileUploadProvider();
-            // resolveBuilderPrivateKey() reads per-user credentials from app_secrets
-            // (DB), which requires request context (AsyncLocalStorage) to know which
-            // user to scope by. Without runWithRequestContext() the ALS store is empty
-            // and it falls back to process.env only — missing OAuth-connected users.
-            const session = await getSession(event).catch(() => null);
-            const userEmail = session?.email;
-            let builderConfigured = !!process.env.BUILDER_PRIVATE_KEY;
+            }));
+            // ─── Voice transcription (Whisper) ───────────────────────────────
+            // POST /_agent-native/transcribe-voice — multipart audio → text
+            getH3App(nitroApp).use(`${P}/transcribe-voice`, createTranscribeVoiceHandler());
+            // ─── Google realtime transcription session bridge ───────────────
+            // POST /_agent-native/transcribe-stream/session — resolve the user's
+            // Google service-account credential server-side, mint an opaque managed
+            // streaming session in ai-services, and return the websocket URL.
+            getH3App(nitroApp).use(`${P}/transcribe-stream/session`, createGoogleRealtimeSessionHandler());
+            // ─── Voice provider status ───────────────────────────────────────
+            // GET /_agent-native/voice-providers/status — which providers are
+            // configured for the current user (powers the Settings UI pills).
+            getH3App(nitroApp).use(`${P}/voice-providers/status`, createVoiceProvidersStatusHandler());
+            // ─── Ad-hoc secrets (user-created keys) ────────────────────────────
+            // Must mount before the generic /secrets handler to avoid shadowing.
+            const adHocSecretHandler = createAdHocSecretHandler();
+            getH3App(nitroApp).use(`${P}/secrets/adhoc`, adHocSecretHandler);
+            // ─── Secrets registry ────────────────────────────────────────────
+            // GET    /_agent-native/secrets              — list registered secrets + status
+            // POST   /_agent-native/secrets/:key         — write a secret value
+            // DELETE /_agent-native/secrets/:key         — remove a secret value
+            // POST   /_agent-native/secrets/:key/test    — re-run the validator
+            const listSecretsHandler = createListSecretsHandler();
+            const writeSecretHandler = createWriteSecretHandler();
+            const testSecretHandler = createTestSecretHandler();
+            getH3App(nitroApp).use(`${P}/secrets`, defineEventHandler(async (event) => {
+                const pathname = (event.url?.pathname || "")
+                    .replace(/^\/+/, "")
+                    .replace(/\/+$/, "");
+                const parts = pathname ? pathname.split("/") : [];
+                // Collection root — list handler.
+                if (parts.length === 0) {
+                    return listSecretsHandler(event);
+                }
+                // /:key/test — re-validate stored value.
+                if (parts.length === 2 && parts[1] === "test") {
+                    return testSecretHandler(event);
+                }
+                // /:key — write / delete a specific secret.
+                if (parts.length === 1) {
+                    return writeSecretHandler(event);
+                }
+                setResponseStatus(event, 404);
+                return { error: "Not found" };
+            }));
+            // ─── Notifications inbox ──────────────────────────────────────────
+            // GET    /_agent-native/notifications[?unread&limit&before]
+            // GET    /_agent-native/notifications/count
+            // POST   /_agent-native/notifications/:id/read
+            // POST   /_agent-native/notifications/read-all
+            // DELETE /_agent-native/notifications/:id
+            getH3App(nitroApp).use(`${P}/notifications`, createNotificationsHandler());
+            // ─── Extensions (sandboxed mini-app runtime + proxy) ────────────────
             try {
-                const { resolveBuilderPrivateKey } = await import("./credential-provider.js");
-                const resolve = () => resolveBuilderPrivateKey().then((k) => !!k);
-                builderConfigured = userEmail
-                    ? await runWithRequestContext({ userEmail }, resolve)
-                    : await resolve();
+                const { ensureExtensionsTables, registerExtensionsShareable } = await import("../extensions/store.js");
+                const { createExtensionsHandler } = await import("../extensions/routes.js");
+                ensureExtensionsTables().catch(() => { });
+                registerExtensionsShareable();
+                const extensionsHandler = createExtensionsHandler();
+                getH3App(nitroApp).use(`${P}/extensions`, extensionsHandler);
+                // Legacy alias — the previous public API was /_agent-native/tools/*.
+                // Mounted in addition to /extensions/* so any deployed iframes mid-flight
+                // (or external integrations bookmarked the old path) keep working.
+                getH3App(nitroApp).use(`${P}/tools`, extensionsHandler);
+                // Extension-point slots — sub-system of extensions.
+                const { ensureSlotTables } = await import("../extensions/slots/store.js");
+                const { createSlotsHandler } = await import("../extensions/slots/routes.js");
+                ensureSlotTables().catch(() => { });
+                getH3App(nitroApp).use(`${P}/slots`, createSlotsHandler());
             }
             catch {
-                // fall back to env check above
-            }
-            // When the builder builtin is selected via env var, its sync
-            // isConfigured() doesn't reflect per-user OAuth credentials. Use the
-            // async builderConfigured check so the status accurately represents
-            // whether this specific user can actually upload (thread 7 fix).
-            const isBuilderEnvActive = active?.id === "builder";
-            const configured = isBuilderEnvActive
-                ? builderConfigured
-                : !!active || builderConfigured;
-            const activeProvider = isBuilderEnvActive
-                ? builderConfigured
-                    ? { id: "builder", name: "Builder.io" }
-                    : null
-                : active
-                    ? { id: active.id, name: active.name }
-                    : builderConfigured
-                        ? { id: "builder", name: "Builder.io" }
-                        : null;
-            return {
-                configured,
-                activeProvider,
-                providers: listFileUploadProviders().map((p) => ({
-                    id: p.id,
-                    name: p.name,
-                    configured: p.isConfigured(),
-                })),
-                builderConfigured,
-            };
-        }));
-        getH3App(nitroApp).use(`${P}/file-upload`, defineEventHandler(async (event) => {
-            if (getMethod(event) !== "POST") {
-                setResponseStatus(event, 405);
-                return { error: "Method not allowed" };
-            }
-            const parts = await readMultipartFormData(event);
-            const filePart = parts?.find((p) => p.name === "file");
-            if (!filePart?.data) {
-                setResponseStatus(event, 400);
-                return { error: "No file uploaded" };
-            }
-            const session = await getSession(event);
-            if (!session?.email) {
-                setResponseStatus(event, 401);
-                return { error: "Unauthorized" };
+                // Extensions module not available — skip
             }
-            const userEmail = session.email;
-            const result = await runWithRequestContext({ userEmail }, () => uploadFile({
-                data: filePart.data,
-                filename: filePart.filename,
-                mimeType: filePart.type,
-                ownerEmail: userEmail,
+            // ─── Page-level legacy redirect: /tools → /extensions ──────────────
+            // Catches direct browser navigation / bookmarks for the old page route
+            // (`/tools`, `/tools/:id`) and 302s to the renamed equivalent under
+            // `/extensions`. The framework API alias above (`/_agent-native/tools/*`)
+            // is intentionally untouched — it stays mounted in parallel.
+            //
+            // Mounted with no path so the helper can do its own base-path stripping
+            // (h3 mount-matching only allows base-path stripping for `/_agent-native`
+            // and `/.well-known`). Returns undefined to fall through for anything
+            // that isn't a `/tools` page navigation.
+            getH3App(nitroApp).use(defineEventHandler((event) => {
+                const method = getMethod(event);
+                if (method !== "GET" && method !== "HEAD")
+                    return;
+                const rawPath = event.url?.pathname ??
+                    String(event.node?.req?.url ?? event.path ?? "/").split("?")[0];
+                const search = event.url?.search ?? "";
+                const target = resolveLegacyToolsRedirect(rawPath, search);
+                if (!target)
+                    return;
+                setResponseStatus(event, 302);
+                setResponseHeader(event, "Location", target);
+                return "";
             }));
-            if (result) {
-                setResponseStatus(event, 201);
-                return result;
-            }
-            setResponseStatus(event, 503);
-            return {
-                error: "No file upload provider configured. Connect Builder.io in Settings → File uploads, or register a provider.",
-            };
-        }));
-        // ─── Voice transcription (Whisper) ───────────────────────────────
-        // POST /_agent-native/transcribe-voice — multipart audio → text
-        getH3App(nitroApp).use(`${P}/transcribe-voice`, createTranscribeVoiceHandler());
-        // ─── Google realtime transcription session bridge ───────────────
-        // POST /_agent-native/transcribe-stream/session — resolve the user's
-        // Google service-account credential server-side, mint an opaque managed
-        // streaming session in ai-services, and return the websocket URL.
-        getH3App(nitroApp).use(`${P}/transcribe-stream/session`, createGoogleRealtimeSessionHandler());
-        // ─── Voice provider status ───────────────────────────────────────
-        // GET /_agent-native/voice-providers/status — which providers are
-        // configured for the current user (powers the Settings UI pills).
-        getH3App(nitroApp).use(`${P}/voice-providers/status`, createVoiceProvidersStatusHandler());
-        // ─── Ad-hoc secrets (user-created keys) ────────────────────────────
-        // Must mount before the generic /secrets handler to avoid shadowing.
-        const adHocSecretHandler = createAdHocSecretHandler();
-        getH3App(nitroApp).use(`${P}/secrets/adhoc`, adHocSecretHandler);
-        // ─── Secrets registry ────────────────────────────────────────────
-        // GET    /_agent-native/secrets              — list registered secrets + status
-        // POST   /_agent-native/secrets/:key         — write a secret value
-        // DELETE /_agent-native/secrets/:key         — remove a secret value
-        // POST   /_agent-native/secrets/:key/test    — re-run the validator
-        const listSecretsHandler = createListSecretsHandler();
-        const writeSecretHandler = createWriteSecretHandler();
-        const testSecretHandler = createTestSecretHandler();
-        getH3App(nitroApp).use(`${P}/secrets`, defineEventHandler(async (event) => {
-            const pathname = (event.url?.pathname || "")
-                .replace(/^\/+/, "")
-                .replace(/\/+$/, "");
-            const parts = pathname ? pathname.split("/") : [];
-            // Collection root — list handler.
-            if (parts.length === 0) {
-                return listSecretsHandler(event);
-            }
-            // /:key/test — re-validate stored value.
-            if (parts.length === 2 && parts[1] === "test") {
-                return testSecretHandler(event);
-            }
-            // /:key — write / delete a specific secret.
-            if (parts.length === 1) {
-                return writeSecretHandler(event);
-            }
-            setResponseStatus(event, 404);
-            return { error: "Not found" };
-        }));
-        // ─── Notifications inbox ──────────────────────────────────────────
-        // GET    /_agent-native/notifications[?unread&limit&before]
-        // GET    /_agent-native/notifications/count
-        // POST   /_agent-native/notifications/:id/read
-        // POST   /_agent-native/notifications/read-all
-        // DELETE /_agent-native/notifications/:id
-        getH3App(nitroApp).use(`${P}/notifications`, createNotificationsHandler());
-        // ─── Extensions (sandboxed mini-app runtime + proxy) ────────────────
-        try {
-            const { ensureExtensionsTables, registerExtensionsShareable } = await import("../extensions/store.js");
-            const { createExtensionsHandler } = await import("../extensions/routes.js");
-            ensureExtensionsTables().catch(() => { });
-            registerExtensionsShareable();
-            const extensionsHandler = createExtensionsHandler();
-            getH3App(nitroApp).use(`${P}/extensions`, extensionsHandler);
-            // Legacy alias — the previous public API was /_agent-native/tools/*.
-            // Mounted in addition to /extensions/* so any deployed iframes mid-flight
-            // (or external integrations bookmarked the old path) keep working.
-            getH3App(nitroApp).use(`${P}/tools`, extensionsHandler);
-            // Extension-point slots — sub-system of extensions.
-            const { ensureSlotTables } = await import("../extensions/slots/store.js");
-            const { createSlotsHandler } = await import("../extensions/slots/routes.js");
-            ensureSlotTables().catch(() => { });
-            getH3App(nitroApp).use(`${P}/slots`, createSlotsHandler());
-        }
-        catch {
-            // Extensions module not available — skip
-        }
-        // ─── Page-level legacy redirect: /tools → /extensions ──────────────
-        // Catches direct browser navigation / bookmarks for the old page route
-        // (`/tools`, `/tools/:id`) and 302s to the renamed equivalent under
-        // `/extensions`. The framework API alias above (`/_agent-native/tools/*`)
-        // is intentionally untouched — it stays mounted in parallel.
-        //
-        // Mounted with no path so the helper can do its own base-path stripping
-        // (h3 mount-matching only allows base-path stripping for `/_agent-native`
-        // and `/.well-known`). Returns undefined to fall through for anything
-        // that isn't a `/tools` page navigation.
-        getH3App(nitroApp).use(defineEventHandler((event) => {
-            const method = getMethod(event);
-            if (method !== "GET" && method !== "HEAD")
-                return;
-            const rawPath = event.url?.pathname ??
-                String(event.node?.req?.url ?? event.path ?? "/").split("?")[0];
-            const search = event.url?.search ?? "";
-            const target = resolveLegacyToolsRedirect(rawPath, search);
-            if (!target)
-                return;
-            setResponseStatus(event, 302);
-            setResponseHeader(event, "Location", target);
-            return "";
-        }));
-        // ─── Agent run progress ───────────────────────────────────────────
-        // GET    /_agent-native/runs[?active&limit]
-        // GET    /_agent-native/runs/:id
-        // DELETE /_agent-native/runs/:id
-        getH3App(nitroApp).use(`${P}/runs`, createProgressHandler());
-        // ─── Automations API ──────────────────────────────────────────────
-        // GET  /_agent-native/automations — list all automations (parsed triggers)
-        // POST /_agent-native/automations/fire-test — emit test.event.fired
-        getH3App(nitroApp).use(`${P}/automations`, defineEventHandler(async (event) => {
-            const method = getMethod(event);
-            const pathname = (event.path || event.url?.pathname || "")
-                .split("?")[0]
-                .replace(/^\/+/, "")
-                .replace(/\/+$/, "");
-            // Auth check applies to every method. Without this, any anonymous
-            // caller could `POST /fire-test` to emit unowned events that fan
-            // out across every tenant's matching trigger (the dispatcher
-            // short-circuits its owner check when `eventMeta.owner` is
-            // undefined). See audit 12 / fire-test finding.
-            const session = await getSession(event).catch(() => null);
-            if (!session?.email) {
-                setResponseStatus(event, 401);
-                return { error: "Unauthenticated" };
-            }
-            if ((pathname === "fire-test" || pathname.endsWith("/fire-test")) &&
-                method === "POST") {
-                try {
-                    const { emit } = await import("../event-bus/index.js");
-                    const body = (await readBody(event).catch(() => ({})));
-                    // Scope the test event to the current user so only their
-                    // automations fire, not those owned by other tenants.
-                    emit("test.event.fired", { data: body.data ?? {} }, {
-                        owner: session.email,
-                    });
-                    return { ok: true };
+            // ─── Agent run progress ───────────────────────────────────────────
+            // GET    /_agent-native/runs[?active&limit]
+            // GET    /_agent-native/runs/:id
+            // DELETE /_agent-native/runs/:id
+            getH3App(nitroApp).use(`${P}/runs`, createProgressHandler());
+            // ─── Automations API ──────────────────────────────────────────────
+            // GET  /_agent-native/automations — list all automations (parsed triggers)
+            // POST /_agent-native/automations/fire-test — emit test.event.fired
+            getH3App(nitroApp).use(`${P}/automations`, defineEventHandler(async (event) => {
+                const method = getMethod(event);
+                const pathname = (event.path || event.url?.pathname || "")
+                    .split("?")[0]
+                    .replace(/^\/+/, "")
+                    .replace(/\/+$/, "");
+                // Auth check applies to every method. Without this, any anonymous
+                // caller could `POST /fire-test` to emit unowned events that fan
+                // out across every tenant's matching trigger (the dispatcher
+                // short-circuits its owner check when `eventMeta.owner` is
+                // undefined). See audit 12 / fire-test finding.
+                const session = await getSession(event).catch(() => null);
+                if (!session?.email) {
+                    setResponseStatus(event, 401);
+                    return { error: "Unauthenticated" };
                 }
-                catch (err) {
-                    setResponseStatus(event, 500);
-                    return { error: err?.message ?? "Failed to emit test event" };
+                if ((pathname === "fire-test" || pathname.endsWith("/fire-test")) &&
+                    method === "POST") {
+                    try {
+                        const { emit } = await import("../event-bus/index.js");
+                        const body = (await readBody(event).catch(() => ({})));
+                        // Scope the test event to the current user so only their
+                        // automations fire, not those owned by other tenants.
+                        emit("test.event.fired", { data: body.data ?? {} }, {
+                            owner: session.email,
+                        });
+                        return { ok: true };
+                    }
+                    catch (err) {
+                        setResponseStatus(event, 500);
+                        return { error: err?.message ?? "Failed to emit test event" };
+                    }
                 }
-            }
-            if (method !== "GET") {
-                setResponseStatus(event, 405);
-                return { error: "Method not allowed" };
-            }
-            try {
-                const owner = session.email;
-                const { resourceListAllOwners, SHARED_OWNER } = await import("../resources/store.js");
-                const allResources = await resourceListAllOwners("jobs/");
-                const resources = allResources.filter((r) => r.owner === owner || r.owner === SHARED_OWNER);
-                const FRONT_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
-                const automations = resources
-                    .filter((r) => r.path.endsWith(".md") && !r.path.endsWith(".keep"))
-                    .map((r) => {
-                    const match = r.content.match(FRONT_RE);
-                    if (!match)
+                if (method !== "GET") {
+                    setResponseStatus(event, 405);
+                    return { error: "Method not allowed" };
+                }
+                try {
+                    const owner = session.email;
+                    const { resourceListAllOwners, SHARED_OWNER } = await import("../resources/store.js");
+                    const allResources = await resourceListAllOwners("jobs/");
+                    const resources = allResources.filter((r) => r.owner === owner || r.owner === SHARED_OWNER);
+                    const FRONT_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+                    const automations = resources
+                        .filter((r) => r.path.endsWith(".md") && !r.path.endsWith(".keep"))
+                        .map((r) => {
+                        const match = r.content.match(FRONT_RE);
+                        if (!match)
+                            return {
+                                id: r.id,
+                                name: r.path.replace(/^jobs\//, "").replace(/\.md$/, ""),
+                                path: r.path,
+                                owner: r.owner,
+                                triggerType: "schedule",
+                                enabled: false,
+                                mode: "agentic",
+                                body: r.content,
+                            };
+                        const yaml = match[1];
+                        const body = match[2].trim();
+                        const meta = {};
+                        for (const line of yaml.split("\n")) {
+                            const ci = line.indexOf(":");
+                            if (ci === -1)
+                                continue;
+                            const k = line.slice(0, ci).trim();
+                            let v = line.slice(ci + 1).trim();
+                            if ((v.startsWith('"') && v.endsWith('"')) ||
+                                (v.startsWith("'") && v.endsWith("'")))
+                                v = v.slice(1, -1);
+                            meta[k] = v;
+                        }
                         return {
                             id: r.id,
                             name: r.path.replace(/^jobs\//, "").replace(/\.md$/, ""),
                             path: r.path,
                             owner: r.owner,
-                            triggerType: "schedule",
-                            enabled: false,
-                            mode: "agentic",
-                            body: r.content,
+                            triggerType: meta.triggerType || "schedule",
+                            event: meta.event,
+                            schedule: meta.schedule,
+                            condition: meta.condition,
+                            mode: meta.mode || "agentic",
+                            domain: meta.domain,
+                            enabled: meta.enabled !== "false",
+                            lastStatus: meta.lastStatus,
+                            lastRun: meta.lastRun,
+                            lastError: meta.lastError,
+                            createdBy: meta.createdBy,
+                            body,
                         };
-                    const yaml = match[1];
-                    const body = match[2].trim();
-                    const meta = {};
-                    for (const line of yaml.split("\n")) {
-                        const ci = line.indexOf(":");
-                        if (ci === -1)
-                            continue;
-                        const k = line.slice(0, ci).trim();
-                        let v = line.slice(ci + 1).trim();
-                        if ((v.startsWith('"') && v.endsWith('"')) ||
-                            (v.startsWith("'") && v.endsWith("'")))
-                            v = v.slice(1, -1);
-                        meta[k] = v;
-                    }
-                    return {
-                        id: r.id,
-                        name: r.path.replace(/^jobs\//, "").replace(/\.md$/, ""),
-                        path: r.path,
-                        owner: r.owner,
-                        triggerType: meta.triggerType || "schedule",
-                        event: meta.event,
-                        schedule: meta.schedule,
-                        condition: meta.condition,
-                        mode: meta.mode || "agentic",
-                        domain: meta.domain,
-                        enabled: meta.enabled !== "false",
-                        lastStatus: meta.lastStatus,
-                        lastRun: meta.lastRun,
-                        lastError: meta.lastError,
-                        createdBy: meta.createdBy,
-                        body,
-                    };
-                });
-                return automations;
-            }
-            catch (err) {
-                setResponseStatus(event, 500);
-                return { error: err?.message ?? "Failed to list automations" };
-            }
-        }));
-        // ─── Application State CRUD ──────────────────────────────────────
-        // Auto-mounted so templates don't need boilerplate route files.
-        // ─── User-scoped settings store ────────────────────────────────────
-        // GET    /_agent-native/settings/:key   — read current user's value
-        // PUT    /_agent-native/settings/:key   — write current user's value
-        // DELETE /_agent-native/settings/:key   — clear current user's value
-        //
-        // Keys are auto-prefixed with `u:<email>:` so each user gets their
-        // own row — no leakage between sessions sharing the same DB.
-        getH3App(nitroApp).use(`${P}/settings`, defineEventHandler(async (event) => {
-            const rawKey = (event.url?.pathname || "").replace(/^\/+/, "").split("/")[0] || "";
-            const key = rawKey.replace(/[^a-zA-Z0-9_-]/g, "");
-            if (!key) {
-                setResponseStatus(event, 404);
-                return { error: "Settings key required" };
-            }
-            const session = await getSession(event);
-            if (!session?.email) {
-                setResponseStatus(event, 401);
-                return { error: "unauthorized" };
-            }
-            const method = getMethod(event);
-            const requestSource = event.node?.req?.headers?.["x-request-source"] || undefined;
-            if (method === "GET") {
-                const value = await getUserSetting(session.email, key);
-                if (!value) {
-                    setResponseStatus(event, 404);
-                    return { error: `No setting for ${key}` };
+                    });
+                    return automations;
                 }
-                return value;
-            }
-            if (method === "PUT") {
-                const body = await readBody(event);
-                await putUserSetting(session.email, key, body, { requestSource });
-                return body;
-            }
-            if (method === "DELETE") {
-                await deleteUserSetting(session.email, key, { requestSource });
-                return { ok: true };
-            }
-            setResponseStatus(event, 405);
-            return { error: "Method not allowed" };
-        }));
-        // ─── Avatar routes ──────────────────────────────────────────────────
-        // GET /_agent-native/avatar/:email — fetch any user's avatar (public)
-        // PUT /_agent-native/avatar       — update current user's avatar (auth required)
-        getH3App(nitroApp).use(`${P}/avatar`, defineEventHandler(async (event) => {
-            const method = getMethod(event);
-            const emailParam = (event.url?.pathname || "")
-                .replace(/^\/+/, "")
-                .split("/")[0];
-            if (method === "GET") {
-                if (!emailParam) {
-                    setResponseStatus(event, 400);
-                    return { error: "email required" };
+                catch (err) {
+                    setResponseStatus(event, 500);
+                    return { error: err?.message ?? "Failed to list automations" };
+                }
+            }));
+            // ─── Application State CRUD ──────────────────────────────────────
+            // Auto-mounted so templates don't need boilerplate route files.
+            // ─── User-scoped settings store ────────────────────────────────────
+            // GET    /_agent-native/settings/:key   — read current user's value
+            // PUT    /_agent-native/settings/:key   — write current user's value
+            // DELETE /_agent-native/settings/:key   — clear current user's value
+            //
+            // Keys are auto-prefixed with `u:<email>:` so each user gets their
+            // own row — no leakage between sessions sharing the same DB.
+            getH3App(nitroApp).use(`${P}/settings`, defineEventHandler(async (event) => {
+                const rawKey = (event.url?.pathname || "").replace(/^\/+/, "").split("/")[0] || "";
+                const key = rawKey.replace(/[^a-zA-Z0-9_-]/g, "");
+                if (!key) {
+                    setResponseStatus(event, 404);
+                    return { error: "Settings key required" };
                 }
-                const data = await getSetting(`avatar:${decodeURIComponent(emailParam)}`);
-                return { image: data?.image ?? null };
-            }
-            if (method === "PUT") {
                 const session = await getSession(event);
                 if (!session?.email) {
                     setResponseStatus(event, 401);
                     return { error: "unauthorized" };
                 }
-                const body = await readBody(event);
-                const { image } = body;
-                if (!image || !image.startsWith("data:image/")) {
-                    setResponseStatus(event, 400);
-                    return { error: "image (data URL) required" };
-                }
-                await putSetting(`avatar:${session.email}`, { image });
-                return { ok: true };
-            }
-            setResponseStatus(event, 405);
-            return { error: "Method not allowed" };
-        }));
-        if (!options.disableMcpConnect) {
-            getH3App(nitroApp).use("/.well-known/oauth-protected-resource", defineEventHandler((event) => handleMcpOAuthProtectedResourceMetadata(event)));
-            getH3App(nitroApp).use("/.well-known/oauth-authorization-server", defineEventHandler((event) => handleMcpOAuthAuthorizationServerMetadata(event)));
-            getH3App(nitroApp).use("/.well-known/openid-configuration", defineEventHandler((event) => handleMcpOAuthAuthorizationServerMetadata(event)));
-            getH3App(nitroApp).use(`${P}/mcp/oauth`, defineEventHandler(async (event) => {
-                const subpath = event.url?.pathname || "";
-                return handleMcpOAuth(event, subpath, {
-                    appId: options.mcpConnectAppId,
-                    appName: options.mcpConnectAppName ?? getAppName(),
-                });
-            }));
-            // Frictionless external-agent connection. A logged-in user mints a
-            // per-user, scoped, revocable MCP bearer token here — via the browser
-            // Connect page or the OAuth-style device-code flow a CLI drives — so
-            // they never copy a shared deployment secret. The handler resolves the
-            // browser session itself and serves its own login form (like /open)
-            // for the page + unauth device endpoints; the /token, /device/authorize,
-            // /tokens, /tokens/revoke subpaths require a session and 401 without it.
-            // The auth guard bypasses ONLY the page + device/start + device/poll
-            // (see createAuthGuardFn in auth.ts).
-            const mcpConnectOpts = {
-                appId: options.mcpConnectAppId,
-                appName: options.mcpConnectAppName ?? getAppName(),
-            };
-            getH3App(nitroApp).use(`${P}/mcp/connect`, defineEventHandler(async (event) => {
-                // The framework strips the mount prefix from event.url.pathname,
-                // so what remains is the subpath after `/connect` (e.g. `/token`,
-                // `/device/start`, or `` for the page itself).
-                const subpath = event.url?.pathname || "";
-                return handleMcpConnect(event, subpath, mcpConnectOpts);
-            }));
-        }
-        // Cross-app SSO ("Sign in with Agent-Native") — CLIENT side. Mounted
-        // ONLY when `AGENT_NATIVE_IDENTITY_HUB_URL` is set, so an unset env var
-        // means the route is never even registered: zero new surface, existing
-        // auth byte-for-byte unchanged. `/login` 302s to the identity hub;
-        // `/callback` verifies the hub-issued A2A-signed identity JWT and JIT-
-        // links the verified email into this app's local Better Auth store. The
-        // handler 404s if disabled (defence in depth). The auth guard bypasses
-        // these two exact paths under the same env gate.
-        if (isIdentitySsoEnabled()) {
-            getH3App(nitroApp).use(`${P}/identity`, defineEventHandler(async (event) => {
-                // Framework strips the mount prefix; what remains is the subpath
-                // after `/identity` (e.g. `/login`, `/callback`).
-                const subpath = event.url?.pathname || "";
-                return handleIdentitySso(event, subpath);
-            }));
-        }
-        if (!options.disableOpenRoute) {
-            // Stable deep-link route. External agents (MCP/A2A) surface
-            // `/_agent-native/open?app=…&view=…&<recordId>=…` links; this resolves
-            // the browser session, writes the one-shot `navigate` app-state command
-            // the UI already drains, and 302s to the rendered SPA view. The auth
-            // guard bypasses this exact path so it can serve its own login form.
-            getH3App(nitroApp).use(`${P}/open`, createOpenRouteHandler({ resolveOpenPath: options.resolveOpenPath }));
-        }
-        if (!options.disableEmbedRoute) {
-            // One-time ticket launcher for MCP Apps that embed the full React app.
-            // The ticket is minted by an authenticated MCP tool call and exchanged
-            // here for a short-lived browser session cookie + bearer fallback.
-            getH3App(nitroApp).use(`${P}/embed/start`, createEmbedStartRouteHandler({ getExistingSession: getSession }));
-        }
-        if (!options.disableAppState) {
-            // Compose draft routes (more specific path, mounted first so the
-            // generic app-state matcher below doesn't shadow them). The framework
-            // strips the mount prefix from event.url.pathname before calling us,
-            // so we just see e.g. `/abc-123` (id) or `/` (collection root).
-            getH3App(nitroApp).use(`${P}/application-state/compose`, defineEventHandler(async (event) => {
-                const id = (event.url?.pathname || "").replace(/^\/+/, "").split("/")[0] || "";
-                if (event.context) {
-                    event.context.params = { ...event.context.params, id };
-                }
                 const method = getMethod(event);
-                if (!id) {
-                    if (method === "GET")
-                        return listComposeDrafts(event);
-                    if (method === "DELETE")
-                        return deleteAllComposeDrafts(event);
+                const requestSource = event.node?.req?.headers?.["x-request-source"] || undefined;
+                if (method === "GET") {
+                    const value = await getUserSetting(session.email, key);
+                    if (!value) {
+                        setResponseStatus(event, 404);
+                        return { error: `No setting for ${key}` };
+                    }
+                    return value;
                 }
-                else {
-                    if (method === "GET")
-                        return getComposeDraft(event);
-                    if (method === "PUT")
-                        return putComposeDraft(event);
-                    if (method === "DELETE")
-                        return deleteComposeDraft(event);
+                if (method === "PUT") {
+                    const body = await readBody(event);
+                    await putUserSetting(session.email, key, body, { requestSource });
+                    return body;
+                }
+                if (method === "DELETE") {
+                    await deleteUserSetting(session.email, key, { requestSource });
+                    return { ok: true };
                 }
                 setResponseStatus(event, 405);
                 return { error: "Method not allowed" };
             }));
-            // Generic application state — match `/application-state/:key` only
-            // (NOT `/application-state/compose/...` which the handler above owns).
-            getH3App(nitroApp).use(`${P}/application-state`, defineEventHandler(async (event) => {
-                const key = (event.url?.pathname || "").replace(/^\/+/, "").split("/")[0] || "";
-                // Skip — compose handler above already handled it
-                if (key === "compose" || key === "")
-                    return;
-                if (event.context) {
-                    event.context.params = { ...event.context.params, key };
-                }
+            // ─── Avatar routes ──────────────────────────────────────────────────
+            // GET /_agent-native/avatar/:email — fetch any user's avatar (public)
+            // PUT /_agent-native/avatar       — update current user's avatar (auth required)
+            getH3App(nitroApp).use(`${P}/avatar`, defineEventHandler(async (event) => {
                 const method = getMethod(event);
-                if (method === "GET")
-                    return getState(event);
-                if (method === "PUT")
-                    return putState(event);
-                if (method === "DELETE")
-                    return deleteState(event);
+                const emailParam = (event.url?.pathname || "")
+                    .replace(/^\/+/, "")
+                    .split("/")[0];
+                if (method === "GET") {
+                    if (!emailParam) {
+                        setResponseStatus(event, 400);
+                        return { error: "email required" };
+                    }
+                    const data = await getSetting(`avatar:${decodeURIComponent(emailParam)}`);
+                    return { image: data?.image ?? null };
+                }
+                if (method === "PUT") {
+                    const session = await getSession(event);
+                    if (!session?.email) {
+                        setResponseStatus(event, 401);
+                        return { error: "unauthorized" };
+                    }
+                    const body = await readBody(event);
+                    const { image } = body;
+                    if (!image || !image.startsWith("data:image/")) {
+                        setResponseStatus(event, 400);
+                        return { error: "image (data URL) required" };
+                    }
+                    await putSetting(`avatar:${session.email}`, { image });
+                    return { ok: true };
+                }
                 setResponseStatus(event, 405);
                 return { error: "Method not allowed" };
             }));
+            if (!options.disableMcpConnect) {
+                getH3App(nitroApp).use("/.well-known/oauth-protected-resource", defineEventHandler((event) => handleMcpOAuthProtectedResourceMetadata(event)));
+                getH3App(nitroApp).use("/.well-known/oauth-authorization-server", defineEventHandler((event) => handleMcpOAuthAuthorizationServerMetadata(event)));
+                getH3App(nitroApp).use("/.well-known/openid-configuration", defineEventHandler((event) => handleMcpOAuthAuthorizationServerMetadata(event)));
+                getH3App(nitroApp).use(`${P}/mcp/oauth`, defineEventHandler(async (event) => {
+                    const subpath = event.url?.pathname || "";
+                    return handleMcpOAuth(event, subpath, {
+                        appId: options.mcpConnectAppId,
+                        appName: options.mcpConnectAppName ?? getAppName(),
+                    });
+                }));
+                // Frictionless external-agent connection. A logged-in user mints a
+                // per-user, scoped, revocable MCP bearer token here — via the browser
+                // Connect page or the OAuth-style device-code flow a CLI drives — so
+                // they never copy a shared deployment secret. The handler resolves the
+                // browser session itself and serves its own login form (like /open)
+                // for the page + unauth device endpoints; the /token, /device/authorize,
+                // /tokens, /tokens/revoke subpaths require a session and 401 without it.
+                // The auth guard bypasses ONLY the page + device/start + device/poll
+                // (see createAuthGuardFn in auth.ts).
+                const mcpConnectOpts = {
+                    appId: options.mcpConnectAppId,
+                    appName: options.mcpConnectAppName ?? getAppName(),
+                };
+                getH3App(nitroApp).use(`${P}/mcp/connect`, defineEventHandler(async (event) => {
+                    // The framework strips the mount prefix from event.url.pathname,
+                    // so what remains is the subpath after `/connect` (e.g. `/token`,
+                    // `/device/start`, or `` for the page itself).
+                    const subpath = event.url?.pathname || "";
+                    return handleMcpConnect(event, subpath, mcpConnectOpts);
+                }));
+            }
+            // Cross-app SSO ("Sign in with Agent-Native") — CLIENT side. Mounted
+            // ONLY when `AGENT_NATIVE_IDENTITY_HUB_URL` is set, so an unset env var
+            // means the route is never even registered: zero new surface, existing
+            // auth byte-for-byte unchanged. `/login` 302s to the identity hub;
+            // `/callback` verifies the hub-issued A2A-signed identity JWT and JIT-
+            // links the verified email into this app's local Better Auth store. The
+            // handler 404s if disabled (defence in depth). The auth guard bypasses
+            // these two exact paths under the same env gate.
+            if (isIdentitySsoEnabled()) {
+                getH3App(nitroApp).use(`${P}/identity`, defineEventHandler(async (event) => {
+                    // Framework strips the mount prefix; what remains is the subpath
+                    // after `/identity` (e.g. `/login`, `/callback`).
+                    const subpath = event.url?.pathname || "";
+                    return handleIdentitySso(event, subpath);
+                }));
+            }
+            if (!options.disableOpenRoute) {
+                // Stable deep-link route. External agents (MCP/A2A) surface
+                // `/_agent-native/open?app=…&view=…&<recordId>=…` links; this resolves
+                // the browser session, writes the one-shot `navigate` app-state command
+                // the UI already drains, and 302s to the rendered SPA view. The auth
+                // guard bypasses this exact path so it can serve its own login form.
+                getH3App(nitroApp).use(`${P}/open`, createOpenRouteHandler({ resolveOpenPath: options.resolveOpenPath }));
+            }
+            if (!options.disableEmbedRoute) {
+                // One-time ticket launcher for MCP Apps that embed the full React app.
+                // The ticket is minted by an authenticated MCP tool call and exchanged
+                // here for a short-lived browser session cookie + bearer fallback.
+                getH3App(nitroApp).use(`${P}/embed/start`, createEmbedStartRouteHandler({ getExistingSession: getSession }));
+            }
+            if (!options.disableAppState) {
+                // Compose draft routes (more specific path, mounted first so the
+                // generic app-state matcher below doesn't shadow them). The framework
+                // strips the mount prefix from event.url.pathname before calling us,
+                // so we just see e.g. `/abc-123` (id) or `/` (collection root).
+                getH3App(nitroApp).use(`${P}/application-state/compose`, defineEventHandler(async (event) => {
+                    const id = (event.url?.pathname || "").replace(/^\/+/, "").split("/")[0] ||
+                        "";
+                    if (event.context) {
+                        event.context.params = { ...event.context.params, id };
+                    }
+                    const method = getMethod(event);
+                    if (!id) {
+                        if (method === "GET")
+                            return listComposeDrafts(event);
+                        if (method === "DELETE")
+                            return deleteAllComposeDrafts(event);
+                    }
+                    else {
+                        if (method === "GET")
+                            return getComposeDraft(event);
+                        if (method === "PUT")
+                            return putComposeDraft(event);
+                        if (method === "DELETE")
+                            return deleteComposeDraft(event);
+                    }
+                    setResponseStatus(event, 405);
+                    return { error: "Method not allowed" };
+                }));
+                // Generic application state — match `/application-state/:key` only
+                // (NOT `/application-state/compose/...` which the handler above owns).
+                getH3App(nitroApp).use(`${P}/application-state`, defineEventHandler(async (event) => {
+                    const key = (event.url?.pathname || "").replace(/^\/+/, "").split("/")[0] ||
+                        "";
+                    // Skip — compose handler above already handled it
+                    if (key === "compose" || key === "")
+                        return;
+                    if (event.context) {
+                        event.context.params = { ...event.context.params, key };
+                    }
+                    const method = getMethod(event);
+                    if (method === "GET")
+                        return getState(event);
+                    if (method === "PUT")
+                        return putState(event);
+                    if (method === "DELETE")
+                        return deleteState(event);
+                    setResponseStatus(event, 405);
+                    return { error: "Method not allowed" };
+                }));
+            }
+            resolveInit();
+        }
+        catch (error) {
+            rejectInit(error);
+            throw error;
         }
     };
 }