@openmixer/plugin-qualify 0.18.4 → 0.19.1

package/tools/compare-run.mjs

@@ -0,0 +1,355 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+// `plugin-qualify compare` and `plugin-qualify compare summary`: the processes and the files. Every decision is in
+// src/compare.ts; this module finds the hosts and their versions, starts the private JACK server, runs
+// tools/compare-host.mjs for each plugin and host, and writes the records and the summary.
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, rmSync, statfsSync } from "node:fs";
+import { cpus, tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  COMPARISON_RECORD_SUFFIX,
+  COMPARISON_SUMMARY_FILE,
+  HOST_TRAITS,
+  comparisonFileName,
+  comparisonRecordOf,
+  comparisonRecordProblems,
+  compareHelpText,
+  discoverAllTargets,
+  clapLoader,
+  hostRowOf,
+  lv2Loader,
+  missingReferences,
+  notApplicableRow,
+  parseCompareArgs,
+  parseSummaryArgs,
+  presenceFromRecords,
+  resolveTargets,
+  sameConditions,
+  summarise,
+  summaryHelpText,
+  summaryTable,
+  writeFileWhole,
+} from "../dist/index.js";
+
+const DRIVER = fileURLToPath(new URL("./compare-host.mjs", import.meta.url));
+const log = (line) => process.stderr.write(`plugin-qualify compare: ${line}\n`);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const sh = (cmd, args) => spawnSync(cmd, args, { encoding: "utf8", timeout: 10000 });
+
+/** The installed package that owns a program, as "name version", from rpm or dpkg; else the program's own --version. */
+function versionOf(program, path) {
+  // a host built outside a package (Zynthian's mod-host in /usr/local/bin) is named by the one who runs the comparison
+  const named = process.env[`OMX_COMPARE_VERSION_${program.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`];
+  if (named) return `${program} ${named}`;
+  const rpm = sh("rpm", ["-qf", "--qf", "%{NAME} %{VERSION}-%{RELEASE}", path]);
+  if (rpm.status === 0 && rpm.stdout.trim()) return rpm.stdout.trim();
+  const dpkg = sh("dpkg-query", ["-S", path]);
+  if (dpkg.status === 0) {
+    const pkg = dpkg.stdout.split(":")[0].trim();
+    const v = sh("dpkg-query", ["-W", "-f", "${Version}", pkg]);
+    if (v.status === 0 && v.stdout.trim()) return `${pkg} ${v.stdout.trim()}`;
+  }
+  const own = sh(program, ["-V"]);
+  const line = `${own.stdout ?? ""}${own.stderr ?? ""}`.split("\n").find((l) => /\d+\.\d+/.test(l));
+  return line ? `${program} ${line.match(/\d+(\.\d+)+\S*/)[0]} (self-reported)` : null;
+}
+
+function presence(hosts) {
+  return hosts.map((host) => {
+    const program = HOST_TRAITS[host].program;
+    const w = sh("sh", ["-c", `command -v "$1"`, "sh", program]);
+    const path = w.status === 0 ? w.stdout.trim() : "";
+    if (!path) return { host, installed: false, version: null, reason: `${program} is not installed (not on PATH)` };
+    return { host, installed: true, version: versionOf(program, path) };
+  });
+}
+
+/** The private JACK server: dummy driver, the run's rate and quantum, a name of its own. */
+let jackSerial = 0;
+async function startJack(rate, quantum) {
+  const name = `cmp${String(process.pid)}_${String(jackSerial++)}`;
+  const env = { ...process.env, JACK_NO_START_SERVER: "1" };
+  // the server's output goes to a file, never to a pipe: this process waits on each host's run, a pipe it does not
+  // read fills, and a JACK server blocked writing its log stops answering
+  const logFile = join(tmpdir(), `plugin-qualify-${name}.log`);
+  const fd = openSync(logFile, "w");
+  const p = spawn("jackd", ["-n", name, "-d", "dummy", "-r", String(rate), "-p", String(quantum)], { stdio: ["ignore", fd, fd], detached: true, env });
+  closeSync(fd);
+  const lastLine = () => {
+    try {
+      return readFileSync(logFile, "utf8").trim().split("\n").filter((l) => !/lock down/.test(l)).pop() ?? "";
+    } catch {
+      return "";
+    }
+  };
+  let failed;
+  p.on("error", (e) => (failed = e.code));
+  p.on("exit", (c, s) => (failed = failed ?? s ?? `exit ${String(c)}`));
+  const probe = locateCompareTool();
+  for (let i = 0; i < 100 && failed === undefined; i++) {
+    const r = spawnSync(probe, ["ports"], { env: { ...env, JACK_DEFAULT_SERVER: name }, stdio: "ignore", timeout: 5000 });
+    if (r.status === 0) {
+      return {
+        name,
+        proc: p,
+        alive: () => failed === undefined && answers(name),
+        // SIGTERM first: a JACK server ended so removes its shared memory (100 MB at the defaults), which a killed one
+        // leaves in /dev/shm for the next server to run short of
+        stop: async () => {
+          try {
+            process.kill(-p.pid, "SIGTERM");
+          } catch {
+            return;
+          }
+          for (let i = 0; i < 50 && failed === undefined; i++) await sleep(100);
+          try {
+            process.kill(-p.pid, "SIGKILL");
+          } catch {}
+          rmSync(logFile, { force: true });
+        },
+      };
+    }
+    await sleep(100);
+  }
+  try {
+    process.kill(-p.pid, "SIGKILL");
+  } catch {}
+  throw new Error(`the private JACK server did not start (${failed ?? "no answer"}): ${lastLine()}`);
+}
+
+/** The server lists its ports within five seconds: a server that does not is not one to measure on. */
+function answers(name) {
+  const t0 = Date.now();
+  const r = spawnSync(locateCompareTool(), ["ports"], { env: { ...process.env, JACK_DEFAULT_SERVER: name, JACK_NO_START_SERVER: "1" }, encoding: "utf8", timeout: 20000, killSignal: "SIGKILL" });
+  if (r.status !== 0 || Date.now() - t0 > 2000) log(`the JACK server ${name} answered ${r.status === 0 ? "" : "nothing "}in ${String(Date.now() - t0)} ms${r.status === 0 ? "" : `: ${(r.stderr ?? "").trim().split("\n").pop() ?? r.error?.code ?? ""}`}`);
+  return r.status === 0;
+}
+
+function locateCompareTool() {
+  const dirs = [fileURLToPath(new URL("../native/build/", import.meta.url)), "/usr/libexec/plugin-qualify/", "/usr/lib/plugin-qualify/"];
+  return process.env.OMX_JACK_COMPARE || dirs.map((d) => `${d}jack_compare`).find((p) => existsSync(p)) || "jack_compare";
+}
+
+/** The real-time priority a process here may take: what the JACK server and the hosts were granted. */
+function realtimeGrant() {
+  try {
+    const line = readFileSync("/proc/self/limits", "utf8").split("\n").find((l) => l.startsWith("Max realtime priority"));
+    const soft = line?.split(/\s{2,}/)[1]?.trim();
+    return soft === "0" || soft === undefined ? "none (RLIMIT_RTPRIO 0: SCHED_OTHER)" : `rtprio ${soft}`;
+  } catch {
+    return "unknown";
+  }
+}
+
+/** The LV2 plugins lilv calls instruments: their stimulus is notes. */
+function lv2Instruments(uris) {
+  if (uris.length === 0) return new Set();
+  const py = [
+    "import json,sys",
+    `sys.path.insert(0, ${JSON.stringify(fileURLToPath(new URL(".", import.meta.url)))})`,
+    "from lilv_load import load_lilv",
+    "lilv=load_lilv()",
+    "w=lilv.World();w.load_all()",
+    "want=set(json.load(sys.stdin));out=[]",
+    "for p in w.get_all_plugins():",
+    "  u=str(p.get_uri())",
+    "  if u in want and str(p.get_class().get_uri()).endswith('#InstrumentPlugin'): out.append(u)",
+    "print(json.dumps(out))",
+  ].join("\n");
+  const r = spawnSync("python3", ["-c", py], { input: JSON.stringify(uris), encoding: "utf8", timeout: 120000 });
+  if (r.status !== 0) {
+    log(`the LV2 classes could not be read (${(r.stderr || "").trim().split("\n").pop()}): instruments are found by their ports`);
+    return new Set();
+  }
+  return new Set(JSON.parse(r.stdout));
+}
+
+// a CLAP target's uri is urn:clap:<id>; the hosts take clap:<path>#<id>
+const addSpec = (t) => (t.format === "clap" ? `clap:${t.binaryPath}#${t.uri.replace(/^urn:clap:/, "")}` : t.uri);
+
+function readRecords(dir) {
+  const out = [];
+  for (const f of existsSync(dir) ? readdirSync(dir).filter((n) => n.endsWith(COMPARISON_RECORD_SUFFIX)).sort() : []) {
+    const rec = JSON.parse(readFileSync(join(dir, f), "utf8"));
+    const problems = comparisonRecordProblems(rec);
+    if (problems.length) throw new Error(`${join(dir, f)}: ${problems.join("; ")}`);
+    out.push(rec);
+  }
+  return out;
+}
+
+function writeSummary(dir, records, present, meta, format) {
+  const summary = summarise(records, present, meta);
+  if (dir !== undefined) {
+    writeFileWhole(join(dir, COMPARISON_SUMMARY_FILE), `${JSON.stringify(summary, null, 2)}\n`);
+    log(`summary ${join(dir, COMPARISON_SUMMARY_FILE)}`);
+  }
+  process.stdout.write(format === "json" ? `${JSON.stringify(summary, null, 2)}\n` : summaryTable(summary));
+  return summary;
+}
+
+export async function compareSummaryMain(argv) {
+  const parsed = parseSummaryArgs(argv);
+  if (!parsed.ok) {
+    process.stderr.write(`plugin-qualify compare summary: ${parsed.error}\n\n${summaryHelpText()}`);
+    return 2;
+  }
+  if (parsed.args.help) {
+    process.stdout.write(summaryHelpText());
+    return 0;
+  }
+  const records = readRecords(parsed.args.dir);
+  if (records.length === 0) {
+    log(`no ${COMPARISON_RECORD_SUFFIX} in ${parsed.args.dir}`);
+    return 2;
+  }
+  const present = presenceFromRecords(records);
+  const missing = missingReferences(present);
+  if (parsed.args.publish && missing.length) {
+    for (const m of missing) log(`not publishable: ${m.host}: ${m.reason}`);
+    return 1;
+  }
+  writeSummary(parsed.args.dir, records, present, { hostClass: parsed.args.hostClass, set: parsed.args.set, publish: parsed.args.publish }, "text");
+  return 0;
+}
+
+export async function compareMain(argv) {
+  if (argv[0] === "summary") return compareSummaryMain(argv.slice(1));
+  const parsed = parseCompareArgs(argv);
+  if (!parsed.ok) {
+    process.stderr.write(`plugin-qualify compare: ${parsed.error}\n\n${compareHelpText()}`);
+    return 2;
+  }
+  const a = parsed.args;
+  if (a.help) {
+    process.stdout.write(compareHelpText());
+    return 0;
+  }
+  const present = presence(a.hosts);
+  for (const p of present) log(p.installed ? `host ${p.host}: ${p.version ?? "version unknown"}` : `host ${p.host}: skipped, ${p.reason}`);
+  const missing = missingReferences(present);
+  if (a.publish && missing.length) {
+    // a publishable comparison is against both references: refused before anything runs, each missing one named
+    for (const m of missing) log(`--publish refused: ${m.host}: ${m.reason}`);
+    log(`install them (see the README, "Compare with mod-host and jalv"), or run without --publish for a local look`);
+    return 1;
+  }
+  let targets;
+  if (a.all) targets = discoverAllTargets();
+  else {
+    // an LV2 URI with a path in it (http://...) is a URI here, not a missing file: lv2Loader takes only the path-free ones
+    const isUri = (x) => /^[A-Za-z][A-Za-z0-9+.-]*:\S+$/.test(x) && !existsSync(x) && !x.endsWith(".clap") && !x.endsWith(".lv2");
+    const r = resolveTargets(a.targets.filter((x) => !isUri(x)), [clapLoader(), lv2Loader]);
+    if (!r.ok) {
+      log(`no plugin found for: ${r.refused.join(", ")}`);
+      return 2;
+    }
+    targets = [...a.targets.filter(isUri).map((uri) => ({ format: "lv2", uri })), ...r.plugins];
+  }
+  if (a.limit > 0) targets = targets.slice(0, a.limit);
+  if (targets.length === 0) {
+    log("no plugin to compare");
+    return 2;
+  }
+  log(`${String(targets.length)} plugins, ${String(present.filter((p) => p.installed).length)} hosts, ${String(a.rate)}/${String(a.quantum)}`);
+  // a JACK server maps about 100 MB of /dev/shm and its clients more: a container's default 64 MB runs out mid-run, and
+  // the server then stops answering
+  try {
+    const st = statfsSync("/dev/shm");
+    const free = (st.bavail * st.bsize) / 2 ** 20;
+    if (free < 512) log(`/dev/shm has ${String(Math.round(free))} MiB free; the JACK server and its clients want 512 or more (podman run --shm-size=1g)`);
+  } catch {
+    // no /dev/shm to read: JACK says so itself
+  }
+  const instruments = lv2Instruments(targets.filter((t) => t.format === "lv2").map((t) => t.uri));
+  let jack;
+  const startOwn = async () => (a.server === undefined ? startJack(a.rate, a.quantum) : { name: a.server, alive: () => answers(a.server), stop: async () => {} });
+  try {
+    jack = await startOwn();
+  } catch (e) {
+    log(e.message);
+    return 2;
+  }
+  const jackVersion = (() => {
+    const r = sh("jackd", ["--version"]);
+    return (`${r.stdout ?? ""}`.match(/jackdmp version (\S+)/) ?? [])[1] ?? "unknown";
+  })();
+  const conditions = { rate: a.rate, quantum: a.quantum, cycles: a.cycles, soakS: a.soakS, windowMs: a.windowMs, timeoutMs: a.timeoutMs, jack: `jackd ${jackVersion} ${a.server === undefined ? "dummy driver, private server" : `server ${a.server}`}`, realtime: realtimeGrant() };
+  if (a.out !== undefined) mkdirSync(a.out, { recursive: true });
+  const work = mkdtempSync(join(tmpdir(), "plugin-qualify-compare-"));
+  // a host step at most timeoutMs, cycles add and remove each, the run, two windows and the soak; then a margin
+  const budget = a.timeoutMs * (2 * a.cycles + 8) + a.soakS * 1000 + 2 * a.windowMs + 15000;
+  const records = [];
+  try {
+    for (const [i, t] of targets.entries()) {
+      const file = a.out === undefined ? undefined : join(a.out, comparisonFileName(t.format, t.uri));
+      if (file !== undefined && !a.force && existsSync(file)) {
+        try {
+          const old = JSON.parse(readFileSync(file, "utf8"));
+          if (comparisonRecordProblems(old).length === 0 && sameConditions(old.conditions, conditions)) {
+            log(`[${String(i + 1)}/${String(targets.length)}] ${t.uri}: compared already under these conditions, kept`);
+            records.push(old);
+            continue;
+          }
+        } catch {
+          // an unreadable record is measured again
+        }
+      }
+      const stimulus = t.format === "lv2" ? (instruments.has(t.uri) ? "notes" : "tone") : "tone";
+      const rows = [];
+      for (const p of present) {
+        if (!p.installed) {
+          rows.push({ host: p.host, version: null, status: "skipped", reason: p.reason });
+          continue;
+        }
+        if (!HOST_TRAITS[p.host].formats.includes(t.format)) {
+          rows.push(notApplicableRow(p.host, p.version, t.format));
+          continue;
+        }
+        // a server that stopped answering is started again, and the host's run on it is made again once: the
+        // server's failure is not the host's
+        let obs;
+        for (let attempt = 0; attempt < 2; attempt++) {
+          if (!jack.alive()) {
+            if (a.server !== undefined) {
+              obs = { installed: true, started: false, problem: `the JACK server ${a.server} does not answer` };
+              break;
+            }
+            log("the JACK server does not answer; starting a new one");
+            await jack.stop();
+            jack = await startOwn();
+          }
+          const opts = { server: jack.name, cycles: a.cycles, soakS: a.soakS, windowMs: a.windowMs, timeoutMs: a.timeoutMs, stimulus, workdir: join(work, p.host) };
+          const r = spawnSync(process.execPath, [DRIVER, p.host, addSpec(t), JSON.stringify(opts)], { encoding: "utf8", timeout: budget, killSignal: "SIGKILL" });
+          try {
+            obs = JSON.parse(r.stdout.trim().split("\n").pop() ?? "");
+          } catch {
+            obs = { installed: true, started: false, problem: r.error?.code === "ETIMEDOUT" ? `the comparison of this plugin went past its budget of ${String(Math.round(budget / 1000))} s` : `the driver gave no result: ${(r.stderr ?? "").trim().split("\n").pop() ?? ""}` };
+          }
+          if (jack.alive()) break;
+          log(`${t.uri} ${p.host}: the JACK server stopped answering during the run${attempt === 0 ? "; once more on a new server" : ""}`);
+          if (attempt === 1) obs = { installed: true, started: false, problem: "the JACK server stopped answering during this host's run, twice" };
+        }
+        const row = hostRowOf(p.host, p.version, obs, conditions);
+        rows.push(row);
+        const c = row.checks;
+        log(
+          `[${String(i + 1)}/${String(targets.length)}] ${t.uri} ${p.host}: ${row.status === "ran" ? `${row.runsClean ? "clean" : "not clean"}; load ${c.loads.result}, output ${c.output.result}, cycles ${c.cycles.result}, soak ${c.soak.result}, rt ${c.rtSafe.result}${row.crash ? `, crashed at ${row.crash.step} (${row.crash.signal})` : ""}` : `${row.status}: ${row.reason}`}`,
+        );
+      }
+      const rec = comparisonRecordOf({ format: t.format, id: t.uri, ...(t.binary ? { binary: t.binary } : {}) }, stimulus, conditions, new Date().toISOString(), rows);
+      records.push(rec);
+      if (file !== undefined) writeFileWhole(file, `${JSON.stringify(rec, null, 2)}\n`);
+    }
+  } finally {
+    await jack.stop();
+    rmSync(work, { recursive: true, force: true });
+  }
+  log(`machine: ${String(cpus().length)} CPUs, ${cpus()[0]?.model ?? "unknown CPU"}; real time ${conditions.realtime}`);
+  const all = a.out === undefined ? records : readRecords(a.out);
+  writeSummary(a.out, all, present, { hostClass: a.hostClass, set: a.set, publish: a.publish }, a.format);
+  return 0;
+}

