@openmixer/plugin-qualify 0.18.1 → 0.18.3

package/src/qualify-declarations.ts

@@ -104,12 +104,17 @@ export const CLAP_QUALIFY_TOOL_ENV = "OMX_CLAP_QUALIFY";
 export const LV2_MEASURE_TOOL_ENV = "OMX_LV2_MEASURE";
 export const RT_INTERPOSE_ENV = "OMX_RT_INTERPOSE";
 export const LV2_HOST_PROBE_TOOL_ENV = "OMX_LV2_HOST_PROBE";
+export const ISOLATED_SIGNAL_TOOL_ENV = "OMX_ISOLATED_SIGNAL";
+/** `native/jack-peak.c`, the level of an instrument under a held note in the adapter run (`tools/mod-host-admit.mjs`). */
+export const JACK_PEAK_TOOL_ENV = "OMX_JACK_PEAK";
 
 /** The file names of the native tools, in every place they are looked for. */
 export const CLAP_QUALIFY_TOOL_NAME = "clap-qualify";
+export const ISOLATED_SIGNAL_TOOL_NAME = "isolated_signal";
 export const LV2_MEASURE_TOOL_NAME = "lv2_measure";
 export const RT_INTERPOSE_NAME = "rt_interpose.so";
 export const LV2_HOST_PROBE_TOOL_NAME = "lv2_host_probe";
