fix(agent): start mobile previews through trusted launcher (#219)

## Why

Production mobile app-builder runs repeatedly failed before the model
could edit the scaffold. Cloudflare Workflow history showed the exact
error: `pnpm must be passed as direct command argv.` The app-builder had
already produced a trusted native-mirror Expo launcher, but then sent it
through the generic model-command normalizer. That normalizer replaced
it with a shell-wrapped Expo self-heal command, which the sandbox
package policy correctly rejected.

## What changed

- Launch the app-builder's already-resolved Next and Expo preview
commands directly through the provider-neutral sandbox process contract.
- Preserve strict normalization and package-manager rejection for
model-supplied dev-server commands.
- Remove the redundant second project-port allocation and the now-unused
combined executor.
- Activate immutable snapshot dependencies for exact scaffold manifests;
detach them before any package mutation or non-template restore.
- Strengthen the snapshot smoke to start Expo through the immutable
runtime dependency tree and assert the mirror's dependency link.
- Document the trusted harness/model-command boundary and dependency
lifecycle.

## Architecture and migration effects

- No database or migration changes.
- The sandbox snapshot and agent Worker must be promoted together.
- Existing strict package-manager policy remains unchanged.

## Verification

- `pnpm lint`
- `pnpm typecheck`
- `pnpm turbo build --force`
- `pnpm deadcode`
- `pnpm architecture:check`
- `pnpm turbo skills:build`
- Reproduced the production failure on `trycheatcode.com` and inspected
the Cloudflare Workflow instance; every retry failed with the same
direct-argv policy error before model execution.
- Reproduced the exact production Expo launch in the active Daytona
sandbox; Metro remained healthy for the full bounded test, proving the
child runtime was not the terminal failure.

Production browser acceptance will be repeated on a new mobile project
after the immutable snapshot and Worker are promoted.

Author: iamjr15

.github/workflows/build-snapshot.yml

@@ -341,7 +341,7 @@ jobs:
             CI=1 EXPO_NO_TELEMETRY=1 NODE_PATH=/home/node/.cheatcode/app-runtimes/expo/node_modules \
               /opt/cheatcode/project-source-sync.py preview-run \
               "$expo_source" "$expo_mirror" "$expo_lock" "$expo_mirror" \
-              /home/node/cheatcode-expo-template -- \
+              /home/node/.cheatcode/app-runtimes/expo -- \
               /home/node/.cheatcode/app-runtimes/expo/node_modules/.bin/expo \
               start -c --web --host lan --port 5201 > "$expo_log" 2>&1 &
             expo_pid="$!"
@@ -354,6 +354,9 @@ jobs:
               sleep 1
               expo_attempt=$((expo_attempt + 1))
             done
+            test -L "$expo_mirror/node_modules"
+            test "$(readlink -f "$expo_mirror/node_modules")" = \
+              /home/node/.cheatcode/app-runtimes/expo/node_modules
             printf "%s\n" "mobile source synchronization works" > "$expo_source/.cheatcode-mobile-sync-smoke"
             expo_sync_attempt=0
             until test -f "$expo_mirror/.cheatcode-mobile-sync-smoke" && \

apps/agent-worker/README.md

@@ -177,9 +177,13 @@ a stale listening port. The local source,
 dependency tree, and build cache are disposable;
 wake and restart reconstruct them from the durable project without changing the Files surface.
 Persisted pnpm-backed preview commands restore a missing sandbox-local dependency tree before the
-server starts. A package/lock/config digest skips the install entirely when the local dependency tree
-is current; automatic preview restoration does not create a durable lockfile. An unchanged baked
-app-builder template continues to use the immutable runtime without an unnecessary install.
+server starts. Exact scaffold manifests link the disposable mirror to the matching immutable runtime
+dependency tree; the package boundary detaches that link before any dependency mutation. A
+package/lock/config digest skips the install entirely when a project-local dependency tree is current;
+automatic preview restoration does not create a durable lockfile.
+The app-builder harness launches its already-resolved native-mirror command directly through the
+sandbox contract. Model-supplied dev-server commands continue through framework and package-manager
+normalization; trusted harness commands are not reinterpreted as user shell input.
 The immutable sandbox exposes that synchronizer as the root-owned
 `/opt/cheatcode/project-source-sync.py` helper, keeping Worker-to-sandbox command arguments small
 and making the snapshot the source of truth for executable sandbox runtime code.

apps/agent-worker/src/durable-objects/agent-run-app-builder.ts

@@ -1,8 +1,4 @@
-import {
-  executeShellExec,
-  executeShellTerminal,
-  executeStartDevServer,
-} from "@cheatcode/agent-core/tools/code";
+import { executeShellExec, executeShellTerminal } from "@cheatcode/agent-core/tools/code";
 import {
   type AnalyticsBindings,
   APIError,
@@ -56,6 +52,9 @@ const DEFAULT_MOBILE_PORT = 8081;
 // Keep the header-free Expo Go capability short-lived. It is re-minted whenever
 // the preview wakes, so a fresh QR is available without leaving a day-long URL live.
 const SIGNED_PREVIEW_TTL_SECONDS = 60 * 60;
+const PREVIEW_KEEP_ALIVE_MS = 60 * 60 * 1_000;
+const PREVIEW_MAX_RESTARTS = 3;
+const PREVIEW_START_TIMEOUT_MS = 180_000;
 
 type AppendChunk = (chunk: UIMessageChunk) => Promise<void>;
 
@@ -510,34 +509,23 @@ async function startExpoDevServer(
   // header-free URL, and Metro must know its public host (EXPO_PACKAGER_PROXY_URL) so the manifest's
   // launchAsset/bundle URLs point at the signed host instead of 127.0.0.1 (which Expo Go can't hit).
   const signedUrl = await getSignedMetroUrl(sandbox, logger, workspace.port);
-  await executeStartDevServer(
-    {
-      // `--web` makes the single Metro dev server also serve the react-native-web
-      // build as a real web page at `/` (iframe-renderable in the Computer panel),
-      // while the SAME server keeps answering exp:// manifests for Expo Go — so we
-      // get both the in-panel preview and the QR from one process on the project port.
-      // Metro runs against the same supervised native-disk source mirror as Next. Durable
-      // workspace edits reach that mirror atomically, so Metro's native watcher hot-reloads them
-      // without the old post-run restart.
-      command: localExpoPreviewCommand({
-        port: workspace.port,
-        sourceDir: workspace.dir,
-        workspaceSlug: workspace.slug,
-      }),
-      cwd: workspace.dir,
-      env: {
-        CHEATCODE_APP_RUNTIME: "expo",
-        CI: "1",
-        EXPO_NO_TELEMETRY: "1",
-        ...(signedUrl ? { EXPO_PACKAGER_PROXY_URL: signedUrl } : {}),
-      },
-      isMobile: true,
-      name: workspace.slot,
+  // `--web` makes the single Metro dev server also serve the react-native-web build as a real page
+  // in Computer while the same process answers Expo Go manifests. This command is already the
+  // trusted native-mirror launcher, so it must not pass through model-command normalization.
+  await startManagedPreview(sandbox, workspace, {
+    command: localExpoPreviewCommand({
       port: workspace.port,
-      timeoutMs: 180_000,
+      sourceDir: workspace.dir,
+      workspaceSlug: workspace.slug,
+    }),
+    env: {
+      CHEATCODE_APP_RUNTIME: "expo",
+      CI: "1",
+      EXPO_NO_TELEMETRY: "1",
+      ...(signedUrl ? { EXPO_PACKAGER_PROXY_URL: signedUrl } : {}),
     },
-    { sandbox, workspaceDir: workspace.dir, workspaceSlug: workspace.slug },
-  );
+    shouldReuseMatchingProcess: false,
+  });
 }
 
 // Best-effort Metro bootstrap capability. It is passed only to the live process so Metro emits
@@ -566,28 +554,54 @@ async function startAppBuilderDevServer(
   sandbox: ProjectSandboxStub,
   workspace: AppBuilderWorkspace,
 ): Promise<void> {
-  await executeStartDevServer(
-    {
-      command: localNextPreviewCommand({
-        port: workspace.port,
-        sourceDir: workspace.dir,
-        workspaceSlug: workspace.slug,
-      }),
-      cwd: workspace.dir,
-      env: {
-        CHEATCODE_APP_RUNTIME: "next",
-        CHEATCODE_NEXT_DIST_DIR: "../cache/next",
-        CHOKIDAR_USEPOLLING: "true",
-        WATCHPACK_POLLING: "1000",
-      },
-      isMobile: false,
-      name: workspace.slot,
+  await startManagedPreview(sandbox, workspace, {
+    command: localNextPreviewCommand({
       port: workspace.port,
-      shouldReuseMatchingProcess: true,
-      timeoutMs: 180_000,
+      sourceDir: workspace.dir,
+      workspaceSlug: workspace.slug,
+    }),
+    env: {
+      CHEATCODE_APP_RUNTIME: "next",
+      CHEATCODE_NEXT_DIST_DIR: "../cache/next",
+      CHOKIDAR_USEPOLLING: "true",
+      WATCHPACK_POLLING: "1000",
     },
-    { sandbox, workspaceDir: workspace.dir, workspaceSlug: workspace.slug },
-  );
+    shouldReuseMatchingProcess: true,
+  });
+}
+
+interface ManagedPreviewOptions {
+  command: string[];
+  env: Record<string, string>;
+  shouldReuseMatchingProcess: boolean;
+}
+
+async function startManagedPreview(
+  sandbox: ProjectSandboxStub,
+  workspace: AppBuilderWorkspace,
+  options: ManagedPreviewOptions,
+): Promise<void> {
+  await sandbox.startProcess({
+    command: options.command,
+    cwd: workspace.dir,
+    env: {
+      ...options.env,
+      HOST: "0.0.0.0",
+      HOSTNAME: "0.0.0.0",
+      PORT: String(workspace.port),
+    },
+    isMobile: workspace.mobile,
+    keepAliveTimeoutMs: PREVIEW_KEEP_ALIVE_MS,
+    maxRestarts: PREVIEW_MAX_RESTARTS,
+    processId: workspace.slot,
+    restartOnFailure: true,
+    shouldReuseMatchingProcess: options.shouldReuseMatchingProcess,
+    timeoutMs: PREVIEW_START_TIMEOUT_MS,
+    waitForPort: {
+      port: workspace.port,
+      timeoutMs: PREVIEW_START_TIMEOUT_MS,
+    },
+  });
 }
 
 async function hasExistingAppBuilderWorkspace(

apps/agent-worker/src/durable-objects/app-builder-local-preview.ts

@@ -1,9 +1,9 @@
 import { localProjectProcessCommand } from "./project-sandbox-local-source";
 import {
   EXPO_RUNTIME_BIN,
-  EXPO_TEMPLATE_DIR,
+  EXPO_RUNTIME_DIR,
   NEXT_RUNTIME_BIN,
-  NEXT_TEMPLATE_DIR,
+  NEXT_RUNTIME_DIR,
   resolveProjectLocalRuntime,
 } from "./project-sandbox-package-runtime";
 
@@ -25,7 +25,7 @@ export function localNextPreviewCommand(input: LocalPreviewCommandInput): string
     "--port",
     String(input.port),
   ];
-  return localProjectProcessCommand(runtime, nextCommand, NEXT_TEMPLATE_DIR);
+  return localProjectProcessCommand(runtime, nextCommand, NEXT_RUNTIME_DIR);
 }
 
 /** Runs Expo/Metro from native sandbox disk while `/workspace` remains durable source. */
@@ -41,7 +41,7 @@ export function localExpoPreviewCommand(input: LocalPreviewCommandInput): string
     "--port",
     String(input.port),
   ];
-  return localProjectProcessCommand(runtime, expoCommand, EXPO_TEMPLATE_DIR);
+  return localProjectProcessCommand(runtime, expoCommand, EXPO_RUNTIME_DIR);
 }
 
 function requireLocalPreviewRuntime(input: LocalPreviewCommandInput) {

apps/agent-worker/src/durable-objects/project-sandbox-local-source.ts

@@ -35,7 +35,7 @@ export function localPackageCommand(
 export function localProjectProcessCommand(
   runtime: ProjectLocalRuntime,
   command: readonly string[],
-  dependencyTemplateDir?: string,
+  dependencyRuntimeDir?: string,
 ): string[] {
   const { lockPath } = runtimeStatePaths(runtime);
   return [
@@ -45,7 +45,7 @@ export function localProjectProcessCommand(
     runtime.localSourceDir,
     lockPath,
     runtime.localCwd,
-    dependencyTemplateDir ?? "-",
+    dependencyRuntimeDir ?? "-",
     "--",
     ...command,
   ];

apps/agent-worker/src/durable-objects/project-sandbox-package-runtime.ts

@@ -11,8 +11,10 @@ const SHELL_EXECUTABLES = new Set(["bash", "sh", "zsh"]);
 const SHELL_PACKAGE_MANAGER_COMMAND =
   /(?:^|&&|\|\||;|\n|\()\s*(?:(?:[A-Za-z_][A-Za-z0-9_]*=[^\s;&|()]+)\s+)*(?:command\s+)?(?:sudo\s+)?(?:[^\s;&|()]+\/)?(bun|bunx|npm|npx|pnpm|pnpx|yarn|yarnpkg)(?=\s|$)/u;
 
-export const NEXT_RUNTIME_BIN = `${APP_RUNTIME_ROOT}/next/node_modules/.bin/next`;
-export const EXPO_RUNTIME_BIN = `${APP_RUNTIME_ROOT}/expo/node_modules/.bin/expo`;
+export const NEXT_RUNTIME_DIR = `${APP_RUNTIME_ROOT}/next`;
+export const EXPO_RUNTIME_DIR = `${APP_RUNTIME_ROOT}/expo`;
+export const NEXT_RUNTIME_BIN = `${NEXT_RUNTIME_DIR}/node_modules/.bin/next`;
+export const EXPO_RUNTIME_BIN = `${EXPO_RUNTIME_DIR}/node_modules/.bin/expo`;
 export const NEXT_TEMPLATE_DIR = "/home/node/cheatcode-next-template";
 export const EXPO_TEMPLATE_DIR = "/home/node/cheatcode-expo-template";
 

infra/containers/sandbox/README.md

@@ -89,8 +89,11 @@ pnpm locks under `app-templates/`. Their locked packages are installed into immu
 sandbox-local runtimes in the image. Project creation copies only source and config to
 the persistent Daytona volume; dependency trees and generated compiler caches stay on
 the sandbox's local filesystem, avoiding slow, partial writes to object-store FUSE.
-Additional dependencies use a project-scoped local modules directory and can be
-restored from the reviewed package store after a sandbox replacement. Expo uses an exact
+Exact scaffold projects link their disposable native-disk mirror to the matching immutable
+runtime dependency tree, avoiding both package copies and installs during startup. The helper
+detaches that link before a package mutation or non-template restore; additional dependencies then
+use a project-scoped local modules directory and can be restored from the reviewed package store
+after a sandbox replacement. Expo uses an exact
 `expo-template-default` tarball with a reviewed SHA-256 rather than the mutable
 `default` alias. These locks prevent a snapshot rebuild from resolving a different
 dependency tree while the application source stays unchanged.
@@ -110,9 +113,10 @@ native-disk app and sync-loop children, and forwards termination signals. Transi
 from the durable FUSE source is retried during a bounded grace period without interrupting the app.
 If source access does not recover or the synchronizer otherwise exits, the managed preview exits as
 one failed process unit so its existing bounded restart policy cannot leave a healthy port backed by
-stale source. A dependency-state digest
-skips unchanged reinstalls, while projects without a durable lockfile install without creating one
-as a preview side effect. Dependency restoration temporarily merges the image's reviewed build
+stale source. Exact scaffold manifests activate the immutable runtime dependency tree, while a
+dependency-state digest skips unchanged project-local reinstalls. Projects without a durable
+lockfile install without creating one as a preview side effect. Dependency restoration temporarily
+merges the image's reviewed build
 policy into the sandbox-local workspace, currently permitting `esbuild` so Vite can install its
 platform binary while pnpm's default-deny lifecycle policy remains intact for every other package.
 The original workspace manifest is restored byte-for-byte before the app starts, and the managed

infra/containers/sandbox/scripts/project-source-sync.py

@@ -279,6 +279,7 @@ def package_run(source, target, lock_path, local_cwd, command):
         fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
         sync_directory(source, target)
         baseline = tree_state(target)
+        detach_runtime_dependencies(local_cwd)
         completed = subprocess.run(command, cwd=local_cwd, check=False)
         if completed.returncode != 0:
             return completed.returncode
@@ -329,6 +330,9 @@ def dependency_state_path(local_cwd):
 
 
 def dependencies_are_current(local_cwd, local_root):
+    modules = os.path.join(local_cwd, "node_modules")
+    if os.path.islink(modules):
+        return False
     marker = dependency_state_path(local_cwd)
     try:
         with open(marker, "r", encoding="ascii") as source:
@@ -353,6 +357,30 @@ def record_dependency_state(local_cwd, local_root):
             pass
 
 
+def activate_runtime_dependencies(local_cwd, dependency_runtime):
+    runtime_modules = os.path.join(dependency_runtime, "node_modules")
+    if not os.path.isdir(runtime_modules):
+        return False
+    modules = os.path.join(local_cwd, "node_modules")
+    if os.path.islink(modules) and os.path.realpath(modules) == os.path.realpath(runtime_modules):
+        return True
+    temporary = os.path.join(local_cwd, f".cheatcode-modules-{os.getpid()}")
+    remove_path(temporary)
+    try:
+        os.symlink(os.path.realpath(runtime_modules), temporary)
+        remove_path(modules)
+        os.replace(temporary, modules)
+    finally:
+        remove_path(temporary)
+    return True
+
+
+def detach_runtime_dependencies(local_cwd):
+    modules = os.path.join(local_cwd, "node_modules")
+    if os.path.islink(modules):
+        remove_path(modules)
+
+
 def pnpm_workspace_path(local_cwd, local_root):
     current = os.path.realpath(local_cwd)
     root = os.path.realpath(local_root)
@@ -412,17 +440,19 @@ def reviewed_pnpm_build_policy(local_cwd, local_root):
         restore_path(workspace_path, captured)
 
 
-def restore_pnpm_dependencies(local_cwd, local_root, dependency_template):
+def restore_pnpm_dependencies(local_cwd, local_root, dependency_runtime):
     package_path = os.path.join(local_cwd, "package.json")
     lock_path = os.path.join(local_cwd, "pnpm-lock.yaml")
     if not os.path.isfile(package_path):
         return 0
-    if dependency_template and files_equal(
-        package_path, os.path.join(dependency_template, "package.json")
-    ) and files_equal(lock_path, os.path.join(dependency_template, "pnpm-lock.yaml")):
-        return 0
+    if dependency_runtime and files_equal(
+        package_path, os.path.join(dependency_runtime, "package.json")
+    ) and files_equal(lock_path, os.path.join(dependency_runtime, "pnpm-lock.yaml")):
+        if activate_runtime_dependencies(local_cwd, dependency_runtime):
+            return 0
     if dependencies_are_current(local_cwd, local_root):
         return 0
+    detach_runtime_dependencies(local_cwd)
     common = ["install", "--prefer-offline", "--network-concurrency", "4"]
     with reviewed_pnpm_build_policy(local_cwd, local_root):
         if not os.path.isfile(lock_path):
@@ -472,14 +502,14 @@ def reap_process(process):
         process.wait()
 
 
-def preview_run(source, target, lock_path, local_cwd, dependency_template, command):
+def preview_run(source, target, lock_path, local_cwd, dependency_runtime, command):
     validate_local_cwd(target, local_cwd)
     if not command:
         raise ValueError("preview-run requires an app command")
     with open_lock(lock_path) as lock:
         fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
         sync_source_once(source, target)
-        dependency_status = restore_pnpm_dependencies(local_cwd, target, dependency_template)
+        dependency_status = restore_pnpm_dependencies(local_cwd, target, dependency_runtime)
         if dependency_status != 0:
             return dependency_status
 
@@ -541,15 +571,15 @@ def main():
         raise SystemExit(package_run(source, target, lock_path, sys.argv[5], sys.argv[7:]))
     if mode == "preview-run":
         if len(sys.argv) < 9 or sys.argv[7] != "--":
-            raise ValueError("preview-run requires a cwd, dependency template, and argv after --")
-        dependency_template = None if sys.argv[6] == "-" else sys.argv[6]
+            raise ValueError("preview-run requires a cwd, dependency runtime, and argv after --")
+        dependency_runtime = None if sys.argv[6] == "-" else sys.argv[6]
         raise SystemExit(
             preview_run(
                 source,
                 target,
                 lock_path,
                 sys.argv[5],
-                dependency_template,
+                dependency_runtime,
                 sys.argv[8:],
             )
         )

packages/agent-core/src/tools/code/index.ts

@@ -45,7 +45,6 @@ export {
 } from "./git";
 export {
   executePreparedStartDevServer,
-  executeStartDevServer,
   prepareStartDevServer,
 } from "./preview";
 export { executeRunCode, RunCodeInputSchema, RunCodeOutputSchema } from "./run-code";