studiograph 1.3.48-next.21 → 1.3.48-next.211

package/dist/server/index.js

@@ -4,118 +4,327 @@
  * Hosts:
  *   - Graph API (read-only REST over WorkspaceManager)
  *   - Agent chat via POST /api/chat and SSE GET /api/chat/stream
- *   - App plugins mounted via PluginLoader
+ *   - Static web UI (SvelteKit build) with SPA fallback
  */
 import Fastify from 'fastify';
 import cookie from '@fastify/cookie';
 import cors from '@fastify/cors';
+import rateLimit from '@fastify/rate-limit';
 import websocket from '@fastify/websocket';
+import { sanitize } from './middleware/sanitize.js';
 import { existsSync, readFileSync, createReadStream, statSync } from 'fs';
-import { join, extname } from 'path';
+import { join, extname, resolve, sep } from 'path';
 import { Workspace } from '../core/workspace.js';
 import { AgentOrchestrator } from '../agent/orchestrator.js';
-import { PluginLoader, MIME_TYPES } from './plugin-loader.js';
 import { registerGraphApiRoutes } from './routes/graph-api.js';
 import { registerChatRoutes } from './routes/chat.js';
 import { registerWorkspaceApiRoutes } from './routes/workspace-api.js';
+import { registerHealthApiRoutes } from './routes/health.js';
 import { registerPermissionsApiRoutes } from './routes/permissions-api.js';
 import { registerAuthApiRoutes } from './routes/auth-api.js';
 import { registerGitHttpRoutes } from './routes/git-http.js';
 import { registerViewsApiRoutes } from './routes/views-api.js';
-import { registerBriefingApiRoutes } from './routes/insights-api.js';
+import { registerInsightsApiRoutes } from './routes/insights-api.js';
 import { registerMcpRoutes } from './routes/mcp.js';
 import { registerConnectorsApiRoutes } from './routes/connectors-api.js';
+import { registerOAuthApiRoutes, resolveCanonicalBaseUrl } from './routes/oauth-api.js';
 import { registerAssetApiRoutes } from './routes/asset-api.js';
+import { verifyArtifactAssetToken } from '../services/artifact-asset-token.js';
+import { registerR2ApiRoutes } from './routes/r2-api.js';
 import multipart from '@fastify/multipart';
-import { registerMeetingIngestRoutes } from './routes/meeting-ingest-api.js';
+import { registerEventIngestRoutes } from './routes/event-ingest-api.js';
 import { registerCaptureRoutes } from './routes/capture-api.js';
 import { registerUrlRoutes } from './routes/url-api.js';
-import { registerMessagesApiRoutes } from './routes/messages-api.js';
 import { registerConfigApiRoutes } from './routes/config-api.js';
-import { AuthService, isAdminOrOwner } from '../services/auth-service.js';
-import { MessageService } from '../services/message-service.js';
+import { registerSettingsApiRoutes } from './routes/settings-api.js';
+import { registerSecretsApiRoutes } from './routes/secrets-api.js';
+import { registerAuditApiRoutes } from './routes/audit-api.js';
+import { registerCommentsApiRoutes } from './routes/comments-api.js';
+import { registerChatSessionsApiRoutes } from './routes/chat-sessions-api.js';
+import { registerShareApiRoutes } from './routes/share-api.js';
+import { registerArtifactExportApiRoutes } from './routes/artifact-export-api.js';
+import { AuthService, isWorkspaceOwner } from '../services/auth-service.js';
 import { MemoryService } from '../services/memory-service.js';
+import { CommentService } from '../services/comment-service.js';
+import { ChatSessionService } from '../services/chat-session-service.js';
+import { ShareLinkService } from '../services/share-link-service.js';
+import { NotificationService } from '../services/notification-service.js';
 import { WsHub } from './ws-hub.js';
 import { registerWsRoute } from './routes/ws.js';
 import { SessionManager } from './session-manager.js';
+import { AssetIndexQueue } from './asset-index-queue.js';
 import { YjsManager } from './yjs-manager.js';
-/** Ensure every user has a private "My Entries" collection (idempotent). */
-async function ensureAllPrivateCollections(authService, workspacePath, workspaceManager) {
+import { YjsPersistence, acquireYjsStateLock } from './yjs-persistence.js';
+import { BodyWriteCoordinator } from './body-write-coordinator.js';
+import { ensurePersonalFolder } from '../services/personal-folder.js';
+import { loadUserConfig, resolveProvider, resolveModelId, resolveApiKey } from '../core/user-config.js';
+/** Ensure every user has a personal "My Folder" folder + admin access on it (idempotent). */
+async function ensureAllPersonalFolders(authService, workspacePath, workspaceManager) {
     const users = authService.listUsers();
     const workspace = new Workspace(workspacePath);
     for (const user of users) {
-        if (workspaceManager.getUserPrivateRepo(user.id))
-            continue;
         try {
-            await workspace.registerRepo({
-                name: `entries-${user.id}`,
-                display_name: 'My Entries',
-                description: `Private entries for ${user.displayName}`,
-                private: true,
-                owner_id: user.id,
-            });
-            workspaceManager.reloadConfig();
+            await ensurePersonalFolder(workspace, authService, user);
         }
-        catch { /* already exists or other issue — skip */ }
+        catch { /* non-fatal — skip and let the user re-authenticate */ }
+    }
+    workspaceManager.reloadConfig();
+}
+/** MIME types for static file serving (web UI assets). */
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+};
+const PUBLIC_IMMUTABLE_FONT_ASSET_RE = /^\/api\/assets\/[^/]+\/[^/]+\.(?:woff2?|ttf|otf)$/i;
+// EXACT two-segment immutable asset shape — the only path the artifact-asset
+// capability token (`?at=`) may unlock. Excludes the legacy 3-segment route
+// (which carries known repo-identity hazards) by matching to end-of-path.
+const ARTIFACT_ASSET_TOKEN_PATH_RE = /^\/api\/assets\/[^/]+\/[^/]+$/;
+export function resolveStaticFilePath(webDir, urlPath) {
+    let decodedPath;
+    try {
+        decodedPath = decodeURIComponent(urlPath);
+    }
+    catch {
+        return null;
+    }
+    const filePath = decodedPath === '/' ? '/index.html' : decodedPath;
+    const webRoot = resolve(webDir);
+    const fullPath = resolve(webRoot, `.${filePath}`);
+    if (fullPath !== webRoot && !fullPath.startsWith(webRoot + sep)) {
+        return null;
+    }
+    return fullPath;
+}
+function normalizeOrigin(value) {
+    if (!value)
+        return null;
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return null;
     }
 }
