mixdog 0.9.95 → 0.9.97

package/src/runtime/shared/agent-route-config.mjs

@@ -0,0 +1,119 @@
+const LEGACY_AGENT_ROUTE_SLOTS = Object.freeze({
+  explore: Object.freeze({ workflow: 'explorer', maintenance: 'explore' }),
+  maintainer: Object.freeze({ alias: 'maintenance', workflow: 'memory', maintenance: 'memory' }),
+  worker: Object.freeze({ workflow: 'agent' }),
+});
+
+const REDUNDANT_WORKFLOW_PRESET_IDS = new Set([
+  'workflow-agent',
+  'workflow-explorer',
+  'workflow-memory',
+]);
+
+function record(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+export function isCompleteAgentRoute(value) {
+  return !!value
+    && typeof value === 'object'
+    && !Array.isArray(value)
+    && !!String(value.provider || '').trim()
+    && !!String(value.model || '').trim();
+}
+
+function generatedPresetAgentId(preset) {
+  const id = String(preset?.id || '').trim().toLowerCase();
+  if (id === 'workflow-agent') return 'worker';
+  if (id === 'workflow-explorer') return 'explore';
+  if (id === 'workflow-memory') return 'maintainer';
+  if (!id.startsWith('workflow-agent-')) return '';
+  const suffix = id.slice('workflow-agent-'.length);
+  if (suffix === 'explorer' || suffix === 'explore') return 'explore';
+  if (suffix === 'maintenance' || suffix === 'memory' || suffix === 'maintainer') return 'maintainer';
+  return suffix;
+}
+
+function routeFromGeneratedPreset(preset) {
+  const provider = String(preset?.provider || '').trim();
+  const model = String(preset?.model || '').trim();
+  if (!provider || !model) return null;
+  const route = { provider, model };
+  const effort = String(preset?.effort || '').trim();
+  if (effort) route.effort = effort;
+  if (preset?.fast === true) route.fast = true;
+  return route;
+}
+
+export function configuredAgentRouteCandidates(config, agentId) {
+  const id = String(agentId || '').trim();
+  if (!id) return [];
+  const agents = record(config?.agents);
+  const legacy = LEGACY_AGENT_ROUTE_SLOTS[id] || null;
+  const candidates = [agents[id]];
+  if (legacy?.alias) candidates.push(agents[legacy.alias]);
+  if (legacy?.workflow) candidates.push(record(config?.workflowRoutes)[legacy.workflow]);
+  if (legacy?.maintenance) candidates.push(record(config?.maintenance)[legacy.maintenance]);
+  return candidates.filter(Boolean);
+}
+
+export function canonicalizeAgentRoutes(config = {}) {
+  const sourceAgents = record(config.agents);
+  const agents = Object.fromEntries(
+    Object.entries(sourceAgents).filter(([, route]) => isCompleteAgentRoute(route)),
+  );
+  for (const id of Object.keys(LEGACY_AGENT_ROUTE_SLOTS)) {
+    if (agents[id]) continue;
+    const candidate = configuredAgentRouteCandidates({ ...config, agents: sourceAgents }, id)
+      .find((route) => isCompleteAgentRoute(route));
+    if (candidate) agents[id] = candidate;
+  }
+  delete agents.maintenance;
+  // Older settings saves generated one preset per fixed/custom agent. Promote
+  // a preset only when no higher-priority canonical/legacy route exists, then
+  // the redundant preset can be removed without discarding user assignments.
+  for (const preset of Array.isArray(config?.presets) ? config.presets : []) {
+    const id = generatedPresetAgentId(preset);
+    if (!id || agents[id]) continue;
+    const route = routeFromGeneratedPreset(preset);
+    if (route) agents[id] = route;
+  }
+  return agents;
+}
+
+export function isRedundantGeneratedRoutePreset(preset, defaultPreset = null) {
+  const id = String(preset?.id || '').trim();
+  if (!id || id === String(defaultPreset || '').trim()) return false;
+  return REDUNDANT_WORKFLOW_PRESET_IDS.has(id) || id.startsWith('workflow-agent-');
+}
+
+export function canonicalizeAgentRouteStorage(config = {}) {
+  const {
+    workflowRoutes: _legacyWorkflowRoutes,
+    ...rest
+  } = config || {};
+  const maintenance = { ...record(config?.maintenance) };
+  delete maintenance.explore;
+  delete maintenance.memory;
+  const presets = Array.isArray(config?.presets)
+    ? config.presets.filter((preset) => !isRedundantGeneratedRoutePreset(preset, config?.default))
+    : [];
+  return {
+    ...rest,
+    agents: canonicalizeAgentRoutes(config),
+    maintenance,
+    presets,
+  };
+}
+
+export function agentRouteStorageNeedsMigration(config = {}) {
+  const agents = record(config?.agents);
+  const maintenance = record(config?.maintenance);
+  return Object.prototype.hasOwnProperty.call(config || {}, 'workflowRoutes')
+    || Object.prototype.hasOwnProperty.call(agents, 'maintenance')
+    || Object.prototype.hasOwnProperty.call(maintenance, 'explore')
+    || Object.prototype.hasOwnProperty.call(maintenance, 'memory')
+    || Object.values(agents).some((route) => !isCompleteAgentRoute(route))
+    || (Array.isArray(config?.presets)
+      && config.presets.some((preset) => isRedundantGeneratedRoutePreset(preset, config?.default)));
+}

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

@@ -28,6 +28,55 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 
 const _execFileAsync = promisify(execFile);
 
+// Async atomic writes from many daemon sessions share one disk. Keep enough
+// parallelism for SSD throughput, then use additive-increase/multiplicative-
+// decrease when latency shows the filesystem is saturated. This gate never
+// touches synchronous compatibility paths and never revokes in-flight writes.
+const _ioCeiling = Math.max(1, Math.floor(Number(process.env.MIXDOG_FILE_IO_MAX_CONCURRENCY) || 16));
+let _ioLimit = Math.min(4, _ioCeiling);
+let _ioActive = 0;
+let _ioFastStreak = 0;
+const _ioQueue = [];
+
+function _drainAdaptiveFileIo() {
+  while (_ioActive < _ioLimit && _ioQueue.length > 0) {
+    const item = _ioQueue.shift();
+    _ioActive += 1;
+    const startedAt = Date.now();
+    Promise.resolve()
+      .then(item.run)
+      .then(item.resolve, item.reject)
+      .finally(() => {
+        const elapsed = Date.now() - startedAt;
+        _ioActive = Math.max(0, _ioActive - 1);
+        if (elapsed >= 250) {
+          _ioLimit = Math.max(1, Math.ceil(_ioLimit / 2));
+          _ioFastStreak = 0;
+        } else if (elapsed <= 40 && _ioLimit < _ioCeiling) {
+          _ioFastStreak += 1;
+          if (_ioFastStreak >= _ioLimit * 4) {
+            _ioLimit += 1;
+            _ioFastStreak = 0;
+          }
+        } else {
+          _ioFastStreak = 0;
+        }
+        _drainAdaptiveFileIo();
+      });
+  }
+}
+
+function _runAdaptiveFileIo(run) {
+  return new Promise((resolve, reject) => {
+    _ioQueue.push({ run, resolve, reject });
+    _drainAdaptiveFileIo();
+  });
+}
+
+export function adaptiveFileIoSnapshot() {
+  return { active: _ioActive, queued: _ioQueue.length, limit: _ioLimit, ceiling: _ioCeiling };
+}
+
 const RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY', 'EEXIST']);
 const LOCK_WAIT_CODES = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY']);
 const DEFAULT_BACKOFFS_MS = Object.freeze([25, 50, 100, 200, 400, 800, 1200, 1600]);
@@ -79,6 +128,28 @@ function _describeLockHolder(lockPath) {
   }
 }
 
