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

package/src/serve/runtime/identity.ts

@@ -0,0 +1,26 @@
+import type { AuthUserRecord } from 'pyric/auth';
+
+export interface RuntimeIdentity {
+  uid: string;
+  email?: string | null;
+  displayName?: string | null;
+}
+
+/** The chip's complete identity integration seam, passed intact through mounting. */
+export interface RuntimeIdentityBindings {
+  listUsers(): Promise<AuthUserRecord[]> | AuthUserRecord[];
+  switchUser(uid: string): Promise<void> | void;
+  signOut(): Promise<void> | void;
+  openCreateUser(): void;
+  getCurrentUser(): RuntimeIdentity | null;
+  subscribeAuth(listener: (user: RuntimeIdentity | null) => void): () => void;
+}
+
+export function projectRuntimeIdentity(user: RuntimeIdentity | null | undefined): RuntimeIdentity | null {
+  if (!user) return null;
+  return {
+    uid: user.uid,
+    email: user.email,
+    displayName: user.displayName,
+  };
+}

package/src/serve/sandbox-session.ts

@@ -14,6 +14,7 @@ import {
   rulesHashOf,
 } from './rules.js';
 import { createEventHub, createPyricNamespace } from './namespace.js';
+import type { BeaconReport } from '../register/beacon.js';
 import { diskProjectStore, diskWorkspace } from './studio/index.js';
 import type { ServeLogger } from './server.js';
 import {
@@ -38,6 +39,12 @@ export interface SandboxSessionOptions {
   permissive?: boolean;
   logger?: ServeLogger;
   activity?: (incident: ActivityIncident) => void;
+  /** Receives one handshake beacon per pyric-launched child, the dev
+   *  server's only positive proof that the register module reached it. */
+  beacon?: (report: BeaconReport) => void;
+  /** The per-launch secret a beacon must present, also placed in the child's
+   *  `PYRIC_BEACON_TOKEN`. */
+  beaconToken?: string;
 }
 
 export interface SandboxSessionSummary {
@@ -212,6 +219,8 @@ export async function createSandboxSession(
     workerVersion: options.sdk.workerVersion,
     aiProxyUpstream: options.aiProxyUpstream,
     activity: options.activity,
+    beacon: options.beacon,
+    beaconToken: options.beaconToken,
     logger: options.logger,
   });
 

package/src/serve/studio/disk-workspace.ts

@@ -17,8 +17,16 @@ import {
   stat,
   writeFile,
 } from 'node:fs/promises';
-import { existsSync, mkdirSync, watch as fsWatch, type FSWatcher } from 'node:fs';
-import { dirname, join, posix, relative, resolve, sep } from 'node:path';
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readlinkSync,
+  realpathSync,
+  watch as fsWatch,
+  type FSWatcher,
+} from 'node:fs';
+import { basename, dirname, join, posix, relative, resolve, sep } from 'node:path';
 
 import type {
   WorkspaceChange,
@@ -34,6 +42,54 @@ export class WorkspacePathError extends Error {
   }
 }
 
