@duckmind/dm-linux-x64 0.65.8 → 0.66.2

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

@@ -1,1267 +0,0 @@
-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;
-}