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

package/src/cli/serve.ts

@@ -1,5 +1,5 @@
 /**
- * `pyric dev` — local dev server with the pyric sandbox standing in for
+ * `pyric sandbox` is the local server with the Pyric sandbox standing in for
  * Firebase. Feels like `firebase serve` (banner, labeled lines, port 3473,
  * SIGINT shutdown) with the sandbox-flavored extras firebase can't do: the
  * served page runs an in-browser backend, your `firestore.rules` deploy into
@@ -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,23 +23,30 @@ 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';
 import { createBridgeMount } from '../serve/bridge-mount.js';
 import { openBrowser, shouldAutoOpen } from '../serve/open-browser.js';
+import { readPyricConfig, type PyricConfig } from './pyric-config.js';
 import {
   buildChildEnv,
-  detectPackageManager,
   formatStartupEnvExport,
-  readDevScript,
   registerModuleUrl,
-  resolveDevChild,
-  spawnDevChild,
+  resolveSandboxChild,
+  spawnSandboxChild,
   waitForSandboxPeer,
-  type DevChildHandle,
-} from './dev-runner.js';
+  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,
@@ -60,7 +68,7 @@ interface HostingConfig {
   rewrites?: Array<{ source?: string; destination?: string }>;
 }
 
-/** Extract the single hosting config `pyric dev` v1 supports. Arrays
+/** Extract the single hosting config `pyric sandbox` supports. Arrays
  *  (multi-site) take the first entry with a warning — multi-site is out of
  *  scope (plan section 6). */
 export function extractHosting(config: FirebaseJson | null): HostingConfig | null {
@@ -84,11 +92,17 @@ export interface ServeRuntime {
   payload: () => InitPayload;
   /** HTTP MCP endpoint when `--bridge` is on; null otherwise. */
   mcpUrl: string | null;
-  /** The Studio app URL (`/__pyric/ui/`) when `--ui` is on and the build is
+  /** The Studio hub URL (`/__pyric/ui/studio`) when `--ui` is on and the build is
    *  present; null otherwise. */
   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.
@@ -147,17 +161,25 @@ export async function startServe(opts: {
    *  (the served project's file tree) + `/__pyric/projects` (single-project
    *  store over `cwd`). The Studio app's `local` mode talks to these. */
   ui?: boolean;
+  /** Explicit opt-in to permissive mode (default-allow RTDB rules when unconfigured). */
+  permissive?: boolean;
   logger?: Parameters<typeof startStaticServer>[0]['logger'];
 }): 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).
   // Fail fast instead of pretending to reset something.
   if (opts.fresh && !opts.persist) {
     throw new Error(
-      'pyric dev: --fresh requires --persist (it discards .pyric/state/state.json). ' +
+      'pyric sandbox: --fresh requires --persist (it discards .pyric/state/state.json). ' +
         'Browser-stored data is cleared from Studio → Settings → Reset, or DevTools → Clear site data.',
     );
   }
@@ -172,9 +194,29 @@ export async function startServe(opts: {
     logger.note('  ⚠ no firebase.json found — serving the current directory without hosting config');
   }
 
+  const pyricConfig = await readPyricConfig(opts.cwd);
+  if (pyricConfig.rules) {
+    if (!config) config = {};
+    if (typeof pyricConfig.rules === 'string') {
+      config.firestore = { ...config.firestore, rules: pyricConfig.rules };
+    } else {
+      if (pyricConfig.rules.firestore) {
+        config.firestore = { ...config.firestore, rules: pyricConfig.rules.firestore };
+      }
+      if (pyricConfig.rules.database) {
+        config.database = { ...config.database, rules: pyricConfig.rules.database };
+      }
+      if (pyricConfig.rules.storage) {
+        const baseStorage =
+          typeof config.storage === 'object' && !Array.isArray(config.storage) ? config.storage : {};
+        config.storage = { ...baseStorage, rules: pyricConfig.rules.storage };
+      }
+    }
+  }
+
   const hosting = extractHosting(config);
   if (Array.isArray(config?.hosting) && (config.hosting as unknown[]).length > 1) {
-    logger.note('  ⚠ multiple hosting sites configured — pyric dev v1 serves the first entry only');
+    logger.note('  ⚠ multiple hosting sites configured. pyric sandbox serves the first entry only');
   }
   const publicDir = resolve(opts.cwd, hosting?.public ?? '.');
   if (!existsSync(publicDir)) {
@@ -184,31 +226,31 @@ export async function startServe(opts: {
     const looksLikeBuildOutput = /(^|[\\/])(dist|build|out)$/.test(publicDir);
     const hint = looksLikeBuildOutput
       ? `\n  No build yet? Run \`bun run dev\` for the live sandbox dev server, ` +
-        `or \`bun run build\` then \`pyric dev\` to preview the production build.`
+        `or \`bun run build\` then \`pyric sandbox\` to preview the production build.`
       : '';
-    throw new Error(`pyric dev: hosting.public directory does not exist: ${publicDir}${hint}`);
+    throw new Error(`pyric sandbox: hosting.public directory does not exist: ${publicDir}${hint}`);
   }
 
   // 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 dev` REFUSES such a dist
+  // 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) {
       throw new Error(
-        `pyric dev: ${inlined[0]} bundles the REAL firebase SDK, so this dist cannot be ` +
+        `pyric sandbox: ${inlined[0]} bundles the real Firebase SDK, so this dist cannot be ` +
           `sandboxed — its firebase/* calls would reach LIVE Google endpoints, not the ` +
           `pyric sandbox. Two ways forward:\n` +
-          `  (a) plain \`pyric dev\` runs the child dev-server flow (the @pyric/cli/vite ` +
+          `  (a) \`pyric sandbox -- <command>\` runs the child server with the @pyric/cli/vite ` +
           `plugin swaps firebase/* live) — use \`bun run dev\`;\n` +
           `  (b) rebuild as a self-contained sandbox bundle and serve THAT: ` +
           `\`vite build --mode development\` (or pyric({ swapInBuild: true })) then ` +
-          `\`pyric dev\`.\n` +
+          `\`pyric sandbox\`.\n` +
           `A plain \`vite build\` is your production build — deploy it, don't sandbox it.`,
       );
     }
@@ -285,15 +327,21 @@ 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,
     });
   } catch (error) {
     bundle.dispose?.();
     if (error instanceof SandboxSeedError) {
       if (error.kind === 'read') {
-        throw new Error(`pyric dev: failed to read --seed ${error.path}: ${error.detail}`);
+        throw new Error(`pyric sandbox: failed to read --seed ${error.path}: ${error.detail}`);
       }
-      throw new Error(`pyric dev: --seed must be a JSON object of "collection/doc" → fields, ${error.detail}`);
+      throw new Error(`pyric sandbox: --seed must be a JSON object of "collection/doc" to fields, ${error.detail}`);
     }
     throw error;
   }
