@zackbart/connecta 0.24.2 → 0.24.4

package/dist/routes/shared.js

@@ -52,20 +52,20 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
         if (result.ok) {
             const subjectId = result.subjectId ?? result.userId;
             const actorNamespace = activityActorNamespace(provider);
-            const subject = subjectId && actorNamespace
-                ? { namespace: actorNamespace, id: subjectId }
-                : undefined;
             const derivedPrincipal = result.userId && actorNamespace
                 ? { namespace: actorNamespace, id: result.userId }
                 : undefined;
             const principal = validIdentityReference(result.principal)
                 ? result.principal
                 : derivedPrincipal;
+            const subject = subjectId
+                ? { namespace: actorNamespace ?? `connecta:auth:${provider.kind}`, id: subjectId }
+                : principal;
             const interactive = Boolean(result.userId && provider.interactiveOperator);
             const actor = {
                 kind: provider.kind,
                 ...(subjectId ? { id: subjectId } : {}),
-                ...(subject ? { namespace: subject.namespace } : {}),
+                ...(subjectId && actorNamespace ? { namespace: actorNamespace } : {}),
             };
             const identity = {
                 actor,

package/dist/server.js

@@ -1,3 +1,4 @@
+import { aggregateCallAdmissionSnapshots } from "./call-admission.js";
 import { isAdmittingExecutor } from "./executor-admission.js";
 import { createMcpRoute, MCP_CORS_HEADERS } from "./routes/mcp.js";
 import { routeOAuthCallback, } from "./routes/oauth.js";
@@ -18,6 +19,9 @@ export function createFetchHandler(opts) {
         const defer = runtimeContext
             ? runtimeContext.waitUntil.bind(runtimeContext)
             : undefined;
+        const originRefusal = routeMcp.rejectOrigin(request);
+        if (originRefusal)
+            return withSecurityHeaders(originRefusal, url, path);
         // Container and orchestrator probes reach /health over plain HTTP on
         // loopback, where no proxy has set X-Forwarded-Proto. Redirecting them to
         // the public origin would make an internal liveness check depend on
@@ -59,6 +63,9 @@ export function createFetchHandler(opts) {
             if (uiResponse)
                 return uiResponse;
             if (request.method === "OPTIONS") {
+                const preflight = await routeMcp.handle(context);
+                if (preflight)
+                    return preflight;
                 for (const provider of auth) {
                     if (provider.handleMetadata) {
                         const response = await provider.handleMetadata(request, baseUrl);
@@ -102,14 +109,19 @@ export function createFetchHandler(opts) {
                     // Counts only, from refreshes that already happened — the endpoint
                     // asks no downstream anything, and `connecta doctor` reads it to
                     // report a stale allowlist without a probe of its own (#343).
-                    catalogDrift: registry.catalogDriftSnapshot(),
+                    // Stable 64-bit hashes preserve that shape without publishing ids.
+                    catalogDrift: Object.fromEntries(await Promise.all(Object.entries(registry.catalogDriftSnapshot()).map(async ([id, report]) => {
+                        const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(id)));
+                        const key = Array.from(hash.subarray(0, 8), byte => byte.toString(16).padStart(2, "0")).join("");
+                        return [key, report];
+                    }))),
                     admission: {
                         policy: "global-fifo",
                         requests: opts.requestAdmission.snapshot(),
                         code: codeAdmission ?? { managedByExecutor: true },
                         downstreamCalls: {
                             policy: "connector-partitioned-per-runtime",
-                            connectors: registry.callAdmissionSnapshot(),
+                            aggregate: aggregateCallAdmissionSnapshots(Object.values(registry.callAdmissionSnapshot())),
                         },
                         reservedRoutes: [
                             "/health",
@@ -123,7 +135,7 @@ export function createFetchHandler(opts) {
             const oauthCallback = await routeOAuthCallback(context);
             if (oauthCallback)
                 return oauthCallback;
-            const mcp = await routeMcp(context);
+            const mcp = await routeMcp.handle(context);
             if (mcp)
                 return mcp;
             return new Response("Not Found", { status: 404 });

package/dist/skills.js

@@ -1,3 +1,4 @@
+import { boundedEchoText } from "./errors.js";
 export const CONNECTA_INSTRUCTIONS = 'Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar result shapes with a small sample before proceeding. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
 const USAGE_SKILL_BASE = `# Connecta usage
 
@@ -423,14 +424,14 @@ export function resolveSkill(name, connectors) {
         if (!connector) {
             return {
                 found: false,
-                message: `Unknown connector "${id}". Available skills: ${available()}.`,
+                message: `Unknown connector "${boundedEchoText(id)}". Available skills: ${available()}.`,
             };
         }
         const guide = connectorGuide(connector);
         if (!guide) {
             return {
                 found: false,
-                message: `Connector "${id}" has no usage guide. Available skills: ${available()}.`,
+                message: `Connector "${boundedEchoText(id)}" has no usage guide. Available skills: ${available()}.`,
             };
         }
         return { found: true, content: guide };
@@ -440,12 +441,12 @@ export function resolveSkill(name, connectors) {
         return {
             found: false,
             message: connectorGuide(bare)
-                ? `Unknown skill "${name}". Connector guides are fetched as "${connectorSkillName(name)}". Available skills: ${available()}.`
-                : `Connector "${name}" has no usage guide. Available skills: ${available()}.`,
+                ? `Unknown skill "${boundedEchoText(name)}". Connector guides are fetched as "${boundedEchoText(connectorSkillName(name))}". Available skills: ${available()}.`
+                : `Connector "${boundedEchoText(name)}" has no usage guide. Available skills: ${available()}.`,
         };
     }
     return {
         found: false,
-        message: `Unknown skill "${name}". Available skills: ${available()}.`,
+        message: `Unknown skill "${boundedEchoText(name)}". Available skills: ${available()}.`,
     };
 }

package/dist/storage/file.d.ts

@@ -5,7 +5,11 @@ export interface FileStorageOptions {
 }
 /**
  * JSON-file-backed KVStorage for Node. Loads once, persists on every write via
- * a temp-file + rename (atomic-ish). Only reachable via the "@zackbart/connecta/node"
+ * an exclusive temp-file + rename. Refuses a second holder of the same path.
+ * Call close() when finished to release its lock; process exit also releases it.
+ * Only reachable via the "@zackbart/connecta/node"
  * subpath so the main entry stays Workers-clean.
  */
-export declare function fileStorage(path: string, opts?: FileStorageOptions): KVStorage;
+export declare function fileStorage(path: string, opts?: FileStorageOptions): KVStorage & {
+    close(): void;
+};

package/dist/storage/file.js

@@ -1,11 +1,263 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
-import { dirname } from "node:path";
+import { chmodSync, closeSync, existsSync, futimesSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { dirname, resolve } from "node:path";
+const HEARTBEAT_MS = 15_000;
+const STALE_LOCK_MS = 60_000;
+const localLocks = new Map();
+// A pid is meaningful only in its own host/namespace. Container hostnames may
+// be shared, so Linux uses the kernel boot id and the actual PID namespace.
+const pidScope = (() => {
+    if (process.platform !== "linux")
+        return hostname();
+    try {
+        return `${readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()}:${readlinkSync("/proc/self/ns/pid")}`;
+    }
+    catch {
+        return undefined; // Without namespace evidence, rely on the heartbeat.
+    }
+})();
+function stale(path) {
+    return Date.now() - statSync(path).mtimeMs > STALE_LOCK_MS;
+}
+// One listener per module, removed when the last store closes. Node's listen()
+// drains requests before process.exit(), so the lock lasts through those writes.
+const openStores = new Set();
+const closeStores = () => {
+    for (const close of openStores) {
+        try {
+            close();
+        }
+        catch {
+            // A dead-pid or expired-heartbeat lock can be reclaimed next startup.
+        }
+    }
+};
+function hasCode(error, code) {
+    return error?.code === code;
+}
+function lockFile(path) {
+    const lockPath = `${path}.lock`;
+    const contents = JSON.stringify({
+        pid: process.pid,
+        pidScope,
+        createdAt: Date.now(),
+        id: randomUUID(),
+    });
+    const readLock = () => {
+        try {
+            return readFileSync(lockPath, "utf8");
+        }
+        catch (error) {
+            if (hasCode(error, "ENOENT"))
+                return null;
+            throw error;
+        }
+    };
+    const refuseLiveHolder = () => {
+        const raw = readLock();
+        if (raw === null)
+            return false;
+        try {
+            if (stale(lockPath))
+                return true;
+        }
+        catch (error) {
+            if (hasCode(error, "ENOENT"))
+                return false;
+            throw error;
+        }
+        let holder;
+        try {
+            holder = JSON.parse(raw);
+            if (!holder || !Number.isInteger(holder.pid) || holder.pid <= 0 ||
+                holder.pid > 2147483647 || !Number.isFinite(holder.createdAt)) {
+                throw new Error("Invalid lock holder");
+            }
+        }
+        catch {
+            throw new Error(`[connecta] state file ${path} has an unreadable lock at ${lockPath}. ` +
+                `Refusing to start. Retry after its heartbeat has been stale for 60 seconds.`);
+        }
+        if (pidScope !== undefined && holder.pidScope === pidScope) {
+            if (holder.pid === process.pid) {
+                // A new container process may inherit the old holder's pid. Only our
+                // own registry can distinguish that incarnation from a second opener.
+                if (localLocks.get(path) !== raw)
+                    return true;
+            }
+            else {
+                try {
+                    process.kill(holder.pid, 0);
+                }
+                catch (error) {
+                    if (hasCode(error, "ESRCH"))
+                        return true;
+                    // Permission errors do not establish that the holder is dead.
+                }
+            }
+        }
+        throw new Error(`[connecta] state file ${path} is held by pid ${holder.pid} ` +
+            `(lock timestamp ${holder.createdAt}). Close that store before opening another.`);
+    };
+    const acquire = () => {
+        let fd;
+        try {
+            fd = openSync(lockPath, "wx", 0o600);
+        }
+        catch (error) {
+            if (hasCode(error, "EEXIST"))
+                return false;
+            throw error;
+        }
+        try {
+            writeFileSync(fd, contents);
+            const now = new Date();
+            futimesSync(fd, now, now);
+        }
+        catch (error) {
+            unlinkSync(lockPath);
+            throw error;
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    };
+    if (!acquire()) {
+        refuseLiveHolder();
+        // Serialize stale-lock removal. Without this guard, two reclaimers could
+        // both observe the dead pid and the slower one unlink the new live lock.
+        // Recovery is synchronous. A guard older than the lease is from a crashed
+        // or paused reclaimer, which must recheck its ownership before continuing.
+        const reclaimPath = `${lockPath}.reclaim`;
+        const recoveryError = () => new Error(`[connecta] state file ${path} has a lock recovery in progress at ${reclaimPath}. ` +
+            `Retry after its 60-second lease expires.`);
+        try {
+            const expired = statSync(reclaimPath);
+            if (Date.now() - expired.mtimeMs > STALE_LOCK_MS) {
+                const markers = readdirSync(reclaimPath);
+                const current = statSync(reclaimPath);
+                if (current.dev !== expired.dev || current.ino !== expired.ino ||
+                    current.birthtimeMs !== expired.birthtimeMs || !stale(reclaimPath)) {
+                    throw recoveryError();
+                }
+                // Delete only the expired owner's unique marker. A competing cleanup
+                // cannot empty a replacement guard by deleting these old filenames.
+                for (const marker of markers)
+                    rmSync(`${reclaimPath}/${marker}`, { force: true });
+                rmdirSync(reclaimPath);
+            }
+        }
+        catch (error) {
+            if (hasCode(error, "ENOTEMPTY") || hasCode(error, "EEXIST"))
+                throw recoveryError();
+            if (!hasCode(error, "ENOENT"))
+                throw error;
+        }
+        try {
+            mkdirSync(reclaimPath, { mode: 0o700 });
+        }
+        catch (error) {
+            if (!hasCode(error, "EEXIST"))
+                throw error;
+            throw recoveryError();
+        }
+        const guard = statSync(reclaimPath);
+        const markerPath = `${reclaimPath}/${randomUUID()}`;
+        const ownsGuard = () => {
+            try {
+                const current = statSync(reclaimPath);
+                return current.dev === guard.dev && current.ino === guard.ino &&
+                    existsSync(markerPath);
+            }
+            catch (error) {
+                if (hasCode(error, "ENOENT"))
+                    return false;
+                throw error;
+            }
+        };
+        const assertGuard = () => {
+            if (!ownsGuard() || stale(reclaimPath))
+                throw recoveryError();
+        };
+        try {
+            writeFileSync(markerPath, "", { flag: "wx", mode: 0o600 });
+            if (!ownsGuard())
+                throw recoveryError();
+            const now = new Date();
+            utimesSync(reclaimPath, now, now);
+            const removeStale = refuseLiveHolder();
+            assertGuard();
+            if (removeStale)
+                unlinkSync(lockPath);
+            if (!acquire()) {
+                refuseLiveHolder();
+                throw new Error(`[connecta] state file ${path} lock changed during recovery. Retry opening it.`);
+            }
+        }
+        finally {
+            const owned = ownsGuard();
+            rmSync(markerPath, { force: true });
+            if (owned)
+                rmdirSync(reclaimPath);
+        }
+    }
+    const assertHeld = () => {
+        if (readLock() !== contents) {
+            throw new Error(`[connecta] state file ${path} lock was lost. Refusing to write a stale snapshot.`);
+        }
+    };
+    localLocks.set(path, contents);
+    const heartbeat = setInterval(() => {
+        try {
+            assertHeld();
+            const now = new Date();
+            utimesSync(lockPath, now, now);
+        }
+        catch {
+            // A replaced lock belongs to its new holder. Failed refreshes let the
+            // lease expire; subsequent writes still have to prove ownership.
+            clearInterval(heartbeat);
+        }
+    }, HEARTBEAT_MS);
+    heartbeat.unref();
+    return {
+        assertHeld,
+        release() {
+            clearInterval(heartbeat);
+            if (localLocks.get(path) === contents)
+                localLocks.delete(path);
+            if (readLock() === contents)
+                unlinkSync(lockPath);
+        },
+    };
+}
 /**
  * JSON-file-backed KVStorage for Node. Loads once, persists on every write via
- * a temp-file + rename (atomic-ish). Only reachable via the "@zackbart/connecta/node"
+ * an exclusive temp-file + rename. Refuses a second holder of the same path.
+ * Call close() when finished to release its lock; process exit also releases it.
+ * Only reachable via the "@zackbart/connecta/node"
  * subpath so the main entry stays Workers-clean.
  */
 export function fileStorage(path, opts = {}) {
+    path = resolve(path);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const lock = lockFile(path);
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        openStores.delete(close);
+        if (!openStores.size)
+            process.removeListener("exit", closeStores);
+        lock.release();
+    };
+    const assertOpen = () => {
+        if (closed)
+            throw new Error(`[connecta] state file ${path} is closed.`);
+    };
     const logger = opts.logger ?? console;
     // The state file holds downstream OAuth access/refresh tokens in cleartext,
     // so keep it owner-only. Repair is best-effort: chmod is a no-op or throws on
@@ -20,51 +272,68 @@ export function fileStorage(path, opts = {}) {
         }
     };
     let data = {};
-    if (existsSync(path)) {
-        tighten();
-        try {
-            data = JSON.parse(readFileSync(path, "utf8"));
-        }
-        catch (error) {
-            // Never let a damaged state file be silently replaced by an empty one:
-            // the next set() would persist {} over irreplaceable downstream OAuth
-            // tokens and credential-vault entries. Quarantine the bytes so they
-            // survive for manual recovery, and refuse to start if even that fails —
-            // losing the file loudly beats losing it quietly.
-            const quarantine = `${path}.corrupt-${Date.now()}`;
+    try {
+        if (existsSync(path)) {
+            tighten();
             try {
-                renameSync(path, quarantine);
+                data = JSON.parse(readFileSync(path, "utf8"));
             }
-            catch (renameError) {
-                throw new Error(`[connecta] state file ${path} is not valid JSON and could not be ` +
-                    `moved aside (${String(renameError)}). Refusing to start rather ` +
-                    `than overwrite it. Move or repair the file, then restart.`);
+            catch (error) {
+                // Never let a damaged state file be silently replaced by an empty one:
+                // the next set() would persist {} over irreplaceable downstream OAuth
+                // tokens and credential-vault entries. Quarantine the bytes so they
+                // survive for manual recovery, and refuse to start if even that fails —
+                // losing the file loudly beats losing it quietly.
+                const quarantine = `${path}.corrupt-${Date.now()}`;
+                try {
+                    renameSync(path, quarantine);
+                }
+                catch (renameError) {
+                    throw new Error(`[connecta] state file ${path} is not valid JSON and could not be ` +
+                        `moved aside (${String(renameError)}). Refusing to start rather ` +
+                        `than overwrite it. Move or repair the file, then restart.`);
+                }
+                logger.error(`[connecta] state file ${path} is not valid JSON ` +
+                    `(${error instanceof Error ? error.message : String(error)}) — ` +
+                    `moved to ${quarantine}, starting from empty state. Downstream ` +
+                    `OAuth connectors must be re-authorized and stored credentials ` +
+                    `re-entered.`);
+                data = {};
             }
-            logger.error(`[connecta] state file ${path} is not valid JSON ` +
-                `(${error instanceof Error ? error.message : String(error)}) — ` +
-                `moved to ${quarantine}, starting from empty state. Downstream ` +
-                `OAuth connectors must be re-authorized and stored credentials ` +
-                `re-entered.`);
-            data = {};
         }
     }
+    catch (error) {
+        close();
+        throw error;
+    }
+    if (!openStores.size)
+        process.on("exit", closeStores);
+    openStores.add(close);
     const persist = () => {
         // Physical expiry rides on an operation that was already going to write.
-        // A read must not flush this instance's load-once snapshot: another live
-        // instance may have written newer unrelated values since we loaded it.
+        // Reads only prune memory; they do not rewrite the state file.
         const now = Date.now();
         for (const [key, entry] of Object.entries(data)) {
             if (entry.exp && now > entry.exp)
                 delete data[key];
         }
-        const dir = dirname(path);
-        if (dir)
-            mkdirSync(dir, { recursive: true, mode: 0o700 });
-        const tmp = `${path}.tmp`;
+        const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
         // 0o600 on the tmp file; the atomic rename below preserves it, so the live
         // state file is never briefly world-readable.
-        writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
-        renameSync(tmp, path);
+        const fd = openSync(tmp, "wx", 0o600);
+        try {
+            try {
+                writeFileSync(fd, JSON.stringify(data));
+            }
+            finally {
+                closeSync(fd);
+            }
+            lock.assertHeld();
+            renameSync(tmp, path);
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
         tighten();
     };
     const fresh = (key) => {
@@ -78,10 +347,16 @@ export function fileStorage(path, opts = {}) {
         return e;
     };
     return {
+        close,
         async get(key) {
+            // Reads use the loaded snapshot; only writes need filesystem ownership
+            // checks to prevent a reclaimed holder from overwriting newer state.
+            assertOpen();
             return fresh(key)?.value ?? null;
         },
         async set(key, value, opts) {
+            assertOpen();
+            lock.assertHeld();
             data[key] = {
                 value,
                 ...(opts?.ttlSeconds
@@ -91,10 +366,13 @@ export function fileStorage(path, opts = {}) {
             persist();
         },
         async delete(key) {
+            assertOpen();
+            lock.assertHeld();
             delete data[key];
             persist();
         },
         async list(prefix) {
+            assertOpen();
             return Object.keys(data)
                 .filter((key) => Boolean(fresh(key)) && key.startsWith(prefix))
                 .sort();

package/dist/storage/memory.js

@@ -1,11 +1,12 @@
 /** In-memory KV store with expiry. The default for dev and Node. */
 export function memoryStorage() {
     const map = new Map();
+    let sweep = map.keys();
     const fresh = (key) => {
         const e = map.get(key);
         if (!e)
             return null;
-        if (e.exp && Date.now() > e.exp) {
+        if (e.exp !== undefined && Date.now() >= e.exp) {
             map.delete(key);
             return null;
         }
@@ -16,6 +17,16 @@ export function memoryStorage() {
             return fresh(key)?.value ?? null;
         },
         async set(key, value, opts) {
+            // Rotate through at most 16 existing keys. Live entries cannot keep an
+            // expired tail resident forever, and no request starts a background job.
+            for (let i = 0; i < 16; i++) {
+                const next = sweep.next();
+                if (next.done) {
+                    sweep = map.keys();
+                    break;
+                }
+                fresh(next.value);
+            }
             map.set(key, {
                 value,
                 ...(opts?.ttlSeconds

package/dist/types.d.ts

@@ -519,6 +519,43 @@ export interface ConnectaBranding {
     };
     /** `theme-color` meta value. Defaults to "#ffffff". */
     themeColor?: string;
+    /**
+     * Operator-page appearance. Every field is optional, and a rejected value
+     * takes its default rather than failing the page, so `createConnecta` warns
+     * at startup about anything it dropped.
+     *
+     * Five knobs, not a palette. Surfaces, borders, muted text, and the status
+     * colors all derive from these, so a deployment sets an accent and gets a
+     * readable page instead of thirty chances to break one.
+     */
+    theme?: ConnectaTheme;
+}
+/**
+ * The operator UI's themeable tokens. These land in a `:root` block on the
+ * page, so each is gated by a narrow syntactic check: an unvalidated value
+ * here would let deployment config write arbitrary CSS.
+ */
+export interface ConnectaTheme {
+    /**
+     * The brand color: links, focus rings, primary actions, the active nav item.
+     * Hex only (`#rgb`, `#rrggbb`, or `#rrggbbaa`). Defaults to `#2f5fe0`.
+     */
+    accent?: string;
+    /**
+     * Corner rounding for cards, inputs, and buttons. A CSS length (`10px`,
+     * `0.5rem`) or a bare number read as pixels. `0` restores square corners.
+     * Defaults to `10px`.
+     */
+    radius?: string | number;
+    /** Body font stack. A plain CSS font-family list. Defaults to a system stack. */
+    fontFamily?: string;
+    /** Monospace font stack for addresses, ids, and the endpoint URL. */
+    monoFamily?: string;
+    /**
+     * `"system"` (the default) follows the operator's OS setting; `"light"` and
+     * `"dark"` pin the page to one palette.
+     */
+    colorScheme?: "system" | "light" | "dark";
 }
 /** An inbound authentication provider (bearer token, interactive identity, ...). */
 export interface InboundAuth {

package/dist/ui.js

@@ -8,7 +8,7 @@ import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concu
 import { OPERATOR_UI_CSS, OPERATOR_UI_SCRIPT, } from "./operator-ui/generated.js";
 import { CONNECTA_VERSION } from "./version.js";
 export { filterUiConnectors, } from "./operator-ui/model.js";
-import { resolveBranding, isSafeHttpsUrl } from "./branding.js";
+import { resolveBranding, isSafeHttpsUrl, themeCss } from "./branding.js";
 export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
 /**
  * A JS string literal safe to inline in a script element. Escaping `/` keeps
@@ -281,8 +281,14 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
     const clerkScript = clerk && clerkScriptOrigin
         ? `<script${nonceAttr} crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
         : "";
+    // A pinned scheme is an attribute, not a stylesheet edit: the dark palette
+    // keys off `html[data-scheme]`, so "system" leaves the attribute off and the
+    // media query decides.
+    const schemeAttr = brand.theme.colorScheme === "system"
+        ? ""
+        : ` data-scheme="${brand.theme.colorScheme}"`;
     return `<!doctype html>
-<html lang="en">
+<html lang="en"${schemeAttr}>
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -292,22 +298,24 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
 <link rel="shortcut icon" href="/favicon.ico">
 <title>${escapeHtmlAttr(title)}</title>
 ${clerkScript}
-<style>${OPERATOR_UI_CSS}</style>
+<style>${OPERATOR_UI_CSS}${themeCss(brand.theme)}</style>
 </head>
 <body>
 <a class="skip-link" href="#operatorContent">Skip to operator page</a>
-<header class="masthead shell pgrid">
-  ${owner}
-  <div class="mast-nav">
-    ${product}
+<header class="masthead shell">
+  <div class="masthead-inner">
+    <div class="mast-nav">
+      ${owner}
+      ${product}
+    </div>
     <div id="operatorNav"></div>
   </div>
 </header>
 
 <main id="operatorContent" class="page shell" tabindex="-1">
-  <div class="lead pgrid">
-    <h1 class="pcap">${OPERATOR_PAGE_LABELS[page]}</h1>
-    <div class="pbody lead-copy">
+  <div class="lead">
+    <h1>${OPERATOR_PAGE_LABELS[page]}</h1>
+    <div class="lead-copy">
       <p>${escapeHtmlAttr(brand.description)}</p>
       <noscript><p class="msg">The operator pages need JavaScript. Nothing else here
       does — agents reach this deployment through <span class="mono">/mcp</span>.</p></noscript>