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

package/src/bridge/tool-families.generated.ts

@@ -0,0 +1,17 @@
+// Generated by scripts/generate-tool-family-registry.ts. Do not edit.
+import type { ToolFamily } from './tool-families.js';
+import conformance from './tool-family-records/conformance.js';
+import firestoreData from './tool-family-records/firestore-data.js';
+import firestoreInspect from './tool-family-records/firestore-inspect.js';
+import firestoreRules from './tool-family-records/firestore-rules.js';
+import firestoreSimulator from './tool-family-records/firestore-simulator.js';
+import rtdbInspection from './tool-family-records/rtdb-inspection.js';
+
+export const TOOL_FAMILIES = [
+  { key: "conformance", ...conformance },
+  { key: "firestore-data", ...firestoreData },
+  { key: "firestore-inspect", ...firestoreInspect },
+  { key: "firestore-rules", ...firestoreRules },
+  { key: "firestore-simulator", ...firestoreSimulator },
+  { key: "rtdb-inspection", ...rtdbInspection },
+] as const satisfies readonly ToolFamily[];

package/src/bridge/tool-families.ts

@@ -0,0 +1,87 @@
+/**
+ * Tool family contract shared by both sides of the bridge.
+ *
+ * A family is authored as one record under `tool-family-records/`: its
+ * transport, its position in the default `tools/list` order, and the exact
+ * tool names its factory yields. `scripts/generate-tool-family-registry.ts`
+ * aggregates the records into `tool-families.generated.ts`. This module reads
+ * only that aggregate, so the browser bundle and the MCP process share one
+ * manifest without either importing the other's factories.
+ *
+ * Factories live in `server/tool-family-factories.ts` (Node) and
+ * `client/tool-family-factories.ts` (browser). Each map is typed against the
+ * family keys derived here, so a record without a factory, or a factory
+ * without a record, fails to compile.
+ */
+import { TOOL_FAMILIES } from './tool-families.generated.js';
+
+export type ToolTransport = 'forwarded' | 'in-process';
+
+/** Authored in one record file per family. The key is the filename without `.ts`; the generator adds it. */
+export interface ToolFamilyRecord {
+  /** `forwarded`: executed by the browser sandbox peer. `in-process`: executed in the MCP process. */
+  readonly transport: ToolTransport;
+  /** Stable position in the default `tools/list` order. Unique across all records; authored with gaps of 10. */
+  readonly order: number;
+  /** Exact names the family factory yields for the default surface, in factory order. */
+  readonly tools: readonly string[];
+}
+
+export interface ToolFamily extends ToolFamilyRecord {
+  readonly key: string;
+}
+
+type RegisteredFamily = (typeof TOOL_FAMILIES)[number];
+export type ForwardedFamilyKey = Extract<RegisteredFamily, { transport: 'forwarded' }>['key'];
+export type InProcessFamilyKey = Extract<RegisteredFamily, { transport: 'in-process' }>['key'];
+
+function assertUnique(label: string, values: readonly (string | number)[]): void {
+  const seen = new Set<string | number>();
+  for (const value of values) {
+    if (seen.has(value)) throw new Error(`duplicate tool family ${label} '${value}'`);
+    seen.add(value);
+  }
+}
+
+function validateFamilies(families: readonly RegisteredFamily[]): readonly RegisteredFamily[] {
+  assertUnique('key', families.map((family) => family.key));
+  assertUnique('order', families.map((family) => family.order));
+  assertUnique('tool name', families.flatMap((family) => family.tools));
+  return [...families].sort((a, b) => a.order - b.order);
+}
+
+const FAMILIES_BY_ORDER = validateFamilies(TOOL_FAMILIES);
+
+/** Families of one transport, sorted by `order`. Validates once at load: duplicate key, order, or tool name throws. */
+export function toolFamilies<T extends ToolTransport>(
+  transport: T,
+): readonly Extract<RegisteredFamily, { transport: T }>[] {
+  return FAMILIES_BY_ORDER.filter(
+    (family): family is Extract<RegisteredFamily, { transport: T }> =>
+      family.transport === transport,
+  );
+}
+
+/**
+ * Fail closed when a factory yields a different name set from the records.
+ * Both sides call this with the same message so drift reads the same
+ * wherever it surfaces.
+ */
+export function assertExactToolNames(
+  label: string,
+  actual: readonly string[],
+  expected: readonly string[],
+): void {
+  const actualSorted = [...actual].sort();
+  const expectedSorted = [...expected].sort();
+  if (
+    actualSorted.length !== expectedSorted.length ||
+    actualSorted.some((name, index) => name !== expectedSorted[index])
+  ) {
+    throw new Error(
+      `${label} drifted from the default MCP contract\n` +
+        `expected: ${expected.join(', ')}\n` +
+        `actual:   ${actual.join(', ')}`,
+    );
+  }
+}