+// Lock-wait watchdog. A cross-process file lock is invisible in a profile: the
+// only symptom is "everything stopped". One bounded line per path names the
+// path and the wait, so the next stall is diagnosed from the log instead of a
+// live repro.
+const LOCK_WAIT_WARN_MS = 500;
+const LOCK_WAIT_WARN_INTERVAL_MS = 10_000;
+const _lockWaitWarnedAt = new Map();
+function _reportLockWait(lockPath, waitedMs, mode) {
+  if (waitedMs < LOCK_WAIT_WARN_MS) return;
+  const now = Date.now();
+  if (now - (_lockWaitWarnedAt.get(lockPath) || 0) < LOCK_WAIT_WARN_INTERVAL_MS) return;
+  _lockWaitWarnedAt.set(lockPath, now);
+  if (_lockWaitWarnedAt.size > 64) {
+    for (const [path, at] of _lockWaitWarnedAt) {
+      if (now - at >= LOCK_WAIT_WARN_INTERVAL_MS * 6) _lockWaitWarnedAt.delete(path);
+    }
+  }
+  try {
+    process.stderr.write(`[atomic-file] ${mode} lock wait ${waitedMs}ms: ${lockPath}\n`);
+  } catch { /* diagnostics only */ }
+}
+
 export function renameWithRetrySync(src, dst, opts = {}) {
   const backoffs = Array.isArray(opts.backoffs) && opts.backoffs.length > 0
     ? opts.backoffs
@@ -129,6 +200,7 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
   }
   const deadline = Date.now() + timeoutMs;
   mkdirSync(dirname(lockPath), { recursive: true });
