@pyric/cli 0.1.0-alpha.18 → 0.1.0-alpha.20

package/src/serve/namespace.ts

@@ -18,7 +18,7 @@ import { collectBody } from '../bridge/server/peer.js';
 import { StateFileError, type StateSection, type StateStore } from './state-store.js';
 import { createWriterLock, type WriterLock } from './writer-lock.js';
 import { createStudioRoutes, type StudioRouteOptions } from './studio/index.js';
-import { pipeFileToResponse, type ServeLogger } from './server.js';
+import { pipeFileToResponse, getHeader, isAllowedHost, isAllowedOrigin, type ServeLogger } from './server.js';
 import type { InitPayload } from './init-payload.js';
 import { handleActivity } from './activity-route.js';
 import { createSiteTreeHandler } from './site-tree.js';
@@ -107,6 +107,12 @@ export interface NamespaceOptions {
    *  (disk-backed `WorkspaceStore`/`ProjectStore`, plus the SSE watch stream)
    *  that `@pyric/studio`'s `local` mode talks to. */
   studio?: StudioRouteOptions;
+  /** Per-boot session capability token required on workspace and project endpoints. */
+  sessionToken?: string;
+  /** Bound host for DNS rebinding guard. */
+  boundHost?: string;
+  /** Extra allowed hostnames. */
+  allowedHosts?: string[];
   /** The OpenAI-compatible upstream `/__pyric/ai-proxy` forwards to
    *  (pyric/ai — cdd-deltas #98.2). Falls back to the
    *  `PYRIC_AI_PROXY_UPSTREAM` env var, then `http://localhost:11434/v1`
@@ -471,8 +477,20 @@ async function handleDenials(
 }
 
 export function createPyricNamespace(opts: NamespaceOptions) {
-  const writerLock = createWriterLock();
-  const studioRoutes = opts.studio ? createStudioRoutes(opts.studio) : null;
+  const stateWriterLock = createWriterLock();
+  const studioWriterLock = opts.studio?.writerLock ?? createWriterLock();
+  const sessionToken = opts.sessionToken ?? randomBytes(24).toString('base64url');
+  let studioRoutes: ((req: IncomingMessage, res: ServerResponse, url: URL) => Promise<boolean>) | null = null;
+  if (opts.studio) {
+    const studioOptions: StudioRouteOptions = {
+      ...opts.studio,
+      sessionToken,
+      writerLock: studioWriterLock,
+      boundHost: opts.boundHost,
+      allowedHosts: opts.allowedHosts,
+    };
+    studioRoutes = createStudioRoutes(studioOptions);
+  }
   const siteTree = opts.siteUiDir
     ? createSiteTreeHandler(opts.siteUiDir, opts.workerVersion)
     : null;
@@ -489,7 +507,7 @@ export function createPyricNamespace(opts: NamespaceOptions) {
       return studioRoutes(req, res, url);
     }
     if (opts.state && url.pathname === '/__pyric/state') {
-      return handleState(opts.state!, writerLock, req, res, url).then(() => true);
+      return handleState(opts.state!, stateWriterLock, req, res, url).then(() => true);
     }
     if (opts.capture && url.pathname === '/__pyric/capture') {
       return handleCapture(opts.capture, req, res).then(() => true);
@@ -498,6 +516,21 @@ export function createPyricNamespace(opts: NamespaceOptions) {
       return handleActivity(opts.activity, req, res, activityToken!).then(() => true);
     }
     if (opts.events && url.pathname === '/__pyric/events') {
+      const hostHeader = getHeader(req, 'host');
+      const originHeader = getHeader(req, 'origin');
+      if (!isAllowedHost(hostHeader, opts.boundHost ?? 'localhost', opts.allowedHosts)) {
+        res.writeHead(403, { 'content-type': 'text/plain' }).end('Forbidden: host not allowed');
+        return true;
+      }
+      if (originHeader && !isAllowedOrigin(originHeader, opts.boundHost ?? 'localhost', opts.allowedHosts)) {
+        res.writeHead(403, { 'content-type': 'text/plain' }).end('Forbidden: origin mismatch');
+        return true;
+      }
+      const reqToken = getHeader(req, 'x-pyric-session-token') ?? url.searchParams.get('token');
+      if (sessionToken && reqToken && reqToken !== sessionToken) {
+        res.writeHead(401, { 'content-type': 'text/plain' }).end('Unauthorized: invalid session capability token');
+        return true;
+      }
       opts.events.handle(req, res);
       return true;
     }
@@ -509,7 +542,13 @@ export function createPyricNamespace(opts: NamespaceOptions) {
     }
     if (url.pathname === '/__pyric/init.json') {
       res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
-      res.end(JSON.stringify({ ...opts.initPayload(), ...(activityToken ? { activityToken } : {}) }));
+      res.end(
+        JSON.stringify({
+          ...opts.initPayload(),
+          sessionToken,
+          ...(activityToken ? { activityToken } : {}),
+        }),
+      );
       return true;
     }
     if (url.pathname.startsWith('/__pyric/sdk/')) {

package/src/serve/rules.ts

@@ -56,7 +56,7 @@ export function prepareRulesSource(raw: string, sourcePath: string): string {
     const resolved = resolveModulesBrowser(raw);
     if (!resolved.success) {
       throw new Error(
-        `pyric dev: ${sourcePath} uses 2+modules but module resolution failed: ${resolved.error.message}`,
+        `pyric sandbox: ${sourcePath} uses 2+modules but module resolution failed: ${resolved.error.message}`,
       );
     }
     source = resolved.data.resolved;
@@ -65,13 +65,13 @@ export function prepareRulesSource(raw: string, sourcePath: string): string {
   if (lint.parseError) {
     const { line, column } = lint.parseError;
     throw new Error(
-      `pyric dev: ${sourcePath} failed to parse (line ${line}, col ${column}) — fix the rules before serving.`,
+      `pyric sandbox: ${sourcePath} failed to parse (line ${line}, col ${column}). Fix the rules before serving.`,
     );
   }
   const errors = lint.warnings.filter((w) => w.severity === 'error');
   if (errors.length > 0) {
     throw new Error(
-      `pyric dev: ${sourcePath} has ${errors.length} rules error(s):\n` +
+      `pyric sandbox: ${sourcePath} has ${errors.length} rules error(s):\n` +
         errors.map((e) => `  - ${e.message}`).join('\n'),
     );
   }
@@ -98,7 +98,7 @@ export async function loadProjectRules(
   } catch (e) {
     if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
       if (configured) {
-        throw new Error(`pyric dev: firebase.json points firestore.rules at ${path}, but it does not exist.`);
+        throw new Error(`pyric sandbox: firebase.json points firestore.rules at ${path}, but it does not exist.`);
       }
       return { rules: null, rulesHash: null, sourcePath: null };
     }
@@ -109,19 +109,29 @@ export async function loadProjectRules(
 }
 
 /**
- * Validate a raw storage-rules source. `pyric/storage`'s parser throws a
- * plain `SyntaxError` (no line/col like the firestore lint path) — wrap it
- * into the same actionable "fix before serving" message shape.
+ * Resolve and validate a raw Storage rules source. Modular sources are
+ * authored in storage.modules.rules and resolved in memory before the
+ * sandbox sees them; firebase.json can continue to point at storage.rules.
  */
 export function prepareStorageRulesSource(raw: string, sourcePath: string): string {
+  let source = raw;
+  if (/^\s*rules_version\s*=\s*['"]2\+modules['"]/m.test(raw)) {
+    const resolved = resolveModulesBrowser(raw, { sourceFile: sourcePath });
+    if (!resolved.success) {
+      throw new Error(
+        `pyric sandbox: ${sourcePath} uses 2+modules but module resolution failed: ${resolved.error.message}`,
+      );
+    }
+    source = resolved.data.resolved;
+  }
   try {
-    parseStorageRules(raw);
+    parseStorageRules(source);
   } catch (e) {
     throw new Error(
-      `pyric dev: ${sourcePath} failed to parse: ${e instanceof Error ? e.message : String(e)} — fix the rules before serving.`,
+      `pyric sandbox: ${sourcePath} failed to parse: ${e instanceof Error ? e.message : String(e)}. Fix the rules before serving.`,
     );
   }
-  return raw;
+  return source;
 }
 
 /**
@@ -149,7 +159,7 @@ export async function loadProjectStorageRules(
   } catch (e) {
     if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
       if (configured) {
-        throw new Error(`pyric dev: firebase.json points storage.rules at ${path}, but it does not exist.`);
+        throw new Error(`pyric sandbox: firebase.json points storage.rules at ${path}, but it does not exist.`);
       }
       return { rules: null, rulesHash: null, sourcePath: null };
     }
@@ -159,27 +169,52 @@ export async function loadProjectStorageRules(
   return { rules, rulesHash: rulesHashOf(rules), sourcePath: path };
 }
 
+function normalizeDatabaseEntries(block: unknown): Array<Record<string, unknown>> {
+  if (!block) {
+    return [];
+  }
+  if (Array.isArray(block)) {
+    return block.filter((item): item is Record<string, unknown> => typeof item === 'object' && item !== null);
+  }
+  if (typeof block === 'object' && block !== null) {
+    return [block as Record<string, unknown>];
+  }
+  return [];
+}
+
+function hasConfiguredRules(entry: Record<string, unknown>): entry is Record<string, unknown> & { rules: string } {
+  return typeof entry.rules === 'string';
+}
+
+function hasConfiguredUrl(entry: Record<string, unknown>): entry is Record<string, unknown> & { url: string } {
+  return typeof entry.url === 'string';
+}
+
 export async function loadProjectDatabaseRules(
   cwd: string,
   config: FirebaseJson | null,
 ): Promise<LoadedDatabaseRules> {
-  const configured = config?.database?.rules;
-  if (!configured) {
-    return {
-      rules: null,
-      rulesHash: null,
-      sourcePath: null,
-      databaseUrl: config?.database?.url ?? null,
-    };
-  }
-
-  const path = isAbsolute(configured) ? configured : join(cwd, configured);
+  const entries = normalizeDatabaseEntries(config?.database);
+  const configuredEntry = entries.find(hasConfiguredRules);
+  const configured = configuredEntry?.rules;
+  const rel = configured ?? 'database.rules.json';
+  const path = isAbsolute(rel) ? rel : join(cwd, rel);
+  const urlEntry = entries.find(hasConfiguredUrl);
+  const databaseUrl = urlEntry?.url ?? null;
   let raw: string;
   try {
     raw = await readFile(path, 'utf8');
   } catch (e) {
     if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
-      throw new Error(`pyric dev: firebase.json points database.rules at ${path}, but it does not exist.`);
+      if (configured) {
+        throw new Error(`pyric sandbox: firebase.json points database.rules at ${path}, but it does not exist.`);
+      }
+      return {
+        rules: null,
+        rulesHash: null,
+        sourcePath: null,
+        databaseUrl,
+      };
     }
     throw e;
   }
@@ -188,18 +223,18 @@ export async function loadProjectDatabaseRules(
   try {
     parsed = JSON.parse(stripJsonComments(raw));
   } catch (e) {
-    throw new Error(`pyric dev: ${path} failed to parse as RTDB rules JSON: ${e instanceof Error ? e.message : String(e)}`);
+    throw new Error(`pyric sandbox: ${path} failed to parse as RTDB rules JSON: ${e instanceof Error ? e.message : String(e)}`);
   }
   const rules = parseRtdbRulesJson(
     parsed,
-    () => new Error(`pyric dev: ${path} must contain a top-level "rules" object.`),
+    () => new Error(`pyric sandbox: ${path} must contain a top-level "rules" object.`),
   );
 
   return {
     rules,
     rulesHash: rulesHashOf(raw),
     sourcePath: path,
-    databaseUrl: config?.database?.url ?? null,
+    databaseUrl,
   };
 }
 

package/src/serve/runtime/chip.ts

@@ -18,6 +18,32 @@ export interface PyricRuntimeChip {
   dispose(): void;
 }
 
+interface AiEngineDisplay {
+  primary: string;
+  subline: string | null;
+}
+
+function aiEngineState(): AiEngineDisplay {
+  const engine = (globalThis as { __PYRIC_AI_ENGINE__?: { kind?: string; model?: string } }).__PYRIC_AI_ENGINE__;
+  if (engine?.kind === 'gemini') {
+    return {
+      primary: 'gemini (production)',
+      subline: 'gemini-3.5-flash-lite → gemini-flash-lite-latest',
+    };
+  }
+  if (engine?.kind === 'openai') {
+    const modelLabel = engine.model ? ` (${engine.model})` : '';
+    return {
+      primary: `openai (proxy${modelLabel})`,
+      subline: null,
+    };
+  }
+  return {
+    primary: 'sandbox (scripted)',
+    subline: null,
+  };
+}
+
 const styles = `
   :host {
     --pyric-bg: #1e1e24;
@@ -86,8 +112,11 @@ const styles = `
   .icon-button[data-copy-failed] { color: var(--pyric-error); }
   .icon { height: 15px; width: 15px; }
   .worker-state { border-top: 1px solid var(--pyric-border-soft); color: var(--pyric-muted); font-size: 10px; justify-content: space-between; min-height: 34px; padding: 7px 12px; }
+  .worker-state-col { border-top: 1px solid var(--pyric-border-soft); color: var(--pyric-muted); font-size: 10px; display: flex; flex-direction: column; min-height: 34px; padding: 7px 12px; }
+  .worker-state-row { align-items: center; display: flex; justify-content: space-between; width: 100%; }
+  .worker-state-subline { color: #89899f; font: 9px/1.4 ui-monospace, monospace; margin-top: 4px; overflow-wrap: anywhere; text-align: right; width: 100%; }
   .worker-state .available { color: var(--pyric-warning); }
-  .worker-state .state-label { align-items: center; display: flex; gap: 7px; }
+  .worker-state .state-label, .worker-state-col .state-label { align-items: center; display: flex; gap: 7px; white-space: nowrap; }
   .mini-dot { background: var(--pyric-accent); border-radius: 50%; height: 6px; width: 6px; }
   .available .mini-dot { background: var(--pyric-warning); }
   .epochs { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
@@ -203,6 +232,7 @@ export function mountPyricRuntimeChip(options: PyricRuntimeChipOptions): PyricRu
     const epochs = snapshot.updateAvailable
       ? `${snapshot.runningEpoch?.slice(0, 8) ?? 'unknown'} → ${snapshot.servedEpoch?.slice(0, 8) ?? 'unknown'}`
       : snapshot.runningEpoch?.slice(0, 8) ?? '';
+    const aiState = aiEngineState();
 
     view.innerHTML = `${open ? `
       <section class="panel" role="dialog" aria-label="Pyric runtime">
@@ -214,6 +244,13 @@ export function mountPyricRuntimeChip(options: PyricRuntimeChipOptions): PyricRu
           </div>
         </header>
         <div class="worker-state"><span class="state-label${snapshot.updateAvailable ? ' available' : ''}"><span class="mini-dot"></span>${workerLabel}</span><span class="epochs">${epochs}</span></div>
+        <div class="worker-state-col" data-ai-status>
+          <div class="worker-state-row">
+            <span class="state-label"><span class="mini-dot"></span>AI engine</span>
+            <span class="epochs">${aiState.primary}</span>
+          </div>
+          ${aiState.subline ? `<div class="worker-state-subline">${aiState.subline}</div>` : ''}
+        </div>
         <div class="errors" data-error-viewport>${renderErrors(snapshot, Boolean(clipboard))}</div>
         <div class="actions">
           <button class="button update" type="button" data-update-worker ${snapshot.updateAvailable ? '' : 'disabled'} aria-disabled="${snapshot.updateAvailable && !snapshot.updatingWorker ? 'false' : 'true'}">${snapshot.updatingWorker ? 'Updating…' : 'Update worker'}</button>

package/src/serve/runtime/manifest.ts

@@ -1,7 +1,7 @@
 /** Stable routes and identity used by the served runtime and its UI. */
 export const PYRIC_WORKER_URL = '/__pyric/sdk/worker.js';
 export const PYRIC_WORKER_NAME = 'pyric-shared-worker';
-export const PYRIC_STUDIO_URL = '/__pyric/ui/';
+export const PYRIC_STUDIO_URL = '/__pyric/ui/studio';
 
 export interface PyricRuntimeManifest {
   studioUrl: string;

package/src/serve/runtime/status.ts

@@ -108,6 +108,13 @@ function isListenerPhaseErroredEvent(event: SandboxEvent): boolean {
   return isListenerKind && isErroredPhase && hasErrorPayload;
 }
 
+function isAiRejectedEvent(event: SandboxEvent): boolean {
+  const isServiceMutationKind = event.kind === 'service_mutation';
+  const isAiService = event.service === 'ai';
+  const isRejectedOp = 'op' in event && event.op === 'request_rejected';
+  return isServiceMutationKind && isAiService && isRejectedOp;
+}
+
 function sandboxError(event: SandboxEvent): PyricRuntimeError | null {
   if (isRuntimeErrorEvent(event)) {
     const hasPathProperty = 'path' in event && typeof event.path === 'string';
@@ -127,6 +134,23 @@ function sandboxError(event: SandboxEvent): PyricRuntimeError | null {
       message: errorPayload?.message ? errorPayload.message : 'Sandbox runtime error',
     };
   }
+  if (isAiRejectedEvent(event)) {
+    const detail = 'detail' in event ? (event.detail as Record<string, unknown> | undefined) : undefined;
+    const code = typeof detail?.code === 'string' ? detail.code : 'AI_ERROR';
+    const message = typeof detail?.message === 'string' ? detail.message : 'AI request rejected';
+    const hasPathProperty = 'path' in event && typeof event.path === 'string';
+    const targetPath = hasPathProperty ? event.path : '(ai)';
+    return {
+      id: event.id,
+      source: 'sandbox',
+      at: event.at,
+      service: 'ai',
+      method: 'generateContent',
+      path: targetPath,
+      code,
+      message: `AI_ERROR: ${message}`,
+    };
+  }
   if (isListenerErroredEvent(event)) {
     const errorPayload = (event as { error: { code?: string; message: string } }).error;
     return {

package/src/serve/sandbox-session.ts

@@ -35,6 +35,7 @@ export interface SandboxSessionOptions {
   bridgeUrl?: () => string | null;
   ai?: InitPayload['ai'];
   aiProxyUpstream?: string;
+  permissive?: boolean;
   logger?: ServeLogger;
   activity?: (incident: ActivityIncident) => void;
 }
@@ -97,6 +98,13 @@ export async function createSandboxSession(
     databaseRules: database.rules,
     databaseRulesHash: database.rulesHash,
   };
+  if (!database.sourcePath) {
+    if (options.permissive) {
+      options.logger?.note('  ⓘ RTDB permissive mode active — client reads/writes are open by default.');
+    } else {
+      options.logger?.note('  ⚠ no database.rules.json found — client RTDB reads/writes default to DENY (matching production Firebase). Use --permissive for open prototyping.');
+    }
+  }
   const events = createEventHub();
   const capture: CaptureStore | undefined = (options.capture ?? true)
     ? createCaptureStore(options.projectDir)
@@ -164,6 +172,7 @@ export async function createSandboxSession(
       : seedUsers,
     messaging: true,
     ai: options.ai ?? null,
+    permissive: Boolean(options.permissive),
   });
 
   const summary: SandboxSessionSummary = {
@@ -221,16 +230,13 @@ export async function createSandboxSession(
     }
   };
   const reloadDatabaseRules = async (): Promise<RulesReloadResult> => {
-    const isMissingDatabaseRules = database.sourcePath === null;
-    if (isMissingDatabaseRules) {
-      return { kind: 'not-configured' };
-    }
     try {
       const updated = await loadProjectDatabaseRules(options.projectDir, options.firebaseConfig);
       const isMissingUpdatedRules = updated.rules === null || updated.rulesHash === null;
       if (isMissingUpdatedRules) {
         return { kind: 'not-configured' };
       }
+      database.sourcePath = updated.sourcePath;
       live.databaseRules = updated.rules;
       live.databaseRulesHash = updated.rulesHash;
       events.broadcast('rtdb-rules-update', { rules: updated.rules, rulesHash: updated.rulesHash });

package/src/serve/server.ts

@@ -134,6 +134,23 @@ export function isAllowedUpgrade(
   );
 }
 
+/**
+ * Extract a header value case-insensitively from either Node's IncomingMessage headers
+ * or Fetch API Headers object.
+ */
+export function getHeader(
+  req: { headers?: Record<string, string | string[] | undefined> | Headers },
+  name: string,
+): string | undefined {
+  const headers = req?.headers;
+  if (!headers) return undefined;
+  if (typeof (headers as Headers).get === 'function') {
+    return (headers as Headers).get(name) ?? undefined;
+  }
+  const val = (headers as Record<string, string | string[] | undefined>)[name.toLowerCase()];
+  return Array.isArray(val) ? val.join(', ') : val;
+}
+
 export interface ServeHandle {
   port: number;
   host: string;
@@ -249,7 +266,7 @@ async function handleRequest(
   if (!isAllowedHost(req.headers.host, opts.host ?? 'localhost', opts.allowedHosts)) {
     logger.note(`  ✖ 403 blocked Host '${req.headers.host}' (DNS-rebinding guard)`);
     res.writeHead(403, { 'content-type': 'text/plain' }).end(
-      `pyric dev: refused request for Host '${req.headers.host ?? ''}'. ` +
+      `pyric sandbox: refused request for Host '${req.headers.host ?? ''}'. ` +
         'Only localhost is allowed; use --allowed-host to add one.',
     );
     return;

package/src/serve/studio/routes.ts

@@ -33,12 +33,22 @@ import type {
   WorkspaceChange,
   WorkspaceStore,
 } from './store-types.js';
+import { isAllowedHost, isAllowedOrigin, getHeader } from '../server.js';
+import type { WriterLock } from '../writer-lock.js';
 
 export interface StudioRouteOptions {
   /** The single-project file tree served at `/__pyric/workspace`. */
   workspace?: WorkspaceStore;
   /** The project list served at `/__pyric/projects`. */
   projects?: ProjectStore;
+  /** Per-boot session capability token required on workspace & project endpoints. */
+  sessionToken?: string;
+  /** Single-writer lock validator for file mutation & deletion endpoints. */
+  writerLock?: WriterLock;
+  /** Bound host for DNS rebinding guard. */
+  boundHost?: string;
+  /** Extra hostnames allowed for DNS rebinding/origin guard. */
+  allowedHosts?: string[];
 }
 
 /** Collect the raw request body as a UTF-8 string. */
@@ -207,6 +217,10 @@ async function handleProjects(
     .end('method not allowed');
 }
 
+function isWorkspaceMutation(method?: string): boolean {
+  return method === 'PUT' || method === 'POST' || method === 'PATCH' || method === 'DELETE';
+}
+
 /**
  * Build a namespace fragment for the Studio storage routes. Returns a handler
  * shaped like the other `/__pyric/*` fragments: it resolves `true` when it
@@ -219,13 +233,55 @@ export function createStudioRoutes(opts: StudioRouteOptions) {
     url: URL,
   ): Promise<boolean> => {
     try {
-      if (opts.workspace && url.pathname.startsWith('/__pyric/workspace')) {
-        await handleWorkspace(opts.workspace, req, res, url);
-        return true;
-      }
-      if (opts.projects && url.pathname.startsWith('/__pyric/projects')) {
-        await handleProjects(opts.projects, req, res, url);
-        return true;
+      const isWorkspaceRoute = opts.workspace && url.pathname.startsWith('/__pyric/workspace');
+      const isProjectsRoute = opts.projects && url.pathname.startsWith('/__pyric/projects');
+
+      if (isWorkspaceRoute || isProjectsRoute) {
+        const hostHeader = getHeader(req, 'host');
+        const originHeader = getHeader(req, 'origin');
+
+        // 1. Host and Origin guard (Requirement 1)
+        if (!isAllowedHost(hostHeader, opts.boundHost ?? 'localhost', opts.allowedHosts)) {
+          res.writeHead(403, { 'content-type': 'text/plain' }).end('Forbidden: host not allowed');
+          return true;
+        }
+        if (originHeader && !isAllowedOrigin(originHeader, opts.boundHost ?? 'localhost', opts.allowedHosts)) {
+          res.writeHead(403, { 'content-type': 'text/plain' }).end('Forbidden: origin mismatch');
+          return true;
+        }
+
+        // 2. Per-boot session capability token guard (Requirement 2)
+        if (opts.sessionToken) {
+          const reqToken =
+            getHeader(req, 'x-pyric-session-token') ??
+            url.searchParams.get('token');
+          if (!reqToken || reqToken !== opts.sessionToken) {
+            res.writeHead(401, { 'content-type': 'text/plain' }).end('Unauthorized: invalid session capability token');
+            return true;
+          }
+        }
+
+        // 3. Single-writer lock guard for mutation endpoints (Requirement 4)
+        if (opts.writerLock && isWorkspaceMutation(req.method)) {
+          const writerId = getHeader(req, 'x-pyric-writer');
+          if (!writerId) {
+            res.writeHead(423, { 'content-type': 'text/plain' }).end('Locked: missing active writer lock header');
+            return true;
+          }
+          if (!opts.writerLock.claim(writerId, Date.now())) {
+            res.writeHead(423, { 'content-type': 'text/plain' }).end('Locked: another tab holds the writer lock');
+            return true;
+          }
+        }
+
+        if (isWorkspaceRoute) {
+          await handleWorkspace(opts.workspace!, req, res, url);
+          return true;
+        }
+        if (isProjectsRoute) {
+          await handleProjects(opts.projects!, req, res, url);
+          return true;
+        }
       }
     } catch (e) {
       if (!res.headersSent) sendError(res, e);

package/src/serve/vite-ai-config.ts

@@ -44,7 +44,18 @@ export function loadViteAiEnv(
   const resolvedEnvDir = envDir === undefined
     ? resolvedRoot
     : path.resolve(resolvedRoot, envDir);
-  return loadEnv(mode, resolvedEnvDir, '');
+  const loaded = loadEnv(mode, resolvedEnvDir, '');
+  for (const [key, val] of Object.entries(loaded)) {
+    const isAuthKey =
+      key === 'GEMINI_API_KEY' ||
+      key === 'GOOGLE_GENAI_API_KEY' ||
+      key === 'VITE_GEMINI_API_KEY' ||
+      key === 'PYRIC_API_KEY';
+    if (isAuthKey && process.env[key] === undefined) {
+      process.env[key] = val;
+    }
+  }
+  return loaded;
 }
 
 /** Convert a public declarative engine into the JSON-safe worker wire shape. */
@@ -65,6 +76,21 @@ export function engineConfigToWire(engine: PyricAiEngineConfig): AiEngineConfigW
     }
     return result as AiEngineConfigWire;
   }
+  const isGeminiEngine = engine.kind === 'gemini';
+  if (isGeminiEngine) {
+    const result: Record<string, unknown> = {
+      kind: 'gemini',
+    };
+    const hasBaseUrl = engine.baseUrl !== undefined;
+    if (hasBaseUrl) {
+      result.baseUrl = engine.baseUrl;
+    }
+    const hasApiKey = engine.apiKey !== undefined;
+    if (hasApiKey) {
+      result.apiKey = engine.apiKey;
+    }
+    return result as AiEngineConfigWire;
+  }
   const result: Record<string, unknown> = {
     kind: 'scripted',
   };
@@ -123,12 +149,16 @@ export function resolveViteAiConfig(
   }
 
   let engineWire: AiEngineConfigWire | undefined = undefined;
-  if (!isProductionMode) {
-    if (explicitEngine !== undefined) {
-      engineWire = engineConfigToWire(explicitEngine);
-    } else if (model !== undefined) {
-      engineWire = engineConfigToWire({ kind: 'openai', baseUrl: AI_PROXY_PATH, model });
-    }
+  if (isProductionMode) {
+    const apiKey = env.GEMINI_API_KEY ?? env.GOOGLE_GENAI_API_KEY ?? env.VITE_GEMINI_API_KEY;
+    engineWire = {
+      kind: 'gemini',
+      ...(apiKey !== undefined && apiKey.trim() !== '' ? { apiKey: apiKey.trim() } : {}),
+    };
+  } else if (explicitEngine !== undefined) {
+    engineWire = engineConfigToWire(explicitEngine);
+  } else if (model !== undefined) {
+    engineWire = engineConfigToWire({ kind: 'openai', baseUrl: AI_PROXY_PATH, model });
   }
 
   let proxyUpstream: string | undefined = undefined;

package/src/serve/vite-module-swap.ts

@@ -86,20 +86,6 @@ export function createViteModuleSwap(
 
         const match = FIREBASE_SPECIFIER.exec(args.path);
         const subpath = match !== null && match[1] !== undefined ? match[1] : '';
-        const isProductionAiMode = aiMode() === 'production';
-        if (isProductionAiMode) {
-          const isAiSubpath = subpath === 'ai';
-          if (isAiSubpath) {
-            return null;
-          }
-          const isAppSubpath = subpath === 'app';
-          const passthroughEntry = entries['app-ai-passthrough'];
-          const hasPassthroughEntry = passthroughEntry !== undefined;
-          const shouldUsePassthroughBridge = isAppSubpath && hasPassthroughEntry;
-          if (shouldUsePassthroughBridge) {
-            return { path: passthroughEntry };
-          }
-        }
 
         const isServedSubpath = SERVED_FIREBASE_SUBPATHS.has(subpath);
         if (isServedSubpath) {
@@ -173,20 +159,6 @@ export function createViteModuleSwap(
       const isFirebaseSpecifier = firebaseMatch !== null;
       if (isFirebaseSpecifier) {
         const subpath = firebaseMatch[1] !== undefined ? firebaseMatch[1] : '';
-        const isProductionAiMode = aiMode() === 'production';
-        if (isProductionAiMode) {
-          const isAiSubpath = subpath === 'ai';
-          if (isAiSubpath) {
-            return null;
-          }
-          const isAppSubpath = subpath === 'app';
-          const passthroughEntry = entries['app-ai-passthrough'];
-          const hasPassthroughEntry = passthroughEntry !== undefined;
-          const shouldUsePassthroughBridge = isAppSubpath && hasPassthroughEntry;
-          if (shouldUsePassthroughBridge) {
-            return passthroughEntry;
-          }
-        }
         const isServedSubpath = SERVED_FIREBASE_SUBPATHS.has(subpath);
         if (isServedSubpath) {
           const key = entryKey(subpath);