package/src/bridge/tool-family-records/conformance.ts

@@ -0,0 +1,6 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'in-process',
+  order: 60,
+  tools: ['pyric_can_i_use'],
+} as const satisfies ToolFamilyRecord;

package/src/bridge/tool-family-records/firestore-data.ts

@@ -0,0 +1,15 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'forwarded',
+  order: 20,
+  tools: [
+    'firestore_get_document',
+    'firestore_list_documents',
+    'firestore_create_document',
+    'firestore_add_document',
+    'firestore_update_document',
+    'firestore_delete_document',
+    'firestore_batch_write',
+    'firestore_query_where',
+  ],
+} as const satisfies ToolFamilyRecord;

package/src/bridge/tool-family-records/firestore-inspect.ts

@@ -0,0 +1,6 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'forwarded',
+  order: 30,
+  tools: ['sandbox_inspect'],
+} as const satisfies ToolFamilyRecord;

package/src/bridge/tool-family-records/firestore-rules.ts

@@ -0,0 +1,15 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'in-process',
+  order: 50,
+  tools: [
+    'firestore_simulate_rules',
+    'firestore_rules_stdlib_list',
+    'firestore_rules_stdlib_get',
+    'firestore_lint_rules',
+    'firestore_resolve_modules',
+    'rules_stdlib_list',
+    'rules_stdlib_get',
+    'rules_resolve_modules',
+  ],
+} as const satisfies ToolFamilyRecord;

package/src/bridge/tool-family-records/firestore-simulator.ts

@@ -0,0 +1,16 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'forwarded',
+  order: 10,
+  tools: [
+    'firestore_simulator_create',
+    'firestore_simulator_execute',
+    'firestore_simulator_read',
+    'firestore_simulator_batch',
+    'firestore_create_with_auto_id',
+    'firestore_simulator_undo',
+    'firestore_simulator_redo',
+    'firestore_simulator_events',
+    'firestore_simulator_transaction',
+  ],
+} as const satisfies ToolFamilyRecord;

package/src/bridge/tool-family-records/rtdb-inspection.ts

@@ -0,0 +1,6 @@
+import type { ToolFamilyRecord } from '../tool-families.js';
+export default {
+  transport: 'forwarded',
+  order: 40,
+  tools: ['rtdb_simulate_access', 'rtdb_crawl_structure'],
+} as const satisfies ToolFamilyRecord;

package/src/bundler/externals.ts

