mixdog 1.4.0 → 1.4.2

package/src/runtime/shared/atomic-file.mjs

@@ -128,12 +128,113 @@ export function renameWithRetrySync(src, dst, opts = {}) {
   }
 }
 
+// Windows refuses to rename over a file while any handle on it is open, so
+// this process's own reads of a busy state file (a delivery loop polling it)
+// could fail every attempt of its writer's rename until the retries ran out.
+// Here a rename attempt waits for the reads of its target in flight and holds
+// new ones off only while it runs; other processes are what the retries cover.
+// A read still open after RENAME_READ_WAIT_MS is left behind with its path's
+// entry (a stuck read must not hold the writer, its lock, or later readers),
+// and the attempt goes ahead under those same retries. Likewise a rename not
+// returned by then: readers held off read anyway, as without it. A reader's
+// bound counts from the rename call, not from the attempt's own (bounded)
+// wait for reads, so a rename that just started is never read across.
+export const RENAME_READ_WAIT_MS = 1_000;
+const targetUse = new Map();
+const targetKey = (path) => {
+  const full = resolve(path);
+  return process.platform === 'win32' ? full.toLowerCase() : full;
+};
+function useOf(key) {
+  let use = targetUse.get(key);
+  if (!use) targetUse.set(key, (use = { reads: 0, renaming: null, draining: null, drained: [] }));
+  return use;
+}
+function forgetIfIdle(key, use) {
+  if (use.reads === 0 && !use.renaming && targetUse.get(key) === use) targetUse.delete(key);
+}
+
+// Waits for the rename `use` runs; one that has not returned within the bound
+// is left behind with the entry, and the caller goes on as without it.
+async function outwaitRename(key, use) {
+  await use.draining;
+  if (use.renaming && !(await settlesWithin(use.renaming, RENAME_READ_WAIT_MS)) && targetUse.get(key) === use) {
+    targetUse.delete(key);
+  }
+  return useOf(key);
+}
+
+function settlesWithin(promise, ms) {
+  let timer;
+  const bound = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  return Promise.race([promise.then(() => true), bound]).finally(() => clearTimeout(timer));
+}
+
+async function readTarget(path, read) {
+  const key = targetKey(path);
+  let use = useOf(key);
+  while (use.renaming) use = await outwaitRename(key, use);
+  use.reads += 1;
+  try {
+    return await read();
+  } finally {
+    use.reads -= 1;
+    if (use.reads === 0) for (const done of use.drained.splice(0)) done();
+    forgetIfIdle(key, use);
+  }
+}
+
+async function renameOver(src, dst) {
+  const key = targetKey(dst);
+  let use = useOf(key);
+  while (use.renaming) use = await outwaitRename(key, use);
+  let finish;
+  use.renaming = new Promise((resolve) => {
+    finish = resolve;
+  });
+  use.draining = use.reads > 0 ? readsDrained(use, RENAME_READ_WAIT_MS) : null;
+  try {
+    if (use.draining && !(await use.draining) && targetUse.get(key) === use) targetUse.delete(key);
+    await renameAsync(src, dst);
+  } finally {
+    use.renaming = null;
+    use.draining = null;
+    finish();
+    forgetIfIdle(key, use);
+  }
+}
+
+// True once `use` has no read in flight, false after `ms` (its waiter removed).
+function readsDrained(use, ms) {
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      resolve(true);
+    };
+    const timer = setTimeout(() => {
+      const at = use.drained.indexOf(done);
+      if (at >= 0) use.drained.splice(at, 1);
+      resolve(false);
+    }, ms);
+    use.drained.push(done);
+  });
+}
+
+/** Test seam: the per-path coordination left (entries, drain waiters). */
+export function _renameCoordinationForTest() {
+  let waiters = 0;
+  for (const use of targetUse.values()) waiters += use.drained.length;
+  return { entries: targetUse.size, waiters };
+}
+
 async function renameWithRetry(src, dst, opts = {}) {
   const backoffs = renameBackoffs(opts);
   let lastErr = null;
   for (let attempt = 0; attempt <= backoffs.length; attempt++) {
     try {
-      await renameAsync(src, dst);
+      await renameOver(src, dst);
       return true;
     } catch (err) {
       lastErr = err;
@@ -433,7 +534,7 @@ function readContentOrNullSync(filePath) {
 
 async function readContentOrNullAsync(filePath) {
   try {
-    return await readFileAsync(filePath);
+    return await readTarget(filePath, () => readFileAsync(filePath));
   } catch (err) {
     if (err?.code === 'ENOENT') return null;
     throw err;

package/src/runtime/shared/background-tasks.mjs

@@ -310,7 +310,9 @@ export function cleanupBackgroundTasks(options = {}) {
 function cancelRunningTask(task, reason, notify, terminalReason = null) {
   try {
     task.cancel?.();
-  } catch {}
+  } catch {
+    // A failing cancel hook must not stop the task from being marked cancelled.
+  }
   completeBackgroundTask(task.taskId, { status: 'cancelled', error: reason, notify: notify === true, terminalReason });
   if (task.notifyOnCancel !== true || notify === true || task.status !== 'cancelled' || task.cancelNotify) return;
   if (notify === false) {
@@ -370,9 +372,12 @@ export function cancelBackgroundTasks(options = {}) {
   const wanted = clean(options.surface);
   const executionSessionId = clean(options.executionSessionId);
   const scope = normalizeTaskScope(options);
-  let cancelled = 0;
+  // Optional: only tasks started at/after this time (a turn's own work).
+  const startedSinceMs = Number(options.startedSinceMs) || 0;
+  const taskIds = [];
   for (const task of [...tasks.values()]) {
     if (wanted && task.surface !== wanted) continue;
+    if (startedSinceMs > 0 && !(task.startedAtMs >= startedSinceMs)) continue;
     // Scoped teardown must be exact. Legacy tasks without ownership stay
     // visible/recoverable, but may not be claimed by whichever session happens
     // to close first.
@@ -386,9 +391,9 @@ export function cancelBackgroundTasks(options = {}) {
       continue;
     }
     cancelRunningTask(task, reason, options.notify, terminalReason);
-    cancelled += 1;
+    taskIds.push(task.taskId);
   }
-  return { cancelled };
+  return { cancelled: taskIds.length, taskIds };
 }
 
 export function acknowledgeBackgroundTaskCompletion(taskId, options = {}) {
@@ -415,13 +420,17 @@ function resultTextForTask(task) {
         // fallback below so the completion notification still carries a body.
         try {
           process.stderr.write(`[background-${task.surface}] renderResult failed: ${err?.message || err}\n`);
-        } catch {}
+        } catch {
+          // A closed stderr must not lose the completion body.
+        }
       }
     }
     if (typeof task.result === 'string') return task.result;
     try {
       return JSON.stringify(task.result, null, 2);
-    } catch {}
+    } catch {
+      // Unserializable result (circular, BigInt): fall back to the empty body.
+    }
   }
   return '';
 }

package/src/runtime/shared/bot-owned-work.mjs

@@ -0,0 +1,56 @@
+// Bot-owned work: the live work in a session that a bot sent. A bot's accepted
+// `session` send or create (session-runtime/agent-task-sessions.mjs) is the
+// bot's work in that session from its acceptance until it settles or is
+// cancelled — whether or not it reports back (`notify: false`, a report watch
+// that could not be stored). A turn nobody sent (the user typed it in the
+// task session) is owned by no bot, so it never reads as a bot being busy.
+// Process-wide and dependency-free like delegated-approval-host.mjs. The
+// registry is only this process's cache: what keeps the work owned across a
+// restart is stored apart (a reporting send's watch, any other send's record
+// of its work, both in agent-home-delivery.mjs) and re-noted by
+// agent-task-sessions.mjs recover. A change of which bots own a session's work
+// is announced (session-activity-signal.mjs onSessionBotWorkChange), so the
+// session catalog, which stamps them on each row, re-lists.
+import { emitSessionBotWorkChange } from './session-activity-signal.mjs';
+
+const KEY = Symbol.for('mixdog.botOwnedWork.v1');
+
+/** Map run id → `{ sessionId, agentId }`. */
+function registry() {
+  globalThis[KEY] ??= new Map();
+  return globalThis[KEY];
+}
+
+/** How many owned works of `agentId` run in `sessionId`. */
+function worksOf(sessionId, agentId) {
+  let count = 0;
+  for (const work of registry().values()) if (work.sessionId === sessionId && work.agentId === agentId) count += 1;
+  return count;
+}
+
+/** Every session with owned work and the bots owning it (each once, in noting
+ *  order): Map session → agent ids. */
+export function botWorkBySession() {
+  const bySession = new Map();
+  for (const { sessionId, agentId } of registry().values()) {
+    const agents = bySession.get(sessionId) ?? [];
+    if (!agents.includes(agentId)) agents.push(agentId);
+    bySession.set(sessionId, agents);
+  }
+  return bySession;
+}
+
+/** Agent `agentId`'s submission `runId` to `sessionId` was accepted. */
+export function noteBotWork({ runId, sessionId, agentId }) {
+  if (!runId || !sessionId || !agentId || registry().has(String(runId))) return;
+  registry().set(String(runId), { sessionId: String(sessionId), agentId: String(agentId) });
+  if (worksOf(String(sessionId), String(agentId)) === 1) emitSessionBotWorkChange(sessionId);
+}
+
+/** Submission `runId` settled or was cancelled: its work is nobody's now. */
+export function endBotWork(runId) {
+  const work = registry().get(String(runId));
+  if (!work) return;
+  registry().delete(String(runId));
+  if (worksOf(work.sessionId, work.agentId) === 0) emitSessionBotWorkChange(work.sessionId);
+}

package/src/runtime/shared/connector-accounts.mjs

@@ -1,7 +1,7 @@
-// What a multi-account connector server tells the model about itself (MCP
+// What a connector server tells the model about its accounts (MCP
 // `instructions`), in one line: the connected accounts, and that each tool
-// takes `account` (asked of the user when several are connected and none was
-// named). An account that cannot be used right now is listed with why.
+// takes `account` (left out, the account used last). An account that cannot
+// be used right now is listed with why.
 
 /** The MCP instructions naming `accounts` (`{ email, note? }`, `note` a short
  *  reason it is unusable such as "needs sign-in"; one without an address is
@@ -12,12 +12,12 @@ export function connectorAccountsInstructions(accounts) {
   const list = named.map(({ email, note }) => (note ? `${email} (${note})` : email)).join(', ');
   return named.length === 1
     ? `Accounts: ${list}. \`account\` may be left out.`
-    : `Accounts: ${list}. Pass \`account\`; if the user named none and there are several, ask which.`;
+    : `Accounts: ${list}. \`account\` picks one; left out, a call uses the account used last, and its result names it.`;
 }
 
 /** The account addresses instructions from connectorAccountsInstructions name. */
 export function accountsOfInstructions(instructions) {
-  const list = /^Accounts: (.+?)\. (?:`account`|Pass `account`)/.exec(String(instructions || ''))?.[1] || '';
+  const list = /^Accounts: (.+?)\. `account`/.exec(String(instructions || ''))?.[1] || '';
   return list
     .split(', ')
     .map((part) => part.replace(/ \(.*\)$/, '').trim())

package/src/runtime/shared/connector-catalog.d.mts

@@ -40,8 +40,7 @@ export function connectorToolDefault(connectorId: string, tool: string): 'auto'
 export function connectorServerInput(
   entry: ConnectorCatalogEntry,
   name: string,
-  key?: string,
-  options?: { extraAccount?: boolean }
+  key?: string
 ): Record<string, unknown>;
 export function connectorAppPasswordOnly(entry: ConnectorCatalogEntry | null | undefined): boolean;
 export function connectorUsesGoogleClient(entry: ConnectorCatalogEntry | null | undefined): boolean;
@@ -52,12 +51,19 @@ export function gmailAppPasswordValue(value: unknown): string;
 export function gmailAppPasswordAccount(cfg: unknown): string;
 export function gmailAppPasswordServerInput(name: string, email: string, password: string): Record<string, unknown>;
 
-/** One stored account of a multi-account connector server. */
+/** One stored account of a connector server. */
 export interface ConnectorAccountEntry {
   name: string;
-  url: string;
+  /** Absent: http. */
+  type?: string;
+  url?: string;
   headers?: Record<string, string>;
   oauthClientId?: string;
+  /** The account's own sign-in key, when another account signs in at its URL. */
+  oauthKey?: string;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
   /** `false`: the account is kept but neither connected nor called. */
   enabled?: boolean;
 }
@@ -76,6 +82,7 @@ export function withConnectorAccountEnabled(
   enabled: boolean
 ): Record<string, unknown>;
 export function connectorAccountEntry(name: string, cfg: Record<string, unknown>): ConnectorAccountEntry;
+export function connectorServerSettings(cfg: Record<string, unknown>): Record<string, unknown>;
 export function mergeConnectorAccountServers(servers: Record<string, unknown>): {
   servers: Record<string, unknown>;
   merged: { connector: string; name: string; from: string[] }[];

package/src/runtime/shared/connector-catalog.mjs

@@ -184,25 +184,27 @@ export function gmailAppPasswordServerInput(name, email, password) {
 }
 
 /** Whether several accounts of catalog connector `entry` can be connected at
- *  once: Gmail (also by app password), Calendar and Drive with the Google
- *  sign-in. Other remote servers keep one (their tokens and URL are shared). */
+ *  once: every catalog connector holds its accounts in one server. */
 export function connectorMultiAccount(entry) {
-  return entry?.backend?.kind === 'oauth' && entry.backend.oauthClient === 'google';
+  return Boolean(entry?.id) && connectorById(entry.id) === entry;
 }
 
-// ── One server per multi-account connector ──────────────────────────────────
-// A multi-account connector is ONE MCP server (`gmail`, `google-calendar`,
-// `google-drive`) holding its accounts:
+// ── One server per connector ────────────────────────────────────────────────
+// A catalog connector is ONE MCP server (`gmail`, `notion`, `postgres`…)
+// holding its accounts:
 //   { type: 'http', url: connectorAccountsUrl(id), connector: id,
-//     accounts: [{ name, url, headers?, oauthClientId? }, …] }
-// Each account keeps the transport it had as a server of its own (the Google
-// sign-in URL its tokens are stored under, or the app-password address and
-// account header), so its keychain entries are untouched. Account names share
-// the server-name space (`gmail`, `gmail-2`…): a name-based call (remove, sign
-// in, sign out) that names an account acts on that account. The server is
-// answered in-process (connectors/connector-accounts-mcp.mjs): one tool set
-// with an `account` argument.
-const ACCOUNT_FIELDS = ['url', 'headers', 'oauthClientId'];
+//     accounts: [{ name, type?, url?, headers?, oauthClientId?, oauthKey?,
+//                  command?, args?, env? }, …] }
+// Each account keeps the transport it had as a server of its own (its remote
+// URL and sign-in, its key header, its app-password address, or its local
+// command and environment), so its keychain entries are untouched. A remote
+// sign-in is stored under the account's URL, or under its own `oauthKey` when
+// another account of the connector already signs in at that URL. Account names
+// share the server-name space (`notion`, `notion-2`…): a name-based call
+// (remove, sign in, sign out) that names an account acts on that account. The
+// server is answered in-process (connectors/connector-accounts-mcp.mjs): one
+// tool set with an `account` argument.
+const ACCOUNT_FIELDS = ['type', 'url', 'headers', 'oauthClientId', 'oauthKey', 'command', 'args', 'env'];
 
 /** The reserved (never resolvable) address of connector `id`'s accounts server. */
 export function connectorAccountsUrl(id) {
@@ -211,14 +213,16 @@ export function connectorAccountsUrl(id) {
 
 const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 
-/** The stored accounts of a multi-account connector server, [] for any other
- *  config (a legacy one-account server included). */
+/** The stored accounts of a connector server, [] for any other config (a
+ *  legacy one-account server included). */
 export function connectorAccountsOf(cfg) {
-  if (!isRecord(cfg) || !Array.isArray(cfg.accounts)) return [];
-  if (!connectorMultiAccount(connectorById(connectorOfServer(cfg)))) return [];
+  if (!isRecord(cfg) || !Array.isArray(cfg.accounts) || !connectorOfServer(cfg)) return [];
   return cfg.accounts.filter(
     (account) =>
-      isRecord(account) && typeof account.name === 'string' && account.name && typeof account.url === 'string'
+      isRecord(account) &&
+      typeof account.name === 'string' &&
+      account.name &&
+      (typeof account.url === 'string' || typeof account.command === 'string')
   );
 }
 
@@ -231,6 +235,12 @@ export function connectorAccountServer(cfg, account) {
   return out;
 }
 
+/** `cfg` without what is an account's own connection: the settings of the
+ *  server holding its accounts (timeouts, enabled…). */
+export function connectorServerSettings(cfg) {
+  return Object.fromEntries(Object.entries(cfg).filter(([key]) => key !== 'accounts' && !ACCOUNT_FIELDS.includes(key)));
+}
+
 /** Every account of `cfg` as its one-account server config. */
 export function connectorAccountServers(cfg) {
   return connectorAccountsOf(cfg).map((account) => connectorAccountServer(cfg, account));
@@ -264,33 +274,39 @@ export function withConnectorAccountEnabled(cfg, name, enabled) {
   return connectorAccountsOf(next).some(connectorAccountEnabled) ? next : { ...next, enabled: false };
 }
 
-/** The stored account entry of one-account config `cfg` under `name`. */
+/** The stored account entry of one-account config `cfg` under `name` (an
+ *  http transport is the default and is not stored). */
 export function connectorAccountEntry(name, cfg) {
   const out = { name };
   for (const field of ACCOUNT_FIELDS) if (cfg?.[field] !== undefined) out[field] = cfg[field];
+  if (out.type === 'http') delete out.type;
   return out;
 }
 
 const naturalOrder = (a, b) => a.localeCompare(b, 'en', { numeric: true });
 
+/** What makes an account the same connection as another: its transport
+ *  (URL, sign-in key, headers, command and environment), whatever its name. */
+const connectionOf = (cfg, account) => JSON.stringify({ ...connectorAccountServer(cfg, account), name: '' });
+
 /**
- * Merges every multi-account connector's servers into one server holding the
- * accounts: legacy one-account servers (`gmail`, `gmail-2`…, Calendar and
- * Drive alike) and any second accounts server. The server keeps the name of
- * an existing accounts server, else the connector id when a server has it,
+ * Merges every catalog connector's servers into one server holding the
+ * accounts: legacy one-account servers (`notion`, `notion-2`…, Gmail, Calendar
+ * and Drive alike) and any second accounts server. The server keeps the name
+ * of an existing accounts server, else the connector id when a server has it,
  * else the first name; its other fields come from that server. Accounts keep
  * their names, transports and order (that server's first); a second entry
- * for the same name or app-password address is dropped. The merged server is
- * off only when every merged one was; otherwise the accounts of a merged
- * server that was off stay off (`enabled: false` on the account), and an
- * account's own `enabled: false` is kept. A server left with no switched-on
- * account is off. Idempotent: `merged` is empty when
- * nothing changed. Returns `{ servers, merged: [{ connector, name, from }] }`.
+ * for the same name, app-password address or connection is dropped. The
+ * merged server is off only when every merged one was; otherwise the accounts
+ * of a merged server that was off stay off (`enabled: false` on the account),
+ * and an account's own `enabled: false` is kept. A server left with no
+ * switched-on account is off. Idempotent: `merged` is empty when nothing
+ * changed. Returns `{ servers, merged: [{ connector, name, from }] }`.
  */
 export function mergeConnectorAccountServers(input) {
   const servers = isRecord(input) ? { ...input } : {};
   const merged = [];
-  for (const entry of CONNECTOR_CATALOG.filter(connectorMultiAccount)) {
+  for (const entry of CONNECTOR_CATALOG) {
     const names = Object.keys(servers)
       .filter((name) => isRecord(servers[name]) && connectorOfServer(servers[name]) === entry.id)
       .sort(naturalOrder);
@@ -303,6 +319,7 @@ export function mergeConnectorAccountServers(input) {
     const accounts = [];
     const seenNames = new Set();
     const seenAddresses = new Set();
+    const seenConnections = new Set();
     for (const name of order) {
       const cfg = servers[name];
       const own = Array.isArray(cfg.accounts) ? connectorAccountsOf(cfg) : [connectorAccountEntry(name, cfg)];
@@ -311,21 +328,17 @@ export function mergeConnectorAccountServers(input) {
       const serverOff = !off && cfg.enabled === false;
       for (const account of own) {
         const address = gmailAppPasswordAccount(connectorAccountServer(cfg, account));
-        if (seenNames.has(account.name) || (address && seenAddresses.has(address))) continue;
+        const connection = connectionOf(cfg, account);
+        if (seenNames.has(account.name) || (address && seenAddresses.has(address)) || seenConnections.has(connection)) {
+          continue;
+        }
         seenNames.add(account.name);
         if (address) seenAddresses.add(address);
+        seenConnections.add(connection);
         accounts.push(serverOff ? { ...account, enabled: false } : account);
       }
     }
-    const {
-      type: _type,
-      url: _url,
-      headers: _headers,
-      oauthClientId: _client,
-      accounts: _accounts,
-      enabled: _enabled,
-      ...rest
-    } = servers[target];
+    const { enabled: _enabled, ...rest } = connectorServerSettings(servers[target]);
     for (const name of order) delete servers[name];
     servers[target] = {
       ...rest,
@@ -352,17 +365,12 @@ export function connectorUsesGoogleClient(entry) {
 }
 
 /** The MCP server input that connects catalog entry `entry` under `name`
- *  (oauth / apiKey); `key` fills an apiKey backend; `extraAccount`
- *  makes it one more account of a multi-account connector. */
-export function connectorServerInput(entry, name, key = '', { extraAccount = false } = {}) {
+ *  (oauth / apiKey); `key` fills an apiKey backend. Every account keeps the
+ *  service's real URL; another account at that URL gets its own sign-in key
+ *  (resource-mcp-connector-accounts.mjs). */
+export function connectorServerInput(entry, name, key = '') {
   const { backend } = entry;
-  if (backend.kind === 'oauth') {
-    // Tokens are stored per exact server URL, so another account of the same
-    // connector needs its own URL; the in-process Google servers ignore the query.
-    const url =
-      extraAccount && connectorMultiAccount(entry) ? `${backend.url}?account=${encodeURIComponent(name)}` : backend.url;
-    return { name, type: 'http', url, connector: entry.id };
-  }
+  if (backend.kind === 'oauth') return { name, type: 'http', url: backend.url, connector: entry.id };
   if (backend.kind !== 'apiKey') throw new Error(`${entry.name} is not an MCP connector`);
   const value = String(key || '').trim();
   if (!value) throw new Error(`${entry.name} needs a key`);

package/src/runtime/shared/custom-provider-keys.mjs

@@ -0,0 +1,20 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { getSecret } = require('../../lib/keychain-cjs.cjs');
+
+// A custom provider's additional API keys are keychain secrets beside its
+// primary key (`agent.<id>.apiKey`), one per key id of its roster
+// (provider-accounts.mjs `setCustomProviderKeyIds`). Never config values.
+export function customProviderKeyAccount(providerId, keyId) {
+  return `agent.${providerId}.apiKey.${keyId}`;
+}
+
+/** The stored value of additional key `keyId`, or '' when it is not readable. */
+export function readCustomProviderKey(providerId, keyId) {
+  try {
+    return getSecret(customProviderKeyAccount(providerId, keyId)) || '';
+  } catch {
+    return '';
+  }
+}

package/src/runtime/shared/defaults-separation.mjs

@@ -176,10 +176,7 @@ function removeLegacyKeys(root, dataDir) {
  * not set the marker. `stripRouteDefaults` drops shipped presets and
  * maintenance routes (their defaults live with the agent config).
  */
-function separateDefaultsInConfig(
-  root,
-  { stripRouteDefaults = (agent) => agent, dataDir = resolvePluginData() } = {}
-) {
+function separateDefaultsInConfig(root, { stripRouteDefaults = (agent) => agent, dataDir = resolvePluginData() } = {}) {
   const from = Number(root?.[DEFAULTS_VERSION_KEY]) || 0;
   let next = { ...(root || {}) };
   if (from < 1) {

package/src/runtime/shared/fetch-safe-listen.d.mts

@@ -0,0 +1,16 @@
+import type { Server } from 'node:net';
+
+export const FETCH_BLOCKED_PORTS: ReadonlySet<number>;
+
+export const FETCH_SAFE_ATTEMPTS: number;
+
+export function listenOnFetchSafePort(
+  server: Server,
+  host: string,
+  onListening: () => void,
+  options?: {
+    attempts?: number;
+    isCurrent?: () => boolean;
+    portOf?: (server: Server) => number;
+  }
+): void;

package/src/runtime/shared/fetch-safe-listen.mjs

@@ -0,0 +1,50 @@
+// Ports the WHATWG Fetch spec blocks ("bad port"): fetch (undici) and Chromium
+// refuse to connect to them, so a loopback server that a fetch client or a
+// browser context must reach cannot live on one. https://fetch.spec.whatwg.org/#port-blocking
+export const FETCH_BLOCKED_PORTS = new Set([
+  0, 1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77, 79, 87, 95, 101, 102, 103, 104, 109, 110,
+  111, 113, 115, 117, 119, 123, 135, 137, 139, 143, 161, 179, 389, 427, 465, 512, 513, 514, 515, 526, 530, 531, 532,
+  540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993, 995, 1719, 1720, 1723, 2049, 3659, 4045, 4190, 5060, 5061,
+  6000, 6566, 6665, 6666, 6667, 6668, 6669, 6679, 6697, 10080,
+]);
+
+/** How many more OS-assigned ports a listener takes after a blocked one. */
+export const FETCH_SAFE_ATTEMPTS = 16;
+
+const assignedPort = (server) => {
+  const address = server.address();
+  return address && typeof address === 'object' ? address.port : 0;
+};
+
+/**
+ * `server.listen(0, host)` that never settles on a fetch-blocked port: when the
+ * OS assigns one, the server is closed and listened again, at most `attempts`
+ * more times. `onListening` runs once, on a safe port. When the attempts run
+ * out the server is closed and an 'error' is emitted, like a failed listen.
+ * `isCurrent` lets a caller that stopped the server meanwhile cancel the retry;
+ * `portOf` reads the assigned port.
+ */
+export function listenOnFetchSafePort(
+  server,
+  host,
+  onListening,
+  { attempts = FETCH_SAFE_ATTEMPTS, isCurrent = () => true, portOf = assignedPort } = {}
+) {
+  let retries = attempts;
+  const attempt = () => {
+    server.listen(0, host, () => {
+      if (!FETCH_BLOCKED_PORTS.has(portOf(server))) {
+        onListening();
+        return;
+      }
+      const exhausted = retries <= 0;
+      retries -= 1;
+      server.close(() => {
+        if (!isCurrent()) return;
+        if (exhausted) server.emit('error', new Error('no fetch-safe loopback port was assigned'));
+        else attempt();
+      });
+    });
+  };
+  attempt();
+}

package/src/runtime/shared/file-has-data.mjs

@@ -1,14 +1,22 @@
 import { closeSync, openSync, readSync } from 'node:fs';
+import { open } from 'node:fs/promises';
 import { holdsNoData } from './atomic-file.mjs';
 
 const PROBE_BYTES = 4096;
 
+// Only these errno codes mean the path names no file. Every other failure
+// leaves the file present (a scanner's or the running process's lock, EIO, ...):
+// this is an install check on settings and status paths, so it never throws.
+const ABSENT_CODES = new Set(['ENOENT', 'ENOTDIR']);
+const presentDespite = (err) => !ABSENT_CODES.has(err?.code);
+
 /**
  * Install check for a downloaded binary or model: false when `path` is absent
  * or its first bytes hold no data (empty, or NUL-filled by a crash that
  * committed the size but not the bytes). Cheaper than hashing a multi-GB file
  * on every use. A file that exists but cannot be opened right now (locked by a
- * scanner or by the process running it) still counts as present.
+ * scanner or by the process running it) still counts as present, as does any
+ * other failure.
  */
 export function fileHasData(path) {
   let fd;
@@ -17,7 +25,7 @@ export function fileHasData(path) {
     const head = Buffer.alloc(PROBE_BYTES);
     return !holdsNoData(head.subarray(0, readSync(fd, head, 0, PROBE_BYTES, 0)));
   } catch (err) {
-    return err?.code !== 'ENOENT' && err?.code !== 'ENOTDIR';
+    return presentDespite(err);
   } finally {
     if (fd !== undefined) {
       try {
@@ -26,3 +34,19 @@ export function fileHasData(path) {
     }
   }
 }
+
+/** Same verdict as `fileHasData`, without blocking the event loop on the open
+ *  (an antivirus scan of a binary can stall a synchronous open for seconds). */
+export async function fileHasDataAsync(path) {
+  let handle;
+  try {
+    handle = await open(path, 'r');
+    const head = Buffer.alloc(PROBE_BYTES);
+    const { bytesRead } = await handle.read(head, 0, PROBE_BYTES, 0);
+    return !holdsNoData(head.subarray(0, bytesRead));
+  } catch (err) {
+    return presentDespite(err);
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}