@lowdefy/server-dev 6.1.0 → 7.0.0

package/manager/utils/createBuildActivity.mjs

@@ -0,0 +1,67 @@
+/*
+  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 { wait } from '@lowdefy/helpers';
+
+// Whether the manager is processing a change: a watcher batch from its first
+// change until it is handled, a config build, a plugin install, a server
+// restart until the new server answers. lowdefy_build_status({ wait: true })
+// waits on it, so an agent reads the build - and talks to the server - that
+// includes its last edit. onChange mirrors it into the instance record for
+// readers in other processes; the proxy waits on it here, in the manager,
+// because a restart ends every wait running in the dev server.
+function createBuildActivity({ onChange }) {
+  let active = 0;
+
+  function setBusy(busy) {
+    active += busy ? 1 : -1;
+    onChange(active > 0);
+  }
+
+  async function track(task) {
+    setBusy(true);
+    try {
+      return await task();
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  // An edit reaches a watcher a moment after it is saved, so the wait first
+  // gives the watchers graceMs to start on it.
+  async function waitForIdle({ graceMs = 1000, timeoutMs = 120000, intervalMs = 50 } = {}) {
+    const start = Date.now();
+    let sawBuild = false;
+    while (Date.now() - start < graceMs) {
+      if (active > 0) {
+        sawBuild = true;
+        break;
+      }
+      await wait(intervalMs);
+    }
+    while (active > 0) {
+      if (Date.now() - start > timeoutMs) {
+        return { settled: false, sawBuild, waitedMs: Date.now() - start };
+      }
+      await wait(intervalMs);
+    }
+    return { settled: true, sawBuild, waitedMs: Date.now() - start };
+  }
+
+  return { setBusy, track, waitForIdle };
+}
+
+export default createBuildActivity;

package/manager/utils/createBuildActivity.test.mjs

@@ -0,0 +1,58 @@
+/*
+  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 { jest } from '@jest/globals';
+
+import createBuildActivity from './createBuildActivity.mjs';
+
+test('waitForIdle waits for tracked work to finish and reports that it saw a build', async () => {
+  const onChange = jest.fn();
+  const activity = createBuildActivity({ onChange });
+  let finish;
+  const work = activity.track(
+    () =>
+      new Promise((resolve) => {
+        finish = resolve;
+      })
+  );
+  const waiting = activity.waitForIdle({ graceMs: 100, intervalMs: 10 });
+  await new Promise((resolve) => setTimeout(resolve, 150));
+  finish('done');
+
+  await expect(work).resolves.toBe('done');
+  await expect(waiting).resolves.toMatchObject({ settled: true, sawBuild: true });
+  expect(onChange.mock.calls).toEqual([[true], [false]]);
+});
+
+test('waitForIdle stays busy while overlapping work remains', async () => {
+  const activity = createBuildActivity({ onChange: () => {} });
+  activity.setBusy(true);
+  activity.setBusy(true);
+  activity.setBusy(false);
+
+  await expect(
+    activity.waitForIdle({ graceMs: 10, timeoutMs: 100, intervalMs: 10 })
+  ).resolves.toMatchObject({ settled: false, sawBuild: true });
+});
+
+test('waitForIdle returns after the grace window when nothing starts', async () => {
+  const activity = createBuildActivity({ onChange: () => {} });
+
+  await expect(activity.waitForIdle({ graceMs: 30, intervalMs: 10 })).resolves.toMatchObject({
+    settled: true,
+    sawBuild: false,
+  });
+});

package/manager/utils/createChangeSignal.mjs

@@ -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.
+*/
+
+import fs from 'fs';
+import path from 'path';
+
+// build/invalidatePages tells the dev server that watched files changed: the
+// server reads it by value, so every write must differ from the one before,
+// even two in one millisecond. The value stays a timestamp, which build status
+// reads as the time of the latest edit.
+function createChangeSignal({ buildDirectory }) {
+  const filePath = path.join(buildDirectory, 'invalidatePages');
+  let last = 0;
+  try {
+    last = Number(fs.readFileSync(filePath, 'utf8')) || 0;
+  } catch {
+    // No change signalled yet.
+  }
+  return function writeChangeSignal() {
+    last = Math.max(Date.now(), last + 1);
+    fs.writeFileSync(filePath, String(last));
+    return last;
+  };
+}
+
+export default createChangeSignal;

