mixdog 0.8.1 → 0.9.1

package/src/runtime/search/lib/state.mjs

@@ -88,10 +88,6 @@ export function loadUsageState() {
   return state
 }
 
-export function saveUsageState(state) {
-  scheduleUsageFlush(state)
-}
-
 export function updateProviderState(state, provider, patch) {
   let normalizedPatch = { ...patch }
   const remaining =
@@ -125,7 +121,7 @@ export function noteProviderSuccess(state, provider, extra = {}) {
   })
 }
 
-export const PROVIDER_ERROR_KIND = {
+const PROVIDER_ERROR_KIND = {
   AUTH: 'auth',
   QUOTA: 'quota',
   PAYMENT: 'payment',
@@ -151,16 +147,6 @@ export function classifyProviderError(error) {
   return PROVIDER_ERROR_KIND.UNKNOWN
 }
 
-/** Structured HTTP error for search backends (enables cooldown via classifyProviderError). */
-export function providerHttpError(provider, status, detail = '') {
-  const code = Number(status)
-  const snippet = detail ? `: ${String(detail).slice(0, 200)}` : ''
-  const err = new Error(`[search:${provider}] HTTP ${code}${snippet}`)
-  err.status = code
-  err.provider = provider
-  return err
-}
-
 const PROVIDER_DISABLE_TTL_MS = {
   auth: 24 * 3600 * 1000,
   quota: 24 * 3600 * 1000,

package/src/runtime/search/lib/web-tools.mjs

@@ -3,12 +3,26 @@ import dns from 'dns'
 import net from 'net'
 import { Agent, fetch as undiciFetch } from 'undici'
 
-import { JSDOM } from 'jsdom'
-import puppeteer from 'puppeteer-core'
 import { Readability } from '@mozilla/readability'
 import { isWSL } from '../../shared/wsl.mjs'
 import { startChildGuardian } from '../../shared/child-guardian.mjs'
 
+// Lazy heavy deps: importing jsdom (~400ms) and puppeteer-core (~130ms) at
+// module load added ~540ms to the first web search even when the request never
+// scraped HTML. Load them on first actual use and cache the resolved binding so
+// repeat calls pay nothing. The search runtime itself is already dynamically
+// imported, so this keeps that first-use cost proportional to what the request
+// truly needs (a plain fetch path touches neither).
+let _JSDOM = null
+async function loadJSDOM() {
+  if (!_JSDOM) ({ JSDOM: _JSDOM } = await import('jsdom'))
+  return _JSDOM
+}
+let _puppeteer = null
+async function loadPuppeteer() {
+  if (!_puppeteer) _puppeteer = (await import('puppeteer-core')).default
+  return _puppeteer
+}
 
 const PKG_VERSION = (() => { try { return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version } catch { return '0.0.1' } })()
 import {
@@ -491,7 +505,8 @@ function classifyJavascriptRenderingPlaceholder(page) {
   return null
 }
 
-function extractReadableArticle(url, html) {
+async function extractReadableArticle(url, html) {
+  const JSDOM = await loadJSDOM()
   const dom = new JSDOM(html, { url })
   try {
     const doc = dom.window.document
@@ -701,11 +716,11 @@ async function fetchPinnedForPausedRequest(url, { signal, method = 'GET', header
       currentUrl = new URL(location, currentUrl).toString()
       continue
     }
-    const body = await readBodyBytesWithCap(response, MAX_BODY_BYTES)
+    const respBody = await readBodyBytesWithCap(response, MAX_BODY_BYTES)
     return {
       status: response.status,
       responseHeaders: headersToCdpPairs(response.headers),
-      body,
+      body: respBody,
     }
   }
 }
@@ -812,7 +827,7 @@ async function scrapeWithReadability(url, timeoutMs, signal) {
     currentUrl = target
     html = await fetchHtml(currentUrl, timeoutMs, signal)
   }
-  return extractReadableArticle(currentUrl, html)
+  return await extractReadableArticle(currentUrl, html)
 }
 
 function resolveBrowserLaunchOptions() {
@@ -888,23 +903,26 @@ async function _getPoolBrowser() {
   }
   if (_poolBrowser) return _poolBrowser
   if (!_poolLaunching) {
-    _poolLaunching = puppeteer.launch({
-      headless: true,
-      ...resolveBrowserLaunchOptions(),
-      args: buildPuppeteerLaunchArgs(),
-    }).then((browser) => {
-      _poolBrowser = browser
-      try {
-        const proc = browser.process?.()
-        startChildGuardian({ childPid: proc?.pid, label: 'puppeteer-browser' })
-      } catch {}
-      browser.on('disconnected', () => {
-        if (_poolBrowser === browser) _poolBrowser = null
+    _poolLaunching = loadPuppeteer()
+      .then((puppeteer) => puppeteer.launch({
+        headless: true,
+        ...resolveBrowserLaunchOptions(),
+        args: buildPuppeteerLaunchArgs(),
+      }))
+      .then((browser) => {
+        _poolBrowser = browser
+        try {
+          const proc = browser.process?.()
+          startChildGuardian({ childPid: proc?.pid, label: 'puppeteer-browser' })
+        } catch {}
+        browser.on('disconnected', () => {
+          if (_poolBrowser === browser) _poolBrowser = null
+        })
+        return browser
+      })
+      .finally(() => {
+        _poolLaunching = null
       })
-      return browser
-    }).finally(() => {
-      _poolLaunching = null
-    })
   }
   return _poolLaunching
 }
@@ -1033,7 +1051,7 @@ async function scrapeWithPuppeteer(url, timeoutMs, signal) {
     }
     try {
       return {
-        ...extractReadableArticle(finalUrl, html),
+        ...(await extractReadableArticle(finalUrl, html)),
         extractor: 'puppeteer',
       }
     } catch {
@@ -1088,7 +1106,8 @@ function filterLinks(rawLinks, baseUrl, { limit = 50, sameDomainOnly = true, sea
   return items
 }
 
-function extractLinksFromHtml(baseUrl, html, options) {
+async function extractLinksFromHtml(baseUrl, html, options) {
+  const JSDOM = await loadJSDOM()
   const dom = new JSDOM(html, { url: baseUrl })
   try {
     const links = Array.from(dom.window.document.querySelectorAll('a[href]')).map(link => ({
@@ -1103,7 +1122,7 @@ function extractLinksFromHtml(baseUrl, html, options) {
 
 async function mapWithHttp(url, options, timeoutMs, signal) {
   const html = await fetchHtml(url, timeoutMs, signal)
-  return extractLinksFromHtml(url, html, options)
+  return await extractLinksFromHtml(url, html, options)
 }
 
 async function mapWithPuppeteer(url, options, timeoutMs, signal) {

package/src/runtime/search/tool-defs.mjs

@@ -1,44 +1,37 @@
 import {
-  TOOL_ASYNC_EXECUTION_CONTRACT,
   TOOL_SYNC_EXECUTION_CONTRACT,
-  executionModeSchemaDescription,
-} from '../shared/background-tasks.mjs';
+} from '../shared/tool-execution-contract.mjs';
 
 export const TOOL_DEFS = [
   {
     name: 'search',
     title: 'Mixdog Web Search',
-    description: `Web search through the Web Researcher agent. Prefer mode=async for broad/current web research or multi-query searches; use sync only when the next step must block on this result. ${TOOL_SYNC_EXECUTION_CONTRACT} ${TOOL_ASYNC_EXECUTION_CONTRACT} Keeps Mixdog search caching, fan-out, and result formatting.`,
+    description: `Web/docs/current-info search. Not repo-local; use explore/code_graph/grep. ${TOOL_SYNC_EXECUTION_CONTRACT} Cached; query supports array fan-out.`,
     inputSchema: {
       type: 'object',
       properties: {
-        query: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Search query, or array for fan-out. Keep each query focused.' },
-        mode: { type: 'string', enum: ['async', 'sync'], description: `${executionModeSchemaDescription('sync')} Prefer async for non-trivial web research; choose sync only for an explicit blocking lookup.` },
-        action: { type: 'string', enum: ['run', 'list', 'status', 'read', 'cancel'], description: 'Default run. list/status/read/cancel are manual recovery controls for async search tasks.' },
-        task_id: { type: 'string', description: 'Shared background task id for manual status/read/cancel recovery.' },
-        firstResponseTimeoutMs: { type: 'number', minimum: 0, description: 'Abort only when the Web Researcher produces no first stream/tool activity within this many ms. Default 120s. 0 disables this watchdog.' },
-        idleTimeoutMs: { type: 'number', minimum: 0, description: 'Stale watchdog after first Web Researcher stream/tool activity. Default 30m. 0 disables stale abort.' },
-        site: { type: 'string', description: 'Optional site/domain filter.' },
-        type: { type: 'string', enum: ['web', 'news', 'images'], description: 'Search type. Default web.' },
-        maxResults: { type: 'number', minimum: 1, maximum: 20, description: 'Maximum results to return, 1-20.' },
+        query: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Query or array for fan-out.' },
+        site: { type: 'string', description: 'Site/domain filter.' },
+        type: { type: 'string', enum: ['web', 'news', 'images'], description: 'Default web.' },
+        maxResults: { type: 'number', minimum: 1, maximum: 20, description: 'Result count, 1-20.' },
         locale: {
-          description: 'Optional locale hint as a string or structured location/language object.',
+          description: 'Optional locale hint.',
           anyOf: [
             { type: 'string' },
             {
               type: 'object',
               properties: {
-                country: { type: 'string', description: 'Country code or name for result localization.' },
-                language: { type: 'string', description: 'Preferred result language.' },
-                region: { type: 'string', description: 'Region/state hint.' },
-                city: { type: 'string', description: 'City hint.' },
-                timezone: { type: 'string', description: 'IANA timezone hint.' },
+                country: { type: 'string', description: 'Country.' },
+                language: { type: 'string', description: 'Language.' },
+                region: { type: 'string', description: 'Region.' },
+                city: { type: 'string', description: 'City.' },
+                timezone: { type: 'string', description: 'Timezone.' },
               },
               additionalProperties: false,
             },
           ],
         },
-        contextSize: { type: 'string', enum: ['low', 'medium', 'high'], description: 'Search context size hint. Default low.' },
+        contextSize: { type: 'string', enum: ['low', 'medium', 'high'], description: 'Default low.' },
       },
       required: [],
       additionalProperties: false,
@@ -48,12 +41,12 @@ export const TOOL_DEFS = [
   {
     name: 'web_fetch',
     title: 'Mixdog Web Fetch',
-    description: 'Fetch full page body from a URL (web page, article, docs). Requires url. Use after search to read a result.',
+    description: 'Use after search. Fetch page/docs body from URL.',
     inputSchema: {
       type: 'object',
       properties: {
-        url: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'URL, or array of URLs, to fetch.' },
-        startIndex: { type: 'number', minimum: 0, description: 'Character offset for paging large pages.' },
+        url: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'URL or array of URLs.' },
+        startIndex: { type: 'number', minimum: 0, description: 'Character offset.' },
         maxLength: { type: 'number', minimum: 0, description: 'Maximum characters to return.' },
       },
       required: ['url'],

package/src/runtime/shared/abort-controller.mjs

@@ -1,5 +1,5 @@
 /**
- * AbortController helpers — ported from the Claude Code CLI pattern.
+ * AbortController helpers — ported from a reference agent CLI pattern.
  *
  * `createAbortController()` raises the signal's max listener cap so long-running
  * sessions with many per-iteration handlers don't trip Node's default warning.

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

@@ -121,9 +121,10 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
     // For secret-bearing critical sections, the lock file sits beside
     // the secret in the same (shared-home) directory; clamp it owner-only
     // too. Fail-closed: an unenforceable ACL aborts before fn() runs.
-    if (opts.secret === true) _enforceOwnerOnlyAclWin32(lockPath);
-    try { return fn(); }
-    finally {
+    try {
+      if (opts.secret === true) _enforceOwnerOnlyAclWin32(lockPath);
+      return fn();
+    } finally {
       try { closeSync(fd); } catch {}
       // Only unlink if we still own the lock. If our hold exceeded
       // staleMs and another process already stole + replaced the

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

@@ -19,6 +19,14 @@ const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
 const tasks = new Map();
 let seq = 0;
 
+// Owner-injected fallback used by notifyToolCompletion: when no notifyFn is
+// available (or it declines), enqueue the completion onto the caller session so
+// the owner is never left waiting on a canonical completion that never arrives.
+let _enqueueFallback = null;
+export function setBackgroundTaskEnqueueFallback(fn) {
+  _enqueueFallback = typeof fn === 'function' ? fn : null;
+}
+
 function clean(value) {
   return String(value ?? '').trim();
 }
@@ -41,7 +49,7 @@ export function resolveExecutionMode(args = {}, defaultMode = 'sync') {
 
 export function executionModeSchemaDescription(defaultMode = 'sync') {
   const defaultText = defaultMode === 'async' ? 'Default async.' : 'Default sync.';
-  return `Execution mode: sync returns the result in this call; async returns a task_id immediately and sends an owner-session notification on completion. ${defaultText}`;
+  return `sync = inline result; async = task_id + completion notification. ${defaultText}`;
 }
 
 export function taskIdFromArgs(args = {}) {
@@ -75,6 +83,45 @@ function normalizeTaskScope(options = {}) {
   };
 }
 
+const RENDER_META_OMIT_KEYS = new Set([
+  // Internal watchdog/control knobs are intentionally not part of the public
+  // task notification surface. They may appear on legacy/in-flight task meta
+  // from older callers, but rendering them teaches the model/user to set them.
+  'firstResponseTimeoutMs',
+  'idleTimeoutMs',
+  'spawnPrepTimeoutMs',
+  'watchdogPolicy',
+]);
+
+function isInternalTaskMetaKey(key) {
+  const name = clean(key);
+  if (!name) return true;
+  if (RENDER_META_OMIT_KEYS.has(name)) return true;
+  if (/timeoutms$/i.test(name)) return true;
+  return false;
+}
+
+/** Drop internal control knobs from meta before persisting on a task row. */
+export function sanitizeTaskMeta(meta = {}) {
+  if (!meta || typeof meta !== 'object') return {};
+  const out = {};
+  for (const [key, value] of Object.entries(meta)) {
+    if (isInternalTaskMetaKey(key)) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+function publicTaskMeta(meta = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(meta || {})) {
+    if (value == null || value === '') continue;
+    if (isInternalTaskMetaKey(key)) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
 function hasScopeCriteria(scope) {
   return Boolean(scope?.callerSessionId || scope?.routingSessionId || scope?.clientHostPid);
 }
@@ -153,7 +200,7 @@ export function registerBackgroundTask({
     ownerSessionId: notifyContext.callerSessionId || notifyContext.routingSessionId || null,
     routingSessionId: notifyContext.routingSessionId || notifyContext.callerSessionId || null,
     clientHostPid: notifyContext.clientHostPid || null,
-    meta: meta && typeof meta === 'object' ? meta : {},
+    meta: sanitizeTaskMeta(meta && typeof meta === 'object' ? meta : {}),
     resultType: clean(resultType) || null,
     renderResult: typeof renderResult === 'function' ? renderResult : null,
     cancel: typeof cancel === 'function' ? cancel : null,
@@ -167,7 +214,7 @@ export function startBackgroundTask(options = {}) {
   task.promise = Promise.resolve()
     .then(() => options.run?.())
     .then((result) => {
-      completeBackgroundTask(task.taskId, { status: 'completed', result });
+      completeBackgroundTask(task.taskId, { status: 'completed', result, terminalReason: 'run-resolved' });
       return result;
     })
     .catch((error) => {
@@ -175,6 +222,7 @@ export function startBackgroundTask(options = {}) {
       completeBackgroundTask(task.taskId, {
         status: 'failed',
         error,
+        terminalReason: 'run-rejected',
       });
       return null;
     });
@@ -241,7 +289,14 @@ function resultTextForTask(task) {
   if (task.resultText) return task.resultText;
   if (task.result !== undefined) {
     if (typeof task.renderResult === 'function') {
-      try { return String(task.renderResult(task.result, task) || ''); } catch {}
+      try {
+        const rendered = String(task.renderResult(task.result, task) || '');
+        if (rendered) return rendered;
+      } catch (err) {
+        // Don't silently swallow a renderer throw: fall through to the JSON
+        // fallback below so the completion notification still carries a body.
+        try { process.stderr.write(`[background-${task.surface}] renderResult failed: ${err?.message || err}\n`); } catch {}
+      }
     }
     if (typeof task.result === 'string') return task.result;
     try { return JSON.stringify(task.result, null, 2); } catch {}
@@ -257,6 +312,7 @@ export function completeBackgroundTask(taskId, {
   resultType,
   instruction,
   notify = true,
+  terminalReason = null,
 } = {}) {
   const task = getBackgroundTask(taskId);
   if (!task) return null;
@@ -265,17 +321,30 @@ export function completeBackgroundTask(taskId, {
   task.status = normalizeStatus(status);
   task.finishedAtMs = now;
   task.finishedAt = new Date(now).toISOString();
+  if (terminalReason) task.terminalReason = terminalReason;
   if (result !== undefined) task.result = result;
   if (resultText != null) task.resultText = compactText(resultText);
   if (error != null) task.error = presentErrorText(error, { surface: task.surface });
   if (resultType) task.resultType = resultType;
-  if (notify) notifyTaskCompletion(task, instruction);
+  if (notify) {
+    task.meta = sanitizeTaskMeta(task.meta);
+    notifyTaskCompletion(task, instruction);
+  }
   return task;
 }
 
 export function notifyTaskCompletion(task, instruction) {
-  if (!task || task.notified === true) return false;
+  if (!task) return false;
   if (!TERMINAL_STATUSES.has(task.status)) return false;
+  // `notified` tracks whether *any* completion notification was sent (e.g. an
+  // early header-only preview from the agent surface). A later call that can
+  // finally include the result body must still fire once, otherwise the owner
+  // only ever sees the bodyless preview. Gate on `notifiedWithBody` so the
+  // body-carrying notification is delivered exactly once.
+  const body = resultTextForTask(task);
+  const hasBody = Boolean(body);
+  if (task.notifiedWithBody === true) return false;
+  if (task.notified === true && !hasBody) return false;
   const text = renderBackgroundTask(task, { includeResult: true });
   const sent = notifyToolCompletion({
     surface: task.surface,
@@ -285,12 +354,43 @@ export function notifyTaskCompletion(task, instruction) {
     resultType: task.resultType || `${task.surface}_task_result`,
     instruction,
     context: task.notifyContext,
+    enqueueFallback: _enqueueFallback || undefined,
     logPrefix: `background-${task.surface}`,
   });
-  if (sent) task.notified = true;
+  if (sent) {
+    task.notified = true;
+    if (hasBody) task.notifiedWithBody = true;
+  }
   return sent;
 }
 
+// Safety net for the "task stuck in running" failure mode: when an upstream
+// owner (e.g. the agent surface) knows a job has reached a terminal state but
+// the normal run-resolved path did not mark the task — typically because a
+// post-result step (session save) hung or threw before the task promise could
+// settle — this forces the task to a terminal state and fires the completion
+// notification. Idempotent: a no-op once the task is already terminal.
+export function reconcileBackgroundTask(taskId, {
+  status = 'completed',
+  result,
+  resultText,
+  error,
+  instruction,
+  terminalReason = 'reconciled',
+} = {}) {
+  const task = getBackgroundTask(taskId);
+  if (!task) return null;
+  if (TERMINAL_STATUSES.has(task.status)) return task;
+  return completeBackgroundTask(task.taskId, {
+    status,
+    result,
+    resultText,
+    error,
+    instruction,
+    terminalReason,
+  });
+}
+
 export function notifyBackgroundTaskProgress(taskOrId, {
   text,
   resultText,
@@ -317,6 +417,7 @@ export function notifyBackgroundTaskProgress(taskOrId, {
     resultType: resultType || `${task.surface}_task_progress`,
     instruction,
     context: task.notifyContext,
+    enqueueFallback: _enqueueFallback || undefined,
     logPrefix: `background-${task.surface}`,
   });
   if (sent && once) task.progressNotifiedKeys.add(progressKey);
@@ -334,13 +435,14 @@ export function taskSummary(task) {
     startedAt: task.startedAt,
     finishedAt: task.finishedAt,
     error: task.error,
-    ...task.meta,
+    ...publicTaskMeta(task.meta),
   };
 }
 
 export function renderBackgroundTask(taskOrId, { includeResult = false } = {}) {
   const task = typeof taskOrId === 'string' ? getBackgroundTask(taskOrId) : taskOrId;
   if (!task) return 'Error: background task not found';
+  const visibleMeta = publicTaskMeta(sanitizeTaskMeta(task.meta));
   const lines = [
     'background task',
     `task_id: ${task.taskId}`,
@@ -352,8 +454,7 @@ export function renderBackgroundTask(taskOrId, { includeResult = false } = {}) {
     task.finishedAt ? `finished: ${task.finishedAt}` : null,
     task.error ? `error: ${task.error}` : null,
   ];
-  for (const [key, value] of Object.entries(task.meta || {})) {
-    if (value == null || value === '') continue;
+  for (const [key, value] of Object.entries(visibleMeta)) {
     lines.push(`${key}: ${value}`);
   }
   if (task.status === 'running') {
@@ -361,7 +462,17 @@ export function renderBackgroundTask(taskOrId, { includeResult = false } = {}) {
   }
   if (includeResult) {
     const body = resultTextForTask(task);
-    if (body) lines.push('', body);
+    if (body) {
+      lines.push('', body);
+    } else if (TERMINAL_STATUSES.has(task.status) && task.error) {
+      const errorText = String(task.error || '').trim();
+      lines.push('', /^error\s*:/i.test(errorText) ? errorText : `Error: ${errorText}`);
+    } else if (TERMINAL_STATUSES.has(task.status) && task.status === 'completed') {
+      // Terminal-completed task with no extractable body: surface a placeholder
+      // instead of silently omitting the result so the owner isn't left with a
+      // header-only card that looks truncated.
+      lines.push('', '(no result body — use read for full output)');
+    }
   }
   return lines.filter((line) => line !== null).join('\n');
 }

package/src/runtime/shared/child-spawn-gate.mjs

@@ -0,0 +1,139 @@
+'use strict';
+
+// ── Module-global child-spawn semaphore ──────────────────────────────────
+//
+// Single-daemon premise: tool execution is in-process, so a module-level
+// singleton semaphore bounds the number of concurrent child processes (rg,
+// mixdog-graph, …) across ALL agents/workers in this daemon. The goal is to
+// absorb the over-saturation tail — when N agents fire grep/code_graph at
+// once each child no longer fans out across every core, and the rg 20s
+// deadline stops tripping en masse — WITHOUT serializing: up to the cap run
+// concurrently, only the overflow queues and drains as slots free.
+//
+// IMPORTANT: this is a resource-control knob and is deliberately NOT exposed
+// on any tool JSON schema / tool parameter surface. The only tuning surface
+// is the internal constant + the MIXDOG_CHILD_SPAWN_MAX_INFLIGHT env override.
+
+import os from 'node:os';
+
+function _defaultMaxInflight() {
+  const override = Number(process.env.MIXDOG_CHILD_SPAWN_MAX_INFLIGHT);
+  if (Number.isFinite(override) && override >= 1) return Math.floor(override);
+  let cpus = 0;
+  try { cpus = os.cpus()?.length || 0; } catch { cpus = 0; }
+  return Math.max(4, cpus || 4);
+}
+
+const MAX_INFLIGHT = _defaultMaxInflight();
+
+// Warn (once-throttled, stderr only) when a waiter sat in the queue longer
+// than this — a coarse signal that the cap is undersized for the load. Kept
+// intentionally quiet so a busy daemon does not spam stderr.
+const SLOW_WAIT_MS = Math.max(
+  1000,
+  Number(process.env.MIXDOG_CHILD_SPAWN_SLOW_MS) || 10000,
+);
+const SLOW_WARN_THROTTLE_MS = 30000;
+
+let _inflight = 0;
+/** @type {Array<{ resolve: () => void, reject: (e: any) => void, signal: AbortSignal | null, onAbort: (() => void) | null, enqueuedAt: number }>} */
+const _queue = [];
+let _lastSlowWarnAt = 0;
+
+function _maybeWarnSlow(waitedMs) {
+  if (waitedMs < SLOW_WAIT_MS) return;
+  const now = Date.now();
+  if (now - _lastSlowWarnAt < SLOW_WARN_THROTTLE_MS) return;
+  _lastSlowWarnAt = now;
+  try {
+    process.stderr.write(
+      `[child-spawn-gate] queue wait ${waitedMs}ms (inflight cap=${MAX_INFLIGHT}, queued=${_queue.length}); `
+      + 'raise MIXDOG_CHILD_SPAWN_MAX_INFLIGHT if this persists\n',
+    );
+  } catch { /* ignore */ }
+}
+
+function _drain() {
+  while (_inflight < MAX_INFLIGHT && _queue.length > 0) {
+    const waiter = _queue.shift();
+    if (waiter.onAbort && waiter.signal) {
+      try { waiter.signal.removeEventListener('abort', waiter.onAbort); } catch { /* ignore */ }
+    }
+    _inflight++;
+    _maybeWarnSlow(Date.now() - waiter.enqueuedAt);
+    waiter.resolve();
+  }
+}
+
+/**
+ * Acquire one child-spawn slot. Resolves immediately when below the cap,
+ * otherwise queues until a slot frees. The returned function releases the
+ * slot and is idempotent (safe to call from multiple settle paths — only the
+ * first call counts). Supports an optional AbortSignal: aborting while still
+ * queued rejects with the signal reason and removes the waiter (no leak); a
+ * post-acquire abort is a no-op here — the caller owns teardown and must still
+ * call release().
+ *
+ * @param {AbortSignal | null} [signal]
+ * @returns {Promise<() => void>}
+ */
+export function acquire(signal = null) {
+  if (signal && signal.aborted) {
+    return Promise.reject(signal.reason ?? _abortError());
+  }
+  return new Promise((resolve, reject) => {
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      _inflight = Math.max(0, _inflight - 1);
+      _drain();
+    };
+    if (_inflight < MAX_INFLIGHT && _queue.length === 0) {
+      _inflight++;
+      resolve(release);
+      return;
+    }
+    const waiter = {
+      enqueuedAt: Date.now(),
+      signal: signal || null,
+      onAbort: null,
+      resolve: () => resolve(release),
+      reject,
+    };
+    if (signal) {
+      waiter.onAbort = () => {
+        const idx = _queue.indexOf(waiter);
+        if (idx !== -1) _queue.splice(idx, 1);
+        try { signal.removeEventListener('abort', waiter.onAbort); } catch { /* ignore */ }
+        reject(signal.reason ?? _abortError());
+      };
+      try { signal.addEventListener('abort', waiter.onAbort, { once: true }); } catch { /* ignore */ }
+    }
+    _queue.push(waiter);
+  });
+}
+
+function _abortError() {
+  const e = new Error('child-spawn-gate: aborted while queued');
+  e.code = 'ABORT_ERR';
+  return e;
+}
+
+/**
+ * Run `fn` while holding one child-spawn slot. Release is guaranteed in a
+ * finally so a throw/return from `fn` cannot leak a slot or deadlock the gate.
+ *
+ * @template T
+ * @param {(args: { signal: AbortSignal | null }) => Promise<T> | T} fn
+ * @param {AbortSignal | null} [signal]
+ * @returns {Promise<T>}
+ */
+export async function withGate(fn, signal = null) {
+  const release = await acquire(signal);
+  try {
+    return await fn({ signal: signal || null });
+  } finally {
+    release();
+  }
+}