@agent-native/core 0.7.19 → 0.7.21

package/docs/content/security.md

@@ -182,7 +182,7 @@ Workspace-scope secret writes still require org owner/admin role regardless of t
 - [ ] `A2A_SECRET` set on every app that calls or receives A2A traffic
 - [ ] `SECRETS_ENCRYPTION_KEY` set (or rely on the `BETTER_AUTH_SECRET` fallback)
 - [ ] `AUTH_MODE` is **not** set to `local`
-- [ ] `AUTH_SKIP_EMAIL_VERIFICATION` is **not** set (or set only on QA preview deploys)
+- [ ] `AUTH_SKIP_EMAIL_VERIFICATION` is **not** set in production (or set only on QA preview deploys)
 
 ### Webhook secrets (set the ones for integrations you use)
 

package/docs/content/tools.md

@@ -52,6 +52,10 @@ Tools are fully capable despite being lightweight. They can:
 
 All of this works out of the box. No configuration, no new files, no schema changes.
 
+## Layout defaults {#layout}
+
+Tools render with modest canvas padding by default so simple widgets and dashboards do not hug the iframe edge. For full-bleed experiences such as maps, canvases, or custom editors, set `data-tool-layout="full-bleed"` or `data-tool-padding="none"` on the outermost element.
+
 ## Persistent storage {#persistent-storage}
 
 Every tool has access to a built-in key-value store. Data is automatically scoped per tool and per user — your data stays yours.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.7.19",
+  "version": "0.7.21",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -89,7 +89,7 @@
     "build": "tsc && node scripts/finalize-build.mjs",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
-    "test": "vitest --run",
+    "test": "vitest --run src",
     "prepack": "cp ../../README.md ./README.md",
     "prepublishOnly": "npm run build",
     "release": "npm version patch && npm publish --access public"

package/src/templates/default/_gitignore

@@ -1,5 +1,6 @@
 # React Router generated types
 .react-router/
+.generated/
 .agent-native/
 
 # Logs
@@ -30,9 +31,12 @@ dist-ssr
 !.env.example
 
 # Data
