mixdog 0.7.17 → 0.8.0

package/src/runtime/shared/launcher-control.mjs

@@ -0,0 +1,259 @@
+// Cross-platform managed-launcher control channel.
+//
+// Replaces the Windows-only AttachConsole + WriteConsoleInputW front-injection
+// path. A `mixdog`-launched session can be "managed": the launcher
+// (setup/mixdog.mjs) owns the child process and exposes a file-based
+// command queue under the runtime root. Internal commands (/clear,
+// /reload-plugins) are enqueued by the MCP server (inject_command / inject_input)
+// and the launcher delivers them to the child's stdin — no terminal keystroke
+// injection, no new window. Works on Windows / macOS / Linux.
+//
+// Native backend (CANONICAL): Rust is canonical for mixdog's native
+// functionality. The enqueue/drain primitives and the managed terminal bridge
+// are owned by the Rust crate native/mixdog-launch. The pure-JS queue path below
+// is only a wire-compatible fallback for queue writes/drains when the binary has
+// not landed; managed terminal ownership never falls back to JS/node-pty.
+//
+// Wire-up:
+//   • The launcher sets MIXDOG_LAUNCH_ID (and MIXDOG_MANAGED_LAUNCH=1) on the
+//     child env ONLY when it has actually engaged the stdin control bridge.
+//   • The MCP server (a descendant of the child) inherits that env, so
+//     managedLaunchId() is the single source of truth for "am I managed?".
+//   • enqueueLauncherCommand() publishes one command file atomically; the
+//     launcher's watchLauncherCommands() drains + delivers them in order.
+
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  renameSync,
+  existsSync,
+  statSync,
+} from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+
+const ENV_LAUNCH_ID = 'MIXDOG_LAUNCH_ID';
+const ENV_MANAGED = 'MIXDOG_MANAGED_LAUNCH';
+
+// 0x1E (ASCII Record Separator): how `mixdog-launch drain` joins multiple
+// command bodies on stdout so embedded newlines in a command survive transport.
+const RECORD_SEP = '\x1e';
+
+// Names the env vars the launcher must set on the child so this module's
+// managedLaunchId() resolves inside the MCP server.
+export const LAUNCHER_ENV = Object.freeze({ ENV_LAUNCH_ID, ENV_MANAGED });
+
+// Mirror of channels/lib/runtime-paths.mjs RUNTIME_ROOT resolution so the
+// launcher and the MCP server agree on the queue location without importing
+// the channels layer into setup/.
+export function launcherRuntimeRoot() {
+  return process.env.MIXDOG_RUNTIME_ROOT
+    ? resolve(process.env.MIXDOG_RUNTIME_ROOT)
+    : join(tmpdir(), 'mixdog');
+}
+
+function sanitize(value) {
+  return String(value).replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+export function launcherQueueDir(launchId) {
+  return join(launcherRuntimeRoot(), `launch-cmds-${sanitize(launchId)}`);
+}
+
+// ── Native backend resolution (canonical) ──────────────────────────────────
+// Locate the Rust mixdog-launch binary built by dev-sync / cargo. Resolution
+// order: explicit override → fresh live build → local cargo release build →
+// shipped prebuilt.
+// Returns an absolute path when present, else null (JS fallback engages).
+const PLUGIN_ROOT = process.env.MIXDOG_ROOT
+  || resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const NATIVE_LAUNCH_DEFAULT_BIN = join(
+  PLUGIN_ROOT,
+  'native/mixdog-launch/target/release',
+  process.platform === 'win32' ? 'mixdog-launch.exe' : 'mixdog-launch',
+);
+const NATIVE_LAUNCH_LIVE_BIN = join(
+  PLUGIN_ROOT,
+  'native/mixdog-launch/target-live/release',
+  process.platform === 'win32' ? 'mixdog-launch.exe' : 'mixdog-launch',
+);
+
+function nativeLaunchSourceMtime() {
+  let mtime = 0;
+  for (const rel of ['native/mixdog-launch/Cargo.toml', 'native/mixdog-launch/src/main.rs']) {
+    try { mtime = Math.max(mtime, statSync(join(PLUGIN_ROOT, rel)).mtimeMs); } catch {}
+  }
+  return mtime;
+}
+
+function freshNativeLaunchBin(path) {
+  try {
+    const binMtime = statSync(path).mtimeMs;
+    const srcMtime = nativeLaunchSourceMtime();
+    return binMtime > 0 && binMtime >= srcMtime ? path : null;
+  } catch {
+    return null;
+  }
+}
+
+// Shipped prebuilt path under native/prebuilt/<os-arch>/mixdog-launch(.exe)
+function nativeLaunchPrebuiltPath() {
+  const arch =
+    process.arch === 'x64' ? 'x86_64'
+    : process.arch === 'arm64' ? 'aarch64'
+    : process.arch === 'ia32' ? 'i686'
+    : process.arch;
+  const os =
+    process.platform === 'win32' ? 'windows'
+    : process.platform === 'darwin' ? 'macos'
+    : 'linux';
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  return join(PLUGIN_ROOT, 'native', 'prebuilt', `${os}-${arch}`, `mixdog-launch${ext}`);
+}
+
+let _nativeBinCache; // undefined = unresolved, string|null = resolved
+export function nativeLaunchBin() {
+  if (_nativeBinCache !== undefined) return _nativeBinCache;
+  // Opt-out for tests / forced-JS parity checks.
+  if (/^(0|false|no|off|js)$/i.test(String(process.env.MIXDOG_LAUNCH_NATIVE || ''))) {
+    _nativeBinCache = null;
+    return _nativeBinCache;
+  }
+  const override = process.env.MIXDOG_LAUNCH_NATIVE_BIN;
+  if (override && existsSync(override)) { _nativeBinCache = override; return _nativeBinCache; }
+  const live = freshNativeLaunchBin(NATIVE_LAUNCH_LIVE_BIN);
+  if (live) { _nativeBinCache = live; return _nativeBinCache; }
+  const release = freshNativeLaunchBin(NATIVE_LAUNCH_DEFAULT_BIN);
+  if (release) { _nativeBinCache = release; return _nativeBinCache; }
+  // Shipped prebuilt fallback (under native/prebuilt/<os-arch>/)
+  const prebuilt = nativeLaunchPrebuiltPath();
+  if (prebuilt && existsSync(prebuilt)) { _nativeBinCache = prebuilt; return _nativeBinCache; }
+  _nativeBinCache = null;
+  return _nativeBinCache;
+}
+
+// Returns true when the native mixdog-launch binary's `bridge` subcommand is
+// available for this platform (exit 0). The launcher uses this to gate the
+// managed-launch interactive path — no JS stdin pipe bridge fallback.
+export function nativeBridgeAvailable() {
+  const bin = nativeLaunchBin();
+  if (!bin) return false;
+  const r = spawnSync(bin, ['bridge', '--probe'], {
+    encoding: 'utf8', windowsHide: true,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return r.status === 0;
+}
+
+export function newLaunchId() {
+  return `${process.pid}-${randomUUID().slice(0, 8)}`;
+}
+
+// MCP-server side: returns the managed launch id when this process belongs to a
+// `mixdog`-launched session that engaged the control bridge, else null. The
+// launcher only sets MIXDOG_LAUNCH_ID once the bridge is live, so presence is
+// sufficient — there is no half-managed state to disambiguate.
+export function managedLaunchId() {
+  const id = process.env[ENV_LAUNCH_ID];
+  return id && String(id).length > 0 ? String(id) : null;
+}
+
+let enqueueSequence = 0;
+
+// Writer side (inject_command / inject_input): publish one command for the
+// launcher to deliver. Prefers the canonical Rust backend; the JS writer (temp
+// name + rename so the watcher never sees a partial file) is the fallback.
+// Returns the published path.
+export function enqueueLauncherCommand(launchId, command) {
+  const dir = launcherQueueDir(launchId);
+  mkdirSync(dir, { recursive: true });
+  const bin = nativeLaunchBin();
+  if (bin) {
+    const r = spawnSync(bin, ['enqueue', '--dir', dir, '--command', String(command)], {
+      encoding: 'utf8', windowsHide: true,
+    });
+    if (r.status === 0) {
+      const out = String(r.stdout || '').trim();
+      if (out) return out;
+    }
+    // Native spawn failed / non-zero → fall through to the JS writer.
+  }
+  const seq = String(enqueueSequence++).padStart(6, '0');
+  const base = `${Date.now()}-${seq}-${randomUUID().slice(0, 8)}.cmd`;
+  const tmp = join(dir, `.${base}.tmp`);
+  const dst = join(dir, base);
+  writeFileSync(tmp, String(command), 'utf8');
+  renameSync(tmp, dst);
+  return dst;
+}
+
+// Launcher side: drain queued commands oldest-first (lexical sort on the
+// timestamp-prefixed name), deleting each as it is read. Prefers the canonical
+// Rust backend; the JS reader is the fallback.
+export function drainLauncherCommands(launchId) {
+  const dir = launcherQueueDir(launchId);
+  const bin = nativeLaunchBin();
+  if (bin) {
+    const r = spawnSync(bin, ['drain', '--dir', dir], {
+      encoding: 'utf8', windowsHide: true,
+    });
+    if (r.status === 0) {
+      const out = String(r.stdout || '');
+      return out.length === 0 ? [] : out.split(RECORD_SEP);
+    }
+    // Native spawn failed / non-zero → fall through to the JS reader.
+  }
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of entries.filter((f) => f.endsWith('.cmd')).sort()) {
+    const full = join(dir, name);
+    let text;
+    try {
+      text = readFileSync(full, 'utf8');
+    } catch {
+      continue;
+    }
+    try {
+      rmSync(full, { force: true });
+    } catch {}
+    out.push(text);
+  }
+  return out;
+}
+
+// Launcher side: poll-based watcher. fs.watch semantics differ enough across
+// platforms (and miss atomic-rename publishes on some) that a short poll is the
+// robust choice for this low-rate control path. Returns a stop() that also
+// removes the queue directory.
+export function watchLauncherCommands(launchId, onCommand, { intervalMs = 150 } = {}) {
+  mkdirSync(launcherQueueDir(launchId), { recursive: true });
+  let stopped = false;
+  const timer = setInterval(() => {
+    if (stopped) return;
+    for (const cmd of drainLauncherCommands(launchId)) {
+      try {
+        onCommand(cmd);
+      } catch {}
+    }
+  }, intervalMs);
+  if (typeof timer.unref === 'function') timer.unref();
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(timer);
+    try {
+      rmSync(launcherQueueDir(launchId), { recursive: true, force: true });
+    } catch {}
+  };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Per-call cost estimator for bridge-trace usage rows.
+ *
+ * Pricing is pulled from the LiteLLM catalog (already warmed by providers/
+ * agent bootstrap). All four token slots — input / output / cacheRead /
+ * cacheWrite — are multiplied by their matching $/M rate from the catalog
+ * and summed. Missing rates are treated as 0 (no extrapolation).
+ *
+ * The catalog is looked up synchronously: if it has not been warmed yet
+ * (fresh process, first call), this returns 0 without blocking. The next
+ * call will pick up the cache.
+ */
+
+import { getModelMetadataSync } from '../../agent/orchestrator/providers/model-catalog.mjs';
+
+// OpenAI / Codex / Gemini report `input_tokens` as the total prompt token
+// count *including* the cached portion (inclusive). Anthropic reports the
+// uncached remainder only and bills cached_read / cached_write as separate
+// additive slots (additive). Cost and prompt-total math has to branch on this.
+// OpenAI-compatible direct providers (deepseek / ollama / lmstudio)
+// go through the OpenAI SDK and likewise report an inclusive prompt_tokens
+// with a separate cached-tokens detail — so they are inclusive too. Omitting
+// them bills the cached portion at the full input rate AND re-adds it as a
+// cacheRead slot, double-billing the cache (e.g. a ~10k-token cached system
+// prompt charged ~25x its real cost on every DeepSeek call).
+export function isInclusiveProvider(provider) {
+    if (!provider) return false;
+    const p = String(provider).toLowerCase();
+    // 'grok' covers grok-oauth, which delegates inference to the xai compat
+    // provider (inclusive input_tokens) but reports its own provider id on
+    // usage rows — without it, cached tokens would be double-billed in the
+    // cost fallback and prompt totals.
+    return p.includes('openai') || p.includes('codex') || p.includes('gemini') || p.includes('google') || p.includes('xai') || p.includes('grok')
+        || p.includes('deepseek') || p.includes('ollama') || p.includes('lmstudio') || p.includes('groq') || p.includes('openrouter');
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.model
+ * @param {string} [args.provider]
+ * @param {number} [args.inputTokens]
+ * @param {number} [args.outputTokens]
+ * @param {number} [args.cacheReadTokens]
+ * @param {number} [args.cacheWriteTokens]
+ * @returns {number} USD, rounded to 6 decimal places.
+ */
+export function computeCostUsd(args) {
+    const meta = getModelMetadataSync(args?.model, args?.provider);
+    if (!meta) return 0;
+    const inputTokens = args.inputTokens || 0;
+    const outputTokens = args.outputTokens || 0;
+    const cacheReadTokens = args.cacheReadTokens || 0;
+    const cacheWriteTokens = args.cacheWriteTokens || 0;
+    const billableInput = isInclusiveProvider(args.provider)
+        ? Math.max(inputTokens - cacheReadTokens - cacheWriteTokens, 0)
+        : inputTokens;
+    const parts = [
+        billableInput * (meta.inputCostPerM || 0),
+        outputTokens * (meta.outputCostPerM || 0),
+        cacheReadTokens * (meta.cacheReadCostPerM || 0),
+        cacheWriteTokens * (meta.cacheWriteCostPerM || 0),
+    ];
+    const total = parts.reduce((s, x) => s + x, 0) / 1_000_000;
+    if (!Number.isFinite(total) || total <= 0) return 0;
+    return Number(total.toFixed(6));
+}

package/src/runtime/shared/llm/http-agent.mjs

@@ -0,0 +1,129 @@
+/**
+ * Shared HTTP connection pool for outbound LLM provider API calls.
+ *
+ * The provider modules (anthropic-oauth, openai-oauth, grok-oauth, gemini)
+ * call the global `fetch()` with no dispatcher, so they ride Node's default
+ * undici agent. That agent keeps connections alive only briefly, so after an
+ * idle gap the first request to a provider pays a fresh TLS handshake — a
+ * 100-300ms first-byte penalty observed on cold calls.
+ *
+ * This module exports ONE lazily-created singleton undici `Agent` with a long
+ * keep-alive window and a sane connection cap, passed as the `dispatcher`
+ * option on those providers' `fetch()` calls so warm sockets survive idle
+ * gaps. `preconnect(origin)` opens a socket ahead of the first real request
+ * (best-effort, errors swallowed) and is called once at provider construction.
+ *
+ * Scope note: this is deliberately NOT used by src/search/lib/web-tools.mjs,
+ * whose per-request Agent pins a pre-validated DNS address for SSRF safety and
+ * must own its own short-lived pool. LLM API origins are fixed, trusted hosts,
+ * so a shared long-lived pool is appropriate here.
+ */
+
+import { Agent, getGlobalDispatcher, setGlobalDispatcher, request as undiciRequest } from 'undici'
+
+let _agent = null
+let _globalInstalled = false
+
+function envInt(name, fallback) {
+  const raw = process.env[name]
+  if (!raw) return fallback
+  const n = Number(raw)
+  return Number.isFinite(n) && n > 0 ? Math.trunc(n) : fallback
+}
+
+/**
+ * Detect whether outbound HTTP is meant to flow through a proxy or any custom
+ * global dispatcher. When so, pinning our own bare keep-alive `Agent` as the
+ * per-request `dispatcher` would silently bypass `setGlobalDispatcher(...)` and
+ * env-proxy wiring — so callers must fall back to the global dispatcher.
+ *
+ * What is preserved (we step aside): explicit proxy env vars, undici's built-in
+ * `ProxyAgent`, and ANY non-default global dispatcher — i.e. any installed
+ * global whose constructor name is not `Agent` (undici's default global is a
+ * plain `Agent`). Our own singleton is never installed via
+ * `setGlobalDispatcher`, so this never self-detects.
+ *
+ * Accepted gap: a custom dispatcher deliberately constructed AS a plain undici
+ * `Agent` and set as the global is indistinguishable from the default here, so
+ * we'd keep using our shared pool. That's tolerable — such a dispatcher is
+ * itself a direct-connection pool (no proxy hop), so the bypass risk is minimal.
+ */
+function proxyConfigured() {
+  const env = process.env
+  if (env.HTTP_PROXY || env.HTTPS_PROXY || env.http_proxy || env.https_proxy) return true
+  if (env.NODE_USE_ENV_PROXY) return true
+  try {
+    const g = getGlobalDispatcher?.()
+    // Any non-default global dispatcher (constructor name other than the plain
+    // `Agent` undici installs by default) is treated as custom — ProxyAgent,
+    // EnvHttpProxyAgent, MockAgent, or a user subclass — and we step aside.
+    if (g && g.constructor && g.constructor.name !== 'Agent') return true
+  } catch { /* getGlobalDispatcher unavailable — treat as no proxy */ }
+  return false
+}
+
+/**
+ * The shared singleton dispatcher for LLM API requests. Created on first use.
+ *
+ * keepAliveTimeout (~60s) keeps a socket warm across the typical idle gap
+ * between bridge turns; connections caps concurrent sockets per origin so a
+ * burst of parallel calls can't open an unbounded number of handshakes.
+ *
+ * Returns `undefined` when a proxy / any custom (non-default) global dispatcher
+ * is configured, so `fetch({ dispatcher: undefined })` falls back to that
+ * global dispatcher instead of bypassing it. `dispatcher: undefined` is a
+ * harmless fetch option, so call sites need no change.
+ */
+export function getLlmDispatcher() {
+  if (proxyConfigured()) return undefined
+  if (!_agent) {
+    _agent = new Agent({
+      keepAliveTimeout: envInt('MIXDOG_LLM_KEEPALIVE_MS', 60_000),
+      keepAliveMaxTimeout: envInt('MIXDOG_LLM_KEEPALIVE_MAX_MS', 90_000),
+      connections: envInt('MIXDOG_LLM_CONNECTIONS', 16),
+    })
+  }
+  // mixdog standalone: separate undici instance from Node's fetch undici, so
+  // a per-request dispatcher throws UND_ERR_INVALID_ARG. Install globally once
+  // and omit the per-request dispatcher. See port-plan D7.
+  if (!_globalInstalled) {
+    try { setGlobalDispatcher(_agent); _globalInstalled = true } catch { /* fall back */ }
+  }
+  return _globalInstalled ? undefined : _agent
+}
+
+// Origins already warmed (or warming) this process, so repeated provider
+// construction or multiple providers on the same host don't spam handshakes.
+const _preconnected = new Set()
+
+/**
+ * Best-effort warm a kept-alive socket to `origin` so the first real request
+ * skips the TLS handshake. Fire-and-forget: never throws, never returns a
+ * pending promise the caller must await.
+ *
+ * @param {string} origin e.g. 'https://api.anthropic.com'
+ */
+export function preconnect(origin) {
+  try {
+    // With a proxy / custom global dispatcher in play we deliberately don't own
+    // the connection pool, so there's no warm socket to seed — no-op.
+    if (proxyConfigured()) return
+    if (!origin || typeof origin !== 'string') return
+    let url
+    try { url = new URL(origin) } catch { return }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return
+    const key = url.origin
+    if (_preconnected.has(key)) return
+    _preconnected.add(key)
+    // A throwaway HEAD lands a pooled socket without fetching a body. Any
+    // failure (offline, DNS, 4xx/5xx) is irrelevant — the handshake is the
+    // point, and the real request will surface genuine errors.
+    undiciRequest(key, {
+      method: 'HEAD',
+      dispatcher: getLlmDispatcher(),
+      signal: AbortSignal.timeout(10_000),
+    })
+      .then((res) => res.body?.dump?.())
+      .catch(() => { /* best-effort warmup; ignore */ })
+  } catch { /* never let warmup break construction */ }
+}

package/src/runtime/shared/open-url.mjs

@@ -0,0 +1,37 @@
+import { spawn } from 'child_process';
+import { isWSL } from './wsl.mjs';
+
+/**
+ * Open a URL in the user's default browser. Best-effort and non-blocking.
+ * Callers also print the URL, so opener failure should never block OAuth.
+ */
+export function openInBrowser(url) {
+  const u = String(url);
+  let candidates;
+  if (process.platform === 'win32') {
+    candidates = [['rundll32', ['url.dll,FileProtocolHandler', u]]];
+  } else if (process.platform === 'darwin') {
+    candidates = [['open', [u]]];
+  } else if (isWSL()) {
+    const psUrl = `'${u.replace(/'/g, "''")}'`;
+    candidates = [
+      ['wslview', [u]],
+      ['powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', `Start-Process -FilePath ${psUrl}`]],
+    ];
+  } else {
+    candidates = [['xdg-open', [u]]];
+  }
+  tryOpenCandidates(candidates, 0);
+}
+
+function tryOpenCandidates(candidates, index) {
+  if (index >= candidates.length) return;
+  const [cmd, args] = candidates[index];
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true });
+    child.on('error', () => { tryOpenCandidates(candidates, index + 1); });
+    child.unref();
+  } catch {
+    tryOpenCandidates(candidates, index + 1);
+  }
+}