package/tools/descriptors.py

@@ -109,6 +109,33 @@ def schema_candidates(env=None):
     ]
 
 
+SCHEMA_MAJOR = re.search(r"\d+", DESCRIPTOR_SCHEMA_FLOOR).group(0)
+UNITS_SHEET = os.path.join("formats", "lv2", "units.json")
+
+
+def contract_data_candidates(rel, env=None):
+    """Where one of omx-contract's data files is looked for: in the same omx-contract as each place the schema is,
+    its package's `data/` beside `schema/`, or the contract directory beside the installed schema."""
+    out = []
+    for schema in schema_candidates(env):
+        here = os.path.dirname(schema)
+        out.append(os.path.join(os.path.dirname(here), "data", rel))
+        out.append(os.path.join(here, "contract.d", SCHEMA_MAJOR, "omx-contract", rel))
+    return out
+
+
+def unit_words(env=None):
+    """omx-contract's units sheet as LV2 unit URI -> the word it is spelled by; a unit the sheet gives no word has
+    none here. The sheet is the owner: there is no table of units in this package."""
+    found = [p for p in contract_data_candidates(UNITS_SHEET, env) if os.path.isfile(p)]
+    if not found:
+        raise DescriptorRefused(DESCRIPTOR_CODE_SCHEMA_MISSING,
+                                f"no omx-contract units sheet at {', '.join(contract_data_candidates(UNITS_SHEET, env))}")
+    with open(found[0], encoding="utf-8") as f:
+        terms = json.load(f)["LV2_UNITS_TERMS"]["terms"]
+    return {t["uri"]: t["word"] for t in terms.values() if t.get("kind") == "unit" and "word" in t}
+
+
 class SchemaValidator:
     """omx-contract's schema, compiled once; `check` refuses a document it does not hold."""
 

