mixdog 0.9.95 → 0.9.97

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

@@ -1,45 +1,108 @@
 'use strict';
 
+import { availableParallelism } from 'node:os';
+import { createOwnerFairGate } from './owner-fair-gate.mjs';
+import { currentToolExecutionOwner } from './tool-execution-owner.mjs';
+
 // ── Module-global child-spawn semaphore ──────────────────────────────────
 //
 // Single-daemon premise: tool execution is in-process, so a module-level
 // singleton semaphore CAN bound the number of concurrent child processes (rg,
 // mixdog-graph, …) across ALL agents/workers in this daemon.
 //
-// Default: 1 on win32, unbounded elsewhere. Measured on Windows (explore-bench
-// 13-way fan-out, 2026-08-05): concurrent rg spawns thrash the AV child-scan
-// path — wall 31-61s unbounded vs 20-23s at cap 1, monotonic 1<2<6≈∞, tool
-// p50 14.6s→11.0s, quality unchanged. Spawns are short (rg/graph only; shell
-// is deliberately NOT gated), so serializing them overlaps LLM waits instead
-// of starving anything. MIXDOG_CHILD_SPAWN_MAX_INFLIGHT still overrides.
+// Default: Windows search scales conservatively from 1..4 with CPU count;
+// code-graph remains 1. Other platforms are unbounded. Windows measurements
+// showed both extremes are poor: cap 1 creates multi-session queue latency,
+// while unbounded multithreaded rg amplifies Defender/process-scan and disk
+// contention. Separate lanes isolate short search from long graph builds.
+// MIXDOG_CHILD_SPAWN_MAX_INFLIGHT overrides globally.
 //
-// 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 MIXDOG_CHILD_SPAWN_MAX_INFLIGHT env override.
+// IMPORTANT: these are resource-control knobs and are deliberately NOT exposed
+// on any tool JSON schema / tool parameter surface. Operators may set the
+// shared MIXDOG_CHILD_SPAWN_MAX_INFLIGHT fallback or a lane-specific override.
 
