V48 (impl-only): Host law — Setup in-box clone, no Sandbox.create git source

Deposit on serverless creates the Pipeliner image only (no create-time customer
git source). Clone specs pass via BITCODE_HOST_CLONE_* env; Setup multi-step
clones inside the box (branch shallow + pin commit). Shared provisionGitWorkingTree
backs LocalHost and Setup. Telemetry: cloneLocation=setup-in-box. Requires
Pipeliner image rebuild for Setup agent package changes.

Author: geraldarthurdavis

packages/asset-packs-pipelines/domain/package.json

@@ -69,7 +69,8 @@
     "@bitcode/generic-measurements-absolutes": "workspace:*",
     "@bitcode/generic-measurements-needinesses": "workspace:*",
     "@bitcode/asset-packs-generics": "workspace:*",
-    "@bitcode/generic-asset-packs-synthesis": "workspace:*"
+    "@bitcode/generic-asset-packs-synthesis": "workspace:*",
+    "@bitcode/host-generics": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

packages/asset-packs-pipelines/domain/src/agents/setup/asset-pack-clone-vcs-repository-agent.ts

@@ -2,20 +2,29 @@
  * AssetPack Pipeline - Clone VCS Repository Agent (Setup).
  *
  * Pipeline executions always run on a **Host** (LocalHost, VercelSandboxHost, …).
- * Cloning is a Setup responsibility only — never pre-pipeline initialization.
+ * Cloning is a Setup responsibility only — never pre-pipeline initialization,
+ * never inside a serverless function process, and not via Sandbox.create git
+ * source (that is outside the pipeline).
  *
  * For this pipeline run the agent ensures a **complete working tree at the
  * requested SHA/ref** (all files; shallow history is fine):
- * 1. If the Host already has the repository for this run (e.g. VercelSandboxHost
- *    provisioned the git source on the Host image), adopt that checkout.
- * 2. Else if the Host wired `deposit:cloneRepositoryForRun` (LocalHost deposit),
+ * 1. If the Host wired `deposit:cloneRepositoryForRun` (LocalHost deposit),
  *    clone into an ephemeral Host workspace for this run only.
- * 3. Else clone via the Setup VCS clone tool on the Host.
+ * 2. Else if `BITCODE_HOST_CLONE_*` env is set (sandbox deposit: create with
+ *    image only + clone specs in env), multi-step git clone **inside the box**.
+ * 3. Else if the Host already has a real checkout for this run (`.git` present
+ *    or explicit workspace path), adopt that tree.
+ * 4. Else clone via the Setup VCS clone tool on the Host.
  *
  * LocalHost never reads paths outside the workspace cloned for this run.
  * Discovery builds the source catalog from that same tree (not a second clone).
  */
 
