moshcode 0.73.0 → 0.75.0

package/src/mirror.mjs

@@ -56,6 +56,28 @@ export function pressKey(name, rl = null, stdin = process.stdin) {
 const FLUSH_MS = 150;      // batch writes so a busy render is one request, not fifty
 const MAX_BUFFER = 16000;  // flush early once a batch gets big
 
+// Where a child process's output should be copied while a mirror is watching.
+//
+// Module-level rather than threaded through every call, because "is anyone
+// watching this pit" is one fact about the process and the launchers that need
+// it are scattered: the shell, the installers, the upgrader, the plugin/skill/
+// MCP hand-offs. Passing it down by hand is what left most of them writing
+// straight to the tty with the session page showing nothing — each new launcher
+// had to remember, and none of them did. src/pty.mjs reads this as its default,
+// so capture is what a launcher gets for free and opting out is the deliberate
+// act.
+let activeSink = null;
+
+/** Point child capture at this mirror (or null when the pit stops mirroring). */
+export function setActiveSink(sink) {
+  activeSink = typeof sink === "function" ? sink : null;
+}
+
+/** The sink a child's output should be copied to, or null when unmirrored. */
+export function activeChildSink() {
+  return activeSink;
+}
+
 export function createMirror({
   version = "",
   cwd = process.cwd(),

package/src/payments.mjs

@@ -22,6 +22,7 @@
 // `/payments connect stripe` records a *reference* — vault and key name — and
 // says out loud where the secret should go.
 import { spawnSync } from "node:child_process";
+import { captureSpec } from "./pty.mjs";
 
 import { loadBusiness, updateBusiness } from "./business-store.mjs";
 import { parseFields } from "./clients.mjs";
@@ -178,7 +179,10 @@ function connectGateway(args, write, run) {
     return 1;
   }
   write(info(`handing you to ${bone(gateway.bin)} — it owns its own session`));
-  const result = run(gateway.bin, gateway.connect, { stdio: "inherit" });
+  const launch = captureSpec({ cmd: gateway.bin, args: gateway.connect });
+  let result;
+  try { result = run(launch.cmd, launch.args, { stdio: "inherit" }); }
+  finally { launch.stop(); }
   if (result?.error) { write(err(String(result.error.message || result.error))); return 1; }
   if (result?.status) {
     write(err(`${gateway.bin} ${gateway.connect.join(" ")} exited ${result.status} — nothing recorded`));

package/src/pkg-install.mjs

@@ -0,0 +1,195 @@
+// Installer for the tools that only ship through a system package manager.
+//
+// ffmpeg and ImageMagick are the odd ones in TOOLS: they are not a vendor's CLI
+// with a `curl … | sh` of its own, and they are not a static binary on a GitHub
+// release either. They are distro packages, which is why they are installed the
+// way a distro package is installed — and why this is a separate file from
+// release-install.mjs rather than another descriptor in it.
+//
+// Static builds do exist for both. They are third-party redistributions of
+// somebody else's codec stack, unsigned, and updated by nobody in particular.
+// Downloading one to avoid a sudo prompt would be trading a password for a
+// binary we cannot vouch for, on the two tools most likely to be pointed at a
+// file from the internet.
+//
+// Everything that decides *what to run* is a pure function so the per-manager
+// argv (which differ in irritating ways) is unit-tested offline; the only
+// impure part is the loop at the bottom that runs it.
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { findEscalator } from "./escalate.mjs";
+
+/**
+ * How each manager installs, non-interactively.
+ *
+ * Non-interactive is the point: this runs inside `moshcode install` and inside
+ * `moshcode upgrade tools`, and a manager that stops to ask "Do you want to
+ * continue? [Y/n]" inside an upgrade sweep parks the whole plan.
+ *
+ * apt refreshes first because its index goes stale on its own: a box that has
+ * not run `apt-get update` in a few months gets a 404 on the archive rather
+ * than a package, and the error names a URL instead of the actual problem.
+ */
+export const MANAGERS = {
+  brew: {
+    // Never escalated. Homebrew refuses to run as root and says so at length.
+    root: false,
+    steps: (pkg) => [["brew", ["install", pkg]]],
+  },
+  "apt-get": {
+    root: true,
+    steps: (pkg) => [
+      ["apt-get", ["update", "-qq"]],
+      ["apt-get", ["install", "-y", "--no-install-recommends", pkg]],
+    ],
+  },
+  dnf: { root: true, steps: (pkg) => [["dnf", ["install", "-y", pkg]]] },
+  zypper: { root: true, steps: (pkg) => [["zypper", ["--non-interactive", "install", pkg]]] },
+  pacman: { root: true, steps: (pkg) => [["pacman", ["-S", "--needed", "--noconfirm", pkg]]] },
+  apk: { root: true, steps: (pkg) => [["apk", ["add", "--no-cache", pkg]]] },
+};
+
+/** The order managers are probed in. brew first, and only because of macOS. */
+export const MANAGER_ORDER = ["brew", "apt-get", "dnf", "zypper", "pacman", "apk"];
+
+/**
+ * Package names per tool, per manager, in the order they are worth trying.
+ *
+ * Two entries have more than one name and both are facts about somebody else's
+ * archive rather than hedging:
+ *
+ *   Fedora ships `ffmpeg-free` in the main repositories and the full `ffmpeg`
+ *   only from RPM Fusion, so a box without that repo enabled has exactly one of
+ *   the two names and `dnf install ffmpeg` fails outright on it.
+ *
+ *   `imagemagick` is one name for two different programs: on Ubuntu up to
+ *   24.04 it depends on the 6.x package and puts `convert` on PATH, and from
+ *   25.04 it depends on the 7.x one and puts `magick` there instead. The
+ *   package name is stable, which is why this table has one entry and the
+ *   tool's `bin` has two.
+ */
+export const PACKAGES = {
+  ffmpeg: {
+    brew: ["ffmpeg"],
+    "apt-get": ["ffmpeg"],
+    dnf: ["ffmpeg", "ffmpeg-free"],
+    zypper: ["ffmpeg"],
+    pacman: ["ffmpeg"],
+    apk: ["ffmpeg"],
+  },
+  imagemagick: {
+    brew: ["imagemagick"],
+    "apt-get": ["imagemagick"],
+    dnf: ["ImageMagick"],
+    zypper: ["ImageMagick"],
+    pacman: ["imagemagick"],
+    apk: ["imagemagick"],
+  },
+};
+
+function defaultProbe(tool) {
+  return spawnSync("sh", ["-c", `command -v ${tool}`], { stdio: "ignore" }).status === 0;
+}
+
+/** Resolve a name to its package table, or throw. Own properties only. */
+export function resolvePackage(tool) {
+  const key = String(tool ?? "").trim().toLowerCase();
+  if (!Object.hasOwn(PACKAGES, key)) {
+    throw new Error(
+      `unknown package ${JSON.stringify(tool)} — expected one of ${Object.keys(PACKAGES).join(", ")}`,
+    );
+  }
+  return [key, PACKAGES[key]];
+}
+
+/** Which package manager this machine has, or null. */
+export function findManager({ probe = defaultProbe, order = MANAGER_ORDER } = {}) {
+  for (const name of order) {
+    if (probe(name)) return name;
+  }
+  return null;
+}
+
+/**
+ * The commands that install one package name with one manager.
+ *
+ * Escalation is applied here rather than by the caller because whether a step
+ * needs it is a property of the manager: brew must not be escalated, the rest
+ * must be unless we are already root. A `null` escalator on a manager that
+ * needs one yields the bare command, which fails with the manager's own
+ * permission message — better advice than anything we would write.
+ */
+export function installSteps(manager, pkg, { escalator = null, isRoot = false } = {}) {
+  const spec = MANAGERS[manager];
+  if (!spec) throw new Error(`unknown package manager ${JSON.stringify(manager)}`);
+  const escalate = spec.root && !isRoot && escalator;
+  return spec.steps(pkg).map(([cmd, args]) =>
+    escalate ? { cmd: escalator, args: [cmd, ...args] } : { cmd, args },
+  );
+}
+
+/**
+ * Install a tool through whichever package manager is here.
+ *
+ * Package names are tried in order and the first that installs wins, because a
+ * name that is absent from this box's archive is a normal outcome (see the
+ * Fedora note above) rather than a failure to report. Only when every candidate
+ * has failed is there something to say.
+ */
+export function installPackage(tool, { run = spawnSync, probe = defaultProbe, log = console.log } = {}) {
+  const [key, table] = resolvePackage(tool);
+  const manager = findManager({ probe });
+  if (!manager) {
+    throw new Error(
+      `no supported package manager found (${MANAGER_ORDER.join(", ")}) — install ${key} yourself and re-run`,
+    );
+  }
+
+  const candidates = table[manager];
+  if (!candidates?.length) {
+    throw new Error(`${key} has no known package name for ${manager} — install it yourself and re-run`);
+  }
+
+  const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+  const escalator = MANAGERS[manager].root && !isRoot ? findEscalator({ probe }) : null;
+
+  const failures = [];
+  for (const pkg of candidates) {
+    log(`↓ ${manager} ${pkg}`);
+    let ok = true;
+    for (const step of installSteps(manager, pkg, { escalator, isRoot })) {
+      const result = run(step.cmd, step.args, { stdio: "inherit" });
+      if (result?.error || result?.status !== 0) {
+        failures.push(`${pkg}: ${step.cmd} ${step.args.join(" ")} ${result?.error ? `(${result.error.message})` : `exited ${result?.status}`}`);
+        ok = false;
+        break;
+      }
+    }
+    if (ok) {
+      log(`✓ ${key} installed with ${manager}`);
+      return { manager, pkg };
+    }
+  }
+
+  throw new Error(`could not install ${key} with ${manager}:\n  ${failures.join("\n  ")}`);
+}
+
+/** True when this file was executed directly rather than imported. */
+function invokedDirectly() {
+  try {
+    return realpathSync(process.argv[1] || "") === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedDirectly()) {
+  try {
+    installPackage(process.argv[2]);
+  } catch (e) {
+    console.error(`install failed: ${e.message}`);
+    process.exit(1);
+  }
+}

package/src/pty.mjs

@@ -19,8 +19,11 @@
 // `script` disagree on both flag names and argument order, and anything we
 // cannot positively identify falls back to today's plain `inherit`.
 import { spawnSync } from "node:child_process";
-import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
+import { closeSync, existsSync, mkdtempSync, openSync, readSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { StringDecoder } from "node:string_decoder";
+import { activeChildSink } from "./mirror.mjs";
 
 /**
  * POSIX single-quote escaping, for argv that has to survive being flattened
@@ -178,3 +181,57 @@ export function ptyEnabled(sink, flavor = scriptFlavor()) {
   if (process.env.MOSHCODE_MIRROR_PTY === "0") return false;
   return Boolean(flavor);
 }
+
+/**
+ * Wrap a spawn spec so a copy of everything the child prints reaches `onOutput`
+ * while the child still owns the real terminal.
+ *
+ * The whole capture dance in one place — temp transcript, the flavour-specific
+ * `script` argv, the follower, the banner strip, the cleanup — because every
+ * launcher in the pit needs it, and each one growing its own copy is how a
+ * shell command ended up invisible in the mirror while `/agents claude` was
+ * captured: both spawn `inherit`, and only one of them had been taught this.
+ *
+ * `onOutput` defaults to whatever the live mirror is (src/mirror.mjs), so a
+ * launcher gets capture without having to know the mirror exists — the reverse
+ * of how this started, where each launcher had to be taught separately and only
+ * two ever were. Pass `null` to opt a launch out.
+ *
+ * Returns `{ cmd, args, stop }`. With nothing watching, or on a box with no
+ * `script(1)` we can drive, `cmd`/`args` come back exactly as passed in and
+ * `stop` is a no-op — the caller spawns what it always spawned. `stop()` must
+ * be called once the child exits: it drains the tail of the transcript (the
+ * last lines of a command are usually the ones you were waiting for) and
+ * removes the temp dir.
+ */
+export function captureSpec({ cmd, args = [] }, onOutput = activeChildSink(), { flavor = scriptFlavor() } = {}) {
+  const plain = { cmd, args, stop: () => {} };
+  if (!ptyEnabled(onOutput, flavor)) return plain;
+  let workDir = null;
+  try {
+    workDir = mkdtempSync(path.join(tmpdir(), "moshcode-pty-"));
+    const transcript = path.join(workDir, "transcript");
+    writeFileSync(transcript, "");
+    const wrapped = ptySpec(cmd, args, transcript, flavor);
+    if (!wrapped) throw new Error("no script(1) spec for this flavour");
+    let first = true;
+    const stopFollow = followFile(transcript, (chunk) => {
+      const clean = stripScriptBanner(chunk, first);
+      first = false;
+      if (clean) onOutput(clean);
+    });
+    const dir = workDir;
+    return {
+      cmd: wrapped.cmd,
+      args: wrapped.args,
+      stop() {
+        try { stopFollow(); } catch { /* nothing left to drain */ }
+        try { rmSync(dir, { recursive: true, force: true }); } catch { /* temp dir */ }
+      },
+    };
+  } catch {
+    // Capture is a nicety; never let it stop a command from running.
+    if (workDir) { try { rmSync(workDir, { recursive: true, force: true }); } catch { /* temp dir */ } }
+    return plain;
+  }
+}

package/src/release-install.mjs

@@ -29,6 +29,8 @@ import { fileURLToPath } from "node:url";
  *   - supabase also publishes version-less asset aliases, so `latest/download`
  *     resolves without asking the API for a tag first.
  *   - doctl separates its asset fields with "-" instead of "_".
+ *   - yt-dlp publishes the executable itself rather than an archive, so there
+ *     is nothing to unpack; `bare` is what says so.
  */
 export const RELEASES = {
   gh: {
@@ -54,6 +56,27 @@ export const RELEASES = {
     asset: ({ version, platform, arch }) => `doctl-${version}-${platform}-${arch}.tar.gz`,
     binPath: () => "doctl",
   },
+  "yt-dlp": {
+    repo: "yt-dlp/yt-dlp",
+    binary: "yt-dlp",
+    // The asset IS the executable — a PyInstaller bundle, so it needs no
+    // python on the box, and there is no archive around it to unpack.
+    bare: true,
+    // `unversioned` is not a convenience here, it is required: yt-dlp tags
+    // releases by date with no leading "v" (2025.08.11), so the versioned URL
+    // this builds otherwise — /download/v2025.08.11/ — is a 404. The
+    // /releases/latest/download/ alias sidesteps the tag spelling entirely.
+    unversioned: true,
+    // macOS gets one universal2 build for both architectures; Linux names arm64
+    // "aarch64" while every other vendor here calls it arm64.
+    asset: ({ platform, arch }) =>
+      platform === "darwin"
+        ? "yt-dlp_macos"
+        : arch === "arm64"
+          ? "yt-dlp_linux_aarch64"
+          : "yt-dlp_linux",
+    binPath: () => "yt-dlp",
+  },
 };
 
 // Node's process.arch names differ from the ones release assets use.
@@ -151,14 +174,18 @@ export async function installRelease(tool, { fetchImpl = fetch } = {}) {
   try {
     const archive = path.join(work, path.posix.basename(new URL(url).pathname));
     writeFileSync(archive, Buffer.from(await res.arrayBuffer()));
-    const unpacked = path.join(work, "unpacked");
-    mkdirSync(unpacked);
-    extract(archive, unpacked);
-
-    const relative = spec.binPath(target);
-    const from = path.join(unpacked, relative);
-    if (!existsSync(from)) {
-      throw new Error(`${spec.binary} was not at ${relative} inside ${path.basename(archive)} — the vendor's archive layout changed`);
+
+    let from = archive;
+    if (!spec.bare) {
+      const unpacked = path.join(work, "unpacked");
+      mkdirSync(unpacked);
+      extract(archive, unpacked);
+
+      const relative = spec.binPath(target);
+      from = path.join(unpacked, relative);
+      if (!existsSync(from)) {
+        throw new Error(`${spec.binary} was not at ${relative} inside ${path.basename(archive)} — the vendor's archive layout changed`);
+      }
     }
 
     const dir = installDir();

package/src/settings-sync.mjs

@@ -74,6 +74,28 @@ export const SYNCED_FILES = [
   // reported as skipped rather than failing the snapshot, which is the right
   // answer for a list that got big by importing somebody else's.
   { path: "news.opml", json: false, label: "news subscriptions" },
+  // Herd's notification preferences — which states nag you and whether they
+  // ask. `rules.json` above has been carried since the first version and this
+  // sat next to it, unsynced, which made "my herd settings came across" true
+  // of half of them.
+  { path: "herd/config.json", json: true, label: "herd notifications" },
+  // Per-model price overrides for `/cost`. Nothing writes this file; a person
+  // types it, once, from a pricing page — which is exactly the kind of work
+  // `/save` exists so you only do once.
+  { path: "pricing.json", json: true, label: "cost model prices" },
+  // The DNS filter's policy: categories, and your own allow and block lists.
+  // A curated decision, not machine state — the blocklists it names are a
+  // cache that re-downloads itself, and `dns-filter/stats.json` next to it is
+  // browsing history and named below as never-synced.
+  { path: "dns-filter/filter.json", json: true, label: "dns filter policy" },
+  // Clients, teams, rates, invoices. The largest single "start from nothing"
+  // on a new machine, and safe to carry because payment gateways are stored
+  // here as references into a vault rather than as keys (see payments.mjs).
+  //
+  // Last on purpose. The total cap is spent in this order, so the file most
+  // likely to grow past it goes after the small ones — otherwise a year of
+  // invoices silently pushes your aliases out of the snapshot.
+  { path: "business.json", json: true, label: "clients, rates and invoices" },
 ];
 
 /**
@@ -91,13 +113,63 @@ export const NEVER_SYNCED = [
   "sync.json",
   "herd/sessions.json",
   "herd/hook.json",
+  // A billing ledger, not a preference. Two machines both appending hours and
+  // then both saving means the later `/save` drops the earlier one's entries,
+  // and it grows without bound — the two properties that make a file wrong for
+  // a last-write-wins sync.
+  "timers.json",
+  // "the numbers you last saw here", so that `add 3` means something. Carrying
+  // them would make `add 3` on another machine refer to a listing it never saw.
+  "news-last.json",
+  "news-found.json",
+  // Counters, and `recent[]` — the last twenty domains this machine was
+  // blocked from reaching. That is browsing history, and it has no business in
+  // a settings snapshot even one belonging to the person who generated it.
+  "dns-filter/stats.json",
+  // One box's daemon.
+  "moshpit-dns.pid",
+  "moshpit-dns.log",
+];
+
+/**
+ * Whole subtrees that never sync, matched by prefix.
+ *
+ * `NEVER_SYNCED` is an exact-string list, so a directory named there would be
+ * inert — the entries under it would not match it and would fall through. Any
+ * rule about a directory has to live here to have an effect.
+ */
+export const NEVER_SYNCED_PREFIXES = [
+  // The program itself. ~/.moshcode is also the install directory.
+  "pkg/",
+  // Hook reports, remote polls and per-session task ledgers: all pinned to one
+  // runtime, and the task ledgers carry prompt text and output artifacts.
+  "herd/status/",
+  "herd/remote/",
+  "herd/tasks/",
+  // Cached copies of published feed lists, re-fetched on demand.
+  "lists/",
+  // Downloaded blocklists. Megabytes, and self-renewing.
+  "dns-filter/lists/",
 ];
 
+/**
+ * The pty substrate, by extension.
+ *
+ * The header comment above has claimed since the first version that `*.sock`
+ * and `*.pid` are excluded "because they describe processes on exactly one
+ * box". That was true of the intent and never of the code: nothing enforced
+ * it, and the allowlist alone happened to be doing the work. Now it is a rule.
+ * A transcript is the one that matters — it is a full screen capture and will
+ * hold whatever was typed into that session.
+ */
+export const NEVER_SYNCED_SUFFIXES = [".transcript", ".stdin", ".exit", ".sock", ".pid", ".log"];
+
 /** True for a path this build is willing to read or write. */
 export function isSyncable(relative) {
   const name = String(relative ?? "");
   if (NEVER_SYNCED.includes(name)) return false;
-  if (name.startsWith("pkg/")) return false;
+  if (NEVER_SYNCED_PREFIXES.some((prefix) => name.startsWith(prefix))) return false;
+  if (NEVER_SYNCED_SUFFIXES.some((suffix) => name.endsWith(suffix))) return false;
   return SYNCED_FILES.some((f) => f.path === name);
 }
 

package/src/timer.mjs

@@ -45,8 +45,12 @@ export function parseDuration(text) {
 export function humanDuration(seconds) {
   const total = Math.max(0, Math.round(Number(seconds) || 0));
   if (total < 60) return `${total}s`;
-  const h = Math.floor(total / 3600);
-  const m = Math.round((total % 3600) / 60);
+  // Round to whole minutes first, then split — computing hours and minutes off
+  // the raw seconds lets a remainder that rounds up to 60 (59m30s..59m59s) print
+  // as "60m"/"1h 60m" instead of carrying into the hour it belongs in.
+  const minutes = Math.round(total / 60);
+  const h = Math.floor(minutes / 60);
+  const m = minutes % 60;
   if (!h) return `${m}m`;
   return m ? `${h}h ${m}m` : `${h}h`;
 }

package/src/tools.mjs

@@ -18,6 +18,12 @@ import { isInstalled, openPassthrough } from "./engines.mjs";
 const RELEASE_INSTALLER = path.join(path.dirname(fileURLToPath(import.meta.url)), "release-install.mjs");
 const releaseInstall = (tool) => ({ cmd: process.execPath, args: [RELEASE_INSTALLER, tool] });
 
+// ffmpeg and ImageMagick ship as distro packages and nothing else — no vendor
+// installer, no release binary we would trust. See src/pkg-install.mjs for why
+// the static rebuilds floating around are not an option here.
+const PACKAGE_INSTALLER = path.join(path.dirname(fileURLToPath(import.meta.url)), "pkg-install.mjs");
+const packageInstall = (tool) => ({ cmd: process.execPath, args: [PACKAGE_INSTALLER, tool] });
+
 export const TOOLS = {
   ugig: {
     desc: "UGig — freelance marketplace CLI for humans and agents",
@@ -354,6 +360,55 @@ export const TOOLS = {
     // there is deliberately no `upgrade` key.
     install: { cmd: "npm", args: ["install", "-g", "@elevenlabs/cli"] },
   },
+  "yt-dlp": {
+    desc: "yt-dlp — download video and audio from a URL (a thousand sites, not just YouTube)",
+    bin: "yt-dlp",
+    // The three tools below are not workflow CLIs like everything above: they
+    // are the media toolchain `cli-tools` builds on. `dl` is a front for
+    // yt-dlp, `vid` for ffmpeg and `img` for ImageMagick, and all three used to
+    // tell you to go and install a system package by hand. Now the same
+    // registry that installs cli-tools can install what it runs on.
+    //
+    // A PyInstaller bundle from the project's own releases, so it needs no
+    // python and no package manager, and it lands in ~/.local/bin like
+    // gh/supabase/doctl. Distro packages of yt-dlp are the one thing worth
+    // avoiding here: extractors break whenever a site changes, upstream ships a
+    // fix within days, and a distro package is frozen for the life of a release.
+    install: releaseInstall("yt-dlp"),
+    // Which is also why the upgrade is yt-dlp's own `-U` rather than a
+    // re-download: it is the update path the project documents, it checks
+    // before it fetches, and it is the one an operator will reach for anyway.
+    // On a yt-dlp that came from a package manager instead, `-U` declines and
+    // says so, which is the correct answer rather than a failure.
+    upgrade: { cmd: "yt-dlp", args: ["-U"] },
+    // Same gap turso, gradient and kimi have: nothing appends to PATH.
+    binDirs: [path.join(homedir(), ".local", "bin")],
+  },
+  ffmpeg: {
+    desc: "ffmpeg — convert, cut, scale and inspect audio and video",
+    bin: "ffmpeg",
+    // Through the distro package manager, which means root everywhere but
+    // macOS, where Homebrew refuses to run as root at all. Same shape as
+    // tailscale, and for the same reason: get the password prompt out of the
+    // way before a sweep starts rather than partway through one.
+    needsRoot: { except: ["darwin"] },
+    install: packageInstall("ffmpeg"),
+    // No upgrade key: `apt-get install` / `brew install` on a package that is
+    // already there upgrades it, so re-running the install IS the upgrade —
+    // the same reasoning as mcpjam and railway, and toolUpgradeSpec falls back
+    // to install on its own.
+  },
+  imagemagick: {
+    desc: "ImageMagick — resize, convert and composite images from the command line",
+    // Two names, deliberately. The command is `magick` on ImageMagick 7 and
+    // `convert` on 6, and both are current: Ubuntu 24.04 and earlier ship 6,
+    // 25.04 and later ship 7, and the package is called `imagemagick` on both.
+    // A single name would report a perfectly good install as missing on
+    // whichever half of the fleet has the other one.
+    bin: ["magick", "convert"],
+    needsRoot: { except: ["darwin"] },
+    install: packageInstall("imagemagick"),
+  },
 };
 
 /** Resolve a name to `[key, tool]`, or null. */
@@ -377,7 +432,7 @@ export function toolStatus() {
 
 export function toolList() {
   return Object.entries(TOOLS)
-    .map(([key, tool]) => `  ${key.padEnd(10)} ${tool.desc}`)
+    .map(([key, tool]) => `  ${key.padEnd(11)} ${tool.desc}`)
     .join("\n");
 }