@openmixer/plugin-qualify 0.20.1 → 0.20.4

package/src/qualify-isolated.ts

@@ -16,6 +16,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 
+import { withRunHome } from "./run-home.js";
 import { ADAPTER_PASS_CELLS, startPrivateJack, type JackStarter } from "./qualify-adapter-pass.js";
 import type { GridCell } from "./measurement-grid.js";
 import { clapPinUri, type PinEntry } from "./pins-file.js";
@@ -130,6 +131,21 @@ export function pinFromRecord(record: QualificationRecord): PinEntry | undefined
   return pinAfterStep({ uri, integrity: { files: sorted, layout } }, step);
 }
 
+/**
+ * Whether a step of the isolated kind is a verdict. A refusal (`isolated.silent-output`, `isolated.not-added`) is one: the
+ * plugin was tried and the answer is no. A step that could not run decided nothing, and neither did silence before the
+ * notes were played where a plugin could hear them: a step of that tool does not say how many inputs it linked. Those two
+ * are owed, and a pass tries them again.
+ */
+export function isolatedDecided(s: RunStep): boolean {
+  return s.step === RUN_STEP.isolated && s.result !== ISOLATED_RESULT.notRun && !(s.code === ISOLATED_CODE.silent && s.figures?.midiInputsLinked === undefined);
+}
+
+/** Whether the record holds a finished isolated step, of whatever answer: nothing about it is owed. */
+export function isolatedFinished(record: QualificationRecord): boolean {
+  return record.run?.steps.some(isolatedDecided) === true;
+}
+
 /** Whether the isolated step saw this plugin running alone. A record's word alone never says so. */
 export function provenAlone(record: QualificationRecord): boolean {
   return record.run?.steps.some((s) => s.step === RUN_STEP.isolated && s.result === ISOLATED_RESULT.isolated) === true;
@@ -182,7 +198,7 @@ export function spawnedIsolatedRunner(jack: JackStarter = startPrivateJack): Iso
         encoding: "utf8",
         timeout: ISOLATED_WINDOW_MS + ISOLATED_STEP_SLACK_MS,
         killSignal: "SIGKILL",
-        env: { ...env, JACK_DEFAULT_SERVER: server.name, [ISOLATED_SIGNAL_TOOL_ENV]: signal },
+        env: { ...withRunHome(env), JACK_DEFAULT_SERVER: server.name, [ISOLATED_SIGNAL_TOOL_ENV]: signal },
       });
       if (r.error !== undefined || r.status !== 0) return { started: false, problem: `isolated-step: ${r.error?.message ?? `exit ${String(r.status)}`}: ${(r.stderr ?? "").trim()}` };
       return JSON.parse(r.stdout) as IsolatedRunFacts;
@@ -225,10 +241,7 @@ export function runIdOf(record: QualificationRecord, dir: string): string | unde
  */
 export function completeIsolated(path: string, record: QualificationRecord, uri: string, cell: GridCell, runner: IsolatedRunner, env: Readonly<Record<string, string | undefined>>): { readonly record: QualificationRecord; readonly step: RunStep } | undefined {
   const isStep = (s: RunStep): boolean => s.step === RUN_STEP.isolated;
-  // a step that could not run decided nothing, and neither did silence before the notes were played where a plugin could
-  // hear them: a step of that tool does not say how many inputs it linked. A pass tries these again, and it takes their place
-  const decided = (s: RunStep): boolean => s.result !== ISOLATED_RESULT.notRun && !(s.code === ISOLATED_CODE.silent && s.figures?.midiInputsLinked === undefined);
-  if (!owesIsolated(record) || record.run?.steps.some((s) => isStep(s) && decided(s)) === true) return undefined;
+  if (!owesIsolated(record) || isolatedFinished(record)) return undefined;
   const id = runIdOf(record, join(path, ".."));
   if (id === undefined) return undefined;
   const step = judgeIsolatedRun(runner(uri, cell, env));

package/src/qualify-pool.ts

@@ -30,6 +30,7 @@ import { existsSync } from "node:fs";
 import { availableParallelism } from "node:os";
 import { join } from "node:path";
 
+import { withRunHome } from "./run-home.js";
 import type { GridCell } from "./measurement-grid.js";
 import type { PinEntry, PinPool } from "./pins-file.js";
 import type { PoolFigures, QualificationRecord, RunBlock, RunStep } from "./qualification-record.js";
@@ -203,7 +204,7 @@ const POOL_STEP_SLACK_MS = 120000;
 export function asksForPool(prober: string, uri: string, env: Readonly<Record<string, string | undefined>>): boolean | undefined {
   const m = /^clap:(.*)#([^#]*)$/s.exec(uri);
   if (m === null) return undefined;
-  const r = spawnSync(prober, ["--asks-thread-pool", m[1]!, m[2]!], { encoding: "utf8", timeout: 60000, killSignal: "SIGKILL", env: { ...env } });
+  const r = spawnSync(prober, ["--asks-thread-pool", m[1]!, m[2]!], { encoding: "utf8", timeout: 60000, killSignal: "SIGKILL", env: withRunHome(env) });
   if (r.status !== 0) return undefined;
   try {
     return (JSON.parse(r.stdout) as { threadPool?: unknown }).threadPool === true;
@@ -233,7 +234,7 @@ export function watchOnHelpers(prober: string, interposer: string, uri: string,
     encoding: "utf8",
     timeout: 120000,
     killSignal: "SIGKILL",
-    env: { ...env, LD_PRELOAD: preload },
+    env: { ...withRunHome(env), LD_PRELOAD: preload },
   });
   if (r.error !== undefined || r.status !== 0) return { problem: `${CLAP_QUALIFY_TOOL_NAME} --pool: ${r.error?.message ?? `exit ${String(r.status)}`}` };
   const line = r.stdout.split("\n").filter((l) => l.startsWith("{")).pop();
@@ -273,7 +274,7 @@ export function spawnedPoolRunner(jack: JackStarter = startPrivateJack): PoolRun
         encoding: "utf8",
         timeout: 2 * POOL_ROUNDS * POOL_WINDOW_MS + POOL_STEP_SLACK_MS,
         killSignal: "SIGKILL",
-        env: { ...env, JACK_DEFAULT_SERVER: server.name, [ISOLATED_SIGNAL_TOOL_ENV]: signal },
+        env: { ...withRunHome(env), JACK_DEFAULT_SERVER: server.name, [ISOLATED_SIGNAL_TOOL_ENV]: signal },
       });
       if (r.error !== undefined || r.status !== 0) return { started: false, problem: `pool-step: ${r.error?.message ?? `exit ${String(r.status)}`}: ${(r.stderr ?? "").trim()}` };
       return { ...(JSON.parse(r.stdout) as PoolRunFacts), asks: true, rt: watched.rt };