+export function buildAllowedCorsOrigins(workspaceConfig, port) {
+    const rawOrigins = [];
+    const envOrigins = process.env.STUDIOGRAPH_CORS_ORIGINS;
+    if (envOrigins)
+        rawOrigins.push(...envOrigins.split(',').map(o => o.trim()).filter(Boolean));
+    const configured = workspaceConfig.cors_origins;
+    if (Array.isArray(configured)) {
+        rawOrigins.push(...configured.filter((o) => typeof o === 'string'));
+    }
+    else if (typeof configured === 'string') {
+        rawOrigins.push(...configured.split(',').map(o => o.trim()).filter(Boolean));
+    }
+    const serverUrl = workspaceConfig.server_url;
+    if (typeof serverUrl === 'string')
+        rawOrigins.push(serverUrl);
+    rawOrigins.push(`http://localhost:${port}`, `http://127.0.0.1:${port}`, `http://[::1]:${port}`);
+    return new Set(rawOrigins.map(normalizeOrigin).filter((o) => Boolean(o)));
+}
+export function isCorsOriginAllowed(origin, allowedOrigins) {
+    if (!origin)
+        return true;
+    const normalized = normalizeOrigin(origin);
+    return Boolean(normalized && allowedOrigins.has(normalized));
+}
+function isTruthyEnv(value) {
+    return Boolean(value && ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase()));
+}
 /**
  * Auth middleware — validates JWT cookie or Authorization: Bearer <key> header.
  * When users exist in the auth database, all routes require authentication
  * (except auth endpoints and static assets). When no users exist, everything
  * is open (backward compatible).
  */
