V48 (impl-only): Force sandbox host on serverless; LocalHost is local-only

Serverless (VERCEL=1 / VERCEL_ENV / Lambda) always selects sandbox for deposit
synthesis, even if BITCODE_PIPELINE_HOST=local is mis-set. LocalHost remains
the default only on developer machines. Docs and tests match the host law.

Author: geraldarthurdavis

packages/pipeline-image/README.md

@@ -15,9 +15,19 @@ stock `node24` runtime that cannot install the monorepo on every run.
 | `/opt/bitcode/.bitcode/pipeline-host/*.mjs` | Host-smoke + live runners (`../../packages` resolves) |
 | `/vercel/sandbox` | Customer git checkout + run manifest/artifacts |
 
+## Host law
+
+| Runtime | Host |
+|---------|------|
+| **Local machine** (laptop, full FS) | **LocalHost** by default — optional `BITCODE_PIPELINE_HOST=sandbox` to exercise boxes |
+| **Serverless** (Vercel Production/Preview) | **Always sandbox** — LocalHost is never used (`VERCEL=1` forces sandbox) |
+
+LocalHost cannot run deposit/read pipelines on serverless. Serverless always spawns a Sandbox microVM; prefer a VCR pipeline image for cold-start cost.
+
 ## Env (Production)
 
 ```bash
+# Host is auto-sandbox on Vercel; still fine to set explicitly:
 BITCODE_PIPELINE_HOST=sandbox
 BITCODE_PIPELINE_SANDBOX_IMAGE=bitcode-pipeline:v48-<gitsha>
 # or full ref:

uapi/.env.example

@@ -33,11 +33,14 @@ XAI_API_KEY=<your xAI API key>
 BITCODE_ASSET_PACK_REAL_INFERENCE=false
 BITCODE_ASSET_PACK_REAL_INFERENCE_PROFILE=bounded
 BITCODE_ENABLE_PIPELINE_HOST_API=false
-# Pipeline Host: local = LocalHost (in-process; use while debugging locally)
-# sandbox = VercelSandboxHost (prod/staging box dispatch)
+# Pipeline Host:
+# - Local machine: default LocalHost (BITCODE_PIPELINE_HOST=local or unset).
+#   Optional sandbox from laptop: BITCODE_PIPELINE_HOST=sandbox (needs Vercel auth).
+# - Serverless (Vercel Production/Preview): always sandbox — LocalHost is never used.
+#   VERCEL=1 forces sandbox even if BITCODE_PIPELINE_HOST=local is mis-set.
 BITCODE_PIPELINE_HOST=local
 BITCODE_PIPELINE_HOST_MAX_RUNTIME_MS=600000
-# VCR pipeline appliance (when set, Sandbox.create uses image, not stock runtime):
+# VCR pipeline appliance (Production sandbox image; Sandbox.create({ image })):
 # BITCODE_PIPELINE_SANDBOX_IMAGE=bitcode-pipeline:v48-<sha>
 # BITCODE_PIPELINE_IMAGE_ENTRY=/opt/bitcode/pipeline/run-pipeline.mjs
 

uapi/lib/deposit-source-provisioning.ts

@@ -7,9 +7,15 @@
  * already has the tree (e.g. VercelSandboxHost image source), adopt it;
  * otherwise LocalHost clones via `deposit:cloneRepositoryForRun`.
  *
- * LocalHost only reads files from the workspace cloned for that run.
+ * Host law:
+ * - **LocalHost** — developer machine only (full system access). Never on
+ *   serverless/Production. Used when iterating locally with the monorepo on disk.
+ * - **Sandbox (VercelSandboxHost)** — always on serverless (Vercel / Lambda).
+ *   Synthesis spawns a microVM; optional VCR pipeline image via
+ *   `BITCODE_PIPELINE_SANDBOX_IMAGE`.
  *
- * Host selection: `BITCODE_PIPELINE_HOST` (`local` | `sandbox`).
+ * Host selection: `BITCODE_PIPELINE_HOST` (`local` | `sandbox`); serverless
+ * runtimes always resolve to `sandbox` even if `local` is misconfigured.
  */
 
 import {
@@ -60,18 +66,40 @@ export interface ProvisionedDepositCheckout {
 }
 
 /**
- * Select the deposit HostKind by CONFIGURATION (not environment): `BITCODE_PIPELINE_HOST`
- * (`local` | `sandbox`; `inline` = alias of `local`) chooses which HostKind runs the synthesis pipeline; default
- * `local`. (A SandboxHost's provider is `BITCODE_SANDBOX_PROVIDER`, `vercel` | `aws`.)
- * Pure + testable; no dev/prod or local/remote semantics.
+ * True when the process is a deployed serverless runtime (not a laptop dev server).
+ * Vercel sets `VERCEL=1` / `VERCEL_ENV` on Production and Preview functions.
+ */
+export function isServerlessPipelineRuntime(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (env.BITCODE_PIPELINE_RUNTIME?.trim().toLowerCase() === 'serverless') {
+    return true;
+  }
+  if (env.VERCEL === '1') return true;
+  if (env.VERCEL_ENV === 'production' || env.VERCEL_ENV === 'preview') return true;
+  if (env.AWS_LAMBDA_FUNCTION_NAME) return true;
+  return false;
+}
+
+/**
+ * Select deposit HostKind.
+ *
+ * - **Serverless:** always `sandbox` (LocalHost cannot run pipelines on Vercel).
+ *   Explicit `BITCODE_PIPELINE_HOST=local` is ignored on serverless.
+ * - **Local machine:** default `local` (LocalHost); set `BITCODE_PIPELINE_HOST=sandbox`
+ *   to exercise the sandbox path from a laptop (needs Vercel auth).
+ * - `inline` is a deprecated alias of `local`.
  */
 export function selectDepositHostKind(
   env: NodeJS.ProcessEnv = process.env,
 ): BitcodeHostKind {
+  if (isServerlessPipelineRuntime(env)) {
+    return 'sandbox';
+  }
   const explicit = env.BITCODE_PIPELINE_HOST?.trim().toLowerCase();
-  if (explicit === "sandbox") return "sandbox";
-  // `inline` is a deprecated alias of `local` (LocalHost, formerly LocalHost).
-  return "local";
+  if (explicit === 'sandbox') return 'sandbox';
+  // local | inline | unset → LocalHost on developer machines only
+  return 'local';
 }
 
 /**

uapi/tests/lib/depositSourceProvisioning.test.ts

@@ -138,13 +138,25 @@ describe('provisionDepositSourceInventory (compat full catalog load)', () => {
 });
 
 describe('selectDepositHostKind', () => {
-  it('selects by configured BITCODE_PIPELINE_HOST (default local; env does not auto-select)', () => {
+  it('uses LocalHost only on local machines; serverless always sandbox', () => {
+    // Local machine (no Vercel/Lambda markers)
     expect(selectDepositHostKind({ BITCODE_PIPELINE_HOST: 'sandbox' } as any)).toBe('sandbox');
     expect(selectDepositHostKind({ BITCODE_PIPELINE_HOST: ' Sandbox ' } as any)).toBe('sandbox');
     expect(selectDepositHostKind({ BITCODE_PIPELINE_HOST: 'local' } as any)).toBe('local');
     expect(selectDepositHostKind({ BITCODE_PIPELINE_HOST: 'inline' } as any)).toBe('local');
     expect(selectDepositHostKind({} as any)).toBe('local');
-    expect(selectDepositHostKind({ VERCEL: '1' } as any)).toBe('local');
+
+    // Serverless: always sandbox — LocalHost is never valid here
+    expect(selectDepositHostKind({ VERCEL: '1' } as any)).toBe('sandbox');
+    expect(selectDepositHostKind({ VERCEL: '1', BITCODE_PIPELINE_HOST: 'local' } as any)).toBe(
+      'sandbox',
+    );
+    expect(selectDepositHostKind({ VERCEL_ENV: 'production' } as any)).toBe('sandbox');
+    expect(selectDepositHostKind({ VERCEL_ENV: 'preview' } as any)).toBe('sandbox');
+    expect(selectDepositHostKind({ AWS_LAMBDA_FUNCTION_NAME: 'fn' } as any)).toBe('sandbox');
+    expect(
+      selectDepositHostKind({ BITCODE_PIPELINE_RUNTIME: 'serverless' } as any),
+    ).toBe('sandbox');
   });
 });