@pyric/cli 0.1.0-alpha.19 → 0.1.0-alpha.21

package/src/serve/runtime/chip.ts

@@ -1,8 +1,20 @@
+import type { AuthLens } from 'pyric/sandbox';
 import type {
   PyricRuntimeError,
   PyricRuntimeSnapshot,
   PyricRuntimeStatus,
 } from './status.js';
+import {
+  createChipDialogController,
+  DIALOG_STYLES,
+  type ChipDialogController,
+} from './chip-dialog.js';
+import type { RuntimeIdentity, RuntimeIdentityBindings } from './identity.js';
+import {
+  getLens as defaultGetLens,
+  setLens as defaultSetLens,
+  subscribeLens as defaultSubscribeLens,
+} from '../worker/client/core.js';
 
 export interface PyricRuntimeChipOptions {
   runtime: PyricRuntimeStatus;
@@ -11,6 +23,14 @@ export interface PyricRuntimeChipOptions {
   initiallyOpen?: boolean;
   /** Override Studio availability. Omitted uses the runtime manifest URL. */
   studioUrl?: string | null;
+  /** Optional identity integration. Missing operations use lens/no-op fallbacks. */
+  identity?: Partial<RuntimeIdentityBindings>;
+  /** Injectable lens getter (defaults to worker client getLens). */
+  getLens?: () => AuthLens | undefined;
+  /** Injectable lens setter (defaults to worker client setLens). */
+  setLens?: (lens: AuthLens | undefined) => void;
+  /** Injectable lens subscription (defaults to worker client subscribeLens). */
+  subscribeLens?: (listener: (lens: AuthLens | undefined) => void) => () => void;
 }
 
 export interface PyricRuntimeChip {
@@ -18,6 +38,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;
@@ -63,9 +109,14 @@ const styles = `
   .brand-label { font-size: 11px; }
   .signals { color: var(--pyric-muted); font-size: 10px; gap: 8px; }
   .signal { gap: 4px; white-space: nowrap; }
+  .signal[data-identity-badge] {
+    max-width: 140px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
   .dot { background: var(--pyric-accent); border-radius: 50%; height: 8px; width: 8px; }
-  .dot.error { background: var(--pyric-error); box-shadow: 0 0 0 3px rgba(240,160,160,.12); }
   .signal.update { color: var(--pyric-warning); }
+  .signal.bypass { color: #8f7fe8; font-weight: 500; }
   .chevron { color: var(--pyric-muted); height: 14px; width: 14px; }
   .panel {
     background: var(--pyric-bg);
@@ -86,8 +137,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; }
@@ -104,7 +158,7 @@ const styles = `
   .error-body code { color: #d7d7df; display: block; font-size: 11px; line-height: 1.55; overflow-wrap: anywhere; white-space: pre-wrap; }
   .error-meta { color: var(--pyric-muted); font: 9px/1.4 ui-monospace, monospace; margin-top: 4px; overflow-wrap: anywhere; }
   .empty { align-items: center; color: var(--pyric-muted); display: flex; font: 11px/1.5 ui-monospace, monospace; min-height: 57px; padding: 12px; }
-  .actions { display: grid; gap: 8px; grid-template-columns: 1fr 1fr; min-height: 56px; padding: 10px 12px; }
+  .actions { display: grid; gap: 8px; grid-template-columns: repeat(3, 1fr); min-height: 56px; padding: 10px 12px; }
   .button { align-items: center; background: transparent; border: 1px solid var(--pyric-border-soft); border-radius: 4px; color: var(--pyric-muted); display: inline-flex; font-size: 10px; justify-content: center; letter-spacing: .06em; min-height: 34px; padding: 6px 8px; text-decoration: none; text-transform: uppercase; }
   button.button { cursor: pointer; }
   .button:hover:not(:disabled):not([aria-disabled="true"]), a.button:hover { border-color: #3a3a48; color: var(--pyric-text); }
@@ -121,6 +175,8 @@ const styles = `
     .chip, .panel { animation: pyric-enter 120ms ease-out; transform-origin: bottom right; }
     @keyframes pyric-enter { from { opacity: 0; transform: translateY(4px) scale(.98); } }
   }
+
+  ${DIALOG_STYLES}
 `;
 
 const icons = {
@@ -132,7 +188,7 @@ const icons = {
 };
 
 function escapeAttribute(value: string): string {
-  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;');
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
 }
 
 export function formatPyricRuntimeError(error: PyricRuntimeError): string {
@@ -160,7 +216,19 @@ function renderErrors(snapshot: PyricRuntimeSnapshot, canCopy: boolean): string
 /** Mount the framework-independent runtime chip in an isolated shadow root. */
 export function mountPyricRuntimeChip(options: PyricRuntimeChipOptions): PyricRuntimeChip {
   const documentLike = options.document ?? document;
-  const host = documentLike.createElement('div');
+  const existingHost = documentLike.querySelector<HTMLElement>(
+    '[data-pyric-runtime-chip-host], pyric-runtime-chip',
+  );
+  if (existingHost) {
+    existingHost.remove();
+  }
+
+  let host: HTMLElement;
+  try {
+    host = documentLike.createElement('pyric-runtime-chip');
+  } catch {
+    host = documentLike.createElement('div');
+  }
   host.setAttribute('data-pyric-runtime-chip-host', '');
   const root = host.attachShadow({ mode: 'open' });
   root.innerHTML = `<style>${styles}</style><div class="announcer" role="status" aria-live="polite" aria-atomic="true"></div><div data-view></div>`;
@@ -174,6 +242,50 @@ export function mountPyricRuntimeChip(options: PyricRuntimeChipOptions): PyricRu
   let open = options.initiallyOpen ?? false;
   let snapshot = options.runtime.getSnapshot();
 
+  const getLensFn = options.getLens ?? defaultGetLens;
+  const setLensFn = options.setLens ?? defaultSetLens;
+  const subscribeLensFn = options.subscribeLens ?? defaultSubscribeLens;
+  const providedIdentity = options.identity;
+  let clientUser: RuntimeIdentity | null = null;
+  const readCurrentUser = (): RuntimeIdentity | null => {
+    if (providedIdentity?.getCurrentUser) return providedIdentity.getCurrentUser();
+    return clientUser;
+  };
+  clientUser = readCurrentUser();
+
+  const identity: RuntimeIdentityBindings = {
+    listUsers: providedIdentity?.listUsers ?? (() => []),
+    switchUser: async (uid) => {
+      if (providedIdentity?.switchUser) await providedIdentity.switchUser(uid);
+      else setLensFn({ mode: 'as', uid });
+      clientUser = readCurrentUser();
+      render();
+    },
+    signOut: async () => {
+      if (providedIdentity?.signOut) await providedIdentity.signOut();
+      else setLensFn(undefined);
+      clientUser = null;
+      render();
+    },
+    openCreateUser: providedIdentity?.openCreateUser ?? (() => {}),
+    getCurrentUser: readCurrentUser,
+    subscribeAuth: providedIdentity?.subscribeAuth ?? (() => () => {}),
+  };
+
+  const dialogController: ChipDialogController = createChipDialogController({
+    shadowRoot: root,
+    identity,
+    onToggleAdminBypass: (enable) => {
+      if (enable) {
+        setLensFn({ mode: 'admin' });
+      } else {
+        setLensFn(undefined);
+      }
+      render();
+    },
+    getLens: () => getLensFn(),
+  });
+
   const render = (next = snapshot): void => {
     const active = root.activeElement;
     const oldViewport = view.querySelector<HTMLElement>('[data-error-viewport]');
@@ -184,7 +296,7 @@ export function mountPyricRuntimeChip(options: PyricRuntimeChipOptions): PyricRu
         }
       : null;
     const activeCopyId = active?.getAttribute('data-copy-error');
-    const activeControl = ['data-expand', 'data-collapse', 'data-update-worker', 'data-open-studio']
+    const activeControl = ['data-expand', 'data-collapse', 'data-update-worker', 'data-open-studio', 'data-open-impersonate']
       .find((attribute) => active?.hasAttribute(attribute));
     const focusToken = activeCopyId !== null && activeCopyId !== undefined
       ? { attribute: 'data-copy-error', value: activeCopyId }
@@ -199,33 +311,60 @@ export function mountPyricRuntimeChip(options: PyricRuntimeChipOptions): PyricRu
         ? 'Sandbox starting'
         : snapshot.mode === 'in-page'
           ? 'In-page sandbox'
-          : 'Worker current';
+          : 'Worker version';
     const epochs = snapshot.updateAvailable
       ? `${snapshot.runningEpoch?.slice(0, 8) ?? 'unknown'} → ${snapshot.servedEpoch?.slice(0, 8) ?? 'unknown'}`
       : snapshot.runningEpoch?.slice(0, 8) ?? '';
+    const aiState = aiEngineState();
+
+    const lens = getLensFn();
+    const user = readCurrentUser();
+    const isAdmin = lens?.mode === 'admin';
+    const activeUid = lens?.mode === 'as' ? lens.uid : user?.uid;
+
+    const identitySignals: string[] = [];
+    let identityStateHtml = '<span class="epochs" data-identity-state>App session</span>';
+    if (activeUid) {
+      identitySignals.push(`<span class="signal" data-identity-badge title="as: ${escapeAttribute(activeUid)}">as: ${escapeAttribute(activeUid)}</span>`);
+      identityStateHtml = `<span class="epochs" data-identity-state data-identity-badge title="as: ${escapeAttribute(activeUid)}">as: ${escapeAttribute(activeUid)}</span>`;
+    }
+    if (isAdmin) {
+      identitySignals.push('<span class="signal bypass" data-identity-badge>bypass rules</span>');
+    }
+    const identitySignalHtml = identitySignals.join('');
 
     view.innerHTML = `${open ? `
-      <section class="panel" role="dialog" aria-label="Pyric runtime">
+      <section class="panel" role="dialog" aria-label="pyric">
         <header class="panel-header">
-          <div class="panel-title"><span class="brand-mark">&gt;_</span><strong>Pyric runtime</strong>${errorCount > 0 ? `<span class="count">${errorCount} ${errorCount === 1 ? 'error' : 'errors'}</span><button class="clear-button" type="button" data-clear-errors aria-label="Clear all errors">Clear</button>` : ''}</div>
+          <div class="panel-title"><span class="brand-mark">&gt;_</span><strong>pyric</strong>${errorCount > 0 ? `<span class="count">${errorCount} ${errorCount === 1 ? 'error' : 'errors'}</span><button class="clear-button" type="button" data-clear-errors aria-label="Clear all errors">Clear</button>` : ''}</div>
           <div class="panel-controls">
-            <button class="icon-button" type="button" data-collapse aria-label="Minimize Pyric runtime">${icons.minimize}</button>
-            <button class="icon-button" type="button" data-dismiss-chip aria-label="Dismiss Pyric runtime from page">${icons.close}</button>
+            <button class="icon-button" type="button" data-collapse aria-label="Minimize pyric">${icons.minimize}</button>
+            <button class="icon-button" type="button" data-dismiss-chip aria-label="Dismiss pyric from page">${icons.close}</button>
           </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"><span class="state-label${snapshot.updateAvailable ? ' available' : ''}">${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">AI engine</span>
+            <span class="epochs">${aiState.primary}</span>
+          </div>
+          ${aiState.subline ? `<div class="worker-state-subline">${aiState.subline}</div>` : ''}
+        </div>
+        <div class="worker-state"><span class="state-label">Rules</span><span class="epochs" style="${isAdmin ? 'color: #8f7fe8; font-weight: 500;' : ''}">${isAdmin ? 'bypassed' : 'enforced'}</span></div>
+        <div class="worker-state"><span class="state-label">Identity</span>${identityStateHtml}</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>
+          <button class="button" type="button" data-open-impersonate>Identity</button>
           ${studioUrl
             ? `<a class="button" data-open-studio href="${escapeAttribute(studioUrl)}" target="_blank" rel="noopener noreferrer">Studio${icons.external}</a>`
             : `<span class="button" data-open-studio aria-disabled="true" title="Pyric Studio is disabled">Studio${icons.external}</span>`}
         </div>
       </section>
     ` : `
-      <button class="chip" type="button" data-expand aria-label="Open Pyric runtime" aria-expanded="false">
-        <span class="brand"><span class="dot${errorCount > 0 ? ' error' : ''}"></span><span class="brand-label">Pyric</span></span>
-        <span class="signals">${snapshot.updateAvailable ? '<span class="signal update">update</span>' : ''}${errorCount > 0 ? `<span class="signal">${errorCount} ${errorCount === 1 ? 'error' : 'errors'}</span>` : '<span class="signal">ready</span>'}${icons.chevron}</span>
+      <button class="chip" type="button" data-expand aria-label="Open pyric" aria-expanded="false">
+        <span class="brand"><span class="dot${errorCount > 0 ? ' error' : ''}"></span><span class="brand-label">pyric</span></span>
+        <span class="signals">${identitySignalHtml}${snapshot.updateAvailable ? '<span class="signal update">update</span>' : ''}${errorCount > 0 ? `<span class="signal">${errorCount} ${errorCount === 1 ? 'error' : 'errors'}</span>` : ''}${icons.chevron}</span>
       </button>
     `}`;
 
@@ -265,6 +404,9 @@ export function mountPyricRuntimeChip(options: PyricRuntimeChipOptions): PyricRu
       if (!snapshot.updateAvailable || snapshot.updatingWorker) return;
       void options.runtime.updateWorker().catch(() => { /* status records and renders the failure */ });
     });
+    root.querySelector('[data-open-impersonate]')?.addEventListener('click', (e) => {
+      void dialogController.open(e.currentTarget as HTMLElement);
+    });
     for (const button of root.querySelectorAll<HTMLButtonElement>('[data-copy-error]')) {
       button.addEventListener('click', () => {
         const error = snapshot.errors.find((item) => item.id === button.dataset.copyError);
@@ -292,11 +434,31 @@ export function mountPyricRuntimeChip(options: PyricRuntimeChipOptions): PyricRu
   };
 
   documentLike.body.append(host);
+  const reattachAfterAstroSwap = (): void => {
+    if (!host.isConnected) documentLike.body.append(host);
+  };
+  documentLike.addEventListener('astro:after-swap', reattachAfterAstroSwap);
   const unsubscribe = options.runtime.subscribe(render);
+
+  const unsubLens = subscribeLensFn(() => {
+    render();
+  });
+
+  const unsubAuth = identity.subscribeAuth((user) => {
+    clientUser = user;
+    render();
+  });
+
+  render();
+
   return {
     element: host,
     dispose() {
       unsubscribe();
+      unsubLens();
+      unsubAuth();
+      documentLike.removeEventListener('astro:after-swap', reattachAfterAstroSwap);
+      dialogController.dispose();
       host.remove();
     },
   };

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/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

@@ -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 {
@@ -35,8 +36,15 @@ export interface SandboxSessionOptions {
   bridgeUrl?: () => string | null;
   ai?: InitPayload['ai'];
   aiProxyUpstream?: string;
+  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 {
@@ -97,6 +105,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 +179,7 @@ export async function createSandboxSession(
       : seedUsers,
     messaging: true,
     ai: options.ai ?? null,
+    permissive: Boolean(options.permissive),
   });
 
   const summary: SandboxSessionSummary = {
@@ -203,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,
   });
 
@@ -221,16 +239,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/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;
 }