+export const JACK_PEAK_TOOL_NAME = "jack_peak";
 
 /**
  * The ONE list of the native tools the packages install, each with the setting that names it.
@@ -120,6 +125,8 @@ export const NATIVE_TOOLS: readonly { readonly name: string; readonly env: strin
   { name: LV2_MEASURE_TOOL_NAME, env: LV2_MEASURE_TOOL_ENV },
   { name: RT_INTERPOSE_NAME, env: RT_INTERPOSE_ENV },
   { name: LV2_HOST_PROBE_TOOL_NAME, env: LV2_HOST_PROBE_TOOL_ENV },
+  { name: ISOLATED_SIGNAL_TOOL_NAME, env: ISOLATED_SIGNAL_TOOL_ENV },
+  { name: JACK_PEAK_TOOL_NAME, env: JACK_PEAK_TOOL_ENV },
 ];
 
 /**

package/src/qualify-isolated.ts

@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+/**
+ * The steps of one plugin's pass, and the last of them: `verdict=isolated` means the plugin was seen running alone in a
+ * worker of its own (plugin-qualify#249). A plugin the RT-safety step finds unsafe takes the isolated step in the same
+ * pass, and so does one that crashed or hung in the probe. The step runs on a private JACK server at the host's rate and
+ * quantum, under a plugin-hostd of its own: the plugin is added alone, `worker_list` must show it alone, and a sine plays
+ * through it for a window. Only a plugin that was added, stayed alive and gave finite, non-silent output is isolated. A
+ * machine that could not run the step decides nothing about the plugin: no verdict word, and the sync tries it again.
+ *
+ * Every record says which steps judged it. {@link missingSteps} is what the sync refuses a record by; a record from before
+ * the steps has no `run` at all, owes the isolated step if its outcome calls for one, and a completion adds it
+ * ({@link completeIsolated}), measuring nothing else.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+import { ADAPTER_PASS_CELLS, startPrivateJack, type JackStarter } from "./qualify-adapter-pass.js";
+import type { GridCell } from "./measurement-grid.js";
+import type { PinEntry } from "./pins-file.js";
+import { PROBE_OK, readProbeOutput } from "./probe-output.js";
+import type { IsolatedFigures, QualificationRecord, RunBlock, RunStep } from "./qualification-record.js";
+import { ISOLATED_SIGNAL_TOOL_ENV, ISOLATED_SIGNAL_TOOL_NAME } from "./qualify-declarations.js";
+import { locateNativeTool, toolsDir } from "./tool-paths.js";
+import { writeFileWhole } from "./whole-file.js";
+
+/** The steps of a pass, in the order they run. */
+export const RUN_STEP = { scan: "scan", describe: "describe", probe: "probe", rtSafety: "rt-safety", isolated: "isolated" } as const;
+
+export const ISOLATED_RESULT = { isolated: "isolated", refused: "refused", notRun: "not-run" } as const;
+
+/** Why the step refused a plugin, or why it could not run. */
+export const ISOLATED_CODE = {
+  crashed: "isolated.crashed",
+  notAdded: "isolated.not-added",
+  noWorker: "isolated.no-worker",
+  notAlone: "isolated.not-alone",
+  nonFinite: "isolated.non-finite-output",
+  silent: "isolated.silent-output",
+  noServer: "isolated.no-private-server",
+  noHost: "isolated.no-host",
+} as const;
+
+/** The outcomes of a probe that take the isolated step as well: the plugin never reached a verdict in-process. */
+const PROBE_FAILED_HARD = new Set(["probe.crashed", "probe.timeout"]);
+
+/** What one run of the step saw. A run that never reached the plugin says `started: false`, and `problem`. */
+export interface IsolatedRunFacts {
+  readonly started: boolean;
+  readonly problem?: string;
+  readonly added?: boolean;
+  /** How many workers `worker_list` showed, and how many instances the plugin's holds. */
+  readonly workers?: number;
+  readonly instancesInWorker?: number;
+  readonly alive?: boolean;
+  readonly latencyFrames?: number;
+  readonly cpuPercent?: number;
+  readonly xruns?: number;
+  readonly finite?: boolean;
+  readonly silent?: boolean;
+}
+
+export type IsolatedRunner = (uri: string, cell: GridCell, env: Readonly<Record<string, string | undefined>>) => IsolatedRunFacts;
+
+/** The decision table of the step, with the figures it took. Pure. */
+export function judgeIsolatedRun(run: IsolatedRunFacts): RunStep {
+  const step = (result: string, code?: string, detail?: string): RunStep => ({
+    step: RUN_STEP.isolated,
+    result,
+    ...(code === undefined ? {} : { code }),
+    ...(detail === undefined ? {} : { detail }),
+    ...(figuresOf(run) === undefined ? {} : { figures: figuresOf(run)! }),
+  });
+  if (!run.started) return step(ISOLATED_RESULT.notRun, ISOLATED_CODE.noHost, run.problem);
+  if (run.added !== true) return step(ISOLATED_RESULT.refused, ISOLATED_CODE.notAdded, run.problem);
+  if (run.alive !== true) return step(ISOLATED_RESULT.refused, ISOLATED_CODE.crashed, run.problem);
+  if ((run.workers ?? 0) < 1) return step(ISOLATED_RESULT.refused, ISOLATED_CODE.noWorker);
+  if (run.workers !== 1 || run.instancesInWorker !== 1) return step(ISOLATED_RESULT.refused, ISOLATED_CODE.notAlone);
+  if (run.finite !== true) return step(ISOLATED_RESULT.refused, ISOLATED_CODE.nonFinite);
+  if (run.silent !== false) return step(ISOLATED_RESULT.refused, ISOLATED_CODE.silent);
+  return step(ISOLATED_RESULT.isolated);
+}
+
+function figuresOf(run: IsolatedRunFacts): IsolatedFigures | undefined {
+  if (run.latencyFrames === undefined && run.cpuPercent === undefined && run.xruns === undefined) return undefined;
+  return {
+    ...(run.latencyFrames === undefined ? {} : { latencyFrames: run.latencyFrames }),
+    ...(run.cpuPercent === undefined ? {} : { cpuPercent: run.cpuPercent }),
+    ...(run.xruns === undefined ? {} : { xruns: run.xruns }),
+  };
+}
+
+/** Whether a record's outcome calls for the isolated step: rated `conditional` by some host, or a probe that crashed or hung. */
+export function owesIsolated(record: QualificationRecord): boolean {
+  return PROBE_FAILED_HARD.has(record.probe.outcome) || record.verdicts.some((v) => v.measured && v.rating === "conditional");
+}
+
+/** 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;
+}
+
+/** The steps a record's outcome calls for. */
+export function stepsCalledFor(record: QualificationRecord): readonly string[] {
+  return [
+    RUN_STEP.scan,
+    RUN_STEP.describe,
+    RUN_STEP.probe,
+    ...(record.probe.outcome === PROBE_OK ? [RUN_STEP.rtSafety] : []),
+    ...(owesIsolated(record) ? [RUN_STEP.isolated] : []),
+  ];
+}
+
+/** The steps a record that carries a `run` lacks, for the sync to refuse it by. A record from before the steps has none to lack. */
+export function missingSteps(record: QualificationRecord): readonly string[] {
+  if (record.run === undefined) return [];
+  const had = new Set(record.run.steps.map((s) => s.step));
+  return stepsCalledFor(record).filter((s) => !had.has(s));
+}
+
+/** The steps every record has by the time it is written, from what it says of them. Pure. */
+export function baseSteps(record: QualificationRecord, describeProblem?: string): RunStep[] {
+  const measured = record.measurements.grid.some((p) => p.rtSafety !== undefined);
+  return [
+    { step: RUN_STEP.scan, result: "ok" },
+    describeProblem === undefined ? { step: RUN_STEP.describe, result: "ok" } : { step: RUN_STEP.describe, result: "failed", detail: describeProblem },
+    { step: RUN_STEP.probe, result: record.probe.outcome },
+    ...(record.probe.outcome === PROBE_OK
+      ? [{ step: RUN_STEP.rtSafety, result: !measured ? "not-measured" : record.verdicts.some((v) => v.rating === "conditional") ? "unsafe" : "safe" }]
+      : []),
+  ];
+}
+
+/** How long the sine plays, and what a step may take beyond it: the host's start and its answers. */
+const ISOLATED_WINDOW_MS = 3000;
+const ISOLATED_STEP_SLACK_MS = 90000;
+
+/** The step as it runs on a device: a private server at the cell, and `tools/isolated-step.mjs` under it. */
+export function spawnedIsolatedRunner(jack: JackStarter = startPrivateJack): IsolatedRunner {
+  return (uri, cell, env) => {
+    const signal = locateNativeTool(ISOLATED_SIGNAL_TOOL_NAME, env, existsSync).path;
+    if (signal === undefined) return { started: false, problem: `no ${ISOLATED_SIGNAL_TOOL_NAME}` };
+    const server = jack(cell);
+    if (server === undefined) return { started: false, problem: `${ISOLATED_CODE.noServer} at ${String(cell.rate)}/${String(cell.quantum)}` };
+    try {
+      const r = spawnSync(process.execPath, [join(toolsDir(), "isolated-step.mjs"), uri, String(ISOLATED_WINDOW_MS)], {
+        encoding: "utf8",
+        timeout: ISOLATED_WINDOW_MS + ISOLATED_STEP_SLACK_MS,
+        killSignal: "SIGKILL",
+        env: { ...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;
+    } finally {
+      server.stop();
+    }
+  };
+}
+
+/** The cell the step runs at: the rate and quantum the host's cost was judged at, else the first cell a Pi runs. */
+export function isolatedCell(record: QualificationRecord, host: string): GridCell {
+  const at = record.cost.find((c) => c.host === host) ?? record.cost[0];
+  return at === undefined ? ADAPTER_PASS_CELLS[0]! : { rate: at.rate, quantum: at.quantum };
+}
+
+/** The pin once the step has spoken: its verdict word follows the step, and a step that could not run leaves none. Pure. */
+export function pinAfterStep(pin: PinEntry | undefined, step: RunStep): PinEntry | undefined {
+  if (pin === undefined) return undefined;
+  const { verdict: _had, ...rest } = pin;
+  if (step.result === ISOLATED_RESULT.isolated) return { ...rest, verdict: "isolated" };
+  if (step.result === ISOLATED_RESULT.refused) return { ...rest, verdict: "refused" };
+  return rest;
+}
+
+/** The run id of a record from before the steps: its probe output's, read from the copy beside it. */
+function runIdOf(record: QualificationRecord, dir: string): string | undefined {
+  if (record.run !== undefined) return record.run.id;
+  if (record.rejudged !== undefined) return record.rejudged.figures.runId;
+  try {
+    const read = readProbeOutput(readFileSync(join(dir, basename(record.probe.file)), "utf8"));
+    return read.ok ? read.output.run.id : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The missing isolated step of a record already judged: the run keeps its id and gains the step, and nothing else is
+ * measured. `undefined` when it owes none, or has no run id to extend. Writes the record whole.
+ */
+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, so a pass tries it again and it takes that one's place
+  if (!owesIsolated(record) || record.run?.steps.some((s) => isStep(s) && s.result !== ISOLATED_RESULT.notRun) === true) return undefined;
+  const id = runIdOf(record, join(path, ".."));
+  if (id === undefined) return undefined;
+  const step = judgeIsolatedRun(runner(uri, cell, env));
+  const run: RunBlock = { id, steps: [...(record.run?.steps ?? baseSteps(record)).filter((s) => !isStep(s)), step] };
+  const next = { ...record, run };
+  writeFileWhole(path, `${JSON.stringify(next, null, 2)}\n`);
+  return { record: next, step };
+}

package/src/qualify-rejudge.ts

@@ -46,7 +46,9 @@ import {
   type QualificationRecord,
   type RecordGridPoint,
   type RecordVerdict,
+  type RunBlock,
 } from "./qualification-record.js";
+import { ISOLATED_RESULT, RUN_STEP, pinAfterStep, provenAlone } from "./qualify-isolated.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";
 import type { SuitabilityRating } from "./rating.js";
@@ -54,6 +56,7 @@ import { writeFileWhole } from "./whole-file.js";
 
 /** The codes of a measurement a record owes. */
 export const OWED_CODE = {
+  isolatedStep: "qualify.sync.isolated-step-owed",
   /** An LV2 verdict of a host that runs it through the adapter, and no measured adapter run. */
   adapterRun: "qualify.sync.adapter-run-owed",
   /** A verdict decided by a run under its host (mod-host, jalv), and no run in the record. */
@@ -192,8 +195,11 @@ export function rejudgeRecord(record: QualificationRecord, probeBytes: Uint8Arra
   if (!read.ok) throw new RejudgeRefusal(`${record.probe.file}: ${read.code}: ${read.problem}`);
   const output = withMemoryRun(read.output, record);
   const { profiles, kept } = rejudgeProfiles(record, output, options.host);
-  const { reasons, owes } = runsOwed(record, output, profiles);
+  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
+  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 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 } };
@@ -263,9 +269,17 @@ const readRecord = (path: string): QualificationRecord | undefined => {
 const nameOf = (record: QualificationRecord): string => record.plugin.id;
 
 /** A state plugin with the verdict its record now holds for the host: the pin's files stay as they are, only its word follows. */
-function pluginWithVerdict(plugin: SyncPlugin, v: RecordVerdict): SyncPlugin {
+function pluginWithVerdict(plugin: SyncPlugin, v: RecordVerdict, run?: RunBlock): SyncPlugin {
   const { pin, code: _code, ...rest } = plugin;
   const word = v.measured ? pinVerdictOf(v.rating as SuitabilityRating) : undefined;
+  // a rating does not make a plugin isolated: a run seen alone does, and a re-judge measures nothing. A record from before
+  // the steps keeps its word until a completion has run it.
+  if (word === "isolated" && run !== undefined) {
+    const step = run.steps.find((s) => s.step === RUN_STEP.isolated);
+    const kept = pinAfterStep(pin, step ?? { step: RUN_STEP.isolated, result: ISOLATED_RESULT.notRun });
+    const refused = step?.result === ISOLATED_RESULT.refused;
+    return { ...rest, outcome: refused ? "refused" : outcomeOfVerdict(v), ...(refused && step.code !== undefined ? { code: step.code } : v.deciding === undefined ? {} : { code: v.deciding }), ...(kept === undefined ? {} : { pin: kept }) };
+  }
   return {
     ...rest,
     outcome: outcomeOfVerdict(v),
@@ -331,7 +345,7 @@ export function rejudgeState(ctx: SyncContext, state: SyncState, now: () => stri
     const plugins = entry.plugins.map((plugin) => {
       const record = plugin.record === undefined ? undefined : judged.get(basename(plugin.record));
       const v = record?.verdicts.find((x) => x.host === hostProfile.id);
-      if (v !== undefined) return pluginWithVerdict(plugin, v);
+      if (v !== undefined) return pluginWithVerdict(plugin, v, record?.run);
       if (record === undefined && plugin.outcome === "unmeasured" && plugin.record?.endsWith(RECORD_SUFFIX) !== true) {
         owing.push({ plugin: plugin.uri, ...(plugin.record === undefined ? {} : { record: basename(plugin.record) }), owes: [{ measurement: "qualification", code: OWED_CODE.noFigures }] });
       }

package/src/qualify-sync.ts

@@ -35,10 +35,11 @@ import type { Judgment } from "./probe-judge.js";
 import { qualifyTargets, type ProbeRun } from "./probe-runner.js";
 import { GRID_FULL, parseGridSpec, type GridSpec } from "./measurement-grid.js";
 import { adapterPass, type AdapterPassOptions, type AdapterPassResult } from "./qualify-adapter-pass.js";
+import { ISOLATED_RESULT, baseSteps, completeIsolated, isolatedCell, missingSteps, judgeIsolatedRun, owesIsolated, pinAfterStep, spawnedIsolatedRunner, type IsolatedRunner } from "./qualify-isolated.js";
 import { lv2World, rejudgeState, memoryPass, type MemoryPassResult, type RejudgeResult } from "./qualify-rejudge.js";
 import { memoryBoundOf, parseMemoryLimit, type MemoryBound } from "./memory-bound.js";
-import { writeQualification, type NotMeasured } from "./qualification-record.js";
-import { DESCRIPTOR_DIR_STATE_SUBDIR, DESCRIPTOR_DIR_SYSTEM, MEMORY_PASS_PROBE_NOTES, QUALIFY_QUANTA, QUALIFY_RATES } from "./qualify-declarations.js";
+import { 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";
 
@@ -139,6 +140,8 @@ export interface SyncArgs {
   readonly memoryOnly: boolean;
   /** `--adapter-only`: the run of each LV2 plugin under the adapter at the Pi's cells, merged into its record. */
   readonly adapterOnly: boolean;
+  /** `--isolated-only`: the missing isolated step of each record already judged, extending its run. */
+  readonly isolatedOnly: boolean;
   readonly help: boolean;
   /** The settings given as flags, by key. */
   readonly values: ReadonlyMap<string, string>;
@@ -158,6 +161,7 @@ export function parseSyncArgs(argv: readonly string[]): { ok: true; args: SyncAr
   let rejudge = false;
   let memoryOnly = false;
   let adapterOnly = false;
+  let isolatedOnly = false;
   let help = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
@@ -169,6 +173,7 @@ export function parseSyncArgs(argv: readonly string[]): { ok: true; args: SyncAr
     else if (a === "--rejudge") rejudge = true;
     else if (a === "--memory-only") memoryOnly = true;
     else if (a === "--adapter-only") adapterOnly = true;
+    else if (a === "--isolated-only") isolatedOnly = true;
     else if (a === "--help") help = true;
     else if (a === "--grid-hosts") values.set("grid", "hosts");
     else if (a === "--config" || byFlag.has(a)) {
@@ -178,9 +183,9 @@ export function parseSyncArgs(argv: readonly string[]): { ok: true; args: SyncAr
       else values.set(byFlag.get(a)!, v);
     } else return { ok: false, error: `unknown argument ${a}` };
   }
-  if (rejudge && (memoryOnly || adapterOnly || force || refreshPinsOnly)) return { ok: false, error: "--rejudge measures nothing: it goes with none of --memory-only, --adapter-only, --force and --refresh-pins" };
-  if ([memoryOnly, adapterOnly, refreshPinsOnly].filter(Boolean).length > 1) return { ok: false, error: "--memory-only, --adapter-only and --refresh-pins are different runs: one at a time" };
-  return { ok: true, args: { ...(config === undefined ? {} : { config }), system, force, noDistributed, noWait, refreshPins: refreshPinsOnly, rejudge, memoryOnly, adapterOnly, help, values } };
+  if (rejudge && (memoryOnly || adapterOnly || isolatedOnly || force || refreshPinsOnly)) return { ok: false, error: "--rejudge measures nothing: it goes with none of --memory-only, --adapter-only, --force and --refresh-pins" };
+  if ([memoryOnly, adapterOnly, isolatedOnly, refreshPinsOnly].filter(Boolean).length > 1) return { ok: false, error: "--memory-only, --adapter-only and --refresh-pins are different runs: one at a time" };
+  return { ok: true, args: { ...(config === undefined ? {} : { config }), system, force, noDistributed, noWait, refreshPins: refreshPinsOnly, rejudge, memoryOnly, adapterOnly, isolatedOnly, help, values } };
 }
 
 export function syncHelpText(): string {
@@ -196,6 +201,7 @@ export function syncHelpText(): string {
     "  --refresh-pins                      only bring every pin's files up to the ones plugin-hostd names, measuring nothing",
     "  --rejudge                           derive every record's verdicts, tiers and pin again from the figures it holds; measures nothing",
     "  --memory-only                       measure only the footprint of each recorded plugin at the Pi's cells and merge it; with --force, those already merged too",
+    "  --isolated-only                     run only the isolated step each record still owes, adding it to the record's run",
     "  --adapter-only                      run each LV2 plugin only under omx-clap-host's LV2 adapter at the Pi's cells, on private JACK servers, and merge it; with --force, those already done too",
     "  --grid-hosts                        the fast grid, the same as --grid hosts (7 cells with the shipped hosts)",
     "  --help                              this text",
@@ -613,6 +619,8 @@ export interface SyncContext {
   readonly log: (line: string) => void;
   /** The run of `plugin-hostd --pin-files`, a stand-in in tests. */
   readonly pinFilesRun?: PinFilesRun;
+  /** The isolated step, a stand-in in tests. */
+  readonly isolatedRunner?: IsolatedRunner;
 }
 
 /**
@@ -696,13 +704,41 @@ 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) });
+
 /** 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 }[]): SyncPlugin[] {
+function judgedPlugins(ctx: SyncContext, runs: readonly { bytes: Buffer; judgment: Judgment }[], describeProblem?: string): SyncPlugin[] {
   const host = ctx.settings.hostProfile.id;
   const entries = runs.map(({ bytes, judgment }) => {
-    const { recordPath } = writeQualification(ctx.settings.qualificationDir, bytes, judgment, QUICK_NOT_MEASURED);
-    const pin = withHostdFiles(ctx, judgmentPinEntries(judgment, host)[0]);
-    const { outcome, code } = outcomeOf(judgment, host);
+    const { recordPath, record } = writeQualification(ctx.settings.qualificationDir, bytes, judgment, QUICK_NOT_MEASURED);
+    const steps = baseSteps(record, describeProblem);
+    let pin = withHostdFiles(ctx, judgmentPinEntries(judgment, host)[0]);
+    let { outcome, code } = outcomeOf(judgment, host);
+    if (owesIsolated(record)) {
+      // in this same pass: a record's verdict=isolated is a run seen alone, never a rating alone
+      const uri = pin?.uri ?? judgment.output.plugin.id;
+      const runner = ctx.isolatedRunner ?? spawnedIsolatedRunner();
+      const step = judgeIsolatedRun(runner(uri, isolatedCell(record, host), isolatedEnv(ctx)));
+      steps.push(step);
+      pin = pinAfterStep(pin, step);
+      // a crash or a hang in the probe stays what it was unless the step saw the plugin run: only a rating waited on the step
+      if (step.result === ISOLATED_RESULT.refused) {
+        if (outcome === "qualified") {
+          outcome = "refused";
+          code = step.code;
+        }
+      } else if (step.result === ISOLATED_RESULT.notRun) {
+        if (outcome === "qualified") {
+          outcome = "unmeasured";
+          code = step.code;
+        }
+      } else if (outcome !== "qualified") {
+        outcome = "qualified";
+        code = undefined;
+      }
+    }
+    rewriteRecord(recordPath, { ...record, run: { id: judgment.output.run.id, steps } });
     const plugin: SyncPlugin = { uri: pin?.uri ?? judgment.output.plugin.id, outcome, ...(code === undefined ? {} : { code }), ...(pin === undefined ? {} : { pin }), record: recordPath };
     return { plugin, judgedHere: judgment.hosts.some((h) => h.verdict.host === host) };
   });
@@ -796,7 +832,7 @@ function qualifyClap(ctx: SyncContext, item: SyncItem): SyncPlugin[] {
     const pass = runPass(ctx, { format: "clap", uri: `urn:clap:${p.id}`, bundle: item.root, binary: item.files[0]!, binaryPath: file }, ctx.env);
     for (const f of pass.failures) out.push({ uri, outcome: "unmeasured", code: SYNC_CODE.notMeasured, detail: f.problem });
     const problem = descriptorFailed.get(p.id);
-    out.push(...judgedPlugins(ctx, pass.runs).map((j) => (problem === undefined ? j : { ...j, descriptorProblem: problem })));
+    out.push(...judgedPlugins(ctx, pass.runs, problem).map((j) => (problem === undefined ? j : { ...j, descriptorProblem: problem })));
   }
   return out;
 }
@@ -826,6 +862,46 @@ export function qualifyItem(ctx: SyncContext, item: SyncItem, files: readonly Fi
   return { format: item.format, root: item.root, files: all, plugins, qualifiedAt: new Date(started).toISOString(), seconds: (Date.now() - started) / 1000 };
 }
 
+/**
+ * The isolated steps the records of a state still owe, each extending its record's run. A plugin's pin follows its step, and
+ * a step that could not run stays owed: the next pass tries it again.
+ */
+export function isolatedPass(ctx: SyncContext, state: SyncState): { readonly state: SyncState; readonly isolated: number; readonly refused: number; readonly notRun: number } {
+  const count = { isolated: 0, refused: 0, notRun: 0 };
+  const runner = ctx.isolatedRunner ?? spawnedIsolatedRunner();
+  const host = ctx.settings.hostProfile.id;
+  const entries: Record<string, SyncEntry> = {};
+  for (const [key, entry] of Object.entries(state.entries)) {
+    entries[key] = {
+      ...entry,
+      plugins: entry.plugins.map((p) => {
+        if (p.record === undefined || !p.record.endsWith(".qualification.json")) return p;
+        const path = join(ctx.settings.qualificationDir, basename(p.record));
+        let record: QualificationRecord;
+        try {
+          record = JSON.parse(readFileSync(path, "utf8")) as QualificationRecord;
+        } catch {
+          ctx.log(`${p.uri}: its record does not read; no isolated step`);
+          return p;
+        }
+        const done = completeIsolated(path, record, p.pin?.uri ?? record.plugin.id, isolatedCell(record, host), runner, isolatedEnv(ctx));
+        if (done === undefined) return p;
+        ctx.log(`${p.uri}: isolated step ${done.step.result}${done.step.code === undefined ? "" : ` (${done.step.code})`}`);
+        const pin = pinAfterStep(p.pin, done.step);
+        const { pin: _pin, code: _code, ...rest } = p;
+        if (done.step.result === ISOLATED_RESULT.isolated) {
+          count.isolated++;
+          return { ...rest, outcome: "qualified" as const, ...(pin === undefined ? {} : { pin }) };
+        }
+        if (done.step.result === ISOLATED_RESULT.refused) count.refused++;
+        else count.notRun++;
+        return { ...rest, outcome: done.step.result === ISOLATED_RESULT.refused ? ("refused" as const) : ("unmeasured" as const), ...(done.step.code === undefined ? {} : { code: done.step.code }), ...(pin === undefined ? {} : { pin }) };
+      }),
+    };
+  }
+  return { ...count, state: count.isolated + count.refused + count.notRun === 0 ? state : { ...state, entries } };
+}
+
 // --- the distributed records ----------------------------------------------------------------------------------------
 
 /** The layer a run reads: none under `--force` or `--no-distributed`, or without a host class. */
@@ -856,6 +932,13 @@ function takeDistributed(ctx: SyncContext, layer: DistributedLayer, item: SyncIt
     for (const line of match.lines) ctx.log(line);
     return undefined;
   }
+  for (const r of match.records) {
+    const missing = missingSteps(r.record);
+    if (missing.length > 0) {
+      ctx.log(`distributed: ${distributedUri(item, r)}: its record lacks the step${missing.length === 1 ? "" : "s"} ${missing.join(", ")}; measured here`);
+      return undefined;
+    }
+  }
   let plugins: SyncPlugin[];
   try {
     plugins = applyDistributed(ctx.settings.qualificationDir, item, match, host);
@@ -1096,6 +1179,8 @@ export interface SyncSummary {
   readonly memoryOnly?: { readonly measured: number; readonly already: number; readonly failed: number };
   /** Every plugin the run measured was unmeasured for this one reason of the machine ({@link machineReason}): the run failed. */
   readonly machineFailure?: string;
+  /** `--isolated-only`: how the steps ended. */
+  readonly isolatedOnly?: { readonly isolated: number; readonly refused: number; readonly notRun: number };
   /** `--adapter-only`: the plugins run, those done already at these host versions, and those whose host could not be run. */
   readonly adapterOnly?: { readonly measured: number; readonly already: number; readonly failed: number };
 }
@@ -1184,6 +1269,10 @@ export interface SyncRunOptions {
   readonly rejudge?: boolean;
   /** `--memory-only`: take only the footprints; `force` takes those already merged again. */
   readonly memoryOnly?: boolean;
+  /** The isolated step, a stand-in in tests. */
+  readonly isolatedRunner?: IsolatedRunner;
+  /** `--isolated-only`: take only the isolated steps records still owe. */
+  readonly isolatedOnly?: boolean;
   /** `--adapter-only`: take only the adapter runs; `force` takes those already done again. */
   readonly adapterOnly?: boolean;
   /** Stand-ins for the pass's hosts, in tests. */
@@ -1251,6 +1340,7 @@ function addSummaries(a: SyncSummary, b: SyncSummary): SyncSummary {
     ...(refreshed === 0 ? {} : { refreshed }),
     ...(b.rejudge === undefined ? (a.rejudge === undefined ? {} : { rejudge: a.rejudge }) : { rejudge: b.rejudge }),
     ...(b.memoryOnly === undefined ? (a.memoryOnly === undefined ? {} : { memoryOnly: a.memoryOnly }) : { memoryOnly: b.memoryOnly }),
+    ...(b.isolatedOnly === undefined ? (a.isolatedOnly === undefined ? {} : { isolatedOnly: a.isolatedOnly }) : { isolatedOnly: b.isolatedOnly }),
     ...(b.adapterOnly === undefined ? (a.adapterOnly === undefined ? {} : { adapterOnly: a.adapterOnly }) : { adapterOnly: b.adapterOnly }),
   };
 }
@@ -1276,7 +1366,7 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
   {
     const started = Date.now();
     const dirs = [...settings.clapDirs, ...settings.lv2Dirs];
-    const ctx: SyncContext = { settings, env, log, ...(options.pinFilesRun === undefined ? {} : { pinFilesRun: options.pinFilesRun }) };
+    const ctx: SyncContext = { settings, env, log, ...(options.pinFilesRun === undefined ? {} : { pinFilesRun: options.pinFilesRun }), ...(options.isolatedRunner === undefined ? {} : { isolatedRunner: options.isolatedRunner }) };
     // the pins first, before the quiet wait and any measurement: an upgrade of plugin-hostd that collects more files
     // than the pins on disk hold refuses those plugins until their pins name them (plugin-qualify#239)
     const fresh = refreshPins(ctx, readSyncState(settings.stateFile, log));
@@ -1290,6 +1380,12 @@ async function runLocked(settings: SyncSettings, options: SyncRunOptions): Promi
       const summary = await sendRefreshed(settings, r.state, fresh.refreshed.length, started, log);
       return { ...summary, rejudge: { changed: r.changed, unchanged: r.unchanged, owing: r.owing.length } };
     }
+    if (options.isolatedOnly === true) {
+      const r = isolatedPass(ctx, fresh.state);
+      if (r.state !== fresh.state) writeFileWhole(settings.stateFile, `${JSON.stringify(r.state, null, 1)}\n`);
+      const summary = await sendRefreshed(settings, r.state, fresh.refreshed.length, started, log);
+      return { ...summary, isolatedOnly: { isolated: r.isolated, refused: r.refused, notRun: r.notRun } };
+    }
     if (options.adapterOnly === true) {
       const r: AdapterPassResult = adapterPass(ctx, fresh.state, { ...options.adapterPass, force: options.force === true });
       log(`adapter runs under ${Object.entries(r.versions).map(([k, v]) => `${k} ${v}`).join(", ")}`);

package/tools/isolated-step.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+// One isolated step (plugin-qualify#249): a plugin-hostd of its own on the JACK server the environment names, the plugin
+// added alone, worker_list read, a sine through it for a window, and worker_list read again. Prints one JSON line for
+// src/qualify-isolated.ts to judge. A host that never listened says started: false: nothing was learned about the plugin.
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { createConnection } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+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;
+// the sync gives each command its budget: a plugin that hangs in add ends there
+const COMMAND_MS = Number(process.env.OMX_ADMIT_STEP_MS ?? 0) || 30000;
+const INSTANCE = 0;
+const CLOCK_TICKS = 100;
+const WORKER_SPAWN = -503;
+
+const state = mkdtempSync(join(tmpdir(), "plugin-qualify-isolated-"));
+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]), instances: (f[7] ?? "").split(",").filter(Boolean) };
+  });
+
+function cpuTicks(pid) {
+  try {
+    const after = readFileSync(`/proc/${String(pid)}/stat`, "utf8").replace(/^.*\) /, "").split(" ");
+    return Number(after[11]) + Number(after[12]);
+  } catch {
+    return undefined;
+  }
+}
+
+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)}`);
+  // 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)}` };
+  const before = workersOf(await send("worker_list"));
+  const worker = before[0];
+  const ticksBefore = worker === undefined ? undefined : cpuTicks(worker.pid);
+  const signal = spawnSync(signalTool, [`effect_${String(INSTANCE)}`, String(windowMs)], { encoding: "utf8", timeout: windowMs + 15000, killSignal: "SIGKILL" });
+  const ticksAfter = worker === undefined ? undefined : cpuTicks(worker.pid);
+  const after = workersOf(await send("worker_list"));
+  sock.destroy();
+  const alive = after.length > 0 && after[0].pid === worker?.pid && ticksAfter !== undefined;
+  if (signal.error !== undefined || signal.status !== 0) {
+    if (signal.status === 2 && alive) return { started: false, problem: `isolated_signal: ${signal.stderr.trim()}` };
+    return { started: true, added: true, alive, workers: before.length, instancesInWorker: worker?.instances.length ?? 0, problem: signal.stderr?.trim() };
+  }
+  const heard = JSON.parse(signal.stdout);
+  return {
+    started: true,
+    added: true,
+    alive,
+    workers: before.length,
+    instancesInWorker: worker?.instances.length ?? 0,
+    latencyFrames: heard.latencyFrames,
+    xruns: heard.xruns,
+    finite: heard.finite,
+    silent: heard.silent,
+    ...(ticksBefore === undefined || ticksAfter === undefined ? {} : { cpuPercent: ((ticksAfter - ticksBefore) * 100000) / CLOCK_TICKS / windowMs }),
+  };
+}
+
+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);