-function _defaultMaxInflight() {
-  const override = Number(process.env.MIXDOG_CHILD_SPAWN_MAX_INFLIGHT);
+export function resolveDefaultChildSpawnMaxInflight(env = process.env, platform = process.platform) {
+  const override = Number(env.MIXDOG_CHILD_SPAWN_MAX_INFLIGHT);
   if (Number.isFinite(override) && override >= 1) return Math.floor(override);
-  return process.platform === 'win32' ? 1 : Infinity;
+  return platform === 'win32' ? 1 : Infinity;
+}
+
+export function resolveDefaultChildSpawnLaneMaxInflight(
+  laneName,
+  env = process.env,
+  platform = process.platform,
+  parallelism = availableParallelism(),
+) {
+  const lane = _laneName(laneName);
+  const key = lane.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
+  const laneOverride = Number(env[`MIXDOG_CHILD_SPAWN_${key}_MAX_INFLIGHT`]);
+  if (Number.isFinite(laneOverride) && laneOverride >= 1) return Math.floor(laneOverride);
+  const sharedOverride = Number(env.MIXDOG_CHILD_SPAWN_MAX_INFLIGHT);
+  if (Number.isFinite(sharedOverride) && sharedOverride >= 1) return Math.floor(sharedOverride);
+  if (platform !== 'win32') return Infinity;
+  if (lane !== 'search') return 1;
+  // Multiple rg processes beat one under multi-session load, but each process
+  // is itself threaded and Defender amplifies excess fan-out. Scale slowly and
+  // cap at four: 4 cores→1, 8→2, 12→3, 16+→4.
+  const cpus = Math.max(1, Math.floor(Number(parallelism) || 1));
+  return Math.max(1, Math.min(4, Math.floor(cpus / 4)));
 }
 
-const MAX_INFLIGHT = _defaultMaxInflight();
+const DEFAULT_MAX_INFLIGHT = resolveDefaultChildSpawnMaxInflight();
+const LANE_ALIASES = new Map([
+  ['default', 'search'],
+  ['build', 'code-graph'],
+]);
+
+function _laneName(name) {
+  const clean = String(name || 'search').trim().toLowerCase() || 'search';
+  return LANE_ALIASES.get(clean) || clean;
+}
+
+function _laneLimit(name) {
+  return resolveDefaultChildSpawnLaneMaxInflight(name);
+}
+
+function _laneSetting(name, suffix, fallback) {
+  const key = _laneName(name).toUpperCase().replace(/[^A-Z0-9]+/g, '_');
+  const laneValue = Number(process.env[`MIXDOG_CHILD_SPAWN_${key}_${suffix}`]);
+  if (Number.isFinite(laneValue) && laneValue >= 1) return Math.floor(laneValue);
+  const sharedValue = Number(process.env[`MIXDOG_CHILD_SPAWN_${suffix}`]);
+  return Number.isFinite(sharedValue) && sharedValue >= 1
+    ? Math.floor(sharedValue)
+    : fallback;
+}
 
 // ── Lanes ────────────────────────────────────────────────────────────────
-// One shared cap number, applied PER LANE with independent counters/queues:
-//   'default' — short-lived spawns (rg). Holding time is one search run.
-//   'build'   — long-lived builds (code-graph worker / graph binary). A cold
-//               graph build can hold its slot for seconds-to-minutes; on the
-//               win32 cap=1 default a single shared lane would let one build
+// Independent optional limits and queues:
+//   'search'     — short-lived rg processes.
+//   'code-graph' — long-lived graph workers / native graph binaries. A cold
+//               graph build can hold its slot for seconds-to-minutes; a
+//               single shared lane would let one build
 //               stall every rg spawn behind it. Separate lanes remove that
 //               starvation class while keeping each spawn family bounded.
-function _makeLane() {
-  return { inflight: 0, queue: [] };
+function _makeLane(name) {
+  const limit = _laneLimit(name);
+  const queueMax = _laneSetting(name, 'MAX_QUEUE', 1024);
+  const waitTimeoutMs = _laneSetting(name, 'WAIT_TIMEOUT_MS', 30_000);
+  return {
+    limit,
+    queueMax,
+    waitTimeoutMs,
+    gate: createOwnerFairGate({
+      name: `${name} child spawn`,
+      activeMax: limit,
+      queueMax,
+      minOwnerQueue: Math.max(8, Math.floor(queueMax / 32)),
+      waitTimeoutMs,
+    }),
+  };
 }
 const _lanes = new Map();
 function _lane(name) {
-  let lane = _lanes.get(name);
-  if (!lane) { lane = _makeLane(); _lanes.set(name, lane); }
+  const normalized = _laneName(name);
+  let lane = _lanes.get(normalized);
+  if (!lane) { lane = _makeLane(normalized); _lanes.set(normalized, lane); }
   return lane;
 }
 
@@ -61,24 +124,12 @@ function _maybeWarnSlow(waitedMs, laneName, lane) {
   _lastSlowWarnAt = now;
   try {
     process.stderr.write(
-      `[child-spawn-gate] lane=${laneName} queue wait ${waitedMs}ms (inflight cap=${MAX_INFLIGHT}, queued=${lane.queue.length}); `
-      + 'raise MIXDOG_CHILD_SPAWN_MAX_INFLIGHT if this persists\n',
+      `[child-spawn-gate] lane=${laneName} queue wait ${waitedMs}ms (inflight cap=${lane.limit}, queued=${lane.queue.length}); `
+      + 'raise the lane-specific MIXDOG_CHILD_SPAWN_*_MAX_INFLIGHT if this persists\n',
     );
   } catch { /* ignore */ }
 }
 
-function _drain(laneName, lane) {
-  while (lane.inflight < MAX_INFLIGHT && lane.queue.length > 0) {
-    const waiter = lane.queue.shift();
-    if (waiter.onAbort && waiter.signal) {
-      try { waiter.signal.removeEventListener('abort', waiter.onAbort); } catch { /* ignore */ }
-    }
-    lane.inflight++;
-    _maybeWarnSlow(Date.now() - waiter.enqueuedAt, laneName, lane);
-    waiter.resolve();
-  }
-}
-
 /**
  * Acquire one child-spawn slot. Resolves immediately when below the cap,
  * otherwise queues until a slot frees. The returned function releases the
@@ -89,45 +140,37 @@ function _drain(laneName, lane) {
  * call release().
  *
  * @param {AbortSignal | null} [signal]
- * @param {string} [laneName] — 'default' (short spawns) or 'build'.
+ * @param {string} [laneName] — 'search' (rg) or 'code-graph'.
  * @returns {Promise<() => void>}
  */
-export function acquire(signal = null, laneName = 'default') {
+export function acquire(signal = null, laneName = 'search', options = {}) {
   if (signal && signal.aborted) {
     return Promise.reject(signal.reason ?? _abortError());
   }
-  const lane = _lane(laneName);
-  return new Promise((resolve, reject) => {
-    let released = false;
-    const release = () => {
-      if (released) return;
-      released = true;
-      lane.inflight = Math.max(0, lane.inflight - 1);
-      _drain(laneName, lane);
-    };
-    if (lane.inflight < MAX_INFLIGHT && lane.queue.length === 0) {
-      lane.inflight++;
-      resolve(release);
-      return;
-    }
-    const waiter = {
-      enqueuedAt: Date.now(),
-      signal: signal || null,
-      onAbort: null,
-      resolve: () => resolve(release),
-      reject,
-    };
-    if (signal) {
-      waiter.onAbort = () => {
-        const idx = lane.queue.indexOf(waiter);
-        if (idx !== -1) lane.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 */ }
-    }
-    lane.queue.push(waiter);
+  const normalizedLaneName = _laneName(laneName);
+  const lane = _lane(normalizedLaneName);
+  const admitted = Promise.withResolvers();
+  const held = Promise.withResolvers();
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    held.resolve();
+  };
+  const ownerKey = options?.ownerKey || currentToolExecutionOwner();
+  const running = lane.gate.run(ownerKey, async () => {
+    admitted.resolve(release);
+    await held.promise;
+  }, {
+    signal,
+    waitTimeoutMs: options?.waitTimeoutMs ?? lane.waitTimeoutMs,
+    onAdmit: (waitedMs) => _maybeWarnSlow(waitedMs, normalizedLaneName, {
+      limit: lane.limit,
+      queue: { length: lane.gate.queued },
+    }),
   });
+  running.catch((error) => admitted.reject(error));
+  return admitted.promise;
 }
 
 function _abortError() {
@@ -147,9 +190,33 @@ function _abortError() {
  * best-effort work. Real queries must use acquire()/withGate() and never gate
  * themselves on this.
  */
-export function hasSpareCapacity(laneName = 'default') {
+export function hasSpareCapacity(laneName = 'search') {
   const lane = _lane(laneName);
-  return lane.inflight < MAX_INFLIGHT && lane.queue.length === 0;
+  return lane.gate.active < lane.limit && lane.gate.queued === 0;
+}
+
+export function snapshot() {
+  return {
+    maxInflight: Number.isFinite(DEFAULT_MAX_INFLIGHT) ? DEFAULT_MAX_INFLIGHT : null,
+    lanes: [..._lanes.entries()].map(([name, lane]) => {
+      const state = lane.gate.snapshot();
+      return {
+        name,
+        inflight: state.active,
+        queued: state.queued,
+        limit: Number.isFinite(lane.limit) ? lane.limit : null,
+        queueMax: lane.queueMax,
+        waitTimeoutMs: lane.waitTimeoutMs,
+        owners: state.owners,
+        oldestWaitMs: state.oldestWaitMs,
+        admitted: state.admitted,
+        rejected: state.rejected,
+        timedOut: state.timedOut,
+        averageWaitMs: state.averageWaitMs,
+        maxWaitMs: state.maxWaitMs,
+      };
+    }),
+  };
 }
 
 /**
@@ -162,7 +229,7 @@ export function hasSpareCapacity(laneName = 'default') {
  * @param {string} [laneName]
  * @returns {Promise<T>}
  */
-async function withGate(fn, signal = null, laneName = 'default') {
+async function withGate(fn, signal = null, laneName = 'search') {
   const release = await acquire(signal, laneName);
   try {
     return await fn({ signal: signal || null });

package/src/runtime/shared/config.mjs

@@ -117,6 +117,107 @@ function isPlainObject(value) {
   return !!value && typeof value === 'object' && !Array.isArray(value)
 }
 
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value || {}, key)
+}
+
+// Canonical on-disk channel shape. Provider-specific ids are durable. Schedule
+// arrays moved to the scheduler DB and prompt injection moved to runtime hooks,
+// so neither belongs in config anymore.
+export function canonicalizeStoredChannelsConfig(value = {}) {
+  const next = isPlainObject(value) ? { ...value } : {}
+  delete next.promptInjection
+  delete next.schedules
+  delete next.nonInteractive
+  delete next.interactive
+
+  const channel = isPlainObject(next.channel) ? { ...next.channel } : {}
+  next.provider = next.provider === 'telegram' || next.backend === 'telegram'
+    ? 'telegram'
+    : 'discord'
+  delete next.backend
+  delete channel.channelId
+  next.channel = channel
+  return next
+}
+
+// Normalize cross-section legacy keys without touching independent domains
+// (ui/theme, desktop, voice, channels access, memory schedules/embedding, …).
+// Reads use this shape in-memory; every subsequent locked write persists it.
+export function canonicalizeUnifiedConfig(value = {}) {
+  const next = isPlainObject(value) ? { ...value } : {}
+  const hadAgent = isPlainObject(next.agent)
+  const agent = hadAgent ? { ...next.agent } : {}
+
+  if (!String(next.outputStyle || '').trim() && String(agent.outputStyle || '').trim()) {
+    next.outputStyle = agent.outputStyle
+  }
+  delete agent.outputStyle
+
+  for (const key of ['autoClear', 'compaction', 'shell']) {
+    if (!isPlainObject(agent[key]) && isPlainObject(next[key])) agent[key] = next[key]
+    delete next[key]
+  }
+  if (isPlainObject(next.mcpServers)) {
+    agent.mcpServers = {
+      ...next.mcpServers,
+      ...(isPlainObject(agent.mcpServers) ? agent.mcpServers : {}),
+    }
+    delete next.mcpServers
+  }
+  if (!isPlainObject(agent.searchRoute) && isPlainObject(agent.search)) {
+    agent.searchRoute = agent.search
+  }
+  delete agent.search
+  delete agent.capabilities
+
+  const modules = isPlainObject(agent.modules) ? { ...agent.modules } : {}
+  if (hasOwn(modules, 'memory')) {
+    const legacyMemory = modules.memory
+    const explicitRecap = isPlainObject(agent.recap) && hasOwn(agent.recap, 'enabled')
+    if (!explicitRecap) {
+      const enabled = isPlainObject(legacyMemory)
+        ? legacyMemory.enabled !== false
+        : legacyMemory !== false
+      agent.recap = { ...(isPlainObject(agent.recap) ? agent.recap : {}), enabled }
+    }
+    delete modules.memory
+    agent.modules = modules
+  }
+
+  if (isPlainObject(next.memory)) {
+    const memory = { ...next.memory }
+    const user = isPlainObject(memory.user) ? { ...memory.user } : {}
+    const legacyTitle = String(user.title || '').trim()
+    if (legacyTitle && !String(agent.profile?.title || '').trim()) {
+      agent.profile = { ...(isPlainObject(agent.profile) ? agent.profile : {}), title: legacyTitle }
+    }
+    delete user.title
+    if (Object.keys(user).length) memory.user = user
+    else delete memory.user
+    if (hasOwn(memory, 'enabled')) {
+      const explicitRecap = isPlainObject(agent.recap) && hasOwn(agent.recap, 'enabled')
+      if (!explicitRecap) {
+        agent.recap = { ...(isPlainObject(agent.recap) ? agent.recap : {}), enabled: memory.enabled !== false }
+      }
+      delete memory.enabled
+    }
+    if (Object.keys(memory).length) next.memory = memory
+    else delete next.memory
+  }
+
+  if (isPlainObject(next.channels)) {
+    next.channels = canonicalizeStoredChannelsConfig(next.channels)
+  }
+  // Both sections are retired. `search` had only a fixed timeout that the
+  // runtime now owns, while `capabilities.homeAccess` never had a live path
+  // consumer or settings writer. Do not keep inert user-facing config.
+  delete next.search
+  delete next.capabilities
+  if (hadAgent || Object.keys(agent).length) next.agent = agent
+  return next
+}
+
 export function stripGeneratedMarker(data) {
   if (!isPlainObject(data) || !Object.prototype.hasOwnProperty.call(data, GENERATED_KEY)) return data
   const { [GENERATED_KEY]: _generated, ...rest } = data
@@ -188,7 +289,7 @@ function writeJsonFile(path, data) {
 
 function readAll() {
   const parsed = readJsonFile(CONFIG_PATH)
-  if (parsed != null) return parsed
+  if (parsed != null) return canonicalizeUnifiedConfig(parsed)
   // Symmetric with readAllForRmW(): a missing/unreadable config on a data
   // dir that was previously initialized means the file was LOST (deleted,
   // failed write), not a fresh install. Self-heal from the newest
@@ -202,7 +303,7 @@ function readAll() {
     const restored = loadLatestMixdogConfigFromBackup(DATA_DIR)
     if (restored && isPlainObject(restored)) {
       process.stderr.write('[config] read: restored mixdog-config.json from latest user-data backup (missing after init)\n')
-      return restored
+      return canonicalizeUnifiedConfig(restored)
     }
   }
   return {}
@@ -259,7 +360,7 @@ function readAllForRmW() {
 }
 
 function writeAll(data) {
-  writeJsonFile(CONFIG_PATH, data)
+  writeJsonFile(CONFIG_PATH, canonicalizeUnifiedConfig(data))
 }
 
 // Serialize a read-modify-write under the same file lock. Concurrent
@@ -268,10 +369,13 @@ function writeAll(data) {
 // silently clobber the earlier section update. Holding the lock across
 // read+modify+write keeps RMW linearizable.
 function withConfigLock(fn) {
-  // secret:true clamps the lock file (which sits beside the API-key
-  // config in a possibly shared home dir) to an owner-only ACL on win32,
-  // fail-closed. POSIX is unaffected.
-  return withFileLockSync(`${CONFIG_PATH}.lock`, fn, { secret: true })
+  // The lock file itself carries no secret — only `<pid> <ts> <token>`, an
+  // integrity marker. Clamping IT owner-only meant two synchronous icacls
+  // spawns (plus whoami) INSIDE the critical section on every config write:
+  // hundreds of ms with the daemon's event loop parked and every other writer
+  // queued behind it. The CONFIG file keeps secret:true, which is where the
+  // API keys actually live.
+  return withFileLockSync(`${CONFIG_PATH}.lock`, fn)
 }
 
 export function readSection(section) {
@@ -288,7 +392,7 @@ export function updateConfig(updater) {
     const current = stripGeneratedMarker(readAllForRmW()) || {}
     const next = typeof updater === 'function' ? updater({ ...current }) : updater
     if (!isPlainObject(next)) throw new Error('[config] updateConfig updater must return an object')
-    saved = stripGeneratedMarker(next) || {}
+    saved = canonicalizeUnifiedConfig(stripGeneratedMarker(next) || {})
     writeAll(saved)
   })
   return saved
@@ -335,13 +439,13 @@ async function writeJsonFileAsync(path, data) {
 }
 
 async function writeAllAsync(data) {
-  await writeJsonFileAsync(CONFIG_PATH, data)
+  await writeJsonFileAsync(CONFIG_PATH, canonicalizeUnifiedConfig(data))
 }
 
-// secret:true clamps the shared-home lock file owner-only on win32 via the
-// ASYNC icacls variant inside withFileLock (fail-closed, non-blocking).
 function withConfigLockAsync(fn) {
-  return withFileLock(`${CONFIG_PATH}.lock`, fn, { secret: true })
+  // Same reasoning as withConfigLock: the ACL belongs on the config file, not
+  // on its lock marker, and icacls has no business inside the lock.
+  return withFileLock(`${CONFIG_PATH}.lock`, fn)
 }
 
 // Process-wide registry at the lock-owning layer: every public async RMW path
@@ -376,7 +480,7 @@ export function updateConfigAsync(updater) {
       const current = stripGeneratedMarker(readAllForRmW()) || {}
       const next = typeof updater === 'function' ? updater({ ...current }) : updater
       if (!isPlainObject(next)) throw new Error('[config] updateConfigAsync updater must return an object')
-      saved = stripGeneratedMarker(next) || {}
+      saved = canonicalizeUnifiedConfig(stripGeneratedMarker(next) || {})
       await writeAllAsync(saved)
     })
     return saved
@@ -400,37 +504,6 @@ export function updateSectionAsync(section, updater) {
   }))
 }
 
-// ── Capabilities (B2 central path policy) ───────────────────────────
-// Top-level `capabilities` section in mixdog-config.json. Safe defaults
-// win on missing/malformed input — every cap is OFF unless explicitly
-// enabled. Settings round-trip through the setup UI; the in-process
-// path gate reads them via `getCapabilities()`.
-//
-// homeAccess: when true, file tools may write anywhere under $HOME. When
-// false (default), file tools are cwd-scoped — matches the setup UI's
-// out-of-the-box "OFF" toggle so a fresh install is restrictive until the
-// user explicitly opts in. This ONLY controls the main-agent path gate —
-// agent role Edit/Write to HOME paths always go through Discord approval
-// regardless (enforced in hooks/pre-tool-subagent.cjs).
-const CAPABILITY_DEFAULTS = Object.freeze({ homeAccess: false })
-
-function readCapabilities() {
-  const raw = readAll().capabilities
-  const out = { ...CAPABILITY_DEFAULTS }
-  if (raw && typeof raw === 'object') {
-    if (raw.homeAccess === true) out.homeAccess = true
-    else if (raw.homeAccess === false) out.homeAccess = false
-  }
-  return out
-}
-
-// Convenience alias requested by B2 call-site plumbing. Returns the
-// same object shape as readCapabilities(); callers that only need a
-// boolean can read `.homeAccess` directly.
-function getCapabilities() {
-  return readCapabilities()
-}
-
 // ── Secret account names ─────────────────────────────────────────────────────
 // Canonical account strings stored in the OS keychain. Must stay in sync with
 // the migration logic in seed.mjs.
@@ -519,9 +592,9 @@ export function saveSecret(account, value) {
   try {
     _setSecret(account, value)
   } catch (err) {
-    // On WSL/headless Linux (and any host missing a usable keychain backend,
+    // On WSL/headless Linux (and any host missing a usable keychain provider,
     // e.g. keytar/libsecret not installed or no running Secret Service) the OS
-    // write throws a cryptic backend error. Surface an actionable message that
+    // write throws a cryptic provider error. Surface an actionable message that
     // points at the env-var read path the getters already honor, instead of
     // silently writing the plaintext secret to mixdog-config.json.
     const envKey = _envKey(account)
@@ -530,7 +603,7 @@ export function saveSecret(account, value) {
     const envHint = stdEnv ? `${stdEnv} (or ${envKey})` : envKey
     const e = new Error(
       `[config] could not save secret to the OS keychain: ${err && err.message ? err.message : err}\n` +
-      `  No usable keychain backend on this host (common on WSL / headless Linux without libsecret).\n` +
+      `  No usable keychain provider on this host (common on WSL / headless Linux without libsecret).\n` +
       `  Set the ${envHint} environment variable instead — the runtime reads it directly.`
     )
     e.cause = err

package/src/runtime/shared/llm/index.mjs

@@ -6,7 +6,7 @@
  * (`makeAgentDispatch({ taskType })`) and, for memory maintenance specifically,
  * through `maintenance-llm.mjs`'s thin wrapper.
  *
- * Only preset resolution remains here: memory-cycle and future backend
+ * Only preset resolution remains here: memory-cycle and future provider
  * callers still need a consistent way to map `(task, agent-config)` to a
  * preset id.
  */

package/src/runtime/shared/owner-fair-gate.mjs

@@ -0,0 +1,134 @@
+import { createFairCallScheduler } from '../../standalone/fair-call-scheduler.mjs';
+import { currentToolExecutionOwner } from './tool-execution-owner.mjs';
+
+function positiveInt(value, fallback) {
+  const parsed = Math.floor(Number(value));
+  return Number.isFinite(parsed) && parsed >= 1 ? parsed : fallback;
+}
+
+function waitTimeoutError(name, waitTimeoutMs) {
+  const error = new Error(`${name} admission wait exceeded ${waitTimeoutMs}ms; retry after running work completes`);
+  error.code = 'EADMISSIONWAITTIMEOUT';
+  error.statusCode = 503;
+  error.waitTimeoutMs = waitTimeoutMs;
+  return error;
+}
+
+/**
+ * Owner-fair bounded work gate. The underlying scheduler lets a lone owner
+ * borrow all capacity, then rotates contending session owners and rebalances a
+ * full borrowed queue so a late interactive session is not trapped behind one
+ * session's entire fan-out.
+ */
+export function createOwnerFairGate({
+  name = 'work',
+  activeMax = 8,
+  queueMax = 1024,
+  minOwnerQueue = 8,
+  waitTimeoutMs = 30_000,
+  schedule = setImmediate,
+  now = Date.now,
+} = {}) {
+  const defaultWaitTimeoutMs = Math.max(0, Math.floor(Number(waitTimeoutMs) || 0));
+  const scheduler = createFairCallScheduler({
+    name,
+    activeMax,
+    queueMax,
+    minOwnerQueue,
+    dispatchBurst: Math.max(1, Math.min(8, positiveInt(activeMax, 8))),
+    schedule,
+    now,
+  });
+  const stats = {
+    admitted: 0,
+    rejected: 0,
+    timedOut: 0,
+    totalWaitMs: 0,
+    maxWaitMs: 0,
+  };
+
+  function run(ownerKey, task, {
+    signal = null,
+    weight = 1,
+    waitTimeoutMs: callWaitTimeoutMs = defaultWaitTimeoutMs,
+    onAdmit = null,
+  } = {}) {
+    if (typeof task !== 'function') return Promise.reject(new TypeError(`${name} task must be a function`));
+    const owner = String(ownerKey || currentToolExecutionOwner() || 'anonymous').trim().slice(0, 240) || 'anonymous';
+    const queuedAt = now();
+    const timeoutMs = Math.max(0, Math.floor(Number(callWaitTimeoutMs) || 0));
+    const controller = (signal || timeoutMs > 0) ? new AbortController() : null;
+    let timer = null;
+    let started = false;
+    let timeoutError = null;
+    let onAbort = null;
+
+    const cleanupQueueWait = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      if (onAbort && signal) {
+        try { signal.removeEventListener('abort', onAbort); } catch {}
+        onAbort = null;
+      }
+    };
+
+    if (controller && signal) {
+      onAbort = () => {
+        if (!controller.signal.aborted) controller.abort(signal.reason);
+      };
+      if (signal.aborted) onAbort();
+      else signal.addEventListener('abort', onAbort, { once: true });
+    }
+    if (controller && timeoutMs > 0 && !controller.signal.aborted) {
+      timer = setTimeout(() => {
+        if (started || controller.signal.aborted) return;
+        timeoutError = waitTimeoutError(name, timeoutMs);
+        controller.abort(timeoutError);
+      }, timeoutMs);
+    }
+
+    const promise = scheduler.enqueue(owner, async () => {
+      started = true;
+      cleanupQueueWait();
+      const waitedMs = Math.max(0, now() - queuedAt);
+      stats.admitted += 1;
+      stats.totalWaitMs += waitedMs;
+      stats.maxWaitMs = Math.max(stats.maxWaitMs, waitedMs);
+      try { onAdmit?.(waitedMs); } catch {}
+      return task();
+    }, {
+      weight,
+      signal: controller?.signal || signal,
+    });
+
+    return promise.catch((error) => {
+      if (!started) {
+        stats.rejected += 1;
+        if (timeoutError && error === timeoutError) stats.timedOut += 1;
+      }
+      throw error;
+    }).finally(cleanupQueueWait);
+  }
+
+  function snapshot() {
+    const base = scheduler.snapshot();
+    return {
+      ...base,
+      admitted: stats.admitted,
+      rejected: stats.rejected,
+      timedOut: stats.timedOut,
+      averageWaitMs: stats.admitted > 0 ? Math.round(stats.totalWaitMs / stats.admitted) : 0,
+      maxWaitMs: stats.maxWaitMs,
+    };
+  }
+
+  return {
+    run,
+    close: (reason) => scheduler.close(reason),
+    snapshot,
+    get active() { return scheduler.active; },
+    get queued() { return scheduler.queued; },
+  };
+}