+data/*.db
+data/*.db-shm
+data/*.db-wal
 data/uploads/
 data/settings.json
-data/.sessions.json
+data/.sessions.json
 
 # Learnings (personal preferences and memory — use learnings.defaults.md for tracked defaults)
 learnings.md

package/src/templates/default/app/root.tsx

@@ -37,6 +37,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
           content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
         />
         <link rel="manifest" href="/manifest.json" />
+        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
         <meta name="theme-color" content="#111111" />
         <meta name="mobile-web-app-capable" content="yes" />
         <meta

package/src/templates/default/public/favicon.svg

@@ -1,6 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024" fill="none">
-  <rect x="100" y="100" width="824" height="824" rx="185" fill="#000000"/>
-  <g transform="translate(198.5 330.5) scale(5.5)">
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 600 600" fill="none">
+  <rect width="600" height="600" fill="#000000"/>
+  <g transform="translate(92 179) scale(3.6491228070175437)">
     <path d="M24.5537 65.7695H0L15.0859 39.4619L37.708 0L60.4912 39.4619H39.6396L24.5537 65.7695Z" fill="white"/>
     <path d="M89.446 0H114L76.2921 65.7704H51.7383L89.446 0Z" fill="url(#favicon_grad)"/>
     <defs>

package/src/templates/default/public/icon-180.svg

@@ -1,6 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="180" height="180" viewBox="0 0 1024 1024" fill="none">
-  <rect x="100" y="100" width="824" height="824" rx="185" fill="#000000"/>
-  <g transform="translate(198.5 330.5) scale(5.5)">
+<svg xmlns="http://www.w3.org/2000/svg" width="180" height="180" viewBox="0 0 600 600" fill="none">
+  <rect width="600" height="600" fill="#000000"/>
+  <g transform="translate(92 179) scale(3.6491228070175437)">
     <path d="M24.5537 65.7695H0L15.0859 39.4619L37.708 0L60.4912 39.4619H39.6396L24.5537 65.7695Z" fill="white"/>
     <path d="M89.446 0H114L76.2921 65.7704H51.7383L89.446 0Z" fill="url(#favicon_grad)"/>
     <defs>

package/src/templates/default/public/icon-192.svg

@@ -1,6 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="192" height="192" viewBox="0 0 1024 1024" fill="none">
-  <rect x="100" y="100" width="824" height="824" rx="185" fill="#000000"/>
-  <g transform="translate(198.5 330.5) scale(5.5)">
+<svg xmlns="http://www.w3.org/2000/svg" width="192" height="192" viewBox="0 0 600 600" fill="none">
+  <rect width="600" height="600" fill="#000000"/>
+  <g transform="translate(92 179) scale(3.6491228070175437)">
     <path d="M24.5537 65.7695H0L15.0859 39.4619L37.708 0L60.4912 39.4619H39.6396L24.5537 65.7695Z" fill="white"/>
     <path d="M89.446 0H114L76.2921 65.7704H51.7383L89.446 0Z" fill="url(#favicon_grad)"/>
     <defs>

package/src/templates/default/public/icon-512.svg

@@ -1,6 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 1024 1024" fill="none">
-  <rect x="100" y="100" width="824" height="824" rx="185" fill="#000000"/>
-  <g transform="translate(198.5 330.5) scale(5.5)">
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 600 600" fill="none">
+  <rect width="600" height="600" fill="#000000"/>
+  <g transform="translate(92 179) scale(3.6491228070175437)">
     <path d="M24.5537 65.7695H0L15.0859 39.4619L37.708 0L60.4912 39.4619H39.6396L24.5537 65.7695Z" fill="white"/>
     <path d="M89.446 0H114L76.2921 65.7704H51.7383L89.446 0Z" fill="url(#favicon_grad)"/>
     <defs>

package/src/templates/workspace-core/AGENTS.md

@@ -17,11 +17,12 @@ business context without you having to repeat it per app.
   workspace share `DATABASE_URL` by default, so a record created by one
   app can be read by another as long as it respects the `owner_email` and
   `org_id` scoping conventions.
-- **All API secrets come from the central credential store.** Never
-  hardcode a token. Call `resolveCompanyCredential("KEY")` from
-  `@{{APP_NAME}}/core-module/credentials` — it pulls from env first and
-  falls back to the shared settings table so one rotation updates every
-  app.
+- **All API secrets come from scoped credential storage.** Never hardcode a
+  token or read `process.env` for user/org credentials in production. Call
+  `resolveCompanyCredential("KEY", { userEmail, orgId })` from
+  `@{{APP_NAME}}/core-module/credentials`, or omit the context only when the
+  current request/action already has agent-native request context. The helper
+  reads per-user credentials first and org-shared credentials second.
 - **UI chrome comes from the workspace core.** Wrap every screen in
   `<AuthenticatedLayout>` from `@{{APP_NAME}}/core-module/client`. Don't
   re-implement the brand header, sidebar, or org switcher per app.
@@ -46,10 +47,25 @@ Example rules:
 ## How to add a new app
 
 ```bash
-cd apps
-pnpm exec agent-native create <app-name>
+pnpm exec agent-native create <app-name> --template=starter
 ```
 
+Run this from the workspace root. The CLI detects the workspace and creates
+`apps/<app-name>` with the workspace core module already connected. Use a
+different template when useful, for example `--template=analytics` or
+`--template=forms`.
+
+The workspace dev command is a gateway:
+
+```bash
+pnpm dev
+```
+
+It opens Dispatch at `/dispatch`, serves every app at `/<app-name>`, and
+auto-detects newly-created app directories. After creating an app, do not
+restart the dev server unless the gateway reports an error; wait for it to
+start the new app process, then open `/<app-name>`.
+
 The new app will automatically inherit:
 
 1. The workspace auth plugin (Better Auth + company SSO)

package/src/templates/workspace-core/package.json

@@ -40,7 +40,8 @@
     "prepare": "tsc"
   },
   "dependencies": {
-    "@agent-native/core": "latest"
+    "@agent-native/core": "latest",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^24.2.1",

package/src/templates/workspace-core/src/credentials.ts

@@ -12,17 +12,18 @@
  * DATABASE_URL by default, so storing a credential once makes it
  * available everywhere.
  *
- * Once @agent-native/core publishes the upcoming 2-arg signature you can
- * extend this to take a `{ userEmail, orgId }` context and pass it through
- * for per-user / per-org scoping. The current shape works against both
- * versions — the published 1-arg signature ignores the second argument.
+ * A request/action context is required so credentials stay scoped to the
+ * correct user and organization. This helper can read that context
+ * automatically inside agent-native actions; otherwise pass it explicitly.
  */
 import { resolveCredential } from "@agent-native/core/credentials";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
 
 /**
- * Optional context for scoping a credential lookup to a specific user or
- * org. Forward-compatible with the upcoming 2-arg @agent-native/core
- * signature; ignored by the current 1-arg published one.
+ * Optional context for scoping a credential lookup to a specific user or org.
  */
 export interface CompanyCredentialContext {
   userEmail?: string;
@@ -31,7 +32,7 @@ export interface CompanyCredentialContext {
 
 type ResolveCredentialFn = (
   key: string,
-  ctx?: CompanyCredentialContext,
+  ctx: CompanyCredentialContext,
 ) => Promise<string | undefined>;
 
 /**
@@ -39,10 +40,10 @@ type ResolveCredentialFn = (
  * directly — it keeps your keys organized under a workspace namespace and
  * makes "where does this secret come from" greppable.
  *
- * Example:
+ * Inside an agent-native action:
  *   const slackToken = await resolveCompanyCredential("SLACK_BOT_TOKEN");
  *
- * With per-user scoping (after upgrading @agent-native/core):
+ * Outside request context:
  *   const slackToken = await resolveCompanyCredential("SLACK_BOT_TOKEN", {
  *     userEmail: session.email,
  *     orgId: session.orgId ?? null,
@@ -52,5 +53,15 @@ export async function resolveCompanyCredential(
   key: string,
   ctx?: CompanyCredentialContext,
 ): Promise<string | undefined> {
-  return await (resolveCredential as ResolveCredentialFn)(key, ctx);
+  const effectiveCtx: CompanyCredentialContext = ctx?.userEmail
+    ? ctx
+    : {
+        userEmail: getRequestUserEmail() ?? undefined,
+        orgId: getRequestOrgId(),
+      };
+  if (!effectiveCtx.userEmail) return undefined;
+  return await (resolveCredential as ResolveCredentialFn)(key, {
+    userEmail: effectiveCtx.userEmail,
+    orgId: effectiveCtx.orgId ?? null,
+  });
 }

package/src/templates/workspace-root/.env.example

@@ -22,6 +22,13 @@ OPENAI_API_KEY=
 BUILDER_PRIVATE_KEY=
 BUILDER_PUBLIC_KEY=
 
+# Builder app creation / branching. In local dev these can live in .env.
+# In production, configure deploy env vars instead; production app creation
+# never writes credentials or project IDs to the filesystem.
+ENABLE_BUILDER=
+DISPATCH_BUILDER_PROJECT_ID=
+BUILDER_BRANCH_PROJECT_ID=
+
 # A2A shared secret — required for cross-app JWT verification. Every app
 # in the workspace should use the same value. Generate with:
 #   openssl rand -hex 32

package/src/templates/workspace-root/README.md

@@ -40,14 +40,17 @@ the workspace core package (`@{{APP_NAME}}/core-module`).
 ```bash
 pnpm install
 cp .env.example .env   # fill in DATABASE_URL, BETTER_AUTH_SECRET, ANTHROPIC_API_KEY
-pnpm dev               # starts the example app
+pnpm dev               # starts the workspace gateway and opens Dispatch
 ```
 
+The dev gateway serves Dispatch at `/dispatch` and every app at its own path
+such as `/starter`. It watches `apps/`, so newly-created apps are detected and
+started without restarting `pnpm dev`.
+
 ## Adding a new app
 
 ```bash
-cd apps
-pnpm exec agent-native create crm
+pnpm exec agent-native create crm --template=starter
 ```
 
 The CLI detects the workspace root and scaffolds a minimal app that already

package/src/templates/workspace-root/_gitignore

@@ -19,5 +19,8 @@ packages/*/.env
 .pnpm-store/
 pnpm-debug.log*
 
+# Local workspace data
+data/
+
 # Personal agent memory — per-developer, not shared
 learnings.md

package/src/templates/workspace-root/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "version": "0.0.0",
   "scripts": {
-    "dev": "pnpm --filter example dev",
+    "dev": "tsx scripts/workspace-dev.ts",
     "build": "pnpm -r build",
     "typecheck": "pnpm -r typecheck"
   },
@@ -11,7 +11,9 @@
     "workspaceCore": "@{{APP_NAME}}/core-module"
   },
   "devDependencies": {
+    "@types/node": "^24.2.1",
     "prettier": "^3.6.2",
+    "tsx": "catalog:",
     "typescript": "^6.0.3"
   },
   "packageManager": "pnpm@10.14.0"

package/src/templates/workspace-root/scripts/workspace-dev.ts

@@ -0,0 +1,375 @@
+#!/usr/bin/env tsx
+import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
+import http from "node:http";
+import net from "node:net";
+import path from "node:path";
+
+interface WorkspaceApp {
+  id: string;
+  name: string;
+  dir: string;
+  port: number;
+  process?: ChildProcess;
+}
+
+const root = process.cwd();
+const appsDir = path.join(root, "apps");
+fs.mkdirSync(path.join(root, "data"), { recursive: true });
+const gatewayHost = process.env.WORKSPACE_HOST || "127.0.0.1";
+const requestedPort = Number(
+  process.env.WORKSPACE_PORT || process.env.PORT || 8080,
+);
+const appPortStart = Number(process.env.WORKSPACE_APP_PORT_START || 8100);
+let gatewayUrl = `http://${gatewayHost}:${requestedPort}`;
+
+function readJson(file: string): any {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function discoverApps(): WorkspaceApp[] {
+  if (!fs.existsSync(appsDir)) return [];
+  return fs
+    .readdirSync(appsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const dir = path.join(appsDir, entry.name);
+      const pkg = readJson(path.join(dir, "package.json"));
+      if (!pkg) return null;
+      return {
+        id: entry.name,
+        name: pkg.displayName || pkg.name || entry.name,
+        dir,
+        port: appPortStart,
+      } satisfies WorkspaceApp;
+    })
+    .filter((app): app is WorkspaceApp => !!app)
+    .sort((a, b) => {
+      if (a.id === "dispatch") return -1;
+      if (b.id === "dispatch") return 1;
+      return a.id.localeCompare(b.id);
+    })
+    .map((app, index) => ({ ...app, port: appPortStart + index }));
+}
+
+const apps = discoverApps();
+if (apps.length === 0) {
+  console.error("[workspace] No apps found under ./apps");
+  process.exit(1);
+}
+
+const appById = new Map(apps.map((app) => [app.id, app]));
+const defaultApp =
+  process.env.WORKSPACE_DEFAULT_APP &&
+  appById.has(process.env.WORKSPACE_DEFAULT_APP)
+    ? process.env.WORKSPACE_DEFAULT_APP
+    : appById.has("dispatch")
+      ? "dispatch"
+      : apps[0].id;
+
+function syncApps(): void {
+  const discovered = discoverApps();
+  for (const app of discovered) {
+    if (appById.has(app.id)) continue;
+    const usedPorts = new Set(apps.map((existing) => existing.port));
+    let port = appPortStart;
+    while (usedPorts.has(port)) port++;
+    const next = { ...app, port };
+    apps.push(next);
+    apps.sort((a, b) => {
+      if (a.id === "dispatch") return -1;
+      if (b.id === "dispatch") return 1;
+      return a.id.localeCompare(b.id);
+    });
+    appById.set(next.id, next);
+    console.log(`[workspace] Detected new app: /${next.id}`);
+    startApp(next);
+  }
+}
+
+let syncTimer: NodeJS.Timeout | undefined;
+function scheduleSync(): void {
+  if (syncTimer) clearTimeout(syncTimer);
+  syncTimer = setTimeout(syncApps, 400);
+}
+
+function firstPathSegment(url: string | undefined): string | null {
+  if (!url) return null;
+  try {
+    const parsed = new URL(url, "http://workspace.local");
+    const [segment] = parsed.pathname.split("/").filter(Boolean);
+    return segment || null;
+  } catch {
+    return null;
+  }
+}
+
+function appForRequest(req: http.IncomingMessage): WorkspaceApp | null {
+  const direct = firstPathSegment(req.url);
+  if (direct && appById.has(direct)) return appById.get(direct) ?? null;
+  const referer = req.headers.referer;
+  const fromReferer =
+    typeof referer === "string" ? firstPathSegment(referer) : null;
+  return fromReferer && appById.has(fromReferer)
+    ? (appById.get(fromReferer) ?? null)
+    : null;
+}
+
+function startApp(app: WorkspaceApp): void {
+  const basePath = `/${app.id}`;
+  const child = spawn(
+    "pnpm",
+    [
+      "--dir",
+      app.dir,
+      "exec",
+      "vite",
+      "--host",
+      "127.0.0.1",
+      "--port",
+      String(app.port),
+      "--strictPort",
+    ],
+    {
+      cwd: root,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        APP_NAME: app.id,
+        APP_BASE_PATH: basePath,
+        VITE_APP_BASE_PATH: basePath,
+        PORT: String(app.port),
+        WORKSPACE_GATEWAY_URL: gatewayUrl,
+      },
+    },
+  );
+  app.process = child;
+
+  const prefix = `[${app.id}]`;
+  child.stdout?.on("data", (chunk) => {
+    process.stdout.write(
+      String(chunk)
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => `${prefix} ${line}`)
+        .join("\n") + "\n",
+    );
+  });
+  child.stderr?.on("data", (chunk) => {
+    process.stderr.write(
+      String(chunk)
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => `${prefix} ${line}`)
+        .join("\n") + "\n",
+    );
+  });
+  child.on("exit", (code) => {
+    if (code === 0 || shuttingDown) return;
+    console.error(`${prefix} exited with code ${code}`);
+  });
+}
+
+function renderIndex(): string {
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Agent-Native Workspace</title>
+    <style>
+      body { font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 0; padding: 32px; background: #fafafa; color: #171717; }
+      main { max-width: 760px; margin: 0 auto; }
+      a { color: inherit; text-decoration: none; }
+      .grid { display: grid; gap: 12px; margin-top: 20px; }
+      .card { display: flex; justify-content: space-between; border: 1px solid #d4d4d4; border-radius: 8px; padding: 14px 16px; background: white; }
+      .muted { color: #737373; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Agent-Native Workspace</h1>
+      <p class="muted">Open an app below. Dispatch is the workspace control plane.</p>
+      <div class="grid">
+        ${apps
+          .map(
+            (app) =>
+              `<a class="card" href="/${app.id}"><strong>${app.name}</strong><span class="muted">/${app.id}</span></a>`,
+          )
+          .join("")}
+      </div>
+    </main>
+  </body>
+</html>`;
+}
+
+function proxyHttp(
+  app: WorkspaceApp,
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+): void {
+  const headers = { ...req.headers, host: `127.0.0.1:${app.port}` };
+  const proxyReq = http.request(
+    {
+      hostname: "127.0.0.1",
+      port: app.port,
+      method: req.method,
+      path: req.url,
+      headers,
+    },
+    (proxyRes) => {
+      res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+      proxyRes.pipe(res);
+    },
+  );
+
+  proxyReq.on("error", (err) => {
+    res.writeHead(502, { "content-type": "text/plain" });
+    res.end(`App "${app.id}" is not ready yet: ${err.message}`);
+  });
+
+  req.pipe(proxyReq);
+}
+
+function proxyUpgrade(
+  app: WorkspaceApp,
+  req: http.IncomingMessage,
+  socket: net.Socket,
+  head: Buffer,
+): void {
+  const target = net.connect(app.port, "127.0.0.1", () => {
+    const headers = Object.entries({
+      ...req.headers,
+      host: `127.0.0.1:${app.port}`,
+    })
+      .flatMap(([key, value]) =>
+        Array.isArray(value)
+          ? value.map((item) => `${key}: ${item}`)
+          : [`${key}: ${value ?? ""}`],
+      )
+      .join("\r\n");
+    target.write(
+      `${req.method} ${req.url} HTTP/${req.httpVersion}\r\n${headers}\r\n\r\n`,
+    );
+    if (head.length) target.write(head);
+    socket.pipe(target).pipe(socket);
+  });
+
+  target.on("error", () => socket.destroy());
+}
+
+let shuttingDown = false;
+let workspaceStarted = false;
+
+function startWorkspaceProcesses(): void {
+  if (workspaceStarted) return;
+  workspaceStarted = true;
+  for (const app of apps) startApp(app);
+  try {
+    fs.watch(appsDir, { recursive: true }, scheduleSync);
+  } catch {
+    // Some platforms do not support recursive directory watches.
+  }
+  setInterval(syncApps, 2_000).unref();
+}
+
+function openBrowser(url: string): void {
+  if (process.env.WORKSPACE_NO_OPEN === "1") return;
+  const command =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "cmd"
+        : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  const child = spawn(command, args, {
+    stdio: "ignore",
+    detached: true,
+  });
+  child.unref();
+}
+
+const server = http.createServer((req, res) => {
+  if (req.url === "/" || req.url === "/index.html") {
+    res.writeHead(302, { location: `/${defaultApp}` });
+    res.end();
+    return;
+  }
+
+  if (req.url === "/_workspace/apps") {
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(
+      JSON.stringify(
+        apps.map((app) => ({
+          id: app.id,
+          name: app.name,
+          path: `/${app.id}`,
+          port: app.port,
+        })),
+      ),
+    );
+    return;
+  }
+
+  const app = appForRequest(req);
+  if (!app) {
+    res.writeHead(404, { "content-type": "text/html" });
+    res.end(renderIndex());
+    return;
+  }
+  proxyHttp(app, req, res);
+});
+
+server.on("upgrade", (req, socket, head) => {
+  const app = appForRequest(req);
+  if (!app) {
+    socket.destroy();
+    return;
+  }
+  proxyUpgrade(app, req, socket, head);
+});
+
+function listen(port: number, attempts = 20): void {
+  server.once("error", (err: NodeJS.ErrnoException) => {
+    if (err.code === "EADDRINUSE" && attempts > 0) {
+      listen(port + 1, attempts - 1);
+      return;
+    }
+    console.error(`[workspace] Could not start gateway: ${err.message}`);
+    process.exit(1);
+  });
+  server.listen(port, gatewayHost, () => {
+    const address = server.address();
+    const actualPort =
+      typeof address === "object" && address ? address.port : port;
+    gatewayUrl = `http://${gatewayHost}:${actualPort}`;
+    console.log(`[workspace] Gateway: http://${gatewayHost}:${actualPort}`);
+    console.log(
+      `[workspace] Default: http://${gatewayHost}:${actualPort}/${defaultApp}`,
+    );
+    for (const app of apps) {
+      console.log(`[workspace] ${app.id}: /${app.id} -> 127.0.0.1:${app.port}`);
+    }
+    startWorkspaceProcesses();
+    openBrowser(`http://${gatewayHost}:${actualPort}/${defaultApp}`);
+  });
+}
+
+function shutdown(): void {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  server.close();
+  for (const app of apps) {
+    app.process?.kill("SIGTERM");
+  }
+  setTimeout(() => process.exit(0), 300).unref();
+}
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+listen(requestedPort);