@lowdefy/server-dev 6.1.0 → 7.1.0

package/lib/docs/getOverviewBasePath.test.mjs

@@ -0,0 +1,37 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+import path from 'path';
+
+import setupTestFixtures from './setupTestFixtures.mjs';
+
+// lib/build/config.js reads build/config.json from process.cwd() at import
+// time, so the fixture carries the basePath before getOverview is imported.
+const fixtureDir = setupTestFixtures();
+fs.writeFileSync(path.join(fixtureDir, 'build/config.json'), JSON.stringify({ basePath: '/app' }));
+fs.writeFileSync(path.join(fixtureDir, 'build', 'routes.json'), JSON.stringify([]));
+process.chdir(fixtureDir);
+
+const { default: getOverview } = await import('./getOverview.js');
+
+test('getOverview tells agents the docs routes are served under the app basePath', () => {
+  const overview = getOverview();
+
+  expect(overview).toContain(
+    'This app sets `config.basePath: /app`, so every route below is served under it: `GET /app/lowdefy-docs`, `/app/lowdefy-docs/mcp`, `/app/api/...`.'
+  );
+});

package/lib/docs/getPageBuildStatus.js

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import reviewPageBuilds from './reviewPageBuilds.js';
+
+// The page side of build status. The dev server builds a page when it is first
+// requested, so the config build's status says nothing about page content:
+// this reports the pages whose latest build failed, the pages changed since
+// they were built, and how many pages nothing has built yet. checked is the
+// list of pages build status just built (wait: true).
+async function getPageBuildStatus({ checked } = {}) {
+  const { edited, unbuilt, failed } = await reviewPageBuilds();
+  const status = {};
+  if (checked) {
+    status.checked = checked;
+  }
+  if (failed.length > 0) {
+    status.failed = failed;
+  }
+  if (edited.length > 0) {
+    status.changedSinceBuild = edited;
+    status.changedSinceBuildNote = checked
+      ? 'These pages changed on disk after their last build, but the dev server has not rebuilt them: it has not seen the change yet. Call again; if they stay here, the file watcher missed the edit.'
+      : 'These pages, or the config build they build against, changed after their last build and have not been rebuilt, so their errors are not known yet. Call with wait: true to build them.';
+  }
+  status.unbuilt = unbuilt.length;
+  if (unbuilt.length > 0) {
+    status.unbuiltNote = `${unbuilt.length} page(s) have not been built since the dev server started, so this status does not cover them. lowdefy_check validates every page.`;
+  }
+  return status;
+}
+
+export default getPageBuildStatus;

package/lib/docs/getPluginDoc.js

@@ -15,40 +15,38 @@
 */
 
 import fs from 'node:fs';
-import path from 'node:path';
 import { type } from '@lowdefy/helpers';
 
+import listPackageDocFiles from './listPackageDocFiles.js';
+import readBuildArtifact from './readBuildArtifact.js';
+import readPluginPackages from './readPluginPackages.js';
 import resolvePluginDir from './resolvePluginDir.js';
 
