@lowdefy/server-dev 6.0.0 → 7.0.0

package/manager/processes/startProxy.mjs

@@ -17,6 +17,11 @@
 import http from 'node:http';
 import net from 'node:net';
 
+import { devPassiveHeader } from '@lowdefy/node-utils';
+
+import buildWaitHeader from '../../lib/docs/buildWaitHeader.js';
+import readBuildStatusWait from '../utils/readBuildStatusWait.mjs';
+
 /*
 The manager owns the public port; the Vite child listens on an internal
 loopback port and every restart replaces only the child. Before this proxy the
@@ -32,6 +37,19 @@ While the child is down, requests and upgrades wait for it to come back
 covers a Vite respawn with headroom; a child that stays down longer than that
 answers 503 so callers are not held forever. In-flight streams cannot survive
 a child exit — those sockets close and the client reconnects into the hold.
+
+A child is probed until it answers once; after that, requests go straight to
+it for as long as that child process lives. Probing every request opened (and
+closed) one extra TCP connection per request, and a Vite page load is hundreds
+of module requests: each closed probe sits in TIME_WAIT, and a few dozen page
+loads within half a minute ran the machine out of ephemeral ports, failing
+unrelated connections. A proxied request that cannot reach the child, a child
+that exits, or a new child after a restart sends requests back through the
+probe and its hold. A restart first waits for the stopped child to exit, since
+until then it still answers the probe. A GET or HEAD that never reached the
+child (a refused connect, or a keep-alive socket the dying child had closed)
+is replayed through the hold rather than answered 502: a child can close its
+sockets before the manager sees it exit.
 */
 
 const RETRY_MS = 250;
@@ -51,8 +69,7 @@ function probeChild(port) {
   });
 }
 
