ccdeck 3.29.11 → 3.31.0

package/src/server/login-service.mjs

@@ -456,8 +456,9 @@ export function installService({
  * ASKED, NOT INFERRED FROM THE REFUSAL. schtasks exits 1 for a missing task and
  * for a permission it does not have, and the two are told apart only by an
  * English sentence that is not English on a localised Windows — the same trap
- * `looksMissing` in exec.mjs documents. So the task is queried first, which is
- * one extra call and an answer that does not depend on the machine's language.
+ * `looksMissing` in exec-not-found.mjs documents. So the task is queried first,
+ * which is one extra call and an answer that does not depend on the machine's
+ * language.
  */
 export function uninstallService({
   platform = process.platform,

package/src/server/macmon.mjs

@@ -26,7 +26,7 @@
 // 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 { renameWithRetry } from "./atomic-write.mjs";
 import { existsSync } from "node:fs";
 import { chmod, copyFile, mkdir, mkdtemp, open, rm, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";

package/src/server/memory-files.mjs

@@ -0,0 +1,163 @@
+// Which memory files a session has in scope: the CLAUDE.md family for a Claude
+// session and AGENTS.md for a Codex one, found by the walk both CLIs make from
+// the working directory up to the filesystem root, plus the user-global file
+// each one adds — and, for Claude, the per-project auto-memory directory.
+//
+// These lived in src/server/session-enrichment.mjs, beside the context pass
+// that sends their answer on, and they read no transcript: they stat a working
+// tree. So they moved on their own, and session-enrichment.mjs imports the two
+// scans its context passes call. index.mjs still re-exports both. The bodies
+// are unchanged.
+import { readdir, stat } from "node:fs/promises";
+import { join, resolve, dirname as pdirname } from "node:path";
+import { ccProjectSlug, claudeConfigDir } from "./claude-dir.mjs";
+import { CODEX_HOME } from "./codex-dir.mjs";
+
+/**
+ * Candidate memory-file paths on the walk from `cwd` up to the filesystem root.
+ *
+ * Both CLIs load their memory file the same way — nearest-first from the
+ * working directory outwards — and differ only in what the file is CALLED and
+ * in what else they add on top, so the walk is written once here and the two
+ * scanners below supply their own names. `rels` is a list of paths RELATIVE to
+ * each directory on the walk rather than bare filenames, because CC also honours
+ * `.claude/CLAUDE.md` at every level and Codex does not.
+ *
+ * Sixteen levels is the same depth this has always used: deep enough for any
+ * real checkout, shallow enough that a cwd on a network mount cannot turn one
+ * context read into an unbounded number of stat() calls.
+ *
+ * Returns paths without touching the disk. Statting them is collectMemoryFiles'
+ * job, so a caller that wants to add its own paths — a user-global file, a
+ * per-project memory directory — can splice them into one ordered list and get
+ * a single de-duplicated, existence-checked answer back.
+ */
+function memoryWalkPaths(cwd, rels) {
+  const out = [];
+  let dir = resolve(cwd);
+  for (let depth = 0; depth < 16; depth++) {
+    for (const rel of rels) out.push(join(dir, rel));
+    const parent = pdirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return out;
+}
+
+/**
+ * Which of `paths` are real, non-empty files, in the order given and with
+ * duplicates dropped.
+ *
+ * A zero-byte file is skipped on purpose: it contributes nothing to the model's
+ * context, and listing it in the modal would have the reader looking for the
+ * bytes it claims to cost. A path that cannot be stat()ed is simply absent —
+ * this runs against a tree another process is editing, and a permissions error
+ * on one candidate is no reason to lose the other fifteen.
+ */
+async function collectMemoryFiles(paths) {
+  const found = [];
+  const seen = new Set();
+  for (const p of paths) {
+    if (seen.has(p)) continue;
+    seen.add(p);
+    try {
+      const s = await stat(p);
+      if (s.isFile() && s.size > 0) found.push({ path: p, bytes: s.size });
+    } catch {}
+  }
+  return found;
+}
+
+/** The memory files a CLAUDE session has in scope. Exported alongside its Codex
+ *  counterpart below so a test can check the pair together — the two must agree
+ *  on the walk and disagree on the filename, and only one of them showing up in
+ *  a test is how they would drift. */
+export async function scanClaudeMdFiles(cwd) {
+  if (!cwd || typeof cwd !== "string") return [];
+  // The CONFIG dir, not the home directory. CLAUDE_CONFIG_DIR relocates it
+  // wholesale — it replaces ~/.claude rather than overlaying it — so on a
+  // machine where it is set, `homedir()/.claude` is a directory Claude Code
+  // does not read. Spelling it by hand here failed in both directions at once:
+  // the user-global memory file and every auto-memory file went missing from
+  // the modal and from the byte total beside it, while a stale ~/.claude left
+  // over from before the variable was set got listed as if it were in context.
+  // Resolved per call, like every other claudeConfigDir() reader in
+  // src/server, so nothing captures the answer from an environment that has
+  // moved.
+  const cfg = claudeConfigDir();
+  // Walk up from cwd to filesystem root, checking the canonical CC memory
+  // filenames plus CLAUDE.local.md (user-private) at each level.
+  //
+  // The `.claude/` prefix on the last two is NOT the config dir wearing a
+  // second spelling: it is CC's per-directory project convention, one such
+  // folder per level of the walk, and it stays literal however the config dir
+  // moves.
+  const paths = memoryWalkPaths(cwd, [
+    "CLAUDE.md",
+    "CLAUDE.local.md",
+    join(".claude", "CLAUDE.md"),
+    join(".claude", "CLAUDE.local.md"),
+  ]);
+  // User-global memory.
+  paths.push(join(cfg, "CLAUDE.md"));
+  paths.push(join(cfg, "CLAUDE.local.md"));
+  // Per-project auto-memory: $CLAUDE_CONFIG_DIR/projects/<slug>/memory/*.md
+  // (plus MEMORY.md index). CC injects these into context for sessions whose
+  // cwd matches the slug. That directory sits beside the <sessionId>.jsonl
+  // transcripts, so it moves with the config dir by construction.
+  const slug = ccProjectSlug(cwd);
+  if (slug) {
+    const memDir = join(cfg, "projects", slug, "memory");
+    try {
+      const entries = await readdir(memDir);
+      for (const f of entries) {
+        if (f.toLowerCase().endsWith(".md")) paths.push(join(memDir, f));
+      }
+    } catch {}
+  }
+  return collectMemoryFiles(paths);
+}
+
+/**
+ * The memory files a CODEX session has in scope: AGENTS.md, not CLAUDE.md.
+ *
+ * WHY THIS FUNCTION EXISTS AT ALL (#399). The context modal's third section was
+ * fed by scanClaudeMdFiles for every session regardless of provider, so the
+ * moment the donut became reachable for Codex the modal would have told a Codex
+ * user "No CLAUDE.md files found on the path from cwd to ~/.claude" — naming a
+ * file and a directory Codex does not read. Before this, `AGENTS.md` did not
+ * appear anywhere in this repository.
+ *
+ * That Codex reads it is not an assumption. Sampled every rollout under this
+ * machine's CODEX_HOME (structural search, no record content printed): the
+ * literal string `AGENTS.md` appears on 9 lines across 5 of the 8 files — in the
+ * `response_item/message` role=user preamble Codex prepends to a turn, in a
+ * role=developer message, and in a `world_state` record — while `CLAUDE.md`
+ * appears on zero lines in any of them.
+ *
+ * WHY THE FILESYSTEM AND NOT THE ROLLOUT. The rollout does name the files, but
+ * only inside message TEXT, and reading the text of a user's conversation to
+ * find a filename is not a trade this deck makes anywhere else — the Claude side
+ * has always answered the same question by walking the filesystem, and the two
+ * halves of one modal section should be derived the same way or the reader
+ * cannot compare them.
+ *
+ * CODEX_HOME comes from codex-dir.mjs like every other Codex path in the
+ * process (#375), so a relocated Codex home is honoured here without this
+ * module growing a sixth spelling of the rule.
+ *
+ * Exported for the tests, like readContextFromTranscript in
+ * session-enrichment.mjs: the rule for which files a session has in scope is
+ * worth pinning directly, rather than through a watcher, a temp home and a
+ * 1.5s poll.
+ */
+export async function scanAgentsMdFiles(cwd) {
+  if (!cwd || typeof cwd !== "string") return [];
+  // Codex has no `.codex/AGENTS.md` per-directory convention to mirror CC's
+  // `.claude/CLAUDE.md`, so the per-level list is the single filename.
+  const paths = memoryWalkPaths(cwd, ["AGENTS.md"]);
+  // The user-global instructions file, which Codex loads for every session
+  // whatever the cwd — the counterpart of ~/.claude/CLAUDE.md.
+  paths.push(join(CODEX_HOME, "AGENTS.md"));
+  return collectMemoryFiles(paths);
+}

package/src/server/memory-metrics.mjs

@@ -0,0 +1,178 @@
+// The memory section's sources: how much memory a new process could really get,
+// and how much swap — commit charge, on Windows — is in use.
+//
+// Moved out of system-metrics.mjs unchanged. The sampler there decides when to
+// ask — every MEM_INTERVAL_MS, never on the CPU tick — and what a reading that
+// failed does to the meter and to the history (sampleMemory, #789). This file
+// only answers: readAvailable and readSwap return a reading or null per call,
+// and keep nothing between calls.
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import { run } from "./metrics-run.mjs";
+
+/**
+ * Bytes of memory a new process could actually get, per platform.
+ *
+ * `os.freemem()` is the obvious call and it is the wrong one on two of the three
+ * platforms, because "free" and "available" are different questions. Pages
+ * holding cached files or inactive anonymous memory are not free, but the kernel
+ * will hand them over the moment something asks. Reporting them as used is what
+ * makes the naive `(total - free) / total` read 99.5% on an idle 32 GB Mac — a
+ * number that would send the reader straight to Activity Monitor, which is the
+ * one outcome this readout exists to prevent.
+ *
+ *   linux   /proc/meminfo MemAvailable — the kernel's own answer, a file read
+ *   win32   os.freemem() already reports available physical memory
+ *   darwin  vm_stat, because nothing in Node exposes the page classes
+ *
+ * Only darwin costs a subprocess, and only at MEM_INTERVAL_MS.
+ */
+/**
+ * Available bytes out of `/proc/meminfo` text, or null when the field is absent.
+ *
+ * Pure and exported for the same reason codexHome() takes a platform: a Linux
+ * answer has to be checkable from a Mac, and the only alternative is trusting
+ * that a regex nobody has run is right.
+ */
+export function availableFromMeminfo(text) {
+  const m = /^MemAvailable:\s+(\d+)\s*kB/m.exec(String(text ?? ""));
+  return m ? Number(m[1]) * 1024 : null;
+}
+
+/**
+ * Available bytes out of `vm_stat` output, or null when it does not parse.
+ *
+ * Everything the kernel can hand over without swapping: genuinely free pages,
+ * read-ahead it can drop, inactive anonymous pages, and purgeable caches. This
+ * is the number `os.freemem()` is missing — it reports only the first of the
+ * four, which is why the naive formula reads ~99% on an idle 32 GB Mac.
+ */
+export function availableFromVmStat(text, total) {
+  const out = String(text ?? "");
+  const pageSize = Number(/page size of (\d+) bytes/.exec(out)?.[1]) || 4096;
+  const pages = name => {
+    const m = new RegExp(`^Pages ${name}:\\s+(\\d+)`, "m").exec(out);
+    return m ? Number(m[1]) : 0;
+  };
+  const reclaimable = pages("free") + pages("speculative")
+    + pages("inactive") + pages("purgeable");
+  if (reclaimable <= 0) return null;
+  const avail = reclaimable * pageSize;
+  return total != null && avail > total ? null : avail;
+}
+
+/**
+ * How much memory is really available, or NULL when this machine could not be
+ * asked.
+ *
+ * `os.freemem()` USED TO BE THE FALLBACK ON BOTH REAL PLATFORMS, and it is the
+ * one number this function exists to avoid (#789). The header above says why:
+ * counting only genuinely free pages makes the naive `(total - free) / total`
+ * read 99.5% on an idle 32 GB Mac — "a number that would send the reader
+ * straight to Activity Monitor, which is the one outcome this readout exists to
+ * prevent". So a failed measurement produced exactly the reading the module was
+ * written to suppress.
+ *
+ * And it did not merely flicker. `record` folds into the minute bucket by
+ * MAXIMUM, so one failed poll painted a red 99% peak on the memory chart that
+ * survived every good sample for the next twenty-four hours. The failure is
+ * ordinary: `run` resolves null on a spawn error (EAGAIN/EMFILE under fork
+ * pressure — a deck watching many agents is exactly that), on a non-zero exit,
+ * and on its own 2s deadline. 2,880 chances a day.
+ *
+ * Null instead, and the caller keeps the previous reading and records nothing.
+ * A gap in the chart is honest; a 99% peak is not.
+ *
+ * The last branch still answers `freemem()` because on Windows there is no
+ * better source to have failed — it is the measurement, not a substitute for
+ * one.
+ */
+export async function readAvailable(platform = process.platform) {
+  const total = os.totalmem();
+
+  if (platform === "linux") {
+    try {
+      const parsed = availableFromMeminfo(await readFile("/proc/meminfo", "utf8"));
+      if (parsed != null) return parsed;
+    } catch { /* unreadable /proc — say so rather than guessing */ }
+    return null;
+  }
+
+  if (platform === "darwin") {
+    const out = await run("vm_stat", []);
+    return (out ? availableFromVmStat(out, total) : null) ?? null;
+  }
+
+  return os.freemem();
+}
+
+/**
+ * Swap out of macOS `sysctl -n vm.swapusage`, which prints
+ * `total = 14336.00M  used = 12876.00M  free = 1460.00M  (encrypted)`.
+ *
+ * Swap is the reading a percentage cannot give you. A machine at "64% memory
+ * used" that is quietly paging 12 GB to disk is not the same machine as one at
+ * 64% with an empty swap file, and the difference is the one you can feel.
+ */
+export function swapFromSysctl(text) {
+  const unit = s => {
+    // `,` as well as `.`: C_LOCALE should mean this never arrives, and a parser
+    // that fails closed on a whole continent's default is not a thing to leave
+    // resting on one environment variable. Safe to accept both here because
+    // sysctl formats with printf's %f, which never groups thousands — so a
+    // comma in this field can only ever be the decimal point.
+    const m = /^([\d.,]+)([KMG])?$/i.exec(s);
+    if (!m) return null;
+    const mult = { k: 1024, m: 1024 ** 2, g: 1024 ** 3 }[(m[2] || "M").toLowerCase()] ?? 1;
+    return Math.round(Number(m[1].replace(",", ".")) * mult);
+  };
+  const total = unit(/total\s*=\s*(\S+)/i.exec(String(text ?? ""))?.[1] ?? "");
+  const used = unit(/used\s*=\s*(\S+)/i.exec(String(text ?? ""))?.[1] ?? "");
+  if (total == null || used == null) return null;
+  return { total, used };
+}
+
+/** Swap out of `/proc/meminfo`, where it is two fields rather than one line. */
+export function swapFromMeminfo(text) {
+  const s = String(text ?? "");
+  const total = /^SwapTotal:\s+(\d+)\s*kB/m.exec(s);
+  const free = /^SwapFree:\s+(\d+)\s*kB/m.exec(s);
+  if (!total || !free) return null;
+  const t = Number(total[1]) * 1024;
+  return { total: t, used: Math.max(0, t - Number(free[1]) * 1024) };
+}
+
+/**
+ * Windows has no swap file in the Unix sense; the comparable pressure signal is
+ * commit charge, which `Win32_OperatingSystem` reports as total and free
+ * virtual memory in KB. Labelled "commit" in the UI rather than "swap", because
+ * calling it swap would be borrowing a word for a different mechanism.
+ */
+export function swapFromWmicJson(json) {
+  try {
+    const o = typeof json === "string" ? JSON.parse(json) : json;
+    const total = Number(o?.TotalVirtualMemorySize) * 1024;
+    const free = Number(o?.FreeVirtualMemory) * 1024;
+    if (!Number.isFinite(total) || !Number.isFinite(free) || total <= 0) return null;
+    return { total, used: Math.max(0, total - free) };
+  } catch { return null; }
+}
+
+export async function readSwap(platform = process.platform) {
+  if (platform === "darwin") {
+    const out = await run("sysctl", ["-n", "vm.swapusage"]);
+    return out ? swapFromSysctl(out) : null;
+  }
+  if (platform === "linux") {
+    try { return swapFromMeminfo(await readFile("/proc/meminfo", "utf8")); }
+    catch { return null; }
+  }
+  if (platform === "win32") {
+    const out = await run("powershell.exe", [
+      "-NoProfile", "-NonInteractive", "-Command",
+      "Get-CimInstance Win32_OperatingSystem | Select-Object TotalVirtualMemorySize,FreeVirtualMemory | ConvertTo-Json -Compress",
+    ], 4_000);
+    return out ? swapFromWmicJson(out.trim()) : null;
+  }
+  return null;
+}

package/src/server/metrics-history.mjs

@@ -0,0 +1,94 @@
+// The Machine panel's history: a day of minute buckets that every section
+// records into, and the reads its charts are drawn from.
+//
+// Moved out of system-metrics.mjs unchanged, so that a sampler lifted out of it
+// can record here without importing the sampler back — which would be a cycle
+// in src/server, the thing boot-module-graph.test.ts exists to refuse. The
+// sampler still decides what is recorded and when, builds each section's series
+// out of these reads, and answers /api/system/history (historySnapshot). This
+// file holds the ring, and nothing outside it touches the array: record writes
+// it, three named reads answer from it, and resetHistory empties it.
+
+/** Minute buckets, oldest first, for every section that keeps a history.
+ *  See HISTORY_MINUTES. */
+const history = [];
+
+/**
+ * How much history the panel keeps, and why it is bucketed by minute.
+ *
+ * Each section answers "what is it now"; the chart behind it answers "what did
+ * it do while that build was running", which is a different question and the
+ * reason a section opens one at all. 1440 minutes is a day, which covers "since
+ * the deck started" for every session anybody actually has.
+ *
+ * A bucket holds the MAXIMUM of its minute, never the mean, and that choice is
+ * the same one for every series here. A machine that touched 94°C for twenty
+ * seconds and sat at 60 for the rest of the minute averages to 66 and reads as
+ * calm; a load average that spiked to 114 between two quiet stretches averages
+ * away entirely. The spike is what somebody opens a chart to find.
+ *
+ * Kept out of systemSnapshot deliberately. That endpoint is polled every three
+ * seconds by a topbar meter that draws none of this; a day of buckets on every
+ * one of those responses would be the largest thing the deck sends, for charts
+ * that are usually closed. It has its own route, like the process list.
+ */
+const HISTORY_MINUTES = 1440;
+export const BUCKET_MS = 60_000;
+
+/**
+ * Fold one reading into the minute it belongs to, under a namespaced key.
+ *
+ * Keys are namespaced by section (`thermal:GPU`, `cpu:all`, `mem:swap`) rather
+ * than kept in four rings, because they all share one clock: a bucket is a
+ * minute of this machine, and every series that has something to say about that
+ * minute says it in the same place. The sections sample at different rates —
+ * CPU every three seconds, thermal every ten, memory every thirty — and folding
+ * by maximum makes that difference invisible to the reader, which is what it
+ * should be.
+ */
+export function record(key, value, nowMs = Date.now()) {
+  if (!Number.isFinite(value)) return;
+  const minute = Math.floor(nowMs / BUCKET_MS);
+  let last = history[history.length - 1];
+  if (!last || last.m !== minute) {
+    last = { m: minute, v: {} };
+    history.push(last);
+    while (history.length > HISTORY_MINUTES) history.shift();
+  }
+  const prev = last.v[key];
+  last.v[key] = prev == null ? value : Math.max(prev, value);
+}
+
+/** Every reading recorded under `key`, oldest first, one point per minute that
+ *  has one. */
+export function pointsOf(key) {
+  return history.filter(b => b.v[key] != null)
+    // Timestamps rather than indices: a bucket only exists for a minute that was
+    // sampled, so a gap — the machine asleep, the process paused — stays a gap
+    // rather than becoming a straight line across it.
+    .map(b => ({ t: b.m * BUCKET_MS, v: b.v[key] }));
+}
+
+/** What follows `prefix` in every key recorded under it, in the order each
+ *  first appeared — a series per sensor, however late the sensor turned up. */
+export function labelsUnder(prefix) {
+  const labels = [];
+  for (const b of history) {
+    for (const k of Object.keys(b.v)) {
+      if (!k.startsWith(prefix)) continue;
+      const label = k.slice(prefix.length);
+      if (!labels.includes(label)) labels.push(label);
+    }
+  }
+  return labels;
+}
+
+/** Where the oldest minute still held begins, or 0 before anything is. */
+export function oldestBucketMs() {
+  return history.length ? history[0].m * BUCKET_MS : 0;
+}
+
+/** Empty the ring. See stopSystemMetrics, which is the one caller. */
+export function resetHistory() {
+  history.length = 0;
+}

package/src/server/metrics-run.mjs

@@ -0,0 +1,100 @@
+// How the Machine panel's readers run a command: no shell, a forced number
+// format, stdout or null, and a deadline that kills the child rather than
+// waiting on it.
+//
+// Moved out of system-metrics.mjs unchanged, so that a reader lifted out of the
+// sampler can share the one runner without importing the sampler back — which
+// would be a cycle in src/server, the thing boot-module-graph.test.ts exists to
+// refuse. It is not exec.mjs's `run` and should not become it: that one is for
+// the tools the deck manages, resolves Windows shims and PATHEXT, and answers a
+// result object; this one only ever runs a system binary and answers its stdout,
+// or null, which is all a sampler can use.
+import { spawn } from "node:child_process";
+
+/**
+ * The locale every child of this module runs in — and only the part of it that
+ * had to be forced.
+ *
+ * Not a preference. Every command spawned here has its output read by a regex
+ * and every one of those regexes reads a number with a `.` in it. `ps` and
+ * `sysctl` honour LC_NUMERIC, so on a machine set to de_DE, fr_FR, ru_RU or
+ * pt_BR — comma is the decimal separator for most of Europe and Latin America —
+ * the same commands print:
+ *
+ *     ps      1   0,2  0,0 /sbin/launchd
+ *     sysctl  total = 8192,00M  used = 7189,75M  free = 1002,25M
+ *
+ * and the parsers matched nothing at all. Not partially: `parsePsProcesses`
+ * `continue`s on every row, so the process panel was permanently empty, and
+ * `swapFromSysctl` returned null, so the macOS swap meter was permanently
+ * blank. Silently, on a machine where everything else worked.
+ *
+ * THIS USED TO FORCE THE WHOLE LOCALE, and forcing the whole locale also forces
+ * the CHARACTER SET. Under `LC_ALL=C`, `ps` escapes every byte it cannot render
+ * as ASCII, so an application named in Cyrillic came back as
+ *
+ *     M-PM-/M-PM-=M-PM-4M-PM-5M-PM-:M-QM^A M-PM^\M-QM^CM-PM-7M-QM^KM-PM-:M-PM-0
+ *
+ * where the name is `Яндекс Музыка`. The panel truncates at 164px so it read as
+ * noise; the process list added in #738 has room for all ninety-one characters
+ * of it, which is how it was found. Every reader with a non-Latin application
+ * on their machine was being shown that.
+ *
+ * So only the numeric is forced now, and the character set is inherited. All
+ * four measured on this machine:
+ *
+ *     LC_ALL=C                        name mangled,  0.7
+ *     LC_ALL="" LC_NUMERIC=C          Яндекс Музыка, 0.7
+ *     LANG=de_DE + our override       Яндекс Музыка, 0.7   ← the comma case
+ *     LC_ALL=de_DE + our empty LC_ALL                0.7   ← a hostile env
+ *
+ * The empty `LC_ALL` is doing real work in the last of those: POSIX ignores an
+ * empty LC_ALL, so clearing it is what stops a user's own LC_ALL from
+ * outranking the LC_NUMERIC below. Setting LC_NUMERIC alone would not survive
+ * it.
+ *
+ * A reader whose own locale is C still sees the escaped form — but so does
+ * their terminal, so that is their machine being consistent rather than this
+ * module choosing for them.
+ *
+ * Meaningless on Windows, where the readers' branches are PowerShell piped
+ * through ConvertTo-Json and already culture-invariant — and harmless there for
+ * the same reason. The comma tolerance in their parsers stays as defence in
+ * depth for a sandbox that strips the environment, not as the primary answer.
+ */
+const C_LOCALE = { LC_ALL: "", LC_NUMERIC: "C" };
+
+/** Run a command and resolve its stdout, or null. Never rejects, never inherits
+ *  a shell, never inherits a locale, and is killed rather than allowed to hang
+ *  the sampler. */
+export function run(file, args, timeoutMs = 2_000) {
+  return new Promise(resolve => {
+    let child;
+    try {
+      child = spawn(file, args, {
+        windowsHide: true,
+        env: { ...process.env, ...C_LOCALE },
+        // stderr is PIPED AND NEVER READ, which is a deadlock waiting for a
+        // chatty child: a pipe nobody drains fills at 64 KB and the writer
+        // blocks there until this function's own deadline kills it. Nothing
+        // here has ever looked at it — `run` resolves on stdout or null — so
+        // the honest arrangement is not to open it.
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+    }
+    catch { return resolve(null); }
+    let out = "";
+    const timer = setTimeout(() => { try { child.kill(); } catch {} resolve(null); }, timeoutMs);
+    // DECODE THE STREAM, NOT EACH CHUNK. `out += d` on a Buffer calls toString()
+    // per chunk, and a chunk boundary falls wherever the pipe happened to break
+    // — measured on `ps` output as three chunks of 8192/8192/5718 — so a
+    // multi-byte character split across two of them became two replacement
+    // characters. An application called `Яндекс Музыка` in the process list
+    // rendered as `Ян��екс Музыка`. setEncoding carries the partial sequence
+    // across the boundary, which is the whole reason it exists.
+    child.stdout?.setEncoding?.("utf8");
+    child.stdout?.on("data", d => { out += d; });
+    child.on("error", () => { clearTimeout(timer); resolve(null); });
+    child.on("close", code => { clearTimeout(timer); resolve(code === 0 ? out : null); });
+  });
+}