mixdog 1.4.2 → 1.4.3

package/src/runtime/connectors/connector-accounts-mcp.mjs

@@ -11,17 +11,21 @@
 // conversation, else the connector's last-used account (connectorAccountInUse),
 // else the topmost connected account. A named or remembered account that is
 // switched off, removed or needs a sign-in fails the call with the usable
-// accounts listed; no other account ever stands in for it. A conversation's
+// accounts listed; no other account ever stands in for it, a new account
+// given a removed one's name included (a remembered account is bound to its
+// identity, not its name). A conversation's
 // call (`_meta[CONVERSATION_META]`) makes its account the last used, for the
 // conversation and the connector. Every result of a call made on an account,
 // errors included, says which account answered. A name binds a call to one
 // account; an address or label two accounts share binds none.
 // An account that fails stays listed with why (connectorAccountHealth); the
 // server only fails to start when no account can be used.
+import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 import { readJsonStateSync, updateJsonAtomicSync } from '../shared/atomic-file.mjs';
+import { readSection, updateSection } from '../shared/config.mjs';
 import { accountsOfInstructions, connectorAccountsInstructions } from '../shared/connector-accounts.mjs';
-import { connectorById } from '../shared/connector-catalog.mjs';
+import { connectorAccountsOf, connectorById, connectorOfServer } from '../shared/connector-catalog.mjs';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
 
 const PROTOCOL_VERSION = '2025-06-18';
@@ -49,8 +53,8 @@ export function forgetConnectorAccountHealth(name) {
 }
 
 // ── The last-used account ───────────────────────────────────────────────────
-// Per connector, in the data dir (every runtime reads the same one); per
-// conversation, in memory (the newest conversations kept).
+// Per connector and per conversation, in the data dir (every runtime and every
+// restart reads the same ones).
 const ACCOUNTS_IN_USE_FILE = 'connector-accounts-in-use.json';
 const inUseFile = () => join(resolvePluginData(), ACCOUNTS_IN_USE_FILE);
 const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
@@ -59,37 +63,149 @@ const validInUse = (value) => {
   return value;
 };
 
