brains-mcp 1.61.2

package/dist/httpServer.js

@@ -0,0 +1,3913 @@
+import http from "http";
+import zlib from "zlib";
+import { randomUUID } from "crypto";
+import { promises as fs } from "fs";
+import path from "path";
+import { URL } from "url";
+import AdmZip from "adm-zip";
+import { z } from "zod";
+import { createScopedStorageClient, GrantAwareStorageClient } from "./storage/client.js";
+import { listActiveGrantsForGrantee } from "./access/projectShares.js";
+import { createBrainsServer, executeToolCall, getVisibleTools, ToolNotAvailableError } from "./server.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { OAuthManager } from "./auth/oauth.js";
+import { SupabaseAuthManager } from "./auth/supabase.js";
+import { createTokenStore } from "./auth/tokenStore.js";
+import { createClientStore } from "./auth/clientStore.js";
+import { createPATStore, PAT_EXPIRY_DAYS_DEFAULT, PAT_EXPIRY_DAYS_MAX } from "./auth/patStore.js";
+import { buildOpenApiSpec } from "./api/openapi.js";
+import { renderErrorBox, renderMetaRows, renderStatusBadge, renderWordmark } from "./html/components.js";
+import { renderPageShell } from "./html/layout.js";
+import { getPostgresSearchIndex } from "./search/postgresIndex.js";
+import { parseBundle } from "./session/bundle.js";
+import { parsePage } from "./wiki/frontmatter.js";
+import { pullSessionBundle } from "./tools/pullSessionBundle.js";
+import { pushSessionBundle } from "./tools/pushSessionBundle.js";
+import { buildExportZip } from "./tools/exportWiki.js";
+import { runImportFromBuffer, isValidWikiFilename, computeDiscoveredFolders, buildInstructionRefreshHint, } from "./tools/importWikiZip.js";
+import { purgeWiki } from "./tools/purgeWiki.js";
+import { AsyncJobRegistry } from "./jobs/asyncJobRegistry.js";
+import { appendLogEntry } from "./wiki/log.js";
+import { DriveNotFoundError } from "./drive/errors.js";
+import { StorageLimitError, PageLimitError, resolvePageLimitContext } from "./wiki/storageLimits.js";
+import { insertRequestEvent } from "./observability/requestEvents.js";
+import { queryMetrics, isValidWindow } from "./observability/metricsQuery.js";
+import { metricsUiHtml } from "./html/metricsUi.js";
+import { recordSearchLatency } from "./observability/slowQueryAlert.js";
+import { recordSearch, maybeRecordRelevanceSignal } from "./observability/relevanceSignal.js";
+import { startZeroResultTriageCron } from "./observability/zeroResultTriage.js";
+import { fetchTopQueries, setHotCached } from "./search/hotQueryCache.js";
+import { startDigestCron, runDigestForUser, } from "./digest/digestCron.js";
+import { getDigestPreference, upsertDigestPreference, updateDigestEnabled, } from "./digest/digestPreferences.js";
+import { DEFAULT_ACCESS_CONTEXT, getUserAccessLevel, isHiveModeEnabled, } from "./governance/accessControl.js";
+import { seedUsers, purgeSeedUsers, isSeedEnabled, isGodModeSubject } from "./admin/seedUsers.js";
+import { deleteAccount } from "./auth/deleteAccount.js";
+const MAX_BODY_BYTES = 1024 * 1024;
+const MAX_IMPORT_ZIP_UPLOAD_BYTES = 64 * 1024 * 1024;
+// ── Launch spot counter (GET /api/v1/launch/status) ────────────────────────
+// First-500 launch offer shown on the marketing pricing page. Counts total
+// registered users (Supabase auth.users when configured, else local users/
+// directories — same source priority as /admin/users) and caches the result
+// for 60s so the pricing page can poll without hammering Supabase auth-admin.
+const LAUNCH_SPOT_CAP = 500;
+const LAUNCH_STATUS_CACHE_TTL_MS = 60_000;
+let launchStatusCache = null;
+async function countRegisteredUsersForLaunch(drive) {
+    const supabaseUrl = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+    const serviceRoleKey = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+    if (supabaseUrl && serviceRoleKey) {
+        let total = 0;
+        let page = 1;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const url = `${supabaseUrl}/auth/v1/admin/users?page=${page}&per_page=1000`;
+            const ac = new AbortController();
+            const acTimer = setTimeout(() => ac.abort(), 15_000);
+            const authHeaderValue = ["Bearer", serviceRoleKey].join(" ");
+            const resp = await fetch(url, {
+                headers: { apikey: serviceRoleKey, authorization: authHeaderValue },
+                signal: ac.signal,
+            }).catch(() => null).finally(() => clearTimeout(acTimer));
+            if (!resp || !resp.ok)
+                break;
+            const body = await resp.json().catch(() => null);
+            const batch = body?.users ?? [];
+            total += batch.length;
+            if (batch.length < 1000)
+                break;
+            page++;
+        }
+        return total;
+    }
+    const usersBasePath = path.join(drive.getStorageLocation(), "users");
+    const userDirs = await fs.readdir(usersBasePath, { withFileTypes: true }).catch(() => []);
+    return userDirs.filter((d) => d.isDirectory()).length;
+}
+async function getLaunchStatus(drive) {
+    const now = Date.now();
+    if (!launchStatusCache || now - launchStatusCache.cachedAt >= LAUNCH_STATUS_CACHE_TTL_MS) {
+        const count = await countRegisteredUsersForLaunch(drive).catch(() => launchStatusCache?.count ?? 0);
+        launchStatusCache = { count, cachedAt: now };
+    }
+    const spotsRemaining = Math.max(0, LAUNCH_SPOT_CAP - launchStatusCache.count);
+    return { spotsRemaining, offerOpen: spotsRemaining > 0 };
+}
+// Test-only: clears the 60s in-memory cache so tests can assert fresh counts
+// without waiting out the TTL.
+export function resetLaunchStatusCacheForTests() {
+    launchStatusCache = null;
+}
+class BodyTooLargeError extends Error {
+    maxBytes;
+    constructor(maxBytes) {
+        super(`Request body too large (max ${maxBytes} bytes)`);
+        this.maxBytes = maxBytes;
+        this.name = "BodyTooLargeError";
+    }
+}
+// ── MCP session helpers ───────────────────────────────────────────────────
+/**
+ * Primes a freshly created StreamableHTTPServerTransport with a synthetic
+ * `initialize` request so the transport's `_initialized` flag and `sessionId`
+ * are set before we dispatch the client's actual non-initialize message.
+ *
+ * This is the server-side half of the "transparent reconnect" strategy: when a
+ * client sends a request with a stale Mcp-Session-Id (e.g. after a redeploy),
+ * we create a new transport, call this function, then handle the original
+ * request as if the session had never been lost.  The client never receives a
+ * -32000 error and therefore never discards its OAuth tokens.
+ *
+ * Implementation note: this function accesses the Node.js transport wrapper's
+ * PRIVATE `_webStandardTransport` field via a type-cast.  `_webStandardTransport`
+ * is intentionally a private SDK internal; it may be renamed or removed in future
+ * SDK versions.  A runtime guard detects this and returns `false` so the caller
+ * can safely fall back to returning -32000.  The `parsedBody` option passed to
+ * `handleRequest` is part of the SDK's public API surface (documented in
+ * `WebStandardStreamableHTTPServerTransportOptions`) and is stable.
+ *
+ * @returns `true` if the synthetic init succeeded, `false` if the private field
+ *   was absent (SDK structural change) — in which case the caller must NOT
+ *   register or use the transport.
+ */
+async function syntheticMcpInit(transport) {
+    const initBody = {
+        jsonrpc: "2.0",
+        id: 0,
+        method: "initialize",
+        params: {
+            protocolVersion: "2025-03-26",
+            capabilities: {},
+            clientInfo: { name: "brains-reconnect", version: "1.0" },
+        },
+    };
+    // Access the inner web-standard transport via its private field.  A runtime
+    // guard detects SDK structural changes.  Callers MUST check the return value
+    // and abort if it is `false` to avoid registering an uninitialized transport.
+    const inner = transport._webStandardTransport;
+    if (!inner) {
+        console.error("[brains] syntheticMcpInit: _webStandardTransport field not found — SDK structure changed?");
+        return false;
+    }
+    const syntheticReq = new Request("http://localhost/mcp", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "Accept": "application/json, text/event-stream" },
+    });
+    const resp = await inner.handleRequest(syntheticReq, { parsedBody: initBody });
+    // Cancel the SSE/JSON response body so the ReadableStream can be GC'd.
+    resp.body?.cancel().catch(() => { });
+    return true;
+}
+// ── Response compression ──────────────────────────────────────────────────
+const COMPRESSION_MIN_BYTES = 1024;
+const SKIP_COMPRESSION_RE = /^(image\/|video\/|audio\/|font\/|application\/zip|application\/gzip|application\/x-br)/;
+function selectEncoding(acceptEncoding) {
+    const ae = Array.isArray(acceptEncoding) ? acceptEncoding.join(",") : (acceptEncoding ?? "");
+    // Parse Accept-Encoding tokens per RFC 9110 §12.5.3: split on commas,
+    // strip optional quality values (;q=...) and whitespace, then exact-match.
+    const tokens = ae.split(",").map((t) => t.split(";")[0].trim().toLowerCase());
+    if (tokens.includes("br"))
+        return "br";
+    if (tokens.includes("gzip"))
+        return "gzip";
+    return null;
+}
+function compressIfNeeded(req, contentType, buf) {
+    if (!req || buf.length < COMPRESSION_MIN_BYTES)
+        return { buf, encoding: null };
+    if (SKIP_COMPRESSION_RE.test(contentType))
+        return { buf, encoding: null };
+    const encoding = selectEncoding(req.headers["accept-encoding"]);
+    if (!encoding)
+        return { buf, encoding: null };
+    const compressed = encoding === "br"
+        ? zlib.brotliCompressSync(buf, { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 4 } })
+        : zlib.gzipSync(buf);
+    return { buf: compressed, encoding };
+}
+function classifyRouteForRateLimit(method, pathname) {
+    if (method === "GET" && pathname === "/api/v1/search")
+        return "search";
+    if (method === "GET" &&
+        (pathname === "/api/v1/page" || pathname === "/api/v1/pages" || pathname.endsWith("/backlinks") || pathname.endsWith("/related") || pathname.endsWith("/history"))) {
+        return "reads";
+    }
+    if (method === "POST" && (pathname === "/api/v1/pages/batch" || pathname === "/api/v1/import" || pathname === "/api/v1/links/extract" || pathname === "/api/v1/links/suggest" || pathname === "/api/v1/pages/delete-batch"))
+        return "batch";
+    if (method === "POST" && pathname === "/chat")
+        return "chat";
+    if (method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE")
+        return "writes";
+    return null;
+}
+function checkRateLimit(windows, key, limit, windowMs) {
+    // Returns null when the request is allowed.
+    // Returns the remaining milliseconds until the oldest timestamp exits the
+    // window (i.e. the earliest the client may retry) when the limit is exceeded.
+    const now = Date.now();
+    const cutoff = now - windowMs;
+    const timestamps = windows.get(key) ?? [];
+    const pruned = timestamps.filter((t) => t > cutoff);
+    if (pruned.length >= limit) {
+        windows.set(key, pruned);
+        // pruned is sorted ascending (timestamps are appended in arrival order).
+        // The oldest entry is pruned[0]; when it falls out of the window the
+        // client earns one new slot.
+        const oldest = pruned[0];
+        return oldest + windowMs - now;
+    }
+    pruned.push(now);
+    windows.set(key, pruned);
+    return null;
+}
+// ── Timeout race helper ───────────────────────────────────────────────────
+const TIMEOUT_SENTINEL = Symbol("timeout");
+function raceWithTimeout(promise, ms) {
+    let timer;
+    const timeoutPromise = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(TIMEOUT_SENTINEL), ms);
+    });
+    return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timer));
+}
+function emitRequestLog(method, reqPath, status, durationMs, extras = {}) {
+    const logFormat = (process.env.LOG_FORMAT ?? "").toLowerCase();
+    if (logFormat === "json") {
+        const entry = { ts: new Date().toISOString(), method, path: reqPath, status, durationMs };
+        if (extras.backend !== undefined)
+            entry["backend"] = extras.backend;
+        if (extras.queryMs !== undefined)
+            entry["queryMs"] = extras.queryMs;
+        if (extras.resultCount !== undefined)
+            entry["resultCount"] = extras.resultCount;
+        if (extras.queryText !== undefined)
+            entry["queryText"] = extras.queryText;
+        if (extras.zeroResults)
+            entry["zero-results"] = true;
+        console.log(JSON.stringify(entry));
+    }
+    else {
+        let line = `[req] ${method} ${reqPath} ${status} ${durationMs}ms`;
+        if (extras.backend !== undefined)
+            line += ` backend=${extras.backend}`;
+        if (extras.queryMs !== undefined)
+            line += ` queryMs=${extras.queryMs}`;
+        if (extras.resultCount !== undefined)
+            line += ` resultCount=${extras.resultCount}`;
+        if (extras.queryText !== undefined)
+            line += ` query=${JSON.stringify(extras.queryText)}`;
+        if (extras.zeroResults)
+            line += ` zero-results=true`;
+        console.log(line);
+    }
+}
+function json(req, res, statusCode, payload, extraHeaders) {
+    const bodyStr = JSON.stringify(payload);
+    const bodyBuf = Buffer.from(bodyStr, "utf8");
+    const { buf: outBuf, encoding } = compressIfNeeded(req, "application/json", bodyBuf);
+    const headers = {
+        "content-type": "application/json; charset=utf-8",
+        "content-length": outBuf.length.toString(),
+        "cache-control": "no-store",
+        ...extraHeaders,
+    };
+    if (encoding) {
+        headers["content-encoding"] = encoding;
+        headers["vary"] = "Accept-Encoding";
+    }
+    res.writeHead(statusCode, headers);
+    res.end(outBuf);
+}
+function parseBearerToken(req) {
+    const auth = req.headers.authorization ?? "";
+    if (!auth.startsWith("Bearer "))
+        return null;
+    return auth.slice(7);
+}
+function parseBasicClientCredentials(req) {
+    const auth = req.headers.authorization ?? "";
+    if (!auth.startsWith("Basic "))
+        return null;
+    try {
+        const decoded = Buffer.from(auth.slice(6), "base64").toString("utf8");
+        const split = decoded.indexOf(":");
+        if (split <= 0)
+            return null;
+        return {
+            clientId: decoded.slice(0, split),
+            clientSecret: decoded.slice(split + 1),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isApiKeyAuthorized(req) {
+    const apiKey = process.env.BRAINS_API_KEY;
+    if (!apiKey)
+        return true;
+    const bearer = parseBearerToken(req);
+    if (bearer && bearer === apiKey)
+        return true;
+    const headerKey = req.headers["x-api-key"];
+    if (typeof headerKey === "string" && headerKey === apiKey)
+        return true;
+    return false;
+}
+function isConnectorKeyAuthorized(parsedUrl) {
+    const connectorKey = process.env.BRAINS_CONNECTOR_KEY;
+    if (!connectorKey)
+        return false;
+    const providedKey = parsedUrl.searchParams.get("connector_key");
+    if (!providedKey)
+        return false;
+    return providedKey === connectorKey;
+}
+function isPublicRoute(method, pathname) {
+    return ((method === "GET" && pathname === "/") ||
+        (method === "GET" && pathname === "/cb") ||
+        (method === "GET" && pathname === "/chat-ui") ||
+        (method === "GET" && pathname === "/connect") ||
+        (method === "POST" && pathname === "/api/inbound-email") ||
+        (method === "GET" && pathname.startsWith("/assets/css/")) ||
+        (method === "GET" && pathname.startsWith("/assets/img/")) ||
+        (method === "GET" && pathname === "/openapi.json") ||
+        (method === "GET" && pathname === "/.well-known/openapi.json") ||
+        (method === "GET" && pathname === "/api/v1") ||
+        (method === "GET" && pathname === "/.well-known/oauth-authorization-server") ||
+        (method === "GET" && pathname === "/.well-known/oauth-protected-resource") ||
+        pathname === "/oauth/authorize" ||
+        pathname === "/oauth/token" ||
+        pathname === "/oauth/register" ||
+        pathname === "/oauth/signup" ||
+        pathname === "/oauth/revoke" ||
+        (method === "GET" && pathname === "/healthz") ||
+        (method === "GET" && pathname === "/api/v1/health") ||
+        (method === "GET" && pathname === "/api/v1/launch/status"));
+}
+function html(req, res, statusCode, body) {
+    const bodyBuf = Buffer.from(body, "utf8");
+    const { buf: outBuf, encoding } = compressIfNeeded(req, "text/html", bodyBuf);
+    const headers = {
+        "content-type": "text/html; charset=utf-8",
+        "content-length": outBuf.length.toString(),
+        "cache-control": "no-store",
+    };
+    if (encoding) {
+        headers["content-encoding"] = encoding;
+        headers["vary"] = "Accept-Encoding";
+    }
+    res.writeHead(statusCode, headers);
+    res.end(outBuf);
+}
+const CSS_ASSET_PREFIX = "/assets/css/";
+const CSS_ROOT = path.resolve(process.cwd(), "src/styles");
+const IMG_ASSET_PREFIX = "/assets/img/";
+const IMG_ROOT = path.resolve(process.cwd(), "src/assets/img");
+async function imgAsset(res, pathname) {
+    const relativePath = decodeURIComponent(pathname.slice(IMG_ASSET_PREFIX.length));
+    if (!relativePath) {
+        json(null, res, 404, { ok: false, error: "Not found" });
+        return;
+    }
+    const resolved = path.resolve(IMG_ROOT, relativePath);
+    if (resolved === IMG_ROOT || !resolved.startsWith(`${IMG_ROOT}${path.sep}`)) {
+        json(null, res, 404, { ok: false, error: "Not found" });
+        return;
+    }
+    try {
+        const buf = await fs.readFile(resolved);
+        const ext = path.extname(resolved).toLowerCase();
+        const ct = ext === ".svg" ? "image/svg+xml" : ext === ".png" ? "image/png" : "application/octet-stream";
+        res.writeHead(200, { "content-type": ct, "content-length": buf.length.toString(), "cache-control": "public, max-age=300" });
+        res.end(buf);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            json(null, res, 404, { ok: false, error: "Not found" });
+            return;
+        }
+        throw err;
+    }
+}
+function resolveCssFilePath(pathname) {
+    if (!pathname.startsWith(CSS_ASSET_PREFIX))
+        return null;
+    const relativePath = decodeURIComponent(pathname.slice(CSS_ASSET_PREFIX.length));
+    if (!relativePath || !relativePath.endsWith(".css"))
+        return null;
+    const resolved = path.resolve(CSS_ROOT, relativePath);
+    if (resolved === CSS_ROOT)
+        return null;
+    if (!resolved.startsWith(`${CSS_ROOT}${path.sep}`))
+        return null;
+    return resolved;
+}
+async function cssAsset(res, pathname) {
+    const filePath = resolveCssFilePath(pathname);
+    if (!filePath) {
+        json(null, res, 404, { ok: false, error: "Not found" });
+        return;
+    }
+    try {
+        const body = await fs.readFile(filePath, "utf8");
+        res.writeHead(200, {
+            "content-type": "text/css; charset=utf-8",
+            "content-length": Buffer.byteLength(body).toString(),
+            "cache-control": "public, max-age=300",
+        });
+        res.end(body);
+        return;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            json(null, res, 404, { ok: false, error: "Not found" });
+            return;
+        }
+        throw err;
+    }
+}
+// ── Editor SPA static asset serving ──────────────────────────────────────
+const EDITOR_DIST = path.resolve(process.cwd(), "dist/editor");
+const EDITOR_PREFIX = "/editor";
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".ttf": "font/ttf",
+    ".json": "application/json; charset=utf-8",
+};
+async function serveEditorAsset(res, assetPath) {
+    const ext = path.extname(assetPath).toLowerCase();
+    const contentType = MIME[ext] ?? "application/octet-stream";
+    const isHtml = contentType.startsWith("text/html");
+    const cacheControl = isHtml ? "no-store" : "public, max-age=31536000, immutable";
+    try {
+        const buf = await fs.readFile(assetPath);
+        res.writeHead(200, {
+            "content-type": contentType,
+            "content-length": buf.length.toString(),
+            "cache-control": cacheControl,
+        });
+        res.end(buf);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR") {
+            // SPA fallback: serve index.html for any unmatched path under /editor
+            try {
+                const indexBuf = await fs.readFile(path.join(EDITOR_DIST, "index.html"));
+                res.writeHead(200, {
+                    "content-type": "text/html; charset=utf-8",
+                    "content-length": indexBuf.length.toString(),
+                    "cache-control": "no-store",
+                });
+                res.end(indexBuf);
+            }
+            catch {
+                res.writeHead(404, { "content-type": "text/plain" });
+                res.end("Editor frontend moved to apps/web (/notes route)");
+            }
+            return;
+        }
+        throw err;
+    }
+}
+async function readBodyBuffer(req, maxBytes = MAX_BODY_BYTES) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buf.length;
+        if (bytes > maxBytes) {
+            throw new BodyTooLargeError(maxBytes);
+        }
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks);
+}
+async function readBody(req, maxBytes = MAX_BODY_BYTES) {
+    return (await readBodyBuffer(req, maxBytes)).toString("utf8");
+}
+async function scanImportDiffFromBuffer(drive, buffer, opts) {
+    const zip = new AdmZip(buffer);
+    const entries = zip.getEntries().filter((e) => !e.isDirectory);
+    const diff = [];
+    let newCount = 0;
+    let modifiedCount = 0;
+    let unchangedCount = 0;
+    let skippedCount = 0;
+    let deletedCount = 0;
+    const systemFiles = new Set(["index.md", "log.md"]);
+    const zipNames = new Set();
+    const effectiveConflictStrategy = opts.mode === "replace" ? "overwrite" : opts.conflictStrategy;
+    let scanProcessed = 0;
+    for (const entry of entries) {
+        const name = entry.entryName.replace(/\\/g, "/");
+        if (name === "export-index.json")
+            continue;
+        try {
+            // Reject path-traversal and absolute-path entries before any filesystem access.
+            if (name.startsWith("/") || name.split("/").some((segment) => segment === "..")) {
+                diff.push({ name, status: "skipped" });
+                skippedCount++;
+                continue;
+            }
+            if (!opts.includeSystem && systemFiles.has(name)) {
+                diff.push({ name, status: "skipped" });
+                skippedCount++;
+                continue;
+            }
+            if (!isValidWikiFilename(name)) {
+                diff.push({ name, status: "skipped" });
+                skippedCount++;
+                continue;
+            }
+            zipNames.add(name);
+            const incomingContent = entry.getData().toString("utf8");
+            const existing = await drive
+                .readFile(name)
+                .catch((err) => (err instanceof DriveNotFoundError ? null : Promise.reject(err)));
+            if (!existing) {
+                diff.push({ name, status: "new" });
+                newCount++;
+                continue;
+            }
+            if (existing.content === incomingContent) {
+                diff.push({ name, status: "unchanged" });
+                unchangedCount++;
+                continue;
+            }
+            if (effectiveConflictStrategy === "skip") {
+                diff.push({ name, status: "skipped" });
+                skippedCount++;
+                continue;
+            }
+            diff.push({ name, status: "modified" });
+            modifiedCount++;
+        }
+        finally {
+            opts.onProgress?.(++scanProcessed, entries.length);
+        }
+    }
+    if (opts.mode === "replace") {
+        const existingFiles = await drive.listFiles();
+        for (const existing of existingFiles) {
+            const name = existing.name.replace(/\\/g, "/");
+            if (!opts.includeSystem && systemFiles.has(name)) {
+                continue;
+            }
+            if (!zipNames.has(name)) {
+                diff.push({ name, status: "deleted" });
+                deletedCount++;
+            }
+        }
+    }
+    return { totalEntries: entries.length, newCount, modifiedCount, unchangedCount, skippedCount, deletedCount, diff };
+}
+async function readJsonBody(req) {
+    const raw = (await readBody(req)).trim();
+    if (!raw)
+        return {};
+    return JSON.parse(raw);
+}
+async function readFormBody(req) {
+    const raw = (await readBody(req)).trim();
+    const params = new URLSearchParams(raw);
+    const output = {};
+    for (const [key, value] of params.entries()) {
+        output[key] = value;
+    }
+    return output;
+}
+const toolCallSchema = z.object({
+    name: z.string().min(1),
+    arguments: z.unknown().optional(),
+});
+const chatMessageSchema = z.object({
+    role: z.enum(["user", "assistant"]),
+    content: z.string(),
+});
+const chatRequestSchema = z.object({
+    apiKey: z.string().min(20),
+    model: z.string().optional(),
+    maxTokens: z.number().int().min(256).max(8192).optional(),
+    message: z.string().optional(),
+    messages: z.array(chatMessageSchema).optional(),
+});
+const createPageHttpSchema = z.object({
+    name: z.string().min(1),
+    title: z.string().min(1),
+    body: z.string(),
+    tags: z.array(z.string()).optional(),
+    summary: z.string().optional(),
+});
+const createPagesHttpSchema = z.object({
+    pages: z.array(createPageHttpSchema).min(1).max(20),
+    verbose: z.boolean().optional(),
+    runLabel: z.string().optional(),
+    logTiming: z.boolean().optional(),
+});
+const updatePageHttpSchema = z.object({
+    name: z.string().min(1),
+    fileId: z.string().min(1),
+    revision: z.string().min(1),
+    body: z.string(),
+    frontmatterPatch: z.record(z.unknown()).optional(),
+    summary: z.string().optional(),
+});
+const patchPageHttpSchema = z.object({
+    name: z.string().min(1),
+    operations: z.array(z.record(z.unknown())).min(1).max(20),
+    lineNumbersAre: z.string().optional(),
+    summary: z.string().optional(),
+});
+const movePageHttpSchema = z.object({
+    name: z.string().min(1),
+    action: z.enum(["archive", "rename"]),
+    newName: z.string().optional(),
+});
+const appendLogHttpSchema = z.object({
+    type: z.enum(["ingest", "query", "update", "create", "move", "lint", "error"]),
+    title: z.string().min(1),
+    detail: z.string().optional(),
+});
+const auditIndexHttpSchema = z.object({
+    cleanup: z.boolean().optional(),
+});
+const extractLinksHttpSchema = z.object({
+    tags: z.array(z.string()).optional(),
+    folder: z.string().optional(),
+    userId: z.string().optional(),
+});
+const suggestLinksHttpSchema = z.object({
+    tags: z.array(z.string()).optional(),
+    folder: z.string().optional(),
+    maxPages: z.number().int().min(1).max(50).optional(),
+});
+const importBrainSourceHttpSchema = z.object({
+    sourceRoot: z.string().min(1),
+    execute: z.boolean().optional(),
+    maxFiles: z.number().int().min(1).max(5000).optional(),
+    skipRawCatalogs: z.boolean().optional(),
+    excludeDirs: z.array(z.string()).optional(),
+    chunkSize: z.number().int().min(1).max(20).optional(),
+    runLabel: z.string().optional(),
+    logTiming: z.boolean().optional(),
+    previewLimit: z.number().int().min(1).max(200).optional(),
+});
+const exportWikiHttpSchema = z.object({
+    outputPath: z.string().min(1),
+    includeSystem: z.boolean().optional(),
+    folder: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+});
+const importWikiZipHttpSchema = z.object({
+    zipPath: z.string().min(1),
+    execute: z.boolean().optional(),
+    conflictStrategy: z.enum(["skip", "overwrite", "merge"]).optional(),
+    includeSystem: z.boolean().optional(),
+    logTiming: z.boolean().optional(),
+});
+const purgeWikiHttpSchema = z.object({
+    confirm: z.boolean().optional(),
+    exportBeforeDelete: z.boolean().optional(),
+    exportOutputPath: z.string().optional(),
+    includeSystem: z.boolean().optional(),
+});
+const toolInvokeHttpSchema = z.object({
+    arguments: z.unknown().optional(),
+});
+// Form POST always sends empty strings for unset hidden fields; coerce them to undefined.
+const emptyToUndefined = (v) => (v === "" ? undefined : v);
+const oauthAuthorizeQuerySchema = z.object({
+    response_type: z.literal("code"),
+    client_id: z.string().min(1),
+    redirect_uri: z.string().url(),
+    scope: z.preprocess(emptyToUndefined, z.string().optional()),
+    state: z.preprocess(emptyToUndefined, z.string().optional()),
+    code_challenge: z.preprocess(emptyToUndefined, z.string().optional()),
+    code_challenge_method: z.preprocess(emptyToUndefined, z.enum(["S256", "plain"]).optional()),
+});
+const oauthAuthorizeFormSchema = oauthAuthorizeQuerySchema.extend({
+    username: z.string().min(1),
+    password: z.string().min(1),
+});
+const oauthSignupFormSchema = oauthAuthorizeQuerySchema.extend({
+    email: z.string().email(),
+    password: z.string().min(8),
+    confirm_password: z.string().min(1),
+});
+const oauthTokenFormSchema = z.object({
+    grant_type: z.enum(["authorization_code", "refresh_token"]),
+    code: z.string().optional(),
+    redirect_uri: z.string().url().optional(),
+    client_id: z.string().optional(),
+    client_secret: z.string().optional(),
+    code_verifier: z.string().optional(),
+    refresh_token: z.string().optional(),
+});
+const oauthRevokeFormSchema = z.object({
+    token: z.string().min(1),
+    token_type_hint: z.enum(["access_token", "refresh_token"]).optional(),
+    client_id: z.string().optional(),
+    client_secret: z.string().optional(),
+});
+const createPATHttpSchema = z.object({
+    label: z.string().min(1).max(255),
+    scopes: z.array(z.enum(["wiki.read", "wiki.write"])).optional(),
+    // null = never expires; omit to use default (30 days)
+    expiresInDays: z.number().int().min(1).max(PAT_EXPIRY_DAYS_MAX).nullable().optional(),
+});
+function chatUiHtml() {
+    const body = `<main class="app-shell chat-wrap">
+  ${renderWordmark("Chat with Claude + MCP tools using your brains server.")}
+  <section class="panel card">
+    <h1 class="page-title">brains Chat</h1>
+    <form class="chat-form" onsubmit="return false;">
+      <div class="form-row">
+        <label for="brainsKey">Brains API Key (BRAINS_API_KEY)</label>
+        <input class="input" id="brainsKey" type="password" placeholder="Optional if server has no BRAINS_API_KEY" />
+      </div>
+      <div class="form-row">
+        <label for="claudeKey">Claude API Key (Anthropic)</label>
+        <input class="input" id="claudeKey" type="password" placeholder="sk-ant-..." />
+      </div>
+      <div class="form-row">
+        <label for="model">Model</label>
+        <input class="input" id="model" value="claude-3-7-sonnet-latest" />
+      </div>
+      <div class="form-row">
+        <label for="message">Message</label>
+        <textarea class="textarea" id="message" placeholder="Ask about your brain, then tools will be called automatically."></textarea>
+      </div>
+      <button class="btn btn--block" id="send" type="button">Send</button>
+    </form>
+    <div class="log" id="log"></div>
+  </section>
+
+  <script>
+    const log = document.getElementById("log");
+    const send = document.getElementById("send");
+    const brainsKey = document.getElementById("brainsKey");
+    const claudeKey = document.getElementById("claudeKey");
+    const model = document.getElementById("model");
+    const message = document.getElementById("message");
+
+    let history = [];
+
+    function push(role, text, cls = "") {
+      const div = document.createElement("div");
+      div.className = "msg " + role + (cls ? (" " + cls) : "");
+      div.textContent = (role === "user" ? "You: " : "Claude: ") + text;
+      log.appendChild(div);
+      log.scrollTop = log.scrollHeight;
+    }
+
+    send.addEventListener("click", async () => {
+      const userText = message.value.trim();
+      if (!userText) return;
+      if (!claudeKey.value.trim()) {
+        push("assistant", "Claude API key is required.", "error");
+        return;
+      }
+
+      push("user", userText);
+      history.push({ role: "user", content: userText });
+      message.value = "";
+
+      try {
+        const headers = { "content-type": "application/json" };
+        if (brainsKey.value.trim()) headers["x-api-key"] = brainsKey.value.trim();
+
+        const res = await fetch("/chat", {
+          method: "POST",
+          headers,
+          body: JSON.stringify({
+            apiKey: claudeKey.value.trim(),
+            model: model.value.trim(),
+            messages: history,
+          }),
+        });
+
+        const data = await res.json();
+        if (!res.ok || !data.ok) {
+          push("assistant", data.error || "Request failed", "error");
+          return;
+        }
+
+        history = data.messages || history;
+        push("assistant", data.assistant || "(No text returned)");
+      } catch (err) {
+        push("assistant", String(err), "error");
+      }
+    });
+  </script>
+</main>`;
+    return renderPageShell({
+        title: "brains Chat",
+        body,
+        bodyClass: "chat-page",
+        cssPaths: ["/assets/css/pages/chat.css"],
+    });
+}
+function hasRequiredScopes(ownedScopes, requiredScopes) {
+    return requiredScopes.every((scope) => ownedScopes.includes(scope));
+}
+function unauthorized(res, resourceMetadataUrl) {
+    const wwwAuth = resourceMetadataUrl
+        ? `Bearer resource_metadata="${resourceMetadataUrl}"`
+        : "Bearer";
+    res.setHeader("WWW-Authenticate", wwwAuth);
+    json(null, res, 401, {
+        ok: false,
+        error: "Unauthorized",
+        detail: "Use a valid bearer token (Supabase/OAuth), x-api-key, or connector_key query parameter",
+    });
+}
+function forbidden(res, requiredScopes) {
+    json(null, res, 403, {
+        ok: false,
+        error: "Forbidden",
+        detail: `Missing required scopes: ${requiredScopes.join(", ")}`,
+    });
+}
+function authorizeRequest(req, parsedUrl, oauth, supabaseAuth, patStore) {
+    if (isConnectorKeyAuthorized(parsedUrl)) {
+        return Promise.resolve({
+            scopes: ["wiki.read", "wiki.write"],
+            subject: "connector-key",
+            mode: "connector-key",
+        });
+    }
+    if (isApiKeyAuthorized(req)) {
+        return Promise.resolve({
+            scopes: ["wiki.read", "wiki.write"],
+            subject: "api-key",
+            mode: "api-key",
+        });
+    }
+    const bearer = parseBearerToken(req);
+    if (!bearer)
+        return Promise.resolve(null);
+    return (async () => {
+        // PAT lookup first. NOTE: this is only a local DB check when Supabase is
+        // unconfigured — production selects PostgresPATStore, where find() is an
+        // HTTP round trip. It is cached (60s, invalidated on revoke) precisely
+        // because it lands on every authenticated request, and because PATs are
+        // indistinguishable from OAuth tokens so this runs even for OAuth callers
+        // that will always miss (GH #427).
+        const pat = await patStore.find(bearer);
+        if (pat) {
+            return {
+                scopes: pat.scopes,
+                subject: pat.subject,
+                mode: "pat",
+            };
+        }
+        const supabase = await supabaseAuth.authenticateAccessToken(bearer);
+        if (supabase) {
+            return {
+                scopes: supabase.scopes,
+                subject: supabase.subject,
+                mode: "supabase",
+            };
+        }
+        const access = await oauth.authenticateAccessToken(bearer);
+        if (!access)
+            return null;
+        return {
+            scopes: access.scopes,
+            subject: access.subject,
+            mode: "oauth",
+        };
+    })();
+}
+/**
+ * Normalizes an OAuth/Supabase user subject (UUID or email) into a
+ * filesystem/object-storage safe path segment: lowercase, chars outside
+ * [a-z0-9._-] replaced with underscore, leading/trailing underscores
+ * stripped, capped at 96 characters.
+ *
+ * This value becomes the second path segment: `users/<subjectKey>/…`.
+ * The output must be stable across calls for the same subject because it
+ * is used as the durable user-scope prefix in storage.
+ *
+ * Exported for unit testing only — call sites outside this module should
+ * not depend on the sanitization details.
+ */
+export function sanitizeSubjectForPath(subject) {
+    const trimmed = subject.trim().toLowerCase();
+    const normalized = trimmed.replace(/[^a-z0-9._-]/g, "_").replace(/^_+|_+$/g, "");
+    return normalized.slice(0, 96) || "user";
+}
+/**
+ * Returns true only for auth modes that carry a stable per-user identity
+ * (`oauth` and `supabase`).  API-key and connector-key requests are
+ * intentionally routed to the shared/global storage root because those
+ * credentials are workspace-wide, not user-specific.
+ *
+ * DO NOT add `api-key` or `connector-key` here without a corresponding
+ * key-management model that maps keys to owner identities.
+ */
+function shouldUseUserScopedStorage(mode) {
+    return mode === "oauth" || mode === "supabase" || mode === "pat";
+}
+function oauthAuthorizeFormHtml(params) {
+    const activeTab = params.tab ?? "signin";
+    const hiddenOAuthFields = `
+    <input type="hidden" name="response_type" value="code" />
+    <input type="hidden" name="client_id" value="${escapeHtml(params.clientId)}" />
+    <input type="hidden" name="redirect_uri" value="${escapeHtml(params.redirectUri)}" />
+    <input type="hidden" name="scope" value="${escapeHtml(params.scope)}" />
+    <input type="hidden" name="state" value="${escapeHtml(params.state)}" />
+    <input type="hidden" name="code_challenge" value="${escapeHtml(params.codeChallenge)}" />
+    <input type="hidden" name="code_challenge_method" value="${escapeHtml(params.codeChallengeMethod)}" />`;
+    const errorHtml = renderErrorBox(params.error ? escapeHtml(params.error) : undefined);
+    const body = `<main class="app-shell auth-wrap">
+  ${renderWordmark()}
+  <h1 class="auth-headline">Turn on your brain</h1>
+  <section class="panel auth-panel">
+
+    <div class="tabs">
+      <button type="button" class="tab${activeTab === "signin" ? " active" : ""}" data-tab="signin">Sign in</button>
+      <button type="button" class="tab${activeTab === "signup" ? " active" : ""}" data-tab="signup">Create account</button>
+    </div>
+
+    <div id="panel-signin" class="panel-block${activeTab === "signin" ? " active" : ""}">
+      <form method="post" action="/oauth/authorize">
+        ${hiddenOAuthFields}
+        ${activeTab === "signin" ? errorHtml : ""}
+        <div class="form-row">
+          <label>Email</label>
+          <input class="input" name="username" type="email" autocomplete="email" required />
+        </div>
+
+        <div class="form-row">
+          <label>Password</label>
+          <input class="input" name="password" type="password" autocomplete="current-password" required />
+        </div>
+
+        <div class="form-row">
+          <button class="btn btn--block" type="submit">Authorize</button>
+        </div>
+      </form>
+    </div>
+
+    <div id="panel-signup" class="panel-block${activeTab === "signup" ? " active" : ""}">
+      <form method="post" action="/oauth/signup" id="signup-form">
+        ${hiddenOAuthFields}
+        ${activeTab === "signup" ? errorHtml : ""}
+        <p class="auth-platforms-note">Works with your favourite AI assistant:</p>
+        <div class="auth-platforms">
+          <span class="auth-platform-pill">✦ ChatGPT</span>
+          <span class="auth-platform-pill">◆ Claude</span>
+          <span class="auth-platform-pill">⬡ Copilot</span>
+          <span class="auth-platform-pill auth-platform-pill--soon">✶ Gemini (soon)</span>
+        </div>
+        <div class="form-row">
+          <label>Email</label>
+          <input class="input" name="email" type="email" autocomplete="email" required />
+        </div>
+
+        <div class="form-row">
+          <label>Password</label>
+          <input class="input" name="password" id="su-password" type="password" autocomplete="new-password" minlength="8" required />
+          <div class="hint">At least 8 characters.</div>
+          <div id="pw-length-error" class="inline-error">Password must be at least 8 characters.</div>
+        </div>
+
+        <div class="form-row">
+          <label>Confirm password</label>
+          <input class="input" name="confirm_password" id="su-confirm" type="password" autocomplete="new-password" required />
+          <div id="pw-match-error" class="inline-error">Passwords do not match.</div>
+        </div>
+
+        <div class="form-row">
+          <button class="btn btn--block" type="submit">Create account</button>
+        </div>
+      </form>
+    </div>
+
+    ${renderMetaRows([
+        { label: "Client", value: escapeHtml(params.clientId) },
+        { label: "Scopes", value: escapeHtml(params.scope) },
+    ])}
+  </section>
+
+  <script>
+    document.querySelectorAll(".tab").forEach(function(btn) {
+      btn.addEventListener("click", function() {
+        var target = btn.getAttribute("data-tab");
+        document.querySelectorAll(".tab").forEach(function(t) { t.classList.remove("active"); });
+        document.querySelectorAll(".panel-block").forEach(function(p) { p.classList.remove("active"); });
+        btn.classList.add("active");
+        document.getElementById("panel-" + target).classList.add("active");
+      });
+    });
+
+    var form = document.getElementById("signup-form");
+    var pwInput = document.getElementById("su-password");
+    var confirmInput = document.getElementById("su-confirm");
+    var pwLenErr = document.getElementById("pw-length-error");
+    var pwMatchErr = document.getElementById("pw-match-error");
+
+    form.addEventListener("submit", function(e) {
+      var ok = true;
+      if (pwInput.value.length < 8) {
+        pwLenErr.style.display = "block";
+        ok = false;
+      } else {
+        pwLenErr.style.display = "none";
+      }
+      if (pwInput.value !== confirmInput.value) {
+        pwMatchErr.style.display = "block";
+        ok = false;
+      } else {
+        pwMatchErr.style.display = "none";
+      }
+      if (!ok) e.preventDefault();
+    });
+  </script>
+</main>`;
+    return renderPageShell({
+        title: "brains OAuth Consent",
+        body,
+        bodyClass: "auth-page",
+        cssPaths: ["/assets/css/pages/auth.css"],
+    });
+}
+function signupConfirmHtml(params) {
+    const body = `<main class="app-shell auth-wrap">
+  ${renderWordmark()}
+  <h1 class="auth-headline">Check your email</h1>
+  <section class="panel auth-panel">
+    <p>We sent a confirmation link to <strong>${escapeHtml(params.email)}</strong>.<br />Click the link in the email to activate your account, then come back here to sign in.</p>
+    <div class="form-row">
+      <a class="btn" href="${escapeHtml(params.backPath)}">Back to sign in</a>
+    </div>
+  </section>
+</main>`;
+    return renderPageShell({
+        title: "Check your email - brains",
+        body,
+        bodyClass: "auth-page",
+        cssPaths: ["/assets/css/pages/auth.css"],
+    });
+}
+function oauthSuccessHtml(params) {
+    const safeRedirectUri = escapeHtml(params.redirectUri);
+    const body = `<main class="app-shell auth-wrap">
+  ${renderWordmark()}
+  <h1 class="auth-headline">brains connected</h1>
+  <section class="panel auth-panel">
+    <p>Your brains account is now connected. Return to the app — you may close this tab.</p>
+    <p class="auth-hint">If the app did not open automatically, <a href="${safeRedirectUri}">click here to complete the connection</a>.</p>
+  </section>
+  <script>
+    try { window.location.href = ${JSON.stringify(params.redirectUri)}; } catch (_) {}
+  </script>
+</main>`;
+    return renderPageShell({
+        title: "Connected - brains",
+        body,
+        bodyClass: "auth-page",
+        cssPaths: ["/assets/css/pages/auth.css"],
+    });
+}
+function oauthCallbackHtml(params) {
+    const valueOrNone = (value) => (value ? escapeHtml(value) : "<em>(none)</em>");
+    const hasError = Boolean(params.error);
+    const body = `<main class="app-shell callback-wrap">
+  ${renderWordmark("OAuth callback payload for local testing and code exchange.")}
+  <section class="panel card mono">
+    <h2 class="page-title">OAuth callback received</h2>
+    <p>Use the values below for local testing or exchange the authorization code at <code>/oauth/token</code>.</p>
+    ${renderStatusBadge(hasError ? "err" : "ok", hasError ? "Authorization error" : "Authorization success")}
+    <div class="kv-grid">
+      <div class="kv-label">code</div>
+      <div class="kv-value">${valueOrNone(params.code)}</div>
+      <div class="kv-label">state</div>
+      <div class="kv-value">${valueOrNone(params.state)}</div>
+      <div class="kv-label">error</div>
+      <div class="kv-value">${valueOrNone(params.error)}</div>
+      <div class="kv-label">error_description</div>
+      <div class="kv-value">${valueOrNone(params.errorDescription)}</div>
+    </div>
+  </section>
+</main>`;
+    return renderPageShell({
+        title: "OAuth Callback - brains",
+        body,
+        bodyClass: "callback-page",
+        cssPaths: ["/assets/css/pages/callback.css"],
+    });
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll("\"", "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function connectPageHtml(base, _registeredClientIds) {
+    const mcpUrl = `${base}/mcp`;
+    const platforms = {
+        chatgpt: { name: "ChatGPT", emoji: "✦" },
+        claude: { name: "Claude", emoji: "◆" },
+        copilot: { name: "GitHub Copilot · VS Code", emoji: "⬡" },
+        "copilot-app": { name: "GitHub Copilot · app", emoji: "⬡" },
+        gemini: { name: "Gemini", emoji: "✶" },
+    };
+    const vscodeJsonHtml = escapeHtml(`{\n  "brains": {\n    "type": "http",\n    "url": "${mcpUrl}"\n  }\n}`);
+    const steps = [
+        {
+            title: "Add the app",
+            description: "Connect brains to your AI assistant using the MCP Server URL below.",
+            bodyHtml: `
+        <p class="cj-url-label">MCP Server URL</p>
+        <div class="cj-url-block"><code>${escapeHtml(mcpUrl)}</code></div>`,
+            accordions: [
+                {
+                    platformId: "chatgpt",
+                    steps: [
+                        "<strong>Do this on <a href=\"https://chatgpt.com\" target=\"_blank\" rel=\"noopener\">chatgpt.com</a></strong> in a browser — the Mac and iOS apps may not support custom MCP connectors yet.",
+                        "Go to <strong>Settings → Apps</strong>, then <strong>Advanced settings</strong> and enable <strong>Developer mode</strong>.",
+                        "Back in <strong>Settings → Apps</strong>, click <strong>Add app</strong>.",
+                        "Enter a name like <em>brains</em>, paste the MCP Server URL above into the <strong>MCP Server URL</strong> field.",
+                        "Leave Authentication as <strong>OAuth</strong> and click <strong>Create</strong>.",
+                    ],
+                },
+                {
+                    platformId: "claude",
+                    steps: [
+                        "Go to <strong>Claude.ai → Settings → Integrations</strong> and click <strong>Add integration</strong>.",
+                        "Paste the MCP Server URL above and give the integration a name like <em>brains</em>.",
+                        "Click <strong>Add</strong>.",
+                    ],
+                },
+                {
+                    platformId: "copilot",
+                    steps: [
+                        "Open (or create) <code>.vscode/mcp.json</code> in your project (or the global VS Code MCP settings).",
+                        `Add the following entry and save:<br><pre class="connect-code">${vscodeJsonHtml}</pre>`,
+                        "VS Code detects the server and shows a sign-in prompt — continue to step 2.",
+                    ],
+                },
+                {
+                    platformId: "copilot-app",
+                    steps: [
+                        "Click <strong>Generate token</strong> below — you must be signed in to brains.",
+                        `Copy the full config block that appears and save it as <code>~/.copilot/mcp-config.json</code> (create the file if it doesn't exist).`,
+                    ],
+                    footerHtml: `<div style="margin-top:0.75rem">
+            <button class="btn" id="gen-pat-btn" type="button" style="font-size:0.85rem;padding:0.45rem 0.9rem;min-height:0">Generate token</button>
+            <p id="pat-msg" style="display:none;margin:0.5rem 0 0;font-size:0.84rem;color:var(--error,#b00)"></p>
+            <pre class="connect-code" id="pat-config-out" style="display:none;margin-top:0.6rem;user-select:all"></pre>
+          </div>`,
+                },
+                { platformId: "gemini", soon: true, steps: [] },
+            ],
+        },
+        {
+            title: "Authenticate",
+            description: "Sign in or create a brains account to link your personal wiki. Each user gets their own private, isolated space.",
+            bodyHtml: "",
+            accordions: [
+                {
+                    platformId: "chatgpt",
+                    steps: [
+                        "After clicking <strong>Create</strong>, ChatGPT opens the brains sign-in page.",
+                        "Click the <strong>Create account</strong> tab and sign up with your email.",
+                        "Authorise access — ChatGPT returns you to your conversation.",
+                        "<strong>Note:</strong> ChatGPT may show an error saying it couldn't complete the task after you return. This is a known quirk — the connection almost certainly worked. Continue to step 3 and try using brains; if it responds, you're all set.",
+                    ],
+                },
+                {
+                    platformId: "claude",
+                    steps: [
+                        "After adding the integration, Claude redirects you to the brains sign-in page.",
+                        "Click the <strong>Create account</strong> tab and sign up with your email.",
+                        "Authorise access — you'll be returned to Claude.",
+                    ],
+                },
+                {
+                    platformId: "copilot",
+                    steps: [
+                        "VS Code shows an <strong>Allow</strong> sign-in prompt — click it.",
+                        "A browser tab opens with the brains sign-in page.",
+                        "Click the <strong>Create account</strong> tab, sign up with your email, and authorise.",
+                    ],
+                },
+                {
+                    platformId: "copilot-app",
+                    steps: [
+                        "Authentication is handled by the token you generated — no sign-in popup needed.",
+                    ],
+                },
+                { platformId: "gemini", soon: true, steps: [] },
+            ],
+        },
+        {
+            title: "Activate for a project",
+            description: "Connecting brains makes tools available but passive — nothing runs automatically. To enable active memory, run init_project once in your project and paste the output into your project's instruction settings.",
+            bodyHtml: `
+        <p class="cj-step-hint">Run this prompt inside your project:</p>
+        <div class="cj-prompt">&ldquo;Set up brains for this project.&rdquo;</div>`,
+            accordions: [
+                {
+                    platformId: "chatgpt",
+                    steps: [
+                        "Open or create a <strong>Project</strong> in ChatGPT, then run the prompt above.",
+                        "brains saves a page like <code>projects/&lt;your-project&gt;/instructions/gpt.md</code> — open it and copy the contents.",
+                        "In the project, click <strong>Edit project</strong> and paste into the <strong>Instructions</strong> field.",
+                    ],
+                },
+                {
+                    platformId: "claude",
+                    steps: [
+                        "Open or create a <strong>Project</strong> in Claude.ai, then run the prompt above.",
+                        "brains saves a page like <code>projects/&lt;your-project&gt;/instructions/claude.md</code> — open it and copy the contents.",
+                        "In the project, go to <strong>Project instructions</strong> and paste.",
+                    ],
+                },
+                {
+                    platformId: "copilot",
+                    steps: [
+                        "In VS Code with a project open, run the prompt above in Copilot Chat.",
+                        "brains saves an instructions page — open it and copy the contents.",
+                        "Paste into <code>.github/copilot-instructions.md</code> at the root of your project.",
+                    ],
+                },
+                {
+                    platformId: "copilot-app",
+                    steps: [
+                        "In the Copilot app with a project open, run the prompt above.",
+                        "brains saves an instructions page — open it and copy the contents.",
+                        "Paste into <code>.github/copilot-instructions.md</code> at the root of your project.",
+                    ],
+                },
+                { platformId: "gemini", soon: true, steps: [] },
+            ],
+        },
+        {
+            title: "Happy braining",
+            description: "You're all set. Your assistant can now read, write, and search your private wiki — and remember things across sessions.",
+            bodyHtml: `
+        <ul class="cj-examples">
+          <li><em>&ldquo;Save the spec sheet for my project car.&rdquo;</em></li>
+          <li><em>&ldquo;Remember that Sarah at Acme is the main contact for billing questions.&rdquo;</em></li>
+          <li><em>&ldquo;Save a decision record — we're going with Instagram over TikTok for the launch.&rdquo;</em></li>
+          <li><em>&ldquo;What do we know about the Henderson account?&rdquo;</em></li>
+        </ul>`,
+            accordions: [],
+        },
+    ];
+    function renderAccordions(accordions) {
+        if (accordions.length === 0)
+            return "";
+        const items = accordions.map((acc) => {
+            const p = platforms[acc.platformId];
+            if (acc.soon) {
+                return `<details class="cj-accordion cj-accordion--soon" aria-disabled="true">
+          <summary>
+            <span class="cj-acc-emoji">${p.emoji}</span>
+            <span>${escapeHtml(p.name)}</span>
+            <span class="cj-acc-soon">Coming soon</span>
+          </summary>
+        </details>`;
+            }
+            const stepsHtml = acc.steps
+                .map((s, i) => `<li><span class="step-num">${i + 1}</span><span>${s}</span></li>`)
+                .join("");
+            return `<details class="cj-accordion">
+          <summary>
+            <span class="cj-acc-emoji">${p.emoji}</span>
+            <span>${escapeHtml(p.name)}</span>
+          </summary>
+          <div class="cj-accordion-body">
+            <ol class="connect-steps">${stepsHtml}</ol>
+            ${acc.footerHtml ?? ""}
+          </div>
+        </details>`;
+        }).join("\n        ");
+        return `<div class="cj-accordions">${items}</div>`;
+    }
+    const stepsHtml = steps.map((step, i) => `
+    <div class="cj-step">
+      <div class="cj-step-header">
+        <span class="cj-step-num">${i + 1}</span>
+        <div>
+          <h2 class="cj-step-title">${escapeHtml(step.title)}</h2>
+          <p class="cj-step-desc">${escapeHtml(step.description)}</p>
+        </div>
+      </div>
+      <div class="cj-step-body">
+        ${step.bodyHtml}
+        ${renderAccordions(step.accordions)}
+      </div>
+    </div>`).join("\n");
+    const body = `<main class="app-shell connect-wrap">
+  ${renderWordmark("Connect your AI assistant to your personal wiki.")}
+  <section class="connect-journey">
+    ${stepsHtml}
+  </section>
+  <script>
+    (function () {
+      var btn = document.getElementById('gen-pat-btn');
+      var out = document.getElementById('pat-config-out');
+      var msg = document.getElementById('pat-msg');
+      if (!btn) return;
+      btn.addEventListener('click', async function () {
+        btn.disabled = true;
+        btn.textContent = 'Generating…';
+        msg.style.display = 'none';
+        out.style.display = 'none';
+        try {
+          var r = await fetch('/api/v1/tokens', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ label: 'Copilot app', expiresInDays: 365 })
+          });
+          var d = await r.json();
+          if (!r.ok || !d.ok) {
+            if (r.status === 401 || r.status === 403) {
+              msg.innerHTML = 'Sign in to brains first (<a href="/">brains.app</a>), then return here and click Generate token.';
+            } else {
+              msg.textContent = d.error || 'Failed to generate token.';
+            }
+            msg.style.display = '';
+            btn.disabled = false;
+            btn.textContent = 'Generate token';
+            return;
+          }
+          out.textContent = JSON.stringify({
+            mcpServers: {
+              brains: {
+                type: 'http',
+                url: ${JSON.stringify(mcpUrl)},
+                headers: { Authorization: 'Bearer ' + d.token }
+              }
+            }
+          }, null, 2);
+          out.style.display = '';
+          btn.textContent = 'Regenerate token';
+          btn.disabled = false;
+        } catch (err) {
+          msg.textContent = 'Network error: ' + err.message;
+          msg.style.display = '';
+          btn.disabled = false;
+          btn.textContent = 'Generate token';
+        }
+      });
+    })();
+  </script>
+</main>`;
+    return renderPageShell({
+        title: "Connect to brains",
+        body,
+        bodyClass: "connect-page",
+        cssPaths: ["/assets/css/pages/connect.css"],
+    });
+}
+function redirectWithParams(res, redirectUri, params) {
+    const url = new URL(redirectUri);
+    for (const [key, value] of Object.entries(params)) {
+        if (!value)
+            continue;
+        url.searchParams.set(key, value);
+    }
+    res.writeHead(302, { location: url.toString() });
+    res.end();
+}
+function coerceNumber(value) {
+    if (value === null || value.trim() === "")
+        return undefined;
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        return undefined;
+    return n;
+}
+async function callAnthropic(apiKey, model, maxTokens, messages) {
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-api-key": apiKey,
+            "anthropic-version": "2023-06-01",
+        },
+        body: JSON.stringify({
+            model,
+            max_tokens: maxTokens,
+            tools: getVisibleTools().map((t) => ({
+                name: t.name,
+                description: t.description,
+                input_schema: t.inputSchema,
+            })),
+            messages,
+        }),
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`Anthropic API error (${response.status}): ${text}`);
+    }
+    return JSON.parse(text);
+}
+async function runClaudeWithTools(drive, req, userId = "", accessCtx = DEFAULT_ACCESS_CONTEXT) {
+    const model = req.model ?? process.env.CLAUDE_MODEL ?? "claude-3-7-sonnet-latest";
+    const maxTokens = req.maxTokens ?? 1500;
+    const history = [...(req.messages ?? [])];
+    if (req.message && req.message.trim()) {
+        history.push({ role: "user", content: req.message.trim() });
+    }
+    const anthropicMessages = history.map((m) => ({
+        role: m.role,
+        content: [{ type: "text", text: m.content }],
+    }));
+    let finalText = "";
+    for (let i = 0; i < 8; i += 1) {
+        const response = await callAnthropic(req.apiKey, model, maxTokens, anthropicMessages);
+        const content = Array.isArray(response.content) ? response.content : [];
+        anthropicMessages.push({ role: "assistant", content });
+        const textParts = content
+            .filter((c) => c.type === "text")
+            .map((c) => c.text);
+        if (textParts.length > 0) {
+            finalText = textParts.join("\n").trim();
+        }
+        const toolUses = content.filter((c) => c.type === "tool_use");
+        if (toolUses.length === 0) {
+            break;
+        }
+        const toolResults = [];
+        for (const toolUse of toolUses) {
+            try {
+                const result = await executeToolCall(drive, String(toolUse.name), toolUse.input ?? {}, userId, accessCtx);
+                toolResults.push({
+                    type: "tool_result",
+                    tool_use_id: String(toolUse.id),
+                    content: JSON.stringify(result),
+                });
+            }
+            catch (toolErr) {
+                const errMsg = toolErr instanceof Error ? toolErr.message : String(toolErr);
+                toolResults.push({
+                    type: "tool_result",
+                    tool_use_id: String(toolUse.id),
+                    content: errMsg,
+                    is_error: true,
+                });
+            }
+        }
+        anthropicMessages.push({ role: "user", content: toolResults });
+    }
+    if (!finalText) {
+        finalText = "(Claude returned no text output)";
+    }
+    history.push({ role: "assistant", content: finalText });
+    return { assistant: finalText, messages: history };
+}
+/**
+ * After bootstrap, walk every file in the scoped storage and upsert it into
+ * the Postgres search index.  Runs entirely in the background — the caller's
+ * first request is never delayed.  Safe to call multiple times (upsert is
+ * idempotent).  No-ops when Postgres is not configured.
+ */
+async function backfillIndexForUser(scoped, userId) {
+    const idx = getPostgresSearchIndex();
+    if (!idx.isConfigured())
+        return;
+    let files;
+    try {
+        files = await scoped.listFiles();
+    }
+    catch {
+        return;
+    }
+    for (const entry of files) {
+        try {
+            const wiki = await scoped.readFile(entry.name);
+            const { frontmatter } = parsePage(wiki.content);
+            // Full content (frontmatter included) — matches patchPage.ts's DB-primary
+            // convention, which read_page/patch_page read back as the complete file.
+            await idx.upsertPage(entry.name, frontmatter, wiki.content, wiki.revision, wiki.modifiedTime, userId);
+        }
+        catch {
+            // Non-fatal — skip unreadable / unparseable files
+        }
+    }
+}
+async function countMdFiles(dir) {
+    let count = 0;
+    const walk = async (d) => {
+        const entries = await fs.readdir(d, { withFileTypes: true }).catch(() => []);
+        for (const e of entries) {
+            if (e.isDirectory()) {
+                await walk(path.join(d, e.name));
+                continue;
+            }
+            if (e.isFile() && e.name.endsWith(".md"))
+                count++;
+        }
+    };
+    await walk(dir);
+    return count;
+}
+async function calcDirBytes(dir) {
+    let bytes = 0;
+    const walk = async (d) => {
+        const entries = await fs.readdir(d, { withFileTypes: true }).catch(() => []);
+        for (const e of entries) {
+            if (e.isDirectory()) {
+                await walk(path.join(d, e.name));
+                continue;
+            }
+            if (e.isFile()) {
+                const stat = await fs.stat(path.join(d, e.name)).catch(() => null);
+                if (stat)
+                    bytes += stat.size;
+            }
+        }
+    };
+    await walk(dir);
+    return bytes;
+}
+export async function startHttpServer(drive, port) {
+    const tokenStore = createTokenStore(drive.getStorageLocation());
+    const clientStore = createClientStore(drive.getStorageLocation());
+    const patStore = createPATStore(drive.getStorageLocation());
+    const oauth = new OAuthManager(tokenStore, clientStore);
+    const supabaseAuth = new SupabaseAuthManager();
+    const openApi = buildOpenApiSpec();
+    // ── Per-request timeouts ──────────────────────────────────────────────────
+    const TIMEOUT_DEFAULT_MS = parseInt(process.env.TIMEOUT_DEFAULT_MS ?? "30000");
+    const TIMEOUT_CHAT_MS = parseInt(process.env.TIMEOUT_CHAT_MS ?? "120000");
+    const TIMEOUT_IMPORT_MS = parseInt(process.env.TIMEOUT_IMPORT_MS ?? "300000");
+    // ── Rate limiting (per-instance state so tests can run in isolation) ────────
+    const RATE_LIMIT_ENABLED = (process.env.RATE_LIMIT_ENABLED ?? "true").toLowerCase() !== "false";
+    const RATE_LIMIT_WINDOW_MS = parseInt(process.env.RATE_LIMIT_WINDOW_MS ?? "60000");
+    const RATE_LIMITS = {
+        search: parseInt(process.env.RATE_LIMIT_SEARCH ?? "60"),
+        reads: parseInt(process.env.RATE_LIMIT_READS ?? "120"),
+        writes: parseInt(process.env.RATE_LIMIT_WRITES ?? "30"),
+        batch: parseInt(process.env.RATE_LIMIT_BATCH ?? "5"),
+        chat: parseInt(process.env.RATE_LIMIT_CHAT ?? "10"),
+    };
+    // Map<"class:subject", number[]> — timestamp arrays pruned on each check
+    const rateLimitWindows = new Map();
+    // ── Concurrency caps ──────────────────────────────────────────────────────
+    const CONCURRENCY_LIMIT_BATCH = parseInt(process.env.CONCURRENCY_LIMIT_BATCH ?? "3");
+    const CONCURRENCY_LIMIT_IMPORT = parseInt(process.env.CONCURRENCY_LIMIT_IMPORT ?? "1");
+    const CONCURRENCY_LIMIT_PURGE = parseInt(process.env.CONCURRENCY_LIMIT_PURGE ?? "1");
+    const CONCURRENCY_LIMIT_CHAT = parseInt(process.env.CONCURRENCY_LIMIT_CHAT ?? "5");
+    let batchInFlight = 0;
+    let importInFlight = 0;
+    let purgeInFlight = 0;
+    let chatInFlight = 0;
+    const asyncJobRegistry = new AsyncJobRegistry();
+    // ── FTS startup backfill ──────────────────────────────────────────────────
+    // Detect and fix rows where fts_vector is NULL — happens when data is
+    // migrated to a new Supabase project before the trigger is applied.
+    if ((process.env.STORAGE_BACKEND ?? "local").toLowerCase() === "supabase") {
+        getPostgresSearchIndex().reindexFts().then(({ updated }) => {
+            if (updated > 0)
+                console.log(`[startup] FTS reindex: backfilled ${updated} rows`);
+        }).catch((err) => {
+            console.error("[startup] FTS reindex error:", err instanceof Error ? err.message : err);
+        });
+    }
+    function publicBase() {
+        const raw = (process.env.BRAINS_BASE_URL?.trim() ||
+            process.env.BRAINS_PUBLIC_BASE_URL?.trim() ||
+            "https://brains-staging.up.railway.app").replace(/\/$/, "");
+        return raw || `http://localhost:${port}`;
+    }
+    function webUrl() {
+        return process.env.WEB_URL?.trim().replace(/\/$/, "") || undefined;
+    }
+    function oauthAuthorizationServerMetadata() {
+        const base = publicBase();
+        return {
+            issuer: base,
+            authorization_endpoint: `${base}/oauth/authorize`,
+            token_endpoint: `${base}/oauth/token`,
+            registration_endpoint: `${base}/oauth/register`,
+            revocation_endpoint: `${base}/oauth/revoke`,
+            response_types_supported: ["code"],
+            grant_types_supported: ["authorization_code", "refresh_token"],
+            code_challenge_methods_supported: ["S256", "plain"],
+            scopes_supported: ["wiki.read", "wiki.write"],
+            token_endpoint_auth_methods_supported: [...new Set(["none", ...oauth.getTokenEndpointAuthMethods()])],
+            revocation_endpoint_auth_methods_supported: [...new Set(["none", ...oauth.getTokenEndpointAuthMethods()])],
+        };
+    }
+    function oauthProtectedResourceMetadata() {
+        const base = publicBase();
+        return {
+            resource: `${base}/mcp`,
+            authorization_servers: [base],
+            scopes_supported: ["wiki.read", "wiki.write"],
+            bearer_methods_supported: ["header"],
+        };
+    }
+    const enableRemoteMcp = (process.env.BRAINS_ENABLE_REMOTE_MCP ?? "false").toLowerCase() === "true";
+    // Cache scoped StorageClient promises per user subject. Each entry also
+    // records the last time the cache was validated for an external wipe so we
+    // only re-check once per TTL rather than on every request.
+    const SCOPED_DRIVE_WIPE_CHECK_TTL_MS = 5 * 60 * 1000; // 5 minutes
+    const scopedDriveCache = new Map();
+    const mcpSessions = new Map();
+    // Deduplicates concurrent reconnect attempts for the same stale session ID.
+    // Keyed by session ID; value is a Promise that resolves to the newly created
+    // session (or null if syntheticMcpInit failed).
+    const mcpReconnectPromises = new Map();
+    /**
+     * Returns the storage client scoped to the authenticated user.
+     *
+     * Scoping behavior by auth mode:
+     *   oauth / supabase  → isolated prefix `users/<sanitized-subject>/`
+     *   api-key           → shared global root  (intentional, by design)
+     *   connector-key     → shared global root  (intentional, by design)
+     *   unauthenticated   → shared global root
+     *
+     * Scoped clients are cached per subject for the lifetime of the server
+     * process to amortise the verifyAccess + bootstrapWikiFiles overhead.
+     * The cache entry is evicted if storage is found to be empty on a
+     * subsequent request (e.g. after an external data wipe), so bootstrap
+     * re-runs automatically without needing a redeploy.
+     *
+     * Note: when the storage backend is Supabase the service-role key is used
+     * for all operations, which bypasses Supabase Storage RLS by design.
+     * App-level path isolation is the primary enforcement mechanism.
+     * Supabase Storage RLS policies (see scripts/supabase-rls-policies.sql)
+     * provide defence-in-depth for direct API / JWT-based access.
+     */
+    async function getOrCreateScopedClient(subjectKey, displaySubject) {
+        const cached = scopedDriveCache.get(subjectKey);
+        if (cached) {
+            const now = Date.now();
+            if (now - cached.lastWipeCheckAt < SCOPED_DRIVE_WIPE_CHECK_TTL_MS) {
+                // Within TTL — return the cached client without an expensive listing.
+                return cached.client;
+            }
+            // TTL expired — probe for a single marker file to detect an external
+            // wipe without listing the whole wiki. Uses an existence check rather
+            // than a read: index.md is ~200 KB on a large wiki, and downloading it
+            // every 5 minutes per user to answer a yes/no question is pure waste
+            // (GH #412).
+            const scoped = await cached.client;
+            const wipeDetected = await scoped.fileExists("index.md")
+                .then((exists) => !exists)
+                .catch(() => false);
+            if (!wipeDetected) {
+                cached.lastWipeCheckAt = now;
+                return scoped;
+            }
+            // Storage was wiped — evict and fall through to re-bootstrap below.
+            scopedDriveCache.delete(subjectKey);
+        }
+        const createDrive = (async () => {
+            const scoped = createScopedStorageClient(drive, `users/${subjectKey}`);
+            await scoped.verifyAccess();
+            await scoped.bootstrapWikiFiles();
+            // Backfill the Postgres index in the background — non-blocking.
+            backfillIndexForUser(scoped, displaySubject).catch(() => { });
+            return scoped;
+        })();
+        scopedDriveCache.set(subjectKey, { client: createDrive, lastWipeCheckAt: Date.now() });
+        try {
+            return await createDrive;
+        }
+        catch (err) {
+            scopedDriveCache.delete(subjectKey);
+            throw err;
+        }
+    }
+    /**
+     * Cross-account project sharing (BRA-368): when the authenticated user has
+     * one or more active grants (see src/access/projectShares.ts), wraps their
+     * own scoped client so page paths under a granted project route to the
+     * grant owner's storage namespace instead. Transparent to the MCP tool
+     * layer — read_page/patch_page/etc. see one StorageClient either way.
+     */
+    async function resolveDriveForAuthorization(auth) {
+        if (!auth || !shouldUseUserScopedStorage(auth.mode)) {
+            // api-key and connector-key modes fall through to the shared global drive.
+            return drive;
+        }
+        const subjectKey = sanitizeSubjectForPath(auth.subject);
+        const ownScoped = await getOrCreateScopedClient(subjectKey, auth.subject);
+        const grants = await listActiveGrantsForGrantee(auth.subject).catch((err) => {
+            console.warn("[project-shares] failed to list grants:", err instanceof Error ? err.message : err);
+            return [];
+        });
+        if (grants.length === 0)
+            return ownScoped;
+        const routes = await Promise.all(grants.map(async (g) => {
+            const ownerKey = sanitizeSubjectForPath(g.owner_subject);
+            const ownerScoped = await getOrCreateScopedClient(ownerKey, g.owner_subject);
+            return { prefix: g.project_path, client: ownerScoped, ownerSubject: g.owner_subject };
+        }));
+        return new GrantAwareStorageClient(ownScoped, routes, auth.subject);
+    }
+    const server = http.createServer(async (req, res) => {
+        const startTime = Date.now();
+        const method = req.method ?? "GET";
+        const parsedUrl = new URL(req.url ?? "/", "http://localhost");
+        const pathname = parsedUrl.pathname;
+        // Inject X-Response-Time header before headers are flushed.
+        const _origWriteHead = res.writeHead.bind(res);
+        res.writeHead = function (...args) {
+            if (!res.headersSent) {
+                res.setHeader("X-Response-Time", `${Date.now() - startTime}ms`);
+            }
+            return _origWriteHead(...args);
+        };
+        // Emit one log line per request after the response is fully sent.
+        res.on("finish", () => {
+            const durationMs = Date.now() - startTime;
+            const extras = res._logExtras ?? {};
+            emitRequestLog(method, pathname, res.statusCode, durationMs, extras);
+            // Fire-and-forget insert into Supabase request_events table.
+            const supabaseUrl = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+            const serviceRoleKey = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+            if (supabaseUrl && serviceRoleKey) {
+                void insertRequestEvent(supabaseUrl, serviceRoleKey, {
+                    method,
+                    path: pathname,
+                    status: res.statusCode,
+                    duration_ms: durationMs,
+                    backend: extras.backend,
+                    query_ms: extras.queryMs,
+                    sync_ms: extras.syncMs,
+                    result_count: extras.resultCount,
+                    query_text: extras.queryText,
+                    tool: extras.tool,
+                    page_count: extras.pageCount,
+                }).catch((err) => {
+                    console.error("[metrics] insert failed", err.message);
+                });
+            }
+        });
+        try {
+            let authorization = null;
+            if (method === "GET" && pathname === "/openapi.json") {
+                json(req, res, 200, openApi);
+                return;
+            }
+            if (method === "GET" && pathname === "/.well-known/openapi.json") {
+                json(req, res, 200, openApi);
+                return;
+            }
+            if (method === "GET" && pathname === "/api/v1") {
+                json(req, res, 200, openApi);
+                return;
+            }
+            if (method === "GET" && pathname === "/.well-known/oauth-authorization-server") {
+                json(req, res, 200, oauthAuthorizationServerMetadata());
+                return;
+            }
+            if (method === "GET" && pathname === "/.well-known/oauth-protected-resource") {
+                json(req, res, 200, oauthProtectedResourceMetadata());
+                return;
+            }
+            if (method === "GET" && pathname.startsWith(CSS_ASSET_PREFIX)) {
+                await cssAsset(res, pathname);
+                return;
+            }
+            if (method === "GET" && pathname.startsWith(IMG_ASSET_PREFIX)) {
+                await imgAsset(res, pathname);
+                return;
+            }
+            // ── Editor SPA ──────────────────────────────────────────────────────────
+            if (method === "GET" && pathname === EDITOR_PREFIX) {
+                res.writeHead(302, { location: `${EDITOR_PREFIX}/` });
+                res.end();
+                return;
+            }
+            if (method === "GET" && pathname.startsWith(`${EDITOR_PREFIX}/`)) {
+                const relativePath = pathname.slice(EDITOR_PREFIX.length + 1); // strip /editor/
+                const filePath = relativePath
+                    ? path.resolve(EDITOR_DIST, ...relativePath.split("/").filter(Boolean))
+                    : path.join(EDITOR_DIST, "index.html");
+                // Path traversal guard
+                if (!filePath.startsWith(EDITOR_DIST + path.sep) && filePath !== EDITOR_DIST) {
+                    res.writeHead(400, { "content-type": "text/plain" });
+                    res.end("Bad request");
+                    return;
+                }
+                await serveEditorAsset(res, filePath);
+                return;
+            }
+            if (enableRemoteMcp && pathname === "/mcp") {
+                const mcpAuthStart = Date.now();
+                authorization = await authorizeRequest(req, parsedUrl, oauth, supabaseAuth, patStore);
+                const mcpAuthMs = Date.now() - mcpAuthStart;
+                if (!authorization) {
+                    unauthorized(res, `${publicBase()}/.well-known/oauth-protected-resource`);
+                    return;
+                }
+                // MCP can invoke both read and write tools, so require write scope up front.
+                if (!hasRequiredScopes(authorization.scopes, ["wiki.write"])) {
+                    forbidden(res, ["wiki.write"]);
+                    return;
+                }
+                if (method === "POST") {
+                    const body = await readJsonBody(req);
+                    const sessionIdHeader = req.headers["mcp-session-id"];
+                    const sessionId = typeof sessionIdHeader === "string" ? sessionIdHeader : undefined;
+                    // Log the JSON-RPC method for diagnostics.
+                    const bodyMsg = Array.isArray(body) ? body[0] : body;
+                    const rpcMethod = typeof bodyMsg === "object" && bodyMsg !== null
+                        ? String(bodyMsg.method ?? "unknown")
+                        : "unknown";
+                    const rpcId = typeof bodyMsg === "object" && bodyMsg !== null
+                        ? bodyMsg.id ?? null
+                        : null;
+                    console.error(`[brains] MCP rpc=${rpcMethod} session=${sessionId ?? "none"} authMs=${mcpAuthMs}`);
+                    let existing = sessionId ? mcpSessions.get(sessionId) : undefined;
+                    if (!existing) {
+                        if (rpcMethod !== "initialize") {
+                            if (!sessionId) {
+                                // No session ID at all — client must send initialize first.
+                                json(req, res, 400, {
+                                    jsonrpc: "2.0",
+                                    error: {
+                                        code: -32000,
+                                        message: "No active session. Send an initialize request first.",
+                                    },
+                                    id: rpcId,
+                                });
+                                return;
+                            }
+                            // Stale session ID (e.g. after a server redeploy) with valid auth.
+                            // Transparently spin up a new session using the same session ID so
+                            // the client never sees a -32000 error and never discards its OAuth
+                            // tokens.  The synthetic initialize primes the transport's internal
+                            // state before we dispatch the client's actual request.
+                            //
+                            // Use mcpReconnectPromises to deduplicate concurrent requests that arrive
+                            // with the same stale session ID before the first reconnect completes.
+                            const staleSid = sessionId;
+                            let reconnectPromise = mcpReconnectPromises.get(staleSid);
+                            if (!reconnectPromise) {
+                                console.error(`[brains] MCP stale session=${staleSid} rpc=${rpcMethod} — transparent reconnect`);
+                                reconnectPromise = (async () => {
+                                    const mcpUserId = shouldUseUserScopedStorage(authorization.mode) ? authorization.subject : "";
+                                    const mcpUserAccessLevel = await getUserAccessLevel(mcpUserId);
+                                    // Re-resolve the drive on every tool call rather than baking in a
+                                    // snapshot here — otherwise a project-share grant revoked mid-session
+                                    // keeps being honored for the lifetime of this MCP session (BRA-377).
+                                    const mcpServer = createBrainsServer(() => resolveDriveForAuthorization(authorization), mcpUserId, mcpUserAccessLevel);
+                                    const transport = new StreamableHTTPServerTransport({
+                                        sessionIdGenerator: () => staleSid,
+                                    });
+                                    transport.onclose = () => {
+                                        mcpSessions.delete(staleSid);
+                                    };
+                                    await mcpServer.connect(transport);
+                                    const ok = await syntheticMcpInit(transport);
+                                    if (!ok) {
+                                        return null;
+                                    }
+                                    const entry = { server: mcpServer, transport };
+                                    mcpSessions.set(staleSid, entry);
+                                    return entry;
+                                })().finally(() => {
+                                    mcpReconnectPromises.delete(staleSid);
+                                });
+                                mcpReconnectPromises.set(staleSid, reconnectPromise);
+                            }
+                            const reconnected = await reconnectPromise;
+                            if (!reconnected) {
+                                json(req, res, 400, {
+                                    jsonrpc: "2.0",
+                                    error: {
+                                        code: -32000,
+                                        message: "No active session. Send an initialize request first.",
+                                    },
+                                    id: rpcId,
+                                });
+                                return;
+                            }
+                            existing = reconnected;
+                        }
+                        else {
+                            const mcpUserId = shouldUseUserScopedStorage(authorization.mode) ? authorization.subject : "";
+                            const mcpUserAccessLevel = await getUserAccessLevel(mcpUserId);
+                            // Re-resolve the drive on every tool call rather than baking in a
+                            // snapshot here — otherwise a project-share grant revoked mid-session
+                            // keeps being honored for the lifetime of this MCP session (BRA-377).
+                            const mcpServer = createBrainsServer(() => resolveDriveForAuthorization(authorization), mcpUserId, mcpUserAccessLevel);
+                            const transport = new StreamableHTTPServerTransport({
+                                sessionIdGenerator: () => randomUUID(),
+                            });
+                            transport.onclose = () => {
+                                const activeSessionId = transport.sessionId;
+                                if (activeSessionId) {
+                                    mcpSessions.delete(activeSessionId);
+                                }
+                            };
+                            await mcpServer.connect(transport);
+                            existing = { server: mcpServer, transport };
+                        }
+                    }
+                    const { transport } = existing;
+                    const mcpHandlerStart = Date.now();
+                    // Inject timing headers before the transport writes its response headers.
+                    res.setHeader("X-Brains-Auth-Ms", String(mcpAuthMs));
+                    res.setHeader("X-Brains-Handler-Start-Ms", String(mcpHandlerStart));
+                    try {
+                        await transport.handleRequest(req, res, body);
+                    }
+                    catch (mcpErr) {
+                        console.error("[brains] MCP transport error:", mcpErr instanceof Error ? mcpErr.stack : String(mcpErr));
+                        throw mcpErr;
+                    }
+                    if (!res.headersSent) {
+                        res.setHeader("X-Brains-Handler-End-Ms", String(Date.now()));
+                    }
+                    const newSessionId = transport.sessionId;
+                    if (newSessionId && !mcpSessions.has(newSessionId)) {
+                        mcpSessions.set(newSessionId, existing);
+                    }
+                    return;
+                }
+                if (method === "GET" || method === "DELETE") {
+                    const sessionIdHeader = req.headers["mcp-session-id"];
+                    const sessionId = typeof sessionIdHeader === "string" ? sessionIdHeader : undefined;
+                    if (!sessionId) {
+                        json(req, res, 400, {
+                            jsonrpc: "2.0",
+                            error: {
+                                code: -32000,
+                                message: "Bad Request: Mcp-Session-Id header is required.",
+                            },
+                            id: null,
+                        });
+                        return;
+                    }
+                    const existing = mcpSessions.get(sessionId);
+                    if (!existing) {
+                        json(req, res, 404, {
+                            jsonrpc: "2.0",
+                            error: {
+                                code: -32001,
+                                message: "Session not found.",
+                            },
+                            id: null,
+                        });
+                        return;
+                    }
+                    const { transport } = existing;
+                    await transport.handleRequest(req, res);
+                    return;
+                }
+            }
+            if (pathname === "/oauth/authorize") {
+                if (!oauth.isEnabled()) {
+                    json(req, res, 503, {
+                        ok: false,
+                        error: "OAuth is not configured",
+                        detail: "Set BRAINS_OAUTH_CLIENTS and either BRAINS_OAUTH_PASSWORD or SUPABASE_URL + SUPABASE_ANON_KEY",
+                    });
+                    return;
+                }
+                if (method === "GET") {
+                    const parsed = oauthAuthorizeQuerySchema.parse({
+                        response_type: parsedUrl.searchParams.get("response_type"),
+                        client_id: parsedUrl.searchParams.get("client_id"),
+                        redirect_uri: parsedUrl.searchParams.get("redirect_uri"),
+                        scope: parsedUrl.searchParams.get("scope") ?? undefined,
+                        state: parsedUrl.searchParams.get("state") ?? undefined,
+                        code_challenge: parsedUrl.searchParams.get("code_challenge") ?? undefined,
+                        code_challenge_method: parsedUrl.searchParams.get("code_challenge_method") ?? undefined,
+                    });
+                    const validated = await oauth.validateAuthorizeRequest({
+                        responseType: parsed.response_type,
+                        clientId: parsed.client_id,
+                        redirectUri: parsed.redirect_uri,
+                        scope: parsed.scope,
+                        state: parsed.state,
+                        codeChallenge: parsed.code_challenge,
+                        codeChallengeMethod: parsed.code_challenge_method,
+                    });
+                    const web = webUrl();
+                    if (web) {
+                        const consentUrl = new URL("/oauth/consent", web);
+                        consentUrl.searchParams.set("client_id", validated.client.clientId);
+                        consentUrl.searchParams.set("redirect_uri", parsed.redirect_uri);
+                        consentUrl.searchParams.set("scope", validated.scope.join(" "));
+                        if (parsed.state)
+                            consentUrl.searchParams.set("state", parsed.state);
+                        if (parsed.code_challenge)
+                            consentUrl.searchParams.set("code_challenge", parsed.code_challenge);
+                        if (parsed.code_challenge_method)
+                            consentUrl.searchParams.set("code_challenge_method", parsed.code_challenge_method);
+                        res.writeHead(302, { location: consentUrl.toString() });
+                        res.end();
+                    }
+                    else {
+                        html(req, res, 200, oauthAuthorizeFormHtml({
+                            clientId: validated.client.clientId,
+                            redirectUri: parsed.redirect_uri,
+                            scope: validated.scope.join(" "),
+                            state: parsed.state ?? "",
+                            codeChallenge: parsed.code_challenge ?? "",
+                            codeChallengeMethod: parsed.code_challenge_method ?? "",
+                        }));
+                    }
+                    return;
+                }
+                if (method === "POST") {
+                    const form = await readFormBody(req);
+                    const parsed = oauthAuthorizeFormSchema.parse(form);
+                    const validated = await oauth.validateAuthorizeRequest({
+                        responseType: parsed.response_type,
+                        clientId: parsed.client_id,
+                        redirectUri: parsed.redirect_uri,
+                        scope: parsed.scope,
+                        state: parsed.state,
+                        codeChallenge: parsed.code_challenge,
+                        codeChallengeMethod: parsed.code_challenge_method,
+                    });
+                    const loginSubject = await oauth.verifyLogin(parsed.username, parsed.password);
+                    if (!loginSubject) {
+                        const web = webUrl();
+                        if (web) {
+                            const consentUrl = new URL("/oauth/consent", web);
+                            consentUrl.searchParams.set("client_id", parsed.client_id);
+                            consentUrl.searchParams.set("redirect_uri", parsed.redirect_uri);
+                            if (parsed.scope)
+                                consentUrl.searchParams.set("scope", parsed.scope);
+                            if (parsed.state)
+                                consentUrl.searchParams.set("state", parsed.state);
+                            if (parsed.code_challenge)
+                                consentUrl.searchParams.set("code_challenge", parsed.code_challenge);
+                            if (parsed.code_challenge_method)
+                                consentUrl.searchParams.set("code_challenge_method", parsed.code_challenge_method);
+                            consentUrl.searchParams.set("error", "Invalid email or password.");
+                            res.writeHead(302, { location: consentUrl.toString() });
+                            res.end();
+                        }
+                        else {
+                            json(req, res, 401, { ok: false, error: "Invalid login" });
+                        }
+                        return;
+                    }
+                    const code = await oauth.issueAuthorizationCode({
+                        clientId: validated.client.clientId,
+                        redirectUri: parsed.redirect_uri,
+                        scope: validated.scope,
+                        subject: loginSubject,
+                        codeChallenge: parsed.code_challenge,
+                        codeChallengeMethod: parsed.code_challenge_method,
+                    });
+                    // Build the full redirect URI with code + state params, then show a
+                    // success page that auto-redirects (handles desktop/mobile deep links
+                    // like obsidian:// where a bare 302 leaves the browser on a blank page).
+                    const callbackUrl = new URL(parsed.redirect_uri);
+                    callbackUrl.searchParams.set("code", code);
+                    if (parsed.state)
+                        callbackUrl.searchParams.set("state", parsed.state);
+                    html(req, res, 200, oauthSuccessHtml({ redirectUri: callbackUrl.toString() }));
+                    return;
+                }
+                json(req, res, 405, { ok: false, error: "Method not allowed" });
+                return;
+            }
+            if (pathname === "/oauth/token") {
+                if (!oauth.isEnabled()) {
+                    json(req, res, 503, {
+                        ok: false,
+                        error: "OAuth is not configured",
+                        detail: "Set BRAINS_OAUTH_CLIENTS and either BRAINS_OAUTH_PASSWORD or SUPABASE_URL + SUPABASE_ANON_KEY",
+                    });
+                    return;
+                }
+                if (method !== "POST") {
+                    json(req, res, 405, { ok: false, error: "Method not allowed" });
+                    return;
+                }
+                const form = oauthTokenFormSchema.parse(await readFormBody(req));
+                const basic = parseBasicClientCredentials(req);
+                const clientId = form.client_id ?? basic?.clientId;
+                const clientSecret = form.client_secret ?? basic?.clientSecret;
+                if (!clientId) {
+                    json(req, res, 400, {
+                        error: "invalid_client",
+                        error_description: "client_id is required",
+                    });
+                    return;
+                }
+                if (form.grant_type === "authorization_code") {
+                    if (!form.code || !form.redirect_uri) {
+                        json(req, res, 400, {
+                            error: "invalid_request",
+                            error_description: "code and redirect_uri are required",
+                        });
+                        return;
+                    }
+                    const token = await oauth.exchangeAuthorizationCode({
+                        code: form.code,
+                        clientId,
+                        clientSecret,
+                        redirectUri: form.redirect_uri,
+                        codeVerifier: form.code_verifier,
+                    });
+                    json(req, res, 200, {
+                        token_type: token.tokenType,
+                        access_token: token.accessToken,
+                        expires_in: token.expiresIn,
+                        refresh_token: token.refreshToken,
+                        scope: token.scope,
+                    });
+                    return;
+                }
+                if (!form.refresh_token) {
+                    json(req, res, 400, {
+                        error: "invalid_request",
+                        error_description: "refresh_token is required",
+                    });
+                    return;
+                }
+                const token = await oauth.refreshAccessToken({
+                    refreshToken: form.refresh_token,
+                    clientId,
+                    clientSecret,
+                });
+                json(req, res, 200, {
+                    token_type: token.tokenType,
+                    access_token: token.accessToken,
+                    expires_in: token.expiresIn,
+                    refresh_token: token.refreshToken,
+                    scope: token.scope,
+                });
+                return;
+            }
+            if (pathname === "/oauth/register") {
+                if (!oauth.hasLoginConfig()) {
+                    json(req, res, 503, { error: "invalid_client_metadata", error_description: "OAuth is not configured" });
+                    return;
+                }
+                if (method !== "POST") {
+                    json(req, res, 405, { ok: false, error: "Method not allowed" });
+                    return;
+                }
+                const body = await readJsonBody(req);
+                const redirectUris = body?.redirect_uris;
+                if (!Array.isArray(redirectUris) || redirectUris.length === 0) {
+                    json(req, res, 400, { error: "invalid_redirect_uri", error_description: "redirect_uris is required" });
+                    return;
+                }
+                try {
+                    const clientInfo = await oauth.registerDynamicClient({
+                        redirectUris: redirectUris,
+                        clientName: typeof body?.client_name === "string"
+                            ? body.client_name
+                            : undefined,
+                    });
+                    json(req, res, 201, {
+                        client_id: clientInfo.clientId,
+                        client_secret_expires_at: 0,
+                        redirect_uris: clientInfo.redirectUris,
+                        token_endpoint_auth_method: clientInfo.tokenEndpointAuthMethod,
+                        grant_types: clientInfo.grantTypes,
+                        response_types: clientInfo.responseTypes,
+                        scope: clientInfo.scope,
+                    });
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : "Registration failed";
+                    json(req, res, 400, { error: "invalid_redirect_uri", error_description: msg });
+                }
+                return;
+            }
+            if (pathname === "/oauth/revoke") {
+                if (!oauth.isEnabled()) {
+                    json(req, res, 503, {
+                        ok: false,
+                        error: "OAuth is not configured",
+                        detail: "Set BRAINS_OAUTH_CLIENTS and either BRAINS_OAUTH_PASSWORD or SUPABASE_URL + SUPABASE_ANON_KEY",
+                    });
+                    return;
+                }
+                if (method !== "POST") {
+                    json(req, res, 405, { ok: false, error: "Method not allowed" });
+                    return;
+                }
+                const form = oauthRevokeFormSchema.parse(await readFormBody(req));
+                const basic = parseBasicClientCredentials(req);
+                const clientId = form.client_id ?? basic?.clientId;
+                const clientSecret = form.client_secret ?? basic?.clientSecret;
+                if (!clientId) {
+                    json(req, res, 400, {
+                        error: "invalid_client",
+                        error_description: "client_id is required",
+                    });
+                    return;
+                }
+                try {
+                    await oauth.revokeToken({
+                        token: form.token,
+                        tokenTypeHint: form.token_type_hint,
+                        clientId,
+                        clientSecret,
+                    });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+                    if (message.includes("unknown client_id")
+                        || message.includes("invalid client credentials")
+                        || message.includes("invalid client")) {
+                        const status = req.headers.authorization?.startsWith("Basic ") ? 401 : 400;
+                        const headers = {};
+                        if (status === 401) {
+                            headers["www-authenticate"] = 'Basic realm="oauth"';
+                        }
+                        json(req, res, status, {
+                            error: "invalid_client",
+                            error_description: "Client authentication failed",
+                        }, headers);
+                        return;
+                    }
+                    if (message.includes("unknown token")
+                        || message.includes("invalid token")
+                        || message.includes("token not found")) {
+                        // RFC 7009 §2.2: respond with 200 and empty body for unknown/invalid tokens
+                        res.writeHead(200, {
+                            "content-type": "application/json; charset=utf-8",
+                            "content-length": "2",
+                            "cache-control": "no-store",
+                        });
+                        res.end("{}");
+                        return;
+                    }
+                    if (message.includes("unsupported token type")) {
+                        json(req, res, 400, {
+                            error: "unsupported_token_type",
+                            error_description: "The authorization server does not support the revocation of the presented token type",
+                        });
+                        return;
+                    }
+                    throw error;
+                }
+                // RFC 7009 §2.2: respond with 200 and empty body on success
+                res.writeHead(200, {
+                    "content-type": "application/json; charset=utf-8",
+                    "content-length": "2",
+                    "cache-control": "no-store",
+                });
+                res.end("{}");
+                return;
+            }
+            if (pathname === "/oauth/signup") {
+                if (!oauth.isEnabled()) {
+                    json(req, res, 503, {
+                        ok: false,
+                        error: "OAuth is not configured",
+                        detail: "Set BRAINS_OAUTH_CLIENTS and SUPABASE_URL + SUPABASE_ANON_KEY",
+                    });
+                    return;
+                }
+                if (method !== "POST") {
+                    json(req, res, 405, { ok: false, error: "Method not allowed" });
+                    return;
+                }
+                const form = await readFormBody(req);
+                const parsed = oauthSignupFormSchema.safeParse(form);
+                if (!parsed.success) {
+                    const firstIssue = parsed.error.issues[0]?.message ?? "Invalid form data";
+                    const displayError = firstIssue.toLowerCase().includes("email") ? "Enter a valid email address." : firstIssue;
+                    const web = webUrl();
+                    if (web) {
+                        const consentUrl = new URL("/oauth/consent", web);
+                        consentUrl.searchParams.set("client_id", form.client_id ?? "");
+                        consentUrl.searchParams.set("redirect_uri", form.redirect_uri ?? "");
+                        if (form.scope)
+                            consentUrl.searchParams.set("scope", form.scope);
+                        if (form.state)
+                            consentUrl.searchParams.set("state", form.state);
+                        if (form.code_challenge)
+                            consentUrl.searchParams.set("code_challenge", form.code_challenge);
+                        if (form.code_challenge_method)
+                            consentUrl.searchParams.set("code_challenge_method", form.code_challenge_method);
+                        consentUrl.searchParams.set("tab", "signup");
+                        consentUrl.searchParams.set("error", displayError);
+                        res.writeHead(302, { location: consentUrl.toString() });
+                        res.end();
+                    }
+                    else {
+                        html(req, res, 400, oauthAuthorizeFormHtml({
+                            clientId: form.client_id ?? "",
+                            redirectUri: form.redirect_uri ?? "",
+                            scope: form.scope ?? "",
+                            state: form.state ?? "",
+                            codeChallenge: form.code_challenge ?? "",
+                            codeChallengeMethod: form.code_challenge_method ?? "",
+                            tab: "signup",
+                            error: displayError,
+                        }));
+                    }
+                    return;
+                }
+                if (parsed.data.password !== parsed.data.confirm_password) {
+                    const web = webUrl();
+                    if (web) {
+                        const consentUrl = new URL("/oauth/consent", web);
+                        consentUrl.searchParams.set("client_id", parsed.data.client_id);
+                        consentUrl.searchParams.set("redirect_uri", parsed.data.redirect_uri);
+                        if (parsed.data.scope)
+                            consentUrl.searchParams.set("scope", parsed.data.scope);
+                        if (parsed.data.state)
+                            consentUrl.searchParams.set("state", parsed.data.state);
+                        if (parsed.data.code_challenge)
+                            consentUrl.searchParams.set("code_challenge", parsed.data.code_challenge);
+                        if (parsed.data.code_challenge_method)
+                            consentUrl.searchParams.set("code_challenge_method", parsed.data.code_challenge_method);
+                        consentUrl.searchParams.set("tab", "signup");
+                        consentUrl.searchParams.set("error", "Passwords do not match.");
+                        res.writeHead(302, { location: consentUrl.toString() });
+                        res.end();
+                    }
+                    else {
+                        html(req, res, 400, oauthAuthorizeFormHtml({
+                            clientId: parsed.data.client_id,
+                            redirectUri: parsed.data.redirect_uri,
+                            scope: parsed.data.scope ?? "",
+                            state: parsed.data.state ?? "",
+                            codeChallenge: parsed.data.code_challenge ?? "",
+                            codeChallengeMethod: parsed.data.code_challenge_method ?? "",
+                            tab: "signup",
+                            error: "Passwords do not match.",
+                        }));
+                    }
+                    return;
+                }
+                // Build a URL back to the consent page for use in two places:
+                //   1. Supabase email redirect_to — where Supabase sends the user after email verification.
+                //      Must be in Supabase's allowed-URL list. Use the web domain (www.usebrains.app) which
+                //      is more likely to be allowlisted than the API domain (lets.usebrains.app).
+                //   2. The "Back to sign in" link on the confirm-email page.
+                // Falls back to the API authorize URL if WEB_URL is not set.
+                const web = webUrl();
+                // Extract parsed fields to locals so TypeScript narrowing works inside closures.
+                const sd = parsed.data;
+                const addOAuthParams = (u) => {
+                    u.searchParams.set("response_type", "code");
+                    u.searchParams.set("client_id", sd.client_id);
+                    u.searchParams.set("redirect_uri", sd.redirect_uri);
+                    if (sd.scope)
+                        u.searchParams.set("scope", sd.scope);
+                    if (sd.state)
+                        u.searchParams.set("state", sd.state);
+                    if (sd.code_challenge)
+                        u.searchParams.set("code_challenge", sd.code_challenge);
+                    if (sd.code_challenge_method)
+                        u.searchParams.set("code_challenge_method", sd.code_challenge_method);
+                };
+                const makeConsentBase = () => web ? new URL("/oauth/consent", web) : new URL("/oauth/authorize", publicBase());
+                const emailRedirectUrl = (() => { const u = makeConsentBase(); addOAuthParams(u); u.searchParams.set("verified", "true"); return u.toString(); })();
+                const backPath = (() => { const u = makeConsentBase(); addOAuthParams(u); return u.pathname + u.search; })();
+                const result = await oauth.signUpWithEmail(parsed.data.email, parsed.data.password, emailRedirectUrl);
+                if (!result.ok) {
+                    if (web) {
+                        const consentUrl = new URL("/oauth/consent", web);
+                        consentUrl.searchParams.set("client_id", parsed.data.client_id);
+                        consentUrl.searchParams.set("redirect_uri", parsed.data.redirect_uri);
+                        if (parsed.data.scope)
+                            consentUrl.searchParams.set("scope", parsed.data.scope);
+                        if (parsed.data.state)
+                            consentUrl.searchParams.set("state", parsed.data.state);
+                        if (parsed.data.code_challenge)
+                            consentUrl.searchParams.set("code_challenge", parsed.data.code_challenge);
+                        if (parsed.data.code_challenge_method)
+                            consentUrl.searchParams.set("code_challenge_method", parsed.data.code_challenge_method);
+                        consentUrl.searchParams.set("tab", "signup");
+                        consentUrl.searchParams.set("error", result.error);
+                        res.writeHead(302, { location: consentUrl.toString() });
+                        res.end();
+                    }
+                    else {
+                        html(req, res, 400, oauthAuthorizeFormHtml({
+                            clientId: parsed.data.client_id,
+                            redirectUri: parsed.data.redirect_uri,
+                            scope: parsed.data.scope ?? "",
+                            state: parsed.data.state ?? "",
+                            codeChallenge: parsed.data.code_challenge ?? "",
+                            codeChallengeMethod: parsed.data.code_challenge_method ?? "",
+                            tab: "signup",
+                            error: result.error,
+                        }));
+                    }
+                    return;
+                }
+                if (web) {
+                    const confirmUrl = new URL("/oauth/confirm-email", web);
+                    confirmUrl.searchParams.set("email", parsed.data.email);
+                    confirmUrl.searchParams.set("back", backPath);
+                    res.writeHead(302, { location: confirmUrl.toString() });
+                    res.end();
+                }
+                else {
+                    html(req, res, 200, signupConfirmHtml({ email: parsed.data.email, backPath }));
+                }
+                return;
+            }
+            if (!isPublicRoute(method, pathname)) {
+                authorization = await authorizeRequest(req, parsedUrl, oauth, supabaseAuth, patStore);
+                if (!authorization) {
+                    unauthorized(res, `${publicBase()}/.well-known/oauth-protected-resource`);
+                    return;
+                }
+                const writeRoute = (method === "POST" && pathname === "/api/v1/pages") ||
+                    (method === "POST" && pathname === "/api/v1/pages/batch") ||
+                    (method === "PUT" && pathname === "/api/v1/page") ||
+                    (method === "PATCH" && pathname === "/api/v1/page") ||
+                    (method === "DELETE" && pathname === "/api/v1/page") ||
+                    (method === "POST" && pathname === "/api/v1/page/move") ||
+                    (method === "POST" && pathname === "/api/v1/audit") ||
+                    (method === "POST" && pathname === "/api/v1/pages/delete-batch") ||
+                    (method === "POST" && pathname === "/api/v1/logs") ||
+                    (method === "POST" && pathname === "/api/v1/import") ||
+                    (method === "POST" && pathname === "/api/v1/export") ||
+                    (method === "POST" && pathname === "/api/v1/import-zip") ||
+                    (method === "POST" && pathname === "/api/v1/import-zip/upload") ||
+                    (method === "POST" && pathname === "/api/v1/purge") ||
+                    (method === "POST" && pathname === "/api/v1/links/extract") ||
+                    (method === "POST" && pathname === "/api/v1/session/bundle") ||
+                    (method === "POST" && pathname.startsWith("/api/v1/tools/")) ||
+                    (method === "POST" && pathname === "/tool") ||
+                    (method === "POST" && pathname === "/chat") ||
+                    (method === "POST" && pathname === "/admin/seed-users") ||
+                    (method === "DELETE" && pathname === "/admin/seed-users") ||
+                    (method === "DELETE" && pathname === "/api/v1/account");
+                const requiredScopes = writeRoute ? ["wiki.write"] : ["wiki.read"];
+                if (!hasRequiredScopes(authorization.scopes, requiredScopes)) {
+                    forbidden(res, requiredScopes);
+                    return;
+                }
+            }
+            // ── Rate limiting ───────────────────────────────────────────────────
+            if (RATE_LIMIT_ENABLED) {
+                const rlClass = classifyRouteForRateLimit(method, pathname);
+                if (rlClass !== null) {
+                    const subject = authorization?.subject ?? req.socket.remoteAddress ?? "unknown";
+                    const rateLimitRemaining = checkRateLimit(rateLimitWindows, `${rlClass}:${subject}`, RATE_LIMITS[rlClass], RATE_LIMIT_WINDOW_MS);
+                    if (rateLimitRemaining !== null) {
+                        const retryAfterSec = Math.max(1, Math.ceil(rateLimitRemaining / 1000));
+                        json(req, res, 429, { ok: false, error: "Rate limit exceeded", retryAfter: retryAfterSec }, { "Retry-After": String(retryAfterSec) });
+                        return;
+                    }
+                }
+            }
+            const requestDrive = await resolveDriveForAuthorization(authorization);
+            const requestUserId = authorization && shouldUseUserScopedStorage(authorization.mode)
+                ? authorization.subject
+                : "";
+            const requestUserAccessLevel = await getUserAccessLevel(requestUserId);
+            const requestAccessCtx = { userAccessLevel: requestUserAccessLevel };
+            if (method === "GET" && pathname === "/") {
+                json(req, res, 200, {
+                    ok: true,
+                    service: "brains",
+                    architecture: "api-first",
+                    endpoints: [
+                        "GET /cb",
+                        "GET /connect",
+                        "GET /openapi.json",
+                        "GET /.well-known/openapi.json",
+                        "GET /.well-known/oauth-authorization-server",
+                        "GET /.well-known/oauth-protected-resource",
+                        "GET /oauth/authorize",
+                        "POST /oauth/authorize",
+                        "POST /oauth/token",
+                        "POST /oauth/revoke",
+                        "GET /api/v1/health",
+                        "GET /api/v1/launch/status",
+                        "GET /api/v1/pages",
+                        "POST /api/v1/pages",
+                        "GET /api/v1/pages/{name}/backlinks",
+                        "GET /api/v1/pages/{name}/related",
+                        "GET /api/v1/pages/{name}/history",
+                        "GET /api/v1/page",
+                        "PUT /api/v1/page",
+                        "PATCH /api/v1/page",
+                        "DELETE /api/v1/page",
+                        "POST /api/v1/page/move",
+                        "POST /api/v1/audit",
+                        "POST /api/v1/pages/delete-batch",
+                        "POST /api/v1/links/extract",
+                        "POST /api/v1/links/suggest",
+                        "GET /api/v1/search",
+                        "POST /api/v1/logs",
+                        "POST /api/v1/import",
+                        "POST /api/v1/export",
+                        "GET /api/v1/export/download",
+                        "POST /api/v1/import-zip",
+                        "POST /api/v1/import-zip/upload",
+                        "GET /api/v1/jobs/{id}",
+                        "GET /api/v1/jobs/{id}/download",
+                        "POST /api/v1/purge",
+                        "GET /api/session-bundle",
+                        "GET /api/v1/session/bundle",
+                        "POST /api/v1/session/bundle",
+                        "GET /api/v1/tools",
+                        "POST /api/v1/tools/{name}",
+                        "GET /api/v1/metrics",
+                        "GET /metrics-ui",
+                        "POST /api/v1/tokens",
+                        "GET /api/v1/tokens",
+                        "DELETE /api/v1/tokens/{id}",
+                        "DELETE /api/v1/account",
+                    ],
+                    compatibility: {
+                        legacyRoutes: ["GET /tools", "POST /tool", "POST /chat", "GET /chat-ui", "GET /healthz"],
+                        mcp: "MCP transport remains available, but HTTP API is the primary integration surface.",
+                    },
+                });
+                return;
+            }
+            if (method === "GET" && pathname === "/cb") {
+                html(req, res, 200, oauthCallbackHtml({
+                    code: parsedUrl.searchParams.get("code") ?? undefined,
+                    state: parsedUrl.searchParams.get("state") ?? undefined,
+                    error: parsedUrl.searchParams.get("error") ?? undefined,
+                    errorDescription: parsedUrl.searchParams.get("error_description") ?? undefined,
+                }));
+                return;
+            }
+            if (method === "GET" && pathname === "/connect") {
+                const resolvedBase = publicBase();
+                const base = resolvedBase !== `http://localhost:${port}`
+                    ? resolvedBase
+                    : `${req.headers["x-forwarded-proto"] ?? "https"}://${req.headers.host}`;
+                const clientIds = new Set(oauth.getClientConfigs().map((c) => c.clientId));
+                html(req, res, 200, connectPageHtml(base, clientIds));
+                return;
+            }
+            if (method === "GET" && pathname === "/chat-ui") {
+                html(req, res, 200, chatUiHtml());
+                return;
+            }
+            if (method === "POST" && pathname === "/api/inbound-email") {
+                let body = "";
+                req.on("data", (chunk) => { body += chunk; });
+                await new Promise((resolve) => req.on("end", resolve));
+                let event;
+                try {
+                    event = JSON.parse(body);
+                }
+                catch {
+                    json(req, res, 400, { error: "Invalid JSON" });
+                    return;
+                }
+                if (event.type !== "email.received") {
+                    json(req, res, 200, { ok: true, skipped: true });
+                    return;
+                }
+                const emailId = event.data?.email_id;
+                if (!emailId) {
+                    json(req, res, 400, { error: "Missing email_id" });
+                    return;
+                }
+                const resendKey = process.env.RESEND_API_KEY;
+                let text = null;
+                let html_body = null;
+                if (resendKey) {
+                    try {
+                        const emailRes = await fetch(`https://api.resend.com/emails/receiving/${emailId}`, {
+                            headers: { Authorization: `Bearer ${resendKey}` },
+                            signal: AbortSignal.timeout(8000),
+                        });
+                        if (emailRes.ok) {
+                            const full = await emailRes.json();
+                            text = full.text ?? null;
+                            html_body = full.html ?? null;
+                        }
+                    }
+                    catch { /* forward without body */ }
+                }
+                const webhookUrl = process.env.PAPERCLIP_WEBHOOK_URL;
+                const webhookSecret = process.env.PAPERCLIP_WEBHOOK_SECRET;
+                if (!webhookUrl || !webhookSecret) {
+                    json(req, res, 503, { error: "Webhook not configured" });
+                    return;
+                }
+                const enriched = {
+                    type: event.type,
+                    email_id: emailId,
+                    from: event.data?.from,
+                    to: event.data?.to,
+                    subject: event.data?.subject,
+                    text,
+                    html: html_body,
+                };
+                const fwdRes = await fetch(webhookUrl, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", Authorization: `Bearer ${webhookSecret}` },
+                    body: JSON.stringify({ payload: enriched }),
+                    signal: AbortSignal.timeout(10000),
+                });
+                if (!fwdRes.ok) {
+                    const detail = await fwdRes.text().catch(() => "");
+                    json(req, res, 502, { error: "Upstream error", status: fwdRes.status, detail });
+                    return;
+                }
+                json(req, res, 200, { ok: true });
+                return;
+            }
+            if (method === "GET" && pathname === "/healthz") {
+                const result = await executeToolCall(requestDrive, "health_check", {}, requestUserId);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "GET" && pathname === "/api/v1/health") {
+                const result = await executeToolCall(requestDrive, "health_check", {}, requestUserId);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "GET" && pathname === "/api/v1/launch/status") {
+                const status = await getLaunchStatus(drive);
+                json(req, res, 200, status, { "cache-control": "public, max-age=60" });
+                return;
+            }
+            if (method === "GET" && pathname === "/api/v1/account/limits") {
+                const { currentCount, limit } = await resolvePageLimitContext(requestUserId);
+                const godMode = !requestUserId || isGodModeSubject(requestUserId);
+                const tier = godMode ? "admin" : (currentCount > 0 ? "beta" : "free");
+                json(req, res, 200, { ok: true, tier, pageCount: currentCount, pageLimit: limit });
+                return;
+            }
+            if (method === "DELETE" && pathname === "/api/v1/account") {
+                if (authorization.mode !== "supabase" && authorization.mode !== "oauth") {
+                    json(req, res, 403, { ok: false, error: "Account deletion requires a user session (Supabase or OAuth auth)" });
+                    return;
+                }
+                const userId = authorization.subject;
+                const supabaseUrl = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+                const serviceRoleKey = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+                if (!supabaseUrl || !serviceRoleKey) {
+                    json(req, res, 500, { ok: false, error: "Server not configured for account deletion" });
+                    return;
+                }
+                // Guard against concurrent or duplicate deletion requests
+                const pendingCheckUrl = `${supabaseUrl}/rest/v1/pending_deletions?user_id=eq.${encodeURIComponent(userId)}&completed_at=is.null&limit=1`;
+                const pendingCheckRes = await fetch(pendingCheckUrl, {
+                    headers: { apikey: serviceRoleKey, authorization: `Bearer ${serviceRoleKey}`, accept: "application/json" },
+                });
+                const existingRows = pendingCheckRes.ok
+                    ? (await pendingCheckRes.json().catch(() => []))
+                    : [];
+                if (existingRows.length > 0) {
+                    json(req, res, 409, { ok: false, error: "Account deletion already in progress" });
+                    return;
+                }
+                const result = await deleteAccount(userId, { tokenStore, supabaseUrl, serviceRoleKey });
+                if (!result.completed) {
+                    // Some cascade steps failed — do NOT report success, or the client
+                    // would sign the user out while their data is only partially deleted.
+                    json(req, res, 500, { ok: false, error: "Account deletion partially failed", details: result });
+                    return;
+                }
+                json(req, res, 200, { ok: true, ...result });
+                return;
+            }
+            // ─────────────────────────────────────────────────────────────────────
+            if (method === "GET" && pathname === "/api/v1/metrics") {
+                const win = parsedUrl.searchParams.get("window") ?? "1h";
+                if (!isValidWindow(win)) {
+                    json(req, res, 400, { ok: false, error: "Invalid window. Use: 1h, 6h, 24h, or 7d" });
+                    return;
+                }
+                const metrics = await queryMetrics(win);
+                json(req, res, 200, metrics);
+                return;
+            }
+            if (method === "GET" && pathname === "/metrics-ui") {
+                html(req, res, 200, metricsUiHtml());
+                return;
+            }
+            if (method === "GET" && pathname === "/tools") {
+                json(req, res, 200, {
+                    ok: true,
+                    tools: getVisibleTools().map((t) => ({ name: t.name, description: t.description })),
+                });
+                return;
+            }
+            if (method === "GET" && pathname === "/api/v1/tools") {
+                json(req, res, 200, {
+                    ok: true,
+                    tools: getVisibleTools().map((t) => ({
+                        name: t.name,
+                        description: t.description,
+                        inputSchema: t.inputSchema,
+                    })),
+                });
+                return;
+            }
+            if (method === "POST" && pathname.startsWith("/api/v1/tools/")) {
+                const toolName = decodeURIComponent(pathname.slice("/api/v1/tools/".length));
+                if (!toolName) {
+                    json(req, res, 400, { ok: false, error: "Tool name is required" });
+                    return;
+                }
+                const body = toolInvokeHttpSchema.parse(await readJsonBody(req));
+                const result = await executeToolCall(requestDrive, toolName, body.arguments ?? {}, requestUserId, requestAccessCtx);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "GET" && pathname === "/api/v1/pages") {
+                const result = await executeToolCall(requestDrive, "list_pages", {
+                    tag: parsedUrl.searchParams.get("tag") ?? undefined,
+                    status: parsedUrl.searchParams.get("status") ?? undefined,
+                    folder: parsedUrl.searchParams.get("folder") ?? undefined,
+                    compact: parsedUrl.searchParams.get("compact") === "true" ? true : undefined,
+                    limit: coerceNumber(parsedUrl.searchParams.get("limit")) ?? undefined,
+                    offset: coerceNumber(parsedUrl.searchParams.get("offset")) ?? undefined,
+                }, requestUserId, requestAccessCtx);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            const backlinksMatch = method === "GET"
+                ? pathname.match(/^\/api\/v1\/pages\/(.+)\/backlinks$/)
+                : null;
+            if (backlinksMatch) {
+                const name = decodeURIComponent(backlinksMatch[1] ?? "");
+                const normalizedName = name.endsWith(".md") ? name : `${name}.md`;
+                const overrideUserId = parsedUrl.searchParams.get("userId");
+                let effectiveUserId = requestUserId;
+                if (overrideUserId !== null && overrideUserId !== requestUserId) {
+                    if (authorization?.mode !== "api-key") {
+                        json(req, res, 403, { ok: false, error: "userId override requires api-key authentication" });
+                        return;
+                    }
+                    effectiveUserId = overrideUserId;
+                }
+                const result = await getPostgresSearchIndex().getBacklinks(normalizedName, effectiveUserId, isHiveModeEnabled() ? requestAccessCtx.userAccessLevel : undefined);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            const relatedMatch = method === "GET"
+                ? pathname.match(/^\/api\/v1\/pages\/(.+)\/related$/)
+                : null;
+            if (relatedMatch) {
+                const name = decodeURIComponent(relatedMatch[1] ?? "");
+                const normalizedName = name.endsWith(".md") ? name : `${name}.md`;
+                const overrideUserId = parsedUrl.searchParams.get("userId");
+                let effectiveUserId = requestUserId;
+                if (overrideUserId !== null && overrideUserId !== requestUserId) {
+                    if (authorization?.mode !== "api-key") {
+                        json(req, res, 403, { ok: false, error: "userId override requires api-key authentication" });
+                        return;
+                    }
+                    effectiveUserId = overrideUserId;
+                }
+                const result = await getPostgresSearchIndex().getRelatedPages(normalizedName, effectiveUserId, isHiveModeEnabled() ? requestAccessCtx.userAccessLevel : undefined);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            const historyMatch = method === "GET"
+                ? pathname.match(/^\/api\/v1\/pages\/(.+)\/history$/)
+                : null;
+            if (historyMatch) {
+                const name = decodeURIComponent(historyMatch[1] ?? "");
+                const normalizedName = name.endsWith(".md") ? name : `${name}.md`;
+                const result = await executeToolCall(requestDrive, "list_page_history", { name: normalizedName }, requestUserId);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/pages") {
+                const body = createPageHttpSchema.parse(await readJsonBody(req));
+                const result = await executeToolCall(requestDrive, "create_page", body, requestUserId);
+                res._logExtras = { tool: "create_page" };
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/pages/batch") {
+                const body = createPagesHttpSchema.parse(await readJsonBody(req));
+                if (batchInFlight >= CONCURRENCY_LIMIT_BATCH) {
+                    json(req, res, 503, { ok: false, error: "Server busy — try again shortly", retryAfter: 5 }, { "Retry-After": "5" });
+                    return;
+                }
+                batchInFlight++;
+                try {
+                    const outcome = await raceWithTimeout(executeToolCall(requestDrive, "create_pages", body, requestUserId), TIMEOUT_DEFAULT_MS);
+                    if (outcome === TIMEOUT_SENTINEL) {
+                        if (!res.headersSent)
+                            json(req, res, 504, { ok: false, error: "Request timed out" });
+                        return;
+                    }
+                    res._logExtras = {
+                        tool: "create_pages",
+                        pageCount: body.pages.length,
+                    };
+                    json(req, res, 200, { ok: true, result: outcome });
+                }
+                finally {
+                    batchInFlight--;
+                }
+                return;
+            }
+            if (method === "GET" && pathname === "/api/v1/page") {
+                const name = parsedUrl.searchParams.get("name");
+                if (!name) {
+                    json(req, res, 400, { ok: false, error: "Query parameter 'name' is required" });
+                    return;
+                }
+                const result = await executeToolCall(requestDrive, "read_page", { name }, requestUserId, requestAccessCtx);
+                // Conditional GET: clients (e.g. the Obsidian plugin) poll an open page
+                // for freshness. When they send If-None-Match with the revision they
+                // already hold and it still matches, answer 304 with no body so the poll
+                // is a tiny request instead of a full content download.
+                // (Future optimization: resolve the revision from the index to also skip
+                // the read above; the bandwidth win is the dominant cost today.)
+                const revision = result?.revision;
+                if (revision) {
+                    const stripTag = (v) => v.trim().replace(/^W\//, "").replace(/^"|"$/g, "");
+                    const ifNoneMatch = req.headers["if-none-match"];
+                    const matched = typeof ifNoneMatch === "string" &&
+                        ifNoneMatch.split(",").some((tag) => stripTag(tag) === revision);
+                    if (matched) {
+                        res.writeHead(304, { etag: `"${revision}"`, "cache-control": "no-store" });
+                        res.end();
+                        return;
+                    }
+                }
+                // Phase 4: record implicit relevance signal if this read follows a recent
+                // search. Only on a real 200 read — 304 polls must not spam this signal.
+                const supabaseUrl = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+                const serviceRoleKey = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+                maybeRecordRelevanceSignal(requestUserId, name, supabaseUrl, serviceRoleKey);
+                json(req, res, 200, { ok: true, result }, revision ? { etag: `"${revision}"` } : undefined);
+                return;
+            }
+            if (method === "PUT" && pathname === "/api/v1/page") {
+                const body = updatePageHttpSchema.parse(await readJsonBody(req));
+                const result = await executeToolCall(requestDrive, "update_page", body, requestUserId);
+                res._logExtras = { tool: "update_page" };
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "PATCH" && pathname === "/api/v1/page") {
+                const body = patchPageHttpSchema.parse(await readJsonBody(req));
+                const result = await executeToolCall(requestDrive, "patch_page", body, requestUserId);
+                res._logExtras = { tool: "patch_page" };
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/page/move") {
+                const body = movePageHttpSchema.parse(await readJsonBody(req));
+                const normalizedName = body.name.endsWith(".md") ? body.name : `${body.name}.md`;
+                const result = await executeToolCall(requestDrive, "move_page", { ...body, name: normalizedName }, requestUserId);
+                res._logExtras = { tool: "move_page" };
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/audit") {
+                const body = auditIndexHttpSchema.parse(await readJsonBody(req));
+                const result = await executeToolCall(requestDrive, "audit_index", body, requestUserId);
+                res._logExtras = { tool: "audit_index" };
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "DELETE" && pathname === "/api/v1/page") {
+                const name = parsedUrl.searchParams.get("name");
+                const confirmParam = parsedUrl.searchParams.get("confirm");
+                const reason = parsedUrl.searchParams.get("reason") ?? undefined;
+                if (!name) {
+                    json(req, res, 400, { ok: false, error: "Query parameter 'name' is required" });
+                    return;
+                }
+                const confirm = confirmParam === "true";
+                const result = await executeToolCall(requestDrive, "delete_page", { name, confirm, ...(reason ? { reason } : {}) }, requestUserId);
+                res._logExtras = { tool: "delete_page" };
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/pages/delete-batch") {
+                const body = await readJsonBody(req);
+                const result = await executeToolCall(requestDrive, "batch_delete_pages", body, requestUserId);
+                res._logExtras = { tool: "batch_delete_pages" };
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            // ── Webhook Rules REST endpoints ──────────────────────────────────────────
+            if (method === "GET" && pathname === "/api/v1/webhooks") {
+                const result = await executeToolCall(requestDrive, "list_webhooks", {}, requestUserId);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/webhooks") {
+                const body = await readJsonBody(req);
+                const result = await executeToolCall(requestDrive, "set_webhook", body, requestUserId);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "DELETE" && pathname.startsWith("/api/v1/webhooks/")) {
+                const id = pathname.slice("/api/v1/webhooks/".length);
+                if (!id) {
+                    json(req, res, 400, { ok: false, error: "Webhook ID is required" });
+                    return;
+                }
+                const result = await executeToolCall(requestDrive, "remove_webhook", { id }, requestUserId);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname.endsWith("/patterns") && pathname.startsWith("/api/v1/webhooks/")) {
+                const id = pathname.slice("/api/v1/webhooks/".length, -"/patterns".length);
+                const body = await readJsonBody(req);
+                if (!id || !body.pattern) {
+                    json(req, res, 400, { ok: false, error: "Webhook ID and pattern are required" });
+                    return;
+                }
+                const result = await executeToolCall(requestDrive, "add_webhook_pattern", { id, pattern: body.pattern }, requestUserId);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            // ── Personal Access Token (PAT) management ──────────────────────────────
+            if (pathname === "/api/v1/tokens" || pathname.startsWith("/api/v1/tokens/")) {
+                // PAT routes require a real user identity (supabase, oauth, or pat mode).
+                if (!authorization ||
+                    (authorization.mode !== "supabase" &&
+                        authorization.mode !== "oauth" &&
+                        authorization.mode !== "pat")) {
+                    json(req, res, 403, {
+                        ok: false,
+                        error: "Forbidden",
+                        detail: "PAT management requires user authentication (OAuth or Supabase login).",
+                    });
+                    return;
+                }
+                const patSubject = authorization.subject;
+                if (method === "GET" && pathname === "/api/v1/tokens") {
+                    void patStore.pruneExpired().catch(() => { });
+                    const pats = await patStore.list(patSubject);
+                    json(req, res, 200, { ok: true, tokens: pats });
+                    return;
+                }
+                if (method === "POST" && pathname === "/api/v1/tokens") {
+                    const body = createPATHttpSchema.parse(await readJsonBody(req));
+                    const scopes = body.scopes ?? ["wiki.read", "wiki.write"];
+                    // undefined → default (30 days); null → never expires; number → that many days
+                    const expiresInDays = body.expiresInDays !== undefined ? body.expiresInDays : PAT_EXPIRY_DAYS_DEFAULT;
+                    const expiresAt = expiresInDays === null ? null : Date.now() + expiresInDays * 24 * 60 * 60 * 1000;
+                    void patStore.pruneExpired().catch(() => { });
+                    const issued = await patStore.create(patSubject, body.label, scopes, expiresAt);
+                    json(req, res, 201, {
+                        ok: true,
+                        id: issued.id,
+                        token: issued.token,
+                        label: issued.label,
+                        scopes: issued.scopes,
+                        expiresAt: issued.expiresAt,
+                        createdAt: issued.createdAt,
+                    });
+                    return;
+                }
+                if (method === "DELETE" && pathname.startsWith("/api/v1/tokens/")) {
+                    const patId = pathname.slice("/api/v1/tokens/".length);
+                    if (!patId) {
+                        json(req, res, 400, { ok: false, error: "PAT id is required" });
+                        return;
+                    }
+                    await patStore.revoke(patId, patSubject);
+                    res.writeHead(204, { "cache-control": "no-store" });
+                    res.end();
+                    return;
+                }
+                json(req, res, 405, { ok: false, error: "Method not allowed" });
+                return;
+            }
+            if (method === "GET" && pathname === "/api/v1/search") {
+                const query = parsedUrl.searchParams.get("query");
+                if (!query) {
+                    json(req, res, 400, { ok: false, error: "Query parameter 'query' is required" });
+                    return;
+                }
+                const result = await executeToolCall(requestDrive, "search_pages", {
+                    query,
+                    tag: parsedUrl.searchParams.get("tag") ?? undefined,
+                    folder: parsedUrl.searchParams.get("folder") ?? undefined,
+                    maxCandidates: coerceNumber(parsedUrl.searchParams.get("maxCandidates")) ?? undefined,
+                    maxResults: coerceNumber(parsedUrl.searchParams.get("maxResults")) ?? undefined,
+                    maxConcurrency: coerceNumber(parsedUrl.searchParams.get("maxConcurrency")) ?? undefined,
+                }, requestUserId, requestAccessCtx);
+                // Attach search-specific fields for the request logging middleware.
+                const sr = result;
+                const durationMs = Date.now() - startTime;
+                res._logExtras = {
+                    backend: sr.backend,
+                    queryMs: sr.timings?.queryMs,
+                    syncMs: sr.timings?.syncMs,
+                    zeroResults: sr.count === 0,
+                    resultCount: sr.count,
+                    queryText: query,
+                };
+                // Phase 4: slow-query alert + relevance signal correlation tracking.
+                recordSearchLatency(durationMs);
+                if (requestUserId && sr.results) {
+                    recordSearch(requestUserId, query, sr.results.map((r) => r.name));
+                }
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/logs") {
+                const body = appendLogHttpSchema.parse(await readJsonBody(req));
+                const result = await executeToolCall(requestDrive, "append_log", body, requestUserId);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/links/extract") {
+                const body = extractLinksHttpSchema.parse(await readJsonBody(req));
+                const tags = (body.tags ?? []).map((tag) => tag.trim()).filter((tag) => tag.length > 0);
+                const folder = body.folder?.trim();
+                if (tags.length === 0 && !folder) {
+                    json(req, res, 400, { ok: false, error: "At least one filter is required: tags or folder" });
+                    return;
+                }
+                let effectiveUserId = requestUserId;
+                if (body.userId !== undefined && body.userId !== requestUserId) {
+                    if (authorization?.mode !== "api-key") {
+                        json(req, res, 403, { ok: false, error: "userId override requires api-key authentication" });
+                        return;
+                    }
+                    effectiveUserId = body.userId;
+                }
+                const result = await getPostgresSearchIndex().extractLinksForStalePages({
+                    tags,
+                    folder,
+                    userId: effectiveUserId,
+                });
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/links/suggest") {
+                const body = suggestLinksHttpSchema.parse(await readJsonBody(req));
+                const tags = (body.tags ?? []).map((tag) => tag.trim()).filter((tag) => tag.length > 0);
+                const folder = body.folder?.trim();
+                if (tags.length === 0 && !folder) {
+                    json(req, res, 400, { ok: false, error: "At least one filter is required: tags or folder" });
+                    return;
+                }
+                const result = await executeToolCall(requestDrive, "suggest_links", { tags, folder, maxPages: body.maxPages }, requestUserId, requestAccessCtx);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/import") {
+                const body = importBrainSourceHttpSchema.parse(await readJsonBody(req));
+                if (importInFlight >= CONCURRENCY_LIMIT_IMPORT) {
+                    json(req, res, 503, { ok: false, error: "Server busy — try again shortly", retryAfter: 5 }, { "Retry-After": "5" });
+                    return;
+                }
+                importInFlight++;
+                try {
+                    const outcome = await raceWithTimeout(executeToolCall(requestDrive, "import_brain_source", body), TIMEOUT_IMPORT_MS);
+                    if (outcome === TIMEOUT_SENTINEL) {
+                        if (!res.headersSent)
+                            json(req, res, 504, { ok: false, error: "Request timed out" });
+                        return;
+                    }
+                    json(req, res, 200, { ok: true, result: outcome });
+                }
+                finally {
+                    importInFlight--;
+                }
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/export") {
+                const body = exportWikiHttpSchema.parse(await readJsonBody(req));
+                const result = await executeToolCall(requestDrive, "export_wiki", body);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "GET" && pathname === "/api/v1/export/download") {
+                const folder = parsedUrl.searchParams.get("folder")?.trim() || undefined;
+                const tagsParam = parsedUrl.searchParams.get("tags");
+                const tags = tagsParam
+                    ? tagsParam.split(",").map((t) => t.trim()).filter(Boolean)
+                    : undefined;
+                const includeSystemRaw = parsedUrl.searchParams.get("includeSystem");
+                const includeSystem = includeSystemRaw ? includeSystemRaw.toLowerCase() === "true" : false;
+                if (includeSystemRaw && includeSystemRaw.toLowerCase() !== "true" && includeSystemRaw.toLowerCase() !== "false") {
+                    json(req, res, 400, { ok: false, error: "Invalid includeSystem query param; expected true or false" });
+                    return;
+                }
+                const sinceParam = parsedUrl.searchParams.get("since")?.trim() || undefined;
+                if (sinceParam && isNaN(new Date(sinceParam).getTime())) {
+                    json(req, res, 400, { ok: false, error: "Invalid 'since' param — expected ISO 8601 datetime, e.g. 2026-05-15T00:00:00Z" });
+                    return;
+                }
+                // Async job: avoids Railway 30s edge timeout on large wikis (500+ pages).
+                // Client polls /api/v1/jobs/{id} then downloads from /api/v1/jobs/{id}/download.
+                const job = asyncJobRegistry.create("export");
+                json(req, res, 202, {
+                    ok: true,
+                    jobId: job.id,
+                    status: "queued",
+                    pollUrl: `/api/v1/jobs/${job.id}`,
+                    downloadUrl: `/api/v1/jobs/${job.id}/download`,
+                });
+                const capturedDrive = requestDrive;
+                const capturedUserId = requestUserId;
+                void (async () => {
+                    asyncJobRegistry.update(job.id, { status: "running", progress: { processed: 0, total: 0, phase: "exporting" } });
+                    try {
+                        const result = await buildExportZip(capturedDrive, {
+                            includeSystem,
+                            folder,
+                            tags,
+                            changedAfter: sinceParam,
+                            userId: capturedUserId,
+                        });
+                        const fileName = sinceParam
+                            ? `wiki-delta-${sinceParam.replace(/[:.]/g, "-")}.zip`
+                            : `wiki-export-${result.generatedAt.replace(/:/g, "-")}.zip`;
+                        asyncJobRegistry.setBinary(job.id, result.buffer, "application/zip", fileName);
+                        asyncJobRegistry.update(job.id, {
+                            status: "done",
+                            completedAt: new Date().toISOString(),
+                            progress: { processed: result.pageCount, total: result.pageCount, phase: "done" },
+                            result: {
+                                pageCount: result.pageCount,
+                                skippedCount: result.skippedCount,
+                                generatedAt: result.generatedAt,
+                                ...(result.since ? { since: result.since } : {}),
+                                downloadUrl: `/api/v1/jobs/${job.id}/download`,
+                                fileName,
+                            },
+                        });
+                    }
+                    catch (err) {
+                        asyncJobRegistry.update(job.id, {
+                            status: "failed",
+                            completedAt: new Date().toISOString(),
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                })();
+                return;
+            }
+            if (method === "GET" && pathname === "/api/v1/session/bundle") {
+                const tagsParam = parsedUrl.searchParams.get("tags");
+                const folderParam = parsedUrl.searchParams.get("folder") ?? undefined;
+                const tagFilter = tagsParam ? tagsParam.split(",").map((t) => t.trim()).filter(Boolean) : undefined;
+                if ((!tagFilter || tagFilter.length === 0) && !folderParam) {
+                    json(req, res, 400, { ok: false, error: "At least one of 'tags' or 'folder' query params is required" });
+                    return;
+                }
+                // Delegates to pullSessionBundle so this endpoint shares the Postgres-indexed
+                // tag lookup with the MCP tool path. The previous inline scan read every .md
+                // file just to inspect frontmatter — fine on small wikis but causes a 502
+                // (Railway 90s edge timeout) once the wiki passes a few hundred pages.
+                const result = await pullSessionBundle(requestDrive, {
+                    tags: tagFilter && tagFilter.length > 0 ? tagFilter : undefined,
+                    folder: folderParam,
+                    maxBytes: 150_000,
+                    maxPages: 50,
+                    includeSystem: false,
+                }, requestUserId, requestAccessCtx);
+                if (!result.ok) {
+                    json(req, res, 500, { ok: false, error: result.error ?? "Failed to build session bundle" });
+                    return;
+                }
+                const bundle = result.bundle ?? "";
+                const pages = result.pages ?? [];
+                const sessionToken = randomUUID();
+                const bodyBuf = Buffer.from(bundle, "utf8");
+                const { buf: outBuf, encoding: bundleEncoding } = compressIfNeeded(req, "text/plain", bodyBuf);
+                const bundleHeaders = {
+                    "Content-Type": "text/plain; charset=utf-8",
+                    "Content-Length": String(outBuf.length),
+                    "X-Page-Count": String(pages.length),
+                    "X-Session-Token": sessionToken,
+                };
+                if (bundleEncoding) {
+                    bundleHeaders["Content-Encoding"] = bundleEncoding;
+                    bundleHeaders["Vary"] = "Accept-Encoding";
+                }
+                res.writeHead(200, bundleHeaders);
+                res.end(outBuf);
+                return;
+            }
+            if (method === "GET" && pathname === "/api/session-bundle") {
+                // Collect tags[] array params and/or comma-separated tags param
+                const tagsArrayParam = parsedUrl.searchParams.getAll("tags[]");
+                const tagsParam = parsedUrl.searchParams.get("tags");
+                const folderParam = parsedUrl.searchParams.get("folder") ?? undefined;
+                const maxBytesParam = parsedUrl.searchParams.get("maxBytes");
+                const maxBytes = maxBytesParam ? parseInt(maxBytesParam, 10) : 150_000;
+                const tagFilter = [
+                    ...tagsArrayParam,
+                    ...(tagsParam ? tagsParam.split(",").map((t) => t.trim()).filter(Boolean) : []),
+                ];
+                if (tagFilter.length === 0 && !folderParam) {
+                    json(req, res, 400, { ok: false, error: "At least one of 'tags[]', 'tags', or 'folder' query params is required" });
+                    return;
+                }
+                const result = await pullSessionBundle(requestDrive, {
+                    tags: tagFilter.length > 0 ? tagFilter : undefined,
+                    folder: folderParam,
+                    maxBytes: isNaN(maxBytes) ? 150_000 : maxBytes,
+                    maxPages: 50,
+                    includeSystem: false,
+                }, requestUserId, requestAccessCtx);
+                if (!result.ok) {
+                    json(req, res, 500, { ok: false, error: result.error ?? "Failed to build session bundle" });
+                    return;
+                }
+                const bundle = result.bundle ?? "";
+                const pages = result.pages ?? [];
+                const sessionToken = randomUUID();
+                const bodyBuf = Buffer.from(bundle, "utf8");
+                const { buf: outBuf, encoding: bundleEncoding } = compressIfNeeded(req, "text/plain", bodyBuf);
+                const bundleHeaders = {
+                    "Content-Type": "text/plain; charset=utf-8",
+                    "Content-Length": String(outBuf.length),
+                    "X-Page-Count": String(pages.length),
+                    "X-Session-Token": sessionToken,
+                };
+                if (bundleEncoding) {
+                    bundleHeaders["Content-Encoding"] = bundleEncoding;
+                    bundleHeaders["Vary"] = "Accept-Encoding";
+                }
+                res.writeHead(200, bundleHeaders);
+                res.end(outBuf);
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/session/bundle") {
+                const rawBody = await readBody(req);
+                let bundlePages;
+                try {
+                    bundlePages = parseBundle(rawBody);
+                }
+                catch {
+                    json(req, res, 400, { ok: false, error: "Invalid bundle format" });
+                    return;
+                }
+                // Delegates to pushSessionBundle so this endpoint writes through Postgres the
+                // same way the MCP tool path does. The previous inline loop wrote only to
+                // Storage, which left pushed content invisible to read_page/patch_page once
+                // those went DB-primary (BRA-1813) — see open-loop-session-bundle-postgres-writethrough.
+                // includeSystem:true preserves this endpoint's prior no-skip behavior.
+                const result = await pushSessionBundle(requestDrive, {
+                    pages: bundlePages,
+                    conflictStrategy: "overwrite",
+                    includeSystem: true,
+                }, requestUserId);
+                const errors = result.errors ?? [];
+                const response = {
+                    ok: errors.length === 0,
+                    updated: Number(result.updated ?? 0),
+                    created: Number(result.created ?? 0),
+                };
+                if (errors.length > 0) {
+                    response.failed = errors.map((e) => ({ name: e.path, error: e.reason }));
+                }
+                json(req, res, 200, response);
+                return;
+            }
+            if (method === "GET" && /^\/api\/v1\/jobs\/[^/]+$/.test(pathname)) {
+                const jobId = pathname.split("/").pop() ?? "";
+                const job = asyncJobRegistry.get(jobId);
+                if (!job) {
+                    json(req, res, 404, { ok: false, error: "Job not found or expired" });
+                    return;
+                }
+                json(req, res, 200, { ok: true, job });
+                return;
+            }
+            if (method === "GET" && /^\/api\/v1\/jobs\/[^/]+\/download$/.test(pathname)) {
+                const parts = pathname.split("/");
+                const jobId = parts[parts.length - 2] ?? "";
+                const job = asyncJobRegistry.get(jobId);
+                if (!job) {
+                    json(req, res, 404, { ok: false, error: "Job not found or expired" });
+                    return;
+                }
+                if (job.status !== "done") {
+                    json(req, res, 409, { ok: false, error: `Job is ${job.status} — poll /api/v1/jobs/${jobId} until status is 'done'` });
+                    return;
+                }
+                const binary = asyncJobRegistry.getBinary(jobId);
+                if (!binary) {
+                    json(req, res, 404, { ok: false, error: "Binary result not available (job may have expired)" });
+                    return;
+                }
+                res.writeHead(200, {
+                    "Content-Type": binary.contentType,
+                    "Content-Disposition": `attachment; filename="${binary.filename}"`,
+                    "Content-Length": String(binary.buffer.length),
+                    "Cache-Control": "no-store",
+                });
+                res.end(binary.buffer);
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/import-zip") {
+                const body = importWikiZipHttpSchema.parse(await readJsonBody(req));
+                const result = await executeToolCall(requestDrive, "import_wiki", body, requestUserId);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/import-zip/upload") {
+                const contentType = (req.headers["content-type"] ?? "").toString().toLowerCase();
+                if (!contentType.includes("application/zip")) {
+                    json(req, res, 415, { ok: false, error: "Content-Type must be application/zip" });
+                    return;
+                }
+                const executeRaw = parsedUrl.searchParams.get("execute");
+                const execute = executeRaw ? executeRaw.toLowerCase() === "true" : true;
+                if (executeRaw && executeRaw.toLowerCase() !== "true" && executeRaw.toLowerCase() !== "false") {
+                    json(req, res, 400, { ok: false, error: "Invalid execute query param; expected true or false" });
+                    return;
+                }
+                const includeSystemRaw = parsedUrl.searchParams.get("includeSystem");
+                const includeSystem = includeSystemRaw ? includeSystemRaw.toLowerCase() === "true" : false;
+                if (includeSystemRaw && includeSystemRaw.toLowerCase() !== "true" && includeSystemRaw.toLowerCase() !== "false") {
+                    json(req, res, 400, { ok: false, error: "Invalid includeSystem query param; expected true or false" });
+                    return;
+                }
+                const conflictStrategyRaw = parsedUrl.searchParams.get("conflictStrategy");
+                const conflictStrategy = conflictStrategyRaw ?? "merge";
+                if (!["skip", "overwrite", "merge"].includes(conflictStrategy)) {
+                    json(req, res, 400, { ok: false, error: "Invalid conflictStrategy query param; expected skip, overwrite, or merge" });
+                    return;
+                }
+                const modeRaw = parsedUrl.searchParams.get("mode");
+                const mode = modeRaw ?? "additive";
+                if (!["additive", "replace"].includes(mode)) {
+                    json(req, res, 400, { ok: false, error: "Invalid mode query param; expected additive or replace" });
+                    return;
+                }
+                const logTimingRaw = parsedUrl.searchParams.get("logTiming");
+                const logTiming = logTimingRaw ? logTimingRaw.toLowerCase() === "true" : false;
+                if (logTimingRaw && logTimingRaw.toLowerCase() !== "true" && logTimingRaw.toLowerCase() !== "false") {
+                    json(req, res, 400, { ok: false, error: "Invalid logTiming query param; expected true or false" });
+                    return;
+                }
+                const effectiveConflictStrategy = mode === "replace" ? "overwrite" : conflictStrategy;
+                const zipBuffer = await readBodyBuffer(req, MAX_IMPORT_ZIP_UPLOAD_BYTES);
+                const startedAt = new Date().toISOString();
+                const startMs = Date.now();
+                if (!execute) {
+                    // Preview mode: async job to avoid Railway 30s gateway timeout on large wikis.
+                    const job = asyncJobRegistry.create("import-preview");
+                    json(req, res, 202, {
+                        ok: true,
+                        jobId: job.id,
+                        status: "queued",
+                        pollUrl: `/api/v1/jobs/${job.id}`,
+                    });
+                    const capturedDrive = requestDrive;
+                    void (async () => {
+                        asyncJobRegistry.update(job.id, { status: "running", progress: { processed: 0, total: 0, phase: "scanning" } });
+                        try {
+                            const preview = await scanImportDiffFromBuffer(capturedDrive, zipBuffer, {
+                                conflictStrategy: effectiveConflictStrategy,
+                                includeSystem,
+                                mode: mode,
+                                onProgress: (processed, total) => {
+                                    asyncJobRegistry.update(job.id, { progress: { processed, total, phase: "scanning" } });
+                                },
+                            });
+                            asyncJobRegistry.update(job.id, {
+                                status: "done",
+                                completedAt: new Date().toISOString(),
+                                result: {
+                                    success: true,
+                                    mode: "preview",
+                                    importMode: mode,
+                                    zipPath: "(uploaded)",
+                                    startedAt,
+                                    durationMs: Date.now() - startMs,
+                                    totalEntries: preview.totalEntries,
+                                    newCount: preview.newCount,
+                                    modifiedCount: preview.modifiedCount,
+                                    unchangedCount: preview.unchangedCount,
+                                    skippedCount: preview.skippedCount,
+                                    deletedCount: preview.deletedCount,
+                                    diff: preview.diff,
+                                },
+                            });
+                        }
+                        catch (err) {
+                            asyncJobRegistry.update(job.id, {
+                                status: "failed",
+                                completedAt: new Date().toISOString(),
+                                error: err instanceof Error ? err.message : String(err),
+                            });
+                        }
+                    })();
+                    return;
+                }
+                // Execute mode: async job — returns immediately, job runs in background.
+                // Avoids Railway 30s edge timeout on large imports (500+ pages).
+                const job = asyncJobRegistry.create("import");
+                json(req, res, 202, {
+                    ok: true,
+                    jobId: job.id,
+                    status: "queued",
+                    pollUrl: `/api/v1/jobs/${job.id}`,
+                });
+                const capturedDrive = requestDrive;
+                const capturedUserId = requestUserId;
+                void (async () => {
+                    asyncJobRegistry.update(job.id, { status: "running", progress: { processed: 0, total: 0, phase: "scanning" } });
+                    try {
+                        const preview = await scanImportDiffFromBuffer(capturedDrive, zipBuffer, {
+                            conflictStrategy: effectiveConflictStrategy,
+                            includeSystem,
+                            mode: mode,
+                            onProgress: (processed, total) => {
+                                asyncJobRegistry.update(job.id, { progress: { processed, total, phase: "scanning" } });
+                            },
+                        });
+                        const deletedNames = mode === "replace"
+                            ? preview.diff.filter((item) => item.status === "deleted").map((item) => item.name)
+                            : [];
+                        asyncJobRegistry.update(job.id, { progress: { processed: 0, total: preview.totalEntries, phase: "writing" } });
+                        const importResult = await runImportFromBuffer(capturedDrive, zipBuffer, {
+                            conflictStrategy: effectiveConflictStrategy,
+                            includeSystem,
+                            deletedNames,
+                            userId: capturedUserId,
+                            onProgress: (processed, total, phase) => {
+                                asyncJobRegistry.update(job.id, { progress: { processed, total, phase } });
+                            },
+                        });
+                        const durationMs = Date.now() - startMs;
+                        const completedAt = new Date().toISOString();
+                        const failures = importResult.errors.map((e) => ({ name: e.path, error: e.reason }));
+                        const appliedCount = importResult.created + importResult.updated;
+                        const deletedCount = importResult.deleted;
+                        const appliedOrChanged = appliedCount > 0 || deletedCount > 0;
+                        const discoveredFolders = computeDiscoveredFolders(preview.diff);
+                        if (logTiming) {
+                            await appendLogEntry(capturedDrive, {
+                                type: "ingest",
+                                title: "Import wiki zip upload",
+                                detail: `mode=${mode}, deleted=${deletedCount}, applied=${appliedCount}, failed=${failures.length}, durationMs=${durationMs}`,
+                            }, capturedUserId).catch(() => { });
+                        }
+                        asyncJobRegistry.update(job.id, {
+                            status: "done",
+                            completedAt,
+                            progress: { processed: appliedCount + deletedCount, total: appliedCount + deletedCount, phase: "done" },
+                            result: {
+                                success: failures.length === 0,
+                                mode: "execute",
+                                importMode: mode,
+                                zipPath: "(uploaded)",
+                                startedAt,
+                                completedAt,
+                                durationMs,
+                                totalEntries: preview.totalEntries,
+                                appliedCount,
+                                deletedCount,
+                                failedCount: failures.length,
+                                failures,
+                                warnings: importResult.warnings.map((w) => ({ name: w.path, warning: w.reason })),
+                                diff: preview.diff,
+                                ...(appliedOrChanged ? {
+                                    instructionRefreshRequired: true,
+                                    discoveredFolders,
+                                    nextAction: buildInstructionRefreshHint(discoveredFolders),
+                                } : {}),
+                            },
+                        });
+                    }
+                    catch (err) {
+                        asyncJobRegistry.update(job.id, {
+                            status: "failed",
+                            completedAt: new Date().toISOString(),
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                })();
+                return;
+            }
+            if (method === "POST" && pathname === "/api/v1/purge") {
+                const body = purgeWikiHttpSchema.parse(await readJsonBody(req));
+                if (!body.confirm) {
+                    // Dry-run: synchronous (just lists files, fast)
+                    if (purgeInFlight >= CONCURRENCY_LIMIT_PURGE) {
+                        json(req, res, 503, { ok: false, error: "Server busy — try again shortly", retryAfter: 5 }, { "Retry-After": "5" });
+                        return;
+                    }
+                    purgeInFlight++;
+                    try {
+                        const result = await executeToolCall(requestDrive, "purge_wiki", body, requestUserId);
+                        json(req, res, 200, { ok: true, result });
+                    }
+                    finally {
+                        purgeInFlight--;
+                    }
+                    return;
+                }
+                // confirm=true: async job — avoids Railway 30s edge timeout on large wikis.
+                const job = asyncJobRegistry.create("purge");
+                json(req, res, 202, {
+                    ok: true,
+                    jobId: job.id,
+                    status: "queued",
+                    pollUrl: `/api/v1/jobs/${job.id}`,
+                });
+                const capturedDrive = requestDrive;
+                const capturedUserId = requestUserId;
+                void (async () => {
+                    asyncJobRegistry.update(job.id, { status: "running", progress: { processed: 0, total: 0, phase: "purging" } });
+                    try {
+                        const purgeInput = {
+                            confirm: true,
+                            exportBeforeDelete: body.exportBeforeDelete ?? false,
+                            exportOutputPath: body.exportOutputPath,
+                            includeSystem: body.includeSystem ?? false,
+                        };
+                        const result = await purgeWiki(capturedDrive, purgeInput, capturedUserId, {
+                            onProgress: (processed, total) => {
+                                asyncJobRegistry.update(job.id, { progress: { processed, total, phase: "purging" } });
+                            },
+                        });
+                        asyncJobRegistry.update(job.id, {
+                            status: "done",
+                            completedAt: new Date().toISOString(),
+                            result,
+                        });
+                    }
+                    catch (err) {
+                        asyncJobRegistry.update(job.id, {
+                            status: "failed",
+                            completedAt: new Date().toISOString(),
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                    }
+                })();
+                return;
+            }
+            if (method === "POST" && pathname === "/tool") {
+                const body = await readJsonBody(req);
+                const parsed = toolCallSchema.parse(body);
+                const result = await executeToolCall(requestDrive, parsed.name, parsed.arguments ?? {}, requestUserId, requestAccessCtx);
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            if (method === "POST" && pathname === "/chat") {
+                const body = await readJsonBody(req);
+                const parsed = chatRequestSchema.parse(body);
+                if (chatInFlight >= CONCURRENCY_LIMIT_CHAT) {
+                    json(req, res, 503, { ok: false, error: "Server busy — try again shortly", retryAfter: 5 }, { "Retry-After": "5" });
+                    return;
+                }
+                chatInFlight++;
+                try {
+                    const outcome = await raceWithTimeout(runClaudeWithTools(requestDrive, parsed, requestUserId, requestAccessCtx), TIMEOUT_CHAT_MS);
+                    if (outcome === TIMEOUT_SENTINEL) {
+                        if (!res.headersSent)
+                            json(req, res, 504, { ok: false, error: "Request timed out" });
+                        return;
+                    }
+                    json(req, res, 200, { ok: true, ...outcome });
+                }
+                finally {
+                    chatInFlight--;
+                }
+                return;
+            }
+            if (method === "POST" && pathname === "/admin/reindex-fts") {
+                if (!isApiKeyAuthorized(req)) {
+                    json(req, res, 403, { ok: false, error: "Admin access required" });
+                    return;
+                }
+                try {
+                    const result = await getPostgresSearchIndex().reindexFts();
+                    json(req, res, 200, { ok: true, ...result });
+                }
+                catch (err) {
+                    json(req, res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+                }
+                return;
+            }
+            if (method === "GET" && pathname === "/admin/users") {
+                const godModeSubjects = (process.env.BRAINS_GOD_MODE_SUBJECTS ?? "")
+                    .split(",").map(s => s.trim()).filter(Boolean);
+                const isGodMode = !!(authorization?.subject && godModeSubjects.includes(authorization.subject));
+                if (!isApiKeyAuthorized(req) && !isGodMode) {
+                    json(req, res, 403, { ok: false, error: "Admin access required" });
+                    return;
+                }
+                const sinceParam = parsedUrl.searchParams.get("since");
+                const sinceMs = sinceParam ? new Date(sinceParam).getTime() : undefined;
+                if (sinceParam && (sinceMs === undefined || isNaN(sinceMs))) {
+                    json(req, res, 400, { ok: false, error: "Invalid 'since' date" });
+                    return;
+                }
+                let userRecords = [];
+                const supabaseUrl = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+                const serviceRoleKey = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+                if (supabaseUrl && serviceRoleKey) {
+                    // Paginate through all Supabase auth users (max 1000 per page).
+                    // Each fetch is guarded by a 15-second AbortController so a hung
+                    // Supabase auth-admin connection never stalls the entire request.
+                    const allSupaUsers = [];
+                    let page = 1;
+                    // eslint-disable-next-line no-constant-condition
+                    while (true) {
+                        const url = `${supabaseUrl}/auth/v1/admin/users?page=${page}&per_page=1000`;
+                        const ac = new AbortController();
+                        const acTimer = setTimeout(() => ac.abort(), 15_000);
+                        const resp = await fetch(url, {
+                            headers: { apikey: serviceRoleKey, authorization: `Bearer ${serviceRoleKey}` },
+                            signal: ac.signal,
+                        }).catch(() => null).finally(() => clearTimeout(acTimer));
+                        if (!resp || !resp.ok)
+                            break;
+                        const body = await resp.json().catch(() => null);
+                        const batch = body?.users ?? [];
+                        if (batch.length === 0)
+                            break;
+                        for (const u of batch) {
+                            // subject = email for display; filesystemSubject = Supabase UUID (matches users/<id>/ dirs)
+                            allSupaUsers.push({ subject: u.email ?? u.id, filesystemSubject: u.id, registeredAt: u.created_at });
+                        }
+                        if (batch.length < 1000)
+                            break;
+                        page++;
+                    }
+                    userRecords = sinceMs
+                        ? allSupaUsers.filter(u => new Date(u.registeredAt).getTime() >= sinceMs)
+                        : allSupaUsers;
+                }
+                if (userRecords.length === 0) {
+                    const usersBasePath = path.join(drive.getStorageLocation(), "users");
+                    const userDirs = await fs.readdir(usersBasePath, { withFileTypes: true }).catch(() => []);
+                    const allDirRecords = await Promise.all(userDirs.filter(d => d.isDirectory()).map(async (d) => {
+                        const stat = await fs.stat(path.join(usersBasePath, d.name)).catch(() => null);
+                        return { subject: d.name, filesystemSubject: d.name, registeredAt: (stat?.birthtime ?? stat?.mtime ?? new Date()).toISOString() };
+                    }));
+                    userRecords = sinceMs
+                        ? allDirRecords.filter(u => new Date(u.registeredAt).getTime() >= sinceMs)
+                        : allDirRecords;
+                    if (allDirRecords.length === 0) {
+                        const clients = await clientStore.listAll(sinceMs);
+                        userRecords = clients.map(c => ({ subject: c.clientId, filesystemSubject: c.clientId, registeredAt: new Date(c.createdAt).toISOString() }));
+                    }
+                }
+                // Count pages and storage per user.
+                // Page count: prefer Postgres (fast, accurate) when configured; fall back to storage listing.
+                // Storage bytes: always from storage listing (no bytes in Postgres), with 15s timeout.
+                // Use filesystemSubject (UUID) not display subject (email) for scope lookups.
+                const pgIdx = getPostgresSearchIndex();
+                const pgConfigured = pgIdx.isConfigured();
+                const listFilesTimeout = () => new Promise((_, reject) => setTimeout(() => reject(new Error("listFiles timeout")), 15_000));
+                const users = await Promise.all(userRecords.map(async (u) => {
+                    const subjectKey = sanitizeSubjectForPath(u.filesystemSubject);
+                    const userScoped = createScopedStorageClient(drive, `users/${subjectKey}`);
+                    let pageCount = 0;
+                    let storageBytes = 0;
+                    // Use Postgres for page count — avoids storage walk timeout on large wikis.
+                    if (pgConfigured) {
+                        pageCount = await pgIdx.countActivePages(u.filesystemSubject).catch(() => 0);
+                    }
+                    try {
+                        const files = await Promise.race([userScoped.listFiles(), listFilesTimeout()]);
+                        storageBytes = files.reduce((acc, f) => acc + f.size, 0);
+                        if (!pgConfigured) {
+                            pageCount = files.filter(f => f.name.endsWith(".md")).length;
+                        }
+                    }
+                    catch { /* user has no files yet, or timed out */ }
+                    return { subject: u.subject, registeredAt: u.registeredAt, pageCount, storageBytes };
+                }));
+                const totalStorageBytes = users.reduce((acc, u) => acc + u.storageBytes, 0);
+                json(req, res, 200, { ok: true, users, total: users.length, totalStorageBytes });
+                return;
+            }
+            // ── Admin: seed-users (staging-only, god-mode gated) ────────────────────
+            if (pathname === "/admin/seed-users") {
+                if (!isSeedEnabled()) {
+                    json(req, res, 404, { ok: false, error: "Not found" });
+                    return;
+                }
+                if (!authorization || !isGodModeSubject(authorization.subject)) {
+                    json(req, res, 403, { ok: false, error: "Forbidden — god-mode required" });
+                    return;
+                }
+                if (method === "POST") {
+                    const body = await readJsonBody(req);
+                    const count = typeof body.count === "number" ? body.count : 1;
+                    const tier = typeof body.tier === "string" ? body.tier : "free_beta";
+                    const prefix = typeof body.prefix === "string" ? body.prefix.trim() : "seed";
+                    if (!prefix || !/^[a-z0-9-]+$/i.test(prefix)) {
+                        json(req, res, 400, { ok: false, error: "prefix must be alphanumeric/hyphens" });
+                        return;
+                    }
+                    const validTiers = ["free_beta", "launch_user", "solo", "pro", "team"];
+                    if (!validTiers.includes(tier)) {
+                        json(req, res, 400, { ok: false, error: `tier must be one of: ${validTiers.join(", ")}` });
+                        return;
+                    }
+                    const result = await seedUsers(drive, {
+                        count: Math.min(Math.max(1, Math.floor(count)), 100),
+                        tier: tier,
+                        prefix,
+                    });
+                    json(req, res, 200, { ok: true, ...result });
+                    return;
+                }
+                if (method === "DELETE") {
+                    const prefix = parsedUrl.searchParams.get("prefix")?.trim() ?? "";
+                    if (!prefix || !/^[a-z0-9-]+$/i.test(prefix)) {
+                        json(req, res, 400, { ok: false, error: "Query param 'prefix' must be alphanumeric/hyphens" });
+                        return;
+                    }
+                    const result = await purgeSeedUsers(prefix);
+                    json(req, res, 200, { ok: true, ...result });
+                    return;
+                }
+                json(req, res, 405, { ok: false, error: "Method not allowed" });
+                return;
+            }
+            // ── Digest: opt-in preferences ─────────────────────────────────────────
+            if (pathname === "/api/v1/digest/preferences") {
+                if (!authorization) {
+                    unauthorized(res, `${publicBase()}/.well-known/oauth-protected-resource`);
+                    return;
+                }
+                if (!hasRequiredScopes(authorization.scopes, ["wiki.read"])) {
+                    forbidden(res, ["wiki.read"]);
+                    return;
+                }
+                const digestSupaUrl = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+                const digestSrKey = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+                if (!digestSupaUrl || !digestSrKey) {
+                    json(req, res, 503, { ok: false, error: "Digest feature requires Supabase configuration" });
+                    return;
+                }
+                if (method === "GET") {
+                    const pref = await getDigestPreference(digestSupaUrl, digestSrKey, authorization.subject);
+                    json(req, res, 200, {
+                        ok: true,
+                        enabled: pref?.enabled ?? false,
+                        lastSentAt: pref?.last_sent_at ?? null,
+                    });
+                    return;
+                }
+                if (method === "PATCH") {
+                    const body = await readJsonBody(req);
+                    const enabledRaw = body["enabled"];
+                    if (typeof enabledRaw !== "boolean") {
+                        json(req, res, 400, { ok: false, error: "Body must include 'enabled' boolean" });
+                        return;
+                    }
+                    if (enabledRaw) {
+                        // Opt-in: upsert with the user's current email from auth context
+                        const userEmail = typeof body["email"] === "string"
+                            ? body["email"].trim()
+                            : "";
+                        if (!userEmail) {
+                            json(req, res, 400, { ok: false, error: "Provide 'email' in body when enabling digest" });
+                            return;
+                        }
+                        await upsertDigestPreference(digestSupaUrl, digestSrKey, {
+                            user_id: authorization.subject,
+                            email: userEmail,
+                            enabled: true,
+                        });
+                    }
+                    else {
+                        // Opt-out: just flip the flag (leave email/created_at intact)
+                        await updateDigestEnabled(digestSupaUrl, digestSrKey, authorization.subject, false);
+                    }
+                    json(req, res, 200, { ok: true, enabled: enabledRaw });
+                    return;
+                }
+                json(req, res, 405, { ok: false, error: "Method not allowed" });
+                return;
+            }
+            // ── Digest: manual trigger (for testing) ────────────────────────────────
+            if (method === "POST" && pathname === "/api/v1/digest/trigger") {
+                if (!authorization) {
+                    unauthorized(res, `${publicBase()}/.well-known/oauth-protected-resource`);
+                    return;
+                }
+                if (!hasRequiredScopes(authorization.scopes, ["wiki.write"])) {
+                    forbidden(res, ["wiki.write"]);
+                    return;
+                }
+                const digestSupaUrl = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+                const digestSrKey = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+                const resendKey = (process.env.RESEND_API_KEY ?? "").trim();
+                const fromEmail = (process.env.DIGEST_FROM_EMAIL ?? "digest@usebrains.app").trim();
+                const fromName = (process.env.DIGEST_FROM_NAME ?? "brains Weekly Digest").trim();
+                const body = await readJsonBody(req);
+                const overrideEmail = typeof body["email"] === "string" ? body["email"].trim() : "";
+                if (!overrideEmail) {
+                    json(req, res, 400, { ok: false, error: "Body must include 'email' for the digest recipient" });
+                    return;
+                }
+                const result = await runDigestForUser(authorization.subject, overrideEmail, requestDrive, { supabaseUrl: digestSupaUrl, serviceRoleKey: digestSrKey, resendApiKey: resendKey, fromEmail, fromName });
+                json(req, res, 200, { ok: true, result });
+                return;
+            }
+            json(req, res, 404, { ok: false, error: "Not found" });
+        }
+        catch (err) {
+            if (err instanceof z.ZodError) {
+                json(req, res, 400, { ok: false, error: `Invalid arguments: ${err.message}` });
+                return;
+            }
+            if (err instanceof Error && err.message.startsWith("Unknown tool:")) {
+                json(req, res, 400, { ok: false, error: err.message });
+                return;
+            }
+            if (err instanceof ToolNotAvailableError) {
+                json(req, res, 404, { ok: false, error: err.message });
+                return;
+            }
+            if (err instanceof StorageLimitError) {
+                json(req, res, 429, err.toJSON());
+                return;
+            }
+            if (err instanceof BodyTooLargeError) {
+                json(req, res, 413, { ok: false, error: err.message });
+                return;
+            }
+            if (err instanceof PageLimitError) {
+                json(req, res, 429, err.toJSON());
+                return;
+            }
+            if (err instanceof Error && err.message.includes("OAuth")) {
+                json(req, res, 400, {
+                    ok: false,
+                    error: err.message,
+                });
+                return;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[brains] Unhandled request error: ${message}`, err instanceof Error ? err.stack : "");
+            json(req, res, 500, { ok: false, error: message });
+        }
+    });
+    server.setTimeout(TIMEOUT_DEFAULT_MS);
+    // Keep connections alive longer than Railway's 60s proxy timeout so warm
+    // MCP clients reuse the same TCP/TLS connection across sequential tool calls.
+    server.keepAliveTimeout = 65_000;
+    server.headersTimeout = 70_000;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "0.0.0.0", () => resolve());
+    });
+    console.error(`[brains] HTTP server listening on 0.0.0.0:${port}`);
+    // ── Phase 4: start background crons (non-blocking) ────────────────────────
+    const supabaseUrlBg = (process.env.SUPABASE_URL ?? "").trim().replace(/\/$/, "");
+    const serviceRoleKeyBg = (process.env.SUPABASE_SERVICE_ROLE_KEY ?? "").trim();
+    if (supabaseUrlBg && serviceRoleKeyBg) {
+        // Warm up hot query cache from top queries in the last 7 days.
+        void (async () => {
+            try {
+                const topQueries = await fetchTopQueries(supabaseUrlBg, serviceRoleKeyBg);
+                if (topQueries.length > 0) {
+                    const { searchPages: sp } = await import("./tools/searchPages.js");
+                    await Promise.allSettled(topQueries.map(async (q) => {
+                        try {
+                            const result = await sp(drive, { query: q, maxCandidates: 120, maxResults: 80, maxConcurrency: 8 }, "");
+                            setHotCached("", q, result);
+                        }
+                        catch {
+                            // non-fatal
+                        }
+                    }));
+                    console.error(`[metrics] hot cache warmed up with ${topQueries.length} queries`);
+                }
+            }
+            catch {
+                // non-fatal
+            }
+        })();
+        // Start zero-result triage weekly cron.
+        startZeroResultTriageCron(supabaseUrlBg, serviceRoleKeyBg, () => drive);
+        // Start weekly brain digest cron (Sunday 08:00 UTC).
+        const resendApiKey = (process.env.RESEND_API_KEY ?? "").trim();
+        const digestFromEmail = (process.env.DIGEST_FROM_EMAIL ?? "digest@usebrains.app").trim();
+        const digestFromName = (process.env.DIGEST_FROM_NAME ?? "brains Weekly Digest").trim();
+        startDigestCron(drive, {
+            supabaseUrl: supabaseUrlBg,
+            serviceRoleKey: serviceRoleKeyBg,
+            resendApiKey,
+            fromEmail: digestFromEmail,
+            fromName: digestFromName,
+        });
+    }
+    // Prune expired PATs daily.
+    const patPruneCron = setInterval(() => { void patStore.pruneExpired().catch(() => { }); }, 24 * 60 * 60 * 1000);
+    if (typeof patPruneCron.unref === "function")
+        patPruneCron.unref();
+    return server;
+}
+//# sourceMappingURL=httpServer.js.map