-// Local plugins have no doc convention — probe the common locations and
-// return whatever markdown ships with the package.
+// The package name comes from the caller, and a name such as "../../x" would
+// resolve outside node_modules, so only the app's own plugins are read.
+function isAppPlugin({ packageName }) {
+  const installed = readBuildArtifact({ name: 'installedPluginPackages.json' }) ?? [];
+  if (installed.includes(packageName)) {
+    return true;
+  }
+  return readPluginPackages().some((plugin) => plugin.package === packageName);
+}
+
+// Every markdown file a plugin package ships, joined into one document.
 function getPluginDoc({ packageName }) {
+  if (!isAppPlugin({ packageName })) {
+    return null;
+  }
   const pluginDir = resolvePluginDir({ packageName });
   if (type.isNone(pluginDir)) {
     return null;
   }
-  const sections = [];
-  for (const readme of ['README.md', 'readme.md']) {
-    const readmePath = path.join(pluginDir, readme);
-    if (fs.existsSync(readmePath)) {
-      sections.push(fs.readFileSync(readmePath, 'utf8'));
-      break;
-    }
-  }
-  for (const docsDir of ['docs', 'dist/docs']) {
-    const dirPath = path.join(pluginDir, docsDir);
-    if (!fs.existsSync(dirPath)) {
-      continue;
-    }
-    for (const fileName of fs.readdirSync(dirPath).sort()) {
-      if (fileName.endsWith('.md')) {
-        sections.push(fs.readFileSync(path.join(dirPath, fileName), 'utf8'));
-      }
-    }
-  }
-  if (sections.length === 0) {
+  const { readme, docs } = listPackageDocFiles({ dir: pluginDir });
+  const files = type.isNone(readme) ? docs : [readme, ...docs];
+  if (files.length === 0) {
     return null;
   }
+  const sections = files.map((filePath) => fs.readFileSync(filePath, 'utf8'));
   return { package: packageName, markdown: sections.join('\n\n---\n\n') };
 }
 

package/lib/docs/getSchema.js

@@ -15,7 +15,9 @@
 */
 
 import { type } from '@lowdefy/helpers';
+import { JOURNEY_STEP_SCHEMAS, journeyStepSchema } from '@lowdefy/node-utils';
 
+import getHazards from './getHazards.js';
 import normalizeTypeKind from './normalizeTypeKind.js';
 import readBuildArtifact from './readBuildArtifact.js';
 
@@ -27,11 +29,40 @@ const SCHEMA_ARTIFACTS = {
   requests: 'plugins/requestSchemas.json',
 };
 
+const JOURNEY_STEP_KINDS = ['journey-step', 'journey-steps'];
+
+// kind journey-step returns the journey step grammar: every step, or the one
+// step `type` names.
+function getJourneyStepSchema({ typeName }) {
+  if (type.isNone(typeName) || typeName === '' || typeName === 'all') {
+    return { kind: 'journey-step', schema: journeyStepSchema };
+  }
+  const schema = JOURNEY_STEP_SCHEMAS[typeName];
+  if (type.isNone(schema)) {
+    return null;
+  }
+  return { kind: 'journey-step', type: typeName, schema };
+}
+
 function getSchema({ kind, type: typeName }) {
+  if (JOURNEY_STEP_KINDS.includes(String(kind ?? '').toLowerCase())) {
+    return getJourneyStepSchema({ typeName });
+  }
   const normalizedKind = normalizeTypeKind({ kind });
   if (type.isNone(SCHEMA_ARTIFACTS[normalizedKind])) {
     throw new Error(
-      `No schemas available for type kind. Received ${JSON.stringify(kind)}. Use one of: blocks, operators, actions, connections, requests.`
+      `No schemas available for type kind. Received ${JSON.stringify(
+        kind
+      )}. Use one of: blocks, operators, actions, connections, requests, or journey-step for the journey step grammar.`
+    );
+  }
+  // type is optional only for journey-step, so a type kind without one is
+  // refused rather than looked up as "undefined".
+  if (type.isNone(typeName) || typeName === '') {
+    throw new Error(
+      `Getting a ${normalizedKind} schema requires a "type", the exact type name. Received ${JSON.stringify(
+        typeName
+      )}.`
     );
   }
   const schemas = readBuildArtifact({ name: SCHEMA_ARTIFACTS[normalizedKind] }) ?? {};
@@ -59,6 +90,7 @@ function getSchema({ kind, type: typeName }) {
       result.meta = blockMetas[typeName];
     }
   }
+  result.hazards = getHazards({ kind: normalizedKind, type: typeName });
   return result;
 }
 

package/lib/docs/getStaleStatus.js

@@ -0,0 +1,36 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import readBuildArtifact from './readBuildArtifact.js';
+
+// When a dev rebuild fails the manager writes status "error" to
+// build/buildStatus.json but leaves the previous build's artifacts in place, so
+// every docs read keeps answering from a build that predates the caller's
+// edits. Returns null — not { stale: false } — when the build is ok or unknown:
+// a response with no stale fields means not stale, and a false flag on every
+// response costs tokens on every call.
+function getStaleStatus() {
+  const build = readBuildArtifact({ name: 'buildStatus.json' });
+  if (build?.status !== 'error') return null;
+  return {
+    stale: true,
+    staleSince: build.timestamp ?? null,
+    staleReason:
+      'The last build failed. The dev server is still serving the previous successful build, so this result may not reflect your latest edits. Call lowdefy_build_status (or GET /lowdefy-docs/build-status) for the errors.',
+  };
+}
+
+export default getStaleStatus;

package/lib/docs/getStaleStatus.test.mjs

