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

package/src/functions-rtdb/child.ts

@@ -97,34 +97,128 @@ function isChildMessage(value: unknown): value is FunctionsRtdbChildMessage {
   return typeof value === 'object' && value !== null && 'type' in value;
 }
 
+export interface FunctionsChildEnvOptions {
+  baseEnv: NodeJS.ProcessEnv;
+  entry: string;
+  instance: string;
+  location: string;
+  databaseHost: string;
+  projectId: string;
+}
+
+/**
+ * Resolve the project identifier for the functions child process.
+ *
+ * Precedence:
+ * 1. Explicit options.projectId
+ * 2. baseEnv.PYRIC_PROJECT
+ * 3. Instance prefix when formatted as `<projectId>-default-rtdb`
+ * 4. Default fallback to 'demo-project'
+ */
+export function resolveChildProjectId(
+  explicitProjectId?: string,
+  instance?: string,
+  baseEnv?: NodeJS.ProcessEnv,
+): string {
+  if (typeof explicitProjectId === 'string' && explicitProjectId.length > 0) {
+    return explicitProjectId;
+  }
+
+  const pyricProject = baseEnv?.PYRIC_PROJECT;
+  if (typeof pyricProject === 'string' && pyricProject.length > 0) {
+    return pyricProject;
+  }
+
+  if (typeof instance === 'string' && instance.length > 0) {
+    const stripped = instance.replace(/-default-rtdb$/, '');
+    if (stripped.length > 0) {
+      return stripped;
+    }
+  }
+
+  return 'demo-project';
+}
+
+/**
+ * Resolve the database host, defaulting to 'firebasedatabase.app'.
+ */
+export function resolveChildDatabaseHost(databaseHost?: string): string {
+  if (typeof databaseHost === 'string' && databaseHost.length > 0) {
+    return databaseHost;
+  }
+  return 'firebasedatabase.app';
+}
+
+/**
+ * Resolve the filesystem path to the child entrypoint module.
+ */
+export function resolveChildModulePath(childModuleUrl?: string | URL): string {
+  if (!childModuleUrl) {
+    return fileURLToPath(new URL('./child.js', import.meta.url));
+  }
+  if (typeof childModuleUrl === 'string' && !childModuleUrl.startsWith('file:')) {
+    return resolve(childModuleUrl);
+  }
+  return fileURLToPath(childModuleUrl);
+}
+
+/**
+ * Assemble the child process environment variables.
+ *
+ * Guaranteed child-only synthetic sandbox metadata:
+ * - GCLOUD_PROJECT is set to the resolved sandbox project ID
+ * - FIREBASE_CONFIG is set to synthetic JSON with projectId, databaseURL, and storageBucket
+ *
+ * Explicit control flow ensures that host environment cannot pollute or route
+ * sandbox functions execution to a production Firebase/GCP project.
+ */
+export function buildFunctionsChildEnv(options: FunctionsChildEnvOptions): NodeJS.ProcessEnv {
+  const { baseEnv, entry, instance, location, databaseHost, projectId } = options;
+
+  const resolvedEntry = resolve(entry);
+  const databaseURL = `https://${instance}.${databaseHost}`;
+  const storageBucket = `${projectId}.appspot.com`;
+
+  const syntheticFirebaseConfig = JSON.stringify({
+    projectId,
+    databaseURL,
+    storageBucket,
+  });
+
+  const childEnv: NodeJS.ProcessEnv = {
+    ...baseEnv,
+    PYRIC_FUNCTIONS_RTDB_CHILD: '1',
+    PYRIC_FUNCTIONS_ENTRY: resolvedEntry,
+    PYRIC_FUNCTIONS_INSTANCE: instance,
+    PYRIC_FUNCTIONS_LOCATION: location,
+    PYRIC_FUNCTIONS_DATABASE_HOST: databaseHost,
+    GCLOUD_PROJECT: projectId,
+    FIREBASE_CONFIG: syntheticFirebaseConfig,
+  };
+
+  return childEnv;
+}
+
 /** Spawn the real Firebase Functions SDK in an isolated Node process. */
 export function spawnFunctionsRtdbChild(
   options: SpawnFunctionsRtdbChildOptions,
 ): FunctionsRtdbChildHandle {
-  const childModuleUrl = options.childModuleUrl ?? new URL('./child.js', import.meta.url);
-  const childModulePath = typeof childModuleUrl === 'string' && !childModuleUrl.startsWith('file:')
-    ? resolve(childModuleUrl)
-    : fileURLToPath(childModuleUrl);
-  const projectId = options.projectId ?? options.instance.replace(/-default-rtdb$/, '') ?? 'demo-project';
-  const databaseHost = options.databaseHost ?? 'firebasedatabase.app';
-  const databaseURL = `https://${options.instance}.${databaseHost}`;
-  const firebaseConfig = JSON.stringify({
+  const childModulePath = resolveChildModulePath(options.childModuleUrl);
+  const projectId = resolveChildProjectId(options.projectId, options.instance, options.env);
+  const databaseHost = resolveChildDatabaseHost(options.databaseHost);
+  const childEnv = buildFunctionsChildEnv({
+    baseEnv: options.env,
+    entry: options.entry,
+    instance: options.instance,
+    location: options.location,
+    databaseHost,
     projectId,
-    databaseURL,
-    storageBucket: `${projectId}.appspot.com`,
   });
-  const child = spawn(options.nodeExecutable ?? 'node', [childModulePath], {
+
+  const nodeExecutable = options.nodeExecutable ?? 'node';
+  const child = spawn(nodeExecutable, [childModulePath], {
     cwd: options.cwd,
-    env: {
-      ...options.env,
-      PYRIC_FUNCTIONS_RTDB_CHILD: '1',
-      PYRIC_FUNCTIONS_ENTRY: resolve(options.entry),
-      PYRIC_FUNCTIONS_INSTANCE: options.instance,
-      PYRIC_FUNCTIONS_LOCATION: options.location,
-      PYRIC_FUNCTIONS_DATABASE_HOST: databaseHost,
-      GCLOUD_PROJECT: options.env.GCLOUD_PROJECT ?? projectId,
-      FIREBASE_CONFIG: options.env.FIREBASE_CONFIG ?? firebaseConfig,
-    },
+    env: childEnv,
     stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
   });
 

package/src/functions-rtdb/development-runtime.ts

@@ -6,7 +6,7 @@ import {
   type FunctionsRtdbChildReady,
   type SpawnFunctionsRtdbChildOptions,
 } from './child.js';
-import { buildChildEnv, createLinePrefixer } from '../cli/dev-runner.js';
+import { buildChildEnv, createLinePrefixer } from '../cli/sandbox-runner.js';
 
 const INITIAL_PEER_TIMEOUT_MS = 30_000;
 const RELOAD_PEER_TIMEOUT_MS = 5_000;
@@ -38,6 +38,9 @@ export interface FunctionsDevelopmentRuntimeOptions {
   baseEnv: NodeJS.ProcessEnv;
   serveUrl: string;
   registerUrl: string;
+  /** The per-launch secret this child's handshake beacon must present.
+   *  Absent when the host runs no beacon receiver. */
+  beaconToken?: string | undefined;
   instance: string;
   location: string;
   projectId?: string;
@@ -216,6 +219,7 @@ export function createFunctionsDevelopmentRuntime(
         env: buildChildEnv(options.baseEnv, {
           serveUrl: options.serveUrl,
           registerUrl: options.registerUrl,
+          beaconToken: options.beaconToken,
         }),
         instance: options.instance,
         location: options.location,

package/src/functions-rtdb/project.ts

@@ -22,7 +22,7 @@ export function discoverFunctionsRtdbProject(cwd: string): FunctionsRtdbProject
     config = JSON.parse(readFileSync(firebaseJsonPath, 'utf8')) as FirebaseJson;
   } catch (error) {
     throw new Error(
-      `pyric dev: failed to parse firebase.json while discovering Functions: ` +
+      `pyric sandbox: failed to parse firebase.json while discovering Functions: ` +
         `${error instanceof Error ? error.message : String(error)}`,
     );
   }
@@ -33,23 +33,23 @@ export function discoverFunctionsRtdbProject(cwd: string): FunctionsRtdbProject
     : [config.functions as FunctionsConfig];
   if (declared.length !== 1) {
     throw new Error(
-      'pyric dev: multiple Functions codebases are not supported by the first ' +
+      'pyric sandbox: multiple Functions codebases are not supported by the first ' +
         'onValueCreated slice; configure one source for this development session.',
     );
   }
   const functions = declared[0];
   if (typeof functions !== 'object' || functions === null) {
-    throw new Error('pyric dev: firebase.json `functions` must be an object with a source.');
+    throw new Error('pyric sandbox: firebase.json `functions` must be an object with a source.');
   }
   if (functions.source !== undefined && typeof functions.source !== 'string') {
-    throw new Error('pyric dev: firebase.json `functions.source` must be a string.');
+    throw new Error('pyric sandbox: firebase.json `functions.source` must be a string.');
   }
 
   const sourceDir = resolve(cwd, functions.source ?? 'functions');
   const packageJsonPath = join(sourceDir, 'package.json');
   if (!existsSync(packageJsonPath)) {
     throw new Error(
-      `pyric dev: Functions source is declared but ${packageJsonPath} does not exist.`,
+      `pyric sandbox: Functions source is declared but ${packageJsonPath} does not exist.`,
     );
   }
 
@@ -58,17 +58,17 @@ export function discoverFunctionsRtdbProject(cwd: string): FunctionsRtdbProject
     packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { main?: unknown };
   } catch (error) {
     throw new Error(
-      `pyric dev: failed to parse ${packageJsonPath}: ` +
+      `pyric sandbox: failed to parse ${packageJsonPath}: ` +
         `${error instanceof Error ? error.message : String(error)}`,
     );
   }
   if (packageJson.main !== undefined && typeof packageJson.main !== 'string') {
-    throw new Error(`pyric dev: ${packageJsonPath} \`main\` must be a string.`);
+    throw new Error(`pyric sandbox: ${packageJsonPath} \`main\` must be a string.`);
   }
 
   const entry = resolve(sourceDir, packageJson.main ?? 'index.js');
   if (!existsSync(entry) || !statSync(entry).isFile()) {
-    throw new Error(`pyric dev: Functions entry does not exist: ${entry}`);
+    throw new Error(`pyric sandbox: Functions entry does not exist: ${entry}`);
   }
   return { sourceDir, entry };
 }

package/src/google-endpoints.ts

@@ -0,0 +1,155 @@
+/**
+ * The single shared source of Google/Firebase production endpoint hosts.
+ *
+ * Two readers consume this table and they must never drift apart:
+ *  - the runtime net guard (`register/net-guard.ts`), which matches every
+ *    catalog host on egress from a pyric-launched child;
+ *  - the throwing frontend build check (`cli/inlined-sdk-scanner.ts`), which
+ *    greps served assets for the narrower SDK fingerprint subset below.
+ *
+ * It lives at the package root, not under `cli/` or `register/`, so both
+ * import it without a cycle, and it has zero imports so the `--import`ed
+ * register entry stays cheap.
+ *
+ * Membership rule: a host belongs here only if it is real-SDK-only, meaning it
+ * can never legitimately be contacted by a sandbox-clean app (whose Firebase
+ * traffic all routes to the local `/__pyric/*` namespace). User-configured
+ * upstreams (BYOK AI base URLs, app APIs) are handled by the guard's
+ * allowlist, not by omission from this table.
+ */
+
+/** One production endpoint host and the service it belongs to. */
+export interface GoogleEndpoint {
+  /** Registrable host or host suffix. Matched by label-boundary suffix. */
+  readonly host: string;
+  /** Human-readable service name, used verbatim in guard and scanner messages. */
+  readonly service: string;
+  /**
+   * Blocked from day one rather than warn-first. Reserved for egress that is
+   * never explainable as a false positive, currently only the GCE/GKE metadata
+   * server, whose only purpose here would be credential theft.
+   */
+  readonly alwaysBlock?: true;
+  /**
+   * True when the host string is evidence that real Firebase SDK code was
+   * compiled into a build artifact. Only these hosts feed the throwing
+   * frontend build check, because that check fails a build outright.
+   *
+   * False for a host an ordinary app can carry without any SDK: a public Cloud
+   * Storage asset URL, a bare callable URL on `cloudfunctions.net`, a
+   * `databaseURL` config literal on `firebaseio.com`, a Vertex AI call from a
+   * hand-written client, a server-side FCM send, an admin control plane, or an
+   * infrastructure reference to the metadata server. The net guard still
+   * matches all of them on the wire.
+   */
+  readonly fingerprint: boolean;
+}
+
+export const GOOGLE_ENDPOINT_CATALOG: readonly GoogleEndpoint[] = [
+  // Identity. Both are reached by the Auth SDK and by nothing else.
+  { host: 'identitytoolkit.googleapis.com', service: 'Firebase Authentication', fingerprint: true },
+  {
+    host: 'securetoken.googleapis.com',
+    service: 'Firebase Authentication (token refresh)',
+    fingerprint: true,
+  },
+  // Firestore.
+  { host: 'firestore.googleapis.com', service: 'Cloud Firestore', fingerprint: true },
+  // Realtime Database. `firebaseio.com` is the legacy/us-central1 host and is
+  // also the shape of a `databaseURL` config literal, so it does not
+  // fingerprint a build; `firebasedatabase.app` is the regional host.
+  { host: 'firebaseio.com', service: 'Realtime Database', fingerprint: false },
+  { host: 'firebasedatabase.app', service: 'Realtime Database', fingerprint: true },
+  // Cloud Storage. Both hosts appear in ordinary download and asset URLs, so
+  // neither fingerprints a build.
+  {
+    host: 'firebasestorage.googleapis.com',
+    service: 'Cloud Storage for Firebase',
+    fingerprint: false,
+  },
+  { host: 'storage.googleapis.com', service: 'Cloud Storage', fingerprint: false },
+  // Cloud Functions: `cloudfunctions.net` is the data plane the callable SDK
+  // hits (`https://<region>-<project>.cloudfunctions.net/<fn>`) and is equally
+  // the shape of a hand-written fetch; `cloudfunctions.googleapis.com` is the
+  // admin/control plane, reached by deployment tooling.
+  { host: 'cloudfunctions.net', service: 'Cloud Functions', fingerprint: false },
+  {
+    host: 'cloudfunctions.googleapis.com',
+    service: 'Cloud Functions (control plane)',
+    fingerprint: false,
+  },
+  // Messaging. `fcmregistrations` issues the token and only the SDK calls it;
+  // `fcm.googleapis.com` is the server-side send endpoint. Installations is
+  // the ID prerequisite every FCM/Remote Config bundle carries.
+  {
+    host: 'fcmregistrations.googleapis.com',
+    service: 'Firebase Cloud Messaging (registration)',
+    fingerprint: true,
+  },
+  { host: 'fcm.googleapis.com', service: 'Firebase Cloud Messaging', fingerprint: false },
+  {
+    host: 'firebaseinstallations.googleapis.com',
+    service: 'Firebase Installations',
+    fingerprint: true,
+  },
+  // AI. The Firebase AI Logic host is SDK-only; raw Vertex AI is reachable
+  // from any HTTP client.
+  { host: 'firebasevertexai.googleapis.com', service: 'Firebase AI Logic', fingerprint: true },
+  { host: 'aiplatform.googleapis.com', service: 'Vertex AI', fingerprint: false },
+  // Credential exfiltration target. Never a false positive on the wire, and
+  // never evidence that an SDK was inlined.
+  {
+    host: '169.254.169.254',
+    service: 'GCE metadata server',
+    alwaysBlock: true,
+    fingerprint: false,
+  },
+  {
+    host: 'metadata.google.internal',
+    service: 'GCE metadata server',
+    alwaysBlock: true,
+    fingerprint: false,
+  },
+];
+
+/**
+ * The subset that is evidence of inlined SDK code, and the only set the
+ * throwing frontend build check may grep for. See
+ * {@link GoogleEndpoint.fingerprint}.
+ */
+export const SDK_FINGERPRINT_HOSTS: readonly string[] = GOOGLE_ENDPOINT_CATALOG.filter(
+  (e) => e.fingerprint,
+).map((e) => e.host);
+
+/**
+ * Catalog entries longest host first, so the narrowest suffix wins regardless
+ * of the order the entries are authored in
+ * (`firebasestorage.googleapis.com` before `storage.googleapis.com`).
+ */
+const CATALOG_BY_SPECIFICITY: readonly GoogleEndpoint[] = [...GOOGLE_ENDPOINT_CATALOG].sort(
+  (a, b) => b.host.length - a.host.length,
+);
+
+/** Trim, lowercase, and drop a trailing root dot. The one spelling of a
+ *  hostname that every comparison in the guard and the catalog uses. */
+export function normalizeHostname(value: string): string {
+  return value.trim().toLowerCase().replace(/\.$/, '');
+}
+
+/**
+ * Label-boundary suffix match: `x.example.com` matches `example.com`,
+ * `notexample.com` does not.
+ */
+export function matchesHostSuffix(hostname: string, suffix: string): boolean {
+  return hostname === suffix || hostname.endsWith(`.${suffix}`);
+}
+
+/**
+ * Resolve a hostname to its catalog entry, or `undefined` when it is not a
+ * known production endpoint. Matches the exact host or a subdomain of it, on
+ * label boundaries, narrowest suffix first.
+ */
+export function lookupGoogleEndpoint(hostname: string): GoogleEndpoint | undefined {
+  const host = normalizeHostname(hostname);
+  return CATALOG_BY_SPECIFICITY.find((e) => matchesHostSuffix(host, e.host));
+}

package/src/next/guard.ts

@@ -54,7 +54,7 @@ export function enforceSandboxGuard(options?: PyricNextOptions): void {
   const errorMessage =
     '[Pyric] Next.js development server started without active Pyric sandbox environment variables.\n' +
     'To prevent accidental connections to production Firebase databases, launch this server using:\n' +
-    '  pyric dev -- next dev\n' +
+    '  pyric sandbox -- next dev\n' +
     'or source environment keys via `pyric env`.\n' +
     'To disable this guard, pass { guard: false } to withPyric(config, options).';
   throw new Error(errorMessage);

package/src/next/runtime-env.ts

@@ -12,6 +12,11 @@ export function augmentRuntimeEnv(config: NextConfigObject, options?: PyricNextO
   const updatedConfig: NextConfigObject = Object.assign({}, config);
   const existingEnv = updatedConfig.env !== undefined ? Object.assign({}, updatedConfig.env) : {};
   const chipValue = runtimeChipMetaValue(options.runtimeChip);
+  // Next.js only inlines `.env`-sourced values into the browser bundle when the
+  // key carries the `NEXT_PUBLIC_` prefix, so client components must read the
+  // prefixed name. The unprefixed name is kept for backwards compatibility with
+  // any existing server-side or bundler-level readers of `PYRIC_RUNTIME_CHIP`.
+  existingEnv.NEXT_PUBLIC_PYRIC_RUNTIME_CHIP = chipValue;
   existingEnv.PYRIC_RUNTIME_CHIP = chipValue;
   updatedConfig.env = existingEnv;
   return updatedConfig;

package/src/next/with-pyric.ts

@@ -25,7 +25,7 @@ function applyPyricEnhancements(config: NextConfigObject, options?: PyricNextOpt
 /**
  * Higher-order configuration wrapper for Next.js (`next.config.js` or `next.config.mjs`).
  *
- * During development mode (`pyric dev` or non-production NODE_ENV):
+ * During development mode (`pyric sandbox` or non-production NODE_ENV):
  *   - Applies Webpack and Turbopack alias mappings to swap `firebase/*` imports
  *     for Pyric local sandbox mirrors on client components.
  *   - Adds `firebase` and `firebase-admin` to `serverExternalPackages` to prevent

package/src/register/beacon.ts

@@ -0,0 +1,232 @@
+/**
+ * The handshake beacon: register's proof that interception is live in this
+ * process.
+ *
+ * `pyric sandbox` sets `PYRIC_SANDBOX` and appends `--import
+ * @pyric/cli/register` to the child's `NODE_OPTIONS`, and then assumes the
+ * rest. Every link in that chain is silently breakable by the user's own
+ * command: a `bun`/`deno` runner that never evaluates Node loader hooks, a
+ * script that overwrites `NODE_OPTIONS` wholesale, a `NODE_ENV=production`
+ * that trips the activation refusal, an intermediate process that strips the
+ * env. In every one of those cases the child comes up looking perfectly
+ * healthy while its `firebase-admin` and `firebase` imports resolve to the
+ * real SDKs and reach live Firebase.
+ *
+ * The beacon closes that gap the only honest way: the child says so itself,
+ * after the hooks and the net-guard are actually installed.
+ *
+ * Two channels, on purpose
+ * ------------------------
+ * 1. A fire-and-forget `POST <bridge>/__pyric/beacon`, whenever a bridge URL
+ *    is knowable from the child's own env. That is the machine channel: it
+ *    reaches the dev server across an arbitrary depth of intermediate
+ *    processes (npm, then next, then its worker), where stderr scraping stops
+ *    being attributable. It carries the per-launch secret from
+ *    `PYRIC_BEACON_TOKEN`, which is what the route authorizes on.
+ * 2. One structured stderr line, printed when the developer asked for detail
+ *    or when the report is bad news (see {@link beaconLineIsPrinted}). It is
+ *    the fallback for a process with no reachable server, no port, no network.
+ *
+ * Where the bridge URL comes from
+ * -------------------------------
+ * `cli/sandbox-runner.ts:buildChildEnv` sets
+ * `PYRIC_SANDBOX=remote:<serveUrl>`, so the activator is the address. Nothing
+ * else needs to be plumbed, and the beacon works for any descendant that
+ * inherited the env, not just the direct child. When the activator carries no
+ * URL (`PYRIC_SANDBOX=local`, or a hand-set value), there is no endpoint and
+ * the line says `bridge=none` rather than guessing.
+ *
+ * The POST must never be able to hurt the child
+ * ---------------------------------------------
+ * It is diagnostics. A refused connection, a 500, an unreachable host: every
+ * one of those is swallowed. `emitBeacon` is `void`, never awaited.
+ *
+ * It is sent over a raw `node:http` request, an unref'd socket under a hard
+ * one-second bound (see {@link BEACON_TIMEOUT_MS}), rather than `fetch`, whose
+ * pending promise has neither knob. A short `node seed.js` child must not sit
+ * around after finishing its work just to deliver a diagnostic. A child that
+ * exits before the beacon lands simply loses the machine channel, which is
+ * exactly why the watchdog on the other end is warn-only.
+ *
+ * The POST targets loopback, which is not in the shared Google endpoint
+ * catalog, so it passes the net-guard installed moments earlier without a
+ * verdict.
+ */
+import { createRequire } from 'node:module';
+import type { GuardMode } from './net-guard.js';
+
+/** The dev server route that receives beacons (`serve/beacon-route.ts`). */
+export const BEACON_PATH = '/__pyric/beacon';
+
+/** Header carrying the per-launch secret from `PYRIC_BEACON_TOKEN`. The route
+ *  rejects a beacon that does not present it. */
+export const BEACON_TOKEN_HEADER = 'x-pyric-beacon-token';
+
+const LOG_PREFIX = '@pyric/cli/register: beacon';
+
+/** What one activated child asserts about itself. Wire shape of the POST body
+ *  and the fields of the stderr line, kept identical on purpose. */
+export interface BeaconReport {
+  /** The child's own pid, the only durable handle a parent has on it. */
+  readonly pid: number;
+  /** Net-guard mode actually in force in this process. */
+  readonly guard: GuardMode;
+  /** Whether module resolution hooks were installed. `false` means imports
+   *  are NOT being rewritten, which is the whole thing worth knowing. */
+  readonly hooks: boolean;
+  /** The activator verbatim, so the parent can attribute the beacon. */
+  readonly sandbox: string;
+}
+
+export interface BeaconHooks {
+  readonly write?: (line: string) => void;
+  /** Delivery seam for the machine channel. Defaults to
+   *  {@link sendBeaconRequest}. */
+  readonly send?: (endpoint: string, body: string, token: string) => void;
+  /** Environment read for the beacon secret and the stderr gate. Defaults to
+   *  `process.env`. */
+  readonly env?: Record<string, string | undefined>;
+}
+
+/**
+ * The hard bound on how long a beacon may delay a child's exit.
+ *
+ * One second, because this is loopback: the bridge is the dev server that
+ * launched us. If it has not accepted a connection in a second it is not
+ * going to, and no diagnostic is worth more of the child's life than that.
+ */
+const BEACON_TIMEOUT_MS = 1_000;
+
+/**
+ * POST one beacon body, fire and forget, over an unref'd socket. See the
+ * module header for why this is `node:http` and not `fetch`.
+ *
+ * `token` is the per-launch secret from `PYRIC_BEACON_TOKEN`; the route
+ * rejects a beacon without it.
+ */
+export function sendBeaconRequest(endpoint: string, body: string, token: string): void {
+  const require = createRequire(import.meta.url);
+  const secure = endpoint.startsWith('https:');
+  const http = require(secure ? 'node:https' : 'node:http') as {
+    request: (url: string, options: unknown) => {
+      on(event: string, listener: (arg: unknown) => void): unknown;
+      destroy(): void;
+      end(chunk: string): void;
+    };
+  };
+  const req = http.request(endpoint, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'content-length': Buffer.byteLength(body),
+      [BEACON_TOKEN_HEADER]: token,
+    },
+  });
+
+  // The bound on how long this can delay the child's exit is the unref'd timer
+  // below, not the socket and not a request timeout. A pending connect holds
+  // the event loop open regardless of `socket.unref()`, and `req.setTimeout()`
+  // does not arm until the `connect` event, so against a blackholed loopback
+  // address a 300 ms request timeout was measured firing at 5006 ms, when the
+  // kernel reset the connection. The timer destroys the request instead: it
+  // cannot hold the loop by itself, and it always gets to run.
+  const abort = setTimeout(() => req.destroy(), BEACON_TIMEOUT_MS);
+  abort.unref?.();
+  const settle = (): void => clearTimeout(abort);
+
+  req.on('socket', (socket) => {
+    (socket as { unref?: () => void }).unref?.();
+  });
+  // A refused/reset connection is an expected outcome, not an error the child
+  // should ever hear about.
+  req.on('error', settle);
+  req.on('close', settle);
+  req.on('response', (res) => {
+    (res as { resume?: () => void }).resume?.();
+    settle();
+  });
+  req.end(body);
+}
+
+/**
+ * The beacon endpoint implied by an activator value, or `null` when none is.
+ * Accepts `remote:<url>` (what `buildChildEnv` writes) and a bare URL; any
+ * non-http(s) scheme, and anything unparseable, is `null`: an unfetchable
+ * guess is worse than an honest absence.
+ */
+export function beaconEndpoint(sandbox: string | undefined): string | null {
+  if (sandbox === undefined) return null;
+  const raw = sandbox.trim();
+  if (raw.length === 0) return null;
+  const value = raw.startsWith('remote:') ? raw.slice('remote:'.length).trim() : raw;
+  if (value.length === 0) return null;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  return `${url.origin}${BEACON_PATH}`;
+}
+
+/**
+ * One stderr line, structured the way net-guard's verdict lines are: fixed
+ * leading fields first so it is greppable (`beacon ACTIVE pid= guard= hooks=
+ * bridge=`), then the explanation.
+ */
+export function formatBeaconLine(report: BeaconReport, endpoint: string | null): string {
+  const head =
+    `${LOG_PREFIX} ACTIVE pid=${report.pid} guard=${report.guard} ` +
+    `hooks=${report.hooks ? 1 : 0} bridge=${endpoint ?? 'none'}`;
+  let hooksNote: string;
+  if (report.hooks) {
+    hooksNote = 'firebase-admin/firebase imports in this process are rewritten to the pyric sandbox';
+  } else {
+    hooksNote =
+      'module hooks did NOT install, so firebase-admin/firebase imports in this process are NOT rewritten';
+  }
+  return `${head}: ${hooksNote}, net-guard mode ${report.guard}.\n`;
+}
+
+/**
+ * Whether the stderr channel prints.
+ *
+ * Quiet by default: a healthy first run should not carry a line per launched
+ * process, and the POST already tells the dev server what happened. The line
+ * prints when the developer asked for detail (`PYRIC_GUARD` set explicitly,
+ * `PYRIC_DEBUG`, or `PYRIC_VERBOSE`), and always when the report itself is bad
+ * news, since a child whose hooks did not install may have no other way to say
+ * so.
+ */
+export function beaconLineIsPrinted(
+  report: BeaconReport,
+  env: Record<string, string | undefined>,
+): boolean {
+  if (!report.hooks) return true;
+  if ((env.PYRIC_GUARD ?? '').trim().length > 0) return true;
+  if (env.PYRIC_DEBUG) return true;
+  return Boolean(env.PYRIC_VERBOSE);
+}
+
+/**
+ * Emit the beacon. Never throws, never returns a promise: the caller is the
+ * `--import` hot path of every pyric-launched process.
+ *
+ * The POST always goes out. The stderr line is conditional, see
+ * {@link beaconLineIsPrinted}.
+ */
+export function emitBeacon(report: BeaconReport, hooks: BeaconHooks = {}): void {
+  const env = hooks.env ?? process.env;
+  const write = hooks.write ?? ((line: string) => void process.stderr.write(line));
+  const endpoint = beaconEndpoint(report.sandbox);
+  if (beaconLineIsPrinted(report, env)) write(formatBeaconLine(report, endpoint));
+  if (endpoint === null) return;
+  const token = env.PYRIC_BEACON_TOKEN ?? '';
+  try {
+    (hooks.send ?? sendBeaconRequest)(endpoint, JSON.stringify(report), token);
+  } catch {
+    // A runtime with no usable http module, or an endpoint that slipped the
+    // URL parse, loses the machine channel only.
+  }
+}