package/manager/utils/createChangeSignal.test.mjs

@@ -0,0 +1,62 @@
+/*
+  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';
+import { jest } from '@jest/globals';
+
+import createChangeSignal from './createChangeSignal.mjs';
+
+function readSignal(buildDirectory) {
+  return Number(fs.readFileSync(path.join(buildDirectory, 'invalidatePages'), 'utf8'));
+}
+
+afterEach(() => {
+  jest.restoreAllMocks();
+});
+
+test('each write gives build/invalidatePages a new, larger value, even within one millisecond', () => {
+  const buildDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'ldf-change-signal-'));
+  jest.spyOn(Date, 'now').mockReturnValue(5000);
+  const writeChangeSignal = createChangeSignal({ buildDirectory });
+
+  expect(writeChangeSignal()).toBe(5000);
+  expect(readSignal(buildDirectory)).toBe(5000);
+  expect(writeChangeSignal()).toBe(5001);
+  expect(readSignal(buildDirectory)).toBe(5001);
+  fs.rmSync(buildDirectory, { recursive: true, force: true });
+});
+
+test('a new manager continues above the value the last one wrote', () => {
+  const buildDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'ldf-change-signal-'));
+  fs.writeFileSync(path.join(buildDirectory, 'invalidatePages'), '9000');
+  jest.spyOn(Date, 'now').mockReturnValue(5000);
+
+  expect(createChangeSignal({ buildDirectory })()).toBe(9001);
+  fs.rmSync(buildDirectory, { recursive: true, force: true });
+});
+
+test('the value is the current time when the clock is ahead of the last value', () => {
+  const buildDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'ldf-change-signal-'));
+  const writeChangeSignal = createChangeSignal({ buildDirectory });
+  jest.spyOn(Date, 'now').mockReturnValue(5000);
+  writeChangeSignal();
+  Date.now.mockReturnValue(7000);
+
+  expect(writeChangeSignal()).toBe(7000);
+  fs.rmSync(buildDirectory, { recursive: true, force: true });
+});

package/manager/utils/createCustomPluginMessagesMap.mjs

@@ -16,10 +16,8 @@
 */
 
 import { createRequire } from 'node:module';
-import path from 'path';
-import { get } from '@lowdefy/helpers';
-import { readFile } from '@lowdefy/node-utils';
-import YAML from 'yaml';
+import importFresh from './importFresh.mjs';
+import readPluginDefinitions from './readPluginDefinitions.mjs';
 
 const require = createRequire(import.meta.url);
 
@@ -27,38 +25,30 @@ const require = createRequire(import.meta.url);
 // process instead of repeating the same skip message on each rebuild.
 const warnedMissingMessages = new Set();
 
