@meshbench/client 0.0.1

package/lib/nodes.mjs

@@ -0,0 +1,416 @@
+// The network: what is in it, and what one node can be asked to do.
+
+import { NotFound } from "./errors.mjs";
+import { Device } from "./device.mjs";
+import { Kind, Transport } from "./sets.mjs";
+import { FIRMWARE_WAIT_MS, waitFor } from "./wait.mjs";
+
+/** The score below which `find` will not act on a top answer.
+ *
+ *  Taking the top result unconditionally is how a script ends up sending an
+ *  advert from a node that merely shared a word with what was asked for, and it
+ *  does that silently. */
+export const FIND_LEAST = 0.5;
+
+/** Names, whether handles or strings were passed.
+ *
+ *  `search` and `near` hand back handles and every verb takes names, so without
+ *  this each caller writes the same map - and the one that forgets sends an
+ *  object down the socket and is told there is no node named "[object
+ *  Object]". */
+const names = (ns) => ns.map((n) => String(n));
+
+/** The collection. Live: every call reads the session. */
+export class Nodes {
+  constructor(wb) { this._wb = wb; }
+
+  /** Every node, as the network currently has them. */
+  async list() {
+    return ((await this._wb.call("nodes.list")) || {}).nodes || [];
+  }
+
+  /** How many there are. */
+  async count() { return (await this.list()).length; }
+
+  /** One by name. */
+  async info(name) {
+    for (const n of await this.list()) if (n.name === String(name)) return n;
+    throw new NotFound("nodes.list", `no node named "${name}"`, "not_found");
+  }
+
+  /** Whether the network holds one by that name. */
+  async has(name) {
+    return (await this.list()).some((n) => n.name === String(name));
+  }
+
+  /** A handle, checked: a typo fails here rather than three calls later. */
+  async get(name) {
+    await this.info(name);
+    return new Node(this._wb, String(name));
+  }
+
+  /** Find nodes by name, best first, when you cannot type the name.
+   *
+   *  Imported names carry emoji and accents - "\u{1F3D4}️ West Lomond \u{1F4E1}"
+   *  is one real node - so matching is done on letters and digits alone, with
+   *  accents folded and word order ignored. The ranking happens at the workbench
+   *  rather than here, so all three clients agree about which result is the top
+   *  one.
+   *
+   *  An empty result is not an error: "nothing matched" is an answer, and the
+   *  caller usually wants to widen the query rather than handle a refusal. */
+  async search(query, limit = 10) {
+    const got = await this._wb.call("nodes.search", { query, limit });
+    return (got || {}).matches || [];
+  }
+
+  /** The one node a search meant, or a refusal naming what it did find. */
+  async find(query, least = FIND_LEAST) {
+    const matches = await this.search(query, 5);
+    if (matches.length === 0 || matches[0].score < least) {
+      const near = matches.slice(0, 3)
+        .map((m) => `"${m.name}" (${m.score.toFixed(2)})`).join(", ");
+      throw new NotFound("nodes.search",
+        `nothing matches "${query}" well enough` +
+        (near ? `; nearest were ${near}` : ""), "not_found");
+    }
+    return new Node(this._wb, matches[0].name);
+  }
+
+  /** The nodes closest to this one, nearest first, at most `count` of them (all
+   *  of them when it is zero).
+   *
+   *  Trimming an imported deployment to a neighbourhood is the first thing
+   *  anybody does with one, and the distance is the workbench's own - the same
+   *  great circle its path losses use. */
+  async near(node, count = 0) {
+    const got = await this._wb.call("nodes.near", { node: String(node), count });
+    return (got || {}).near || [];
+  }
+
+  /** Filter by kind. Evaluated here rather than at the workbench: it is a
+   *  question about a list somebody already has. */
+  async ofKind(kind) {
+    return (await this.list()).filter((n) => n.kind === kind);
+  }
+
+  /** Put one node down, and hand back a handle to it.
+   *
+   *  It inherits its neighbours' regions and their firmware, because somebody
+   *  dropping a repeater on a map is adding a repeater to this network, not
+   *  choosing a firmware strategy.
+   *
+   *  A board name nothing matches is refused rather than ignored: the board
+   *  decides the transmit ceiling, the noise figure and the battery, so a silent
+   *  fallback would be a different node answering the question. */
+  async place({ name, kind = Kind.SIMPLE_REPEATER, lat = 0, lon = 0,
+    heightM, txDbm, board } = {}) {
+    const params = { name, kind, lat, lon };
+    if (heightM !== undefined) params.height_m = heightM;
+    if (txDbm !== undefined) params.tx_dbm = txDbm;
+    if (board) params.board = board;
+    await this._wb.call("nodes.place", params);
+    return new Node(this._wb, name);
+  }
+
+  /** Put several down, then measure the links once.
+   *
+   *  One warm at the end rather than one per node: nodes.place re-measures the
+   *  matrix each time, and on a national network that is minutes repeated. */
+  async placeMany(placements) {
+    const out = [];
+    for (const p of placements) out.push(await this.place(p));
+    await this._wb.call("links.recompute");
+    return out;
+  }
+
+  /** Remove them, in one rebuild.
+   *
+   *  All or none: a name that is not there refuses and removes nothing, because
+   *  half a deletion leaves a scenario nobody described and no way to tell which
+   *  half survived without asking again. */
+  async delete(...nodes) {
+    if (nodes.length) await this._wb.call("nodes.delete_many", names(nodes));
+  }
+
+  /** Delete everything these do not name.
+   *
+   *  The complement is worked out at the workbench rather than here, so it
+   *  cannot be computed against a list that changed in between. */
+  async keep(...nodes) {
+    await this._wb.call("nodes.keep", names(nodes));
+  }
+
+  /** Replace the selection, or add to it. */
+  async select(nodes, { add = false } = {}) {
+    await this._wb.call(add ? "nodes.add_to_selection" : "nodes.select_many",
+      names(nodes));
+  }
+
+  /** Who is selected now. */
+  async selected() {
+    return (await this.list()).filter((n) => n.selected).map((n) => n.name);
+  }
+
+  /** Sample what every node is costing, rather than waiting for the window to
+   *  ask. */
+  async stats() { return this._wb.nodeStats(); }
+
+  /** Give every node the same antenna, or every node of one kind.
+   *
+   *  The fleet-level default, and the only way a large scenario gets one:
+   *  setting fifty-eight nodes by hand is not a workflow anybody will use. What
+   *  is not named is left alone, so this can retune the whole mesh's feedlines
+   *  without restating what is on top of the masts. */
+  async setAntenna({ kind = "", ...change } = {}) {
+    const p = antennaParams(change);
+    if (kind) p.kind = kind;
+    await this._wb.call("nodes.antenna", p);
+  }
+}
+
+/** What an antenna change says, in the wire's own spelling.
+ *
+ *  What is left out is left alone, because "leave this" and "set it to zero"
+ *  are different answers and one number cannot say both. */
+function antennaParams({ pattern, gainDbiPeak, beamwidthDeg, frontToBackDb,
+  bearingDeg, downtiltDeg, polarisation, feedlineDb } = {}) {
+  const p = {};
+  if (pattern !== undefined) p.pattern = pattern;
+  if (gainDbiPeak !== undefined) p.gain_dbi_peak = gainDbiPeak;
+  if (beamwidthDeg !== undefined) p.beamwidth_deg = beamwidthDeg;
+  if (frontToBackDb !== undefined) p.front_to_back_db = frontToBackDb;
+  if (bearingDeg !== undefined) p.bearing_deg = bearingDeg;
+  if (downtiltDeg !== undefined) p.downtilt_deg = downtiltDeg;
+  if (polarisation !== undefined) p.polarisation = polarisation;
+  if (feedlineDb !== undefined) p.feedline_db = feedlineDb;
+  return p;
+}
+
+/** One node. Live: a handle, not a copy - it holds a name and asks. */
+export class Node {
+  constructor(wb, name) {
+    this._wb = wb;
+    this.name = name;
+  }
+
+  toString() { return this.name; }
+
+  // ---- what it is ------------------------------------------------------
+
+  /** What the network says about it, now. */
+  async info() { return new Nodes(this._wb).info(this.name); }
+
+  /** Its row from the statistics sample, or null when it has none yet. */
+  async stat() {
+    return (await this._wb.nodeStats()).find((s) => s.name === this.name) || null;
+  }
+
+  /** Whether its firmware process is up. */
+  async running() {
+    const s = await this.stat();
+    return Boolean(s && s.running);
+  }
+
+  /** "running", "stopped", or one of the transitions. A boolean cannot say
+   *  "changing firmware", and a row that goes blank while it happens looks like
+   *  a node that has died. */
+  async state() {
+    const s = await this.stat();
+    return s ? s.state : "unknown";
+  }
+
+  /** The build this node runs, or null when it is pinned to nothing.
+   *
+   *  The whole row rather than the version string, because deleting a build or
+   *  comparing two needs its path and its board, and reassembling those from a
+   *  version is the kind of guesswork that deletes the wrong file. */
+  async build() {
+    const want = (await this.info()).firmware;
+    if (!want) return null;
+    return (await this._wb.firmware.library()).find((b) => b.version === want) || null;
+  }
+
+  /** What this node's radio is set to - the same thing the workbench shows
+   *  under Radio. What the model assumes, and, for a node that is running, what
+   *  it reports back and where the two differ. Left as the workbench sent it
+   *  because a repeater and a companion answer it differently. */
+  async radio() {
+    return (await this._wb.call("node.radio", { node: this.name })) || {};
+  }
+
+  /** What this node stands under, and which way it points.
+   *
+   *  Gain is directional in azimuth, so `bearing_deg` is not decoration: a beam
+   *  is twenty decibels or more down off its boresight, and which way it faces
+   *  decides which links close. */
+  async antenna() {
+    return (await this._wb.call("node.antenna", { node: this.name })) || {};
+  }
+
+  /** Choose and aim this node's antenna. What is not named is left alone, so
+   *  turning a beam does not restate the beam. */
+  async setAntenna(change) {
+    const p = antennaParams(change);
+    p.node = this.name;
+    await this._wb.call("nodes.antenna", p);
+  }
+
+  /** Turn this node's antenna towards another node.
+   *
+   *  The bearing between two placed nodes is exact, so this is a better answer
+   *  than reading one off a map and typing it back. What comes back says what
+   *  the turn won, which on an omni is nothing. */
+  async aim(at) {
+    return (await this._wb.call("node.aim",
+      { node: this.name, at: String(at) })) || {};
+  }
+
+  // ---- what it does ----------------------------------------------------
+
+  async start() { await this._wb.call("node.start", this.name); }
+
+  async stop() { await this._wb.call("node.stop", this.name); }
+
+  /** Remove it from the scenario, and re-measure what is left. */
+  async delete() { await this._wb.call("nodes.delete", { node: this.name }); }
+
+  /** Put it somewhere else. The physics moves with it: cached losses for this
+   *  node are forgotten. */
+  async move(lat, lon) {
+    await this._wb.call("nodes.move", { node: this.name, lat, lon });
+  }
+
+  /** What this node relays flood traffic for. */
+  async setRegions(...regions) {
+    await this._wb.call("nodes.regions", { node: this.name, regions });
+  }
+
+  /** Change what it runs.
+   *
+   *  Applied by default, which means stop, provision, start: firmware is chosen
+   *  when a node launches, so recording it and leaving the node on its old build
+   *  is the control somebody presses twice and then distrusts. Pass
+   *  `{apply: false}` to record it for the next start instead - and know that is
+   *  what you have done. */
+  async setFirmware(build, { apply = true } = {}) {
+    const b = typeof build === "string" ? { version: build } : build;
+    await this._wb.call(apply ? "node.set_firmware" : "node.set_firmware_only", {
+      node: this.name, version: b.version,
+      board: b.board || "", role: b.role || "",
+    });
+  }
+
+  /** What hardware this node is.
+   *
+   *  A change to the physics rather than a label, so it rebuilds and re-warms -
+   *  and it clears a firmware pin made for a different board, because that image
+   *  cannot run on this one and a pin nobody can honour reads as a configured
+   *  node right up until it refuses to start. */
+  async setBoard(board) {
+    await this._wb.call("node.set_board", { node: this.name, board });
+  }
+
+  /** Take waveform verdicts whatever the run's mode - the hybrid flag, for
+   *  measuring one node honestly inside a cheap run. */
+  async setTrueRF(on = true) {
+    await this._wb.call("node.truerf", { node: this.name, on });
+  }
+
+  /** Originate a packet without firmware.
+   *
+   *  It exercises the radio model and the channel; what it does not exercise is
+   *  relaying, which is a firmware behaviour and needs a firmware. */
+  async inject() { await this._wb.call("sim.inject", this.name); }
+
+  /** What this node is told at boot, in the console's own words. */
+  async provisioning() {
+    return ((await this._wb.call("node.provisioning", this.name)) || {}).commands || [];
+  }
+
+  /** Hand this companion to a real client - meshcore-cli, or an app over a
+   *  bridge - and say where to point it. */
+  async serve(over = Transport.TCP) {
+    const got = await this._wb.call("bench.serve", { node: this.name, kind: over });
+    return (got || {}).addr || "";
+  }
+
+  /** Take it back. */
+  async unserve() { await this._wb.call("bench.drop", { node: this.name }); }
+
+  // ---- looking at it ---------------------------------------------------
+
+  /** What this node printed, from one of four voices - the lines, not a count
+   *  of them.
+   *
+   *  "serial" is the board's own port (a native node's standard error), "boot"
+   *  is the ROM's on a board whose application talks over USB, "emulator" is
+   *  what QEMU or Renode said about running it, and "radio" is the radio
+   *  model's log. A board that has gone quiet is read by looking at what it last
+   *  said. */
+  async output(source = "serial", lines = 200) {
+    const got = await this._wb.call("node.output",
+      { node: this.name, source, lines });
+    return (got || {}).tail || [];
+  }
+
+  /** Open one of this node's logs in a window of its own.
+   *
+   *  A tab is one pane. What people do while a board is misbehaving is watch its
+   *  screen and two of its logs together - what the board printed beside what
+   *  the emulator said about running it - and that needs windows. */
+  async outputWindow(source = "serial") {
+    await this._wb.call("node.output_window", { node: this.name, source });
+  }
+
+  /** This node's console, on whichever of the two verbs its kind reads. */
+  get console() { return this._wb.console(this.name); }
+
+  /** This node as a device to drive: its screen, buttons and panel. All of it
+   *  works headless - the display is the framebuffer the controller holds, not a
+   *  picture of the desktop. */
+  get device() { return new Device(this._wb, this.name); }
+
+  // ---- its storage -----------------------------------------------------
+
+  /** What is in this node's card slot, and changing it.
+   *
+   *  A slot is not a fitted card: the board says the slot exists, this says
+   *  whether it is filled. `file` hands the node a card of your own - shared
+   *  between runs, or prepared in advance; an empty string returns it to its
+   *  own, named after it and kept beside its flash. `wipe` erases it, which is
+   *  what reformatting one is, and is refused while the node is running.
+   *
+   *  A firmware marked as needing a card fills the slot whatever this says,
+   *  because a build that keeps its settings there boots into nothing without
+   *  one. */
+  async card({ fitted, file, wipe = false } = {}) {
+    const p = { node: this.name };
+    if (fitted !== undefined) p.fitted = fitted;
+    if (file !== undefined) p.file = file;
+    if (wipe) p.wipe = true;
+    return (await this._wb.call("node.card", p)) || {};
+  }
+
+  /** Put this board back to factory: its flash, its card, its files.
+   *
+   *  A board keeps what it was told between runs, as hardware does, so a node
+   *  configured into a corner stays there until this is called. Refused while it
+   *  is running, rather than rewriting a flash underneath the emulator holding
+   *  it. */
+  async wipe() { await this._wb.call("node.wipe", { node: this.name }); }
+
+  // ---- waiting ---------------------------------------------------------
+
+  /** Wait for its firmware process to be up.
+   *
+   *  `timeoutMs` is wall clock - how long you are prepared to sit here - not
+   *  simulated time. Starting a process is real work on the real machine. */
+  waitRunning(timeoutMs = FIRMWARE_WAIT_MS) {
+    return waitFor(async () => {
+      const s = await this.stat();
+      if (s && s.running) return [true, ""];
+      return [false, s ? s.state : "no stat row yet"];
+    }, timeoutMs, `firmware on ${this.name}`);
+  }
+}

