@agent-native/core 0.12.16 → 0.12.17

package/dist/cli/workspace-dev.js

@@ -4,16 +4,26 @@ import fs from "node:fs";
 import http from "node:http";
 import net from "node:net";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import * as Sentry from "@sentry/node";
 import { extractOAuthStateAppId } from "../shared/oauth-state.js";
-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);
-const forceVite = process.env.WORKSPACE_VITE_FORCE === "1";
-let gatewayUrl = `http://${gatewayHost}:${requestedPort}`;
+const DEFAULT_GATEWAY_HOST = "127.0.0.1";
+const DEFAULT_GATEWAY_PORT = 8080;
+const DEFAULT_APP_PORT_START = 8100;
+const PROXY_READY_RETRY_DELAY_MS = 250;
+const APP_RESTART_MAX_DELAY_MS = 10_000;
+export function shouldEagerStartWorkspaceApps(args = [], env = process.env) {
+    return (args.includes("--eager") ||
+        env.WORKSPACE_EAGER === "1" ||
+        env.WORKSPACE_EAGER === "true");
+}
+export function initialWorkspaceAppIds(apps, defaultApp, eager, startDefault = true) {
+    if (eager)
+        return apps.map((app) => app.id);
+    if (!startDefault)
+        return [];
+    return apps.some((app) => app.id === defaultApp) ? [defaultApp] : [];
+}
 function readJson(file) {
     try {
         return JSON.parse(fs.readFileSync(file, "utf8"));
@@ -22,13 +32,11 @@ function readJson(file) {
         return null;
     }
 }
-function discoverApps() {
+function discoverApps(appsDir, appPortStart) {
     if (!fs.existsSync(appsDir))
         return [];
-    // existsSync → readdirSync is a TOCTOU race — appsDir can vanish between
-    // the two calls (e.g. user running `git checkout` on the workspace mid-dev).
-    // Treat ENOENT as "no apps right now" and let the next 2s sync recover.
-    // Other errors get surfaced to Sentry so we learn about new failure modes.
+    // existsSync -> readdirSync is a TOCTOU race. Treat ENOENT as "no apps
+    // right now" and let the polling sync recover.
     let entries;
     try {
         entries = fs.readdirSync(appsDir, { withFileTypes: true });
@@ -60,29 +68,18 @@ function discoverApps() {
         };
     })
         .filter((app) => !!app)
-        .sort((a, b) => {
-        if (a.id === "dispatch")
-            return -1;
-        if (b.id === "dispatch")
-            return 1;
-        return a.id.localeCompare(b.id);
-    })
+        .sort(compareApps)
         .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);
+function compareApps(a, b) {
+    if (a.id === "dispatch")
+        return -1;
+    if (b.id === "dispatch")
+        return 1;
+    return a.id.localeCompare(b.id);
 }
-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 isChildDevServerUrlLine(line) {
-    return /^\s*➜\s+(?:Local|Network):\s+https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d+(?:\/\S*)?\s*$/i.test(line);
+    return /^\s*->\s+(?:Local|Network):\s+https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d+(?:\/\S*)?\s*$/i.test(line.replace(/\u279c/g, "->"));
 }
 function pipeAppOutput(prefix, chunk, write) {
     const lines = String(chunk)
@@ -93,39 +90,6 @@ function pipeAppOutput(prefix, chunk, write) {
         return;
     write(lines.map((line) => `${prefix} ${line}`).join("\n") + "\n");
 }
-function syncApps() {
-    const discovered = discoverApps();
-    for (const app of discovered) {
-        const existing = appById.get(app.id);
-        if (existing) {
-            existing.name = app.name;
-            existing.dir = app.dir;
-            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;
-function scheduleSync() {
-    if (syncTimer)
-        clearTimeout(syncTimer);
-    syncTimer = setTimeout(syncApps, 400);
-}
 function firstPathSegment(url) {
     if (!url)
         return null;
@@ -138,128 +102,6 @@ function firstPathSegment(url) {
         return null;
     }
 }
-function appForRequest(req) {
-    const params = new URL(req.url || "/", "http://workspace.local").searchParams;
-    const explicit = params.get("_app");
-    if (explicit && appById.has(explicit))
-        return appById.get(explicit) ?? null;
-    const direct = firstPathSegment(req.url);
-    if (direct && appById.has(direct))
-        return appById.get(direct) ?? null;
-    const fromState = extractOAuthStateAppId(params.get("state"));
-    if (fromState && appById.has(fromState)) {
-        return appById.get(fromState) ?? 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) {
-    if (app.process && !app.process.killed)
-        return;
-    if (app.restartTimer) {
-        clearTimeout(app.restartTimer);
-        app.restartTimer = undefined;
-    }
-    const basePath = `/${app.id}`;
-    const workspaceAppsJson = JSON.stringify(apps.map((workspaceApp) => ({
-        id: workspaceApp.id,
-        name: workspaceApp.name,
-        path: `/${workspaceApp.id}`,
-    })));
-    const child = spawn("pnpm", [
-        "--dir",
-        app.dir,
-        "exec",
-        "vite",
-        "--host",
-        "127.0.0.1",
-        "--port",
-        String(app.port),
-        "--strictPort",
-        ...(forceVite ? ["--force"] : []),
-    ], {
-        cwd: root,
-        stdio: ["ignore", "pipe", "pipe"],
-        env: {
-            ...process.env,
-            APP_NAME: app.id,
-            AGENT_NATIVE_WORKSPACE: "1",
-            AGENT_NATIVE_WORKSPACE_APPS_JSON: workspaceAppsJson,
-            APP_BASE_PATH: basePath,
-            VITE_AGENT_NATIVE_WORKSPACE: "1",
-            VITE_APP_BASE_PATH: basePath,
-            PORT: String(app.port),
-            WORKSPACE_GATEWAY_URL: gatewayUrl,
-        },
-    });
-    app.process = child;
-    const prefix = `[${app.id}]`;
-    const stableTimer = setTimeout(() => {
-        app.restartAttempts = 0;
-    }, 5_000);
-    stableTimer.unref();
-    child.stdout?.on("data", (chunk) => {
-        pipeAppOutput(prefix, chunk, (value) => process.stdout.write(value));
-    });
-    child.stderr?.on("data", (chunk) => {
-        pipeAppOutput(prefix, chunk, (value) => process.stderr.write(value));
-    });
-    child.on("exit", (code) => {
-        clearTimeout(stableTimer);
-        app.process = undefined;
-        app.ready = false;
-        if (code === 0 || shuttingDown)
-            return;
-        app.restartAttempts = (app.restartAttempts ?? 0) + 1;
-        const delay = appRestartDelay(app.restartAttempts);
-        console.error(`${prefix} exited with code ${code}; retrying in ${Math.round(delay / 1000)}s`);
-        app.restartTimer = setTimeout(() => {
-            app.restartTimer = undefined;
-            startApp(app);
-        }, delay);
-        app.restartTimer.unref();
-    });
-}
-function renderIndex() {
-    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>`;
-}
-// On `pnpm dev` the gateway answers requests immediately, but each app's vite
-// server takes a beat to bind its port. Without retry, the user sees an
-// "App is not ready yet: ECONNREFUSED" banner on the first page load and has
-// to refresh manually. We do a quick pre-flight TCP connect with retry so
-// startup is invisible for the common case (small/no body, slow boot).
-const PROXY_READY_TIMEOUT_MS = Number(process.env.WORKSPACE_PROXY_READY_TIMEOUT_MS ?? 30_000);
-const PROXY_READY_RETRY_DELAY_MS = 250;
-const APP_RESTART_MAX_DELAY_MS = 10_000;
 function appRestartDelay(attempts) {
     return Math.min(1_000 * 2 ** Math.max(0, attempts - 1), APP_RESTART_MAX_DELAY_MS);
 }
@@ -288,230 +130,510 @@ function firstHeaderValue(value) {
         return undefined;
     return String(value);
 }
-function forwardedProto(req) {
-    return (firstHeaderValue(req.headers["x-forwarded-proto"]) ||
-        (req.socket.encrypted ? "https" : "http"));
+function wantsHtml(req) {
+    if (req.method !== "GET" && req.method !== "HEAD")
+        return false;
+    const accept = firstHeaderValue(req.headers.accept);
+    if (!accept)
+        return false;
+    return accept.includes("text/html");
 }
-function forwardedHost(req) {
-    return (firstHeaderValue(req.headers["x-forwarded-host"]) ||
-        firstHeaderValue(req.headers.host) ||
-        new URL(gatewayUrl).host);
+function renderStartingApp(app) {
+    const escapedName = escapeHtml(app.name || app.id);
+    return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta http-equiv="refresh" content="1" />
+    <title>Starting ${escapedName}</title>
+    <style>
+      body { min-height: 100vh; margin: 0; display: grid; place-items: center; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #fafafa; color: #171717; }
+      main { width: min(420px, calc(100vw - 48px)); }
+      .bar { height: 3px; overflow: hidden; border-radius: 999px; background: #e5e5e5; }
+      .bar::before { content: ""; display: block; height: 100%; width: 42%; border-radius: inherit; background: #171717; animation: load 1s ease-in-out infinite; }
+      p { color: #737373; }
+      @keyframes load { 0% { transform: translateX(-105%); } 100% { transform: translateX(245%); } }
+    </style>
+    <script>setTimeout(() => window.location.reload(), 900);</script>
+  </head>
+  <body>
+    <main>
+      <div class="bar"></div>
+      <h1>Starting ${escapedName}</h1>
+      <p>The workspace gateway is waking this app's dev server.</p>
+    </main>
+  </body>
+</html>`;
 }
-function proxyHeaders(req, targetHost) {
-    return {
-        ...req.headers,
-        "x-forwarded-host": forwardedHost(req),
-        "x-forwarded-proto": forwardedProto(req),
-        host: targetHost,
-    };
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => {
+        switch (char) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case '"':
+                return "&quot;";
+            default:
+                return "&#39;";
+        }
+    });
 }
-async function waitForPort(port, deadline) {
-    while (Date.now() < deadline) {
-        if (await probePort(port))
-            return true;
-        await new Promise((r) => setTimeout(r, PROXY_READY_RETRY_DELAY_MS));
-    }
-    return false;
+function renderIndex(apps) {
+    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 when installed.</p>
+      <div class="grid">
+        ${apps
+        .map((app) => `<a class="card" href="/${app.id}"><strong>${escapeHtml(app.name)}</strong><span class="muted">/${escapeHtml(app.id)}</span></a>`)
+        .join("")}
+      </div>
+    </main>
+  </body>
+</html>`;
 }
-function proxyHttp(app, req, res) {
-    const dispatch = () => {
-        const headers = proxyHeaders(req, `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) => {
-            app.ready = true;
-            res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
-            proxyRes.pipe(res);
+export function runWorkspaceDev(options = {}) {
+    const args = options.args ?? process.argv.slice(2);
+    const env = options.env ?? process.env;
+    const root = options.root ?? process.cwd();
+    const appsDir = path.join(root, "apps");
+    const spawnProcess = options.spawnProcess ?? spawn;
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    fs.mkdirSync(path.join(root, "data"), { recursive: true });
+    const gatewayHost = env.WORKSPACE_HOST || DEFAULT_GATEWAY_HOST;
+    const requestedPort = Number(env.WORKSPACE_PORT || env.PORT || DEFAULT_GATEWAY_PORT);
+    const appPortStart = Number(env.WORKSPACE_APP_PORT_START || DEFAULT_APP_PORT_START);
+    const forceVite = env.WORKSPACE_VITE_FORCE === "1";
+    const eager = shouldEagerStartWorkspaceApps(args, env);
+    const proxyReadyTimeoutMs = Number(env.WORKSPACE_PROXY_READY_TIMEOUT_MS ?? 30_000);
+    let gatewayUrl = `http://${gatewayHost}:${requestedPort}`;
+    const apps = discoverApps(appsDir, appPortStart);
+    if (apps.length === 0) {
+        throw new Error("[workspace] No apps found under ./apps");
+    }
+    const appById = new Map(apps.map((app) => [app.id, app]));
+    const explicitDefaultApp = env.WORKSPACE_DEFAULT_APP && appById.has(env.WORKSPACE_DEFAULT_APP)
+        ? env.WORKSPACE_DEFAULT_APP
+        : null;
+    const hasDispatch = appById.has("dispatch");
+    const defaultApp = explicitDefaultApp ?? (hasDispatch ? "dispatch" : apps[0].id);
+    const redirectRootToDefault = Boolean(explicitDefaultApp || hasDispatch);
+    let syncTimer;
+    let shuttingDown = false;
+    let workspaceStarted = false;
+    let readyResolve;
+    const ready = new Promise((resolve) => {
+        readyResolve = resolve;
+    });
+    function workspaceAppsJson() {
+        return JSON.stringify(apps.map((workspaceApp) => ({
+            id: workspaceApp.id,
+            name: workspaceApp.name,
+            path: `/${workspaceApp.id}`,
+        })));
+    }
+    function syncApps() {
+        const discovered = discoverApps(appsDir, appPortStart);
+        for (const app of discovered) {
+            const existing = appById.get(app.id);
+            if (existing) {
+                existing.name = app.name;
+                existing.dir = app.dir;
+                continue;
+            }
+            const usedPorts = new Set(apps.map((existingApp) => existingApp.port));
+            let port = appPortStart;
+            while (usedPorts.has(port))
+                port++;
+            const next = { ...app, port };
+            apps.push(next);
+            apps.sort(compareApps);
+            appById.set(next.id, next);
+            stdout.write(`[workspace] Detected new app: /${next.id}\n`);
+        }
+    }
+    function scheduleSync() {
+        if (syncTimer)
+            clearTimeout(syncTimer);
+        syncTimer = setTimeout(syncApps, 400);
+    }
+    function appForRequest(req) {
+        const params = new URL(req.url || "/", "http://workspace.local")
+            .searchParams;
+        const explicit = params.get("_app");
+        if (explicit && appById.has(explicit))
+            return appById.get(explicit) ?? null;
+        const direct = firstPathSegment(req.url);
+        if (direct && appById.has(direct))
+            return appById.get(direct) ?? null;
+        const fromState = extractOAuthStateAppId(params.get("state"));
+        if (fromState && appById.has(fromState)) {
+            return appById.get(fromState) ?? 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) {
+        if (app.process && !app.process.killed)
+            return;
+        if (app.restartTimer) {
+            clearTimeout(app.restartTimer);
+            app.restartTimer = undefined;
+        }
+        const basePath = `/${app.id}`;
+        const child = spawnProcess("pnpm", [
+            "--dir",
+            app.dir,
+            "exec",
+            "vite",
+            "--host",
+            "127.0.0.1",
+            "--port",
+            String(app.port),
+            "--strictPort",
+            ...(forceVite ? ["--force"] : []),
+        ], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...env,
+                APP_NAME: app.id,
+                AGENT_NATIVE_WORKSPACE: "1",
+                AGENT_NATIVE_WORKSPACE_APPS_JSON: workspaceAppsJson(),
+                APP_BASE_PATH: basePath,
+                VITE_AGENT_NATIVE_WORKSPACE: "1",
+                VITE_APP_BASE_PATH: basePath,
+                PORT: String(app.port),
+                WORKSPACE_GATEWAY_URL: gatewayUrl,
+            },
         });
-        proxyReq.on("error", (err) => {
-            if (res.headersSent) {
-                res.end();
+        app.process = child;
+        const prefix = `[${app.id}]`;
+        const stableTimer = setTimeout(() => {
+            app.restartAttempts = 0;
+        }, 5_000);
+        stableTimer.unref();
+        child.stdout?.on("data", (chunk) => {
+            pipeAppOutput(prefix, chunk, (value) => stdout.write(value));
+        });
+        child.stderr?.on("data", (chunk) => {
+            pipeAppOutput(prefix, chunk, (value) => stderr.write(value));
+        });
+        child.on("exit", (code) => {
+            clearTimeout(stableTimer);
+            app.process = undefined;
+            app.ready = false;
+            if (code === 0 || shuttingDown)
                 return;
-            }
-            res.writeHead(502, { "content-type": "text/plain" });
-            res.end(`App "${app.id}" is not ready yet: ${err.message}`);
+            app.restartAttempts = (app.restartAttempts ?? 0) + 1;
+            const delay = appRestartDelay(app.restartAttempts);
+            stderr.write(`${prefix} exited with code ${code}; retrying in ${Math.round(delay / 1000)}s\n`);
+            app.restartTimer = setTimeout(() => {
+                app.restartTimer = undefined;
+                startApp(app);
+            }, delay);
+            app.restartTimer.unref();
         });
-        req.pipe(proxyReq);
-    };
-    // Fast path: the upstream has accepted at least one request before, so it's
-    // listening. Skip the probe so steady-state requests stay zero-latency.
-    if (app.ready) {
-        dispatch();
-        return;
     }
-    // Cold path: hold the request open while the child server boots. Node
-    // keeps the request body in paused mode until a consumer attaches via
-    // pipe(), so awaiting waitForPort() doesn't lose data.
-    void waitForPort(app.port, Date.now() + PROXY_READY_TIMEOUT_MS).then((ready) => {
-        if (!ready) {
-            if (!res.headersSent) {
+    function forwardedProto(req) {
+        return (firstHeaderValue(req.headers["x-forwarded-proto"]) ||
+            (req.socket.encrypted ? "https" : "http"));
+    }
+    function forwardedHost(req) {
+        return (firstHeaderValue(req.headers["x-forwarded-host"]) ||
+            firstHeaderValue(req.headers.host) ||
+            new URL(gatewayUrl).host);
+    }
+    function proxyHeaders(req, targetHost) {
+        return {
+            ...req.headers,
+            "x-forwarded-host": forwardedHost(req),
+            "x-forwarded-proto": forwardedProto(req),
+            host: targetHost,
+        };
+    }
+    async function waitForPort(port, deadline) {
+        while (Date.now() < deadline) {
+            if (await probePort(port))
+                return true;
+            await new Promise((r) => setTimeout(r, PROXY_READY_RETRY_DELAY_MS));
+        }
+        return false;
+    }
+    function proxyHttp(app, req, res) {
+        const cold = !app.process || app.process.killed;
+        startApp(app);
+        if (!app.ready && wantsHtml(req)) {
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            if (req.method === "HEAD") {
+                res.end();
+                return;
+            }
+            res.end(renderStartingApp(app));
+            return;
+        }
+        const dispatch = () => {
+            const headers = proxyHeaders(req, `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) => {
+                app.ready = true;
+                res.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+                proxyRes.pipe(res);
+            });
+            proxyReq.on("error", (err) => {
+                if (res.headersSent) {
+                    res.end();
+                    return;
+                }
                 res.writeHead(502, { "content-type": "text/plain" });
-                res.end(`App "${app.id}" is not ready yet: connect ECONNREFUSED 127.0.0.1:${app.port}`);
+                res.end(`App "${app.id}" is not ready yet: ${err.message}`);
+            });
+            req.pipe(proxyReq);
+        };
+        // Fast path: the upstream has accepted at least one request before, so
+        // it's listening. Skip the probe so steady-state requests stay zero-latency.
+        if (app.ready && !cold) {
+            dispatch();
+            return;
+        }
+        // Cold path: hold non-HTML requests open while the child server boots.
+        // Node keeps the request body paused until pipe() attaches.
+        void waitForPort(app.port, Date.now() + proxyReadyTimeoutMs).then((ready) => {
+            if (!ready) {
+                if (!res.headersSent) {
+                    res.writeHead(502, { "content-type": "text/plain" });
+                    res.end(`App "${app.id}" is not ready yet: connect ECONNREFUSED 127.0.0.1:${app.port}`);
+                }
+                else {
+                    res.end();
+                }
+                return;
             }
-            else {
-                res.end();
+            app.ready = true;
+            dispatch();
+        });
+    }
+    function proxyUpgrade(app, req, socket, head) {
+        startApp(app);
+        void waitForPort(app.port, Date.now() + proxyReadyTimeoutMs).then((ready) => {
+            if (!ready) {
+                socket.destroy();
+                return;
             }
+            app.ready = true;
+            const target = net.connect(app.port, "127.0.0.1", () => {
+                const headers = Object.entries(proxyHeaders(req, `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());
+        });
+    }
+    function handleWatcherError(err) {
+        if (err.code === "ENOSPC") {
+            stderr.write(`[workspace] Recursive file watcher hit the system limit (ENOSPC). ` +
+                `New apps will still be detected via polling every ~2s. ` +
+                `On Linux you can raise the limit with ` +
+                `\`sudo sysctl fs.inotify.max_user_watches=524288\` ` +
+                `(persist via /etc/sysctl.d/*.conf). On macOS/Windows this usually ` +
+                `means too many other watchers are running.\n`);
+            Sentry.captureException(err, {
+                tags: { handled: "dev-watch-enospc" },
+                level: "warning",
+            });
             return;
         }
-        app.ready = true;
-        dispatch();
-    });
-}
-function proxyUpgrade(app, req, socket, head) {
-    const target = net.connect(app.port, "127.0.0.1", () => {
-        const headers = Object.entries(proxyHeaders(req, `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 handleWatcherError(err) {
-    // ENOSPC: system inotify watcher limit hit (Linux). Userland-fixable;
-    // capture as a warning so we still see frequency in Sentry but don't get
-    // paged. Print actionable guidance and continue without watching — the
-    // 2s polling interval below keeps app discovery working.
-    if (err.code === "ENOSPC") {
-        console.warn(`[workspace] Recursive file watcher hit the system limit (ENOSPC). ` +
-            `New apps will still be detected via polling every ~2s. ` +
-            `On Linux you can raise the limit with ` +
-            `\`sudo sysctl fs.inotify.max_user_watches=524288\` ` +
-            `(persist via /etc/sysctl.d/*.conf). On macOS/Windows this usually ` +
-            `means too many other watchers are running.`);
+        if (err.code === "ENOENT") {
+            return;
+        }
+        stderr.write(`[workspace] Recursive file watcher failed (${err.code ?? "unknown"}): ${err.message}. ` +
+            `Falling back to polling.\n`);
         Sentry.captureException(err, {
-            tags: { handled: "dev-watch-enospc" },
+            tags: { handled: "dev-watch-unknown" },
             level: "warning",
         });
-        return;
     }
-    // ENOENT: a watched directory disappeared (or a transient subdir under
-    // appsDir vanished mid-enumeration). Benign — the polling fallback and
-    // future scheduleSync calls will re-establish state. Don't capture.
-    if (err.code === "ENOENT") {
-        console.debug(`[workspace] Recursive file watcher saw a directory disappear ` +
-            `(ENOENT: ${err.path ?? "unknown"}). Polling fallback will recover.`);
-        return;
-    }
-    // Unknown failure mode — keep the dev experience alive (polling still
-    // runs) but surface to Sentry as a warning so we learn about new cases.
-    console.warn(`[workspace] Recursive file watcher failed (${err.code ?? "unknown"}): ${err.message}. ` +
-        `Falling back to polling.`);
-    Sentry.captureException(err, {
-        tags: { handled: "dev-watch-unknown" },
-        level: "warning",
-    });
-}
-function startWorkspaceProcesses() {
-    if (workspaceStarted)
-        return;
-    workspaceStarted = true;
-    for (const app of apps)
-        startApp(app);
-    try {
-        const watcher = fs.watch(appsDir, { recursive: true }, scheduleSync);
-        // Async errors (e.g. ENOENT when a subdir vanishes mid-watch) surface on
-        // the watcher rather than the original call site. Without an `error`
-        // listener, Node would treat them as uncaught and crash the dev process.
-        watcher.on("error", (err) => {
+    function startWorkspaceProcesses() {
+        if (workspaceStarted)
+            return;
+        workspaceStarted = true;
+        for (const id of initialWorkspaceAppIds(apps, defaultApp, eager, redirectRootToDefault)) {
+            const app = appById.get(id);
+            if (app)
+                startApp(app);
+        }
+        try {
+            const watcher = fs.watch(appsDir, { recursive: true }, scheduleSync);
+            watcher.on("error", (err) => {
+                handleWatcherError(err);
+            });
+        }
+        catch (err) {
             handleWatcherError(err);
-        });
+        }
+        setInterval(syncApps, 2_000).unref();
     }
-    catch (err) {
-        handleWatcherError(err);
+    function openBrowser(url) {
+        if (options.openBrowser === false || env.WORKSPACE_NO_OPEN === "1")
+            return;
+        const command = process.platform === "darwin"
+            ? "open"
+            : process.platform === "win32"
+                ? "cmd"
+                : "xdg-open";
+        const openArgs = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+        const child = spawnProcess(command, openArgs, {
+            stdio: "ignore",
+            detached: true,
+        });
+        child.unref();
     }
-    setInterval(syncApps, 2_000).unref();
-}
-function openBrowser(url) {
-    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,
+    const server = http.createServer((req, res) => {
+        if (req.url === "/" || req.url === "/index.html") {
+            if (redirectRootToDefault) {
+                res.writeHead(302, { location: `/${defaultApp}` });
+                res.end();
+                return;
+            }
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            res.end(renderIndex(apps));
+            return;
+        }
+        if (req.url === "/_workspace/apps") {
+            syncApps();
+            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,
+                running: Boolean(app.process && !app.process.killed),
+            }))));
+            return;
+        }
+        let app = appForRequest(req);
+        if (!app) {
+            syncApps();
+            app = appForRequest(req);
+        }
+        if (!app) {
+            res.writeHead(404, { "content-type": "text/html; charset=utf-8" });
+            res.end(renderIndex(apps));
+            return;
+        }
+        proxyHttp(app, req, res);
     });
-    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, attempts = 20) {
-    server.once("error", (err) => {
-        if (err.code === "EADDRINUSE" && attempts > 0) {
-            listen(port + 1, attempts - 1);
+    server.on("upgrade", (req, socket, head) => {
+        const app = appForRequest(req);
+        if (!app) {
+            socket.destroy();
             return;
         }
-        console.error(`[workspace] Could not start gateway: ${err.message}`);
-        process.exit(1);
+        proxyUpgrade(app, req, socket, head);
     });
-    server.listen(port, gatewayHost, () => {
-        const address = server.address();
-        const actualPort = typeof address === "object" && address ? address.port : port;
-        gatewayUrl = `http://${gatewayHost}:${actualPort}`;
-        console.log(`[workspace] Default: http://${gatewayHost}:${actualPort}/${defaultApp}`);
-        console.log(`[workspace] Gateway: http://${gatewayHost}:${actualPort}`);
+    function listen(port, attempts = 20) {
+        server.once("error", (err) => {
+            if (err.code === "EADDRINUSE" && attempts > 0) {
+                listen(port + 1, attempts - 1);
+                return;
+            }
+            stderr.write(`[workspace] Could not start gateway: ${err.message}\n`);
+            throw err;
+        });
+        server.listen(port, gatewayHost, () => {
+            const address = server.address();
+            const actualPort = typeof address === "object" && address ? address.port : port;
+            gatewayUrl = `http://${gatewayHost}:${actualPort}`;
+            stdout.write(`[workspace] Default: ${redirectRootToDefault ? `${gatewayUrl}/${defaultApp}` : gatewayUrl}\n`);
+            stdout.write(`[workspace] Gateway: ${gatewayUrl}\n`);
+            stdout.write(`[workspace] Mode: ${eager ? "eager" : "lazy"}\n`);
+            for (const app of apps) {
+                stdout.write(`[workspace] ${app.id}: /${app.id} -> 127.0.0.1:${app.port}\n`);
+            }
+            startWorkspaceProcesses();
+            openBrowser(redirectRootToDefault ? `${gatewayUrl}/${defaultApp}` : gatewayUrl);
+            readyResolve({ port: actualPort, url: gatewayUrl });
+        });
+    }
+    function shutdown() {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        server.close();
         for (const app of apps) {
-            console.log(`[workspace] ${app.id}: /${app.id} -> 127.0.0.1:${app.port}`);
+            app.process?.kill("SIGTERM");
         }
-        startWorkspaceProcesses();
-        openBrowser(`http://${gatewayHost}:${actualPort}/${defaultApp}`);
-    });
+        if (syncTimer)
+            clearTimeout(syncTimer);
+        process.off("SIGINT", handleSigint);
+        process.off("SIGTERM", handleSigterm);
+    }
+    const handleSigint = () => shutdown();
+    const handleSigterm = () => shutdown();
+    process.once("SIGINT", handleSigint);
+    process.once("SIGTERM", handleSigterm);
+    listen(requestedPort);
+    return {
+        apps,
+        defaultApp,
+        gatewayUrl: () => gatewayUrl,
+        ready,
+        server,
+        shutdown,
+    };
 }
-function shutdown() {
-    if (shuttingDown)
-        return;
-    shuttingDown = true;
-    server.close();
-    for (const app of apps) {
-        app.process?.kill("SIGTERM");
+function isDirectRun() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return path.resolve(entry) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectRun()) {
+    try {
+        runWorkspaceDev({ args: process.argv.slice(2) });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
     }
-    setTimeout(() => process.exit(0), 300).unref();
 }
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
-listen(requestedPort);
 //# sourceMappingURL=workspace-dev.js.map