fix(mobile): make the Expo web preview actually render (self-healing dev server)

The in-panel mobile web preview never rendered. Four compounding causes,
each fixed deterministically at the dev-server layer so it works regardless
of how the model builds the app:

1. Scaffold nesting: `cp -a template dir` nests when the run-start mkdir has
   already created `dir` (dir/cheatcode-expo-template/), so the project had no
   package.json at its root and fell back to a bare create-expo-app missing
   expo-router + the web deps. Copy template CONTENTS and verify package.json.

2. Broken start command: the model starts its own dev server via start_dev_server
   with a hallucinated `npx expo start --web --port 5173 --no-dev-client` (invalid
   flag -> expo exits; hardcoded 5173 -> collides). Normalize any `expo start`
   command to the one canonical invocation on the project's allocated port.

3. Corrupted dependency tree: the model rewrites package.json mid-build, pruning
   Metro's deps (react-dom, react-native-web, expo-asset) and DOWNGRADING others
   (expo-router to a pre-SDK major -> `Font.resetServerContext is not a function`).
   Self-heal: re-merge the template's deps with the template's versions winning
   for shared packages, keeping app-added extras, and reinstall only on change.

4. SSR-behind-proxy: without web.output:"single" the web dev server renders
   per-request and does `new URL(req.url)` behind the preview proxy ->
   `TypeError: Invalid URL`. Pin app.json to a metro SPA on every start.

The heal is embedded in the canonical command persisted to the process record,
so it re-applies on restart and wake-from-idle too. Also stop telling the
app-builder agent to "Run Metro" (the preview is managed) to cut redundant
starts. Verified live: fresh mobile builds -> previewRunning:true, no deps
error, no Invalid URL, Metro serving; app HTML renders.

Author: iamjr15

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

@@ -666,27 +666,42 @@ async function stopProjectPreview(
   }
 }
 