@@ -0,0 +1,55 @@
+/**
+ * Externalization presets and helpers for Node backend bundlers.
+ *
+ * Prevents backend bundlers (Rolldown, esbuild, tsup, Rollup, Vite, Webpack)
+ * from inlining Firebase and Firebase Admin SDKs into bundled server outputs,
+ * preserving runtime interception by `@pyric/cli/register` under `pyric sandbox`.
+ */
+
+/**
+ * RegExp patterns matching Firebase packages for bundlers that accept RegExp
+ * in their external configuration (Rolldown, Rollup, Vite, Webpack).
+ */
+export const pyricRollupExternals: readonly RegExp[] = Object.freeze([
+  /^firebase-admin(\/.*)?$/,
+  /^firebase(\/.*)?$/,
+  /^@firebase(\/.*)?$/,
+]);
+
+/**
+ * Wildcard string patterns matching Firebase packages for bundlers that require
+ * string arrays with glob wildcards (esbuild, tsup).
+ */
+export const pyricEsbuildExternals: readonly string[] = Object.freeze([
+  'firebase-admin',
+  'firebase-admin/*',
+  'firebase',
+  'firebase/*',
+  '@firebase/*',
+]);
+
+/**
+ * Universal predicate returning true if a module specifier belongs to Firebase
+ * or Firebase Admin SDK surfaces intercepted by Pyric.
+ *
+ * Compatible with bundlers that accept a function in their external setting
+ * (Rolldown, Rollup, Vite, Webpack).
+ */
+export function isPyricExternal(id: string): boolean {
+  if (typeof id !== 'string' || id.length === 0) {
+    return false;
+  }
+  return pyricRollupExternals.some((regex) => regex.test(id));
+}
+
+/**
+ * Convenience presets mapping bundler names to their supported external pattern format.
+ */
+export const pyricExternals = Object.freeze({
+  rolldown: pyricRollupExternals,
+  rollup: pyricRollupExternals,
+  vite: pyricRollupExternals,
+  webpack: pyricRollupExternals,
+  esbuild: pyricEsbuildExternals,
+  tsup: pyricEsbuildExternals,
+});

package/src/bundler/index.ts

@@ -0,0 +1,21 @@
+/**
+ * `@pyric/cli/bundler` — externalization presets and helpers for Node backend
+ * bundlers (Rolldown, esbuild, tsup, Rollup, Vite) to preserve `@pyric/cli/register`
+ * runtime sandbox interception.
+ *
+ *   // rolldown.config.ts / rollup.config.js
+ *   import { pyricExternals } from '@pyric/cli/bundler';
+ *   export default { external: pyricExternals.rolldown };
+ *
+ *   // vite.config.ts (SSR / Node backend builds)
+ *   export default { build: { rollupOptions: { external: pyricExternals.vite } } };
+ *
+ *   // tsup.config.ts / esbuild.config.mjs
+ *   export default { external: pyricExternals.esbuild };
+ */
+export {
+  pyricRollupExternals,
+  pyricEsbuildExternals,
+  isPyricExternal,
+  pyricExternals,
+} from './externals.js';

package/src/cli/cli.test.ts

@@ -461,47 +461,3 @@ describe('runInit', () => {
     expect(io.getOut()).toContain('skipped package.json'); // unchanged merge
   });
 });
-
-describe('scanForInlinedFirebase', () => {
-  it('flags a bundled chunk that inlines real-SDK endpoint hosts', async () => {
-    const { scanForInlinedFirebase } = await import('./serve.js');
-    const { mkdtempSync, mkdirSync, writeFileSync } = await import('node:fs');
-    const { tmpdir } = await import('node:os');
-    const { join } = await import('node:path');
-    const dir = mkdtempSync(join(tmpdir(), 'pyric-inline-scan-'));
-    mkdirSync(join(dir, 'assets'));
-    writeFileSync(
-      join(dir, 'assets', 'index-abc.js'),
-      'fetch("https://identitytoolkit.googleapis.com/v1/projects?key="+k)',
-    );
-    const hits = scanForInlinedFirebase(dir);
-    expect(hits).toEqual(['assets/index-abc.js']);
-  });
-
-  it('stays clean for an unbundled app importing firebase by bare specifier', async () => {
-    const { scanForInlinedFirebase } = await import('./serve.js');
-    const { mkdtempSync, writeFileSync } = await import('node:fs');
-    const { tmpdir } = await import('node:os');
-    const { join } = await import('node:path');
-    const dir = mkdtempSync(join(tmpdir(), 'pyric-inline-clean-'));
-    writeFileSync(
-      join(dir, 'main.js'),
-      "import { getAuth } from 'firebase/auth'; import { getFirestore } from 'firebase/firestore';",
-    );
-    expect(scanForInlinedFirebase(dir)).toEqual([]);
-  });
-
-  it('ignores hidden frameworks and build cache directories like .next and .git', async () => {
-    const { scanForInlinedFirebase } = await import('./serve.js');
-    const { mkdtempSync, mkdirSync, writeFileSync } = await import('node:fs');
-    const { tmpdir } = await import('node:os');
-    const { join } = await import('node:path');
-    const dir = mkdtempSync(join(tmpdir(), 'pyric-inline-ignore-'));
-    mkdirSync(join(dir, '.next'));
-    writeFileSync(
-      join(dir, '.next', 'bundle.js'),
-      'fetch("https://identitytoolkit.googleapis.com/v1/projects?key="+k)',
-    );
-    expect(scanForInlinedFirebase(dir)).toEqual([]);
-  });
-});