-async function waitForChild({ port }) {
-  const deadline = Date.now() + HOLD_MS;
+async function waitForChild({ port, deadline }) {
   for (;;) {
     if (await probeChild(port)) return true;
     if (Date.now() > deadline) return false;
@@ -60,14 +77,57 @@ async function waitForChild({ port }) {
   }
 }
 
-function forwardRequest(context, req, res) {
+function isConfirmedChild({ context, proxyState }) {
+  const child = context.devServer;
+  return (
+    Boolean(child) &&
+    child === proxyState.confirmedChild &&
+    child.exitCode === null &&
+    child.signalCode === null
+  );
+}
+
+function waitUntil({ promise, deadline }) {
+  return Promise.race([
+    promise,
+    new Promise((resolve) => setTimeout(resolve, Math.max(0, deadline - Date.now()))),
+  ]);
+}
+
+async function waitForConfirmedChild({ context, proxyState, deadline }) {
+  if (isConfirmedChild({ context, proxyState })) {
+    return true;
+  }
+  await waitUntil({ promise: context.devServerExited, deadline });
+  const child = context.devServer;
+  const up = await waitForChild({ port: context.internalPort, deadline });
+  if (up) {
+    proxyState.confirmedChild = child;
+  }
+  return up;
+}
+
+const REPLAYABLE_METHODS = ['GET', 'HEAD'];
+
+// Nothing reached the child: the connect was refused, or the keep-alive socket
+// the agent reused had already been closed by a child that is going away.
+function isUnsentError({ error, proxyReq }) {
+  return (
+    error.code === 'ECONNREFUSED' || (proxyReq.reusedSocket === true && error.code === 'ECONNRESET')
+  );
+}
+
+function forwardRequest({ body, context, proxyState }, req, res, deadline = Date.now() + HOLD_MS) {
   // Wait for a live child BEFORE piping the request body — the body stream can
   // only be consumed once, so retrying after a failed proxy request would need
-  // full-body buffering. A probe-then-forward race (child dies between the
-  // probe and the connect) surfaces as one 502, which the client's next
-  // attempt resolves through the hold.
-  waitForChild({ port: context.internalPort }).then((up) => {
-    if (req.destroyed) return;
+  // full-body buffering. Only a bodiless GET or HEAD that never reached the
+  // child is replayed; any other request that loses the child mid-forward
+  // surfaces as one 502, which the client's next attempt resolves through the
+  // hold.
+  waitForConfirmedChild({ context, proxyState, deadline }).then((up) => {
+    // The response, not the request: an incoming request reads as destroyed
+    // once its body has been read, which a replayed GET's has.
+    if (res.destroyed) return;
     if (!up) {
       res.writeHead(503, { 'content-type': 'application/json' });
       res.end(JSON.stringify({ message: 'Lowdefy dev server is restarting.' }));
@@ -87,7 +147,16 @@ function forwardRequest(context, req, res) {
       res.flushHeaders?.();
       proxyRes.pipe(res);
     });
-    proxyReq.on('error', () => {
+    proxyReq.on('error', (error) => {
+      proxyState.confirmedChild = null;
+      if (
+        !res.headersSent &&
+        REPLAYABLE_METHODS.includes(req.method) &&
+        isUnsentError({ error, proxyReq })
+      ) {
+        forwardRequest({ body, context, proxyState }, req, res, deadline);
+        return;
+      }
       if (res.headersSent) {
         res.destroy();
         return;
@@ -95,7 +164,16 @@ function forwardRequest(context, req, res) {
       res.writeHead(502, { 'content-type': 'application/json' });
       res.end(JSON.stringify({ message: 'Lowdefy dev server connection dropped.' }));
     });
-    req.pipe(proxyReq);
+    // A body read to recognise a build-status wait is sent as read. A
+    // replayed GET's request stream has already ended, so there is nothing
+    // left to pipe.
+    if (body !== undefined) {
+      proxyReq.end(body);
+    } else if (req.readableEnded) {
+      proxyReq.end();
+    } else {
+      req.pipe(proxyReq);
+    }
     req.on('error', () => proxyReq.destroy());
     // A client that goes away mid-response (a closed browser tab holding the
     // reload SSE stream, an agent dropping its MCP stream) must reach the
@@ -107,8 +185,43 @@ function forwardRequest(context, req, res) {
   });
 }
 
+// Activity is use of the server. Not counted: a passive look (the hub's tab
+// poll, an agent's status read), and long-lived streams - an event stream a
+// client opens with a GET (the agent shim's MCP push stream, a tab's reload
+// stream) or a websocket - which live as long as the server and reconnect on
+// their own, so counting them would keep every server they touch alive. An
+// MCP tool call is a POST that may be answered as an event stream; it counts.
+function isActivity(req) {
+  if (req.headers[devPassiveHeader] === '1') {
+    return false;
+  }
+  const accept = req.headers.accept ?? '';
+  return !(req.method === 'GET' && accept.includes('text/event-stream'));
+}
+
+// A build-status wait is held here until the manager has processed the
+// latest edits, restarts included, and only then forwarded: a restart ends
+// the dev server process, and any wait running in it. The header tells the
+// dev server what this wait saw, so it does not wait again.
+async function handleRequest({ context, proxyState }, req, res) {
+  if (isActivity(req)) {
+    context.requestActivity.trackResponse(res);
+  }
+  delete req.headers[buildWaitHeader];
+  const { wait, body } = await readBuildStatusWait({ basePath: context.basePath, req });
+  if (wait) {
+    const waited = await context.buildActivity.waitForIdle();
+    req.headers[buildWaitHeader] = new URLSearchParams({
+      settled: String(waited.settled),
+      sawBuild: String(waited.sawBuild),
+      waitedMs: String(waited.waitedMs),
+    }).toString();
+  }
+  forwardRequest({ body, context, proxyState }, req, res);
+}
+
 function forwardUpgrade(context, req, socket, head) {
-  waitForChild({ port: context.internalPort }).then((up) => {
+  waitForChild({ port: context.internalPort, deadline: Date.now() + HOLD_MS }).then((up) => {
     if (socket.destroyed) return;
     if (!up) {
       socket.end('HTTP/1.1 503 Service Unavailable\r\nconnection: close\r\n\r\n');
@@ -136,7 +249,11 @@ function forwardUpgrade(context, req, socket, head) {
 
 function startProxy(context) {
   if (context.proxyServer) return Promise.resolve();
-  const proxy = http.createServer((req, res) => forwardRequest(context, req, res));
+  const proxyState = { confirmedChild: null };
+  const proxy = http.createServer((req, res) => {
+    // A client that drops an MCP request while its body is read.
+    handleRequest({ context, proxyState }, req, res).catch(() => res.destroy());
+  });
   proxy.on('upgrade', (req, socket, head) => forwardUpgrade(context, req, socket, head));
   // Long-lived streams (SSE, MCP) must not be reaped by the default 5-minute
   // request timeout; keep the proxy transparent.

package/manager/processes/startProxy.test.mjs

@@ -20,6 +20,8 @@ import net from 'node:net';
 import { jest } from '@jest/globals';
 
 const { default: startProxy } = await import('./startProxy.mjs');
+const { default: createBuildActivity } = await import('../utils/createBuildActivity.mjs');
+const { default: createRequestActivity } = await import('../utils/createRequestActivity.mjs');
 
 function listen(server) {
   return new Promise((resolve) => {
@@ -46,6 +48,7 @@ function getFreePort() {
 
 let child;
 let context;
+let activityRecords;
 
 afterEach(async () => {
   if (context?.proxyServer) await close(context.proxyServer);
@@ -57,10 +60,15 @@ afterEach(async () => {
 async function startChildAndProxy(handler) {
   child = http.createServer(handler);
   const internalPort = await listen(child);
+  activityRecords = [];
   context = {
     internalPort,
     options: { port: await getFreePort() },
     logger: { debug: jest.fn() },
+    requestActivity: createRequestActivity({
+      onChange: (fields) => activityRecords.push(fields),
+      throttleMs: 0,
+    }),
   };
   await startProxy(context);
   return context.options.port;
@@ -76,6 +84,101 @@ test('startProxy forwards a request to the child and relays its response', async
   expect(await response.json()).toEqual({ path: '/api/ping?x=1' });
 });
 
+test('startProxy probes a running child once instead of opening a connection per request', async () => {
+  let childConnections = 0;
+  const port = await startChildAndProxy((req, res) => {
+    res.writeHead(200, { 'content-type': 'text/plain' });
+    res.end('ok');
+  });
+  child.on('connection', () => {
+    childConnections += 1;
+  });
+  context.devServer = { exitCode: null, signalCode: null };
+
+  for (let i = 0; i < 20; i += 1) {
+    const response = await fetch(`http://localhost:${port}/module-${i}.js`);
+    expect(await response.text()).toBe('ok');
+  }
+
+  // One probe, then the keep-alive agent's socket - not a probe per request.
+  expect(childConnections).toBeLessThanOrEqual(2);
+});
+
+test('startProxy probes a new child after a restart before forwarding to it', async () => {
+  let childConnections = 0;
+  const port = await startChildAndProxy((req, res) => {
+    res.writeHead(200, { 'content-type': 'text/plain' });
+    res.end('ok');
+  });
+  child.on('connection', () => {
+    childConnections += 1;
+  });
+  context.devServer = { exitCode: null, signalCode: null };
+  await fetch(`http://localhost:${port}/a.js`).then((response) => response.text());
+  const afterFirstChild = childConnections;
+
+  context.devServer = { exitCode: null, signalCode: null };
+  await fetch(`http://localhost:${port}/b.js`).then((response) => response.text());
+
+  expect(childConnections).toBe(afterFirstChild + 1);
+});
+
+test('startProxy sends requests back through the hold once a confirmed child goes away', async () => {
+  function handler(req, res) {
+    res.end('ok');
+  }
+  const port = await startChildAndProxy(handler);
+  context.devServer = { exitCode: null, signalCode: null };
+  expect(await (await fetch(`http://localhost:${port}/a.js`)).text()).toBe('ok');
+
+  async function stopChildAndRestartSoon() {
+    await close(child);
+    setTimeout(() => {
+      child = http.createServer(handler);
+      child.listen(context.internalPort, '127.0.0.1');
+    }, 300);
+  }
+
+  // Gone before the manager has seen it exit: a GET never reached the child,
+  // so it is replayed through the hold and answered by the next child.
+  await stopChildAndRestartSoon();
+  expect(await (await fetch(`http://localhost:${port}/b.js`)).text()).toBe('ok');
+
+  // A POST's body was consumed by the failed forward, so it fails once, and
+  // the next request waits for the child instead of failing too.
+  await stopChildAndRestartSoon();
+  expect(
+    (await fetch(`http://localhost:${port}/save`, { method: 'POST', body: '{}' })).status
+  ).toBe(502);
+  expect(await (await fetch(`http://localhost:${port}/c.js`)).text()).toBe('ok');
+
+  // An exit the manager has seen sends the very next request through the hold.
+  await stopChildAndRestartSoon();
+  context.devServer.exitCode = 1;
+  expect(await (await fetch(`http://localhost:${port}/d.js`)).text()).toBe('ok');
+});
+
+test('startProxy waits for a stopped child to exit before probing its replacement', async () => {
+  const port = await startChildAndProxy((req, res) => res.end('old'));
+  context.devServer = { exitCode: null, signalCode: null };
+  expect(await (await fetch(`http://localhost:${port}/a.js`)).text()).toBe('old');
+
+  // A restart: the old child is signalled but answers until it exits.
+  let markExited;
+  context.devServerExited = new Promise((resolve) => {
+    markExited = resolve;
+  });
+  context.devServer = { exitCode: null, signalCode: null };
+  const pending = fetch(`http://localhost:${port}/b.js`).then((response) => response.text());
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  await close(child);
+  child = http.createServer((req, res) => res.end('new'));
+  await new Promise((resolve) => child.listen(context.internalPort, '127.0.0.1', resolve));
+  markExited();
+
+  expect(await pending).toBe('new');
+});
+
 test('startProxy aborts the child request when the client drops a streaming response', async () => {
   let upstreamClosed;
   const upstreamClosedPromise = new Promise((resolve) => {
@@ -100,3 +203,266 @@ test('startProxy aborts the child request when the client drops a streaming resp
   ]);
   expect(outcome).toBe('closed');
 });
+
+function echoRequest(label) {
+  return async (req, res) => {
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(
+      JSON.stringify({
+        label,
+        body: Buffer.concat(chunks).toString('utf8'),
+        buildWait: req.headers['x-lowdefy-build-wait'] ?? null,
+      })
+    );
+  };
+}
+
+function mcpCall(name, args) {
+  return JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/call',
+    params: { name, arguments: args },
+  });
+}
+
+test.each([
+  ['GET build-status?wait=true', () => ({ path: '/lowdefy-docs/build-status?wait=true' })],
+  [
+    'the lowdefy_build_status MCP tool with wait: true',
+    () => ({
+      path: '/lowdefy-docs/mcp',
+      init: { method: 'POST', body: mcpCall('lowdefy_build_status', { wait: true }) },
+    }),
+  ],
+])(
+  'startProxy holds %s through a restart and forwards it to the new server',
+  async (_, makeRequest) => {
+    const port = await startChildAndProxy(echoRequest('old'));
+    context.basePath = '';
+    context.buildActivity = createBuildActivity({ onChange: () => {} });
+    context.devServer = { exitCode: null, signalCode: null };
+    context.buildActivity.setBusy(true);
+    // waitedMs is timed from when the proxy starts waiting, a moment after the request is sent.
+    // Holding for 200ms from that moment, not from the fetch call, keeps the waitedMs assertion
+    // below from racing the request's arrival.
+    const { waitForIdle } = context.buildActivity;
+    const waitStarted = new Promise((resolve) => {
+      context.buildActivity.waitForIdle = (options) => {
+        const waiting = waitForIdle(options);
+        resolve();
+        return waiting;
+      };
+    });
+
+    const { path: requestPath, init } = makeRequest();
+    const pending = fetch(`http://localhost:${port}${requestPath}`, {
+      ...init,
+      headers: { 'x-lowdefy-build-wait': 'settled=true&sawBuild=false&waitedMs=0' },
+    }).then((response) => response.json());
+    await waitStarted;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+
+    // The restart the build needed: the old server stops, a new one answers.
+    context.devServerExited = Promise.resolve();
+    context.devServer = { exitCode: null, signalCode: null };
+    await close(child);
+    child = http.createServer(echoRequest('new'));
+    await new Promise((resolve) => child.listen(context.internalPort, '127.0.0.1', resolve));
+    context.buildActivity.setBusy(false);
+
+    const result = await pending;
+    expect(result.label).toBe('new');
+    expect(result.body).toBe(init?.body ?? '');
+    const wait = new URLSearchParams(result.buildWait);
+    expect(wait.get('settled')).toBe('true');
+    expect(wait.get('sawBuild')).toBe('true');
+    expect(Number(wait.get('waitedMs'))).toBeGreaterThanOrEqual(200);
+  }
+);
+
+test('startProxy forwards other MCP calls and build-status reads at once, with their body', async () => {
+  const port = await startChildAndProxy(echoRequest('child'));
+  context.basePath = '';
+  context.buildActivity = createBuildActivity({ onChange: () => {} });
+  context.buildActivity.setBusy(true);
+  const body = mcpCall('lowdefy_build_status', {});
+
+  const [call, read] = await Promise.all([
+    fetch(`http://localhost:${port}/lowdefy-docs/mcp`, {
+      method: 'POST',
+      body,
+      headers: { 'x-lowdefy-build-wait': 'settled=true' },
+    }).then((response) => response.json()),
+    fetch(`http://localhost:${port}/lowdefy-docs/build-status`).then((response) => response.json()),
+  ]);
+
+  expect(call).toEqual({ label: 'child', body, buildWait: null });
+  expect(read).toEqual({ label: 'child', body: '', buildWait: null });
+});
+
+const paddedWaitCall = mcpCall('lowdefy_build_status', { wait: true, pad: 'x'.repeat(70 * 1024) });
+const waitCall = mcpCall('lowdefy_build_status', { wait: true });
+
+test.each([
+  ['a body larger than 64 KiB', { body: paddedWaitCall }, paddedWaitCall],
+  [
+    'a streamed body without a length',
+    { body: new Blob([waitCall]).stream(), duplex: 'half' },
+    waitCall,
+  ],
+])('startProxy forwards an MCP POST with %s unread, without holding it', async (_, init, sent) => {
+  const port = await startChildAndProxy(echoRequest('child'));
+  context.basePath = '';
+  context.buildActivity = createBuildActivity({ onChange: () => {} });
+  context.buildActivity.setBusy(true);
+
+  const call = await fetch(`http://localhost:${port}/lowdefy-docs/mcp`, {
+    method: 'POST',
+    ...init,
+  }).then((response) => response.json());
+
+  expect(call).toEqual({ label: 'child', body: sent, buildWait: null });
+});
+
+function activeRequests() {
+  return activityRecords.at(-1).activeRequests;
+}
+
+async function waitFor(check) {
+  const deadline = Date.now() + 2000;
+  while (!check()) {
+    if (Date.now() > deadline) throw new Error('Condition not met within 2 seconds.');
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+// A child that holds every response open until release() is called.
+function heldHandler({ contentType = 'text/plain' } = {}) {
+  const held = [];
+  function handler(req, res) {
+    res.writeHead(200, { 'content-type': contentType });
+    res.flushHeaders();
+    if (contentType === 'text/event-stream') res.write('event: message\ndata: {}\n\n');
+    held.push(res);
+  }
+  function release() {
+    held.splice(0).forEach((res) => res.end('done'));
+  }
+  return { handler, held, release };
+}
+
+test('startProxy counts a request as activity for as long as it is in flight', async () => {
+  const child$ = heldHandler();
+  const port = await startChildAndProxy(child$.handler);
+  context.basePath = '';
+  expect(activeRequests()).toBe(0);
+
+  const pending = fetch(`http://localhost:${port}/api/request/page/get`).then((response) =>
+    response.text()
+  );
+  await waitFor(() => child$.held.length === 1);
+  expect(activeRequests()).toBe(1);
+
+  child$.release();
+  expect(await pending).toBe('done');
+  await waitFor(() => activeRequests() === 0);
+});
+
+test('startProxy counts an MCP POST answered as an event stream until it ends', async () => {
+  const child$ = heldHandler({ contentType: 'text/event-stream' });
+  const port = await startChildAndProxy(child$.handler);
+  context.basePath = '';
+
+  const pending = fetch(`http://localhost:${port}/lowdefy-docs/mcp`, {
+    method: 'POST',
+    headers: { accept: 'application/json, text/event-stream' },
+    body: mcpCall('lowdefy_screenshot', {}),
+  }).then((response) => response.text());
+  await waitFor(() => child$.held.length === 1);
+  expect(activeRequests()).toBe(1);
+
+  child$.release();
+  await pending;
+  await waitFor(() => activeRequests() === 0);
+});
+
+test.each([
+  ['a GET that opens an event stream', { accept: 'text/event-stream' }],
+  ['a passive request', { 'x-lowdefy-passive': '1' }],
+])('startProxy does not count %s as activity', async (_, headers) => {
+  const child$ = heldHandler({ contentType: 'text/event-stream' });
+  const port = await startChildAndProxy(child$.handler);
+  context.basePath = '';
+  const before = activityRecords.length;
+
+  const clientRequest = http.get(`http://localhost:${port}/lowdefy-docs/mcp`, { headers });
+  await new Promise((resolve) => clientRequest.on('response', resolve));
+  await waitFor(() => child$.held.length === 1);
+  clientRequest.destroy();
+  child$.release();
+  await new Promise((resolve) => setTimeout(resolve, 50));
+
+  expect(activityRecords.length).toBe(before);
+});
+
+test('startProxy ends the activity of a request whose client goes away', async () => {
+  const child$ = heldHandler();
+  const port = await startChildAndProxy(child$.handler);
+  context.basePath = '';
+
+  const clientRequest = http.get(`http://localhost:${port}/slow`);
+  clientRequest.on('error', () => {});
+  await waitFor(() => child$.held.length === 1);
+  expect(activeRequests()).toBe(1);
+
+  clientRequest.destroy();
+  await waitFor(() => activeRequests() === 0);
+  child$.release();
+});
+
+test('startProxy does not count a websocket upgrade as activity', async () => {
+  const port = await startChildAndProxy((req, res) => res.end('ok'));
+  const childSockets = [];
+  child.on('upgrade', (req, socket) => {
+    childSockets.push(socket);
+    socket.write(
+      'HTTP/1.1 101 Switching Protocols\r\nupgrade: websocket\r\nconnection: upgrade\r\n\r\n'
+    );
+  });
+  const before = activityRecords.length;
+
+  const clientRequest = http.get(`http://localhost:${port}/hmr`, {
+    headers: { connection: 'upgrade', upgrade: 'websocket' },
+  });
+  const socket = await new Promise((resolve) =>
+    clientRequest.on('upgrade', (res, upgraded) => resolve(upgraded))
+  );
+
+  expect(activityRecords.length).toBe(before);
+  socket.destroy();
+  childSockets.forEach((childSocket) => childSocket.destroy());
+});
+
+test('startProxy keeps a request held through a child restart counted', async () => {
+  const port = await startChildAndProxy((req, res) => res.end('old'));
+  context.basePath = '';
+  context.devServer = { exitCode: null, signalCode: null };
+  expect(await (await fetch(`http://localhost:${port}/a.js`)).text()).toBe('old');
+  await waitFor(() => activeRequests() === 0);
+
+  await close(child);
+  context.devServer.exitCode = 1;
+  const pending = fetch(`http://localhost:${port}/b.js`).then((response) => response.text());
+  await new Promise((resolve) => setTimeout(resolve, 300));
+  expect(activeRequests()).toBe(1);
+
+  context.devServer = { exitCode: null, signalCode: null };
+  child = http.createServer((req, res) => res.end('new'));
+  await new Promise((resolve) => child.listen(context.internalPort, '127.0.0.1', resolve));
+
+  expect(await pending).toBe('new');
+  await waitFor(() => activeRequests() === 0);
+});

package/manager/processes/startServer.mjs

@@ -15,8 +15,12 @@
 */
 
 import { spawn } from 'child_process';
+import crypto from 'crypto';
 
-import warnAuthUrlPortMismatch from './warnAuthUrlPortMismatch.mjs';
+import createServerEnv from '../utils/createServerEnv.mjs';
+import killTaggedBrowser from '../utils/killTaggedBrowser.mjs';
+import readBasePath from '../utils/readBasePath.mjs';
+import resolveDevAuthUrl from '../utils/resolveDevAuthUrl.mjs';
 
 function createStdErrLineHandler({ context }) {
   const port = context.internalPort;
@@ -33,7 +37,31 @@ function createStdErrLineHandler({ context }) {
 
 function startServer(context) {
   context.shutdownServer();
-  warnAuthUrlPortMismatch({ context });
+
+  // The app, its API and the /lowdefy-docs tools all live under basePath, and
+  // a config change that edits basePath restarts the child - so the URL is
+  // recorded on every start. Everything that finds this server through
+  // .lowdefy/instance.json (lowdefy mcp, the hub, lowdefy test) appends its
+  // paths to this URL.
+  context.basePath = readBasePath(context);
+  context.url = `http://localhost:${context.options.port}${context.basePath}`;
+  context.instance.update({ url: context.url });
+
+  const env = createServerEnv(context);
+  const configuredAuthUrl = process.env.BETTER_AUTH_URL;
+  const { authUrl, rewritten } = resolveDevAuthUrl({
+    configured: configuredAuthUrl,
+    port: context.options.port,
+  });
+  if (rewritten && context.loggedAuthUrl !== authUrl) {
+    context.logger.info(
+      `BETTER_AUTH_URL ${configuredAuthUrl} names another port; this dev server uses ${authUrl}.`
+    );
+    context.loggedAuthUrl = authUrl;
+  }
+
+  // New per child start, so killing one child's browser can match nothing else.
+  const browserTag = crypto.randomUUID();
 
   // The child binds context.internalPort on loopback; the manager's proxy owns
   // the public context.options.port (see startProxy.mjs) so a restart never
@@ -41,6 +69,8 @@ function startServer(context) {
   const devServer = spawn(
     'node',
     [
+      // For the child's idle GC (lib/server/startIdleGc.js).
+      '--expose-gc',
       context.bin.vite,
       '--host',
       '127.0.0.1',
@@ -49,11 +79,21 @@ function startServer(context) {
       '--strictPort',
     ],
     {
-      stdio: ['ignore', 'inherit', 'pipe'],
+      // The manager holds the child's stdin and never writes to it: the pipe
+      // closes when the manager dies, however it dies (SIGKILL, out of
+      // memory), and the child exits on that (see vite.config.js).
+      stdio: ['pipe', 'inherit', 'pipe'],
       env: {
-        ...process.env,
-        LOWDEFY_DIRECTORY_CONFIG: context.directories.config,
-        PORT: context.internalPort,
+        ...env,
+        LOWDEFY_BROWSER_TAG: browserTag,
+        LOWDEFY_EXIT_ON_STDIN_CLOSE: '1',
+        // The manager's owner and registry record cover the child: it does
+        // not register, and it lives and dies with the manager.
+        LOWDEFY_EXIT_WITH_PID: undefined,
+        LOWDEFY_SERVER_REGISTRY_DIR: undefined,
+        // Reported as the MCP serverInfo version: lowdefy mcp takes each
+        // tool's definition from the newest Lowdefy version it meets.
+        LOWDEFY_SERVER_DEV_VERSION: context.version,
       },
     }
   );
@@ -71,6 +111,7 @@ function startServer(context) {
   context.logger.debug(`Started dev server with pid ${devServer.pid}.`);
   devServer.on('exit', (code, signal) => {
     context.logger.debug(`devServer exit ${devServer.pid}, signal: ${signal}, code: ${code}`);
+    killTaggedBrowser({ tag: browserTag });
   });
   devServer.on('error', (error) => {
     context.logger.error(error);