+/**
+ * Resolves the canonical realpath of a path, handling symlinks and non-existent
+ * terminal segments by resolving the nearest existing ancestor.
+ */
+function getCanonicalPath(targetPath: string, seen = new Set<string>()): string {
+  const abs = resolve(targetPath);
+  if (seen.has(abs)) {
+    throw new WorkspacePathError(targetPath);
+  }
+  seen.add(abs);
+
+  try {
+    return realpathSync(abs);
+  } catch (err: any) {
+    if (err?.code === 'ELOOP') {
+      throw new WorkspacePathError(targetPath);
+    }
+    if (err?.code !== 'ENOENT' && err?.code !== 'ENOTDIR') {
+      throw err;
+    }
+  }
+
+  try {
+    const st = lstatSync(abs);
+    if (st.isSymbolicLink()) {
+      const linkTarget = readlinkSync(abs);
+      const nextTarget = resolve(dirname(abs), linkTarget);
+      return getCanonicalPath(nextTarget, seen);
+    }
+  } catch {
+    // abs does not exist as a directory entry
+  }
+
+  const parent = dirname(abs);
+  if (parent === abs) {
+    return abs;
+  }
+  const canonicalParent = getCanonicalPath(parent, seen);
+  return join(canonicalParent, basename(abs));
+}
+
+/** Check whether canonical target is contained within canonical root. */
+function isContained(root: string, target: string): boolean {
+  if (target === root) return true;
+  const prefix = root.endsWith(sep) ? root : root + sep;
+  return target.startsWith(prefix);
+}
+
 /**
  * Resolve a project-relative POSIX path to an absolute OS path inside `root`,
  * or throw {@link WorkspacePathError} if it would escape. Leading slashes are
@@ -52,6 +108,24 @@ export function resolveWorkspacePath(root: string, rel: string): string {
   if (abs !== root && !abs.startsWith(root + sep)) {
     throw new WorkspacePathError(rel);
   }
+
+  // Canonical realpath containment check:
+  // Reject symlinks that escape the workspace root.
+  const canonicalRoot = getCanonicalPath(root);
+  let canonicalTarget: string;
+  try {
+    canonicalTarget = getCanonicalPath(abs);
+  } catch (err) {
+    if (err instanceof WorkspacePathError) {
+      throw new WorkspacePathError(rel);
+    }
+    throw err;
+  }
+
+  if (!isContained(canonicalRoot, canonicalTarget)) {
+    throw new WorkspacePathError(rel);
+  }
+
   return abs;
 }
 

package/src/serve/vite-plugin.ts

@@ -1,18 +1,18 @@
 /**
  * `@pyric/cli/vite` — the firebase→pyric-sandbox swap as a Vite plugin.
  *
- * The serve analog for SOURCE-driven apps: instead of `vite build && pyric dev
+ * The serve analog for SOURCE-driven apps: instead of `vite build && pyric sandbox
  * dist`, a team keeps `vite dev` (HMR, source maps) with the in-process sandbox
  * standing in for Firebase. The app's `firebase/*` imports are UNCHANGED — the
  * plugin swaps them at the module-resolution layer (`resolveId`), the same way
- * `pyric dev` swaps via a runtime import map. (Design: `plans/pyric-vite-plugin.md`.)
+ * `pyric sandbox` swaps via a runtime import map. (Design: `plans/pyric-vite-plugin.md`.)
  *
  * Two flavors, one `apply` function. Under `vite dev` the swap is ALWAYS on.
  * For `vite build` the swap is MODE-gated: a plain `vite build` (mode
  * `production`) ships the real `firebase` package — the swap never reaches the
  * prod artifact — while `vite build --mode development` (any NON-production
  * mode) produces a SANDBOX build that bundles pyric's in-page adapters instead
- * of the real SDK: self-contained, meant to be previewed under `pyric dev`, and
+ * of the real SDK: self-contained, meant to be previewed under `pyric sandbox`, and
  * stamped with the sandbox-build marker so it can never be deployed (`pyric
  * deploy hosting` refuses it). `pyric({ swapInBuild })` forces the build
  * behavior on/off regardless of mode. See `sandbox-marker.ts`.
@@ -24,11 +24,11 @@
  *   - the host-neutral sandbox session — rules, fixtures, stores, live payload,
  *     Studio routes, `/__pyric/*` namespace, and owned cleanup;
  *   - the SharedWorker host — `bundleWorker` served at `/__pyric/sdk/worker.js`;
- *   - the bridge mount shared with `pyric dev --bridge`.
+ *   - the bridge mount shared with `pyric sandbox --bridge`.
  *
  * Scope = M1 (swap + rules) + M2 (SharedWorker multi-tab + persist/capture/seed)
  * + M3 (the MCP bridge fold — `{ bridge }`). M3 reuses `createBridgeMount` (the
- * proven serve-flavored bridge behind `pyric dev --bridge`), composing it into
+ * proven serve-flavored bridge behind `pyric sandbox --bridge`), composing it into
  * the same `/__pyric` middleware; on the worker path the bridge peer routes
  * agent tool-calls THROUGH the SharedWorker (`connectBridgePeer`), so the agent
  * and the app share one backend without forcing the page in-page.
@@ -82,7 +82,7 @@ export interface PyricOptions {
    *  only when the worker bundle itself fails, bridge or not. */
   bridge?: boolean | { project?: string; disableAuditLog?: boolean };
   /** Serve the **Pyric Studio** app at `/__pyric/ui/` on Vite's dev origin (the
-   *  `pyric dev --ui` equivalent). Mounts the disk-backed workspace/project
+   *  `pyric sandbox --ui` equivalent). Mounts the disk-backed workspace/project
    *  routes Studio's `local` mode talks to AND serves the unified Astro site
    *  (vendored in this package at `dist/serve/site-ui`). **On by default**,
    *  including under `bridge` (the bridge peer routes through the SharedWorker,
@@ -93,7 +93,7 @@ export interface PyricOptions {
    *  dev/builds. On by default. Pass `false` to hide it, or
    *  `{ initiallyOpen: true }` when actively debugging runtime errors. */
   runtimeChip?: PyricRuntimeChipOption;