-function createAuthHook(apiKeys, authService) {
+export function createAuthHook(authService, workspaceConfig) {
     return async (req, reply) => {
         // Always allow auth endpoints
         if (req.url.startsWith('/api/auth/'))
             return;
+        // Managed Cloud login handoff verifies its own short-lived token.
+        if (req.url.startsWith('/api/cloud/auth/'))
+            return;
         // OAuth callbacks and claims identify the user via state/claim code, not cookies
         if (req.url.startsWith('/api/oauth/callback/'))
             return;
         if (req.url.startsWith('/api/oauth/claim/'))
             return;
+        // OAuth authorization-server discovery + token endpoints are
+        // unauthenticated by spec (the client has no user yet). They are
+        // rate-limited + validated in oauth-api.ts. NOT /oauth/authorize — that
+        // one must run as the logged-in user (handled explicitly below, above the
+        // HTML-GET bypass which would otherwise skip cookie resolution).
+        if (req.url.startsWith('/.well-known/oauth-'))
+            return;
+        if (req.url.startsWith('/oauth/token') ||
+            req.url.startsWith('/oauth/register') ||
+            req.url.startsWith('/oauth/revoke'))
+            return;
+        if (req.url.startsWith('/oauth/authorize')) {
+            const cookieTok = req.cookies?.['__sg_token'];
+            // Resolve the session cookie, but REFUSE an OAuth access token here — a
+            // cookie is a browser-session surface and must never carry an
+            // authorization-server-issued token (see the cookie branch below).
+            const c = cookieTok ? authService.verifyTokenWithClaims(cookieTok) : null;
+            if (c && !c.oauth) {
+                req.user = c.user;
+                return;
+            }
+            // Not logged in: bounce a browser GET to login (carrying the authorize
+            // URL as returnTo); refuse a POST.
+            if (req.method === 'GET') {
+                return reply.redirect(`/login?returnTo=${encodeURIComponent(req.url)}`);
+            }
+            return reply.status(401).send({ error: 'login_required' });
+        }
         // Git HTTP routes have their own Basic Auth
         if (req.url.startsWith('/git/'))
             return;
         // WebSocket route handles its own auth
         if (req.url.startsWith('/ws'))
             return;
-        // Allow static assets (JS, CSS, fonts, images) — needed for login page
-        if (req.url.startsWith('/_app/') || req.url.startsWith('/api/chrome/'))
+        // Allow static assets (JS, CSS, fonts, images) — needed for login page.
+        // Covers SvelteKit-bundled output under /_app/ and root-level public
+        // files (favicon.ico, studiograph-logomark.svg, …) identified by a file
+        // extension on a non-API GET.
+        if (req.url.startsWith('/_app/'))
+            return;
+        // Public share surface: the two read-only routes are authorized by the
+        // opaque token (verified in share-api.ts), not a session. Scope the bypass
+        // to EXACTLY the public read + asset shapes so a future /api/share/* route
+        // isn't accidentally public. Allow HEAD as well as GET — the asset route is
+        // registered for both (image preflights / link unfurlers issue HEAD). The
+        // mint route is POST /api/repos/... and stays fully authed.
+        if ((req.method === 'GET' || req.method === 'HEAD') &&
+            /^\/api\/share\/[^/]+(\/asset\/[^/]+\/[^/]+)?$/.test(req.url.split('?')[0]))
+            return;
+        // Sandboxed artifact iframes have an opaque origin, so @font-face loads may
+        // arrive without the web session cookie. Let immutable font asset requests
+        // reach the asset route; the route still only serves public workspace-wide
+        // font assets and keeps all other asset URLs behind normal authz.
+        if ((req.method === 'GET' || req.method === 'HEAD') &&
+            PUBLIC_IMMUTABLE_FONT_ASSET_RE.test(req.url.split('?')[0]))
+            return;
+        // Sandboxed artifact iframes (opaque origin, no cookie) carry an
+        // artifact-asset capability token in `?at=`. Only the EXACT 2-segment
+        // immutable shape qualifies (never the legacy 3-seg route). Verify the
+        // signature and stash the payload as a CANDIDATE — the asset route does the
+        // authoritative authz against the resolved row (repo + allowlist + per-serve
+        // user re-check). We do NOT set req.user. An invalid token falls through to
+        // normal auth (→ 401/404), so a bad `?at=` can't downgrade security.
+        if ((req.method === 'GET' || req.method === 'HEAD') &&
+            ARTIFACT_ASSET_TOKEN_PATH_RE.test(req.url.split('?')[0])) {
+            const at = req.query?.at;
+            if (typeof at === 'string' && at.length > 0) {
+                try {
+                    req.artifactAssetToken = verifyArtifactAssetToken(at, authService.getJwtSecret());
+                    // Only short-circuit for a cookieless caller (the sandboxed iframe).
+                    // If a session cookie is present, fall through to normal auth so
+                    // req.user is set and the route serves on the SESSION's access — the
+                    // token is a fallback for the no-cookie case, never an override.
+                    if (!req.cookies?.['__sg_token'])
+                        return;
+                }
+                catch { /* invalid/expired → fall through to normal auth */ }
+            }
+        }
+        if (req.method === 'GET' &&
+            !req.url.startsWith('/api/') &&
+            extname(req.url.split('?')[0]).length > 1)
             return;
         // Allow HTML page requests (SPA routing) — the app handles auth client-side
         if (req.method === 'GET' && req.headers.accept?.includes('text/html'))
             return;
-        // If no users configured, allow everything (open mode)
-        if (!authService.hasUsers()) {
-            // Still check API keys for programmatic routes if configured
-            if (apiKeys.length > 0) {
-                const authHeader = req.headers['authorization'];
-                const bearer = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : undefined;
-                if (bearer && apiKeys.includes(bearer))
-                    return;
-                // For non-API routes (i.e. browser requests), allow without auth
-                if (!req.url.startsWith('/api/') || req.url.startsWith('/api/auth/'))
-                    return;
-                // For API routes without a bearer token, allow if no users exist
-            }
+        // If no users configured, allow everything in local open mode. Managed
+        // Cloud workspaces still require auth before the first user handoff lands.
+        if (!authService.hasUsers() && !isTruthyEnv(process.env.STUDIOGRAPH_MANAGED_AUTH))
             return;
-        }
-        // Check JWT cookie (web UI sessions)
+        // Check JWT cookie (web UI sessions).
+        //
+        // Security: resolve with verifyTokenWithClaims and REJECT OAuth access
+        // tokens (`oauth:true`). OAuth tokens are JWTs signed with the same
+        // jwtSecret, so the legacy verifyToken() would accept one supplied as a
+        // cookie and return a fully-privileged session — bypassing the MCP-only
+        // audience scoping enforced on the Bearer path below. A session cookie is
+        // a web-UI surface and must never carry an authorization-server token.
         const jwtToken = req.cookies?.['__sg_token'];
         if (jwtToken) {
-            const user = authService.verifyToken(jwtToken);
-            if (user) {
-                req.user = user;
+            const claims = authService.verifyTokenWithClaims(jwtToken);
+            if (claims && !claims.oauth) {
+                req.user = claims.user;
                 return;
             }
         }
-        // Check Bearer token (API clients, MCP)
+        // Check Bearer token (API clients, MCP, CLI): JWT → per-user API token.
+        // Both yield a user identity. There is no shared workspace key — every
+        // caller must be identifiable so access control can enforce per-folder rules.
         const authHeader = req.headers['authorization'];
         const bearer = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : undefined;
-        if (bearer && apiKeys.includes(bearer))
-            return;
+        if (bearer) {
+            const claims = authService.verifyTokenWithClaims(bearer);
+            if (claims) {
+                if (claims.oauth) {
+                    // OAuth access tokens are confined to the MCP surface. Reject them on
+                    // the rest of the REST API so a leaked connector token can't drive the
+                    // whole product (least privilege — sg_ tokens stay full).
+                    const path = req.url.split('?')[0];
+                    const mcpScoped = path === '/mcp' || path.startsWith('/mcp/') || path.startsWith('/oauth/');
+                    if (!mcpScoped) {
+                        return reply.status(403).send({ error: 'insufficient_scope' });
+                    }
+                    // Enforce the token audience: it must be bound to THIS server's /mcp
+                    // resource. Without this, any JWT signed with the workspace secret +
+                    // `oauth:true` would be accepted regardless of the `aud` it was minted
+                    // for (stale/wrong-resource/host-spoofed tokens).
+                    let expectedAud = null;
+                    try {
+                        expectedAud = `${resolveCanonicalBaseUrl(workspaceConfig, req)}/mcp`;
+                    }
+                    catch {
+                        expectedAud = null;
+                    }
+                    if (!expectedAud || claims.aud !== expectedAud) {
+                        return reply.status(403).send({ error: 'insufficient_scope', error_description: 'token audience mismatch' });
+                    }
+                    // Label the integration for agent-activity attribution (parity with
+                    // the api-token name path below). cid is the stable client_id.
+                    if (claims.cid) {
+                        const client = authService.oauthServer.getClient(claims.cid);
+                        req.apiTokenName = client?.client_name ?? 'OAuth client';
+                    }
+                }
+                req.user = claims.user;
+                return;
+            }
+            const tokenMeta = authService.verifyApiTokenWithMeta(bearer);
+            if (tokenMeta) {
+                req.user = tokenMeta.user;
+                // Stash the token's user-set name so downstream surfaces (MCP, agent
+                // activity) can label the integration. Absent for cookie/JWT auth.
+                req.apiTokenName = tokenMeta.tokenName;
+                return;
+            }
+        }
         // Check Basic Auth (CLI join command)
         if (authHeader?.startsWith('Basic ')) {
             try {
@@ -131,27 +340,158 @@ function createAuthHook(apiKeys, authService) {
             }
             catch { /* fall through to 401 */ }
         }
+        // MCP OAuth discovery: an unauthenticated /mcp request gets a
+        // WWW-Authenticate header pointing at the protected-resource metadata, so
+        // an MCP client (Claude Chat/Cowork) knows to begin the OAuth flow.
+        if (req.url.startsWith('/mcp')) {
+            // Best-effort: if no canonical issuer is pinned (fails closed in prod),
+            // skip the discovery hint rather than 500 the 401.
+            try {
+                const base = resolveCanonicalBaseUrl(workspaceConfig, req);
+                reply.header('WWW-Authenticate', `Bearer resource_metadata="${base}/.well-known/oauth-protected-resource"`);
+            }
+            catch { /* issuer unconfigured — omit discovery header */ }
+        }
         return reply.status(401).send({ error: 'Unauthorized' });
     };
 }
+/**
+ * Phase 11 — preSerialization payload sanitizer.
+ *
+ * The API has many routes that respond with `{ error: err.message }` from a
+ * catch block. Those messages can carry upstream provider errors, git
+ * stderr (with embedded credentials), or other free-form text that we
+ * don't want surfacing in HTTP responses. Walk the response payload,
+ * sanitize any string value at a "message" / "error" / "detail" key,
+ * and leave structured fields (status codes, IDs, classification flags)
+ * alone.
+ *
+ * Conservatively, we ONLY redact at keys that conventionally carry
+ * free-form text. Arbitrary string fields (entity names, IDs, etc.) are
+ * left untouched so we don't garble legitimate content. The Fastify
+ * logger sanitization (above) handles log-line redaction independently;
+ * this hook focuses on the wire response.
+ */
+const FREEFORM_ERROR_KEYS = new Set(['error', 'message', 'detail', 'stack', 'description', 'error_description']);
+function sanitizeResponsePayload(value) {
+    if (typeof value === 'string')
+        return sanitize(value);
+    if (Array.isArray(value))
+        return value.map(sanitizeResponsePayload);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (FREEFORM_ERROR_KEYS.has(k) && typeof v === 'string') {
+                out[k] = sanitize(v);
+            }
+            else if (v && typeof v === 'object') {
+                out[k] = sanitizeResponsePayload(v);
+            }
+            else {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    return value;
+}
 export async function createServer(config) {
+    // Phase 11: every Fastify log line flows through sanitize() before
+    // reaching stdout. A thin Writable wrapper passes each chunk through
+    // the redactor; pino accepts any `stream` with a `write()` method.
+    // STUDIOGRAPH_LOG_RAW=1 disables redaction for local debugging.
+    const shouldRedactFastifyLogs = process.env.STUDIOGRAPH_LOG_RAW !== '1' &&
+        (process.env.NODE_ENV === 'production' || !!process.env.RAILWAY_ENVIRONMENT);
+    const redactingStream = {
+        write(chunk) {
+            const out = shouldRedactFastifyLogs ? sanitize(chunk) : chunk;
+            process.stdout.write(out);
+        },
+    };
     const fastify = Fastify({
         logger: process.env.STUDIOGRAPH_LOG === '1'
-            ? true
-            : { level: 'warn' },
+            ? { stream: redactingStream }
+            : { level: 'warn', stream: redactingStream },
         bodyLimit: 10 * 1024 * 1024, // 10 MB — entities can be large (e.g. meeting transcripts)
     });
+    // Phase 11: sanitize uncaught errors before serialization so neither
+    // err.message nor err.stack echoes upstream secrets. Stable error
+    // codes (err.code) pass through; we only redact freeform text.
+    fastify.setErrorHandler((error, _req, reply) => {
+        const sanitizedMsg = shouldRedactFastifyLogs ? sanitize(error.message) : error.message;
+        const status = error.statusCode ?? 500;
+        fastify.log.error({
+            err: { message: sanitizedMsg, code: error.code },
+        });
+        reply.status(status).send({
+            statusCode: status,
+            code: error.code,
+            error: status >= 500 ? 'Internal Server Error' : (error.name || 'Error'),
+            message: status >= 500 ? 'An internal error occurred.' : sanitizedMsg,
+        });
+    });
+    // Phase 11: pre-serialization hook scans every response body for
+    // freeform error/message strings and runs them through sanitize().
+    // This catches the many `reply.status(4xx).send({ error: err.message })`
+    // call sites scattered across the API routes — without this, an
+    // upstream provider error or git remote error would echo through to
+    // the API consumer with embedded credentials. Stable error codes pass
+    // through unchanged. Only kicks in when redaction is enabled.
+    if (shouldRedactFastifyLogs) {
+        fastify.addHook('preSerialization', async (_req, _reply, payload) => {
+            if (!payload || typeof payload !== 'object')
+                return payload;
+            return sanitizeResponsePayload(payload);
+        });
+    }
     // CORS
+    const allowedCorsOrigins = buildAllowedCorsOrigins(config.workspaceConfig, config.port);
     await fastify.register(cors, {
-        origin: true,
+        origin: (origin, cb) => {
+            cb(null, isCorsOriginAllowed(origin, allowedCorsOrigins));
+        },
         credentials: true,
     });
     // Cookie support for web UI session auth
     await fastify.register(cookie);
-    // WebSocket support for real-time notifications
-    await fastify.register(websocket);
+    // WebSocket support for real-time notifications.
+    //
+    // perMessageDeflate is enabled here on purpose. Our origin would otherwise
+    // leave compression off (ws lib default), but Railway's edge proxy
+    // negotiates `permessage-deflate` with the browser anyway and does its own
+    // inflate/deflate layer in the middle — which Safari/WebKit mis-decodes,
+    // producing truncated buffers and `RangeError: Length out of range of buffer`
+    // inside Yjs's varint reader, followed by WS disconnect loops.
+    //
+    // Negotiating compression at the origin forces end-to-end deflate (Node's
+    // zlib ↔ browser) and prevents the proxy from inserting its own layer.
+    // `noContextTakeover` on both sides keeps each frame independently
+    // decompressible, which avoids cross-frame state bugs that have historically
+    // hit Safari.
+    await fastify.register(websocket, {
+        options: {
+            perMessageDeflate: {
+                threshold: 1024,
+                serverNoContextTakeover: true,
+                clientNoContextTakeover: true,
+            },
+        },
+    });
     // Multipart support for file uploads (images, assets)
     await fastify.register(multipart, { limits: { fileSize: 10 * 1024 * 1024 } });
+    // Global rate-limit registration with a permissive default; individual
+    // routes opt into tighter limits via `config: { rateLimit: ... }`. Today
+    // only comment mutations apply tight limits — keeps the runtime in
+    // place without changing the rest of the API's request-rate behaviour.
+    await fastify.register(rateLimit, {
+        global: false,
+        max: 1000,
+        timeWindow: '1 minute',
+        keyGenerator: (req) => {
+            const u = req.user;
+            return u?.id ? `u:${u.id}` : (req.ip ?? 'unknown');
+        },
+    });
     fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, (req, body, done) => {
         try {
             req.rawBody = body;
@@ -161,6 +501,21 @@ export async function createServer(config) {
             done(err, undefined);
         }
     });
+    // application/x-www-form-urlencoded — the OAuth token + consent POSTs use
+    // form encoding (RFC 6749). Parsed inline to avoid pulling in a dependency
+    // just for two endpoints; mirrors the hand-rolled JSON parser above.
+    fastify.addContentTypeParser('application/x-www-form-urlencoded', { parseAs: 'string' }, (_req, body, done) => {
+        try {
+            const params = new URLSearchParams(body);
+            const obj = {};
+            for (const [k, v] of params)
+                obj[k] = v;
+            done(null, obj);
+        }
+        catch (err) {
+            done(err, undefined);
+        }
+    });
     // Git Smart HTTP binary content types — pass raw stream through (no parsing)
     for (const gitType of [
         'application/x-git-upload-pack-request',
@@ -170,159 +525,187 @@ export async function createServer(config) {
             done(null); // Don't consume the body — the route handler pipes req.raw directly
         });
     }
-    // Initialize auth service, WebSocket hub, session manager, and collab server
-    const authService = new AuthService(config.workspacePath);
-    // Ensure API key is committed to auth-seed.json so `studiograph pull` can use it
-    authService.syncApiKeyToSeed();
-    // Ensure all users have their private "My Entries" collection
-    await ensureAllPrivateCollections(authService, config.workspacePath, config.workspaceManager);
-    const wsHub = new WsHub();
-    const messageService = new MessageService(config.workspacePath);
+    // Initialize auth service, WebSocket hub, session manager, and collab server.
+    // Phase 8: when the boot path provided master-key options, hand them through
+    // so OAuth tokens + per-user secret prefs use the encrypted column path.
+    const authService = new AuthService(config.workspacePath, config.authCryptoOptions);
+    // Ensure all users have their personal "My Folder" folder
+    await ensureAllPersonalFolders(authService, config.workspacePath, config.workspaceManager);
+    const { getCurrentVersion } = await import('../utils/version-checker.js');
+    const wsHub = new WsHub(getCurrentVersion());
+    const commentService = new CommentService(config.workspacePath);
+    const chatSessionService = new ChatSessionService(config.workspacePath);
+    const shareLinkService = new ShareLinkService(config.workspacePath);
+    const notificationService = new NotificationService(config.workspacePath);
     const sessionManager = new SessionManager(config.workspaceManager, wsHub);
-    const yjsManager = new YjsManager(config.workspaceManager);
+    // Recover any dirty repos before accepting requests. Replays persisted
+    // pending commits from a previous process AND sweeps every working tree
+    // for uncommitted state. Catches anything dropped by a crash, OOM, or
+    // hard restart. Logs and continues on failure — recovery is best-effort
+    // and must never block server startup.
+    try {
+        await sessionManager.recoverOnBoot();
+    }
+    catch (err) {
+        console.warn('[server] sessionManager.recoverOnBoot failed:', err.message);
+    }
+    // Live asset-index drain: captions new image uploads and re-extracts document
+    // sidecars while the server runs, instead of only at boot (a tenant can run
+    // for weeks between deploys). Config (model/key/gate/repos) is resolved fresh
+    // each drain so a Settings change takes effect without a restart. Web upload
+    // + MCP finalize call `enqueue()` after the asset entity exists.
+    const assetIndexQueue = new AssetIndexQueue({
+        workspaceManager: config.workspaceManager,
+        resolveConfig: () => {
+            const userConfig = loadUserConfig();
+            // Read the LIVE workspace config from the WorkspaceManager, NOT the boot
+            // snapshot (config.workspaceConfig). reloadConfig() refreshes both the
+            // repo list (so a folder auto-created at runtime — e.g. the shared
+            // "Assets" store on first inline/presign upload — is visible to the
+            // sweep) and the captioning gate (so toggling it in workspace.json takes
+            // effect without a restart). Model/key already resolve store-first.
+            const wsConfig = config.workspaceManager.getConfig();
+            const apiKey = resolveApiKey(userConfig, wsConfig);
+            return {
+                repos: config.workspaceManager.getAllRepoConfigs(),
+                captionConfig: apiKey
+                    ? { provider: resolveProvider(userConfig, wsConfig), modelId: resolveModelId(userConfig, wsConfig), apiKey }
+                    : null,
+                captioningEnabled: wsConfig.captioning?.enabled ?? true,
+            };
+        },
+        log: (msg) => console.warn(`[asset-index] ${msg}`),
+    });
+    assetIndexQueue.start();
+    // Single chokepoint: VectorService fires onAssetPending exactly when a fresh
+    // indexable IMAGE assets.db row is seeded `pending` (every image-upload path
+    // funnels through ensureInitialAssetIndexState — import, manager/editor
+    // upload, presign finalize). Registering here replaces per-call-site enqueue
+    // wiring and keys the queue on the immutable assetId.
+    config.workspaceManager.vectorService?.setOnAssetPending((assetId) => assetIndexQueue.enqueue(assetId));
+    // Boot recovery: drain anything a prior process left queued AND re-derive the
+    // full unfinished set in LanceDB (legacy assets, a mid-flight crash). Fire-and-
+    // forget — it can take minutes on a large gallery and must not block listen().
+    void assetIndexQueue.recoverOnBoot().catch((err) => {
+        console.warn('[asset-index] recoverOnBoot failed (non-fatal):', err instanceof Error ? err.message : err);
+    });
+    // Persistence layer: durable Y.Doc snapshot store across server restarts.
+    // Lives at `<workspace>/.studiograph/yjs-state/` — gitignored binary state
+    // separate from the .md files (which remain canonical for git, MCP, agents).
+    // See yjs-persistence.ts for the file format and concurrency model.
+    const yjsStateDir = join(config.workspacePath, '.studiograph', 'yjs-state');
+    // Single-instance lock. Throws if another studiograph server is already
+    // running against this workspace. We don't support horizontal scaling today
+    // (no shared Yjs pubsub), so the safe default is to fail fast on misuse
+    // rather than silently corrupt snapshots via concurrent writers.
+    const releaseYjsLock = acquireYjsStateLock(yjsStateDir);
+    const yjsPersistence = new YjsPersistence(yjsStateDir);
+    const yjsManager = new YjsManager(config.workspaceManager, yjsPersistence);
+    // Yjs configuration startup log. Surfacing the flags at boot lets operators
+    // verify the configuration without reading source. The fail-closed guards
+    // (`assertWritable`, 412 convergence gate) prevent silent data corruption
+    // regardless of how the flags are set, but `broadcast=off` while clients
+    // are connected degrades UX, so we warn explicitly.
+    const broadcastEnabled = process.env.STUDIOGRAPH_YJS_BROADCAST !== '0';
+    const allowDegradedWrites = process.env.STUDIOGRAPH_ALLOW_DEGRADED_WRITES === '1';
+    console.log(`[yjs] config: broadcast=${broadcastEnabled ? 'on' : 'OFF'} ` +
+        `allow-degraded-writes=${allowDegradedWrites ? 'on' : 'off'}`);
+    if (!broadcastEnabled && !allowDegradedWrites) {
+        console.warn('[yjs] STUDIOGRAPH_YJS_BROADCAST=0 without STUDIOGRAPH_ALLOW_DEGRADED_WRITES=1: ' +
+            'server-side body writes will REFUSE while clients are connected. ' +
+            'This is the fail-closed kill-switch path — intentional during incident response, ' +
+            'misconfiguration otherwise.');
+    }
+    // Wire the Yjs persistence layer to follow structural .md mutations.
+    // delete / rename / changeType all change a doc's identity (path on disk
+    // and its docName), so the snapshot file has to move with it. Without
+    // these hooks, snapshots leak (orphaned files for deleted entities) or
+    // serve stale state at the new identity (ghost content after a rename).
+    config.workspaceManager.setPersistenceCallbacks({
+        onDelete: (repo, entityType, entityId) => yjsPersistence.delete(`${repo}/${entityType}/${entityId}`),
+        onRename: (repo, entityType, oldId, newId) => yjsPersistence.rename(`${repo}/${entityType}/${oldId}`, `${repo}/${entityType}/${newId}`),
+        onChangeType: (repo, entityId, fromType, toType) => yjsPersistence.rename(`${repo}/${fromType}/${entityId}`, `${repo}/${toType}/${entityId}`),
+    });
+    // Body-write coordinator owns the single critical section for every body
+    // write (autosave PUT + MCP / agent / event-processor server-writes). Holds
+    // the per-doc lock, base-hash precondition, atomic disk write, commit +
+    // dirty recovery, post-commit applyAgentContent broadcast, and
+    // mdRevisionHash bookkeeping. Replaces the previous nine-callback shape on
+    // graph.update.
+    const bodyWriteCoordinator = new BodyWriteCoordinator({
+        // Narrow commit hook — keeps the coordinator from reaching back
+        // through WorkspaceManager. No-op when the repo has no GitService.
+        commit: async (coords, actor, message) => {
+            const gitService = config.workspaceManager.getGraph(coords.repo).getGitService();
+            if (!gitService)
+                return;
+            const tx = gitService.createTransaction();
+            tx.add({
+                operation: 'update',
+                entityType: coords.entityType,
+                entityId: coords.entityId,
+                filePath: coords.entityPath,
+            });
+            await tx.commit(actor, message);
+        },
+    }, yjsManager, sessionManager);
+    config.workspaceManager.setBodyWriteCoordinator(bodyWriteCoordinator);
     // Register auth API routes (before the auth hook so they are always accessible)
     await registerAuthApiRoutes(fastify, authService, config.workspacePath, config.workspaceManager, config.workspaceConfig.team_name);
     // Auth hook — applied to all routes
-    const authHook = createAuthHook(config.apiKeys, authService);
+    const authHook = createAuthHook(authService, config.workspaceConfig);
     fastify.addHook('preHandler', authHook);
     // Register WebSocket route (real-time change notifications + cursor broadcasting)
-    await registerWsRoute(fastify, wsHub, authService, yjsManager);
-    // Register graph API routes (with per-collection access filtering)
+    await registerWsRoute(fastify, wsHub, authService, config.workspaceManager, yjsManager);
+    // Register graph API routes (with per-folder access filtering)
     await registerGraphApiRoutes(fastify, config.workspaceManager, authService, wsHub, sessionManager);
     // Register workspace API routes (git operations)
-    await registerWorkspaceApiRoutes(fastify, config.workspaceManager, config.gitUser);
+    await registerWorkspaceApiRoutes(fastify, config.workspaceManager, config.gitUser, authService);
+    // Register health endpoints (per-repo dirty status)
+    await registerHealthApiRoutes(fastify, config.workspaceManager, sessionManager);
     // Register config + workspace data API routes (for `studiograph push/pull --remote`)
     await registerConfigApiRoutes(fastify, config.workspaceManager, config.workspacePath, authService);
-    // Register permissions API routes (self-hosted collection access)
+    // Register Phase 7 settings/secrets/audit API routes. Owner-only via
+    // isWorkspaceOwner() inside each handler.
+    await registerSettingsApiRoutes(fastify, authService);
+    await registerSecretsApiRoutes(fastify, authService);
+    await registerAuditApiRoutes(fastify, authService);
+    // Register comments API + notifications feed (Comments-First Phase 1).
+    // The getAgent closure resolves the orchestrator lazily — it's
+    // initialised below at line ~613, AFTER routes register, so route
+    // handlers can't capture it eagerly. The closure binding to the outer
+    // `agent` variable picks up the value once the orchestrator is alive.
+    await registerCommentsApiRoutes(fastify, commentService, notificationService, authService, wsHub, config.workspaceManager, () => agent);
+    // Register chat-session persistence routes (cross-device agent history).
+    // `() => agent` defers the orchestrator handle (assigned below) so the scratch
+    // cleanup can also evict the agent-pool session JSON on chat deletion.
+    await registerChatSessionsApiRoutes(fastify, chatSessionService, config.workspaceManager, authService, wsHub, () => agent);
+    // Register permissions API routes (self-hosted folder access)
     await registerPermissionsApiRoutes(fastify, authService, config.workspaceManager, wsHub);
     // Messages API routes registered after agent init (below) so @agent invocation works
     // Register connectors API routes (MCP connector management + OAuth)
     await registerConnectorsApiRoutes(fastify, authService, config.workspacePath);
+    // Register OAuth 2.0 authorization-server routes (Claude Chat/Cowork connect)
+    await registerOAuthApiRoutes(fastify, authService, config.workspaceConfig);
     // Register asset upload routes (image upload to R2/local)
     await registerAssetApiRoutes(fastify, config.workspaceManager, authService);
+    // Register public share-link routes (mint authed; read + asset public)
+    await registerShareApiRoutes(fastify, config.workspaceManager, authService, shareLinkService);
+    // Register authenticated artifact export routes.
+    await registerArtifactExportApiRoutes(fastify, config.workspaceManager, authService);
+    // Register R2 management routes (bucket creation, local-asset sync, status)
+    await registerR2ApiRoutes(fastify, config.workspaceManager, authService, config.gitUser);
     // Register git Smart HTTP routes (clone/fetch/push with Basic Auth)
     await registerGitHttpRoutes(fastify, config.workspaceManager, authService, config.workspacePath, wsHub);
     // Register views API routes (per-user saved views)
     await registerViewsApiRoutes(fastify, authService, config.workspaceManager);
     // Register insights + preferences API routes
-    // Build core tool metadata once from actual tool factories
-    const coreToolMeta = [];
-    try {
-        const { createGraphTools } = await import('../agent/tools/graph-tools.js');
-        const { createOpsTools } = await import('../agent/tools/ops-tools.js');
-        const dummyUser = { id: '0', name: 'system', email: 'system' };
-        const allTools = [
-            ...createGraphTools(config.workspaceManager, dummyUser, config.workspacePath, undefined, undefined, () => null, authService),
-            ...createOpsTools(config.workspacePath, config.workspaceConfig),
-        ];
-        for (const t of allTools) {
-            if (t.name && t.description) {
-                coreToolMeta.push({ name: t.name, description: t.description });
-            }
-        }
-    }
-    catch (err) {
-        console.warn('[insights] Failed to build tool metadata:', err);
-    }
-    const getToolsForUser = (userId) => {
-        const tools = [...coreToolMeta];
-        // Add connector tools based on user's actually connected services
-        try {
-            const connectedConnectors = authService.getUserConnectedConnectors(userId);
-            for (const c of connectedConnectors) {
-                tools.push({ name: `${c.connector_name}_connector`, description: `Connected ${c.connector_name} integration — can sync and access ${c.connector_name} data` });
-            }
-        }
-        catch { /* no connector tools */ }
-        return tools;
-    };
-    await registerBriefingApiRoutes(fastify, config.workspaceManager, authService, config.workspacePath, wsHub, getToolsForUser);
-    // Background briefing refresh — check staleness for online users every heartbeat tick
-    {
-        const BRIEFING_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
-        const loadWsConfig = () => {
-            const cfgPath = join(config.workspacePath, '.studiograph', 'workspace.json');
-            if (!existsSync(cfgPath))
-                return undefined;
-            try {
-                return JSON.parse(readFileSync(cfgPath, 'utf-8'));
-            }
-            catch {
-                return undefined;
-            }
-        };
-        const getReposForUser = (userId) => {
-            const allRepos = config.workspaceManager.getAllRepoConfigs();
-            const user = authService.findUserById(userId);
-            if (!user)
-                return allRepos.filter(r => !r.private).map(r => r.name);
-            if (isAdminOrOwner(user.role))
-                return allRepos.filter(r => !r.private || r.owner_id === user.id).map(r => r.name);
-            const allowed = new Set(authService.getUserCollections(user.id));
-            return allRepos.filter(r => (r.private && r.owner_id === user.id) || allowed.has(r.name)).map(r => r.name);
-        };
-        wsHub.setBriefingRefresh((userId) => {
-            const brief = authService.getHomeBrief(userId);
-            if (!brief)
-                return false;
-            // Always regenerate if no briefing text exists yet (migration from old insights system)
-            const cached = authService.getCachedBriefing(userId);
-            if (!cached.briefingText)
-                return true;
-            const age = authService.getCachedBriefingAge(userId);
-            return age === null || age > BRIEFING_MAX_AGE_MS;
-        }, async (userId) => {
-            const brief = authService.getHomeBrief(userId);
-            const repoNames = getReposForUser(userId);
-            const tools = getToolsForUser(userId);
-            try {
-                const { generateBriefing } = await import('../services/briefing.js');
-                await generateBriefing(config.workspaceManager, repoNames, brief, authService, userId, loadWsConfig(), tools);
-                wsHub.broadcastToUser(String(userId), { type: 'briefing_updated', timestamp: new Date().toISOString() });
-                console.log(`[briefing] Background refresh complete for user ${userId}`);
-            }
-            catch (err) {
-                console.error(`[briefing] Background refresh failed for user ${userId}:`, err.message);
-            }
-        });
-    }
-    // Register meeting ingest API (Chrome extension + other capture tools)
-    await registerMeetingIngestRoutes(fastify, config.workspaceManager, authService, wsHub);
+    await registerInsightsApiRoutes(fastify, config.workspaceManager, authService, config.workspacePath, wsHub, chatSessionService);
+    // Register event ingest API (meeting capture from desktop and external sources)
+    await registerEventIngestRoutes(fastify, config.workspaceManager, authService, wsHub, yjsManager);
     // Register MCP Streamable HTTP endpoint
-    await registerMcpRoutes(fastify, config.workspaceManager, authService);
-    // Serve chrome assets (shared header/footer for app editors)
-    const chromeDir = join(import.meta.dirname, 'chrome');
-    if (existsSync(chromeDir)) {
-        const CHROME_MIME = { '.js': 'application/javascript', '.css': 'text/css' };
-        fastify.get('/api/chrome/:file', async (req, reply) => {
-            const file = req.params.file;
-            if (file.includes('..') || file.includes('/')) {
-                return reply.status(400).send({ error: 'Invalid path' });
-            }
-            const filePath = join(chromeDir, file);
-            if (!existsSync(filePath) || !statSync(filePath).isFile()) {
-                return reply.status(404).send({ error: 'Not found' });
-            }
-            const ext = extname(filePath).toLowerCase();
-            reply.type(CHROME_MIME[ext] || 'application/octet-stream');
-            reply.header('Cache-Control', 'public, max-age=300');
-            return reply.send(createReadStream(filePath));
-        });
-    }
-    // Discover installed apps and collect their skill/tool dirs
-    const loader = new PluginLoader();
-    const manifests = loader.loadApps(config.appsDir);
-    const appSkillsDirs = [];
-    const appToolsDirs = [];
-    for (const manifest of manifests) {
-        const skillsDir = loader.getSkillsDir(config.appsDir, manifest);
-        if (skillsDir)
-            appSkillsDirs.push(skillsDir);
-        const toolsDir = loader.getToolsDir(config.appsDir, manifest);
-        if (toolsDir)
-            appToolsDirs.push(toolsDir);
-    }
-    // Initialize memory service and agent — non-fatal so the server can still serve graph API and apps
+    await registerMcpRoutes(fastify, config.workspaceManager, authService, wsHub, commentService);
+    // Initialize memory service and agent — non-fatal so the server can still serve graph API
     const memoryService = new MemoryService();
     let agent = null;
     try {
@@ -331,13 +714,23 @@ export async function createServer(config) {
             workspacePath: config.workspacePath,
             workspaceConfig: config.workspaceConfig,
             gitUser: config.gitUser,
-            skillsDirs: appSkillsDirs,
-            toolsDirs: appToolsDirs,
             recentMemory,
             workspaceManager: config.workspaceManager,
-            messageService,
+            // Share the route-level AuthService. Without this the orchestrator
+            // constructs its own crypto-less copy and (a) errors when reading
+            // encrypted oauth_tokens rows, (b) subscribes to a different
+            // pubsub than the one the OAuth callback fires on — so per-user
+            // OAuth state changes never invalidate the agent pool.
+            authService,
+            // Lets the agent's generic read tools resolve the virtual `comment`
+            // entity type, and lets the chat route fold an entry's comments into
+            // context (see registerChatRoutes below).
+            commentService,
+            // Lets the agent's `save_file_to_assets` tool promote a conversation
+            // scratch image into the curated asset library.
+            chatSessionService,
         });
-        await registerChatRoutes(fastify, agent, memoryService);
+        await registerChatRoutes(fastify, agent, wsHub, authService, memoryService, commentService, chatSessionService);
         await registerCaptureRoutes(fastify, agent);
         await registerUrlRoutes(fastify);
     }
@@ -357,67 +750,34 @@ export async function createServer(config) {
             return reply.status(503).send({ error: 'The AI agent is not configured yet. Please set the API key for your model provider in the server environment variables and restart.' });
         });
     }
-    // Initialize heartbeat service for conversation analysis
-    let heartbeatService = null;
-    try {
-        const { HeartbeatService } = await import('../services/heartbeat.js');
-        heartbeatService = new HeartbeatService(messageService, config.workspaceManager, wsHub, config.workspaceConfig);
-        heartbeatService.start();
-    }
-    catch (err) {
-        fastify.log.warn(`Heartbeat not available: ${err.message}`);
-    }
-    // Register messages API routes (collection-scoped messaging with @agent support)
-    await registerMessagesApiRoutes(fastify, messageService, authService, wsHub, config.workspaceManager, agent, heartbeatService);
-    // GET /api/apps — list installed app manifests with resolved entity type names
-    const resolvedApps = manifests.map(m => {
-        let entityTypes = [];
-        try {
-            const etPath = join(config.appsDir, m.name, m.entityTypes);
-            if (existsSync(etPath)) {
-                const raw = JSON.parse(readFileSync(etPath, 'utf-8'));
-                if (Array.isArray(raw)) {
-                    entityTypes = raw.map((item) => item.name).filter(Boolean);
-                }
-            }
-        }
-        catch {
-            // gracefully degrade — return empty array
-        }
-        return { name: m.name, version: m.version, description: m.description, mountPath: m.mountPath, entityTypes };
-    });
-    fastify.get('/api/apps', async (_req, reply) => {
-        return reply.send(resolvedApps);
-    });
     // GET /api/workspace — workspace metadata
     fastify.get('/api/workspace', async (_req, reply) => {
         const workspace = new Workspace(config.workspacePath);
         const about = workspace.loadAbout();
-        return reply.send({ name: config.workspaceConfig.team_name, about, accent_color: config.workspaceConfig.accent_color ?? null });
+        return reply.send({ name: config.workspaceConfig.team_name, about });
     });
-    // PUT /api/workspace — update workspace identity (admin only)
+    // GET /api/server-info — identity probe for the stdio MCP proxy.
+    // Authed by the global middleware (not in the exempt list), so a 401/403 here
+    // tells the proxy "server present, token rejected" → fail loud, never write
+    // locally. The serverId + workspacePath let the proxy confirm it is talking
+    // to the server that owns this exact workspace before forwarding tool calls.
+    fastify.get('/api/server-info', async (_req, reply) => {
+        return reply.send({
+            serverId: config.serverId ?? null,
+            workspacePath: config.workspacePath,
+            name: config.workspaceConfig.team_name,
+        });
+    });
+    // PUT /api/workspace — update workspace identity (owner only)
     fastify.put('/api/workspace', async (req, reply) => {
         const user = req.user;
-        if (user && !isAdminOrOwner(user.role)) {
-            return reply.status(403).send({ error: 'Admin access required' });
+        if (user && !isWorkspaceOwner(user.role)) {
+            return reply.status(403).send({ error: 'Workspace owner access required' });
         }
-        const { name, about, accent_color } = req.body ?? {};
+        const { name, about } = req.body ?? {};
         const workspace = new Workspace(config.workspacePath);
-        let configChanged = false;
         if (typeof name === 'string' && name.trim()) {
             config.workspaceConfig.team_name = name.trim();
-            configChanged = true;
-        }
-        if (accent_color !== undefined) {
-            if (accent_color === null) {
-                delete config.workspaceConfig.accent_color;
-            }
-            else {
-                config.workspaceConfig.accent_color = accent_color;
-            }
-            configChanged = true;
-        }
-        if (configChanged) {
             workspace.writeConfig(config.workspaceConfig);
         }
         if (typeof about === 'string') {
@@ -425,24 +785,38 @@ export async function createServer(config) {
         }
         return reply.send({ success: true });
     });
-    // GET /api/workspace/mcp-config — MCP client configuration snippet (all authenticated users)
+    // GET /api/workspace/mcp-config — MCP client configuration snippet.
+    // Returns a template with `<your-token-here>` in the Authorization header;
+    // the frontend fills it in after the user mints a personal token via
+    // POST /api/auth/tokens. We never embed a shared key here because doing so
+    // would leak a workspace-wide credential and re-introduce the bug the
+    // per-user-token model exists to solve.
     fastify.get('/api/workspace/mcp-config', async (req, reply) => {
-        const proto = req.headers['x-forwarded-proto'] === 'https' ? 'https' : (req.protocol ?? 'http');
-        const host = req.headers['x-forwarded-host'] || req.headers.host || 'localhost';
-        const baseUrl = `${proto}://${host}`;
-        const apiKey = authService.getApiKey();
+        // Prefer the pinned canonical URL so the connect URL shown in Settings
+        // matches the OAuth issuer/resource. Fall back to the request origin when
+        // none is configured (local dev / unpinned), rather than failing closed —
+        // this endpoint is informational, not a security boundary.
+        let baseUrl;
+        try {
+            baseUrl = resolveCanonicalBaseUrl(config.workspaceConfig, req);
+        }
+        catch {
+            const proto = req.headers['x-forwarded-proto'] === 'https' ? 'https' : (req.protocol ?? 'http');
+            const host = req.headers['x-forwarded-host'] || req.headers.host || 'localhost';
+            baseUrl = `${proto}://${host}`;
+        }
         const mcpConfig = {
             mcpServers: {
                 studiograph: {
                     type: 'streamable-http',
                     url: `${baseUrl}/mcp`,
                     headers: {
-                        Authorization: `Bearer ${apiKey}`,
+                        Authorization: 'Bearer <your-token-here>',
                     },
                 },
             },
         };
-        return reply.send({ config: mcpConfig });
+        return reply.send({ config: mcpConfig, url: `${baseUrl}/mcp` });
     });
     // DELETE /api/memory — clear all agent memory files
     fastify.delete('/api/memory', async (_req, reply) => {
@@ -454,19 +828,6 @@ export async function createServer(config) {
         const count = agent?.clearSessions() ?? 0;
         return reply.send({ cleared: count });
     });
-    // Mount app plugins
-    for (const manifest of manifests) {
-        try {
-            await loader.mountPlugin(fastify, manifest, config.appsDir, {
-                workspaceManager: config.workspaceManager,
-                gitUser: config.gitUser,
-            });
-            fastify.log.info(`Mounted app "${manifest.name}" at ${manifest.mountPath}`);
-        }
-        catch (err) {
-            fastify.log.error(err, `Failed to mount app "${manifest.name}"`);
-        }
-    }
     // Serve web UI static files from dist/web/ with SPA fallback
     // When running via tsx from source, import.meta.dirname is src/server/ so ../web doesn't exist.
     // Fall back to dist/web/ relative to project root.
@@ -474,12 +835,34 @@ export async function createServer(config) {
     const webDir = existsSync(webDirCandidate) ? webDirCandidate : join(import.meta.dirname, '..', '..', 'dist', 'web');
     if (existsSync(webDir)) {
         const indexPath = join(webDir, 'index.html');
-        // SPA fallback for app routes: if an app plugin returns a JSON error for a
-        // browser GET request, serve the SPA instead. This happens when the browser
-        // refreshes a URL like /documents/document/doc-123 — the app's greedy route
-        // catches it but fails because the params don't match its expectations.
+        // SPA fallback: if any API route returns a JSON error for a browser GET,
+        // serve the SPA instead so client-side routing can handle the URL.
         // Read fresh from disk each time so rebuilds take effect without server restart.
         const readIndexHtml = () => readFileSync(indexPath);
+        /**
+         * Cache policy for static assets:
+         * - `/_app/immutable/*` are content-hashed by SvelteKit, so the URL
+         *   changes every time the file does — safe to cache forever.
+         * - `index.html` (and the SPA fallback) MUST revalidate every load,
+         *   otherwise stale HTML keeps pointing at expired immutable hashes.
+         * - Other root assets (favicons, og images, etc.) get a modest TTL.
+         *
+         * Without these headers the upstream CDN (Fastly in front of Railway)
+         * forwards almost every request to origin, producing multi-second
+         * TTFB on cold edges and a 3-5s "black screen" while the SPA bundle
+         * loads.
+         */
+        function setStaticCacheHeader(reply, urlPath) {
+            if (urlPath.startsWith('/_app/immutable/')) {
+                reply.header('Cache-Control', 'public, max-age=31536000, immutable');
+            }
+            else if (urlPath === '/' || urlPath === '/index.html' || !extname(urlPath)) {
+                reply.header('Cache-Control', 'no-cache');
+            }
+            else {
+                reply.header('Cache-Control', 'public, max-age=3600');
+            }
+        }
         fastify.addHook('onSend', async (request, reply, payload) => {
             if (reply.sent)
                 return payload;
@@ -490,23 +873,24 @@ export async function createServer(config) {
                 typeof ct === 'string' && ct.includes('application/json')) {
                 reply.removeHeader('content-length');
                 reply.code(200).type('text/html');
+                reply.header('Cache-Control', 'no-cache');
                 return readIndexHtml();
             }
             return payload;
         });
-        // Use setNotFoundHandler so app plugins and API routes take priority
+        // Use setNotFoundHandler so API routes take priority over SPA fallback
         fastify.setNotFoundHandler(async (req, reply) => {
             const urlPath = req.url.split('?')[0];
-            const filePath = urlPath === '/' ? '/index.html' : urlPath;
-            const fullPath = join(webDir, filePath);
+            const fullPath = resolveStaticFilePath(webDir, urlPath);
+            if (!fullPath) {
+                return reply.status(400).send({ error: 'Invalid path' });
+            }
             // Serve the file if it exists (and is a file, not directory)
             if (existsSync(fullPath) && statSync(fullPath).isFile()) {
-                if (fullPath.includes('..')) {
-                    return reply.status(400).send({ error: 'Invalid path' });
-                }
                 const ext = extname(fullPath).toLowerCase();
                 const contentType = MIME_TYPES[ext] || 'application/octet-stream';
                 reply.type(contentType);
+                setStaticCacheHeader(reply, urlPath);
                 return reply.send(createReadStream(fullPath));
             }
             // SPA fallback — serve index.html for client-side routing.
@@ -516,18 +900,22 @@ export async function createServer(config) {
             const hasFileExt = extname(urlPath).length > 1;
             if (req.method === 'GET' && !hasFileExt && existsSync(indexPath)) {
                 reply.type('text/html');
+                reply.header('Cache-Control', 'no-cache');
                 return reply.send(createReadStream(indexPath));
             }
             return reply.status(404).send({ error: 'Not found' });
         });
         fastify.log.info('Web UI enabled — serving from dist/web/');
     }
-    // Graceful shutdown
+    // Graceful shutdown — sessionManager.shutdown() flushes pending commits
+    // BEFORE tearing down the timer (the old destroy()-only path could lose
+    // dirty sessions if called without an explicit flush).
     fastify.addHook('onClose', async () => {
-        await sessionManager.flushAll();
-        sessionManager.destroy();
-        yjsManager.destroy();
+        await sessionManager.shutdown();
+        await assetIndexQueue.shutdown();
+        await yjsManager.destroy();
         wsHub.destroy();
+        releaseYjsLock();
     });
     return fastify;
 }