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

package/src/bridge/surface/sandbox-context.ts

@@ -0,0 +1,49 @@
+/**
+ * The execution context a method record gets wherever the sandbox lives.
+ *
+ * Its dispatcher reaches only the forwarded tool families, through the same
+ * `buildSandboxDispatcher` the page and the SharedWorker already run, and it
+ * reads no file. A host that keeps its sandbox in a browser can therefore
+ * build one and run any record marked `runsIn: 'sandbox'` against it. The
+ * bridge process builds the wider context in `./context.ts` on top of this one.
+ */
+import type { LocalSandbox } from 'pyric/sandbox';
+import { buildSandboxDispatcher } from '../client/dispatch.js';
+import { accountLookupFor } from './app-session.js';
+import type { DatabaseInstanceCatalog } from './database-instance-catalog.js';
+import { SurfaceIdentity } from './identity.js';
+import type { OperationResult, SandboxSurfaceContext } from './types.js';
+
+/**
+ * Build the context for one sandbox. `databaseInstances` answers which RTDB
+ * instances a `database` method may name, from what the host serves.
+ */
+export function createSandboxSurfaceContext(
+  sandbox: LocalSandbox,
+  databaseInstances: () => Promise<DatabaseInstanceCatalog>,
+): SandboxSurfaceContext {
+  return {
+    sandbox,
+    dispatch: buildSandboxDispatcher(sandbox),
+    identity: new SurfaceIdentity(accountLookupFor(sandbox)),
+    databaseInstances,
+  };
+}
+
+/**
+ * Call one existing sandbox tool under the held identity. Arguments are
+ * objects in and objects out; nothing is JSON-encoded on the way through.
+ */
+export async function callSandboxTool(
+  ctx: SandboxSurfaceContext,
+  name: string,
+  args: Record<string, unknown>,
+): Promise<OperationResult> {
+  return ctx.dispatch(name, args, ctx.identity.lens());
+}
+
+/** Report a failure in the shape every handler returns. */
+export function operationFailure(summary: string, data?: unknown): OperationResult {
+  if (data === undefined) return { ok: false, summary };
+  return { ok: false, summary, data };
+}

package/src/bridge/surface/service-handles.ts

@@ -12,15 +12,15 @@ import { getAdminDatabase, getDatabase, type Database } from 'pyric/database';
 import { getAdminFirestore, getFirestore, type Firestore } from 'pyric/firestore';
 import { getMessagingBroker, type MessagingBroker } from 'pyric/messaging/internal';
 import { getStorageSandbox, type FirebaseStorage } from 'pyric/storage';
-import { getAdminStorageSandbox } from 'pyric/storage/internal';
-import type { SurfaceContext } from './types.js';
+import { getAdminStorageSandbox, nameStorageBucket } from 'pyric/storage/internal';
+import type { SandboxSurfaceContext } from './types.js';
 
 /**
  * A Realtime Database handle for the held identity, on the instance `selector`
  * names (`instanceSelector` in `database-instance.ts`); absent is the default
  * instance. Each instance enforces its own rules.
  */
