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

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;

package/src/cli/serve.ts

@@ -10,8 +10,9 @@
  * rules load (fail fast on broken rules) → SDK bundle (cached per pyric
  * version) → static server with the `/__pyric/` namespace + HTML injection.
  */
+import { randomBytes } from 'node:crypto';
 import { join, relative, resolve } from 'node:path';
-import { existsSync, readdirSync, readFileSync, statSync, watch as watchFile } from 'node:fs';
+import { existsSync, watch as watchFile } from 'node:fs';
 import type { ParsedArgs } from './parse-args.js';
 import { readFirebaseJson, readFirebaseRc, type FirebaseJson } from './firebase-json.js';
 import { bundleSdk, bundleWorker, defaultSdkEntries, resolveSiteUiDir } from '../serve/bundler.js';
@@ -22,7 +23,9 @@ import {
   embeddedWorkerVersion,
 } from '../serve/standalone-assets.js';
 import { hasSandboxBuildMarker } from '../serve/sandbox-marker.js';
+import { formatBeaconReceipt } from '../serve/beacon-route.js';
 import type { InitPayload } from '../serve/namespace.js';
+import { formatAiStatusLine } from '../serve/ai-status.js';
 import { injectServeTags } from '../serve/html-injection.js';
 import { formatActivityWarning } from '../serve/activity-warning.js';
 import { consoleServeLogger, startStaticServer, stderrServeLogger, type ServeHandle } from '../serve/server.js';
@@ -38,6 +41,12 @@ import {
   waitForSandboxPeer,
   type SandboxChildHandle,
 } from './sandbox-runner.js';