@@ -0,0 +1,74 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+// getStaleStatus reads build/buildStatus.json from process.cwd() — point it at
+// a throwaway server directory before the module is imported.
+const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-stale-test-'));
+fs.mkdirSync(path.join(fixtureDir, 'build'));
+process.chdir(fixtureDir);
+
+const statusPath = path.join(fixtureDir, 'build', 'buildStatus.json');
+
+function writeStatus(status) {
+  fs.writeFileSync(statusPath, JSON.stringify(status));
+}
+
+function removeStatus() {
+  if (fs.existsSync(statusPath)) fs.rmSync(statusPath);
+}
+
+const { default: getStaleStatus } = await import('./getStaleStatus.js');
+
+test('getStaleStatus returns null when buildStatus.json is missing', () => {
+  removeStatus();
+  expect(getStaleStatus()).toBe(null);
+});
+
+test('getStaleStatus returns null when the build status is ok', () => {
+  writeStatus({ status: 'ok', timestamp: '2026-01-01T00:00:00.000Z', errors: [], warnings: [] });
+  expect(getStaleStatus()).toBe(null);
+});
+
+test('getStaleStatus returns null when the build status is unknown', () => {
+  writeStatus({ status: 'unknown' });
+  expect(getStaleStatus()).toBe(null);
+});
+
+test('getStaleStatus returns the stale fields with the artifact timestamp when the build failed', () => {
+  writeStatus({
+    status: 'error',
+    timestamp: '2026-02-03T04:05:06.000Z',
+    errors: [{ message: 'Block type "Buton" not found.' }],
+  });
+  const status = getStaleStatus();
+  expect(status.stale).toBe(true);
+  expect(status.staleSince).toEqual('2026-02-03T04:05:06.000Z');
+  expect(status.staleReason).toContain('The last build failed.');
+  expect(status.staleReason).toContain('lowdefy_build_status');
+});
+
+test('getStaleStatus returns a null staleSince when the failed build has no timestamp', () => {
+  writeStatus({ status: 'error', errors: [] });
+  expect(getStaleStatus()).toEqual({
+    stale: true,
+    staleSince: null,
+    staleReason: expect.any(String),
+  });
+});

package/lib/docs/guardJourneyOrigin.js

@@ -0,0 +1,39 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+const DEFAULT_PORTS = { 'http:': '80', 'https:': '443' };
+
+function portOf(url) {
+  return url.port === '' ? DEFAULT_PORTS[url.protocol] : url.port;
+}
+
+// The data cookie is set for the journey's origin only, so a request to the dev server's port on
+// another host (127.0.0.1 against localhost, [::1], a LAN address) would carry none and read the
+// real database as a signed-out caller. Such requests are aborted before they leave the browser and
+// handed to onLeave; requests to other ports and other sites are untouched.
+async function guardJourneyOrigin({ context, origin, onLeave }) {
+  const originUrl = new URL(origin);
+  const originPort = portOf(originUrl);
+  await context.route(
+    (url) => portOf(url) === originPort && url.hostname !== originUrl.hostname,
+    async (route) => {
+      onLeave(route.request().url());
+      await route.abort('blockedbyclient');
+    }
+  );
+}
+
+export default guardJourneyOrigin;

package/lib/docs/inspectState.js

@@ -22,25 +22,27 @@ import resolveSource from './resolveSource.js';
 // headless-only. Falls back to headless whenever the tab path isn't usable
 // (no tab connected, or `source: 'tab'` was requested but it errored) so
 // agents always get an answer.