package/src/cli/inlined-sdk-scanner.ts

@@ -0,0 +1,77 @@
+/**
+ * Detect a served frontend build that inlined the real Firebase SDK.
+ *
+ * The served import map remaps only bare `firebase/*` specifiers, so a plain
+ * `vite build` that compiled the SDK into an app chunk cannot be sandboxed:
+ * its calls reach real Google endpoints while the injected banner claims
+ * otherwise. `cli/serve.ts` refuses such a dist rather than serving it.
+ *
+ * Only the SDK fingerprint hosts are matched, never the full endpoint catalog.
+ * This check throws, and a dist can legitimately carry a bare callable URL, a
+ * public asset URL, or a `databaseURL` literal without any Firebase SDK in it.
+ *
+ * Backend bundles are deliberately out of scope. `withPyric` externalizes
+ * firebase and firebase-admin, the backend-bundler docs tell users to mark them
+ * external, and the net guard reports real egress at runtime with attribution,
+ * which a grep over build output cannot do.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { SDK_FINGERPRINT_HOSTS } from '../google-endpoints.js';
+
+/** Depth limit for the walk. */
+const MAX_DEPTH = 4;
+
+/** Total script files read. */
+const MAX_FILES = 200;
+
+/** Script extensions worth reading in served frontend output. */
+const SCRIPT_FILE = /\.(js|mjs)$/;
+
+/**
+ * Scan `dir` for inlined SDK fingerprints and return the offending paths,
+ * relative to `dir`. Bounded: depth 4, 200 script files, first hit per file.
+ */
+export function scanForInlinedFirebase(dir: string): string[] {
+  const hits: string[] = [];
+  let scanned = 0;
+  const walk = (current: string, rel: string, depth: number): void => {
+    if (depth > MAX_DEPTH || scanned >= MAX_FILES) return;
+    let names: string[];
+    try {
+      names = readdirSync(current);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      if (scanned >= MAX_FILES) return;
+      const path = join(current, name);
+      const relPath = rel ? `${rel}/${name}` : name;
+      let stat;
+      try {
+        stat = statSync(path);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        // The pyric namespace itself never lands in hosting.public, but a
+        // node_modules inside a served dir would be a scan-cost trap.
+        // Dot-directories (.next, .git, .pyric) are internal caches.
+        if (name === 'node_modules' || name.startsWith('.')) continue;
+        walk(path, relPath, depth + 1);
+        continue;
+      }
+      if (!SCRIPT_FILE.test(name)) continue;
+      scanned++;
+      let text: string;
+      try {
+        text = readFileSync(path, 'utf8');
+      } catch {
+        continue; // unreadable asset
+      }
+      if (SDK_FINGERPRINT_HOSTS.some((host) => text.includes(host))) hits.push(relPath);
+    }
+  };
+  walk(dir, '', 0);
+  return hits;
+}

package/src/cli/sandbox-interlock.ts