-  /** RTDB-triggered Cloud Functions under this dev server (the `pyric dev`
+  /** RTDB-triggered Cloud Functions under this dev server (the `pyric sandbox`
    *  parity fold). By default a `functions` block in `firebase.json` is
    *  discovered automatically: its `onValueCreated` triggers run in an isolated
    *  node child against the shared sandbox (other trigger kinds warn and are
@@ -216,7 +216,7 @@ export function pyric(options: PyricOptions = {}): Plugin {
     // `vite build` keeps the real firebase package — the swap never reaches
     // production output. A sandbox build applies the same swap so the output
     // bundles pyric's in-page adapters (self-contained; preview it under
-    // `pyric dev`, never deploy it).
+    // `pyric sandbox`, never deploy it).
     apply(config, env) {
       void config;
       return pageRuntime.applies(env);

package/src/serve/vite-sandbox-generation.ts

@@ -7,6 +7,7 @@ import {
   type FunctionsRtdbProject,
 } from '../functions-rtdb/project.js';
 import { formatActivityWarning } from './activity-warning.js';
+import { formatAiStatusNote } from './ai-status.js';
 import {
   createBridgeMount,
   type BridgeHostAttachment,
@@ -217,6 +218,20 @@ export async function createViteSandboxGeneration(
       server.config.logger.info('  ⓘ [pyric] fresh: discarded the existing state file; re-seeding');
     }
 
+    // Say what AI resolved to. This is the one front door where the engine and
+    // its model binding ARE known at boot (`ai.engine` / `ai.model` reduced to
+    // the wire shape above); the broker itself is still built lazily, in the
+    // page or the worker, on the first `ai.*` op. Every generation prints it,
+    // so a Vite restart on an `.env`/config edit re-announces the new binding
+    // through the same formatter instead of swapping engines in silence.
+    server.config.logger.info(
+      formatAiStatusNote({
+        engine: ai.engineWire,
+        mode: ai.mode,
+        proxyUpstream: ai.proxyUpstream,
+      }),
+    );
+
     const middlewareInput = { server, bridge, session };
     const disposeMiddleware = attachViteGenerationMiddleware(middlewareInput);
     listenerDisposers.push(disposeMiddleware);

package/src/serve/worker/client/auth.ts

@@ -312,7 +312,7 @@ export async function restorePortSession(
     t: 'op', id: nextId(), method: 'auth.restorePortSession', uid,
   })) as SerializedUser | null;
   const user = toClientUser(auth.port, raw);
-  if (user) auth.currentUser = user;
+  auth.currentUser = user;
   return user;
 }
 

package/src/serve/worker/client/core.ts

@@ -259,26 +259,103 @@ export function wirePort(port: ClientPort): void {
 // ops (`auth.*`) and `getVersion` are NEVER lensed — they operate the worker's
 // session, not data — so the lens is stamped only on the data-op path.
 
+export const AUTH_LENS_STORAGE_KEY = 'pyric:auth-lens';
+
+type PersistedAuthLens =
+  | Extract<AuthLens, { mode: 'admin' }>
+  | Extract<AuthLens, { mode: 'as' }>;
+
+export function isPersistedAuthLens(value: unknown): value is PersistedAuthLens {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as { mode?: unknown; uid?: unknown };
+  if (candidate.mode === 'admin') return true;
+  return candidate.mode === 'as' && typeof candidate.uid === 'string';
+}
+
+function normalizePersistedAuthLens(value: unknown): PersistedAuthLens | undefined {
+  if (isPersistedAuthLens(value)) return value;
+  return undefined;
+}
+
+/** Read persisted auth lens from sessionStorage safely. */
+export function hydrateLensFromStorage(): AuthLens | undefined {
+  if (typeof sessionStorage === 'undefined') return undefined;
+  try {
+    const raw = sessionStorage.getItem(AUTH_LENS_STORAGE_KEY);
+    if (!raw) return undefined;
+    const parsed: unknown = JSON.parse(raw);
+    const persistedLens = normalizePersistedAuthLens(parsed);
+    if (persistedLens) return persistedLens;
+    sessionStorage.removeItem(AUTH_LENS_STORAGE_KEY);
+    return undefined;
+  } catch {
+    try {
+      sessionStorage.removeItem(AUTH_LENS_STORAGE_KEY);
+    } catch {
+      // Ignore storage restrictions
+    }
+    return undefined;
+  }
+}
+
 /** Module-level default lens. `undefined` ⇒ the worker treats the op as the
  *  app's session (the additive default — existing senders omit `actAs`).
  *
  *  Exported as a LIVE binding: family modules read it to stamp the lens onto
  *  subscriptions (`onSnapshot`, `rtdbOnValue`), and see `setLens(...)` updates
  *  through this one singleton. */