-async function inspectState({ origin, pageId, source, user }) {
+async function inspectState({ origin, pageId, pathParams, source, user, data }) {
   const { tryTab, error, invalidInput } = resolveSource({
     name: 'inspectState',
     pageId,
+    pathParams,
     source,
     user,
+    data,
   });
   if (error) {
     return { error, invalidInput };
   }
 
   if (tryTab) {
-    const result = await inspectStateFromTab({ pageId });
+    const result = await inspectStateFromTab({ pageId, pathParams });
     if (!result?.error) {
       return { ...result, source: 'tab' };
     }
   }
 
-  const result = await inspectStateHeadless({ origin, pageId, user });
+  const result = await inspectStateHeadless({ origin, pageId, pathParams, user, data });
   return { ...result, source: 'headless' };
 }
 

package/lib/docs/inspectStateFromTab.js

@@ -26,8 +26,8 @@ import { requestFromTab } from './tabChannel.js';
 // (see tabChannel.js) — a serialized snapshot string on success, or an
 // `{ error }` object if no tab is connected, the request timed out, or
 // Inspector.jsx itself failed to build the snapshot.
-async function inspectStateFromTab({ pageId } = {}) {
-  const response = await requestFromTab({ pageId, event: 'inspect-request' });
+async function inspectStateFromTab({ pageId, pathParams } = {}) {
+  const response = await requestFromTab({ pageId, pathParams, event: 'inspect-request' });
   if (response?.error) {
     return { error: response.error };
   }

package/lib/docs/inspectStateHeadless.js

@@ -17,18 +17,27 @@
 import { type } from '@lowdefy/helpers';
 
 import { getBrowser, openPage, buildPageUrl } from './getBrowser.js';
+import noBrowserError from './noBrowserError.js';
+import resolvePageInstance from './resolvePageInstance.js';
+import resolveToolCaller from './resolveToolCaller.js';
+import unsettledPageNote from './unsettledPageNote.js';
+import withBrowserSlot from './withBrowserSlot.js';
+import withDataSession from './withDataSession.js';
 
 // Collects a state snapshot from a headless Chromium tab navigated to the
-// page's own route. Mirrors Inspector.jsx's buildSnapshot (the live-tab
+// page instance's own route (`pathParams` fill a patterned page's placeholders),
+// read under the instance key. Mirrors Inspector.jsx's buildSnapshot (the live-tab
 // equivalent), but window.lowdefy does not expose the app's serializer, so
 // the snapshot is round-tripped through JSON.parse(JSON.stringify(...))
 // inside the page instead. That strips functions/undefined and turns Dates
 // into plain ISO strings — good enough for agent inspection, just not a
 // byte-for-byte match of the app's own `~d`-tagged serialization.
-async function inspectStateHeadless({ origin, pageId, user, timeout = 15000 }) {
+async function inspectStateHeadless({ origin, pageId, pathParams, user, data, timeout = 15000 }) {
   if (type.isNone(origin) || !type.isString(origin)) {
     return {
-      error: `inspectStateHeadless requires an "origin" string. Received ${JSON.stringify(origin)}.`,
+      error: `inspectStateHeadless requires an "origin" string. Received ${JSON.stringify(
+        origin
+      )}.`,
     };
   }
   if (type.isNone(pageId) || !type.isString(pageId)) {
@@ -37,40 +46,93 @@ async function inspectStateHeadless({ origin, pageId, user, timeout = 15000 }) {
     };
   }
 
+  const instance = resolvePageInstance({ pageId, pathParams });
+  if (!type.isUndefined(instance.error)) {
+    return { error: instance.error, invalidInput: true };
+  }
+
+  const caller = await resolveToolCaller({ user, data });
+  if (!type.isUndefined(caller.error)) {
+    return caller;
+  }
+
+  return withBrowserSlot({
+    task: () =>
+      withDataSession({
+        dataSet: caller.dataSet,
+        task: ({ dataCookie }) =>
+          inspectStateInBrowser({
+            origin,
+            pageId,
+            pathParams,
+            instance,
+            user: caller.user,
+            dataCookie,
+            timeout,
+          }),
+      }),
+  });
+}
+
+// The part of inspectStateHeadless that runs in the browser, inside a browser slot.
+async function inspectStateInBrowser({
+  origin,
+  pageId,
+  pathParams,
+  instance,
+  user,
+  dataCookie,
+  timeout,
+}) {
   let browser;
   try {
     browser = await getBrowser();
   } catch (error) {
-    return {
-      error: `No Chromium available. Run: npx playwright install chromium (${error.message})`,
-    };
+    return { error: noBrowserError(error) };
   }
 
-  const url = buildPageUrl({ origin, pageId });
+  const url = buildPageUrl({ origin, pageId, path: instance.path, pathParams });
 
   let context;
   try {
-    const opened = await openPage({ browser, origin, pageId, user, timeout });
+    const opened = await openPage({
+      browser,
+      origin,
+      pageId,
+      path: instance.path,
+      pathParams,
+      user,
+      dataCookie,
+      timeout,
+    });
     context = opened.context;
-    const snapshot = await opened.page.evaluate((id) => {
-      const lowdefy = window.lowdefy;
-      const pageContext = lowdefy?.contexts?.[`page:${id}`];
-      if (!pageContext) {
-        return { error: `No live context for page "${id}".` };
-      }
-      return JSON.parse(
-        JSON.stringify({
-          pageId: id,
-          state: pageContext.state,
-          requests: pageContext.requests,
-          eventLog: (pageContext.eventLog ?? []).slice(-50),
-          global: lowdefy.lowdefyGlobal,
-          user: lowdefy.user,
-          input: lowdefy.inputs?.[`page:${id}`],
-          urlQuery: window.location.search,
-        })
-      );
-    }, pageId);
+    const snapshot = await opened.page.evaluate(
+      ({ id, instanceKey, path }) => {
+        const lowdefy = window.lowdefy;
+        const pageContext = lowdefy?.contexts?.[instanceKey];
+        if (!pageContext) {
+          return { error: `No live context for page "${id}" at "/${path}".` };
+        }
+        return JSON.parse(
+          JSON.stringify({
+            pageId: id,
+            pathParams: pageContext.pathParams,
+            instanceKey,
+            state: pageContext.state,
+            requests: pageContext.requests,
+            eventLog: (pageContext.eventLog ?? []).slice(-50),
+            global: lowdefy.lowdefyGlobal,
+            user: lowdefy.user,
+            input: lowdefy.inputs?.[instanceKey],
+            urlQuery: window.location.search,
+          })
+        );
+      },
+      { id: pageId, instanceKey: instance.instanceKey, path: instance.path }
+    );
+    if (!opened.ready) {
+      return { ...snapshot, ready: false, note: unsettledPageNote({ timeout }) };
+    }
     return snapshot;
   } catch (error) {
     return { error: `Failed to inspect state at "${url}": ${error.message}` };

package/lib/docs/inspectStateHeadless.test.mjs

@@ -25,7 +25,10 @@ import { jest } from '@jest/globals';
 // screenshotPage.test.mjs, which exercises the same getBrowser.js singleton.
 jest.unstable_mockModule('playwright-core', () => ({
   chromium: { launch: jest.fn().mockRejectedValue(new Error("Executable doesn't exist")) },
+  selectors: { register: jest.fn(async () => {}) },
 }));
+// A missing shell would otherwise start a real download.
+jest.unstable_mockModule('./installHeadlessShell.js', () => ({ default: () => null }));
 
 // lib/build/config.js reads build/config.json from process.cwd() at import
 // time — chdir into a fixture that has one before getBrowser.js (which
@@ -35,6 +38,10 @@ const originalCwd = process.cwd();
 const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lowdefy-inspect-state-test-'));
 fs.mkdirSync(path.join(fixtureDir, 'build'), { recursive: true });
 fs.writeFileSync(path.join(fixtureDir, 'build', 'config.json'), JSON.stringify({ basePath: '' }));
+fs.writeFileSync(
+  path.join(fixtureDir, 'build', 'routes.json'),
+  JSON.stringify([{ pageId: 'ticket', path: 'tickets/{space}/{ticket_id}' }])
+);
 process.chdir(fixtureDir);
 
 const { default: inspectStateHeadless } = await import('./inspectStateHeadless.js');
@@ -56,5 +63,17 @@ test('inspectStateHeadless returns an error when pageId is missing', async () =>
 
 test('inspectStateHeadless returns an actionable error when no browser is available', async () => {
   const result = await inspectStateHeadless({ origin: 'http://localhost:3001', pageId: 'home' });
-  expect(result.error).toMatch(/No Chromium available. Run: npx playwright install chromium/);
+  expect(result.error).toMatch(
+    /No Chromium available. Run: npx playwright install chromium-headless-shell/
+  );
+});
+
+test('inspectStateHeadless returns the error naming a missing placeholder before opening a browser', async () => {
+  const result = await inspectStateHeadless({
+    origin: 'http://localhost:3001',
+    pageId: 'ticket',
+    pathParams: { space: 's' },
+  });
+  expect(result.invalidInput).toBe(true);
+  expect(result.error).toMatch(/missing a value for path placeholder "ticket_id"/);
 });

package/lib/docs/installHeadlessShell.failure.test.mjs

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { EventEmitter } from 'node:events';
+
+import { jest } from '@jest/globals';
+
+const mockSpawn = jest.fn();
+jest.unstable_mockModule('child_process', () => ({ spawn: mockSpawn, spawnSync: jest.fn() }));
+
+// A file of its own: installHeadlessShell keeps its one install per process
+// in module state.
+const { default: installHeadlessShell } = await import('./installHeadlessShell.js');
+
+test('installHeadlessShell logs a failed install once and does not retry it in this process', async () => {
+  const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+  jest.spyOn(console, 'info').mockImplementation(() => {});
+  const installer = Object.assign(new EventEmitter(), { stderr: new EventEmitter() });
+  mockSpawn.mockReturnValue(installer);
+
+  const install = installHeadlessShell();
+  installer.stderr.emit('data', Buffer.from('Download failed: server returned code 503'));
+  installer.emit('exit', 1);
+  // An error event after exit (or before it) must not log twice.
+  installer.emit('error', new Error('spawn EPIPE'));
+
+  expect(await install).toMatchObject({ installed: false });
+  expect(installHeadlessShell()).toBe(install);
+  expect(mockSpawn).toHaveBeenCalledTimes(1);
+  expect(warn).toHaveBeenCalledTimes(1);
+  expect(warn.mock.calls[0][0]).toContain('Download failed: server returned code 503');
+});