package/lib/pairing.mjs

@@ -0,0 +1,65 @@
+// Which workbench this client may drive.
+//
+// A client and the workbench it drives must be the same release. The protocol
+// number beside this rule says whether two ends can understand each other's
+// frames; it moves rarely and on purpose, so it cannot answer the question a
+// script actually has, which is whether the package in this node_modules is the
+// one that came with the workbench on the PATH. Two releases apart with no
+// protocol bump between them connect happily and then disagree about a verb's
+// parameters, forty calls in, looking like the simulation misbehaving.
+
+import fs from "node:fs";
+
+/** The wire version this client speaks. A workbench answering anything else is
+ *  refused rather than failing halfway through a script. */
+export const PROTOCOL = 1;
+
+/** The release this client belongs to, as npm spells it.
+ *
+ *  Read from its own package.json rather than kept as a second literal here:
+ *  the release workflow runs `npm version`, which rewrites that file and
+ *  nothing else, and a copy in this module would be a copy somebody has to
+ *  remember. Empty if it cannot be read, which is the same thing a build from a
+ *  working copy would say and is treated the same way. */
+export const RELEASE = readRelease();
+
+function readRelease() {
+  try {
+    const p = new URL("../package.json", import.meta.url);
+    return JSON.parse(fs.readFileSync(p, "utf8")).version || "";
+  } catch {
+    return "";
+  }
+}
+
+/** Whether these two releases may be used together: an exact match, or one of
+ *  the two ends not being a release at all.
+ *
+ *  The second half of the rule is what keeps the tree usable by the people
+ *  working on it: a workbench built from a working copy has no release stamped
+ *  in it, so insisting on equality would refuse every pair a developer has, for
+ *  a disagreement that does not exist. Nothing is lost, because what the rule
+ *  catches is a released client meeting a released workbench of another number,
+ *  and both ends of that pair carry their stamp. */
+export function pairedRelease(ours, theirs) {
+  return !ours || !theirs || ours === theirs;
+}
+
+/** What to say about a check that did not compare anything, so a pair nothing
+ *  verified is visible rather than quietly assumed sound. Returned rather than
+ *  logged: a client is a library, and a script that wants the line can print
+ *  it. */
+export function pairingNote(ours, theirs) {
+  if (!ours && !theirs) {
+    return "release check skipped: neither this client nor the workbench is a release build";
+  }
+  if (!ours) {
+    return "release check skipped: this client is a development build; " +
+      `the workbench is ${theirs}`;
+  }
+  if (!theirs) {
+    return "release check skipped: the workbench is a development build; " +
+      `this client is ${ours}`;
+  }
+  return "";
+}