@@ -0,0 +1,167 @@
+/**
+ * The interlock: the launcher's statement about interception in the child it
+ * is about to start, plus the warn-only watchdog for the child's answer.
+ *
+ * The status line is knowable synchronously from the env `pyric sandbox` just
+ * assembled: guard mode, whether NODE_OPTIONS really carries the register
+ * import, and where the child's handshake beacon will land. The watchdog is
+ * the other half: a child still alive well after launch that never posted a
+ * beacon is probably not intercepted.
+ */
+import { beaconEndpoint } from '../register/beacon.js';
+import { parseGuardMode, type GuardMode } from '../register/net-guard.js';
+import { detectUnsupportedRuntime, formatUnsupportedRuntimeWarning } from './unsupported-runtime.js';
+
+/**
+ * What `pyric sandbox` can say about the interception it is about to hand the
+ * child, entirely from the env it just assembled: no waiting, no round trip.
+ */
+export interface InterlockStatus {
+  /** Net-guard mode the child will run under (`PYRIC_GUARD`, default warn). */
+  readonly guard: GuardMode;
+  /** Whether `NODE_OPTIONS` actually carries the register `--import`. */
+  readonly registerImported: boolean;
+  /** Where the child's handshake beacon will land, or null when the
+   *  activator carries no bridge URL. */
+  readonly beacon: string | null;
+}
+
+/**
+ * Read the interlock off the child env. Everything here is synchronous by
+ * construction: it is a statement about the launch, printed before anything at
+ * runtime has had a chance to go wrong.
+ */
+export function describeInterlock(
+  childEnv: NodeJS.ProcessEnv,
+  registerUrl: string,
+): InterlockStatus {
+  return {
+    guard: parseGuardMode(childEnv.PYRIC_GUARD),
+    registerImported: (childEnv.NODE_OPTIONS ?? '').includes(`--import ${registerUrl}`),
+    beacon: beaconEndpoint(childEnv.PYRIC_SANDBOX),
+  };
+}
+
+/**
+ * The startup status line, alongside the other `✔ <service>` checks.
+ *
+ * The healthy line is deliberately short: one fact per field and nothing the
+ * reader has to skim past. The degraded line is long because it reports a
+ * broken launch, which is worth every word.
+ */
+export function formatInterlockLine(status: InterlockStatus): string {
+  if (!status.registerImported) {
+    return (
+      `⚠ interlock guard=${status.guard}, register is NOT in the child's NODE_OPTIONS. ` +
+      `Its firebase-admin/firebase imports will NOT be rewritten and would reach LIVE Firebase.\n`
+    );
+  }
+  return `✔ interlock guard=${status.guard}, register loaded via NODE_OPTIONS\n`;
+}
+
+export interface LaunchCheckOptions {
+  /** The environment the child is about to receive. */
+  readonly childEnv: NodeJS.ProcessEnv;
+  /** Absolute `file:` URL of the register module, to look for in NODE_OPTIONS. */
+  readonly registerUrl: string;
+  /** The child's argv, for the unsupported-runtime check. */
+  readonly argv: readonly string[];
+  readonly write: (line: string) => void;
+}
+
+/**
+ * Every statement the launcher makes about the child, printed in one block
+ * before the spawn, and the interlock status it derived on the way.
+ *
+ * Two checks: the interlock status line, from the env alone, and the
+ * unsupported-runtime warning for the other way interception can be absent, a
+ * child runtime that never evaluates Node loader hooks at all.
+ */
+export function reportLaunchChecks(opts: LaunchCheckOptions): InterlockStatus {
+  const interlock = describeInterlock(opts.childEnv, opts.registerUrl);
+  opts.write(formatInterlockLine(interlock));
+  const unsupportedRuntime = detectUnsupportedRuntime(opts.argv);
+  if (unsupportedRuntime !== null) opts.write(formatUnsupportedRuntimeWarning(unsupportedRuntime));
+  return interlock;
+}
+
+/** How long a child may live without its beacon before we say something. */
+const BEACON_GRACE_MS = 15_000;
+
+export interface BeaconWatchdogOptions {
+  /** The child command, for attribution in the warning. */
+  readonly label: string;
+  /** The endpoint the child would post to. Null means nothing to watch. */
+  readonly beacon: string | null;
+  /** Whether a beacon from this child has been recorded. */
+  readonly sawBeacon: () => boolean;
+  /** Whether the child is still running. */
+  readonly isAlive: () => boolean;
+  readonly warn: (line: string) => void;
+  readonly graceMs?: number;
+}
+
+export interface BeaconWatchdog {
+  /** Cancel a pending check. Idempotent. */
+  stop(): void;
+}
+
+/** The warning itself: one paragraph naming what the silence means and what
+ *  to check. Kept separate so its exact wording is testable. */
+export function formatMissingBeaconWarning(opts: {
+  label: string;
+  graceMs: number;
+  beacon: string;
+}): string {
+  const seconds = Math.round(opts.graceMs / 1000);
+  return (
+    `  ⚠ interlock: \`${opts.label}\` has been running ${seconds}s without posting a register ` +
+    `beacon to ${opts.beacon}. Its firebase-admin/firebase imports are probably NOT routed to ` +
+    `the pyric sandbox, which means they would reach LIVE Firebase. Check that the command starts ` +
+    `a Node process (bun and deno do not evaluate Node loader hooks), that it does not overwrite ` +
+    `NODE_OPTIONS, and that NODE_ENV is not production. Warning only: nothing was blocked, and ` +
+    `this is reported once per child.`
+  );
+}
+
+/**
+ * The warn-only interlock watchdog.
+ *
+ * It never kills the child and never blocks a request. The reason is the
+ * signal's own honesty: beacon delivery is best-effort (see
+ * `register/beacon.ts`), and a plausible silent child is not the same thing as
+ * a broken one. A short-lived script that exits before its POST lands, a child
+ * that reaches the sandbox only through a grandchild, a dev server slow to
+ * boot: each would be killed by a fail-closed version of this check, and each
+ * is fine.
+ *
+ * So the heuristic is the simple, attributable one: the child is still alive
+ * `graceMs` after launch and no beacon has arrived. Both halves matter. An
+ * exited child was never expected to say anything, and a child whose beacon
+ * landed has already proved the point. One warning per child, guaranteed by
+ * the one-shot timer; the timer is unref'd so a watchdog can never be the
+ * reason a process stays up.
+ *
+ * `sawBeacon` is a count delta rather than a pid match, deliberately. The
+ * process that loads register is often a grandchild (`npm run dev` starts
+ * node, `next dev` starts its worker), so the spawned child's own pid is
+ * frequently not the pid in the beacon, and matching on it would warn about
+ * perfectly healthy launches. The delta's known imprecision runs the other
+ * way: a sibling runtime's beacon that lands inside the grace window can mask
+ * a real miss. Erring toward silence is the right bias for a warn-only check.
+ */
+export function startBeaconWatchdog(opts: BeaconWatchdogOptions): BeaconWatchdog {
+  const beacon = opts.beacon;
+  if (beacon === null) return { stop: () => {} };
+  const graceMs = opts.graceMs ?? BEACON_GRACE_MS;
+  const timer = setTimeout(() => {
+    if (opts.sawBeacon() || !opts.isAlive()) return;
+    opts.warn(formatMissingBeaconWarning({ label: opts.label, graceMs, beacon }));
+  }, graceMs);
+  timer.unref?.();
+  return {
+    stop(): void {
+      clearTimeout(timer);
+    },
+  };
+}