-export function databaseFor(ctx: SurfaceContext, selector?: string): Database {
+export function databaseFor(ctx: SandboxSurfaceContext, selector?: string): Database {
   if (ctx.identity.bypassesRules()) return getAdminDatabase(ctx.sandbox, selector);
   return getDatabase(ctx.sandbox.withAuth(ctx.identity.authState()), selector);
 }
@@ -32,15 +32,19 @@ export function databaseFor(ctx: SurfaceContext, selector?: string): Database {
 // `Firestore` handle rather than the dispatcher's plain-object tool call.
 
 /** A Cloud Firestore handle for the held identity, for the methods that build a `Query` directly. */
-export function firestoreFor(ctx: SurfaceContext): Firestore {
+export function firestoreFor(ctx: SandboxSurfaceContext): Firestore {
   if (ctx.identity.bypassesRules()) return getAdminFirestore(ctx.sandbox);
   return getFirestore(ctx.sandbox.withAuth(ctx.identity.authState()));
 }
 
 /** A Cloud Storage handle for the held identity. */
-export function storageFor(ctx: SurfaceContext): FirebaseStorage {
-  if (ctx.identity.bypassesRules()) return getAdminStorageSandbox(ctx.sandbox);
-  return getStorageSandbox(ctx.sandbox.withAuth(ctx.identity.authState()));
+export function storageFor(ctx: SandboxSurfaceContext): FirebaseStorage {
+  // Rules, and a simulation on this handle, see the default bucket under the
+  // served app's name for it, as the app's own requests do (ST-H2-4).
+  const handle = ctx.identity.bypassesRules()
+    ? getAdminStorageSandbox(ctx.sandbox)
+    : getStorageSandbox(ctx.sandbox.withAuth(ctx.identity.authState()));
+  return nameStorageBucket(handle, ctx.storageBucketName?.());
 }
 
 /**
@@ -50,7 +54,7 @@ export function storageFor(ctx: SurfaceContext): FirebaseStorage {
  * routed through the held identity the way firestore, database, and storage
  * are.
  */
-export function messagingBrokerFor(ctx: SurfaceContext): MessagingBroker {
+export function messagingBrokerFor(ctx: SandboxSurfaceContext): MessagingBroker {
   return getMessagingBroker(ctx.sandbox);
 }
 
@@ -59,7 +63,7 @@ export function messagingBrokerFor(ctx: SurfaceContext): MessagingBroker {
  * the way messaging does not, so this is not routed through the held
  * identity either.
  */
-export function aiFor(ctx: SurfaceContext): AI {
+export function aiFor(ctx: SandboxSurfaceContext): AI {
   return getAI(ctx.sandbox);
 }
 

package/src/bridge/surface/sign-in.ts

@@ -19,9 +19,9 @@ import { getAuth, sandbox as authSandbox } from 'pyric/auth';
 import type { LocalSandbox } from 'pyric/sandbox';
 
 import { describeAppSession, readAppSession } from './app-session.js';
-import { operationFailure } from './context.js';
+import { operationFailure } from './sandbox-context.js';
 import { describeAgentIdentity } from './held-identity.js';
-import type { OperationResult, SurfaceContext } from './types.js';
+import type { OperationResult, SandboxSurfaceContext } from './types.js';
 
 /** The fix for a credential no account in the pool matches. */
 export const MISSING_ACCOUNT_FIX =
@@ -66,7 +66,7 @@ export function scopeToStoredTenant(sandbox: LocalSandbox, subject: SignInSubjec
  * Report what a sign-in or a sign-out did: the app session it moved, and the
  * agent identity it left alone.
  */
-export function reportAppSession(ctx: SurfaceContext): OperationResult {
+export function reportAppSession(ctx: SandboxSurfaceContext): OperationResult {
   const appSession = readAppSession(ctx.sandbox);
   const agent = ctx.identity.describe();
   return {

package/src/bridge/surface/storage-rules.ts

@@ -9,10 +9,9 @@
  * ruleset.
  */
 import type { LocalSandbox } from 'pyric/sandbox';
-import type { StorageReference } from 'pyric/storage';
 import { getStorageRulesResolution } from 'pyric/storage/internal';
 import { storageFor } from './service-handles.js';
-import type { SurfaceContext } from './types.js';
+import type { SandboxSurfaceContext } from './types.js';
 
 /**
  * A project's storage rules source that could not be loaded into the service
@@ -30,19 +29,8 @@ export function rememberUnloadedStorageRules(sandbox: LocalSandbox, source: stri
  * The storage rules source in force, or the project source that failed to
  * load, or null when the service was opened without rules.
  */
-export function activeStorageRules(ctx: SurfaceContext): string | null {
+export function activeStorageRules(ctx: SandboxSurfaceContext): string | null {
   const loaded = getStorageRulesResolution(storageFor(ctx))?.source;
   if (loaded !== undefined) return loaded;
   return unloadedStorageRules.get(ctx.sandbox) ?? null;
 }
-
-/**
- * The path a Storage rule matches on. Rules address an object through the
- * bucket, as `b/<bucket>/o/<object path>`, while the operation set names the
- * object path alone.
- */
-export function rulesRequestPath(object: StorageReference): string {
-  return object.fullPath === ''
-    ? `b/${object.bucket}/o`
-    : `b/${object.bucket}/o/${object.fullPath}`;
-}

package/src/bridge/surface/stored-identity.ts

@@ -18,7 +18,7 @@
 import { getAuth, sandbox as authSandbox } from 'pyric/auth';
 
 import type { IdentityInput } from './identity.js';
-import type { SurfaceContext } from './types.js';
+import type { SandboxSurfaceContext } from './types.js';
 
 /** The tenant and claims one user record holds, as a caller may override them. */
 export interface NamedIdentity {
@@ -31,7 +31,7 @@ export interface NamedIdentity {
  * session has no remembered projection, and without this lookup it would act
  * untenanted and unclaimed, and the verdict would explain the wrong denial.
  */
-export function storedIdentity(ctx: SurfaceContext, uid: string): NamedIdentity {
+export function storedIdentity(ctx: SandboxSurfaceContext, uid: string): NamedIdentity {
   const stored = authSandbox.exportUsers(getAuth(ctx.sandbox)).find((user) => user.uid === uid);
   const identity: NamedIdentity = {};
   if (stored?.tenantId !== undefined) identity.tenant = stored.tenantId;
@@ -44,7 +44,7 @@ export function storedIdentity(ctx: SurfaceContext, uid: string): NamedIdentity
  * the call named written over it field by field.
  */
 export function impersonatedIdentity(
-  ctx: SurfaceContext,
+  ctx: SandboxSurfaceContext,
   uid: string,
   named: NamedIdentity,
 ): IdentityInput {

package/src/bridge/surface/types.ts

@@ -9,6 +9,7 @@
  */
 import type { LocalSandbox } from 'pyric/sandbox';
 import type { SandboxDispatch } from '../client/dispatch.js';
+import type { DatabaseInstanceCatalog } from './database-instance-catalog.js';
 import type { SurfaceIdentity } from './identity.js';
 
 /** What one operation returns. Mirrors the dispatcher's result shape. */
@@ -28,11 +29,37 @@ export interface SurfaceTargetRouter {
   ): Promise<OperationResult>;
 }
 
-/** Everything a handler is given: the sandbox, the shared dispatcher, and the caller identity. */
-export interface SurfaceContext {
+/**
+ * What a handler is given wherever the sandbox lives: the sandbox, the
+ * dispatcher over the forwarded tool families, the caller identity, and the
+ * RTDB instances a `database` method may name. A record that runs in the
+ * sandbox (`runsIn: 'sandbox'`) is given only this, so it cannot reach the
+ * project directory or a tool family that exists only in Node.
+ */
+export interface SandboxSurfaceContext {
   sandbox: LocalSandbox;
   dispatch: SandboxDispatch;
   identity: SurfaceIdentity;
+  /**
+   * The RTDB instances a `database` method may name. A host answers from the
+   * instances it serves; the bridge process reads the project's files on each
+   * call.
+   */
+  databaseInstances(): Promise<DatabaseInstanceCatalog>;
+  /**
+   * The name the served app knows its default Storage bucket by (its
+   * `storageBucket` option), when the host serving the sandbox knows it.
+   * Storage rules simulation binds it as the bucket's name.
+   */
+  storageBucketName?: () => string | undefined;
+}
+
+/**
+ * Everything a handler in the bridge process is given: the sandbox context,
+ * plus the project directory, the checkpoint store, the target router, and a
+ * dispatcher that also reaches the in-process tool families.
+ */
+export interface SurfaceContext extends SandboxSurfaceContext {
   /**
    * The directory the session's own files live under: the rules files, the
    * in-process state, and everything else below `.pyric/`. A method that reaches
@@ -41,15 +68,10 @@ export interface SurfaceContext {
    * project directory that is not where the process was started.
    */
   projectDir: string;
-  /** Dynamic target router for hosted following (ADR 0016). */
   /** Where the host keeps checkpoints, when not the project's directory. */
   checkpoints?: import('pyric/sandbox/checkpoints').CheckpointBackend;
+  /** Dynamic target router for hosted following (ADR 0016). */
   targetRouter?: SurfaceTargetRouter;
-  /**
-   * The RTDB instances a `database` method may name, when the host serving the
-   * sandbox knows them. Absent, they are read from the project's files.
-   */
-  databaseInstances?: import('./database-instance-catalog.js').DatabaseInstanceCatalog;
 }
 
 /** One tool as an MCP client sees it. */

package/src/cli/firebase-json.ts

@@ -15,11 +15,13 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 export interface FirebaseJson {
-  firestore?: {
-    rules?: string;
-    indexes?: string;
-    database?: string;
-  };
+  /**
+   * Firestore rules and indexes, as the Firebase CLI reads them: one object
+   * that deploys to its `database`, or to `(default)`, or an array whose
+   * entries each name a `database`, or a `target` that `.firebaserc` maps to
+   * databases. `firestoreRulesConfig` in `pyric/sandbox/internal` resolves it.
+   */
+  firestore?: FirestoreConfig | FirestoreConfigEntry[];
   /**
    * Realtime Database rules, as the Firebase CLI reads them: one object whose
    * `rules` file deploys to the project's default instance, or an array whose
@@ -35,6 +37,41 @@ export interface FirebaseJson {
   storage?: { rules?: string; bucket?: string } | Array<{ rules?: string; bucket?: string }>;
 }
 
+/** The single-object `firestore` form. */
+export interface FirestoreConfig {
+  rules?: string;
+  indexes?: string;
+  /** The database the object deploys to. Defaults to `(default)`. */
+  database?: string;
+}
+
+/** One entry of the array `firestore` form. */
+export interface FirestoreConfigEntry extends FirestoreConfig {
+  /** A deploy target that `.firebaserc` maps to database ids. Wins over `database`. */
+  target?: string;
+  /**
+   * Pyric's own key, never in a `firebase.json`: the rules file a Vite or
+   * `pyric.config` override serves on `(default)`. See `withDefaultFirestoreRules`.
+   */
+  pyricRulesOverride?: string;
+}
+
+/**
+ * `firestore` with `rules` served on `(default)` in place of what it names
+ * there. An object gets the `rules` key. An array gets a
+ * `{ pyricRulesOverride: rules }` entry, which `firestoreRulesConfig` applies
+ * after it resolves the array, so the override reaches `(default)` however
+ * the array deploys to it, through `database` or a `.firebaserc` target.
+ */
+export function withDefaultFirestoreRules(
+  firestore: FirebaseJson['firestore'],
+  rules: string,
+): FirestoreConfig | FirestoreConfigEntry[] {
+  if (!Array.isArray(firestore)) return { ...firestore, rules };
+  const entries = firestore.filter((entry) => entry.pyricRulesOverride === undefined);
+  return [...entries, { pyricRulesOverride: rules }];
+}
+
 /** The single-object `database` form: `rules` deploys to the default instance. */
 export interface DatabaseRulesConfig {
   rules?: string;
@@ -63,8 +100,9 @@ export interface FirebaseRc {
   /**
    * Deploy-target maps, keyed project → resource type → target name →
    * resource ids (mirrors firebase-tools' RCData,
-   * clones/firebase-tools/src/rc.ts:28-36). `hosting` (target → site ids)
-   * and `database` (target → instance names) are consumed.
+   * clones/firebase-tools/src/rc.ts:28-36). `hosting` (target → site ids),
+   * `database` (target → instance names) and `firestore` (target → database
+   * ids) are consumed.
    */
   targets?: {
     [projectId: string]: {

package/src/cli/firestore-indexes.ts

@@ -6,6 +6,7 @@ import {
 } from 'pyric/rules/internal/extract';
 import type { ParsedArgs } from './parse-args.js';
 import { readFirebaseJson, type FirebaseJson } from './firebase-json.js';
+import { defaultFirestoreDatabase, firestoreRulesConfig } from 'pyric/sandbox/internal';
 
 type ExtractResult = ReturnType<ExtractFirestoreIndexesHandler['execute']>;
 
@@ -46,7 +47,7 @@ export async function runFirestoreIndexesGenerate(
   let configuredPath: string | undefined;
   if (typeof outFlag !== 'string') {
     try {
-      configuredPath = (await (deps.readFirebaseJson ?? readFirebaseJson)(cwd)).firestore?.indexes;
+      configuredPath = defaultFirestoreDatabase(firestoreRulesConfig((await (deps.readFirebaseJson ?? readFirebaseJson)(cwd)).firestore))?.indexesFile;
     } catch {
       configuredPath = undefined;
     }

package/src/cli/index.ts

@@ -40,14 +40,38 @@
 import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { parseArgs, type ParsedArgs } from './parse-args.js';
-import { runInit, runVendor } from './init.js';
-import { runSnapshot } from './snapshot.js';
-import { runVerify } from './verify.js';
-import { runMcpProxy } from './mcp-proxy.js';
 import { pyricVersion } from '../serve/standalone-assets.js';
 import { cliVersion } from '../pkg-version.js';
 import { FIREBASE_TESTED_AGAINST } from '../version/compat-target.js';
-import { dispatchServiceCommand } from './service-commands.js';
+
+// Each command's module is imported when that command runs, never at startup.
+// The service commands alone load about 500 modules, the TypeScript compiler
+// among them, which made every `pyric run` spend about 0.5 s at idle (over 3 s
+// on a loaded CI runner) before its first request (#1671).
+
+/**
+ * The commands this dispatcher runs itself that no service command starts
+ * with, so they skip loading the service command registry. `sandbox` is not
+ * here: `pyric sandbox inspect` is a service command.
+ */
+export const COMMANDS_BEFORE_SERVICES: ReadonlySet<string> = new Set([
+  'bridge',
+  'run',
+  'snapshot',
+  'verify',
+  'can-i-use',
+  'mcp',
+  'init',
+  'vendor',
+]);
+
+async function dispatchServiceCommand(parsed: ParsedArgs): Promise<number | null> {
+  const subcommand = parsed.subcommand;
+  const skipsServices = subcommand == null || COMMANDS_BEFORE_SERVICES.has(subcommand);
+  if (skipsServices) return null;
+  const services = await import('./service-commands.js');
+  return services.dispatchServiceCommand(parsed);
+}
 
 // The standalone binary bakes the real `pyric` version onto the embedded-assets
 // global; the npm bin has no such global and falls back to '0.0.0'.
@@ -86,7 +110,9 @@ USAGE
   pyric --version
 
 COMMANDS
-  bridge                     Start the HTTP+WebSocket bridge external MCP clients point at.
+  bridge                     Start an HTTP MCP server with the rules, conformance, identity
+                             and capture tools. It has no browser socket: for an agent
+                             that drives the sandbox in a page, run \`pyric sandbox --bridge\`.
   sandbox [command...]       Run an application command or script inside the local Firebase sandbox
                              with unmodified firebase/* and firebase-admin/* imports routed to the
                              in-memory mirror. When [command...] is omitted, runs the command
@@ -94,9 +120,12 @@ COMMANDS
                              A firebase.json Functions source is discovered automatically;
                              supported RTDB onValueCreated exports run in isolated Node.
   run [--sandbox URL]        Run a command against a sandbox host that is already
-                             running (a Vite dev server with the pyric plugin, or
-                             \`pyric sandbox\`), with the environment \`pyric sandbox\`
-                             gives its child. --sandbox URL names the host; without
+                             running, with the environment \`pyric sandbox\` gives
+                             its child. The host is \`pyric sandbox --hosted\`, or a
+                             Vite dev server with \`pyric({ hosted: true })\` in
+                             vite.config.ts. A Vite server with the in-page
+                             \`pyric()\` plugin has no host, so pyric run refuses it.
+                             --sandbox URL names the host; without
                              it, PYRIC_SANDBOX=remote:<url>, then .pyric/serve.json.
                              The register module is passed by absolute file URL, so
                              the command can run outside pyric's install tree.
@@ -361,11 +390,12 @@ async function runBridge(parsed: ParsedArgs): Promise<number> {
       `  project: ${handle.bridge.project}\n` +
       `  health:  ${handle.url}/health\n` +
       `  mcp:     ${handle.url}/mcp\n` +
-      `  sandbox: ${handle.url.replace('http://', 'ws://')}/sandbox\n` +
       (handle.auditLogPath ? `  audit:   ${handle.auditLogPath}\n` : '') +
       `\nRegister with Claude Code:\n` +
       `  claude mcp add --transport http pyric ${handle.url}/mcp --scope project\n` +
-      `\nBridge will log peer connect/disconnect to stderr. Set PYRIC_VERBOSE=1 for per-tool-call logs.\n` +
+      `\nThis bridge serves the tools that run in this process. A browser page cannot attach to it;\n` +
+      `for an agent that drives the sandbox in a page, run \`pyric sandbox --bridge\`.\n` +
+      `Set PYRIC_VERBOSE=1 for per-tool-call logs.\n` +
       `Press Ctrl-C to stop.\n`,
   );
 
@@ -415,17 +445,22 @@ export async function dispatch(parsed: ParsedArgs): Promise<number> {
       const { runRun } = await import('./run.js');
       return runRun(parsed);
     case 'snapshot':
+      const { runSnapshot } = await import('./snapshot.js');
       return await runSnapshot(parsed);
     case 'verify':
+      const { runVerify } = await import('./verify.js');
       return await runVerify(parsed);
     case 'can-i-use':
       const { runCanIUse } = await import('./can-i-use.js');
       return runCanIUse(parsed);
     case 'mcp':
+      const { runMcpProxy } = await import('./mcp-proxy.js');
       return await runMcpProxy(parsed);
     case 'init':
+      const { runInit } = await import('./init.js');
       return await runInit(parsed);
     case 'vendor':
+      const { runVendor } = await import('./init.js');
       return await runVendor(parsed);
     default:
       process.stderr.write(

package/src/cli/public-dir-hint.ts

@@ -0,0 +1,35 @@
+/**
+ * The hint `pyric sandbox` adds when `hosting.public` does not exist.
+ *
+ * A missing `dist/` almost always means "no build yet": the web scaffold's
+ * hosting.public is the Vite output, so the hint points at the dev and build
+ * loop. With `--hosted` in a Vite project the user wants the Node host for a
+ * Vite app, and that runs inside Vite's dev server with `pyric({ hosted: true })`
+ * (#1423); `pyric sandbox` only serves a built directory.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const VITE_CONFIG_FILES = ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs', 'vite.config.cts', 'vite.config.cjs'];
+
+/** The Vite config file in `cwd`, or `null` when the project has none. */
+export function viteConfigIn(cwd: string): string | null {
+  return VITE_CONFIG_FILES.find((file) => existsSync(join(cwd, file))) ?? null;
+}
+
+/** The text to append to the missing-directory error, starting with a newline, or `''`. */
+export function missingPublicDirHint(publicDir: string, opts: { cwd: string; hosted: boolean }): string {
+  const viteConfig = opts.hosted ? viteConfigIn(opts.cwd) : null;
+  if (viteConfig !== null) {
+    return (
+      `\n  For a Vite app, the Node host runs in the Vite dev server: set pyric({ hosted: true }) in ${viteConfig}, ` +
+      'then start Vite on its own, without pyric sandbox.'
+    );
+  }
+  const looksLikeBuildOutput = /(^|[\\/])(dist|build|out)$/.test(publicDir);
+  if (!looksLikeBuildOutput) return '';
+  return (
+    `\n  No build yet? Run \`bun run dev\` for the live sandbox dev server, ` +
+    `or \`bun run build\` then \`pyric sandbox\` to preview the production build.`
+  );
+}

package/src/cli/run.ts

@@ -1,7 +1,7 @@
 /**
  * `pyric run [--sandbox <url>] -- <command...>`: run one command against a
- * sandbox host that is already running, such as a Vite dev server with the
- * pyric plugin or a `pyric sandbox` in another terminal.
+ * sandbox host that is already running, such as a Vite dev server with
+ * `pyric({ hosted: true })` or a `pyric sandbox --hosted` in another terminal.
  *
  * The child gets the environment `pyric sandbox` gives its own child
  * (`buildChildEnv`): the activator, the host's identity, and `--import` with
@@ -16,7 +16,8 @@ import {
   spawnSandboxChild,
   type SandboxChildPlan,
 } from './sandbox-runner.js';
-import { discoverServe, probeHostUrl } from '../serve/discovery.js';
+import { discoverServe, probeHostUrlAnswer, servesViteClient } from '../serve/discovery.js';
+import { viteConfigIn } from './public-dir-hint.js';
 
 export interface RunInvocation {
   /** The host URL named by `--sandbox` or `PYRIC_SANDBOX=remote:<url>`; null to discover it. */
@@ -92,6 +93,24 @@ export async function pollUntil<T>(
   }
 }
 
+/**
+ * The refusal for a URL that answers but is not a sandbox host (#1568). A Vite
+ * dev server whose plugin is in-page, `pyric()` with no `hosted`, is the
+ * common one: it has no sandbox host, and `hosted: true` gives it one.
+ */
+export function notAHostMessage(hostUrl: string, isVite: boolean, viteConfig: string): string {
+  if (isVite) {
+    return (
+      `pyric run: reached a Vite server without a hosted pyric sandbox at ${hostUrl}, so it can't run this command.\n` +
+      `  Set pyric({ hosted: true }) in ${viteConfig}, restart Vite, then run this command again.\n`
+    );
+  }
+  return (
+    `pyric run: ${hostUrl} answers, but it is not a sandbox host: /__pyric/health did not return a health reply.\n` +
+    `  Start a host with pyric sandbox --hosted, or for a Vite dev server set pyric({ hosted: true }) in ${viteConfig}.\n`
+  );
+}
+
 export async function runRun(parsed: ParsedArgs): Promise<number> {
   const invocation = parseRunInvocation(parsed, process.env);
   if (typeof invocation === 'string') {
@@ -103,14 +122,23 @@ export async function runRun(parsed: ParsedArgs): Promise<number> {
   let instanceId: string | null;
   if (invocation.hostUrl !== null) {
     const hostUrl = invocation.hostUrl;
-    const host = await pollUntil(() => probeHostUrl(hostUrl), { timeoutMs: invocation.waitMs });
-    if (host === null) {
+    // A server that answers but is not a sandbox host will not become one, so only silence is waited out.
+    const answer = await pollUntil(async () => {
+      const probed = await probeHostUrlAnswer(hostUrl);
+      return probed.kind === 'no-answer' ? null : probed;
+    }, { timeoutMs: invocation.waitMs });
+    if (answer === null) {
       const waited = invocation.waitMs > 0 ? ` after waiting ${invocation.waitMs / 1000}s` : '';
       process.stderr.write(`pyric run: no sandbox host answers at ${hostUrl}/__pyric/health${waited}.\n`);
       return 2;
     }
-    serveUrl = host.base;
-    instanceId = host.instanceId;
+    if (answer.kind === 'not-a-host') {
+      const viteConfig = viteConfigIn(cwd) ?? 'vite.config.ts';
+      process.stderr.write(notAHostMessage(hostUrl, await servesViteClient(answer.base), viteConfig));
+      return 2;
+    }
+    serveUrl = answer.host.base;
+    instanceId = answer.host.instanceId;
   } else {
     const log = (line: string): void => void process.stderr.write(`pyric run: ${line}\n`);
     const host = await pollUntil(() => discoverServe(cwd, log), { timeoutMs: invocation.waitMs });

package/src/cli/sandbox-runner.ts

@@ -18,6 +18,7 @@
  */
 import { spawn, type ChildProcess } from 'node:child_process';
 import { SHELL_OPERATORS } from './unsupported-runtime.js';
+import { boundedFetch } from '../bounded-request.js';
 import type { WorkerInitPayload } from '../serve/init-payload.js';
 
 // ─── First-run race guard ───────────────────────────────────────────────────
@@ -44,12 +45,19 @@ export async function waitForSandboxPeer(
 ): Promise<boolean> {
   const timeoutMs = opts.timeoutMs ?? 30_000;
   const intervalMs = opts.intervalMs ?? 250;
-  const fetchImpl = opts.fetchImpl ?? fetch;
   const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const deadline = Date.now() + timeoutMs;
+  // By default each poll is bounded by the time left, connect included, so a
+  // health port whose connect never completes cannot carry the wait past its
+  // timeout or hold the process open after it (#1167).
+  const fetchHealth = (url: string): Promise<Response> => {
+    const injected = opts.fetchImpl;
+    if (injected) return injected(url);
+    return boundedFetch(url, { deadlineMs: Math.max(1, deadline - Date.now()) });
+  };
   for (;;) {
     try {
-      const res = await fetchImpl(`${serveUrl.replace(/\/$/, '')}/__pyric/health`);
+      const res = await fetchHealth(`${serveUrl.replace(/\/$/, '')}/__pyric/health`);
       if (res.ok) {
         const health = (await res.json()) as { sandboxConnected?: boolean };
         if (health.sandboxConnected === true) return true;

package/src/cli/serve-diagnostics.ts

@@ -1,7 +1,11 @@
 import type { ParsedArgs } from './parse-args.js';
+import { boundedFetch } from '../bounded-request.js';
 import { discoverServe } from '../serve/discovery.js';
 import { DIAGNOSTICS_PATH } from '../serve/runtime/diagnostics-report.js';
 
+/** Milliseconds the diagnostics request has, connect and body included. */
+const DIAGNOSTICS_DEADLINE_MS = 3000;
+
 export async function runServeDiagnostics(parsed: ParsedArgs, deps: {
   cwd?: string;
   stdout?: { write(value: string): void };
@@ -27,7 +31,14 @@ export async function runServeDiagnostics(parsed: ParsedArgs, deps: {
   }
   let reachedServer = false;
   try {
-    const response = await fetch(endpoint, { signal: AbortSignal.timeout(3000), redirect: 'error' });
+    // Bounded, connect included, so a port whose connect never completes
+    // cannot hold the command open past its answer (#1167). The report is
+    // read whole within the deadline, as fetch's abort covered the body too.
+    const response = await boundedFetch(endpoint, {
+      deadlineMs: DIAGNOSTICS_DEADLINE_MS,
+      maxBytes: Number.POSITIVE_INFINITY,
+      redirect: 'error',
+    });
     reachedServer = true;
     if (!response.ok) {
       print({ version: 1, server: { http: 'responding', status: response.status }, error: 'Diagnostics endpoint unavailable. Check the URL and CLI version.' });