@pyric/cli 0.1.0-alpha.30.1 → 0.1.0-alpha.31

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

@@ -10,7 +10,9 @@ import { packAiEvidence, setAiEvidence, type AiEvidence } from 'pyric/ai/interna
  *   2. The openai engine's default base URL in this (browser) context is the
  *      same-origin `/__pyric/ai-proxy` route, so a localhost upstream (Ollama)
  *      needs no CORS setup. Relative URLs resolve against the worker script's
- *      origin, so the plain path works from inside the SharedWorker.
+ *      origin, so the plain path works from inside the SharedWorker. The
+ *      gemini engine sends through `/__pyric/ai-proxy/gemini`, where the
+ *      server attaches the key, so the key never enters the browser.
  *   3. `ai.generateContent` / `ai.countTokens` are unary ops exactly like
  *      `rtdb.*` / `auth.*`; `ai.streamGenerateContent` is a FINITE
  *      subscription that delivers `{ chunk }` snaps in order, then a terminal
@@ -31,9 +33,9 @@ import { getAI, TARGET_SYMBOL, type AIOptions } from 'pyric/ai';
 
 import { serializeError, type OpMessage, type AiStreamSubMessage, type AiEngineConfigWire } from './protocol.js';
 import { type HostCtx, type PortLike, type AiBrokerLike, post, ok, fail } from './host-context.js';
+import { AI_PROXY_PATH, browserGeminiEngine } from './ai-proxy-paths.js';
 