+// A remembered account is `{ name, id }`: the name it was called by and its
+// identity (connector-catalog.mjs connectorAccountId: the random id stored
+// with it). A name can be given to a new account once the old one is
+// removed; the identity cannot, so it binds the choice to the account.
+const readInUse = () => readJsonStateSync(inUseFile(), { validate: validInUse, fallback: {} });
+
+// Set in the accounts-in-use file once its name-only records (from before
+// identities) were bound to the accounts then under those names.
+const IDS_MIGRATED = '#ids';
+
+const hasId = (account) => typeof account?.id === 'string' && account.id !== '';
+const missingIds = (servers) =>
+  Object.values(isRecord(servers) ? servers : {}).some((cfg) => connectorAccountsOf(cfg).some((one) => !hasId(one)));
+
+/** Test seam: runs once the config lock that gave the ids is released, before
+ *  the binding (where another process's write may land). */
+export const accountIdsDeps = { afterIdsGiven: () => {} };
+
+/** `servers` with a random id given to every connector account stored
+ *  without one; null when every account has one. */
+function withAccountIds(servers) {
+  if (!missingIds(servers)) return null;
+  return Object.fromEntries(
+    Object.entries(servers).map(([name, cfg]) => {
+      if (!connectorAccountsOf(cfg).some((one) => !hasId(one))) return [name, cfg];
+      const accounts = cfg.accounts.map((account) =>
+        isRecord(account) && !hasId(account) ? { ...account, id: randomUUID() } : account
+      );
+      return [name, { ...cfg, accounts }];
+    })
+  );
+}
+
+/**
+ * Every stored connector account gets an identity, once, at every start and
+ * after a config change (an account written by hand has none). All under the
+ * accounts-in-use file's lock, so concurrent runs (processes, runtimes) and
+ * choices serialize: the config is changed only where an id is missing (an id
+ * once given is never replaced), and the first run also binds each name-only
+ * record (from before identities) to the account then under that name, which
+ * is where such a record routed until now, and marks that done. A name-only
+ * record found afterwards stays unbound (it fails closed). Records already
+ * holding an identity are never touched. True when it changed the config.
+ *
+ * The binding uses the accounts exactly as the ids were given or confirmed:
+ * the config is re-read nowhere after that, so an account replaced under the
+ * same name meanwhile (by another process) is never the one bound; it fails
+ * the identity check instead.
+ */
+export function ensureConnectorAccountIds() {
+  let changed = false;
+  updateJsonAtomicSync(inUseFile(), (current) => {
+    const stored = isRecord(current) ? current : {};
+    // The stored servers whose ids the binding below uses.
+    let snapshot = readSection('agent')?.mcpServers;
+    if (missingIds(snapshot)) {
+      updateSection('agent', (agent) => {
+        const servers = withAccountIds(agent.mcpServers);
+        snapshot = servers ?? agent.mcpServers;
+        if (!servers) return agent;
+        changed = true;
+        return { ...agent, mcpServers: servers };
+      });
+      accountIdsDeps.afterIdsGiven();
+    }
+    if (stored[IDS_MIGRATED]) return undefined;
+    const servers = Object.values(isRecord(snapshot) ? snapshot : {});
+    const next = { ...stored, [IDS_MIGRATED]: true };
+    for (const [connector, name] of Object.entries(stored)) {
+      if (typeof name !== 'string' || !name) continue;
+      const cfg = servers.find((one) => connectorOfServer(one) === connector && connectorAccountsOf(one).length);
+      const account = cfg && connectorAccountsOf(cfg).find((one) => one.name === name);
+      if (hasId(account)) next[connector] = { name, id: account.id };
+    }
+    return next;
+  });
+  return changed;
+}
+
+/** The account catalog connector `connector` used last, null when none was
+ *  recorded. A name-only record (from before identities, unbound) has an
+ *  empty `id`. */
+export function connectorAccountInUseRecord(connector) {
+  const value = readInUse()[connector];
+  if (typeof value === 'string') return value ? { name: value, id: '' } : null;
+  if (!isRecord(value) || typeof value.name !== 'string' || !value.name) return null;
+  return { name: value.name, id: typeof value.id === 'string' ? value.id : '' };
+}
+
 /** The name of the account catalog connector `connector` used last, '' when
  *  none was recorded. */
 export function connectorAccountInUse(connector) {
-  const stored = readJsonStateSync(inUseFile(), { validate: validInUse, fallback: {} });
-  return typeof stored[connector] === 'string' ? stored[connector] : '';
+  return connectorAccountInUseRecord(connector)?.name || '';
 }
 