@@ -376,7 +424,7 @@ export async function startServe(opts: {
   };
   if (bundle.dispose) handle.server.once('close', bundle.dispose);
   handle.server.once('close', () => void closeOwnedResources());
-  const uiUrl = siteUiDir ? `${handle.url}/__pyric/ui/` : null;
+  const uiUrl = siteUiDir ? `${handle.url}/__pyric/ui/studio` : null;
   const docsUrl = siteUiDir ? `${handle.url}/__pyric/ui/docs/` : null;
 
   // Hot-reload: the static adapter observes the filesystem; the session owns
@@ -472,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}`);
@@ -483,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) {
@@ -531,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 };
 }
 
 /**
@@ -547,7 +603,7 @@ export function bridgeEnabledFromFlags(flags: { get(key: string): unknown }): bo
  * A dev child also implies the bridge: the runner injects
  * `PYRIC_SANDBOX=remote:<url>` into the child, whose remote client dials the
  * `/__pyric/sandbox` WS — without the bridge mount that upgrade 404s and
- * plain `pyric dev -- <cmd>` (or a detected dev script) breaks its own
+ * `pyric sandbox -- <cmd>` breaks its own
  * child. Pure + exported for unit coverage.
  */
 export function bridgeEnabledFor(
@@ -560,7 +616,7 @@ export function bridgeEnabledFor(
 
 /**
  * Process-level last line of defense for the dev server: a single bad
- * request/WS interaction must never take `pyric dev` down. Node kills the
+ * request/WS interaction must never take `pyric sandbox` down. Node kills the
  * process on an unhandled rejection (default `--unhandled-rejections=throw`
  * since v15) and on any uncaught exception — and the serve process hosts
  * long-lived, browser-driven machinery (WS peers, SSE streams, file watchers,
@@ -578,13 +634,13 @@ export function installServeProcessGuard(
     reason instanceof Error ? (reason.stack ?? reason.message) : String(reason);
   const onRejection = (reason: unknown): void => {
     log(
-      `  ✖ pyric dev: UNHANDLED REJECTION (the server was kept alive — please report this):\n` +
+      `  ✖ pyric sandbox: unhandled rejection. The server was kept alive. Please report this:\n` +
         `    ${describe(reason).split('\n').join('\n    ')}`,
     );
   };
   const onException = (err: unknown): void => {
     log(
-      `  ✖ pyric dev: UNCAUGHT EXCEPTION (the server was kept alive — please report this):\n` +
+      `  ✖ pyric sandbox: uncaught exception. The server was kept alive. Please report this:\n` +
         `    ${describe(err).split('\n').join('\n    ')}`,
     );
   };
@@ -596,10 +652,49 @@ export function installServeProcessGuard(
   };
 }
 
+function resolveServePort(flagPort: unknown, configPort?: number): number {
+  if (typeof flagPort === 'string') return Number(flagPort);
+  if (typeof flagPort === 'number') return flagPort;
+  if (typeof configPort === 'number') return configPort;
+  return 3473;
+}
+
+function resolveProjectIdentifier(
+  flagProject?: unknown,
+  envProject?: string,
+  configProject?: string,
+  rcDefault?: string,
+): string {
+  if (typeof flagProject === 'string' && flagProject.length > 0) return flagProject;
+  if (typeof envProject === 'string' && envProject.length > 0) return envProject;
+  if (typeof configProject === 'string' && configProject.length > 0) return configProject;
+  if (typeof rcDefault === 'string' && rcDefault.length > 0) return rcDefault;
+  return 'demo-project';
+}
+
+function resolveExplicitCommand(parsed: ParsedArgs): string[] | null {
+  if (parsed.passthrough && parsed.passthrough.length > 0) {
+    return parsed.passthrough;
+  }
+  if (parsed.positional.length > 0) {
+    return parsed.positional;
+  }
+  return null;
+}
+
 /** CLI entry. Resolves on SIGINT/SIGTERM after a clean stop. */
 export async function runServe(parsed: ParsedArgs): Promise<number> {
+  const cwd = process.cwd();
+  let pyricConfig: PyricConfig = {};
+  try {
+    pyricConfig = await readPyricConfig(cwd);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 2;
+  }
+
   const flagPort = parsed.flags.get('port');
-  const port = typeof flagPort === 'string' ? Number(flagPort) : 3473;
+  const port = resolveServePort(flagPort, pyricConfig.port);
   if (!Number.isFinite(port) || port < 0 || port > 65535) {
     process.stderr.write(`pyric: invalid --port '${flagPort}'.\n`);
     return 1;
@@ -610,7 +705,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
   const only = parsed.flags.get('only');
   if (typeof only === 'string' && only !== 'hosting') {
     process.stderr.write(
-      `pyric: --only '${only}' is not supported — pyric dev v1 serves hosting (with the in-page sandbox standing in for firestore/auth).\n`,
+      `pyric: --only '${only}' is not supported. pyric sandbox serves hosting with the in-page sandbox standing in for Firestore and Auth.\n`,
     );
     return 1;
   }
@@ -623,7 +718,6 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
   // Resolve the child plan BEFORE the server starts: a planned child implies
   // the bridge (see bridgeEnabledFor) — the child's injected PYRIC_SANDBOX
   // is useless without the /__pyric/sandbox WS mount.
-  const cwd = process.cwd();
   let functionsProject: FunctionsRtdbProject | null;
   let functionsProjectId: string | null = null;
   try {
@@ -631,22 +725,25 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     if (functionsProject) {
       const flagProject = parsed.flags.get('project');
       const rc = await readFirebaseRc(cwd);
-      functionsProjectId =
-        (typeof flagProject === 'string' ? flagProject : undefined) ??
-        process.env.PYRIC_PROJECT ??
-        rc?.projects?.default ??
-        'demo-project';
+      functionsProjectId = resolveProjectIdentifier(
+        flagProject,
+        process.env.PYRIC_PROJECT,
+        pyricConfig.project,
+        rc?.projects?.default,
+      );
     }
   } catch (error) {
     process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
     return 2;
   }
-  const plan = resolveDevChild({
-    passthrough: parsed.passthrough ?? [],
+
+  const explicitCommand = resolveExplicitCommand(parsed);
+
+  const plan = resolveSandboxChild({
+    explicitCommand,
+    configCommand: pyricConfig.command,
     noRun: Boolean(parsed.flags.get('no-run')),
     json,
-    devScript: readDevScript(cwd),
-    packageManager: detectPackageManager(cwd),
   });
   const bridgeOn = bridgeEnabledFor(parsed.flags, plan, functionsProject);
 
@@ -663,6 +760,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
       watch: parsed.flags.get('no-watch') ? false : undefined,
       persist: Boolean(parsed.flags.get('persist')),
       fresh: Boolean(parsed.flags.get('fresh')),
+      permissive: Boolean(parsed.flags.get('permissive')),
       // --ui mounts the Pyric Studio storage routes (workspace + projects).
       ui: uiOn,
       // --no-capture disables the default-on session capture. The pattern
@@ -675,7 +773,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
       project:
         typeof parsed.flags.get('project') === 'string'
           ? (parsed.flags.get('project') as string)
-          : process.env.PYRIC_PROJECT ?? functionsProjectId ?? undefined,
+          : process.env.PYRIC_PROJECT ?? pyricConfig.project ?? functionsProjectId ?? undefined,
     });
   } catch (e) {
     process.stderr.write(`${e instanceof Error ? e.message : String(e)}\n`);
@@ -691,7 +789,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
   // (the banner went to stderr). Readiness probe: GET /__pyric/init.json.
   if (json) process.stdout.write(serveJsonLine(runtime) + '\n');
 
-  // Footgun guard (hybrid-MCP plan Phase 3): plain `dev` mounts no MCP bridge,
+  // A host-only sandbox mounts no MCP bridge unless one is needed.
   // so a `pyric mcp-proxy` in an editor cannot attach. Nudge toward --bridge.
   if (!bridgeOn && !json) {
     process.stderr.write(
@@ -714,7 +812,8 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     void openBrowser(targetUrl);
   }
 
-  let devChild: DevChildHandle | null = null;
+  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; });
@@ -737,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);
@@ -781,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',
@@ -793,7 +894,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     if (result.kind === 'no-peer') {
       process.stderr.write(
         `  ⚠ functions not started — no browser tab connected after 30s. ` +
-          `Open ${runtime.handle.url} and restart pyric dev.\n`,
+          `Open ${runtime.handle.url} and restart pyric sandbox.\n`,
       );
     } else if (result.kind === 'failed') {
       process.stderr.write(`${result.error.message}\n`);
@@ -810,16 +911,15 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
       for (const unsupported of ready.unsupportedTriggers) {
         process.stderr.write(
           `  ⚠ functions export ${unsupported.exportName} uses unsupported trigger ` +
-            `${unsupported.eventType}; it will not run in pyric dev.\n`,
+            `${unsupported.eventType}; it will not run in pyric sandbox.\n`,
         );
       }
     }
   }
 
-  // The child runner ("one command, not two"): run the user's own dev
-  // command with the sandbox environment injected. Precedence: `-- <cmd>`
-  // wins; else the package.json dev script; else host-only. --no-run forces
-  // host-only; --json defaults to host-only (explicit `--` still wins).
+  // Run the explicit or configured command with the sandbox environment.
+  // `--no-run` forces host-only. `--json` skips the configured command, but an
+  // explicit command still runs.
   // (`plan` was resolved above so it could imply the bridge mount.)
   if (plan) {
     const info = json ? process.stderr : process.stdout;
@@ -838,23 +938,46 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
           `  ⚠ no browser tab connected after 30s — starting your command anyway; sandbox ops will fail until ${runtime.handle.url} is open.\n`,
         );
       }
+    } else if (!json) {
+      info.write(
+        `  ⓘ Auto-open is disabled (--no-open/CI). The pyric sandbox is browser-resident: ` +
+          `open ${runtime.handle.url} to connect if your command performs Firebase operations.\n`,
+      );
     }
     info.write(
       `✔ run      \`${plan.label}\` — firebase-admin/firebase imports are routed to the sandbox at ${runtime.handle.url}\n`,
     );