package/tools/isolated-step.mjs

@@ -10,6 +10,8 @@ import { createConnection } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+import { pinWord } from "../dist/pins-file.js";
+
 const [uri, windowMsWord] = process.argv.slice(2);
 const windowMs = Number(windowMsWord);
 const signalTool = process.env.OMX_ISOLATED_SIGNAL;
@@ -80,7 +82,7 @@ async function main() {
   const sock = await connect();
   if (sock === undefined) return { started: false, problem: `${hostd} did not listen` };
   const send = commander(sock);
-  const added = await send(`add ${uri} ${String(INSTANCE)}`);
+  const added = await send(`add ${pinWord(uri)} ${String(INSTANCE)}`);
   // WORKER_SPAWN: no worker came up to hold the plugin, which says nothing of the plugin. The next pass tries it again.
   if (added?.code === WORKER_SPAWN) return { started: false, problem: `no worker came up: add answered ${String(WORKER_SPAWN)}` };
   if (added === undefined || added.code < 0) return { started: true, added: false, problem: added === undefined ? "the host gave no answer to add" : `add answered ${String(added.code)}` };

package/tools/lilv_load.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+"""lilv's Python bindings, with the library loaded by its soname."""
+import ctypes
+
+LILV_DEV_NAME = "liblilv-0.so"
+LILV_SONAME = "liblilv-0.so.0"
+
+
+def load_lilv():
+    """
+    The bindings module. Fedora's and Debian's lilv.py open liblilv-0.so, a name only their development packages
+    install, so it is opened as liblilv-0.so.0 during the import. Raises what the import raises.
+    """
+    real = ctypes.CDLL
+
+    def by_soname(name, *args, **kwargs):
+        return real(LILV_SONAME if name == LILV_DEV_NAME else name, *args, **kwargs)
+
+    ctypes.CDLL = by_soname
+    try:
+        import lilv
+    finally:
+        ctypes.CDLL = real
+    return lilv

package/tools/lv2_resolve.py

@@ -25,7 +25,9 @@ def path_of(uri):
 
 def main():
     try:
-        import lilv
+        from lilv_load import load_lilv
+
+        lilv = load_lilv()
     except ImportError as e:
         print(f"lv2_resolve: lilv's Python bindings are not installed: {e}", file=sys.stderr)
         return 2

package/tools/pool-step.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+// The pool step: does the CLAP thread pool help this plugin, and is it safe? A plugin-hostd of its own on the JACK server
+// the environment names. The plugin is added once so the daemon learns its pin, and the pin is then set twice, `pool=off`
+// and `pool=cores`, twice each in turn: each time the plugin is added alone in a worker (the daemon starts that worker with
+// the thread pool on only for `pool=cores`), the same notes are played through it for a window, and the window's xruns,
+// its output and the server's DSP load are read; a mode is judged by its best window. Prints one JSON line for src/qualify-pool.ts to judge. A host that never listened says so:
+// nothing was learned about the plugin then. That the plugin asks for the pool at all is the caller's to know first.
+//
+//   pool-step.mjs <clap uri> <window ms>
+//   environment: OMX_ISOLATED_SIGNAL (the signal tool), PLUGIN_HOSTD
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { createConnection } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { pinWord, pinWords } from "../dist/pins-file.js";
+
+const [uri, windowMsWord] = process.argv.slice(2);
+const windowMs = Number(windowMsWord);
+const signalTool = process.env.OMX_ISOLATED_SIGNAL;
+const hostd = process.env.PLUGIN_HOSTD ?? "plugin-hostd";
+const port = 40000 + (process.pid % 20000);
+const CONNECT_TRIES = 50;
+const COMMAND_MS = Number(process.env.OMX_ADMIT_STEP_MS ?? 0) || 30000;
+const INSTANCE = 0;
+const WORKER_SPAWN = -503;
+/** How many times each mode is run, the two alternating. */
+const ROUNDS = 2;
+/** hostd's worker_list field for a worker started with the thread pool on. */
+const POOL_ON = "on";
+
+const state = mkdtempSync(join(tmpdir(), "plugin-qualify-pool-"));
+const host = spawn(hostd, ["-n", "-p", String(port)], { stdio: "ignore", detached: true, env: { ...process.env, XDG_STATE_HOME: state } });
+let ended = false;
+host.on("exit", () => (ended = true));
+host.on("error", () => (ended = true));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function connect() {
+  for (let i = 0; i < CONNECT_TRIES && !ended; i++) {
+    const s = await new Promise((resolve) => {
+      const c = createConnection({ port, host: "127.0.0.1" }, () => resolve(c));
+      c.on("error", () => resolve(undefined));
+    });
+    if (s !== undefined) return s;
+    await sleep(100);
+  }
+  return undefined;
+}
+
+function commander(sock) {
+  let buffer = "";
+  let closed = false;
+  sock.on("data", (d) => (buffer += d.toString()));
+  sock.on("close", () => (closed = true));
+  sock.on("error", () => (closed = true));
+  return async (line) => {
+    buffer = "";
+    sock.write(`${line}\0`);
+    const until = Date.now() + COMMAND_MS;
+    while (Date.now() < until && !closed) {
+      const m = /resp (-?\d+)([^\0]*)\0?/.exec(buffer);
+      if (m !== null && buffer.includes("\0")) return { code: Number(m[1]), rest: m[2].trim() };
+      await sleep(20);
+    }
+    return undefined;
+  };
+}
+
+/** `<worker>:<pid>:<format>:<state>:<core>:<pool>:<place>:<i>,<i>,...` per worker. */
+const workersOf = (answer) =>
+  (answer?.rest ?? "").split(/\s+/).filter(Boolean).map((w) => {
+    const f = w.split(":");
+    return { pid: Number(f[1]), pool: f[5], instances: (f[7] ?? "").split(",").filter(Boolean) };
+  });
+
+/** The pin the daemon learned for the uri, as its store holds it: the files and the layout words, and none of the optional ones. */
+function learnedPin() {
+  let text;
+  try {
+    text = readFileSync(join(state, "plugin-hostd", "pins"), "utf8");
+  } catch {
+    return undefined;
+  }
+  for (const line of text.split("\n")) {
+    // the store writes the uri as it is: look for it as a prefix, whatever it holds
+    const head = `pin_set ${uri} `;
+    const quoted = `pin_set ${pinWord(uri)} `;
+    const rest = line.startsWith(quoted) ? line.slice(quoted.length) : line.startsWith(head) ? line.slice(head.length) : undefined;
+    if (rest === undefined) continue;
+    const words = pinWords(rest);
+    if (words.length >= 2) return { files: words[0], layout: words[1] };
+  }
+  return undefined;
+}
+
+/** Nanoseconds the pool's helper threads of a worker have been on a cpu (`omx-pool-<core>`), or `undefined` when the worker is gone. */
+function helperNs(pid) {
+  try {
+    let ns = 0;
+    for (const t of readdirSync(`/proc/${String(pid)}/task`)) {
+      if (!readFileSync(`/proc/${String(pid)}/task/${t}/comm`, "utf8").startsWith("omx-pool-")) continue;
+      ns += Number(readFileSync(`/proc/${String(pid)}/task/${t}/schedstat`, "utf8").split(" ")[0]);
+    }
+    return ns;
+  } catch {
+    return undefined;
+  }
+}
+
+/** One window: the plugin added alone under `pool=<word>`, the notes played, what was seen. */
+async function window(send, pool, pin) {
+  const set = await send(`pin_set ${pinWord(uri)} ${pinWord(pin.files)} ${pin.layout} pool=${pool}`);
+  if (set === undefined || set.code !== 0) return { problem: `pin_set pool=${pool} answered ${set === undefined ? "nothing" : String(set.code)}` };
+  const added = await send(`add ${pinWord(uri)} ${String(INSTANCE)}`);
+  if (added?.code === WORKER_SPAWN) return { problem: `no worker came up: add answered ${String(WORKER_SPAWN)}` };
+  if (added === undefined || added.code < 0) return { problem: added === undefined ? "the host gave no answer to add" : `add answered ${String(added.code)}` };
+  const workers = workersOf(await send("worker_list"));
+  const worker = workers[0];
+  const heard = spawnSync(signalTool, [`effect_${String(INSTANCE)}`, String(windowMs)], { encoding: "utf8", timeout: windowMs + 15000, killSignal: "SIGKILL" });
+  const helperBusyNs = worker === undefined ? undefined : helperNs(worker.pid);
+  const after = workersOf(await send("worker_list"));
+  await send(`remove ${String(INSTANCE)}`);
+  const alive = after.length > 0 && after[0].pid === worker?.pid;
+  if (heard.error !== undefined || heard.status !== 0) return { problem: `isolated_signal: ${(heard.stderr ?? "").trim()}`, alive };
+  const f = JSON.parse(heard.stdout);
+  return { alive, workers: workers.length, poolOfWorker: worker?.pool, xruns: f.xruns, finite: f.finite, silent: f.silent, dspLoad: f.dspLoad, ...(helperBusyNs === undefined ? {} : { helperBusyNs }) };
+}
+
+/** The windows of one mode as one: the lowest load and the fewest xruns, and any window that failed, died or was silent counts. */
+function best(windows) {
+  const failed = windows.find((w) => w.problem !== undefined);
+  if (failed !== undefined) return failed;
+  const low = (key) => Math.min(...windows.map((w) => w[key]));
+  return {
+    alive: windows.every((w) => w.alive),
+    workers: windows[0].workers,
+    poolOfWorker: windows[0].poolOfWorker,
+    xruns: low("xruns"),
+    finite: windows.every((w) => w.finite),
+    silent: windows.some((w) => w.silent),
+    dspLoad: low("dspLoad"),
+    // what the helpers did in the window that used them most: the pool is idle only if it was idle in every one
+    ...(windows.every((w) => w.helperBusyNs === undefined) ? {} : { helperBusyNs: Math.max(...windows.map((w) => w.helperBusyNs ?? 0)) }),
+  };
+}
+
+async function main() {
+  const sock = await connect();
+  if (sock === undefined) return { started: false, problem: `${hostd} did not listen` };
+  const send = commander(sock);
+  // the first add teaches the daemon the plugin's pin; the store holds it once the plugin is in
+  const first = await send(`add ${pinWord(uri)} ${String(INSTANCE)}`);
+  if (first?.code === WORKER_SPAWN) return { started: false, problem: `no worker came up: add answered ${String(WORKER_SPAWN)}` };
+  if (first === undefined || first.code < 0) return { started: true, added: false, problem: first === undefined ? "the host gave no answer to add" : `add answered ${String(first.code)}` };
+  await send(`remove ${String(INSTANCE)}`);
+  await sleep(300);
+  const pin = learnedPin();
+  if (pin === undefined) return { started: false, problem: "the daemon kept no pin of the plugin" };
+  // the two modes alternate, and each is read at its best window: the cost of a block only ever grows with what else runs on
+  // the machine, so the lowest load of a mode is the one least disturbed, and a pool that causes xruns causes them in
+  // every window it runs
+  const offs = [];
+  const ons = [];
+  for (let round = 0; round < ROUNDS; round++) {
+    offs.push(await window(send, "off", pin));
+    ons.push(await window(send, "cores", pin));
+  }
+  const off = best(offs);
+  const on = best(ons);
+  sock.destroy();
+  return { started: true, added: true, off, on, poolApplied: on.poolOfWorker === POOL_ON && off.poolOfWorker !== POOL_ON };
+}
+
+const result = await main();
+try {
+  process.kill(-host.pid, "SIGKILL");
+} catch {
+  // the host went on its own
+}
+rmSync(state, { recursive: true, force: true });
+process.stdout.write(`${JSON.stringify(result)}\n`);
+process.exit(0);