-async function getPluginDefinitions({ directories }) {
-  let lowdefyYaml = await readFile(path.join(directories.config, 'lowdefy.yaml'));
-  if (!lowdefyYaml) {
-    lowdefyYaml = await readFile(path.join(directories.config, 'lowdefy.yml'));
-  }
-  if (!lowdefyYaml) {
-    return [];
-  }
-  const lowdefy = YAML.parse(lowdefyYaml);
-  return get(lowdefy, 'plugins', { default: [] });
-}
-
 async function createCustomPluginMessagesMap({ directories, logger }) {
   const customMessagesMap = {};
-  const pluginDefinitions = await getPluginDefinitions({ directories });
-
-  for (const plugin of pluginDefinitions) {
-    let messagesModule;
-    try {
-      messagesModule = require(`${plugin.name}/messages`);
-    } catch (e) {
-      // Plugin does not ship a `./messages` export — silently skip.
-      if (!warnedMissingMessages.has(plugin.name)) {
-        warnedMissingMessages.add(plugin.name);
-        logger?.debug?.(`Plugin "${plugin.name}" has no "./messages" export; skipping.`);
+  const pluginDefinitions = await readPluginDefinitions({ directories });
+
+  // Each import starts a worker, so the plugins are imported in parallel.
+  await Promise.all(
+    pluginDefinitions.map(async (plugin) => {
+      let messagesPath;
+      try {
+        messagesPath = require.resolve(`${plugin.name}/messages`);
+      } catch (e) {
+        // Plugin does not ship a `./messages` export — silently skip.
+        if (!warnedMissingMessages.has(plugin.name)) {
+          warnedMissingMessages.add(plugin.name);
+          logger?.debug?.(`Plugin "${plugin.name}" has no "./messages" export; skipping.`);
+        }
+        return;
       }
-      continue;
-    }
-    const messages = messagesModule.default ?? messagesModule;
-    if (!messages || typeof messages !== 'object') continue;
-    customMessagesMap[plugin.name] = messages;
-  }
+      const messagesModule = await importFresh(messagesPath);
+      const messages = messagesModule.default ?? messagesModule;
+      if (!messages || typeof messages !== 'object') return;
+      customMessagesMap[plugin.name] = messages;
+    })
+  );
 
   return customMessagesMap;
 }

package/manager/utils/createCustomPluginTypesMap.mjs

@@ -16,40 +16,27 @@
 */
 
 import { createRequire } from 'node:module';
-import path from 'path';
-import { get } from '@lowdefy/helpers';
-import { readFile } from '@lowdefy/node-utils';
 import { createPluginTypesMap } from '@lowdefy/build';
-import YAML from 'yaml';
+import importFresh from './importFresh.mjs';
+import readPluginDefinitions from './readPluginDefinitions.mjs';
 
 const require = createRequire(import.meta.url);
 
-async function getPluginDefinitions({ directories }) {
-  let lowdefyYaml = await readFile(path.join(directories.config, 'lowdefy.yaml'));
-  if (!lowdefyYaml) {
-    lowdefyYaml = await readFile(path.join(directories.config, 'lowdefy.yml'));
-  }
-  if (!lowdefyYaml) {
-    return [];
-  }
-  const lowdefy = YAML.parse(lowdefyYaml);
-  return get(lowdefy, 'plugins', { default: [] });
-}
-
 async function createCustomPluginTypesMap({ directories, logger }) {
   const customTypesMap = {
     actions: {},
     agents: {},
     auth: {
       adapters: {},
-      callbacks: {},
-      events: {},
       providers: {},
+      strategies: {},
     },
     blockMetas: {},
+    connectionMetas: {},
     blocks: {},
     connections: {},
     icons: {},
+    iconSets: {},
     operators: {
       client: {},
       server: {},
@@ -58,18 +45,25 @@ async function createCustomPluginTypesMap({ directories, logger }) {
     websockets: {},
   };
 
-  const pluginDefinitions = await getPluginDefinitions({ directories });
+  const pluginDefinitions = await readPluginDefinitions({ directories });
+
+  // Each import starts a worker, so the plugins are imported in parallel and
+  // added to the map in the order lowdefy.yaml lists them.
+  const pluginTypes = await Promise.all(
+    pluginDefinitions.map(async (plugin) => {
+      try {
+        return await importFresh(require.resolve(`${plugin.name}/types`));
+      } catch (e) {
+        logger.error(`Failed to import plugin "${plugin.name}".`);
+        logger.debug(e);
+        logger.info('If the plugin was added while the server was running, restart the server.');
+        throw new Error(`Failed to import plugin "${plugin.name}".`);
+      }
+    })
+  );
 
-  for (const plugin of pluginDefinitions) {
-    let types;
-    try {
-      types = require(`${plugin.name}/types`);
-    } catch (e) {
-      logger.error(`Failed to import plugin "${plugin.name}".`);
-      logger.debug(e);
-      logger.info('If the plugin was added while the server was running, restart the server.');
-      throw new Error(`Failed to import plugin "${plugin.name}".`);
-    }
+  pluginDefinitions.forEach((plugin, index) => {
+    const types = pluginTypes[index];
     createPluginTypesMap({
       packageTypes: types.default ?? types,
       typesMap: customTypesMap,
@@ -77,7 +71,7 @@ async function createCustomPluginTypesMap({ directories, logger }) {
       version: plugin.version,
       typePrefix: plugin.typePrefix,
     });
-  }
+  });
 
   return customTypesMap;
 }

package/manager/utils/createCustomPluginTypesMap.test.mjs

@@ -0,0 +1,94 @@
+/*
+  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 { jest } from '@jest/globals';
+
+const mockImportFresh = jest.fn();
+jest.unstable_mockModule('./importFresh.mjs', () => ({ default: mockImportFresh }));
+const mockCreatePluginTypesMap = jest.fn();
+jest.unstable_mockModule('@lowdefy/build', () => ({
+  createPluginTypesMap: mockCreatePluginTypesMap,
+}));
+// The module under test imports @lowdefy/build, which links against every
+// export it uses, so the real module passes through and only readFile is
+// replaced.
+const realNodeUtils = await import('@lowdefy/node-utils');
+jest.unstable_mockModule('@lowdefy/node-utils', () => ({
+  ...realNodeUtils,
+  readFile: jest.fn(async () => 'plugins:\n  - name: plugin-a\n  - name: plugin-b\n'),
+}));
+jest.unstable_mockModule('node:module', () => ({
+  createRequire: () => ({ resolve: (name) => `/plugins/${name}.js` }),
+}));
+
+const { default: createCustomPluginTypesMap } = await import('./createCustomPluginTypesMap.mjs');
+const { default: createCustomPluginMessagesMap } = await import(
+  './createCustomPluginMessagesMap.mjs'
+);
+
+const logger = { debug: jest.fn(), error: jest.fn(), info: jest.fn() };
+const directories = { config: '/app' };
+
+// Holds every import open until release(), so a test can see which imports
+// started before any of them finished.
+function deferImports(values) {
+  const releases = [];
+  mockImportFresh.mockImplementation(
+    (filePath) =>
+      new Promise((resolve) => {
+        releases.push(() => resolve(values[filePath]));
+      })
+  );
+  return {
+    started: () => mockImportFresh.mock.calls.map(([filePath]) => filePath),
+    release: () => releases.forEach((release) => release()),
+  };
+}
+
+test('createCustomPluginTypesMap imports every plugin before any import finishes', async () => {
+  const imports = deferImports({
+    '/plugins/plugin-a/types.js': { blocks: ['A'] },
+    '/plugins/plugin-b/types.js': { blocks: ['B'] },
+  });
+
+  const result = createCustomPluginTypesMap({ directories, logger });
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  expect(imports.started()).toEqual(['/plugins/plugin-a/types.js', '/plugins/plugin-b/types.js']);
+  imports.release();
+  await result;
+
+  expect(mockCreatePluginTypesMap.mock.calls.map(([args]) => args.packageName)).toEqual([
+    'plugin-a',
+    'plugin-b',
+  ]);
+});
+
+test('createCustomPluginMessagesMap imports every plugin before any import finishes', async () => {
+  const imports = deferImports({
+    '/plugins/plugin-a/messages.js': { hello: 'A' },
+    '/plugins/plugin-b/messages.js': { hello: 'B' },
+  });
+
+  const result = createCustomPluginMessagesMap({ directories, logger });
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  expect(imports.started()).toEqual([
+    '/plugins/plugin-a/messages.js',
+    '/plugins/plugin-b/messages.js',
+  ]);
+  imports.release();
+
+  expect(await result).toEqual({ 'plugin-a': { hello: 'A' }, 'plugin-b': { hello: 'B' } });
+});

package/manager/utils/createDotPathIgnore.mjs

@@ -0,0 +1,44 @@
+/*
+  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 path from 'path';
+
+function findWatchRoot({ filePath, watchPaths }) {
+  let watchRoot;
+  for (const watchPath of watchPaths) {
+    const contains = filePath === watchPath || filePath.startsWith(`${watchPath}${path.sep}`);
+    if (contains && (watchRoot === undefined || watchPath.length > watchRoot.length)) {
+      watchRoot = watchPath;
+    }
+  }
+  return watchRoot;
+}
+
+// Ignores a path with a segment that starts with a dot (.git, .lowdefy, .env
+// files). Segments are counted from the watched path the file is under, not
+// from the file system root, so an app that lives inside a dot-folder (a git
+// worktree under .claude/worktrees/) is still watched. A path under no watched
+// path is a file added to the watch on its own, so only its name is tested.
+function createDotPathIgnore({ watchPaths }) {
+  return function isDotPath(filePath) {
+    const watchRoot = findWatchRoot({ filePath, watchPaths });
+    const relativePath =
+      watchRoot === undefined ? path.basename(filePath) : path.relative(watchRoot, filePath);
+    return relativePath.split(path.sep).some((segment) => segment.startsWith('.'));
+  };
+}
+
+export default createDotPathIgnore;

package/manager/utils/createDotPathIgnore.test.mjs

@@ -0,0 +1,65 @@
+/*
+  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 path from 'path';
+
+import createDotPathIgnore from './createDotPathIgnore.mjs';
+
+// setupWatcher hands the ignore function paths with the platform separator.
+const appRoot = path.join('/home/dev/repo/.claude/worktrees/feature/app');
+
+test('a file in an app that lives under a dot-folder is not ignored', () => {
+  const isDotPath = createDotPathIgnore({ watchPaths: [appRoot] });
+  expect(isDotPath(appRoot)).toBe(false);
+  expect(isDotPath(path.join(appRoot, 'pages/home.yaml'))).toBe(false);
+});
+
+test('a dot-folder or dotfile inside the watched path is ignored', () => {
+  const isDotPath = createDotPathIgnore({ watchPaths: [appRoot] });
+  expect(isDotPath(path.join(appRoot, '.lowdefy/server/build/app.json'))).toBe(true);
+  expect(isDotPath(path.join(appRoot, '.git'))).toBe(true);
+  expect(isDotPath(path.join(appRoot, 'pages/.home.yaml.swp'))).toBe(true);
+});
+
+test('segments are counted from the deepest watched path that holds the file', () => {
+  const moduleRoot = path.join(appRoot, '.modules/layout');
+  const isDotPath = createDotPathIgnore({ watchPaths: [appRoot, moduleRoot] });
+  expect(isDotPath(path.join(moduleRoot, 'components/page.yaml'))).toBe(false);
+  expect(isDotPath(path.join(appRoot, '.modules/other/page.yaml'))).toBe(true);
+});
+
+test('a file under no watched path is tested by its name only', () => {
+  const isDotPath = createDotPathIgnore({ watchPaths: [appRoot] });
+  expect(
+    isDotPath(path.join('/home/dev/repo/.claude/worktrees/feature/modules/shared/title.yaml'))
+  ).toBe(false);
+  expect(isDotPath(path.join('/home/dev/repo/modules/shared/.title.yaml'))).toBe(true);
+});
+
+test('a watched path that only shares a prefix with the file does not hold it', () => {
+  const isDotPath = createDotPathIgnore({ watchPaths: [path.join('/home/dev/app')] });
+  expect(isDotPath(path.join('/home/dev/app-other/.cache/file.yaml'))).toBe(false);
+});
+
+test('dev recordings under .lowdefy/traces are ignored by the config watcher', () => {
+  const configDirectory = path.join('/home/dev/app');
+  const isDotPath = createDotPathIgnore({ watchPaths: [configDirectory] });
+  expect(
+    isDotPath(
+      path.join(configDirectory, '.lowdefy/traces/dev/2026-10-03/20261003T140311Z-k3x9qa.jsonl')
+    )
+  ).toBe(true);
+});

package/manager/utils/createIdleGc.mjs

@@ -0,0 +1,51 @@
+/*
+  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 v8 from 'node:v8';
+import vm from 'node:vm';
+
+// The manager is started without --expose-gc (by every launch path), so it
+// turns the flag on itself and takes gc from a fresh context.
+function exposeGc() {
+  v8.setFlagsFromString('--expose-gc');
+  return vm.runInNewContext('gc');
+}
+
+// The manager's heap grows two to three times during a config build and V8
+// does not shrink it while the process is idle. One full GC delayMs after a
+// build ends hands that slack back (about 50-150 ms of GC, never during a
+// build: a build starting within delayMs cancels it).
+function createIdleGc({ delayMs = 5000, gc = exposeGc() } = {}) {
+  let timer = null;
+
+  function onBuildingChange(building) {
+    clearTimeout(timer);
+    timer = null;
+    if (building) {
+      return;
+    }
+    timer = setTimeout(() => {
+      timer = null;
+      gc();
+    }, delayMs);
+    // Never the reason the manager stays up.
+    timer.unref();
+  }
+
+  return { onBuildingChange };
+}
+
+export default createIdleGc;