-function rememberAccountInUse(connector, name) {
-  if (connectorAccountInUse(connector) === name) return;
-  updateJsonAtomicSync(inUseFile(), (current) => ({ ...(isRecord(current) ? current : {}), [connector]: name }));
+function rememberAccountInUse(connector, account) {
+  const current = connectorAccountInUseRecord(connector);
+  if (current?.name === account.name && current.id === account.id) return;
+  updateJsonAtomicSync(inUseFile(), (stored) => ({
+    ...(isRecord(stored) ? stored : {}),
+    [connector]: { name: account.name, id: account.id },
+  }));
 }
 
-const CONVERSATIONS_KEPT = 500;
-// conversation → (connector → account name), oldest first.
-const conversations = new Map();
+// Per conversation, in the data dir too, so a conversation resumed after a
+// restart keeps its own account: conversation (its session id) → { accounts:
+// (connector → { name, id }) }. A binding lives as long as its session: it is
+// dropped only when the session is deleted (forgetConversationConnectorAccounts,
+// a session purge hook), never to make room, so no live conversation falls
+// back to another conversation's choice.
+const CONVERSATION_ACCOUNTS_FILE = 'connector-accounts-by-conversation.json';
+const conversationsFile = () => join(resolvePluginData(), CONVERSATION_ACCOUNTS_FILE);
 
-/** Account `name` of `connector` was removed: wherever it is the last used it
- *  stays a removed account, so a call that would default to it keeps failing
- *  closed, even once a new account is given the same name. */
-export function retireConnectorAccount(connector, name) {
-  const removed = `${name} (removed)`;
-  for (const own of conversations.values()) if (own.get(connector) === name) own.set(connector, removed);
-  if (connectorAccountInUse(connector) === name) rememberAccountInUse(connector, removed);
+/** Drop the connector accounts conversation `conversation` used (its session
+ *  was deleted). */
+export function forgetConversationConnectorAccounts(conversation) {
+  const id = text(conversation);
+  if (!id || !Object.hasOwn(readJsonStateSync(conversationsFile(), { validate: validInUse, fallback: {} }), id)) return;
+  updateJsonAtomicSync(conversationsFile(), (stored) => {
+    const { [id]: _gone, ...rest } = isRecord(stored) ? stored : {};
+    return rest;
+  });
 }
 
-function rememberConversationAccount(conversation, connector, name) {
-  const own = conversations.get(conversation) || new Map();
-  conversations.delete(conversation);
-  own.set(connector, name);
-  conversations.set(conversation, own);
-  if (conversations.size > CONVERSATIONS_KEPT) conversations.delete(conversations.keys().next().value);
+/** The account conversation `conversation` used last on `connector`, or null. */
+function conversationAccount(conversation, connector) {
+  const own = readJsonStateSync(conversationsFile(), { validate: validInUse, fallback: {} })[conversation];
+  const value = isRecord(own?.accounts) ? own.accounts[connector] : null;
+  if (!isRecord(value) || typeof value.name !== 'string' || !value.name) return null;
+  return { name: value.name, id: typeof value.id === 'string' ? value.id : '' };
+}
+
+function rememberConversationAccount(conversation, connector, account) {
+  const current = conversationAccount(conversation, connector);
+  if (current?.name === account.name && current.id === account.id) return;
+  updateJsonAtomicSync(conversationsFile(), (stored) => {
+    const all = isRecord(stored) ? stored : {};
+    const accounts = isRecord(all[conversation]?.accounts) ? all[conversation].accounts : {};
+    return {
+      ...all,
+      [conversation]: { accounts: { ...accounts, [connector]: { name: account.name, id: account.id } } },
+    };
+  });
 }
 
 const ACCOUNT_PROPERTY = Object.freeze({
@@ -102,7 +218,9 @@ const ACCOUNT_PROPERTY = Object.freeze({
 const canonical = (value) => {
   if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
   if (isRecord(value)) {
-    const keys = Object.keys(value).filter((key) => value[key] !== undefined).sort();
+    const keys = Object.keys(value)
+      .filter((key) => value[key] !== undefined)
+      .sort();
     return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
   }
   return JSON.stringify(value) ?? 'null';
@@ -146,7 +264,8 @@ const withAccountNote = (result, service, label) => ({
 
 /**
  * A `fetch` answering the accounts server of `connector` in-process. Each of
- * `accounts` is `{ name, email, connect(signal), callTool(params, { signal, onprogress }) }`:
+ * `accounts` is `{ name, id, email, connect(signal), callTool(params, { signal, onprogress }) }`
+ * (`id`: its identity, connector-catalog.mjs connectorAccountId):
  * `connect` resolves `{ instructions, tools }` of that account's own MCP
  * connection, `callTool` sends it one tools/call (reporting its progress to
  * `onprogress`, when given) and resolves the result; both
@@ -189,9 +308,25 @@ export function withConnectorAccountsMcp({ connector, accounts }) {
       [account] = matches;
     } else {
       const remembered =
-        (conversation && conversations.get(conversation)?.get(connector)) || connectorAccountInUse(connector);
-      account = remembered ? accounts.find((one) => one.name === remembered) : accounts[0];
-      if (!account) throw refuse(`The ${service} account used last (${remembered}) is not connected now.`);
+        (conversation && conversationAccount(conversation, connector)) || connectorAccountInUseRecord(connector);
+      if (remembered) {
+        account = accounts.find((one) => one.name === remembered.name);
+        // The name must still be the account it named: one removed and its
+        // name given to a new account, or a record without an identity (one
+        // ensureConnectorAccountIds did not bind, or an account picked before
+        // it had an id), fails closed until an account is picked again.
+        if (account && !remembered.id) {
+          throw refuse(
+            `The ${service} account used last (${remembered.name}) cannot be confirmed as the same account.`
+          );
+        }
+        if (account && account.id !== remembered.id) {
+          throw refuse(`The ${service} account used last (${remembered.name} (removed)) is not connected now.`);
+        }
+        if (!account) throw refuse(`The ${service} account used last (${remembered.name}) is not connected now.`);
+      } else {
+        account = accounts[0];
+      }
     }
     if (!usable(account)) throw refuse(`${labelOf(account)} needs a sign-in in Connectors.`);
     const has = toolsOf.get(account.name);
@@ -275,8 +410,8 @@ export function withConnectorAccountsMcp({ connector, accounts }) {
       try {
         account = choose({ tool: name, wanted, conversation });
         if (conversation) {
-          rememberConversationAccount(conversation, connector, account.name);
-          rememberAccountInUse(connector, account.name);
+          rememberConversationAccount(conversation, connector, account);
+          rememberAccountInUse(connector, account);
         }
       } catch (error) {
         return reply(errorResult(error?.message || String(error)));
@@ -289,7 +424,8 @@ export function withConnectorAccountsMcp({ connector, accounts }) {
       const progressToken = params?._meta?.progressToken;
       const onprogress =
         notify && progressToken !== undefined
-          ? (progress) => notify({ jsonrpc: '2.0', method: 'notifications/progress', params: { ...progress, progressToken } })
+          ? (progress) =>
+              notify({ jsonrpc: '2.0', method: 'notifications/progress', params: { ...progress, progressToken } })
           : undefined;
       try {
         // An unlisted tool (one only the approval gate calls) is the account's to answer.

package/src/runtime/connectors/gmail-app-password.mjs

@@ -7,7 +7,7 @@
 // for each call. The password is checked with Gmail before it is saved, and
 // never appears in a config, log, error or tool result.
 import { createHash } from 'node:crypto';
-import keychain from '../../lib/keychain-cjs.cjs';
+import { keychainSecretStore as keychain } from '../shared/config.mjs';
 import { GMAIL_APP_PASSWORD, gmailAddress } from '../shared/connector-catalog.mjs';
 import { connectorAccountsInstructions } from '../shared/connector-accounts.mjs';
 
@@ -724,7 +724,7 @@ const TOOLS = [
 
 /** The tool definitions (name, description, schema, annotations) the server
  *  lists: never the ones only the approval gate calls. */
-export function gmailAppPasswordTools() {
+function gmailAppPasswordTools() {
   return TOOLS.filter((tool) => !tool.hidden).map(({ run, hidden: _hidden, ...tool }) => tool);
 }
 

package/src/runtime/connectors/google-mcp.mjs

@@ -331,7 +331,7 @@ const SERVICES = {
 
 /** The tool definitions (name, description, schema, annotations) of built-in
  *  Google service `service` (`gmail`, `calendar`, `drive`). */
-export function googleMcpTools(service) {
+function googleMcpTools(service) {
   return (SERVICES[service]?.tools || []).map(({ run, ...tool }) => tool);
 }
 

package/src/runtime/effort-judge/judge-client.mjs

@@ -83,7 +83,7 @@ function waitReady(ms) {
   });
 }
 
-export function effortJudgeModelDir() {
+function effortJudgeModelDir() {
   return process.env.MIXDOG_EFFORT_JUDGE_DIR || join(resolvePluginData(), 'models', 'effort-judge');
 }
 
@@ -280,7 +280,7 @@ async function runInstall() {
  * background. Runs on the first judged turn of the process, never at runtime
  * creation, so booting touches no network.
  */
-export function refreshEffortJudge() {
+function refreshEffortJudge() {
   if (!onnxRuntimeSupported()) return;
   installEffortJudge().catch((error) => {
     // An older complete install still works.

package/src/runtime/effort-judge/judge-input.mjs

@@ -17,7 +17,7 @@ const HEX = /(?<![0-9A-Za-z])[0-9a-fA-F]{12,}(?![0-9A-Za-z])/g;
 const SPACES = /[ \t]+/g;
 const BLANK_LINES = /\n[ \t]*\n[\n \t]*/g;
 
-export function cleanJudgeText(text) {
+function cleanJudgeText(text) {
   return String(text || '')
     .replace(/\r\n?/g, '\n')
     .replace(ANSI, '')
@@ -49,10 +49,10 @@ export function judgeInputClean(request, prev) {
 // continues), the previous reply's first line (its topic), then as much of the
 // reply's END (what a short approval answers) as remains. Training builds the
 // same id sequence (clean_text.pack_ids) with the identical tokenizer.
-export const PACK_BUDGET = Object.freeze({ request: 64, prevRequest: 24, replyHead: 16 });
+const PACK_BUDGET = Object.freeze({ request: 64, prevRequest: 24, replyHead: 16 });
 
 /** Split the cleaned previous reply into its first line and the remaining text. */
-export function splitReply(reply) {
+function splitReply(reply) {
   const at = reply.indexOf('\n');
   return at < 0 ? [reply, ''] : [reply.slice(0, at), reply.slice(at + 1)];
 }
@@ -63,7 +63,7 @@ export function splitReply(reply) {
 // A result keeps its start and end (where errors and summaries sit); the
 // stored window (2000 + 1000 code points) bounds the cleaning work on huge
 // outputs. Training builds the same text (clean_text.step_judge_text).
-export const STEP_CALLS = 3;
+const STEP_CALLS = 3;
 
 export function stepResultWindow(text) {
   const cps = Array.from(String(text ?? ''));

package/src/runtime/explore/explorer.mjs

@@ -32,11 +32,6 @@ export const EXPLORER_SYSTEM_PROMPT = [
 const EXPLORER_TOOLS = readOnlyFilesystemTools();
 export const EXPLORER_TOOL_NAMES = Object.freeze(EXPLORER_TOOLS.map((tool) => tool.name));
 
-/** Exact provider prefix inputs, for cache-stability checks. */
-export function explorerPrefix() {
-  return { system: EXPLORER_SYSTEM_PROMPT, tools: EXPLORER_TOOLS };
-}
-
 /**
  * Answer `query` on `route` with `provider`. Resolves the answer text (on a
  * salvage-flagged abort, the text written so far); rejects on failure.

package/src/runtime/explore/tool.mjs

@@ -8,8 +8,8 @@ import { runExplorer } from './explorer.mjs';
 
 // Hidden ids are reserved from user agents, so this one keeps the `-agent`
 // suffix: a plain `explorer` would hide a user's own Explorer agent.
-export const EXPLORER_AGENT = 'explore-agent';
-export const EXPLORE_TIMEOUT_MS = 120_000;
+const EXPLORER_AGENT = 'explore-agent';
+const EXPLORE_TIMEOUT_MS = 120_000;
 export const EXPLORE_OUTPUT_CAP = 24_000;
 const TRUNCATED = '\n[explore: answer truncated]';
 
@@ -17,7 +17,7 @@ function result(text, isError = false) {
   return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
 }
 
-export function normalizeExploreQueries(raw) {
+function normalizeExploreQueries(raw) {
   const list = Array.isArray(raw) ? raw : [raw];
   return list.map((q) => (typeof q === 'string' ? q.trim() : '')).filter(Boolean);
 }

package/src/runtime/local-provider/hardware.mjs

@@ -19,7 +19,7 @@ export function localProviderPlatformKey(platform = process.platform, arch = pro
  *  RAM — exactly what llama.cpp's Metal backend reports on a 16 GB M4; larger
  *  Macs may allow more, which this leaves unused. Metal reports that whole
  *  working set as free, so free equals total here as it does in llama.cpp. */
-export function appleSiliconGpu({ name, totalBytes, wiredLimitMb }) {
+function appleSiliconGpu({ name, totalBytes, wiredLimitMb }) {
   const memoryBytes = wiredLimitMb > 0 ? wiredLimitMb * 1024 ** 2 : Math.floor((totalBytes * 2) / 3);
   return { index: 0, uuid: 'MTL0', vendor: 'Apple', name, memoryBytes, freeMemoryBytes: memoryBytes };
 }

package/src/runtime/media/adapters/codex-image.mjs

@@ -32,9 +32,9 @@ import {
 
 const REQUEST_TIMEOUT_MS = 400_000;
 const LABEL = 'ChatGPT image';
-export const CODEX_IMAGE_MODEL = 'gpt-image-2';
-export const CODEX_IMAGES_GENERATIONS_URL = new URL('images/generations', CODEX_RESPONSES_URL).href;
-export const CODEX_IMAGES_EDITS_URL = new URL('images/edits', CODEX_RESPONSES_URL).href;
+const CODEX_IMAGE_MODEL = 'gpt-image-2';
+const CODEX_IMAGES_GENERATIONS_URL = new URL('images/generations', CODEX_RESPONSES_URL).href;
+const CODEX_IMAGES_EDITS_URL = new URL('images/edits', CODEX_RESPONSES_URL).href;
 const BACKGROUNDS = new Set(['transparent', 'opaque', 'auto']);
 
 const dataUrl = (ref) => `data:${ref.mime || 'image/png'};base64,${ref.base64}`;

package/src/runtime/media/adapters/gemini-video.mjs

@@ -83,7 +83,7 @@ async function generateViaVeo({ model, prompt, options, references = [], signal,
   if ([4, 6, 8].includes(duration)) parameters.durationSeconds = duration;
 
   // The budget starts at submission, not after it: a hung predictLongRunning
-  // POST used to run without any ceiling of its own.
+  // POST would otherwise run without any ceiling of its own.
   const deadline = Date.now() + TOTAL_TIMEOUT_MS;
   const started = await fetch(`${BASE_URL}/models/${encodeURIComponent(model)}:predictLongRunning`, {
     method: 'POST',

package/src/runtime/media/media-usage.mjs

@@ -91,7 +91,7 @@ export function imageApiUsage(body) {
 }
 
 /** True when the provider reported something billable for the request. */
-export function hasReportedUsage(usage) {
+function hasReportedUsage(usage) {
   if (!usage) return false;
   // Seconds are only attached once a video generation completed (billed per second).
   return (

package/src/runtime/media/store.mjs

@@ -231,7 +231,7 @@ export function saveMediaAsset({ kind, lane, model, prompt, options = {}, mime,
   // whose bytes are all NUL.
   writeFileAtomicSync(path, bytes);
   entry.file = file;
-  // The gallery is NOT capped (user). An entry-count trim used to unlink the
+  // The gallery is NOT capped (user). An entry-count trim would unlink the
   // oldest files here, which is data loss nobody asked for: a generated asset
   // leaves this store only through an explicit delete.
   mutateIndex((assets) => [entry, ...assets]);

package/src/runtime/memory/index.mjs

@@ -59,7 +59,8 @@ import {
   resolveCoalesceMaxRetries,
   scheduleCoalescedCycleRetry,
 } from './lib/memory-cycle-requests.mjs';
-import { drainEmbeddingReindex } from './lib/embedding-reindex.mjs';
+import { drainEmbeddingReindex, runRootEmbedSweep } from './lib/embedding-reindex.mjs';
+import { sweepRootEmbedText } from './lib/memory-embed.mjs';
 import { refreshCoreMemoryFile } from './lib/core-memory-file.mjs';
 import { resolveProjectId, resolveProjectScope } from './lib/project-id-resolver.mjs';
 import {
@@ -432,6 +433,15 @@ function _startEmbeddingReindex() {
             `ok=${summary.succeeded} failed=${summary.failed}\n`
         );
       }
+      return runRootEmbedSweep({
+        sweepStep: ({ signal }) => sweepRootEmbedText(db, { signal }),
+        signal: controller.signal,
+      });
+    })
+    .then((sweep) => {
+      if (sweep.replaced > 0) {
+        __mixdogMemoryLog(`[memory-service] root text sweep steps=${sweep.steps} replaced=${sweep.replaced}\n`);
+      }
     })
     .catch((error) => {
       if (!controller.signal.aborted) {

package/src/runtime/memory/lib/embedding-reindex.mjs

@@ -46,3 +46,30 @@ export async function drainEmbeddingReindex({
 
   return { passes, attempted, succeeded, failed };
 }
+
+// The root-text sweep replaces vectors that still work, so it has no urgency:
+// small steps with long rests keep a ~62k-root backfill in the background of a
+// working session instead of competing with it.
+const ROOT_SWEEP_PAUSE_MS = 4_000;
+
+export async function runRootEmbedSweep({
+  sweepStep,
+  signal,
+  pauseMs = ROOT_SWEEP_PAUSE_MS,
+  wait = waitForNextPass,
+} = {}) {
+  if (typeof sweepStep !== 'function') {
+    throw new TypeError('runRootEmbedSweep: sweepStep required');
+  }
+  let steps = 0;
+  let replaced = 0;
+  while (true) {
+    throwIfAborted(signal);
+    const result = await sweepStep({ signal });
+    steps += 1;
+    replaced += Number(result?.replaced ?? 0);
+    if (result?.done) break;
+    await wait(pauseMs, signal);
+  }
+  return { steps, replaced };
+}