agent-dag 3.22.0 → 3.22.3

package/src/server/macmon.mjs

@@ -1,310 +0,0 @@
-// The one thermal reading a Mac will not give up on its own.
-//
-// #747. On Apple Silicon there is no command shipped with macOS that prints a
-// CPU or GPU temperature. `powermetrics` needs root. `pmset -g therm` records
-// nothing on M-series and answers "No CPU power status has been recorded", so
-// there is no throttle row either. The AGX driver does not publish the
-// `"Temperature(C)"` that ioreg reads on Intel GPUs. And the SMC keys changed
-// with M1 and are inconsistent between models sharing one chip — an M1 Mac mini
-// uses different FourCCs from an M1 MacBook Pro, with no public mapping — so
-// there is nothing to hard-code either.
-//
-// The sensors are reachable, and without root: they come through a HID sensor
-// hub, which is a private C API. Every tool that shows a temperature on Apple
-// Silicon calls it, and every one of them is native code. A Node process cannot,
-// and this package has zero runtime dependencies, which is worth more than a
-// number.
-//
-// So it asks a tool the user already has, exactly the way the deck already asks
-// `cswap` about accounts and `ccusage` about spend. `macmon` is in
-// homebrew-core — `brew install macmon`, no third-party tap — runs without
-// sudo, supports M1 through M5, and prints JSON.
-//
-// COSTS INTEL NOTHING. This is reached only when ioreg has already answered
-// with nothing, which on an Intel Mac it never does. Deliberately not gated on
-// `process.arch`: a Node built for x64 running under Rosetta on an Apple
-// Silicon Mac reports "x64", and gating on that would skip the one machine this
-// exists for.
-import { run } from "./exec.mjs";
-import { renameWithRetry } from "./installer.mjs";
-import { existsSync } from "node:fs";
-import { chmod, copyFile, mkdir, mkdtemp, open, rm, writeFile } from "node:fs/promises";
-import { createHash } from "node:crypto";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-const TOOL_DIR   = join(homedir(), ".agents-deck", "tools");
-const MACMON_DIR = join(TOOL_DIR, "macmon");
-
-/** Where the deck puts its own copy, and where brew puts one on both prefixes —
- *  because ~/.local/bin's lesson applies here too: a tool the user installed is
- *  not always on the PATH of the shell that launched the deck. Ours first, so a
- *  machine that has both uses the one whose version this code was written
- *  against. Apple Silicon's brew prefix before Intel's; that is the only
- *  machine that reaches this file. */
-export const MACMON_CANDIDATES = [
-  join(MACMON_DIR, "macmon"),
-  "/opt/homebrew/bin/macmon",
-  "/usr/local/bin/macmon",
-];
-
-/** One sample, then exit. `-i` is the sampling window and its default is a full
- *  second; 200ms is long enough for an average the tool is willing to publish
- *  and short enough that a poll every ten seconds costs nothing anybody can
- *  feel. */
-export const MACMON_ARGS = ["pipe", "-s", "1", "-i", "200"];
-
-/**
- * The resolution, remembered — including the failure.
- *
- * `null` means "not looked yet" and `false` means "looked, not there", which is
- * the distinction that keeps a machine without macmon from paying a lookup
- * every ten seconds forever. cswapBin memoizes only success and re-probes on
- * failure; that is right for a tool the deck installs and wrong for one it
- * never will.
- */
-let _bin = null;
-
-/** Forget it. For the test, and for the day something installs macmon while the
- *  deck is up — nothing calls this on that path yet, and it is one line. */
-export function resetMacmonBin() { _bin = null; }
-
-export async function macmonBin({
-  exists = existsSync, probe = defaultProbe, candidates = MACMON_CANDIDATES,
-} = {}) {
-  if (_bin !== null) return _bin || null;
-  // The bare name first, because PATH is the cheap answer and the one a user
-  // who installed it themselves will usually have.
-  if (await probe("macmon")) return (_bin = "macmon");
-  for (const c of candidates) {
-    if (exists(c) && await probe(c)) return (_bin = c);
-  }
-  _bin = false;
-  return null;
-}
-
-async function defaultProbe(bin) {
-  return (await run(bin, ["--version"], { timeout: 4_000 })).ok;
-}
-
-/**
- * CPU and GPU degrees out of one `macmon pipe` sample.
- *
- * The shape is `{ temp: { cpu_temp_avg, gpu_temp_avg } }`, both in Celsius —
- * read off macmon's own `TempMetrics` struct rather than guessed from an
- * example, because a field renamed upstream should read as "no sensor" and not
- * as zero.
- *
- * A zero is dropped rather than shown. macmon defaults both fields to 0.0 and
- * fills what it read, so a machine that answered for the CPU and not the GPU
- * arrives as `{ cpu_temp_avg: 47.3, gpu_temp_avg: 0 }` — and 0 °C is not a
- * reading, it is the absence of one wearing a number.
- */
-export function tempsFromMacmonJson(json) {
-  let d;
-  try { d = typeof json === "string" ? JSON.parse(json) : json; }
-  catch { return {}; }
-  const t = d?.temp;
-  if (!t || typeof t !== "object") return {};
-  const out = {};
-  for (const [key, field] of [["cpu", "cpu_temp_avg"], ["gpu", "gpu_temp_avg"]]) {
-    const v = Number(t[field]);
-    // The same plausibility floor the rest of the thermal code uses, stated
-    // here rather than imported so this module has no opinion to disagree with.
-    if (Number.isFinite(v) && v > 0 && v < 150) out[key] = Math.round(v);
-  }
-  return out;
-}
-
-/**
- * Ask macmon, or answer nothing.
- *
- * Never throws and never waits long: `run` does not reject, the sample is
- * capped, and a machine without macmon returns before it spawns anything at
- * all after the first lookup.
- */
-export async function readMacmonTemps(deps = {}) {
-  const bin = await macmonBin(deps);
-  if (!bin) return {};
-  const r = await run(bin, MACMON_ARGS, { timeout: 6_000 });
-  if (!r.ok) return {};
-  // `pipe` prints one JSON object per sample and `-s 1` asks for one, but a
-  // build that ever printed a banner first would put it on the same stream.
-  const line = r.stdout.split("\n").find(l => l.trim().startsWith("{"));
-  return line ? tempsFromMacmonJson(line) : {};
-}
-
-// ── fetching it, so the user does not have to ────────────────────────────────
-//
-// `npx ccdeck` should work, and on Apple Silicon "work" includes the two rows
-// this file exists for. Telling somebody to run a brew command first is a step,
-// and a step is a thing most people will not take.
-//
-// So the deck fetches macmon the same way it already fetches uv — see
-// uv-bootstrap.mjs, whose shape this follows including the parts that were
-// learned the hard way. NOT through Homebrew: a machine without brew would then
-// need brew installed first, which is a very large thing to do to somebody who
-// asked for a dashboard.
-//
-// WHAT MAKES THIS SAFE TO RUN ON SOMEBODY'S MACHINE, each verified against the
-// real release rather than assumed:
-//
-//   * There is a prebuilt binary. `macmon-v0.8.2.tar.gz`, 746 KB, containing a
-//     `Mach-O 64-bit executable arm64`. No compiler, no toolchain, no Rust.
-//   * There is a checksum. The release publishes no `.sha256` file, but the
-//     GitHub releases API carries a `digest` field per asset, and it matched
-//     the bytes actually downloaded. An unverified binary is not something to
-//     run on someone's machine, which is uv-bootstrap's rule and is kept here.
-//   * It will execute. Apple Silicon refuses an unsigned binary; this one is
-//     `adhoc, linker-signed`, which is what the Rust toolchain emits and what
-//     macOS accepts. And a programmatic download carries no
-//     com.apple.quarantine — only com.apple.provenance, which blocks nothing —
-//     so there is no Gatekeeper prompt and nothing for the user to click.
-//
-// NEVER ON THE BOOT'S CRITICAL PATH. It is started by the thermal sampler, on
-// the tick where it found no reading, and nothing waits for it. The boot was
-// just taught not to wait for an install (#742) and this does not undo that.
-
-const RELEASE_API = "https://api.github.com/repos/vladkens/macmon/releases/latest";
-const DOWNLOAD_TIMEOUT_MS = 60_000;
-
-/** One attempt per process. A machine that is offline, or behind a proxy that
- *  refuses GitHub, must not re-download every ten seconds for as long as the
- *  deck runs — and a success does not need a second attempt either. */
-let _fetched = false;
-
-/** Cleared with the resolution, so a test can run the whole thing twice. */
-export function resetMacmonFetch() { _fetched = false; }
-
-/**
- * The asset to download, out of what the release actually published.
- *
- * Pure and exported: this is the part that has to keep working when the project
- * changes its file names, and the only way to check that from here is to feed
- * it a release document. `digest` is `sha256:<hex>` — the prefix is part of the
- * field and dropping it silently would make every download fail verification.
- */
-export function macmonAsset(release) {
-  const tag = release?.tag_name;
-  const a = (release?.assets ?? []).find(x => typeof x?.name === "string" && x.name.endsWith(".tar.gz"));
-  if (!a?.browser_download_url) return null;
-  const m = /^sha256:([0-9a-f]{64})$/.exec(String(a.digest ?? ""));
-  if (!m) return null;
-  return { version: typeof tag === "string" ? tag : "unknown", url: a.browser_download_url, sha256: m[1] };
-}
-
-
-/**
- * Download macmon into ~/.agents-deck/tools/macmon.
- *
- * Returns `{ ok: true, bin, version }` or `{ ok: false, reason }`, and never
- * throws: every caller treats a missing macmon as an ordinary state.
- *
- * Apple Silicon only, because that is the only build published and the only
- * machine that has anything to gain — an Intel Mac already answers through
- * ioreg and never reaches this file at all.
- */
-export async function bootstrapMacmon({
-  platform = process.platform, arch = process.arch, env = process.env,
-  fetchFn = fetch, dir = MACMON_DIR, findBin = macmonBin,
-} = {}) {
-  if (platform !== "darwin") return { ok: false, reason: "unsupported_platform" };
-  // ARM64 ONLY, checked rather than merely documented. The release publishes
-  // one asset and it is an arm64 Mach-O, so an Intel Mac downloaded 746 KB it
-  // could not execute and failed its own --version check afterwards. That is
-  // the small half. The larger half is the promise: the README says an Intel
-  // Mac never downloads anything, and this reached api.github.com on any Mac
-  // whose sensors happened to stay silent — which an Intel Mac's do whenever
-  // ioreg publishes no Temperature(C).
-  if (arch !== "arm64") return { ok: false, reason: "unsupported_arch" };
-  // A macmon the user already has is the other thing the README promises to
-  // notice, and until now the skip was emergent rather than checked: a working
-  // copy produces a reading, the reading sets thermalEverAnswered, and the
-  // give-up branch never fires. That chain breaks on a macmon which runs but
-  // reports values this deck rejects as implausible — and then a machine with
-  // macmon on PATH downloaded a second one.
-  if (await findBin()) return { ok: false, reason: "already_installed" };
-  // Both switches, for the reason uv-bootstrap has both: downloading an
-  // executable is a bigger step than installing a package with a tool the user
-  // already chose, so somebody may want the managed installs and not this.
-  if (env.AGENTS_DECK_NO_INSTALL === "1") return { ok: false, reason: "installs_disabled" };
-  if (env.AGENTS_DECK_NO_DOWNLOAD === "1") return { ok: false, reason: "download_disabled" };
-  if (_fetched) return { ok: false, reason: "already_tried" };
-  _fetched = true;
-
-  let staging = null;
-  let partial = null;
-  try {
-    const res = await fetchFn(RELEASE_API, {
-      headers: { accept: "application/vnd.github+json", "user-agent": "agents-deck" },
-      signal: AbortSignal.timeout(10_000),
-    });
-    if (!res.ok) return { ok: false, reason: "release_lookup_failed" };
-    const asset = macmonAsset(await res.json());
-    // No published digest means no way to know what was downloaded. There is no
-    // fallback version here on purpose: uv can have one because any recent uv
-    // installs claude-swap, while a hard-coded macmon URL would be a checksum
-    // this file invented for bytes it has never seen.
-    if (!asset) return { ok: false, reason: "no_verifiable_asset" };
-
-    const dl = await fetchFn(asset.url, {
-      redirect: "follow",
-      headers: { "user-agent": "agents-deck" },
-      signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
-    });
-    if (!dl.ok) return { ok: false, reason: "download_failed" };
-    const archive = Buffer.from(await dl.arrayBuffer());
-    if (createHash("sha256").update(archive).digest("hex") !== asset.sha256) {
-      return { ok: false, reason: "checksum_mismatch" };
-    }
-
-    // mkdtemp under a directory the user already owns, for every reason
-    // uv-bootstrap gives: the name cannot be guessed, and mkdtemp CREATES
-    // rather than accepting a directory somebody else made.
-    // Staged beside the destination rather than in the system temp directory,
-    // so the rename below is same-filesystem and therefore atomic.
-    await mkdir(dir, { recursive: true });
-    staging = await mkdtemp(join(dir, "macmon-staging-"));
-    const archivePath = join(staging, "macmon.tar.gz");
-    await writeFile(archivePath, archive);
-    if (!(await run("tar", ["-xzf", archivePath, "-C", staging], { timeout: 60_000 })).ok) {
-      return { ok: false, reason: "extract_failed" };
-    }
-
-    // The archive is flat — readme.md, LICENSE, macmon — so this is a name
-    // rather than a search. It is checked instead of assumed because a layout
-    // change upstream should read as "not in the archive", not as a crash.
-    const found = join(staging, "macmon");
-    if (!existsSync(found)) return { ok: false, reason: "not_in_archive" };
-
-    // Copied to a name of its own inside the destination — same filesystem, so
-    // the rename below is the atomic kind — and only becomes `macmon` once it
-    // is whole, flushed, executable, and has answered `--version`. Interrupt
-    // this and all that is left is an inert temp file.
-    partial = join(dir, `.macmon-${process.pid}-${Date.now().toString(36)}`);
-    await copyFile(found, partial);
-    const handle = await open(partial, "r+");
-    try { await handle.sync(); } finally { await handle.close(); }
-    await chmod(partial, 0o755);
-
-    // The binary is adhoc/linker-signed and carries no quarantine, so this
-    // should simply run — and if some future build does not, the deck finds out
-    // here rather than by leaving a file every later boot trusts.
-    if (!(await run(partial, ["--version"], { timeout: 20_000 })).ok) {
-      return { ok: false, reason: "does_not_run" };
-    }
-
-    const dest = join(dir, "macmon");
-    await renameWithRetry(partial, dest);
-    partial = null;
-    // The resolution memo remembers a failure, and the failure it remembers is
-    // "there is no macmon". There is one now.
-    resetMacmonBin();
-    return { ok: true, bin: dest, version: asset.version };
-  } catch (err) {
-    return { ok: false, reason: "error", detail: String(err?.message ?? err).slice(0, 200) };
-  } finally {
-    if (staging) await rm(staging, { recursive: true, force: true, maxRetries: 10, retryDelay: 25 }).catch(() => {});
-    if (partial) await rm(partial, { force: true }).catch(() => {});
-  }
-}