+import {
+  reportLaunchChecks,
+  startBeaconWatchdog,
+  type BeaconWatchdog,
+} from './sandbox-interlock.js';
+import { scanForInlinedFirebase } from './inlined-sdk-scanner.js';
 import {
   createFunctionsDevelopmentRuntime,
   createHttpFunctionsPeerReadiness,
@@ -88,6 +97,12 @@ export interface ServeRuntime {
   uiUrl: string | null;
   /** Persistence summary (null when `--persist` is off). */
   persist: { restoredDocs: number; restoredUsers: number } | null;
+  /** Handshake beacons posted to `/__pyric/beacon` so far, the interlock
+   *  watchdog's only input. */
+  beaconCount: () => number;
+  /** The per-launch secret a beacon must present, placed in every child's
+   *  `PYRIC_BEACON_TOKEN`. */
+  beaconToken: string;
 }
 
 /** The `--json` stdout contract — one line, keep stable; agents parse this.
@@ -152,6 +167,12 @@ export async function startServe(opts: {
 }): Promise<ServeRuntime> {
   const logger = opts.logger ?? consoleServeLogger();
 
+  // Handshake beacons from pyric-launched children, plus the per-launch secret
+  // that authorizes one. Both live here because the route does.
+  let beaconsSeen = 0;
+  const beaconCount = (): number => beaconsSeen;
+  const beaconToken = randomBytes(24).toString('base64url');
+
   // --fresh only means anything against the state.json file `--persist`
   // maintains — without `--persist` there is no file to discard, so
   // `--fresh` alone was a silent no-op (nothing happened, nothing said so).
@@ -212,12 +233,12 @@ export async function startServe(opts: {
 
   // The import map can only remap BARE `firebase/*` specifiers. A plain bundler
   // build (`vite build`) inlines the real SDK into the app chunk, leaving
-  // nothing to intercept — the page would then talk to REAL Firebase endpoints
+  // nothing to intercept: the page would then talk to REAL Firebase endpoints
   // with the sandbox's fake credentials while the injected banner claims
   // otherwise. That hole is structural, so `pyric sandbox` refuses such a dist
   // rather than serving it. A pyric SANDBOX build (`vite build --mode
   // development`) carries the marker and bundles pyric's in-page adapters, so it
-  // is trusted and the scan is skipped (marker present → no real SDK to find).
+  // is trusted and the scan is skipped (marker present, no real SDK to find).
   if (!hasSandboxBuildMarker(publicDir)) {
     const inlined = scanForInlinedFirebase(publicDir);
     if (inlined.length > 0) {
@@ -306,6 +327,11 @@ export async function startServe(opts: {
       studio: opts.ui ? { siteUiDir } : false,
       bridgeUrl: () => mount && origin.port > 0 ? mount.wsUrl(origin) : null,
       activity: (incident) => logger.note(formatActivityWarning(incident)),
+      beaconToken,
+      beacon: (report) => {
+        beaconsSeen += 1;
+        logger.note(formatBeaconReceipt(report));
+      },
       permissive: opts.permissive,
       logger,
     });
@@ -494,7 +520,7 @@ export async function startServe(opts: {
     session.payload().storageRules
       ? `✔ rules    ${session.summary.rules.storage.sourcePath} → deployed to the storage sandbox (hash ${session.summary.rules.storage.hash}; ` +
         `edits require a restart — storage rules do not hot-reload)`
-      : `• rules    no storage.rules — storage sandbox runs open (no rules configured)`,
+      : `• rules    no storage.rules — storage sandbox denies client operations by default`,
   );
   if (uiUrl) {
     logger.info(`✔ studio   Pyric Studio: ${uiUrl}`);
@@ -505,6 +531,13 @@ export async function startServe(opts: {
   if (mount) {
     logger.info(`✔ bridge   MCP endpoint: ${mount.mcpUrl(origin)} (sandbox peers over ws at /__pyric/sandbox)`);
   }
+  // AI is a mounted service like the bridge: `/__pyric/ai-proxy` answers from
+  // the first request on, whether or not anything is configured. `pyric
+  // sandbox` has no AI flag, so the ENGINE is always the page's own `getAI()`
+  // choice (resolved lazily in the browser, since nothing here instantiates a
+  // broker to find out); what this server does decide is where the proxy
+  // forwards, and that is what the line reports.
+  logger.info(formatAiStatusLine({}));
   let persistSummary: ServeRuntime['persist'] = null;
   const persistence = session.summary.persistence;
   if (persistence) {
@@ -553,7 +586,8 @@ export async function startServe(opts: {
   logger.note('');
   logger.note('  ⚠ the pyric sandbox runs IN the served page — keep the browser tab open.');
   logger.note('    Firestore/auth data and persistence stop when no page is open.');
-  return { handle, publicDir, payload, uiUrl, mcpUrl: mount ? mount.mcpUrl(origin) : null, persist: persistSummary };
+  const mcpUrl = mount ? mount.mcpUrl(origin) : null;
+  return { handle, publicDir, payload, uiUrl, mcpUrl, persist: persistSummary, beaconCount, beaconToken };
 }
 
 /**
@@ -779,6 +813,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
   }
 
   let devChild: SandboxChildHandle | null = null;
+  let beaconWatchdog: BeaconWatchdog | null = null;
   let functionsRuntime: FunctionsDevelopmentRuntime | null = null;
   let resolveFunctionsExit!: (code: number) => void;
   const functionsExited = new Promise<number>((resolve) => { resolveFunctionsExit = resolve; });
@@ -801,6 +836,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     ]);
   const stopAfterSignal = async (): Promise<number> => {
     (json ? process.stderr : process.stdout).write('\nShutting down...\n');
+    beaconWatchdog?.stop();
     if (devChild && devChild.child.exitCode === null) devChild.signal(await signal);
     await functionsRuntime?.close().catch(() => undefined);
     await runtime.handle.stop().catch(() => undefined);
@@ -845,6 +881,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
       baseEnv: process.env,
       serveUrl: runtime.handle.url,
       registerUrl: registerModuleUrl(),
+      beaconToken: runtime.beaconToken,
       instance: `${functionsProjectId}-default-rtdb`,
       location: process.env.PYRIC_FUNCTIONS_RTDB_REGION ?? 'us-central1',
       projectId: functionsProjectId ?? 'demo-project',
@@ -910,19 +947,37 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     info.write(
       `✔ run      \`${plan.label}\` — firebase-admin/firebase imports are routed to the sandbox at ${runtime.handle.url}\n`,
     );
-    devChild = spawnSandboxChild(plan, {
-      cwd,
-      json,
-      env: buildChildEnv(process.env, {
-        serveUrl: runtime.handle.url,
-        registerUrl: registerModuleUrl(),
-      }),
+    const childEnv = buildChildEnv(process.env, {
+      serveUrl: runtime.handle.url,
+      registerUrl: registerModuleUrl(),
+      beaconToken: runtime.beaconToken,
+    });
+    // What we are handing the child, stated before it starts: the interlock
+    // line and the unsupported-runtime check.
+    const interlock = reportLaunchChecks({
+      childEnv,
+      registerUrl: registerModuleUrl(),
+      argv: plan.argv,
+      write: (line) => info.write(line),
+    });
+
+    devChild = spawnSandboxChild(plan, { cwd, json, env: childEnv });
+    // A child still alive well after launch that never posted a beacon is very
+    // likely not intercepted. `startBeaconWatchdog` says why this only warns.
+    const beaconsAtSpawn = runtime.beaconCount();
+    beaconWatchdog = startBeaconWatchdog({
+      label: plan.label,
+      beacon: interlock.beacon,
+      sawBeacon: () => runtime.beaconCount() > beaconsAtSpawn,
+      isAlive: () => devChild !== null && devChild.child.exitCode === null,
+      warn: (line) => void process.stderr.write(`${line}\n`),
     });
   } else if (!json) {
     process.stdout.write(
       formatStartupEnvExport({
         serveUrl: runtime.handle.url,
         registerUrl: registerModuleUrl(),
+        beaconToken: runtime.beaconToken,
       }),
     );
   }
@@ -934,6 +989,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
       if (settled) return;
       settled = true;
       void (async () => {
+        beaconWatchdog?.stop();
         await functionsRuntime?.close().catch(() => undefined);
         if (devChild && devChild.child.exitCode === null) {
           devChild.signal('SIGTERM');
@@ -971,60 +1027,3 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     void signal.then(shutdown);
   });
 }
-
-/**
- * Detect a bundler build that INLINED the real firebase SDK into its served
- * assets (`vite build` output). The served import map remaps only bare
- * `firebase/*` specifiers, so such a build cannot be sandboxed — its calls
- * reach real Google endpoints. Fingerprints are real-SDK-only endpoint hosts
- * that never appear in a sandbox-clean app (whose calls all route to
- * `/__pyric/*`). Bounded: depth ≤ 4, ≤ 200 script files, first hit per file.
- * Returns publicDir-relative paths of offending assets.
- */
-export function scanForInlinedFirebase(dir: string): string[] {
-  const FINGERPRINTS = [
-    'identitytoolkit.googleapis.com',
-    'firestore.googleapis.com',
-    'securetoken.googleapis.com',
-    'firebasedatabase.app',
-  ];
-  const hits: string[] = [];
-  let scanned = 0;
-  const walk = (d: string, rel: string, depth: number): void => {
-    if (depth > 4 || scanned >= 200) return;
-    let names: string[];
-    try {
-      names = readdirSync(d);
-    } catch {
-      return;
-    }
-    for (const name of names) {
-      if (scanned >= 200) return;
-      const p = join(d, name);
-      const r = rel ? `${rel}/${name}` : name;
-      let st;
-      try {
-        st = statSync(p);
-      } catch {
-        continue;
-      }
-      if (st.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 and must be ignored.
-        if (name === 'node_modules' || name.startsWith('.')) continue;
-        walk(p, r, depth + 1);
-      } else if (/\.(js|mjs)$/.test(name)) {
-        scanned++;
-        try {
-          const text = readFileSync(p, 'utf8');
-          if (FINGERPRINTS.some((f) => text.includes(f))) hits.push(r);
-        } catch {
-          // unreadable asset: skip
-        }
-      }
-    }
-  };
-  walk(dir, '', 0);
-  return hits;
-}

package/src/cli/unsupported-runtime.ts

@@ -0,0 +1,68 @@
+/**
+ * Child runtimes that cannot evaluate Node loader hooks, and the one warning
+ * that says what is lost when a command starts one.
+ */
+
+/** Tokens that end one command and begin the next inside a shell string. */
+export const SHELL_OPERATORS = new Set(['&&', '||', '|', ';', '&']);
+
+/** Command basenames that cannot evaluate Node loader hooks, to the runtime. */
+const UNSUPPORTED_RUNTIME_BINARIES = new Map<string, string>([
+  ['bun', 'bun'],
+  ['bunx', 'bun'],
+  ['deno', 'deno'],
+]);
+
+/** Leading `KEY=VAL` environment assignments in a shell command. */
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/** Strip directory and a Windows `.exe` suffix from a command token. */
+function commandBasename(token: string): string {
+  const base = token.split(/[\\/]/).pop() ?? token;
+  return base.toLowerCase().replace(/\.exe$/, '');
+}
+
+/**
+ * Decide whether the child command starts a runtime that cannot intercept.
+ *
+ * Detection is by command name: argv[0], and any token that begins a new
+ * command after a shell operator, with leading `KEY=VAL` assignments skipped
+ * and the path and `.exe` decoration stripped. That is the honest 90%.
+ * `npm run dev` whose package script shells out to bun is undetectable from
+ * here, and guessing would cost false positives on names that merely start
+ * with the same letters (`bundle exec`).
+ *
+ * Returns the canonical runtime name (`bun` for `bunx` too) or null.
+ */
+export function detectUnsupportedRuntime(argv: readonly string[]): string | null {
+  let atCommandStart = true;
+  for (const token of argv) {
+    if (atCommandStart && ENV_ASSIGNMENT.test(token)) continue;
+    if (SHELL_OPERATORS.has(token)) {
+      atCommandStart = true;
+      continue;
+    }
+    if (atCommandStart) {
+      const runtime = UNSUPPORTED_RUNTIME_BINARIES.get(commandBasename(token));
+      if (runtime !== undefined) return runtime;
+      atCommandStart = false;
+    }
+  }
+  return null;
+}
+
+/**
+ * The one warning. It has to say both halves of what is lost: the loader swap
+ * (interception itself) and the net guard (the socket backstop that would
+ * otherwise catch the egress), because the guard is installed by the same
+ * `--import`ed register module and is therefore just as absent.
+ */
+export function formatUnsupportedRuntimeWarning(runtime: string): string {
+  return (
+    `  ⚠ runtime: pyric interception is not supported under \`${runtime}\`. It does not evaluate ` +
+    `Node loader hooks, so the child's firebase/firebase-admin imports will NOT be rewritten and ` +
+    `may reach LIVE Firebase. The net-guard socket backstop also only applies under Node, so it ` +
+    `will not catch that egress either. Run the command under \`node\` (or \`npx tsx\`) for the ` +
+    `sandbox swap. Warning only: nothing was blocked.\n`
+  );
+}