package/src/runtime/shared/plugin-paths.mjs

@@ -0,0 +1,25 @@
+/**
+ * Canonical resolver for the Mixdog data dir.
+ *
+ * Resolution order:
+ *   1. MIXDOG_DATA_DIR
+ *   2. <MIXDOG_HOME|~/.mixdog>/data
+ */
+
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const DEFAULT_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+export function mixdogHome() {
+  return process.env.MIXDOG_HOME || join(homedir(), '.mixdog');
+}
+
+export function mixdogRoot() {
+  return process.env.MIXDOG_ROOT || DEFAULT_ROOT;
+}
+
+export function resolvePluginData() {
+  return process.env.MIXDOG_DATA_DIR || join(mixdogHome(), 'data');
+}

package/src/runtime/shared/process-shutdown.mjs

@@ -0,0 +1,147 @@
+'use strict';
+
+const SIGNAL_EXIT_CODES = {
+  SIGINT: 130,
+  SIGTERM: 143,
+  SIGHUP: 129,
+};
+
+function errorText(error) {
+  return error?.stack || error?.message || String(error);
+}
+
+function writeStderr(line) {
+  try { process.stderr.write(`${line}\n`); } catch {}
+}
+
+export function signalExitCode(signal, fallback = 1) {
+  return SIGNAL_EXIT_CODES[signal] || fallback;
+}
+
+export function waitWithTimeout(promise, timeoutMs, label = 'cleanup') {
+  const ms = Math.max(1, Math.floor(Number(timeoutMs) || 1));
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+    if (typeof timer.unref === 'function') timer.unref();
+    Promise.resolve(promise)
+      .then((value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(value);
+      })
+      .catch((error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        reject(error);
+      });
+  });
+}
+
+export function installProcessSignalCleanup({
+  name = 'mixdog',
+  signals = ['SIGINT', 'SIGTERM', 'SIGHUP'],
+  timeoutMs = 6500,
+  exit = true,
+  fatal = true,
+  beforeCleanup,
+  cleanup,
+  afterCleanup,
+  log = writeStderr,
+} = {}) {
+  let installed = true;
+  let running = false;
+  let hardExitTimer = null;
+  const handlers = [];
+
+  const removeHandlers = () => {
+    for (const [event, handler] of handlers.splice(0)) {
+      try { process.removeListener(event, handler); } catch {}
+    }
+  };
+
+  const hardExit = (code) => {
+    try { process.exit(code); } catch {}
+  };
+
+  const run = async (reason = 'process-exit', {
+    code = 0,
+    shouldExit = false,
+    error = null,
+  } = {}) => {
+    if (running) {
+      if (shouldExit) hardExit(code);
+      return false;
+    }
+    running = true;
+    removeHandlers();
+
+    if (shouldExit) {
+      hardExitTimer = setTimeout(() => hardExit(code), Math.max(1000, Number(timeoutMs) + 1000));
+      if (typeof hardExitTimer.unref === 'function') hardExitTimer.unref();
+    }
+
+    if (error && typeof log === 'function') {
+      log(`[${name}] ${reason}: ${errorText(error)}`);
+    }
+
+    try { beforeCleanup?.(reason, { code, error }); } catch {}
+    try {
+      if (typeof cleanup === 'function') {
+        await waitWithTimeout(cleanup(reason, { code, error }), timeoutMs, `${name} shutdown`);
+      }
+    } catch (cleanupError) {
+      if (typeof log === 'function') log(`[${name}] cleanup failed: ${errorText(cleanupError)}`);
+    }
+    try { afterCleanup?.(reason, { code, error }); } catch {}
+    if (hardExitTimer) {
+      clearTimeout(hardExitTimer);
+      hardExitTimer = null;
+    }
+    running = false;
+    if (shouldExit) hardExit(code);
+    return true;
+  };
+
+  const add = (event, handler) => {
+    try {
+      process.once(event, handler);
+      handlers.push([event, handler]);
+    } catch {}
+  };
+
+  for (const signal of signals) {
+    if (!signal) continue;
+    add(signal, () => {
+      void run(signal, { code: signalExitCode(signal), shouldExit: exit });
+    });
+  }
+
+  if (fatal) {
+    add('uncaughtException', (error) => {
+      void run('uncaughtException', { code: 1, shouldExit: exit, error });
+    });
+    add('unhandledRejection', (error) => {
+      void run('unhandledRejection', { code: 1, shouldExit: exit, error });
+    });
+  }
+
+  return {
+    run,
+    uninstall() {
+      if (!installed) return;
+      installed = false;
+      removeHandlers();
+      if (hardExitTimer) {
+        clearTimeout(hardExitTimer);
+        hardExitTimer = null;
+      }
+    },
+  };
+}