package/src/cli/sandbox-runner.ts

@@ -16,6 +16,7 @@
  * only `spawnDevChild` touches the process table.
  */
 import { spawn, type ChildProcess } from 'node:child_process';
+import { SHELL_OPERATORS } from './unsupported-runtime.js';
 
 // ─── First-run race guard ───────────────────────────────────────────────────
 
@@ -152,41 +153,60 @@ export function registerModuleUrl(): string {
   return new URL('../register/index.js', import.meta.url).href;
 }
 
+/** What the launcher has to put in a child's environment for interception. */
+export interface ChildActivation {
+  /** The serve host the child's sandbox calls reach. */
+  readonly serveUrl: string;
+  /** Absolute `file:` URL of the register module. */
+  readonly registerUrl: string;
+  /** The per-launch secret the child's handshake beacon must present.
+   *  Absent when the launcher runs no beacon receiver, as the Vite plugin's
+   *  Functions runtime does; the child then reports on stderr only. */
+  readonly beaconToken?: string | undefined;
+}
+
 /**
- * Child env: sets the activator and APPENDS the loader to NODE_OPTIONS —
- * never replaces it (the user's own --inspect / --max-old-space-size etc.
- * must survive). `file:` URLs are percent-encoded, so no quoting is needed
- * even for paths with spaces.
+ * Child env: sets the activator and the beacon secret, and APPENDS the loader
+ * to NODE_OPTIONS rather than replacing it (the user's own --inspect /
+ * --max-old-space-size and so on must survive). `file:` URLs are
+ * percent-encoded, so no quoting is needed even for paths with spaces.
  */
 export function buildChildEnv(
   base: NodeJS.ProcessEnv,
-  opts: { serveUrl: string; registerUrl: string },
+  opts: ChildActivation,
 ): NodeJS.ProcessEnv {
   const importFlag = `--import ${opts.registerUrl}`;
-  return {
+  const env: NodeJS.ProcessEnv = {
     ...base,
     PYRIC_SANDBOX: `remote:${opts.serveUrl}`,
     NODE_OPTIONS: base.NODE_OPTIONS ? `${base.NODE_OPTIONS} ${importFlag}` : importFlag,
   };
+  if (opts.beaconToken !== undefined) env.PYRIC_BEACON_TOKEN = opts.beaconToken;
+  return env;
 }
 
 /**
  * Format copy-pasteable POSIX export statements for host-only startup.
  * Grouped in a cleanly formatted console block for easy selection and copying
  * into a separate terminal (for example, when running Next.js independently).
+ *
+ * The beacon secret is part of the block: without it a process started this
+ * way still intercepts, but the dev server cannot confirm that it did.
  */
-export function formatStartupEnvExport(opts: { serveUrl: string; registerUrl: string }): string {
-  const pyricSandbox = `remote:${opts.serveUrl}`;
-  const nodeOptions = `--import ${opts.registerUrl}`;
-  const line1 = `export PYRIC_SANDBOX="${pyricSandbox}"`;
-  const line2 = `export NODE_OPTIONS="${nodeOptions}"`;
-  const divider = '─'.repeat(Math.max(line1.length, line2.length) + 4);
+export function formatStartupEnvExport(opts: ChildActivation): string {
+  const lines = [`export PYRIC_SANDBOX="remote:${opts.serveUrl}"`];
+  if (opts.beaconToken !== undefined) {
+    lines.push(`export PYRIC_BEACON_TOKEN="${opts.beaconToken}"`);
+  }
+  lines.push(`export NODE_OPTIONS="--import ${opts.registerUrl}"`);
+  const width = Math.max(...lines.map((line) => line.length));
+  const divider = '─'.repeat(width + 4);
+  const body = lines.map((line) => `  ${line}\n`).join('');
   return (
     '\n' +
     '  To run external commands against this sandbox, paste in another terminal:\n' +
     `  ${divider}\n` +
-    `  ${line1}\n` +
-    `  ${line2}\n` +
+    body +
     `  ${divider}\n`
   );
 }
@@ -225,8 +245,6 @@ export function createLinePrefixer(
 /** How long a signalled child may linger before SIGKILL. */
 const FORCE_KILL_AFTER_MS = 2_000;
 
-const SHELL_OPERATORS = new Set(['&&', '||', '|', ';', '&']);
-
 export interface SandboxChildHandle {
   exited: Promise<number>;
   signal(sig: NodeJS.Signals): void;
@@ -259,16 +277,9 @@ export function spawnSandboxChild(
   // 2. Check for discrete shell operators (&&, ||, |, ;) among top-level tokens
   const hasShellOperators = parts.some((token) => SHELL_OPERATORS.has(token));
 
-  // 3. Warn if runtime is bun or deno
-  if (parts.length > 0 && (parts[0] === 'bun' || parts[0] === 'deno')) {
-    const runner = parts[0];
-    const target = opts.json ? process.stderr : process.stdout;
-    target.write(
-      `  ⚠ ${runner} detected: pyric intercepts Firebase imports via Node.js module loader hooks (NODE_OPTIONS="--import ..."). ` +
-        `${runner} does not evaluate Node loader hooks — SDK calls in this process will not reach the pyric sandbox. ` +
-        `Use \`node\` (or \`npx tsx\`) to run with the sandbox swap.\n`,
-    );
-  }
+  // The bun/deno warning is emitted by the launch seam in serve.ts, alongside
+  // the interlock line, so every pre-spawn statement about the child prints in
+  // one block and in order.
 
   const [command, ...args] = parts;
   let child: ChildProcess;