+  const waitStartedAt = Date.now();
   let attempt = 0;
   let lastErr = null;
   while (true) {
@@ -168,6 +240,7 @@ export function withFileLockSync(lockPath, fn, opts = {}) {
     // `<pid> <ts> <token>` is a superset of the old `<pid> <ts>`; a
     // tokenless (old-format) lock is still read as pid-authoritative.
     try { writeFileSync(fd, `${process.pid} ${Date.now()} ${_OWNER_TOKEN}\n`, 'utf8'); } catch {}
+    _reportLockWait(lockPath, Date.now() - waitStartedAt, 'sync');
     // 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.
@@ -362,6 +435,7 @@ async function _withOsFileLock(lockPath, fn, opts = {}) {
   const staleMs = Number.isFinite(opts.staleMs) ? opts.staleMs : 30000;
   const deadline = Date.now() + timeoutMs;
   mkdirSync(dirname(lockPath), { recursive: true });
+  const waitStartedAt = Date.now();
   let attempt = 0;
   let lastErr = null;
   while (true) {
@@ -393,6 +467,7 @@ async function _withOsFileLock(lockPath, fn, opts = {}) {
       continue;
     }
     try { writeFileSync(fd, `${process.pid} ${Date.now()} ${_OWNER_TOKEN}\n`, 'utf8'); } catch {}
+    _reportLockWait(lockPath, Date.now() - waitStartedAt, 'async');
     _osHeldPaths.add(lockPath);
     try {
       // Async ACL enforcement (promisified execFile) so a secret-bearing
@@ -738,10 +813,11 @@ export async function writeFileAtomicAsync(filePath, data, opts = {}) {
       throw err;
     }
   };
-  if (opts.lock === true) {
-    return withFileLock(`${filePath}.lock`, run, opts);
-  }
-  return run();
+  return _runAdaptiveFileIo(() => (
+    opts.lock === true
+      ? withFileLock(`${filePath}.lock`, run, opts)
+      : run()
+  ));
 }
 
 export function writeJsonAtomicAsync(filePath, value, opts = {}) {

package/src/runtime/shared/channel-notification-routing.mjs

@@ -7,8 +7,8 @@ export function channelNotificationModelContent(params = {}) {
 }
 
 export function shouldMirrorChannelNotificationToPending(meta = {}) {
-  // CC parity (reference messageQueueManager.ts): every inbound channel/
-  // schedule notification flows through the single queue — when no live
+  // Every inbound channel/schedule notification flows through the single
+  // queue — when no live
   // listener handled it (engine not subscribed yet, pane disposed, headless),
   // it is mirrored into the session pending queue for the next turn instead
   // of being dropped. Silent-to-agent stays excluded; the upstream content

package/src/runtime/shared/child-guardian.mjs

@@ -1,6 +1,7 @@
 'use strict';
 
 import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { detachedSpawnOpts } from './spawn-flags.mjs';
 
 function positiveInt(value) {
@@ -8,13 +9,6 @@ function positiveInt(value) {
   return Number.isInteger(n) && n > 0 ? n : null;
 }
 
-const DEFAULT_MIN_FREE_MEMORY_MB = 1024;
-
-export function childGuardianMemoryFloorMb(env = process.env) {
-  const n = Math.floor(Number(env.MIXDOG_MIN_FREE_MEMORY_MB));
-  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_MIN_FREE_MEMORY_MB;
-}
-
 export function childGuardianSpawnEnv(env = process.env) {
   return {
     PATH: env.PATH || '',
@@ -29,40 +23,25 @@ export function childGuardianSpawnEnv(env = process.env) {
   };
 }
 
-function guardianScript({
-  parentPid,
-  childPid,
-  childGroupPid,
-  platform,
-  pollMs,
-  orphanGraceMs,
-  forceGraceMs,
-  minFreeMemoryMb,
-  receiptPath,
-}) {
+function guardianBrokerScript() {
   return `
 const { spawnSync } = require('node:child_process');
-const { freemem } = require('node:os');
-const parentPid = ${JSON.stringify(parentPid)};
-const childPid = ${JSON.stringify(childPid)};
-const childGroupPid = ${JSON.stringify(childGroupPid || childPid)};
-const platform = ${JSON.stringify(platform)};
-const pollMs = ${JSON.stringify(pollMs)};
-const orphanGraceMs = ${JSON.stringify(orphanGraceMs)};
-const forceGraceMs = ${JSON.stringify(forceGraceMs)};
-const minFreeMemoryBytes = ${JSON.stringify(minFreeMemoryMb * 1024 * 1024)};
-const receiptPath = ${JSON.stringify(receiptPath || null)};
+const platform = ${JSON.stringify(process.platform)};
+const targets = new Map();
+let input = '';
+let everHadTarget = false;
+let emptySince = 0;
 // Kill receipt: guardian kills are otherwise indistinguishable from a crashed
 // wrapper ("process exited without reporting an exit code"). Written BEFORE
 // the kill so the owner's next status refresh can attribute the death.
-function writeReceipt(reason, extra) {
-  if (!receiptPath) return;
+function writeReceipt(target, reason, extra) {
+  if (!target.receiptPath) return;
   try {
-    require('node:fs').writeFileSync(receiptPath, JSON.stringify({
+    require('node:fs').writeFileSync(target.receiptPath, JSON.stringify({
       reason,
       at: new Date().toISOString(),
       guardianPid: process.pid,
-      childPid,
+      childPid: target.childPid,
       ...extra,
     }));
   } catch {}
@@ -72,57 +51,186 @@ function alive(pid) {
   try { process.kill(pid, 0); return true; }
   catch (error) { return error && error.code === 'EPERM'; }
 }
-function killTarget(force) {
+function killTarget(target, force) {
   if (platform === 'win32') {
     const systemRoot = process.env.SystemRoot || process.env.WINDIR || 'C:\\\\Windows';
     const taskkill = systemRoot + '\\\\System32\\\\taskkill.exe';
     if (force) {
-      try { spawnSync(taskkill, ['/PID', String(childPid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }); } catch {}
+      try { spawnSync(taskkill, ['/PID', String(target.childPid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }); } catch {}
     } else {
-      try { process.kill(childPid, 'SIGTERM'); } catch {}
-      try { spawnSync(taskkill, ['/PID', String(childPid), '/T'], { stdio: 'ignore', windowsHide: true }); } catch {}
+      try { process.kill(target.childPid, 'SIGTERM'); } catch {}
+      try { spawnSync(taskkill, ['/PID', String(target.childPid), '/T'], { stdio: 'ignore', windowsHide: true }); } catch {}
     }
     return;
   }
   const signal = force ? 'SIGKILL' : 'SIGTERM';
-  try { process.kill(-childGroupPid, signal); return; } catch {}
-  try { process.kill(childPid, signal); } catch {}
+  try { process.kill(-target.childGroupPid, signal); return; } catch {}
+  try { process.kill(target.childPid, signal); } catch {}
+}
+function accept(message) {
+  if (!message || typeof message !== 'object') return;
+  const id = String(message.id || '');
+  if (!id) return;
+  if (message.type === 'remove') {
+    targets.delete(id);
+    return;
+  }
+  if (message.type !== 'add') return;
+  const childPid = Number(message.childPid);
+  const parentPid = Number(message.parentPid);
+  if (!Number.isInteger(childPid) || childPid <= 0
+    || !Number.isInteger(parentPid) || parentPid <= 0) return;
+  targets.set(id, {
+    id,
+    parentPid,
+    childPid,
+    childGroupPid: Number(message.childGroupPid) || childPid,
+    pollMs: Math.max(100, Number(message.pollMs) || 750),
+    orphanGraceMs: Math.max(100, Number(message.orphanGraceMs) || 3000),
+    forceGraceMs: Math.max(100, Number(message.forceGraceMs) || 3000),
+    receiptPath: typeof message.receiptPath === 'string' ? message.receiptPath : null,
+    orphanedAt: 0,
+    lastPolledAt: 0,
+    killing: false,
+  });
+  everHadTarget = true;
+  emptySince = 0;
 }
-let killing = false;
-let orphanedAt = 0;
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+  let newline;
+  while ((newline = input.indexOf('\\n')) >= 0) {
+    const line = input.slice(0, newline);
+    input = input.slice(newline + 1);
+    try { accept(JSON.parse(line)); } catch {}
+  }
+});
 const timer = setInterval(() => {
-  if (!alive(childPid)) process.exit(0);
-  // Admission protects only NEW work. A running shell can still consume the
-  // host after it starts, so reclaim its entire tree before it starves the
-  // owning Mixdog process. Force is intentional: at the memory floor there is
-  // no safe grace window for a runaway allocator.
-  if (!killing && minFreeMemoryBytes > 0) {
-    let freeBytes = Number.POSITIVE_INFINITY;
-    try { freeBytes = Number(freemem()); } catch {}
-    if (Number.isFinite(freeBytes) && freeBytes < minFreeMemoryBytes) {
-      killing = true;
-      writeReceipt('host-memory-floor', { freeBytes, minFreeMemoryBytes });
-      killTarget(true);
-      process.exit(0);
+  const now = Date.now();
+  for (const [id, target] of targets) {
+    if (now - target.lastPolledAt < target.pollMs) continue;
+    target.lastPolledAt = now;
+    if (!alive(target.childPid)) {
+      targets.delete(id);
+      continue;
+    }
+    if (alive(target.parentPid)) {
+      target.orphanedAt = 0;
+      continue;
     }
+    if (!target.orphanedAt) target.orphanedAt = now;
+    if (target.killing || now - target.orphanedAt < target.orphanGraceMs) continue;
+    target.killing = true;
+    writeReceipt(target, 'parent-exit', {});
+    killTarget(target, false);
+    setTimeout(() => {
+      if (alive(target.childPid)) killTarget(target, true);
+      targets.delete(id);
+    }, target.forceGraceMs).unref?.();
   }
-  // Orphaned when the parent PID dies. Matches mainstream CLIs: no console
-  // probe — a hidden shell spawn (windowsHide) plus tree-kill on cleanup, so
-  // orphan detection is pure parent-liveness.
-  if (alive(parentPid)) {
-    orphanedAt = 0;
-    return;
+  // Pay for one Node supervisor only while it owns at least one live child.
+  // A short empty grace absorbs command-to-command reuse without keeping the
+  // broker resident for the whole daemon lifetime.
+  if (targets.size > 0) emptySince = 0;
+  else if (everHadTarget) {
+    if (!emptySince) emptySince = now;
+    else if (now - emptySince >= 1000) process.exit(0);
   }
-  if (!orphanedAt) orphanedAt = Date.now();
-  if (killing || Date.now() - orphanedAt < orphanGraceMs) return;
-  killing = true;
-  writeReceipt('parent-exit', {});
-  killTarget(false);
-  setTimeout(() => { if (alive(childPid)) killTarget(true); process.exit(0); }, forceGraceMs).unref?.();
-}, pollMs);
+}, 100);
 `;
 }
 
+let sharedBroker = null;
+let brokerRestartTimer = null;
+let brokerTargetSweepTimer = null;
+const brokerTargets = new Map();
+
+function sendBrokerMessage(message) {
+  try {
+    if (!sharedBroker?.stdin?.writable) return false;
+    sharedBroker.stdin.write(`${JSON.stringify(message)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function targetPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function stopBrokerTargetSweepIfIdle() {
+  if (brokerTargets.size > 0 || !brokerTargetSweepTimer) return;
+  clearInterval(brokerTargetSweepTimer);
+  brokerTargetSweepTimer = null;
+}
+
+function removeBrokerTarget(id, { notify = true } = {}) {
+  const target = brokerTargets.get(id);
+  if (!target) return false;
+  brokerTargets.delete(id);
+  try { target.onRemoved?.(); } catch {}
+  if (notify) sendBrokerMessage({ type: 'remove', id });
+  stopBrokerTargetSweepIfIdle();
+  return true;
+}
+
+function ensureBrokerTargetSweep() {
+  if (brokerTargetSweepTimer) return;
+  brokerTargetSweepTimer = setInterval(() => {
+    for (const [id, target] of brokerTargets) {
+      if (!targetPidAlive(target.childPid)) removeBrokerTarget(id);
+    }
+    stopBrokerTargetSweepIfIdle();
+  }, 250);
+  brokerTargetSweepTimer.unref?.();
+}
+
+function ensureSharedBroker() {
+  if (sharedBroker && sharedBroker.exitCode == null && sharedBroker.signalCode == null) {
+    return sharedBroker;
+  }
+  try {
+    const broker = spawn(process.execPath, [
+      '--no-warnings',
+      '--eval',
+      guardianBrokerScript(),
+    ], {
+      stdio: ['pipe', 'ignore', 'ignore'],
+      env: childGuardianSpawnEnv(),
+      ...detachedSpawnOpts,
+    });
+    sharedBroker = broker;
+    broker.unref?.();
+    broker.stdin?.unref?.();
+    broker.stdin?.on?.('error', () => {});
+    broker.once('exit', () => {
+      if (sharedBroker !== broker) return;
+      sharedBroker = null;
+      if (brokerTargets.size > 0 && !brokerRestartTimer) {
+        brokerRestartTimer = setTimeout(() => {
+          brokerRestartTimer = null;
+          const replacement = ensureSharedBroker();
+          if (!replacement) return;
+          for (const target of brokerTargets.values()) sendBrokerMessage(target);
+        }, 100);
+        brokerRestartTimer.unref?.();
+      }
+    });
+    for (const target of brokerTargets.values()) sendBrokerMessage(target);
+    return broker;
+  } catch {
+    sharedBroker = null;
+    return null;
+  }
+}
+
 export function startChildGuardian({
   parentPid = process.pid,
   childPid,
@@ -132,53 +240,41 @@ export function startChildGuardian({
   graceMs = 3000,
   orphanGraceMs = graceMs,
   forceGraceMs = graceMs,
-  protectHostMemory = false,
-  minFreeMemoryMb = protectHostMemory ? childGuardianMemoryFloorMb() : 0,
   receiptPath = null,
 } = {}) {
   const parent = positiveInt(parentPid);
   const child = positiveInt(childPid);
   if (!parent || !child || parent === child) return null;
-  const memoryFloorMb = Math.max(0, Math.floor(Number(minFreeMemoryMb) || 0));
-
-  try {
-    const guardian = spawn(process.execPath, [
-      '--no-warnings',
-      '--eval',
-      guardianScript({
-        parentPid: parent,
-        childPid: child,
-        childGroupPid: positiveInt(childGroupPid) || child,
-        platform: process.platform,
-        pollMs: Math.max(100, Math.floor(Number(pollMs) || 750)),
-        orphanGraceMs: Math.max(100, Math.floor(Number(orphanGraceMs) || Number(graceMs) || 3000)),
-        forceGraceMs: Math.max(100, Math.floor(Number(forceGraceMs) || Number(graceMs) || 3000)),
-        minFreeMemoryMb: memoryFloorMb,
-        receiptPath: typeof receiptPath === 'string' && receiptPath ? receiptPath : null,
-      }),
-    ], {
-      stdio: 'ignore',
-      env: childGuardianSpawnEnv(),
-      ...detachedSpawnOpts,
-    });
-    guardian.unref?.();
-    let stopped = false;
-    return {
-      pid: guardian.pid || null,
-      label,
-      childPid: child,
-      stop() {
-        if (stopped) return false;
-        stopped = true;
-        try {
-          guardian.kill();
-          return true;
-        } catch {
-          return false;
-        }
-      },
-    };
-  } catch {
+  const id = randomUUID();
+  let stopped = false;
+  const target = {
+    type: 'add',
+    id,
+    parentPid: parent,
+    childPid: child,
+    childGroupPid: positiveInt(childGroupPid) || child,
+    pollMs: Math.max(100, Math.floor(Number(pollMs) || 750)),
+    orphanGraceMs: Math.max(100, Math.floor(Number(orphanGraceMs) || Number(graceMs) || 3000)),
+    forceGraceMs: Math.max(100, Math.floor(Number(forceGraceMs) || Number(graceMs) || 3000)),
+    receiptPath: typeof receiptPath === 'string' && receiptPath ? receiptPath : null,
+    onRemoved: () => { stopped = true; },
+  };
+  brokerTargets.set(id, target);
+  ensureBrokerTargetSweep();
+  const broker = ensureSharedBroker();
+  if (!broker) {
+    removeBrokerTarget(id, { notify: false });
     return null;
   }
+  sendBrokerMessage(target);
+  return {
+    pid: broker.pid || null,
+    label,
+    childPid: child,
+    stop() {
+      if (stopped) return false;
+      stopped = true;
+      return removeBrokerTarget(id);
+    },
+  };
 }