package/src/server/npx.mjs

@@ -1,264 +0,0 @@
-// How to run npx from a supervisor that cannot afford npx to be broken.
-//
-// The supervisor's upgrade path is `npx -y <spec>@latest`, and it used to
-// resolve npx by bare name — `npx.cmd` on Windows — letting the OS find it on
-// PATH. That trusts a batch shim to be sitting in a real npm install root,
-// because the shim computes everything else from its own directory:
-//
-//   SET "NPX_CLI_JS=%~dp0\node_modules\npm\bin\npx-cli.js"
-//   SET "NPM_PREFIX_JS=%~dp0\node_modules\npm\bin\npm-prefix.js"
-//
-// Reported from a Windows machine on Node 24 where `%~dp0` was the user's home
-// directory and no `node_modules\npm` existed under it. Clicking
-// "Update & restart" printed a raw MODULE_NOT_FOUND stack trace and came back
-// on the same version.
-//
-// The cause was guessed at here as "an npm global prefix pointed somewhere the
-// shim did not follow", and #456 established it was not: `%~dp0` was the DECK'S
-// WORKING DIRECTORY, because a shim asked for by bare name has no directory in
-// its `%0` to be the drive-and-path of. Nothing about that machine's npm was
-// wrong. The correction lives in shimPath in exec.mjs, and the shim fallback
-// below now asks for the full path.
-//
-// Node ships npm, so npx's real entry point can be reached from
-// `process.execPath` with no PATH lookup, no batch file, and no shim-relative
-// arithmetic. That is what this prefers. The shim stays as the fallback for
-// installs whose npm lives somewhere else entirely, and it still goes through
-// spawnSpec — the cmd.exe quoting there is load-bearing and unchanged.
-//
-// The pre-flight fetch below goes through the very same launcher, for the same
-// reason stated the other way round: a supervisor that cannot afford npx to be
-// broken cannot afford to discover that it is only after it has stopped
-// serving. So the fetch happens first, and only a fetch that worked costs the
-// deck its listener.
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { killTree, shimPath, spawnSpec } from "./exec.mjs";
-
-/**
- * Where npm's own `npx-cli.js` sits relative to the running Node binary, most
- * likely first. Pure: the platform and the executable path are parameters, so
- * the Windows layout can be checked from any OS.
- *
- * Windows keeps npm beside node.exe (`C:\Program Files\nodejs\node_modules\npm`,
- * and the same shape under nvm-windows). POSIX puts it in a `lib` next to the
- * `bin` — usually the parent (`/usr/local/bin/node` →
- * `/usr/local/lib/node_modules/npm`, as for nvm, fnm and Volta), but not
- * always: Homebrew's node lives in `/usr/local/Cellar/node/<v>/bin` while its
- * npm stays at the prefix, four levels up. So the `lib` spelling is tried at
- * each of the first four ancestors rather than only at the parent. Every
- * candidate is confirmed by the exact file existing, so a wider search cannot
- * pick something that is not npm.
- *
- * The path arithmetic is done on the string rather than through `node:path`,
- * for the same reason npxRoot in self-update.mjs does: `path` here is the
- * platform running the SUITE, so a Windows layout checked from macOS would come
- * back with forward slashes and a `..` nothing resolves.
- */
-export function npxCliCandidates(execPath = process.execPath, platform = process.platform) {
-  if (typeof execPath !== "string" || !execPath) return [];
-  const sep = platform === "win32" ? "\\" : "/";
-  const dir = execPath.split(/[\\/]/);
-  dir.pop(); // the binary itself
-  if (!dir.length) return [];
-  const beside = [...dir, "node_modules", "npm", "bin", "npx-cli.js"].join(sep);
-  const above = [];
-  for (let up = 1; up <= 4 && dir.length - up > 0; up++) {
-    above.push([...dir.slice(0, -up), "lib", "node_modules", "npm", "bin", "npx-cli.js"].join(sep));
-  }
-  return platform === "win32" ? [beside, ...above] : [...above, beside];
-}
-
-/**
- * What to hand `spawn` to run `npx <args>`.
- *
- * Returns `{ file, args, opts, via }`, where `via` is "node" for the bundled
- * CLI and "shim" for the PATH lookup. `exists` is injected so the choice can be
- * tested without a matching Node install on the machine running the suite.
- */
-export function npxLaunch(args, {
-  platform = process.platform,
-  execPath = process.execPath,
-  exists = existsSync,
-  pathEnv,
-} = {}) {
-  for (const cli of npxCliCandidates(execPath, platform)) {
-    let found = false;
-    try { found = exists(cli); } catch { found = false; }
-    // Same node, same npm, spawned directly: nothing here reads PATH and
-    // nothing resolves a path relative to a shim's own directory.
-    if (found) return { file: execPath, args: [cli, ...args], opts: {}, via: "node", cli };
-  }
-  // The shim, and on Windows by its FULL path. A bare `npx.cmd` is what made
-  // the shim compute `%~dp0` — where it looks for npx-cli.js — from the deck's
-  // working directory rather than from its own, which is #456; shimPath in
-  // exec.mjs carries the account. The bare name stays as the last resort, so a
-  // layout the lookup cannot see is exactly as well off as it was before.
-  const shim = platform === "win32"
-    ? (shimPath("npx.cmd", { execPath, exists, ...(pathEnv === undefined ? {} : { pathEnv }) }) ?? "npx.cmd")
-    : "npx";
-  return { ...spawnSpec(shim, args, platform), via: "shim", cli: null };
-}
-
-// Long enough for a cold tarball on a slow line; short enough that a connection
-// hanging on a dead proxy does not hold the deck's Update button for the three
-// minutes the tab waits before giving up on its own.
-//
-// Not exported (#383): it is the default of `prefetch`'s `timeoutMs` parameter
-// and nothing else. A caller that wants a different budget passes one, and a
-// caller that wants this one passes nothing — there is no third caller for the
-// number to be worth naming across the module boundary.
-const PREFETCH_TIMEOUT_MS = 120_000;
-
-/**
- * What to hand npx to DOWNLOAD a spec without running it.
- *
- * The reason this is not simply `["-y", spec]`: that form is the upgrade
- * itself. npx resolves, unpacks AND executes the package's bin in one command,
- * so asking it "can you fetch this?" the obvious way starts a second deck —
- * which either binds the port the running one holds or, worse, does not, and
- * registers itself with the hooks anyway. Both are outages of their own.
- *
- * `--package` is the half that installs; `--call` is the half that runs, and
- * pointing it at a shell builtin is what makes the install the only effect. The
- * spec never appears as a positional argument, so no bin of ours is ever named,
- * let alone started.
- *
- * `exit 0` rather than anything more informative on purpose: npm runs the call
- * through its script shell — `sh -c` on POSIX, cmd.exe on Windows — and both
- * spell that builtin the same way. Anything that needed a program on PATH would
- * fail exactly where PATH is broken, which is the environment from #184 this
- * pre-flight most needs to answer honestly.
- */
-export function npxPrefetchArgs(spec) {
-  return ["-y", "--package", spec, "--call", "exit 0"];
-}
-
-/**
- * Resolve, download and unpack `spec` while the current deck keeps serving.
- *
- * Answers `{ ok, error, hint }` — never throws, because the caller's whole
- * reason for asking is that it must survive the answer being "no". A refusal
- * here costs the click; the alternative, which is what shipped before, was to
- * exit the worker first and discover offline, a proxy, an ETARGET or a broken
- * npx shim with the port already given up and the SSE stream already dropped.
- *
- * Nothing is echoed: the deck this runs alongside owns the terminal and is
- * still drawing its pulse line over the last row, so npm's progress output
- * would smear across it. The tail is kept only as evidence for a failure that
- * may not happen, and reduced to one line by npxFailureSummary when it does.
- *
- * `spawnFn` and `launch` are injected so the choice of launcher and the stdio
- * it is given can be asserted without a Node install to match, and `onChild`
- * hands the process out so a Ctrl+C arriving mid-fetch has something to kill.
- */
-export function npxPrefetch(spec, {
-  launch = npxLaunch,
-  spawnFn = spawn,
-  timeoutMs = PREFETCH_TIMEOUT_MS,
-  onChild = null,
-} = {}) {
-  return new Promise((resolve) => {
-    const { file, args, opts } = launch(npxPrefetchArgs(spec));
-    let child;
-    try {
-      child = spawnFn(file, args, { stdio: ["ignore", "pipe", "pipe"], ...opts });
-    } catch (err) {
-      resolve({ ok: false, error: `could not run npx: ${err?.message ?? err}`, hint: null });
-      return;
-    }
-    onChild?.(child);
-
-    let tail = "";
-    const keep = (d) => { tail = (tail + String(d)).slice(-8000); };
-    // Both streams, one buffer: npm writes its errors to stderr and its
-    // resolution notices to stdout, and which of the two carries the sentence
-    // worth quoting depends on the failure.
-    child.stdout?.on("data", keep);
-    child.stderr?.on("data", keep);
-
-    let settled = false;
-    const settle = (result) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve(result);
-    };
-    const timer = setTimeout(() => {
-      // killTree, not kill: on Windows the shim path puts cmd.exe between us
-      // and npm, so a plain kill stops the shell and leaves the download
-      // running — writing into the very cache directory the next attempt reads.
-      killTree(child);
-      settle({ ok: false, error: `fetching ${spec} timed out after ${Math.round(timeoutMs / 1000)}s`, hint: null });
-    }, timeoutMs);
-    timer.unref?.();
-
-    child.on("error", err => settle({ ok: false, error: `could not run npx: ${err?.message ?? err}`, hint: null }));
-    // 'close' rather than 'exit': 'exit' fires when the process ends and says
-    // nothing about its pipes, so past one pipe buffer the tail this kept —
-    // deliberately the TAIL, because npm's reason is on its last lines — was
-    // still only the first 8 KiB when npxFailureSummary read it. 'close' is
-    // emitted after both streams have been drained.
-    child.on("close", (code, signal) => {
-      if (code === 0) { settle({ ok: true, error: null, hint: null }); return; }
-      settle({
-        ok: false,
-        error: npxFailureSummary(tail) ?? `npx could not fetch ${spec} — exited ${code ?? signal}`,
-        hint: npxFailureHint(tail),
-      });
-    });
-  });
-}
-
-// Lines that are structure rather than content: a Node crash prints a stack,
-// the source line it threw on, a caret under it, then the error object's own
-// fields and the runtime version. None of that tells a user of a DAG dashboard
-// what went wrong.
-const NOISE = [
-  /^\s*at\s/,
-  /^\s*\^+\s*$/,
-  /^node:internal\//,
-  /^\s*throw\s/,
-  /^Node\.js v/,
-  /^\s*[{}]\s*$/,
-  /^\s*(code|errno|syscall|path|requireStack|stack):/,
-  /^A complete log/,
-];
-
-// The line worth quoting, when there is one. npm's failures and Node's both
-// lead with the sentence a person can act on; everything after it is detail.
-const SIGNAL = /(Error:|error code|ERR_|No matching version|ENOENT|EACCES|EPERM|not found|permission denied)/i;
-
-/**
- * One line summarising why an npx run failed, or null when its output said
- * nothing. Pure, and separate from the printing, because "do not dump a stack
- * trace at the user" is the rule and a rule worth a bug is worth a test.
- */
-export function npxFailureSummary(output) {
-  const lines = String(output ?? "")
-    .split(/\r?\n/)
-    // A warning is by definition not the reason this failed, and npm emits one
-    // for every ordinary exec ("the following package will be installed") whose
-    // wording would otherwise outrank the real error below it.
-    .filter(l => !/^npm (WARN|warn)\b/.test(l))
-    .map(l => l.replace(/^npm (ERR!|error)\s*/i, "").trimEnd())
-    .filter(l => l.trim() && !NOISE.some(re => re.test(l)));
-  if (!lines.length) return null;
-  const pick = lines.find(l => SIGNAL.test(l)) ?? lines[lines.length - 1];
-  return pick.trim().slice(0, 300);
-}
-
-/**
- * The actionable half, for the one failure shape that is a broken environment
- * rather than a broken network: npx exists, runs, and cannot find the npm it is
- * supposed to load. `npm config get prefix` is the thing to check — a prefix
- * pointing at a directory with no `node_modules/npm` under it leaves exactly
- * this trace.
- */
-export function npxFailureHint(output) {
-  const s = String(output ?? "");
-  if (/MODULE_NOT_FOUND/.test(s) && /(npx-cli\.js|npm-cli\.js|npm-prefix\.js)/.test(s)) {
-    return "the npx on PATH is a shim whose npm install is missing — check `npm config get prefix`";
-  }
-  return null;
-}