+import { execFile } from 'node:child_process';
+import { existsSync, statSync, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
 import { factoryPTRRAgent } from '@bitcode/agent-generics';
 import { Prompt } from '@bitcode/prompts/prompt';
 import {
@@ -25,6 +34,11 @@ import {
   VCS_REFINE_PROMPT,
   VCS_RETRY_PROMPT,
 } from '@bitcode/generic-agents-vcs';
+import {
+  provisionGitWorkingTree,
+  readHostCloneEnv,
+  type HostExec,
+} from '@bitcode/host-generics';
 import {
   DP_CLONE_VCS_SYSTEM_PROMPT,
   DP_CLONE_VCS_PLAN_PROMPT,
@@ -162,8 +176,9 @@ function normalizeRepositoryInput(input: any, execution: any): {
 }
 
 /**
- * True when the Host already has this run's repository working tree available
- * (VercelSandboxHost image source, explicit Host workspace path, etc.).
+ * True when the Host already has this run's repository working tree available.
+ * Must be a real checkout — never treat bare `sourceRevision` metadata as proof
+ * the customer tree is on disk (that falsely adopted empty sandbox CWD).
  */
 function resolveHostAvailableWorkspace(
   input: any,
@@ -179,26 +194,128 @@ function resolveHostAvailableWorkspace(
     return { workspacePath: explicitPath, availability: 'host-workspace-path' };
   }
 
-  // Host plan already provisioned git source on the Host image for this run
-  // (VercelSandboxHost and similar). sourceRevision is stored on the Host context.
-  const hostSourceRevision = resolveHostSourceRevision(input, execution);
-  const hostContext =
-    input?.host ??
-    findExecutionValue(execution, 'host', 'manifest') ??
-    findExecutionValue(execution, 'host', 'hostKind');
-  if (hostSourceRevision && hostContext != null) {
-    // Working tree root on the Host image for this pipeline process.
-    return { workspacePath: process.cwd(), availability: 'host-image-source' };
-  }
-  // sourceRevision alone (from Host runner input) without LocalHost cloner:
-  // Host already placed the tree for in-box execution.
-  if (hostSourceRevision && !findExecutionValue(execution, 'deposit', DEPOSIT_CLONE_REPOSITORY_FOR_RUN_KEY)) {
-    return { workspacePath: process.cwd(), availability: 'host-image-source' };
+  // Legacy create-time git source: only adopt CWD when a real .git exists.
+  // (New deposit path uses BITCODE_HOST_CLONE_* + Setup multi-step clone.)
+  const cwd = process.cwd();
+  if (existsSync(path.join(cwd, '.git'))) {
+    return { workspacePath: cwd, availability: 'host-cwd-git-present' };
   }
 
   return null;
 }
 
+function defaultSetupHostExec(): HostExec {
+  return (cmd, args, opts) =>
+    new Promise((resolve) => {
+      execFile(
+        cmd,
+        args,
+        {
+          cwd: opts?.cwd,
+          env: opts?.env ? { ...process.env, ...opts.env } : process.env,
+          maxBuffer: 64 * 1024 * 1024,
+        },
+        (error, stdout, stderr) => {
+          const code =
+            error && typeof (error as NodeJS.ErrnoException & { code?: unknown }).code === 'number'
+              ? (error as unknown as { code: number }).code
+              : error
+                ? 1
+                : 0;
+          resolve({
+            exitCode: code,
+            stdout: stdout?.toString() ?? '',
+            stderr: stderr?.toString() ?? '',
+          });
+        },
+      );
+    });
+}
+
+function slugRepo(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'repo';
+}
+
+/**
+ * Setup in-box clone using BITCODE_HOST_CLONE_* env (sandbox deposit law path).
+ * Multi-step git — not Vercel Sandbox.create source.
+ */
+async function cloneFromHostEnvForRun(execution: any): Promise<{
+  workspacePath: string;
+  listFiles: () => Promise<string[]>;
+  readFile: (p: string) => Promise<string | null>;
+  strategy: string;
+} | null> {
+  const spec = readHostCloneEnv();
+  if (!spec) return null;
+
+  const repoName = spec.repositoryFullName || 'customer/repo';
+  const root =
+    spec.root ||
+    process.env.BITCODE_PIPELINE_HOST_ARTIFACT_DIR?.replace(/\/\.bitcode\/pipeline-host\/?$/, '') ||
+    (existsDir('/vercel/sandbox') ? '/vercel/sandbox' : os.tmpdir());
+  const workspacePath = path.join(
+    root,
+    `customer-source-${slugRepo(repoName)}-${Date.now().toString(36)}`,
+  );
+
+  log('[setup/clone] in-box host-env clone starting', 'info', {
+    repository: repoName,
+    branch: spec.branch,
+    commit: spec.commit ? `${spec.commit.slice(0, 12)}…` : null,
+    hasToken: Boolean(spec.password),
+    root,
+  });
+
+  const exec = defaultSetupHostExec();
+  const result = await provisionGitWorkingTree({
+    url: spec.url,
+    username: spec.username,
+    password: spec.password,
+    branch: spec.branch,
+    commit: spec.commit,
+    revision: spec.commit || spec.branch || 'HEAD',
+    workspacePath,
+    exec,
+  });
+
+  log('[setup/clone] in-box host-env clone complete', 'info', {
+    strategy: result.strategy,
+    workspacePath: result.workspacePath,
+  });
+
+  return {
+    workspacePath: result.workspacePath,
+    strategy: result.strategy,
+    listFiles: async () => {
+      const listed = await exec('git', ['-C', result.workspacePath, 'ls-files']);
+      if (listed.exitCode !== 0) return [];
+      return listed.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    },
+    readFile: async (relativePath: string) => {
+      const absRoot = path.resolve(result.workspacePath);
+      const absolute = path.resolve(result.workspacePath, relativePath);
+      if (absolute !== absRoot && !absolute.startsWith(absRoot + path.sep)) return null;
+      try {
+        return await fs.readFile(absolute, 'utf8');
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+function existsDir(dirPath: string): boolean {
+  try {
+    return existsSync(dirPath) && statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 function presentCheckoutResult(
   normalized: NonNullable<ReturnType<typeof normalizeRepositoryInput>>,
   workspacePath: string,
@@ -351,27 +468,44 @@ export default async function runAssetPackCloneVCSRepositoryAgent(input: any, ex
       'localhost-clone-for-run',
     );
   } else if (normalized) {
-    // 2) Host already has the repository for this run (e.g. VercelSandboxHost image).
-    const hostAvailable = resolveHostAvailableWorkspace(input, execution);
-    if (hostAvailable) {
+    // 2) Sandbox deposit: clone customer repo inside the box from host env
+    //    (Sandbox.create had image only — no create-time git source).
+    const hostEnvClone = await cloneFromHostEnvForRun(execution);
+    if (hostEnvClone) {
+      await recordDepositCatalogFromRunWorkspace(execution, hostEnvClone);
       out = presentCheckoutResult(
         normalized,
-        hostAvailable.workspacePath,
-        'host-source-present',
-        hostAvailable.availability,
+        hostEnvClone.workspacePath,
+        'cloned-for-run',
+        `setup-in-box-${hostEnvClone.strategy}`,
       );
     } else {
-      // 3) Clone on the Host via Setup VCS tool.
-      out = await AssetPackCloneVCSRepositoryAgent(input, execution);
-      if (out && typeof out === 'object') {
-        out = {
-          ...out,
-          metadata: {
-            ...(out.metadata || {}),
-            workingTree: 'complete-at-revision',
-            hostProvision: 'setup-clone-on-host',
-          },
-        };
+      // 3) Host already has a real checkout for this run.
+      const hostAvailable = resolveHostAvailableWorkspace(input, execution);
+      if (hostAvailable) {
+        out = presentCheckoutResult(
+          normalized,
+          hostAvailable.workspacePath,
+          'host-source-present',
+          hostAvailable.availability,
+        );
+      } else {
+        // 4) Clone on the Host via Setup VCS tool.
+        log('[setup/clone] falling back to Setup VCS clone tool', 'info', {
+          hasNormalized: Boolean(normalized),
+          hasHostCloneEnv: Boolean(readHostCloneEnv()),
+        });
+        out = await AssetPackCloneVCSRepositoryAgent(input, execution);
+        if (out && typeof out === 'object') {
+          out = {
+            ...out,
+            metadata: {
+              ...(out.metadata || {}),
+              workingTree: 'complete-at-revision',
+              hostProvision: 'setup-clone-on-host',
+            },
+          };
+        }
       }
     }
   } else {

packages/generic-hosts/Local/src/__tests__/local-host.test.ts

@@ -86,6 +86,20 @@ describe('LocalHost (primitive Host implementation)', () => {
     await expect(fs.stat(ws.workspacePath)).rejects.toBeDefined(); // removed
   });
 
+  it('prefers branch --branch for shallow clone when branch is provided', async () => {
+    const { exec, calls } = fakeExec();
+    const host = new LocalHost({ exec, rootDir: await makeRoot() });
+    await host.provisionRepository({
+      repositoryFullName: 'o/r',
+      url: 'https://github.com/o/r.git',
+      revision: 'abc1234',
+      branch: 'version/v48',
+      commit: 'abc1234',
+    });
+    const cloneCall = calls.find((c) => c[0] === 'git' && c[1] === 'clone');
+    expect(cloneCall).toEqual(expect.arrayContaining(['--branch', 'version/v48']));
+  });
+
   it('readFile refuses path traversal outside the checkout', async () => {
     const host = new LocalHost({ exec: fakeExec().exec, rootDir: await makeRoot() });
     const ws = await host.provisionRepository({
@@ -131,7 +145,7 @@ describe('LocalHost (primitive Host implementation)', () => {
         revision: 'main',
         password: 'ghs_secrettoken',
       }),
-    ).rejects.toThrow(/LocalHost git clone failed/);
+    ).rejects.toThrow(/Host git clone failed/);
 
     const cloneCall = calls.find((c) => c[1] === 'clone')!;
     // cloneArgs: clone --depth 1 --single-branch [--branch rev] <url> <dest>