+// Populate `dir` with the CONTENTS of a baked template (`src/.` copies dotfiles too), then verify a
+// package.json landed at the root. Returns false instead of throwing so callers fall back to a
+// generator only on a genuine failure. `dir` is a filesystem-safe /workspace/<slug> path (no shell
+// metacharacters), so the interpolation is safe; the whole script is shell-quoted by the exec layer.
+async function copyTemplateContents(
+  sandbox: ProjectSandboxStub,
+  templateDir: string,
+  dir: string,
+): Promise<boolean> {
+  const copied = await executeShellTerminal(
+    {
+      command: `mkdir -p ${dir} && cp -a ${templateDir}/. ${dir}/ && test -f ${dir}/package.json`,
+      cwd: "/workspace",
+      timeoutMs: 120_000,
+    },
+    { sandbox },
+  );
+  return copied.success;
+}
+
 async function scaffoldExpoApp(
   sandbox: ProjectSandboxStub,
   logger: AgentRunLogger,
   dir: string,
 ): Promise<void> {
-  try {
-    await executeShellExec(
-      {
-        command: ["cp", "-a", "/home/node/cheatcode-expo-template", dir],
-        cwd: "/workspace",
-        timeoutMs: 120_000,
-      },
-      { sandbox },
-    );
+  // Copy the template CONTENTS (`src/.` → `dst/`), never `cp -a src dst`: the latter nests as
+  // `dst/cheatcode-expo-template/` when `dst` already exists (the run-start `mkdir -p` of the
+  // workspace dir can win the race), silently yielding a project with no package.json at its root.
+  // `test -f` verifies the layout so we only fall back to a bare create-expo-app — which lacks
+  // expo-router and the web deps (react-dom/react-native-web) that `expo start --web` needs — on a
+  // genuine copy failure, not on the nesting race.
+  if (await copyTemplateContents(sandbox, "/home/node/cheatcode-expo-template", dir)) {
     logger.info("sandbox_expo_template_copied", { targetDir: dir });
     return;
-  } catch (error) {
-    logger.warn("sandbox_expo_template_copy_failed", {
-      error: error instanceof Error ? error.message : "Unknown template copy error",
-    });
   }
+  logger.warn("sandbox_expo_template_copy_failed", { targetDir: dir });
 
   await executeShellExec(
     {
@@ -712,22 +727,13 @@ async function scaffoldAppBuilder(
   logger: AgentRunLogger,
   dir: string,
 ): Promise<void> {
-  try {
-    await executeShellExec(
-      {
-        command: ["cp", "-a", "/home/node/cheatcode-next-template", dir],
-        cwd: "/workspace",
-        timeoutMs: 120_000,
-      },
-      { sandbox },
-    );
+  // Copy template CONTENTS into the project dir (see scaffoldExpoApp): `cp -a src dst` nests as
+  // `dst/cheatcode-next-template/` when `dst` already exists, leaving no package.json at the root.
+  if (await copyTemplateContents(sandbox, "/home/node/cheatcode-next-template", dir)) {
     logger.info("sandbox_next_template_copied", { targetDir: dir });
     return;
-  } catch (error) {
-    logger.warn("sandbox_next_template_copy_failed", {
-      error: error instanceof Error ? error.message : "Unknown template copy error",
-    });
   }
+  logger.warn("sandbox_next_template_copy_failed", { targetDir: dir });
 
   await executeShellExec(
     {

packages/agent-core/src/mastra/system-prompt.ts

@@ -218,7 +218,16 @@ Verify it in the browser: open the app's INTERNAL address in the sandbox's heade
 
 const MOBILE_MODULE = `## Building the mobile app
 
-Build the Expo Router screens for a polished, native-feeling app: real screens, real navigation, considered design — no lorem ipsum, no dead buttons. Run Metro and verify the app renders. The preview and Expo Go QR code are shown to the user automatically in the App panel — refer to them naturally, don't paste URLs.`;
+Build the Expo Router screens for a polished, native-feeling app: real screens, real navigation, considered design — no lorem ipsum, no dead buttons. Verify the app renders in the live preview. The preview and Expo Go QR code are shown to the user automatically in the App panel — refer to them naturally, don't paste URLs.`;
+
+// Injected for app-builder / app-builder-mobile runs: their workspace is scaffolded and the dev
+// server is already running and managed BEFORE the agent's turn (see agent-run-app-builder), so any
+// server the model starts itself just fights the managed one for the project's port and breaks the
+// preview (e.g. a hallucinated `npx expo start --web --port 5173 --no-dev-client`). The general path
+// keeps WEB_MODULE's "start the dev server yourself" guidance; this note only applies here.
+const APP_BUILDER_PREVIEW_NOTE = `## Your preview is already running — do not start your own
+
+This project is scaffolded and its dev server + live preview are ALREADY running and managed for you before your turn begins (for a mobile app that's Metro serving the app on web plus the Expo Go QR). Do NOT start, restart, or reconfigure the server yourself — no start_dev_server, \`expo start\`, \`npm run dev\`/\`web\`, or \`npx expo …\`: a second server fights the managed one for the project's port and breaks the preview. Just create and edit files in your workspace and the preview hot-reloads on save. Verify by opening the running app in the sandbox's headed Chromium at its INTERNAL localhost address; it's shown to the user automatically in the Computer/App panel — never paste the preview URL.`;
 
 const DOCS_MODULE = `## Building documents & slides
 
@@ -267,10 +276,10 @@ const DOMAIN_MODULES: Record<DomainKey, string> = {
  */
 function selectDomainModules(projectMode?: string, taskMessage?: string): string[] {
   if (projectMode === "app-builder") {
-    return [WEB_MODULE];
+    return [WEB_MODULE, APP_BUILDER_PREVIEW_NOTE];
   }
   if (projectMode === "app-builder-mobile") {
-    return [MOBILE_MODULE];
+    return [MOBILE_MODULE, APP_BUILDER_PREVIEW_NOTE];
   }
   const domains = classifyDomains(taskMessage ?? "");
   return domains.length > 0 ? domains.map((domain) => DOMAIN_MODULES[domain]) : [GENERALIST_MODULE];

packages/tools-code/src/preview.ts

@@ -57,12 +57,21 @@ export async function executeStartDevServer(
   const cwd = runtimeContext.workspaceDir ?? parsedInput.cwd;
   const slug = deriveWorkspaceSlug(cwd);
   const name = `${APP_PREVIEW_SLOT_PREFIX}${slug}`;
-  const port = await allocateDevServerPort(runtimeContext, slug, parsedInput.isMobile);
+  // A mobile/Expo dev server has exactly one correct invocation: `expo start --web` on the project's
+  // own allocated port. The model sometimes emits a broken variant via start_dev_server — a
+  // hallucinated `--no-dev-client` that makes expo exit, or a hardcoded `--port 5173` that collides
+  // with another project in the shared per-user sandbox — which lands in this project's preview slot
+  // and leaves the panel blank. Normalize any `expo start` command (from the model OR the app-builder,
+  // where it's a no-op) to the canonical form; web (Next/Vite) commands pass through untouched.
+  const isExpo = isExpoStartCommand(parsedInput.command);
+  const isMobile = isExpo || parsedInput.isMobile;
+  const port = await allocateDevServerPort(runtimeContext, slug, isMobile);
+  const command = isExpo ? expoWebCommand(port) : parsedInput.command;
   const process = await callSandboxMethod(runtimeContext.sandbox, "startProcess", {
-    command: parsedInput.command,
+    command,
     cwd,
     env: { ...parsedInput.env, PORT: String(port) },
-    isMobile: parsedInput.isMobile,
+    isMobile,
     keepAliveTimeoutMs: parsedInput.keepAliveTimeoutMs,
     maxRestarts: parsedInput.maxRestarts,
     processId: name,
@@ -89,6 +98,56 @@ export async function executeStartDevServer(
   });
 }
 
+// An `expo start …` invocation, however the model spelled it (npx / pnpm exec / bare, any flags).
+function isExpoStartCommand(command: readonly string[]): boolean {
+  return command.includes("expo") && command.includes("start");
+}
+
+// Restore the curated Expo dependency tree onto the project's package.json. The model routinely
+// rewrites package.json mid-build — pruning packages Metro needs (react-dom, react-native-web,
+// expo-asset) AND downgrading others (e.g. expo-router to a pre-SDK major), which crashes
+// `expo start --web`. Re-merge the baked template's deps with the TEMPLATE's versions authoritative
+// for shared packages (fixes downgrades + restores removals) while keeping any extra packages the
+// app genuinely added. Exit 0 only when something changed, so the caller reinstalls only then —
+// keeping wake-from-idle (deps already correct) fast.
+const RESTORE_EXPO_DEPS_JS = [
+  'const fs=require("fs");',
+  'const t=require("/home/node/cheatcode-expo-template/package.json");',
+  // Pin the web config to a client-rendered SPA on the Metro bundler. Without output:"single" the
+  // Expo web dev server renders per-request and does `new URL(req.url)` behind the preview proxy,
+  // which throws `TypeError: Invalid URL`; the model routinely drops this from app.json. Cheap file
+  // write, applied every start (Metro reads it on boot), independent of the reinstall decision below.
+  "try{",
+  'const aj=process.cwd()+"/app.json";const a=require(aj);a.expo=a.expo||{};',
+  'a.expo.web=Object.assign({},a.expo.web,{bundler:"metro",output:"single"});',
+  'fs.writeFileSync(aj,JSON.stringify(a,null,2)+"\\n");',
+  "}catch(e){}",
+  'const j=process.cwd()+"/package.json";',
+  "const p=require(j);",
+  "const before=JSON.stringify([p.dependencies,p.devDependencies,p.main]);",
+  "p.dependencies=Object.assign({},p.dependencies||{},t.dependencies);",
+  "p.devDependencies=Object.assign({},p.devDependencies||{},t.devDependencies);",
+  "p.main=t.main;",
+  "const after=JSON.stringify([p.dependencies,p.devDependencies,p.main]);",
+  "if(before===after){process.exit(1)}",
+  'fs.writeFileSync(j,JSON.stringify(p,null,2)+"\\n");',
+].join("");
+
+// The one canonical Expo dev-server command. It first self-heals the dependency tree (see above) and
+// reinstalls only if the merge changed anything — so a build that corrupted deps is repaired, while a
+// clean start / wake-from-idle skips straight to Metro. Because this is the command PERSISTED in the
+// process record, it re-heals on restart and wake too. Then Metro: `-c` clears its cache so a finished
+// app re-crawls cleanly; `--web` also answers exp:// manifests for the Expo Go QR; `--host lan` + the
+// project's allocated port keep it reachable and collision-free. `exec` hands the slot to Metro.
+function expoWebCommand(port: number): string[] {
+  const restoreB64 = btoa(RESTORE_EXPO_DEPS_JS);
+  const writeScript = `echo ${restoreB64} | base64 -d > /tmp/cc-restore-expo-deps.js`;
+  const heal =
+    "node /tmp/cc-restore-expo-deps.js && rm -f pnpm-lock.yaml package-lock.json && CI=1 EXPO_NO_TELEMETRY=1 pnpm install --prefer-offline";
+  const startMetro = `exec pnpm exec expo start -c --web --host lan --port ${port}`;
+  return ["sh", "-lc", `${writeScript}; (${heal}) ; ${startMetro}`];
+}
+
 // The project's workspaceSlug = the last non-empty path segment of the cwd (/workspace/<slug>).
 // Every run has a project, so the forced cwd is always /workspace/<slug> and yields a slug here.
 function deriveWorkspaceSlug(cwd: string): string {