@jami-studio/core 0.92.13 → 0.92.15

package/corpus/core/src/deploy/workspace-deploy.ts

@@ -1,1453 +1,1458 @@
-/**
- * `agent-native deploy` — build and deploy every app in a workspace to a
- * single origin. Each app is served from `/<app-name>/*`, so:
- *
- *   https://your-agents.com/mail/*       → apps/mail
- *   https://your-agents.com/calendar/*   → apps/calendar
- *
- * Benefits of same-origin deploy:
- *   - Shared auth cookie → log in once, every app is signed in
- *   - Cross-app A2A is a same-origin fetch (no CORS, no JWT for siblings)
- *   - One DNS record, one TLS cert, one CDN cache
- *
- * Per-app independent deploy is still supported — just cd into the app and
- * run `agent-native build` as before. This orchestrator is for teams that
- * want the whole workspace behind one domain.
- */
-import { execFileSync } from "child_process";
-import fs from "fs";
-import path from "path";
-
-import { AGENT_CHAT_PROCESS_RUN_PATH } from "../agent/durable-background.js";
-import { findWorkspaceRoot } from "../scripts/utils.js";
-import {
-  DEFAULT_WORKSPACE_APP_AUDIENCE,
-  normalizeWorkspaceAppAudience,
-  normalizeWorkspaceAppPathList,
-  workspaceAppAudienceFromPackageJson,
-  workspaceAppRouteAccessFromPackageJson,
-  type WorkspaceAppRouteAccess,
-  type WorkspaceAppAudience,
-} from "../shared/workspace-app-audience.js";
-import { DISPATCH_WORKSPACE_ROOT_REDIRECTS } from "../shared/workspace-app-id.js";
-import {
-  collectImmutableAssetPaths,
-  IMMUTABLE_ASSET_CACHE_HEADERS,
-} from "./immutable-assets.js";
-
-export type WorkspaceDeployPreset = "cloudflare_pages" | "netlify" | "vercel";
-
-const NETLIFY_WORKSPACE_STATIC_DIR = "_workspace_static";
-const NETLIFY_PUBLIC_ASSET_EXTENSIONS = new Set([
-  "avif",
-  "css",
-  "gif",
-  "ico",
-  "jpeg",
-  "jpg",
-  "js",
-  "json",
-  "map",
-  "mp4",
-  "pdf",
-  "png",
-  "svg",
-  "txt",
-  "wasm",
-  "webm",
-  "webmanifest",
-  "webp",
-  "xml",
-]);
-const WORKSPACE_APPS_ENV_KEY = "AGENT_NATIVE_WORKSPACE_APPS_JSON";
-const WORKSPACE_APPS_MANIFEST_DIR = ".agent-native";
-const WORKSPACE_APPS_MANIFEST_FILE = "workspace-apps.json";
-const VERCEL_OUTPUT_DIR = ".vercel/output";
-
-interface WorkspaceAppManifestEntry {
-  id: string;
-  name: string;
-  description: string;
-  path: string;
-  url?: string;
-  isDispatch: boolean;
-  audience: WorkspaceAppAudience;
-  publicPaths: string[];
-  protectedPaths: string[];
-}
-
-interface WorkspaceAppManifestOverride {
-  id: string;
-  url?: string;
-  audience?: WorkspaceAppAudience;
-  publicPaths?: string[];
-  protectedPaths?: string[];
-}
-
-export interface WorkspaceDeployOptions {
-  args?: string[];
-  /** Override the workspace root (defaults to walking up from cwd). */
-  workspaceRoot?: string;
-  /** Only build — don't invoke the deploy platform CLI. */
-  buildOnly?: boolean;
-  /** Target preset. Defaults to `cloudflare_pages`. */
-  preset?: WorkspaceDeployPreset;
-  /** @internal Override process execution in tests. */
-  execFile?: typeof execFileSync;
-}
-
-export async function runWorkspaceDeploy(
-  opts: WorkspaceDeployOptions = {},
-): Promise<void> {
-  const workspaceRoot =
-    opts.workspaceRoot ?? findWorkspaceRoot(process.cwd()) ?? process.cwd();
-  const appsDir = path.join(workspaceRoot, "apps");
-  if (!fs.existsSync(appsDir)) {
-    throw new Error(
-      `No apps/ directory found at ${workspaceRoot}. Run this inside an agent-native workspace.`,
-    );
-  }
-
-  const rawArgs = opts.args ?? [];
-  const args = new Set(rawArgs);
-  const buildOnly = opts.buildOnly ?? args.has("--build-only");
-
-  const apps = fs
-    .readdirSync(appsDir, { withFileTypes: true })
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name)
-    .filter((n) => fs.existsSync(path.join(appsDir, n, "package.json")))
-    .sort(compareWorkspaceAppIds);
-
-  if (apps.length === 0) {
-    throw new Error(
-      `Workspace has no apps. Run \`agent-native add-app\` to add one.`,
-    );
-  }
-  assertNoReservedWorkspaceAppIds(apps);
-  const workspaceApps = readWorkspaceAppManifest(workspaceRoot, apps);
-
-  const preset = resolvePreset(opts.preset, rawArgs);
-  assertWorkspaceDeployProductionEnv({ buildOnly, preset });
-  const distDir = path.join(workspaceRoot, "dist");
-  const vercelOutputDir = path.join(workspaceRoot, VERCEL_OUTPUT_DIR);
-  if (preset === "vercel") {
-    fs.rmSync(vercelOutputDir, { recursive: true, force: true });
-    fs.mkdirSync(path.join(vercelOutputDir, "static"), { recursive: true });
-    fs.mkdirSync(path.join(vercelOutputDir, "functions"), {
-      recursive: true,
-    });
-  } else {
-    fs.rmSync(distDir, { recursive: true, force: true });
-    fs.mkdirSync(distDir, { recursive: true });
-  }
-
-  if (preset === "netlify") {
-    const functionsDir = netlifyFunctionsDir(workspaceRoot);
-    fs.rmSync(functionsDir, { recursive: true, force: true });
-    fs.mkdirSync(functionsDir, { recursive: true });
-  }
-
-  console.log(
-    `[workspace-deploy] Building ${apps.length} app(s) for preset=${preset}`,
-  );
-
-  const execFile = opts.execFile ?? execFileSync;
-  for (const app of apps) {
-    buildOneApp(workspaceRoot, app, preset, execFile, workspaceApps);
-    moveAppBuildIntoWorkspaceOutput(
-      workspaceRoot,
-      app,
-      preset,
-      distDir,
-      vercelOutputDir,
-      workspaceApps,
-    );
-  }
-  writeWorkspaceAppManifests(
-    workspaceRoot,
-    distDir,
-    apps,
-    workspaceApps,
-    preset,
-  );
-
-  if (preset === "netlify") {
-    writeNetlifyRedirects(distDir, apps);
-    writeNetlifyHeaders(distDir, apps);
-  } else if (preset === "vercel") {
-    writeVercelBuildConfig(vercelOutputDir, apps);
-  } else {
-    writeCloudflareRoutingManifest(distDir, apps);
-  }
-
-  if (buildOnly) {
-    const outputDir = preset === "vercel" ? vercelOutputDir : distDir;
-    console.log(
-      `\n[workspace-deploy] Build complete at ${outputDir}. Skipping publish (--build-only).`,
-    );
-    return;
-  }
-
-  console.log(`\n[workspace-deploy] Build complete. Publish with:\n`);
-  console.log(`  cd ${path.relative(process.cwd(), workspaceRoot) || "."}`);
-  if (preset === "netlify") {
-    console.log(
-      `  netlify deploy --prod --dir=dist --functions=.netlify/functions-internal\n`,
-    );
-  } else if (preset === "vercel") {
-    console.log(`  vercel deploy --prebuilt\n`);
-  } else {
-    console.log(`  wrangler pages deploy dist\n`);
-  }
-  console.log(
-    `All apps live at https://<origin>/<app-name>/*. Log in once on any app\nand the session is shared across the workspace.`,
-  );
-}
-
-function buildOneApp(
-  workspaceRoot: string,
-  app: string,
-  preset: WorkspaceDeployPreset,
-  execFile: typeof execFileSync,
-  workspaceApps: WorkspaceAppManifestEntry[],
-): void {
-  const appDir = path.join(workspaceRoot, "apps", app);
-  const workspaceAppAudience = workspaceAppAudienceForApp(workspaceApps, app);
-  const workspaceAppRouteAccess = workspaceAppRouteAccessForApp(
-    workspaceApps,
-    app,
-  );
-  const workspaceGatewayUrl =
-    process.env.VITE_WORKSPACE_GATEWAY_URL || workspaceBaseUrl();
-  const workspaceOAuthUrl = workspaceOAuthOrigin(workspaceGatewayUrl);
-  const env: NodeJS.ProcessEnv = {
-    ...process.env,
-    NITRO_PRESET: preset,
-    AGENT_NATIVE_WORKSPACE: "1",
-    AGENT_NATIVE_WORKSPACE_APP_ID: app,
-    VITE_AGENT_NATIVE_WORKSPACE: "1",
-    VITE_AGENT_NATIVE_WORKSPACE_APP_ID: app,
-    APP_BASE_PATH: `/${app}`,
-    VITE_APP_BASE_PATH: `/${app}`,
-    AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: workspaceAppAudience,
-    AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: JSON.stringify(
-      workspaceAppRouteAccess.publicPaths,
-    ),
-    AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: JSON.stringify(
-      workspaceAppRouteAccess.protectedPaths,
-    ),
-    VITE_AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: workspaceAppAudience,
-    VITE_AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: JSON.stringify(
-      workspaceAppRouteAccess.publicPaths,
-    ),
-    VITE_AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: JSON.stringify(
-      workspaceAppRouteAccess.protectedPaths,
-    ),
-    VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON: JSON.stringify(workspaceApps),
-    ...(workspaceGatewayUrl
-      ? {
-          WORKSPACE_GATEWAY_URL:
-            process.env.WORKSPACE_GATEWAY_URL || workspaceGatewayUrl,
-          VITE_WORKSPACE_GATEWAY_URL: workspaceGatewayUrl,
-          ...(workspaceOAuthUrl
-            ? { VITE_WORKSPACE_OAUTH_ORIGIN: workspaceOAuthUrl }
-            : {}),
-        }
-      : {}),
-    [WORKSPACE_APPS_ENV_KEY]: JSON.stringify(workspaceApps),
-  };
-
-  if (preset === "netlify" && appUsesNetlifyUnpooledDatabaseUrl(appDir)) {
-    env.DATABASE_URL =
-      process.env.NETLIFY_DATABASE_URL_UNPOOLED ??
-      process.env.DATABASE_URL ??
-      env.DATABASE_URL;
-  }
-
-  console.log(
-    `[workspace-deploy] Building ${app} (base=/${app}, preset=${preset})`,
-  );
-
-  cleanAppBuildOutputs(appDir);
-
-  execFile("pnpm", ["--filter", app, "build"], {
-    cwd: workspaceRoot,
-    env,
-    stdio: "inherit",
-  });
-}
-
-function moveAppBuildIntoWorkspaceOutput(
-  workspaceRoot: string,
-  app: string,
-  preset: WorkspaceDeployPreset,
-  distDir: string,
-  vercelOutputDir: string,
-  workspaceApps: WorkspaceAppManifestEntry[],
-): void {
-  const appDir = path.join(workspaceRoot, "apps", app);
-  if (preset === "vercel") {
-    copyVercelAppBuildIntoWorkspace(
-      workspaceRoot,
-      app,
-      vercelOutputDir,
-      workspaceApps,
-    );
-    return;
-  }
-
-  // Resolve the per-app build output: prefer dist/ (standard), fall back to
-  // .output/ (Nitro's default). The Cloudflare preset emits into dist/
-  // containing the worker + assets.
-  const candidates = ["dist", ".output"];
-  const src = candidates
-    .map((c) => path.join(appDir, c))
-    .find((p) => fs.existsSync(p));
-  if (!src) {
-    throw new Error(
-      `Expected ${candidates.join(" or ")} under ${appDir} but none existed. Check the app's build script.`,
-    );
-  }
-  if (preset === "netlify") {
-    const mountedSrc = path.join(src, app);
-    const staticSrc = fs.existsSync(mountedSrc) ? mountedSrc : src;
-    const target = path.join(distDir, NETLIFY_WORKSPACE_STATIC_DIR, app);
-    fs.mkdirSync(target, { recursive: true });
-    copyDir(staticSrc, target);
-    // Nitro/Vite mounted builds can contain a nested copy of public assets at
-    // dist/<app>/<app>/...; the workspace root already supplies the outer
-    // mount path, so keeping it would publish duplicate /<app>/<app> URLs.
-    fs.rmSync(path.join(target, app), { recursive: true, force: true });
-    copyNetlifyFunctionIntoWorkspace(workspaceRoot, app, workspaceApps, target);
-  } else {
-    const target = path.join(distDir, app);
-    fs.mkdirSync(target, { recursive: true });
-    copyDir(src, target);
-  }
-}
-
-function copyVercelAppBuildIntoWorkspace(
-  workspaceRoot: string,
-  app: string,
-  vercelOutputDir: string,
-  workspaceApps: WorkspaceAppManifestEntry[],
-): void {
-  const appDir = path.join(workspaceRoot, "apps", app);
-  const src = path.join(appDir, VERCEL_OUTPUT_DIR);
-  if (!fs.existsSync(src)) {
-    throw new Error(
-      `Expected Vercel output at ${src} after building ${app}. Check the app's build script and NITRO_PRESET.`,
-    );
-  }
-
-  const staticSrc = path.join(src, "static");
-  const staticDest = path.join(vercelOutputDir, "static");
-  if (fs.existsSync(staticSrc)) {
-    copyDir(staticSrc, staticDest);
-    // Nitro's Vercel preset already nests assets under baseURL. The shared
-    // deploy build also mirrors client assets under baseURL for other Nitro
-    // presets, so mounted apps can contain a duplicate /<app>/<app> copy.
-    fs.rmSync(path.join(staticDest, app, app), {
-      recursive: true,
-      force: true,
-    });
-  }
-
-  const functionSrc = path.join(src, "functions", "__server.func");
-  if (!fs.existsSync(functionSrc)) {
-    throw new Error(
-      `Expected Vercel function at ${functionSrc} after building ${app}. Check the app's build script and NITRO_PRESET.`,
-    );
-  }
-
-  const functionDest = path.join(
-    vercelOutputDir,
-    "functions",
-    `${app}-server.func`,
-  );
-  fs.rmSync(functionDest, { recursive: true, force: true });
-  copyDir(functionSrc, functionDest);
-  patchVercelFunctionEntry(functionDest, app, workspaceApps);
-}
-
-/**
- * Write the Cloudflare Pages `_routes.json` and a dispatcher `_worker.js` at
- * the workspace dist root so each app is reachable under /<app>/*.
- */
-function writeCloudflareRoutingManifest(distDir: string, apps: string[]): void {
-  const dispatchFaviconAsset = apps.includes("dispatch")
-    ? dispatchRootFaviconAsset(distDir)
-    : null;
-  // _routes.json tells Cloudflare which paths are dynamic (Functions) vs
-  // static. Mark both /<app> and /<app>/* as include so every app's worker
-  // handles its root and subtree.
-  const include = apps.flatMap((a) => [`/${a}`, `/${a}/*`]).concat(["/"]);
-  if (apps.includes("dispatch")) {
-    include.push("/_agent-native/*");
-    include.push("/.well-known/*");
-    include.push(
-      ...DISPATCH_WORKSPACE_ROOT_REDIRECTS.map(([from]) => `/${from}`),
-    );
-    include.push("/apps/*");
-    if (dispatchFaviconAsset) include.push("/favicon.ico");
-  }
-  const routes = {
-    version: 1,
-    include,
-    exclude: [],
-  };
-  fs.writeFileSync(
-    path.join(distDir, "_routes.json"),
-    JSON.stringify(routes, null, 2) + "\n",
-  );
-
-  // Dispatcher worker: inspects the path and forwards to the matching
-  // per-app worker.
-  const imports = apps
-    .map((a) => `import ${moduleIdent(a)} from "./${a}/_worker.js";`)
-    .join("\n");
-  const dispatch = apps
-    .map(
-      (a) =>
-        `  if (pathname === "/${a}" || pathname.startsWith("/${a}/")) return ${moduleIdent(a)}.fetch(requestForMountedApp(request, "/${a}"), env, ctx);`,
-    )
-    .join("\n");
-  const dispatchRootFrameworkRoutes = apps.includes("dispatch")
-    ? `    if (pathname === "/_agent-native" || pathname.startsWith("/_agent-native/") || pathname === "/.well-known" || pathname.startsWith("/.well-known/")) return ${moduleIdent("dispatch")}.fetch(request, env, ctx);
-`
-    : "";
-  const dispatchRootFaviconRoute = dispatchFaviconAsset
-    ? `    if (pathname === "/favicon.ico") return Response.redirect(new URL("/dispatch/${dispatchFaviconAsset}", request.url).toString(), 302);
-`
-    : "";
-  const dispatchRootAliasRoutes = apps.includes("dispatch")
-    ? DISPATCH_WORKSPACE_ROOT_REDIRECTS.map(
-        ([from, to]) =>
-          `    if (pathname === "/${from}") return Response.redirect(new URL("/dispatch/${to}" + search, request.url).toString(), 302);`,
-      ).join("\n") + "\n"
-    : "";
-  const dispatchRootDynamicAliasRoutes = apps.includes("dispatch")
-    ? `    if (pathname.startsWith("/apps/")) return Response.redirect(new URL("/dispatch" + pathname + search, request.url).toString(), 302);
-`
-    : "";
-  const dispatchMountedRootRedirect = apps.includes("dispatch")
-    ? `    if (pathname === "/dispatch" || pathname === "/dispatch/") return Response.redirect(new URL("/dispatch/overview" + search, request.url).toString(), 302);
-`
-    : "";
-
-  const worker = `${imports}
-
-function requestForMountedApp(request, basePath) {
-  const url = new URL(request.url);
-  if (url.pathname !== basePath && url.pathname !== \`\${basePath}/\`) {
-    return request;
-  }
-  url.pathname = \`\${basePath}//\`;
-  return new Request(url, request);
-}
-
-export default {
-  async fetch(request, env, ctx) {
-    const { pathname, search } = new URL(request.url);
-${dispatchRootFrameworkRoutes}${dispatchRootFaviconRoute}${dispatchRootAliasRoutes}${dispatchRootDynamicAliasRoutes}${dispatchMountedRootRedirect}${dispatch}
-    if (pathname === "/") {
-      return Response.redirect(new URL("${cloudflareRootRedirectPath(apps)}", request.url).toString(), 302);
-    }
-    return new Response("Not found", { status: 404 });
-  },
-};
-`;
-  fs.writeFileSync(path.join(distDir, "_worker.js"), worker);
-}
-
-function cloudflareRootRedirectPath(apps: string[]): string {
-  return apps.includes("dispatch") ? "/dispatch/overview" : `/${apps[0]}/`;
-}
-
-function writeNetlifyRedirects(distDir: string, apps: string[]): void {
-  const lines: string[] = [
-    "# Generated by agent-native deploy --preset netlify",
-    "# Static app assets are stored under a safe namespace; dynamic app routes are handled by function route config.",
-  ];
-
-  if (apps.includes("dispatch")) {
-    lines.push("/_agent-native/* /.netlify/functions/dispatch-server 200");
-    lines.push("/.well-known/* /.netlify/functions/dispatch-server 200");
-    const faviconAsset = dispatchRootFaviconAsset(distDir);
-    if (faviconAsset) {
-      lines.push(`/favicon.ico /dispatch/${faviconAsset} 302`);
-    }
-  }
-
-  for (const app of apps) {
-    lines.push(...netlifyAssetRedirectsFor(app, distDir));
-  }
-
-  if (apps.includes("dispatch")) {
-    lines.push("/ /dispatch/overview 302");
-    lines.push("/dispatch /dispatch/overview 302");
-    lines.push("/dispatch/ /dispatch/overview 302");
-    for (const [from, to] of DISPATCH_WORKSPACE_ROOT_REDIRECTS) {
-      lines.push(`/${from} /dispatch/${to} 302`);
-    }
-    lines.push("/apps/* /dispatch/apps/:splat 302");
-  } else {
-    lines.push(`/ /${apps[0]}/ 302`);
-  }
-
-  fs.writeFileSync(path.join(distDir, "_redirects"), lines.join("\n") + "\n");
-}
-
-function writeNetlifyHeaders(distDir: string, apps: string[]): void {
-  const blocks = apps.flatMap((app) => {
-    const staticDir = path.join(distDir, NETLIFY_WORKSPACE_STATIC_DIR, app);
-    return collectImmutableAssetPaths(staticDir).flatMap((assetPath) => [
-      netlifyHeaderBlock(`/${app}${assetPath}`),
-      netlifyHeaderBlock(`/${NETLIFY_WORKSPACE_STATIC_DIR}/${app}${assetPath}`),
-    ]);
-  });
-
-  if (blocks.length === 0) return;
-  fs.writeFileSync(path.join(distDir, "_headers"), blocks.join("\n\n") + "\n");
-}
-
-function netlifyHeaderBlock(pathname: string): string {
-  return [
-    pathname,
-    ...Object.entries(IMMUTABLE_ASSET_CACHE_HEADERS).map(
-      ([name, value]) => `  ${name}: ${value}`,
-    ),
-  ].join("\n");
-}
-
-function writeVercelBuildConfig(outputDir: string, apps: string[]): void {
-  const routes: Array<Record<string, any>> = [
-    ...vercelImmutableAssetHeaderRoutes(outputDir, apps),
-    { handle: "filesystem" },
-  ];
-
-  if (apps.includes("dispatch")) {
-    routes.push(
-      { src: "/_agent-native", dest: "/dispatch-server" },
-      { src: "/_agent-native/(.*)", dest: "/dispatch-server" },
-      { src: "/\\.well-known", dest: "/dispatch-server" },
-      { src: "/\\.well-known/(.*)", dest: "/dispatch-server" },
-    );
-
-    const faviconAsset = dispatchRootFaviconAsset(
-      path.join(outputDir, "static"),
-    );
-    if (faviconAsset) {
-      routes.push(vercelRedirect("/favicon.ico", `/dispatch/${faviconAsset}`));
-    }
-
-    routes.push(
-      vercelRedirect("/", "/dispatch/overview"),
-      vercelRedirect("/dispatch", "/dispatch/overview"),
-      vercelRedirect("/dispatch/", "/dispatch/overview"),
-    );
-    for (const [from, to] of DISPATCH_WORKSPACE_ROOT_REDIRECTS) {
-      routes.push(vercelRedirect(`/${from}`, `/dispatch/${to}`));
-    }
-    routes.push(vercelRedirect("/apps/(.*)", "/dispatch/apps/$1"));
-  } else {
-    routes.push(vercelRedirect("/", `/${apps[0]}/`));
-  }
-
-  for (const app of apps) {
-    if (app !== "dispatch") {
-      routes.push({ src: `/${app}`, dest: `/${app}-server` });
-    }
-    routes.push({ src: `/${app}/(.*)`, dest: `/${app}-server` });
-  }
-
-  const config = {
-    version: 3,
-    routes,
-  };
-  fs.writeFileSync(
-    path.join(outputDir, "config.json"),
-    JSON.stringify(config, null, 2) + "\n",
-  );
-}
-
-function vercelImmutableAssetHeaderRoutes(
-  outputDir: string,
-  apps: string[],
-): Array<Record<string, any>> {
-  return apps.flatMap((app) => {
-    const staticDir = path.join(outputDir, "static", app);
-    return collectImmutableAssetPaths(staticDir).map((assetPath) => ({
-      src: vercelRouteSrc(`/${app}${assetPath}`),
-      headers: IMMUTABLE_ASSET_CACHE_HEADERS,
-      continue: true,
-    }));
-  });
-}
-
-function vercelRouteSrc(pathname: string): string {
-  return pathname.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function vercelRedirect(src: string, location: string): Record<string, any> {
-  return {
-    src,
-    status: 302,
-    headers: { Location: location },
-  };
-}
-
-function netlifyAssetRedirectsFor(app: string, distDir: string): string[] {
-  const from = `/${app}`;
-  const to = `/${NETLIFY_WORKSPACE_STATIC_DIR}/${app}`;
-  return [
-    `${from}/assets/* ${to}/assets/:splat 200`,
-    ...netlifyPublicRootAssetPaths(
-      app,
-      path.join(distDir, NETLIFY_WORKSPACE_STATIC_DIR, app),
-    ).map((assetPath) => {
-      const assetName = assetPath.slice(from.length + 1);
-      return `${assetPath} ${to}/${assetName} 200`;
-    }),
-  ];
-}
-
-function dispatchRootFaviconAsset(distDir: string): string | null {
-  for (const asset of ["favicon.ico", "favicon.svg", "favicon.png"]) {
-    if (workspaceAppAssetExists(distDir, "dispatch", asset)) return asset;
-  }
-  return null;
-}
-
-function workspaceAppAssetExists(
-  distDir: string,
-  app: string,
-  asset: string,
-): boolean {
-  return [
-    path.join(distDir, NETLIFY_WORKSPACE_STATIC_DIR, app, asset),
-    path.join(distDir, app, app, asset),
-    path.join(distDir, app, asset),
-  ].some((candidate) => fs.existsSync(candidate));
-}
-
-const RESERVED_WORKSPACE_APP_IDS = new Set([
-  "_agent-native",
-  "_workspace_static",
-  "netlify",
-  ...DISPATCH_WORKSPACE_ROOT_REDIRECTS.map(([from]) => from),
-]);
-
-function assertNoReservedWorkspaceAppIds(apps: string[]): void {
-  const conflicts = apps.filter(
-    (app) => app !== "dispatch" && RESERVED_WORKSPACE_APP_IDS.has(app),
-  );
-  if (conflicts.length === 0) return;
-  throw new Error(
-    `Workspace app id ${conflicts.map((id) => `"${id}"`).join(", ")} conflicts with reserved workspace routes. Choose a different app id.`,
-  );
-}
-
-function copyNetlifyFunctionIntoWorkspace(
-  workspaceRoot: string,
-  app: string,
-  workspaceApps: WorkspaceAppManifestEntry[],
-  staticDir: string,
-): void {
-  const appDir = path.join(workspaceRoot, "apps", app);
-  const src = path.join(appDir, ".netlify", "functions-internal", "server");
-  if (!fs.existsSync(src)) {
-    throw new Error(
-      `Expected Netlify function at ${src} after building ${app}. Check the app's build script and NITRO_PRESET.`,
-    );
-  }
-
-  const dest = path.join(netlifyFunctionsDir(workspaceRoot), `${app}-server`);
-  fs.rmSync(dest, { recursive: true, force: true });
-  copyDir(src, dest);
-  patchNetlifyFunctionEntry(dest, app, workspaceApps, staticDir);
-
-  // Durable background agent runs (default-ON; opt out with a falsy
-  // AGENT_CHAT_DURABLE_BACKGROUND). Additive ONLY: when explicitly opted out
-  // this emits nothing and the single-function deploy is unchanged.
-  if (isDurableBackgroundDeployEnabled()) {
-    emitNetlifyBackgroundFunction(workspaceRoot, app, src, workspaceApps);
-  }
-}
-
-/**
- * Deploy-time gate for emitting the second `-background` Netlify function. Reads
- * the same env flag the runtime gate uses (`AGENT_CHAT_DURABLE_BACKGROUND`).
- *
- * DEFAULT-ON, matching the runtime gate (`isFlagEnabled` in
- * durable-background.ts) and the single-template gate
- * (`isDurableBackgroundDeployEnabled` in deploy/build.ts): unset/empty/unknown
- * means enabled; an app opts OUT only with an explicit falsy value
- * (`false`/`0`/`no`/`off`). This emits the per-app 15-min `-background` function
- * so the chat `_process-run` dispatch lands on it with the real long budget.
- */
-function isDurableBackgroundDeployEnabled(): boolean {
-  const raw = process.env.AGENT_CHAT_DURABLE_BACKGROUND;
-  if (raw == null) return true;
-  const v = raw.trim().toLowerCase();
-  return !(v === "0" || v === "false" || v === "no" || v === "off");
-}
-
-/**
- * Emit a SECOND Netlify function for `app` whose name ends in `-background`,
- * re-exporting the SAME `main.mjs` handler bundle. Netlify invokes any function
- * with `config.background: true` asynchronously (202 immediately, up to 15-min
- * budget), which is exactly what the durable-background chat dispatch
- * (`fireInternalDispatch` → the function's default url) needs.
- *
- * DOC-CORRECT DEFAULT-URL APPROACH (mirrors the single-template emit in
- * deploy/build.ts): the function declares NO custom `config.path`, so it keeps
- * its DEFAULT url `/.netlify/functions/<app>-agent-background`. The `<app>-server`
- * function's catch-all already excludes `/.netlify/*`, so that default-url
- * namespace is NEVER shadowed by the synchronous function — no overlapping
- * `config.path` and no catch-all patch are needed. The foreground dispatches to
- * that default url (`resolveAgentChatProcessRunDispatchPath` resolves the per-app
- * name from `AGENT_NATIVE_WORKSPACE_APP_ID`); `fireInternalDispatch` strips the
- * app base path for `/.netlify/*` targets so the request reaches the host-root
- * function url. The entry then REWRITES the incoming pathname to the
- * base-path-prefixed `_process-run` route before delegating to the Nitro router.
- *
- * It shares the same bundle (`includedFiles: ["**"]`) so `A2A_SECRET`, the DB
- * URL, and the rest of the env/bundle are present. A prior attempt gave the
- * function a custom `config.path` (the framework route) that overlapped the
- * synchronous `<app>-server` catch-all; that path was not honored as a route in
- * prod (probe → 404). The default url is the doc-correct fix.
- *
- * Safety net: if the dispatch fast-fails the foreground degrades to an inline
- * 40s synchronous run (see production-agent.ts).
- */
-function emitNetlifyBackgroundFunction(
-  workspaceRoot: string,
-  app: string,
-  srcServerDir: string,
-  workspaceApps: WorkspaceAppManifestEntry[],
-): void {
-  // Name MUST end in `-background` (Netlify async convention + the runtime guard
-  // reads the -background Lambda-name suffix as a fallback). It is reached at its
-  // DEFAULT url /.netlify/functions/<app>-agent-background.
-  const backgroundName = `${app}-agent-background`;
-  const dest = path.join(netlifyFunctionsDir(workspaceRoot), backgroundName);
-  fs.rmSync(dest, { recursive: true, force: true });
-  copyDir(srcServerDir, dest);
-
-  const basePath = `/${app}`;
-  const workspaceAppAudience = workspaceAppAudienceForApp(workspaceApps, app);
-  const workspaceAppRouteAccess = workspaceAppRouteAccessForApp(
-    workspaceApps,
-    app,
-  );
-  // The Nitro router for this app expects the base-path-prefixed framework route.
-  // The function is reached at its default url, so the entry rewrites the
-  // incoming pathname to `/<app>/_agent-native/agent-chat/_process-run`.
-  const processRunPath = `${basePath}${AGENT_CHAT_PROCESS_RUN_PATH}`;
-  const server = `// Mark this isolate as the durable background runtime BEFORE the handler bundle
-// is imported, so isInBackgroundFunctionRuntime() reliably returns true in this
-// function (the deployed Lambda name is not guaranteed to end in -background). A
-// globalThis flag (NOT process.env) avoids the no-env-mutation guard and carries
-// no cross-request state.
-globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true;
-
-const basePath = ${JSON.stringify(basePath)};
-// The base-path-prefixed framework route the Nitro router dispatches to.
-const PROCESS_RUN_PATH = ${JSON.stringify(processRunPath)};
-
-function setBasePathEnv() {
-  const processRef = globalThis.process ??= { env: {} };
-  processRef.env ??= {};
-  Object.assign(processRef.env, {
-    AGENT_NATIVE_WORKSPACE: "1",
-    AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
-    APP_BASE_PATH: basePath,
-    AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
-    AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
-    AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
-    VITE_AGENT_NATIVE_WORKSPACE: "1",
-    VITE_AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
-    VITE_APP_BASE_PATH: basePath,
-    VITE_AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
-    VITE_AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
-    VITE_AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
-    VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON: ${JSON.stringify(JSON.stringify(workspaceApps))},
-    ${JSON.stringify(WORKSPACE_APPS_ENV_KEY)}: ${JSON.stringify(JSON.stringify(workspaceApps))},
-  });
-}
-
-setBasePathEnv();
-
-let cachedHandler;
-
-// Reached at the DEFAULT url /.netlify/functions/${backgroundName}; REWRITE the
-// incoming pathname to the base-path-prefixed _process-run route so the Nitro
-// router runs the plugin. Method, ALL headers (the HMAC Authorization: Bearer
-// MUST survive) and the body are preserved.
-export default async function handler(request) {
-  setBasePathEnv();
-  cachedHandler ??= (await import("./main.mjs")).default;
-  const url = new URL(request.url);
-  url.pathname = PROCESS_RUN_PATH;
-  const method = request.method || "POST";
-  const hasBody = method !== "GET" && method !== "HEAD";
-  const body = hasBody ? await request.text() : undefined;
-  const rewritten = new Request(url.toString(), {
-    method,
-    headers: request.headers,
-    body,
-  });
-  return cachedHandler(rewritten);
-}
-
-export const config = {
-  name: ${JSON.stringify(`${app} agent background handler`)},
-  generator: "agent-native workspace deploy",
-  // background: true → async invoke (202, 15-min budget). NO custom path: the
-  // function keeps its default url /.netlify/functions/${backgroundName}, which
-  // the <app>-server catch-all never shadows (it excludes /.netlify/*).
-  background: true,
-  nodeBundler: "none",
-  includedFiles: ["**"],
-  preferStatic: false,
-};
-`;
-  // Remove the original Nitro entry (server.mjs) so only our background entry
-  // is the function entrypoint, mirroring patchNetlifyFunctionEntry.
-  fs.rmSync(path.join(dest, "server.mjs"), { force: true });
-  fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), server);
-  console.log(
-    `[workspace-deploy] Emitted durable-background function "${backgroundName}" ` +
-      `for app "${app}" with config { background:true } and NO custom path — ` +
-      `reachable at its default url /.netlify/functions/${backgroundName} ` +
-      `(rewrites to ${processRunPath}). REQUIRES real-deploy verification of ` +
-      `Netlify async (202) invocation — see docs/design/durable-agent-runs.md.`,
-  );
-}
-
-function patchNetlifyFunctionEntry(
-  functionDir: string,
-  app: string,
-  workspaceApps: WorkspaceAppManifestEntry[],
-  staticDir: string,
-): void {
-  const serverPath = path.join(functionDir, "server.mjs");
-  if (!fs.existsSync(serverPath)) return;
-
-  const basePath = `/${app}`;
-  const workspaceAppAudience = workspaceAppAudienceForApp(workspaceApps, app);
-  const workspaceAppRouteAccess = workspaceAppRouteAccessForApp(
-    workspaceApps,
-    app,
-  );
-  const pathConfig =
-    app === "dispatch"
-      ? ["/_agent-native/*", "/.well-known/*", `${basePath}/*`]
-      : [basePath, `${basePath}/*`];
-  const normalizeBasePathHelper =
-    app === "dispatch"
-      ? ""
-      : `
-function normalizeBasePathArgs(args) {
-  const request = args[0];
-  if (!request || typeof request.url !== "string" || typeof Request !== "function") {
-    return args;
-  }
-  const url = new URL(request.url);
-  if (url.pathname === basePath || url.pathname === \`\${basePath}/\`) {
-    url.pathname = \`\${basePath}//\`;
-    return [new Request(url, request), ...args.slice(1)];
-  }
-  return args;
-}
-`;
-  const handlerArgs =
-    app === "dispatch" ? "...args" : "...normalizeBasePathArgs(args)";
-  const server = `const basePath = ${JSON.stringify(basePath)};
-
-function setBasePathEnv() {
-  const processRef = globalThis.process ??= { env: {} };
-  processRef.env ??= {};
-  Object.assign(processRef.env, {
-    AGENT_NATIVE_WORKSPACE: "1",
-    AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
-    APP_BASE_PATH: basePath,
-    AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
-    AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
-    AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
-    VITE_AGENT_NATIVE_WORKSPACE: "1",
-    VITE_AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
-    VITE_APP_BASE_PATH: basePath,
-    VITE_AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
-    VITE_AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
-    VITE_AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
-    VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON: ${JSON.stringify(JSON.stringify(workspaceApps))},
-    ${JSON.stringify(WORKSPACE_APPS_ENV_KEY)}: ${JSON.stringify(JSON.stringify(workspaceApps))},
-  });
-}
-
-setBasePathEnv();
-${normalizeBasePathHelper}
-
-let cachedHandler;
-
-export default async function handler(...args) {
-  setBasePathEnv();
-  cachedHandler ??= (await import("./main.mjs")).default;
-  return cachedHandler(${handlerArgs});
-}
-
-export const config = {
-  name: ${JSON.stringify(`${app} server handler`)},
-  generator: "agent-native workspace deploy",
-  path: ${JSON.stringify(pathConfig)},
-  nodeBundler: "none",
-  includedFiles: ["**"],
-  excludedPath: ${JSON.stringify(
-    netlifyFunctionExcludedPaths(app, staticDir),
-    null,
-    2,
-  )
-    .split("\n")
-    .join("\n  ")},
-  preferStatic: false,
-};
-`;
-  fs.rmSync(serverPath, { force: true });
-  fs.writeFileSync(path.join(functionDir, `${app}-server.mjs`), server);
-}
-
-function patchVercelFunctionEntry(
-  functionDir: string,
-  app: string,
-  workspaceApps: WorkspaceAppManifestEntry[],
-): void {
-  const entryPath = path.join(functionDir, "index.mjs");
-  if (!fs.existsSync(entryPath)) return;
-
-  const mainPath = path.join(functionDir, "main.mjs");
-  fs.rmSync(mainPath, { force: true });
-  fs.renameSync(entryPath, mainPath);
-
-  const basePath = `/${app}`;
-  const workspaceAppAudience = workspaceAppAudienceForApp(workspaceApps, app);
-  const workspaceAppRouteAccess = workspaceAppRouteAccessForApp(
-    workspaceApps,
-    app,
-  );
-  const entry = `const basePath = ${JSON.stringify(basePath)};
-
-function setBasePathEnv() {
-  const processRef = globalThis.process ??= { env: {} };
-  processRef.env ??= {};
-  Object.assign(processRef.env, {
-    AGENT_NATIVE_WORKSPACE: "1",
-    AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
-    APP_BASE_PATH: basePath,
-    AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
-    AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
-    AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
-    VITE_AGENT_NATIVE_WORKSPACE: "1",
-    VITE_AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
-    VITE_APP_BASE_PATH: basePath,
-    VITE_AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
-    VITE_AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
-    VITE_AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
-    VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON: ${JSON.stringify(JSON.stringify(workspaceApps))},
-    ${JSON.stringify(WORKSPACE_APPS_ENV_KEY)}: ${JSON.stringify(JSON.stringify(workspaceApps))},
-  });
-}
-
-function normalizeBasePathArgs(args) {
-  const request = args[0];
-  if (!request) return args;
-
-  if (typeof Request === "function" && request instanceof Request) {
-    const url = new URL(request.url);
-    if (url.pathname === basePath || url.pathname === \`\${basePath}/\`) {
-      url.pathname = \`\${basePath}//\`;
-      return [new Request(url, request), ...args.slice(1)];
-    }
-    return args;
-  }
-
-  if (typeof request.url !== "string") return args;
-  const url = new URL(request.url, "http://agent-native.local");
-  if (url.pathname === basePath || url.pathname === \`\${basePath}/\`) {
-    request.url = \`\${basePath}//\${url.search}\`;
-  }
-  return args;
-}
-
-setBasePathEnv();
-
-let cachedHandler;
-
-export default async function handler(...args) {
-  setBasePathEnv();
-  cachedHandler ??= (await import("./main.mjs")).default;
-  return cachedHandler(...normalizeBasePathArgs(args));
-}
-`;
-  fs.writeFileSync(entryPath, entry);
-}
-
-function netlifyFunctionExcludedPaths(
-  app: string,
-  staticDir: string,
-): string[] {
-  return [
-    "/.netlify/*",
-    `/${app}/assets/*`,
-    ...netlifyPublicRootAssetPaths(app, staticDir),
-  ];
-}
-
-function netlifyPublicRootAssetPaths(app: string, staticDir: string): string[] {
-  if (!fs.existsSync(staticDir)) return [];
-  return fs
-    .readdirSync(staticDir, { withFileTypes: true })
-    .filter((entry) => entry.isFile())
-    .map((entry) => entry.name)
-    .filter((name) => {
-      const ext = path.extname(name).slice(1).toLowerCase();
-      return NETLIFY_PUBLIC_ASSET_EXTENSIONS.has(ext);
-    })
-    .sort()
-    .map((name) => `/${app}/${encodeURI(name)}`);
-}
-
-function netlifyFunctionsDir(workspaceRoot: string): string {
-  return path.join(workspaceRoot, ".netlify", "functions-internal");
-}
-
-function cleanAppBuildOutputs(appDir: string): void {
-  for (const name of ["dist", ".output", "build"]) {
-    fs.rmSync(path.join(appDir, name), { recursive: true, force: true });
-  }
-  fs.rmSync(path.join(appDir, ".netlify", "functions-internal"), {
-    recursive: true,
-    force: true,
-  });
-  fs.rmSync(path.join(appDir, ".vercel", "output"), {
-    recursive: true,
-    force: true,
-  });
-}
-
-function appUsesNetlifyUnpooledDatabaseUrl(appDir: string): boolean {
-  const netlifyPath = path.join(appDir, "netlify.toml");
-  if (!fs.existsSync(netlifyPath)) return false;
-  try {
-    return fs
-      .readFileSync(netlifyPath, "utf-8")
-      .includes("NETLIFY_DATABASE_URL_UNPOOLED");
-  } catch {
-    return false;
-  }
-}
-
-function writeWorkspaceAppManifests(
-  workspaceRoot: string,
-  distDir: string,
-  apps: string[],
-  workspaceApps: WorkspaceAppManifestEntry[],
-  preset: WorkspaceDeployPreset,
-): void {
-  const manifest = JSON.stringify(
-    {
-      version: 1,
-      apps: workspaceApps,
-    },
-    null,
-    2,
-  );
-
-  const targets =
-    preset === "netlify"
-      ? apps.map((app) =>
-          path.join(
-            netlifyFunctionsDir(workspaceRoot),
-            `${app}-server`,
-            WORKSPACE_APPS_MANIFEST_DIR,
-            WORKSPACE_APPS_MANIFEST_FILE,
-          ),
-        )
-      : preset === "vercel"
-        ? apps.map((app) =>
-            path.join(
-              workspaceRoot,
-              VERCEL_OUTPUT_DIR,
-              "functions",
-              `${app}-server.func`,
-              WORKSPACE_APPS_MANIFEST_DIR,
-              WORKSPACE_APPS_MANIFEST_FILE,
-            ),
-          )
-        : apps.map((app) =>
-            path.join(
-              distDir,
-              app,
-              WORKSPACE_APPS_MANIFEST_DIR,
-              WORKSPACE_APPS_MANIFEST_FILE,
-            ),
-          );
-
-  for (const target of targets) {
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, `${manifest}\n`);
-  }
-}
-
-function readWorkspaceAppManifest(
-  workspaceRoot: string,
-  apps: string[],
-): WorkspaceAppManifestEntry[] {
-  const explicitApps = readExistingWorkspaceAppManifest(workspaceRoot);
-
-  return apps
-    .map((app) => {
-      const appDir = path.join(workspaceRoot, "apps", app);
-      const pkg = readPackageJson(path.join(appDir, "package.json"));
-      const appPath = `/${app}`;
-      const explicit = explicitApps.get(app);
-      const url =
-        normalizeWorkspaceAppUrl(explicit?.url) ?? workspaceAppUrl(appPath);
-      const audience =
-        workspaceAppAudienceFromPackageJson(pkg) ??
-        explicit?.audience ??
-        DEFAULT_WORKSPACE_APP_AUDIENCE;
-      const packageRouteAccess = workspaceAppRouteAccessFromPackageJson(pkg);
-      // Prefer the package.json value whenever the field was set — including
-      // an explicit empty array, which is how a per-app package.json signals
-      // "clear any previously-published manifest override." Falling back on
-      // length > 0 would silently keep the explicit override even after the
-      // app owner blanked their list.
-      const publicPaths =
-        packageRouteAccess.publicPaths ?? explicit?.publicPaths ?? [];
-      const protectedPaths =
-        packageRouteAccess.protectedPaths ?? explicit?.protectedPaths ?? [];
-      return {
-        id: app,
-        name: pkg?.displayName || titleCase(app),
-        description: pkg?.description || "",
-        path: appPath,
-        ...(url ? { url } : {}),
-        isDispatch: app === "dispatch",
-        audience,
-        publicPaths,
-        protectedPaths,
-      };
-    })
-    .sort((a, b) => {
-      if (a.id === "dispatch") return -1;
-      if (b.id === "dispatch") return 1;
-      return a.name.localeCompare(b.name);
-    });
-}
-
-function readExistingWorkspaceAppManifest(
-  workspaceRoot: string,
-): Map<string, WorkspaceAppManifestOverride> {
-  const fromEnv = parseWorkspaceAppsJson(process.env[WORKSPACE_APPS_ENV_KEY]);
-  const fromFile =
-    readWorkspaceAppsFromFile(
-      path.join(
-        workspaceRoot,
-        WORKSPACE_APPS_MANIFEST_DIR,
-        WORKSPACE_APPS_MANIFEST_FILE,
-      ),
-    ) ??
-    readWorkspaceAppsFromFile(
-      path.join(workspaceRoot, WORKSPACE_APPS_MANIFEST_FILE),
-    );
-  const apps = fromEnv ?? fromFile ?? [];
-  return new Map(apps.map((app) => [app.id, app]));
-}
-
-function parseWorkspaceAppsJson(
-  raw: string | undefined,
-): WorkspaceAppManifestOverride[] | null {
-  if (!raw) return null;
-  try {
-    return parseWorkspaceAppsManifest(JSON.parse(raw));
-  } catch {
-    return null;
-  }
-}
-
-function readWorkspaceAppsFromFile(
-  file: string,
-): WorkspaceAppManifestOverride[] | null {
-  if (!fs.existsSync(file)) return null;
-  return parseWorkspaceAppsManifest(readPackageJson(file));
-}
-
-function parseWorkspaceAppsManifest(
-  parsed: any,
-): WorkspaceAppManifestOverride[] | null {
-  const rawApps = Array.isArray(parsed?.apps)
-    ? parsed.apps
-    : Array.isArray(parsed)
-      ? parsed
-      : null;
-  if (!rawApps) return null;
-
-  const apps = (rawApps as unknown[])
-    .map((entry) => {
-      if (!entry || typeof entry !== "object") return null;
-      const e = entry as Record<string, unknown>;
-      const id = typeof e.id === "string" ? e.id.trim() : "";
-      if (!id) return null;
-      const url = normalizeWorkspaceAppUrl(e.url);
-      const audience =
-        e.audience === undefined
-          ? undefined
-          : normalizeWorkspaceAppAudience(e.audience);
-      const publicPaths = normalizeWorkspaceAppPathList(e.publicPaths);
-      const protectedPaths = normalizeWorkspaceAppPathList(e.protectedPaths);
-      return {
-        id,
-        ...(url ? { url } : {}),
-        ...(audience ? { audience } : {}),
-        ...(publicPaths.length > 0 ? { publicPaths } : {}),
-        ...(protectedPaths.length > 0 ? { protectedPaths } : {}),
-      };
-    })
-    .filter((app): app is NonNullable<typeof app> => !!app);
-
-  return apps.length ? apps : null;
-}
-
-function workspaceBaseUrl(): string | null {
-  const gatewayOrigin =
-    process.env.WORKSPACE_GATEWAY_URL || process.env.VITE_WORKSPACE_GATEWAY_URL;
-  const publicGatewayOrigin = normalizeOrigin(gatewayOrigin);
-  const gatewayFallback =
-    publicGatewayOrigin && !isLoopbackOrigin(publicGatewayOrigin)
-      ? gatewayOrigin
-      : null;
-  return (
-    process.env.APP_URL ||
-    process.env.WORKSPACE_OAUTH_ORIGIN ||
-    process.env.VITE_WORKSPACE_OAUTH_ORIGIN ||
-    process.env.URL ||
-    process.env.DEPLOY_URL ||
-    process.env.BETTER_AUTH_URL ||
-    gatewayFallback ||
-    gatewayOrigin ||
-    null
-  );
-}
-
-function normalizeOrigin(value: string | null | undefined): string | undefined {
-  if (!value) return undefined;
-  try {
-    return new URL(value).origin;
-  } catch {
-    return undefined;
-  }
-}
-
-function isLoopbackOrigin(origin: string | undefined): boolean {
-  if (!origin) return false;
-  try {
-    const host = new URL(origin).hostname.toLowerCase();
-    return (
-      host === "localhost" ||
-      host === "127.0.0.1" ||
-      host === "[::1]" ||
-      host === "::1"
-    );
-  } catch {
-    return false;
-  }
-}
-
-function workspaceOAuthOrigin(
-  workspaceGatewayUrl: string | null,
-): string | undefined {
-  // Explicit overrides (env vars set by the operator) win even if they happen
-  // to be loopback — that's a deliberate dev-against-prod choice.
-  // The gateway-URL fallback, however, is auto-resolved and would silently
-  // send users to localhost if the configured gateway is loopback in a
-  // production deploy. Strip loopback there so OAuth fails loudly instead.
-  const gatewayFallback = normalizeOrigin(workspaceGatewayUrl);
-  return (
-    normalizeOrigin(process.env.VITE_WORKSPACE_OAUTH_ORIGIN) ||
-    normalizeOrigin(process.env.WORKSPACE_OAUTH_ORIGIN) ||
-    normalizeOrigin(process.env.APP_URL) ||
-    normalizeOrigin(process.env.BETTER_AUTH_URL) ||
-    normalizeOrigin(process.env.URL) ||
-    normalizeOrigin(process.env.DEPLOY_URL) ||
-    (isLoopbackOrigin(gatewayFallback) ? undefined : gatewayFallback)
-  );
-}
-
-function workspaceAppUrl(appPath: string): string | undefined {
-  const base = workspaceBaseUrl();
-  if (!base) return undefined;
-  try {
-    return new URL(appPath, `${base.replace(/\/$/, "")}/`).toString();
-  } catch {
-    return undefined;
-  }
-}
-
-function normalizeWorkspaceAppUrl(value: unknown): string | undefined {
-  if (typeof value !== "string" || !value.trim()) return undefined;
-  try {
-    return new URL(value.trim()).toString().replace(/\/$/, "");
-  } catch {
-    return undefined;
-  }
-}
-
-function readPackageJson(file: string): Record<string, any> | null {
-  try {
-    return JSON.parse(fs.readFileSync(file, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function titleCase(value: string): string {
-  return value
-    .split(/[-_\s]+/)
-    .filter(Boolean)
-    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-    .join(" ");
-}
-
-function parsePresetArg(args: string[]): WorkspaceDeployPreset | null {
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--preset" && args[i + 1]) {
-      return normalizePreset(args[i + 1]);
-    }
-    if (arg.startsWith("--preset=")) {
-      return normalizePreset(arg.slice("--preset=".length));
-    }
-  }
-  return null;
-}
-
-function resolvePreset(
-  optionPreset: WorkspaceDeployPreset | undefined,
-  args: string[],
-): WorkspaceDeployPreset {
-  return (
-    optionPreset ??
-    parsePresetArg(args) ??
-    normalizePreset(process.env.NITRO_PRESET) ??
-    "cloudflare_pages"
-  );
-}
-
-function assertWorkspaceDeployProductionEnv(opts: {
-  buildOnly: boolean;
-  preset: WorkspaceDeployPreset;
-}): void {
-  if (!isProductionWorkspaceDeploy(opts)) return;
-  if (process.env.A2A_SECRET?.trim()) return;
-  const providerHint =
-    opts.preset === "netlify"
-      ? ' For Netlify, one option is: netlify env:set A2A_SECRET "$(openssl rand -hex 32)".'
-      : "";
-  throw new Error(
-    [
-      "A2A_SECRET is required for production workspace deploys.",
-      "Workspace Slack, webhook, and cross-app A2A work resumes through signed background processors; without A2A_SECRET those production routes return 503.",
-      `Set A2A_SECRET in your deploy provider and redeploy.${providerHint}`,
-      "For local artifact checks, run agent-native deploy --build-only outside the deploy provider environment.",
-    ].join(" "),
-  );
-}
-
-function isProductionWorkspaceDeploy(opts: {
-  buildOnly: boolean;
-  preset: WorkspaceDeployPreset;
-}): boolean {
-  if (!opts.buildOnly) return true;
-  if (
-    opts.preset === "netlify" &&
-    process.env.NETLIFY === "true" &&
-    process.env.NETLIFY_LOCAL !== "true"
-  ) {
-    return true;
-  }
-  if (opts.preset === "cloudflare_pages" && process.env.CF_PAGES === "1") {
-    return true;
-  }
-  if (opts.preset === "vercel" && process.env.VERCEL === "1") {
-    return true;
-  }
-  return false;
-}
-
-function normalizePreset(
-  value: string | undefined,
-): WorkspaceDeployPreset | null {
-  if (!value) return null;
-  if (value === "cloudflare_pages" || value === "cloudflare-pages") {
-    return "cloudflare_pages";
-  }
-  if (value === "netlify") return "netlify";
-  if (value === "vercel") return "vercel";
-  throw new Error(
-    `Unsupported workspace deploy preset "${value}". Supported presets: cloudflare_pages, netlify, vercel.`,
-  );
-}
-
-function moduleIdent(app: string): string {
-  return "app_" + app.replace(/[^a-zA-Z0-9_]/g, "_");
-}
-
-function workspaceAppAudienceForApp(
-  workspaceApps: WorkspaceAppManifestEntry[],
-  app: string,
-): WorkspaceAppAudience {
-  return (
-    workspaceApps.find((entry) => entry.id === app)?.audience ??
-    DEFAULT_WORKSPACE_APP_AUDIENCE
-  );
-}
-
-function workspaceAppRouteAccessForApp(
-  workspaceApps: WorkspaceAppManifestEntry[],
-  app: string,
-): WorkspaceAppRouteAccess {
-  const entry = workspaceApps.find((candidate) => candidate.id === app);
-  return {
-    publicPaths: entry?.publicPaths ?? [],
-    protectedPaths: entry?.protectedPaths ?? [],
-  };
-}
-
-function compareWorkspaceAppIds(a: string, b: string): number {
-  if (a === "dispatch") return -1;
-  if (b === "dispatch") return 1;
-  return a.localeCompare(b);
-}
-
-function copyDir(src: string, dest: string): void {
-  fs.mkdirSync(dest, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const s = path.join(src, entry.name);
-    const d = path.join(dest, entry.name);
-    if (entry.isSymbolicLink()) {
-      try {
-        const target = fs.readlinkSync(s);
-        fs.symlinkSync(target, d);
-      } catch {
-        fs.copyFileSync(s, d);
-      }
-    } else if (entry.isDirectory()) {
-      copyDir(s, d);
-    } else {
-      fs.copyFileSync(s, d);
-    }
-  }
-}
+/**
+ * `agent-native deploy` — build and deploy every app in a workspace to a
+ * single origin. Each app is served from `/<app-name>/*`, so:
+ *
+ *   https://your-agents.com/mail/*       → apps/mail
+ *   https://your-agents.com/calendar/*   → apps/calendar
+ *
+ * Benefits of same-origin deploy:
+ *   - Shared auth cookie → log in once, every app is signed in
+ *   - Cross-app A2A is a same-origin fetch (no CORS, no JWT for siblings)
+ *   - One DNS record, one TLS cert, one CDN cache
+ *
+ * Per-app independent deploy is still supported — just cd into the app and
+ * run `agent-native build` as before. This orchestrator is for teams that
+ * want the whole workspace behind one domain.
+ */
+import { execFileSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+import { AGENT_CHAT_PROCESS_RUN_PATH } from "../agent/durable-background.js";
+import { findWorkspaceRoot } from "../scripts/utils.js";
+import {
+  DEFAULT_WORKSPACE_APP_AUDIENCE,
+  normalizeWorkspaceAppAudience,
+  normalizeWorkspaceAppPathList,
+  workspaceAppAudienceFromPackageJson,
+  workspaceAppRouteAccessFromPackageJson,
+  type WorkspaceAppRouteAccess,
+  type WorkspaceAppAudience,
+} from "../shared/workspace-app-audience.js";
+import { DISPATCH_WORKSPACE_ROOT_REDIRECTS } from "../shared/workspace-app-id.js";
+import {
+  collectImmutableAssetPaths,
+  IMMUTABLE_ASSET_CACHE_HEADERS,
+} from "./immutable-assets.js";
+
+export type WorkspaceDeployPreset = "cloudflare_pages" | "netlify" | "vercel";
+
+const NETLIFY_WORKSPACE_STATIC_DIR = "_workspace_static";
+const NETLIFY_PUBLIC_ASSET_EXTENSIONS = new Set([
+  "avif",
+  "css",
+  "gif",
+  "ico",
+  "jpeg",
+  "jpg",
+  "js",
+  "json",
+  "map",
+  "mp4",
+  "pdf",
+  "png",
+  "svg",
+  "txt",
+  "wasm",
+  "webm",
+  "webmanifest",
+  "webp",
+  "xml",
+]);
+const WORKSPACE_APPS_ENV_KEY = "AGENT_NATIVE_WORKSPACE_APPS_JSON";
+const WORKSPACE_APPS_MANIFEST_DIR = ".agent-native";
+const WORKSPACE_APPS_MANIFEST_FILE = "workspace-apps.json";
+const VERCEL_OUTPUT_DIR = ".vercel/output";
+
+interface WorkspaceAppManifestEntry {
+  id: string;
+  name: string;
+  description: string;
+  path: string;
+  url?: string;
+  isDispatch: boolean;
+  audience: WorkspaceAppAudience;
+  publicPaths: string[];
+  protectedPaths: string[];
+}
+
+interface WorkspaceAppManifestOverride {
+  id: string;
+  url?: string;
+  audience?: WorkspaceAppAudience;
+  publicPaths?: string[];
+  protectedPaths?: string[];
+}
+
+export interface WorkspaceDeployOptions {
+  args?: string[];
+  /** Override the workspace root (defaults to walking up from cwd). */
+  workspaceRoot?: string;
+  /** Only build — don't invoke the deploy platform CLI. */
+  buildOnly?: boolean;
+  /** Target preset. Defaults to `cloudflare_pages`. */
+  preset?: WorkspaceDeployPreset;
+  /** @internal Override process execution in tests. */
+  execFile?: typeof execFileSync;
+}
+
+export async function runWorkspaceDeploy(
+  opts: WorkspaceDeployOptions = {},
+): Promise<void> {
+  const workspaceRoot =
+    opts.workspaceRoot ?? findWorkspaceRoot(process.cwd()) ?? process.cwd();
+  const appsDir = path.join(workspaceRoot, "apps");
+  if (!fs.existsSync(appsDir)) {
+    throw new Error(
+      `No apps/ directory found at ${workspaceRoot}. Run this inside an agent-native workspace.`,
+    );
+  }
+
+  const rawArgs = opts.args ?? [];
+  const args = new Set(rawArgs);
+  const buildOnly = opts.buildOnly ?? args.has("--build-only");
+
+  const apps = fs
+    .readdirSync(appsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .filter((n) => fs.existsSync(path.join(appsDir, n, "package.json")))
+    .sort(compareWorkspaceAppIds);
+
+  if (apps.length === 0) {
+    throw new Error(
+      `Workspace has no apps. Run \`agent-native add-app\` to add one.`,
+    );
+  }
+  assertNoReservedWorkspaceAppIds(apps);
+  const workspaceApps = readWorkspaceAppManifest(workspaceRoot, apps);
+
+  const preset = resolvePreset(opts.preset, rawArgs);
+  assertWorkspaceDeployProductionEnv({ buildOnly, preset });
+  const distDir = path.join(workspaceRoot, "dist");
+  const vercelOutputDir = path.join(workspaceRoot, VERCEL_OUTPUT_DIR);
+  if (preset === "vercel") {
+    fs.rmSync(vercelOutputDir, { recursive: true, force: true });
+    fs.mkdirSync(path.join(vercelOutputDir, "static"), { recursive: true });
+    fs.mkdirSync(path.join(vercelOutputDir, "functions"), {
+      recursive: true,
+    });
+  } else {
+    fs.rmSync(distDir, { recursive: true, force: true });
+    fs.mkdirSync(distDir, { recursive: true });
+  }
+
+  if (preset === "netlify") {
+    const functionsDir = netlifyFunctionsDir(workspaceRoot);
+    fs.rmSync(functionsDir, { recursive: true, force: true });
+    fs.mkdirSync(functionsDir, { recursive: true });
+  }
+
+  console.log(
+    `[workspace-deploy] Building ${apps.length} app(s) for preset=${preset}`,
+  );
+
+  const execFile = opts.execFile ?? execFileSync;
+  for (const app of apps) {
+    buildOneApp(workspaceRoot, app, preset, execFile, workspaceApps);
+    moveAppBuildIntoWorkspaceOutput(
+      workspaceRoot,
+      app,
+      preset,
+      distDir,
+      vercelOutputDir,
+      workspaceApps,
+    );
+  }
+  writeWorkspaceAppManifests(
+    workspaceRoot,
+    distDir,
+    apps,
+    workspaceApps,
+    preset,
+  );
+
+  if (preset === "netlify") {
+    writeNetlifyRedirects(distDir, apps);
+    writeNetlifyHeaders(distDir, apps);
+  } else if (preset === "vercel") {
+    writeVercelBuildConfig(vercelOutputDir, apps);
+  } else {
+    writeCloudflareRoutingManifest(distDir, apps);
+  }
+
+  if (buildOnly) {
+    const outputDir = preset === "vercel" ? vercelOutputDir : distDir;
+    console.log(
+      `\n[workspace-deploy] Build complete at ${outputDir}. Skipping publish (--build-only).`,
+    );
+    return;
+  }
+
+  console.log(`\n[workspace-deploy] Build complete. Publish with:\n`);
+  console.log(`  cd ${path.relative(process.cwd(), workspaceRoot) || "."}`);
+  if (preset === "netlify") {
+    console.log(
+      `  netlify deploy --prod --dir=dist --functions=.netlify/functions-internal\n`,
+    );
+  } else if (preset === "vercel") {
+    console.log(`  vercel deploy --prebuilt\n`);
+  } else {
+    console.log(`  wrangler pages deploy dist\n`);
+  }
+  console.log(
+    `All apps live at https://<origin>/<app-name>/*. Log in once on any app\nand the session is shared across the workspace.`,
+  );
+}
+
+function buildOneApp(
+  workspaceRoot: string,
+  app: string,
+  preset: WorkspaceDeployPreset,
+  execFile: typeof execFileSync,
+  workspaceApps: WorkspaceAppManifestEntry[],
+): void {
+  const appDir = path.join(workspaceRoot, "apps", app);
+  const workspaceAppAudience = workspaceAppAudienceForApp(workspaceApps, app);
+  const workspaceAppRouteAccess = workspaceAppRouteAccessForApp(
+    workspaceApps,
+    app,
+  );
+  const workspaceGatewayUrl =
+    process.env.VITE_WORKSPACE_GATEWAY_URL || workspaceBaseUrl();
+  const workspaceOAuthUrl = workspaceOAuthOrigin(workspaceGatewayUrl);
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    NITRO_PRESET: preset,
+    AGENT_NATIVE_WORKSPACE: "1",
+    AGENT_NATIVE_WORKSPACE_APP_ID: app,
+    VITE_AGENT_NATIVE_WORKSPACE: "1",
+    VITE_AGENT_NATIVE_WORKSPACE_APP_ID: app,
+    APP_BASE_PATH: `/${app}`,
+    VITE_APP_BASE_PATH: `/${app}`,
+    AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: workspaceAppAudience,
+    AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: JSON.stringify(
+      workspaceAppRouteAccess.publicPaths,
+    ),
+    AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: JSON.stringify(
+      workspaceAppRouteAccess.protectedPaths,
+    ),
+    VITE_AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: workspaceAppAudience,
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: JSON.stringify(
+      workspaceAppRouteAccess.publicPaths,
+    ),
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: JSON.stringify(
+      workspaceAppRouteAccess.protectedPaths,
+    ),
+    VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON: JSON.stringify(workspaceApps),
+    ...(workspaceGatewayUrl
+      ? {
+          WORKSPACE_GATEWAY_URL:
+            process.env.WORKSPACE_GATEWAY_URL || workspaceGatewayUrl,
+          VITE_WORKSPACE_GATEWAY_URL: workspaceGatewayUrl,
+          ...(workspaceOAuthUrl
+            ? { VITE_WORKSPACE_OAUTH_ORIGIN: workspaceOAuthUrl }
+            : {}),
+        }
+      : {}),
+    [WORKSPACE_APPS_ENV_KEY]: JSON.stringify(workspaceApps),
+  };
+
+  if (preset === "netlify" && appUsesNetlifyUnpooledDatabaseUrl(appDir)) {
+    env.DATABASE_URL =
+      process.env.NETLIFY_DATABASE_URL_UNPOOLED ??
+      process.env.DATABASE_URL ??
+      env.DATABASE_URL;
+  }
+
+  console.log(
+    `[workspace-deploy] Building ${app} (base=/${app}, preset=${preset})`,
+  );
+
+  cleanAppBuildOutputs(appDir);
+
+  execFile("pnpm", ["--filter", app, "build"], {
+    cwd: workspaceRoot,
+    env,
+    stdio: "inherit",
+  });
+}
+
+function moveAppBuildIntoWorkspaceOutput(
+  workspaceRoot: string,
+  app: string,
+  preset: WorkspaceDeployPreset,
+  distDir: string,
+  vercelOutputDir: string,
+  workspaceApps: WorkspaceAppManifestEntry[],
+): void {
+  const appDir = path.join(workspaceRoot, "apps", app);
+  if (preset === "vercel") {
+    copyVercelAppBuildIntoWorkspace(
+      workspaceRoot,
+      app,
+      vercelOutputDir,
+      workspaceApps,
+    );
+    return;
+  }
+
+  // Resolve the per-app build output: prefer dist/ (standard), fall back to
+  // .output/ (Nitro's default). The Cloudflare preset emits into dist/
+  // containing the worker + assets.
+  const candidates = ["dist", ".output"];
+  const src = candidates
+    .map((c) => path.join(appDir, c))
+    .find((p) => fs.existsSync(p));
+  if (!src) {
+    throw new Error(
+      `Expected ${candidates.join(" or ")} under ${appDir} but none existed. Check the app's build script.`,
+    );
+  }
+  if (preset === "netlify") {
+    const mountedSrc = path.join(src, app);
+    const staticSrc = fs.existsSync(mountedSrc) ? mountedSrc : src;
+    const target = path.join(distDir, NETLIFY_WORKSPACE_STATIC_DIR, app);
+    fs.mkdirSync(target, { recursive: true });
+    copyDir(staticSrc, target);
+    // Nitro/Vite mounted builds can contain a nested copy of public assets at
+    // dist/<app>/<app>/...; the workspace root already supplies the outer
+    // mount path, so keeping it would publish duplicate /<app>/<app> URLs.
+    fs.rmSync(path.join(target, app), { recursive: true, force: true });
+    copyNetlifyFunctionIntoWorkspace(workspaceRoot, app, workspaceApps, target);
+  } else {
+    const target = path.join(distDir, app);
+    fs.mkdirSync(target, { recursive: true });
+    copyDir(src, target);
+  }
+}
+
+function copyVercelAppBuildIntoWorkspace(
+  workspaceRoot: string,
+  app: string,
+  vercelOutputDir: string,
+  workspaceApps: WorkspaceAppManifestEntry[],
+): void {
+  const appDir = path.join(workspaceRoot, "apps", app);
+  const src = path.join(appDir, VERCEL_OUTPUT_DIR);
+  if (!fs.existsSync(src)) {
+    throw new Error(
+      `Expected Vercel output at ${src} after building ${app}. Check the app's build script and NITRO_PRESET.`,
+    );
+  }
+
+  const staticSrc = path.join(src, "static");
+  const staticDest = path.join(vercelOutputDir, "static");
+  if (fs.existsSync(staticSrc)) {
+    copyDir(staticSrc, staticDest);
+    // Nitro's Vercel preset already nests assets under baseURL. The shared
+    // deploy build also mirrors client assets under baseURL for other Nitro
+    // presets, so mounted apps can contain a duplicate /<app>/<app> copy.
+    fs.rmSync(path.join(staticDest, app, app), {
+      recursive: true,
+      force: true,
+    });
+  }
+
+  const functionSrc = path.join(src, "functions", "__server.func");
+  if (!fs.existsSync(functionSrc)) {
+    throw new Error(
+      `Expected Vercel function at ${functionSrc} after building ${app}. Check the app's build script and NITRO_PRESET.`,
+    );
+  }
+
+  const functionDest = path.join(
+    vercelOutputDir,
+    "functions",
+    `${app}-server.func`,
+  );
+  fs.rmSync(functionDest, { recursive: true, force: true });
+  copyDir(functionSrc, functionDest);
+  patchVercelFunctionEntry(functionDest, app, workspaceApps);
+}
+
+/**
+ * Write the Cloudflare Pages `_routes.json` and a dispatcher `_worker.js` at
+ * the workspace dist root so each app is reachable under /<app>/*.
+ */
+function writeCloudflareRoutingManifest(distDir: string, apps: string[]): void {
+  const dispatchFaviconAsset = apps.includes("dispatch")
+    ? dispatchRootFaviconAsset(distDir)
+    : null;
+  // _routes.json tells Cloudflare which paths are dynamic (Functions) vs
+  // static. Mark both /<app> and /<app>/* as include so every app's worker
+  // handles its root and subtree.
+  const include = apps.flatMap((a) => [`/${a}`, `/${a}/*`]).concat(["/"]);
+  if (apps.includes("dispatch")) {
+    include.push("/_agent-native/*");
+    include.push("/.well-known/*");
+    include.push(
+      ...DISPATCH_WORKSPACE_ROOT_REDIRECTS.map(([from]) => `/${from}`),
+    );
+    include.push("/apps/*");
+    if (dispatchFaviconAsset) include.push("/favicon.ico");
+  }
+  const routes = {
+    version: 1,
+    include,
+    exclude: [],
+  };
+  fs.writeFileSync(
+    path.join(distDir, "_routes.json"),
+    JSON.stringify(routes, null, 2) + "\n",
+  );
+
+  // Dispatcher worker: inspects the path and forwards to the matching
+  // per-app worker.
+  const imports = apps
+    .map((a) => `import ${moduleIdent(a)} from "./${a}/_worker.js";`)
+    .join("\n");
+  const dispatch = apps
+    .map(
+      (a) =>
+        `  if (pathname === "/${a}" || pathname.startsWith("/${a}/")) return ${moduleIdent(a)}.fetch(requestForMountedApp(request, "/${a}"), env, ctx);`,
+    )
+    .join("\n");
+  const dispatchRootFrameworkRoutes = apps.includes("dispatch")
+    ? `    if (pathname === "/_agent-native" || pathname.startsWith("/_agent-native/") || pathname === "/.well-known" || pathname.startsWith("/.well-known/")) return ${moduleIdent("dispatch")}.fetch(request, env, ctx);
+`
+    : "";
+  const dispatchRootFaviconRoute = dispatchFaviconAsset
+    ? `    if (pathname === "/favicon.ico") return Response.redirect(new URL("/dispatch/${dispatchFaviconAsset}", request.url).toString(), 302);
+`
+    : "";
+  const dispatchRootAliasRoutes = apps.includes("dispatch")
+    ? DISPATCH_WORKSPACE_ROOT_REDIRECTS.map(
+        ([from, to]) =>
+          `    if (pathname === "/${from}") return Response.redirect(new URL("/dispatch/${to}" + search, request.url).toString(), 302);`,
+      ).join("\n") + "\n"
+    : "";
+  const dispatchRootDynamicAliasRoutes = apps.includes("dispatch")
+    ? `    if (pathname.startsWith("/apps/")) return Response.redirect(new URL("/dispatch" + pathname + search, request.url).toString(), 302);
+`
+    : "";
+  const dispatchMountedRootRedirect = apps.includes("dispatch")
+    ? `    if (pathname === "/dispatch" || pathname === "/dispatch/") return Response.redirect(new URL("/dispatch/overview" + search, request.url).toString(), 302);
+`
+    : "";
+
+  const worker = `${imports}
+
+function requestForMountedApp(request, basePath) {
+  const url = new URL(request.url);
+  if (url.pathname !== basePath && url.pathname !== \`\${basePath}/\`) {
+    return request;
+  }
+  url.pathname = \`\${basePath}//\`;
+  return new Request(url, request);
+}
+
+export default {
+  async fetch(request, env, ctx) {
+    const { pathname, search } = new URL(request.url);
+${dispatchRootFrameworkRoutes}${dispatchRootFaviconRoute}${dispatchRootAliasRoutes}${dispatchRootDynamicAliasRoutes}${dispatchMountedRootRedirect}${dispatch}
+    if (pathname === "/") {
+      return Response.redirect(new URL("${cloudflareRootRedirectPath(apps)}", request.url).toString(), 302);
+    }
+    return new Response("Not found", { status: 404 });
+  },
+};
+`;
+  fs.writeFileSync(path.join(distDir, "_worker.js"), worker);
+}
+
+function cloudflareRootRedirectPath(apps: string[]): string {
+  return apps.includes("dispatch") ? "/dispatch/overview" : `/${apps[0]}/`;
+}
+
+function writeNetlifyRedirects(distDir: string, apps: string[]): void {
+  const lines: string[] = [
+    "# Generated by agent-native deploy --preset netlify",
+    "# Static app assets are stored under a safe namespace; dynamic app routes are handled by function route config.",
+  ];
+
+  if (apps.includes("dispatch")) {
+    lines.push("/_agent-native/* /.netlify/functions/dispatch-server 200");
+    lines.push("/.well-known/* /.netlify/functions/dispatch-server 200");
+    const faviconAsset = dispatchRootFaviconAsset(distDir);
+    if (faviconAsset) {
+      lines.push(`/favicon.ico /dispatch/${faviconAsset} 302`);
+    }
+  }
+
+  for (const app of apps) {
+    lines.push(...netlifyAssetRedirectsFor(app, distDir));
+  }
+
+  if (apps.includes("dispatch")) {
+    lines.push("/ /dispatch/overview 302");
+    lines.push("/dispatch /dispatch/overview 302");
+    lines.push("/dispatch/ /dispatch/overview 302");
+    for (const [from, to] of DISPATCH_WORKSPACE_ROOT_REDIRECTS) {
+      lines.push(`/${from} /dispatch/${to} 302`);
+    }
+    lines.push("/apps/* /dispatch/apps/:splat 302");
+  } else {
+    lines.push(`/ /${apps[0]}/ 302`);
+  }
+
+  fs.writeFileSync(path.join(distDir, "_redirects"), lines.join("\n") + "\n");
+}
+
+function writeNetlifyHeaders(distDir: string, apps: string[]): void {
+  const blocks = apps.flatMap((app) => {
+    const staticDir = path.join(distDir, NETLIFY_WORKSPACE_STATIC_DIR, app);
+    return collectImmutableAssetPaths(staticDir).flatMap((assetPath) => [
+      netlifyHeaderBlock(`/${app}${assetPath}`),
+      netlifyHeaderBlock(`/${NETLIFY_WORKSPACE_STATIC_DIR}/${app}${assetPath}`),
+    ]);
+  });
+
+  if (blocks.length === 0) return;
+  fs.writeFileSync(path.join(distDir, "_headers"), blocks.join("\n\n") + "\n");
+}
+
+function netlifyHeaderBlock(pathname: string): string {
+  return [
+    pathname,
+    ...Object.entries(IMMUTABLE_ASSET_CACHE_HEADERS).map(
+      ([name, value]) => `  ${name}: ${value}`,
+    ),
+  ].join("\n");
+}
+
+function writeVercelBuildConfig(outputDir: string, apps: string[]): void {
+  const routes: Array<Record<string, any>> = [
+    ...vercelImmutableAssetHeaderRoutes(outputDir, apps),
+    { handle: "filesystem" },
+  ];
+
+  if (apps.includes("dispatch")) {
+    routes.push(
+      { src: "/_agent-native", dest: "/dispatch-server" },
+      { src: "/_agent-native/(.*)", dest: "/dispatch-server" },
+      { src: "/\\.well-known", dest: "/dispatch-server" },
+      { src: "/\\.well-known/(.*)", dest: "/dispatch-server" },
+    );
+
+    const faviconAsset = dispatchRootFaviconAsset(
+      path.join(outputDir, "static"),
+    );
+    if (faviconAsset) {
+      routes.push(vercelRedirect("/favicon.ico", `/dispatch/${faviconAsset}`));
+    }
+
+    routes.push(
+      vercelRedirect("/", "/dispatch/overview"),
+      vercelRedirect("/dispatch", "/dispatch/overview"),
+      vercelRedirect("/dispatch/", "/dispatch/overview"),
+    );
+    for (const [from, to] of DISPATCH_WORKSPACE_ROOT_REDIRECTS) {
+      routes.push(vercelRedirect(`/${from}`, `/dispatch/${to}`));
+    }
+    routes.push(vercelRedirect("/apps/(.*)", "/dispatch/apps/$1"));
+  } else {
+    routes.push(vercelRedirect("/", `/${apps[0]}/`));
+  }
+
+  for (const app of apps) {
+    if (app !== "dispatch") {
+      routes.push({ src: `/${app}`, dest: `/${app}-server` });
+    }
+    routes.push({ src: `/${app}/(.*)`, dest: `/${app}-server` });
+  }
+
+  const config = {
+    version: 3,
+    routes,
+  };
+  fs.writeFileSync(
+    path.join(outputDir, "config.json"),
+    JSON.stringify(config, null, 2) + "\n",
+  );
+}
+
+function vercelImmutableAssetHeaderRoutes(
+  outputDir: string,
+  apps: string[],
+): Array<Record<string, any>> {
+  return apps.flatMap((app) => {
+    const staticDir = path.join(outputDir, "static", app);
+    return collectImmutableAssetPaths(staticDir).map((assetPath) => ({
+      src: vercelRouteSrc(`/${app}${assetPath}`),
+      headers: IMMUTABLE_ASSET_CACHE_HEADERS,
+      continue: true,
+    }));
+  });
+}
+
+function vercelRouteSrc(pathname: string): string {
+  return pathname.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function vercelRedirect(src: string, location: string): Record<string, any> {
+  return {
+    src,
+    status: 302,
+    headers: { Location: location },
+  };
+}
+
+function netlifyAssetRedirectsFor(app: string, distDir: string): string[] {
+  const from = `/${app}`;
+  const to = `/${NETLIFY_WORKSPACE_STATIC_DIR}/${app}`;
+  return [
+    `${from}/assets/* ${to}/assets/:splat 200`,
+    ...netlifyPublicRootAssetPaths(
+      app,
+      path.join(distDir, NETLIFY_WORKSPACE_STATIC_DIR, app),
+    ).map((assetPath) => {
+      const assetName = assetPath.slice(from.length + 1);
+      return `${assetPath} ${to}/${assetName} 200`;
+    }),
+  ];
+}
+
+function dispatchRootFaviconAsset(distDir: string): string | null {
+  for (const asset of ["favicon.ico", "favicon.svg", "favicon.png"]) {
+    if (workspaceAppAssetExists(distDir, "dispatch", asset)) return asset;
+  }
+  return null;
+}
+
+function workspaceAppAssetExists(
+  distDir: string,
+  app: string,
+  asset: string,
+): boolean {
+  return [
+    path.join(distDir, NETLIFY_WORKSPACE_STATIC_DIR, app, asset),
+    path.join(distDir, app, app, asset),
+    path.join(distDir, app, asset),
+  ].some((candidate) => fs.existsSync(candidate));
+}
+
+const RESERVED_WORKSPACE_APP_IDS = new Set([
+  "_agent-native",
+  "_workspace_static",
+  "netlify",
+  ...DISPATCH_WORKSPACE_ROOT_REDIRECTS.map(([from]) => from),
+]);
+
+function assertNoReservedWorkspaceAppIds(apps: string[]): void {
+  const conflicts = apps.filter(
+    (app) => app !== "dispatch" && RESERVED_WORKSPACE_APP_IDS.has(app),
+  );
+  if (conflicts.length === 0) return;
+  throw new Error(
+    `Workspace app id ${conflicts.map((id) => `"${id}"`).join(", ")} conflicts with reserved workspace routes. Choose a different app id.`,
+  );
+}
+
+function copyNetlifyFunctionIntoWorkspace(
+  workspaceRoot: string,
+  app: string,
+  workspaceApps: WorkspaceAppManifestEntry[],
+  staticDir: string,
+): void {
+  const appDir = path.join(workspaceRoot, "apps", app);
+  const src = path.join(appDir, ".netlify", "functions-internal", "server");
+  if (!fs.existsSync(src)) {
+    throw new Error(
+      `Expected Netlify function at ${src} after building ${app}. Check the app's build script and NITRO_PRESET.`,
+    );
+  }
+
+  const dest = path.join(netlifyFunctionsDir(workspaceRoot), `${app}-server`);
+  fs.rmSync(dest, { recursive: true, force: true });
+  copyDir(src, dest);
+  patchNetlifyFunctionEntry(dest, app, workspaceApps, staticDir);
+
+  // Durable background agent runs (default-ON; opt out with a falsy
+  // AGENT_CHAT_DURABLE_BACKGROUND). Additive ONLY: when explicitly opted out
+  // this emits nothing and the single-function deploy is unchanged.
+  if (isDurableBackgroundDeployEnabled()) {
+    emitNetlifyBackgroundFunction(workspaceRoot, app, src, workspaceApps);
+  }
+}
+
+/**
+ * Deploy-time gate for emitting the second `-background` Netlify function. Reads
+ * the same env flag the runtime gate uses (`AGENT_CHAT_DURABLE_BACKGROUND`).
+ *
+ * DEFAULT-ON, matching the runtime gate (`isFlagEnabled` in
+ * durable-background.ts) and the single-template gate
+ * (`isDurableBackgroundDeployEnabled` in deploy/build.ts): unset/empty/unknown
+ * means enabled; an app opts OUT only with an explicit falsy value
+ * (`false`/`0`/`no`/`off`). This emits the per-app 15-min `-background` function
+ * so the chat `_process-run` dispatch lands on it with the real long budget.
+ */
+function isDurableBackgroundDeployEnabled(): boolean {
+  const raw = process.env.AGENT_CHAT_DURABLE_BACKGROUND;
+  if (raw == null) return true;
+  const v = raw.trim().toLowerCase();
+  return !(v === "0" || v === "false" || v === "no" || v === "off");
+}
+
+/**
+ * Emit a SECOND Netlify function for `app` whose name ends in `-background`,
+ * re-exporting the SAME `main.mjs` handler bundle. Netlify invokes any function
+ * with `config.background: true` asynchronously (202 immediately, up to 15-min
+ * budget), which is exactly what the durable-background chat dispatch
+ * (`fireInternalDispatch` → the function's default url) needs.
+ *
+ * DOC-CORRECT DEFAULT-URL APPROACH (mirrors the single-template emit in
+ * deploy/build.ts): the function declares NO custom `config.path`, so it keeps
+ * its DEFAULT url `/.netlify/functions/<app>-agent-background`. The `<app>-server`
+ * function's catch-all already excludes `/.netlify/*`, so that default-url
+ * namespace is NEVER shadowed by the synchronous function — no overlapping
+ * `config.path` and no catch-all patch are needed. The foreground dispatches to
+ * that default url (`resolveAgentChatProcessRunDispatchPath` resolves the per-app
+ * name from `AGENT_NATIVE_WORKSPACE_APP_ID`); `fireInternalDispatch` strips the
+ * app base path for `/.netlify/*` targets so the request reaches the host-root
+ * function url. The entry then REWRITES the incoming pathname to the
+ * base-path-prefixed `_process-run` route before delegating to the Nitro router.
+ *
+ * It shares the same bundle (`includedFiles: ["**"]`) so `A2A_SECRET`, the DB
+ * URL, and the rest of the env/bundle are present. A prior attempt gave the
+ * function a custom `config.path` (the framework route) that overlapped the
+ * synchronous `<app>-server` catch-all; that path was not honored as a route in
+ * prod (probe → 404). The default url is the doc-correct fix.
+ *
+ * Safety net: if the dispatch fast-fails the foreground degrades to an inline
+ * 40s synchronous run (see production-agent.ts).
+ */
+function emitNetlifyBackgroundFunction(
+  workspaceRoot: string,
+  app: string,
+  srcServerDir: string,
+  workspaceApps: WorkspaceAppManifestEntry[],
+): void {
+  // Name MUST end in `-background` (Netlify async convention + the runtime guard
+  // reads the -background Lambda-name suffix as a fallback). It is reached at its
+  // DEFAULT url /.netlify/functions/<app>-agent-background.
+  const backgroundName = `${app}-agent-background`;
+  const dest = path.join(netlifyFunctionsDir(workspaceRoot), backgroundName);
+  fs.rmSync(dest, { recursive: true, force: true });
+  copyDir(srcServerDir, dest);
+
+  const basePath = `/${app}`;
+  const workspaceAppAudience = workspaceAppAudienceForApp(workspaceApps, app);
+  const workspaceAppRouteAccess = workspaceAppRouteAccessForApp(
+    workspaceApps,
+    app,
+  );
+  // The Nitro router for this app expects the base-path-prefixed framework route.
+  // The function is reached at its default url, so the entry rewrites the
+  // incoming pathname to `/<app>/_agent-native/agent-chat/_process-run`.
+  const processRunPath = `${basePath}${AGENT_CHAT_PROCESS_RUN_PATH}`;
+  const server = `// Mark this isolate as the durable background runtime BEFORE the handler bundle
+// is imported, so isInBackgroundFunctionRuntime() reliably returns true in this
+// function (the deployed Lambda name is not guaranteed to end in -background). A
+// globalThis flag (NOT process.env) avoids the no-env-mutation guard and carries
+// no cross-request state.
+globalThis.__AGENT_NATIVE_BACKGROUND_RUNTIME__ = true;
+
+const basePath = ${JSON.stringify(basePath)};
+// The base-path-prefixed framework route the Nitro router dispatches to.
+const PROCESS_RUN_PATH = ${JSON.stringify(processRunPath)};
+
+function setBasePathEnv() {
+  const processRef = globalThis.process ??= { env: {} };
+  processRef.env ??= {};
+  Object.assign(processRef.env, {
+    AGENT_NATIVE_WORKSPACE: "1",
+    AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
+    APP_BASE_PATH: basePath,
+    AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
+    AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
+    AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE: "1",
+    VITE_AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
+    VITE_APP_BASE_PATH: basePath,
+    VITE_AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON: ${JSON.stringify(JSON.stringify(workspaceApps))},
+    ${JSON.stringify(WORKSPACE_APPS_ENV_KEY)}: ${JSON.stringify(JSON.stringify(workspaceApps))},
+  });
+}
+
+setBasePathEnv();
+
+let cachedHandler;
+
+// Reached at the DEFAULT url /.netlify/functions/${backgroundName}; REWRITE the
+// incoming pathname to the base-path-prefixed _process-run route so the Nitro
+// router runs the plugin. Method, ALL headers (the HMAC Authorization: Bearer
+// MUST survive) and the body are preserved.
+export default async function handler(request) {
+  setBasePathEnv();
+  cachedHandler ??= (await import("./main.mjs")).default;
+  const url = new URL(request.url);
+  url.pathname = PROCESS_RUN_PATH;
+  const method = request.method || "POST";
+  const hasBody = method !== "GET" && method !== "HEAD";
+  const body = hasBody ? await request.text() : undefined;
+  const rewritten = new Request(url.toString(), {
+    method,
+    headers: request.headers,
+    body,
+  });
+  return cachedHandler(rewritten);
+}
+
+export const config = {
+  name: ${JSON.stringify(`${app} agent background handler`)},
+  generator: "agent-native workspace deploy",
+  // background: true → async invoke (202, 15-min budget). NO custom path: the
+  // function keeps its default url /.netlify/functions/${backgroundName}, which
+  // the <app>-server catch-all never shadows (it excludes /.netlify/*).
+  background: true,
+  nodeBundler: "none",
+  includedFiles: ["**"],
+  preferStatic: false,
+};
+`;
+  // Remove the original Nitro entry (server.mjs) so only our background entry
+  // is the function entrypoint, mirroring patchNetlifyFunctionEntry.
+  fs.rmSync(path.join(dest, "server.mjs"), { force: true });
+  fs.writeFileSync(path.join(dest, `${backgroundName}.mjs`), server);
+  console.log(
+    `[workspace-deploy] Emitted durable-background function "${backgroundName}" ` +
+      `for app "${app}" with config { background:true } and NO custom path — ` +
+      `reachable at its default url /.netlify/functions/${backgroundName} ` +
+      `(rewrites to ${processRunPath}). REQUIRES real-deploy verification of ` +
+      `Netlify async (202) invocation — see docs/design/durable-agent-runs.md.`,
+  );
+}
+
+function patchNetlifyFunctionEntry(
+  functionDir: string,
+  app: string,
+  workspaceApps: WorkspaceAppManifestEntry[],
+  staticDir: string,
+): void {
+  const serverPath = path.join(functionDir, "server.mjs");
+  if (!fs.existsSync(serverPath)) return;
+
+  const basePath = `/${app}`;
+  const workspaceAppAudience = workspaceAppAudienceForApp(workspaceApps, app);
+  const workspaceAppRouteAccess = workspaceAppRouteAccessForApp(
+    workspaceApps,
+    app,
+  );
+  const pathConfig =
+    app === "dispatch"
+      ? ["/_agent-native/*", "/.well-known/*", `${basePath}/*`]
+      : [basePath, `${basePath}/*`];
+  const normalizeBasePathHelper =
+    app === "dispatch"
+      ? ""
+      : `
+function normalizeBasePathArgs(args) {
+  const request = args[0];
+  if (!request || typeof request.url !== "string" || typeof Request !== "function") {
+    return args;
+  }
+  const url = new URL(request.url);
+  if (url.pathname === basePath || url.pathname === \`\${basePath}/\`) {
+    url.pathname = \`\${basePath}//\`;
+    return [new Request(url, request), ...args.slice(1)];
+  }
+  return args;
+}
+`;
+  const handlerArgs =
+    app === "dispatch" ? "...args" : "...normalizeBasePathArgs(args)";
+  const server = `const basePath = ${JSON.stringify(basePath)};
+
+function setBasePathEnv() {
+  const processRef = globalThis.process ??= { env: {} };
+  processRef.env ??= {};
+  Object.assign(processRef.env, {
+    AGENT_NATIVE_WORKSPACE: "1",
+    AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
+    APP_BASE_PATH: basePath,
+    AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
+    AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
+    AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE: "1",
+    VITE_AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
+    VITE_APP_BASE_PATH: basePath,
+    VITE_AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON: ${JSON.stringify(JSON.stringify(workspaceApps))},
+    ${JSON.stringify(WORKSPACE_APPS_ENV_KEY)}: ${JSON.stringify(JSON.stringify(workspaceApps))},
+  });
+}
+
+setBasePathEnv();
+${normalizeBasePathHelper}
+
+let cachedHandler;
+
+export default async function handler(...args) {
+  setBasePathEnv();
+  cachedHandler ??= (await import("./main.mjs")).default;
+  return cachedHandler(${handlerArgs});
+}
+
+export const config = {
+  name: ${JSON.stringify(`${app} server handler`)},
+  generator: "agent-native workspace deploy",
+  path: ${JSON.stringify(pathConfig)},
+  nodeBundler: "none",
+  includedFiles: ["**"],
+  excludedPath: ${JSON.stringify(
+    netlifyFunctionExcludedPaths(app, staticDir),
+    null,
+    2,
+  )
+    .split("\n")
+    .join("\n  ")},
+  preferStatic: false,
+};
+`;
+  fs.rmSync(serverPath, { force: true });
+  fs.writeFileSync(path.join(functionDir, `${app}-server.mjs`), server);
+}
+
+function patchVercelFunctionEntry(
+  functionDir: string,
+  app: string,
+  workspaceApps: WorkspaceAppManifestEntry[],
+): void {
+  const entryPath = path.join(functionDir, "index.mjs");
+  if (!fs.existsSync(entryPath)) return;
+
+  const mainPath = path.join(functionDir, "main.mjs");
+  fs.rmSync(mainPath, { force: true });
+  fs.renameSync(entryPath, mainPath);
+
+  const basePath = `/${app}`;
+  const workspaceAppAudience = workspaceAppAudienceForApp(workspaceApps, app);
+  const workspaceAppRouteAccess = workspaceAppRouteAccessForApp(
+    workspaceApps,
+    app,
+  );
+  const entry = `const basePath = ${JSON.stringify(basePath)};
+
+function setBasePathEnv() {
+  const processRef = globalThis.process ??= { env: {} };
+  processRef.env ??= {};
+  Object.assign(processRef.env, {
+    AGENT_NATIVE_WORKSPACE: "1",
+    AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
+    APP_BASE_PATH: basePath,
+    AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
+    AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
+    AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE: "1",
+    VITE_AGENT_NATIVE_WORKSPACE_APP_ID: ${JSON.stringify(app)},
+    VITE_APP_BASE_PATH: basePath,
+    VITE_AGENT_NATIVE_WORKSPACE_APP_AUDIENCE: ${JSON.stringify(workspaceAppAudience)},
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PUBLIC_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.publicPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE_APP_PROTECTED_PATHS: ${JSON.stringify(JSON.stringify(workspaceAppRouteAccess.protectedPaths))},
+    VITE_AGENT_NATIVE_WORKSPACE_APPS_JSON: ${JSON.stringify(JSON.stringify(workspaceApps))},
+    ${JSON.stringify(WORKSPACE_APPS_ENV_KEY)}: ${JSON.stringify(JSON.stringify(workspaceApps))},
+  });
+}
+
+function normalizeBasePathArgs(args) {
+  const request = args[0];
+  if (!request) return args;
+
+  if (typeof Request === "function" && request instanceof Request) {
+    const url = new URL(request.url);
+    if (url.pathname === basePath || url.pathname === \`\${basePath}/\`) {
+      url.pathname = \`\${basePath}//\`;
+      return [new Request(url, request), ...args.slice(1)];
+    }
+    return args;
+  }
+
+  if (typeof request.url !== "string") return args;
+  const url = new URL(request.url, "http://agent-native.local");
+  if (url.pathname === basePath || url.pathname === \`\${basePath}/\`) {
+    request.url = \`\${basePath}//\${url.search}\`;
+  }
+  return args;
+}
+
+setBasePathEnv();
+
+let cachedHandler;
+
+export default async function handler(...args) {
+  setBasePathEnv();
+  cachedHandler ??= (await import("./main.mjs")).default;
+  return cachedHandler(...normalizeBasePathArgs(args));
+}
+`;
+  fs.writeFileSync(entryPath, entry);
+}
+
+function netlifyFunctionExcludedPaths(
+  app: string,
+  staticDir: string,
+): string[] {
+  return [
+    "/.netlify/*",
+    `/${app}/assets/*`,
+    ...netlifyPublicRootAssetPaths(app, staticDir),
+  ];
+}
+
+function netlifyPublicRootAssetPaths(app: string, staticDir: string): string[] {
+  if (!fs.existsSync(staticDir)) return [];
+  return fs
+    .readdirSync(staticDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .filter((name) => {
+      const ext = path.extname(name).slice(1).toLowerCase();
+      return NETLIFY_PUBLIC_ASSET_EXTENSIONS.has(ext);
+    })
+    .sort()
+    .map((name) => `/${app}/${encodeURI(name)}`);
+}
+
+function netlifyFunctionsDir(workspaceRoot: string): string {
+  return path.join(workspaceRoot, ".netlify", "functions-internal");
+}
+
+function cleanAppBuildOutputs(appDir: string): void {
+  // .deploy-tmp: a crashed prior per-app build leaves partial artifacts that
+  // silently poison the next build for that app (observed on Windows: stale
+  // state made a cloudflare_pages build die after the vite phases with no
+  // error output). The deploy post-build also sweeps it, but clean here too
+  // so the unified build never depends on the child's hygiene.
+  for (const name of ["dist", ".output", "build", ".deploy-tmp"]) {
+    fs.rmSync(path.join(appDir, name), { recursive: true, force: true });
+  }
+  fs.rmSync(path.join(appDir, ".netlify", "functions-internal"), {
+    recursive: true,
+    force: true,
+  });
+  fs.rmSync(path.join(appDir, ".vercel", "output"), {
+    recursive: true,
+    force: true,
+  });
+}
+
+function appUsesNetlifyUnpooledDatabaseUrl(appDir: string): boolean {
+  const netlifyPath = path.join(appDir, "netlify.toml");
+  if (!fs.existsSync(netlifyPath)) return false;
+  try {
+    return fs
+      .readFileSync(netlifyPath, "utf-8")
+      .includes("NETLIFY_DATABASE_URL_UNPOOLED");
+  } catch {
+    return false;
+  }
+}
+
+function writeWorkspaceAppManifests(
+  workspaceRoot: string,
+  distDir: string,
+  apps: string[],
+  workspaceApps: WorkspaceAppManifestEntry[],
+  preset: WorkspaceDeployPreset,
+): void {
+  const manifest = JSON.stringify(
+    {
+      version: 1,
+      apps: workspaceApps,
+    },
+    null,
+    2,
+  );
+
+  const targets =
+    preset === "netlify"
+      ? apps.map((app) =>
+          path.join(
+            netlifyFunctionsDir(workspaceRoot),
+            `${app}-server`,
+            WORKSPACE_APPS_MANIFEST_DIR,
+            WORKSPACE_APPS_MANIFEST_FILE,
+          ),
+        )
+      : preset === "vercel"
+        ? apps.map((app) =>
+            path.join(
+              workspaceRoot,
+              VERCEL_OUTPUT_DIR,
+              "functions",
+              `${app}-server.func`,
+              WORKSPACE_APPS_MANIFEST_DIR,
+              WORKSPACE_APPS_MANIFEST_FILE,
+            ),
+          )
+        : apps.map((app) =>
+            path.join(
+              distDir,
+              app,
+              WORKSPACE_APPS_MANIFEST_DIR,
+              WORKSPACE_APPS_MANIFEST_FILE,
+            ),
+          );
+
+  for (const target of targets) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, `${manifest}\n`);
+  }
+}
+
+function readWorkspaceAppManifest(
+  workspaceRoot: string,
+  apps: string[],
+): WorkspaceAppManifestEntry[] {
+  const explicitApps = readExistingWorkspaceAppManifest(workspaceRoot);
+
+  return apps
+    .map((app) => {
+      const appDir = path.join(workspaceRoot, "apps", app);
+      const pkg = readPackageJson(path.join(appDir, "package.json"));
+      const appPath = `/${app}`;
+      const explicit = explicitApps.get(app);
+      const url =
+        normalizeWorkspaceAppUrl(explicit?.url) ?? workspaceAppUrl(appPath);
+      const audience =
+        workspaceAppAudienceFromPackageJson(pkg) ??
+        explicit?.audience ??
+        DEFAULT_WORKSPACE_APP_AUDIENCE;
+      const packageRouteAccess = workspaceAppRouteAccessFromPackageJson(pkg);
+      // Prefer the package.json value whenever the field was set — including
+      // an explicit empty array, which is how a per-app package.json signals
+      // "clear any previously-published manifest override." Falling back on
+      // length > 0 would silently keep the explicit override even after the
+      // app owner blanked their list.
+      const publicPaths =
+        packageRouteAccess.publicPaths ?? explicit?.publicPaths ?? [];
+      const protectedPaths =
+        packageRouteAccess.protectedPaths ?? explicit?.protectedPaths ?? [];
+      return {
+        id: app,
+        name: pkg?.displayName || titleCase(app),
+        description: pkg?.description || "",
+        path: appPath,
+        ...(url ? { url } : {}),
+        isDispatch: app === "dispatch",
+        audience,
+        publicPaths,
+        protectedPaths,
+      };
+    })
+    .sort((a, b) => {
+      if (a.id === "dispatch") return -1;
+      if (b.id === "dispatch") return 1;
+      return a.name.localeCompare(b.name);
+    });
+}
+
+function readExistingWorkspaceAppManifest(
+  workspaceRoot: string,
+): Map<string, WorkspaceAppManifestOverride> {
+  const fromEnv = parseWorkspaceAppsJson(process.env[WORKSPACE_APPS_ENV_KEY]);
+  const fromFile =
+    readWorkspaceAppsFromFile(
+      path.join(
+        workspaceRoot,
+        WORKSPACE_APPS_MANIFEST_DIR,
+        WORKSPACE_APPS_MANIFEST_FILE,
+      ),
+    ) ??
+    readWorkspaceAppsFromFile(
+      path.join(workspaceRoot, WORKSPACE_APPS_MANIFEST_FILE),
+    );
+  const apps = fromEnv ?? fromFile ?? [];
+  return new Map(apps.map((app) => [app.id, app]));
+}
+
+function parseWorkspaceAppsJson(
+  raw: string | undefined,
+): WorkspaceAppManifestOverride[] | null {
+  if (!raw) return null;
+  try {
+    return parseWorkspaceAppsManifest(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+function readWorkspaceAppsFromFile(
+  file: string,
+): WorkspaceAppManifestOverride[] | null {
+  if (!fs.existsSync(file)) return null;
+  return parseWorkspaceAppsManifest(readPackageJson(file));
+}
+
+function parseWorkspaceAppsManifest(
+  parsed: any,
+): WorkspaceAppManifestOverride[] | null {
+  const rawApps = Array.isArray(parsed?.apps)
+    ? parsed.apps
+    : Array.isArray(parsed)
+      ? parsed
+      : null;
+  if (!rawApps) return null;
+
+  const apps = (rawApps as unknown[])
+    .map((entry) => {
+      if (!entry || typeof entry !== "object") return null;
+      const e = entry as Record<string, unknown>;
+      const id = typeof e.id === "string" ? e.id.trim() : "";
+      if (!id) return null;
+      const url = normalizeWorkspaceAppUrl(e.url);
+      const audience =
+        e.audience === undefined
+          ? undefined
+          : normalizeWorkspaceAppAudience(e.audience);
+      const publicPaths = normalizeWorkspaceAppPathList(e.publicPaths);
+      const protectedPaths = normalizeWorkspaceAppPathList(e.protectedPaths);
+      return {
+        id,
+        ...(url ? { url } : {}),
+        ...(audience ? { audience } : {}),
+        ...(publicPaths.length > 0 ? { publicPaths } : {}),
+        ...(protectedPaths.length > 0 ? { protectedPaths } : {}),
+      };
+    })
+    .filter((app): app is NonNullable<typeof app> => !!app);
+
+  return apps.length ? apps : null;
+}
+
+function workspaceBaseUrl(): string | null {
+  const gatewayOrigin =
+    process.env.WORKSPACE_GATEWAY_URL || process.env.VITE_WORKSPACE_GATEWAY_URL;
+  const publicGatewayOrigin = normalizeOrigin(gatewayOrigin);
+  const gatewayFallback =
+    publicGatewayOrigin && !isLoopbackOrigin(publicGatewayOrigin)
+      ? gatewayOrigin
+      : null;
+  return (
+    process.env.APP_URL ||
+    process.env.WORKSPACE_OAUTH_ORIGIN ||
+    process.env.VITE_WORKSPACE_OAUTH_ORIGIN ||
+    process.env.URL ||
+    process.env.DEPLOY_URL ||
+    process.env.BETTER_AUTH_URL ||
+    gatewayFallback ||
+    gatewayOrigin ||
+    null
+  );
+}
+
+function normalizeOrigin(value: string | null | undefined): string | undefined {
+  if (!value) return undefined;
+  try {
+    return new URL(value).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+function isLoopbackOrigin(origin: string | undefined): boolean {
+  if (!origin) return false;
+  try {
+    const host = new URL(origin).hostname.toLowerCase();
+    return (
+      host === "localhost" ||
+      host === "127.0.0.1" ||
+      host === "[::1]" ||
+      host === "::1"
+    );
+  } catch {
+    return false;
+  }
+}
+
+function workspaceOAuthOrigin(
+  workspaceGatewayUrl: string | null,
+): string | undefined {
+  // Explicit overrides (env vars set by the operator) win even if they happen
+  // to be loopback — that's a deliberate dev-against-prod choice.
+  // The gateway-URL fallback, however, is auto-resolved and would silently
+  // send users to localhost if the configured gateway is loopback in a
+  // production deploy. Strip loopback there so OAuth fails loudly instead.
+  const gatewayFallback = normalizeOrigin(workspaceGatewayUrl);
+  return (
+    normalizeOrigin(process.env.VITE_WORKSPACE_OAUTH_ORIGIN) ||
+    normalizeOrigin(process.env.WORKSPACE_OAUTH_ORIGIN) ||
+    normalizeOrigin(process.env.APP_URL) ||
+    normalizeOrigin(process.env.BETTER_AUTH_URL) ||
+    normalizeOrigin(process.env.URL) ||
+    normalizeOrigin(process.env.DEPLOY_URL) ||
+    (isLoopbackOrigin(gatewayFallback) ? undefined : gatewayFallback)
+  );
+}
+
+function workspaceAppUrl(appPath: string): string | undefined {
+  const base = workspaceBaseUrl();
+  if (!base) return undefined;
+  try {
+    return new URL(appPath, `${base.replace(/\/$/, "")}/`).toString();
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeWorkspaceAppUrl(value: unknown): string | undefined {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  try {
+    return new URL(value.trim()).toString().replace(/\/$/, "");
+  } catch {
+    return undefined;
+  }
+}
+
+function readPackageJson(file: string): Record<string, any> | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function titleCase(value: string): string {
+  return value
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function parsePresetArg(args: string[]): WorkspaceDeployPreset | null {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--preset" && args[i + 1]) {
+      return normalizePreset(args[i + 1]);
+    }
+    if (arg.startsWith("--preset=")) {
+      return normalizePreset(arg.slice("--preset=".length));
+    }
+  }
+  return null;
+}
+
+function resolvePreset(
+  optionPreset: WorkspaceDeployPreset | undefined,
+  args: string[],
+): WorkspaceDeployPreset {
+  return (
+    optionPreset ??
+    parsePresetArg(args) ??
+    normalizePreset(process.env.NITRO_PRESET) ??
+    "cloudflare_pages"
+  );
+}
+
+function assertWorkspaceDeployProductionEnv(opts: {
+  buildOnly: boolean;
+  preset: WorkspaceDeployPreset;
+}): void {
+  if (!isProductionWorkspaceDeploy(opts)) return;
+  if (process.env.A2A_SECRET?.trim()) return;
+  const providerHint =
+    opts.preset === "netlify"
+      ? ' For Netlify, one option is: netlify env:set A2A_SECRET "$(openssl rand -hex 32)".'
+      : "";
+  throw new Error(
+    [
+      "A2A_SECRET is required for production workspace deploys.",
+      "Workspace Slack, webhook, and cross-app A2A work resumes through signed background processors; without A2A_SECRET those production routes return 503.",
+      `Set A2A_SECRET in your deploy provider and redeploy.${providerHint}`,
+      "For local artifact checks, run agent-native deploy --build-only outside the deploy provider environment.",
+    ].join(" "),
+  );
+}
+
+function isProductionWorkspaceDeploy(opts: {
+  buildOnly: boolean;
+  preset: WorkspaceDeployPreset;
+}): boolean {
+  if (!opts.buildOnly) return true;
+  if (
+    opts.preset === "netlify" &&
+    process.env.NETLIFY === "true" &&
+    process.env.NETLIFY_LOCAL !== "true"
+  ) {
+    return true;
+  }
+  if (opts.preset === "cloudflare_pages" && process.env.CF_PAGES === "1") {
+    return true;
+  }
+  if (opts.preset === "vercel" && process.env.VERCEL === "1") {
+    return true;
+  }
+  return false;
+}
+
+function normalizePreset(
+  value: string | undefined,
+): WorkspaceDeployPreset | null {
+  if (!value) return null;
+  if (value === "cloudflare_pages" || value === "cloudflare-pages") {
+    return "cloudflare_pages";
+  }
+  if (value === "netlify") return "netlify";
+  if (value === "vercel") return "vercel";
+  throw new Error(
+    `Unsupported workspace deploy preset "${value}". Supported presets: cloudflare_pages, netlify, vercel.`,
+  );
+}
+
+function moduleIdent(app: string): string {
+  return "app_" + app.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+function workspaceAppAudienceForApp(
+  workspaceApps: WorkspaceAppManifestEntry[],
+  app: string,
+): WorkspaceAppAudience {
+  return (
+    workspaceApps.find((entry) => entry.id === app)?.audience ??
+    DEFAULT_WORKSPACE_APP_AUDIENCE
+  );
+}
+
+function workspaceAppRouteAccessForApp(
+  workspaceApps: WorkspaceAppManifestEntry[],
+  app: string,
+): WorkspaceAppRouteAccess {
+  const entry = workspaceApps.find((candidate) => candidate.id === app);
+  return {
+    publicPaths: entry?.publicPaths ?? [],
+    protectedPaths: entry?.protectedPaths ?? [],
+  };
+}
+
+function compareWorkspaceAppIds(a: string, b: string): number {
+  if (a === "dispatch") return -1;
+  if (b === "dispatch") return 1;
+  return a.localeCompare(b);
+}
+
+function copyDir(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isSymbolicLink()) {
+      try {
+        const target = fs.readlinkSync(s);
+        fs.symlinkSync(target, d);
+      } catch {
+        fs.copyFileSync(s, d);
+      }
+    } else if (entry.isDirectory()) {
+      copyDir(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+    }
+  }
+}