package/lib/parts.mjs

@@ -0,0 +1,190 @@
+// The rest of a scripted run: the project, what happened, and what a node said.
+
+import { refusal } from "./errors.mjs";
+import { Kind } from "./sets.mjs";
+import { EVENT_WAIT_MS, JOB_WAIT_MS, waitFor } from "./wait.mjs";
+
+/** Opening, saving, and starting over. Live. */
+export class Project {
+  constructor(wb) { this._wb = wb; }
+
+  /** An empty network.
+   *
+   *  With a place it becomes the study area and the map is framed on it,
+   *  because those are the same wish - and because a blank network with no
+   *  place is a map in the middle of the Atlantic. */
+  async new(place = "") {
+    await this._wb.call("project.new", place ? { place } : {});
+  }
+
+  /** Load a fixture or a saved project. */
+  async open(path) { await this._wb.call("project.open", path); }
+
+  /** Write the current one out. Worth doing before anything that might restart
+   *  the process: the scenario lives in the process, not on disk. */
+  async save(name) {
+    return ((await this._wb.call("project.save", { name })) || {}).path || "";
+  }
+
+  /** What has been saved. */
+  async list() {
+    return ((await this._wb.call("project.list")) || {}).projects || [];
+  }
+}
+
+/** What the engine has done. Live. */
+export class Events {
+  constructor(wb) { this._wb = wb; }
+
+  /** The tail - the events themselves, not a count of them.
+   *
+   *  A tail, and only a tail: the store keeps a bounded one because a long run
+   *  has millions, so a script that needs all of them dumps per round rather
+   *  than polling this. Reading only the tail after a busy flood samples the
+   *  most congested moment of it, which is a mistake already made once here. */
+  async recent(limit = 50) {
+    return ((await this._wb.call("events.recent", { limit })) || {}).events || [];
+  }
+
+  /** How many there have been, which is the cheap question. */
+  async total() {
+    return ((await this._wb.call("events.recent", { limit: 1 })) || {}).total || 0;
+  }
+
+  /** Write every event held to a file, one JSON object per line. */
+  async dump(path) {
+    return ((await this._wb.call("events.dump", { path })) || {}).written || 0;
+  }
+
+  /** Wait for an event to match, and return it.
+   *
+   *  Empty fields match anything, so waiting for "any reception at Glenrothes"
+   *  is `{kind: "rx", to: "Glenrothes"}` and not a predicate somebody has to
+   *  write. */
+  async wait({ kind = "", from = "", to = "", timeoutMs = EVENT_WAIT_MS } = {}) {
+    const matches = (e) =>
+      (!kind || e.kind === kind) && (!from || e.from === from) && (!to || e.to === to);
+    let found = null;
+    const want = [kind, from && `from ${from}`, to && `to ${to}`]
+      .filter(Boolean).join(" ") || "anything";
+    await waitFor(async () => {
+      const evs = await this.recent(500);
+      found = evs.find(matches) || null;
+      if (found) return [true, ""];
+      return [false, `${evs.length} events, none matching`];
+    }, timeoutMs, `an event matching ${want}`);
+    return found;
+  }
+}
+
+/** One node's firmware console. Live.
+ *
+ *  Two consoles, not one, and which you get depends on what the node is.
+ *
+ *  A repeater has a text CLI and reads typed bytes. A companion does not: it
+ *  speaks the framed companion protocol, and its command line is meshcore-cli's
+ *  vocabulary - `advert`, `public <msg>`, `chan <n> <msg>`, and there is no
+ *  `send`. Typing text at a companion goes nowhere, is echoed locally, and
+ *  reads exactly like a command that ran and did nothing.
+ *
+ *  So this picks the right one from the node's kind. A caller should not have to
+ *  know, and every caller that did know got it wrong at least once. */
+export class Console {
+  constructor(wb, node) {
+    this._wb = wb;
+    this.node = node;
+  }
+
+  /** Whether this node's console is the framed protocol.
+   *
+   *  A node this client cannot see is not one to guess about; the typed verb is
+   *  the fallback and its refusal says so in its own words. */
+  async _framed() {
+    try {
+      const info = await this._wb.nodes.info(this.node);
+      return info.kind === Kind.COMPANION || info.kind === Kind.ROOM_SERVER;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Type a line at it. */
+  async send(line) {
+    const verb = (await this._framed()) ? "console.cli" : "console.type";
+    await this._wb.call(verb, { node: this.node, command: line });
+  }
+
+  /** The scrollback, newest last - the lines themselves.
+   *
+   *  They come back under "tail" and "lines" is how many there are in total, so
+   *  reading "lines" hands you a number where you asked for text. The tail is
+   *  the last 200; a node up for an hour has thousands and nobody reads the
+   *  first one. */
+  async read() {
+    return ((await this._wb.call("console.read", { node: this.node })) || {}).tail || [];
+  }
+
+  /** Send a line and wait for the node to answer it.
+   *
+   *  The important one. A node reads its serial input on its next loop and its
+   *  loop only runs when the engine steps, so reading straight after sending
+   *  reads the moment before the command was sent - every script that has done
+   *  this by hand got an empty reply and concluded the console was broken. This
+   *  gives the mesh its own time first, by stepping when the run is paused. */
+  async ask(line, steps = 100) {
+    const before = await this.read();
+    await this.send(line);
+    const sim = this._wb.sim;
+    const st = await sim.state();
+    if (st.playing) {
+      // Already moving, so it will be answered on its own; give it the same
+      // amount of the mesh's time a settle would.
+      await sim.waitUntil((st.now_ms || 0) + steps * Math.max(st.step_ms || 1, 1),
+        2 * 60_000);
+    } else {
+      await sim.settle(steps);
+    }
+    const after = await this.read();
+    return after.length > before.length ? after.slice(before.length).join("\n") : "";
+  }
+}
+
+/** A long operation the workbench is doing. Live: a handle to an id. */
+export class Job {
+  constructor(wb, id) {
+    this._wb = wb;
+    this.id = id;
+  }
+
+  /** Where this job has got to, or null when it is no longer listed - which
+   *  means finished, because a job that has ended is removed. */
+  async info() {
+    return (await this._wb.jobs()).find((j) => j.id === this.id) || null;
+  }
+
+  /** Stop it, where whoever started it left a way to.
+   *
+   *  A job with no cancel refuses by name rather than silently doing nothing:
+   *  an operator who asked deserves to be told, not left watching a bar that
+   *  carries on. */
+  async cancel() { await this._wb.call("job.cancel", { id: this.id }); }
+
+  /** Wait for it to finish, and throw if it finished badly.
+   *
+   *  Ended is not the same as worked: a read that failed used to finish the job
+   *  with the reason in its title and nothing else, so every caller either
+   *  carried on as though it had succeeded or matched on the wording. */
+  async wait(timeoutMs = JOB_WAIT_MS) {
+    let last = null;
+    await waitFor(async () => {
+      const info = await this.info();
+      if (info === null) return [true, ""];
+      last = info;
+      if (info.finished) return [true, ""];
+      return [false, `${info.what}, ${info.done} of ${info.total}`];
+    }, timeoutMs, `job ${this.id}`);
+    if (last && last.failed) {
+      throw refusal("job", `job ${this.id} failed: ${last.what}`, "internal");
+    }
+  }
+}