package/src/qualify-rejudge.ts

@@ -48,7 +48,7 @@ import {
   type RecordVerdict,
   type RunBlock,
 } from "./qualification-record.js";
-import { ISOLATED_RESULT, RUN_STEP, pinAfterStep, provenAlone } from "./qualify-isolated.js";
+import { ISOLATED_RESULT, RUN_STEP, isolatedFinished, pinAfterStep } from "./qualify-isolated.js";
 import { pinAfterPool, poolStepOf } from "./qualify-pool.js";
 import { PI_CELLS, PROBE_MEMORY_ONLY_ENV, PROBE_NOTES_ENV } from "./qualify-declarations.js";
 import { SYNC_STATE_SCHEMA, digestFiles, recordStem, type SyncContext, type SyncEntry, type SyncPlugin, type SyncState } from "./qualify-sync.js";
@@ -198,9 +198,9 @@ export function rejudgeRecord(record: QualificationRecord, probeBytes: Uint8Arra
   const { profiles, kept } = rejudgeProfiles(record, output, options.host);
   const { reasons, owes: runs } = runsOwed(record, output, profiles);
   const judgment = judgeProbeOutput(output, profiles, { admissions: admissionsOf(record), owed: reasons });
-  // decides no verdict: a record from before the steps that reads isolated stays offered, runs alone, and is not proven by the step
+  // decides no verdict: a record from before the steps that reads isolated stays offered and runs alone, and owes the step until one has finished; a refusal is finished: it is the step's verdict, not debt
   const readsIsolated = judgment.hosts.some((h) => h.verdict.measured && h.verdict.rating === "conditional");
-  const owes = readsIsolated && !provenAlone(record) ? [...runs, { measurement: "isolated-step" as const, code: OWED_CODE.isolatedStep }] : runs;
+  const owes = readsIsolated && !isolatedFinished(record) ? [...runs, { measurement: "isolated-step" as const, code: OWED_CODE.isolatedStep }] : runs;
   const memory = record.memoryRun === undefined ? {} : { memory: { tool: record.memoryRun.tool, measuredAt: record.memoryRun.measuredAt } };
   const a = record.adapter;
   const adapterTaken = a?.versions === undefined || a.measuredAt === undefined ? {} : { adapter: { versions: a.versions, measuredAt: a.measuredAt } };

package/src/qualify-sync.ts

@@ -23,15 +23,19 @@ import { createConnection } from "node:net";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 
+import { withRunHome } from "./run-home.js";
 import { clapQualifyTools } from "./clap-qualify.js";
 import { DISTRIBUTED_DIR_SYSTEM, EMPTY_LAYER, applyDistributed, distributedUri, hostClassOfBoard, hostClassOfMachine, outcomeOfVerdict, matchDistributed, readBoardModel, readMachine, readDistributedLayer, type DistributedLayer } from "./distributed-records.js";
-import { clapSearchPath, parseClapScan } from "./clap-loader.js";
+import { parseClapScan } from "./clap-loader.js";
+import { SPAWNED_SEARCH_PATH, hostdSearchPath, searchPathWarnings, type SearchPathRun } from "./hostd-search-path.js";
 import { HOSTING_CODE } from "./hosting-codes.js";
 import { shippedHostProfile, type HostProfile } from "./host-profiles.js";
-import { lv2BundlesOnPath, manifestPlugins } from "./lv2-loader.js";
+import { NO_JACK_SERVER } from "./host-admission.js";
+import { iriPath, lv2BundlesOnPath, manifestPlugins } from "./lv2-loader.js";
 import { judgmentPinEntries, pinClearLine, pinLineUri, pinsFile, type PinEntry } from "./pins-file.js";
 import { POOL_RESULT, completePool, judgePoolRun, pinAfterPool, pinFromRecordWithPool, poolEnv, spawnedPoolRunner, type PoolRunner } from "./qualify-pool.js";
 import { hostdPinFiles, type PinFilesRun } from "./hostd-pin-files.js";
+import { localeOf, reasonText } from "./text-catalog.js";
 import type { Judgment } from "./probe-judge.js";
 import { qualifyTargets, type ProbeRun } from "./probe-runner.js";
 import { GRID_FULL, hostCells, parseGridSpec, type GridCell, type GridSpec } from "./measurement-grid.js";
@@ -39,7 +43,7 @@ import { adapterPass, type AdapterPassOptions, type AdapterPassResult } from "./
 import { ISOLATED_RESULT, baseSteps, completeIsolated, isolatedCell, missingSteps, judgeIsolatedRun, owesIsolated, pinAfterStep, spawnedIsolatedRunner, type IsolatedRunner } from "./qualify-isolated.js";
 import { lv2World, rejudgeRecord, rejudgeState, rejudgeToolName, memoryPass, type MemoryPassResult, type RejudgeResult } from "./qualify-rejudge.js";
 import { memoryBoundOf, parseMemoryLimit, type MemoryBound } from "./memory-bound.js";
-import { QUALIFICATION_RECORD_SCHEMA, latencyNeverTaken, rewriteRecord, writeQualification, type NotMeasured, type QualificationRecord } from "./qualification-record.js";
+import { QUALIFICATION_RECORD_SCHEMA, descriptorNamePart, latencyNeverTaken, rewriteRecord, writeQualification, type NotMeasured, type QualificationRecord } from "./qualification-record.js";
 import { ADMIT_STEP_MS_ENV, DESCRIPTOR_DIR_STATE_SUBDIR, DESCRIPTOR_DIR_SYSTEM, MEMORY_PASS_PROBE_NOTES, QUALIFY_QUANTA, QUALIFY_RATES } from "./qualify-declarations.js";
 import { toolsDir } from "./tool-paths.js";
 import { writeFileWhole } from "./whole-file.js";
@@ -49,12 +53,6 @@ import { writeFileWhole } from "./whole-file.js";
 /** The settings file a system service reads, `key value` per line. */
 export const SYNC_CONF = "/etc/omx/qualify.conf";
 
-/** The LV2 directories plugin-hostd searches when `LV2_PATH` is unset (its `lv2_path` default). */
-export const HOSTD_LV2_PATH = ["/usr/lib64/lv2", "/usr/lib/lv2", "/usr/local/lib/lv2"];
-
-/** Zynthian's own LV2 directories: the image's plugins and the ones its user installs. */
-export const ZYNTHIAN_LV2_DIRS = ["/zynthian/zynthian-plugins/lv2", "/zynthian/zynthian-my-data/plugins/lv2"];
-
 export interface SyncSetting {
   readonly key: string;
   readonly meaning: string;
@@ -64,10 +62,7 @@ export interface SyncSetting {
 
 /** Every setting, declared once: the settings file, the flags (`--pin-file` for `pin_file`) and `--help` read this. */
 export const SYNC_SETTINGS: readonly SyncSetting[] = [
-  { key: "lv2_path", meaning: "the LV2 directories, colon-separated, in the order plugin-hostd searches them", default: "$LV2_PATH, else " + HOSTD_LV2_PATH.join(":") },
-  { key: "lv2_extra", meaning: "more LV2 directories, searched after lv2_path", default: ZYNTHIAN_LV2_DIRS.join(":") },
-  { key: "clap_path", meaning: "the CLAP directories, colon-separated", default: "$CLAP_PATH, then ~/.clap, then /usr/lib/clap" },
-  { key: "clap_extra", meaning: "more CLAP directories, searched after clap_path", default: "" },
+  { key: "hostd_conf", meaning: "plugin-hostd's settings file: the LV2 and CLAP directories scanned are the ones plugin-hostd --search-path -c <file> prints", default: "plugin-hostd's own (its XDG_CONFIG_HOME/plugin-hostd.conf, else ~/.config/plugin-hostd.conf)" },
   { key: "pin_file", meaning: "the pin file plugin-hostd loads as pin_file", default: "/var/lib/omx/qualified.pins (system), else $XDG_STATE_HOME/omx/qualified.pins" },
   { key: "qualification_dir", meaning: "where the qualification records go", default: "/var/lib/omx/qualification (system), else $XDG_STATE_HOME/omx/qualification" },
   { key: "descriptor_dir", meaning: "where the scanned descriptors go", default: `${DESCRIPTOR_DIR_SYSTEM} (system), else $XDG_STATE_HOME/${DESCRIPTOR_DIR_STATE_SUBDIR}` },
@@ -85,8 +80,16 @@ export const SYNC_SETTINGS: readonly SyncSetting[] = [
   { key: "distributed_dir", meaning: "the directories of distributed records, colon-separated, each holding <host class>/<set>/", default: `${DISTRIBUTED_DIR_SYSTEM} (system), else $XDG_DATA_HOME/omx/qualification and each $XDG_DATA_DIRS/omx/qualification` },
 ];
 
+/** The search path settings that moved to plugin-hostd's settings file (plugin-qualify#9): refused here, with where they went. */
+export const MOVED_TO_HOSTD = ["lv2_path", "lv2_extra", "clap_path", "clap_extra"] as const;
+
+const movedText = (key: string): string =>
+  `${key} is plugin-hostd's setting now: write it in plugin-hostd's settings file (plugin-hostd.conf, named here by hostd_conf); the directories scanned are the ones plugin-hostd --search-path prints${key === "clap_extra" ? " (plugin-hostd has no clap_extra: add the directories to clap_path)" : ""}`;
+
 export interface SyncSettings {
+  /** The LV2 directories, as plugin-hostd searches them with hostd_conf (plugin-hostd --search-path). */
   readonly lv2Dirs: readonly string[];
+  /** The CLAP directories, as plugin-hostd searches them with hostd_conf. */
   readonly clapDirs: readonly string[];
   readonly pinFile: string;
   readonly qualificationDir: string;
@@ -121,6 +124,7 @@ export function parseSyncConf(text: string, source = SYNC_CONF): { ok: true; val
     if (line === "") continue;
     const m = /^(\S+)(?:\s+(.*))?$/.exec(line)!;
     const key = m[1]!;
+    if ((MOVED_TO_HOSTD as readonly string[]).includes(key)) return { ok: false, error: `${source}:${String(n + 1)}: ${movedText(key)}` };
     if (!known.has(key)) return { ok: false, error: `${source}:${String(n + 1)}: ${key} is not a setting` };
     values.set(key, (m[2] ?? "").trim());
   }
@@ -186,7 +190,8 @@ export function parseSyncArgs(argv: readonly string[]): { ok: true; args: SyncAr
       if (v === undefined) return { ok: false, error: `${a} needs a value` };
       if (a === "--config") config = v;
       else values.set(byFlag.get(a)!, v);
-    } else return { ok: false, error: `unknown argument ${a}` };
+    } else if (MOVED_TO_HOSTD.some((k) => flagOf(k) === a)) return { ok: false, error: `${a}: ${movedText(a.slice(2).replace(/-/g, "_"))}` };
+    else return { ok: false, error: `unknown argument ${a}` };
   }
   if (rejudge && (memoryOnly || adapterOnly || isolatedOnly || poolOnly || force || refreshPinsOnly)) return { ok: false, error: "--rejudge measures nothing: it goes with none of --memory-only, --adapter-only, --isolated-only, --pool-only, --force and --refresh-pins" };
   if ([memoryOnly, adapterOnly, isolatedOnly, poolOnly, refreshPinsOnly].filter(Boolean).length > 1) return { ok: false, error: "--memory-only, --adapter-only, --isolated-only, --pool-only and --refresh-pins are different runs: one at a time" };
@@ -229,17 +234,18 @@ export function resolveSyncSettings(
   home: string = homedir(),
   boardModel: () => string | undefined = readBoardModel,
   machineArch: () => string | undefined = readMachine,
-): { ok: true; settings: SyncSettings } | { ok: false; error: string } {
+  searchPathRun: SearchPathRun = SPAWNED_SEARCH_PATH,
+): { ok: true; settings: SyncSettings; warnings: string[] } | { ok: false; error: string } {
   const get = (key: string): string | undefined => args.values.get(key) ?? file.get(key);
   const state = env["XDG_STATE_HOME"] !== undefined && env["XDG_STATE_HOME"] !== "" ? env["XDG_STATE_HOME"] : join(home, ".local", "state");
   const place = (key: string, system: string, user: string): string => {
     const v = get(key);
     return v !== undefined && v !== "" ? v : args.system ? system : join(state, user);
   };
-  const lv2Named = get("lv2_path");
-  const lv2Base = lv2Named !== undefined && lv2Named !== "" ? dirList(lv2Named) : dirList(env["LV2_PATH"] ?? "").length > 0 ? dirList(env["LV2_PATH"]!) : HOSTD_LV2_PATH;
-  const clapNamed = get("clap_path");
-  const clapBase = clapNamed !== undefined && clapNamed !== "" ? dirList(clapNamed) : clapSearchPath(env, home);
+  const hostdConfNamed = get("hostd_conf");
+  const hostdConf = hostdConfNamed !== undefined && hostdConfNamed !== "" ? hostdConfNamed : undefined;
+  const search = hostdSearchPath(hostdConf, env, searchPathRun);
+  if (!search.ok) return { ok: false, error: `the directories to scan: ${search.error}` };
   const number = (key: string, min: number): number | undefined => {
     const v = Number(get(key) ?? SYNC_SETTINGS.find((s) => s.key === key)!.default);
     return Number.isFinite(v) && v >= min ? v : undefined;
@@ -281,9 +287,10 @@ export function resolveSyncSettings(
   if (hostClass !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(hostClass)) return { ok: false, error: `host_class ${hostClass} is not a directory name` };
   return {
     ok: true,
+    warnings: searchPathWarnings(search.path, hostdConf),
     settings: {
-      lv2Dirs: once([...lv2Base, ...dirList(get("lv2_extra") ?? ZYNTHIAN_LV2_DIRS.join(":"))]),
-      clapDirs: once([...clapBase, ...dirList(get("clap_extra") ?? "")]),
+      lv2Dirs: once(search.path.lv2),
+      clapDirs: once(search.path.clap),
       pinFile: place("pin_file", "/var/lib/omx/qualified.pins", join("omx", "qualified.pins")),
       qualificationDir: place("qualification_dir", "/var/lib/omx/qualification", join("omx", "qualification")),
       descriptorDir: place("descriptor_dir", DESCRIPTOR_DIR_SYSTEM, DESCRIPTOR_DIR_STATE_SUBDIR),
@@ -442,7 +449,7 @@ export function discoverSyncItems(
         const binary = lilv?.binary ?? (p.binary === undefined ? undefined : join(bundle, p.binary));
         const files = ["manifest.ttl", ...p.files.filter((f) => f !== "manifest.ttl")];
         // a binary named by an absolute IRI (a complement's) is tracked through the bundle's link to it, when it has one
-        if (binary !== undefined && !files.includes(basename(binary)) && linksTo(join(bundle, basename(binary)), binary)) files.push(basename(binary));
+        if (binary !== undefined && !files.some((f) => iriPath(f) === basename(binary)) && linksTo(join(bundle, basename(binary)), binary)) files.push(basename(binary));
         items.push({ key: `lv2:${p.uri}`, format: "lv2", root: bundle, files, uri: p.uri, ...(binary === undefined ? {} : { binary }) });
       }
     }
@@ -482,7 +489,10 @@ export function fileSha256(path: string): string {
 export function digestFiles(root: string, files: readonly string[], known: readonly FileDigest[] = []): FileDigest[] | undefined {
   const out: FileDigest[] = [];
   for (const path of [...new Set(files)].sort()) {
-    const full = join(root, path);
+    // a name may be an IRI's word (the pin keeps `libSurge%20XT.so`); the file is the path it decodes to, and a name
+    // that is a file as written (a .clap with a % in it) is read as written when the decoded one is not there
+    const decoded = join(root, iriPath(path));
+    const full = existsSync(decoded) ? decoded : join(root, path);
     try {
       const st = statSync(full);
       if (!st.isFile()) return undefined;
@@ -526,6 +536,7 @@ export function machineReason(p: Pick<SyncPlugin, "outcome" | "code" | "detail">
   if (p.outcome !== "unmeasured" || p.code !== SYNC_CODE.notMeasured) return undefined;
   const errno = /\b(EACCES|EPERM|ENOSPC)\b/.exec(p.detail ?? "")?.[1];
   if (errno !== undefined) return errno;
+  if ((p.detail ?? "").startsWith(NO_JACK_SERVER)) return NO_JACK_SERVER;
   return /wrote no document|cannot run the probe runner/.test(p.detail ?? "") ? "the measurement wrote no document" : undefined;
 }
 
@@ -623,7 +634,7 @@ export function recordedAsIs(item: SyncItem, entry: SyncEntry | undefined): { sa
  */
 export function sameBinaryElsewhere(item: SyncItem, entry: SyncEntry | undefined): SyncEntry | undefined {
   if (item.format !== "lv2" || entry === undefined || item.binary === undefined || resolve(entry.root) === resolve(item.root)) return undefined;
-  const was = entry.files.find((f) => basename(f.path) === basename(item.binary!));
+  const was = entry.files.find((f) => basename(iriPath(f.path)) === basename(item.binary!));
   if (was === undefined) return undefined;
   let now: string;
   try {
@@ -660,7 +671,7 @@ function withHostdFiles(ctx: SyncContext, pin: PinEntry | undefined): PinEntry |
   if (pin === undefined || pin.integrity.files === undefined) return pin;
   const r = hostdPinFiles(pin.uri, ctx.settings.lv2Dirs, ctx.env, ...(ctx.pinFilesRun === undefined ? [] : [ctx.pinFilesRun]));
   if (!r.ok) {
-    ctx.log(`${pin.uri}: not pinned: ${r.detail}`);
+    ctx.log(`${pin.uri}: not pinned: ${reasonText(r.detail, localeOf(ctx.env))}`);
     return undefined;
   }
   return { ...pin, integrity: { ...pin.integrity, files: r.files } };
@@ -683,7 +694,7 @@ export function refreshPins(ctx: SyncContext, state: SyncState): { state: SyncSt
       if (pin === undefined || pin.integrity.files === undefined) return plugin;
       const r = hostdPinFiles(pin.uri, ctx.settings.lv2Dirs, ctx.env, ...(ctx.pinFilesRun === undefined ? [] : [ctx.pinFilesRun]));
       if (!r.ok) {
-        ctx.log(`${pin.uri}: pin files not refreshed: ${r.detail}`);
+        ctx.log(`${pin.uri}: pin files not refreshed: ${reasonText(r.detail, localeOf(ctx.env))}`);
         return plugin;
       }
       const old = new Map(pin.integrity.files.map((f) => [f.path, f.sha256]));
@@ -715,7 +726,7 @@ function outcomeOf(judgment: Judgment, host: string): { outcome: SyncOutcome; co
   return { outcome: v.rating === "unsuitable" ? "refused" : "unmeasured", ...(code === undefined ? {} : { code }) };
 }
 
-const safe = (text: string): string => text.replace(/[^A-Za-z0-9._-]/g, "_");
+const safe = descriptorNamePart;
 
 /** The record of a plugin no probe output exists for: what it is, the bytes it was, and why nothing was measured. */
 function writeUnmeasuredRecord(ctx: SyncContext, item: SyncItem, files: readonly FileDigest[], plugin: Omit<SyncPlugin, "record">): string {
@@ -735,8 +746,19 @@ function writeUnmeasuredRecord(ctx: SyncContext, item: SyncItem, files: readonly
   return path;
 }
 
-/** The step's environment: each of its commands has the sync's budget. */
-const isolatedEnv = (ctx: SyncContext): Readonly<Record<string, string | undefined>> => ({ ...ctx.env, [ADMIT_STEP_MS_ENV]: String(ctx.settings.budgetS * 1000) });
+/** The directories the sync scanned, as the plugin-hostd a step starts reads them: with neither variable set it searches
+ * only its own defaults, and every plugin of `lv2_extra` or of a directory the settings add is refused at add. */
+export const hostdSearchEnv = (settings: Pick<SyncSettings, "lv2Dirs" | "clapDirs">): Record<string, string> => ({
+  LV2_PATH: settings.lv2Dirs.join(":"),
+  CLAP_PATH: settings.clapDirs.join(":"),
+});
+
+/** The step's environment: the sync's directories, and each of its commands has the sync's budget. */
+export const isolatedEnv = (ctx: Pick<SyncContext, "env" | "settings">): Readonly<Record<string, string | undefined>> => ({
+  ...ctx.env,
+  ...hostdSearchEnv(ctx.settings),
+  [ADMIT_STEP_MS_ENV]: String(ctx.settings.budgetS * 1000),
+});
 
 /** Each judged run of a pass as the plugins it qualified: the record written, the pin taken, the outcome. */
 function judgedPlugins(ctx: SyncContext, runs: readonly { bytes: Buffer; judgment: Judgment; stderr?: readonly Buffer[] }[], describeProblem?: string): SyncPlugin[] {
@@ -772,7 +794,7 @@ function judgedPlugins(ctx: SyncContext, runs: readonly { bytes: Buffer; judgmen
     // the pool is for a CLAP plugin that runs: the thread pool is granted by measuring it, here and nowhere else
     if (judgment.output.plugin.format === "clap" && pin !== undefined && pin.verdict !== "refused" && outcome === "qualified") {
       const runner = ctx.poolRunner ?? spawnedPoolRunner();
-      const step = judgePoolRun(runner(pin.uri, isolatedCell(record, host), poolEnv(ctx.env, ctx.settings.budgetS)));
+      const step = judgePoolRun(runner(pin.uri, isolatedCell(record, host), poolEnv({ ...ctx.env, ...hostdSearchEnv(ctx.settings) }, ctx.settings.budgetS)));
       steps.push(step);
       pin = pinAfterPool(pin, step);
     }
@@ -845,7 +867,7 @@ function qualifyClap(ctx: SyncContext, item: SyncItem): SyncPlugin[] {
     return [{ uri: fileUri, outcome: "unmeasured", code: SYNC_CODE.notMeasured, detail: (e as Error).message }];
   }
   // the scanner lists the plugins of the file in a child of its own, and says how that child ended
-  const r = spawnSync(tool, ["--json", file], { encoding: "utf8", timeout: Math.max(ctx.settings.budgetS, 35) * 1000, killSignal: "SIGKILL", maxBuffer: 64 << 20 });
+  const r = spawnSync(tool, ["--json", file], { encoding: "utf8", timeout: Math.max(ctx.settings.budgetS, 35) * 1000, killSignal: "SIGKILL", maxBuffer: 64 << 20, env: withRunHome(process.env) });
   let scanned;
   try {
     if (r.error !== undefined) throw r.error;
@@ -975,7 +997,7 @@ export function poolPass(ctx: SyncContext, state: SyncState): { readonly state:
           ctx.log(`${p.uri}: its record does not read; no pool step`);
           return p;
         }
-        const done = completePool(path, record, p.pin.uri, isolatedCell(record, host), runner, poolEnv(ctx.env, ctx.settings.budgetS));
+        const done = completePool(path, record, p.pin.uri, isolatedCell(record, host), runner, poolEnv({ ...ctx.env, ...hostdSearchEnv(ctx.settings) }, ctx.settings.budgetS));
         if (done === undefined) return p;
         ctx.log(`${p.uri}: pool step ${done.step.result}${done.step.code === undefined ? "" : ` (${done.step.code})`}`);
         if (done.step.result === POOL_RESULT.cores) count.cores++;
@@ -1079,7 +1101,7 @@ function scanClapDescriptors(ctx: SyncContext, item: SyncItem): void {
     ctx.log(`${file}: descriptors not written: ${(e as Error).message}`);
     return;
   }
-  const r = spawnSync(tool, ["--json", file], { encoding: "utf8", timeout: Math.max(ctx.settings.budgetS, 35) * 1000, killSignal: "SIGKILL", maxBuffer: 64 << 20 });
+  const r = spawnSync(tool, ["--json", file], { encoding: "utf8", timeout: Math.max(ctx.settings.budgetS, 35) * 1000, killSignal: "SIGKILL", maxBuffer: 64 << 20, env: withRunHome(process.env) });
   if (r.error !== undefined || r.status !== 0) {
     ctx.log(`${file}: descriptors not written: the scan ended ${r.error?.message ?? `with exit ${String(r.status)}`}`);
     return;

package/src/record-figures.ts

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The figures a qualification record holds at one rate and quantum: what plugin-qualify's own
+ * menus and the zynthian-ui fork both need to show, read from `plugin-qualify.qualification-record/1`
+ * (`qualification-record.ts`) rather than re-derived.
+ *
+ * `tools/record_figures.py` is the same reader for a Python console (zynthian-ui): the two are
+ * held equal over the same fixtures (`record-figures-python-conformance.test.ts`), figure for
+ * figure, word for word and code for code.
+ *
+ * This reader takes no side on the plugin: no tier, no state, no verdict. A figure plugin-qualify
+ * did not take is absent here, never a zero and never guessed — that is plugin-db's reader
+ * (plugin-db#4) and the tiers already in the record (`RecordTiers`).
+ */
+import type { QualificationRecord } from "./qualification-record.js";
+
+/** The latency frames this cell holds: what the plugin declared, and what the run measured, when either was taken. */
+export interface RecordLatencyFigures {
+  readonly declaredFrames?: number;
+  readonly measuredFrames?: number;
+}
+
+/** The interposer's RT-safety counts for this cell, as the probe wrote them — never re-summed. */
+export interface RecordRtSafetyFigures {
+  /** The interposer was loaded; a count below is zero from a real run, not from no interposer. */
+  readonly interposer?: boolean;
+  readonly swept?: boolean;
+  readonly sweepApplicable?: boolean;
+  readonly allocations?: number;
+  readonly locks?: number;
+  readonly syscalls?: number;
+  readonly threadViolations?: number;
+  readonly processErrors?: number;
+  /** How many events the interposer logged (`malloc ? ?`, ...); the words themselves are for a log, not this reader. */
+  readonly events?: number;
+}
+
+/** The figures of one qualification record at one rate and quantum. */
+export interface RecordFigures {
+  readonly latency?: RecordLatencyFigures;
+  /** The median cost of this cell, in nanoseconds per sample (`ProbeCost.median`'s own unit). */
+  readonly costNsPerSampleMedian?: number;
+  readonly rtSafety?: RecordRtSafetyFigures;
+  /** Whether the continuous soak ran at this rate; `false` when the record never names a soak reading here. */
+  readonly soakRan: boolean;
+  /** This cell's own outcome code, carried verbatim, exactly when it is a crash. */
+  readonly crashCode?: string;
+  /** This cell's own outcome code, carried verbatim, exactly when it is a supervisor timeout. */
+  readonly timeoutCode?: string;
+}
+
+const PROBE_CRASHED = "probe.crashed";
+const PROBE_TIMEOUT = "probe.timeout";
+
+function rtSafetyFiguresOf(rtSafety: QualificationRecord["measurements"]["grid"][number]["rtSafety"]): RecordRtSafetyFigures | undefined {
+  if (rtSafety === undefined) return undefined;
+  return {
+    ...(rtSafety.interposer === undefined ? {} : { interposer: rtSafety.interposer }),
+    ...(rtSafety.swept === undefined ? {} : { swept: rtSafety.swept }),
+    ...(rtSafety.sweepApplicable === undefined ? {} : { sweepApplicable: rtSafety.sweepApplicable }),
+    ...(rtSafety.allocations === undefined ? {} : { allocations: rtSafety.allocations }),
+    ...(rtSafety.locks === undefined ? {} : { locks: rtSafety.locks }),
+    ...(rtSafety.syscalls === undefined ? {} : { syscalls: rtSafety.syscalls }),
+    ...(rtSafety.threadViolations === undefined ? {} : { threadViolations: rtSafety.threadViolations }),
+    ...(rtSafety.processErrors === undefined ? {} : { processErrors: rtSafety.processErrors }),
+    ...(rtSafety.events === undefined ? {} : { events: rtSafety.events.length }),
+  };
+}
+
+function latencyFiguresOf(latency: QualificationRecord["measurements"]["grid"][number]["latency"]): RecordLatencyFigures | undefined {
+  const declaredFrames = (latency as { declaredFrames?: number } | undefined)?.declaredFrames;
+  const measuredFrames = (latency as { measuredFrames?: number } | undefined)?.measuredFrames;
+  if (declaredFrames === undefined && measuredFrames === undefined) return undefined;
+  return {
+    ...(declaredFrames === undefined ? {} : { declaredFrames }),
+    ...(measuredFrames === undefined ? {} : { measuredFrames }),
+  };
+}
+
+/** Whether the record names a continuous soak reading at this rate (`measurements.behaviour.soak.perRate`). */
+function soakRanAt(record: QualificationRecord, rate: number): boolean {
+  const soak = record.measurements.behaviour?.soak as { readonly perRate?: Readonly<Record<string, unknown>> } | undefined;
+  return soak?.perRate?.[String(rate)] !== undefined;
+}
+
+/**
+ * The figures `plugin-qualify.qualification-record/1` holds at one rate and quantum: the cell the
+ * record's grid names at that pair, else every per-cell figure is absent and `soakRan` alone still
+ * answers for the rate.
+ */
+export function recordFigures(record: QualificationRecord, rate: number, quantum: number): RecordFigures {
+  const point = record.measurements.grid.find((p) => p.rate === rate && p.quantum === quantum);
+  return {
+    ...(point === undefined ? {} : { ...wrapLatency(point.latency), ...wrapCost(point.cost), ...wrapRtSafety(point.rtSafety) }),
+    soakRan: soakRanAt(record, rate),
+    ...(point?.outcome === PROBE_CRASHED ? { crashCode: point.outcome } : {}),
+    ...(point?.outcome === PROBE_TIMEOUT ? { timeoutCode: point.outcome } : {}),
+  };
+}
+
+function wrapLatency(latency: QualificationRecord["measurements"]["grid"][number]["latency"]): Pick<RecordFigures, "latency"> | Record<string, never> {
+  const l = latencyFiguresOf(latency);
+  return l === undefined ? {} : { latency: l };
+}
+
+function wrapCost(cost: QualificationRecord["measurements"]["grid"][number]["cost"]): Pick<RecordFigures, "costNsPerSampleMedian"> | Record<string, never> {
+  return cost === undefined ? {} : { costNsPerSampleMedian: cost.median };
+}
+
+function wrapRtSafety(rtSafety: QualificationRecord["measurements"]["grid"][number]["rtSafety"]): Pick<RecordFigures, "rtSafety"> | Record<string, never> {
+  const rt = rtSafetyFiguresOf(rtSafety);
+  return rt === undefined ? {} : { rtSafety: rt };
+}

package/src/refused-stderr-kept.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * #6's conformance check: a refused row's cause must be readable from the record directory itself,
+ * not summed to a byte count in the probe copy's `logs` entry. #311 copies a child's stderr beside
+ * its record (`stderrCopyFileName`) so the bytes `logs` counts can still be read back; this walks a
+ * records directory and names every refused row where that reading still fails: the count is zero
+ * (nothing was ever captured) or the count is positive but no copy answers it (the count was kept,
+ * the words were not).
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readProbeOutput, sha256Hex, PROBE_OK } from "./probe-output.js";
+import { stderrCopyFileName, type QualificationRecord } from "./qualification-record.js";
+
+export type StderrKeptProblem = "empty-stderr" | "log-line-not-kept";
+
+export interface StderrKeptFinding {
+  readonly record: string;
+  readonly plugin: string;
+  readonly problem: StderrKeptProblem;
+  readonly detail: string;
+}
+
+interface ProbeLogEntry {
+  readonly name?: string;
+  readonly sha256?: string;
+  readonly bytes?: number;
+}
+
+const isRefused = (record: QualificationRecord): boolean => record.probe.outcome !== PROBE_OK || record.verdicts.some((v) => !v.qualified);
+
+/** Every `*.qualification.json` in `dir`, refused rows only, with its parsed record. */
+function refusedRecords(dir: string): { readonly file: string; readonly record: QualificationRecord }[] {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".qualification.json"))
+    .map((file) => ({ file, record: JSON.parse(readFileSync(join(dir, file), "utf8")) as QualificationRecord }))
+    .filter((r) => isRefused(r.record));
+}
+
+/**
+ * Every refused row in `dir` whose child's own words are not readable back from disk: a row whose every run's stderr
+ * was never kept, and a row whose `logs` count bytes a copy beside the record does not answer.
+ */
+export function checkStderrKept(dir: string): StderrKeptFinding[] {
+  const findings: StderrKeptFinding[] = [];
+  for (const { file, record } of refusedRecords(dir)) {
+    const probePath = join(dir, record.probe.file);
+    if (!existsSync(probePath)) {
+      findings.push({ record: file, plugin: record.plugin.id, problem: "empty-stderr", detail: `${record.probe.file}: the probe copy named by the record is not beside it` });
+      continue;
+    }
+    const probeText = readFileSync(probePath, "utf8");
+    const read = readProbeOutput(probeText);
+    if (!read.ok) {
+      findings.push({ record: file, plugin: record.plugin.id, problem: "empty-stderr", detail: `${record.probe.file}: ${read.problem}` });
+      continue;
+    }
+    const probeDoc = JSON.parse(probeText) as { readonly logs?: readonly ProbeLogEntry[] };
+    const logs: readonly ProbeLogEntry[] = Array.isArray(probeDoc.logs) ? probeDoc.logs : [];
+    const written = logs.filter((l) => (l.bytes ?? 0) > 0);
+    if (written.length === 0) {
+      findings.push({ record: file, plugin: record.plugin.id, problem: "empty-stderr", detail: "refused, and no run's child printed anything on stderr" });
+      continue;
+    }
+    for (const entry of written) {
+      const name = entry.name ?? "stderr";
+      if (entry.sha256 === undefined) {
+        findings.push({ record: file, plugin: record.plugin.id, problem: "log-line-not-kept", detail: `${name}: ${String(entry.bytes)} bytes counted, no SHA-256 to find a copy by` });
+        continue;
+      }
+      const copyPath = join(dir, stderrCopyFileName(read.output, entry.sha256));
+      if (!existsSync(copyPath)) {
+        findings.push({ record: file, plugin: record.plugin.id, problem: "log-line-not-kept", detail: `${name}: ${String(entry.bytes)} bytes counted, no copy at ${stderrCopyFileName(read.output, entry.sha256)}` });
+        continue;
+      }
+      const copied = readFileSync(copyPath);
+      if (copied.length === 0 || sha256Hex(copied) !== entry.sha256) {
+        findings.push({ record: file, plugin: record.plugin.id, problem: "log-line-not-kept", detail: `${name}: the copy at ${stderrCopyFileName(read.output, entry.sha256)} is empty or does not match the count` });
+      }
+    }
+  }
+  return findings;
+}

package/src/run-home.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The HOME every process that loads a plugin starts with: a scratch directory of this plugin-qualify run, never the
+ * caller's real home. A plugin that reads its user data from HOME (Surge XT) segfaults or stays silent without one,
+ * and a probe must not write into a user's home. Created on first use, removed when the process exits.
+ */
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+let home: string | undefined;
+
+/** The run's scratch HOME, made on first use. */
+export function runHome(): string {
+  if (home === undefined) {
+    const dir = mkdtempSync(join(tmpdir(), "plugin-qualify-home-"));
+    process.on("exit", () => rmSync(dir, { recursive: true, force: true }));
+    home = join(dir, "home");
+    mkdirSync(home);
+  }
+  return home;
+}
+
+/** `env` with HOME set to the run's scratch HOME. */
+export function withRunHome(env: Readonly<Record<string, string | undefined>>): Record<string, string | undefined> {
+  return { ...env, HOME: runHome() };
+}