-export let _defaultLens: AuthLens | undefined;
+export let _defaultLens: AuthLens | undefined = hydrateLensFromStorage();
+
+const lensListeners = new Set<(lens: AuthLens | undefined) => void>();
+
+/**
+ * Register a listener for auth lens mutations.
+ * Returns an unsubscribe function that removes the listener.
+ */
+export function subscribeLens(listener: (lens: AuthLens | undefined) => void): () => void {
+  lensListeners.add(listener);
+  return () => {
+    lensListeners.delete(listener);
+  };
+}
 
 /**
  * Set the default auth lens applied to subsequent Firestore DATA ops from this
- * client (Pyric Studio). Pass `{ mode: 'as', uid }` to read/write AS a user
+ * client (Pyric Studio & Runtime Chip). Pass `{ mode: 'as', uid }` to read/write AS a user
  * (rules apply), `{ mode: 'admin' }` for the admin lens, or
  * `{ mode: 'app-session' }` / `undefined` to revert to the app's own session.
  *
  * The lens is process-wide for this client module (one served page = one
  * worker port), mirroring how Studio drives a single active identity at a time.
  * Auth ops are unaffected — they always operate the real session.
+ *
+ * Persists active admin and impersonation lenses to sessionStorage under
+ * AUTH_LENS_STORAGE_KEY, and removes the key when cleared or reverted to the
+ * app session.
+ * Notifies all registered subscribeLens listeners.
  */
 export function setLens(lens: AuthLens | undefined): void {
-  _defaultLens = lens && lens.mode === 'app-session' ? undefined : lens;
+  _defaultLens = normalizePersistedAuthLens(lens);
+
+  if (typeof sessionStorage !== 'undefined') {
+    try {
+      if (_defaultLens) {
+        sessionStorage.setItem(AUTH_LENS_STORAGE_KEY, JSON.stringify(_defaultLens));
+      } else {
+        sessionStorage.removeItem(AUTH_LENS_STORAGE_KEY);
+      }
+    } catch {
+      // Ignore quota or disabled storage restrictions
+    }
+  }
+
+  for (const listener of [...lensListeners]) {
+    try {
+      listener(_defaultLens);
+    } catch (err) {
+      console.error('Error in subscribeLens listener:', err);
+    }
+  }
 }
 
 /** The active default lens (read-only view), for Studio UI to reflect state. */

package/src/serve/worker/client.ts

@@ -26,7 +26,7 @@
  */
 
 // Shared core: lens/issuer controls + the handle and snapshot types.