-    devChild = spawnDevChild(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,
       }),
     );
   }
@@ -866,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');
@@ -895,7 +1019,7 @@ export async function runServe(parsed: ParsedArgs): Promise<number> {
     if (functionsRuntime) {
       void functionsExited.then((code) => {
         if (!settled && !shuttingDown) {
-          process.stderr.write(`pyric dev: Functions child exited unexpectedly (code ${code}).\n`);
+          process.stderr.write(`pyric sandbox: Functions child exited unexpectedly (code ${code}).\n`);
           finish(code === 0 ? 1 : code);
         }
       });
@@ -903,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/snapshot.ts

@@ -6,13 +6,13 @@
  *   pyric snapshot [--out FILE] [--port N] [--force] [--json]
  *
  * Source preference:
- *   1. LIVE state from a running `pyric dev --persist`
+ *   1. Live state from a running `pyric sandbox --persist`
  *      (`GET /__pyric/state` — `--port`, else the 3473+ scan window),
  *   2. else the on-disk `.pyric/state/state.json`,
  *   3. else exit 2 with a clear message.
  *
  * The output is a `PyricStateFile` envelope — directly re-servable:
- * `pyric dev --seed <out>` (the state-file shape is detected by its
+ * `pyric sandbox --seed <out>` (the state-file shape is detected by its
  * `version` key and seeds docs + users).
  */
 import { existsSync, writeFileSync } from 'node:fs';
@@ -44,7 +44,7 @@ async function fetchLive(port: number): Promise<LiveState | null> {
     if (!body || typeof body !== 'object' || !('version' in body)) return null;
     return { envelope: body, projectDir: res.headers.get('x-pyric-project-dir') };
   } catch {
-    return null; // nothing listening / not a pyric dev — fall through
+    return null; // No Pyric sandbox is listening. Fall through.
   }
 }
 
@@ -110,7 +110,7 @@ export async function runSnapshot(parsed: ParsedArgs, deps: SnapshotDeps = {}):
   }
   if (!envelope) {
     err.write(
-      'pyric snapshot: no state found — no `pyric dev --persist` is running here and ' +
+      'pyric snapshot: no state found. No `pyric sandbox --persist` is running here and ' +
         'no .pyric/state/state.json exists. Run with --persist (and use the app) first.\n',
     );
     return 2;
@@ -158,7 +158,7 @@ export async function runSnapshot(parsed: ParsedArgs, deps: SnapshotDeps = {}):
   if (redactedCount > 0) {
     report.write(`  ⓘ redacted ${redactedCount} password(s) — re-run with --include-passwords to keep them\n`);
   }
-  report.write(`  Re-serve it: pyric dev --seed ${typeof outFlag === 'string' ? outFlag : 'pyric-state.json'}\n`);
+  report.write(`  Re-serve it: pyric sandbox --seed ${typeof outFlag === 'string' ? outFlag : 'pyric-state.json'}\n`);
   if (json) out.write(JSON.stringify({ out: outPath, docs, users, source, redactedPasswords: redactedCount }) + '\n');
   return 0;
 }