-/** The serve proxy route the browser openai engine defaults to (#98.2). */
-export const AI_PROXY_PATH = '/__pyric/ai-proxy';
+export { AI_PROXY_PATH } from './ai-proxy-paths.js';
 
 /** Is this op an AI op (routed here instead of handleOp)? */
 export function isAiOp(method: OpMessage['method']): boolean {
@@ -50,7 +52,11 @@ type AiOpMessage = Extract<OpMessage, { method: 'ai.generateContent' | 'ai.count
  * plain authoring shapes; predicate matchers never made it across the port —
  * structured clone rejects functions loudly at send time).
  */
-function resolveEngineConfig(wire: AiEngineConfigWire, upstream: HostCtx['aiUpstream']): NonNullable<AIOptions['engine']> {
+function resolveEngineConfig(
+  wire: AiEngineConfigWire,
+  upstream: HostCtx['aiUpstream'],
+  runsInBrowser: boolean,
+): NonNullable<AIOptions['engine']> {
   if (wire.kind === 'openai') {
     const configuredUrl = wire.baseUrl ?? AI_PROXY_PATH;
     const usesProxy = configuredUrl.replace(/\/$/, '') === AI_PROXY_PATH;
@@ -65,18 +71,10 @@ function resolveEngineConfig(wire: AiEngineConfigWire, upstream: HostCtx['aiUpst
   }
   const isGeminiWire = wire.kind === 'gemini';
   if (isGeminiWire) {
-    const result: Record<string, unknown> = {
-      kind: 'gemini',
-    };
-    const hasBaseUrl = wire.baseUrl !== undefined;
-    if (hasBaseUrl) {
-      result.baseUrl = wire.baseUrl;
-    }
-    const hasApiKey = wire.apiKey !== undefined;
-    if (hasApiKey) {
-      result.apiKey = wire.apiKey;
-    }
-    return result as unknown as NonNullable<AIOptions['engine']>;
+    // Node reads the key from its own environment. A browser worker has
+    // none, so it sends through the dev server's gemini proxy.
+    const config = runsInBrowser ? browserGeminiEngine(wire) : wire;
+    return { ...config } as NonNullable<AIOptions['engine']>;
   }
   return {
     kind: 'scripted',
@@ -100,7 +98,7 @@ function resolveEngineConfig(wire: AiEngineConfigWire, upstream: HostCtx['aiUpst
 export function ensureAiBroker(ctx: HostCtx, opEngine?: AiEngineConfigWire): AiBrokerLike {
   if (ctx.aiBroker) return ctx.aiBroker;
   const wire = ctx.aiEngine ?? opEngine;
-  const ai = getAI(ctx.sandbox, wire ? { engine: resolveEngineConfig(wire, ctx.aiUpstream) } : undefined);
+  const ai = getAI(ctx.sandbox, wire ? { engine: resolveEngineConfig(wire, ctx.aiUpstream, ctx.aiRunsInBrowser === true) } : undefined);
   const target = (ai as unknown as {
     [TARGET_SYMBOL]?: { broker: AiBrokerLike };
   })[TARGET_SYMBOL];
@@ -123,14 +121,14 @@ export async function handleAiOp(ctx: HostCtx, port: PortLike, msg: OpMessage):
     observation.identity(identity);
     switch (aiMsg.method) {
       case 'ai.generateContent': {
-        const response = await broker.generateContent(aiMsg.request, aiMsg.model);
+        const response = await broker.generateContent(aiMsg.request, aiMsg.model, aiMsg.appCheck);
         observation.response(response);
         observation.finish('completed');
         ok(port, aiMsg.id, packAiEvidence(response));
         break;
       }
       case 'ai.countTokens': {
-        const response = await broker.countTokens(aiMsg.request, aiMsg.model);
+        const response = await broker.countTokens(aiMsg.request, aiMsg.model, aiMsg.appCheck);
         observation.response(response);
         observation.finish('completed');
         ok(port, aiMsg.id, packAiEvidence(response));
@@ -156,9 +154,9 @@ export async function handleAiOp(ctx: HostCtx, port: PortLike, msg: OpMessage):
  * (sub handling is synchronous, like the other sub handlers); a client
  * `unsub` mid-stream flips the registered cancel and delivery stops.
  *
- * Broker validation runs eagerly inside `streamGenerateContent` (before
- * iteration) — either way a throw lands as the shared `{ __error }` snap
- * convention, terminal for this sub.
+ * The App Check gate runs first, then broker validation runs eagerly inside
+ * `streamGenerateContent` (before iteration) — either way a throw lands as
+ * the shared `{ __error }` snap convention, terminal for this sub.
  */
 export function handleAiSub(ctx: HostCtx, port: PortLike, msg: AiStreamSubMessage): void {
   let portSubs = ctx.subs.get(port);
@@ -182,7 +180,9 @@ export function handleAiSub(ctx: HostCtx, port: PortLike, msg: AiStreamSubMessag
       const broker = ensureAiBroker(ctx, msg.engine);
       identity = broker.observationIdentity?.(msg.model);
       observation.identity(identity);
-      for await (const chunk of broker.streamGenerateContent(msg.request, msg.model)) {
+      // The App Check gate answers before any chunk, as AI Logic answers 403 before a stream.
+      await broker.admitAppCheck(msg.model, msg.appCheck);
+      for await (const chunk of broker.streamGenerateContent(msg.request, msg.model, msg.appCheck)) {
         if (cancelled) return;
         observation.response(chunk, true);
         post(port, { t: 'snap', subId: msg.subId, value: { chunk: packAiEvidence(chunk) } });

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

@@ -40,12 +40,13 @@ import {
   remintSessionWithClaims,
   applyProfileToUser,
   resolveOAuthCredentialUser,
-  type OAuthCredentialPayload,
 } from './host/auth-session-seeder.js';
-import { withoutJwtClaims } from 'pyric/sandbox/internal';
+import { signInWithCredentialPayload, type CredentialPayload } from './host/auth-credential-sign-in.js';
+import { rulesTokenFromIdToken } from 'pyric/sandbox/internal';
 
 import { linkSessionProvider } from './host/auth-linking.js';
 import { reauthenticateSession } from './host/auth-reauthentication.js';
+import { createStagedSignInResults, type StagedSignInResults } from './host/staged-sign-in-results.js';
 
 // ─── Auth: per-port sessions + port-scoped fan-out ────────────────────────
 
@@ -71,6 +72,18 @@ export function authSubsFor(ctx: HostCtx): Map<PortLike, Map<string, 'authState'
   return m;
 }
 
+const _stagedSignInResults = new WeakMap<HostCtx, StagedSignInResults>();
+
+/** The sign-in results each of this host's ports staged (`auth.mockSignInResult`). */
+export function stagedSignInResultsFor(ctx: HostCtx): StagedSignInResults {
+  let staged = _stagedSignInResults.get(ctx);
+  if (!staged) {
+    staged = createStagedSignInResults();
+    _stagedSignInResults.set(ctx, staged);
+  }
+  return staged;
+}
+
 function portTenantsFor(ctx: HostCtx): Map<PortLike, string | null> {
   let m = _portTenants.get(ctx);
   if (!m) {
@@ -231,9 +244,9 @@ function refreshPortAuthorization(
   session: MintedSession,
   claims: Record<string, unknown>,
 ): void {
-  // Rules read the token's claim set without the JWT registered claims, as
-  // the in-process session does.
-  session.state.token = withoutJwtClaims(claims);
+  // Rules read the token's full claim set, JWT registered claims included,
+  // as the in-process session does.
+  session.state.token = rulesTokenFromIdToken(claims);
 
   // Frozen sandbox.withAuth handles capture the old token. Clear all
   // session-handle caches so this port and any same-uid sibling rebuild from
@@ -257,6 +270,7 @@ export function cleanupPortSession(ctx: HostCtx, port: PortLike): void {
   ctx.portSessions?.delete(port);
   portTenantsFor(ctx).delete(port);
   _lastAuthStateUid.delete(port);
+  stagedSignInResultsFor(ctx).clear(port);
 }
 
 // ─── Auth op handlers ─────────────────────────────────────────────────────
@@ -533,24 +547,20 @@ export async function handleAuthOp(ctx: HostCtx, port: PortLike, msg: OpMessage)
         const rawMsg: Record<string, unknown> = msg;
         const hasProvider = typeof rawMsg.providerId === 'string';
         const cred = (msg.credential ?? (hasProvider ? rawMsg : undefined)) as
-          | OAuthCredentialPayload
+          | CredentialPayload
           | undefined;
         const hasNoCredential = cred === undefined || !cred.providerId;
         if (hasNoCredential) {
           throw new Error('auth.signInWithCredential requires credential payload or providerId');
         }
         const tenantId = resolveSignInTenant(ctx, port, msg.tenantId);
-        const { uid, isNewUser } = resolveOAuthCredentialUser(auth, cred);
-        const session = authSandboxOps.mintSession(auth, {
-          kind: 'provider',
-          uid,
-          providerId: cred.providerId,
-          tenantId,
-          ...portOriginScope(port),
-        });
+        const takeStaged = (providerId: string) => stagedSignInResultsFor(ctx).take(port, providerId);
+        const { session, providerId, isNewUser } = signInWithCredentialPayload(auth, cred, {
+          tenantId, ...portOriginScope(port),
+        }, takeStaged);
         setPortSession(ctx, port, session);
         await bestEffortFlush(ctx, msg.method);
-        ok(port, msg.id, credReply(session, cred.providerId, isNewUser));
+        ok(port, msg.id, credReply(session, providerId, isNewUser));
       } catch (e) { fail(port, msg.id, e); }
       break;
     }
@@ -572,6 +582,14 @@ export async function handleAuthOp(ctx: HostCtx, port: PortLike, msg: OpMessage)
       break;
     }
 
+    case 'auth.mockSignInResult': {
+      try {
+        stagedSignInResultsFor(ctx).stage(port, msg.identity);
+        ok(port, msg.id, null);
+      } catch (e) { fail(port, msg.id, e); }
+      break;
+    }
+
     case 'auth.listUsers': {
       try {
         ok(port, msg.id, authSandboxOps.listUsers(auth));

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

@@ -24,6 +24,7 @@ import {
   type OutboundMessage,
   type AuthPersistenceMode,
   type AiEngineConfigWire,
+  type AiAppCheckWire,
   type AppConfigMessage,
 } from './protocol.js';
 
@@ -40,9 +41,11 @@ import {
  */
 export interface AiBrokerLike {
   observationIdentity?(model: string): import('pyric/ai/internal').AiEvidence;
-  generateContent(req: Record<string, unknown>, model: string): Promise<Record<string, unknown>>;
-  streamGenerateContent(req: Record<string, unknown>, model: string): AsyncIterable<Record<string, unknown>>;
-  countTokens(req: Record<string, unknown>, model: string): Promise<Record<string, unknown>>;
+  /** AI Logic's App Check gate; a request with no claim passes. */
+  admitAppCheck(model: string, appCheck: AiAppCheckWire | undefined): Promise<void>;
+  generateContent(req: Record<string, unknown>, model: string, appCheck?: AiAppCheckWire): Promise<Record<string, unknown>>;
+  streamGenerateContent(req: Record<string, unknown>, model: string, appCheck?: AiAppCheckWire): AsyncIterable<Record<string, unknown>>;
+  countTokens(req: Record<string, unknown>, model: string, appCheck?: AiAppCheckWire): Promise<Record<string, unknown>>;
 }
 
 // ─── Port interface ───────────────────────────────────────────────────────
@@ -278,6 +281,13 @@ export interface HostCtx {
   aiEngine?: AiEngineConfigWire;
   /** Server-only OpenAI transport. Browser workers retain the same-origin proxy. */
   aiUpstream?: { baseUrl: string; fetch: typeof fetch };
+  /**
+   * The broker's engines run in the browser SharedWorker, which has no server
+   * environment: the gemini engine sends through the dev server's gemini
+   * proxy, which attaches the key (#1584). Set by the worker entry only; a
+   * Node host and a Node repro replay leave it unset.
+   */
+  aiRunsInBrowser?: boolean;
   /**
    * Lazily-built agent tool dispatcher (the canonical sandbox tool set) bound to
    * THIS worker's sandbox. The bridge peer forwards `tool` messages here so the

package/src/serve/worker/inbound-validation/operation-arguments.ts

@@ -7,6 +7,7 @@ import { assertQueryStructure } from '../host/query-structure.js';
 import { isMessageRecord, requireShape, requireRecord, requireString, requireOptionalString,
   requireOptionalBoolean, requireOptionalRecord, requireNumber, requireOptionalNumber } from './fields.js';
 import { assertRtdbQuery } from './rtdb-query.js';
+import { updateValuesShapeError } from '../client/rtdb-value-validation.js';
 export { isMessageRecord } from './fields.js';
 
 function assertRequiredPath(message: Record<string, unknown>): void {
@@ -26,6 +27,19 @@ function assertRequiredPath(message: Record<string, unknown>): void {
   }
 }
 
+/** The `ResolvedIdentity` the picker hands over and a served test stages. */
+function requireResolvedIdentity(identity: unknown): void {
+  requireRecord(identity, 'identity');
+  requireString(identity.uid, 'identity.uid');
+  requireString(identity.providerId, 'identity.providerId');
+  for (const field of ['email', 'displayName', 'photoURL']) {
+    const value = identity[field];
+    const isNullableString = value === undefined || value === null || typeof value === 'string';
+    requireShape(isNullableString, `identity.${field}`);
+  }
+  requireOptionalRecord(identity.customClaims, 'identity.customClaims');
+}
+
 function assertSharedAuthFields(message: Record<string, unknown>): void {
   const method = message.method;
   const isAuthMethod = typeof method === 'string' && method.startsWith('auth.');
@@ -143,8 +157,10 @@ export function assertOperationArguments(message: Record<string, unknown>): void
     case 'rtdb.update':
     case 'rtdb.onDisconnectUpdate': {
       const hasValues = isMessageRecord(message.values);
-      requireShape(hasValues, 'values');
-      return;
+      if (hasValues) return;
+      // The served client refuses this first; the host keeps the SDK's text as its second line.
+      const fnName = message.method === 'rtdb.update' ? 'update' : 'OnDisconnect.update';
+      throw new FirebaseError('invalid-argument', updateValuesShapeError(fnName).message);
     }
     case 'rtdb.push': {
       const hasValidKey = message.key === undefined || typeof message.key === 'string';
@@ -373,21 +389,18 @@ export function assertOperationArguments(message: Record<string, unknown>): void
         const isNullableString = value === undefined || value === null || typeof value === 'string';
         requireShape(isNullableString, `credential.${field}`);
       }
-      return;
-    }
-    case 'auth.acceptIdentity': {
-      const identity = message.identity;
-      requireRecord(identity, 'identity');
-      requireString(identity.uid, 'identity.uid');
-      requireString(identity.providerId, 'identity.providerId');
-      for (const field of ['email', 'displayName', 'photoURL']) {
-        const value = identity[field];
-        const isNullableString = value === undefined || value === null || typeof value === 'string';
-        requireShape(isNullableString, `identity.${field}`);
+      // An email credential's method and secret; the engine decides a missing one.
+      for (const field of ['signInMethod', 'password']) {
+        const value = credential[field];
+        const isOptionalString = value === undefined || typeof value === 'string';
+        requireShape(isOptionalString, `credential.${field}`);
       }
-      requireOptionalRecord(identity.customClaims, 'identity.customClaims');
       return;
     }
+    case 'auth.acceptIdentity':
+    case 'auth.mockSignInResult':
+      requireResolvedIdentity(message.identity);
+      return;
     case 'auth.adminCreateUser':
       requireRecord(message.request, 'request');
       return;
@@ -495,10 +508,21 @@ export function assertOperationArguments(message: Record<string, unknown>): void
 }
 
 
+/** An App Check claim is absent (a handle with no app) or a record whose token is a string or null. */
+function assertAiAppCheck(appCheck: unknown): void {
+  const hasNoClaim = appCheck === undefined;
+  if (hasNoClaim) return;
+  requireRecord(appCheck, 'appCheck');
+  const token = appCheck.token;
+  const hasTokenShape = token === null || typeof token === 'string';
+  requireShape(hasTokenShape, 'appCheck.token');
+}
+
 /** Unary and streaming AI requests share the same adapter-owned wire fields. */
 export function assertAiArguments(message: Record<string, unknown>): void {
   requireString(message.model, 'model');
   requireRecord(message.request, 'request');
+  assertAiAppCheck(message.appCheck);
   const engine = message.engine;
   const hasNoEngine = engine === undefined;
   if (hasNoEngine) return;

package/src/serve/worker/operation-persistence.ts

@@ -73,6 +73,7 @@ export const operationPersistence = {
   'auth.confirmPasswordReset': true,
   'auth.restorePortSession': false,
   'auth.acceptIdentity': true,
+  'auth.mockSignInResult': false,
   'auth.listUsers': false,
   'auth.adminCreateUser': true,
   'auth.adminUpdateUser': true,

package/src/serve/worker/protocol.ts

@@ -59,6 +59,17 @@ export type AiEngineConfigWire =
     }
   | { kind: 'gemini'; baseUrl?: string; apiKey?: string };
 
+/**
+ * The App Check claim an AI request from an app-backed handle carries, as
+ * production reads `X-Firebase-AppCheck`: a token, or `null` when the handle
+ * has none. The worker broker refuses a request whose claim has no valid
+ * sandbox token. Requests from handles with no app send no claim and are not
+ * gated.
+ */
+export interface AiAppCheckWire {
+  token: string | null;
+}
+
 /**
  * Wire form of the Gemini error envelope an `AiBrokerError` carries.
  */
@@ -193,7 +204,8 @@ export type OpMessage = (
       t: 'op';
       id: string;
       method: 'auth.signInWithCredential';
-      credential?: {
+      /** An email credential carries its secret (`toJSON()`), which the host verifies with the engine. */
+      credential?: SerializedAuthCredential | {
         providerId: string;
         idToken?: string | null;
         accessToken?: string | null;
@@ -204,6 +216,8 @@ export type OpMessage = (
         uid?: string | null;
       };
       providerId?: string;
+      signInMethod?: string;
+      password?: string;
       idToken?: string | null;
       accessToken?: string | null;
       rawNonce?: string | null;
@@ -233,6 +247,9 @@ export type OpMessage = (
   | { t: 'op'; id: string; method: 'auth.confirmPasswordReset'; code: string; newPassword: string }
   | { t: 'op'; id: string; method: 'auth.restorePortSession'; uid: string; tenantId?: string | null }
   | { t: 'op'; id: string; method: 'auth.acceptIdentity'; identity: ResolvedIdentity; tenantId?: string | null }
+  // Stage the identity the port's next federated `signInWithCredential` for
+  // `identity.providerId` signs in as (served `sandbox.mockSignInResult`).
+  | { t: 'op'; id: string; method: 'auth.mockSignInResult'; identity: ResolvedIdentity }
   | { t: 'op'; id: string; method: 'auth.listUsers' }
   | { t: 'op'; id: string; method: 'auth.adminCreateUser'; request: Record<string, unknown> }
   | { t: 'op'; id: string; method: 'auth.adminUpdateUser'; uid: string; request: Record<string, unknown> }
@@ -289,8 +306,8 @@ export type OpMessage = (
    */
   | ({ t: 'op'; id: string; method: 'storage.createUploadSession'; path: string; contentType?: string; metadata?: Record<string, unknown>; downloadTokens?: string; origin?: string } & StorageBucketWire)
   // AI ops
-  | { t: 'op'; id: string; method: 'ai.generateContent'; model: string; request: Record<string, unknown>; engine?: AiEngineConfigWire }
-  | { t: 'op'; id: string; method: 'ai.countTokens'; model: string; request: Record<string, unknown>; engine?: AiEngineConfigWire }
+  | { t: 'op'; id: string; method: 'ai.generateContent'; model: string; request: Record<string, unknown>; engine?: AiEngineConfigWire; appCheck?: AiAppCheckWire }
+  | { t: 'op'; id: string; method: 'ai.countTokens'; model: string; request: Record<string, unknown>; engine?: AiEngineConfigWire; appCheck?: AiAppCheckWire }
   | { t: 'op'; id: string; method: 'getRuntimeEpoch' }
   | { t: 'op'; id: string; method: 'retireRuntime'; targetEpoch: string }
   | { t: 'op'; id: string; method: 'getVersion' }
@@ -377,6 +394,7 @@ export interface AiStreamSubMessage {
   model: string;
   request: Record<string, unknown>;
   engine?: AiEngineConfigWire;
+  appCheck?: AiAppCheckWire;
 }
 
 export interface MessagingSubMessage {

package/src/serve/worker/rtdb-value-equality.ts

@@ -2,9 +2,11 @@
 export function sameRtdbValue(left: unknown, right: unknown): boolean {
   if (Object.is(left, right)) return true;
   if (Array.isArray(left) || Array.isArray(right)) {
+    // A hole and a `null` are the same RTDB value: the hosted transport's JSON
+    // writes a sparse array's holes as `null` (RT-6, #1371).
     return Array.isArray(left) && Array.isArray(right)
       && left.length === right.length
-      && left.every((value, index) => sameRtdbValue(value, right[index]));
+      && Array.from(left, (value, index) => sameRtdbValue(value ?? null, right[index] ?? null)).every(Boolean);
   }
   if (!left || !right || typeof left !== 'object' || typeof right !== 'object') return false;
   const leftRecord = left as Record<string, unknown>;

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

@@ -31,7 +31,7 @@ import { SERVE_HISTORY_LIMITS } from '../observation-limits.js';
 
 import { getFirestore } from 'pyric/firestore';
 import { seedDocuments, setRules, snapshotDocuments } from 'pyric/sandbox/firestore';
-import { parseToASTOrError, rulesSourceRejection } from 'pyric/rules/internal';
+import { rulesSourceRejection } from 'pyric/rules/internal';
 import { rtdbRulesSourceRejection } from 'pyric/rules/internal/rtdb';
 import { getDatabase, sandbox as rtdbSandbox } from 'pyric/database';
 import { getAuth, sandbox as authOps, type SeedUser } from 'pyric/auth';
@@ -270,14 +270,8 @@ export function applyServeInit(
   //    rules, surface loudly.
   if (payload.rules) {
     const rejection = rulesSourceRejection(payload.rules);
-    const parsed = rejection === null ? parseToASTOrError(payload.rules) : null;
-    const wrongService = parsed !== null && parsed.ok && parsed.ast.service && parsed.ast.service.name !== 'cloud.firestore'
-      ? parsed.ast.service
-      : null;
-    if (rejection !== null || wrongService !== null) {
-      result.rulesParseError = wrongService !== null
-        ? `Firestore rules did not compile: Expected 'service cloud.firestore', got 'service ${wrongService.name}'.`
-        : `Firestore ${rejection!.message}`;
+    if (rejection !== null) {
+      result.rulesParseError = `Firestore ${rejection.message}`;
       console.error(
         '[pyric worker] firestore.rules not loaded, running WITHOUT your rules:',
         result.rulesParseError,

package/src/serve/worker-build-lock.ts

@@ -0,0 +1,207 @@
+/**
+ * A lock directory that lets one process at a time build into a shared
+ * SharedWorker cache directory (see `worker-bundle-cache.ts`).
+ *
+ * The holder writes `owner.json` (pid, host, token) and refreshes the lock
+ * directory's mtime every `heartbeatMs` while it holds the lock. A waiter
+ * takes the lock over when:
+ * - its owner is on this host and that pid has exited, or
+ * - its mtime has not moved for `staleMs`: a crashed holder on another host,
+ *   a holder that died between creating the directory and writing
+ *   `owner.json`, or one whose event loop stalled past `staleMs`.
+ *
+ * The pid check is a fast path, not a guarantee. A reused pid looks alive, so
+ * that lock waits for `staleMs`. A process in another pid namespace (a
+ * container sharing the home directory) reports the same host name but a pid
+ * this process cannot see, so the owner also records its pid namespace, and
+ * the pid check runs only for an owner in this one. A lock from another pid
+ * namespace, or from the Windows side of a WSL share, which records none, is
+ * taken over only once it goes stale. Should a lock still be taken from a
+ * live builder, that builder does not publish (`isHeld()`) and retries.
+ *
+ * `waitMs` is longer than `staleMs` on purpose: a waiter outlasts any lock
+ * whose holder stopped refreshing it, so the wait limit fires only when a
+ * live holder keeps its lock for longer than `waitMs`.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+
+export const LOCK_DIR = '.worker-build.lock';
+export const ABANDONED_LOCK_PREFIX = `${LOCK_DIR}.abandoned-`;
+const LOCK_OWNER_FILE = 'owner.json';
+
+export interface WorkerBuildLockOptions {
+  /** A lock whose mtime has not moved for this long is abandoned. */
+  staleMs?: number;
+  /** How often the holder refreshes the lock's mtime. */
+  heartbeatMs?: number;
+  /** How long to wait for another builder before failing. */
+  waitMs?: number;
+  pollMs?: number;
+  /** Test seam for the rename that moves an abandoned lock aside. */
+  renameLock?: (from: string, to: string) => void;
+}
+
+/** What the work running under the lock can ask of it. */
+export interface WorkerBuildLock {
+  /** False once another process has taken the lock over as abandoned. */
+  isHeld(): boolean;
+}
+
+interface LockOwner {
+  pid: number;
+  host: string;
+  /** `/proc/self/ns/pid` where there is one; the pid means nothing outside it. */
+  pidNamespace?: string;
+  token: string;
+}
+
+/** A lock, or a staging directory, untouched for this long belongs to a builder that is gone. */
+export const WORKER_BUILD_STALE_MS = 60_000;
+const DEFAULT_STALE_MS = WORKER_BUILD_STALE_MS;
+const DEFAULT_HEARTBEAT_MS = 10_000;
+const DEFAULT_WAIT_MS = 150_000;
+const DEFAULT_POLL_MS = 50;
+
+/** Run `work` while holding the build lock of `outDir`. */
+export async function withWorkerBuildLock<T>(
+  outDir: string,
+  work: (lock: WorkerBuildLock) => Promise<T>,
+  options: WorkerBuildLockOptions = {},
+): Promise<T> {
+  mkdirSync(outDir, { recursive: true });
+  const lockDir = join(outDir, LOCK_DIR);
+  const owner = await acquire(lockDir, options);
+  const heartbeat = startHeartbeat(lockDir, owner.token, options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
+  try {
+    return await work({ isHeld: () => isOwnedBy(lockDir, owner.token) });
+  } finally {
+    clearInterval(heartbeat);
+    release(lockDir, owner.token);
+  }
+}
+
+async function acquire(lockDir: string, options: WorkerBuildLockOptions): Promise<LockOwner> {
+  const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+  const waitMs = options.waitMs ?? DEFAULT_WAIT_MS;
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+  const owner: LockOwner = { pid: process.pid, host: hostname(), pidNamespace: PID_NAMESPACE, token: randomBytes(8).toString('hex') };
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    if (tryCreate(lockDir, owner)) return owner;
+    const brokeAbandonedLock = isAbandoned(lockDir, staleMs) && breakLock(lockDir, options.renameLock ?? renameSync);
+    if (brokeAbandonedLock) continue;
+    const hasWaitedTooLong = Date.now() >= deadline;
+    if (hasWaitedTooLong) {
+      throw new Error(
+        `pyric sandbox: waited ${Math.round(waitMs / 1000)}s for another process to build the SharedWorker bundle; remove ${lockDir} if no pyric process is running.`,
+      );
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
+function tryCreate(lockDir: string, owner: LockOwner): boolean {
+  try {
+    mkdirSync(lockDir);
+  } catch (error) {
+    const isHeld = (error as NodeJS.ErrnoException).code === 'EEXIST';
+    if (isHeld) return false;
+    throw error;
+  }
+  try {
+    writeFileSync(join(lockDir, LOCK_OWNER_FILE), JSON.stringify(owner));
+  } catch (error) {
+    rmSync(lockDir, { recursive: true, force: true });
+    throw error;
+  }
+  return true;
+}
+
+function readOwner(lockDir: string): LockOwner | null {
+  try {
+    return JSON.parse(readFileSync(join(lockDir, LOCK_OWNER_FILE), 'utf8')) as LockOwner;
+  } catch {
+    return null;
+  }
+}
+
+function isOwnedBy(lockDir: string, token: string): boolean {
+  return readOwner(lockDir)?.token === token;
+}
+
+/** This process's pid namespace on Linux; undefined where there is no `/proc`, as on macOS. */
+function readPidNamespace(): string | undefined {
+  try {
+    return readlinkSync('/proc/self/ns/pid');
+  } catch {
+    return undefined;
+  }
+}
+
+const PID_NAMESPACE = readPidNamespace();
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+function isAbandoned(lockDir: string, staleMs: number): boolean {
+  const owner = readOwner(lockDir);
+  const seesOwnerPid = owner !== null && owner.host === hostname() && owner.pidNamespace === PID_NAMESPACE;
+  if (seesOwnerPid && !isProcessAlive(owner.pid)) return true;
+  try {
+    return Date.now() - statSync(lockDir).mtimeMs > staleMs;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Move an abandoned lock aside, then remove it, so two breakers never both
+ * delete. Returns whether this call moved it. A lock that is already gone
+ * returns false, and the caller waits a poll before trying again. Any other
+ * failure (a cache directory this user cannot write) cannot be waited out.
+ */
+function breakLock(lockDir: string, rename: (from: string, to: string) => void): boolean {
+  const aside = `${lockDir}.abandoned-${randomBytes(4).toString('hex')}`;
+  try {
+    rename(lockDir, aside);
+  } catch (error) {
+    const isAlreadyGone = (error as NodeJS.ErrnoException).code === 'ENOENT';
+    if (isAlreadyGone) return false;
+    throw new Error(`pyric sandbox: cannot remove the abandoned SharedWorker build lock ${lockDir}: ${String(error)}`);
+  }
+  rmSync(aside, { recursive: true, force: true });
+  return true;
+}
+
+function startHeartbeat(lockDir: string, token: string, heartbeatMs: number): ReturnType<typeof setInterval> {
+  const timer = setInterval(() => {
+    if (!isOwnedBy(lockDir, token)) return;
+    const now = new Date();
+    try {
+      utimesSync(lockDir, now, now);
+    } catch {
+      // The lock was taken over; isHeld() reports it.
+    }
+  }, heartbeatMs);
+  timer.unref?.();
+  return timer;
+}
+
+/** Remove the lock if it is still ours. A failure here never hides a finished build. */
+function release(lockDir: string, token: string): void {
+  if (!isOwnedBy(lockDir, token)) return;
+  try {
+    rmSync(lockDir, { recursive: true, force: true });
+  } catch {
+    // Left behind, it is taken over once its pid has exited or it goes stale.
+  }
+}