-export { setLens, getLens, setOpIssuer } from './client/core.js';
+export { setLens, getLens, subscribeLens, AUTH_LENS_STORAGE_KEY, hydrateLensFromStorage, setOpIssuer } from './client/core.js';
 export type {
   ClientDb,
   ClientRtdb,

package/src/serve/worker/context-resolver.ts

@@ -0,0 +1,60 @@
+/**
+ * SharedWorker context resolver.
+ *
+ * Coordinates asynchronous initialization of a singleton resource across
+ * concurrent inbound connection requests or burst messages.
+ *
+ * Invariants:
+ * 1. Single In-Flight Attempt: When multiple callers request the context
+ *    concurrently while initialization is in flight, all callers share the
+ *    single in-flight promise rather than starting parallel initializations.
+ * 2. Unpoisoned on Rejection: If initialization rejects, the memoized promise
+ *    is cleared immediately, allowing subsequent requests to retry initialization
+ *    rather than permanently caching the rejection.
+ * 3. Synchronous Retrieval: Once successfully resolved, the resource is
+ *    available synchronously for shutdown and cleanup handlers.
+ */
+
+export interface ContextResolver<T> {
+  /**
+   * Return the resolved resource or the in-flight initialization promise.
+   * If a previous attempt rejected, starts a new attempt.
+   */
+  get(): Promise<T>;
+
+  /**
+   * Return the successfully resolved resource, or null if not yet resolved
+   * or currently in-flight.
+   */
+  current(): T | null;
+}
+
+export function createContextResolver<T>(factory: () => Promise<T>): ContextResolver<T> {
+  let value: T | null = null;
+  let inFlight: Promise<T> | null = null;
+
+  return {
+    async get(): Promise<T> {
+      if (value !== null) {
+        return value;
+      }
+      if (inFlight === null) {
+        inFlight = factory()
+          .then((resolved) => {
+            value = resolved;
+            return resolved;
+          })
+          .catch((error: unknown) => {
+            inFlight = null;
+            value = null;
+            throw error;
+          });
+      }
+      return inFlight;
+    },
+
+    current(): T | null {
+      return value;
+    },
+  };
+}

package/src/serve/worker/entry.ts

@@ -67,36 +67,33 @@ import {
 } from './service-worker-channel.js';
 import { createServiceWorkerRelay } from './service-worker-relay.js';
 import { createWorkerRetirement } from './retirement.js';
+import { createContextResolver } from './context-resolver.js';
+import { createPortLifecycleManager } from './port-lifecycle.js';
 
 declare const __PYRIC_WORKER_VERSION__: string;
 const workerEpoch = typeof __PYRIC_WORKER_VERSION__ !== 'undefined'
   ? __PYRIC_WORKER_VERSION__
   : 'dev';
 const workerScope = self as unknown as SharedWorkerGlobalScope;
+const contextResolver = createContextResolver(buildCtx);
+const portLifecycle = createPortLifecycleManager();
 const retirement = createWorkerRetirement({
   closeWorker: () => workerScope.close(),
-  beforeAnnounce: async () => { await _ctx?.captureFlush?.(); },
+  beforeAnnounce: async () => { await contextResolver.current()?.captureFlush?.(); },
 });
 
 // ─── Singleton context ────────────────────────────────────────────────────
 
-// `_ctx` is the RESOLVED context, kept for the synchronous `close` handler.
-// The build is memoized as a PROMISE (`_ctxPromise`) — NOT as the resolved
-// value — because init is async (it awaits `/__pyric/init.json` + persistence
-// restore). The first messages arrive in a BURST (the authState sub, the first
-// firestore sub, an op — possibly across two tabs at once); if each re-checked
-// only the resolved `_ctx` they would every one start a fresh init and build a
-// SEPARATE sandbox, so a listener and a write could bind to different
-// instances and never see each other. The promise memo guarantees ONE init.
-let _ctx: HostCtx | null = null;
-let _ctxPromise: Promise<HostCtx> | null = null;
-
 /**
  * Return the shared context, memoizing the in-flight init promise so
- * concurrent first messages await ONE build (see `_ctxPromise` above).
+ * concurrent first messages await ONE build. If initialization rejects,
+ * the rejection is cleared so subsequent connection attempts can retry.
+ * Any ports that closed while initialization was in flight are drained immediately.
  */
-function getCtx(): Promise<HostCtx> {
-  return (_ctxPromise ??= buildCtx());
+async function getCtx(): Promise<HostCtx> {
+  const ctx = await contextResolver.get();
+  portLifecycle.drainClosedPorts(ctx);
+  return ctx;
 }
 
 /**
@@ -125,7 +122,6 @@ async function buildCtx(): Promise<HostCtx> {
         ? (url) => new EventSource(url) as unknown as EventSourceLike
         : null,
   });
-  _ctx = ctx; // publish the resolved ctx for the synchronous close handler
   return ctx;
 }
 
@@ -141,6 +137,7 @@ workerScope.onconnect = (e: MessageEvent) => {
   const port = e.ports[0];
   port.start();
   retirement.connect(port);
+  void getCtx().catch(() => undefined);
 
   let messageQueue = Promise.resolve();
   port.onmessage = (ev: MessageEvent<InboundMessage>) => {
@@ -172,9 +169,16 @@ workerScope.onconnect = (e: MessageEvent) => {
     // cannot overtake an already-posted mutation, and later frames see the
     // disconnected-port tombstone instead of touching the shared backend.
     messageQueue = messageQueue.then(async () => {
+      const portLike = port as unknown as PortLike;
+      if (portLifecycle.isPortClosed(portLike)) {
+        return;
+      }
       try {
         const ctx = await getCtx();
-        await handleMessage(ctx, port as unknown as PortLike, ev.data);
+        if (portLifecycle.isPortClosed(portLike)) {
+          return;
+        }
+        await handleMessage(ctx, portLike, ev.data);
       } catch (e) {
         // eslint-disable-next-line no-console
         console.error('[pyric worker] message handler error:', (e as Error)?.stack ?? e, 'msg:', ev.data);
@@ -188,7 +192,7 @@ workerScope.onconnect = (e: MessageEvent) => {
   // best-effort; subscriptions also GC when the worker itself dies.
   port.addEventListener('close', () => {
     retirement.disconnect(port);
-    if (_ctx) void cleanupPortWithDisconnect(_ctx, port as unknown as PortLike).catch(() => undefined);
+    portLifecycle.onPortClosed(port as unknown as PortLike, contextResolver.current());
   });
 };
 

package/src/serve/worker/host/core.ts

@@ -220,16 +220,18 @@ export function lensDb(ctx: HostCtx, actAs?: AuthLens): Firestore {
   return handle;
 }
 
-export function authStateForLens(actAs: Extract<AuthLens, { mode: 'as' }>): { uid: string; token?: Record<string, unknown> } {
-  return actAs.token === undefined
-    ? { uid: actAs.uid }
-    : { uid: actAs.uid, token: actAs.token };
+export function authStateForLens(actAs: Extract<AuthLens, { mode: 'as' }>): { uid: string; token?: Record<string, unknown>; tenant?: string } {
+  const state: { uid: string; token?: Record<string, unknown>; tenant?: string } = { uid: actAs.uid };
+  if (actAs.token !== undefined) state.token = actAs.token;
+  if (actAs.tenant !== undefined) state.tenant = actAs.tenant;
+  return state;
 }
 
 export function lensCacheKey(actAs: Extract<AuthLens, { mode: 'as' }>): string {
-  return actAs.token === undefined
-    ? actAs.uid
-    : `${actAs.uid}:${JSON.stringify(actAs.token)}`;
+  const parts = [actAs.uid];
+  if (actAs.tenant !== undefined) parts.push(`tenant:${actAs.tenant}`);
+  if (actAs.token !== undefined) parts.push(JSON.stringify(actAs.token));
+  return parts.join(':');
 }
 
 /** Cache key for a real port session; claims are part of authorization identity. */

package/src/serve/worker/host/storage.ts

@@ -68,8 +68,8 @@ function ensureStorage(ctx: HostCtx): FirebaseStorage {
  *     `applyServeInit` (`serve-init.ts`), which opens the storage service
  *     with `payload.storageRules` BEFORE any op can reach `ensureStorage`/
  *     `lensStorage`, so every lens on a served worker enforces the
- *     project's storage.rules (or runs open when the project has none,
- *     matching Firestore/RTDB's no-rules posture). The lens split still
+ *     project's storage.rules (or fails closed when the project has none,
+ *     matching Firebase production's no-rules posture). The lens split still
  *     matters for embedding/test hosts that open the service directly.
  *   - `{ mode: 'admin' }` → the rules-BYPASS handle from
  *     `pyric/storage/internal`'s admin plane — same per-sandbox store +

package/src/serve/worker/host-auth.ts

@@ -213,7 +213,7 @@ export async function handleAuthOp(ctx: HostCtx, port: PortLike, msg: OpMessage)
         } catch {
           session = null;
         }
-        if (session) setPortSession(ctx, port, session);
+        setPortSession(ctx, port, session);
         ok(port, msg.id, session ? serializeUser(session.user) : null);
       } catch (e) { fail(port, msg.id, e); }
       break;

package/src/serve/worker/index.ts

@@ -155,9 +155,12 @@ export {
   inMemoryPersistence,
   browserSessionPersistence,
   browserLocalPersistence,
-  // Auth lens (Pyric Studio — admin / impersonation / app-session)
+  // Auth lens (Pyric Studio & Runtime Chip — admin / impersonation / app-session)
   setLens,
   getLens,
+  subscribeLens,
+  AUTH_LENS_STORAGE_KEY,
+  hydrateLensFromStorage,
   // Storage (Pyric Studio data browse): worker-backed FirebaseStorage mirror
   getStorage,
   ref,

package/src/serve/worker/port-lifecycle.ts

@@ -0,0 +1,45 @@
+import { cleanupPortWithDisconnect, type HostCtx, type PortLike } from './host.js';
+
+/**
+ * SharedWorker port lifecycle manager.
+ *
+ * Tracks ports that close before asynchronous worker context initialization
+ * finishes, preventing dead-port leaks and ensuring that port cleanup / disconnect
+ * operations are drained as soon as the context becomes available.
+ */
+export interface PortLifecycleManager {
+  /** Record port closure. Cleans up immediately if context is ready, or defers until resolution. */
+  onPortClosed(port: PortLike, currentCtx: HostCtx | null): void;
+  /** Drain all deferred closed ports against the newly resolved context. */
+  drainClosedPorts(ctx: HostCtx): void;
+  /** Check whether a port has already closed before processing queued messages. */
+  isPortClosed(port: PortLike): boolean;
+}
+
+export function createPortLifecycleManager(): PortLifecycleManager {
+  const closedPorts = new WeakSet<PortLike>();
+  const pendingClosedPorts = new Set<PortLike>();
+
+  return {
+    onPortClosed(port: PortLike, currentCtx: HostCtx | null): void {
+      closedPorts.add(port);
+      if (currentCtx !== null) {
+        void cleanupPortWithDisconnect(currentCtx, port).catch(() => undefined);
+      } else {
+        pendingClosedPorts.add(port);
+      }
+    },
+
+    drainClosedPorts(ctx: HostCtx): void {
+      if (pendingClosedPorts.size === 0) return;
+      for (const port of pendingClosedPorts) {
+        void cleanupPortWithDisconnect(ctx, port).catch(() => undefined);
+      }
+      pendingClosedPorts.clear();
+    },
+
+    isPortClosed(port: PortLike): boolean {
+      return closedPorts.has(port);
+    },
+  };
+}

package/src/serve/worker/serve-init.ts

@@ -39,6 +39,7 @@ import {
 } from 'pyric/sandbox/internal';
 import type { InitPayload } from '../namespace.js';
 import { setupFirebaseActivityGuard } from './activity-bootstrap.js';
+import { setupAiDiagnosticsRelay } from '../ai-diagnostics-relay.js';
 import { createWorkerDurableBackend, setupServerAuthFlush } from './durable-persistence.js';
 import { ensureAuth, getOrCreateInstanceId, type HostCtx } from './host.js';
 import { buildVerifyFixture, type PyricVerifyFixture } from '../../verify/fixture.js';
@@ -245,8 +246,7 @@ export function applyServeInit(
   //     always open storage with no `rules` option, so whichever call opens
   //     the service first wins — making this the sanctioned place to
   //     configure it. `payload.storageRules` is null when the project has no
-  //     storage.rules, matching the same open-by-default posture as no
-  //     firestore.rules / no database.rules.
+  //     storage.rules, so the storage sandbox retains its fail-closed default.
   //     The open ALSO claims the project-scoped IDB name
   //     (`pyric-storage:<projectKey>`, issue #359) — which is why it now runs
   //     unconditionally: a lazy first open from `ensureStorage`/`lensStorage`
@@ -604,6 +604,13 @@ export async function buildWorkerCtx(bootEnv: WorkerBootEnv): Promise<HostCtx> {
   // populate a report without replaying an old warning into a fresh terminal.
   setupFirebaseActivityGuard(ctx, env, payload?.activityToken);
 
+  // Same seam, AI's diagnostics: relay every broker `request_rejected`,
+  // `response_blocked`, and `model_substituted` event to the dev server's
+  // denial relay so a headless developer sees why the broker said no, why an
+  // answer came back empty, or which model actually answered. Live events
+  // only, so it is safe on either side of hydration.
+  setupAiDiagnosticsRelay({ subscribe: (listener) => ctx.sandbox.onEvent(listener) }, env.fetch);
+
   // Apply rules / seed / authUsers / capture BEFORE any port op runs (so
   // seeded users exist and project rules govern the first write), then mirror
   // auth to the committable server file (`--persist` only).