@duckmind/dm-linux-x64 0.65.5 → 0.65.6

package/extensions/dm-lens/dist/clients/safe-spawn.js

@@ -0,0 +1,1267 @@
+import { spawn, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { BoundedFifoMap, BoundedSet } from "./bounded-cache.js";
+import { logLatency } from "./latency-logger.js";
+import { incrementDegradationCount, recordDegradation, recordDegradationOnce } from "./degradation-ledger.js";
+import { logExtension } from "./extension-log.js";
+import { isFullyQualifiedWin32 } from "./path-utils.js";
+import { startSpawnUsageSampler } from "./resource-sampler.js";
+import { DEFAULT_MAX_OUTPUT_BYTES } from "./spawn-output-cap.js";
+import { compareOrdinal } from "./string-utils.js";
+
+export class SpawnFailureError extends Error {
+  kind;
+  cause;
+  name = "SpawnFailureError";
+  constructor(kind, message, cause) {
+    super(message, { cause });
+    this.kind = kind;
+    this.cause = cause;
+  }
+}
+export function hasSpawnFailureKind(error, kind) {
+  return error instanceof Error && "kind" in error && error.kind === kind;
+}
+export function resolveTeardownOutcome(input) {
+  if (input.killStartedAtMs === undefined || input.deathObservedAtMs === undefined) {
+    return;
+  }
+  if (input.deathObservedAtMs <= input.killStartedAtMs) {
+    return { ms: 0, outcome: "exited" };
+  }
+  return {
+    ms: Math.max(0, input.deathObservedAtMs - input.killStartedAtMs),
+    outcome: input.escalated ? "escalate-kill" : "killed-by-signal"
+  };
+}
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+function errorCode(error) {
+  return error.code;
+}
+async function cwdIsUnresolvable(cwd) {
+  if (cwd === undefined)
+    return false;
+  try {
+    return !(await fs.promises.stat(cwd)).isDirectory();
+  } catch {
+    return true;
+  }
+}
+function cwdIsUnresolvableSync(cwd) {
+  if (cwd === undefined)
+    return false;
+  try {
+    return !fs.statSync(cwd).isDirectory();
+  } catch {
+    return true;
+  }
+}
+function commandProbablyPresent(command) {
+  const exts = process.platform === "win32" ? [
+    "",
+    ...(process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+  ] : [""];
+  const existsWithExt = (base) => {
+    for (const ext of exts) {
+      try {
+        if (fs.existsSync(base + ext))
+          return true;
+      } catch {}
+    }
+    return false;
+  };
+  if (path.isAbsolute(command))
+    return existsWithExt(command);
+  if (command.includes("/") || command.includes("\\"))
+    return "ambiguous";
+  for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
+    if (dir && existsWithExt(path.join(dir, command)))
+      return true;
+  }
+  return false;
+}
+function classifyWithCwdFlag(cause, options, cwdUnresolvable) {
+  const code = errorCode(cause);
+  let failure;
+  if (code === "ENOENT" && cwdUnresolvable && commandProbablyPresent(options.command) !== false) {
+    failure = new SpawnFailureError("cwd-unresolvable", `Cannot spawn ${options.command}: working directory is unresolvable (${options.cwd})`, cause);
+  } else if (code === "ENOENT") {
+    failure = new SpawnFailureError("tool-not-found", `Cannot spawn ${options.command}: tool not found (${cause.message})`, cause);
+  } else if (code === "EACCES" || code === "EPERM") {
+    failure = new SpawnFailureError("permission-denied", `Cannot spawn ${options.command}: permission denied`, cause);
+  } else {
+    failure = new SpawnFailureError("spawn-failed", `Cannot spawn ${options.command}: ${cause.message}`, cause);
+  }
+  recordSpawnClassification(failure, options);
+  return failure;
+}
+const loggedSpawnClassifications = new Set;
+const SPAWN_CLASSIFICATION_LOG_CAP = 200;
+function recordSpawnClassification(failure, options) {
+  const pair = `${failure.kind}\x00${options.command}`;
+  if (!loggedSpawnClassifications.has(pair)) {
+    if (loggedSpawnClassifications.size >= SPAWN_CLASSIFICATION_LOG_CAP) {
+      loggedSpawnClassifications.clear();
+    }
+    loggedSpawnClassifications.add(pair);
+    logExtension({
+      subsystem: "safe-spawn",
+      level: "debug",
+      message: "spawn failure classified",
+      metadata: {
+        kind: failure.kind,
+        command: options.command,
+        cwd: options.cwd
+      }
+    });
+  }
+  if (failure.kind !== "tool-not-found") {
+    recordDegradation({
+      kind: "spawn-failure",
+      subject: options.command,
+      reason: `${failure.kind}${options.cwd ? ` in ${options.cwd}` : ""}`
+    });
+  }
+}
+export async function classifySpawnFailure(error, options) {
+  const cause = toError(error);
+  const needsCwdProbe = errorCode(cause) === "ENOENT";
+  const cwdUnresolvable = needsCwdProbe && await cwdIsUnresolvable(options.cwd);
+  return classifyWithCwdFlag(cause, options, cwdUnresolvable);
+}
+function classifySpawnFailureSync(error, options) {
+  const cause = toError(error);
+  const needsCwdProbe = errorCode(cause) === "ENOENT";
+  const cwdUnresolvable = needsCwdProbe && cwdIsUnresolvableSync(options.cwd);
+  return classifyWithCwdFlag(cause, options, cwdUnresolvable);
+}
+const lifetimeStateKey = Symbol.for("dm-lens.safe-spawn.lifetime-state");
+const processWithLifetimeState = process;
+const lifetimeState = processWithLifetimeState[lifetimeStateKey] ?? (processWithLifetimeState[lifetimeStateKey] = {
+  pids: new Set,
+  installed: false
+});
+const PROC_PPID_READABLE = (() => {
+  if (process.platform !== "linux")
+    return false;
+  try {
+    return /^PPid:\s*\d+$/m.test(fs.readFileSync("/proc/self/status", "utf8"));
+  } catch {
+    return false;
+  }
+})();
+export const VERIFIED_OWN_PID_CAP = 512;
+const verifiedOwnPids = new BoundedFifoMap(VERIFIED_OWN_PID_CAP);
+const HELD_OWN_PID_SWEEP_AT = 256;
+const heldOwnPids = new BoundedSet(HELD_OWN_PID_SWEEP_AT);
+function groupIsGone(pid) {
+  try {
+    process.kill(-pid, 0);
+    return false;
+  } catch (error) {
+    return errorCode(error) === "ESRCH";
+  }
+}
+function sweepHeldOwnPids() {
+  if (heldOwnPids.size < HELD_OWN_PID_SWEEP_AT)
+    return;
+  for (const pid of heldOwnPids) {
+    if (groupIsGone(pid))
+      heldOwnPids.delete(pid);
+  }
+}
+export function holdOwnChildPid(pid, site) {
+  const owned = isOwnLiveChild(pid, site);
+  if (!owned || !PROC_PPID_READABLE || typeof pid !== "number")
+    return owned;
+  verifiedOwnPids.delete(pid);
+  sweepHeldOwnPids();
+  heldOwnPids.add(pid);
+  return true;
+}
+export function releaseOwnChildPid(pid) {
+  if (typeof pid === "number")
+    heldOwnPids.delete(pid);
+}
+function recordProcUnavailable(site) {
+  if (process.platform !== "linux")
+    return;
+  recordDegradationOnce({
+    kind: "kill-ownership-unverifiable",
+    subject: site,
+    reason: "/proc/self/status is unreadable on this Linux host; kill-by-pid ownership falls back to best-effort"
+  });
+}
+export function isOwnLiveChild(pid, site, handle) {
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+    return false;
+  if (!PROC_PPID_READABLE) {
+    if (handle && (handle.exitCode != null || handle.signalCode != null))
+      return false;
+    recordProcUnavailable(site);
+    return true;
+  }
+  let status;
+  try {
+    status = fs.readFileSync(`/proc/${pid}/status`, "utf8");
+  } catch {
+    return heldOwnPids.has(pid) || verifiedOwnPids.has(pid);
+  }
+  const parent = /^PPid:\s*(\d+)$/m.exec(status);
+  if (!parent)
+    return true;
+  if (Number(parent[1]) === process.pid) {
+    if (!heldOwnPids.has(pid))
+      verifiedOwnPids.set(pid, true);
+    return true;
+  }
+  incrementDegradationCount({
+    kind: "kill-foreign-pid-refused",
+    subject: site,
+    reason: `pid ${pid} has parent ${parent[1]}, not this process — signal refused`
+  });
+  return false;
+}
+function killPidTreeSync(pid) {
+  if (process.platform === "win32") {
+    try {
+      const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
+      spawnSync(taskkill, ["/F", "/T", "/PID", String(pid)], {
+        shell: false,
+        windowsHide: true,
+        stdio: "ignore"
+      });
+    } catch {}
+    return;
+  }
+  try {
+    try {
+      process.kill(-pid, "SIGKILL");
+    } catch {
+      process.kill(pid, "SIGKILL");
+    }
+  } catch {}
+}
+function installLifetimeCleanup() {
+  if (lifetimeState.installed)
+    return;
+  lifetimeState.installed = true;
+  process.once("exit", () => {
+    for (const pid of lifetimeState.pids)
+      killPidTreeSync(pid);
+  });
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.once(signal, () => {
+      for (const pid of lifetimeState.pids)
+        killPidTreeSync(pid);
+      if (process.platform === "win32" && signal === "SIGHUP") {
+        recordDegradationOnce({
+          kind: "safe-spawn-signal-reraise-unsupported",
+          subject: `${process.platform}:${signal}`,
+          reason: `${process.platform} ${signal}: self signal re-raise is unsupported by the Windows libuv signal capability`,
+          metadata: {
+            platform: process.platform,
+            signal,
+            reason: "unsupported"
+          }
+        });
+        return;
+      }
+      try {
+        process.kill(process.pid, signal);
+      } catch (error) {
+        recordDegradationOnce({
+          kind: "safe-spawn-signal-reraise-unsupported",
+          subject: `${process.platform}:${signal}`,
+          reason: `${process.platform} ${signal}: self signal re-raise was refused (${error.code ?? error.message})`,
+          metadata: {
+            platform: process.platform,
+            signal,
+            reason: "refused",
+            code: error.code ?? null
+          }
+        });
+      }
+    });
+  }
+}
+let ambientAbortSignal;
+export function setAmbientAbortSignal(signal) {
+  ambientAbortSignal = signal;
+}
+export function getAmbientAbortSignal() {
+  return ambientAbortSignal;
+}
+function cmdEscapeArg(arg) {
+  if (!/[\s"&|<>^()]/.test(arg))
+    return arg;
+  return `"${arg.replace(/"/g, '""')}"`;
+}
+export function buildWindowsShellCommand(command, args) {
+  const chcp = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\chcp.com`;
+  return `${chcp} 65001 >nul 2>&1 & ${[command, ...args].map(cmdEscapeArg).join(" ")}`;
+}
+const WINDOWS_DIRECT_RESOLVABLE_EXTS = new Set([
+  ".exe",
+  ".com",
+  ".cmd",
+  ".bat"
+]);
+export function mergeWindowsEnvironment(base, overrides) {
+  const entries = new Map;
+  const assign = (source) => {
+    if (!source)
+      return;
+    for (const [key, value] of Object.entries(source)) {
+      const folded = key.toLowerCase();
+      entries.delete(folded);
+      if (value !== undefined)
+        entries.set(folded, { key, value });
+    }
+  };
+  assign(base);
+  assign(overrides);
+  const merged = {};
+  for (const { key, value } of entries.values())
+    merged[key] = value;
+  return merged;
+}
+function getWindowsEnvironmentValue(env, name) {
+  let value;
+  for (const [key, entry] of Object.entries(env)) {
+    if (key.toLowerCase() === name.toLowerCase())
+      value = entry;
+  }
+  return value;
+}
+function driveLetter(value) {
+  const match = /^([A-Za-z]):/.exec(value);
+  return match?.[1]?.toUpperCase();
+}
+function isDriveAbsolute(value, drive) {
+  return value.length >= 3 && value[0]?.toUpperCase() === drive.toUpperCase() && value[1] === ":" && (value[2] === "\\" || value[2] === "/");
+}
+function isDriveAbsoluteAnyDrive(value) {
+  const drive = driveLetter(value);
+  return drive !== undefined && isDriveAbsolute(value, drive);
+}
+function isUncWindowsPath(value) {
+  return (value[0] === "\\" || value[0] === "/") && (value[1] === "\\" || value[1] === "/") && value[2] !== "\\" && value[2] !== "/";
+}
+function isFullyQualifiedWindowsPath(value) {
+  return isFullyQualifiedWin32(value) && !isRootedWindowsPath(value);
+}
+function isRootedWindowsPath(value) {
+  return (value[0] === "\\" || value[0] === "/") && driveLetter(value) === undefined && !isUncWindowsPath(value);
+}
+function resolveRootedWindowsPath(value, driveSource) {
+  const drive = driveLetter(driveSource);
+  if (drive === undefined)
+    return path.win32.normalize(value);
+  return path.win32.normalize(path.win32.resolve(`${drive}:\\`, value));
+}
+function getValidatedPerDriveCwd(env, drive) {
+  const value = getWindowsEnvironmentValue(env, `=${drive}:`);
+  if (value === undefined || !isDriveAbsolute(value, drive))
+    return;
+  return path.win32.normalize(value);
+}
+function resolveEffectiveWindowsCwd(cwd, env) {
+  if (cwd === undefined) {
+    return path.win32.normalize(process.cwd());
+  }
+  const requestedDrive = driveLetter(cwd);
+  if (requestedDrive !== undefined && !isDriveAbsoluteAnyDrive(cwd)) {
+    const base = getValidatedPerDriveCwd(env, requestedDrive);
+    return base === undefined ? undefined : path.win32.normalize(path.win32.resolve(base, cwd));
+  }
+  if (isFullyQualifiedWindowsPath(cwd))
+    return path.win32.normalize(cwd);
+  if (isRootedWindowsPath(cwd)) {
+    return resolveRootedWindowsPath(cwd, process.cwd());
+  }
+  return path.win32.normalize(path.win32.resolve(process.cwd(), cwd));
+}
+function resolveDriveRelativeWindowsPath(value, effectiveCwd, env) {
+  const drive = driveLetter(value);
+  if (drive === undefined)
+    return;
+  const cwdDrive = effectiveCwd === undefined ? undefined : driveLetter(effectiveCwd);
+  const base = cwdDrive?.toUpperCase() === drive ? effectiveCwd : getValidatedPerDriveCwd(env, drive);
+  if (base === undefined)
+    return;
+  return path.win32.normalize(path.win32.resolve(base, value));
+}
+function resolveWindowsPathEntry(entry, effectiveCwd, env) {
+  if (driveLetter(entry) !== undefined && !isDriveAbsoluteAnyDrive(entry)) {
+    return resolveDriveRelativeWindowsPath(entry, effectiveCwd, env);
+  }
+  if (isFullyQualifiedWindowsPath(entry))
+    return path.win32.normalize(entry);
+  if (isRootedWindowsPath(entry)) {
+    return effectiveCwd === undefined ? undefined : resolveRootedWindowsPath(entry, effectiveCwd);
+  }
+  if (effectiveCwd === undefined)
+    return;
+  return path.win32.normalize(path.win32.resolve(effectiveCwd, entry));
+}
+export const WINDOWS_COMMAND_CACHE_MAX_ENTRIES = 256;
+const WINDOWS_COMMAND_NEGATIVE_CACHE_TTL_MS = 1000;
+const windowsCommandCache = new BoundedFifoMap(WINDOWS_COMMAND_CACHE_MAX_ENTRIES);
+export function resetSafeSpawnWindowsCommandCache() {
+  windowsCommandCache.clear();
+  loggedSpawnClassifications.clear();
+}
+function cacheWindowsCommandResult(key, resolved) {
+  windowsCommandCache.set(key, { resolved, checkedAt: Date.now() });
+}
+function getPathExts(env) {
+  const raw = getWindowsEnvironmentValue(env, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD";
+  return raw.split(";").map((ext) => ext.trim().toLowerCase()).filter(Boolean);
+}
+function statIsFile(candidate) {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+function resolveWindowsCommandUncached(command, effectiveCwd, env) {
+  const pathExts = getPathExts(env);
+  const existingExt = path.win32.extname(command).toLowerCase();
+  const hasExplicitExt = existingExt.length > 0;
+  const isKnownExecutableExt = (ext) => WINDOWS_DIRECT_RESOLVABLE_EXTS.has(ext) || pathExts.includes(ext);
+  const tryBase = (base) => {
+    if (hasExplicitExt && isKnownExecutableExt(existingExt) && statIsFile(base)) {
+      return { resolvedPath: base, ext: existingExt };
+    }
+    if (!hasExplicitExt || !pathExts.includes(existingExt)) {
+      for (const ext of pathExts) {
+        const candidate = base + ext;
+        if (statIsFile(candidate))
+          return { resolvedPath: candidate, ext };
+      }
+    }
+    return null;
+  };
+  const hasPathSep = /[\\/]/.test(command);
+  const hasDrivePrefix = driveLetter(command) !== undefined;
+  if (hasPathSep || hasDrivePrefix || isFullyQualifiedWindowsPath(command)) {
+    let base;
+    if (isFullyQualifiedWindowsPath(command)) {
+      base = path.win32.normalize(command);
+    } else if (hasDrivePrefix) {
+      base = resolveDriveRelativeWindowsPath(command, effectiveCwd, env);
+    } else if (isRootedWindowsPath(command)) {
+      base = effectiveCwd === undefined ? undefined : resolveRootedWindowsPath(command, effectiveCwd);
+    } else if (effectiveCwd !== undefined) {
+      base = path.win32.normalize(path.win32.resolve(effectiveCwd, command));
+    }
+    return base === undefined ? null : tryBase(base);
+  }
+  const pathValue = getWindowsEnvironmentValue(env, "PATH") ?? "";
+  const pathDirs = pathValue.split(path.win32.delimiter);
+  for (const dir of pathDirs) {
+    if (!dir)
+      continue;
+    const resolvedDir = resolveWindowsPathEntry(dir, effectiveCwd, env);
+    if (resolvedDir === undefined)
+      continue;
+    const found = tryBase(path.win32.join(resolvedDir, command));
+    if (found)
+      return found;
+  }
+  return null;
+}
+export function resolveWindowsCommandForEnvironment(command, cwd, env) {
+  const effectiveCwd = resolveEffectiveWindowsCwd(cwd, env);
+  const pathValue = getWindowsEnvironmentValue(env, "PATH");
+  const pathExtValue = getWindowsEnvironmentValue(env, "PATHEXT");
+  const perDriveCwds = Object.entries(env).flatMap(([key, value]) => /^=[A-Za-z]:$/.test(key) ? [[key.toLowerCase(), value]] : []).sort(([left], [right]) => compareOrdinal(left, right));
+  const cacheKey = JSON.stringify([
+    "win32",
+    command,
+    pathValue === undefined ? ["absent"] : ["present", pathValue],
+    pathExtValue === undefined ? ["absent"] : ["present", pathExtValue],
+    effectiveCwd === undefined ? ["unresolved"] : ["resolved", effectiveCwd],
+    perDriveCwds
+  ]);
+  const cached = windowsCommandCache.get(cacheKey);
+  if (cached) {
+    if (cached.resolved && statIsFile(cached.resolved.resolvedPath)) {
+      return cached.resolved;
+    }
+    if (!cached.resolved && Date.now() - cached.checkedAt <= WINDOWS_COMMAND_NEGATIVE_CACHE_TTL_MS) {
+      return null;
+    }
+    windowsCommandCache.delete(cacheKey);
+  }
+  const resolved = resolveWindowsCommandUncached(command, effectiveCwd, env);
+  cacheWindowsCommandResult(cacheKey, resolved);
+  return resolved;
+}
+function resolveWindowsCommand(command, cwd, env) {
+  return resolveWindowsCommandForEnvironment(command, cwd, env);
+}
+function getSpawnEnvironment(overrides) {
+  return process.platform === "win32" ? mergeWindowsEnvironment(process.env, overrides) : { ...process.env, ...overrides };
+}
+const CMD_UNSAFE_CHARS = /["%!\r\n]/;
+function findCmdUnsafeValue(command, args) {
+  if (CMD_UNSAFE_CHARS.test(command))
+    return command;
+  return args.find((arg) => CMD_UNSAFE_CHARS.test(arg));
+}
+function synthesizeEnoentError(command) {
+  const err = new Error(`spawn ${command} ENOENT`);
+  err.code = "ENOENT";
+  err.syscall = "spawn";
+  err.path = command;
+  return err;
+}
+let utf8ConsoleCodePageApplied = false;
+function ensureUtf8ConsoleCodePageOnce() {
+  if (utf8ConsoleCodePageApplied)
+    return;
+  utf8ConsoleCodePageApplied = true;
+  try {
+    const cmdExe = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`;
+    spawnSync(cmdExe, ["/d", "/s", "/c", "chcp 65001 >nul 2>&1"], {
+      shell: false,
+      windowsHide: true,
+      timeout: 5000
+    });
+  } catch {}
+}
+export function resetUtf8ConsoleCodePageStateForTests() {
+  utf8ConsoleCodePageApplied = false;
+}
+const EXIT_PIPE_IDLE_GRACE_MS = 100;
+const EXIT_PIPE_IDLE_MAX_WAIT_MS = 2000;
+const SPAWN_SAMPLER_TEARDOWN_GRACE_MS = 5000;
+export async function safeSpawnAsync(command, args, options) {
+  const configuredTimeout = options?.timeout !== undefined && Number.isFinite(options.timeout) && options.timeout >= 0 ? options.timeout : 30000;
+  const deadlineRemaining = options?.deadlineAt !== undefined && Number.isFinite(options.deadlineAt) ? options.deadlineAt - Date.now() : Number.POSITIVE_INFINITY;
+  const timeout = Math.max(0, Math.min(configuredTimeout, deadlineRemaining));
+  const abortSignal = options?.signal ?? (options?.ignoreAmbientSignal ? undefined : ambientAbortSignal);
+  return new Promise((resolve) => {
+    if (abortSignal?.aborted) {
+      const cause = new Error("Spawn aborted before start");
+      resolve({
+        stdout: "",
+        stderr: "",
+        status: null,
+        error: cause,
+        failure: "aborted",
+        spawnFailure: new SpawnFailureError("killed", cause.message, cause)
+      });
+      return;
+    }
+    if (timeout <= 0) {
+      const cause = new Error(`Process timed out after ${timeout}ms`);
+      resolve({
+        stdout: "",
+        stderr: "",
+        status: null,
+        error: cause,
+        failure: "timeout",
+        spawnFailure: new SpawnFailureError("timeout", cause.message, cause)
+      });
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let aborted = false;
+    let killed = false;
+    let outputTruncated = false;
+    let killedForOutputCap = false;
+    let observedOutputBytes = 0;
+    let retainedOutputBytes = 0;
+    let outputHandlerFailed = false;
+    let streamingMatch = false;
+    let resolved = false;
+    let pendingSpawnError;
+    let escalationTimer;
+    let teardownStartedAtMs;
+    let teardownEscalated = false;
+    let closed = false;
+    let rearmIdleGrace;
+    const callerCap = options?.maxOutputBytes;
+    const capFromCaller = callerCap !== undefined && Number.isFinite(callerCap) && callerCap > 0;
+    const maxOutputBytes = capFromCaller ? Math.floor(callerCap) : DEFAULT_MAX_OUTPUT_BYTES;
+    const outputTruncationMarker = `
+...[output truncated]...
+`;
+    let retainedHead = [];
+    let retainedTail = [];
+    let retainedTailBytes = 0;
+    let retainedTailLimit = 0;
+    let truncationStream = "stderr";
+    const streamingMatcher = options?.matchWhileStreaming;
+    const streamingCarryBytes = streamingMatcher ? Math.max(0, streamingMatcher.source.length - 1) : 0;
+    const streamingCarry = {
+      stdout: "",
+      stderr: ""
+    };
+    const bytePrefix = (text, bytes) => Buffer.from(text).subarray(0, bytes).toString();
+    const byteSuffix = (text, bytes) => {
+      const buffer = Buffer.from(text);
+      return buffer.subarray(Math.max(0, buffer.byteLength - bytes)).toString();
+    };
+    const appendTail = (part, maxBytes) => {
+      if (maxBytes <= 0)
+        return;
+      retainedTail.push({ stream: part.stream, text: part.text });
+      retainedTailBytes += Buffer.byteLength(part.text);
+      while (retainedTailBytes > maxBytes && retainedTail.length > 0) {
+        const first = retainedTail[0];
+        const excess = retainedTailBytes - maxBytes;
+        const firstBytes = Buffer.byteLength(first.text);
+        if (firstBytes <= excess) {
+          retainedTail.shift();
+          retainedTailBytes -= firstBytes;
+        } else {
+          first.text = byteSuffix(first.text, firstBytes - excess);
+          retainedTailBytes -= excess;
+        }
+      }
+    };
+    const renderOutput = (stream) => {
+      const head = retainedHead.filter((part) => part.stream === stream).map((part) => part.text).join("");
+      const tail = retainedTail.filter((part) => part.stream === stream).map((part) => part.text).join("");
+      const marker = stream === truncationStream ? outputTruncationMarker : "";
+      return head + marker + tail;
+    };
+    const refreshRetainedOutputs = () => {
+      stdout = renderOutput("stdout");
+      stderr = renderOutput("stderr");
+    };
+    const appendOutput = (stream, current, chunk) => {
+      const text = typeof chunk === "string" ? chunk : chunk.toString();
+      if (outputTruncated) {
+        appendTail({ stream, text }, retainedTailLimit);
+        truncationStream = stream;
+        return renderOutput(stream);
+      }
+      const bytes = Buffer.byteLength(text);
+      if (retainedOutputBytes + bytes <= maxOutputBytes) {
+        retainedOutputBytes += bytes;
+        return current + text;
+      }
+      outputTruncated = true;
+      truncationStream = stream;
+      const available = Math.max(0, maxOutputBytes - Buffer.byteLength(outputTruncationMarker));
+      const headBytes = Math.floor(available / 2);
+      const tailBytes = available - headBytes;
+      retainedTailLimit = tailBytes;
+      const parts = [
+        { stream: "stdout", text: stdout },
+        { stream: "stderr", text: stderr },
+        { stream, text }
+      ];
+      let headRemaining = headBytes;
+      for (const part of parts) {
+        if (headRemaining <= 0)
+          break;
+        const kept = bytePrefix(part.text, headRemaining);
+        if (kept)
+          retainedHead.push({ stream: part.stream, text: kept });
+        headRemaining -= Buffer.byteLength(kept);
+      }
+      let tailRemaining = tailBytes;
+      for (let index = parts.length - 1;index >= 0 && tailRemaining > 0; index--) {
+        const part = parts[index];
+        const kept = byteSuffix(part.text, tailRemaining);
+        if (kept) {
+          retainedTail.unshift({ stream: part.stream, text: kept });
+          tailRemaining -= Buffer.byteLength(kept);
+        }
+      }
+      retainedTailBytes = tailBytes - tailRemaining;
+      return renderOutput(stream);
+    };
+    const matchStreamingChunk = (stream, chunk) => {
+      if (streamingMatch || !streamingMatcher)
+        return;
+      const text = typeof chunk === "string" ? chunk : chunk.toString();
+      streamingMatcher.lastIndex = 0;
+      streamingMatch = streamingMatcher.test(streamingCarry[stream] + text);
+      if (streamingCarryBytes > 0) {
+        streamingCarry[stream] = Buffer.from(streamingCarry[stream] + text).subarray(-streamingCarryBytes).toString();
+      }
+    };
+    const isWindows = process.platform === "win32";
+    const spawnEnv = getSpawnEnvironment(options?.env);
+    const spawnCwd = isWindows ? resolveEffectiveWindowsCwd(options?.cwd, spawnEnv) ?? options?.cwd : options?.cwd;
+    let spawnCmd = command;
+    let spawnArgs = args;
+    let windowsVerbatimArguments = false;
+    let resolutionError;
+    if (isWindows) {
+      const resolved = resolveWindowsCommand(command, options?.cwd, spawnEnv);
+      if (!resolved) {
+        resolutionError = synthesizeEnoentError(command);
+      } else if (resolved.ext === ".cmd" || resolved.ext === ".bat") {
+        const unsafeValue = findCmdUnsafeValue(resolved.resolvedPath, args);
+        if (unsafeValue !== undefined) {
+          resolutionError = new Error(`Refusing to spawn "${resolved.resolvedPath}" via cmd.exe: ` + `${JSON.stringify(unsafeValue)} contains a character ("` + `, %, !, or CR/LF) that cannot be safely escaped on a ` + `cmd.exe /c command line (CWE-78, #817). Rename/quote the ` + "value or invoke the tool without going through cmd.exe.");
+        } else {
+          spawnCmd = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`;
+          spawnArgs = [
+            "/d",
+            "/s",
+            "/c",
+            buildWindowsShellCommand(resolved.resolvedPath, args)
+          ];
+          windowsVerbatimArguments = true;
+        }
+      } else {
+        ensureUtf8ConsoleCodePageOnce();
+        spawnCmd = resolved.resolvedPath;
+        spawnArgs = args;
+      }
+    }
+    if (resolutionError) {
+      classifySpawnFailure(resolutionError, {
+        command,
+        cwd: options?.cwd
+      }).then((spawnFailure) => resolve({
+        stdout: "",
+        stderr: "",
+        status: null,
+        error: resolutionError,
+        failure: "spawn",
+        spawnFailure
+      }));
+      return;
+    }
+    let child;
+    const posixProcessGroup = process.platform !== "win32";
+    try {
+      child = spawn(spawnCmd, spawnArgs, {
+        cwd: spawnCwd,
+        env: spawnEnv,
+        windowsHide: true,
+        shell: false,
+        windowsVerbatimArguments,
+        detached: posixProcessGroup
+      });
+    } catch (err) {
+      const cause = toError(err);
+      classifySpawnFailure(cause, { command, cwd: options?.cwd }).then((spawnFailure) => resolve({
+        stdout: "",
+        stderr: "",
+        status: null,
+        error: cause,
+        failure: "spawn",
+        spawnFailure
+      }));
+      return;
+    }
+    if (options?.input !== undefined) {
+      child.stdin?.on("error", () => {});
+      child.stdin?.end(options.input);
+    }
+    const ownsChildPid = isOwnLiveChild(child.pid, "safe-spawn-register");
+    if (ownsChildPid && (posixProcessGroup || options?.lifetimeCoupled)) {
+      installLifetimeCleanup();
+      lifetimeState.pids.add(child.pid);
+    }
+    let usageSampler;
+    try {
+      usageSampler = startSpawnUsageSampler(child.pid, undefined, timeout + SPAWN_SAMPLER_TEARDOWN_GRACE_MS);
+    } catch {
+      usageSampler = { stop: () => null };
+    }
+    const resourceLabel = options?.resourceLabel ?? command;
+    let killFailed = false;
+    const trySend = (send) => {
+      try {
+        send();
+        return true;
+      } catch {
+        return false;
+      }
+    };
+    const noteKillFailure = (phase) => {
+      if (killFailed)
+        return;
+      killFailed = true;
+      incrementDegradationCount({
+        kind: "spawn-kill-failed",
+        subject: resourceLabel,
+        reason: `every signal available for the ${phase} teardown was refused; the child may still be running`,
+        metadata: { phase, pid: child.pid }
+      });
+    };
+    const killTree = async (phase) => {
+      if (isWindows && child.pid && child.pid > 0) {
+        const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
+        try {
+          await new Promise((done) => {
+            const killer = spawn(taskkill, ["/F", "/T", "/PID", String(child.pid)], {
+              shell: false,
+              windowsHide: true,
+              stdio: "ignore"
+            });
+            killer.once("close", () => done());
+            killer.once("error", () => {
+              if (!trySend(() => child.kill("SIGKILL")))
+                noteKillFailure(phase);
+              done();
+            });
+          });
+        } catch {
+          if (!trySend(() => child.kill("SIGKILL")))
+            noteKillFailure(phase);
+        }
+      } else if (posixProcessGroup && ownsChildPid) {
+        const pgid = -child.pid;
+        if (!trySend(() => process.kill(pgid, "SIGTERM"))) {
+          if (!trySend(() => child.kill("SIGTERM")))
+            noteKillFailure(phase);
+        }
+        escalationTimer = setTimeout(() => {
+          const escalated = trySend(() => {
+            let groupAlive = true;
+            try {
+              process.kill(pgid, 0);
+            } catch {
+              groupAlive = false;
+            }
+            if (!groupAlive)
+              return;
+            teardownEscalated = true;
+            logLatency({
+              type: "phase",
+              phase: "spawn_group_kill_escalation",
+              filePath: "",
+              durationMs: 0,
+              metadata: { pgid: child.pid }
+            });
+            trySend(() => process.kill(pgid, "SIGKILL"));
+          });
+          if (!escalated)
+            noteKillFailure(phase);
+        }, 1000);
+      } else {
+        if (!trySend(() => child.kill("SIGTERM")))
+          noteKillFailure(phase);
+        escalationTimer = setTimeout(() => {
+          if (closed)
+            return;
+          teardownEscalated = true;
+          if (!trySend(() => child.kill("SIGKILL")))
+            noteKillFailure(phase);
+        }, 1000);
+      }
+    };
+    const onAbort = () => {
+      aborted = true;
+      if (!killed && !child.killed) {
+        killed = true;
+        killTree("abort");
+      }
+    };
+    abortSignal?.addEventListener("abort", onAbort, { once: true });
+    let killPromise;
+    const stopForOutputLimit = () => {
+      const waitingForStreamingMatch = streamingMatcher !== undefined && !streamingMatch;
+      if (outputTruncated && !waitingForStreamingMatch && !killed && !child.killed) {
+        killedForOutputCap = true;
+        killed = true;
+        killPromise = killTree("output-cap");
+      }
+    };
+    const recordOutputCapTrip = () => {
+      incrementDegradationCount({
+        kind: "spawn-output-cap-truncated",
+        subject: resourceLabel,
+        reason: `retained output reached the ${maxOutputBytes}-byte ${capFromCaller ? "caller" : "default"} cap after ${observedOutputBytes} bytes; child ${killedForOutputCap ? "terminated" : "left running"}`,
+        metadata: {
+          capBytes: maxOutputBytes,
+          capSource: capFromCaller ? "caller" : "default",
+          observedBytes: observedOutputBytes,
+          killed: killedForOutputCap
+        }
+      });
+    };
+    const failOutputHandler = (stream, error) => {
+      outputHandlerFailed = true;
+      outputTruncated = true;
+      incrementDegradationCount({
+        kind: "spawn-output-handler-fault",
+        subject: resourceLabel,
+        reason: `${stream} chunk handling threw ${error.name} after ${observedOutputBytes} bytes; retention stopped and the child was terminated`,
+        metadata: {
+          stream,
+          error: error.name,
+          capBytes: maxOutputBytes,
+          observedBytes: observedOutputBytes
+        }
+      });
+      if (!killed && !child.killed) {
+        killedForOutputCap = true;
+        killed = true;
+        killPromise = killTree("handler-fault");
+      }
+    };
+    child.stdout?.setEncoding("utf-8");
+    child.stderr?.setEncoding("utf-8");
+    const onOutputChunk = (stream, data) => {
+      if (outputHandlerFailed)
+        return;
+      try {
+        observedOutputBytes += Buffer.byteLength(data);
+        const wasTruncated = outputTruncated;
+        matchStreamingChunk(stream, data);
+        if (stream === "stdout")
+          stdout = appendOutput(stream, stdout, data);
+        else
+          stderr = appendOutput(stream, stderr, data);
+        if (outputTruncated)
+          refreshRetainedOutputs();
+        stopForOutputLimit();
+        if (!wasTruncated && outputTruncated)
+          recordOutputCapTrip();
+        rearmIdleGrace?.();
+      } catch (error) {
+        failOutputHandler(stream, toError(error));
+      }
+    };
+    child.stdout?.on("data", (data) => onOutputChunk("stdout", data));
+    child.stderr?.on("data", (data) => onOutputChunk("stderr", data));
+    let closeSeen = false;
+    let closedAtMs;
+    child.on("close", () => {
+      closeSeen = true;
+      closedAtMs ??= Date.now();
+    });
+    const timeoutId = setTimeout(() => {
+      timedOut = true;
+      if (!killed && !child.killed) {
+        killed = true;
+        teardownStartedAtMs = Date.now();
+        killPromise = killTree("timeout");
+      }
+    }, timeout);
+    const finishResourceUsage = () => {
+      const summary = usageSampler.stop();
+      if (!summary)
+        return;
+      try {
+        logLatency({
+          type: "phase",
+          phase: "spawn_resource_usage",
+          filePath: "",
+          durationMs: 0,
+          metadata: {
+            command: resourceLabel,
+            ...summary
+          }
+        });
+      } catch {}
+      return summary;
+    };
+    const waitForPipeIdle = () => {
+      if (!child.stdout && !child.stderr)
+        return Promise.resolve();
+      if (closeSeen)
+        return Promise.resolve();
+      return new Promise((finishIdleWait) => {
+        let settled = false;
+        let graceTimer;
+        const capTimer = setTimeout(() => {
+          finish();
+        }, EXIT_PIPE_IDLE_MAX_WAIT_MS);
+        const finish = () => {
+          if (settled)
+            return;
+          settled = true;
+          rearmIdleGrace = undefined;
+          if (graceTimer)
+            clearTimeout(graceTimer);
+          clearTimeout(capTimer);
+          child.removeListener?.("close", finish);
+          finishIdleWait();
+        };
+        child.on("close", finish);
+        rearmIdleGrace = () => {
+          if (graceTimer)
+            clearTimeout(graceTimer);
+          graceTimer = setTimeout(finish, EXIT_PIPE_IDLE_GRACE_MS);
+        };
+        rearmIdleGrace();
+      });
+    };
+    let settled = false;
+    const onChildSettle = (code, signal) => {
+      if (settled || resolved)
+        return;
+      settled = true;
+      closed = true;
+      clearTimeout(timeoutId);
+      abortSignal?.removeEventListener("abort", onAbort);
+      if (child.pid)
+        lifetimeState.pids.delete(child.pid);
+      finalize(code, signal);
+    };
+    const finalize = async (code, signal) => {
+      await killPromise;
+      if (resolved)
+        return;
+      if (escalationTimer && !posixProcessGroup) {
+        clearTimeout(escalationTimer);
+      }
+      resolved = true;
+      await waitForPipeIdle();
+      const resourceUsage = finishResourceUsage();
+      const outputInfo = {
+        ...outputTruncated ? { outputTruncated: true } : {},
+        ...killedForOutputCap ? { killedForOutputCap: true } : {},
+        ...killFailed ? { killFailed: true } : {}
+      };
+      const streamingMatchInfo = streamingMatch ? { streamingMatch: true } : {};
+      const signalInfo = signal ? { signal } : {};
+      if (timedOut) {
+        const cause = new Error(`Process timed out after ${timeout}ms (killed with ${signal || "SIGTERM"})`);
+        const timeoutTeardown = resolveTeardownOutcome({
+          killStartedAtMs: teardownStartedAtMs,
+          deathObservedAtMs: closedAtMs,
+          escalated: teardownEscalated
+        });
+        resolve({
+          stdout,
+          stderr,
+          status: null,
+          error: cause,
+          failure: "timeout",
+          ...signalInfo,
+          ...timeoutTeardown && { timeoutTeardown },
+          spawnFailure: new SpawnFailureError("timeout", cause.message, cause),
+          ...outputInfo,
+          ...streamingMatchInfo,
+          resourceUsage
+        });
+      } else if (aborted) {
+        const cause = new Error("Spawn aborted");
+        resolve({
+          stdout,
+          stderr,
+          status: null,
+          error: cause,
+          failure: "aborted",
+          ...signalInfo,
+          spawnFailure: new SpawnFailureError("killed", cause.message, cause),
+          ...outputInfo,
+          ...streamingMatchInfo,
+          resourceUsage
+        });
+      } else if (signal) {
+        const cause = new Error(`Process killed by signal: ${signal}`);
+        resolve({
+          stdout,
+          stderr,
+          status: null,
+          error: cause,
+          failure: "signal",
+          ...signalInfo,
+          spawnFailure: new SpawnFailureError("killed", cause.message, cause),
+          ...outputInfo,
+          ...streamingMatchInfo,
+          resourceUsage
+        });
+      } else if (code === null || code < 0) {
+        const cause = pendingSpawnError ?? synthesizeEnoentError(command);
+        const spawnFailure = await classifySpawnFailure(cause, {
+          command,
+          cwd: options?.cwd
+        });
+        resolve({
+          stdout,
+          stderr,
+          status: code,
+          error: cause,
+          failure: "spawn",
+          spawnFailure,
+          ...outputInfo,
+          ...streamingMatchInfo,
+          resourceUsage
+        });
+      } else {
+        resolve({
+          stdout,
+          stderr,
+          status: code,
+          ...outputInfo,
+          ...streamingMatchInfo,
+          resourceUsage
+        });
+      }
+    };
+    child.on("exit", onChildSettle);
+    child.on("close", onChildSettle);
+    child.on("error", (err) => {
+      pendingSpawnError = err;
+      if (resolved)
+        return;
+      resolved = true;
+      closed = true;
+      clearTimeout(timeoutId);
+      abortSignal?.removeEventListener("abort", onAbort);
+      if (escalationTimer && !posixProcessGroup) {
+        clearTimeout(escalationTimer);
+      }
+      if (child.pid)
+        lifetimeState.pids.delete(child.pid);
+      const resourceUsage = finishResourceUsage();
+      let failure = "spawn";
+      if (aborted)
+        failure = "aborted";
+      else if (timedOut)
+        failure = "timeout";
+      const controlFailure = aborted ? new SpawnFailureError("killed", err.message, err) : timedOut ? new SpawnFailureError("timeout", err.message, err) : undefined;
+      const finish = (spawnFailure) => resolve({
+        stdout,
+        stderr,
+        status: null,
+        error: err,
+        failure,
+        spawnFailure,
+        ...outputTruncated ? { outputTruncated: true } : {},
+        ...killedForOutputCap ? { killedForOutputCap: true } : {},
+        ...killFailed ? { killFailed: true } : {},
+        ...streamingMatch ? { streamingMatch: true } : {},
+        resourceUsage
+      });
+      if (controlFailure)
+        finish(controlFailure);
+      else {
+        classifySpawnFailure(err, { command, cwd: options?.cwd }).then(finish);
+      }
+    });
+  });
+}
+export async function safeSpawnBatch(commands, concurrency = 3) {
+  const results = [];
+  for (let i = 0;i < commands.length; i += concurrency) {
+    const batch = commands.slice(i, i + concurrency);
+    const batchResults = await Promise.all(batch.map(({ command, args, options }) => safeSpawnAsync(command, args, options)));
+    results.push(...batchResults);
+  }
+  return results;
+}
+export async function isCommandAvailableAsync(command) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const result = await safeSpawnAsync(finder, [command], { timeout: 5000 });
+  return result.status === 0 && !result.error;
+}
+export async function findCommandAsync(command) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const result = await safeSpawnAsync(finder, [command], { timeout: 5000 });
+  if (result.status !== 0 || result.error)
+    return null;
+  return result.stdout.trim().split(`
+`)[0] || null;
+}
+export function safeSpawn(command, args, options) {
+  const spawnEnv = getSpawnEnvironment(options?.env);
+  if (process.platform === "win32") {
+    const spawnCwd = resolveEffectiveWindowsCwd(options?.cwd, spawnEnv) ?? options?.cwd;
+    const resolved = resolveWindowsCommand(command, options?.cwd, spawnEnv);
+    if (!resolved) {
+      const error = synthesizeEnoentError(command);
+      return {
+        stdout: "",
+        stderr: "",
+        status: null,
+        error,
+        failure: "spawn",
+        spawnFailure: classifySpawnFailureSync(error, {
+          command,
+          cwd: options?.cwd
+        })
+      };
+    }
+    let spawnCmd;
+    let spawnArgs;
+    let windowsVerbatimArguments = false;
+    if (resolved.ext === ".cmd" || resolved.ext === ".bat") {
+      const unsafeValue = findCmdUnsafeValue(resolved.resolvedPath, args);
+      if (unsafeValue !== undefined) {
+        const error = new Error(`Refusing to spawn "${resolved.resolvedPath}" via cmd.exe: ` + `${JSON.stringify(unsafeValue)} contains a character ("` + `, %, !, or CR/LF) that cannot be safely escaped on a ` + `cmd.exe /c command line (CWE-78, #817). Rename/quote the ` + "value or invoke the tool without going through cmd.exe.");
+        return {
+          stdout: "",
+          stderr: "",
+          status: null,
+          error,
+          failure: "spawn",
+          spawnFailure: classifySpawnFailureSync(error, {
+            command,
+            cwd: options?.cwd
+          })
+        };
+      }
+      spawnCmd = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`;
+      spawnArgs = [
+        "/d",
+        "/s",
+        "/c",
+        buildWindowsShellCommand(resolved.resolvedPath, args)
+      ];
+      windowsVerbatimArguments = true;
+    } else {
+      ensureUtf8ConsoleCodePageOnce();
+      spawnCmd = resolved.resolvedPath;
+      spawnArgs = args;
+    }
+    const result = spawnSync(spawnCmd, spawnArgs, {
+      ...options,
+      cwd: spawnCwd,
+      env: spawnEnv,
+      encoding: "utf-8",
+      shell: false,
+      windowsHide: true,
+      windowsVerbatimArguments
+    });
+    const spawnFailure = result.error ? classifySpawnFailureSync(result.error, { command, cwd: options?.cwd }) : undefined;
+    return {
+      stdout: result.stdout?.toString() || "",
+      stderr: result.stderr?.toString() || "",
+      status: result.status,
+      error: result.error,
+      ...spawnFailure ? { failure: "spawn", spawnFailure } : {}
+    };
+  }
+  const result = spawnSync(command, args, {
+    ...options,
+    env: spawnEnv,
+    encoding: "utf-8",
+    shell: false,
+    windowsHide: true
+  });
+  const spawnFailure = result.error ? classifySpawnFailureSync(result.error, { command, cwd: options?.cwd }) : undefined;
+  return {
+    stdout: result.stdout?.toString() || "",
+    stderr: result.stderr?.toString() || "",
+    status: result.status,
+    error: result.error,
+    ...spawnFailure ? { failure: "spawn", spawnFailure } : {}
+  };
+}
+export function isCommandAvailable(command) {
+  const result = safeSpawn(process.platform === "win32" ? "where" : "which", [command], { timeout: 5000 });
+  return result.status === 0;
+}
+export function findCommand(command) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const result = safeSpawn(finder, [command], { timeout: 5000 });
+  if (result.status !== 0)
+    return null;
+  return result.stdout.trim().split(`
+`)[0] || null;
+}