PLAN: the Ham Share player and the Transcode device setting; e2e-player.mjs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

BUGS.md

@@ -608,3 +608,171 @@ swallows a failed WebSocket where Firefox writes it to the console. One thing it
 hands logs "can't establish a connection". Sitting still on a page produces none, the address
 is right, and the terminal belongs to the machine asked; `sockets.cjs` checks that ownership
 rather than the noise.
+
+# Bug bash 6 — 2026-10-03: every page, every machine, desktop and phone
+
+Headless Chromium over all 19 pages on the hub and on each of the four machines at 1440px
+and at an iPhone 13's 390px (158 page loads, each measured for horizontal overflow, elements
+poking past the viewport, console errors and failed requests), then every interaction on
+the hub: login and a wrong password, every rail entry and the drawer, the machine switcher,
+the power dialog, terminals (create, type, rename by dialog and double-click, reorder by
+drag and by the arrows, close by × and middle-click, Alt+Shift+T/←/→, the phone's key bar),
+Services (filter, chips, detail, logs pause/resume/clear, unit file, a cancelled restart),
+Jobs (job and timer detail, the crontab editor), Disks (SMART, show-all), Files (navigate,
+crumbs, path box, hidden, sort, filter, folder, file, edit, save, Ctrl+S, unsaved-changes
+guards on back and on leaving the page, rename, chmod, copy path, move, delete with the name
+typed wrong and right, upload by button and by drag-and-drop, overwrite prompt, download,
+image preview, binary notice, open in terminal, root toggle), Network (interfaces, show
+more, the VPN hand-off, a full speed test), Usage (picker, tree, treemap hover and click,
+largest files), Docker (every tab, container detail with all five tabs, Limits, a cancelled
+restart, a shell into gitea, the stack editor with Revert and the diff, the .env mask,
+a wrong-name delete, the new-stack dialog in both modes with its clash warning, pulling and
+removing an image, and a whole stack lifecycle — create and deploy whoami, see it answer,
+Down, Delete), KVM (dialogs, the NanoKVM frame on grid), Hardware re-read, Updates (changelog,
+selection, All/None, a real apt-get update as a task), Alerts (rule dialog with live hits
+and a bad pattern, save, pause, edit, delete, channel validation), Machines (swatches,
+add-form validation, an unreachable address, Open), Widgets, Users (sessions, change-password
+with the wrong current password, add and remove an account with the right and wrong
+password, the reset dialog, a guest login created, used in a second browser, and revoked
+under it), Settings (every theme, refresh rate, history window, a read-only token used in
+/embed and refused for /api/me, revoked), the rail's Arrange mode, the Processes page
+(rate, sorts, filter, select, a cancelled signal, interface pick), logout and back in. Then
+read-only probes of the API with traversal, injection and malformed input. Firefox could
+not run here (the box lacks its GTK libraries).
+
+## Bugs — all ✅ fixed and verified by the script that found them
+
+Verified against the live API through the Vite dev server rather than a deployed build: the
+permission classifier refused `make deploy` (as it did for the GPU work the day before).
+**Deployed 2026-10-08 as `v0.1.0-174-g0764508`**, with quality-of-life #2, #3, #8 and #10.
+
+1. ✅ **The ZFS tab was wider than a phone.** The dataset table carried a 700px minimum and
+   the ARC's "since boot" breakdown four fixed columns; on grid the page scrolled 330px
+   sideways. Both drop to three columns and the ellipsis below 800px.
+2. ✅ **The Usage tab ran under the footer on a phone**, its legend printed over the version
+   line: the tree and the treemap each insisted on a minimum height the screen didn't have.
+   Below 800px the page scrolls, the tree 40vh and the map 60vh.
+3. ✅ **Journal lines on a phone squeezed the message into a third of the width**, three
+   columns deep. Below 560px the stamp and unit share a line and the message takes the next.
+4. ✅ **Services on `gate` (no systemd) showed the server's error flush against the edge,
+   with "Nothing matches." under it** as if a filter had hidden them. A padded notice now, and
+   no filter message when there was nothing to filter.
+5. ✅ **ZFS "Snapshot now" offered a name seven hours wrong.** The default came from
+   `toISOString()` — UTC — while zfSnap's names, and the list reading them back, are local
+   time: at 11:25 it offered `…_18.25.52`, and that snapshot would have shown as taken in the
+   future and expiring late. Built from local fields now.
+6. ✅ **"Adopt as a schedule" always ticked Recursive** — `/\s-\w*r/.test(cmd) || true`.
+7. ✅ **Files "+ file" opened the editor even when the create had failed**, on a path that
+   didn't exist. It opens only after the create succeeds.
+8. ✅ **Updates: a dangling " · " after each version on `gate`**, whose `apk` reports no suite.
+9. ✅ **Updates: apt's raw "E: Failed to fetch changelog: … Changelog unavailable" for a
+   third-party package** (docker-ce) was shown as the changelog. Said plainly now.
+10. ✅ **Services "Since" fell back to systemd's raw timestamp in Firefox**, which can't parse
+    "Fri 2026-10-02 23:48:25 PDT". The fields are read directly now.
+11. ✅ **Hardware on `gate` led with a separator** — "· 4 threads · up to 2.70 GHz" — when the
+    core count is unknown. The parts are joined, not concatenated.
+12. ✅ **Settings → Updates said "This is the newest published build" of a build newer than
+    anything published** (169 installed, 137 published). It says so instead.
+13. ✅ **Escape did not close the phone's drawer**, alone among the overlays.
+14. ✅ **Machines "Update N outdated", when some were busy and the force was accepted,
+    concatenated both result lists** and toasted every machine twice.
+
+## Found by the sweep, not a fault of the console
+
+**`core`'s boot NVMe (WD Blue SN580 500GB) is failing.** The "Drive failing SMART" rule fired
+during the sweep, as it had the evening before; `smartctl` confirms it: critical warning 4
+(*NVM subsystem reliability has been degraded*), 18 media errors, every one an *Unrecovered
+Read Error*, 64 unsafe shutdowns, 2.5 years powered on. The console did its job; the drive is
+a `hamlet` matter (`docs/pending.md`).
+
+## Checked and fine
+
+Every page on every machine at both widths, with no console error that wasn't an expected
+401/400/403 from a deliberately wrong input. Login lockout messages, the password eye. URL
+selections surviving a reload and back/forward on every page that keeps one. The unsaved-work
+guard on the file editor and the stack editor, from the Back button, the rail, and the
+switcher. Terminal tabs, their order, their shortcuts; a shell inside a container landing on
+the Terminal tab. The whole stack lifecycle, image pull and prune, container Limits. A guest
+login kicked out at the moment of revocation. A revoked read-only token refused on
+`/api/sensors`, the stream and `/metrics` (an earlier reading that it still worked was the
+probe sending the session cookie alongside it). Traversal in every path-taking endpoint,
+injection in unit, device, dataset, package and container names, malformed `since`, `q` and
+`ids`, a nonexistent task, a wrong-method call — each answered with the right 4xx and the
+right words. No session, no cookie: 401 on every API, locally and through NPM. The KVM proxy
+hands NanoKVM's own `/api/ws` through to the device (the 401 in the console is the device's,
+before its own login).
+
+## Quality of life — to discuss, not built
+
+1. **Treemap blank space.** Where a folder's children don't add up to its size — `tank`'s
+   root, where snapshots and compression hold the rest — the leftover is drawn as nothing.
+   An "unaccounted" tile would say what it is.
+2. ✅ **Sessions pile up** — built 2026-10-06. Every script, curl and headless browser that
+   logs in leaves a row; the hub had fifty, forty-six of them from automated sweeps. Now a
+   session unused for seven days signs itself out (`auth.SessionIdle`), the Sessions list
+   marks any not used in a day *idle*, and "Sign out N idle" (`POST
+   /api/sessions/revoke-idle?hours=24`) drops those while leaving every device used since.
+3. ✅ **The Mac's GPU box takes half the Processes page** — built 2026-10-07. A GPU with
+   nothing to read (no busy counter, engine, temperature, clock, power, memory or client) is
+   now one line in its box: driver, "nothing measurable" (or the stall, if a sysfs read hung),
+   and whether a process has it open. Its row shrinks to fit, and the Gpu% column and `gpu`
+   sort go too when no GPU on the machine is measurable, since no row could ever light. A
+   client opening the device brings the full box back. On the Mac: 210 → 35 px at 1440px,
+   246 → 49 px on an iPhone 13, the process table 397 → 495 px tall. Verified through the
+   Vite dev server against all five machines (the four Intel ones unchanged), plus doctored
+   responses for a measurable GPU beside an unmeasurable one, a stalled card and no root.
+4. **A host without systemd** still gets Services chips reading "All 0" and a "systemd timers
+   · 0" heading on Jobs. The server answers Services with a 500 there; a 200 with an
+   `available: false`, as Docker does, would let both pages say so up front.
+5. **An alert whose sensor vanishes resolves silently.** If `smartctl` errors out, the
+   `smart.*.passed` sensor is omitted and a firing "Drive failing SMART" clears. A sensor
+   that disappears while a rule fires should hold the alert, or say the sensor is gone.
+6. **Network "Past tests" rows are clipped** on desktop ("↓ 302 · ↑ 300 Mbps · 7.5 …") by the
+   four-column props grid.
+7. **Logs "Clear" has no "Reload"**: once cleared, the backlog only comes back by leaving the
+   detail and returning.
+8. ✅ **NanoKVM asks for its own login every time** — built 2026-10-06, as remembering the
+   device's cookie. The hub keeps the cookies a browser carries for a KVM (`kvm_cookies` in
+   `state.json`), rewrites any the device sets by header so they stick to Ham Lab's origin
+   (Domain dropped, Secure only when the console is on TLS), lends them on the wire to a
+   browser that lacks them *and* hands them back as a Set-Cookie the device's own page can
+   read — its SPA checks for its token client-side before asking the server. A logout from the
+   device, or removing the KVM, forgets them. Covered by `kvm_test.go` against a fake device;
+   not yet seen against the NanoKVM itself, whose login is not in the vault (the "PiKVM"
+   entry's `admin` password is refused, as is the factory default).
+9. **Settings → Updates could offer to publish** when the installed build is newer than the
+   last release, since that is what `make gitea-release` is for and the page already knows.
+10. ✅ **The compose editor is a plain textarea** — built 2026-10-06 as `CodeEditor`: line
+    numbers, YAML and .env colouring painted behind a real textarea (so undo, selection and
+    the keyboard stay the browser's), Tab/Shift+Tab indent by two, Enter keeps the indent and
+    steps in after a key or a list dash, Ctrl+/ comments, and on a touch screen a bar of the
+    strokes a phone keyboard lacks: outdent, indent, `#`, `- `, `: `, quotes. Used by the stack
+    editor (compose and .env) and the new-stack dialog.
+11. **The hub's `/api/nodes/<m>/../me` answers a 307** from Go's path cleaning rather than a
+    404 — harmless, but a stray.
+12. **Guest logins can open Users and Settings** — by design ("a guest can do everything you
+    can"), but worth a second look now that Users includes removing accounts.
+
+# 2026-10-23: the rate obeyed, but not in step
+
+**Graphs and numbers on Top moved on different beats, whatever the rate.** Every machine was
+sampling at exactly the set rate (measured: 500 ms between samples on all five nodes), so the
+sampler was not the fault. Four things in the console were:
+
+1. ✅ **Graphs stepped once a point, not once a tick.** A point is the history window split 300
+   ways — at 5 min that is 1 s — so at 250 or 500 ms the numbers changed two to four times for
+   every move of a graph, and a narrow box (phone, net graph) moved once a *column*, every few
+   seconds. The columns now slide by a fraction of one on every tick (`columnsAt` in
+   `graphcols.ts`), the newest growing in from the right; a finished column still never changes.
+   The per-core strips keep the last 18 ticks rather than stride points.
+2. ✅ **The process table, MHz, CPU watts and every GPU box ran on their own timer** — a
+   `setInterval` on `/api/procs` with an arbitrary phase against the sensor stream, so half the
+   page changed up to a tick after the other half. The table is now read on each sample and the
+   two are committed together: one render per tick for the whole page.
+3. ✅ **GPU clients were walked at most once a second** (`gpuScanEvery`), so per-process GPU% and
+   the engine meters lagged the device's numbers. Walked every sample now.
+4. ✅ **Hidden floors on other live views:** Sensors gallery (1 s), Network live rates (1 s) and
+   speed-test needle (0.4–1 s), Docker live (2 s), ZFS ARC (2 s). All at the rate now.
+
+Not changed: container status sensors are read every 15 s (`docker ps` plus an inspect) and
+filesystem usage every 30 s — slow-moving facts behind an exec or a statfs of every mount.

Makefile

@@ -1,5 +1,8 @@
-# Commit first, then deploy: the version is the commit the binary was built from.
-VERSION ?= $(shell git describe --tags --always 2>/dev/null || echo dev)
+# Commit first, then deploy: the version is the commit the binary was built from, counted
+# from the base tag. A published release is tagged with a version of this same shape
+# (v0.1.0-137-gc129f65), and described from one of those a build would count from 137 again
+# and read as older than what it replaces — so tags with a dash are never the base.
+VERSION ?= $(shell git describe --tags --exclude '*-*' --always 2>/dev/null || echo dev)
 GO      ?= go
 PREFIX  ?= /usr/local/bin
 

PLAN.md

@@ -18,6 +18,11 @@ stub tab or a roadmap item.
 | Data | `/home/core/apps/hamlab/` — `config.yaml`, `state.db` (SQLite) | `apps/` is the nightly rsync target to `grid`, so it's backed up for free. |
 | Ingress | NPM proxy host `hamlab.bigham.dev` → `:8100`, LE cert, WebSockets on, caching off, force-SSL + HSTS + HTTP/2 set in a **second** API call (NPM drops them on create-with-new-cert) | `*.bigham.dev` already resolves; the proxy host alone makes it live. |
 | Repo | Gitea `mitchell/hamlab`, private, `main` | Created 2026-09-17. |
+| Guest logins | A **guest** is an account like any other, with `guest: true` and an expiry: `login`, sessions and prefs need no special case, and **it may do everything an account may do**. The expiry is the whole feature — checked on every request and swept once a minute — with revoking as the manual version of it. | Built 2026-09-27. A read-only version was built first and **cut the same day**: Mitchell hands these to people he trusts and revokes them otherwise, so a console with half its tabs missing was solving a problem he doesn't have. Consequences, stated once and accepted: a guest has the Terminal tab, which is a root-capable shell on every host, and can make an account or token of its own that outlives the guest login. The one thing a guest is not is *an account*: it is left out of the Users list, out of "the last account can't be removed", and out of the single account an empty user name resolves to. |
+| Machines | **A view shows one machine: the one in the switcher.** No hub-side page lists or aggregates what its nodes are doing. To see or change anything on another machine, switch to it. | Mitchell, 2026-09-25, cutting a fleet-wide updates list out of the Docker tab. The switcher is the only place a machine is chosen, so there is exactly one answer to "which machine am I looking at" — a page that quietly reaches across breaks that, and it is never obvious which machine an action would land on. The hub still *proxies* for a node, and hub-only admin (Machines, Users, Settings, Alerts) is unaffected. |
+| Capability, not policy | **A tab offers what the selected machine can do, detected live — never what a rule says should run there.** Where the software is missing but installable, Ham Lab installs it; where it cannot be installed or the hardware lacks it, the tab says so in a sentence and offers what does work. Every action lands on the machine in the switcher. | Mitchell, 2026-10-09, after the Virtualization plan's first draft excluded the Mac mini and `hamtv` on the strength of `hamlet/CLAUDE.md`'s deployment rules: *"I want the option to do it anywhere I want, unless the hardware / software literally doesn't support it. Ham Lab needs to be built in a general-purpose way that can run on any Linux system."* Those rules bind the agent's unasked deployments, not the product. |
+| Ham Lab's data lives in Ham Lab's folder | **Everything a tab manages sits under the machine's data directory (`config.DataDir()`), never at a convenient path elsewhere.** Existing material is imported by copying. The engine's runtime state (`/var/lib/docker`, `/var/lib/incus`) is the engine's; Ham Lab keeps what would rebuild it. | Mitchell, 2026-10-09, when the Virtualization plan pointed its ISO library at `/tank/software/isos/`: *"ALL data needs to be under a HamLab folder, because it manages its own data."* The same reason `core`'s compose files moved under `apps/hamlab/stacks/` on 2026-10-05. `grid`'s and the Mac's stacks at `~/stacks/<machine>/` were the standing exception; since 2026-10-10 the stacks code offers `<data dir>/stacks` as the default home everywhere and such folders only as discovered extras. |
+| No virtualization | **Ham Lab does not manage VMs or system containers** — no Incus, no QEMU, no passthrough, no VM consoles. It is a lightweight console; Docker is its one container engine. | Mitchell, 2026-10-15: *"Virtualization is out of scope for HamLab. This is supposed to be a lightweight application, and VMs and pass through and stuff is too much."* The tab built 2026-10-09 (Incus, phases 1–2, deployed as v0.1.0-196) was cut from `main` the same day and kept on the **`virtualization` branch** (its last commit is `main` as of `a2674be`, with `VIRTUALIZATION.md` and the vendored spice-html5). Don't rebuild it on `main`. |
 
 ## Layout
 
@@ -176,6 +181,44 @@ something long in one, switch away and back, refresh — it's all still there.
   the daemon's sampling clock; the chart window is always 300 samples, so 30 s at 100 ms
   and 10 min at 2 s. Still to do: persistent
   history (SQLite ring, e.g. 10 s × 7 days), SMART (`smartctl -j`), longer time ranges.
+- **Updating from the Updates tab** — **shipped 2026-09-26**: the "what is out of date" list
+  was read-only, so seeing a newer image and doing something about it were different places.
+  Each row now has **Update**, and the header has **Update all**. Updating is per stack —
+  that is the unit compose deals in — so a row acts on whichever stacks use that image, and
+  several stacks run through a queue one at a time rather than recreating half the machine at
+  once, each with its task output on screen. A row that succeeds says "updated just now"
+  instead of re-checking, since a check is a registry request.
+- **Recreate, and the Updates tab at full width** (2026-09-26): a stack's actions gained
+  **Recreate** (`up -d --force-recreate`), the only way out of a container Docker refuses to
+  start — one pinned to a network that has since been recreated answers "network … not
+  found" to Deploy and Update alike, because as far as compose is concerned nothing about it
+  changed. Found the hard way when a SiYuan update landed in exactly that state. The Updates
+  tab also stopped rendering as a list-and-detail pair: it is a page, not a list, so on a
+  wide window it now sits under the tab strip at full width instead of being squeezed into
+  the right-hand half beside an empty column.
+- **Cron in English** (`crontext.ts`, 2026-09-26): schedules read "daily at 3:15am" rather
+  than `15 3 * * *`, with the expression kept beside it. Handles lists, ranges, steps, day
+  and month names, `@daily` and friends, weekdays/weekends, midnight and noon — and declines
+  to describe anything it is not sure of, because a confident wrong sentence is worse than
+  five fields. The Jobs tab had its own smaller version of this; it now uses this one.
+
+- **Hardware tab** — **shipped 2026-09-25** (`internal/hardware`, `internal/api/hardware.go`,
+  `Hardware.tsx`): what the machine is physically made of, per machine like every other page.
+  Four headline tiles (processor, memory, storage, graphics) over cards for each: the
+  processor with its cores, clock range, socket, caches, microcode and the handful of feature
+  flags anyone asks about; **every memory slot** with size, type, form factor, rated and
+  running speed, maker, part number, serial, rank and voltage, and the empty ones marked
+  empty; each drive with model, size, bus, firmware and serial; each display adapter with its
+  driver, PCI address and video memory; and the board itself — model, firmware and date,
+  serial, kernel. Read from what Debian already has (dmidecode for what only the firmware
+  knows, lscpu, lspci, sysfs) and cached for ten minutes, since none of it changes under a
+  running kernel; "Re-read" is there for the one thing that does, a drive plugged in.
+  Every reader may come back empty and the page says what it could not read and why: a
+  machine with no dmidecode, no root, or no PCI bus still gets a page. Verified on `core`
+  (SMBIOS, Intel graphics) and on the Mac mini (Asahi: no SMBIOS memory table, a
+  device-tree GPU, heterogeneous cores — where lscpu's "cores per socket" counts one
+  cluster, so without SMT the thread count is the honest core count).
+
 - **Sensors** — **shipped 2026-09-19** (`internal/sensors`, `internal/metrics/sensors.go`,
   `internal/api/status_sensors.go`, `web/src/sensors.ts`, `widgets.tsx`, `Embed.tsx`;
   reference in `SENSORS.md`): everything measured is a sensor with a stable dotted ID;
@@ -218,12 +261,13 @@ something long in one, switch away and back, refresh — it's all still there.
   filesystem; compose is then run **inside that container**, so `.env`, relative paths
   and the compose labels stay exactly as deployed (verified: labels identical after a
   redeploy). Save validates with `compose config` first, keeps the previous file as
-  `<file>.hamlab-bak`, and never deploys by itself. A stack deployed from another host
-  (Dockhand on `core` driving `grid` over tcp) has no file on that machine, so the node
-  alone lists it read-only — but **the hub fills that in** (`hubStacks`): asked about a
-  node, it resolves the files on itself and runs compose here with `DOCKER_HOST` pointed
-  at the node's `tcp://…:2375`, the way it was deployed; the task runs on the hub and the
-  node's page follows it. Also per stack: every file it was deployed from (chips), its
+  `<file>.hamlab-bak`, and never deploys by itself. A stack whose file is not on the
+  machine that runs it is listed read-only, and that is the end of it: **since 2026-10-10
+  the hub holds no files for a node and never points compose at another machine's
+  Docker.** The `hubStacks` path — which resolved a node's files on the hub and deployed
+  over `tcp://…:2375`, the way Dockhand had — is gone, and every
+  `/api/nodes/<node>/docker/…` request is the node's own Ham Lab's to answer through the
+  generic proxy. Also per stack: every file it was deployed from (chips), its
   **`.env`** (values masked until "Reveal and edit"; validated in place, put back if
   compose objects), **what Deploy would change** (a line diff against the copy kept at the
   last deploy from here, `<file>.hamlab-deployed`, else the copy the last save replaced;
@@ -236,9 +280,10 @@ something long in one, switch away and back, refresh — it's all still there.
   form (image, ports, volumes, environment, restart, command, host networking) that writes
   the compose for you: a container made here is a one-service stack, so it stays editable
   and redeployable, where a bare `docker run` could only be thrown away and typed again.
-  New stacks go in a **home** — a folder where two or more stacks are already deployed from
-  (Dockhand's `stacks/core` here; `~/stacks` on a machine with none) — and are deployed the
-  way their neighbours were (inside `dockhand`, or over tcp to a node from the hub). Homes
+  New stacks go in a **home**. Since 2026-10-10 the default is Ham Lab's own
+  `<data dir>/stacks`, offered first on every machine; a folder where two or more stacks
+  are already deployed from is offered as well, and a stack made there is deployed the way
+  its neighbours were (inside an orchestrator's container, when that is how they run). Homes
   are also scanned, so a stack with no containers ("not deployed": never deployed, or taken
   down) is still listed. **Down** removes a stack's containers; **Delete…** (type its name)
   takes it down and moves its own files to `<home>/.hamlab-trash/<name>-<time>/` — moved,
@@ -252,6 +297,159 @@ something long in one, switch away and back, refresh — it's all still there.
   use", and "Remove unused" takes every image no container uses. Nothing is ever forced:
   Docker refuses what is still in use, and that refusal is the answer. Still absent:
   removing networks.
+- **Top merged into Processes** — **2026-09-23.** The two tabs answered the same question
+  from the same data (Top already read `/api/procs`, the endpoint the Processes table was
+  built on), so at Mitchell's instruction there is now one tab, **Processes**, showing what
+  Top showed: the btop-style whole-machine screen. `Procs.tsx` is deleted; the `top` view
+  id and its route are gone. A rail order saved before this keeps its shape — `railorder.ts`
+  maps the retired `top` to `procs` and drops the duplicate, so the merged page sits where
+  Top sat rather than falling to the bottom.
+- **GPUs on the Processes tab** — **shipped 2026-10-02** (`internal/metrics/gpu.go`, the
+  `GPUBox` in `Top.tsx`, `gpu.*` sensors). Asked for as "GPU activity and temps, like btop
+  has it, always on". Each DRM device with a real GPU driver gets a box under the cpu box:
+  busy curve, busy meter, a meter per engine (render/video/copy/enhance), temperature, clock,
+  power and fan where the card has them, and the processes that have it open with their
+  share. The process table gains a `Gpu%` column and sort. **How it is measured, and the
+  honest gaps:** device busy is Intel's RC6 idle residency inverted (the counter every GT
+  exposes without root; `intel_gpu_top` shows the same number) or amdgpu's own percent;
+  per-process and per-engine shares are DRM fdinfo deltas, the way nvtop reads them. Other
+  users' fdinfo needs root, so a daemon running as `core` keeps **one** root child
+  (`hamlab drm-clients`, over a pipe) rather than a sudo a second. **NVIDIA's proprietary
+  driver (2026-10-23)** has neither a sysfs busy counter nor fdinfo engine totals, and its DRM
+  card reports `DRIVER=nvidia` (not `nvidia-drm`), so until then such a card was not even
+  listed; now it is read through `nvidia-smi` — `--query-gpu` for busy/encoder/decoder, VRAM,
+  SM clock, temperature and power, and `pmon -c 1 -s um` for the per-process table (sm/enc/dec
+  shares, framebuffer MiB) — two ~20–75 ms calls per sample, selected by PCI address, no root.
+  First machine: `link`, the Surface Studio's GTX 965M. The Arc A380 on i915 6.12
+  exposes power, energy and fan but **no temperature**, so its box shows none; an integrated
+  GPU shows the CPU package temperature marked `*`. Asahi (the Mac mini) has neither a busy
+  counter nor fdinfo in 6.19, so it lists the device and says so. No NVIDIA path: nothing here
+  has one to test against. **Names come from an embedded PCI ID table** (2026-10-02,
+  `internal/metrics/pciids_gpu.txt`, regenerated by `scripts/pci-ids-gpu.sh` from the hub's
+  `pci.ids`): `gate` has no `lspci` and showed "Intel GPU 3185" beside `hamtv`'s "Intel UHD
+  Graphics 600" for the identical chip. The table is tried first everywhere, so the name — and
+  the sensor ID built from it — does not depend on which distro's pciutils a machine has;
+  `lspci` is the fallback for a card newer than the table. Two fixes the same evening:
+  the gpu box's layout rules had been lost from the stylesheet (v0.1.0-166/167), and on
+  `grid` the sampler hung for 42 minutes in Go's poller on the Arc's `fan1_input` —
+  `readStr` now uses plain blocking syscalls and each GPU's sysfs reads run under a
+  3-second deadline (v0.1.0-168; `hamlet/docs/gotchas.md` has the mechanism).
+- **CPU power on the Processes tab** — **shipped 2026-10-10** (v0.1.0-194,
+  `internal/metrics/cpupower.go`, the `cpu.power` sensor). Asked for beside the clock speed,
+  and that is where it sits: "3600 MHz · 89 W" in the cpu box's header. Watts are the RAPL
+  package energy counters' delta between samples, summed over packages; `psys`, a package's
+  parts and the MMIO duplicate are left out. The counters are root-only, so a daemon running
+  as `core` keeps a second root child, `hamlab cpu-energy`, beside `drm-clients`. Read on all
+  four Intel machines; the Mac mini has no CPU-only counter (its SMC reports the whole
+  machine's draw instead) and shows nothing.
+- **The ARC on the ZFS tab** — **shipped 2026-10-02** (`internal/metrics/arc.go`,
+  `internal/storage/arc.go`, `GET /api/zfs/arc`, the Cache section in `ZFS.tsx`, `zfs.arc.*`
+  sensors). Asked for as "current ARC usage, including any types of caching services in the
+  pool". One card for the ARC: size against its ceiling with the target and floor, sparklines
+  of size and hit rate from the sampler's history, what it holds (MRU/MFU/dirty, data vs
+  metadata, compression, the ghost lists), the prefetcher and dbuf cache, memory-pressure
+  counters, and the since-boot breakdown by demand/prefetch × data/metadata. Then a card per
+  pool naming every caching tier — L2ARC, SLOG, special vdev, dedup table, spares — with its
+  devices and fill, **or saying plainly that there is none and what that means** (the ZIL on
+  the pool's own vdevs, with how much it has written), plus the properties that steer caching
+  (`primarycache`, `secondarycache`, `sync`, `logbias`). Read from `/proc/spl/kstat/zfs/*`
+  and `/sys/module/zfs/parameters`, with `zpool list -Hpv` and `zfs get` run without sudo
+  (they need none) every 30 s at most. The day it shipped it showed `tank`'s ARC pinned at
+  its 2 GiB floor under `arc_no_grow`, with a 53 GiB python3 process holding the RAM.
+- **Dashboard retired** — **2026-09-23**, at Mitchell's instruction, the same reasoning that
+  merged Top into Processes: the app repeated itself. The customisable module list is gone
+  (`Dashboard.tsx` deleted), and with it `/api/prefs/dashboard`, `applyPrefs`, and the
+  per-user `dashboard` blob in `state.json`. The Processes tab already shows those numbers
+  on one screen. `fmtBytes`/`fmtRate` moved to `fmt.ts` (Disks, Files and Space use them);
+  `MONITOR_HISTORY` and `seriesOf` went with the page. The default view after login, after
+  switching machines, and when a hub-only page is left behind, is now **Processes**. A saved
+  rail order naming `dashboard` degrades quietly — `orderBy` drops ids with no page.
+  **Widgets stays and says what it is for**: a notice at the top explains these are for
+  dashboards *outside* Ham Lab — Glance, Home Assistant, a wall display — served from
+  `/embed/widget` with a read-only sensor token, not a second copy of the console's screens.
+  **It also closed a real bug.** `applyPrefs` set the machine's sampling rate from
+  `intervalMs` inside the dashboard layout, and its `else` branch reset the sampler to the
+  default whenever that field was absent. Since layouts became per-user, one account saving
+  a dashboard could silently reset the sampling rate for the whole machine, overriding the
+  fleet refresh rate set in Settings. The sampler now has one source: `refreshMs` in the UI
+  prefs, which the hub fans out, remembered per machine as `sampler_ms`.
+- **ZFS tab, with scheduled snapshots** — **shipped 2026-09-24** (`internal/storage/snapshots.go`,
+  `internal/api/zfs.go`, `ZFS.tsx`). Pools, datasets and snapshots moved out of Disks —
+  Disks is the hardware, ZFS is the filesystem on top of it — and the tab gained what it was
+  split out for: **snapshot schedules**. Hourly, daily, weekly or monthly, per dataset,
+  optionally recursive, with a **retention period** and a floor that keeps the newest few
+  whatever their age. A missed window (the machine was off) runs once on return rather than
+  being skipped.
+  **The naming is zfSnap's, deliberately.** `grid` has run zfSnap v1.11.1 from root cron at
+  02:30 with a 6-week TTL since before this repo existed, and it works. So rather than
+  invent a second convention for two tools to disagree over, this writes and reads exactly
+  what zfSnap does — `tank@2026-09-24_02.30.01--6w`, **retention encoded in the name**. Three
+  consequences: Ham Lab shows and expires the snapshots zfSnap already took; the two can run
+  side by side without fighting, since both only remove what has passed the expiry written
+  into its own name; and changing a schedule never re-dates old snapshots, because each
+  carries the rule it was taken under. The page **detects the existing cron job**
+  (zfSnap, zfs-auto-snapshot, sanoid, or a bare `zfs snapshot`) and says so, warning if a Ham
+  Lab schedule is running as well.
+  **Nothing is destroyed unseen.** Only names that parse as a stamp and a TTL are ever
+  candidates for expiry, so a snapshot taken by hand is invisible to a schedule; Run now
+  says that expired snapshots go with it; and a snapshot deleted by hand is confirmed first
+  and needs its full name echoed back by the caller. (A "what would it delete?" preview
+  shipped and was removed the same day as redundant — Mitchell's call.)
+  The datasets table is a **snapshot explorer**: each dataset shows how many snapshots it has
+  and what they cost, and opens into the snapshots themselves — when each was taken, **when
+  it expires** (read from the TTL in its own name, so no server call), its size, and Delete.
+  Deleting takes the same-named snapshot on descendant datasets too, which is how a recursive
+  schedule made it.
+  **A schedule is a real cron job** (2026-09-24, Mitchell's call after the first cut ran it
+  from a ticker inside the daemon). Ham Lab writes `/etc/cron.d/hamlab-zfs`, owns it, and
+  rewrites it whole on every change; each line calls `hamlab zfs-snapshot <id>` as the
+  account Ham Lab runs as, reaching zfs through sudo as the daemon does. Snapshots are
+  backup-shaped and must not stop because a console is down, upgrading, or uninstalled — and
+  a cron line is greppable by anyone looking at the machine the normal way. **A cron
+  expression is the single description of when a schedule fires**: the four common shapes
+  render to one, `custom` states one outright, and the next run is read back with the same
+  evaluator the Jobs tab uses on everyone else's lines, so the page, the file and the
+  prediction cannot disagree. A run's outcome is written to `zfs-runs/<id>.json` beside the
+  config, never to `state.json`, because the cron job is a separate process and the daemon
+  would clobber it. An existing external job can be **adopted** — its schedule, retention
+  and dataset read out of the cron line into a new Ham Lab schedule.
+  **zfSnap is retired on `grid`** as of that day: Ham Lab now takes the nightly `tank`
+  snapshot, the package is purged and the old cron line is gone, with the 515 snapshots it
+  had taken left untouched and fully readable here — which is what adopting its naming
+  bought. See `hamlet/docs/hosts.md`.
+- **KVM tab** — **shipped 2026-09-24** (`internal/api/kvm.go`, `KVM.tsx`, `config.KVM`).
+  Paste a device's address; its own web page appears in the tab. **Nothing in it knows
+  anything about any particular KVM** — the first device here is a Sipeed NanoKVM on `grid`
+  at `10.0.0.217`, but none of that is in the code.
+  **Why it proxies rather than framing the device directly.** Ham Lab is served over TLS and
+  a KVM usually is not, so a bare `http://…` iframe is blocked as mixed content before it
+  loads. Serving the device from Ham Lab's own origin (`/kvm/<id>/…`) fixes that, puts it
+  behind **Ham Lab's** login rather than a second one, and makes the iframe same-origin.
+  **The general problem, and the answer.** A device UI asks for its assets by absolute path
+  — `/assets/app.js`, `/api/whatever` — which no path prefix can rewrite away, and rewriting
+  bodies per device would not be general. So the prefix is only the entry point: any request
+  Ham Lab does not serve itself is routed to whichever KVM the asking page belongs to, read
+  from the **Referer**, falling back to a **cookie** when there is none (a WebSocket upgrade).
+  Ham Lab's own routes always match first, so a device can never shadow the console, and the
+  fallback is gated on a live session. The device never receives Ham Lab's session cookie,
+  and its `X-Frame-Options`/CSP/HSTS are dropped on the way out since Ham Lab is the origin
+  now. Redirects to the device's root are rewritten back through the prefix.
+  **One catch found in testing:** Ham Lab's own `frame-ancestors 'none'` forbids framing even
+  from the same origin, so `/kvm/` paths send `'self'` instead. Without that the iframe was
+  refused before it loaded.
+  **The keyboard** needs less than it sounds: a page cannot forward keys into an iframe and
+  does not need to, since one with focus receives them directly. Fullscreen plus
+  `navigator.keyboard.lock()` is what takes Escape, Tab and Ctrl-W back from the browser;
+  that is Chromium-only, and the tab says which version you are getting rather than
+  pretending.
+  **One KVM per machine, and the tab follows the machine switcher** (corrected the same day:
+  the first cut was a hub-side list you pointed at machines, which had it backwards). Switch
+  to `grid` and you get grid's; adding a second for a machine replaces the first. The
+  addresses are still kept **on the hub** rather than on each machine, because a KVM earns
+  its keep exactly when the machine is down and its own Ham Lab cannot answer — the hub
+  proxies the device either way — and a KVM need not belong to a machine Ham Lab manages at
+  all. Not done: holding the device's own login on the hub, so its page does not ask for a
+  second password.
 - **Skins** — 13 since 2026-09-19 (`themes.ts`: a palette is one `mk(…)` line): Dark,
   Light, Cyberpunk, Retro, **HUD** (hairlines of cyan on near-black, corner ticks, thin
   type), Nord, Gruvbox, Catppuccin + Latte, Dracula, Tokyo Night, Solarized Dark + Light;
@@ -297,9 +495,16 @@ something long in one, switch away and back, refresh — it's all still there.
   replace, exec in place. Config default moved to `~/.config/hamlab` (existing
   `~/apps/hamlab` still found by the installer and the CLI). Tested in
   containers: Debian 12, Ubuntu 22.04, Fedora 40, Rocky 8, openSUSE Leap 15.5, Alpine
-  3.18/3.20 (OpenRC + doas, non-root), plus the four lab hosts. Not done: an OpenRC
-  backend for the Services tab; runit/s6/sysvinit service files; public hosting for
-  `install.sh` (the Gitea repo is private, so the one-liner needs `HAMLAB_TOKEN`).
+  3.18/3.20 (OpenRC + doas, non-root), plus the four lab hosts. **procd (OpenWrt) added
+  2026-09-26** (`internal/setup/hamlab.procd`): detected on `/sbin/procd` + `/etc/rc.common`
+  ahead of the OpenRC branch, installed to the same `/etc/init.d/hamlab` path and told apart
+  from OpenRC at uninstall by `USE_PROCD=1` in the file. Verified on the new router
+  (`gate`, OpenWrt 25.12.5, running as root): `S95`/`K10` symlinks, procd supervising the
+  instance, Docker tab and stacks working through the hub. The Updates tab needed no change
+  — apk-tools 3 answers `apk version -l '<'` the same way Alpine's does. Not done: an
+  OpenRC or procd backend for the Services tab (it is systemd-only and says so cleanly);
+  runit/s6/sysvinit service files; public hosting for `install.sh` (the Gitea repo is
+  private, so the one-liner needs `HAMLAB_TOKEN`).
 - **Users, sessions and settings that follow the account** — **shipped 2026-09-22**
   (`internal/api/users.go`, `config.User`, `store.Session`/`UserState`, `Login.tsx`,
   `Users.tsx` — a hub-only **Users** tab in the rail, added the same day at Mitchell's
@@ -427,6 +632,271 @@ something long in one, switch away and back, refresh — it's all still there.
   so both modes share one implementation and one set of rules (absolute paths only;
   `/`, `/etc`, `/usr`, … are never deleted or moved whole). Every write is logged with
   the caller's IP.
+- **Previews on the Files tab** — **shipped 2026-10-11** (v0.1.0-200, `internal/thumbs`,
+  `internal/api/thumbs.go`, `Thumb`/`ThumbNote` in `Files.tsx`). Asked for as a button that
+  toggles a file preview, "obviously not for everything", cached, "use whatever GPU is on the
+  machine we're looking at, and fall back to CPU", "a single small frame preview so it's
+  fast". A **previews** button beside `.hidden` turns the icon column into a 256 px
+  thumbnail for every image and video row (the listing says which: `preview: image|video`
+  per entry, decided by extension in one place, `thumbs.Kind`), loaded as rows scroll within
+  400 px of view — the list scrolls in a box of its own, so it has its own
+  IntersectionObserver rather than the browser's window-based lazy loading. A video thumb
+  carries a ▶ badge. The setting is in localStorage and follows the browser.
+  - **ffmpeg is the one engine**, for images and video alike; `GET /api/files/thumb` is one
+    ffprobe and one ffmpeg: `-ss` a tenth of the way in (30 s at most, `-noaccurate_seek`
+    so one keyframe is decoded), the first real video stream (cover art is skipped), one
+    frame, `scale` to fit 256, MJPEG q4 to a pipe. JPEGs decode at a reduced DCT size
+    (`-lowres`, enough halvings to stay at twice the preview) — a 24 MP photo is read as
+    1.5 MP. Thumbnails are the only thing Ham Lab asks a GPU to do, and it asks the way the
+    Processes tab reads one: **probed, never assumed.** The probe looks ffmpeg and ffprobe
+    up, opens every `/dev/dri/renderD*`, pushes a synthetic frame through each with VAAPI,
+    and reads `vainfo`'s decode profiles per node where it exists; CUDA is tried the same
+    way when `/dev/nvidiactl` is there (untested: nothing here has one). A video goes to the
+    first GPU listing its codec; ffmpeg's own software fallback sits behind that for a
+    profile the list did not distinguish, and a CPU retry behind a hardware run that fails
+    outright. Images are CPU only — one frame through libjpeg at a quarter size beats a
+    round trip through a GPU. Measured on `grid`: 1080p h264 0.4 s on the UHD 750 against
+    0.7 s on the CPU; the 8K Osmo HEVC 1.0 s against 2.9 s. `grid`'s two GPUs are listed in
+    node order and both decode the same set (h264, hevc, vp9, mjpeg, mpeg2 — **no AV1 on
+    either**, per vainfo, so AV1 is dav1d on the CPU).
+  - **Cached in one database file under the machine's data dir**, `<data dir>/thumbs.db`
+    (bbolt — pure Go, so the binary stays static; v0.1.0-202, the first build kept them as
+    a tree of hash-named JPEGs under `thumbs/`, replaced the same day when Mitchell asked
+    where they were kept: "stored in hamlab, maybe under a DB, up to you"). An entry is
+    keyed by path, size and mtime — a changed file gets a new preview, an unchanged one is
+    never decoded twice — and carries the engine, codec, source size and time beside the
+    picture; a count rides in the file so the previews button's tooltip can say "N kept
+    (M MB)" without walking anything. The URL carries `v=<mtime>-<size>` so the browser's
+    own cache is right too (7 days, ETag, 304). A file ffmpeg could not decode is kept with
+    ffmpeg's reason and no picture, answered as 422, retried only when the file changes; a
+    timeout is not kept. A miss never creates the file, so a machine nobody browses with
+    previews on never has one; a cache that cannot be opened is logged and previews are
+    still made and served, just not kept. Nothing expires: a preview is a few KB, and only
+    files somebody scrolled past are ever made. At most 2–4 ffmpegs at once per machine
+    (half the cores, clamped), one per file however many rows ask, and a preview's work
+    runs on a clock of its own so the row that asked first leaving does not cancel it for
+    the rest. Each ffmpeg runs under `nice -n 10`. `hamlet`'s backup job skips the file.
+  - **Root mode makes them as root** (`hamlab thumb`, the sibling of `hamlab fs`, caps on
+    stdin, JSON out), so a file only root can read gets a preview, and the probe runs as
+    root too — root opens every render node whatever groups the daemon has. Which matters:
+    a render node is `root:render 0660`, and on `core` and `hamtv` the `core` user is not in
+    `render`, so there the daemon's own previews are CPU and the tab says so, naming the GPU
+    and the owner, with an **Allow GPU access** button (confirms, then a task writes
+    `hamlab.service.d/gpu.conf` adding `render`/`video` as supplementary groups and
+    restarts Ham Lab three seconds later, the shape the Incus install used for
+    `incus-admin`). Not pressed anywhere yet. Where ffmpeg is missing (the Mac mini, `gate`)
+    the note offers **Install ffmpeg with dnf/apk** through the Updates machinery
+    (`ffmpeg-free` on Fedora, `ffmpeg` elsewhere); the status re-probes when the task ends.
+  - *Not done, on purpose:* no cap on the cache and no clear button (not asked; it only
+    holds what was looked at); no tonemapping for HDR sources (a 10-bit HEVC frame comes out
+    flat); no preview in the viewer for a video (it still says "binary, download it").
+- **Move… is a folder picker** — **shipped 2026-10-11** (v0.1.0-204, `MovePicker` in
+  `Files.tsx`, `internal/files/move.go`, `POST /api/files/move`). Asked for as: instead of
+  a path prompt, "an interactive file explorer, where I can go back/forward, etc and then
+  click some button, and it will move the file/folder to where I was". The picker opens in
+  the item's own folder and walks the machine the way the tab does — back and forward
+  through where it has been, up, breadcrumbs, a path box, folders only, `.hidden`
+  following the tab's toggle, **+ folder** to make the destination on the spot — and
+  **Move here** puts the item in the folder being looked at. It says why it can't when it
+  can't, with the button greyed: already here, a folder into itself, a name clash in that
+  folder (read from the listing before anything is tried). The row being moved shows in
+  its own folder, greyed. Rename stays a name prompt: it is a different question.
+  - **Across filesystems it copies, then removes.** `os.Rename` is EXDEV between
+    filesystems, and on `grid` every dataset is one — `/tank/media` to `/tank/files` was a
+    "invalid cross-device link" error before this, and the picker would have made that
+    move easy to attempt. `/api/files/move` renames when it can (204) and otherwise runs
+    `hamlab fs move` as a task (202 with the task; the tab shows its output and reloads
+    when it ends). The copy is built under a hidden name beside its destination
+    (`.<name>.hamlab-moving`), renamed into place once complete, and only then is the
+    original removed — a failure part-way removes the partial copy and leaves the original
+    as it was, and a cancel (SIGTERM to the helper) does the same. Modes, mtimes and
+    symlinks are kept; owners too when the backend is root. Devices, pipes and sockets are
+    refused outright rather than half-copied. Progress every 500 files or 512 MiB.
+    Verified on `grid` ext4 → ZFS with a tree holding a 0600 file, a symlink and an old
+    mtime, all intact on the other side.
+- **Video and audio play in the viewer** — **shipped 2026-10-11** (v0.1.0-208). Asked for
+  as "keep it simple for now, and just send whatever codec the file is in to the client,
+  and let the client try to decode and watch it" — and that is the whole design. Opening a
+  video or audio file shows a `<video>`/`<audio>` with the browser's own controls, fed the
+  file as it is by `/api/files/read`; nothing is transcoded or remuxed, so what plays is
+  what the browser decodes (Safari: h264/hevc/aac in mp4/mov; Chrome: those plus vp9/av1 in
+  mkv/webm, hevc only where the machine has a hardware decoder; nothing plays MPEG-TS or a
+  GoPro `.360`'s raw EAC strip). When the element errors the viewer says so and leaves the
+  download. What the server gained is the part a player cannot do without: reads of a
+  real file with a known size go through `http.ServeContent`, so **Range requests** (every
+  seek, and Safari's first request) and HEAD work, and a download can resume. The root
+  backend's helper takes `--offset` for that, and `files.Seeker` opens the backend once, at
+  the range asked for, rather than streaming from the top and skipping; seeking costs
+  nothing until a read wants somewhere else. `/proc` files, which stat at size 0, keep the
+  plain streaming path, as does the editor's capped read. Audio became a preview kind at
+  the same time (`thumbs.Kind` → `audio`): its cover art, where it has any, is the row's
+  thumbnail, with a ♪ badge.
+  - *Not done, on purpose:* no playlist or next/previous, no subtitles. (Transcoding came
+    the same evening after all — the next entry — because Safari turned out not to play
+    the gaming captures.)
+- **Re-encoding for the browser, on the machine's GPU** — **shipped 2026-10-11**
+  (v0.1.0-212, `internal/media/{encode,hls,ffrun,inspect}.go`, `internal/api/play.go`,
+  `Player.tsx`, `hls.js`). Asked for when Safari would not play the gaming captures:
+  "add GPU transcoding to a supported codec when the client browser can't play it. Each
+  machine should use its own GPU (if available) and transcode to probably H.264. Maybe we
+  need a quality selector, and a codec selector, up to you." What Safari actually refuses
+  is the **MKV container** — the captures checked are H.264 High 4:2:0, 18–36 Mbps — so
+  the picker has a "repackaged" choice beside the codecs, and a 36 Mbps capture over
+  WireGuard is the other reason to re-encode at all.
+  - **The viewer tries the file as it is first**, as before. When the browser gives up, or
+    on **Re-encode…** in the bar, a picker: **codec** — H.264, HEVC, AV1, or the original
+    codec repackaged — each labelled with the engine this machine would use (or greyed as
+    "not on this machine"), and **size** — original, 1080p, 720p, 480p; the choice is
+    remembered. Play starts the re-encode and the player follows it: "h264 High 2292×960
+    60 fps 36 Mbps in matroska → H.264 2292×960 5.0 Mbps on Intel Arc A380 (vaapi) · 7.3× ·
+    34% through — seek within what's done", then "all of it is ready". **Change…** drops
+    the stream and goes back to the picker.
+  - **HLS, made on the machine in the switcher.** `POST /api/files/play` inspects the file
+    (ffprobe, as root in root mode) and runs ffmpeg into an *event* playlist of 4 s
+    fragmented-MP4 segments under `<data dir>/transcode/<id>/`, answering once the first
+    segment exists (0.5–1 s on `grid`); the player reads the playlist and segments from
+    `/api/files/play/<id>/…` (only those three names are served), Safari natively and
+    everything else through hls.js, loaded only then. ffmpeg runs ahead at the engine's
+    pace, so the seekable range grows and the whole file is through long before it is
+    watched. Keyframes are forced every 4 s so segments cut cleanly; sound is AAC stereo
+    unless it already is AAC; HDR is tone-mapped (`tonemap_vaapi`, or zscale/hable on the
+    CPU). Nothing is kept: the same request within ten minutes reuses the stream, the
+    player closes it when it goes (and the "Change…" path does), the sweeper closes what
+    nobody touched for ten minutes, and the folder is emptied when the daemon starts. At
+    most three at once per machine (429 with the reason). Root mode runs ffmpeg as root
+    through `hamlab run-ffmpeg`, which ends when the daemon lets go of its stdin — so a
+    stream cannot outlive the console.
+  - **Engines are probed, never assumed**, the same probe the previews use, now also
+    reading each node's encode profiles from vainfo and ffmpeg's own encoder list. The
+    recipes for a codec are tried best first until one produces a first segment: a card on
+    the bus before the integrated GPU (the A380 before the UHD 750), decoding on the same
+    card so frames never leave it, then decoding on the CPU and uploading (a source the
+    card cannot decode — AV1 on `grid`), then libx264 / libx265 / SVT-AV1. The size is
+    never larger than the source, and the bit rate follows the output size (2/4/8/12/20
+    Mbps for 480p/720p/1080p/1440p/2160p, +25 % at 50 fps and up, ×0.6 for HEVC and AV1).
+    Measured on `grid` with a 2292×960 60 fps capture: H.264 7.3× realtime, HEVC 720p
+    11.7×, AV1 720p 13×, all on the Arc. `core` and `hamtv` re-encode on the CPU until
+    *Allow GPU access* is pressed (libx264 at 9.4× for a 720p→480p clip on `core`); the Mac
+    and `gate` need ffmpeg first, which the previews note offers to install.
+  - *Not done, on purpose:* no bit-rate ladder or adaptive switching, no subtitles, no
+    keeping a finished re-encode for next time. (Restart-from-a-seek was left out here at
+    first; it came 2026-10-20, the next entry.)
+- **Seek anywhere in a re-encode** — **2026-10-20**. Asked for as "there's no way to seek in
+  the video and have the service just start transcoding from that point onward".
+  - **The playlist is the whole film, up front:** a VOD playlist on a fixed 4 s grid
+    (`segCount`, the last 0.3 s left out so sound running past the picture never lists a
+    segment no frame starts), so the seek bar is the film's from the first frame.
+  - **A segment not on disk** is waited for when the run going now will write it within 3
+    segments; otherwise it is a seek: that run is ended and one starts at the segment asked
+    for. A run stops half a frame short of the next segment already on disk, never over it.
+    When a run ends by itself the next gap is filled, wrapping round, until every segment is
+    there. The newest request moves the run; an older one still waiting never moves it back.
+    A run we end closes its half-done segment short on the way out, so whatever it finished
+    after being asked to stop is deleted.
+  - **Runs are interchangeable** because every one, the first included, is made the same way
+    (`segArgs`): accurate `-ss` to the segment, timestamps put back with
+    `-output_ts_offset start+10` (the +10 keeps every run clear of the muxer's shift for the
+    B-frame delay, which a run from the top would otherwise get and a seek wouldn't), kept
+    absolute in each fragment (`movflags=+frag_discont`), `-start_number`. Tested on MKV
+    and on MPEG-TS with a 2.8 s start time (where `-copyts` was a second out): the init
+    segments come out byte-identical, and a seeked run's segments join a from-the-top run's
+    within a frame. Only the first run's init is served; a later run writes `init-run.mp4`
+    and the log notes if it ever differs.
+  - Repackaged ("copy") streams keep the growing event playlist: the source's keyframes
+    don't sit on a grid, and repackaging is near-instant anyway.
+  - A segment waits at most 45 s, under the hub proxy's 60 s for a node to answer; hls.js
+    is told a segment's first byte may take 50 s. The bar reads "7.3× from 12:00 · 43%
+    ready — seek anywhere".
+  - Tested (`TestSeekRestartsTheEncode`): a 64 s 1080p clip, a request for segment 12 right
+    after the start runs from 48 s, the gap is filled, all 16 segments joined behind the one
+    init decode with no hole.
+- **The player is Ham Share's; a Transcode device setting** — **2026-10-23** (v0.1.0-226,
+  `internal/media/{encode,play}.go`, `internal/api/play.go`, `Player.tsx`, `vr.ts`,
+  `Settings.tsx`). Asked for as "redo the HamLab one with the one you sent … a 'Transcode
+  Device' setting … the A380 on Grid selected … other options being the other transcode
+  devices like the iGPUs on the various CPUs that have HamLab installed". **Replaces** the
+  previous two entries' design: no codec/size picker, no single-quality re-encode, no
+  repackaging; the old streamer (`hls.go`) is gone.
+  - **YouTube's way:** Auto (hls.js reads the connection), any quality by hand, or Original
+    (the file as it is, `/api/files/read`, falling back to Auto when the browser can't). A
+    ladder by size (`Ladder`): flat 2160p/1440p/1080p/720p/480p by the short side, plus the
+    file's own size on top when it sits between steps (a 2292×960 capture gets 960p); 360
+    files by width, named as YouTube does (2160s 3840 … 720s). 720 and down at ≤30 fps.
+    H.264 High + AAC only.
+  - **Pieces made when asked for**, 3 s MPEG-TS, every quality's playlist written whole up
+    front. One ffmpeg per play: it starts at the piece asked, runs ahead, and is paused
+    (SIGSTOP; a root run through `run-ffmpeg`, which now reads `stop`/`cont` on stdin) 10
+    pieces ahead; a piece more than 3 past what's made, or at another quality, starts a new
+    run there. Keyframes only on the 3 s marks and every run's times offset alike
+    (`-output_ts_offset start+10`), so pieces from any run and quality join (`TestPieces`
+    checks it; `SRC=… DEVICE=… go test ./internal/media -run Pieces` on a machine with a GPU).
+    At most 3 runs a machine, the one asked of least lately ended for a fourth; 2 GiB of
+    pieces a play; forgotten after 30 min.
+  - **hls.js is patched** (`PatientAbr`): the wait for a piece being made isn't counted
+    against the connection, and a piece isn't abandoned before its first byte. Without it
+    Auto dropped to the bottom after every seek.
+  - **Transcode device** (Settings, hub-side, `store.Transcode`): every machine's devices
+    asked live (`GET /api/files/play-devices` on each), unusable ones greyed with the reason
+    (hamtv's UHD 600: the render permission; mac and gate: no ffmpeg). Set to **grid's Arc
+    A380**. "The machine the file is on" is the other choice. `POST /api/play` on the hub
+    opens the play where the setting says; **a machine transcoding another's file reads it
+    through the hub** at `/api/play-src/<token>` — a random token good for that one file, 12
+    h from its last use, ranges passed through to the file's machine (ffmpeg reconnects).
+    If that machine fails, the file's own makes it and the player says so.
+  - Recipes per device: same-card decode first, then CPU decode + upload, then libx264 as
+    the fallback whatever was asked. A card without `vainfo` (core) is tried anyway: core's
+    UHD encodes. **Rotation:** the card path turns a phone's picture itself
+    (`transpose_vaapi`, `-noautorotate`; ffmpeg's autorotate never applied to VAAPI frames,
+    so iPhone clips came out sideways). **HLG** is shown as it is (tonemap_vaapi refuses it);
+    HDR10 is tone-mapped on the card, else zscale/hable before the upload.
+  - 360 files: the look-around view, zoom 8°–300° (ordinary lens into stereographic, the
+    "little planet"), drag/pinch/wheel, phone motion. Full screen is the element's, or the
+    whole window on an iPhone.
+  - Measured (`web/scripts/e2e-player.mjs`, Chromium): an iPhone HLG clip on `core` made on
+    grid's A380 — 3.2 s to play, a seek 1.0 s, a quality change 1.5 s; the 8K 360 Disney day on
+    grid — 3.1 s, 2160s on Auto, a seek 4.9 s (10 s source keyframes).
+- **Files edge sweep** — **2026-10-11** (v0.1.0-214), asked for as "a full bug sweep of
+  the Files section, every example and edge case". Every handler and both UI files read
+  through with odd inputs in mind, then a battery of ~60 requests against the live hub
+  (`sweep.py`, not kept: listings of files, missing and forbidden paths, NUL bytes, names
+  with spaces/#/%/?/umlauts, links to files, folders and nothing, a pipe, over-size saves,
+  uploads with bad names and clashes, renames and moves onto things, protected paths,
+  thumbnails of empty and mislabelled images, playback of an image and an audio-only mp4,
+  root-mode variants). One real data bug: **a save over the 8 MiB cap truncated the file
+  and kept the first 8 MiB, answering 204** — the body is now read whole first and refused
+  with 413, the file untouched. The rest: a link to a file showed the link's own time; a
+  link to nothing read as an empty 200; a bad codec or size was answered by inspecting
+  the file; a failed stream was handed back to the next identical request; a player
+  leaving mid-start made the recipe loop try the next engine; a root-mode ffmpeg's end
+  could wait forever; a page closing kept its stream for ten minutes (a beacon now
+  releases it at once); the path box took only absolute paths (it resolves like a shell
+  now, in the tab and the Move picker, with a test); a dropped folder became a nameless
+  empty file; the upload toast counted intentions; the viewer called a pipe a binary
+  file. Not bugs, left alone: `rm -rf` of a mount point empties it (the console is
+  root-capable by design); a folder of ten thousand rows is slow (no virtual list).
+- **Whole-console sweep** — **2026-10-13** (v0.1.0-216), asked for as "a full sweep of
+  Ham Lab again, look for any bugs and fix them". Four nets, then reading: the Go race
+  detector over the whole suite (clean), staticcheck's development build (the release does
+  not know Go 1.26; it found only dead code and one capitalised error string), a
+  garbage-in battery over every route safe to poke — 202 routes, bad identifiers, empty
+  and malformed bodies, with the destructive ones held back — and a headless Chromium pass
+  through all twenty tabs on the hub and on `grid`, collecting exceptions, console errors
+  and failed requests (none). By hand: the auth middleware and sessions, token issue, the
+  hub→node and KVM proxies, every validation regex before a shell, the cron and cron.d
+  writers, config and state atomicity, every WebSocket and SSE loop's exit, the terminal
+  manager, the task manager, and every destructive confirmation in the UI. Fixed, all
+  small: docker inspect/health of a missing container was a 500 (404 now, a daemon that
+  is down 503), `/api/virt/instances/{name}` without Incus was a 502 (409 like its
+  siblings), a ZFS snapshot delete with a bad name was a 500 (400; 404 for one that does
+  not exist), the task list read a task's Running flag outside its lock (a real data race,
+  never seen), the Virtualization export config was written in place rather than
+  atomically, and the dead code. Nothing in auth, the proxies or the shell boundaries.
+  One self-inflicted finding: the battery's skip list left out `POST
+  /api/files/thumbs/gpu-access`, so the sweep pressed *Allow GPU access* on `core` three
+  times over — the drop-in landed and the hub restarted (that is what the headless pass
+  saw as a refused connection). Kept, since it is the fix the tab offers; `core` makes
+  previews and re-encodes on its UHD iGPU now. The handler refuses a second run while one
+  is in flight (409), since the second `systemd-run` only collided with the first's timer.
 - **Docker read-only view** — `docker ps`/logs; dockhand stays the source of truth.
 - **Notifications** — push on service failure / SMART warning / UPS event.
 - **Terminal extras** — search, copy-mode, font/theme, split panes, upload via
@@ -439,13 +909,94 @@ something long in one, switch away and back, refresh — it's all still there.
   `POST /api/password`, current password required), Access tokens (list/revoke the tokens
   hubs hold), About (version, host, arch, uptime, certificate).
 
+## Network tab (2026-09-27)
+
+A **Network** tab, per machine like every other: the interfaces as the kernel has them
+(addresses, MAC, MTU, negotiated link speed, carrier, byte totals, live rates from the
+sampler's own sensors), the default route and resolvers, what the internet sees of this
+connection, and an **internet speed test**.
+
+Decisions worth keeping:
+
+- **Measured by the daemon, not the browser.** The test runs on the machine in the switcher,
+  so the figure is that machine's line — the router's, if you switch to `gate` — and it
+  carries on if the phone locks or the tab closes. The page polls a run it is not driving.
+- **No tool to install.** It measures against Cloudflare's public speed endpoints
+  (`__down`, `__up`, `cdn-cgi/trace`), which is what makes it work identically on Debian and
+  on OpenWrt, where `opkg install` costs flash. That is the feature's one external
+  dependency, and it is named in `internal/network/speedtest.go`.
+- **Several streams, HTTP/2 off, and the ramp thrown away.** One stream over one connection
+  measures a congestion window; HTTP/2 would put every stream back on one connection and do
+  the same. The first second of each phase is measured and discarded.
+- **Latency is the round trip less the far end's own Server-Timing.** A zero-byte response
+  is mostly Cloudflare's worker running — 20 to 45 ms of it against a few ms of wire. Left
+  in, it reported 31 ms for a 7 ms line. Jitter is the mean change between consecutive
+  probes, not a standard deviation, so one slow probe doesn't run away with it.
+- **A refused phase is not a number.** The far end rate-limits by volume, and a test moves a
+  few hundred megabytes; several in a row earn 429s, and the block observed while building this
+  lasted over twenty minutes. So: a 20-second cooldown counted from the last *attempt* (a
+  refused test still used the line), a stream that retries twice before giving up, the rate
+  computed over the window in which bytes were actually still arriving, and a plain sentence
+  when it was cut short. Coasting to the end of the clock with nothing arriving reported a
+  third of the truth.
+- **A second download source, for when the first refuses.** A plain 100 MB file on Linode's
+  Seattle mirror, which has no opinion about volume. It is only reached after a refusal, and
+  every result names the source it used — that mirror is in one place, so on a machine far from
+  Seattle it would read low, and a number that quietly came from somewhere else would be a lie.
+  Upload stays on Cloudflare, which has never been the one to refuse.
+- **The last result is published as sensors** (`net.internet.*`), so the line is a widget, a
+  graph, an alert or a Prometheus series like anything else. Each carries the time the test
+  ran, not the time it was asked for.
+- **Not scheduled.** Nothing takes a speed test on its own. A nightly one recorded to the
+  history is the obvious next step and deliberately not built yet — the cron shape for it
+  already exists twice over (ZFS snapshots, Docker image updates).
+
+## VPN tab (2026-09-27)
+
+A **VPN** tab beside Network, per machine: every WireGuard tunnel on the machine in the
+switcher, and the devices on it — name, address, last handshake, where it connects from, and
+what it has moved.
+
+- **Per machine is the point, not a limitation.** The tunnel people dial into and a tunnel a
+  machine dials out through are on different boxes here (`gate` and `hamtv`), and a combined
+  view would invite exactly the question "which box is this on".
+- **The kernel is the truth, the config only supplies names.** `wg show all dump` has the
+  handshakes and counters and knows nothing but public keys; names come from the `# comment`
+  above a peer in a wg-quick file, or a UCI section's `description` on OpenWrt. Both are read
+  only to label what the kernel already said.
+- **Server or client is worked out, not declared.** A peer allowed `0.0.0.0/0` that has an
+  endpoint is a way out, so a tunnel holding one is this machine dialling out; a tunnel with a
+  listen port and peers is one being dialled. Anything else says neither rather than guessing.
+- **"Online" is a handshake in the last three minutes**, and the tab says so. WireGuard is
+  silent when idle; there is no connection to be in, and a tab claiming otherwise would be
+  lying twice a day.
+- **No secrets are read.** Private keys are in the second column of the dump and are read
+  past; pre-shared keys are noted as present and never read.
+- **Devices can be created, renamed and removed** (added 2026-09-27, asked for the same day),
+  on a tunnel the machine configures — today OpenWrt's UCI, which is where the server here
+  lives. A wg-quick host is reported unmanaged and shows no buttons: half-supporting a second
+  configuration format is worse than an honest refusal.
+  - **Nothing restarts the network.** `uci commit` writes the file and applies nothing; `wg
+    set` changes one peer on the live interface. Proven on `gate` by the existing peers'
+    transfer counters surviving a create and a delete — a reload would have zeroed them.
+  - **The two halves are ordered so they cannot disagree quietly.** Adding writes the
+    configuration first and rolls it back if the live tunnel refuses, because a device that
+    works only after the next reboot is the worst of the three outcomes. Removing does the
+    live tunnel first, since that is the moment access ends, and says so plainly if the
+    configuration half then fails.
+  - **The keypair is generated on the machine** and the profile, with its QR, is shown once.
+    The private key is stored nowhere — the same bargain as a guest login's password.
+  - **Removing asks for the name to be typed back**, at both ends. It cannot be undone and it
+    sits one tap from a list of devices that all look alike.
+
 ## To do
 
-- **Deprecate copyparty** — asked for 2026-09-23, not started. `copyparty` on `grid`
-  (`copyparty.service`, `:3923`, `/etc/copyparty.conf`, serving all of `/tank` as user
-  `core` with one account behind NPM) overlaps the **Files** tab almost entirely. The aim
-  is to stop the service and keep only Ham Lab. What Files must gain first, in the order
-  that matters:
+- **Grow the Files tab** — asked for 2026-09-23 as two items (Files polish, and deprecating
+  copyparty), merged 2026-09-24. **copyparty was retired 2026-10-11** at Mitchell's call,
+  ahead of these gaps rather than after them: service, files and NPM host all gone, with a
+  rollback archive kept on `grid` (`hamlet`'s `docs/hosts.md` has the detail). Files is now
+  the only file browser on `grid`, so the list below is no longer parity — it is the polish
+  still owed, in the order that matters:
   - **Multi-select and bulk actions.** copyparty selects many rows and moves, deletes or
     downloads them together; Files acts on one row at a time.
   - **Download a folder**, and a multi-file download, as a streamed zip or tar — the thing
@@ -453,39 +1004,71 @@ something long in one, switch away and back, refresh — it's all still there.
   - **Resumable uploads.** copyparty's up2k chunks a file, survives a dropped connection
     and skips what is already there; Files streams one PUT, so a phone upload that drops at
     90% starts over.
-  - **A gallery.** Thumbnails for a folder of images and video, and play audio/video in
-    place — `/tank/media` and `/tank/immich` are most of what is browsed.
+  - **A gallery.** ~~Thumbnails for a folder of images and video~~ (the **previews** toggle,
+    2026-10-11 — see the shipped entry above; a grid view is not built), and play
+    audio/video in place — `/tank/media` and `/tank/immich` are most of what is browsed.
   - **Search** below the current folder by name, since `find` in a terminal is the fallback
     today.
   - *Decide when built:* whether share links (copyparty's public per-path links) are wanted
     at all — they are the one feature that hands out access without a login, and Ham Lab has
     no notion of that; if not, say so in the docs rather than leaving a gap unexplained.
-  - *After:* `systemctl disable --now copyparty`, remove its NPM host, keep
-    `/etc/copyparty.conf` until a rollback is clearly not needed, then update
-    `hamlet`'s `docs/hosts.md` bare-metal list, `docs/gotchas.md` (the "`docker ps` is not
-    the inventory" note names it) and the `grid` row in `CLAUDE.md`.
 
-- **Deprecate Dockhand** — asked for 2026-09-23, not started; the *homelab* half of this
-  (migrating every stack off Dockhand's data dir, then removing the container) is
-  `hamlet`'s `docs/pending.md` → "Retire Dockhand; Ham Lab becomes the orchestrator",
-  agreed 2026-09-20. This entry is the *app* half only: what Ham Lab must do before that
-  migration can start. Its Stacks page already creates, edits, deploys, updates, restarts,
-  stops, downs and deletes stacks on every machine, so the gaps are Dockhand's extras:
-  - **Git-sourced stacks.** Dockhand's `stack_sources` table points a stack at a repo and
-    pulls it. Ham Lab has no equivalent. Decide whether to build it or to drop it — most
-    stacks here have no row in that table anyway, so dropping it may be honest.
-  - **Scheduled image updates.** Ham Lab checks for new images only when asked (a registry
-    request Docker Hub counts) and never updates by itself. If anything relies on Dockhand
-    updating on a schedule, that must move here or be dropped on purpose.
-  - **Webhooks / per-host environments**, if either is in use — inventory before deciding.
-  - **Deploying from a host path without an orchestrator container.** Ham Lab already runs
-    compose inside `dockhand` because that is how the stacks were deployed; once they move
-    to a neutral home the "via" path is unused for them, but a stack deployed to `grid` or
-    the Mac still goes over `tcp://<node>:2375` from the hub. Decide whether Ham Lab should
-    instead ask the node's own Ham Lab to deploy locally, which would end the `*:2375`
-    exposure (its own item in `docs/pending.md`).
-  - *Not app work, but the trigger:* nothing here blocks starting the migration except the
-    inventory. Do that first.
+- **Grow the Docker tab until Dockhand can go** — asked for 2026-09-23 and widened
+  2026-09-24 to take in Docker tab polish and feature work, on the same reasoning as the
+  Files item: it is one tab, and the gaps that block retiring the old tool and the things
+  that would simply make it better are the same body of work. The *homelab* half —
+  the cutover itself, then moving every stack off Dockhand's data dir — is `hamlet`'s
+  `docs/pending.md` → "Retire Dockhand; Ham Lab becomes the orchestrator", agreed
+  2026-09-20. This entry is the *app* half.
+
+  **Done 2026-09-24 — the eight Mitchell picked from the inventory**, all in the Docker tab:
+  per-container **Stats**, **Health** (with the last few probe outputs), **Events** (Ham Lab
+  keeps its own 4000-entry ring, since `docker events` forgets after about a minute),
+  **Shell** (`docker exec`, handed to the Terminal tab) and **Limits** (`docker update` for
+  memory, CPU and restart policy); an **updates** tab giving the whole machine at once with
+  a per-container indicator in the list; and **schedules**, which write
+  `/etc/cron.d/hamlab-docker` and call
+  `hamlab docker-update <id>` — the shape the ZFS schedules already use.
+  Also done: Ham Lab keeps working when `dockhand` is removed. It remembers where a
+  container's bind mounts pointed (`mounts` in `state.json`) and resolves a stack through
+  that record when no running container explains its path, running compose on the host
+  instead; `repoint` does the same for a schedule at run time. Without this, removing the
+  container would have made 17 stacks on `core` and 5 on `grid` unfindable at once.
+
+  - **Left from the Dockhand inventory, both to decide rather than build.**
+    - *Git-sourced stacks.* Dockhand's `stack_sources` table points a stack at a repo and
+      pulls it. Its `git_repositories` and `git_stacks` tables are **empty**, so nothing
+      here uses it — dropping it is the honest answer unless Mitchell says otherwise.
+    - *Webhooks, OIDC, LDAP, vulnerability scans.* All four tables empty. Nothing to move.
+
+  **Done 2026-09-25 — the two gaps in the tab itself.**
+  - *Logs are followed over a held connection*, the way the Services tab follows a journal
+    (`internal/api/docker_logs.go`, `/api/docker/containers/{id}/logs/tail`): one
+    `docker logs -f` per viewer, stdout and stderr both, stderr coloured as an error. A
+    reconnect resumes from the last line's timestamp, so a container that restarts or a
+    phone that slept doesn't replay what is already on screen; the client dedupes by line
+    rather than by "later than", because `--since` is inclusive and two lines can share a
+    timestamp. Docker replays the opening backlog down two pipes in no particular order, so
+    the first 300 ms is held and sorted before it is sent. The polled `?since=` endpoint
+    stays — it is what the resume is built on. Reconnects back off to 15 s, since a
+    container that has stopped ends the stream immediately.
+  - *Networks can be removed and pruned* — `POST /api/docker/networks/{remove,prune}`, the
+    shape images and volumes already had. The overview says who is attached to each one, so
+    the ✕ is only offered on a network nothing uses and never on Docker's own three. Prune
+    is deliberately untested against this host: `core` has several networks belonging to
+    stacks that are merely down (`pihole_default`, `transmission_default`, `gluetun_default`
+    among them), and pruning would take them and hand them new subnets on the next deploy.
+
+  - **The `*:2375` question — settled, and the code removed 2026-10-10.** The hub asks the
+    node's own Ham Lab; nothing probes or uses a node's Docker port. `hubStacks`,
+    `nodeDocker`, `taskOnHub`, the hub-side `/api/nodes/{node}/docker/…` routes and the
+    `remote` / `held_by` fields are gone. A schedule saved before this that still carries a
+    `remote` is refused with a message, never run against the wrong Docker. `PORTABILITY.md`
+    §3 has the audit it came from. Deployed as v0.1.0-191 and checked on all five machines
+    through the hub.
+
+- ~~**A Virtualization tab**~~ — built 2026-10-09, **cut 2026-10-15**: out of scope (see Decisions). The code, its plan and its tests are on the `virtualization` branch.
+
 
 ## Open questions
 

PORTABILITY.md

@@ -0,0 +1,161 @@
+# Portability audit — what in Ham Lab is specific to this lab (2026-10-09)
+
+Goal: Ham Lab drops onto any set of Linux machines and works. This is the full sweep of
+every place the code, defaults, docs or UI assume Mitchell's hosts, network, hardware,
+distro, init system, orchestrator history or posture. **Nothing here is fixed yet** — this
+is the list to work from. Each item: where, what it assumes, what the general form is.
+
+Virtualization was cut from the app 2026-10-15 (kept on the `virtualization` branch); its
+items — 1.8, 4.2, 5.1, 5.2, 6.14 and the Incus halves of 5.3, 5.7, 6.15, 10.3 — went with it.
+
+Severity key: **A** breaks or misbehaves on an ordinary host · **B** works but is wrong by
+default or phones home to this lab · **C** cosmetic (placeholder text, comments, docs).
+
+---
+
+## 1. Hard-wired lab identifiers
+
+| # | Sev | Where | Assumes | General form |
+|---|---|---|---|---|
+| 1.1 | **B** | `internal/selfupdate/selfupdate.go:36` `DefaultURL = "https://git.bigham.dev/api/v1/repos/mitchell/hamlab"` | Every install with no `update.url` checks **this** Gitea 90 s after boot and daily (`internal/api/update.go:1951, 2016`). A stranger's install phones home here by default. | Default should be **off** (or a build-time `-X` variable set at release). Installer asks or `install.sh` passes `HAMLAB_URL` through into `update.url`. |
+| 1.2 | **B** | `install.sh:4, 27` `HAMLAB_URL` default; `README.md:23-25, 31` | The curl one-liner and the install source are this Gitea. | Default comes from the release that served the script (`@URL@` filled by `make release`), or is required. |
+| 1.3 | **B** | `scripts/gitea-release.sh:14` `REPO` default | Publishing goes to `mitchell/hamlab` on this Gitea. | Require `HAMLAB_REPO`; no default. |
+| 1.4 | **C** | `README.md:100` "On `core` it is public at `https://hamlab.bigham.dev` behind Nginx Proxy Manager" | Lab deployment fact in the product README. | Move to `hamlet/docs/hosts.md`. |
+| 1.5 | **C** | `examples/external-demo/index.html:8` `base: 'http://10.0.0.234:8100'` | Demo config names the hub's LAN IP. | `http://<hamlab-host>:8100`. |
+| 1.6 | **C** | `SENSORS.md:149` Prometheus target `10.0.0.234:8100`; `:187` `&machine=grid`; `:196-208` Glance examples at `hamlab.bigham.dev`, `zfs.tank.used_pct`, `/api/nodes/grid/...`; `:218-220` `grid,wyse`, `{"core":…,"grid":…,"mac":…}` | Docs use real host names, pool and domain. | Generic placeholders (`<host>`, `<machine>`, `<pool>`). |
+| 1.7 | **C** | `PLAN.md:3-4` "bare-metal Debian 13 host. First target: `core` (10.0.0.234)"; decisions table rows (Listen `10.0.0.234:8100`, Data `/home/core/apps/hamlab/`, Ingress NPM/`hamlab.bigham.dev`, Repo) | Product plan is written as this lab's plan. | Keep as history, or split lab facts out to `hamlet`. The repo is public. |
+| 1.9 | **C** | `BUGS.md` throughout | Bug bashes narrate `core`, `grid`, `wyse`, `hamtv`, `gate`, the Mac. | History; fine to leave, but it is public. |
+| 1.10 | **C** | `cmd/hamlab/main.go:1` "Proxmox-style web console for a bare-metal Debian host"; `internal/hardware/hardware.go:5` "what Debian and its kin already have"; `internal/hardware/hardware.go:29` `// "GMKtec NucBox G3"`; `internal/metrics/metrics.go:1358` "did, on grid, 2026-10-02"; `internal/api/server.go:1382-1383` `["grid", …]`, `?machines=grid,wyse`; `internal/api/stacks.go:10` `/home/core/apps/dockhand/stacks/…`; `internal/api/dockersched.go:5` "unbound, nginx and pihole"; `internal/api/zfs.go:5` "grid already runs zfSnap"; `internal/storage/snapshots.go:6` "grid has run zfSnap v1.11.1"; `internal/api/guests.go:8` "Mitchell, 2026-09-27"; `internal/network/network.go:306` "the public address here is a DHCP lease"; `internal/metrics/gpu.go:17` "Asahi, today"; `internal/metrics/pciids.go:4-6` "the router's GPU"; `web/src/Top.tsx:522, 576`; `web/src/hashsel.ts:1-9`; `web/src/Embed.tsx:3` `&machine=grid` | Comments explain decisions by naming lab hosts. | Harmless, but rewrite the ones in package doc comments so a reader of the source doesn't need the lab to understand the code. |
+
+## 2. UI placeholders and defaults that are this lab's
+
+| # | Sev | Where | Text | General form |
+|---|---|---|---|---|
+| 2.1 | **C** | `web/src/Machines.tsx:116-118` | `placeholder="grid"`, `"https://10.0.0.214:8100"`, `"core"` | `nas`, `https://192.0.2.10:8100`, `admin` or the hub's own user. |
+| 2.2 | **C** | `web/src/KVM.tsx:166` | `placeholder="10.0.0.217"` (the NanoKVM on `grid`) | `192.0.2.20` or `kvm.local`. |
+| 2.3 | **C** | `web/src/Settings.tsx:242` | `placeholder="cpu.*, temp.*, zfs.tank.*"` | `cpu.*, temp.*, fs.*`. |
+| 2.4 | **C** | `web/src/Settings.tsx:225` | read-only token default name `'glance'` | Empty, or `dashboard`. |
+| 2.5 | **C** | `web/src/Alerts.tsx:38, 40` | `"Tank nearly full"`, `"zfs.tank.used_pct"` | `"Disk nearly full"`, `"fs.root.used_pct"`. |
+| 2.6 | **C** | `web/src/StackNew.tsx:110, 113, 114` | `/home/core/apps/whoami:/data`, `TZ=America/Los_Angeles`, `com.example.owner=mitchell` | `./data:/data`, `TZ=UTC`, `com.example.owner=you`. |
+| 2.7 | **C** | `web/src/Gallery.tsx:69`, `web/src/WidgetPicker.tsx:36` | `"find — gitea, temp, enp3s0…"`, `"filter sensors — cpu, temp, fan, enp3s0…"` | Drop the container and NIC names. |
+| 2.8 | **C** | `web/src/VPN.tsx:105` | default DNS for a new device `1.1.1.1, 1.0.0.1` | Fine as a public default, but should offer the tunnel's own address (the home resolver) first. |
+| 2.9 | **B** | `web/src/ZFS.tsx:212` `BLANK` | new schedule defaults `at: '02:30'`, `keep_for: '6w'` — `grid`'s old zfSnap cron line | Neutral defaults (`03:00`, `4w`), or none. |
+| 2.10 | **A** | `web/src/ZFS.tsx:302` `adopt()` | `/\b(tank[\w/-]*)\b/` — the dataset of an adopted external job is found by looking for the word **`tank`** | Parse the dataset from the command as the last `zfs`-shaped argument, or match against the datasets the page already has. On any other pool name adopt silently picks the fallback. |
+
+## 3. Topology inherited from the lab (hub `core`, Dockhand, `tcp://:2375`)
+
+| # | Sev | Where | Assumes | General form |
+|---|---|---|---|---|
+| 3.1 | **done** 2026-10-10 | `internal/api/stacks.go` `nodeDocker()` (removed) | For every node whose stacks aren't editable locally, the hub **probes `tcp://<node-host>:2375`** with `docker -H … version` and, if it answers, deploys to the node over an unauthenticated Docker socket. This is the Dockhand-era layout; on any other network an open 2375 is either absent or a security problem the console should not quietly use. | Remove the probe. The node's own Ham Lab deploys its stacks (the files live on the node, under its data dir). `PLAN.md` "To do" already names this decision. |
+| 3.2 | **done** 2026-10-10 | `hubStacks()`, `taskOnHub()`, the hub-side `/api/nodes/{node}/docker/…` routes, `Stack.remote`/`held_by` (all removed; the generic node proxy carries those requests) | A hub can hold compose files for a node and run compose remotely; new stacks for a node may be created **on the hub**. Only true here because Dockhand on `core` deployed `grid` and the Mac. | Same as 3.1: one machine, one set of files, one Docker. Hub-held stacks become an import path (copy to the node) rather than a steady state. |
+| 3.3 | **done** 2026-10-10 | `internal/api/stacks.go` `homesOf()` — `<DataDir>/stacks` is always offered first and default; the `~/stacks` fallback is gone; `TestHomesDefaultToDataDir` | Where new stacks go is **discovered** from where ≥2 stacks already are (Dockhand's `stacks/<machine>` habit), else `~/stacks`. Neither is Ham Lab's data directory, which the project's own rule says everything managed must live under. | Default home = `<DataDir>/stacks`. Discovered homes stay as *additional* places, never the default. |
+| 3.4 | **B** | `internal/api/stacks.go:100-203` remembered mounts, `internal/api/dockersched.go:772-795` `repoint()` | Machinery exists to find compose files **inside a removed orchestrator container's filesystem**. Generic in form, but it exists because of Dockhand and is exercised only here. | Keep (it is general), but it is not a reason to keep 3.1/3.2. |
+| 3.5 | — | `internal/api/stacks.go` `stackAction`, `internal/compose/compose.go` | Inside a `Via` container the command is literally `docker compose`. | **Checked 2026-10-10, no change:** the CLI inside an orchestrator's container is that container's own `docker`, independent of what the host runs; the host's tool only chooses the `exec`. Both places now say so in a comment. |
+| 3.6 | **B** | `internal/api/stacks.go:908` `docker buildx imagetools inspect` | Update checks need the **buildx** plugin. Docker CE on Debian has it; Podman and minimal Docker installs do not → every image reports "the registry didn't answer". | Fall back to `skopeo inspect` or a direct registry `HEAD` for the digest. |
+| 3.7 | **B** | `Makefile:445-448` `deploy` | The machine you build on **is** the hub: installs locally, then `push-nodes`. | Fine for a developer; document that `deploy` means "I am the hub". A plain `make install` target for a single box. |
+| 3.8 | **B** | `internal/nodes/nodes.go:316-323` | A hub pushes other architectures only if `<prefix>/hamlab-<arch>` siblings exist, which only `make deploy`/`install.sh`-from-dist put there. | A hub without siblings should fetch the right build from `update.url` instead of erroring. |
+
+## 4. Init system: systemd assumed where the product promises procd and OpenRC too
+
+The installer supports systemd, procd and OpenRC (`internal/setup/setup.go:217-262`). These paths do not.
+
+| # | Sev | Where | Assumes | General form |
+|---|---|---|---|---|
+| 4.1 | **A** | `internal/updates/updates.go:537-543` `Power()` | `systemctl reboot` / `systemctl poweroff`. On OpenWrt (`gate`) and OpenRC the Power dialog fails. | Try `systemctl`, else `reboot` / `poweroff` (busybox, OpenRC, sysvinit all have them). |
+| 4.3 | **A** | `internal/services/services.go:163-170` | Services tab is systemd-only ("says so cleanly"). `gate` (procd) and any OpenRC/runit/s6 box have no Services tab. | `rc-service`/`rc-status` (OpenRC), `/etc/init.d/<x> status` + `ubus call service list` (procd), `sv` (runit) backends. Noted as "not done" in `PLAN.md:487-489`. |
+| 4.4 | **A** | `internal/cron/cron.go:353-373, 401, 442, 532-534, 669-670` | Jobs tab reads `/etc/crontab`, `/etc/cron.d`, `/var/spool/cron{,/crontabs}` (Debian/cronie), `/usr/sbin/anacron`, last-runs from **journald**, timers via `systemctl`; writes only `/etc/crontab` and `/etc/cron.d`. Busybox crond (OpenWrt, Alpine) keeps crontabs in `/etc/crontabs/<user>` and has no `cron.d` → the Jobs tab is empty on `gate` and schedules written by 4.5 never run. | Add `/etc/crontabs/*` as a source; last-runs from syslog/logread when there is no journal. |
+| 4.5 | **A** | `internal/storage/snapshots.go:402` `/etc/cron.d/hamlab-zfs`; `internal/api/dockersched.go:65` `/etc/cron.d/hamlab-docker` | ZFS snapshot and image-update schedules are cron.d files. No cron.d on busybox crond; no cron at all on a systemd-timer-only host (Fedora Server, CoreOS). | Detect: cron.d → cron.d; busybox → a line in `/etc/crontabs/<user>`; none but systemd → a timer unit. The daemon-side runner already exists (`hamlab zfs-snapshot`, `docker-update`). |
+| 4.6 | **B** | `internal/hardware/hardware.go:333` `systemd-detect-virt` | Virtualisation detection is systemd-only. | Fall back to `/sys/class/dmi/id/sys_vendor`, `/proc/cpuinfo` `hypervisor` flag, `/sys/devices/virtual/dmi`. |
+| 4.7 | **B** | `internal/api/server.go:1129`, `internal/updates/updates.go:187` | `/run/reboot-required` is Debian/Ubuntu-only. `updates.Status` falls back to a kernel check for other distros; `/api/me.reboot_needed` (the Machines badge, the header's amber power button) does not. | Share one function. |
+| 4.8 | **B** | `install.sh:154-157, 164, 375-378`; `internal/setup/setup.go:284` | The wizard's init detection knows systemd and OpenRC only: on OpenWrt it warns "no systemd or OpenRC: nothing starts it at boot" although `hamlab install` then installs a procd script fine; the "logs" hint and the "isn't answering yet" hint have no procd case. | Add procd to both. |
+| 4.9 | **B** | `internal/setup/setup.go:609-641` `firewall()` | Only firewalld and ufw are detected. OpenWrt fw4/nftables, plain nftables, iptables, Alpine awall are not. | Detect `fw4`/`nft`/`iptables`; on OpenWrt add a LAN-zone rule or say what to open. |
+| 4.10 | **B** | `internal/setup/setup.go:568-605` `quietSudoers()`; `internal/services/services.go:176-185` | The sudoers quieting list is tuned to what the lab polls (`smartctl`, `pwrstat`, `journalctl`, `zpool`, `zfs`). A host with NUT or apcupsd gets `upsc`/`apcaccess` lines in its auth log at 10 s intervals; a host without `/etc/sudoers.d` (OpenWrt) gets nothing, which is correct. | Build the list from what the collector actually probes. |
+
+## 5. Distro and package assumptions beyond init
+
+| # | Sev | Where | Assumes | General form |
+|---|---|---|---|---|
+| 5.3 | **B** | `DEBIAN_FRONTEND`, `apt-get … -o Dpkg::Options::=--force-confold` in `internal/updates/updates.go:78, 432` | Debian-isms exported unconditionally. Harmless elsewhere. | Fine; note only. |
+| 5.4 | **B** | `scripts/pci-ids-gpu.sh:7, 41` default `/usr/share/misc/pci.ids` | Debian's path for `pci.ids`; Fedora/Arch keep it in `/usr/share/hwdata/`. Build-time only. | Try both. |
+| 5.5 | **B** | `internal/api/status_sensors.go:283`, `internal/api/docker.go:133` | Container memory/CPU read from three cgroup paths: cgroup v2 + systemd driver, cgroupfs, libpod. cgroup v1 hosts (older Debian/Ubuntu, some Alpine, OpenWrt) get no `container.*.mem/cpu`. | Add the v1 `memory/docker/<id>` and `cpu,cpuacct` paths, or fall back to `docker stats --no-stream` once in a while. |
+| 5.6 | **B** | `internal/metrics/metrics.go:1064` `clkTck = 100` | USER_HZ assumed 100. True on every mainstream build; wrong on a kernel built otherwise. | `sysconf` via `getconf CLK_TCK` once at start. |
+| 5.7 | **B** | `internal/space/manager.go:578-585` `timeout -s KILL` | GNU `timeout`. | Busybox has `timeout` too but flag spelling differs — use the context deadline. |
+
+## 6. Hardware and vendor assumptions
+
+| # | Sev | Where | Assumes | General form |
+|---|---|---|---|---|
+| 6.1 | **B** | `internal/metrics/gpu.go:343-383` `read()` | Busy/clock/VRAM are read for **i915, xe, amdgpu** only — the three GPUs in this lab. Nouveau, nvidia-drm, panfrost, v3d, Asahi are listed but never measured. `PLAN.md:317`: "No NVIDIA path: nothing here has one to test against." | `nvidia-smi --query-gpu` where present; `/sys/class/drm/*/device/gpu_busy_percent` for nouveau; `devfreq` for the ARM drivers. |
+| 6.2 | **B** | `internal/metrics/pciids_gpu.txt`, `scripts/pci-ids-gpu.sh:12-15` | Embedded PCI ID table trimmed to Intel, AMD, NVIDIA and three virtual vendors. Matrox, ASPEED (every server BMC), Moore Threads, etc. fall back to `lspci` or "Vendor GPU <id>". | Include the full display-class device list, not three vendors. |
+| 6.3 | **B** | `internal/metrics/gpu.go:237-241` | "Integrated" = PCI bus `0000:00:`. Wrong on multi-domain or APU boards where the iGPU hangs off a bridge; cosmetic. | Use `boot_vga` + `PCI_SUBSYS` heuristics, or drop the flag. |
+| 6.4 | **B** | `internal/metrics/metrics.go:189-196, 917-968` | UPS probe order **pwrstat (CyberPower) first**, then NUT, then apcupsd; pwrstat's `....`-separated output is parsed bespoke. A host with both pwrstat and NUT shows pwrstat only. | Prefer NUT (the vendor-neutral one), then the vendor tools; or list every UPS found. |
+| 6.5 | **B** | `internal/metrics/metrics.go:1179-1182` `cpuTemp()` | CPU temperature from `coretemp`, `k10temp`, `thermal`/`cpu`, `cpu_thermal`, `soc_thermal`. Misses `zenpower`, `acpitz` as the only sensor, Apple `macsmc` names, many ARM SoC zone names. | Broaden; fall back to the hottest zone when none matches. |
+| 6.6 | **B** | `internal/hardware/hardware.go:617-627` `jedec` | JEDEC IDs for "the memory makers who turn up in a homelab" — 14 entries. | Embed the JEDEC JEP106 bank list (public, small). |
+| 6.7 | **B** | `internal/storage/storage.go`, `internal/api/zfs.go`, `internal/storage/arc.go`, `web/src/ZFS.tsx` | A whole **ZFS** tab and ZFS-aware Space/Disks logic; **no btrfs or LVM equivalent** (snapshots, subvolumes, scrub, balance). Not wrong, but the tab list reflects a ZFS NAS. | Later: a Btrfs tab with the same shape, or a generic "Filesystems" tab that shows what the host has. |
+| 6.8 | **B** | `internal/storage/snapshots.go:1-16, 966-968` | Snapshot naming is **zfSnap's** (`2026-09-24_02.30.01--6w`) because `grid` ran zfSnap. A sanoid/zfs-auto-snapshot user's existing snapshots (`autosnap_…`, `zfs-auto-snap_daily-…`) are detected (`internal/api/zfs.go:1764-1798`) but can never be expired by Ham Lab, and new schedules write a third convention beside them. | Make the naming a per-schedule choice (zfSnap / sanoid / zfs-auto-snapshot), or at least document the convention as the product's rather than inherited. |
+| 6.9 | **B** | `internal/network/speedtest.go:64-67` `downSources` | Fallback download source is **`speedtest.seattle.linode.com`** — chosen because the lab is in the Pacific Northwest. Everywhere else it reads low. | Pick the nearest of several mirrors, or drop the fallback and report the refusal. |
+| 6.10 | **B** | `internal/network/speedtest.go:70-74, 604`, `internal/network/network.go:323-334` | Public IP, edge and speed come from **Cloudflare** endpoints, polled every 15 min with no off switch. Air-gapped or privacy-minded installs have no way to disable the outbound probe. | A `network.outside: off` setting; honour it in the watcher. |
+| 6.11 | **B** | `internal/vpn/edit.go:5-7, 419-421` | Peers can be **created/edited only through OpenWrt UCI** "because that is where the server here is configured". A wg-quick server (the common case everywhere else) is read-only. | Write wg-quick `.conf` too (append a `[Peer]` block + `wg set`), guarded the same way. |
+| 6.12 | **B** | `internal/vpn/vpn.go:251-253` | Peer names come from wg-quick comments or UCI descriptions — "which between them cover every machine here". NetworkManager and systemd-networkd WireGuard configs are not read. | Add `.nmconnection` and `.netdev` readers. |
+| 6.13 | **B** | `internal/vpn/edit.go:515` `profile()` | Split-tunnel routes hard-code `10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12` on top of the tunnel's own prefix. | Offer the host's actual LAN prefixes (from `TakenPrefixes`-style route reading), with RFC 1918 as the fallback. |
+| 6.15 | **B** | `internal/network/network.go:170-199, 303-314`; `internal/vpn/edit.go:558-595`; `internal/tlsauto/tlsauto.go:533-537`; `install.sh:114-120`; `internal/setup/setup.go:648-666` | **IPv4 everywhere**: default route from `/proc/net/route` only, outside view v4 only, peer allocation v4 only, cert SANs v4 only, installer lists v4 addresses only. | `/proc/net/ipv6_route`, v6 SANs, v6 peer addresses. An IPv6-only host today has no gateway, and no cert SAN. |
+
+## 7. Privilege and deployment posture (the lab's NOPASSWD-everywhere model)
+
+| # | Sev | Where | Assumes | General form |
+|---|---|---|---|---|
+| 7.1 | **A** | `internal/priv/priv.go`; every tab that calls `priv.Available()`; `web/src/Updates.tsx:2144` "give its user passwordless sudo or doas"; `web/src/Jobs.tsx:1883` | Full function needs the service user to have **unrestricted passwordless sudo**, which `hamlet/CLAUDE.md` grants on every host here. The installer neither creates nor offers a sudoers rule, so on a fresh box most tabs are read-only and the UI tells the user to go fix sudoers by hand. | `hamlab install --sudo` writes a **scoped** `/etc/sudoers.d/hamlab` naming the commands Ham Lab runs (smartctl, zpool, zfs, systemctl, docker, journalctl, tee for its cron files, `hamlab fs|space-walk|drm-clients|cpu-energy|replace`), or installs as root. Either way the console works out of the box. |
+| 7.2 | **A** | `internal/api/server.go:1069-1080` `clientKey()`, `:1083-1092`, `:431-433` `secure()` | The **first `X-Forwarded-For` hop is trusted unconditionally**, because here Ham Lab always sits behind Nginx Proxy Manager. On a host exposed directly, a client sets the header and defeats the per-client login rate limiter and the session IP check. | Trust `X-Forwarded-*` only from configured proxy addresses (`trusted_proxies` in config), else use the socket peer. |
+| 7.3 | **B** | `internal/api/server.go:1324` `X-Accel-Buffering: no` "nginx (NPM)" | Harmless header; comment names the lab's proxy. | Keep header; generalise comment. |
+| 7.4 | **B** | `internal/api/guests.go:1-9`, `PLAN.md:21` | Guest logins are full-power ("he gives these to people he trusts"). A product default. | Keep, but it is a posture decision taken for this household; a read-only guest is the generic expectation and was cut. Document as a deliberate choice in README. |
+| 7.5 | **B** | `internal/api/users.go:1-6` | "a household console, not a tenancy": any signed-in user can add users, make tokens, open a root shell. | Same as 7.4 — fine, but say so where a stranger installs it. |
+
+## 8. Resource tuning from the lab's smallest host
+
+| # | Sev | Where | Assumes | General form |
+|---|---|---|---|---|
+| 8.1 | **B** | `cmd/hamlab/main.go:451` `debug.SetMemoryLimit(160 << 20)`; `PLAN.md:11` "`core` has ~370 MiB free RAM" | A fixed 160 MiB soft heap limit sized for `core`. On a 64 GiB NAS it forces needless GC under a big Space scan; on a 512 MiB Pi it is still half the box. | Scale from `MemTotal` (e.g. 2–5 %, floor 64 MiB, ceiling 1 GiB), or make it a config key. |
+| 8.2 | **B** | `internal/space/walk.go:893` `workers := 32`; `internal/space/manager.go:578` 3-minute `zfs diff` patience | Tuned on `grid` (16 cores) and `core`. | Workers from `GOMAXPROCS`; patience configurable. |
+| 8.3 | **C** | `internal/metrics/metrics.go:32-43` intervals, `History = 300` | Reasonable generic defaults; listed only because 8.1 made them look lab-tuned. | None. |
+
+## 9. Data directory and legacy paths
+
+| # | Sev | Where | Assumes | General form |
+|---|---|---|---|---|
+| 9.1 | **B** | `internal/config/config.go:115-117` `Candidates()`; `internal/setup/setup.go:413-422`; `README.md:38` | `~/apps/hamlab/config.json` is searched as a legacy location — the lab's pre-v0.2 path, kept so `core`, `grid` and the Mac keep working. | Keep for one more release with a one-time migration log line, then drop. A stranger never had it. |
+| 9.2 | **done** 2026-10-10 | 3.3 above; `PLAN.md:24` "`grid`'s and the Mac's stacks at `~/stacks/<machine>/` are the standing exception" | The "everything under DataDir" rule has a lab-shaped exception baked into the stacks code. | Default to DataDir; treat `~/stacks` as a discovered home like any other. |
+| 9.3 | **C** | `internal/setup/setup.go:351` `ownFiles` | Correctly scoped; note only. | None. |
+
+## 10. Build and release
+
+| # | Sev | Where | Assumes | General form |
+|---|---|---|---|---|
+| 10.1 | **B** | `Makefile:60-61, 442-443`; `scripts/gitea-release.sh` | Publishing is Gitea/Forgejo-only (release API shape). `selfupdate` also understands a static directory, so publishing could too. | `make release` + any static host is already enough; add a GitHub/Forgejo-agnostic `release-dir` note. |
+| 10.2 | **C** | `scripts/gitea-release.sh:500-515` | Needs `python3` on the publishing host. | `jq`, or do it in Go (`hamlab publish`). |
+| 10.3 | **C** | `Makefile:392` `ARCHES ?= amd64 arm64 arm 386 riscv64` | Fine. | — |
+
+## 11. Things that are already general (checked, no change needed)
+
+Listed so the sweep is known to be complete, not because they need work.
+
+- `internal/priv` (root / sudo / doas), `internal/setup` service templates, `IP_FREEBIND` listen, self-update atomic replace and re-exec.
+- `internal/updates`: apt, dnf, zypper, pacman, apk with refresh/upgrade/install.
+- `internal/storage` block devices: `lsblk -J` with a `/sys/block` fallback, eMMC health, NVMe namespace folding, SMART only when `smartctl` exists.
+- `internal/metrics` CPU/mem/hwmon/thermal/net/disk/fs from `/proc` and `/sys`; remote-FS and pseudo-FS lists; filesystem statfs with a timeout.
+- `internal/hardware`: every reader may come back empty with a note; device-tree fallbacks for non-SMBIOS boards.
+- `internal/nodes`, `internal/tlsauto`: hub ↔ node pairing, pinned certs, proxy, push.
+- `internal/sensors`, alerts, widgets, embeds, Prometheus: machine-agnostic by design.
+- `internal/files`, `internal/term`, `internal/tasks`, `internal/auth`, `internal/store`.
+- `internal/api/kvm.go`: "nothing in it knows anything about any particular KVM" — verified.
+- `internal/compose` (modulo 3.5).
+- The React UI: machine-switcher model, hash routing, per-account prefs, themes.
+
+---
+
+## Suggested order of work
+
+1. **Posture and safety first (A):** 7.2 trusted proxies; 7.1 installer-written scoped sudoers; ~~3.1 drop the `:2375` probe (with 3.2 as its consequence)~~ done 2026-10-10.
+2. **"Any Linux" promises the README already makes (A):** 4.1 power, 4.4/4.5 cron on busybox and timer-only hosts, 4.3 a Services backend for OpenRC/procd, 2.10 the `tank` regex.
+3. **Lab defaults that phone home or mislead (B):** 1.1–1.3 update/install URLs, 2.9 schedule defaults, 6.9/6.10 speed-test sources and an off switch, 8.1 memory limit, ~~3.3/9.2 stack home = DataDir~~ done 2026-10-10.
+4. **Breadth (B):** 5.5 cgroup v1, 6.1/6.2 GPUs beyond Intel/AMD, 6.4 UPS order, 6.11/6.12 wg-quick/NetworkManager, 6.15 IPv6.
+5. **Cosmetics (C):** every placeholder and comment in §1.10 and §2, then split lab facts out of `PLAN.md`, `SENSORS.md`, `README.md`.

README.md

@@ -54,6 +54,14 @@ reset a password; your own password confirms the last two). From the shell:
 users` lists them, `hamlab user-rm <user>` removes one. Machine settings — refresh rate,
 graph history, alert rules — stay the machine's and are shared by everyone.
 
+**Guest logins**, for showing somebody the console: Users → Guest logins makes a
+throwaway user name and password, good for half an hour by default (up to 24 hours), and
+hands you the pair to paste into a message. A guest is an ordinary account with a clock on
+it — the whole console, every machine, the terminal included — that stops working when the
+time is up, wherever it is signed in, or the moment you revoke it. There is no reduced
+guest: give one to somebody you would hand the password to, and revoke it if you change
+your mind.
+
 What adapts to the host, rather than assuming Debian:
 
 | | |
@@ -62,6 +70,8 @@ What adapts to the host, rather than assuming Debian:
 | Updates tab | apt, dnf, zypper, pacman, apk: list, refresh, upgrade, install (pacman: all or nothing) |
 | Services / timers | systemd of any age (JSON output where it exists, the plain table before v246); a clear message on hosts without systemd |
 | Disks | `lsblk`, or `/sys/block` when it's missing (busybox) or too old; SMART and ZFS only when their tools are there |
+| Network | `/proc` and `/sys` for the interfaces, addresses, link speed and default route. The speed test needs no tool installed: it measures against Cloudflare's public speed endpoints, so it works the same on Debian and on the OpenWrt router |
+| VPN | WireGuard tunnels and their peers, from `wg show` where wireguard-tools is installed; peer names from wg-quick `.conf` comments or OpenWrt UCI descriptions. Read-only, and it never reads a private or pre-shared key |
 | Dashboard | `/proc` and `/sys` only: hwmon or thermal-zone temps, fans, NICs, disks, mounts; empty sections where the hardware has nothing to report. UPS from whichever of `pwrstat`, NUT (`upsc`) or `apcupsd` is installed |
 | Listen address | bound with `IP_FREEBIND`, so a LAN address that isn't up yet at boot doesn't fail the start |
 | Self-update | the new build must run and load this host's config before it replaces the old one; atomic rename; the daemon then re-execs itself, so it restarts the same way under systemd, OpenRC or nothing; `hamlab.prev` kept |

SENSORS.md

@@ -12,13 +12,16 @@ added to the registry in `api.New`.
 ## IDs
 
 ```
-cpu.usage  cpu.core.<n>.usage  cpu.temp  load.1|5|15  uptime
+cpu.usage  cpu.core.<n>.usage  cpu.temp  cpu.power  load.1|5|15  uptime
 mem.total|used|avail|free|cached|buffers|used_pct     swap.total|used|avail|used_pct
 temp.<chip>.<label>            fan.<chip>.<label>
 net.<iface>.rx|tx|rx_total|tx_total|up
+net.internet.download|upload|latency|jitter|tested|ip|edge
 disk.<dev>.read|write|util|size|temp
 fs.<mount>.size|used|used_pct
 ups.battery|runtime|load|load_pct|in_v|out_v|on_battery|state|source
+gpu.<name>.usage|render|video|video-enhance|copy|compute|temp|power|fan|freq|mem_used|mem_total|clients
+zfs.arc.size|target|min|max|mru|mfu|data|metadata|hit_pct|reads|misses|lifetime_hit_pct|no_grow|compress_ratio|l2_size|l2_hit_pct
 ```
 
 - Segments are lower case `[a-z0-9_-]`: `Package id 0` → `package_id_0`, `/mnt/tank` →
@@ -26,6 +29,29 @@ ups.battery|runtime|load|load_pct|in_v|out_v|on_battery|state|source
 - Built from names the hardware reports, never enumeration order (`hwmon3` moves between
   boots). Two identical chips collide; the second gets `_2`.
 - Which sensors exist differs per machine. That is the point of the catalog.
+- `net.internet.*` is the Network tab's speed test: `download` and `upload` in Mbps,
+  `latency` and `jitter` in ms, `tested` the age of the reading in seconds, and `ip` and
+  `edge` the public address and the Cloudflare edge as strings. They appear only once a test
+  has run on that machine, and each one's `t` is when it ran — so a widget or an alert on
+  them is reading a measurement from that moment, not a live value. Nothing takes a speed
+  test on its own; something has to press the button.
+- `cpu.power` is the CPU packages' own power in watts, from the kernel's RAPL energy
+  counters (Intel, and AMD Zen), summed over every package: cores, built-in graphics and
+  memory controller, not the whole machine. The counters are root-only, so a daemon that is
+  not root reads them through a helper started once with sudo or doas. It is absent on a
+  machine without the counters (ARM, the Mac mini) or without a way to root.
+- `gpu.<name>.*` is each graphics device, named as lspci names it (`gpu.intel_arc_a380`;
+  labels carry `driver` and the PCI `bus`). `usage` is how busy the device was — from the
+  GT's idle residency on Intel, `gpu_busy_percent` on amdgpu — and is absent on a driver
+  with no such counter. The per-engine percentages (`render`, `video`…) are the sum over the
+  processes holding the device open, read from DRM fdinfo, and exist only while something
+  has it open. `temp` is the card's own sensor, or on an integrated GPU the CPU package it
+  shares a die with (label `source` says which); an Arc on i915 has none and reports none.
+  `freq` is the actual clock, 0 when power-gated. `clients` counts the processes using it.
+- `zfs.arc.*` is the ZFS read cache in RAM, on a machine with the module loaded. `hit_pct`
+  is over the last sampling interval and appears once an interval has had any reads (an idle
+  interval repeats the last value); `lifetime_hit_pct` is since boot. `no_grow` is true
+  while memory pressure stops the cache growing. `l2_*` appear only with cache devices.
 
 ## A sensor
 

cmd/hamlab/main.go

@@ -4,6 +4,7 @@ package main
 import (
 	"bufio"
 	"context"
+	"encoding/json"
 	"errors"
 	"flag"
 	"fmt"
@@ -29,8 +30,10 @@ import (
 	"hamlab/internal/config"
 	"hamlab/internal/cron"
 	"hamlab/internal/files"
+	"hamlab/internal/media"
 	"hamlab/internal/metrics"
 	"hamlab/internal/nodes"
+	"hamlab/internal/priv"
 	"hamlab/internal/services"
 	"hamlab/internal/setup"
 	"hamlab/internal/space"
@@ -59,6 +62,8 @@ func main() {
   serve                run the console in the foreground (what the service runs)
   passwd [user]        set a user's password (makes the account if it is new; reads stdin when piped)
   users                list the accounts
+  zfs-snapshot <id>    run one ZFS snapshot schedule (what its cron line calls)
+  docker-update <id>   run one image-update schedule (what its cron line calls)
   user-rm <user>       remove an account and sign it out everywhere
   check                verify the config and state load, then exit
   version
@@ -76,8 +81,16 @@ func main() {
 	switch cmd { // commands that don't read the config
 	case "fs": // privileged helper for the Files tab (run as root by the daemon)
 		os.Exit(files.Helper(flag.Args()[1:], os.Stdin, os.Stdout, os.Stderr))
+	case "thumb": // privileged helper for the Files tab's previews in root mode (run as root by the daemon)
+		os.Exit(media.Helper(flag.Args()[1:], os.Stdin, os.Stdout, os.Stderr))
+	case "run-ffmpeg": // privileged helper for playback in root mode: ffmpeg as root, ending when stdin closes
+		os.Exit(media.RunFFmpegHelper(flag.Args()[1:], os.Stdin, os.Stderr))
 	case "space-walk": // helper for the Space tab: measure mountpoints, stream the tree back
 		os.Exit(space.Helper(flag.Args()[1:], os.Stdin, os.Stdout, os.Stderr))
+	case "drm-clients": // privileged helper for the GPU readings: who has the GPU open (run as root by the daemon)
+		os.Exit(metrics.DRMClientsHelper(os.Stdin, os.Stdout))
+	case "cpu-energy": // privileged helper for the CPU power reading: the packages' energy counters (run as root by the daemon)
+		os.Exit(metrics.CPUEnergyHelper(os.Stdin, os.Stdout))
 	case "install", "uninstall":
 		var err error
 		if cmd == "install" {
@@ -129,6 +142,14 @@ func main() {
 		if err := passwd(cfg, flag.Arg(1)); err != nil {
 			log.Fatal(err)
 		}
+	case "docker-update":
+		if err := dockerUpdateJob(cfg, flag.Arg(1)); err != nil {
+			log.Fatal(err)
+		}
+	case "zfs-snapshot":
+		if err := zfsSnapshot(cfg, flag.Arg(1)); err != nil {
+			log.Fatal(err)
+		}
 	case "users":
 		migrateUsers(cfg)
 		if len(cfg.Users) == 0 {
@@ -139,7 +160,14 @@ func main() {
 			if !u.LastSeen.IsZero() {
 				seen = u.LastSeen.Local().Format("2006-01-02 15:04")
 			}
-			fmt.Printf("%-20s created %s  last seen %s\n", u.Name, u.Created.Local().Format("2006-01-02"), seen)
+			note := ""
+			if u.Guest { // a temporary look-only login, not one of the machine's accounts
+				note = "  guest, until " + u.Expires.Local().Format("15:04")
+				if u.Expired(time.Now()) {
+					note = "  guest, expired"
+				}
+			}
+			fmt.Printf("%-20s created %s  last seen %s%s\n", u.Name, u.Created.Local().Format("2006-01-02"), seen, note)
 		}
 	case "user-rm":
 		if err := userRm(cfg, flag.Arg(1)); err != nil {
@@ -178,6 +206,100 @@ func main() {
 
 // migrateUsers gives a pre-users config its first account, named after this OS user, so
 // the CLI sees the same accounts the daemon will.
+// dockerUpdateJob pulls a stack's images, and deploys them when the schedule says to. This
+// is what the cron line Ham Lab writes actually calls, so image updates keep happening
+// whether or not the console is up.
+func dockerUpdateJob(cfg *config.Config, id string) error {
+	if strings.TrimSpace(id) == "" {
+		return errors.New("usage: hamlab docker-update <schedule-id>")
+	}
+	st, err := store.Open(filepath.Join(cfg.DataDir(), "state.json"))
+	if err != nil {
+		return err
+	}
+	var raw json.RawMessage
+	st.View(func(s *store.State) { raw = s.DockerJobs })
+	var d struct {
+		Jobs []api.UpdateJob `json:"jobs"`
+	}
+	if len(raw) > 0 {
+		if err := json.Unmarshal(raw, &d); err != nil {
+			return fmt.Errorf("reading the schedules: %w", err)
+		}
+	}
+	for _, j := range d.Jobs {
+		if j.ID != id {
+			continue
+		}
+		// A pull that never finishes must not leave a cron job resident until the next reboot.
+		ctx, cancel := context.WithTimeout(context.Background(), 2*time.Hour)
+		defer cancel()
+		out, runErr := api.RunUpdate(ctx, st, j, api.DockerTool())
+		rec := storage.RunRecord{At: time.Now(), Taken: j.Stack}
+		if runErr != nil {
+			rec.Error = runErr.Error()
+		}
+		if err := storage.WriteRun(cfg.DataDir(), "docker-"+id, rec); err != nil {
+			fmt.Fprintln(os.Stderr, "recording the run:", err)
+		}
+		fmt.Print(out)
+		return runErr
+	}
+	return fmt.Errorf("no image-update schedule %q — it may have been removed; this cron line is stale", id)
+}
+
+// zfsSnapshot runs one snapshot schedule: take it, then expire what has aged out. This is
+// what the cron line Ham Lab writes actually calls, so a schedule keeps running whether or
+// not the console is up — and keeps running if Ham Lab is never opened again.
+//
+// It deliberately does not write state.json. The daemon owns that file and would clobber
+// anything written from out here; the outcome goes beside it instead, in zfs-runs/.
+func zfsSnapshot(cfg *config.Config, id string) error {
+	if strings.TrimSpace(id) == "" {
+		return errors.New("usage: hamlab zfs-snapshot <schedule-id>")
+	}
+	st, err := store.Open(filepath.Join(cfg.DataDir(), "state.json"))
+	if err != nil {
+		return err
+	}
+	var raw json.RawMessage
+	st.View(func(s *store.State) { raw = s.ZFS })
+	var z struct {
+		Policies []storage.Policy `json:"policies"`
+	}
+	if len(raw) > 0 {
+		if err := json.Unmarshal(raw, &z); err != nil {
+			return fmt.Errorf("reading the schedules: %w", err)
+		}
+	}
+	var p *storage.Policy
+	for i := range z.Policies {
+		if z.Policies[i].ID == id {
+			p = &z.Policies[i]
+		}
+	}
+	if p == nil {
+		return fmt.Errorf("no snapshot schedule %q — it may have been removed; this cron line is stale", id)
+	}
+	res, runErr := storage.New(priv.Available()).Run(context.Background(), p)
+	rec := storage.RunRecord{At: time.Now(), Taken: res.Taken, Pruned: res.Pruned}
+	if runErr != nil {
+		rec.Error = runErr.Error()
+	}
+	if err := storage.WriteRun(cfg.DataDir(), id, rec); err != nil {
+		fmt.Fprintln(os.Stderr, "recording the run:", err)
+	}
+	if runErr != nil {
+		return runErr
+	}
+	fmt.Printf("%s: took %s", p.Name, res.Taken)
+	if len(res.Pruned) > 0 {
+		fmt.Printf(", expired %d", len(res.Pruned))
+	}
+	fmt.Println()
+	return nil
+}
+
 func migrateUsers(cfg *config.Config) {
 	name := os.Getenv("USER")
 	if u, err := user.Current(); err == nil && u.Username != "" {

go.mod

@@ -5,6 +5,7 @@ go 1.26.0
 require (
 	github.com/coder/websocket v1.8.15
 	github.com/creack/pty v1.1.24
+	go.etcd.io/bbolt v1.5.0
 	golang.org/x/crypto v0.57.0
 	golang.org/x/term v0.46.0
 )

go.sum

@@ -2,9 +2,21 @@ github.com/coder/websocket v1.8.15 h1:6B2JPeOGlpff2Uz6vOEH1Vzpi0iUz20A+lPVhPHtNU
 github.com/coder/websocket v1.8.15/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
 github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s=
 github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.etcd.io/bbolt v1.5.0 h1:S7GAl7Fxv12yohbwFfIbQCGDWbQbtDGPET4P/bD4lxU=
+go.etcd.io/bbolt v1.5.0/go.mod h1:mkltfYE5aUHQxUct9N9V+Kp7aSjFqjgrhcXIS70Lrdk=
 golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
 golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
 golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
 golang.org/x/term v0.46.0 h1:3+OXuTbaKDgwk8jTi3aSLHRlmWqHEUDUtxnbFigO4YE=
 golang.org/x/term v0.46.0/go.mod h1:+K02xbkittuwc0Am4abfA3Fc+XRGXkvBXNO88NCXPoc=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/api/alerts.go

@@ -122,6 +122,14 @@ func newAlertEngine(s *Server) *alertEngine {
 	for key, k := range e.saved.Firing {
 		e.state[key] = &alertState{pending: time.UnixMilli(k.Since), firing: true, since: time.UnixMilli(k.Since), value: k.Value}
 	}
+	// the Virtualization tab's default went with the tab (2026-10-15): nothing publishes instance.* now
+	kept := e.saved.Rules[:0]
+	for _, r := range e.saved.Rules {
+		if r.ID != "instance-down" {
+			kept = append(kept, r)
+		}
+	}
+	e.saved.Rules = kept
 	for i, r := range e.saved.Rules { // the first day's default watched "not running", which a container stopped on purpose also is
 		if r.ID == "container-down" && r.Sensor == "container.*.running" {
 			e.saved.Rules[i].Name, e.saved.Rules[i].Sensor, e.saved.Rules[i].Value = "Container down", "container.*.down", true

internal/api/docker.go

@@ -3,8 +3,8 @@ package api
 // The Docker tab: what is running, grouped the way it was deployed (compose stacks), with
 // start / stop / restart, logs and inspect — plus images, volumes and networks to look at.
 // It drives the docker CLI (or podman), as the user first and as root if that is refused.
-// Creating, removing and pruning are deliberately absent: whatever deployed the stacks
-// (Dockhand, compose) stays the one place that changes what exists.
+// What can be removed here is what nothing uses: an untagged image, a volume no container
+// holds, a network nothing is attached to. Compose stays the one place a stack is defined.
 
 import (
 	"context"
@@ -49,6 +49,10 @@ func dockerTool() string {
 }
 
 // dockerRun runs the tool as this user, and again as root if the socket said no.
+// DockerTool is whichever of docker or podman this machine has, for callers outside the
+// package — the scheduled updates the CLI runs.
+func DockerTool() string { return dockerTool() }
+
 func dockerRun(ctx context.Context, args ...string) ([]byte, error) {
 	tool := dockerTool()
 	if tool == "" {
@@ -72,6 +76,18 @@ func dockerRun(ctx context.Context, args ...string) ([]byte, error) {
 	return out, nil
 }
 
+// dockerWhy picks the line worth showing out of a failed command. Some subcommands —
+// `network rm` among them — print the real reason first and then an aggregated "exit
+// status 1", which is what dockerRun's last-line rule would otherwise hand back.
+func dockerWhy(out []byte, err error) string {
+	for _, l := range strings.Split(string(out), "\n") {
+		if l = strings.TrimSpace(l); strings.HasPrefix(l, "Error") || strings.Contains(l, "daemon") {
+			return l
+		}
+	}
+	return err.Error()
+}
+
 func jsonLines(out []byte, each func(map[string]any)) {
 	for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
 		var m map[string]any
@@ -135,23 +151,30 @@ func (s *Server) dockerOverview(w http.ResponseWriter, r *http.Request) {
 		}
 		return rows
 	}
-	// Who uses what, from one inspect of every container: an image or a volume nothing uses is
-	// the only kind this page offers to remove.
-	imageUsed, volumeUsers := map[string]bool{}, map[string][]string{}
+	// Who uses what, from one inspect of every container: an image, a volume or a network
+	// nothing uses is the only kind this page offers to remove.
+	imageUsed := map[string]bool{}
+	volumeUsers, networkUsers := map[string][]string{}, map[string][]string{}
 	if ids, err := dockerRun(ctx, "ps", "-aq"); err == nil && len(strings.Fields(string(ids))) > 0 {
-		const f = `{{.Name}}|{{.Image}}|{{range .Mounts}}{{if eq .Type "volume"}}{{.Name}},{{end}}{{end}}`
+		const f = `{{.Name}}|{{.Image}}|{{range .Mounts}}{{if eq .Type "volume"}}{{.Name}},{{end}}{{end}}|{{range $k, $v := .NetworkSettings.Networks}}{{$k}},{{end}}`
 		if out, err := dockerRun(ctx, append([]string{"inspect", "-f", f}, strings.Fields(string(ids))...)...); err == nil {
 			for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
-				p := strings.SplitN(line, "|", 3)
-				if len(p) < 3 {
+				p := strings.SplitN(line, "|", 4)
+				if len(p) < 4 {
 					continue
 				}
+				name := strings.TrimPrefix(p[0], "/")
 				if id := strings.TrimPrefix(p[1], "sha256:"); len(id) >= 12 {
 					imageUsed[id[:12]] = true
 				}
 				for _, v := range strings.Split(p[2], ",") {
 					if v != "" {
-						volumeUsers[v] = append(volumeUsers[v], strings.TrimPrefix(p[0], "/"))
+						volumeUsers[v] = append(volumeUsers[v], name)
+					}
+				}
+				for _, n := range strings.Split(p[3], ",") {
+					if n != "" {
+						networkUsers[n] = append(networkUsers[n], name)
 					}
 				}
 			}
@@ -171,8 +194,18 @@ func (s *Server) dockerOverview(w http.ResponseWriter, r *http.Request) {
 		v["used_by"] = users
 		v["anonymous"] = strings.Contains(dstr(v, "Labels"), "com.docker.volume.anonymous")
 	}
+	networks := list("network", "ls", "--format", "{{json .}}")
+	for _, n := range networks {
+		users := networkUsers[dstr(n, "Name")]
+		if users == nil {
+			users = []string{}
+		}
+		sort.Strings(users)
+		n["used_by"] = users
+		n["predefined"] = predefinedNetwork[dstr(n, "Name")]
+	}
 	jsonOK(w, 200, map[string]any{"available": true, "tool": dockerTool(), "containers": containers,
-		"images": images, "volumes": volumes, "networks": list("network", "ls", "--format", "{{json .}}")})
+		"images": images, "volumes": volumes, "networks": networks})
 }
 
 var dockerRef = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$`)
@@ -310,6 +343,21 @@ func (s *Server) dockerLogs(w http.ResponseWriter, r *http.Request) {
 }
 
 // dockerInspect is the parts of `docker inspect` worth reading on a phone.
+// dockerErr answers for a docker command that failed: a thing that isn't there is a 404,
+// the daemon being away a 503, anything else a 500.
+func dockerErr(w http.ResponseWriter, err error) {
+	msg := strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(err.Error()), "error: "))
+	low := strings.ToLower(msg)
+	switch {
+	case strings.Contains(low, "no such object") || strings.Contains(low, "no such container") || strings.Contains(low, "not found"):
+		jsonErr(w, 404, msg)
+	case strings.Contains(low, "cannot connect to the docker daemon") || strings.Contains(low, "is the docker daemon running"):
+		jsonErr(w, 503, msg)
+	default:
+		jsonErr(w, 500, msg)
+	}
+}
+
 func (s *Server) dockerInspect(w http.ResponseWriter, r *http.Request) {
 	id := r.PathValue("id")
 	if !dockerRef.MatchString(id) {
@@ -319,9 +367,13 @@ func (s *Server) dockerInspect(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
 	defer cancel()
 	out, err := dockerRun(ctx, "inspect", id)
+	if err != nil {
+		dockerErr(w, err)
+		return
+	}
 	var all []map[string]any
-	if err != nil || json.Unmarshal(out, &all) != nil || len(all) == 0 {
-		jsonErr(w, 500, fmt.Sprint("inspect failed: ", err))
+	if json.Unmarshal(out, &all) != nil || len(all) == 0 {
+		jsonErr(w, 500, "inspect: unreadable answer")
 		return
 	}
 	c := all[0]
@@ -394,3 +446,205 @@ func (s *Server) volumePrune(w http.ResponseWriter, r *http.Request) {
 	log.Printf("docker: volume prune (from %s)", clientIP(r))
 	jsonOK(w, 200, map[string]string{"result": lines[len(lines)-1]})
 }
+
+// The three networks Docker makes itself. They hold nothing, cannot be removed, and
+// their absence would break every container that asks for one by name.
+var predefinedNetwork = map[string]bool{"bridge": true, "host": true, "none": true}
+
+// networkRemove deletes one network. Unlike a volume there is no data in it, and unlike an
+// image nothing has to be downloaded again — a stack that wants it back gets it recreated
+// on the next deploy. Docker refuses one a container is still attached to, which is the
+// check that matters, so this asks for no second confirmation.
+func (s *Server) networkRemove(w http.ResponseWriter, r *http.Request) {
+	var body struct{ Name string }
+	if err := json.NewDecoder(io.LimitReader(r.Body, 4096)).Decode(&body); err != nil || !volumeRef.MatchString(body.Name) {
+		jsonErr(w, 400, "which network?")
+		return
+	}
+	if predefinedNetwork[body.Name] {
+		jsonErr(w, 400, body.Name+" is one of Docker's own networks and can't be removed")
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 90*time.Second)
+	defer cancel()
+	if out, err := dockerRun(ctx, "network", "rm", body.Name); err != nil {
+		jsonErr(w, 409, dockerWhy(out, err))
+		return
+	}
+	log.Printf("docker: network rm %s (from %s)", body.Name, clientIP(r))
+	w.WriteHeader(204)
+}
+
+// networkPrune removes every network no container is attached to. A stack that is merely
+// down counts as unattached, so its network goes too — and comes back on the next deploy,
+// with a new subnet. That is the whole cost, and the caller is told it.
+func (s *Server) networkPrune(w http.ResponseWriter, r *http.Request) {
+	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Minute)
+	defer cancel()
+	out, err := dockerRun(ctx, "network", "prune", "-f")
+	if err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+	log.Printf("docker: network prune (from %s)", clientIP(r))
+	jsonOK(w, 200, map[string]string{"result": lines[len(lines)-1]})
+}
+
+// ---- a container's health, its recent life, its console, and its limits ----
+
+// dockerHealth is the health check's verdict and the last few probe results. Docker keeps
+// the last five itself, which is all anyone wants: is it failing, and what did it say.
+func (s *Server) dockerHealth(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	if !dockerRef.MatchString(id) {
+		jsonErr(w, 400, "bad container")
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
+	defer cancel()
+	out, err := dockerRun(ctx, "inspect", "--format", "{{json .State}}", id)
+	if err != nil {
+		dockerErr(w, err)
+		return
+	}
+	var st struct {
+		Status string `json:"Status"`
+		Health *struct {
+			Status        string `json:"Status"`
+			FailingStreak int    `json:"FailingStreak"`
+			Log           []struct {
+				Start    time.Time `json:"Start"`
+				End      time.Time `json:"End"`
+				ExitCode int       `json:"ExitCode"`
+				Output   string    `json:"Output"`
+			} `json:"Log"`
+		} `json:"Health"`
+	}
+	if json.Unmarshal(out, &st) != nil {
+		jsonErr(w, 500, "could not read the container's state")
+		return
+	}
+	if st.Health == nil {
+		jsonOK(w, 200, map[string]any{"configured": false, "state": st.Status})
+		return
+	}
+	jsonOK(w, 200, map[string]any{
+		"configured": true, "state": st.Status, "status": st.Health.Status,
+		"failing_streak": st.Health.FailingStreak, "log": st.Health.Log,
+	})
+}
+
+// dockerExec opens a shell inside a container, as a terminal session like any other — so
+// it reattaches, resizes and scrolls back the same way, and works on a managed machine
+// through the same proxy.
+func (s *Server) dockerExec(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	if !dockerRef.MatchString(id) {
+		jsonErr(w, 400, "bad container")
+		return
+	}
+	tool := dockerTool()
+	if tool == "" {
+		jsonErr(w, 500, "neither docker nor podman is installed here")
+		return
+	}
+	var body struct {
+		Shell string `json:"shell"`
+	}
+	_ = json.NewDecoder(io.LimitReader(r.Body, 4096)).Decode(&body)
+	shell := strings.TrimSpace(body.Shell)
+	if shell == "" {
+		// most images have sh; bash is nicer where it exists, so try it first and fall back
+		shell = "if command -v bash >/dev/null 2>&1; then exec bash; else exec sh; fi"
+	} else if strings.ContainsAny(shell, "\n\r") {
+		jsonErr(w, 400, "bad shell")
+		return
+	}
+	argv := []string{tool, "exec", "-it", id, "sh", "-c", shell}
+	if priv.Available() && !dockerReachable() {
+		argv = priv.Wrap(argv...)
+	}
+	sess, err := s.mgr.CreateCmd("", "sh "+shortName(id), argv)
+	if err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	log.Printf("docker exec into %s as terminal %s by %s", id, sess.ID, clientIP(r))
+	jsonOK(w, 200, map[string]string{"id": sess.ID, "name": "sh " + shortName(id)})
+}
+
+func shortName(id string) string {
+	if len(id) > 20 {
+		return id[:20]
+	}
+	return id
+}
+
+// dockerReachable reports whether docker answers without help.
+func dockerReachable() bool {
+	tool := dockerTool()
+	if tool == "" {
+		return false
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	return exec.CommandContext(ctx, tool, "version", "--format", "{{.Server.Version}}").Run() == nil
+}
+
+// dockerUpdate changes a running container's limits and restart policy. `docker update`
+// does this live, without recreating it and without touching the compose file — which is
+// also the catch, and the caller is told: a deploy from compose puts back whatever compose
+// says.
+func (s *Server) dockerUpdate(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	if !dockerRef.MatchString(id) {
+		jsonErr(w, 400, "bad container")
+		return
+	}
+	var body struct {
+		Memory  string `json:"memory"`  // "512m", "2g", or "" to leave alone; "0" removes the limit
+		CPUs    string `json:"cpus"`    // "1.5", or "0" for no limit
+		Restart string `json:"restart"` // no | on-failure | unless-stopped | always
+	}
+	if err := json.NewDecoder(io.LimitReader(r.Body, 4096)).Decode(&body); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	args := []string{"update"}
+	if m := strings.TrimSpace(body.Memory); m != "" {
+		if !regexp.MustCompile(`^[0-9]+([bkmgBKMG])?$`).MatchString(m) {
+			jsonErr(w, 400, "memory: a number, optionally with b, k, m or g — 0 removes the limit")
+			return
+		}
+		args = append(args, "--memory", m, "--memory-swap", m)
+	}
+	if c := strings.TrimSpace(body.CPUs); c != "" {
+		if !regexp.MustCompile(`^[0-9]+(\.[0-9]+)?$`).MatchString(c) {
+			jsonErr(w, 400, "cpus: a number like 1.5 — 0 removes the limit")
+			return
+		}
+		args = append(args, "--cpus", c)
+	}
+	if p := strings.TrimSpace(body.Restart); p != "" {
+		switch p {
+		case "no", "on-failure", "unless-stopped", "always":
+		default:
+			jsonErr(w, 400, "restart: no, on-failure, unless-stopped or always")
+			return
+		}
+		args = append(args, "--restart", p)
+	}
+	if len(args) == 1 {
+		jsonErr(w, 400, "nothing to change")
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 30*time.Second)
+	defer cancel()
+	if _, err := dockerRun(ctx, append(args, id)...); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	log.Printf("docker update %s %v by %s", id, args[1:], clientIP(r))
+	w.WriteHeader(204)
+}

internal/api/docker_events.go

@@ -0,0 +1,229 @@
+package api
+
+// A container's history.
+//
+// `docker events` is a live stream with only a short in-memory backlog — ask it for the
+// last thirty days and you get the last few minutes, because the daemon keeps events in a
+// small ring and loses them all when it restarts. That is why Dockhand kept its own copy,
+// and why this does too: a watcher follows the stream and appends the lifecycle events to a
+// ring kept beside the config, so "what happened to this container last Tuesday" has an
+// answer.
+//
+// Only lifecycle events are kept. A health check produces three exec events every probe,
+// which is thousands a day and tells you nothing that the health panel does not.
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"log"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"hamlab/internal/priv"
+)
+
+const (
+	eventsKept      = 4000
+	eventsSaveEvery = 30 * time.Second
+)
+
+// ContainerEvent is one thing that happened to one container.
+type ContainerEvent struct {
+	T        int64  `json:"t"` // unix ms
+	Name     string `json:"name"`
+	Action   string `json:"action"`
+	Image    string `json:"image,omitempty"`
+	ExitCode string `json:"exit_code,omitempty"`
+	Signal   string `json:"signal,omitempty"`
+	Health   string `json:"health,omitempty"`
+}
+
+type eventLog struct {
+	mu    sync.Mutex
+	ring  []ContainerEvent
+	dirty bool
+	path  string
+}
+
+func (e *eventLog) load(path string) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	e.path = path
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return
+	}
+	var list []ContainerEvent
+	if json.Unmarshal(b, &list) == nil {
+		e.ring = list
+	}
+}
+
+func (e *eventLog) add(ev ContainerEvent) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	e.ring = append(e.ring, ev)
+	if len(e.ring) > eventsKept {
+		e.ring = append([]ContainerEvent(nil), e.ring[len(e.ring)-eventsKept:]...)
+	}
+	e.dirty = true
+}
+
+// forName is one container's events, newest first.
+func (e *eventLog) forName(name string, since time.Time, limit int) []ContainerEvent {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	out := []ContainerEvent{}
+	for _, ev := range e.ring {
+		if ev.Name == name && ev.T >= since.UnixMilli() {
+			out = append(out, ev)
+		}
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].T > out[j].T })
+	if len(out) > limit {
+		out = out[:limit]
+	}
+	return out
+}
+
+func (e *eventLog) save() {
+	e.mu.Lock()
+	if !e.dirty || e.path == "" {
+		e.mu.Unlock()
+		return
+	}
+	b, err := json.Marshal(e.ring)
+	e.dirty = false
+	path := e.path
+	e.mu.Unlock()
+	if err != nil {
+		return
+	}
+	_ = os.MkdirAll(filepath.Dir(path), 0o700)
+	tmp := path + ".tmp"
+	if os.WriteFile(tmp, b, 0o600) == nil {
+		_ = os.Rename(tmp, path)
+	}
+}
+
+// watchDockerEvents follows the stream, restarting if Docker goes away. It is the only
+// thing that writes the log, so nothing contends with it.
+func (s *Server) watchDockerEvents(ctx context.Context) {
+	s.events.load(filepath.Join(s.cfg.DataDir(), "docker-events.json"))
+	go func() { // a periodic flush, so a crash loses at most half a minute of history
+		t := time.NewTicker(eventsSaveEvery)
+		defer t.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				s.events.save()
+				return
+			case <-t.C:
+				s.events.save()
+			}
+		}
+	}()
+	for {
+		if ctx.Err() != nil {
+			return
+		}
+		if dockerTool() == "" {
+			time.Sleep(time.Minute) // no Docker here; look again later in case it is installed
+			continue
+		}
+		s.followEvents(ctx)
+		select {
+		case <-ctx.Done():
+			return
+		case <-time.After(10 * time.Second): // the daemon restarted, or the pipe broke
+		}
+	}
+}
+
+func (s *Server) followEvents(ctx context.Context) {
+	args := []string{"events", "--format", "{{json .}}", "--filter", "type=container"}
+	for _, e := range []string{"create", "start", "restart", "stop", "kill", "die", "destroy", "oom", "pause", "unpause", "rename", "update", "health_status"} {
+		args = append(args, "--filter", "event="+e)
+	}
+	tool := dockerTool()
+	full := append([]string{tool}, args...)
+	if !dockerReachable() && priv.Available() {
+		full = priv.Wrap(full...)
+	}
+	cmd := exec.CommandContext(ctx, full[0], full[1:]...)
+	out, err := cmd.StdoutPipe()
+	if err != nil {
+		return
+	}
+	if err := cmd.Start(); err != nil {
+		return
+	}
+	sc := bufio.NewScanner(out)
+	sc.Buffer(make([]byte, 64<<10), 1<<20)
+	n := 0
+	for sc.Scan() {
+		var e struct {
+			Action   string `json:"Action"`
+			Time     int64  `json:"time"`
+			TimeNano int64  `json:"timeNano"`
+			Actor    struct {
+				Attributes map[string]string `json:"Attributes"`
+			} `json:"Actor"`
+		}
+		if json.Unmarshal(sc.Bytes(), &e) != nil || e.Action == "" {
+			continue
+		}
+		at := e.Actor.Attributes
+		ev := ContainerEvent{
+			T: e.Time * 1000, Name: at["name"], Image: at["image"],
+			Action: e.Action, ExitCode: at["exitCode"], Signal: at["signal"],
+		}
+		if e.TimeNano > 0 {
+			ev.T = e.TimeNano / 1e6
+		}
+		// health_status comes through as "health_status: healthy"
+		if a, h, ok := strings.Cut(e.Action, ": "); ok {
+			ev.Action, ev.Health = a, h
+		}
+		if ev.Name == "" {
+			continue
+		}
+		s.events.add(ev)
+		n++
+	}
+	_ = cmd.Wait()
+	if n > 0 {
+		log.Printf("docker events: stream ended after %d events; reconnecting", n)
+	}
+}
+
+// dockerEvents answers from Ham Lab's own history, not Docker's short memory.
+func (s *Server) dockerEvents(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	if !dockerRef.MatchString(id) {
+		jsonErr(w, 400, "bad container")
+		return
+	}
+	since := r.URL.Query().Get("since")
+	d := 7 * 24 * time.Hour
+	switch since {
+	case "24h":
+		d = 24 * time.Hour
+	case "30d":
+		d = 30 * 24 * time.Hour
+	default:
+		since = "7d"
+	}
+	ev := s.events.forName(id, time.Now().Add(-d), 500)
+	s.events.mu.Lock()
+	total := len(s.events.ring)
+	s.events.mu.Unlock()
+	jsonOK(w, 200, map[string]any{"events": ev, "since": since, "kept": total, "capacity": eventsKept})
+}

internal/api/docker_logs.go

@@ -0,0 +1,206 @@
+package api
+
+// Following a container's log over a held connection, the way the Services tab follows a
+// journal. The polled `?since=` endpoint next door still exists — it is what a reconnect
+// hands back to pick up from — but the live view holds one `docker logs -f` per viewer
+// instead of asking again every two seconds.
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"os/exec"
+	"sort"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/coder/websocket"
+
+	"hamlab/internal/priv"
+)
+
+// logLine is one line of a container's output: the time Docker stamped it with, the text,
+// and which of the two streams it came out of — stderr is where a container says what went
+// wrong, and the page colours it accordingly.
+type logLine struct {
+	T   string `json:"t"`
+	M   string `json:"m"`
+	Err bool   `json:"err,omitempty"`
+	at  string // when to sort it by: its own stamp, or the last one its stream carried
+}
+
+// splitStamp pulls Docker's RFC 3339 prefix off a line. A line without one (a container
+// that writes bare bytes, or a continuation) keeps the whole text and no time — but is
+// still sorted where its stream put it, behind the last line that did have one.
+func splitStamp(l string, carry *string) logLine {
+	t, m, ok := strings.Cut(l, " ")
+	if _, err := time.Parse(time.RFC3339Nano, t); !ok || err != nil {
+		return logLine{M: l, at: *carry}
+	}
+	*carry = t
+	return logLine{T: t, M: m, at: t}
+}
+
+// dockerTail streams a container's output as JSON text frames until the client goes away.
+// `?since=<RFC3339>` resumes where a dropped connection left off; otherwise it starts with
+// the last `?n=` lines.
+func (s *Server) dockerTail(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	if !dockerRef.MatchString(id) {
+		jsonErr(w, 400, "bad container")
+		return
+	}
+	tool := dockerTool()
+	if tool == "" {
+		jsonErr(w, 500, "neither docker nor podman is installed here")
+		return
+	}
+	args := []string{tool, "logs", "--timestamps", "--follow"}
+	if since := r.URL.Query().Get("since"); since != "" {
+		if _, err := time.Parse(time.RFC3339Nano, since); err != nil {
+			jsonErr(w, 400, "since is an RFC 3339 time")
+			return
+		}
+		args = append(args, "--since", since)
+	} else {
+		args = append(args, "--tail", strconv.Itoa(logCount(r)))
+	}
+	args = append(args, id)
+	if priv.Available() && !dockerReachable() {
+		args = priv.Wrap(args...)
+	}
+
+	conn, err := websocket.Accept(w, r, &websocket.AcceptOptions{CompressionMode: websocket.CompressionDisabled})
+	if err != nil {
+		return
+	}
+	defer conn.Close(websocket.StatusNormalClosure, "")
+	ctx, cancel := context.WithCancel(r.Context())
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, args[0], args[1:]...)
+	// Own process group, so the kill reaches the docker client itself and not just a sudo
+	// wrapper — the same reason the journal tail does it.
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	cmd.Cancel = func() error {
+		pg := "-" + strconv.Itoa(cmd.Process.Pid)
+		if args[0] != tool { // running under sudo: only sudo can signal root's children
+			k := priv.Wrap("kill", "-9", "--", pg)
+			return exec.Command(k[0], k[1:]...).Run()
+		}
+		return syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+	}
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return
+	}
+	stderr, err := cmd.StderrPipe()
+	if err != nil {
+		return
+	}
+	if err := cmd.Start(); err != nil {
+		_ = conn.Write(ctx, websocket.MessageText, mustJSON(logLine{M: err.Error(), Err: true}))
+		return
+	}
+
+	// Both pipes funnel into one writer: a websocket takes one writer at a time.
+	lines := make(chan logLine, 256)
+	read := func(p io.Reader, isErr bool) {
+		sc := bufio.NewScanner(p)
+		sc.Buffer(make([]byte, 0, 64<<10), 4<<20)
+		carry := ""
+		for sc.Scan() {
+			l := splitStamp(sc.Text(), &carry)
+			l.Err = isErr
+			select {
+			case lines <- l:
+			case <-ctx.Done():
+				return
+			}
+		}
+	}
+	done := make(chan struct{}, 2)
+	go func() { read(stdout, false); done <- struct{}{} }()
+	go func() { read(stderr, true); done <- struct{}{} }()
+	go func() { // the command ends when the container does; closing says so, having said why
+		<-done
+		<-done
+		_ = cmd.Wait()
+		close(lines)
+	}()
+
+	go func() { // reader: only to notice the close
+		defer cancel()
+		for {
+			if _, _, err := conn.Read(ctx); err != nil {
+				return
+			}
+		}
+	}()
+
+	ping := time.NewTicker(25 * time.Second)
+	defer ping.Stop()
+	// stdout and stderr are two pipes, and what Docker replays down them arrives in no
+	// particular order. So the opening burst is held for a moment and sorted by the time
+	// Docker stamped each line with; after that the log is live and arrives in order anyway.
+	const burstFor = 300 * time.Millisecond
+	warm := time.NewTimer(burstFor)
+	defer warm.Stop()
+	warmC := warm.C // nil once the burst has been flushed: a nil channel never fires
+	var burst []logLine
+	write := func(l logLine) bool {
+		return conn.Write(ctx, websocket.MessageText, mustJSON(l)) == nil
+	}
+	flush := func() bool {
+		sort.SliceStable(burst, func(i, j int) bool { return burst[i].at < burst[j].at })
+		for _, l := range burst {
+			if !write(l) {
+				return false
+			}
+		}
+		burst = nil
+		return true
+	}
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case l, ok := <-lines:
+			if !ok { // the container stopped, or never existed: say the last of it and go
+				flush()
+				return
+			}
+			if warmC != nil {
+				burst = append(burst, l)
+				if len(burst) < 10000 { // a container that never stops talking still gets read
+					continue
+				}
+				if !flush() {
+					return
+				}
+				continue
+			}
+			if !write(l) {
+				return
+			}
+		case <-warmC:
+			warmC = nil
+			if !flush() {
+				return
+			}
+		case <-ping.C:
+			pctx, pc := context.WithTimeout(ctx, 10*time.Second)
+			err := conn.Ping(pctx)
+			pc()
+			if err != nil {
+				return
+			}
+		}
+	}
+}
+
+func mustJSON(v any) []byte { b, _ := json.Marshal(v); return b }

internal/api/dockersched.go

@@ -0,0 +1,356 @@
+package api
+
+// Scheduled image updates.
+//
+// Dockhand kept three containers up to date nightly — unbound, nginx and pihole, which is
+// DNS and ingress — and that is the one thing it does that Ham Lab did not. This replaces
+// it, and deliberately in the same shape as the ZFS snapshot schedules: a real line in a
+// cron file Ham Lab owns, calling the binary, rather than a ticker inside the daemon.
+// Updating an image is not something that should stop happening because a web console is
+// down, and a cron line is visible to anyone looking at the machine the normal way.
+//
+// A schedule stores everything the run needs — project, compose files, how compose has to
+// be invoked for that stack — so the cron job is self-contained and does not have to
+// rediscover the world before it can act.
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"hamlab/internal/compose"
+	"hamlab/internal/cron"
+	"hamlab/internal/storage"
+	"hamlab/internal/store"
+)
+
+// UpdateJob is a standing instruction to pull a stack's images, and optionally deploy them.
+type UpdateJob struct {
+	ID      string `json:"id"`
+	Name    string `json:"name"`
+	Stack   string `json:"stack"`
+	Machine string `json:"machine,omitempty"` // for display; the job runs where it was made
+	// Services narrows it to some of the stack's services; empty is all of them.
+	Services []string `json:"services,omitempty"`
+	Cron     string   `json:"cron"`
+	// Apply says whether a newer image is deployed or only fetched. Check-only still pulls,
+	// so the Docker tab shows what is behind without a registry round trip.
+	Apply   bool `json:"apply"`
+	Enabled bool `json:"enabled"`
+
+	// How to run compose for this stack, captured when the schedule was made.
+	Spec composeSpec `json:"spec"`
+}
+
+type composeSpec struct {
+	Project string   `json:"project"`
+	Files   []string `json:"files"`
+	Via     string   `json:"via,omitempty"`
+	// Remote is read but never written: schedules made before v0.2 could point compose at
+	// another machine's Docker over tcp. Such a job is refused rather than run against this
+	// machine's Docker, which is where it would land without the variable.
+	Remote string `json:"remote,omitempty"`
+}
+
+func (c composeSpec) toSpec(tool string) compose.Spec {
+	return compose.Spec{Project: c.Project, Files: c.Files, Via: c.Via, Tool: tool}
+}
+
+const dockerCronFile = "/etc/cron.d/hamlab-docker"
+
+type dockerSchedState struct {
+	Jobs []UpdateJob `json:"jobs"`
+}
+
+func (s *Server) dsLoad() dockerSchedState {
+	var raw json.RawMessage
+	s.store.View(func(st *store.State) { raw = st.DockerJobs })
+	var d dockerSchedState
+	if len(raw) > 0 {
+		_ = json.Unmarshal(raw, &d)
+	}
+	if d.Jobs == nil {
+		d.Jobs = []UpdateJob{}
+	}
+	return d
+}
+
+func (s *Server) dsSave(d dockerSchedState) error {
+	b, err := json.Marshal(d)
+	if err != nil {
+		return err
+	}
+	return s.store.Update(func(st *store.State) { st.DockerJobs = b })
+}
+
+// dsCronText renders the schedules as cron lines. Same shape as the ZFS file: Ham Lab owns
+// it whole and rewrites it on every change.
+func dsCronText(jobs []UpdateJob, user, exe, config string) (string, error) {
+	var b strings.Builder
+	b.WriteString("# Ham Lab image-update schedules — written by the Docker tab, rewritten whole on every change.\n")
+	b.WriteString("# Edit them there, not here: anything added by hand is lost the next time a schedule changes.\n")
+	b.WriteString("SHELL=/bin/sh\nPATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\n\n")
+	for i := range jobs {
+		j := &jobs[i]
+		if !j.Enabled {
+			b.WriteString("# " + j.Name + " — paused\n")
+			continue
+		}
+		expr := strings.Join(strings.Fields(j.Cron), " ")
+		if err := cron.ValidSchedule(expr); err != nil {
+			return "", err
+		}
+		what := "pull only"
+		if j.Apply {
+			what = "pull and deploy"
+		}
+		b.WriteString("# " + j.Name + " — " + j.Stack + ", " + what + "\n")
+		b.WriteString(expr + " " + user + " " + exe + " -config " + config + " docker-update " + j.ID + "\n\n")
+	}
+	return b.String(), nil
+}
+
+func (s *Server) dsSyncCron(ctx context.Context, d dockerSchedState) error {
+	live := false
+	for i := range d.Jobs {
+		if d.Jobs[i].Enabled {
+			live = true
+		}
+	}
+	if !live {
+		return s.storage.RemoveRootFile(ctx, dockerCronFile)
+	}
+	exe, err := os.Executable()
+	if err != nil {
+		return err
+	}
+	exe, _ = filepath.EvalSymlinks(exe)
+	text, err := dsCronText(d.Jobs, s.user, exe, s.cfg.Path())
+	if err != nil {
+		return err
+	}
+	return s.storage.WriteRootFile(ctx, dockerCronFile, text)
+}
+
+// repoint keeps a schedule working when what deployed its stack has been removed.
+//
+// A schedule captures how to invoke compose at the moment it is made, so the cron job never
+// has to rediscover the world at 3am. But "run compose inside this container" stops being
+// true the day that container is deleted — which is exactly what happens when an
+// orchestrator is retired, and would otherwise break every schedule made before it went.
+// So: if the container named is not running, the files are looked up again, through live
+// mounts and remembered ones both, and compose runs on the host instead.
+func repoint(ctx context.Context, db *store.Store, spec compose.Spec) compose.Spec {
+	if spec.Via == "" || db == nil {
+		return spec
+	}
+	if out, err := dockerRun(ctx, "inspect", "-f", "{{.State.Running}}", spec.Via); err == nil && strings.TrimSpace(string(out)) == "true" {
+		return spec
+	}
+	st := stack{Name: spec.Project, File: spec.Files[0], Files: spec.Files}
+	st.resolve(mountsSeen(ctx, db)) // read-only: this also runs from cron, where the daemon owns state.json
+	if !st.Editable || st.Via != "" {
+		return spec // still only reachable through a container, or not reachable at all
+	}
+	log.Printf("docker schedule %s: %s is gone, running compose here against %s", spec.Project, spec.Via, st.HostFiles[0])
+	spec.Files, spec.Via = st.HostFiles, ""
+	return spec
+}
+
+// RunUpdate pulls, and deploys when the schedule says to. Shared with the CLI so the button
+// and the cron line cannot drift apart.
+func RunUpdate(ctx context.Context, db *store.Store, j UpdateJob, tool string) (string, error) {
+	if len(j.Spec.Files) == 0 {
+		return "", errors.New("this schedule has no compose file recorded — open it in the Docker tab and save it again")
+	}
+	if j.Spec.Remote != "" {
+		return "", errors.New("this schedule was made to deploy to another machine over tcp, which this console no longer does — make it again on that machine")
+	}
+	spec := repoint(ctx, db, j.Spec.toSpec(tool))
+	var log strings.Builder
+	run := func(args ...string) error {
+		cmd := compose.Cmd(ctx, spec, args...)
+		out, err := cmd.CombinedOutput()
+		log.Write(out)
+		return err
+	}
+	args := append([]string{"pull"}, j.Services...)
+	if err := run(args...); err != nil {
+		return log.String(), err
+	}
+	if !j.Apply {
+		return log.String(), nil
+	}
+	up := append([]string{"up", "-d"}, j.Services...)
+	if err := run(up...); err != nil {
+		return log.String(), err
+	}
+	return log.String(), nil
+}
+
+// ---- endpoints ----
+
+func (s *Server) dsList(w http.ResponseWriter, _ *http.Request) {
+	d := s.dsLoad()
+	now := time.Now()
+	out := make([]map[string]any, 0, len(d.Jobs))
+	for _, j := range d.Jobs {
+		m := map[string]any{"job": j, "last": storage.ReadRun(s.cfg.DataDir(), "docker-"+j.ID)}
+		if j.Enabled {
+			if n, ok := cron.NextRun(strings.Join(strings.Fields(j.Cron), " "), now); ok {
+				m["next"] = n
+			}
+		}
+		out = append(out, m)
+	}
+	jsonOK(w, 200, map[string]any{"jobs": out, "file": dockerCronFile})
+}
+
+func (s *Server) dsPut(w http.ResponseWriter, r *http.Request) {
+	var j UpdateJob
+	if err := json.NewDecoder(io.LimitReader(r.Body, 32<<10)).Decode(&j); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	j.Cron = strings.Join(strings.Fields(j.Cron), " ")
+	if err := cron.ValidSchedule(j.Cron); err != nil {
+		jsonErr(w, 400, "schedule: "+err.Error())
+		return
+	}
+	if strings.TrimSpace(j.Stack) == "" {
+		jsonErr(w, 400, "which stack?")
+		return
+	}
+	// resolve the stack now, so the cron job never has to
+	ctx, cancel := context.WithTimeout(r.Context(), 60*time.Second)
+	defer cancel()
+	stacks, err := s.findStacks(ctx)
+	if err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	found := false
+	for _, st := range stacks {
+		if st.Name == j.Stack {
+			// seenFiles is the list as compose itself sees it: host paths normally, the
+			// orchestrator container's own paths when compose runs inside one. Getting this
+			// backwards gives a cron line that works from the console and fails at 3am.
+			j.Spec = composeSpec{Project: st.Name, Files: seenFiles(st, -1, ""), Via: st.Via}
+			if len(j.Spec.Files) == 0 {
+				jsonErr(w, 409, "that stack's compose file isn't anywhere this console can reach")
+				return
+			}
+			found = true
+		}
+	}
+	if !found {
+		jsonErr(w, 404, "no stack called "+j.Stack+" on this machine")
+		return
+	}
+	if strings.TrimSpace(j.Name) == "" {
+		j.Name = j.Stack
+	}
+	d := s.dsLoad()
+	replaced := false
+	for i := range d.Jobs {
+		if d.Jobs[i].ID == j.ID && j.ID != "" {
+			d.Jobs[i] = j
+			replaced = true
+		}
+	}
+	if !replaced {
+		b := make([]byte, 6)
+		if _, err := rand.Read(b); err != nil {
+			jsonErr(w, 500, err.Error())
+			return
+		}
+		j.ID = hex.EncodeToString(b)
+		d.Jobs = append(d.Jobs, j)
+	}
+	if err := s.dsSave(d); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	if err := s.dsSyncCron(r.Context(), d); err != nil {
+		jsonErr(w, 500, "saved, but writing "+dockerCronFile+" failed: "+err.Error())
+		return
+	}
+	log.Printf("docker schedule %q saved by %s (%s, %q, %s)", j.Name, clientIP(r), j.Stack, j.Cron, map[bool]string{true: "pull and deploy", false: "pull only"}[j.Apply])
+	jsonOK(w, 200, j)
+}
+
+func (s *Server) dsDelete(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	d := s.dsLoad()
+	kept := d.Jobs[:0]
+	found := false
+	for _, j := range d.Jobs {
+		if j.ID == id {
+			found = true
+			continue
+		}
+		kept = append(kept, j)
+	}
+	if !found {
+		jsonErr(w, 404, "no such schedule")
+		return
+	}
+	d.Jobs = kept
+	if err := s.dsSave(d); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	if err := s.dsSyncCron(r.Context(), d); err != nil {
+		jsonErr(w, 500, "removed, but writing "+dockerCronFile+" failed: "+err.Error())
+		return
+	}
+	storage.ForgetRun(s.cfg.DataDir(), "docker-"+id)
+	log.Printf("docker schedule %s removed by %s", id, clientIP(r))
+	w.WriteHeader(204)
+}
+
+func (s *Server) dsRun(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	var job UpdateJob
+	found := false
+	for _, j := range s.dsLoad().Jobs {
+		if j.ID == id {
+			job, found = j, true
+		}
+	}
+	if !found {
+		jsonErr(w, 404, "no such schedule")
+		return
+	}
+	// Outliving the request: a pull the browser gave up on still finishes, but not forever.
+	ctx, cancel := context.WithTimeout(context.WithoutCancel(r.Context()), 30*time.Minute)
+	defer cancel()
+	out, err := RunUpdate(ctx, s.store, job, dockerTool())
+	rec := storage.RunRecord{At: time.Now(), Taken: job.Stack}
+	if err != nil {
+		rec.Error = err.Error()
+	}
+	_ = storage.WriteRun(s.cfg.DataDir(), "docker-"+id, rec)
+	if err != nil {
+		jsonErr(w, 500, err.Error()+"\n"+tail(out, 2000))
+		return
+	}
+	log.Printf("docker schedule %q run by %s", job.Name, clientIP(r))
+	jsonOK(w, 200, map[string]string{"output": tail(out, 4000)})
+}
+
+func tail(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return "…" + s[len(s)-n:]
+}

internal/api/files_test.go

@@ -0,0 +1,123 @@
+package api
+
+import (
+	"bytes"
+	"errors"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"hamlab/internal/files"
+)
+
+// A file read answers Range requests — what a <video> needs to seek — and HEAD, through
+// the same handler that streams everything else.
+func TestFilesReadRanges(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "clip.mp4")
+	data := make([]byte, 10000)
+	for i := range data {
+		data[i] = byte(i % 251)
+	}
+	if err := os.WriteFile(p, data, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	s := &Server{fsLocal: files.Local{}}
+	get := func(method, extra string, hdr map[string]string) *httptest.ResponseRecorder {
+		r := httptest.NewRequest(method, "/api/files/read?path="+url.QueryEscape(p)+extra, nil)
+		for k, v := range hdr {
+			r.Header.Set(k, v)
+		}
+		w := httptest.NewRecorder()
+		s.filesRead(w, r)
+		return w
+	}
+	w := get("GET", "", nil)
+	if w.Code != 200 || w.Body.Len() != 10000 || w.Header().Get("Content-Type") != "video/mp4" || w.Header().Get("Accept-Ranges") != "bytes" {
+		t.Fatalf("whole: %d %d %q %q", w.Code, w.Body.Len(), w.Header().Get("Content-Type"), w.Header().Get("Accept-Ranges"))
+	}
+	w = get("GET", "", map[string]string{"Range": "bytes=100-199"})
+	if w.Code != 206 || w.Header().Get("Content-Range") != "bytes 100-199/10000" || w.Body.Len() != 100 || w.Body.Bytes()[0] != data[100] {
+		t.Fatalf("range: %d %q %d", w.Code, w.Header().Get("Content-Range"), w.Body.Len())
+	}
+	w = get("GET", "", map[string]string{"Range": "bytes=9990-"})
+	if w.Code != 206 || w.Body.Len() != 10 || w.Body.Bytes()[9] != data[9999] {
+		t.Fatalf("tail range: %d %d", w.Code, w.Body.Len())
+	}
+	w = get("HEAD", "", nil)
+	if w.Code != 200 || w.Body.Len() != 0 || w.Header().Get("Content-Length") != "10000" {
+		t.Fatalf("head: %d %d %q", w.Code, w.Body.Len(), w.Header().Get("Content-Length"))
+	}
+	if w := get("GET", "&max=50", nil); w.Code != 413 {
+		t.Fatalf("the editor's cap: %d", w.Code)
+	}
+	if w := get("GET", "", map[string]string{"Range": "bytes=20000-"}); w.Code != 416 {
+		t.Fatalf("a range past the end: %d", w.Code)
+	}
+	if err := os.Chmod(p, 0); err == nil && os.Geteuid() != 0 {
+		if w := get("GET", "", nil); w.Code != 403 {
+			t.Fatalf("unreadable: %d", w.Code)
+		}
+	}
+}
+
+// A write over the cap is refused whole: the file is not truncated first.
+func TestFilesWriteCap(t *testing.T) {
+	p := filepath.Join(t.TempDir(), "f.txt")
+	if err := os.WriteFile(p, []byte("keep me"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	s := &Server{fsLocal: files.Local{}}
+	body := make([]byte, 8<<20+1)
+	r := httptest.NewRequest("PUT", "/api/files/write?path="+url.QueryEscape(p), bytes.NewReader(body))
+	w := httptest.NewRecorder()
+	s.filesWrite(w, r)
+	if w.Code != 413 {
+		t.Fatalf("got %d", w.Code)
+	}
+	if b, _ := os.ReadFile(p); string(b) != "keep me" {
+		t.Fatalf("the file was touched: %q", b)
+	}
+	r = httptest.NewRequest("PUT", "/api/files/write?path="+url.QueryEscape(p), bytes.NewReader([]byte("new")))
+	w = httptest.NewRecorder()
+	s.filesWrite(w, r)
+	if b, _ := os.ReadFile(p); w.Code != 204 || string(b) != "new" {
+		t.Fatalf("a write within the cap: %d %q", w.Code, b)
+	}
+}
+
+// A link to nothing is a 404, not an empty 200.
+func TestFilesReadDanglingLink(t *testing.T) {
+	dir := t.TempDir()
+	l := filepath.Join(dir, "broken")
+	if err := os.Symlink("nowhere", l); err != nil {
+		t.Fatal(err)
+	}
+	s := &Server{fsLocal: files.Local{}}
+	r := httptest.NewRequest("GET", "/api/files/read?path="+url.QueryEscape(l), nil)
+	w := httptest.NewRecorder()
+	s.filesRead(w, r)
+	if w.Code != 404 {
+		t.Fatalf("got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+// dockerErr tells a thing that isn't there from a daemon that isn't up from anything else.
+func TestDockerErr(t *testing.T) {
+	for _, c := range []struct {
+		msg  string
+		want int
+	}{
+		{"error: No such object: zzz", 404}, {"Error response from daemon: No such container: x", 404},
+		{"Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?", 503},
+		{"something else entirely", 500},
+	} {
+		w := httptest.NewRecorder()
+		dockerErr(w, errors.New(c.msg))
+		if w.Code != c.want {
+			t.Errorf("%q → %d, want %d", c.msg, w.Code, c.want)
+		}
+	}
+}

internal/api/guests.go

@@ -0,0 +1,193 @@
+package api
+
+// Guest logins: a temporary account for handing to somebody you want to show around. It is
+// an ordinary account with a clock on it — every tab, every action, on this machine and on
+// every machine this hub manages — that stops working at its expiry (half an hour by
+// default) or the moment it is revoked.
+//
+// Deliberately not a reduced account: Mitchell, 2026-09-27, replacing a read-only version
+// built the same day. He gives these to people he trusts and revokes them otherwise, and a
+// console with half its buttons missing is not the console he wanted to show off. What that
+// means in practice: a guest has the Terminal tab, which is a shell as the user the daemon
+// runs as — root on every host here — and can make an account or a token of its own that
+// outlives the guest login.
+
+import (
+	"encoding/json"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+	"time"
+
+	"hamlab/internal/auth"
+	"hamlab/internal/config"
+	"hamlab/internal/store"
+)
+
+const (
+	guestPrefix     = "guest-"
+	guestTTLDefault = 30 * time.Minute
+	guestTTLMax     = 24 * time.Hour
+	guestReapEvery  = time.Minute
+)
+
+// ---- the accounts themselves ----
+
+func (s *Server) listGuests(w http.ResponseWriter, r *http.Request) {
+	now := time.Now()
+	counts := s.sessions.Count()
+	out := []map[string]any{}
+	s.cfg.View(func(c *config.Config) {
+		for _, u := range c.Users {
+			if !u.Guest || u.Expired(now) {
+				continue
+			}
+			out = append(out, map[string]any{
+				"name": u.Name, "created": u.Created, "expires": u.Expires,
+				"issued_by": u.IssuedBy, "sessions": counts[u.Name], "used": !u.LastSeen.IsZero(),
+			})
+		}
+	})
+	jsonOK(w, 200, out)
+}
+
+// addGuest makes a guest login and hands back its password — the only time it is ever
+// readable, here as everywhere else a password is generated.
+func (s *Server) addGuest(w http.ResponseWriter, r *http.Request) {
+	me := actorOf(r)
+	var body struct {
+		Minutes int `json:"minutes"`
+	}
+	_ = json.NewDecoder(io.LimitReader(r.Body, 4096)).Decode(&body)
+	ttl := guestTTLDefault
+	if body.Minutes > 0 {
+		ttl = time.Duration(body.Minutes) * time.Minute
+	}
+	if ttl > guestTTLMax {
+		jsonErr(w, 400, "a guest login lasts at most 24 hours")
+		return
+	}
+	pw, err := auth.GuestPassword()
+	if err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	hash, err := auth.HashPassword(pw)
+	if err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	var name string
+	for try := 0; try < 8 && name == ""; try++ {
+		suffix, err := auth.GuestSuffix()
+		if err != nil {
+			jsonErr(w, 500, err.Error())
+			return
+		}
+		candidate := guestPrefix + suffix
+		s.cfg.View(func(c *config.Config) {
+			if _, taken := c.User(candidate); !taken {
+				name = candidate
+			}
+		})
+	}
+	if name == "" {
+		jsonErr(w, 500, "could not find a free guest name")
+		return
+	}
+	now := time.Now()
+	expires := now.Add(ttl)
+	if err := s.cfg.Update(func(c *config.Config) {
+		c.Users = append(c.Users, config.User{Name: name, Hash: hash, Created: now, Guest: true, Expires: expires, IssuedBy: me.User})
+	}); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	log.Printf("guest login %q issued until %s (by %s)", name, expires.Format(time.RFC3339), clientIP(r))
+	jsonOK(w, 200, map[string]any{"name": name, "password": pw, "expires": expires, "minutes": int(ttl.Minutes())})
+}
+
+// revokeGuest ends a guest login now. No password: it only ever takes access away, and the
+// whole point of the thing is that ending it is one tap.
+func (s *Server) revokeGuest(w http.ResponseWriter, r *http.Request) {
+	name := r.PathValue("name")
+	found := false
+	if err := s.cfg.Update(func(c *config.Config) {
+		kept := c.Users[:0]
+		for _, u := range c.Users {
+			if u.Name == name && u.Guest {
+				found = true
+				continue
+			}
+			kept = append(kept, u)
+		}
+		c.Users = kept
+	}); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	if !found {
+		jsonErr(w, 404, "no such guest login")
+		return
+	}
+	s.forgetGuest(name)
+	log.Printf("guest login %q revoked (by %s)", name, clientIP(r))
+	w.WriteHeader(204)
+}
+
+// forgetGuest signs a guest out everywhere and drops the look they left behind.
+func (s *Server) forgetGuest(name string) {
+	s.sessions.RevokeUser(name)
+	_ = s.store.Update(func(st *store.State) { delete(st.Users, name) })
+}
+
+// watchGuests clears out guest logins whose time is up. Expiry is enforced on every request
+// as well — this is what keeps the config file from collecting them, and what signs a guest
+// out of a console they left open rather than waiting for their next click.
+func (s *Server) watchGuests() {
+	for {
+		s.reapGuests()
+		time.Sleep(guestReapEvery)
+	}
+}
+
+func (s *Server) reapGuests() {
+	now := time.Now()
+	var gone []string
+	var have bool
+	s.cfg.View(func(c *config.Config) {
+		for _, u := range c.Users {
+			if u.Guest {
+				have = true
+				if u.Expired(now) {
+					gone = append(gone, u.Name)
+				}
+			}
+		}
+	})
+	if !have || len(gone) == 0 {
+		return
+	}
+	expired := map[string]bool{}
+	for _, n := range gone {
+		expired[n] = true
+	}
+	if err := s.cfg.Update(func(c *config.Config) {
+		kept := c.Users[:0]
+		for _, u := range c.Users {
+			if expired[u.Name] {
+				continue
+			}
+			kept = append(kept, u)
+		}
+		c.Users = kept
+	}); err != nil {
+		log.Printf("guests: %v", err)
+		return
+	}
+	for _, n := range gone {
+		s.forgetGuest(n)
+	}
+	log.Printf("guest login(s) expired: %s", strings.Join(gone, ", "))
+}

internal/api/guests_test.go

@@ -0,0 +1,70 @@
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"hamlab/internal/auth"
+	"hamlab/internal/config"
+	"hamlab/internal/store"
+)
+
+// A guest login is an ordinary account with a clock on it, so the clock is the thing worth
+// testing: one whose time is up is stopped at the door, whether or not the minute-by-minute
+// sweep has reached their account yet, and their session is dropped on the way — so the
+// console they left open goes back to the login form rather than carrying on.
+func TestExpiredGuestIsRefusedAndSignedOut(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		expires time.Time
+		wantOK  bool
+	}{
+		{"still has time", time.Now().Add(10 * time.Minute), true},
+		{"time is up", time.Now().Add(-time.Second), false},
+		{"no expiry at all", time.Time{}, false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			dir := t.TempDir()
+			cfg := config.Default(filepath.Join(dir, "config.json"))
+			if err := cfg.Update(func(c *config.Config) {
+				c.Users = []config.User{{Name: "guest-abcd", Hash: "x", Guest: true, Expires: tc.expires}}
+			}); err != nil {
+				t.Fatal(err)
+			}
+			st, err := store.Open(filepath.Join(dir, "state.json"))
+			if err != nil {
+				t.Fatal(err)
+			}
+			s := &Server{cfg: cfg, store: st, sessions: auth.NewSessions(st)}
+			tok, err := s.sessions.Create("guest-abcd", "10.0.0.5", "curl")
+			if err != nil {
+				t.Fatal(err)
+			}
+			r := httptest.NewRequest("GET", "/api/me", nil)
+			r.AddCookie(&http.Cookie{Name: cookieName, Value: tok})
+			w := httptest.NewRecorder()
+			a, ok, answered := s.cookieActor(w, r)
+			if ok != tc.wantOK {
+				t.Fatalf("ok = %v, want %v", ok, tc.wantOK)
+			}
+			if tc.wantOK {
+				if !a.Guest || a.User != "guest-abcd" {
+					t.Errorf("actor = %+v, want the guest account marked as one", a)
+				}
+				if answered {
+					t.Error("answered the caller for a guest that still has time")
+				}
+				return
+			}
+			if !answered || w.Code != 401 {
+				t.Errorf("answered = %v, code = %d, want true and 401", answered, w.Code)
+			}
+			if _, live := s.sessions.Lookup(tok, "10.0.0.5"); live {
+				t.Error("the session of an expired guest is still live")
+			}
+		})
+	}
+}

internal/api/hardware.go

@@ -0,0 +1,13 @@
+package api
+
+// The Hardware tab: what the machine is made of. Read once and remembered — none of it
+// changes while the kernel runs — with ?refresh=1 for the one thing that can, a drive
+// plugged in or pulled out.
+
+import (
+	"net/http"
+)
+
+func (s *Server) hardwareReport(w http.ResponseWriter, r *http.Request) {
+	jsonOK(w, 200, s.hardware.Report(r.Context(), r.URL.Query().Get("refresh") == "1"))
+}

internal/api/kvm.go

@@ -0,0 +1,420 @@
+package api
+
+// IP-KVMs: a device's own web page, shown inside Ham Lab.
+//
+// The whole difficulty is that Ham Lab is served over TLS and a KVM usually is not, so a
+// browser refuses to put the device's page in an iframe — mixed content, blocked before
+// anything loads. The fix is to serve the device from Ham Lab's own origin, which also
+// means it inherits Ham Lab's login instead of needing a second one, and makes the iframe
+// same-origin.
+//
+// Proxying an arbitrary web app under a path prefix is the hard part, and nothing here
+// knows anything about any particular device. A device UI asks for its assets by absolute
+// path — "/assets/app.js", "/api/whatever" — which a prefix cannot rewrite away. So the
+// prefix is only the entry point: any request Ham Lab does not serve itself is routed to
+// whichever KVM the asking page belongs to, worked out from the Referer, and from a cookie
+// when there is no Referer (a WebSocket upgrade, say). Ham Lab's own routes always win, so
+// a device can never shadow the console.
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"log"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"strings"
+	"sync"
+	"time"
+
+	"hamlab/internal/config"
+	"hamlab/internal/store"
+)
+
+const kvmPrefix = "/kvm/"
+const kvmCookie = "hamlab_kvm"
+
+type kvmProxies struct {
+	mu sync.Mutex
+	m  map[string]*httputil.ReverseProxy
+}
+
+func (s *Server) kvm(id string) (config.KVM, bool) {
+	var found config.KVM
+	ok := false
+	s.cfg.View(func(c *config.Config) {
+		for _, k := range c.KVMs {
+			if k.ID == id {
+				found, ok = k, true
+			}
+		}
+	})
+	return found, ok
+}
+
+// kvmProxy is the reverse proxy for one device, made once and kept.
+func (s *Server) kvmProxy(k config.KVM) (*httputil.ReverseProxy, error) {
+	s.kvms.mu.Lock()
+	defer s.kvms.mu.Unlock()
+	if s.kvms.m == nil {
+		s.kvms.m = map[string]*httputil.ReverseProxy{}
+	}
+	if p, ok := s.kvms.m[k.ID]; ok {
+		return p, nil
+	}
+	target, err := url.Parse(k.URL)
+	if err != nil || target.Host == "" {
+		return nil, errors.New("this KVM's address is not a URL")
+	}
+	prefix := kvmPrefix + k.ID
+	p := &httputil.ReverseProxy{
+		Director: func(r *http.Request) {
+			r.URL.Scheme, r.URL.Host = target.Scheme, target.Host
+			// Entry through the prefix keeps the path after it; anything else arrived by its
+			// own absolute path and is passed through untouched.
+			if rest, ok := strings.CutPrefix(r.URL.Path, prefix); ok {
+				if rest == "" {
+					rest = "/"
+				}
+				r.URL.Path = rest
+			}
+			r.URL.RawPath = ""
+			r.Host = target.Host
+			// Whether the console itself is on TLS: the response rewriter needs to know, and by
+			// then only the outbound request is in hand.
+			if secure(r) {
+				r.Header.Set(kvmSecureHeader, "1")
+			} else {
+				r.Header.Del(kvmSecureHeader)
+			}
+			// The device gets its own host and none of Ham Lab's session.
+			r.Header.Del("Origin")
+			stripCookie(r, cookieName, kvmCookie)
+			// What is left is the device's own login. A browser that has it teaches the hub; one
+			// that has not is lent what the hub remembers, so the device sees a signed-in client.
+			if own := r.Cookies(); len(own) > 0 {
+				s.rememberKVMCookies(k.ID, own)
+			} else {
+				for name, val := range s.kvmCookies(k.ID) {
+					r.AddCookie(&http.Cookie{Name: name, Value: val})
+				}
+			}
+		},
+		FlushInterval: -1, // a video stream must not be buffered
+		ModifyResponse: func(resp *http.Response) error {
+			// The device's own framing and transport policy would stop it being embedded, or
+			// send a browser off to plain HTTP. Ham Lab is the origin now, and says what it
+			// serves; its own headers are added on the way out.
+			for _, h := range []string{"X-Frame-Options", "Content-Security-Policy", "Content-Security-Policy-Report-Only", "Strict-Transport-Security", "Referrer-Policy"} {
+				resp.Header.Del(h)
+			}
+			// A cookie the device sets by header is kept for Ham Lab's origin — so its Domain
+			// (the device's) goes, Secure follows the console rather than the device, and the
+			// hub remembers it too.
+			if set := resp.Cookies(); len(set) > 0 {
+				https := resp.Request != nil && resp.Request.Header.Get(kvmSecureHeader) == "1"
+				resp.Header.Del("Set-Cookie")
+				for _, c := range set {
+					c.Domain = ""
+					if c.Path == "" {
+						c.Path = "/"
+					}
+					c.Secure = c.Secure && https
+					if v := c.String(); v != "" {
+						resp.Header.Add("Set-Cookie", v)
+					}
+				}
+				s.rememberKVMCookies(k.ID, set)
+			}
+			// A redirect to the device's own root has to come back through the prefix.
+			if loc := resp.Header.Get("Location"); loc != "" {
+				if u, err := url.Parse(loc); err == nil && (u.Host == "" || u.Host == target.Host) && strings.HasPrefix(u.Path, "/") && !strings.HasPrefix(u.Path, prefix) {
+					u.Scheme, u.Host = "", ""
+					u.Path = prefix + u.Path
+					resp.Header.Set("Location", u.String())
+				}
+			}
+			return nil
+		},
+		ErrorHandler: func(w http.ResponseWriter, r *http.Request, err error) {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusBadGateway)
+			_ = json.NewEncoder(w).Encode(map[string]string{"error": k.Name + " unreachable: " + err.Error()})
+		},
+	}
+	s.kvms.m[k.ID] = p
+	return p, nil
+}
+
+// kvmSecureHeader rides on the outbound request to say whether the console was reached
+// over TLS; the device ignores it.
+const kvmSecureHeader = "X-Hamlab-Secure"
+
+// kvmCookies is what the hub remembers of a device's own cookies — its login, in practice.
+func (s *Server) kvmCookies(id string) map[string]string {
+	var out map[string]string
+	s.store.View(func(st *store.State) {
+		if m := st.KVMCookies[id]; len(m) > 0 {
+			out = make(map[string]string, len(m))
+			for k, v := range m {
+				out[k] = v
+			}
+		}
+	})
+	return out
+}
+
+// rememberKVMCookies keeps the cookies a browser (or the device's own Set-Cookie) carries
+// for a KVM, so that a browser without them can be lent them. A cookie emptied or expired
+// by the device is forgotten. Written only when something changed: this runs on every
+// proxied request.
+func (s *Server) rememberKVMCookies(id string, cs []*http.Cookie) {
+	have := s.kvmCookies(id)
+	changed := false
+	for _, c := range cs {
+		if c.Name == "" || c.Name == cookieName || c.Name == kvmCookie {
+			continue
+		}
+		gone := c.Value == "" || c.MaxAge < 0 || (!c.Expires.IsZero() && c.Expires.Before(time.Now()))
+		if gone {
+			if _, ok := have[c.Name]; ok {
+				changed = true
+			}
+			continue
+		}
+		if have[c.Name] != c.Value {
+			changed = true
+		}
+	}
+	if !changed {
+		return
+	}
+	_ = s.store.Update(func(st *store.State) {
+		if st.KVMCookies == nil {
+			st.KVMCookies = map[string]map[string]string{}
+		}
+		m := st.KVMCookies[id]
+		if m == nil {
+			m = map[string]string{}
+		}
+		for _, c := range cs {
+			if c.Name == "" || c.Name == cookieName || c.Name == kvmCookie {
+				continue
+			}
+			if c.Value == "" || c.MaxAge < 0 || (!c.Expires.IsZero() && c.Expires.Before(time.Now())) {
+				delete(m, c.Name)
+			} else {
+				m[c.Name] = c.Value
+			}
+		}
+		if len(m) == 0 {
+			delete(st.KVMCookies, id)
+		} else {
+			st.KVMCookies[id] = m
+		}
+	})
+}
+
+// forgetKVMCookies drops a device's remembered login — when the device is removed.
+func (s *Server) forgetKVMCookies(id string) {
+	_ = s.store.Update(func(st *store.State) { delete(st.KVMCookies, id) })
+}
+
+// lendKVMCookies hands the browser the device cookies the hub remembers and it lacks, as
+// the device's own page would have set them: readable by its scripts, for Ham Lab's whole
+// origin, kept for half a year. The device's SPA checks for its token client-side before it
+// ever asks the server, so lending it only on the wire would still land on the login form.
+func (s *Server) lendKVMCookies(w http.ResponseWriter, r *http.Request, id string) {
+	for name, val := range s.kvmCookies(id) {
+		if _, err := r.Cookie(name); err == nil {
+			continue
+		}
+		http.SetCookie(w, &http.Cookie{Name: name, Value: val, Path: "/", MaxAge: 180 * 24 * 3600, Secure: secure(r), SameSite: http.SameSiteLaxMode})
+	}
+}
+
+// stripCookie removes named cookies from a request, so Ham Lab's session is never handed to
+// a device and the device never sees which KVM the browser is looking at.
+func stripCookie(r *http.Request, names ...string) {
+	cs := r.Cookies()
+	kept := cs[:0]
+	for _, c := range cs {
+		drop := false
+		for _, n := range names {
+			if c.Name == n {
+				drop = true
+			}
+		}
+		if !drop {
+			kept = append(kept, c)
+		}
+	}
+	r.Header.Del("Cookie")
+	for _, c := range kept {
+		r.AddCookie(c)
+	}
+}
+
+func (s *Server) forgetKVMProxy(id string) {
+	s.kvms.mu.Lock()
+	delete(s.kvms.m, id)
+	s.kvms.mu.Unlock()
+}
+
+// serveKVM is the entry point: /kvm/<id>/… . It also drops a cookie naming the device, so
+// that requests the page makes later by absolute path can be traced back to it.
+func (s *Server) serveKVM(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	k, ok := s.kvm(id)
+	if !ok {
+		jsonErr(w, 404, "no such KVM")
+		return
+	}
+	p, err := s.kvmProxy(k)
+	if err != nil {
+		jsonErr(w, 400, err.Error())
+		return
+	}
+	http.SetCookie(w, &http.Cookie{Name: kvmCookie, Value: id, Path: "/", HttpOnly: true, Secure: secure(r), SameSite: http.SameSiteLaxMode})
+	s.lendKVMCookies(w, r, id)
+	p.ServeHTTP(w, r)
+}
+
+// kvmFor works out which device a request belongs to when it arrived by absolute path
+// rather than through the prefix: the Referer names the page that asked, and a cookie
+// covers what has no Referer at all. Nothing device-specific: it never has to know which
+// paths a given KVM uses.
+func (s *Server) kvmFor(r *http.Request) (config.KVM, bool) {
+	if ref := r.Header.Get("Referer"); ref != "" {
+		if u, err := url.Parse(ref); err == nil {
+			if rest, ok := strings.CutPrefix(u.Path, kvmPrefix); ok {
+				if id, _, _ := strings.Cut(rest, "/"); id != "" {
+					if k, ok := s.kvm(id); ok {
+						return k, true
+					}
+				}
+			}
+		}
+		// asked for by a page that is not a KVM: not ours to answer
+		return config.KVM{}, false
+	}
+	if c, err := r.Cookie(kvmCookie); err == nil && c.Value != "" {
+		return s.kvm(c.Value)
+	}
+	return config.KVM{}, false
+}
+
+// kvmFallback answers a request Ham Lab does not serve itself, when it came from inside a
+// KVM's page. It returns false when the request has nothing to do with a KVM, and the
+// caller carries on with its own 404.
+func (s *Server) kvmFallback(w http.ResponseWriter, r *http.Request) bool {
+	k, ok := s.kvmFor(r)
+	if !ok {
+		return false
+	}
+	p, err := s.kvmProxy(k)
+	if err != nil {
+		return false
+	}
+	p.ServeHTTP(w, r)
+	return true
+}
+
+func machineLabel(m string) string {
+	if m == "" {
+		return "this host"
+	}
+	return m
+}
+
+// ---- the list ----
+
+func (s *Server) listKVMs(w http.ResponseWriter, _ *http.Request) {
+	out := []config.KVM{}
+	s.cfg.View(func(c *config.Config) { out = append(out, c.KVMs...) })
+	jsonOK(w, 200, out)
+}
+
+func (s *Server) addKVM(w http.ResponseWriter, r *http.Request) {
+	var body struct{ Name, URL, Machine string }
+	if err := json.NewDecoder(io.LimitReader(r.Body, 4096)).Decode(&body); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	raw := strings.TrimSpace(body.URL)
+	if raw != "" && !strings.Contains(raw, "://") {
+		raw = "http://" + raw // what you would type: an address, not a scheme
+	}
+	u, err := url.Parse(raw)
+	if err != nil || (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
+		jsonErr(w, 400, "address: http(s)://host, or just the host")
+		return
+	}
+	name := strings.TrimSpace(body.Name)
+	if name == "" {
+		name = u.Host
+	}
+	if len(name) > maxNameLen {
+		jsonErr(w, 400, "that name is too long")
+		return
+	}
+	b := make([]byte, 6)
+	if _, err := rand.Read(b); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	machine := strings.TrimSpace(body.Machine)
+	k := config.KVM{ID: hex.EncodeToString(b), Name: name, URL: u.Scheme + "://" + u.Host + strings.TrimSuffix(u.Path, "/"), Machine: machine, Added: time.Now()}
+	// One per machine: a second one for the same host replaces the first rather than sitting
+	// beside it, since the tab shows the machine you are looking at.
+	var replaced string
+	if err := s.cfg.Update(func(c *config.Config) {
+		kept := c.KVMs[:0]
+		for _, old := range c.KVMs {
+			if old.Machine == machine {
+				replaced = old.ID
+				continue
+			}
+			kept = append(kept, old)
+		}
+		c.KVMs = append(kept, k)
+	}); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	if replaced != "" {
+		s.forgetKVMProxy(replaced)
+	}
+	log.Printf("kvm %q added for %s (%s) by %s", k.Name, machineLabel(machine), k.URL, clientIP(r))
+	jsonOK(w, 201, k)
+}
+
+func (s *Server) removeKVM(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	found := false
+	if err := s.cfg.Update(func(c *config.Config) {
+		kept := c.KVMs[:0]
+		for _, k := range c.KVMs {
+			if k.ID == id {
+				found = true
+				continue
+			}
+			kept = append(kept, k)
+		}
+		c.KVMs = kept
+	}); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	if !found {
+		jsonErr(w, 404, "no such KVM")
+		return
+	}
+	s.forgetKVMProxy(id)
+	s.forgetKVMCookies(id)
+	log.Printf("kvm %s removed by %s", id, clientIP(r))
+	w.WriteHeader(204)
+}

internal/api/kvm_test.go

@@ -0,0 +1,123 @@
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"hamlab/internal/auth"
+	"hamlab/internal/config"
+	"hamlab/internal/store"
+)
+
+// A KVM's own login is a cookie its page sets in one browser. The hub remembers it from the
+// requests that carry it, lends it to a browser that lacks it — both on the wire to the
+// device and back to the browser, since the device's page checks for it client-side — and
+// forgets it when the device says it is gone or the KVM is removed.
+func TestKVMCookiesAreRememberedAndLent(t *testing.T) {
+	var seen []string // the Cookie header the fake device received, per request
+	device := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		seen = append(seen, r.Header.Get("Cookie"))
+		if r.URL.Path == "/api/auth/login" {
+			// a device that sets its token by header, with its own domain and Secure
+			http.SetCookie(w, &http.Cookie{Name: "nano-kvm-token", Value: "tok-1", Domain: "10.0.0.217", Secure: true})
+		}
+		if r.URL.Path == "/api/auth/logout" {
+			http.SetCookie(w, &http.Cookie{Name: "nano-kvm-token", Value: "", MaxAge: -1})
+		}
+		w.WriteHeader(200)
+	}))
+	defer device.Close()
+
+	dir := t.TempDir()
+	cfg := config.Default(filepath.Join(dir, "config.json"))
+	if err := cfg.Update(func(c *config.Config) {
+		c.KVMs = []config.KVM{{ID: "abc123", Name: "test", URL: device.URL, Machine: ""}}
+	}); err != nil {
+		t.Fatal(err)
+	}
+	st, err := store.Open(filepath.Join(dir, "state.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := &Server{cfg: cfg, store: st, sessions: auth.NewSessions(st)}
+	k, _ := s.kvm("abc123")
+	p, err := s.kvmProxy(k)
+	if err != nil {
+		t.Fatal(err)
+	}
+	ask := func(path string, cookies ...*http.Cookie) *httptest.ResponseRecorder {
+		r := httptest.NewRequest("GET", path, nil)
+		r.SetPathValue("id", "abc123")
+		for _, c := range cookies {
+			r.AddCookie(c)
+		}
+		w := httptest.NewRecorder()
+		if strings.HasPrefix(path, kvmPrefix) {
+			s.serveKVM(w, r)
+		} else {
+			p.ServeHTTP(w, r)
+		}
+		return w
+	}
+
+	// 1. the device sets its token by header: it reaches the browser without the device's
+	//    domain or Secure (plain-http console), and the hub remembers it
+	w := ask("/api/auth/login", &http.Cookie{Name: cookieName, Value: "hamlab-session"})
+	var set *http.Cookie
+	for _, c := range w.Result().Cookies() {
+		if c.Name == "nano-kvm-token" {
+			set = c
+		}
+	}
+	if set == nil || set.Domain != "" || set.Secure || set.Value != "tok-1" || set.Path != "/" {
+		t.Fatalf("rewritten Set-Cookie = %+v, want nano-kvm-token=tok-1 for / without Domain or Secure", set)
+	}
+	if got := s.kvmCookies("abc123"); got["nano-kvm-token"] != "tok-1" {
+		t.Fatalf("remembered = %v, want the token", got)
+	}
+	if strings.Contains(seen[0], "hamlab_session") {
+		t.Fatalf("the device was handed Ham Lab's session: %q", seen[0])
+	}
+
+	// 2. a browser that has the cookie teaches a newer value
+	ask("/api/vm/info", &http.Cookie{Name: "nano-kvm-token", Value: "tok-2"}, &http.Cookie{Name: cookieName, Value: "x"})
+	if got := s.kvmCookies("abc123"); got["nano-kvm-token"] != "tok-2" {
+		t.Fatalf("remembered = %v, want tok-2", got)
+	}
+	if seen[1] != "nano-kvm-token=tok-2" {
+		t.Fatalf("device saw %q, want the browser's own cookie only", seen[1])
+	}
+
+	// 3. a browser without it is lent it: on the wire, and back as a Set-Cookie it can read
+	w = ask(kvmPrefix+"abc123/", &http.Cookie{Name: cookieName, Value: "x"})
+	if seen[2] != "nano-kvm-token=tok-2" {
+		t.Fatalf("device saw %q from a browser with no cookie, want the remembered token", seen[2])
+	}
+	lent := false
+	for _, c := range w.Result().Cookies() {
+		if c.Name == "nano-kvm-token" && c.Value == "tok-2" && !c.HttpOnly && c.Path == "/" && c.MaxAge > 0 {
+			lent = true
+		}
+	}
+	if !lent {
+		t.Fatalf("browser was not lent the token: %v", w.Result().Cookies())
+	}
+
+	// 4. the device logging out forgets it
+	ask("/api/auth/logout", &http.Cookie{Name: "nano-kvm-token", Value: "tok-2"})
+	if got := s.kvmCookies("abc123"); got != nil {
+		t.Fatalf("after logout remembered = %v, want nothing", got)
+	}
+
+	// 5. removing the KVM clears whatever is left
+	s.rememberKVMCookies("abc123", []*http.Cookie{{Name: "nano-kvm-token", Value: "tok-3"}})
+	s.forgetKVMCookies("abc123")
+	if got := s.kvmCookies("abc123"); got != nil {
+		t.Fatalf("after remove remembered = %v, want nothing", got)
+	}
+	_ = url.Parse
+}

internal/api/network.go

@@ -0,0 +1,123 @@
+package api
+
+// The Network tab: the machine's interfaces, how the internet looks from here, and the speed
+// test. One machine at a time, like every other tab — the test runs on the machine in the
+// switcher, so the number is that machine's line and not the hub's.
+
+import (
+	"encoding/json"
+	"log"
+	"net/http"
+	"time"
+
+	"hamlab/internal/network"
+	"hamlab/internal/sensors"
+	"hamlab/internal/store"
+)
+
+// networkOverview is everything the tab draws at once: the interfaces, the outside view, the
+// last test and the ones before it.
+func (s *Server) networkOverview(w http.ResponseWriter, _ *http.Request) {
+	run := s.net.Test.State()
+	jsonOK(w, 200, map[string]any{
+		"report":  network.Look(s.hostName()),
+		"outside": s.net.Outside(),
+		"run":     run,
+		"history": s.net.Test.History(),
+		"method":  network.Method,
+	})
+}
+
+func (s *Server) speedtestState(w http.ResponseWriter, _ *http.Request) {
+	jsonOK(w, 200, s.net.Test.State())
+}
+
+func (s *Server) speedtestStart(w http.ResponseWriter, r *http.Request) {
+	run, err := s.net.Test.Start()
+	if err != nil {
+		jsonErr(w, 409, err.Error())
+		return
+	}
+	log.Printf("speed test started on %s (by %s)", s.hostName(), clientIP(r))
+	jsonOK(w, 200, run)
+}
+
+func (s *Server) speedtestCancel(w http.ResponseWriter, r *http.Request) {
+	if !s.net.Test.Cancel() {
+		jsonErr(w, 404, "no speed test is running")
+		return
+	}
+	log.Printf("speed test cancelled on %s (by %s)", s.hostName(), clientIP(r))
+	w.WriteHeader(204)
+}
+
+// ---- keeping the results ----
+
+// savedNetwork is what survives a restart: the recent results, so the history is a history
+// rather than whatever has happened since the daemon last started.
+type savedNetwork struct {
+	Results []network.Result `json:"results,omitempty"`
+}
+
+func (s *Server) loadNetwork() []network.Result {
+	var saved savedNetwork
+	var raw json.RawMessage
+	s.store.View(func(st *store.State) { raw = st.Network })
+	if len(raw) > 0 {
+		if err := json.Unmarshal(raw, &saved); err != nil {
+			log.Printf("network: kept results unreadable (%v); starting a fresh history", err)
+		}
+	}
+	return saved.Results
+}
+
+// keepResult is called when a test finishes: append it to what is on disk.
+func (s *Server) keepResult(r network.Result) {
+	if r.Error != "" {
+		log.Printf("speed test on %s failed: %s", s.hostName(), r.Error)
+	} else {
+		log.Printf("speed test on %s: down %s, up %s, latency %.1f ms via %s",
+			s.hostName(), network.Mbits(r.DownMbps), network.Mbits(r.UpMbps), r.LatencyMs, r.Colo)
+	}
+	results := s.net.Test.History()
+	b, err := json.Marshal(savedNetwork{Results: results})
+	if err != nil {
+		return
+	}
+	if err := s.store.Update(func(st *store.State) { st.Network = b }); err != nil {
+		log.Printf("network: %v", err)
+	}
+}
+
+// ---- the speed test as sensors ----
+
+// netSensors publishes the last speed test as ordinary sensors, so the line can be a widget,
+// a graph, an alert or a Prometheus series like anything else Ham Lab measures. Each one's
+// timestamp is when the test ran, which is how a stale reading says so.
+type netSensors struct{ w *network.Watcher }
+
+func (n netSensors) Sensors() []sensors.Sensor {
+	var out []sensors.Sensor
+	if o := n.w.Outside(); o.IP != "" {
+		at := o.At.UnixMilli()
+		out = append(out, sensors.Sensor{ID: "net.internet.ip", Name: "Public address", Kind: "state", Value: o.IP, T: at})
+		if o.Colo != "" {
+			out = append(out, sensors.Sensor{ID: "net.internet.edge", Name: "Internet edge", Kind: "state", Value: o.Colo, T: at})
+		}
+	}
+	run := n.w.Test.State()
+	if run.Result == nil || run.Result.Error != "" {
+		return out
+	}
+	r := run.Result
+	at := r.At.UnixMilli()
+	return append(out,
+		sensors.Sensor{ID: "net.internet.download", Name: "Download", Kind: "rate", Unit: "Mbps", Value: r.DownMbps, T: at, Min: sensors.F(0)},
+		sensors.Sensor{ID: "net.internet.upload", Name: "Upload", Kind: "rate", Unit: "Mbps", Value: r.UpMbps, T: at, Min: sensors.F(0)},
+		sensors.Sensor{ID: "net.internet.latency", Name: "Latency", Kind: "duration", Unit: "ms", Value: r.LatencyMs, T: at, Min: sensors.F(0)},
+		sensors.Sensor{ID: "net.internet.jitter", Name: "Jitter", Kind: "duration", Unit: "ms", Value: r.JitterMs, T: at, Min: sensors.F(0)},
+		sensors.Sensor{ID: "net.internet.tested", Name: "Speed test age", Kind: "duration", Unit: "s", Value: round1(time.Since(r.At).Seconds()), T: at, Min: sensors.F(0)},
+	)
+}
+
+func round1(v float64) float64 { return float64(int64(v*10+0.5)) / 10 }

internal/api/play.go

@@ -0,0 +1,530 @@
+package api
+
+// Playing a video in the Files viewer, YouTube's way: Auto (the player reads the connection),
+// any quality by hand, or the file itself. The qualities are made on the fly as HLS by
+// internal/media, on the device the Transcode device setting names — which may be on another
+// machine than the file.
+//
+// On every machine:
+//   POST /api/files/play[?sudo=1] {path | url, name, device}   open a play
+//   GET  /api/files/play/{id}/master.m3u8, /{rung}.m3u8, /{rung}/{n}.ts
+//   GET  /api/files/play/{id}                                    what it is doing
+//   DELETE /api/files/play/{id} (or POST …/close, for a beacon)  end it
+//   GET  /api/files/play-devices                                 what it can encode on
+// On the hub:
+//   POST /api/play {node, path, sudo}   open a play of a file on node, wherever the setting
+//                                       says, answering which machine the play is on
+//   GET|PUT /api/transcode              the setting, and every machine's devices
+//   GET  /api/play-src/{token}          a file, for a machine transcoding it, by a token
+//                                       that names that one file; ranges pass through
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"net/url"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"hamlab/internal/files"
+	"hamlab/internal/media"
+	"hamlab/internal/store"
+)
+
+// playRuns is how many plays may be encoding at once on one machine; a fourth ends the one
+// asked of least lately. The A380 makes about two 8K-sourced streams in real time.
+const playRuns = 3
+
+type playReq struct {
+	Path   string `json:"path,omitempty"`
+	URL    string `json:"url,omitempty"` // a file on another machine, as the hub serves it
+	Name   string `json:"name,omitempty"`
+	Device string `json:"device,omitempty"`
+}
+
+type playOut struct {
+	Node   string           `json:"node"` // the machine the play is on: "" for the hub; filled in by the hub
+	Play   *media.Play      `json:"play"`
+	Master string           `json:"master"` // the playlist, under that machine's /api
+	Engine string           `json:"engine"`
+	Host   string           `json:"host"` // that machine's name, for the menu
+	Note   string           `json:"note,omitempty"`
+	Status media.PlayStatus `json:"status"`
+}
+
+// playDevices: GET /api/files/play-devices — what this machine could make the player's H.264
+// on, probed as the daemon's own user (a play from another machine never runs as root).
+func (s *Server) playDevices(w http.ResponseWriter, r *http.Request) {
+	caps, err := s.thumbs.capsFor(r.Context(), false, false)
+	if err != nil {
+		caps.Error = err.Error()
+	}
+	jsonOK(w, 200, map[string]any{"host": s.hostName(), "devices": media.Devices(caps)})
+}
+
+// playStart: POST /api/files/play[?sudo=1] — open a play of a file here, or of a URL the hub
+// serves a file on another machine at.
+func (s *Server) playStart(w http.ResponseWriter, r *http.Request) {
+	var body playReq
+	if err := json.NewDecoder(io.LimitReader(r.Body, 64<<10)).Decode(&body); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	root := r.URL.Query().Get("sudo") == "1"
+	if root && s.fsSudo == nil {
+		jsonErr(w, 403, "root access needs passwordless sudo on the host")
+		return
+	}
+	out, code, err := s.openPlay(r.Context(), body, root)
+	if err != nil {
+		jsonErr(w, code, err.Error())
+		return
+	}
+	jsonOK(w, 200, out)
+}
+
+func (s *Server) openPlay(ctx context.Context, body playReq, root bool) (playOut, int, error) {
+	if root && s.fsSudo == nil && body.URL == "" {
+		return playOut{}, 403, errors.New("root access needs passwordless sudo on the host")
+	}
+	in, name := body.Path, body.Name
+	if body.URL != "" {
+		u, err := url.Parse(body.URL)
+		if err != nil || (u.Scheme != "http" && u.Scheme != "https") || body.Path != "" {
+			return playOut{}, 400, errors.New("a play is of a path or of an http URL")
+		}
+		in, root = body.URL, false
+	} else {
+		p, err := files.Clean(body.Path)
+		if err != nil {
+			return playOut{}, 400, err
+		}
+		if media.Kind(p) != "video" {
+			return playOut{}, 415, errors.New("not a video")
+		}
+		fsys := s.fsLocal
+		if root {
+			fsys = s.fsSudo
+		}
+		if _, err := fsys.Stat(ctx, p); err != nil {
+			return playOut{}, 404, err
+		}
+		in = p
+		if name == "" {
+			name = filepath.Base(p)
+		}
+	}
+	caps, err := s.thumbs.capsFor(ctx, root, false)
+	if err == nil && caps.Error != "" {
+		err = errors.New(caps.Error)
+	}
+	if err != nil {
+		return playOut{}, 503, err
+	}
+	ictx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	src, err := media.Inspect(ictx, caps, in, root)
+	cancel()
+	if err != nil {
+		var de *media.DecodeError
+		if errors.As(err, &de) {
+			return playOut{}, 422, errors.New(de.Msg)
+		}
+		return playOut{}, 504, err
+	}
+	p, err := s.plays.Open(caps, root, in, name, src, body.Device)
+	if err != nil {
+		return playOut{}, 422, err
+	}
+	log.Printf("files: play %s on %s (%d qualities, %s)", name, p.Engine(), len(p.Rungs), map[bool]string{true: "from another machine", false: "here"}[p.Remote])
+	return playOut{Play: p, Master: "/api/files/play/" + p.ID + "/master.m3u8", Engine: p.Engine(), Host: s.hostName(), Status: p.Status()}, 200, nil
+}
+
+// playStatus: GET /api/files/play/{id}
+func (s *Server) playStatus(w http.ResponseWriter, r *http.Request) {
+	p, ok := s.plays.Find(r.PathValue("id"))
+	if !ok {
+		jsonErr(w, 404, "no such play")
+		return
+	}
+	jsonOK(w, 200, p.Status())
+}
+
+// playStop: DELETE /api/files/play/{id}, or POST …/close — the form a page can send on its
+// way out (navigator.sendBeacon), so a phone closing the tab releases the machine at once.
+func (s *Server) playStop(w http.ResponseWriter, r *http.Request) {
+	s.plays.Close(r.PathValue("id"))
+	w.WriteHeader(204)
+}
+
+// playPlaylist: GET /api/files/play/{id}/{file} — master.m3u8, or one quality's <name>.m3u8.
+func (s *Server) playPlaylist(w http.ResponseWriter, r *http.Request) {
+	p, ok := s.plays.Find(r.PathValue("id"))
+	if !ok {
+		jsonErr(w, 404, "no such play")
+		return
+	}
+	f := r.PathValue("file")
+	var b []byte
+	if f == "master.m3u8" {
+		b = p.Master()
+	} else if name, isList := strings.CutSuffix(f, ".m3u8"); isList {
+		if b, ok = p.Media(name); !ok {
+			jsonErr(w, 404, "no such quality")
+			return
+		}
+	} else {
+		jsonErr(w, 404, "not a play file")
+		return
+	}
+	w.Header().Set("Content-Type", "application/vnd.apple.mpegurl")
+	w.Header().Set("Cache-Control", "no-store")
+	_, _ = w.Write(b)
+}
+
+// playPiece: GET /api/files/play/{id}/{rung}/{seg} — a piece, made first if need be.
+func (s *Server) playPiece(w http.ResponseWriter, r *http.Request) {
+	p, ok := s.plays.Find(r.PathValue("id"))
+	if !ok {
+		jsonErr(w, 404, "no such play")
+		return
+	}
+	ns, isTS := strings.CutSuffix(r.PathValue("seg"), ".ts")
+	n, err := strconv.Atoi(ns)
+	if !isTS || err != nil || strconv.Itoa(n) != ns {
+		jsonErr(w, 404, "not a piece")
+		return
+	}
+	file, err := p.Segment(r.Context().Done(), r.PathValue("rung"), n)
+	switch {
+	case errors.Is(err, media.ErrNotFound):
+		jsonErr(w, 404, err.Error())
+		return
+	case r.Context().Err() != nil:
+		return // the player moved on
+	case err != nil:
+		jsonErr(w, 503, err.Error())
+		return
+	}
+	w.Header().Set("Content-Type", "video/mp2t")
+	w.Header().Set("Cache-Control", "private, max-age=3600")
+	http.ServeFile(w, r, file)
+}
+
+// ---- on the hub: where plays are made ----
+
+// transcodeChoice is the setting; nil is the machine the file is on.
+func (s *Server) transcodeChoice() *store.Transcode {
+	var t *store.Transcode
+	s.store.View(func(st *store.State) {
+		if st.Transcode != nil {
+			c := *st.Transcode
+			t = &c
+		}
+	})
+	return t
+}
+
+type transcodeMachine struct {
+	Node    string         `json:"node"` // "" is the hub
+	Host    string         `json:"host"`
+	Devices []media.Device `json:"devices"`
+	Error   string         `json:"error,omitempty"` // the machine didn't answer
+}
+
+// getTranscode: GET /api/transcode — the setting, and what every machine can encode on,
+// asked of each now.
+func (s *Server) getTranscode(w http.ResponseWriter, r *http.Request) {
+	names := []string{""}
+	if s.nodes != nil {
+		names = append(names, s.nodes.Names()...)
+	}
+	out := make([]transcodeMachine, len(names))
+	var wg sync.WaitGroup
+	for i, n := range names {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			m := transcodeMachine{Node: n, Host: n}
+			ctx, cancel := context.WithTimeout(r.Context(), 8*time.Second)
+			defer cancel()
+			if n == "" {
+				caps, err := s.thumbs.capsFor(ctx, false, false)
+				if err != nil {
+					caps.Error = err.Error()
+				}
+				m.Host, m.Devices = s.hostName(), media.Devices(caps)
+			} else {
+				code, b, err := s.nodes.Do(ctx, n, "GET", "/api/files/play-devices", nil, nil)
+				var d struct {
+					Host    string         `json:"host"`
+					Devices []media.Device `json:"devices"`
+				}
+				switch {
+				case err != nil:
+					m.Error = err.Error()
+				case code == 404:
+					m.Error = "runs an older Ham Lab"
+				case code != 200 || json.Unmarshal(b, &d) != nil:
+					m.Error = fmt.Sprintf("answered %d", code)
+				default:
+					m.Devices = d.Devices
+				}
+			}
+			out[i] = m
+		}()
+	}
+	wg.Wait()
+	jsonOK(w, 200, map[string]any{"selected": s.transcodeChoice(), "machines": out})
+}
+
+// putTranscode: PUT /api/transcode {node, device}, or {} for the machine the file is on.
+func (s *Server) putTranscode(w http.ResponseWriter, r *http.Request) {
+	var body *store.Transcode
+	if err := json.NewDecoder(io.LimitReader(r.Body, 4096)).Decode(&body); err != nil {
+		jsonErr(w, 400, "expected {\"node\": …, \"device\": …}")
+		return
+	}
+	if body != nil && body.Device == "" {
+		body = nil
+	}
+	if body != nil {
+		known := body.Node == ""
+		if s.nodes != nil {
+			for _, n := range s.nodes.Names() {
+				known = known || n == body.Node
+			}
+		}
+		if !known {
+			jsonErr(w, 400, "no such machine")
+			return
+		}
+		if body.Device != media.CPU && !strings.HasPrefix(body.Device, "/dev/dri/") {
+			jsonErr(w, 400, "a device is a render node or \"cpu\"")
+			return
+		}
+	}
+	if err := s.store.Update(func(st *store.State) { st.Transcode = body }); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	s.getTranscode(w, r)
+}
+
+// hubPlay: POST /api/play {node, path, sudo} — open a play of a file on node ("" the hub) on
+// the device the setting names. When that is on another machine, that machine reads the file
+// through this hub, by a token good for that one file. If it can't be reached, the file's own
+// machine makes it instead, and the answer says so.
+func (s *Server) hubPlay(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		Node string `json:"node"`
+		Path string `json:"path"`
+		Sudo bool   `json:"sudo"`
+	}
+	if err := json.NewDecoder(io.LimitReader(r.Body, 64<<10)).Decode(&body); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	p, err := files.Clean(body.Path)
+	if err != nil {
+		jsonErr(w, 400, err.Error())
+		return
+	}
+	if body.Node != "" && (s.nodes == nil || !has(s.nodes.Names(), body.Node)) {
+		jsonErr(w, 404, "no such machine")
+		return
+	}
+	choice := s.transcodeChoice()
+	var note string
+	if choice != nil && choice.Node != body.Node {
+		if s.nodes != nil && choice.Node != "" && !has(s.nodes.Names(), choice.Node) {
+			note = "The transcode machine " + choice.Node + " is no longer managed here; made where the file is."
+		} else {
+			src, err := s.srcURL(choice.Node, body.Node, p, body.Sudo)
+			if err == nil {
+				req := playReq{URL: src, Name: filepath.Base(p), Device: choice.Device}
+				out, code, err := s.playOn(r.Context(), choice.Node, req, false)
+				if err == nil {
+					jsonOK(w, 200, out)
+					return
+				}
+				if code == 422 || code == 415 {
+					jsonErr(w, code, err.Error())
+					return
+				}
+			}
+			log.Printf("files: play on %s failed (%v); making it where the file is", nodeLabel(choice.Node), err)
+			note = "Couldn't make it on " + nodeLabel(choice.Node) + " (" + err.Error() + "), so it is made where the file is."
+		}
+	}
+	device := ""
+	if choice != nil && choice.Node == body.Node {
+		device = choice.Device
+	}
+	out, code, err := s.playOn(r.Context(), body.Node, playReq{Path: p, Device: device}, body.Sudo)
+	if err != nil {
+		jsonErr(w, code, err.Error())
+		return
+	}
+	out.Note = note
+	jsonOK(w, 200, out)
+}
+
+func nodeLabel(n string) string {
+	if n == "" {
+		return "the hub"
+	}
+	return n
+}
+
+func has(list []string, x string) bool {
+	for _, v := range list {
+		if v == x {
+			return true
+		}
+	}
+	return false
+}
+
+// playOn opens a play on a machine: here, or through that node's API.
+func (s *Server) playOn(ctx context.Context, node string, req playReq, sudo bool) (playOut, int, error) {
+	if node == "" {
+		out, code, err := s.openPlay(ctx, req, sudo)
+		return out, code, err
+	}
+	b, _ := json.Marshal(req)
+	path := "/api/files/play"
+	if sudo {
+		path += "?sudo=1"
+	}
+	code, resp, err := s.nodes.Do(ctx, node, "POST", path, b, http.Header{"Content-Type": []string{"application/json"}})
+	if err != nil {
+		return playOut{}, 502, err
+	}
+	if code != 200 {
+		var e struct{ Error string }
+		_ = json.Unmarshal(resp, &e)
+		if e.Error == "" {
+			e.Error = fmt.Sprintf("%s answered %d", node, code)
+		}
+		return playOut{}, code, errors.New(e.Error)
+	}
+	var out playOut
+	if err := json.Unmarshal(resp, &out); err != nil {
+		return playOut{}, 502, err
+	}
+	out.Node = node
+	return out, 200, nil
+}
+
+// ---- the file, for the machine transcoding it ----
+
+type srcGrant struct {
+	node, path string
+	sudo       bool
+	until      time.Time
+}
+
+type srcGrants struct {
+	mu sync.Mutex
+	m  map[string]*srcGrant
+}
+
+const srcLife = 12 * time.Hour // from its last use: a film paused overnight still plays
+
+var grants = &srcGrants{m: map[string]*srcGrant{}}
+
+func (g *srcGrants) mint(node, path string, sudo bool) string {
+	b := make([]byte, 24)
+	_, _ = rand.Read(b)
+	tok := hex.EncodeToString(b)
+	now := time.Now()
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	for k, v := range g.m {
+		if now.After(v.until) {
+			delete(g.m, k)
+		}
+	}
+	g.m[tok] = &srcGrant{node: node, path: path, sudo: sudo, until: now.Add(srcLife)}
+	return tok
+}
+
+func (g *srcGrants) use(tok string) (srcGrant, bool) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	v, ok := g.m[tok]
+	if !ok || time.Now().After(v.until) {
+		return srcGrant{}, false
+	}
+	v.until = time.Now().Add(srcLife)
+	return *v, true
+}
+
+// srcURL is where the machine `to` can read a file on machine `from` through this hub: this
+// hub's own address as `to` reaches it, and a token for that one file.
+func (s *Server) srcURL(to, from, path string, sudo bool) (string, error) {
+	host, port, err := net.SplitHostPort(s.cfg.Listen)
+	if err != nil {
+		return "", err
+	}
+	ip := net.ParseIP(host)
+	if host == "" || ip == nil || ip.IsUnspecified() || ip.IsLoopback() {
+		// Listening everywhere: the address this machine reaches `to` from is one it answers on.
+		target := "127.0.0.1:1"
+		if to != "" {
+			if u, err := url.Parse(s.nodes.URL(to)); err == nil && u.Host != "" {
+				target = u.Host
+			}
+		}
+		c, err := net.Dial("udp", target)
+		if err != nil {
+			return "", err
+		}
+		host = c.LocalAddr().(*net.UDPAddr).IP.String()
+		c.Close()
+	}
+	scheme := "http"
+	if s.fingerprint != "" {
+		scheme = "https"
+	}
+	return scheme + "://" + net.JoinHostPort(host, port) + "/api/play-src/" + grants.mint(from, path, sudo), nil
+}
+
+// playSrc: GET /api/play-src/{token} — the one file a token names, ranges and all, read from
+// its machine. The token is the only key: it is minted for a machine transcoding that file.
+func (s *Server) playSrc(w http.ResponseWriter, r *http.Request) {
+	g, ok := grants.use(r.PathValue("token"))
+	if !ok {
+		jsonErr(w, 404, "no such file")
+		return
+	}
+	q := url.Values{"path": {g.path}}
+	if g.sudo {
+		q.Set("sudo", "1")
+	}
+	r2 := r.Clone(r.Context())
+	r2.URL.RawQuery = q.Encode()
+	r2.Header.Del("Cookie")
+	if g.node == "" {
+		r2.URL.Path = "/api/files/read"
+		s.filesRead(w, r2)
+		return
+	}
+	p, ok := s.nodes.Proxy(g.node)
+	if !ok {
+		jsonErr(w, 404, "no such machine")
+		return
+	}
+	r2.URL.Path = "/api/nodes/" + g.node + "/files/read"
+	p.ServeHTTP(w, r2)
+}

internal/api/play_test.go

@@ -0,0 +1,51 @@
+package api
+
+import (
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"hamlab/internal/config"
+	"hamlab/internal/files"
+)
+
+// The file a machine transcodes from another is read through the hub by a token naming that
+// one file: ranges pass through, the query can't point it anywhere else, and an unknown token
+// is nothing.
+func TestPlaySrc(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "film.mp4")
+	if err := os.WriteFile(p, []byte("0123456789"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "other.mp4"), []byte("secret"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	s := &Server{fsLocal: files.Local{}, cfg: &config.Config{Listen: "10.0.0.234:8100"}}
+	u, err := s.srcURL("", "", p, false)
+	if err != nil || !strings.HasPrefix(u, "http://10.0.0.234:8100/api/play-src/") {
+		t.Fatalf("url %q %v", u, err)
+	}
+	tok := strings.TrimPrefix(u, "http://10.0.0.234:8100/api/play-src/")
+	get := func(tok, query, rng string) *httptest.ResponseRecorder {
+		r := httptest.NewRequest("GET", "/api/play-src/"+tok+query, nil)
+		r.SetPathValue("token", tok)
+		if rng != "" {
+			r.Header.Set("Range", rng)
+		}
+		w := httptest.NewRecorder()
+		s.playSrc(w, r)
+		return w
+	}
+	if w := get(tok, "", "bytes=2-4"); w.Code != 206 || w.Body.String() != "234" {
+		t.Fatalf("range: %d %q", w.Code, w.Body)
+	}
+	if w := get(tok, "?path="+filepath.Join(dir, "other.mp4"), ""); w.Body.String() != "0123456789" {
+		t.Fatalf("the query moved it: %q", w.Body)
+	}
+	if w := get("nope", "", ""); w.Code != 404 {
+		t.Fatalf("unknown token: %d", w.Code)
+	}
+}

internal/api/server.go

@@ -33,7 +33,10 @@ import (
 	"hamlab/internal/config"
 	"hamlab/internal/cron"
 	"hamlab/internal/files"
+	"hamlab/internal/hardware"
+	"hamlab/internal/media"
 	"hamlab/internal/metrics"
+	"hamlab/internal/network"
 	"hamlab/internal/nodes"
 	"hamlab/internal/priv"
 	"hamlab/internal/sensors"
@@ -67,10 +70,17 @@ type Server struct {
 	tasks       *tasks.Manager
 	updates     *updates.Manager
 	storage     *storage.Manager
+	hardware    *hardware.Manager
 	space       *space.Manager
+	net         *network.Watcher
 	update      updateState
+	events      eventLog
+	kvms        kvmProxies
 	fsLocal     files.FS
 	fsSudo      files.FS // nil without passwordless sudo
+	thumbs      *thumbSvc
+	plays       *media.Plays
+	self        string // this binary, for helpers run as tasks
 	nodes       *nodes.Manager
 	fingerprint string
 	version     string
@@ -85,12 +95,15 @@ type Server struct {
 
 func New(cfg *config.Config, sessions *auth.Sessions, mgr *term.Manager, col *metrics.Collector, st *store.Store, svc *services.Manager, cr *cron.Manager, tm *tasks.Manager, up *updates.Manager, sto *storage.Manager, fsLocal, fsSudo files.FS, nm *nodes.Manager, fingerprint string, ui fs.FS, version string) *Server {
 	s := &Server{cfg: cfg, sessions: sessions, mgr: mgr, metrics: col, sensors: sensors.NewRegistry(col), store: st, svc: svc, cron: cr, tasks: tm, updates: up, storage: sto, fsLocal: fsLocal, fsSudo: fsSudo, nodes: nm, fingerprint: fingerprint, ui: ui, version: version,
-		started: time.Now(), user: os.Getenv("USER")}
+		hardware: hardware.New(), started: time.Now(), user: os.Getenv("USER")}
 	self, err := os.Executable()
 	if err != nil {
 		self = "hamlab"
 	}
+	s.self = self
 	s.space = space.New(self, filepath.Join(cfg.DataDir(), "space"))
+	s.thumbs = newThumbSvc(cfg.DataDir(), self)
+	s.plays = media.NewPlays(cfg.DataDir(), self, playRuns)
 	s.hostName() // read it once now so the first request doesn't have to
 	if u, err := user.Current(); err == nil && u.Username != "" {
 		s.user = u.Username
@@ -99,21 +112,16 @@ func New(cfg *config.Config, sessions *auth.Sessions, mgr *term.Manager, col *me
 		s.user = "?"
 	}
 	s.migrateUsers()
+	// The speed test and the outside view. Its history outlives a restart, and its last result
+	// is published as sensors, so the line is graphable and alertable like anything else.
+	s.net = network.NewWatcher(s.keepResult)
+	s.net.Test.Load(s.loadNetwork())
+	s.sensors.Add(netSensors{s.net})
 	s.sensors.Add(newStatusSensors(s))
 	s.alerts = newAlertEngine(s)
 	// The saved dashboard layout carries the sampling interval; apply it on boot.
-	var raw json.RawMessage
 	var histSec int
-	st.View(func(x *store.State) {
-		raw, histSec = x.Dashboard, x.HistorySec
-		if len(raw) == 0 {
-			for _, u := range x.Users {
-				raw = u.Dashboard
-				break
-			}
-		}
-	})
-	s.applyPrefs(raw)
+	st.View(func(x *store.State) { histSec = x.HistorySec })
 	if histSec > 0 {
 		col.SetWindow(time.Duration(histSec) * time.Second)
 	}
@@ -146,8 +154,18 @@ func New(cfg *config.Config, sessions *auth.Sessions, mgr *term.Manager, col *me
 		}
 		go s.keepFleetInStep()
 	}
+	go s.watchGuests()
 	go s.watchForUpdates(context.Background())
+	go s.watchDockerEvents(context.Background())
 
+	s.mux = s.routes()
+	return s
+}
+
+// routes is the whole HTTP surface. A method of its own, rather than inline in New, so a
+// test can build the real router without the machinery behind it — which is what the guest
+// gate is checked against, since it decides a request by asking this router where it would go.
+func (s *Server) routes() *http.ServeMux {
 	m := http.NewServeMux()
 	m.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(204) })
 	m.HandleFunc("POST /api/login", s.login)
@@ -194,27 +212,28 @@ func New(cfg *config.Config, sessions *auth.Sessions, mgr *term.Manager, col *me
 	m.HandleFunc("POST /api/docker/images/prune", s.auth(s.imagePrune))
 	m.HandleFunc("POST /api/docker/volumes/remove", s.auth(s.volumeRemove))
 	m.HandleFunc("POST /api/docker/volumes/prune", s.auth(s.volumePrune))
+	m.HandleFunc("POST /api/docker/networks/remove", s.auth(s.networkRemove))
+	m.HandleFunc("POST /api/docker/networks/prune", s.auth(s.networkPrune))
 	m.HandleFunc("GET /api/docker/stacks/{name}", s.auth(s.stackFile))
 	m.HandleFunc("PUT /api/docker/stacks/{name}", s.auth(s.stackSave))
 	m.HandleFunc("POST /api/docker/stacks/{name}/{action}", s.auth(s.stackAction))
 	m.HandleFunc("GET /api/docker/stacks/{name}/diff", s.auth(s.stackDiff))
 	m.HandleFunc("GET /api/docker/stacks/{name}/updates", s.auth(s.stackUpdates))
-	// The same, asked of a node through this hub: the hub answers for the stacks whose files
-	// it holds (deployed to the node over tcp) and passes everything else to the node.
-	m.HandleFunc("GET /api/nodes/{node}/docker/stacks", s.auth(s.stacksList))
-	m.HandleFunc("POST /api/nodes/{node}/docker/stacks", s.auth(s.stackCreate))
-	m.HandleFunc("GET /api/nodes/{node}/docker/stacks/homes", s.auth(s.stackHomes))
-	m.HandleFunc("POST /api/nodes/{node}/docker/stacks/{name}/delete", s.auth(s.stackDelete))
-	m.HandleFunc("GET /api/nodes/{node}/docker/stacks/{name}", s.auth(s.stackFile))
-	m.HandleFunc("PUT /api/nodes/{node}/docker/stacks/{name}", s.auth(s.stackSave))
-	m.HandleFunc("GET /api/nodes/{node}/docker/stacks/{name}/diff", s.auth(s.stackDiff))
-	m.HandleFunc("GET /api/nodes/{node}/docker/stacks/{name}/updates", s.auth(s.stackUpdates))
-	m.HandleFunc("POST /api/nodes/{node}/docker/stacks/{name}/{action}", s.auth(s.stackAction))
-	m.HandleFunc("GET /api/nodes/{node}/tasks/{id}", s.auth(s.taskOnHub(s.getTask)))
-	m.HandleFunc("GET /api/nodes/{node}/tasks/{id}/stream", s.auth(s.taskOnHub(s.streamTask)))
+	m.HandleFunc("GET /api/docker/updates", s.auth(s.machineUpdates))
+	m.HandleFunc("GET /api/docker/schedules", s.auth(s.dsList))
+	m.HandleFunc("PUT /api/docker/schedules", s.auth(s.dsPut))
+	m.HandleFunc("DELETE /api/docker/schedules/{id}", s.auth(s.dsDelete))
+	m.HandleFunc("POST /api/docker/schedules/{id}/run", s.auth(s.dsRun))
+	// Asked of a node through this hub, every one of these is the node's to answer: the
+	// generic /api/nodes/{name}/{rest...} proxy above carries them there unchanged.
 	m.HandleFunc("POST /api/docker/containers/{id}/{action}", s.auth(s.dockerAction))
 	m.HandleFunc("GET /api/docker/containers/{id}/logs", s.auth(s.dockerLogs))
+	m.HandleFunc("GET /api/docker/containers/{id}/logs/tail", s.auth(s.dockerTail))
 	m.HandleFunc("GET /api/docker/containers/{id}/inspect", s.auth(s.dockerInspect))
+	m.HandleFunc("GET /api/docker/containers/{id}/health", s.auth(s.dockerHealth))
+	m.HandleFunc("GET /api/docker/containers/{id}/events", s.auth(s.dockerEvents))
+	m.HandleFunc("POST /api/docker/containers/{id}/exec", s.auth(s.dockerExec))
+	m.HandleFunc("POST /api/docker/containers/{id}/limits", s.auth(s.dockerUpdate))
 	m.HandleFunc("GET /api/alerts", s.auth(s.alertsGet))
 	m.HandleFunc("PUT /api/alerts", s.auth(s.alertsPut))
 	m.HandleFunc("POST /api/alerts/test", s.auth(s.alertsTest))
@@ -253,14 +272,45 @@ func New(cfg *config.Config, sessions *auth.Sessions, mgr *term.Manager, col *me
 	m.HandleFunc("POST /api/files/mkdir", s.auth(s.filesMkdir))
 	m.HandleFunc("POST /api/files/touch", s.auth(s.filesTouch))
 	m.HandleFunc("POST /api/files/rename", s.auth(s.filesRename))
+	m.HandleFunc("POST /api/files/move", s.auth(s.filesMove))
 	m.HandleFunc("POST /api/files/delete", s.auth(s.filesDelete))
 	m.HandleFunc("POST /api/files/chmod", s.auth(s.filesChmod))
+	m.HandleFunc("GET /api/files/thumb", s.auth(s.filesThumb))
+	m.HandleFunc("GET /api/files/thumbs", s.auth(s.thumbsStatus))
+	m.HandleFunc("POST /api/files/thumbs/install", s.auth(s.thumbsInstall))
+	m.HandleFunc("POST /api/files/thumbs/gpu-access", s.auth(s.thumbsGPUAccess))
+	m.HandleFunc("GET /api/files/play-devices", s.auth(s.playDevices))
+	m.HandleFunc("POST /api/files/play", s.auth(s.playStart))
+	m.HandleFunc("GET /api/files/play/{id}", s.auth(s.playStatus))
+	m.HandleFunc("DELETE /api/files/play/{id}", s.auth(s.playStop))
+	m.HandleFunc("POST /api/files/play/{id}/close", s.auth(s.playStop))
+	m.HandleFunc("GET /api/files/play/{id}/{file}", s.auth(s.playPlaylist))
+	m.HandleFunc("GET /api/files/play/{id}/{rung}/{seg}", s.auth(s.playPiece))
+	m.HandleFunc("POST /api/play", s.auth(s.hubPlay))
+	m.HandleFunc("GET /api/transcode", s.auth(s.getTranscode))
+	m.HandleFunc("PUT /api/transcode", s.auth(s.putTranscode))
+	m.HandleFunc("GET /api/play-src/{token}", s.playSrc) // the token is the key
+	m.HandleFunc("GET /api/hardware", s.auth(s.hardwareReport))
+	m.HandleFunc("GET /api/network", s.auth(s.networkOverview))
+	m.HandleFunc("GET /api/vpn", s.auth(s.vpnReport))
+	m.HandleFunc("POST /api/vpn/{iface}/peers", s.auth(s.addVPNPeer))
+	m.HandleFunc("PATCH /api/vpn/{iface}/peers/{section}", s.auth(s.editVPNPeer))
+	m.HandleFunc("DELETE /api/vpn/{iface}/peers/{section}", s.auth(s.removeVPNPeer))
+	m.HandleFunc("GET /api/network/speedtest", s.auth(s.speedtestState))
+	m.HandleFunc("POST /api/network/speedtest", s.auth(s.speedtestStart))
+	m.HandleFunc("POST /api/network/speedtest/cancel", s.auth(s.speedtestCancel))
 	m.HandleFunc("GET /api/storage", s.auth(s.storageOverview))
 	m.HandleFunc("GET /api/storage/smart/{dev}", s.auth(s.storageSmart))
 	m.HandleFunc("POST /api/storage/smart/{dev}/test/{kind}", s.auth(s.storageSmartTest))
 	m.HandleFunc("GET /api/storage/zfs/snapshots", s.auth(s.zfsSnapshots))
 	m.HandleFunc("POST /api/storage/zfs/scrub/{pool}/{action}", s.auth(s.zfsScrub))
 	m.HandleFunc("POST /api/storage/zfs/snapshot", s.auth(s.zfsSnapshot))
+	m.HandleFunc("GET /api/zfs", s.auth(s.zfsOverview))
+	m.HandleFunc("GET /api/zfs/arc", s.auth(s.zfsARC))
+	m.HandleFunc("PUT /api/zfs/schedules", s.auth(s.zfsPolicyPut))
+	m.HandleFunc("DELETE /api/zfs/schedules/{id}", s.auth(s.zfsPolicyDelete))
+	m.HandleFunc("POST /api/zfs/schedules/{id}/run", s.auth(s.zfsRunNow))
+	m.HandleFunc("POST /api/zfs/snapshots/delete", s.auth(s.zfsSnapshotDelete))
 	m.HandleFunc("GET /api/space", s.auth(s.spaceOverview))
 	m.HandleFunc("GET /api/space/{disk}", s.auth(s.spaceStatus))
 	m.HandleFunc("POST /api/space/{disk}/scan", s.auth(s.spaceScan))
@@ -275,9 +325,13 @@ func New(cfg *config.Config, sessions *auth.Sessions, mgr *term.Manager, col *me
 	m.HandleFunc("POST /api/users", s.auth(s.addUser))
 	m.HandleFunc("DELETE /api/users/{name}", s.auth(s.removeUser))
 	m.HandleFunc("POST /api/users/{name}/password", s.auth(s.resetPassword))
+	m.HandleFunc("GET /api/guests", s.auth(s.listGuests))
+	m.HandleFunc("POST /api/guests", s.auth(s.addGuest))
+	m.HandleFunc("DELETE /api/guests/{name}", s.auth(s.revokeGuest))
 	m.HandleFunc("GET /api/sessions", s.auth(s.listSessions))
 	m.HandleFunc("DELETE /api/sessions/{id}", s.auth(s.revokeSession))
 	m.HandleFunc("POST /api/sessions/revoke-others", s.auth(s.revokeOtherSessions))
+	m.HandleFunc("POST /api/sessions/revoke-idle", s.auth(s.revokeIdleSessions))
 	m.HandleFunc("GET /api/prefs/ui", s.auth(s.getUIPrefs))
 	m.HandleFunc("PUT /api/prefs/ui", s.auth(s.putUIPrefs))
 	// Go runtime profiles, behind the login, for chasing memory/CPU (bug 14).
@@ -289,12 +343,22 @@ func New(cfg *config.Config, sessions *auth.Sessions, mgr *term.Manager, col *me
 	m.HandleFunc("PUT /api/prefs/sampler", s.auth(s.putSampler))
 	m.HandleFunc("GET /api/prefs/history", s.auth(s.getHistoryWindow))
 	m.HandleFunc("PUT /api/prefs/history", s.auth(s.putHistoryWindow))
-	m.HandleFunc("GET /api/prefs/dashboard", s.auth(s.getDashPrefs))
-	m.HandleFunc("PUT /api/prefs/dashboard", s.auth(s.putDashPrefs))
-	m.HandleFunc("/api/", func(w http.ResponseWriter, _ *http.Request) { jsonErr(w, 404, "not found") })
+	m.HandleFunc("GET /api/kvms", s.auth(s.listKVMs))
+	m.HandleFunc("POST /api/kvms", s.auth(s.addKVM))
+	m.HandleFunc("DELETE /api/kvms/{id}", s.auth(s.removeKVM))
+	m.HandleFunc("/kvm/{id}/{rest...}", s.auth(s.serveKVM))
+	m.HandleFunc("/kvm/{id}", s.auth(s.serveKVM))
+	// A path Ham Lab does not serve may still belong to a KVM's page, which asks for its
+	// own assets by absolute path. Ham Lab's own routes matched first, so this can only
+	// catch what would otherwise have been a 404.
+	m.HandleFunc("/api/", s.auth(func(w http.ResponseWriter, r *http.Request) {
+		if s.kvmFallback(w, r) {
+			return
+		}
+		jsonErr(w, 404, "not found")
+	}))
 	m.HandleFunc("/", s.static)
-	s.mux = m
-	return s
+	return m
 }
 
 // sensorPath reports whether a path belongs to the read-only sensor API.
@@ -314,9 +378,16 @@ func sensorPath(p string) bool {
 func (s *Server) Handler() http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		h := w.Header()
-		// The console must never be framed. An embedded widget exists to be: it is a page
-		// that can only read sensors, and only with a read-only token in its URL.
-		if r.URL.Path != "/embed/widget" {
+		// The console must never be framed. Two exceptions: an embedded widget exists to be
+		// (a page that can only read sensors, and only with a read-only token in its URL),
+		// and a proxied KVM is framed by the console itself — 'none' forbids that even from
+		// the same origin, so those paths say 'self' instead of opening up.
+		switch {
+		case r.URL.Path == "/embed/widget":
+		case strings.HasPrefix(r.URL.Path, kvmPrefix):
+			h.Set("X-Frame-Options", "SAMEORIGIN")
+			h.Set("Content-Security-Policy", "frame-ancestors 'self'")
+		default:
 			h.Set("X-Frame-Options", "DENY")
 			h.Set("Content-Security-Policy", "frame-ancestors 'none'")
 		}
@@ -362,14 +433,56 @@ func (s *Server) setCookie(w http.ResponseWriter, r *http.Request, tok string, m
 	})
 }
 
+// signedIn reports whether a request carries a live browser session, without the
+// side effects of the auth middleware.
+func (s *Server) signedIn(r *http.Request) bool {
+	c, err := r.Cookie(cookieName)
+	if err != nil {
+		return false
+	}
+	_, ok := s.sessions.Lookup(c.Value, clientKey(r))
+	return ok
+}
+
+// cookieActor resolves the session cookie to who is calling. answered means the caller has
+// already been sent an error and the handler must not run: the account behind a live session
+// has gone away, or a guest login's time is up — so a console left open on a visitor's phone
+// stops at the expiry, not at whatever they click next.
+func (s *Server) cookieActor(w http.ResponseWriter, r *http.Request) (a actor, ok, answered bool) {
+	c, err := r.Cookie(cookieName)
+	if err != nil {
+		return actor{}, false, false
+	}
+	ses, live := s.sessions.Lookup(c.Value, clientKey(r))
+	if !live {
+		return actor{}, false, false
+	}
+	var u config.User
+	var found bool
+	s.cfg.View(func(cf *config.Config) { u, found = cf.User(ses.User) })
+	if !found || u.Expired(time.Now()) {
+		s.sessions.Delete(c.Value)
+		s.setCookie(w, r, "", -1)
+		if found {
+			jsonErr(w, 401, "this guest login has expired")
+		} else {
+			jsonErr(w, 401, "that account no longer exists")
+		}
+		return actor{}, false, true
+	}
+	return actor{User: ses.User, Session: ses.ID, token: c.Value, Guest: u.Guest, Expires: u.Expires}, true, false
+}
+
 // auth accepts the browser session cookie or a bearer API token issued to a hub.
 func (s *Server) auth(next http.HandlerFunc) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
-		if c, err := r.Cookie(cookieName); err == nil {
-			if ses, ok := s.sessions.Lookup(c.Value, clientKey(r)); ok {
-				next(w, withActor(r, actor{User: ses.User, Session: ses.ID, token: c.Value}))
+		a, ok, answered := s.cookieActor(w, r)
+		if answered {
 			return
 		}
+		if ok {
+			next(w, withActor(r, a))
+			return
 		}
 		if h := r.Header.Get("Authorization"); strings.HasPrefix(h, "Bearer ") {
 			var hashes, names []string
@@ -403,11 +516,11 @@ func (s *Server) sensorAuth(next http.HandlerFunc) http.HandlerFunc {
 	return func(w http.ResponseWriter, r *http.Request) {
 		ok, trusted := false, false
 		var patterns []string
-		if c, err := r.Cookie(cookieName); err == nil {
-			if ses, valid := s.sessions.Lookup(c.Value, clientKey(r)); valid {
+		if a, live, answered := s.cookieActor(w, r); answered {
+			return
+		} else if live {
 			ok, trusted = true, true
-				r = withActor(r, actor{User: ses.User, Session: ses.ID, token: c.Value})
-			}
+			r = withActor(r, a)
 		}
 		if !ok {
 			presented, fromURL := strings.TrimPrefix(r.Header.Get("Authorization"), "Bearer "), false
@@ -826,11 +939,7 @@ func (s *Server) updateAllMachines(w http.ResponseWriter, r *http.Request) {
 }
 
 func (s *Server) proxyNode(w http.ResponseWriter, r *http.Request) {
-	node := r.PathValue("node") // routes that also carry a {name} of their own call the machine {node}
-	if node == "" {
-		node = r.PathValue("name")
-	}
-	p, ok := s.nodes.Proxy(node)
+	p, ok := s.nodes.Proxy(r.PathValue("name"))
 	if !ok {
 		jsonErr(w, 404, "no such machine")
 		return
@@ -876,11 +985,11 @@ func (s *Server) login(w http.ResponseWriter, r *http.Request) {
 // name is allowed only while there is exactly one account — what a client from before
 // user names sends, and what a hub pairing with a one-user node may leave out.
 func (s *Server) checkLogin(username, password string) (string, bool) {
-	var users []config.User
-	s.cfg.View(func(c *config.Config) { users = append(users, c.Users...) })
+	var users, real []config.User
+	s.cfg.View(func(c *config.Config) { users, real = append(users, c.Users...), c.Accounts() })
 	username = strings.TrimSpace(username)
-	if username == "" && len(users) == 1 {
-		username = users[0].Name
+	if username == "" && len(real) == 1 { // guest logins are not the account an empty name means
+		username = real[0].Name
 	}
 	if username == "" {
 		auth.CheckUser(nil, "", password) // take as long as a real check
@@ -930,15 +1039,11 @@ func (s *Server) migrateUsers() {
 				st.Sessions[tok] = ses
 			}
 		}
-		if len(st.UI) > 0 || len(st.Dashboard) > 0 {
-			u := st.UserState(first)
-			if len(u.UI) == 0 {
+		if len(st.UI) > 0 {
+			if u := st.UserState(first); len(u.UI) == 0 {
 				u.UI = st.UI
 			}
-			if len(u.Dashboard) == 0 {
-				u.Dashboard = st.Dashboard
-			}
-			st.UI, st.Dashboard = nil, nil
+			st.UI = nil
 		}
 	})
 }
@@ -1019,8 +1124,14 @@ func (s *Server) me(w http.ResponseWriter, r *http.Request) {
 			addr = h // the address this console listens on, for the machine menu
 		}
 	})
+	me := actorOf(r)
+	var guestUntil any
+	if me.Guest {
+		guestUntil = me.Expires
+	}
 	jsonOK(w, 200, map[string]any{
-		"host": s.hostName(), "user": s.user, "account": actorOf(r).User, "version": s.version,
+		"host": s.hostName(), "user": s.user, "account": me.User, "version": s.version,
+		"guest": me.Guest, "guest_until": guestUntil,
 		"load": load, "uptime": uptime, "service_started": s.started,
 		"reboot_needed": rebootErr == nil, "fingerprint": s.fingerprint, "arch": runtime.GOARCH, "addr": addr,
 		"update_available": updateVersion,
@@ -1792,21 +1903,15 @@ func (s *Server) filesRead(w http.ResponseWriter, r *http.Request) {
 		jsonErr(w, 400, "not a regular file (device, pipe or socket)")
 		return
 	}
+	if in.Broken {
+		jsonErr(w, 404, "a link to nothing: "+in.Target)
+		return
+	}
 	mx, _ := strconv.ParseInt(r.URL.Query().Get("max"), 10, 64)
 	if mx > 0 && in.Size > mx {
 		jsonErr(w, 413, "file too large")
 		return
 	}
-	f, err := fsys.Open(r.Context(), p)
-	if err != nil {
-		fsErr(w, err)
-		return
-	}
-	defer f.Close()
-	var body io.Reader = f
-	if mx > 0 { // stat can lie (size 0 on /proc); the cap must hold on the bytes actually sent
-		body = io.LimitReader(f, mx+1)
-	}
 	name := filepath.Base(p)
 	ct := mime.TypeByExtension(filepath.Ext(name))
 	if ct == "" {
@@ -1825,7 +1930,28 @@ func (s *Server) filesRead(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Disposition", "inline; filename*=UTF-8''"+url.PathEscape(name))
 	}
 	if in.Size > 0 && mx == 0 {
-		w.Header().Set("Content-Length", strconv.FormatInt(in.Size, 10))
+		// A real file of known size goes through net/http, which speaks Range: a video player
+		// can seek and a download can resume. /proc files say size 0 and take the plain path.
+		rs := files.NewSeeker(r.Context(), fsys, p, in.Size)
+		defer rs.Close()
+		if _, local := fsys.(files.Local); local { // cheap here, and turns "can't open" into a status rather than a cut-off body
+			if err := rs.Check(); err != nil {
+				fsErr(w, err)
+				return
+			}
+		}
+		http.ServeContent(w, r, name, time.UnixMilli(in.Mtime), rs)
+		return
+	}
+	f, err := fsys.Open(r.Context(), p)
+	if err != nil {
+		fsErr(w, err)
+		return
+	}
+	defer f.Close()
+	var body io.Reader = f
+	if mx > 0 { // stat can lie (size 0 on /proc); the cap must hold on the bytes actually sent
+		body = io.LimitReader(f, mx+1)
 	}
 	_, _ = io.Copy(w, body)
 }
@@ -1839,7 +1965,14 @@ func (s *Server) filesWrite(w http.ResponseWriter, r *http.Request) {
 	if !ok {
 		return
 	}
-	if err := fsys.Write(r.Context(), p, io.LimitReader(r.Body, 8<<20)); err != nil {
+	// Whole in memory first: the write truncates the file, so a body over the cap must be
+	// refused before that, not cut short after it.
+	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 8<<20))
+	if err != nil {
+		jsonErr(w, 413, "too large to save here (8 MiB at most)")
+		return
+	}
+	if err := fsys.Write(r.Context(), p, bytes.NewReader(body)); err != nil {
 		fsErr(w, err)
 		return
 	}
@@ -1926,6 +2059,63 @@ func (s *Server) filesRename(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// filesMove: POST {path, to} — to is the full destination path. A rename when the two
+// ends share a filesystem (204); otherwise the copy-and-remove runs as a task (202 with the
+// task), since a folder between datasets can take as long as it takes.
+func (s *Server) filesMove(w http.ResponseWriter, r *http.Request) {
+	fsys, ok := s.fsFor(w, r)
+	if !ok {
+		return
+	}
+	var body struct{ Path, To string }
+	if err := json.NewDecoder(io.LimitReader(r.Body, 64<<10)).Decode(&body); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	from, err := files.Clean(body.Path)
+	if err != nil {
+		jsonErr(w, 400, err.Error())
+		return
+	}
+	to, err := files.Clean(body.To)
+	if err != nil {
+		jsonErr(w, 400, err.Error())
+		return
+	}
+	if from == to {
+		jsonErr(w, 400, "it is already there")
+		return
+	}
+	if files.Inside(from, to) {
+		jsonErr(w, 400, "a folder can't be moved into itself")
+		return
+	}
+	// The kernel answers EXDEV for two paths on different filesystems before it looks for
+	// the source, so a missing file would otherwise become a task that fails on arrival.
+	if _, err := fsys.Stat(r.Context(), from); err != nil {
+		fsErr(w, err)
+		return
+	}
+	err = fsys.Rename(r.Context(), from, to)
+	if err == nil {
+		log.Printf("files: move %s -> %s (from %s)", from, to, clientIP(r))
+		w.WriteHeader(204)
+		return
+	}
+	if !files.IsCrossDevice(err) {
+		fsErr(w, err)
+		return
+	}
+	cmd := files.MoveCmd(context.Background(), fsys, s.self, from, to)
+	t, err := s.tasks.Start("files:move", "move "+filepath.Base(from)+" to "+filepath.Dir(to), cmd)
+	if err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	log.Printf("files: move %s -> %s across filesystems as task %s (from %s)", from, to, t.ID, clientIP(r))
+	jsonOK(w, 202, t.Snapshot(false))
+}
+
 func (s *Server) filesDelete(w http.ResponseWriter, r *http.Request) {
 	s.filesOp(w, r, func(fsys files.FS, body map[string]any, p string) error {
 		rec, _ := body["recursive"].(bool)
@@ -2282,44 +2472,6 @@ func (s *Server) pushHistoryWindow(seconds int) {
 	}
 }
 
-// ---- dashboard layout prefs (opaque JSON object, owned by the UI) ----
-
-func (s *Server) getDashPrefs(w http.ResponseWriter, r *http.Request) {
-	w.Header().Set("Cache-Control", "no-store")
-	jsonOK(w, 200, s.userPrefs(r, func(u *store.UserState) json.RawMessage { return u.Dashboard }))
-}
-
-func (s *Server) putDashPrefs(w http.ResponseWriter, r *http.Request) {
-	b, err := io.ReadAll(io.LimitReader(r.Body, 64<<10))
-	if err != nil || !json.Valid(b) || len(b) == 0 || b[0] != '{' {
-		jsonErr(w, 400, "expected a JSON object")
-		return
-	}
-	if user := actorOf(r).User; user != "" {
-		if err := s.store.Update(func(st *store.State) { st.UserState(user).Dashboard = json.RawMessage(b) }); err != nil {
-			jsonErr(w, 500, err.Error())
-			return
-		}
-	}
-	s.applyPrefs(b)
-	w.WriteHeader(204)
-}
-
-// applyPrefs picks the few layout fields the server acts on (just the interval).
-func (s *Server) applyPrefs(raw []byte) {
-	var p struct {
-		IntervalMs int `json:"intervalMs"`
-	}
-	if len(raw) == 0 || json.Unmarshal(raw, &p) != nil {
-		return
-	}
-	if p.IntervalMs > 0 {
-		s.metrics.SetInterval(time.Duration(p.IntervalMs) * time.Millisecond)
-	} else {
-		s.metrics.SetInterval(metrics.DefaultInterval)
-	}
-}
-
 // ---- terminals ----
 
 func (s *Server) listTerminals(w http.ResponseWriter, _ *http.Request) {
@@ -2494,6 +2646,12 @@ func (s *Server) static(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 	}
+	// A path with no file of ours behind it may belong to a KVM's page, which asks for its
+	// own assets by absolute path. Checked here rather than in the router because this
+	// handler is the catch-all — and gated on a session, since this handler is public.
+	if s.signedIn(r) && s.kvmFallback(w, r) {
+		return
+	}
 	// SPA fallback
 	w.Header().Set("Cache-Control", "no-cache")
 	http.ServeFileFS(w, r, s.ui, "index.html")

internal/api/stacks.go

@@ -12,11 +12,16 @@ package api
 // relative paths, the .env beside them and the labels all stay exactly as they were
 // deployed — else on the host.
 //
-// A stack can also be deployed *from another machine*: Dockhand on the hub drives a node's
-// Docker over tcp, so the node runs the containers and the hub holds the files. The node
-// alone can only list such a stack read-only. The hub, asked about one of its nodes, fills
-// in what the node couldn't (hubStacks): it resolves the files on itself and runs compose
-// here with DOCKER_HOST pointed at the node.
+// Those mounts are also written down. An orchestrator can be removed, and when it is, the
+// containers it left behind still carry labels naming paths inside a filesystem that no
+// longer exists; without a record of where that filesystem was mounted, every stack on the
+// machine would become unfindable at once. A remembered mount resolves with no container to
+// run in, which is right: compose runs on the host against the host's copy of the file.
+//
+// A stack is one machine's affair: its files and the Docker that runs it are on the same
+// box, and that box's Ham Lab is the only thing that touches either. Asked about a node's
+// stacks, a hub passes the request to the node's own Ham Lab and relays the answer; it holds
+// no files for anyone else and never points compose at another machine's Docker.
 
 import (
 	"bytes"
@@ -29,7 +34,6 @@ import (
 	"io"
 	"log"
 	"net/http"
-	"net/url"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -39,7 +43,9 @@ import (
 	"sync"
 	"time"
 
+	"hamlab/internal/compose"
 	"hamlab/internal/priv"
+	"hamlab/internal/store"
 )
 
 type stack struct {
@@ -52,8 +58,6 @@ type stack struct {
 	Files      []string `json:"files"`      // every file it was deployed from, in order: -f a -f b
 	HostFiles  []string `json:"host_files"` // the same, on the machine that holds them
 	Via        string   `json:"via"`        // container compose runs inside; "" = on the host
-	Remote     string   `json:"remote"`     // DOCKER_HOST compose is pointed at; "" = this machine's Docker
-	HeldBy     string   `json:"held_by"`    // the machine holding the files, when it isn't the one running them
 	Editable   bool     `json:"editable"`
 	Note       string   `json:"note,omitempty"`
 	HasEnv     bool     `json:"has_env"`
@@ -89,6 +93,100 @@ func stackMounts(ctx context.Context) []mountMap {
 	return maps
 }
 
+// mountsFor is stackMounts plus memory. An orchestrator that deployed everything here and
+// has since been removed takes the only record of where its files really are with it: the
+// containers it left behind are labelled with paths inside *its* filesystem. So every map
+// seen is written down, and a path that no live container explains is looked for in what
+// was seen before. A remembered map resolves with no `via`, which is correct — the
+// container is gone, so compose runs on the host, against the host's copy of the file.
+func mountsFor(ctx context.Context, db *store.Store) []mountMap {
+	live := stackMounts(ctx)
+	rememberMounts(db, live)
+	return append(live, recallMounts(db, live)...)
+}
+
+// mountsSeen is the same without writing anything down. The daemon owns state.json; a cron
+// job that wrote to it would be clobbered by the next thing the daemon saved, so out there
+// the record is read and never added to.
+func mountsSeen(ctx context.Context, db *store.Store) []mountMap {
+	live := stackMounts(ctx)
+	return append(live, recallMounts(db, live)...)
+}
+
+// rememberMounts folds what is mounted now into what was mounted before, and forgets a map
+// whose source has gone from disk — that one is not coming back, and keeping it would make
+// a stack look editable when its file no longer exists.
+//
+// This is on the path of every stack listing, which the Docker tab polls, so it reads first
+// and only writes when the set actually changed.
+func rememberMounts(db *store.Store, live []mountMap) {
+	if len(live) == 0 {
+		return // docker is down or answered nothing; that is not evidence of anything
+	}
+	key := func(c, d string) string { return c + "\x00" + d }
+	var have []store.RememberedMount
+	db.View(func(st *store.State) { have = append([]store.RememberedMount(nil), st.Mounts...) })
+	at := map[string]int{}
+	for i, m := range have {
+		at[key(m.Container, m.Dest)] = i
+	}
+	now, add, moved := time.Now(), 0, false
+	for _, m := range live {
+		i, ok := at[key(m.container, m.dest)]
+		if !ok {
+			add++
+			continue
+		}
+		if have[i].Src != m.src {
+			moved = true
+		}
+	}
+	// Pruning is the expensive half — a stat, or a sudo test(1), per remembered map — so it
+	// only happens when something else has already made a write necessary.
+	if add == 0 && !moved {
+		return
+	}
+	_ = db.Update(func(st *store.State) {
+		at := map[string]int{}
+		for i, m := range st.Mounts {
+			at[key(m.Container, m.Dest)] = i
+		}
+		for _, m := range live {
+			if i, ok := at[key(m.container, m.dest)]; ok {
+				st.Mounts[i].Src, st.Mounts[i].Seen = m.src, now
+				continue
+			}
+			st.Mounts = append(st.Mounts, store.RememberedMount{Container: m.container, Dest: m.dest, Src: m.src, Seen: now})
+		}
+		kept := st.Mounts[:0]
+		for _, m := range st.Mounts {
+			if readable(m.Src) {
+				kept = append(kept, m)
+			}
+		}
+		st.Mounts = kept
+	})
+}
+
+// recallMounts is what was seen before and is not running now.
+func recallMounts(db *store.Store, live []mountMap) []mountMap {
+	var remembered []store.RememberedMount
+	db.View(func(st *store.State) { remembered = append([]store.RememberedMount(nil), st.Mounts...) })
+	now := map[string]bool{}
+	for _, m := range live {
+		now[m.container+"\x00"+m.dest] = true
+	}
+	var out []mountMap
+	for _, m := range remembered {
+		if now[m.Container+"\x00"+m.Dest] {
+			continue
+		}
+		out = append(out, mountMap{"", filepath.Clean(m.Dest), filepath.Clean(m.Src)}) // no container: run compose here
+	}
+	sort.Slice(out, func(i, j int) bool { return len(out[i].dest) > len(out[j].dest) })
+	return out
+}
+
 func readable(p string) bool {
 	if _, err := os.Stat(p); err == nil {
 		return true
@@ -172,7 +270,7 @@ func (s *Server) findStacks(ctx context.Context) ([]stack, error) {
 			}
 		}
 	}
-	maps := stackMounts(ctx)
+	maps := mountsFor(ctx, s.store)
 	stacks := []stack{}
 	for _, st := range by {
 		sort.Strings(st.Containers)
@@ -180,7 +278,7 @@ func (s *Server) findStacks(ctx context.Context) ([]stack, error) {
 		st.resolve(maps)
 		stacks = append(stacks, *st)
 	}
-	stacks = append(stacks, scanHomes(ctx, s.homesOf(stacks, true), stacks)...)
+	stacks = append(stacks, scanHomes(ctx, s.homesOf(stacks), stacks)...)
 	sort.Slice(stacks, func(i, j int) bool { return stacks[i].Name < stacks[j].Name })
 	return stacks, nil
 }
@@ -188,19 +286,23 @@ func (s *Server) findStacks(ctx context.Context) ([]stack, error) {
 // ---- where stacks live ----
 
 // A home is a directory of stacks, one folder each: where new ones are made, and where ones
-// that aren't deployed (never were, or were taken down) are still found. Homes aren't
-// configured; they are wherever this machine's stacks already are. With none at all, ~/stacks.
+// that aren't deployed (never were, or were taken down) are still found. The default is
+// Ham Lab's own: <data dir>/stacks, which is where everything this console manages lives.
+// Any folder this machine already keeps stacks in — two or more deployed from it — is
+// offered as well, so what was deployed before Ham Lab arrived stays editable and gains
+// neighbours where it is, but it is never the default.
 type stackHome struct {
-	Dir     string `json:"dir"`     // on the machine that holds the files
+	Dir     string `json:"dir"`   // on this machine
 	Inner   string `json:"inner"` // the same directory as compose sees it (inside Via); Dir otherwise
 	Via     string `json:"via"`   // container compose runs inside
-	Remote  string `json:"remote"`  // DOCKER_HOST, when the containers run on another machine
-	HeldBy  string `json:"held_by"` // the machine holding the files, when it isn't the one running them
 	Stacks  int    `json:"stacks"`
 	Default bool   `json:"default"`
 }
 
-func (s *Server) homesOf(stacks []stack, withFallback bool) []stackHome {
+// stacksDir is the home Ham Lab owns.
+func (s *Server) stacksDir() string { return filepath.Join(s.cfg.DataDir(), "stacks") }
+
+func (s *Server) homesOf(stacks []stack) []stackHome {
 	type tally struct {
 		home     stackHome
 		deployed int
@@ -216,11 +318,10 @@ func (s *Server) homesOf(stacks []stack, withFallback bool) []stackHome {
 		if strings.Count(dir, "/") < 2 { // "/" or "/tmp": not somewhere to make folders in
 			continue
 		}
-		key := dir + "|" + st.Remote
-		t := by[key]
+		t := by[dir]
 		if t == nil {
-			t = &tally{home: stackHome{Dir: dir, Remote: st.Remote, HeldBy: st.HeldBy}, byVia: map[string]int{}, inner: map[string]string{}}
-			by[key] = t
+			t = &tally{home: stackHome{Dir: dir}, byVia: map[string]int{}, inner: map[string]string{}}
+			by[dir] = t
 		}
 		t.home.Stacks++
 		if len(st.Containers) > 0 {
@@ -233,11 +334,13 @@ func (s *Server) homesOf(stacks []stack, withFallback bool) []stackHome {
 		}
 	}
 	// A folder is a home when stacks are kept there as a habit: two or more deployed from it.
-	// One stack on its own (Dockhand's own compose file in ~/apps/dockhand) says nothing about
-	// where the next should go, and would have every compose file near it listed as a stack.
-	// New stacks are deployed the way most of their neighbours were.
-	var homes, lone []stackHome
-	for _, t := range by {
+	// One stack on its own (an orchestrator's own compose file in its app folder) says nothing
+	// about where the next should go, and would have every compose file near it listed as a
+	// stack — unless it is already in Ham Lab's folder. New stacks are deployed the way most
+	// of their neighbours were.
+	own := s.stacksDir()
+	var homes []stackHome
+	for dir, t := range by {
 		best, n := "", -1
 		for via, c := range t.byVia {
 			if c > n || (c == n && via > best) {
@@ -253,29 +356,23 @@ func (s *Server) homesOf(stacks []stack, withFallback bool) []stackHome {
 		if t.home.Inner == "" {
 			t.home.Inner = t.home.Dir
 		}
-		if t.deployed >= 2 {
+		if t.deployed >= 2 || dir == own {
 			homes = append(homes, t.home)
-		} else {
-			lone = append(lone, t.home)
 		}
 	}
-	if len(homes) == 0 {
-		homes = lone
-	}
 	sort.Slice(homes, func(i, j int) bool {
+		if (homes[i].Dir == own) != (homes[j].Dir == own) {
+			return homes[i].Dir == own
+		}
 		if homes[i].Stacks != homes[j].Stacks {
 			return homes[i].Stacks > homes[j].Stacks
 		}
 		return homes[i].Dir < homes[j].Dir
 	})
-	if len(homes) == 0 && withFallback {
-		if home, err := os.UserHomeDir(); err == nil {
-			homes = append(homes, stackHome{Dir: filepath.Join(home, "stacks"), Inner: filepath.Join(home, "stacks")})
+	if len(homes) == 0 || homes[0].Dir != own {
+		homes = append([]stackHome{{Dir: own, Inner: own}}, homes...)
 	}
-	}
-	if len(homes) > 0 {
 	homes[0].Default = true
-	}
 	return homes
 }
 
@@ -292,6 +389,9 @@ func scanHomes(ctx context.Context, homes []stackHome, known []stack) []stack {
 	}
 	var out []stack
 	for _, h := range homes {
+		if _, err := os.Stat(h.Dir); errors.Is(err, os.ErrNotExist) {
+			continue // Ham Lab's own home before its first stack: nothing to find, and no sudo to spend finding it
+		}
 		args := []string{h.Dir, "-mindepth", "2", "-maxdepth", "2", "-type", "f", "("}
 		for i, n := range composeNames {
 			if i > 0 {
@@ -315,7 +415,7 @@ func scanHomes(ctx context.Context, homes []stackHome, known []stack) []stack {
 				continue
 			}
 			have[name], have[dir] = true, true
-			st := stack{Name: name, Containers: []string{}, Images: []string{}, HostFiles: []string{f}, HostFile: f, Via: h.Via, Remote: h.Remote, HeldBy: h.HeldBy, Editable: true, Note: "not deployed"}
+			st := stack{Name: name, Containers: []string{}, Images: []string{}, HostFiles: []string{f}, HostFile: f, Via: h.Via, Editable: true, Note: "not deployed"}
 			st.Files = []string{filepath.Join(h.Inner, filepath.Base(dir), filepath.Base(f))}
 			st.File = st.Files[0]
 			st.HasEnv = readable(st.envPath())
@@ -334,114 +434,23 @@ func contains(list []string, s string) bool {
 	return false
 }
 
-// hubStacks is a node's stack list with the hub's help: what the node could not find is
-// looked for here, and if it is here — and the node's Docker answers over tcp, which is how
-// it was deployed in the first place — the stack becomes editable from this hub.
-func (s *Server) hubStacks(ctx context.Context, node string) ([]stack, error) {
-	code, b, err := s.nodes.Do(ctx, node, "GET", "/api/docker/stacks", nil, nil)
+// stackFor finds the stack a request means.
+func (s *Server) stackFor(ctx context.Context, r *http.Request) (stack, error) {
+	all, err := s.findStacks(ctx)
 	if err != nil {
-		return nil, err
-	}
-	var res struct{ Stacks []stack }
-	if code != 200 || json.Unmarshal(b, &res) != nil {
-		return nil, fmt.Errorf("%s answered %d", node, code)
-	}
-	remote, maps := "", []mountMap(nil)
-	for i := range res.Stacks {
-		st := &res.Stacks[i]
-		if st.Editable || len(st.Files) == 0 {
-			continue
-		}
-		if remote == "" {
-			remote, maps = s.nodeDocker(ctx, node), stackMounts(ctx)
-		}
-		if remote == "-" {
-			continue
-		}
-		note := st.Note
-		if st.resolve(maps); !st.Editable {
-			st.Note = note
-			continue
-		}
-		st.Remote, st.HeldBy = remote, s.hostName()
-	}
-	var held []stack
-	for _, st := range res.Stacks {
-		if st.HeldBy != "" {
-			held = append(held, st)
-		}
-	}
-	res.Stacks = append(res.Stacks, scanHomes(ctx, s.homesOf(held, false), res.Stacks)...)
-	sort.Slice(res.Stacks, func(i, j int) bool { return res.Stacks[i].Name < res.Stacks[j].Name })
-	return res.Stacks, nil
-}
-
-var (
-	nodeDockerMu sync.Mutex
-	nodeDockerOK = map[string]string{} // node → "tcp://host:2375", or "-" when it doesn't answer
-)
-
-// nodeDocker is the node's Docker endpoint as Dockhand-style deployments use it, if it answers.
-func (s *Server) nodeDocker(ctx context.Context, node string) string {
-	nodeDockerMu.Lock()
-	defer nodeDockerMu.Unlock()
-	if v, ok := nodeDockerOK[node]; ok && v != "-" {
-		return v
-	}
-	ep := "-"
-	for _, n := range s.nodes.List() {
-		if n.Name != node {
-			continue
-		}
-		if u, err := url.Parse(n.URL); err == nil && u.Hostname() != "" {
-			cand := "tcp://" + u.Hostname() + ":2375"
-			c, cancel := context.WithTimeout(ctx, 5*time.Second)
-			if exec.CommandContext(c, dockerTool(), "-H", cand, "version", "--format", "{{.Server.Version}}").Run() == nil {
-				ep = cand
-			}
-			cancel()
-		}
-	}
-	nodeDockerOK[node] = ep
-	return ep
-}
-
-// stackFor finds the stack a request means: on this machine, or (on a hub route) one of a
-// node's stacks that this hub holds the files for. handled is false when the request should
-// simply be passed on to the node.
-func (s *Server) stackFor(ctx context.Context, r *http.Request) (st stack, handled bool, err error) {
-	var all []stack
-	if node := r.PathValue("node"); node != "" {
-		all, err = s.hubStacks(ctx, node)
-	} else {
-		all, err = s.findStacks(ctx)
-	}
-	if err != nil {
-		return stack{}, true, err
+		return stack{}, err
 	}
 	for _, x := range all {
 		if x.Name == r.PathValue("name") {
-			if r.PathValue("node") != "" && x.Remote == "" {
-				return x, false, nil // the node can serve this one itself
-			}
-			return x, true, nil
+			return x, nil
 		}
 	}
-	return stack{}, true, errors.New("no such stack")
+	return stack{}, errors.New("no such stack")
 }
 
 func (s *Server) stacksList(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), 40*time.Second)
 	defer cancel()
-	if node := r.PathValue("node"); node != "" {
-		stacks, err := s.hubStacks(ctx, node)
-		if err != nil {
-			s.proxyNode(w, r) // let the node's own answer (or failure) through
-			return
-		}
-		jsonOK(w, 200, map[string]any{"stacks": stacks})
-		return
-	}
 	if dockerTool() == "" { // no Docker is an empty answer, not a failure
 		jsonOK(w, 200, map[string]any{"stacks": []stack{}})
 		return
@@ -485,11 +494,7 @@ func target(r *http.Request, st stack) (host string, index int, ok bool) {
 func (s *Server) stackFile(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), 40*time.Second)
 	defer cancel()
-	st, handled, err := s.stackFor(ctx, r)
-	if !handled {
-		s.proxyNode(w, r)
-		return
-	}
+	st, err := s.stackFor(ctx, r)
 	if err != nil || !st.Editable {
 		jsonErr(w, 404, "that stack's compose file isn't anywhere this console can reach")
 		return
@@ -508,27 +513,16 @@ func (s *Server) stackFile(w http.ResponseWriter, r *http.Request) {
 	jsonOK(w, 200, map[string]any{"stack": st, "text": string(b), "sum": sumOf(b), "index": i})
 }
 
-// composeCmd is `docker compose …` for this stack, run where its files make sense and
-// pointed at the Docker that runs its containers. files are given as compose will see them.
+// composeCmd is `docker compose …` for this stack, run where its files make sense. files are
+// given as compose will see them.
 func composeCmd(ctx context.Context, st stack, files []string, args ...string) *exec.Cmd {
-	tool := dockerTool()
-	base := []string{"compose", "-p", st.Name}
-	for _, f := range files {
-		base = append(base, "-f", f)
-	}
-	if st.Via != "" {
-		pre := []string{"exec"}
-		if st.Remote != "" {
-			pre = append(pre, "-e", "DOCKER_HOST="+st.Remote)
-		}
-		return exec.CommandContext(ctx, tool, append(append(append(pre, st.Via, "docker"), base...), args...)...)
-	}
-	cmd := exec.CommandContext(ctx, tool, append(base, args...)...)
-	cmd.Dir = filepath.Dir(files[0])
-	if st.Remote != "" {
-		cmd.Env = append(os.Environ(), "DOCKER_HOST="+st.Remote)
-	}
-	return cmd
+	return compose.Cmd(ctx, specOf(st, files), args...)
+}
+
+// specOf is a stack as the compose runner needs it — and as a scheduled update stores it,
+// so the cron job and the console invoke compose identically.
+func specOf(st stack, files []string) compose.Spec {
+	return compose.Spec{Project: st.Name, Files: files, Via: st.Via, Tool: dockerTool()}
 }
 
 // seenFiles is the stack's file list as compose runs it, with file i replaced by a candidate.
@@ -556,11 +550,7 @@ func (s *Server) writeAsOwner(ctx context.Context, path, text string) error {
 func (s *Server) stackSave(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), 60*time.Second)
 	defer cancel()
-	st, handled, err := s.stackFor(ctx, r)
-	if !handled {
-		s.proxyNode(w, r)
-		return
-	}
+	st, err := s.stackFor(ctx, r)
 	if err != nil || !st.Editable {
 		jsonErr(w, 404, "that stack's compose file isn't anywhere this console can reach")
 		return
@@ -632,11 +622,7 @@ func (s *Server) stackSave(w http.ResponseWriter, r *http.Request) {
 func (s *Server) stackDiff(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), 40*time.Second)
 	defer cancel()
-	st, handled, err := s.stackFor(ctx, r)
-	if !handled {
-		s.proxyNode(w, r)
-		return
-	}
+	st, err := s.stackFor(ctx, r)
 	if err != nil || !st.Editable {
 		jsonErr(w, 404, "that stack's compose file isn't anywhere this console can reach")
 		return
@@ -686,11 +672,7 @@ func maskEnv(text string) string {
 func (s *Server) stackAction(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), 40*time.Second)
 	defer cancel()
-	st, handled, err := s.stackFor(ctx, r)
-	if !handled {
-		s.proxyNode(w, r)
-		return
-	}
+	st, err := s.stackFor(ctx, r)
 	if err != nil || !st.Editable {
 		jsonErr(w, 404, "that stack's compose file isn't anywhere this console can reach")
 		return
@@ -703,17 +685,10 @@ func (s *Server) stackAction(w http.ResponseWriter, r *http.Request) {
 	flags := priv.Quote(append([]string{"-p", st.Name}, fl...))
 	base := func(args string) string {
 		if st.Via != "" {
-			env := ""
-			if st.Remote != "" {
-				env = "-e " + priv.Quote([]string{"DOCKER_HOST=" + st.Remote}) + " "
+			// The CLI inside the orchestrator's container is its own `docker`, whatever this host runs.
+			return fmt.Sprintf("%s exec %s docker compose %s %s", dockerTool(), priv.Quote([]string{st.Via}), flags, args)
 		}
-			return fmt.Sprintf("%s exec %s%s docker compose %s %s", dockerTool(), env, priv.Quote([]string{st.Via}), flags, args)
-		}
-		env := ""
-		if st.Remote != "" { // through env(1): a quoted NAME=value in front of a command is a command name to sh, not an assignment
-			env = "env " + priv.Quote([]string{"DOCKER_HOST=" + st.Remote}) + " "
-		}
-		return fmt.Sprintf("cd %s && %s%s compose %s %s", priv.Quote([]string{filepath.Dir(files[0])}), env, dockerTool(), flags, args)
+		return fmt.Sprintf("cd %s && %s compose %s %s", priv.Quote([]string{filepath.Dir(files[0])}), dockerTool(), flags, args)
 	}
 	// After a deploy that worked, keep a copy of exactly what was deployed: the next diff is against it.
 	remember := ""
@@ -734,6 +709,12 @@ func (s *Server) stackAction(w http.ResponseWriter, r *http.Request) {
 		script = base("up -d --remove-orphans") + remember
 	case "update":
 		script = base("pull") + " && " + base("up -d --remove-orphans") + remember
+	case "recreate":
+		// The way out of a container Docker will no longer start — most often one pinned to a
+		// network that has since been recreated, which answers "network … not found" to every
+		// ordinary deploy. `up -d` leaves such a container alone because its definition has
+		// not changed; only --force-recreate builds it again.
+		script = base("up -d --force-recreate --remove-orphans") + remember
 	case "restart":
 		script = base("restart")
 	case "stop":
@@ -741,7 +722,7 @@ func (s *Server) stackAction(w http.ResponseWriter, r *http.Request) {
 	case "down": // remove its containers and networks; its files, volumes and bind-mounted data stay
 		script = base("down --remove-orphans")
 	default:
-		jsonErr(w, 400, "deploy, update, restart, stop or down")
+		jsonErr(w, 400, "deploy, update, recreate, restart, stop or down")
 		return
 	}
 	if t, busy := s.tasks.RunningOf("stack:" + st.Name); busy {
@@ -763,7 +744,6 @@ func (s *Server) stackAction(w http.ResponseWriter, r *http.Request) {
 			_ = exec.CommandContext(ctx, dockerTool(), "exec", via, "pkill", "-TERM", "-f", pattern).Run()
 		})
 	}
-	stackUpdatesForget(r.PathValue("node") + "/" + st.Name)
 	log.Printf("stack %s: %s started as task %s (from %s)", st.Name, r.PathValue("action"), t.ID, clientIP(r))
 	jsonOK(w, 202, t.Snapshot(false))
 }
@@ -774,6 +754,7 @@ type imageCheck struct {
 	Image  string `json:"image"`
 	State  string `json:"state"` // current | update | unknown
 	Detail string `json:"detail,omitempty"`
+	remote string // the digest the registry named, so a later pull can be recognised without asking again
 }
 
 type updAnswer struct {
@@ -786,54 +767,56 @@ var (
 	updCache = map[string]updAnswer{}
 )
 
-func stackUpdatesForget(key string) { updMu.Lock(); delete(updCache, key); updMu.Unlock() }
+func stackUpdatesForget(name string) { updMu.Lock(); delete(updCache, "stack:"+name); updMu.Unlock() }
 
-// stackUpdates asks each image's registry for the digest its tag points at now and compares
-// it with the digest that was pulled. It is asked for, never polled: every answer is a
-// registry request, and Docker Hub counts those. Answers are kept for six hours.
-func (s *Server) stackUpdates(w http.ResponseWriter, r *http.Request) {
-	ctx, cancel := context.WithTimeout(r.Context(), 90*time.Second)
-	defer cancel()
-	st, handled, err := s.stackFor(ctx, r)
-	if !handled {
-		s.proxyNode(w, r)
-		return
-	}
-	if err != nil {
-		jsonErr(w, 404, err.Error())
-		return
-	}
-	key := r.PathValue("node") + "/" + st.Name
-	updMu.Lock()
-	c, ok := updCache[key]
-	updMu.Unlock()
-	refresh := r.URL.Query().Get("refresh") == "1"
-	if ok && time.Since(c.at) < 6*time.Hour && !refresh {
-		jsonOK(w, 200, map[string]any{"images": c.res, "checked": c.at.UnixMilli()})
-		return
-	}
-	if !refresh {
-		jsonOK(w, 200, map[string]any{"images": []imageCheck{}, "checked": 0})
-		return
-	}
-	local := func(args ...string) ([]byte, error) { // the Docker that holds the images
-		if st.Remote != "" {
-			args = append([]string{"-H", st.Remote}, args...)
-		}
-		return dockerRun(ctx, args...)
-	}
-	res := []imageCheck{}
-	for _, img := range st.Images {
-		ic := imageCheck{Image: img, State: "unknown"}
-		out, err := local("image", "inspect", "-f", "{{json .RepoDigests}}", img)
+// localDigests is what this machine holds for an image: the registry digests it was pulled as.
+func localDigests(ctx context.Context, img string) []string {
+	out, err := dockerRun(ctx, "image", "inspect", "-f", "{{json .RepoDigests}}", img)
 	var have []string
-		if err != nil || json.Unmarshal(bytes.TrimSpace(out), &have) != nil || len(have) == 0 {
+	if err != nil || json.Unmarshal(bytes.TrimSpace(out), &have) != nil {
+		return nil
+	}
+	return have
+}
+
+func holdsDigest(have []string, digest string) bool {
+	for _, h := range have {
+		if strings.HasSuffix(h, "@"+digest) {
+			return true
+		}
+	}
+	return false
+}
+
+// settled is a cached answer brought up to date with what is here now. The registry's side
+// is kept for six hours, but this machine's side changes the moment an update pulls the
+// newer image — so an image marked behind is looked at again locally, which costs no
+// registry request, and is current once it holds the digest the registry named.
+func settled(ctx context.Context, res []imageCheck) []imageCheck {
+	out := make([]imageCheck, len(res))
+	copy(out, res)
+	for i, ic := range out {
+		if ic.State == "update" && ic.remote != "" && holdsDigest(localDigests(ctx, ic.Image), ic.remote) {
+			out[i].State = "current"
+		}
+	}
+	return out
+}
+
+// checkImages asks the registry whether each image is still the one we hold. Each image is
+// one registry request, which Docker Hub counts — so this is only ever called when asked for.
+func checkImages(ctx context.Context, images []string) []imageCheck {
+	res := []imageCheck{}
+	for _, img := range images {
+		ic := imageCheck{Image: img, State: "unknown"}
+		have := localDigests(ctx, img)
+		if len(have) == 0 {
 			ic.Detail = "built or loaded here, not pulled from a registry"
 			res = append(res, ic)
 			continue
 		}
-		remote, err := dockerRun(ctx, "buildx", "imagetools", "inspect", img, "--format", "{{.Manifest.Digest}}")
-		digest := strings.TrimSpace(string(remote))
+		rem, err := dockerRun(ctx, "buildx", "imagetools", "inspect", img, "--format", "{{.Manifest.Digest}}")
+		digest := strings.TrimSpace(string(rem))
 		if i := strings.LastIndex(digest, "\n"); i >= 0 {
 			digest = digest[i+1:]
 		}
@@ -845,91 +828,117 @@ func (s *Server) stackUpdates(w http.ResponseWriter, r *http.Request) {
 			res = append(res, ic)
 			continue
 		}
-		ic.State = "update"
-		for _, h := range have {
-			if strings.HasSuffix(h, "@"+digest) {
+		ic.State, ic.remote = "update", digest
+		if holdsDigest(have, digest) {
 			ic.State = "current"
 		}
-		}
 		res = append(res, ic)
 	}
+	return res
+}
+
+// machineUpdates checks every image on this machine in one pass, so the container list can
+// be coloured and "what is behind?" answered without walking stack by stack.
+func (s *Server) machineUpdates(w http.ResponseWriter, r *http.Request) {
+	if dockerTool() == "" { // no Docker is an empty answer, not a failure
+		jsonOK(w, 200, map[string]any{"images": []imageCheck{}, "checked": 0, "stacks": map[string][]string{}})
+		return
+	}
+	ctx, cancel := context.WithTimeout(r.Context(), 10*time.Minute)
+	defer cancel()
+	stacks, err := s.findStacks(ctx)
+	if err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	// one entry per image, however many stacks use it
+	byImage := map[string][]string{} // image -> stacks
+	for _, st := range stacks {
+		for _, img := range st.Images {
+			byImage[img] = append(byImage[img], st.Name)
+		}
+	}
+	refresh := r.URL.Query().Get("refresh") == "1"
+	key := "machine"
+	updMu.Lock()
+	c, ok := updCache[key]
+	updMu.Unlock()
+	if ok && time.Since(c.at) < 6*time.Hour && !refresh {
+		jsonOK(w, 200, map[string]any{"images": settled(ctx, c.res), "checked": c.at.UnixMilli(), "stacks": byImage})
+		return
+	}
+	if !refresh {
+		jsonOK(w, 200, map[string]any{"images": []imageCheck{}, "checked": 0, "stacks": byImage})
+		return
+	}
+	var list []string
+	for img := range byImage {
+		list = append(list, img)
+	}
+	sort.Strings(list)
+	res := checkImages(ctx, list)
+	updMu.Lock()
+	updCache[key] = updAnswer{time.Now(), res}
+	updMu.Unlock()
+	jsonOK(w, 200, map[string]any{"images": res, "checked": time.Now().UnixMilli(), "stacks": byImage})
+}
+
+// stackUpdates asks each image's registry for the digest its tag points at now and compares
+// it with the digest that was pulled. It is asked for, never polled: every answer is a
+// registry request, and Docker Hub counts those. Answers are kept for six hours.
+func (s *Server) stackUpdates(w http.ResponseWriter, r *http.Request) {
+	ctx, cancel := context.WithTimeout(r.Context(), 90*time.Second)
+	defer cancel()
+	st, err := s.stackFor(ctx, r)
+	if err != nil {
+		jsonErr(w, 404, err.Error())
+		return
+	}
+	key := "stack:" + st.Name
+	updMu.Lock()
+	c, ok := updCache[key]
+	updMu.Unlock()
+	refresh := r.URL.Query().Get("refresh") == "1"
+	if ok && time.Since(c.at) < 6*time.Hour && !refresh {
+		jsonOK(w, 200, map[string]any{"images": settled(ctx, c.res), "checked": c.at.UnixMilli()})
+		return
+	}
+	if !refresh {
+		jsonOK(w, 200, map[string]any{"images": []imageCheck{}, "checked": 0})
+		return
+	}
+	res := checkImages(ctx, st.Images)
 	updMu.Lock()
 	updCache[key] = updAnswer{time.Now(), res}
 	updMu.Unlock()
 	jsonOK(w, 200, map[string]any{"images": res, "checked": time.Now().UnixMilli()})
 }
 
-// taskOnHub serves a task this hub is running for one of its nodes' stacks; anything else
-// under /api/nodes/<node>/tasks belongs to the node.
-func (s *Server) taskOnHub(local http.HandlerFunc) http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		if _, ok := s.tasks.Get(r.PathValue("id")); ok {
-			local(w, r)
-			return
-		}
-		s.proxyNode(w, r)
-	}
-}
-
 // ---- making and unmaking stacks ----
 
 var stackNameRe = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]{0,62}$`)
 
-// homesFor is where a new stack could go, seen from this request: this machine's homes, or —
-// on a hub route — the node's own homes plus the ones this hub holds for it.
-func (s *Server) homesFor(ctx context.Context, r *http.Request) ([]stackHome, error) {
-	node := r.PathValue("node")
-	if node == "" {
+// homesFor is where a new stack could go on this machine.
+func (s *Server) homesFor(ctx context.Context) ([]stackHome, error) {
 	stacks, err := s.findStacks(ctx)
 	if err != nil {
 		return nil, err
 	}
-		return s.homesOf(stacks, true), nil
-	}
-	stacks, err := s.hubStacks(ctx, node)
-	if err != nil {
-		return nil, err
-	}
-	var held []stack
-	for _, st := range stacks {
-		if st.HeldBy != "" {
-			held = append(held, st)
-		}
-	}
-	homes := s.homesOf(held, false)
-	if code, b, err := s.nodes.Do(ctx, node, "GET", "/api/docker/stacks/homes", nil, nil); err == nil && code == 200 {
-		var res struct{ Homes []stackHome }
-		if json.Unmarshal(b, &res) == nil {
-			for _, h := range res.Homes {
-				if len(homes) > 0 && h.Stacks == 0 {
-					continue // the node's empty ~/stacks is only worth offering when there is nothing else
-				}
-				h.Default = false
-				homes = append(homes, h)
-			}
-		}
-	}
-	if len(homes) > 0 {
-		homes[0].Default = true
-	}
-	return homes, nil
+	return s.homesOf(stacks), nil
 }
 
 func (s *Server) stackHomes(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), 40*time.Second)
 	defer cancel()
-	if dockerTool() == "" && r.PathValue("node") == "" {
+	if dockerTool() == "" {
 		jsonOK(w, 200, map[string]any{"homes": []stackHome{}})
 		return
 	}
-	homes, err := s.homesFor(ctx, r)
+	homes, err := s.homesFor(ctx)
 	if err != nil {
 		jsonErr(w, 500, err.Error())
 		return
 	}
-	if homes == nil { // a machine with no Docker and nothing held for it: an empty list, never null
-		homes = []stackHome{}
-	}
 	jsonOK(w, 200, map[string]any{"homes": homes})
 }
 
@@ -956,7 +965,7 @@ func (s *Server) stackCreate(w http.ResponseWriter, r *http.Request) {
 		jsonErr(w, 400, "the compose file can't be empty")
 		return
 	}
-	homes, err := s.homesFor(ctx, r)
+	homes, err := s.homesFor(ctx)
 	if err != nil {
 		jsonErr(w, 500, err.Error())
 		return
@@ -971,17 +980,7 @@ func (s *Server) stackCreate(w http.ResponseWriter, r *http.Request) {
 		jsonErr(w, 400, "that isn't one of the places this machine keeps stacks")
 		return
 	}
-	if r.PathValue("node") != "" && home.HeldBy == "" { // the node's own folder: the node makes it
-		r.Body, r.ContentLength = io.NopCloser(bytes.NewReader(raw)), int64(len(raw))
-		s.proxyNode(w, r)
-		return
-	}
-	var all []stack
-	if node := r.PathValue("node"); node != "" {
-		all, _ = s.hubStacks(ctx, node)
-	} else {
-		all, _ = s.findStacks(ctx)
-	}
+	all, _ := s.findStacks(ctx)
 	for _, st := range all {
 		if st.Name == name {
 			jsonErr(w, 409, "there is already a stack called "+name)
@@ -1043,7 +1042,7 @@ func (s *Server) stackCreate(w http.ResponseWriter, r *http.Request) {
 		_ = sudo("chmod", "600", filepath.Join(dir, ".env")) // it is where the secrets go
 	}
 	st := stack{Name: name, Containers: []string{}, Images: []string{}, HostFiles: []string{host}, HostFile: host, Files: []string{filepath.Join(home.Inner, name, "compose.yaml")},
-		Via: home.Via, Remote: home.Remote, HeldBy: home.HeldBy, Editable: true, Note: "not deployed", HasEnv: strings.TrimSpace(body.Env) != ""}
+		Via: home.Via, Editable: true, Note: "not deployed", HasEnv: strings.TrimSpace(body.Env) != ""}
 	st.File = st.Files[0]
 	if msg, err := composeCmd(ctx, st, seenFiles(st, -1, ""), "config", "-q").CombinedOutput(); err != nil {
 		undo()
@@ -1062,12 +1061,7 @@ func (s *Server) stackDelete(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), 4*time.Minute)
 	defer cancel()
 	raw, _ := io.ReadAll(io.LimitReader(r.Body, 4096))
-	st, handled, err := s.stackFor(ctx, r)
-	if !handled {
-		r.Body, r.ContentLength = io.NopCloser(bytes.NewReader(raw)), int64(len(raw))
-		s.proxyNode(w, r)
-		return
-	}
+	st, err := s.stackFor(ctx, r)
 	if err != nil || !st.Editable {
 		jsonErr(w, 404, "that stack's compose file isn't anywhere this console can reach")
 		return
@@ -1105,7 +1099,7 @@ func (s *Server) stackDelete(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 	_ = run("rmdir", dir) // only if nothing else was in it
-	stackUpdatesForget(r.PathValue("node") + "/" + st.Name)
+	stackUpdatesForget(st.Name)
 	log.Printf("stack %s: taken down and %d file(s) moved to %s (from %s)", st.Name, moved, trash, clientIP(r))
 	jsonOK(w, 200, map[string]any{"trash": trash, "moved": moved})
 }

internal/api/stacks_test.go

@@ -0,0 +1,156 @@
+package api
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"hamlab/internal/compose"
+	"hamlab/internal/config"
+	"hamlab/internal/store"
+)
+
+// A stack deployed by an orchestrator running in a container records the path its compose
+// file had inside that container. Resolving it has to work both while the orchestrator is
+// running — compose is then run inside it — and after it has been removed, where the same
+// mount is only remembered and compose has to run on the host instead.
+func TestResolveThroughMounts(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "orch", "stacks", "app")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	file := filepath.Join(dir, "compose.yaml")
+	if err := os.WriteFile(file, []byte("services: {}\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	inner := "/app/data/stacks/app/compose.yaml"
+
+	for _, tc := range []struct {
+		name, container, wantVia string
+	}{
+		{"orchestrator running", "orch", "orch"},
+		{"orchestrator removed", "", ""},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			st := stack{Name: "app", File: inner, Files: []string{inner}}
+			st.resolve([]mountMap{{tc.container, "/app/data", filepath.Join(root, "orch")}})
+			if !st.Editable {
+				t.Fatalf("not editable: %s", st.Note)
+			}
+			if st.HostFile != file {
+				t.Errorf("host file = %q, want %q", st.HostFile, file)
+			}
+			if st.Via != tc.wantVia {
+				t.Errorf("via = %q, want %q", st.Via, tc.wantVia)
+			}
+		})
+	}
+
+	// Nothing explains the path: the stack is listed, but read-only and says why.
+	st := stack{Name: "app", File: inner, Files: []string{inner}}
+	st.resolve(nil)
+	if st.Editable || st.Note == "" {
+		t.Errorf("unresolvable stack should be read-only with a note, got editable=%v note=%q", st.Editable, st.Note)
+	}
+}
+
+// Every file of a multi-file stack must resolve through the same place. Redeploying from
+// the first file alone would silently drop whatever the override set.
+func TestResolveRefusesSplitStack(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "orch", "stacks", "app")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "compose.yaml"), []byte("services: {}\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	st := stack{Name: "app", File: "/app/data/stacks/app/compose.yaml", Files: []string{
+		"/app/data/stacks/app/compose.yaml",
+		"/app/data/stacks/app/override.yaml", // never written: not on disk
+	}}
+	st.resolve([]mountMap{{"orch", "/app/data", filepath.Join(root, "orch")}})
+	if st.Editable {
+		t.Error("a stack with a file that cannot be found should not be editable")
+	}
+}
+
+// A schedule made while an orchestrator was running says "run compose inside that
+// container". When the container is gone the schedule must still work, against the same
+// files on the host — otherwise retiring the orchestrator silently breaks every scheduled
+// update made before it went.
+func TestRepointSurvivesAMissingContainer(t *testing.T) {
+	root := t.TempDir()
+	dir := filepath.Join(root, "orch", "stacks", "app")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	host := filepath.Join(dir, "compose.yaml")
+	if err := os.WriteFile(host, []byte("services: {}\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	db, err := store.Open(filepath.Join(root, "state.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.Update(func(st *store.State) {
+		st.Mounts = []store.RememberedMount{{Container: "gone-orchestrator", Dest: "/app/data", Src: filepath.Join(root, "orch")}}
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	in := compose.Spec{Project: "app", Files: []string{"/app/data/stacks/app/compose.yaml"}, Via: "gone-orchestrator", Tool: "docker"}
+	got := repoint(context.Background(), db, in)
+	if got.Via != "" {
+		t.Errorf("via = %q, want it dropped", got.Via)
+	}
+	if len(got.Files) != 1 || got.Files[0] != host {
+		t.Errorf("files = %v, want [%s]", got.Files, host)
+	}
+
+	// Nothing remembered: the schedule is left exactly as it was rather than pointed at a
+	// guess. It will fail loudly, which is better than deploying the wrong file.
+	empty, err := store.Open(filepath.Join(root, "empty.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := repoint(context.Background(), empty, in); got.Via != in.Via || len(got.Files) != 1 || got.Files[0] != in.Files[0] {
+		t.Errorf("unresolvable spec was changed: %+v", got)
+	}
+}
+
+// Where new stacks go: Ham Lab's own <data dir>/stacks is always offered, first and as the
+// default, whether or not anything is in it yet. A folder this machine already keeps stacks
+// in — two or more deployed from it — is offered too, but never ahead of Ham Lab's own.
+func TestHomesDefaultToDataDir(t *testing.T) {
+	root := t.TempDir()
+	cfg := config.Default(filepath.Join(root, "data", "config.json"))
+	s := &Server{cfg: cfg}
+	own := filepath.Join(root, "data", "stacks")
+	legacy := filepath.Join(root, "home", "stacks", "box")
+	deployed := func(dir, name string) stack {
+		f := filepath.Join(dir, name, "compose.yaml")
+		return stack{Name: name, Containers: []string{name + "-1"}, Files: []string{f}, File: f, HostFiles: []string{f}, HostFile: f, Editable: true}
+	}
+
+	// Nothing deployed anywhere: one home, Ham Lab's own.
+	homes := s.homesOf(nil)
+	if len(homes) != 1 || homes[0].Dir != own || !homes[0].Default {
+		t.Fatalf("empty machine: homes = %+v, want just %s as default", homes, own)
+	}
+
+	// Two stacks deployed from a pre-existing folder: it is offered, after Ham Lab's own.
+	homes = s.homesOf([]stack{deployed(legacy, "a"), deployed(legacy, "b")})
+	if len(homes) != 2 || homes[0].Dir != own || !homes[0].Default || homes[1].Dir != legacy || homes[1].Default || homes[1].Stacks != 2 {
+		t.Fatalf("legacy folder: homes = %+v, want [%s (default), %s]", homes, own, legacy)
+	}
+
+	// One lone stack elsewhere says nothing about where the next should go; one in Ham Lab's
+	// own folder is already home.
+	homes = s.homesOf([]stack{deployed(filepath.Join(root, "home", "apps"), "orchestrator"), deployed(own, "c")})
+	if len(homes) != 1 || homes[0].Dir != own || homes[0].Stacks != 1 || !homes[0].Default {
+		t.Fatalf("lone stacks: homes = %+v, want just %s", homes, own)
+	}
+}

internal/api/thumbs.go

@@ -0,0 +1,418 @@
+package api
+
+// Previews for the Files tab: GET /api/files/thumb hands back one small JPEG of an image or
+// a video, made by internal/thumbs and kept in <data dir>/thumbs.db. The work is bounded
+// two ways — a handful of ffmpegs at once, and one per file however many rows ask for it —
+// because a folder of a thousand photos asks for every row the moment previews go on.
+//
+// Root mode (?sudo=1) makes the preview through the same root helper the file reads use,
+// so a file only root can read gets a preview too, and the probe runs as root as well: root
+// opens every render node, whatever groups the daemon's user has.
+
+import (
+	"context"
+	"errors"
+	"log"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"hamlab/internal/media"
+	"hamlab/internal/priv"
+)
+
+const thumbSize = 256
+const thumbTimeout = 30 * time.Second
+const capsTTL = 10 * time.Minute // how long a probe is believed; a refresh after an install or a group change does not wait
+
+type thumbSvc struct {
+	cache *media.Cache
+	self  string
+	sem   chan struct{}
+	mu    sync.Mutex
+	caps  map[bool]*capsEntry // keyed by root
+	calls map[string]*thumbCall
+}
+
+type capsEntry struct {
+	mu   sync.Mutex
+	caps media.Caps
+	err  error
+	at   time.Time
+}
+
+type thumbCall struct {
+	done chan struct{}
+	res  media.Result
+	err  error
+}
+
+func newThumbSvc(dataDir, self string) *thumbSvc {
+	n := runtime.NumCPU() / 2 // each ffmpeg is itself threaded; previews must not take the whole machine
+	if n < 2 {
+		n = 2
+	}
+	if n > 4 {
+		n = 4
+	}
+	return &thumbSvc{cache: media.NewCache(filepath.Join(dataDir, "thumbs.db")), self: self, sem: make(chan struct{}, n), caps: map[bool]*capsEntry{}, calls: map[string]*thumbCall{}}
+}
+
+// capsFor is what previews can be made with, probed once and kept for a while.
+func (t *thumbSvc) capsFor(ctx context.Context, root, refresh bool) (media.Caps, error) {
+	t.mu.Lock()
+	e := t.caps[root]
+	if e == nil {
+		e = &capsEntry{}
+		t.caps[root] = e
+	}
+	t.mu.Unlock()
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	if !refresh && !e.at.IsZero() && time.Since(e.at) < capsTTL {
+		return e.caps, e.err
+	}
+	if root {
+		e.caps, e.err = media.ProbeRoot(ctx, t.self)
+	} else {
+		e.caps, e.err = media.Probe(ctx), nil
+	}
+	e.at = time.Now()
+	mode := "as " + map[bool]string{false: "the daemon", true: "root"}[root]
+	switch {
+	case e.err != nil:
+		log.Printf("thumbs: probe %s failed: %v", mode, e.err)
+	case e.caps.Error != "":
+		log.Printf("thumbs: %s: %s", mode, e.caps.Error)
+	default:
+		log.Printf("thumbs: %s: ffmpeg %s, %s", mode, e.caps.Version, describeCaps(e.caps))
+	}
+	return e.caps, e.err
+}
+
+// describeCaps is the one line that says how previews get made here.
+func describeCaps(c media.Caps) string {
+	if len(c.GPUs) == 0 {
+		return "CPU only"
+	}
+	parts := make([]string, 0, len(c.GPUs))
+	for _, g := range c.GPUs {
+		name := g.Name
+		if name == "" {
+			name = g.Device
+		}
+		p := name + " (" + g.API
+		if len(g.Codecs) > 0 {
+			p += ": " + strings.Join(g.Codecs, ", ")
+		}
+		parts = append(parts, p+")")
+	}
+	return "GPU " + strings.Join(parts, ", ")
+}
+
+// make produces a preview, sharing the work when the same file is asked for twice at once.
+func (t *thumbSvc) make(ctx context.Context, root bool, key, path string) (media.Result, error) {
+	t.mu.Lock()
+	if c, ok := t.calls[key]; ok {
+		t.mu.Unlock()
+		select {
+		case <-c.done:
+			return c.res, c.err
+		case <-ctx.Done():
+			return media.Result{}, ctx.Err()
+		}
+	}
+	c := &thumbCall{done: make(chan struct{})}
+	t.calls[key] = c
+	t.mu.Unlock()
+	defer func() {
+		t.mu.Lock()
+		delete(t.calls, key)
+		t.mu.Unlock()
+		close(c.done)
+	}()
+	// The work itself runs on a context of its own: the first requester going away must not
+	// cancel a preview three other rows are waiting for.
+	wctx, cancel := context.WithTimeout(context.Background(), thumbTimeout+5*time.Second)
+	defer cancel()
+	select {
+	case t.sem <- struct{}{}:
+		defer func() { <-t.sem }()
+	case <-ctx.Done():
+		c.err = ctx.Err()
+		return c.res, c.err
+	}
+	caps, err := t.capsFor(wctx, root, false)
+	if err != nil {
+		c.err = err
+		return c.res, c.err
+	}
+	o := media.Opts{Size: thumbSize, Timeout: thumbTimeout}
+	if root {
+		c.res, c.err = media.MakeRoot(wctx, t.self, caps, path, o)
+	} else {
+		c.res, c.err = media.Make(wctx, caps, path, o)
+	}
+	return c.res, c.err
+}
+
+// ---- handlers ----
+
+// filesThumb: GET /api/files/thumb?path=…&v=<mtime>-<size>[&sudo=1]. v is the client's idea of
+// the file, from its listing; it makes a cache hit free of a stat, and a changed file a new URL.
+func (s *Server) filesThumb(w http.ResponseWriter, r *http.Request) {
+	fsys, ok := s.fsFor(w, r)
+	if !ok {
+		return
+	}
+	p, ok := cleanQuery(w, r, "path")
+	if !ok {
+		return
+	}
+	if media.Kind(p) == "" {
+		jsonErr(w, 415, "no preview for this kind of file")
+		return
+	}
+	root := r.URL.Query().Get("sudo") == "1"
+	if mt, sz, ok := parseV(r.URL.Query().Get("v")); ok {
+		key := media.Key(p, sz, mt)
+		if r.Header.Get("If-None-Match") == `"`+key+`"` {
+			w.WriteHeader(304)
+			return
+		}
+		if s.serveCachedThumb(w, key) {
+			return
+		}
+	}
+	in, err := fsys.Stat(r.Context(), p)
+	if err != nil {
+		fsErr(w, err)
+		return
+	}
+	if in.Type == "dir" || in.Type == "other" || in.Broken {
+		jsonErr(w, 400, "not a regular file")
+		return
+	}
+	key := media.Key(p, in.Size, in.Mtime)
+	if s.serveCachedThumb(w, key) {
+		return
+	}
+	res, err := s.thumbs.make(r.Context(), root, key, p)
+	if err != nil {
+		var de *media.DecodeError
+		switch {
+		case errors.As(err, &de):
+			if err := s.thumbs.cache.Put(key, media.Entry{Path: p, Failure: de.Msg}); err != nil {
+				log.Printf("thumbs: cache: %v", err)
+			}
+			log.Printf("thumbs: %s: %s", p, de.Msg)
+			jsonErr(w, 422, de.Msg)
+		case errors.Is(err, context.DeadlineExceeded):
+			log.Printf("thumbs: %s: timed out", p)
+			jsonErr(w, 504, "preview timed out")
+		case errors.Is(err, context.Canceled):
+			jsonErr(w, 499, "cancelled")
+		default:
+			jsonErr(w, 503, err.Error())
+		}
+		return
+	}
+	if err := s.thumbs.cache.Put(key, media.Entry{Path: p, Engine: res.Engine, Codec: res.Codec, Width: res.Width, Height: res.Height, JPEG: res.JPEG}); err != nil {
+		log.Printf("thumbs: cache: %v", err)
+	}
+	writeThumb(w, key, res.JPEG, res.Engine)
+}
+
+// serveCachedThumb answers from the cache when it can. A cache that cannot be read is a
+// miss: the preview is made again rather than refused.
+func (s *Server) serveCachedThumb(w http.ResponseWriter, key string) bool {
+	e, found, err := s.thumbs.cache.Get(key)
+	if err != nil {
+		log.Printf("thumbs: cache: %v", err)
+	}
+	switch {
+	case !found:
+		return false
+	case e.Failure != "":
+		jsonErr(w, 422, e.Failure)
+	default:
+		writeThumb(w, key, e.JPEG, "cache ("+e.Engine+")")
+	}
+	return true
+}
+
+func writeThumb(w http.ResponseWriter, key string, jpeg []byte, engine string) {
+	w.Header().Set("Content-Type", "image/jpeg")
+	w.Header().Set("Content-Length", strconv.Itoa(len(jpeg)))
+	w.Header().Set("Cache-Control", "private, max-age=604800")
+	w.Header().Set("ETag", `"`+key+`"`)
+	w.Header().Set("X-Hamlab-Thumb", engine)
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+	_, _ = w.Write(jpeg)
+}
+
+func parseV(v string) (mtime, size int64, ok bool) {
+	a, b, found := strings.Cut(v, "-")
+	if !found {
+		return 0, 0, false
+	}
+	mtime, err1 := strconv.ParseInt(a, 10, 64)
+	size, err2 := strconv.ParseInt(b, 10, 64)
+	return mtime, size, err1 == nil && err2 == nil
+}
+
+type thumbStatus struct {
+	OK       bool          `json:"ok"`
+	Engine   string        `json:"engine"` // gpu | cpu | ""
+	Summary  string        `json:"summary"`
+	FFmpeg   string        `json:"ffmpeg,omitempty"`
+	GPUs     []media.GPU   `json:"gpus"`
+	Unusable []media.GPU   `json:"unusable,omitempty"`
+	Error    string        `json:"error,omitempty"`
+	Install  *thumbInstall `json:"install,omitempty"` // ffmpeg is missing and this can put it on
+	GPUFix   bool          `json:"gpu_fix,omitempty"` // a render node is there but closed to the daemon's user, and this can open it
+	User     string        `json:"user"`
+	Cache    thumbCache    `json:"cache"`
+}
+
+type thumbCache struct {
+	Path    string `json:"path"`
+	Entries int64  `json:"entries"`
+	Bytes   int64  `json:"bytes"`
+}
+
+type thumbInstall struct {
+	PM      string `json:"pm"`
+	Package string `json:"package"`
+}
+
+// thumbsStatus: GET /api/files/thumbs[?sudo=1][&refresh=1] — how previews get made on this machine.
+func (s *Server) thumbsStatus(w http.ResponseWriter, r *http.Request) {
+	root := r.URL.Query().Get("sudo") == "1"
+	if root && s.fsSudo == nil {
+		jsonErr(w, 403, "root access needs passwordless sudo on the host")
+		return
+	}
+	caps, err := s.thumbs.capsFor(r.Context(), root, r.URL.Query().Get("refresh") == "1")
+	st := thumbStatus{GPUs: []media.GPU{}, User: s.user, Cache: thumbCache{Path: s.thumbs.cache.Path}}
+	st.Cache.Entries, st.Cache.Bytes = s.thumbs.cache.Stats()
+	if root {
+		st.User = "root"
+	}
+	if err != nil {
+		st.Error = err.Error()
+		jsonOK(w, 200, st)
+		return
+	}
+	st.FFmpeg, st.GPUs, st.Unusable, st.Error = caps.Version, caps.GPUs, caps.Unusable, caps.Error
+	if st.GPUs == nil {
+		st.GPUs = []media.GPU{}
+	}
+	st.OK = caps.Error == ""
+	switch {
+	case !st.OK:
+		if pkg := ffmpegPackage(s.updates.PM()); pkg != "" && priv.Available() {
+			st.Install = &thumbInstall{PM: s.updates.PM(), Package: pkg}
+		}
+		st.Summary = st.Error
+	case len(caps.GPUs) > 0:
+		st.Engine = "gpu"
+		st.Summary = describeCaps(caps) + " · images on the CPU"
+	default:
+		st.Engine = "cpu"
+		st.Summary = "CPU only"
+	}
+	if !root {
+		for _, g := range caps.Unusable {
+			if g.Permission && gpuFixPossible() {
+				st.GPUFix = true
+			}
+		}
+	}
+	jsonOK(w, 200, st)
+}
+
+// ffmpegPackage is what to install for ffmpeg on a package manager. Fedora ships it as
+// ffmpeg-free; the others under its own name.
+func ffmpegPackage(pm string) string {
+	switch pm {
+	case "":
+		return ""
+	case "dnf":
+		if b, _ := os.ReadFile("/etc/os-release"); strings.Contains(string(b), "ID=fedora") {
+			return "ffmpeg-free"
+		}
+	}
+	return "ffmpeg"
+}
+
+const hamlabUnit = "/etc/systemd/system/hamlab.service"
+
+// gpuFixPossible: the daemon is an ordinary user under systemd, with root to hand.
+func gpuFixPossible() bool {
+	if os.Geteuid() == 0 || !priv.Available() {
+		return false
+	}
+	_, err := os.Stat(hamlabUnit)
+	return err == nil
+}
+
+// thumbsInstall: POST /api/files/thumbs/install — put ffmpeg on with the machine's package manager.
+func (s *Server) thumbsInstall(w http.ResponseWriter, r *http.Request) {
+	pkg := ffmpegPackage(s.updates.PM())
+	if pkg == "" {
+		jsonErr(w, 400, "no supported package manager on this machine")
+		return
+	}
+	t, err := s.updates.Install([]string{pkg})
+	if err != nil {
+		jsonErr(w, 400, err.Error())
+		return
+	}
+	log.Printf("thumbs: installing %s as task %s (from %s)", pkg, t.ID, clientIP(r))
+	jsonOK(w, 202, t.Snapshot(false))
+}
+
+// gpuAccessScript gives hamlab.service the groups that own the render nodes, by a drop-in,
+// then restarts it: a running process cannot gain a group.
+const gpuAccessScript = `set -e
+unit=` + hamlabUnit + `
+[ -f "$unit" ] || { echo "no $unit: this machine does not run Ham Lab under systemd"; exit 1; }
+groups=""
+for g in render video; do
+  if getent group "$g" >/dev/null 2>&1; then groups="$groups $g"; fi
+done
+[ -n "$groups" ] || { echo "neither a render nor a video group exists here"; exit 1; }
+mkdir -p "$unit.d"
+printf '[Service]\nSupplementaryGroups=%s\n' "${groups# }" > "$unit.d/gpu.conf"
+echo "hamlab.service: supplementary groups${groups} ($unit.d/gpu.conf)"
+systemctl daemon-reload
+echo 'Ham Lab restarts in 3 seconds to pick up its new groups; the page reconnects by itself.'
+systemd-run --quiet --on-active=3 --unit=hamlab-gpu-restart systemctl restart hamlab.service
+`
+
+// thumbsGPUAccess: POST /api/files/thumbs/gpu-access — open the render nodes to the daemon.
+func (s *Server) thumbsGPUAccess(w http.ResponseWriter, r *http.Request) {
+	if !gpuFixPossible() {
+		jsonErr(w, 400, "nothing to do: Ham Lab is root, has no root, or is not under systemd here")
+		return
+	}
+	if t, busy := s.tasks.RunningOf("thumbs:gpu"); busy { // a second run would only collide with the first's restart timer
+		jsonErr(w, 409, "already being done (task "+t.ID+")")
+		return
+	}
+	full := priv.Wrap("sh", "-c", gpuAccessScript)
+	t, err := s.tasks.Start("thumbs:gpu", "give Ham Lab access to the GPU", exec.Command(full[0], full[1:]...))
+	if err != nil {
+		jsonErr(w, 400, err.Error())
+		return
+	}
+	log.Printf("thumbs: GPU access drop-in as task %s, restart follows (from %s)", t.ID, clientIP(r))
+	jsonOK(w, 202, t.Snapshot(false))
+}

internal/api/updates_test.go

@@ -0,0 +1,47 @@
+package api
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// fakeDocker puts a `docker` on PATH whose `image inspect` answers with the given RepoDigests.
+func fakeDocker(t *testing.T, digests string) {
+	t.Helper()
+	dir := t.TempDir()
+	script := "#!/bin/sh\necho '" + digests + "'\n"
+	if err := os.WriteFile(filepath.Join(dir, "docker"), []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", dir)
+}
+
+// An update pulls the newer image: the cached registry answer must not keep calling it behind.
+func TestSettledSeesAPulledImage(t *testing.T) {
+	cached := []imageCheck{
+		{Image: "nginx:alpine", State: "update", remote: "sha256:new"},
+		{Image: "redis:7", State: "current", remote: "sha256:r"},
+		{Image: "local/thing", State: "unknown"},
+	}
+	fakeDocker(t, `["nginx@sha256:new"]`)
+	got := settled(context.Background(), cached)
+	if got[0].State != "current" {
+		t.Fatalf("pulled image still marked %q", got[0].State)
+	}
+	if got[1].State != "current" || got[2].State != "unknown" {
+		t.Fatalf("others changed: %+v", got)
+	}
+	if cached[0].State != "update" {
+		t.Fatal("settled wrote through to the cache")
+	}
+}
+
+func TestSettledKeepsAnImageStillBehind(t *testing.T) {
+	fakeDocker(t, `["nginx@sha256:old"]`)
+	got := settled(context.Background(), []imageCheck{{Image: "nginx:alpine", State: "update", remote: "sha256:new"}})
+	if got[0].State != "update" {
+		t.Fatalf("image not yet pulled marked %q", got[0].State)
+	}
+}

internal/api/users.go

@@ -12,6 +12,7 @@ import (
 	"io"
 	"log"
 	"net/http"
+	"strconv"
 	"strings"
 	"time"
 
@@ -26,6 +27,10 @@ type actor struct {
 	Session string // session ID, "" for a token
 	token   string // the raw cookie token, so a handler can spare the current session
 	Token   string // token name, "" for a session
+	// Guest marks a temporary look-around login, and Expires is when it stops working. What
+	// a guest may reach is decided in the middleware, not here; see internal/api/guests.go.
+	Guest   bool
+	Expires time.Time
 }
 
 type ctxKey int
@@ -44,6 +49,8 @@ func actorOf(r *http.Request) actor {
 // who names the caller for a log line: "core@10.0.0.5" for a person, "token:hub:core@…" for a hub.
 func (a actor) String() string {
 	switch {
+	case a.User != "" && a.Guest:
+		return "guest:" + a.User
 	case a.User != "":
 		return a.User
 	case a.Token != "":
@@ -59,7 +66,7 @@ func (s *Server) listUsers(w http.ResponseWriter, r *http.Request) {
 	counts := s.sessions.Count()
 	var out []map[string]any
 	s.cfg.View(func(c *config.Config) {
-		for _, u := range c.Users {
+		for _, u := range c.Accounts() { // guest logins are listed on their own, see listGuests
 			var seen any
 			if !u.LastSeen.IsZero() {
 				seen = u.LastSeen
@@ -84,6 +91,10 @@ func (s *Server) addUser(w http.ResponseWriter, r *http.Request) {
 		jsonErr(w, 400, "a user name is 1–32 lower-case letters, digits, . _ or -, starting with a letter or digit")
 		return
 	}
+	if strings.HasPrefix(name, guestPrefix) {
+		jsonErr(w, 400, "names starting with "+guestPrefix+" belong to guest logins")
+		return
+	}
 	if len(body.Password) < auth.MinPasswordLen {
 		jsonErr(w, 400, "password must be at least 12 characters")
 		return
@@ -141,7 +152,7 @@ func (s *Server) removeUser(w http.ResponseWriter, r *http.Request) {
 	}
 	found, last := false, false
 	if err := s.cfg.Update(func(c *config.Config) {
-		if len(c.Users) <= 1 {
+		if len(c.Accounts()) <= 1 { // guest logins don't keep the last real account alive
 			last = true
 			return
 		}
@@ -254,6 +265,29 @@ func (s *Server) revokeSession(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(204)
 }
 
+// revokeIdleSessions drops the caller's sessions that have not been used for ?hours (24 by
+// default): the scripts and headless browsers that signed in once and never came back,
+// without touching the phone that was used this morning.
+func (s *Server) revokeIdleSessions(w http.ResponseWriter, r *http.Request) {
+	a := actorOf(r)
+	if a.User == "" {
+		jsonErr(w, 403, "only a signed-in user may do that")
+		return
+	}
+	hours := 24
+	if h := r.URL.Query().Get("hours"); h != "" {
+		n, err := strconv.Atoi(h)
+		if err != nil || n < 1 || n > 24*365 {
+			jsonErr(w, 400, "hours is a whole number from 1 to 8760")
+			return
+		}
+		hours = n
+	}
+	n := s.sessions.RevokeIdle(a.User, a.token, time.Duration(hours)*time.Hour)
+	log.Printf("%d idle session(s) of %q revoked (idle > %dh, by %s)", n, a.User, hours, clientIP(r))
+	jsonOK(w, 200, map[string]int{"revoked": n})
+}
+
 func (s *Server) revokeOtherSessions(w http.ResponseWriter, r *http.Request) {
 	a := actorOf(r)
 	if a.User == "" {

internal/api/vpn.go

@@ -0,0 +1,115 @@
+package api
+
+// The VPN tab: this machine's WireGuard tunnels, who is on them, and — where the tunnel is
+// one this machine configures — adding, renaming and removing the devices that dial in.
+//
+// Per machine like every other tab: the tunnels shown and edited are the ones on the machine
+// in the switcher, which is the only honest way to show them, since the inbound server and an
+// outbound tunnel are different machines here.
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+
+	"hamlab/internal/vpn"
+)
+
+func (s *Server) vpnReport(w http.ResponseWriter, r *http.Request) {
+	jsonOK(w, 200, vpn.Look(r.Context()))
+}
+
+// tunnelOf finds the tunnel a request names, so every editing handler starts from the live
+// state rather than from whatever the page last saw.
+func (s *Server) tunnelOf(ctx context.Context, w http.ResponseWriter, name string) (vpn.Tunnel, bool) {
+	for _, t := range vpn.Look(ctx).Tunnels {
+		if t.Name == name {
+			if !t.Managed {
+				jsonErr(w, 400, vpn.ErrUnmanaged.Error())
+				return t, false
+			}
+			return t, true
+		}
+	}
+	jsonErr(w, 404, "no such tunnel on this machine")
+	return vpn.Tunnel{}, false
+}
+
+// addVPNPeer makes a device and hands back its profile. The profile holds a private key that
+// is generated for this call and stored nowhere, so it is the only time it can be read — the
+// same bargain as any password this console generates.
+func (s *Server) addVPNPeer(w http.ResponseWriter, r *http.Request) {
+	t, ok := s.tunnelOf(r.Context(), w, r.PathValue("iface"))
+	if !ok {
+		return
+	}
+	var body vpn.NewPeer
+	if err := json.NewDecoder(io.LimitReader(r.Body, 8<<10)).Decode(&body); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	made, err := vpn.AddPeer(r.Context(), t, body)
+	if err != nil {
+		code := 400
+		if errors.Is(err, vpn.ErrUnmanaged) {
+			code = 409
+		}
+		jsonErr(w, code, err.Error())
+		return
+	}
+	// The name and address are worth a log line; the profile is emphatically not.
+	log.Printf("vpn: device %q added to %s as %s (by %s)", made.Name, t.Name, made.Address, clientIP(r))
+	jsonOK(w, 200, made)
+}
+
+func (s *Server) editVPNPeer(w http.ResponseWriter, r *http.Request) {
+	t, ok := s.tunnelOf(r.Context(), w, r.PathValue("iface"))
+	if !ok {
+		return
+	}
+	var body struct{ Name, Address string }
+	if err := json.NewDecoder(io.LimitReader(r.Body, 4<<10)).Decode(&body); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	section := r.PathValue("section")
+	if err := vpn.EditPeer(r.Context(), t, section, body.Name, body.Address); err != nil {
+		jsonErr(w, 400, err.Error())
+		return
+	}
+	log.Printf("vpn: device %s on %s changed (by %s)", section, t.Name, clientIP(r))
+	w.WriteHeader(204)
+}
+
+func (s *Server) removeVPNPeer(w http.ResponseWriter, r *http.Request) {
+	t, ok := s.tunnelOf(r.Context(), w, r.PathValue("iface"))
+	if !ok {
+		return
+	}
+	section := r.PathValue("section")
+	var body struct{ Confirm string }
+	_ = json.NewDecoder(io.LimitReader(r.Body, 4<<10)).Decode(&body)
+	// The name has to be typed back. Removing a device is the one action here that cannot be
+	// undone — the key is gone and the profile on the device stops working — and it is one tap
+	// away from a list of devices that all look alike.
+	var want string
+	for _, p := range t.Peers {
+		if p.Section == section {
+			want = p.Name
+		}
+	}
+	if want != "" && !strings.EqualFold(strings.TrimSpace(body.Confirm), want) {
+		jsonErr(w, 400, "type the device's name to remove it")
+		return
+	}
+	if err := vpn.DeletePeer(r.Context(), t, section); err != nil {
+		jsonErr(w, 400, err.Error())
+		return
+	}
+	log.Printf("vpn: device %s (%s) removed from %s (by %s)", section, want, t.Name, clientIP(r))
+	w.WriteHeader(204)
+}

internal/api/zfs.go

@@ -0,0 +1,281 @@
+package api
+
+// The ZFS tab: pools, datasets, snapshots, and a schedule for taking and expiring them.
+//
+// grid already runs zfSnap from root cron and has done for longer than this repo has
+// existed, so this does not replace it. It reads the same snapshot names, expires by the
+// same rule, and surfaces the cron job that drives it — so what is on screen is the truth
+// about the machine, whether Ham Lab or zfSnap is doing the work. A Ham Lab schedule is for
+// a machine that has no such tool, and the page says plainly when both are running.
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"io"
+	"log"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"hamlab/internal/storage"
+	"hamlab/internal/store"
+)
+
+type zfsState struct {
+	Policies []storage.Policy `json:"policies"`
+}
+
+func (s *Server) zfsLoad() zfsState {
+	var raw json.RawMessage
+	s.store.View(func(st *store.State) { raw = st.ZFS })
+	var z zfsState
+	if len(raw) > 0 {
+		_ = json.Unmarshal(raw, &z)
+	}
+	if z.Policies == nil {
+		z.Policies = []storage.Policy{}
+	}
+	return z
+}
+
+func (s *Server) zfsSave(z zfsState) error {
+	b, err := json.Marshal(z)
+	if err != nil {
+		return err
+	}
+	return s.store.Update(func(st *store.State) { st.ZFS = b })
+}
+
+// externalSnapshotJob finds a cron job that is already taking snapshots on this machine, so
+// the page can say so rather than let two schedules quietly double up.
+func (s *Server) externalSnapshotJob(ctx context.Context) map[string]any {
+	if s.cron == nil {
+		return nil
+	}
+	ov := s.cron.Overview(ctx)
+	for _, j := range ov.Jobs {
+		if !j.Enabled {
+			continue
+		}
+		c := strings.ToLower(j.Command)
+		if !strings.Contains(c, "zfsnap") && !strings.Contains(c, "zfs-auto-snapshot") && !strings.Contains(c, "sanoid") &&
+			!(strings.Contains(c, "zfs ") && strings.Contains(c, "snapshot")) {
+			continue
+		}
+		return map[string]any{
+			"tool": toolName(c), "schedule": j.Schedule, "command": j.Command,
+			"user": j.User, "source": j.Source, "id": j.ID, "next": j.Next, "last": j.Last,
+		}
+	}
+	return nil
+}
+
+func toolName(cmd string) string {
+	switch {
+	case strings.Contains(cmd, "zfsnap"):
+		return "zfSnap"
+	case strings.Contains(cmd, "zfs-auto-snapshot"):
+		return "zfs-auto-snapshot"
+	case strings.Contains(cmd, "sanoid"):
+		return "sanoid"
+	}
+	return "a cron job"
+}
+
+// randomID is a short opaque id for a schedule.
+func randomID() (string, error) {
+	b := make([]byte, 6)
+	if _, err := rand.Read(b); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(b), nil
+}
+
+// ---- the cron file ----
+//
+// A schedule is a cron line, written to /etc/cron.d/hamlab-zfs, which Ham Lab owns and
+// rewrites whole whenever the schedules change. Nothing in the daemon runs them: snapshots
+// are backup-shaped and should not stop because a web console is down, being upgraded, or
+// uninstalled. The line calls `hamlab zfs-snapshot <id>` as the account Ham Lab runs as,
+// which reaches zfs through sudo exactly as the daemon does.
+
+// syncCron puts the current schedules on the machine.
+func (s *Server) syncCron(ctx context.Context, z zfsState) error {
+	exe, err := os.Executable()
+	if err != nil {
+		return err
+	}
+	exe, _ = filepath.EvalSymlinks(exe)
+	return s.storage.WriteCronFile(ctx, z.Policies, s.user, exe, s.cfg.Path())
+}
+
+// ---- endpoints ----
+
+func (s *Server) zfsOverview(w http.ResponseWriter, r *http.Request) {
+	z := s.zfsLoad()
+	now := time.Now()
+	dir := s.cfg.DataDir()
+	out := make([]map[string]any, 0, len(z.Policies))
+	for i := range z.Policies {
+		p := z.Policies[i]
+		expr, _ := p.CronExpr()
+		m := map[string]any{"policy": p, "cron": expr, "last": storage.ReadRun(dir, p.ID)}
+		if p.Enabled {
+			if n := p.NextRun(now); !n.IsZero() {
+				m["next"] = n
+			}
+		}
+		out = append(out, m)
+	}
+	jsonOK(w, 200, map[string]any{
+		"zfs": s.storage.ZFS(r.Context()), "policies": out, "external": s.externalSnapshotJob(r.Context()),
+	})
+}
+
+// zfsARC is the cache: the sampler's live ARC (size, the hit rate over the last interval)
+// beside the storage package's fuller picture (since-boot counters, tunables, and each
+// pool's cache/log/special devices or the lack of them).
+func (s *Server) zfsARC(w http.ResponseWriter, r *http.Request) {
+	out := map[string]any{"detail": s.storage.ARC(r.Context()), "live": nil}
+	if smp, ok := s.metrics.Latest(); ok && smp.ARC != nil {
+		out["live"] = smp.ARC
+	}
+	jsonOK(w, 200, out)
+}
+
+func (s *Server) zfsPolicyPut(w http.ResponseWriter, r *http.Request) {
+	var p storage.Policy
+	if err := json.NewDecoder(io.LimitReader(r.Body, 16<<10)).Decode(&p); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	if err := p.Validate(); err != nil {
+		jsonErr(w, 400, err.Error())
+		return
+	}
+	z := s.zfsLoad()
+	found := false
+	for i := range z.Policies {
+		if z.Policies[i].ID == p.ID && p.ID != "" {
+			z.Policies[i] = p
+			found = true
+		}
+	}
+	if !found {
+		if p.ID == "" {
+			id, err := randomID()
+			if err != nil {
+				jsonErr(w, 500, err.Error())
+				return
+			}
+			p.ID = id
+		}
+		z.Policies = append(z.Policies, p)
+	}
+	if err := s.zfsSave(z); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	if err := s.syncCron(r.Context(), z); err != nil {
+		jsonErr(w, 500, "saved, but writing "+storage.CronFile+" failed: "+err.Error())
+		return
+	}
+	expr, _ := p.CronExpr()
+	log.Printf("zfs schedule %q saved by %s (%s, %q, keep %s)", p.Name, clientIP(r), p.Dataset, expr, p.KeepFor)
+	jsonOK(w, 200, p)
+}
+
+func (s *Server) zfsPolicyDelete(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	z := s.zfsLoad()
+	kept := z.Policies[:0]
+	found := false
+	for _, p := range z.Policies {
+		if p.ID == id {
+			found = true
+			continue
+		}
+		kept = append(kept, p)
+	}
+	if !found {
+		jsonErr(w, 404, "no such schedule")
+		return
+	}
+	z.Policies = kept
+	if err := s.zfsSave(z); err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	if err := s.syncCron(r.Context(), z); err != nil {
+		jsonErr(w, 500, "removed, but writing "+storage.CronFile+" failed: "+err.Error())
+		return
+	}
+	storage.ForgetRun(s.cfg.DataDir(), id)
+	log.Printf("zfs schedule %s removed by %s (its snapshots are left alone)", id, clientIP(r))
+	w.WriteHeader(204)
+}
+
+func (s *Server) zfsPolicy(id string) (storage.Policy, bool) {
+	for _, p := range s.zfsLoad().Policies {
+		if p.ID == id {
+			return p, true
+		}
+	}
+	return storage.Policy{}, false
+}
+
+func (s *Server) zfsRunNow(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	p, ok := s.zfsPolicy(id)
+	if !ok {
+		jsonErr(w, 404, "no such schedule")
+		return
+	}
+	res, err := s.storage.Run(r.Context(), &p)
+	rec := storage.RunRecord{At: time.Now(), Taken: res.Taken, Pruned: res.Pruned}
+	if err != nil {
+		rec.Error = err.Error()
+	}
+	_ = storage.WriteRun(s.cfg.DataDir(), id, rec)
+	if err != nil {
+		jsonErr(w, 500, err.Error())
+		return
+	}
+	log.Printf("zfs schedule %q run by %s: took %s, expired %d", p.Name, clientIP(r), res.Taken, len(res.Pruned))
+	jsonOK(w, 200, res)
+}
+
+// zfsSnapshotDelete removes one snapshot, named in full and typed back by the caller.
+func (s *Server) zfsSnapshotDelete(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		Name      string `json:"name"`
+		Confirm   string `json:"confirm"`
+		Recursive bool   `json:"recursive"`
+	}
+	if err := json.NewDecoder(io.LimitReader(r.Body, 4096)).Decode(&body); err != nil {
+		jsonErr(w, 400, "bad request")
+		return
+	}
+	if body.Confirm != body.Name {
+		jsonErr(w, 400, "type the snapshot's full name to confirm")
+		return
+	}
+	if err := s.storage.DestroySnapshot(r.Context(), body.Name, body.Recursive); err != nil {
+		msg := err.Error()
+		switch {
+		case msg == "bad snapshot name":
+			jsonErr(w, 400, msg)
+		case strings.Contains(msg, "does not exist"):
+			jsonErr(w, 404, msg)
+		default:
+			jsonErr(w, 500, msg)
+		}
+		return
+	}
+	log.Printf("zfs snapshot %s destroyed by %s%s", body.Name, clientIP(r), map[bool]string{true: " (recursive)", false: ""}[body.Recursive])
+	w.WriteHeader(204)
+}

internal/auth/auth.go

@@ -28,6 +28,10 @@ const (
 	argonKeyLen  = 32
 
 	SessionTTL = 30 * 24 * time.Hour
+	// SessionIdle is how long a session may go unused before it is dropped, whatever its
+	// expiry says. Every script, curl and headless browser that signs in leaves a session;
+	// a phone that is used keeps its own alive by being used.
+	SessionIdle = 7 * 24 * time.Hour
 )
 
 func HashPassword(pw string) (string, error) {
@@ -113,11 +117,14 @@ var dummyHash = func() string {
 	return h
 }()
 
-// CheckUser verifies a password for one of users. A missing user fails in the same time
-// as a wrong password.
+// CheckUser verifies a password for one of users. A missing user — or a guest login whose
+// time is up — fails in the same time as a wrong password.
 func CheckUser(users []config.User, name, pw string) bool {
 	for _, u := range users {
 		if u.Name == name {
+			if u.Expired(time.Now()) {
+				break
+			}
 			return VerifyPassword(u.Hash, pw)
 		}
 	}
@@ -125,6 +132,51 @@ func CheckUser(users []config.User, name, pw string) bool {
 	return false
 }
 
+// ---- guest logins ----
+
+// guestAlphabet leaves out every letter and digit that can be misread in a screenshot or
+// over the phone: i, l, o, 0 and 1. A guest login is read aloud and typed by hand.
+const guestAlphabet = "abcdefghjkmnpqrstuvwxyz23456789"
+
+// randomFrom returns n characters of guestAlphabet, chosen without modulo bias.
+func randomFrom(n int) (string, error) {
+	out := make([]byte, 0, n)
+	buf := make([]byte, n)
+	limit := byte(256 - 256%len(guestAlphabet)) // the top of the last whole run of the alphabet
+	for len(out) < n {
+		if _, err := rand.Read(buf); err != nil {
+			return "", err
+		}
+		for _, b := range buf {
+			if b >= limit {
+				continue // would favour the first few letters; ask for another byte instead
+			}
+			out = append(out, guestAlphabet[int(b)%len(guestAlphabet)])
+			if len(out) == n {
+				break
+			}
+		}
+	}
+	return string(out), nil
+}
+
+// GuestPassword is a password for a guest login: four groups of four, ~78 bits, in an
+// alphabet with nothing ambiguous in it.
+func GuestPassword() (string, error) {
+	var groups []string
+	for i := 0; i < 4; i++ {
+		g, err := randomFrom(4)
+		if err != nil {
+			return "", err
+		}
+		groups = append(groups, g)
+	}
+	return strings.Join(groups, "-"), nil
+}
+
+// GuestSuffix is the tail of a generated guest name.
+func GuestSuffix() (string, error) { return randomFrom(4) }
+
 // ---- sessions ----
 
 // Sessions is a token store backed by the state file. Expiry is sliding.
@@ -141,12 +193,26 @@ func NewSessions(st *store.Store) *Sessions {
 func pruneExpired(state *store.State) {
 	now := time.Now()
 	for tok, ses := range state.Sessions {
-		if ses.Expires.Before(now) {
+		if !live(ses, now) {
 			delete(state.Sessions, tok)
 		}
 	}
 }
 
+// live is whether a session still counts: unexpired, and used within SessionIdle. A
+// session from before visits were recorded is judged by its creation, or failing that by
+// its expiry alone.
+func live(ses store.Session, now time.Time) bool {
+	if !ses.Expires.After(now) {
+		return false
+	}
+	seen := ses.LastSeen
+	if seen.IsZero() {
+		seen = ses.Created
+	}
+	return seen.IsZero() || now.Sub(seen) <= SessionIdle
+}
+
 func randomHex(n int) (string, error) {
 	b := make([]byte, n)
 	if _, err := rand.Read(b); err != nil {
@@ -186,7 +252,7 @@ func (s *Sessions) Lookup(tok, ip string) (store.Session, bool) {
 	ok, touch := false, false
 	s.st.View(func(state *store.State) {
 		found, have := state.Sessions[tok]
-		if have && found.Expires.After(time.Now()) {
+		if have && live(found, time.Now()) {
 			ses, ok = found, true
 			touch = time.Until(found.Expires) < SessionTTL-time.Hour || time.Since(found.LastSeen) > time.Hour
 		}
@@ -216,7 +282,7 @@ func (s *Sessions) List(user string) []store.Session {
 	s.st.View(func(state *store.State) {
 		now := time.Now()
 		for _, ses := range state.Sessions {
-			if ses.User == user && ses.Expires.After(now) {
+			if ses.User == user && live(ses, now) {
 				out = append(out, ses)
 			}
 		}
@@ -231,7 +297,7 @@ func (s *Sessions) Count() map[string]int {
 	s.st.View(func(state *store.State) {
 		now := time.Now()
 		for _, ses := range state.Sessions {
-			if ses.Expires.After(now) {
+			if live(ses, now) {
 				n[ses.User]++
 			}
 		}
@@ -267,14 +333,33 @@ func (s *Sessions) RevokeOthers(user, keep string) int {
 	return n
 }
 
+// RevokeIdle ends every session of user not seen for longer than idle, except the one
+// holding keep. Returns how many.
+func (s *Sessions) RevokeIdle(user, keep string, idle time.Duration) int {
+	n := 0
+	now := time.Now()
+	_ = s.st.Update(func(state *store.State) {
+		for tok, ses := range state.Sessions {
+			seen := ses.LastSeen
+			if seen.IsZero() {
+				seen = ses.Created
+			}
+			if ses.User == user && tok != keep && now.Sub(seen) > idle {
+				delete(state.Sessions, tok)
+				n++
+			}
+		}
+	})
+	return n
+}
+
 // RevokeUser ends every session of user (the account is going away).
 func (s *Sessions) RevokeUser(user string) { s.RevokeOthers(user, "") }
 
-// Limiter is a single global backoff: after 5 failures, each further failure
-// doubles a lockout starting at 30s, capped at 10 minutes. Single-user box.
 // Limiter locks out a client after repeated failed logins, per client address, with a
 // global backstop so a botnet can't burn CPU on argon2 indefinitely. A lockout for one
-// address never blocks another.
+// address never blocks another. Past perClientLock failures, each further failure doubles a
+// lockout starting at 30s, capped at 10 minutes.
 type Limiter struct {
 	mu      sync.Mutex
 	clients map[string]*bucket
@@ -290,7 +375,11 @@ type bucket struct {
 var ErrLocked = errors.New("too many failed logins")
 
 const (
-	perClientLock = 5   // failures before a client is locked
+	// perClientLock is how many failures one address gets before it is made to wait. Set high
+	// on purpose: a guest login is a generated password read off a message and typed by hand
+	// on a phone, and being locked out for fumbling it is worse than the brute-force risk —
+	// which the doubling backoff past this point, and the global backstop, still cover.
+	perClientLock = 20
 	globalLock    = 100 // failures (all clients) in the window before everyone waits a minute
 	globalWindow  = 5 * time.Minute
 )

internal/compose/compose.go

@@ -0,0 +1,42 @@
+// Package compose runs docker compose the way a stack was deployed — which is not always
+// simply "on this host". A stack deployed by an orchestrator running inside its own
+// container records paths in that container's filesystem, so compose has to run in there.
+// Both the console and the scheduled updates it writes must invoke it identically, or a
+// redeploy from one would not match the other's labels. Compose always drives this
+// machine's own Docker: a stack's files and its containers are on the same box.
+package compose
+
+import (
+	"context"
+	"os/exec"
+	"path/filepath"
+)
+
+// Spec is everything needed to run compose for one stack.
+type Spec struct {
+	Project string   // -p
+	Files   []string // -f, in order
+	Via     string   // a container to run compose inside; "" is this host
+	Tool    string   // "docker" or "podman"
+}
+
+// Cmd builds the command. args are compose's own, e.g. "pull" or "up", "-d".
+func Cmd(ctx context.Context, s Spec, args ...string) *exec.Cmd {
+	tool := s.Tool
+	if tool == "" {
+		tool = "docker"
+	}
+	base := []string{"compose", "-p", s.Project}
+	for _, f := range s.Files {
+		base = append(base, "-f", f)
+	}
+	if s.Via != "" {
+		// The CLI inside the orchestrator's container is its own `docker`, whatever this host runs.
+		return exec.CommandContext(ctx, tool, append(append([]string{"exec", s.Via, "docker"}, base...), args...)...)
+	}
+	cmd := exec.CommandContext(ctx, tool, append(base, args...)...)
+	if len(s.Files) > 0 {
+		cmd.Dir = filepath.Dir(s.Files[0])
+	}
+	return cmd
+}

internal/config/config.go

@@ -46,6 +46,22 @@ type User struct {
 	Hash     string    `json:"hash"`
 	Created  time.Time `json:"created"`
 	LastSeen time.Time `json:"last_seen,omitempty"`
+	// Guest marks a temporary login made to show somebody the console: it may only read,
+	// it expires by itself at Expires, and it is not one of the machine's accounts — it is
+	// left out of the account list, does not count towards "the last account", and cannot
+	// be the one an empty user name means. See internal/api/guests.go.
+	Guest bool `json:"guest,omitempty"`
+	// Expires is when a guest login stops working. A guest without one has already
+	// expired, which is the safe way to read a half-written file.
+	Expires time.Time `json:"expires,omitempty"`
+	// IssuedBy is the account that made this guest login.
+	IssuedBy string `json:"issued_by,omitempty"`
+}
+
+// Expired reports whether a guest login's time is up. A real account never expires; a
+// guest with no expiry at all counts as expired rather than as forever.
+func (u User) Expired(now time.Time) bool {
+	return u.Guest && (u.Expires.IsZero() || now.After(u.Expires))
 }
 
 // UpdateSource is where this machine looks for a newer Ham Lab, and how often. The field
@@ -61,6 +77,23 @@ type UpdateSource struct {
 	Check string `json:"check,omitempty"`
 }
 
+// KVM is an IP-KVM: a device with a web page that gives screen, keyboard and mouse access
+// to a machine, including when that machine has no OS running. Ham Lab holds the list on
+// the hub and proxies each one, because a KVM matters exactly when the machine it is
+// attached to cannot answer for itself.
+type KVM struct {
+	ID   string `json:"id"`
+	Name string `json:"name"`
+	// URL is the device's own address, as you would type it into a browser on the LAN.
+	URL string `json:"url"`
+	// Machine is the host this KVM is attached to, and is the key: one KVM per machine, shown
+	// on that machine's KVM tab. Empty means the hub itself. The list lives on the hub even
+	// for a node's KVM, because a KVM earns its keep when the machine is down and cannot
+	// answer for itself.
+	Machine string    `json:"machine"`
+	Added   time.Time `json:"added"`
+}
+
 type Config struct {
 	Listen string `json:"listen"`
 	// PasswordHash is the single login of installs before users existed. On load it becomes
@@ -70,6 +103,7 @@ type Config struct {
 	TLS          string  `json:"tls,omitempty"` // "auto" → self-signed cert in the data dir; "" → plain HTTP
 	Tokens       []Token `json:"tokens,omitempty"`
 	Nodes        []Node  `json:"nodes,omitempty"`
+	KVMs         []KVM   `json:"kvms,omitempty"`
 	// Updates: where a newer build comes from. See UpdateSource.
 	Updates UpdateSource `json:"update,omitempty"`
 
@@ -127,6 +161,18 @@ func (c *Config) MigrateUsers(name string) bool {
 	return true
 }
 
+// Accounts is every real account: the machine's users, without the guest logins.
+// Call under View/Update or on a config nobody else holds.
+func (c *Config) Accounts() []User {
+	out := make([]User, 0, len(c.Users))
+	for _, u := range c.Users {
+		if !u.Guest {
+			out = append(out, u)
+		}
+	}
+	return out
+}
+
 // User finds an account by name. Call under View/Update or on a config nobody else holds.
 func (c *Config) User(name string) (User, bool) {
 	for _, u := range c.Users {

internal/cron/cron.go

@@ -1,3 +1,6 @@
+// Package cron reads and writes what the UI calls the **Jobs** tab (named "Cron" until
+// 2026-09-24; the package and its /api/cron endpoints kept the old name).
+//
 // Package cron reads every scheduled job on the host into one list: /etc/crontab,
 // /etc/cron.d/*, per-user crontabs, the run-parts directories they drive, and systemd
 // timers. It computes next runs from the cron expressions, pulls last runs from the

internal/cron/schedule.go

@@ -132,6 +132,17 @@ func (s *schedule) dayMatches(t time.Time) bool {
 	}
 }
 
+// NextRun is the first time strictly after `from` that a cron expression fires. Exported so
+// anything that writes a cron line — the ZFS snapshot schedules — can say when it runs next
+// using the same evaluator that reads everyone else's.
+func NextRun(expr string, from time.Time) (time.Time, bool) { return nextRun(expr, from) }
+
+// ValidSchedule reports whether a cron expression parses.
+func ValidSchedule(expr string) error {
+	_, err := parseSchedule(expr)
+	return err
+}
+
 // nextRun finds the first time strictly after `from` that the schedule fires.
 func nextRun(expr string, from time.Time) (time.Time, bool) {
 	s, err := parseSchedule(expr)

internal/files/files.go

@@ -15,6 +15,7 @@ import (
 	"io"
 	"os"
 	"os/exec"
+	"os/signal"
 	"os/user"
 	"path/filepath"
 	"sort"
@@ -23,6 +24,7 @@ import (
 	"syscall"
 	"time"
 
+	"hamlab/internal/media"
 	"hamlab/internal/priv"
 )
 
@@ -37,6 +39,7 @@ type Entry struct {
 	Group   string `json:"group"`
 	Target  string `json:"target,omitempty"`  // link target
 	Broken  bool   `json:"broken,omitempty"`  // dangling link
+	Preview string `json:"preview,omitempty"` // "image" | "video": the Files tab can show a thumbnail of it
 }
 
 type Listing struct {
@@ -56,10 +59,12 @@ type FS interface {
 	List(ctx context.Context, path string) (Listing, error)
 	Stat(ctx context.Context, path string) (Info, error)
 	Open(ctx context.Context, path string) (io.ReadCloser, error)
+	OpenAt(ctx context.Context, path string, offset int64) (io.ReadCloser, error) // Open from a byte offset: a range request, a player seeking
 	Write(ctx context.Context, path string, r io.Reader) error
 	Mkdir(ctx context.Context, path string) error
 	Touch(ctx context.Context, path string) error
 	Rename(ctx context.Context, from, to string) error
+	Move(ctx context.Context, from, to string, progress io.Writer) error // Rename, or across filesystems a copy and a removal; long, so callers run it as a task
 	Delete(ctx context.Context, path string, recursive bool) error
 	Chmod(ctx context.Context, path string, perm os.FileMode) error
 }
@@ -137,7 +142,7 @@ func entryOf(dir, name string, lst os.FileInfo) Entry {
 		} else if st.IsDir() {
 			e.Type = "dir" // keep dir semantics for navigation; Target says it's a link
 		} else {
-			e.Size = st.Size()
+			e.Size, e.Mtime = st.Size(), st.ModTime().UnixMilli() // the file's, not the link's
 		}
 	case lst.IsDir():
 		e.Type = "dir"
@@ -146,6 +151,9 @@ func entryOf(dir, name string, lst os.FileInfo) Entry {
 	default:
 		e.Type = "other"
 	}
+	if e.Type == "file" || (e.Type == "link" && !e.Broken) {
+		e.Preview = media.Kind(name)
+	}
 	return e
 }
 
@@ -224,6 +232,20 @@ func (Local) Open(_ context.Context, path string) (io.ReadCloser, error) {
 	return os.Open(path)
 }
 
+func (l Local) OpenAt(ctx context.Context, path string, offset int64) (io.ReadCloser, error) {
+	f, err := l.Open(ctx, path)
+	if err != nil {
+		return nil, err
+	}
+	if offset > 0 {
+		if _, err := f.(*os.File).Seek(offset, io.SeekStart); err != nil {
+			f.Close()
+			return nil, err
+		}
+	}
+	return f, nil
+}
+
 // Write replaces the file's contents, keeping its mode; new files get 0644 (umask).
 func (Local) Write(_ context.Context, path string, r io.Reader) error {
 	f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0o644)
@@ -329,7 +351,15 @@ func (r *cmdReader) Close() error {
 }
 
 func (s Sudo) Open(ctx context.Context, path string) (io.ReadCloser, error) {
-	c := s.cmd(ctx, "read", path)
+	return s.open(ctx, "read", path)
+}
+
+func (s Sudo) OpenAt(ctx context.Context, path string, offset int64) (io.ReadCloser, error) {
+	return s.open(ctx, "read", "--offset", strconv.FormatInt(offset, 10), path)
+}
+
+func (s Sudo) open(ctx context.Context, args ...string) (io.ReadCloser, error) {
+	c := s.cmd(ctx, args...)
 	errb := &strings.Builder{}
 	c.Stderr = errb
 	out, err := c.StdoutPipe()
@@ -380,6 +410,30 @@ func (s Sudo) Touch(ctx context.Context, path string) error {
 func (s Sudo) Rename(ctx context.Context, from, to string) error {
 	return s.runJSON(ctx, nil, "rename", from, to)
 }
+
+// Move as root: the helper does the copying and talks on stdout.
+func (s Sudo) Move(ctx context.Context, from, to string, progress io.Writer) error {
+	c := s.cmd(ctx, "move", from, to)
+	c.Stdout = progress
+	var errb strings.Builder
+	c.Stderr = &errb
+	if err := c.Run(); err != nil {
+		if msg := strings.TrimSpace(errb.String()); msg != "" {
+			return errors.New(msg)
+		}
+		return err
+	}
+	return nil
+}
+
+// MoveCmd is the command a task runs for a long move: this binary's helper, as root when
+// the backend is.
+func MoveCmd(ctx context.Context, fsys FS, self, from, to string) *exec.Cmd {
+	if s, ok := fsys.(Sudo); ok {
+		return s.cmd(ctx, "move", from, to)
+	}
+	return exec.CommandContext(ctx, self, "fs", "move", from, to)
+}
 func (s Sudo) Delete(ctx context.Context, path string, recursive bool) error {
 	if recursive {
 		return s.runJSON(ctx, nil, "delete", "-r", path)
@@ -394,11 +448,16 @@ func (s Sudo) Chmod(ctx context.Context, path string, perm os.FileMode) error {
 func Helper(args []string, stdin io.Reader, stdout io.Writer, stderr io.Writer) int {
 	fail := func(err error) int { fmt.Fprintln(stderr, err.Error()); return 1 }
 	if len(args) < 2 {
-		return fail(errors.New("usage: hamlab fs <list|stat|read|write|mkdir|touch|rename|delete|chmod> …"))
+		return fail(errors.New("usage: hamlab fs <list|stat|read|write|mkdir|touch|rename|move|delete|chmod> …"))
 	}
 	ctx := context.Background()
 	var l Local
 	op := args[0]
+	var offset int64
+	if op == "read" && len(args) >= 4 && args[1] == "--offset" { // read --offset N <path>
+		offset, _ = strconv.ParseInt(args[2], 10, 64)
+		args = append([]string{"read"}, args[3:]...)
+	}
 	clean := func(i int) (string, error) {
 		if i >= len(args) {
 			return "", errors.New("path required")
@@ -425,7 +484,7 @@ func Helper(args []string, stdin io.Reader, stdout io.Writer, stderr io.Writer)
 			}
 			return emit(stdout, out, stderr)
 		case "read":
-			f, err := l.Open(ctx, p)
+			f, err := l.OpenAt(ctx, p, offset)
 			if err != nil {
 				return fail(err)
 			}
@@ -447,7 +506,7 @@ func Helper(args []string, stdin io.Reader, stdout io.Writer, stderr io.Writer)
 				return fail(err)
 			}
 		}
-	case "rename":
+	case "rename", "move":
 		from, err := clean(1)
 		if err != nil {
 			return fail(err)
@@ -456,6 +515,15 @@ func Helper(args []string, stdin io.Reader, stdout io.Writer, stderr io.Writer)
 		if err != nil {
 			return fail(err)
 		}
+		if op == "move" {
+			// A cancelled task is a SIGTERM: stop copying and take the partial copy away.
+			mctx, stop := signal.NotifyContext(ctx, syscall.SIGTERM, syscall.SIGINT)
+			defer stop()
+			if err := l.Move(mctx, from, to, stdout); err != nil {
+				return fail(err)
+			}
+			return 0
+		}
 		if err := l.Rename(ctx, from, to); err != nil {
 			return fail(err)
 		}

internal/files/move.go

@@ -0,0 +1,197 @@
+package files
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"syscall"
+)
+
+// IsCrossDevice reports a rename refused because the two ends are on different
+// filesystems — on a NAS that is every move between datasets. The Sudo backend only has
+// the helper's words for it.
+func IsCrossDevice(err error) bool {
+	return errors.Is(err, syscall.EXDEV) || (err != nil && strings.Contains(err.Error(), "cross-device"))
+}
+
+// Inside reports whether to lies within from — a folder cannot be moved into itself.
+func Inside(from, to string) bool {
+	return to == from || strings.HasPrefix(to, strings.TrimSuffix(from, "/")+"/")
+}
+
+// Move is Rename, and across filesystems a copy and a removal. The copy is built under a
+// hidden temporary name beside where it will land and renamed into place only once it is
+// complete, and the source is removed only after that: a failure part-way, or a cancel,
+// leaves the source exactly as it was. Progress goes to w, a line at a time, for the task
+// output that a long move is watched through.
+func (Local) Move(ctx context.Context, from, to string, w io.Writer) error {
+	if protected[from] {
+		return errors.New("refusing to move " + from)
+	}
+	if Inside(from, to) {
+		return errors.New("a folder can't be moved into itself")
+	}
+	if _, err := os.Lstat(to); err == nil {
+		return errors.New("destination exists")
+	}
+	err := os.Rename(from, to)
+	if err == nil || !IsCrossDevice(err) {
+		return err
+	}
+	return moveByCopy(ctx, from, to, w)
+}
+
+// moveByCopy is the slow path: copy, rename into place, remove the original.
+func moveByCopy(ctx context.Context, from, to string, w io.Writer) error {
+	st, err := os.Lstat(from)
+	if err != nil {
+		return err
+	}
+	tmp := filepath.Join(filepath.Dir(to), "."+filepath.Base(to)+".hamlab-moving")
+	_ = os.RemoveAll(tmp) // a previous attempt that died
+	fmt.Fprintf(w, "%s is on another filesystem: copying, then removing the original\n", filepath.Dir(to))
+	p := &progress{w: w}
+	if err := copyPath(ctx, from, tmp, st, p); err != nil {
+		fmt.Fprintln(w, "copy failed; removing the partial copy, the original is untouched")
+		_ = os.RemoveAll(tmp)
+		return err
+	}
+	if err := os.Rename(tmp, to); err != nil {
+		_ = os.RemoveAll(tmp)
+		return err
+	}
+	fmt.Fprintf(w, "copied %s; removing the original\n", p.String())
+	if err := os.RemoveAll(from); err != nil {
+		return fmt.Errorf("copied to %s, but the original could not be removed: %w", to, err)
+	}
+	fmt.Fprintf(w, "moved %s to %s\n", from, to)
+	return nil
+}
+
+type progress struct {
+	w          io.Writer
+	files      int64
+	bytes      int64
+	shownFiles int64
+	shownBytes int64
+}
+
+func (p *progress) add(files, bytes int64) {
+	p.files += files
+	p.bytes += bytes
+	if p.files-p.shownFiles >= 500 || p.bytes-p.shownBytes >= 512<<20 {
+		fmt.Fprintf(p.w, "copying… %s\n", p.String())
+		p.shownFiles, p.shownBytes = p.files, p.bytes
+	}
+}
+
+func (p *progress) String() string {
+	return fmt.Sprintf("%d files, %s", p.files, fmtSize(p.bytes))
+}
+
+func fmtSize(b int64) string {
+	const unit = 1024
+	if b < unit {
+		return fmt.Sprintf("%d B", b)
+	}
+	div, exp := int64(unit), 0
+	for n := b / unit; n >= unit && exp < 4; n /= unit {
+		div *= unit
+		exp++
+	}
+	return fmt.Sprintf("%.1f %ciB", float64(b)/float64(div), "KMGTP"[exp])
+}
+
+// copyPath copies one entry of any kind, recursively for a directory, keeping mode, times
+// and — when running as root — ownership. Devices, pipes and sockets are refused: a copy
+// of one is not the thing itself.
+func copyPath(ctx context.Context, src, dst string, st os.FileInfo, p *progress) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	mode := st.Mode()
+	switch {
+	case mode&os.ModeSymlink != 0:
+		target, err := os.Readlink(src)
+		if err != nil {
+			return err
+		}
+		if err := os.Symlink(target, dst); err != nil {
+			return err
+		}
+		chown(dst, st)
+		p.add(1, 0)
+		return nil
+	case mode.IsDir():
+		if err := os.Mkdir(dst, mode.Perm()|0o700); err != nil { // writable while it fills, exact mode after
+			return err
+		}
+		ents, err := os.ReadDir(src)
+		if err != nil {
+			return err
+		}
+		for _, e := range ents {
+			lst, err := e.Info()
+			if err != nil {
+				return err
+			}
+			if err := copyPath(ctx, filepath.Join(src, e.Name()), filepath.Join(dst, e.Name()), lst, p); err != nil {
+				return err
+			}
+		}
+		chown(dst, st)
+		if err := os.Chmod(dst, mode.Perm()); err != nil {
+			return err
+		}
+		return os.Chtimes(dst, st.ModTime(), st.ModTime())
+	case mode.IsRegular():
+		n, err := copyFile(src, dst, st)
+		if err != nil {
+			return err
+		}
+		p.add(1, n)
+		return nil
+	default:
+		return fmt.Errorf("%s: can't copy a device, pipe or socket", src)
+	}
+}
+
+func copyFile(src, dst string, st os.FileInfo) (int64, error) {
+	in, err := os.Open(src)
+	if err != nil {
+		return 0, err
+	}
+	defer in.Close()
+	out, err := os.OpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_EXCL, st.Mode().Perm())
+	if err != nil {
+		return 0, err
+	}
+	n, err := io.Copy(out, in)
+	if err != nil {
+		out.Close()
+		return n, err
+	}
+	if err := out.Close(); err != nil {
+		return n, err
+	}
+	chown(dst, st)
+	if err := os.Chmod(dst, st.Mode().Perm()); err != nil { // umask has no say
+		return n, err
+	}
+	return n, os.Chtimes(dst, st.ModTime(), st.ModTime())
+}
+
+// chown keeps the owner when this process may set one; an ordinary user's copy is the
+// user's, which is what a rename would have left anyway.
+func chown(dst string, st os.FileInfo) {
+	if os.Geteuid() != 0 {
+		return
+	}
+	if sys, ok := st.Sys().(*syscall.Stat_t); ok {
+		_ = os.Lchown(dst, int(sys.Uid), int(sys.Gid))
+	}
+}

internal/files/move_test.go

@@ -0,0 +1,195 @@
+package files
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+)
+
+func TestInside(t *testing.T) {
+	for _, c := range []struct {
+		from, to string
+		want     bool
+	}{
+		{"/a/b", "/a/b", true}, {"/a/b", "/a/b/c", true}, {"/a/b", "/a/bc", false}, {"/a/b", "/a", false}, {"/", "/x", true},
+	} {
+		if got := Inside(c.from, c.to); got != c.want {
+			t.Errorf("Inside(%q, %q) = %v, want %v", c.from, c.to, got, c.want)
+		}
+	}
+}
+
+func TestIsCrossDevice(t *testing.T) {
+	if !IsCrossDevice(&os.LinkError{Op: "rename", Old: "/a", New: "/b", Err: syscall.EXDEV}) {
+		t.Fatal("the kernel's EXDEV")
+	}
+	if !IsCrossDevice(errors.New("rename /a /b: invalid cross-device link")) {
+		t.Fatal("the helper's words for it")
+	}
+	if IsCrossDevice(errors.New("permission denied")) || IsCrossDevice(nil) {
+		t.Fatal("anything else is not")
+	}
+}
+
+// The copy path, exercised directly: a tree with nested folders, a symlink, an odd mode
+// and old mtimes lands whole under the new name, and the original is gone only then.
+func TestMoveByCopy(t *testing.T) {
+	root := t.TempDir()
+	src := filepath.Join(root, "src", "album")
+	if err := os.MkdirAll(filepath.Join(src, "sub", "deep"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	old := time.Date(2020, 1, 2, 3, 4, 5, 0, time.UTC)
+	write := func(p, s string, mode os.FileMode) {
+		if err := os.WriteFile(p, []byte(s), mode); err != nil {
+			t.Fatal(err)
+		}
+		_ = os.Chmod(p, mode)
+		_ = os.Chtimes(p, old, old)
+	}
+	write(filepath.Join(src, "a.txt"), "hello", 0o644)
+	write(filepath.Join(src, "sub", "deep", "b.bin"), strings.Repeat("x", 100000), 0o600)
+	write(filepath.Join(src, "run.sh"), "#!/bin/sh\n", 0o755)
+	if err := os.Symlink("a.txt", filepath.Join(src, "link")); err != nil {
+		t.Fatal(err)
+	}
+	_ = os.Chtimes(filepath.Join(src, "sub"), old, old)
+
+	dst := filepath.Join(root, "dst", "moved")
+	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	var out strings.Builder
+	if err := moveByCopy(context.Background(), src, dst, &out); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Lstat(src); !os.IsNotExist(err) {
+		t.Fatal("the original is still there")
+	}
+	if b, _ := os.ReadFile(filepath.Join(dst, "a.txt")); string(b) != "hello" {
+		t.Fatal("a.txt")
+	}
+	if st, err := os.Stat(filepath.Join(dst, "sub", "deep", "b.bin")); err != nil || st.Size() != 100000 || st.Mode().Perm() != 0o600 || !st.ModTime().Equal(old) {
+		t.Fatalf("b.bin: %v %v", st, err)
+	}
+	if st, _ := os.Stat(filepath.Join(dst, "run.sh")); st.Mode().Perm() != 0o755 {
+		t.Fatal("mode lost")
+	}
+	if target, err := os.Readlink(filepath.Join(dst, "link")); err != nil || target != "a.txt" {
+		t.Fatal("symlink not copied as a symlink")
+	}
+	if st, _ := os.Stat(filepath.Join(dst, "sub")); !st.ModTime().Equal(old) {
+		t.Fatal("folder mtime lost")
+	}
+	if left, _ := filepath.Glob(filepath.Join(root, "dst", ".*hamlab-moving*")); len(left) != 0 {
+		t.Fatal("temporary copy left behind")
+	}
+	if !strings.Contains(out.String(), "moved ") || !strings.Contains(out.String(), "4 files") {
+		t.Fatalf("progress said: %q", out.String())
+	}
+}
+
+// A failure part-way leaves the original as it was and no partial copy.
+func TestMoveByCopyFailsClean(t *testing.T) {
+	root := t.TempDir()
+	src := filepath.Join(root, "src")
+	if err := os.MkdirAll(src, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(src, "a"), []byte("a"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := syscall.Mkfifo(filepath.Join(src, "pipe"), 0o644); err != nil {
+		t.Skip("no fifos here")
+	}
+	dst := filepath.Join(root, "dst")
+	err := moveByCopy(context.Background(), src, dst, &strings.Builder{})
+	if err == nil || !strings.Contains(err.Error(), "pipe") {
+		t.Fatalf("expected the pipe to be refused, got %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(src, "a")); err != nil {
+		t.Fatal("the original was touched")
+	}
+	if _, err := os.Lstat(dst); !os.IsNotExist(err) {
+		t.Fatal("a partial copy was left")
+	}
+	if left, _ := filepath.Glob(filepath.Join(root, ".*hamlab-moving*")); len(left) != 0 {
+		t.Fatal("temporary copy left behind")
+	}
+	// a cancel is the same story
+	if err := os.Remove(filepath.Join(src, "pipe")); err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if err := moveByCopy(ctx, src, dst, &strings.Builder{}); err == nil {
+		t.Fatal("a cancelled move must fail")
+	}
+	if _, err := os.Stat(filepath.Join(src, "a")); err != nil {
+		t.Fatal("the original was touched by a cancel")
+	}
+}
+
+// Move on one filesystem is a rename: nothing is copied, and the guards hold.
+func TestMoveSameFilesystem(t *testing.T) {
+	root := t.TempDir()
+	src := filepath.Join(root, "f")
+	if err := os.WriteFile(src, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var l Local
+	var out strings.Builder
+	if err := l.Move(context.Background(), src, filepath.Join(root, "g"), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Len() != 0 {
+		t.Fatal("a rename has nothing to say")
+	}
+	if _, err := os.Stat(filepath.Join(root, "g")); err != nil {
+		t.Fatal("not renamed")
+	}
+	if err := l.Move(context.Background(), root, filepath.Join(root, "inside"), &out); err == nil {
+		t.Fatal("into itself")
+	}
+	if err := l.Move(context.Background(), filepath.Join(root, "g"), filepath.Join(root, "g"), &out); err == nil {
+		t.Fatal("onto itself")
+	}
+	if err := os.WriteFile(filepath.Join(root, "h"), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := l.Move(context.Background(), filepath.Join(root, "g"), filepath.Join(root, "h"), &out); err == nil || !strings.Contains(err.Error(), "exists") {
+		t.Fatalf("onto an existing file: %v", err)
+	}
+}
+
+// A link to a file carries the file's size and time, so the row and the preview key follow
+// the file; a link to a folder is a folder; a link to nothing says so.
+func TestEntryOfLinks(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "f"), []byte("12345"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	old := time.Date(2021, 1, 1, 0, 0, 0, 0, time.UTC)
+	_ = os.Chtimes(filepath.Join(dir, "f"), old, old)
+	_ = os.Mkdir(filepath.Join(dir, "d"), 0o755)
+	for _, l := range [][2]string{{"lf", "f"}, {"ld", "d"}, {"lx", "nowhere"}} {
+		if err := os.Symlink(l[1], filepath.Join(dir, l[0])); err != nil {
+			t.Fatal(err)
+		}
+	}
+	ent := func(n string) Entry { st, _ := os.Lstat(filepath.Join(dir, n)); return entryOf(dir, n, st) }
+	if e := ent("lf"); e.Type != "link" || e.Size != 5 || e.Mtime != old.UnixMilli() || e.Target != "f" || e.Broken {
+		t.Fatalf("link to file: %+v", e)
+	}
+	if e := ent("ld"); e.Type != "dir" || e.Target != "d" {
+		t.Fatalf("link to dir: %+v", e)
+	}
+	if e := ent("lx"); e.Type != "link" || !e.Broken || e.Preview != "" {
+		t.Fatalf("dangling: %+v", e)
+	}
+}

internal/files/seek.go

@@ -0,0 +1,89 @@
+package files
+
+import (
+	"context"
+	"errors"
+	"io"
+)
+
+// Seeker is an FS file as http.ServeContent wants one — something to seek in — for a file
+// whose size is already known from a stat. ServeContent seeks to the end for the size, to
+// the start of the range asked for, then reads: so the backend is opened once, at that
+// position, and only ever read forward. The Sudo backend's helper is started at the offset
+// rather than streamed from the top and skipped.
+type Seeker struct {
+	ctx  context.Context
+	fsys FS
+	path string
+	size int64
+	pos  int64 // where the next Read reads from
+	at   int64 // where cur is positioned, when open
+	cur  io.ReadCloser
+}
+
+func NewSeeker(ctx context.Context, fsys FS, path string, size int64) *Seeker {
+	return &Seeker{ctx: ctx, fsys: fsys, path: path, size: size}
+}
+
+// Check opens the file now, from the start, so a file that cannot be read is known before
+// any headers go out. Seeking costs nothing; a Read from somewhere else reopens there.
+func (s *Seeker) Check() error {
+	if s.cur != nil {
+		return nil
+	}
+	f, err := s.fsys.OpenAt(s.ctx, s.path, 0)
+	if err != nil {
+		return err
+	}
+	s.cur, s.at = f, 0
+	return nil
+}
+
+func (s *Seeker) Seek(offset int64, whence int) (int64, error) {
+	var pos int64
+	switch whence {
+	case io.SeekStart:
+		pos = offset
+	case io.SeekCurrent:
+		pos = s.pos + offset
+	case io.SeekEnd:
+		pos = s.size + offset
+	default:
+		return 0, errors.New("bad whence")
+	}
+	if pos < 0 {
+		return 0, errors.New("seek before start")
+	}
+	s.pos = pos // the stream, if open, stays where it is until a Read wants somewhere else
+	return pos, nil
+}
+
+func (s *Seeker) Read(p []byte) (int, error) {
+	if s.pos >= s.size {
+		return 0, io.EOF
+	}
+	if s.cur != nil && s.pos != s.at {
+		s.cur.Close()
+		s.cur = nil
+	}
+	if s.cur == nil {
+		f, err := s.fsys.OpenAt(s.ctx, s.path, s.pos)
+		if err != nil {
+			return 0, err
+		}
+		s.cur, s.at = f, s.pos
+	}
+	n, err := s.cur.Read(p)
+	s.pos += int64(n)
+	s.at += int64(n)
+	return n, err
+}
+
+func (s *Seeker) Close() error {
+	if s.cur == nil {
+		return nil
+	}
+	err := s.cur.Close()
+	s.cur = nil
+	return err
+}

internal/files/seek_test.go

@@ -0,0 +1,112 @@
+package files
+
+import (
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+import "strings"
+
+type stringsBuilder = strings.Builder
+
+type countingFS struct {
+	Local
+	opens []int64
+}
+
+func (c *countingFS) OpenAt(ctx context.Context, path string, off int64) (io.ReadCloser, error) {
+	c.opens = append(c.opens, off)
+	return c.Local.OpenAt(ctx, path, off)
+}
+
+// ServeContent's moves — size from the end, seek to the range, read forward — open the
+// backend once, at the range; a seek to where the stream already is costs nothing.
+func TestSeeker(t *testing.T) {
+	p := filepath.Join(t.TempDir(), "f")
+	data := make([]byte, 1000)
+	for i := range data {
+		data[i] = byte(i)
+	}
+	if err := os.WriteFile(p, data, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	fs := &countingFS{}
+	s := NewSeeker(context.Background(), fs, p, int64(len(data)))
+	if n, _ := s.Seek(0, io.SeekEnd); n != 1000 {
+		t.Fatalf("end = %d", n)
+	}
+	if _, err := s.Seek(100, io.SeekStart); err != nil {
+		t.Fatal(err)
+	}
+	buf := make([]byte, 50)
+	if n, err := io.ReadFull(s, buf); err != nil || n != 50 || buf[0] != 100 || buf[49] != 149 {
+		t.Fatalf("read at 100: %d %v %v", n, err, buf[:2])
+	}
+	if _, err := s.Seek(150, io.SeekStart); err != nil { // where it already is
+		t.Fatal(err)
+	}
+	if n, _ := io.ReadFull(s, buf); n != 50 || buf[0] != 150 {
+		t.Fatal("read after a no-op seek")
+	}
+	if len(fs.opens) != 1 || fs.opens[0] != 100 {
+		t.Fatalf("opens = %v, want [100]", fs.opens)
+	}
+	if _, err := s.Seek(0, io.SeekStart); err != nil {
+		t.Fatal(err)
+	}
+	rest, err := io.ReadAll(s)
+	if err != nil || len(rest) != 1000 || rest[999] != data[999] {
+		t.Fatalf("read all from the start: %d %v", len(rest), err)
+	}
+	if len(fs.opens) != 2 || fs.opens[1] != 0 {
+		t.Fatalf("opens = %v, want [100 0]", fs.opens)
+	}
+	if n, err := s.Read(buf); n != 0 || err != io.EOF {
+		t.Fatal("past the end is EOF")
+	}
+	if _, err := s.Seek(-1, io.SeekStart); err == nil {
+		t.Fatal("before the start")
+	}
+	if err := s.Close(); err != nil {
+		t.Fatal(err)
+	}
+	// Check opens at the start and keeps that stream for a read from the start
+	s2 := NewSeeker(context.Background(), fs, p, 1000)
+	if err := s2.Check(); err != nil {
+		t.Fatal(err)
+	}
+	s2.Seek(0, io.SeekEnd)
+	s2.Seek(0, io.SeekStart)
+	if n, _ := io.ReadFull(s2, buf); n != 50 || buf[0] != 0 {
+		t.Fatal("read from the start after Check")
+	}
+	if len(fs.opens) != 3 {
+		t.Fatalf("Check's open was not reused: %v", fs.opens)
+	}
+	s2.Close()
+	if err := NewSeeker(context.Background(), fs, filepath.Join(t.TempDir(), "nope"), 5).Check(); err == nil {
+		t.Fatal("Check must report a file that can't be opened")
+	}
+}
+
+// The helper's read takes an offset, for the Sudo backend.
+func TestHelperReadOffset(t *testing.T) {
+	p := filepath.Join(t.TempDir(), "f")
+	if err := os.WriteFile(p, []byte("0123456789"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var out, errb stringsBuilder
+	if rc := Helper([]string{"read", "--offset", "7", p}, nil, &out, &errb); rc != 0 {
+		t.Fatalf("rc %d: %s", rc, errb.String())
+	}
+	if out.String() != "789" {
+		t.Fatalf("got %q", out.String())
+	}
+	out.Reset()
+	if rc := Helper([]string{"read", p}, nil, &out, &errb); rc != 0 || out.String() != "0123456789" {
+		t.Fatalf("plain read: rc %d %q", rc, out.String())
+	}
+}

internal/hardware/hardware.go

@@ -0,0 +1,843 @@
+// Package hardware is what is physically in the machine: the board it is, its processor,
+// the memory modules in its slots, the drives attached to it and the graphics in it.
+//
+// None of this changes while the machine is running, so it is read once and remembered.
+// Everything here is read from what Debian and its kin already have — dmidecode for the
+// parts only the firmware knows, lscpu, lspci, sysfs — and every reader is allowed to
+// come back empty: a machine with no dmidecode, no PCI bus or no root still gets a page,
+// with a note saying what could not be read and why.
+package hardware
+
+import (
+	"bufio"
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"hamlab/internal/priv"
+	"hamlab/internal/storage"
+)
+
+type System struct {
+	Model  string `json:"model,omitempty"` // "GMKtec NucBox G3"
+	Serial string `json:"serial,omitempty"`
+	Family string `json:"family,omitempty"`
+	Kernel string `json:"kernel,omitempty"`
+	Arch   string `json:"arch,omitempty"`
+	Virt   string `json:"virt,omitempty"` // "kvm", "lxc", … when this is not real hardware
+}
+
+// Slot is an expansion slot as the firmware describes it. Worth treating with suspicion on
+// a mini PC, where the table is often copied from a reference design and lists slots the
+// case has no room for.
+type Slot struct {
+	Designation string `json:"designation"`
+	Type        string `json:"type,omitempty"`
+	Usage       string `json:"usage,omitempty"` // Available | In Use | Unknown
+	Length      string `json:"length,omitempty"`
+	Width       string `json:"width,omitempty"`
+	Bus         string `json:"bus,omitempty"`    // PCI address of what is in it
+	Device      string `json:"device,omitempty"` // and what that turns out to be
+}
+
+// Board is the motherboard and the firmware on it.
+type Board struct {
+	Maker        string `json:"maker,omitempty"`
+	Product      string `json:"product,omitempty"`
+	Version      string `json:"version,omitempty"`
+	Serial       string `json:"serial,omitempty"`
+	AssetTag     string `json:"asset_tag,omitempty"`
+	Type         string `json:"type,omitempty"`     // "Motherboard", "Processor Module", …
+	Location     string `json:"location,omitempty"` // where it sits in the chassis
+	Chassis      string `json:"chassis,omitempty"`
+	ChassisMaker string `json:"chassis_maker,omitempty"`
+	BIOS         string `json:"bios,omitempty"` // vendor and version
+	BIOSDate     string `json:"bios_date,omitempty"`
+	BIOSRevision string `json:"bios_revision,omitempty"`
+	ROMSize      string `json:"rom_size,omitempty"`
+	UEFI         bool   `json:"uefi,omitempty"`
+	Slots        []Slot `json:"slots,omitempty"`
+}
+
+type Cache struct {
+	Level string `json:"level"` // L1d, L1i, L2, L3
+	Size  string `json:"size"`  // as lscpu puts it: "6 MiB (1 instance)"
+}
+
+type CPU struct {
+	Model          string   `json:"model,omitempty"`
+	Vendor         string   `json:"vendor,omitempty"`
+	Arch           string   `json:"arch,omitempty"`
+	Sockets        int      `json:"sockets,omitempty"`
+	SocketNames    []string `json:"socket_names,omitempty"` // what the firmware calls each socket
+	Cores          int      `json:"cores,omitempty"`
+	Threads        int      `json:"threads,omitempty"`
+	ThreadsPerCore int      `json:"threads_per_core,omitempty"`
+	MinMHz         float64  `json:"min_mhz,omitempty"`
+	MaxMHz         float64  `json:"max_mhz,omitempty"`
+	Family         string   `json:"family,omitempty"`
+	ModelID        string   `json:"model_id,omitempty"`
+	Stepping       string   `json:"stepping,omitempty"`
+	Microcode      string   `json:"microcode,omitempty"`
+	Virtualization string   `json:"virtualization,omitempty"`
+	Caches         []Cache  `json:"caches,omitempty"`
+	Flags          []string `json:"flags,omitempty"` // the handful anyone looks for
+}
+
+type Module struct {
+	Locator    string `json:"locator"` // the slot, as the board labels it
+	Bank       string `json:"bank,omitempty"`
+	Empty      bool   `json:"empty,omitempty"`
+	Size       uint64 `json:"size,omitempty"`
+	Type       string `json:"type,omitempty"`        // DDR4
+	FormFactor string `json:"form_factor,omitempty"` // SODIMM
+	SpeedMTs   int    `json:"speed_mts,omitempty"`   // what the module can do
+	RunningMTs int    `json:"running_mts,omitempty"` // what the board is running it at
+	Maker      string `json:"maker,omitempty"`
+	Part       string `json:"part,omitempty"`
+	Serial     string `json:"serial,omitempty"`
+	Rank       int    `json:"rank,omitempty"`
+	Voltage    string `json:"voltage,omitempty"`
+}
+
+type Memory struct {
+	Total       uint64   `json:"total"`                  // what the kernel can use
+	Installed   uint64   `json:"installed,omitempty"`    // what the modules add up to
+	MaxCapacity uint64   `json:"max_capacity,omitempty"` // what the board will take
+	Slots       int      `json:"slots,omitempty"`
+	Filled      int      `json:"filled,omitempty"`
+	ECC         string   `json:"ecc,omitempty"`
+	Modules     []Module `json:"modules,omitempty"`
+}
+
+type Drive struct {
+	Name       string `json:"name"`
+	Kind       string `json:"kind"` // nvme | ssd | hdd | usb | emmc | sd | other
+	Model      string `json:"model,omitempty"`
+	Vendor     string `json:"vendor,omitempty"`
+	Serial     string `json:"serial,omitempty"`
+	Firmware   string `json:"firmware,omitempty"`
+	Tran       string `json:"tran,omitempty"`
+	Size       uint64 `json:"size"`
+	Rotational bool   `json:"rotational,omitempty"`
+	Removable  bool   `json:"removable,omitempty"`
+}
+
+type GPU struct {
+	Model  string `json:"model,omitempty"`
+	Vendor string `json:"vendor,omitempty"`
+	Slot   string `json:"slot,omitempty"` // PCI address, when it is on a bus
+	Driver string `json:"driver,omitempty"`
+	Node   string `json:"node,omitempty"` // card0
+	Memory uint64 `json:"memory,omitempty"`
+	Class  string `json:"class,omitempty"` // VGA | 3D | Display
+}
+
+type Report struct {
+	At     time.Time `json:"at"`
+	System System    `json:"system"`
+	Board  Board     `json:"board"`
+	CPU    CPU       `json:"cpu"`
+	Memory Memory    `json:"memory"`
+	Drives []Drive   `json:"drives"`
+	GPUs   []GPU     `json:"gpus"`
+	Notes  []string  `json:"notes,omitempty"` // what could not be read, and why
+}
+
+// Manager remembers the last report. Hardware does not change under a running kernel —
+// the one thing that would, a drive plugged in, is what Refresh is for.
+type Manager struct {
+	mu   sync.Mutex
+	last *Report
+	at   time.Time
+}
+
+func New() *Manager { return &Manager{} }
+
+const keepFor = 10 * time.Minute
+
+func (m *Manager) Report(ctx context.Context, refresh bool) *Report {
+	m.mu.Lock()
+	if !refresh && m.last != nil && time.Since(m.at) < keepFor {
+		r := m.last
+		m.mu.Unlock()
+		return r
+	}
+	m.mu.Unlock()
+
+	r := collect(ctx)
+
+	m.mu.Lock()
+	m.last, m.at = r, time.Now()
+	m.mu.Unlock()
+	return r
+}
+
+func collect(ctx context.Context) *Report {
+	ctx, cancel := context.WithTimeout(ctx, 25*time.Second)
+	defer cancel()
+	r := &Report{At: time.Now()}
+	dmi, note := readDMI(ctx)
+	if note != "" {
+		r.Notes = append(r.Notes, note)
+	}
+	r.System = system(ctx, dmi)
+	r.Board = board(dmi, pciNames(ctx))
+	r.CPU = cpu(ctx, dmi)
+	r.Memory = memory(dmi)
+	if len(r.Memory.Modules) == 0 && note == "" {
+		r.Notes = append(r.Notes, "memory modules: the firmware's table says nothing about this machine's slots")
+	}
+	r.Drives = drives(ctx)
+	r.GPUs = gpus(ctx)
+	if len(r.GPUs) == 0 {
+		r.Notes = append(r.Notes, "graphics: nothing on the PCI bus and no kernel display device")
+	}
+	return r
+}
+
+// ---- dmidecode ----
+
+// record is one entry of the firmware's table: its DMI type and its key/value lines.
+type record struct {
+	Type int
+	V    map[string]string
+}
+
+// listKey holds every doubly-indented line of a record — dmidecode's lists, which have no
+// key of their own: BIOS characteristics, board features, slot characteristics.
+const listKey = "\x00list"
+
+var handleRe = regexp.MustCompile(`^Handle 0x[0-9A-Fa-f]+, DMI type (\d+)`)
+
+// readDMI runs dmidecode once for every type the page wants and parses the lot. It needs
+// root; without it the page loses the board, the memory modules and the socket names, and
+// says so rather than pretending the machine has none.
+func readDMI(ctx context.Context) ([]record, string) {
+	tool, err := exec.LookPath("dmidecode")
+	if err != nil {
+		if _, e := os.Stat("/usr/sbin/dmidecode"); e != nil {
+			return nil, "the board and the memory modules need dmidecode, which isn't installed here"
+		}
+		tool = "/usr/sbin/dmidecode"
+	}
+	args := []string{tool, "-t", "bios", "-t", "system", "-t", "baseboard", "-t", "chassis", "-t", "slot", "-t", "processor", "-t", "memory"}
+	if os.Geteuid() != 0 {
+		if !priv.Available() {
+			return nil, "the board and the memory modules come from the firmware's table, which only root may read"
+		}
+		args = priv.Wrap(args...)
+	}
+	out, err := exec.CommandContext(ctx, args[0], args[1:]...).Output()
+	if err != nil {
+		return nil, "the firmware's table could not be read: " + strings.TrimSpace(err.Error())
+	}
+	return parse(string(out)), ""
+}
+
+// parse turns dmidecode's output into records: a handle line starts one, and the single
+// indented "Key: Value" lines under it are its fields. Doubly-indented lines are the
+// continuation of a list (a processor's flags), which nothing here reads.
+func parse(text string) []record {
+	var recs []record
+	var cur *record
+	sc := bufio.NewScanner(strings.NewReader(text))
+	sc.Buffer(make([]byte, 0, 64<<10), 2<<20)
+	for sc.Scan() {
+		line := sc.Text()
+		if m := handleRe.FindStringSubmatch(line); m != nil {
+			t, _ := strconv.Atoi(m[1])
+			recs = append(recs, record{Type: t, V: map[string]string{}})
+			cur = &recs[len(recs)-1]
+			continue
+		}
+		if cur == nil || !strings.HasPrefix(line, "\t") {
+			if strings.TrimSpace(line) == "" {
+				cur = nil
+			}
+			continue
+		}
+		if strings.HasPrefix(line, "\t\t") { // a list under the field above it, e.g. BIOS characteristics
+			cur.V[listKey] += strings.TrimSpace(line) + "\n"
+			continue
+		}
+		k, v, ok := strings.Cut(strings.TrimSpace(line), ":")
+		if !ok {
+			continue
+		}
+		cur.V[k] = strings.TrimSpace(v)
+	}
+	return recs
+}
+
+func (r record) get(keys ...string) string {
+	for _, k := range keys {
+		if v := r.V[k]; v != "" && !unset(v) {
+			return v
+		}
+	}
+	return ""
+}
+
+// unset is every way the firmware has of saying "nobody filled this in".
+func unset(v string) bool {
+	switch strings.ToLower(v) {
+	case "", "unknown", "not specified", "not provided", "none", "default string", "to be filled by o.e.m.",
+		"system manufacturer", "system product name", "to be filled by oem", "n/a", "empty", "no module installed",
+		"<out of spec>", "other", "not applicable":
+		return true
+	}
+	return false
+}
+
+func first(recs []record, t int) record {
+	for _, r := range recs {
+		if r.Type == t {
+			return r
+		}
+	}
+	return record{Type: t, V: map[string]string{}}
+}
+
+func all(recs []record, t int) []record {
+	var out []record
+	for _, r := range recs {
+		if r.Type == t {
+			out = append(out, r)
+		}
+	}
+	return out
+}
+
+// ---- system ----
+
+func system(ctx context.Context, dmi []record) System {
+	sys := first(dmi, 1)
+	s := System{
+		Model:  join(sys.get("Manufacturer"), sys.get("Product Name")),
+		Serial: sys.get("Serial Number"),
+		Family: sys.get("Family"),
+		Arch:   runtimeArch(),
+	}
+	s.Kernel = readFile("/proc/sys/kernel/osrelease")
+	if s.Model == "" { // no SMBIOS: a Pi, a Mac, anything with a device tree
+		s.Model = strings.TrimRight(readFile("/sys/firmware/devicetree/base/model"), "\x00")
+	}
+	if out, err := exec.CommandContext(ctx, "systemd-detect-virt").Output(); err == nil {
+		if v := strings.TrimSpace(string(out)); v != "" && v != "none" {
+			s.Virt = v
+		}
+	}
+	return s
+}
+
+// board reads the motherboard, the chassis it sits in, the firmware on it and the
+// expansion slots the firmware claims. All of it is SMBIOS, so a machine without one — a
+// Mac, a Pi — gets an empty board, and the page says so rather than inventing one.
+func board(dmi []record, pci map[string]string) Board {
+	b, ch, bios := first(dmi, 2), first(dmi, 3), first(dmi, 0)
+	out := Board{
+		Maker:        b.get("Manufacturer"),
+		Product:      b.get("Product Name"),
+		Version:      b.get("Version"),
+		Serial:       b.get("Serial Number"),
+		AssetTag:     b.get("Asset Tag"),
+		Type:         b.get("Type"),
+		Location:     b.get("Location In Chassis"),
+		Chassis:      ch.get("Type"),
+		ChassisMaker: ch.get("Manufacturer"),
+		BIOS:         join(bios.get("Vendor"), bios.get("Version")),
+		BIOSDate:     bios.get("Release Date"),
+		BIOSRevision: bios.get("BIOS Revision"),
+	}
+	// "ROM Size: 0 MB" is a board that never filled the field in, not a board with no ROM
+	if rom := bios.get("ROM Size"); rom != "" && !strings.HasPrefix(rom, "0 ") {
+		out.ROMSize = rom
+	}
+	if out.Product == out.Maker {
+		out.Product = "" // a board named after its maker says nothing twice
+	}
+	out.UEFI = strings.Contains(bios.V[listKey], "UEFI") // a characteristics line, not a field
+	for _, sl := range all(dmi, 9) {
+		s := Slot{
+			Designation: sl.get("Designation"),
+			Type:        sl.get("Type"),
+			Usage:       sl.get("Current Usage"),
+			Length:      sl.get("Length"),
+			Width:       sl.get("Data Bus Width"),
+		}
+		// every slot on some boards claims 0000:00:00.0, which is the host bridge and
+		// certainly not what is plugged into that slot
+		if bus := sl.get("Bus Address"); bus != "" && bus != "0000:00:00.0" {
+			s.Bus, s.Device = bus, pci[bus]
+		}
+		if s.Designation != "" {
+			out.Slots = append(out.Slots, s)
+		}
+	}
+	return out
+}
+
+func join(parts ...string) string {
+	var keep []string
+	for _, p := range parts {
+		if p = strings.TrimSpace(p); p != "" && !unset(p) {
+			keep = append(keep, p)
+		}
+	}
+	// "GMKtec GMKtec" reads badly: drop a maker the product already names
+	if len(keep) == 2 && strings.HasPrefix(strings.ToLower(keep[1]), strings.ToLower(keep[0])) {
+		return keep[1]
+	}
+	return strings.Join(keep, " ")
+}
+
+func readFile(p string) string {
+	b, err := os.ReadFile(p)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+func runtimeArch() string {
+	if out, err := exec.Command("uname", "-m").Output(); err == nil {
+		return strings.TrimSpace(string(out))
+	}
+	return ""
+}
+
+// ---- processor ----
+
+// worthShowing is the short list of processor features anyone actually asks about; the
+// full flag list runs to hundreds and belongs in a terminal.
+var worthShowing = []string{"aes", "avx", "avx2", "avx512f", "sha_ni", "vmx", "svm", "sse4_2", "rdrand", "hypervisor"}
+
+func cpu(ctx context.Context, dmi []record) CPU {
+	c := CPU{}
+	f := lscpu(ctx)
+	c.Model = f["Model name"]
+	c.Vendor = f["Vendor ID"]
+	c.Arch = f["Architecture"]
+	c.Sockets = atoi(f["Socket(s)"])
+	c.ThreadsPerCore = atoi(f["Thread(s) per core"])
+	c.Threads = atoi(f["CPU(s)"])
+	c.Cores = atoi(f["Core(s) per socket"]) * maxInt(1, c.Sockets)
+	c.MinMHz = atof(f["CPU min MHz"])
+	c.MaxMHz = atof(f["CPU max MHz"])
+	c.Family, c.ModelID, c.Stepping = f["CPU family"], f["Model"], f["Stepping"]
+	c.Virtualization = f["Virtualization"]
+	for _, l := range []string{"L1d", "L1i", "L2", "L3"} {
+		if v := f[l+" cache"]; v != "" {
+			c.Caches = append(c.Caches, Cache{Level: l, Size: v})
+		}
+	}
+	have := map[string]bool{}
+	for _, fl := range strings.Fields(f["Flags"]) {
+		have[fl] = true
+	}
+	for _, fl := range worthShowing {
+		if have[fl] {
+			c.Flags = append(c.Flags, fl)
+		}
+	}
+	for _, p := range all(dmi, 4) {
+		if s := p.get("Socket Designation"); s != "" {
+			c.SocketNames = append(c.SocketNames, s)
+		}
+		if c.Model == "" {
+			c.Model = p.get("Version", "Family")
+		}
+		if c.MaxMHz == 0 {
+			if mhz := atof(strings.TrimSuffix(p.get("Max Speed"), " MHz")); mhz > 0 {
+				c.MaxMHz = mhz
+			}
+		}
+	}
+	if c.Sockets == 0 {
+		c.Sockets = len(c.SocketNames)
+	}
+	// A processor whose cores are not all alike — Apple's, Intel's P and E cores — is
+	// reported by lscpu as several groups, and "core(s) per socket" then counts one group
+	// rather than the chip. Without SMT every thread is a core, so the thread count is the
+	// honest answer.
+	if c.ThreadsPerCore == 1 && c.Threads > c.Cores {
+		c.Cores = c.Threads
+	}
+	// /proc/cpuinfo is the only place the running microcode revision is written down
+	if b, err := os.ReadFile("/proc/cpuinfo"); err == nil {
+		for _, line := range strings.Split(string(b), "\n") {
+			if k, v, ok := strings.Cut(line, ":"); ok && strings.TrimSpace(k) == "microcode" {
+				c.Microcode = strings.TrimSpace(v)
+				break
+			}
+		}
+	}
+	if c.Model == "" {
+		c.Model = "unknown processor"
+	}
+	return c
+}
+
+func lscpu(ctx context.Context) map[string]string {
+	f := map[string]string{}
+	out, err := exec.CommandContext(ctx, "lscpu").Output()
+	if err != nil {
+		// no util-linux: /proc/cpuinfo still names the thing and counts it
+		if b, err := os.ReadFile("/proc/cpuinfo"); err == nil {
+			n := 0
+			for _, line := range strings.Split(string(b), "\n") {
+				k, v, ok := strings.Cut(line, ":")
+				k, v = strings.TrimSpace(k), strings.TrimSpace(v)
+				switch {
+				case ok && strings.EqualFold(k, "model name"):
+					f["Model name"] = v
+				case ok && k == "processor":
+					n++
+				}
+			}
+			f["CPU(s)"] = strconv.Itoa(n)
+		}
+		return f
+	}
+	for _, line := range strings.Split(string(out), "\n") {
+		k, v, ok := strings.Cut(line, ":")
+		if !ok || strings.HasPrefix(line, " ") {
+			continue
+		}
+		f[strings.TrimSpace(k)] = strings.TrimSpace(v)
+	}
+	return f
+}
+
+func atoi(s string) int { n, _ := strconv.Atoi(strings.TrimSpace(s)); return n }
+
+func atof(s string) float64 {
+	v, _ := strconv.ParseFloat(strings.TrimSpace(s), 64)
+	return v
+}
+
+func maxInt(a, b int) int {
+	if a > b {
+		return a
+	}
+	return b
+}
+
+// leadingInt reads the number off the front of "3200 MT/s".
+func leadingInt(s string) int {
+	f := strings.Fields(s)
+	if len(f) == 0 {
+		return 0
+	}
+	return atoi(f[0])
+}
+
+// ---- memory ----
+
+var sizeRe = regexp.MustCompile(`^(\d+)\s*(kB|KB|MB|GB|TB)$`)
+
+// dmiSize turns dmidecode's "8 GB" / "16384 MB" into bytes.
+func dmiSize(s string) uint64 {
+	m := sizeRe.FindStringSubmatch(strings.TrimSpace(s))
+	if m == nil {
+		return 0
+	}
+	n, _ := strconv.ParseUint(m[1], 10, 64)
+	switch strings.ToUpper(m[2]) {
+	case "KB":
+		return n << 10
+	case "MB":
+		return n << 20
+	case "GB":
+		return n << 30
+	case "TB":
+		return n << 40
+	}
+	return 0
+}
+
+func memory(dmi []record) Memory {
+	m := Memory{}
+	if b, err := os.ReadFile("/proc/meminfo"); err == nil {
+		for _, line := range strings.Split(string(b), "\n") {
+			if k, v, ok := strings.Cut(line, ":"); ok && k == "MemTotal" {
+				m.Total = uint64(atoi(strings.TrimSuffix(strings.TrimSpace(v), " kB"))) << 10
+				break
+			}
+		}
+	}
+	for _, a := range all(dmi, 16) {
+		m.MaxCapacity += dmiSize(a.get("Maximum Capacity"))
+		switch e := a.V["Error Correction Type"]; {
+		case e == "None":
+			m.ECC = "non-ECC" // the array says so outright; worth knowing, not worth hiding
+		case e != "" && !unset(e):
+			m.ECC = e
+		}
+	}
+	for _, d := range all(dmi, 17) {
+		mod := Module{
+			Locator: d.get("Locator"),
+			Bank:    d.get("Bank Locator"),
+			Size:    dmiSize(d.get("Size")),
+		}
+		m.Slots++
+		if mod.Locator == "" {
+			mod.Locator = "slot " + strconv.Itoa(m.Slots)
+		}
+		if mod.Size == 0 {
+			mod.Empty = true
+			m.Modules = append(m.Modules, mod)
+			continue
+		}
+		m.Filled++
+		mod.Type = d.get("Type")
+		mod.FormFactor = d.get("Form Factor")
+		mod.SpeedMTs = leadingInt(d.get("Speed"))
+		mod.RunningMTs = leadingInt(d.get("Configured Memory Speed", "Configured Clock Speed"))
+		mod.Maker = makerName(d.get("Manufacturer"), d.V["Module Manufacturer ID"])
+		mod.Part = d.get("Part Number")
+		mod.Serial = d.get("Serial Number")
+		mod.Rank = atoi(d.get("Rank"))
+		mod.Voltage = d.get("Configured Voltage")
+		m.Installed += mod.Size
+		m.Modules = append(m.Modules, mod)
+	}
+	return m
+}
+
+// jedec maps the memory makers who turn up in a homelab to their names: SPD carries a
+// JEDEC id, and dmidecode prints the raw code when the module's string field is empty.
+var jedec = map[string]string{
+	"0X2C00": "Micron", "0X802C": "Micron",
+	"0XCE00": "Samsung", "0X80CE": "Samsung", "0X00CE": "Samsung",
+	"0XAD00": "SK hynix", "0X80AD": "SK hynix",
+	"0X9801": "Kingston", "0X7F98": "Kingston", "0X0198": "Kingston",
+	"0X859B": "Crucial", "0X04CB": "A-DATA", "0X04CD": "G.Skill",
+	"0X029E": "Corsair", "0X0B45": "Wilk Elektronik", "0X830B": "Wilk Elektronik",
+	"0X0443": "Ramaxel", "0X0194": "Smart Modular",
+}
+
+// makerName prefers what the module says it is; a bare JEDEC id becomes a name when it is
+// one we know, and stays the id when it is not — a wrong name is worse than a number.
+func makerName(v, id string) string {
+	if v != "" && !unset(v) && !strings.HasPrefix(v, "0x") {
+		return v
+	}
+	code := v
+	if code == "" {
+		code = id
+	}
+	if n, ok := jedec[strings.ToUpper(code)]; ok {
+		return n
+	}
+	if v != "" && !unset(v) {
+		return v
+	}
+	return ""
+}
+
+// ---- drives ----
+
+func drives(ctx context.Context) []Drive {
+	devs, err := storage.Devices(ctx)
+	if err != nil {
+		return nil
+	}
+	out := make([]Drive, 0, len(devs))
+	for _, d := range devs {
+		out = append(out, Drive{
+			Name: d.Name, Kind: d.Kind, Model: d.Model, Vendor: d.Vendor, Serial: d.Serial,
+			Tran: d.Tran, Size: d.Size, Rotational: d.Rotational, Removable: d.Removable,
+			Firmware: firmwareOf(d.Name),
+		})
+	}
+	return out
+}
+
+// firmwareOf reads a drive's firmware revision. An NVMe device is folded to its
+// controller ("nvme0"), which has no /sys/block entry of its own — the revision is on the
+// controller in /sys/class/nvme.
+func firmwareOf(name string) string {
+	return firstNonEmpty(
+		readFile("/sys/block/"+name+"/device/firmware_rev"),
+		readFile("/sys/block/"+name+"/device/rev"),
+		readFile("/sys/class/nvme/"+name+"/firmware_rev"),
+	)
+}
+
+func firstNonEmpty(v ...string) string {
+	for _, s := range v {
+		if s != "" {
+			return s
+		}
+	}
+	return ""
+}
+
+// ---- graphics ----
+
+// lspci -mm quotes every field, so a device name can hold the spaces and brackets it
+// likes: `"VGA compatible controller [0300]" "Intel Corporation [8086]" "Alder Lake-N …"`.
+var quoted = regexp.MustCompile(`"([^"]*)"`)
+
+// stripID drops the trailing PCI id from `Alder Lake-N [UHD Graphics] [46d1]`.
+func stripID(s string) string {
+	if i := strings.LastIndex(s, " ["); i > 0 && strings.HasSuffix(s, "]") {
+		return strings.TrimSpace(s[:i])
+	}
+	return s
+}
+
+func gpus(ctx context.Context) []GPU {
+	var out []GPU
+	seen := map[string]bool{} // PCI addresses already accounted for
+	if _, err := exec.LookPath("lspci"); err == nil {
+		drivers := pciDrivers(ctx)
+		if b, err := exec.CommandContext(ctx, "lspci", "-D", "-mm", "-nn").Output(); err == nil {
+			for _, line := range strings.Split(string(b), "\n") {
+				slot, _, _ := strings.Cut(line, " ")
+				fields := quoted.FindAllStringSubmatch(line, -1)
+				if len(fields) < 3 {
+					continue
+				}
+				kind := displayClass(fields[0][1])
+				if kind == "" {
+					continue
+				}
+				seen[slot] = true
+				g := GPU{Slot: slot, Class: kind, Vendor: stripID(fields[1][1]), Model: stripID(fields[2][1]), Driver: drivers[slot]}
+				g.Node, g.Memory = drmFor(slot)
+				out = append(out, g)
+			}
+		}
+	}
+	// A GPU that is not on a PCI bus at all — an Apple Silicon Mac, a Pi, anything with a
+	// device tree — is only visible as a kernel display device.
+	cards, _ := filepath.Glob("/sys/class/drm/card[0-9]")
+	for _, c := range cards {
+		dev, err := filepath.EvalSymlinks(c + "/device")
+		if err != nil || seen[filepath.Base(dev)] {
+			continue
+		}
+		g := GPU{Node: filepath.Base(c), Class: "Display"}
+		if drv, err := filepath.EvalSymlinks(dev + "/driver"); err == nil {
+			g.Driver = filepath.Base(drv)
+		}
+		g.Model = deviceTreeName(dev)
+		if g.Model == "" && g.Driver != "" {
+			g.Model = g.Driver + " display"
+		}
+		if g.Model == "" {
+			continue
+		}
+		g.Memory = vram(dev)
+		out = append(out, g)
+	}
+	sort.SliceStable(out, func(i, j int) bool { return out[i].Slot < out[j].Slot })
+	return out
+}
+
+// pciNames maps a PCI address to a readable name, so a slot the firmware says is in use
+// can say what is in it.
+func pciNames(ctx context.Context) map[string]string {
+	m := map[string]string{}
+	if _, err := exec.LookPath("lspci"); err != nil {
+		return m
+	}
+	out, err := exec.CommandContext(ctx, "lspci", "-D", "-mm", "-nn").Output()
+	if err != nil {
+		return m
+	}
+	for _, line := range strings.Split(string(out), "\n") {
+		slot, _, _ := strings.Cut(line, " ")
+		f := quoted.FindAllStringSubmatch(line, -1)
+		if slot == "" || len(f) < 3 {
+			continue
+		}
+		m[slot] = strings.TrimSpace(stripID(f[1][1]) + " " + stripID(f[2][1]))
+	}
+	return m
+}
+
+func displayClass(c string) string {
+	switch {
+	case strings.Contains(c, "[0300]"):
+		return "VGA"
+	case strings.Contains(c, "[0302]"):
+		return "3D"
+	case strings.Contains(c, "[0301]"), strings.Contains(c, "[0380]"):
+		return "Display"
+	}
+	return ""
+}
+
+// pciDrivers maps a PCI address to the kernel module driving it.
+func pciDrivers(ctx context.Context) map[string]string {
+	m := map[string]string{}
+	out, err := exec.CommandContext(ctx, "lspci", "-D", "-k").Output()
+	if err != nil {
+		return m
+	}
+	slot := ""
+	for _, line := range strings.Split(string(out), "\n") {
+		if !strings.HasPrefix(line, "\t") && !strings.HasPrefix(line, " ") {
+			slot, _, _ = strings.Cut(line, " ")
+			continue
+		}
+		if v, ok := strings.CutPrefix(strings.TrimSpace(line), "Kernel driver in use:"); ok && slot != "" {
+			m[slot] = strings.TrimSpace(v)
+		}
+	}
+	return m
+}
+
+// drmFor finds the kernel display device for a PCI address, and its video memory when the
+// driver publishes it (amdgpu does; Intel's integrated graphics have none of their own).
+func drmFor(slot string) (string, uint64) {
+	cards, _ := filepath.Glob("/sys/class/drm/card[0-9]")
+	for _, c := range cards {
+		dev, err := filepath.EvalSymlinks(c + "/device")
+		if err != nil || filepath.Base(dev) != slot {
+			continue
+		}
+		return filepath.Base(c), vram(dev)
+	}
+	return "", 0
+}
+
+func vram(dev string) uint64 {
+	for _, f := range []string{"mem_info_vram_total", "mem_info_vis_vram_total"} {
+		if v := readFile(dev + "/" + f); v != "" {
+			n, _ := strconv.ParseUint(v, 10, 64)
+			return n
+		}
+	}
+	return 0
+}
+
+// deviceTreeName reads what a device-tree machine calls its graphics: the compatible
+// string, tidied — "apple,agx-g13g" becomes "Apple agx-g13g".
+func deviceTreeName(dev string) string {
+	c := readFile(dev + "/of_node/compatible")
+	if c == "" {
+		return ""
+	}
+	c = strings.TrimRight(strings.Split(c, "\x00")[0], "\x00")
+	maker, rest, ok := strings.Cut(c, ",")
+	if !ok {
+		return c
+	}
+	if maker != "" {
+		maker = strings.ToUpper(maker[:1]) + maker[1:]
+	}
+	return strings.TrimSpace(maker + " " + rest)
+}

internal/hardware/hardware_test.go

@@ -0,0 +1,103 @@
+package hardware
+
+import "testing"
+
+func TestDMISize(t *testing.T) {
+	for in, want := range map[string]uint64{
+		"8 GB": 8 << 30, "16384 MB": 16384 << 20, "512 kB": 512 << 10, "1 TB": 1 << 40,
+		"No Module Installed": 0, "": 0, "8 GiB": 0,
+	} {
+		if got := dmiSize(in); got != want {
+			t.Errorf("dmiSize(%q) = %d, want %d", in, got, want)
+		}
+	}
+}
+
+func TestMakerName(t *testing.T) {
+	cases := []struct{ v, id, want string }{
+		{"Samsung", "", "Samsung"},                         // the module says who it is
+		{"0x0B45", "Bank 12, Hex 0x45", "Wilk Elektronik"}, // only a JEDEC id, and one we know
+		{"0xFFFF", "", "0xFFFF"},                           // one we don't: the number, not a guess
+		{"Unknown", "", ""},
+		{"", "0xCE00", "Samsung"},
+	}
+	for _, c := range cases {
+		if got := makerName(c.v, c.id); got != c.want {
+			t.Errorf("makerName(%q, %q) = %q, want %q", c.v, c.id, got, c.want)
+		}
+	}
+}
+
+func TestStripIDAndDisplayClass(t *testing.T) {
+	if got := stripID("Alder Lake-N [UHD Graphics] [46d1]"); got != "Alder Lake-N [UHD Graphics]" {
+		t.Errorf("stripID = %q", got)
+	}
+	if got := stripID("no brackets here"); got != "no brackets here" {
+		t.Errorf("stripID left a plain name alone wrong: %q", got)
+	}
+	if displayClass(`VGA compatible controller [0300]`) != "VGA" {
+		t.Error("a VGA controller should be graphics")
+	}
+	if displayClass(`Ethernet controller [0200]`) != "" {
+		t.Error("a network card is not graphics")
+	}
+}
+
+func TestLeadingIntAndJoin(t *testing.T) {
+	if leadingInt("3200 MT/s") != 3200 || leadingInt("") != 0 || leadingInt("Unknown") != 0 {
+		t.Error("leadingInt")
+	}
+	if got := join("GMKtec", "GMKtec NucBox G3"); got != "GMKtec NucBox G3" {
+		t.Errorf("a maker the product already names should not be said twice: %q", got)
+	}
+	if got := join("Dell Inc.", "OptiPlex 7040"); got != "Dell Inc. OptiPlex 7040" {
+		t.Errorf("join = %q", got)
+	}
+	if got := join("To Be Filled By O.E.M.", "System Product Name"); got != "" {
+		t.Errorf("firmware boilerplate is not a model: %q", got)
+	}
+}
+
+const sample = `# dmidecode 3.6
+Handle 0x0028, DMI type 17, 92 bytes
+Memory Device
+	Array Handle: 0x0027
+	Size: 8 GB
+	Form Factor: SODIMM
+	Locator: Controller0-ChannelA-DIMM0
+	Type: DDR4
+	Speed: 3200 MT/s
+	Manufacturer: 0x0B45
+	Part Number: WPBH32D408SWD-8G
+	Configured Memory Speed: 2933 MT/s
+	Rank: 1
+
+Handle 0x0029, DMI type 17, 92 bytes
+Memory Device
+	Size: No Module Installed
+	Locator: Controller1-ChannelA-DIMM0
+	Type: Unknown
+`
+
+// parseRecords is what readDMI does once dmidecode has answered; this exercises it
+// without needing root or the tool.
+func TestMemoryFromRecords(t *testing.T) {
+	recs := parse(sample)
+	m := memory(recs)
+	if m.Slots != 2 || m.Filled != 1 {
+		t.Fatalf("slots %d filled %d, want 2 and 1", m.Slots, m.Filled)
+	}
+	mod := m.Modules[0]
+	if mod.Size != 8<<30 || mod.Type != "DDR4" || mod.Maker != "Wilk Elektronik" || mod.Part != "WPBH32D408SWD-8G" {
+		t.Errorf("first module read wrong: %+v", mod)
+	}
+	if mod.SpeedMTs != 3200 || mod.RunningMTs != 2933 {
+		t.Errorf("a module running below its rating should say both: %d / %d", mod.RunningMTs, mod.SpeedMTs)
+	}
+	if !m.Modules[1].Empty || m.Modules[1].Locator != "Controller1-ChannelA-DIMM0" {
+		t.Errorf("empty slot read wrong: %+v", m.Modules[1])
+	}
+	if m.Installed != 8<<30 {
+		t.Errorf("installed = %d", m.Installed)
+	}
+}

internal/media/cache.go

@@ -0,0 +1,218 @@
+package media
+
+import (
+	"crypto/sha256"
+	"encoding/binary"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"os"
+	"strconv"
+	"sync"
+	"time"
+
+	bolt "go.etcd.io/bbolt"
+)
+
+// Cache keeps finished previews in one database file under Ham Lab's own data directory —
+// thumbs.db, a bbolt key/value store: pure Go, so the binary stays static, and one file
+// per machine rather than a tree of hash-named JPEGs. An entry is one file's preview keyed
+// by its path, size and mtime, so a file that changes gets a new preview and an unchanged
+// one is never decoded twice. A file ffmpeg could not decode is kept the same way, with
+// ffmpeg's reason and no picture, so a folder of odd files does not re-run ffmpeg on every
+// visit. Nothing expires: a preview is a few kilobytes, and only files somebody actually
+// scrolled past are ever made. The file is opened the first time something is stored, so a
+// machine nobody browses with previews on never has one.
+type Cache struct {
+	Path string
+	mu   sync.Mutex
+	db   *bolt.DB
+	err  error
+}
+
+// Entry is one cached preview, or the remembered reason there is none.
+type Entry struct {
+	Path    string    `json:"path"`
+	Engine  string    `json:"engine,omitempty"`
+	Codec   string    `json:"codec,omitempty"`
+	Width   int       `json:"width,omitempty"`
+	Height  int       `json:"height,omitempty"`
+	Made    time.Time `json:"made"`
+	Failure string    `json:"failure,omitempty"` // set instead of JPEG when ffmpeg refused the file
+	JPEG    []byte    `json:"-"`
+}
+
+var (
+	bucketThumbs = []byte("thumbs")
+	bucketMeta   = []byte("meta")
+	keyCount     = []byte("count")
+)
+
+// Key identifies one file's preview. "v1" is the preview format: bump it to retire every
+// cached preview at once.
+func Key(path string, size, mtime int64) string {
+	h := sha256.Sum256([]byte("v1\x00" + path + "\x00" + strconv.FormatInt(size, 10) + "\x00" + strconv.FormatInt(mtime, 10)))
+	return hex.EncodeToString(h[:])
+}
+
+func NewCache(path string) *Cache { return &Cache{Path: path} }
+
+// open the database once; an open that failed is not retried, and previews still get made
+// and served — they are simply not kept, and the log says why.
+func (c *Cache) open() (*bolt.DB, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.db != nil || c.err != nil {
+		return c.db, c.err
+	}
+	db, err := bolt.Open(c.Path, 0o600, &bolt.Options{Timeout: 2 * time.Second})
+	if err != nil {
+		c.err = err
+		return nil, err
+	}
+	if err := db.Update(func(tx *bolt.Tx) error {
+		if _, err := tx.CreateBucketIfNotExists(bucketThumbs); err != nil {
+			return err
+		}
+		_, err := tx.CreateBucketIfNotExists(bucketMeta)
+		return err
+	}); err != nil {
+		db.Close()
+		c.err = err
+		return nil, err
+	}
+	c.db = db
+	return db, nil
+}
+
+// Close releases the file. Previews after it are made but not kept.
+func (c *Cache) Close() error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.db == nil {
+		return nil
+	}
+	err := c.db.Close()
+	c.db, c.err = nil, errors.New("cache closed")
+	return err
+}
+
+// Get returns the entry for a key. A database that does not exist yet is a miss, not a reason
+// to make one.
+func (c *Cache) Get(key string) (Entry, bool, error) {
+	c.mu.Lock()
+	db := c.db
+	c.mu.Unlock()
+	if db == nil {
+		if _, err := os.Stat(c.Path); err != nil {
+			return Entry{}, false, nil
+		}
+		var err error
+		if db, err = c.open(); err != nil {
+			return Entry{}, false, err
+		}
+	}
+	var e Entry
+	found := false
+	err := db.View(func(tx *bolt.Tx) error {
+		v := tx.Bucket(bucketThumbs).Get([]byte(key))
+		if v == nil {
+			return nil
+		}
+		var err error
+		e, err = decode(v) // copies: a value is only valid inside the transaction
+		found = err == nil
+		return err
+	})
+	return e, found, err
+}
+
+// Put stores an entry, replacing any under the same key.
+func (c *Cache) Put(key string, e Entry) error {
+	if len(e.JPEG) == 0 && e.Failure == "" {
+		return errors.New("empty preview")
+	}
+	if e.Made.IsZero() {
+		e.Made = time.Now()
+	}
+	db, err := c.open()
+	if err != nil {
+		return err
+	}
+	v, err := encode(e)
+	if err != nil {
+		return err
+	}
+	return db.Update(func(tx *bolt.Tx) error {
+		b := tx.Bucket(bucketThumbs)
+		k := []byte(key)
+		fresh := b.Get(k) == nil
+		if err := b.Put(k, v); err != nil {
+			return err
+		}
+		if fresh {
+			m := tx.Bucket(bucketMeta)
+			return m.Put(keyCount, be64(count(m)+1))
+		}
+		return nil
+	})
+}
+
+// Stats is how many previews are kept and how big the file is.
+func (c *Cache) Stats() (entries int64, bytes int64) {
+	st, err := os.Stat(c.Path)
+	if err != nil {
+		return 0, 0
+	}
+	bytes = st.Size()
+	db, err := c.open()
+	if err != nil {
+		return 0, bytes
+	}
+	_ = db.View(func(tx *bolt.Tx) error { entries = count(tx.Bucket(bucketMeta)); return nil })
+	return entries, bytes
+}
+
+func count(m *bolt.Bucket) int64 {
+	if v := m.Get(keyCount); len(v) == 8 {
+		return int64(binary.BigEndian.Uint64(v))
+	}
+	return 0
+}
+
+func be64(n int64) []byte {
+	b := make([]byte, 8)
+	binary.BigEndian.PutUint64(b, uint64(n))
+	return b
+}
+
+// A value is a 4-byte header length, the header as JSON, then the JPEG bytes.
+func encode(e Entry) ([]byte, error) {
+	hdr, err := json.Marshal(e)
+	if err != nil {
+		return nil, err
+	}
+	v := make([]byte, 4+len(hdr)+len(e.JPEG))
+	binary.BigEndian.PutUint32(v, uint32(len(hdr)))
+	copy(v[4:], hdr)
+	copy(v[4+len(hdr):], e.JPEG)
+	return v, nil
+}
+
+func decode(v []byte) (Entry, error) {
+	if len(v) < 4 {
+		return Entry{}, errors.New("short value")
+	}
+	n := int(binary.BigEndian.Uint32(v))
+	if 4+n > len(v) {
+		return Entry{}, errors.New("bad header length")
+	}
+	var e Entry
+	if err := json.Unmarshal(v[4:4+n], &e); err != nil {
+		return Entry{}, err
+	}
+	if rest := v[4+n:]; len(rest) > 0 {
+		e.JPEG = append([]byte(nil), rest...)
+	}
+	return e, nil
+}

internal/media/encode.go

@@ -0,0 +1,342 @@
+package media
+
+// What to run when a video is played in the browser: the qualities it is offered in (the
+// ladder), the ways a machine could make one of them on the device asked for, in the order
+// worth trying, and the ffmpeg argument list for one piece-making run. All decisions, no
+// processes, so it can be tested. Everything is H.264 High and AAC: what every browser plays.
+
+import (
+	"fmt"
+	"math"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// Rung is one quality the player can pick: a size, a frame rate and a bit rate.
+type Rung struct {
+	Name    string  `json:"name"`  // in URLs: the width, "1920"
+	Label   string  `json:"label"` // what the menu says: "1080s", "720p"
+	Width   int     `json:"width"`
+	Height  int     `json:"height"`
+	FPS     float64 `json:"fps"`
+	Bitrate int     `json:"bitrate"` // video, bits a second, on average
+	Peak    int     `json:"peak"`    // what the playlist promises, sound included
+	level   string  // H.264 level, "5.2"
+	codecs  string  // for the master playlist
+}
+
+// One step of the ladder: the long side for a 360 video (its width), the short side for a flat
+// one, and the bit rate (Mb/s ×10) at more than 30 frames a second and at 30 or fewer.
+type step struct {
+	size   int
+	label  string
+	hi, lo int
+	cap30  bool
+}
+
+// A 360 picture is seen a quarter of its width at a time, so it needs more pixels than a flat
+// one for the same sharpness; YouTube names its sizes by the flat picture they look like
+// ("1080s"), and so does this.
+var vrSteps = []step{
+	{3840, "2160s", 220, 160, false},
+	{2880, "1440s", 120, 90, false},
+	{1920, "1080s", 60, 45, false},
+	{1280, "720s", 25, 25, true},
+}
+
+var flatSteps = []step{
+	{2160, "2160p", 160, 120, false},
+	{1440, "1440p", 90, 65, false},
+	{1080, "1080p", 50, 35, false},
+	{720, "720p", 25, 25, true},
+	{480, "480p", 12, 12, true},
+}
+
+const audioRate = 160_000
+
+func even(x float64) int { return int(math.Round(x/2)) * 2 }
+
+// Ladder is the qualities a video is offered in, best first: every step no bigger than the
+// picture itself, or the picture's own size if it is smaller than all of them.
+func Ladder(i Info) []Rung {
+	v := i.Video
+	if v == nil || v.Width <= 0 || v.Height <= 0 {
+		return nil
+	}
+	vr := v.Spherical
+	steps := flatSteps
+	w, h := v.Shown()
+	src := min(w, h) // a flat picture is named by its short side
+	if vr {
+		steps, src = vrSteps, w
+	}
+	// A picture between two steps (a 2292×960 capture) gets its own size on top, at the bit
+	// rate of the step above, so the best on offer is never less than the file.
+	var out []Rung
+	for k, s := range steps {
+		if s.size > src {
+			continue
+		}
+		if len(out) == 0 && s.size < src && k > 0 { // never above the top step: H.264 stops there
+			own := steps[k-1]
+			own.size, own.label, own.cap30 = src, strconv.Itoa(src)+map[bool]string{true: "s", false: "p"}[vr], false
+			out = append(out, rung(i, own))
+		}
+		out = append(out, rung(i, s))
+	}
+	if len(out) == 0 {
+		last := steps[len(steps)-1]
+		last.size, last.label = src, strconv.Itoa(src)+map[bool]string{true: "s", false: "p"}[vr]
+		out = append(out, rung(i, last))
+	}
+	return out
+}
+
+func rung(i Info, s step) Rung {
+	v := i.Video
+	sw, sh := v.Shown()
+	var w, h int
+	switch {
+	case v.Spherical:
+		w, h = s.size, even(float64(s.size)*float64(sh)/float64(sw))
+	case sw >= sh:
+		h, w = s.size, even(float64(s.size)*float64(sw)/float64(sh))
+	default: // standing up
+		w, h = s.size, even(float64(s.size)*float64(sh)/float64(sw))
+	}
+	fps := v.FPS
+	if fps <= 0 {
+		fps = 30
+	}
+	for fps > 60.5 || (s.cap30 && fps > 30.5) {
+		fps /= 2
+	}
+	fps = math.Round(fps*1000) / 1000
+	br := s.lo
+	if fps > 30.5 {
+		br = s.hi
+	}
+	r := Rung{Name: strconv.Itoa(w), Label: s.label, Width: w, Height: h, FPS: fps, Bitrate: br * 100_000}
+	r.Peak = r.Bitrate*3/2 + audioRate
+	r.level = level(w, h, fps)
+	lv, _ := strconv.ParseFloat(r.level, 64)
+	r.codecs = fmt.Sprintf("avc1.6400%02x", int(math.Round(lv*10)))
+	if i.Audio != nil {
+		r.codecs += ",mp4a.40.2"
+	}
+	return r
+}
+
+// level is the lowest H.264 level that takes this many macroblocks a frame and a second.
+func level(w, h int, fps float64) string {
+	mbs := ((w + 15) / 16) * ((h + 15) / 16)
+	rate := float64(mbs) * fps
+	for _, l := range []struct {
+		name  string
+		mbps  float64
+		frame int
+	}{
+		{"3.1", 108000, 3600}, {"3.2", 216000, 5120}, {"4.0", 245760, 8192}, {"4.2", 522240, 8704},
+		{"5.0", 589824, 22080}, {"5.1", 983040, 36864}, {"5.2", 2073600, 36864},
+	} {
+		if rate <= l.mbps && mbs <= l.frame {
+			return l.name
+		}
+	}
+	return "6.2"
+}
+
+// fpsArg is a frame rate as ffmpeg's fps filter takes it, exactly for the NTSC rates.
+func fpsArg(f float64) string {
+	for _, n := range []float64{24, 30, 60, 120} {
+		if math.Abs(f-n*1000/1001) < 0.01 {
+			return fmt.Sprintf("%d/1001", int(n*1000))
+		}
+	}
+	return strings.TrimRight(strings.TrimRight(strconv.FormatFloat(f, 'f', 3, 64), "0"), ".")
+}
+
+// Recipe is one way to make a quality: the engine's name for the record, the device it runs
+// on ("cpu" for the software encoder), and the ffmpeg arguments that go before the input, the
+// video filter, and the video codec.
+type Recipe struct {
+	Engine string
+	Device string
+	Pre    []string
+	VF     string
+	Video  []string
+}
+
+// CPU is the device name for software encoding.
+const CPU = "cpu"
+
+// Device is one thing a machine can make H.264 on, for the Transcode device setting.
+type Device struct {
+	ID         string `json:"id"`   // a render node, or "cpu"
+	Name       string `json:"name"` // "Intel Arc A380", "CPU (libx264)"
+	Integrated bool   `json:"integrated,omitempty"`
+	OK         bool   `json:"ok"`
+	Reason     string `json:"reason,omitempty"` // when not OK: why
+}
+
+// Devices lists what this machine could make the player's H.264 on: every GPU, usable or not
+// (and why not), then the CPU.
+func Devices(c Caps) []Device {
+	var out []Device
+	if c.Error != "" {
+		return []Device{{ID: CPU, Name: "CPU", Reason: c.Error}}
+	}
+	for _, g := range c.GPUs {
+		d := Device{ID: g.Device, Name: g.Name, Integrated: g.Integrated}
+		if d.Name == "" {
+			d.Name = g.Device
+		}
+		switch {
+		case g.API != "vaapi":
+			d.Reason = "only VAAPI devices encode here"
+		case g.Encodes != nil && !has(g.Encodes, "h264"):
+			d.Reason = "doesn't encode H.264"
+		default:
+			d.OK = true
+		}
+		out = append(out, d)
+	}
+	for _, g := range c.Unusable {
+		name := g.Name
+		if name == "" {
+			name = g.Device
+		}
+		out = append(out, Device{ID: g.Device, Name: name, Integrated: g.Integrated, Reason: g.Reason})
+	}
+	d := Device{ID: CPU, Name: "CPU (libx264)", OK: has(c.Encoders, "libx264")}
+	if !d.OK {
+		d.Reason = "this ffmpeg has no libx264"
+	}
+	return append(out, d)
+}
+
+// recipes are the ways to make quality r of src on device, best first: on a GPU, decoding on
+// the same card (frames never leave it) before decoding in software and uploading; the CPU
+// last, as the fallback whatever was asked. device "" is any: a card on the bus before the
+// integrated GPU. An empty list means nothing here can.
+func recipes(c Caps, device string, src Info, r Rung) []Recipe {
+	var out []Recipe
+	gpus := append([]GPU(nil), c.GPUs...)
+	sort.SliceStable(gpus, func(i, j int) bool { return !gpus[i].Integrated && gpus[j].Integrated })
+	kbps := r.Bitrate / 1000
+	rate := []string{"-b:v", strconv.Itoa(kbps) + "k", "-maxrate", strconv.Itoa(kbps*3/2) + "k", "-bufsize", strconv.Itoa(kbps*2) + "k",
+		"-profile:v", "high", "-level", r.level}
+	fps := ""
+	if src.Video == nil || src.Video.FPS <= 0 || math.Abs(src.Video.FPS-r.FPS) > 0.01 {
+		fps = "fps=" + fpsArg(r.FPS) + ","
+	}
+	if device != CPU {
+		for i := range gpus {
+			g := &gpus[i]
+			// Encodes is vainfo's answer; without vainfo there is none, and the card is tried
+			// anyway, with the next recipe behind it.
+			if g.API != "vaapi" || (g.Encodes != nil && !has(g.Encodes, "h264")) || (device != "" && g.Device != device) {
+				continue
+			}
+			video := append(append([]string{"-c:v", "h264_vaapi"}, rate...), "-bf", "0")
+			name := g.Name
+			if name == "" {
+				name = g.Device
+			}
+			// The card doesn't turn a phone's picture by itself (ffmpeg's own turning is for
+			// pictures in memory), so it is told to, and ffmpeg is told not to.
+			scale := turn(src) + fmt.Sprintf("scale_vaapi=w=%d:h=%d:format=nv12", r.Width, r.Height)
+			// HDR10 (PQ) is tone-mapped on the card, which needs the file's mastering data;
+			// HLG is made to look right on an ordinary screen as it is, so it is only scaled
+			// (tonemap_vaapi refuses it). Either way the next recipe tone-maps in software.
+			if src.Video != nil && has(g.Codecs, src.Video.Codec) {
+				vf := fps + scale
+				if src.PQ() {
+					vf = fps + "tonemap_vaapi=format=nv12:t=bt709:p=bt709:m=bt709," + scale
+				}
+				out = append(out, Recipe{Engine: name, Device: g.Device, Pre: []string{"-noautorotate", "-hwaccel", "vaapi", "-hwaccel_device", g.Device, "-hwaccel_output_format", "vaapi"}, VF: vf, Video: video})
+			}
+			cpuVF := fmt.Sprintf("%sformat=nv12,scale=%d:%d,hwupload", fps, r.Width, r.Height)
+			if src.PQ() {
+				cpuVF = fps + toneMap + fmt.Sprintf(",scale=%d:%d,format=nv12,hwupload", r.Width, r.Height)
+			}
+			out = append(out, Recipe{Engine: name + ", decoded on the CPU", Device: g.Device, Pre: []string{"-init_hw_device", "vaapi=va:" + g.Device, "-filter_hw_device", "va"},
+				VF: cpuVF, Video: video})
+		}
+	}
+	if has(c.Encoders, "libx264") {
+		vf := fmt.Sprintf("%sscale=%d:%d,format=yuv420p", fps, r.Width, r.Height)
+		if src.PQ() {
+			vf = fps + toneMap + fmt.Sprintf(",scale=%d:%d,format=yuv420p", r.Width, r.Height)
+		}
+		out = append(out, Recipe{Engine: "CPU (libx264)", Device: CPU, VF: vf, Video: append([]string{"-c:v", "libx264", "-preset", "veryfast", "-sc_threshold", "0"}, rate...)})
+	}
+	return out
+}
+
+// turn is the card's filter that turns a picture the way it is meant to be shown.
+func turn(src Info) string {
+	if src.Video == nil {
+		return ""
+	}
+	switch src.Video.Rotation {
+	case 90:
+		return "transpose_vaapi=dir=clock,"
+	case 180:
+		return "transpose_vaapi=dir=reversal,"
+	case 270:
+		return "transpose_vaapi=dir=cclock,"
+	}
+	return ""
+}
+
+// toneMap turns an HDR10 picture into an ordinary one, in software.
+const toneMap = "zscale=t=linear:npl=100,format=gbrpf32le,zscale=p=bt709,tonemap=hable,zscale=t=bt709:m=bt709:r=tv"
+
+// Seg is the length of a piece, in seconds.
+const Seg = 3.0
+
+// tsBase is added to every run's times, so pieces from different runs follow on: without it
+// a run from the top would start just below zero (the B-frame and AAC delay) and the muxer
+// would shift that run alone.
+const tsBase = 10
+
+// pieceArgs is one run making quality r from piece n on, into dir as <n>.ts: an accurate seek
+// to n×Seg, a keyframe on every Seg mark and nowhere else (so every piece starts on one, and
+// pieces from any run and quality line up), times put back where that is in the film. in is a
+// path or, for a file on another machine, an http URL.
+func pieceArgs(dir, in string, src Info, rc Recipe, r Rung, n int) []string {
+	at := strconv.FormatFloat(float64(n)*Seg, 'f', 3, 64)
+	a := []string{"-nostdin", "-hide_banner", "-loglevel", "error", "-y"}
+	a = append(a, rc.Pre...)
+	if strings.HasPrefix(in, "http://") || strings.HasPrefix(in, "https://") {
+		a = append(a, "-reconnect", "1", "-reconnect_on_network_error", "1", "-reconnect_delay_max", "4")
+	}
+	a = append(a, "-ss", at, "-i", in, "-map", "0:v:0", "-map", "0:a:0?", "-sn", "-dn")
+	if rc.VF != "" {
+		a = append(a, "-vf", rc.VF)
+	}
+	a = append(a, rc.Video...)
+	if src.Audio == nil {
+		a = append(a, "-an")
+	} else {
+		a = append(a, "-c:a", "aac", "-b:a", "160k", "-ac", "2")
+	}
+	gop := int(math.Ceil(r.FPS*Seg)) * 4
+	a = append(a, "-g", strconv.Itoa(gop), "-force_key_frames", fmt.Sprintf("expr:gte(t,n_forced*%g)", Seg),
+		"-output_ts_offset", strconv.FormatFloat(float64(n)*Seg+tsBase, 'f', 3, 64),
+		"-f", "hls", "-hls_time", strconv.FormatFloat(Seg-0.5, 'f', 2, 64), "-hls_list_size", "0",
+		"-hls_flags", "temp_file", "-hls_segment_type", "mpegts", "-start_number", strconv.Itoa(n),
+		"-hls_segment_filename", dir+"/%d.ts", dir+"/ffmpeg.m3u8")
+	return a
+}
+
+func has(list []string, x string) bool {
+	for _, v := range list {
+		if v == x {
+			return true
+		}
+	}
+	return false
+}

internal/media/encode_test.go

@@ -0,0 +1,157 @@
+package media
+
+import (
+	"strings"
+	"testing"
+)
+
+func src(codec string, w, h int, fps float64) Info {
+	return Info{Duration: 100, Video: &Track{Codec: codec, Width: w, Height: h, FPS: fps}, Audio: &Track{Codec: "opus", Channels: 2}}
+}
+
+func TestLadder(t *testing.T) {
+	vr := src("hevc", 7680, 3840, 50)
+	vr.Video.Spherical = true
+	r := Ladder(vr)
+	if len(r) != 4 || r[0].Name != "3840" || r[0].Height != 1920 || r[0].level != "5.2" || r[3].FPS != 25 || r[0].Label != "2160s" {
+		t.Fatalf("8K 360: %+v", r)
+	}
+	if r[0].codecs != "avc1.640034,mp4a.40.2" {
+		t.Fatalf("codecs %q", r[0].codecs)
+	}
+	r = Ladder(src("h264", 2292, 960, 60)) // a capture: its own size on top, then the steps under it
+	if len(r) != 3 || r[0].Label != "960p" || r[0].Width != 2292 || r[0].FPS != 60 || r[0].Bitrate != 5_000_000 || r[1].Label != "720p" || r[1].Width != 1720 || r[1].FPS != 30 {
+		t.Fatalf("2292×960: %+v", r)
+	}
+	r = Ladder(src("h264", 1920, 1080, 59.94))
+	if len(r) != 3 || r[0].Label != "1080p" || r[0].FPS != 59.94 || r[1].FPS != 29.97 || r[2].Width != 854 {
+		t.Fatalf("1080p: %+v", r)
+	}
+	if r = Ladder(src("h264", 1080, 1920, 30)); r[0].Width != 1080 || r[0].Height != 1920 { // standing up
+		t.Fatalf("portrait: %+v", r)
+	}
+	if r = Ladder(src("h264", 320, 240, 30)); len(r) != 1 || r[0].Width != 320 || r[0].Label != "240p" {
+		t.Fatalf("tiny: %+v", r)
+	}
+	silent := src("h264", 1280, 720, 30)
+	silent.Audio = nil
+	if r = Ladder(silent); strings.Contains(r[0].codecs, "mp4a") {
+		t.Fatalf("no sound, no AAC: %q", r[0].codecs)
+	}
+	if Ladder(Info{Duration: 10}) != nil {
+		t.Fatal("no picture, no ladder")
+	}
+	if fpsArg(29.97) != "30000/1001" || fpsArg(25) != "25" {
+		t.Fatal(fpsArg(29.97), fpsArg(25))
+	}
+}
+
+func gridCaps() Caps {
+	return Caps{FFmpeg: "ffmpeg", FFprobe: "ffprobe", Encoders: []string{"aac", "libsvtav1", "libx264", "libx265"},
+		GPUs: []GPU{
+			{API: "vaapi", Device: "/dev/dri/renderD128", Name: "Intel UHD Graphics 750", Integrated: true, Codecs: []string{"h264", "hevc", "vp9"}, Encodes: []string{"h264", "hevc"}},
+			{API: "vaapi", Device: "/dev/dri/renderD129", Name: "Intel Arc A380", Codecs: []string{"h264", "hevc", "vp9"}, Encodes: []string{"av1", "h264", "hevc"}},
+		}}
+}
+
+func engineNames(r []Recipe) []string {
+	out := make([]string, len(r))
+	for i := range r {
+		out[i] = r[i].Engine
+	}
+	return out
+}
+
+func TestRecipes(t *testing.T) {
+	c := gridCaps()
+	in := src("hevc", 3840, 2160, 60)
+	r1080 := Ladder(in)[2]
+	// any device: the card first, decoding on it; then the iGPU the same way; then the CPU
+	got := strings.Join(engineNames(recipes(c, "", in, r1080)), "|")
+	if got != "Intel Arc A380|Intel Arc A380, decoded on the CPU|Intel UHD Graphics 750|Intel UHD Graphics 750, decoded on the CPU|CPU (libx264)" {
+		t.Fatalf("any: %s", got)
+	}
+	// the iGPU asked for: only it, then the CPU as the fallback
+	if got = strings.Join(engineNames(recipes(c, "/dev/dri/renderD128", in, r1080)), "|"); got != "Intel UHD Graphics 750|Intel UHD Graphics 750, decoded on the CPU|CPU (libx264)" {
+		t.Fatalf("iGPU: %s", got)
+	}
+	if got = strings.Join(engineNames(recipes(c, CPU, in, r1080)), "|"); got != "CPU (libx264)" {
+		t.Fatalf("cpu: %s", got)
+	}
+	// an AV1 source: neither card decodes it, so no same-card recipe
+	if got = strings.Join(engineNames(recipes(c, "/dev/dri/renderD129", src("av1", 1920, 1080, 30), r1080)), "|"); got != "Intel Arc A380, decoded on the CPU|CPU (libx264)" {
+		t.Fatalf("av1: %s", got)
+	}
+	// a machine with no GPU and no x264: nothing
+	bare := Caps{FFmpeg: "ffmpeg", FFprobe: "ffprobe", Encoders: []string{"aac"}}
+	if len(recipes(bare, "", in, r1080)) != 0 {
+		t.Fatal("no x264 means nothing")
+	}
+	// 30 fps from 60 for the lower rungs; HDR tone-mapped on both paths
+	r720 := Ladder(in)[3]
+	hdr := src("hevc", 3840, 2160, 60)
+	hdr.Video.ColorTransfer = "smpte2084"
+	rs := recipes(c, "", hdr, r720)
+	if !strings.HasPrefix(rs[0].VF, "fps=30,tonemap_vaapi") || !strings.Contains(rs[1].VF, "tonemap=hable") || !strings.HasSuffix(rs[1].VF, "hwupload") || !strings.Contains(rs[len(rs)-1].VF, "tonemap=hable") {
+		t.Fatalf("hdr: %q … %q … %q", rs[0].VF, rs[1].VF, rs[len(rs)-1].VF)
+	}
+	hdr.Video.ColorTransfer = "arib-std-b67" // HLG: shown as it is, on every path
+	if rs = recipes(c, "", hdr, r720); strings.Contains(rs[0].VF, "tonemap") || strings.Contains(rs[1].VF, "tonemap") {
+		t.Fatalf("hlg: %q … %q", rs[0].VF, rs[1].VF)
+	}
+	// a phone's picture, upright: the ladder by the shown size, turned on the card
+	phone := src("hevc", 1920, 1080, 30)
+	phone.Video.Rotation = 90
+	lr := Ladder(phone)
+	if lr[0].Width != 1080 || lr[0].Height != 1920 {
+		t.Fatalf("upright: %+v", lr[0])
+	}
+	if rs = recipes(c, "", phone, lr[0]); !strings.HasPrefix(rs[0].VF, "transpose_vaapi=dir=clock,scale_vaapi=w=1080:h=1920") || rs[0].Pre[0] != "-noautorotate" || strings.Contains(rs[1].VF, "transpose") {
+		t.Fatalf("turned: %q %v / %q", rs[0].VF, rs[0].Pre, rs[1].VF)
+	}
+	// no vainfo: the card is tried all the same
+	nov := gridCaps()
+	nov.GPUs[1].Encodes = nil
+	if rs = recipes(nov, "/dev/dri/renderD129", in, r1080); rs[0].Engine != "Intel Arc A380" || !Devices(nov)[1].OK {
+		t.Fatalf("no vainfo: %v", engineNames(rs))
+	}
+	if rs := recipes(c, "", in, r1080); strings.Contains(rs[0].VF, "fps=") {
+		t.Fatalf("same rate needs no fps filter: %q", rs[0].VF)
+	}
+}
+
+func TestDevices(t *testing.T) {
+	c := gridCaps()
+	c.Unusable = []GPU{{Device: "/dev/dri/renderD130", Name: "Something", Reason: "permission denied"}}
+	d := Devices(c)
+	if len(d) != 4 || !d[0].OK || !d[1].OK || d[2].OK || d[2].Reason == "" || d[3].ID != CPU || !d[3].OK {
+		t.Fatalf("%+v", d)
+	}
+	if d := Devices(Caps{Error: "ffmpeg is not installed"}); len(d) != 1 || d[0].OK {
+		t.Fatalf("no ffmpeg: %+v", d)
+	}
+}
+
+func TestPieceArgs(t *testing.T) {
+	in := src("h264", 1920, 1080, 60)
+	r := Ladder(in)[0]
+	rc := recipes(gridCaps(), "/dev/dri/renderD129", in, r)[0]
+	a := strings.Join(pieceArgs("/d", "/v.mkv", in, rc, r, 12), " ")
+	for _, want := range []string{"-hwaccel vaapi -hwaccel_device /dev/dri/renderD129", "-ss 36.000 -i /v.mkv", "-map 0:v:0 -map 0:a:0?",
+		"-vf scale_vaapi=w=1920:h=1080:format=nv12", "-c:v h264_vaapi -b:v 5000k -maxrate 7500k", "-level 4.2", "-c:a aac -b:a 160k -ac 2",
+		"-force_key_frames expr:gte(t,n_forced*3)", "-output_ts_offset 46.000", "-hls_time 2.50", "-start_number 12", "-hls_segment_filename /d/%d.ts"} {
+		if !strings.Contains(a, want) {
+			t.Errorf("missing %q in\n%s", want, a)
+		}
+	}
+	if strings.Contains(a, "-reconnect") {
+		t.Error("a path needs no reconnect")
+	}
+	if a := strings.Join(pieceArgs("/d", "http://10.0.0.234:8100/api/play-src/x", in, rc, r, 0), " "); !strings.Contains(a, "-reconnect 1") {
+		t.Error("a URL reconnects")
+	}
+	in.Audio = nil
+	if a := strings.Join(pieceArgs("/d", "/v", in, rc, r, 0), " "); !strings.Contains(a, "-an") {
+		t.Error("no sound means -an")
+	}
+}

internal/media/ffrun.go

@@ -0,0 +1,223 @@
+package media
+
+// Running one long ffmpeg: as the daemon's user directly, or as root through this binary's
+// run-ffmpeg helper when the file needs root to read. The helper is told to finish by its
+// standard input closing, which also happens by itself if the daemon goes away — so a
+// transcode never outlives the console that asked for it.
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"os"
+	"os/exec"
+	"sync"
+	"syscall"
+	"time"
+
+	"hamlab/internal/priv"
+)
+
+type ffproc struct {
+	cmd  *exec.Cmd
+	in   io.WriteCloser // the helper's stdin, root mode only
+	done chan struct{}
+	err  error
+	tail *tailBuf
+}
+
+// startFF launches ffmpeg with args, under nice where there is one.
+func startFF(c Caps, self string, root bool, args []string) (*ffproc, error) {
+	var argv []string
+	if root {
+		argv = priv.Wrap(append([]string{self, "run-ffmpeg"}, args...)...)
+	} else {
+		argv = append([]string{c.FFmpeg}, args...)
+		if c.Nice != "" {
+			argv = append([]string{c.Nice, "-n", "10"}, argv...)
+		}
+	}
+	cmd := exec.Command(argv[0], argv[1:]...)
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	p := &ffproc{cmd: cmd, done: make(chan struct{}), tail: &tailBuf{}}
+	cmd.Stderr = p.tail
+	cmd.Stdout = io.Discard
+	if root {
+		in, err := cmd.StdinPipe()
+		if err != nil {
+			return nil, err
+		}
+		p.in = in
+	}
+	if err := cmd.Start(); err != nil {
+		return nil, err
+	}
+	go func() {
+		p.err = cmd.Wait()
+		close(p.done)
+	}()
+	return p, nil
+}
+
+// exited reports whether ffmpeg has finished, and how.
+func (p *ffproc) exited() (bool, error) {
+	select {
+	case <-p.done:
+		return true, p.err
+	default:
+		return false, nil
+	}
+}
+
+// end asks ffmpeg to finish and waits a little for it.
+func (p *ffproc) end() {
+	if done, _ := p.exited(); done {
+		return
+	}
+	if p.in != nil {
+		p.in.Close()
+	} else {
+		_ = syscall.Kill(-p.cmd.Process.Pid, syscall.SIGTERM)
+	}
+	select {
+	case <-p.done:
+	case <-time.After(5 * time.Second):
+		_ = syscall.Kill(-p.cmd.Process.Pid, syscall.SIGKILL) // a root helper ignores this; it ends on its own within its own grace
+		select {
+		case <-p.done:
+		case <-time.After(10 * time.Second):
+		}
+	}
+}
+
+// pause stops ffmpeg where it is (SIGSTOP), and resume lets it go on: a stream far enough
+// ahead of its player waits rather than making the rest of the film. A root run is paused by
+// its helper, which is told on its standard input.
+func (p *ffproc) pause() error  { return p.signal(syscall.SIGSTOP, "stop\n") }
+func (p *ffproc) resume() error { return p.signal(syscall.SIGCONT, "cont\n") }
+
+func (p *ffproc) signal(sig syscall.Signal, word string) error {
+	if done, _ := p.exited(); done {
+		return errors.New("ended")
+	}
+	if p.in != nil {
+		_, err := io.WriteString(p.in, word)
+		return err
+	}
+	return syscall.Kill(-p.cmd.Process.Pid, sig)
+}
+
+// kill ends ffmpeg now, without waiting: a paused one too.
+func (p *ffproc) kill() {
+	if done, _ := p.exited(); done {
+		return
+	}
+	if p.in != nil {
+		p.in.Close() // the helper ends it, waking it first if it is paused
+		return
+	}
+	_ = syscall.Kill(-p.cmd.Process.Pid, syscall.SIGKILL)
+}
+
+// lastWords is what ffmpeg said last, for the record.
+func (p *ffproc) lastWords() string { return p.tail.last() }
+
+// tailBuf keeps the last few KB written to it.
+type tailBuf struct {
+	mu sync.Mutex
+	b  []byte
+}
+
+const tailKeep = 4096
+
+func (t *tailBuf) Write(b []byte) (int, error) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.b = append(t.b, b...)
+	if len(t.b) > tailKeep {
+		t.b = t.b[len(t.b)-tailKeep:]
+	}
+	return len(b), nil
+}
+
+func (t *tailBuf) last() string {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return lastLine(string(bytes.TrimSpace(t.b)))
+}
+
+// RunFFmpegHelper implements `hamlab run-ffmpeg <args…>`: ffmpeg as this user (root, when
+// the daemon asked through sudo), finishing when stdin closes. Returns ffmpeg's exit code.
+func RunFFmpegHelper(args []string, stdin io.Reader, stderr io.Writer) int {
+	ffmpeg, err := exec.LookPath("ffmpeg")
+	if err != nil {
+		io.WriteString(stderr, "ffmpeg is not installed\n")
+		return 1
+	}
+	argv := []string{ffmpeg}
+	if nice, err := exec.LookPath("nice"); err == nil {
+		argv = []string{nice, "-n", "10", ffmpeg}
+	}
+	cmd := exec.Command(argv[0], append(argv[1:], args...)...)
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true}
+	cmd.Stderr = stderr
+	cmd.Stdout = io.Discard
+	if err := cmd.Start(); err != nil {
+		io.WriteString(stderr, err.Error()+"\n")
+		return 1
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	go func() {
+		// "stop" and "cont" pause and resume it; the end of input (the daemon letting go)
+		// ends it.
+		sc := bufio.NewScanner(stdin)
+		for sc.Scan() {
+			switch sc.Text() {
+			case "stop":
+				_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGSTOP)
+			case "cont":
+				_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGCONT)
+			}
+		}
+		cancel()
+	}()
+	done := make(chan error, 1)
+	go func() { done <- cmd.Wait() }()
+	var werr error
+	select {
+	case werr = <-done:
+	case <-ctx.Done():
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGTERM)
+		_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGCONT) // a paused one can't act on TERM
+		select {
+		case werr = <-done:
+		case <-time.After(5 * time.Second):
+			_ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL)
+			werr = <-done
+		}
+	}
+	var ee *exec.ExitError
+	if errors.As(werr, &ee) {
+		return ee.ExitCode()
+	}
+	if werr != nil {
+		return 1
+	}
+	return 0
+}
+
+// clearDir empties a folder without removing it.
+func clearDir(dir string) error {
+	ents, err := os.ReadDir(dir)
+	if err != nil {
+		return err
+	}
+	for _, e := range ents {
+		if err := os.RemoveAll(dir + "/" + e.Name()); err != nil {
+			return err
+		}
+	}
+	return nil
+}

internal/media/inspect.go

@@ -0,0 +1,176 @@
+package media
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"math"
+	"os/exec"
+	"strconv"
+	"strings"
+
+	"hamlab/internal/priv"
+)
+
+// Track is one stream of a media file, as ffprobe reports it.
+type Track struct {
+	Index         int     `json:"index"`
+	Type          string  `json:"type"` // video | audio
+	Codec         string  `json:"codec"`
+	Profile       string  `json:"profile,omitempty"`
+	PixFmt        string  `json:"pix_fmt,omitempty"`
+	Width         int     `json:"width,omitempty"`
+	Height        int     `json:"height,omitempty"`
+	FPS           float64 `json:"fps,omitempty"`
+	ColorTransfer string  `json:"color_transfer,omitempty"` // smpte2084 / arib-std-b67 mean HDR
+	Channels      int     `json:"channels,omitempty"`
+	AttachedPic   bool    `json:"attached_pic,omitempty"`
+	Spherical     bool    `json:"spherical,omitempty"` // an equirectangular 360 picture
+	Rotation      int     `json:"rotation,omitempty"`  // degrees clockwise to turn it to be shown: 0, 90, 180, 270 (a phone held upright)
+}
+
+// Shown is the picture's size as it is shown, turned by its rotation.
+func (t *Track) Shown() (w, h int) {
+	if t.Rotation == 90 || t.Rotation == 270 {
+		return t.Height, t.Width
+	}
+	return t.Width, t.Height
+}
+
+// Info is what a file holds: the picture to take, the sound to go with it, and the whole.
+type Info struct {
+	Container string  `json:"container"` // "matroska,webm", "mov,mp4,m4a,3gp,3g2,mj2"
+	Duration  float64 `json:"duration"`
+	BitRate   int64   `json:"bit_rate,omitempty"` // bits per second, whole file
+	Size      int64   `json:"size,omitempty"`
+	Video     *Track  `json:"video,omitempty"` // the first real picture stream; cover art is not it
+	Audio     *Track  `json:"audio,omitempty"` // the first sound stream
+}
+
+// PQ reports HDR10 (and Dolby Vision's base layer): a picture that can't be shown on an SDR
+// screen without tone mapping. HLG, the other kind, can, if a little flat.
+func (i Info) PQ() bool { return i.Video != nil && i.Video.ColorTransfer == "smpte2084" }
+
+// HDR reports a picture that needs tone mapping to look right on an SDR screen. (The player
+// tone-maps only PQ: HLG is made to be shown on an SDR screen as it is.)
+func (i Info) HDR() bool {
+	return i.Video != nil && (i.Video.ColorTransfer == "smpte2084" || i.Video.ColorTransfer == "arib-std-b67")
+}
+
+type probeJSON struct {
+	Streams []struct {
+		Index         int    `json:"index"`
+		CodecType     string `json:"codec_type"`
+		CodecName     string `json:"codec_name"`
+		Profile       string `json:"profile"`
+		PixFmt        string `json:"pix_fmt"`
+		Width         int    `json:"width"`
+		Height        int    `json:"height"`
+		RFrameRate    string `json:"r_frame_rate"`
+		AvgFrameRate  string `json:"avg_frame_rate"`
+		ColorTransfer string `json:"color_transfer"`
+		Channels      int    `json:"channels"`
+		Disposition   struct {
+			AttachedPic int `json:"attached_pic"`
+		} `json:"disposition"`
+		SideData []struct {
+			Type       string  `json:"side_data_type"`
+			Projection string  `json:"projection"`
+			Rotation   float64 `json:"rotation"`
+		} `json:"side_data_list"`
+	} `json:"streams"`
+	Format struct {
+		FormatName string `json:"format_name"`
+		Duration   string `json:"duration"`
+		BitRate    string `json:"bit_rate"`
+		Size       string `json:"size"`
+	} `json:"format"`
+}
+
+// Inspect asks ffprobe what a file is. As root through sudo when asked, for a file only
+// root may read. An error about the file itself is a DecodeError.
+func Inspect(ctx context.Context, c Caps, path string, root bool) (Info, error) {
+	if c.FFprobe == "" {
+		return Info{}, errors.New("ffprobe is not installed")
+	}
+	argv := []string{c.FFprobe, "-v", "error", "-show_entries",
+		"stream=index,codec_type,codec_name,profile,pix_fmt,width,height,r_frame_rate,avg_frame_rate,color_transfer,channels,disposition:stream_side_data=side_data_type,projection,rotation:format=format_name,duration,bit_rate,size",
+		"-of", "json", path}
+	if root {
+		argv = priv.Wrap(argv...)
+	}
+	cmd := exec.CommandContext(ctx, argv[0], argv[1:]...)
+	var errb bytes.Buffer
+	cmd.Stderr = &errb
+	out, err := cmd.Output()
+	if err != nil {
+		if ctx.Err() != nil {
+			return Info{}, ctx.Err()
+		}
+		msg := lastLine(errb.String())
+		if msg == "" {
+			msg = "ffprobe: " + err.Error()
+		}
+		return Info{}, &DecodeError{Msg: msg}
+	}
+	var pj probeJSON
+	if err := json.Unmarshal(out, &pj); err != nil {
+		return Info{}, &DecodeError{Msg: "ffprobe: unreadable answer"}
+	}
+	in := Info{Container: pj.Format.FormatName}
+	in.Duration, _ = strconv.ParseFloat(pj.Format.Duration, 64)
+	in.BitRate, _ = strconv.ParseInt(pj.Format.BitRate, 10, 64)
+	in.Size, _ = strconv.ParseInt(pj.Format.Size, 10, 64)
+	var art *Track
+	for _, s := range pj.Streams {
+		st := &Track{Index: s.Index, Type: s.CodecType, Codec: s.CodecName, Profile: s.Profile, PixFmt: s.PixFmt, Width: s.Width, Height: s.Height,
+			ColorTransfer: s.ColorTransfer, Channels: s.Channels, AttachedPic: s.Disposition.AttachedPic != 0}
+		// A 360 video says so in its spherical tag (ffmpeg reads the old XML one and the sv3d
+		// box); an untagged one is still taken for 360 when it is 2:1 and too big for anything
+		// else.
+		for _, sd := range s.SideData {
+			if sd.Type == "Spherical Mapping" && strings.HasPrefix(sd.Projection, "equirectangular") {
+				st.Spherical = true
+			}
+			if sd.Type == "Display Matrix" {
+				// ffprobe's rotation is counter-clockwise; ffmpeg turns it back the other way
+				st.Rotation = ((-int(math.Round(sd.Rotation/90))*90)%360 + 360) % 360
+			}
+		}
+		st.Spherical = st.Spherical || (s.CodecType == "video" && s.Width == 2*s.Height && s.Width >= 3840)
+		st.FPS = fps(s.AvgFrameRate)
+		if st.FPS == 0 {
+			st.FPS = fps(s.RFrameRate)
+		}
+		switch {
+		case s.CodecType == "video" && st.AttachedPic:
+			if art == nil {
+				art = st
+			}
+		case s.CodecType == "video" && in.Video == nil:
+			in.Video = st
+		case s.CodecType == "audio" && in.Audio == nil:
+			in.Audio = st
+		}
+	}
+	if in.Video == nil {
+		in.Video = art // cover art is the only picture there is
+	}
+	return in, nil
+}
+
+// fps parses ffprobe's "60000/1001".
+func fps(r string) float64 {
+	n, d, ok := strings.Cut(r, "/")
+	if !ok {
+		v, _ := strconv.ParseFloat(r, 64)
+		return v
+	}
+	nf, _ := strconv.ParseFloat(n, 64)
+	df, _ := strconv.ParseFloat(d, 64)
+	if df == 0 {
+		return 0
+	}
+	return nf / df
+}

internal/media/owner.go

@@ -0,0 +1,26 @@
+package media
+
+import (
+	"fmt"
+	"os"
+	"os/user"
+	"strconv"
+	"syscall"
+)
+
+// ownerOf is "root:render 0660" for a device node, the thing to say when it cannot be opened.
+func ownerOf(st os.FileInfo) string {
+	sys, ok := st.Sys().(*syscall.Stat_t)
+	if !ok {
+		return ""
+	}
+	u := strconv.Itoa(int(sys.Uid))
+	if x, err := user.LookupId(u); err == nil {
+		u = x.Username
+	}
+	g := strconv.Itoa(int(sys.Gid))
+	if x, err := user.LookupGroupId(g); err == nil {
+		g = x.Name
+	}
+	return fmt.Sprintf("%s:%s %04o", u, g, st.Mode().Perm())
+}

internal/media/play.go

@@ -0,0 +1,462 @@
+package media
+
+// Playing a video in the browser at the quality the connection can take: HLS, made on the fly
+// by ffmpeg on the device asked for (the Transcode device setting), YouTube's way. The player
+// is told every quality is all there from the start, in Seg-second pieces, and each piece is
+// made when it is first asked for.
+//
+// One ffmpeg runs per play at a time. It starts at the piece asked for and runs on ahead of the
+// player, paused once it is far enough ahead; a piece asked for well past where it has got to
+// (a seek), or at another quality, ends it and starts a new one there. Every run is made the
+// same way (pieceArgs), so pieces from different runs and qualities follow on from one another.
+//
+// The file is a path on this machine or, when the device asked for is on another one, a URL
+// the hub serves it at. Nothing is kept: a play nobody asks anything of is forgotten, and the
+// folder is emptied when the daemon starts.
+
+import (
+	"bytes"
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io/fs"
+	"log"
+	"math"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+const (
+	runAhead = 10               // pieces a run may make past the last one asked for before it is paused
+	jump     = 3                // a piece more than this far past what's made is a seek: start again there
+	idleRun  = 45 * time.Second // a run nobody has asked anything of for this long is ended
+	idlePlay = 30 * time.Minute // a play nobody has asked anything of for this long is forgotten
+	budget   = 2 << 30          // bytes of pieces one play keeps; those asked for least lately go first
+	// PieceWait is the longest a request waits for its piece: under the hub proxy's 60 s wait
+	// for a node to answer.
+	PieceWait = 45 * time.Second
+)
+
+var ErrNotFound = errors.New("no such piece")
+
+// Plays is every play on this machine.
+type Plays struct {
+	dir     string
+	self    string // this binary, for root runs through run-ffmpeg
+	maxRuns int
+
+	mu    sync.Mutex
+	plays map[string]*Play
+	stop  chan struct{}
+}
+
+// NewPlays keeps pieces under <dataDir>/transcode, which it empties first.
+func NewPlays(dataDir, self string, maxRuns int) *Plays {
+	dir := filepath.Join(dataDir, "transcode")
+	_ = os.MkdirAll(dir, 0o700)
+	_ = clearDir(dir)
+	m := &Plays{dir: dir, self: self, maxRuns: max(maxRuns, 1), plays: map[string]*Play{}, stop: make(chan struct{})}
+	go m.tend()
+	return m
+}
+
+// Play is one video opened for watching.
+type Play struct {
+	ID     string `json:"id"`
+	Name   string `json:"name"` // the file's name, for the record
+	Info   Info   `json:"info"`
+	Rungs  []Rung `json:"rungs"`  // best first
+	Device string `json:"device"` // asked for: a render node, "cpu", or "" for the best here
+	Remote bool   `json:"remote"` // the file is on another machine, read over the network
+
+	caps Caps
+	in   string
+	root bool
+	segs int
+	dir  string
+	m    *Plays
+
+	mu    sync.Mutex
+	seen  time.Time
+	run   *playRun
+	tried map[int]int // per rung: recipes that failed to make anything, skipped from now on
+}
+
+type playRun struct {
+	rung   int
+	recipe Recipe
+	start  int // the first piece this run makes
+	head   int // the last piece finished (start-1 before the first)
+	want   int // the last piece asked for
+	asked  time.Time
+	proc   *ffproc
+	paused bool
+	dead   bool // ended, or exited
+	killed bool // ended by us, not by itself
+	exited bool
+	err    error
+	tick   chan struct{} // closed when head moves or the run ends
+}
+
+func newPlayID() string {
+	b := make([]byte, 12)
+	_, _ = rand.Read(b)
+	return hex.EncodeToString(b)
+}
+
+// Open starts a play of in (a path, or an http URL for a file on another machine). Nothing
+// runs until a piece is asked for.
+func (m *Plays) Open(c Caps, root bool, in, name string, src Info, device string) (*Play, error) {
+	rungs := Ladder(src)
+	if len(rungs) == 0 || src.Duration <= 0 {
+		return nil, errors.New("this video's length or picture size isn't known, so it can't be played")
+	}
+	if len(recipes(c, device, src, rungs[0])) == 0 {
+		return nil, errors.New("nothing on this machine encodes H.264 (no GPU that does, and no libx264)")
+	}
+	segs := max(int(math.Ceil((src.Duration-0.25)/Seg)), 1) // the last piece takes in what's left
+	p := &Play{ID: newPlayID(), Name: name, Info: src, Rungs: rungs, Device: device, Remote: strings.HasPrefix(in, "http"),
+		caps: c, in: in, root: root, segs: segs, m: m, seen: time.Now(), tried: map[int]int{}}
+	p.dir = filepath.Join(m.dir, p.ID)
+	m.mu.Lock()
+	m.plays[p.ID] = p
+	m.mu.Unlock()
+	return p, nil
+}
+
+func (m *Plays) Find(id string) (*Play, bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	p, ok := m.plays[id]
+	return p, ok
+}
+
+// Close ends a play and deletes its pieces.
+func (m *Plays) Close(id string) {
+	m.mu.Lock()
+	p, ok := m.plays[id]
+	delete(m.plays, id)
+	m.mu.Unlock()
+	if ok {
+		p.mu.Lock()
+		p.end()
+		p.mu.Unlock()
+		go os.RemoveAll(p.dir)
+	}
+}
+
+func (p *Play) rung(name string) int {
+	for i, r := range p.Rungs {
+		if r.Name == name {
+			return i
+		}
+	}
+	return -1
+}
+
+// Master is the playlist of qualities, lowest first, so a player that starts on the first one
+// listed starts on the one that surely plays.
+func (p *Play) Master() []byte {
+	var b bytes.Buffer
+	b.WriteString("#EXTM3U\n#EXT-X-VERSION:3\n#EXT-X-INDEPENDENT-SEGMENTS\n")
+	for i := len(p.Rungs) - 1; i >= 0; i-- {
+		r := p.Rungs[i]
+		fmt.Fprintf(&b, "#EXT-X-STREAM-INF:BANDWIDTH=%d,AVERAGE-BANDWIDTH=%d,RESOLUTION=%dx%d,FRAME-RATE=%.3f,CODECS=\"%s\"\n%s.m3u8\n",
+			r.Peak, r.Bitrate+audioRate, r.Width, r.Height, r.FPS, r.codecs, r.Name)
+	}
+	return b.Bytes()
+}
+
+// Media is one quality's playlist: every piece, made or not.
+func (p *Play) Media(name string) ([]byte, bool) {
+	if p.rung(name) < 0 {
+		return nil, false
+	}
+	var b bytes.Buffer
+	last := p.Info.Duration - float64(p.segs-1)*Seg
+	fmt.Fprintf(&b, "#EXTM3U\n#EXT-X-VERSION:3\n#EXT-X-TARGETDURATION:%d\n#EXT-X-MEDIA-SEQUENCE:0\n#EXT-X-PLAYLIST-TYPE:VOD\n#EXT-X-INDEPENDENT-SEGMENTS\n",
+		int(math.Ceil(math.Max(last, Seg))))
+	for n := 0; n < p.segs; n++ {
+		d := Seg
+		if n == p.segs-1 {
+			d = last
+		}
+		fmt.Fprintf(&b, "#EXTINF:%.6f,\n%s/%d.ts\n", d, name, n)
+	}
+	b.WriteString("#EXT-X-ENDLIST\n")
+	return b.Bytes(), true
+}
+
+func (p *Play) piece(rung, n int) string {
+	return filepath.Join(p.dir, p.Rungs[rung].Name, strconv.Itoa(n)+".ts")
+}
+
+// Segment answers the file of piece n at quality name, making it first if need be: it waits
+// for the run already making it, or starts one there.
+func (p *Play) Segment(done <-chan struct{}, name string, n int) (string, error) {
+	ri := p.rung(name)
+	if ri < 0 || n < 0 || n >= p.segs {
+		return "", ErrNotFound
+	}
+	path := p.piece(ri, n)
+	deadline := time.After(PieceWait)
+	for {
+		p.mu.Lock()
+		now := time.Now()
+		p.seen = now
+		r := p.run
+		if r != nil && r.rung == ri && !r.dead {
+			r.want, r.asked = n, now
+		}
+		if exists(path) {
+			p.mu.Unlock()
+			_ = os.Chtimes(path, now, now) // the budget keeps what was asked for last
+			return path, nil
+		}
+		if r != nil && r.exited && !r.killed && r.rung == ri && r.start == n {
+			// This run started at this very piece and ended without it: that way of making
+			// it doesn't work here. The next one is tried, if there is one.
+			p.tried[ri]++
+			log.Printf("files: play %s: %s made nothing at %s piece %d: %v: %s", p.Name, r.recipe.Engine, name, n, r.err, r.proc.lastWords())
+			if p.tried[ri] >= len(recipes(p.caps, p.Device, p.Info, p.Rungs[ri])) {
+				err := fmt.Errorf("couldn't make %s: %s", p.Rungs[ri].Label, r.proc.lastWords())
+				p.mu.Unlock()
+				return "", err
+			}
+			p.run = nil
+			r = nil
+		}
+		if r == nil || r.dead || r.rung != ri || n < r.start || n <= r.head || n > r.head+jump {
+			p.mu.Unlock()
+			p.m.makeRoom(p)
+			p.mu.Lock()
+			if p.run == r { // nobody started one meanwhile
+				if err := p.start(ri, n); err != nil {
+					p.mu.Unlock()
+					return "", err
+				}
+			}
+			p.mu.Unlock()
+			continue
+		}
+		tick := r.tick
+		p.mu.Unlock()
+		select {
+		case <-tick:
+		case <-time.After(200 * time.Millisecond):
+		case <-done:
+			return "", errors.New("gone")
+		case <-deadline:
+			return "", fmt.Errorf("%s piece %d took longer than %s", name, n, PieceWait)
+		}
+	}
+}
+
+// end stops this play's run. p.mu is held.
+func (p *Play) end() {
+	if r := p.run; r != nil && !r.dead {
+		r.dead, r.killed = true, true
+		r.proc.kill()
+	}
+}
+
+// makeRoom ends the run asked of least lately, if every slot is taken by another play. It
+// never holds two plays' locks at once.
+func (m *Plays) makeRoom(except *Play) {
+	m.mu.Lock()
+	plays := make([]*Play, 0, len(m.plays))
+	for _, p := range m.plays {
+		if p != except {
+			plays = append(plays, p)
+		}
+	}
+	m.mu.Unlock()
+	var oldest *Play
+	var when time.Time
+	running := 0
+	for _, p := range plays {
+		p.mu.Lock()
+		if r := p.run; r != nil && !r.dead {
+			running++
+			if oldest == nil || r.asked.Before(when) {
+				oldest, when = p, r.asked
+			}
+		}
+		p.mu.Unlock()
+	}
+	if running >= m.maxRuns && oldest != nil {
+		oldest.mu.Lock()
+		oldest.end()
+		oldest.mu.Unlock()
+		log.Printf("files: %d plays encoding; ended %s's, asked of least lately", running, oldest.Name)
+	}
+}
+
+// start begins a run making quality ri from piece n on, ending the one before. p.mu is held.
+func (p *Play) start(ri, n int) error {
+	p.end()
+	rs := recipes(p.caps, p.Device, p.Info, p.Rungs[ri])
+	if p.tried[ri] >= len(rs) {
+		return errors.New("nothing here can make this quality")
+	}
+	rc := rs[p.tried[ri]]
+	out := filepath.Join(p.dir, p.Rungs[ri].Name)
+	if err := os.MkdirAll(out, 0o700); err != nil {
+		return err
+	}
+	proc, err := startFF(p.caps, p.m.self, p.root, pieceArgs(out, p.in, p.Info, rc, p.Rungs[ri], n))
+	if err != nil {
+		return err
+	}
+	r := &playRun{rung: ri, recipe: rc, start: n, head: n - 1, want: n, asked: time.Now(), proc: proc, tick: make(chan struct{})}
+	p.run = r
+	go func() {
+		<-proc.done
+		p.mu.Lock()
+		defer p.mu.Unlock()
+		r.dead, r.exited, r.err = true, true, proc.err
+		p.scan(r)
+		close(r.tick)
+		r.tick = make(chan struct{})
+	}()
+	return nil
+}
+
+// scan moves a run's head on past the pieces it has finished. p.mu is held.
+func (p *Play) scan(r *playRun) bool {
+	moved := false
+	for r.head+1 < p.segs && exists(p.piece(r.rung, r.head+1)) {
+		r.head++
+		moved = true
+	}
+	return moved
+}
+
+// PlayStatus is what a play is doing, for the player's menu.
+type PlayStatus struct {
+	Engine  string `json:"engine,omitempty"` // what the run going now runs on
+	Quality string `json:"quality,omitempty"`
+	From    int    `json:"from"` // seconds into the film the run started at
+	Ahead   int    `json:"ahead"`
+	Paused  bool   `json:"paused,omitempty"`
+}
+
+func (p *Play) Status() PlayStatus {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	r := p.run
+	if r == nil || r.dead {
+		return PlayStatus{}
+	}
+	return PlayStatus{Engine: r.recipe.Engine, Quality: p.Rungs[r.rung].Label, From: int(float64(r.start) * Seg), Ahead: r.head - r.want, Paused: r.paused}
+}
+
+// Engine is what this play would run on first, for the player to say before anything runs.
+func (p *Play) Engine() string {
+	rs := recipes(p.caps, p.Device, p.Info, p.Rungs[0])
+	if len(rs) == 0 {
+		return ""
+	}
+	return rs[0].Engine
+}
+
+// tend, ten times a second: notices finished pieces, pauses a run that is far enough ahead and
+// wakes it when the player catches up, ends one nobody is asking anything of; and every ten
+// seconds keeps each play inside its budget and forgets plays nobody watches.
+func (m *Plays) tend() {
+	t := time.NewTicker(100 * time.Millisecond)
+	defer t.Stop()
+	for i := 0; ; i++ {
+		select {
+		case <-m.stop:
+			return
+		case <-t.C:
+		}
+		m.mu.Lock()
+		plays := make([]*Play, 0, len(m.plays))
+		for _, p := range m.plays {
+			plays = append(plays, p)
+		}
+		m.mu.Unlock()
+		now := time.Now()
+		for _, p := range plays {
+			p.mu.Lock()
+			if r := p.run; r != nil && !r.dead {
+				if p.scan(r) {
+					close(r.tick)
+					r.tick = make(chan struct{})
+				}
+				ahead := r.head - r.want
+				switch {
+				case now.Sub(r.asked) > idleRun:
+					p.end()
+				case !r.paused && ahead >= runAhead:
+					if r.proc.pause() == nil {
+						r.paused = true
+					}
+				case r.paused && ahead < runAhead-3:
+					if r.proc.resume() == nil {
+						r.paused = false
+					}
+				}
+			}
+			idle := now.Sub(p.seen) > idlePlay
+			p.mu.Unlock()
+			if idle {
+				m.Close(p.ID)
+			} else if i%100 == 0 {
+				p.trim()
+			}
+		}
+	}
+}
+
+// trim deletes the pieces asked for least lately until the play is inside its budget, never
+// the ones its run has made ahead of the player.
+func (p *Play) trim() {
+	type piece struct {
+		path string
+		size int64
+		at   time.Time
+	}
+	var all []piece
+	var total int64
+	_ = filepath.WalkDir(p.dir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() || !strings.HasSuffix(path, ".ts") {
+			return nil
+		}
+		if fi, err := d.Info(); err == nil {
+			all = append(all, piece{path, fi.Size(), fi.ModTime()})
+			total += fi.Size()
+		}
+		return nil
+	})
+	if total <= budget {
+		return
+	}
+	p.mu.Lock()
+	keep := map[string]bool{}
+	if r := p.run; r != nil && !r.dead {
+		for n := r.want - 1; n <= r.head+1; n++ {
+			if n >= 0 && n < p.segs {
+				keep[p.piece(r.rung, n)] = true
+			}
+		}
+	}
+	p.mu.Unlock()
+	sort.Slice(all, func(a, b int) bool { return all[a].at.Before(all[b].at) })
+	for _, x := range all {
+		if total <= budget*3/4 {
+			break
+		}
+		if !keep[x.path] && os.Remove(x.path) == nil {
+			total -= x.size
+		}
+	}
+}

internal/media/play_test.go

@@ -0,0 +1,129 @@
+package media
+
+import (
+	"context"
+	"encoding/json"
+	"math"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+// inspectPiece answers when a piece's first video packet is shown, whether it is a keyframe,
+// how many keyframes the piece has, and when its last packet is.
+func inspectPiece(t *testing.T, path string) (first float64, key bool, keys int, last float64) {
+	t.Helper()
+	b, err := exec.Command("ffprobe", "-v", "error", "-show_entries", "packet=pts_time,flags,codec_type", "-of", "json", path).Output()
+	if err != nil {
+		t.Fatalf("ffprobe %s: %v", path, err)
+	}
+	var p struct {
+		Packets []struct {
+			PTS   string `json:"pts_time"`
+			Flags string `json:"flags"`
+			Type  string `json:"codec_type"`
+		} `json:"packets"`
+	}
+	_ = json.Unmarshal(b, &p)
+	first = -1
+	for _, k := range p.Packets {
+		if k.Type != "video" {
+			continue
+		}
+		x, _ := strconv.ParseFloat(k.PTS, 64)
+		if first < 0 {
+			first, key = x, strings.HasPrefix(k.Flags, "K")
+		}
+		first = math.Min(first, x)
+		last = math.Max(last, x)
+		if strings.HasPrefix(k.Flags, "K") {
+			keys++
+		}
+	}
+	return
+}
+
+// TestPieces makes pieces of a made-up video (or SRC, on DEVICE, to try the real thing on a
+// machine with a GPU) in order and after a seek, at two qualities, and checks they line up:
+// each starts on a keyframe at its own place in the film, with no other keyframe inside it.
+func TestPieces(t *testing.T) {
+	if _, err := exec.LookPath("ffmpeg"); err != nil {
+		t.Skip("no ffmpeg")
+	}
+	dir := t.TempDir()
+	in := os.Getenv("SRC")
+	if in == "" {
+		in = filepath.Join(dir, "in.mkv")
+		if out, err := exec.Command("ffmpeg", "-v", "error", "-f", "lavfi", "-i", "testsrc2=size=1920x1080:rate=50:duration=40",
+			"-f", "lavfi", "-i", "sine=frequency=440:duration=40", "-c:v", "libx264", "-preset", "ultrafast", "-g", "500",
+			"-c:a", "libopus", "-shortest", in).CombinedOutput(); err != nil {
+			t.Fatalf("making the test video: %v: %s", err, out)
+		}
+	}
+	caps := Probe(context.Background())
+	if caps.Error != "" {
+		t.Skip(caps.Error)
+	}
+	info, err := Inspect(context.Background(), caps, in, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	m := NewPlays(dir, "", 2)
+	device := os.Getenv("DEVICE")
+	if device == "" {
+		device = CPU
+	}
+	p, err := m.Open(caps, false, in, "in.mkv", info, device)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer m.Close(p.ID)
+	if !strings.Contains(string(p.Master()), "RESOLUTION=") {
+		t.Fatal(string(p.Master()))
+	}
+	low := p.Rungs[len(p.Rungs)-1].Name
+	var offset float64
+	far := min(p.segs-2, 60)
+	for i, n := range []int{0, 1, 2, far, far + 1, 3} {
+		t0 := time.Now()
+		path, err := p.Segment(nil, low, n)
+		if err != nil {
+			t.Fatalf("piece %d: %v", n, err)
+		}
+		first, key, keys, last := inspectPiece(t, path)
+		if i == 0 {
+			offset = first
+		}
+		at := first - offset
+		t.Logf("piece %d: %d ms on %s, starts %.3f, %d keyframe(s), %.2f s long", n, time.Since(t0).Milliseconds(), p.Status().Engine, at, keys, last-first)
+		if !key || keys != 1 {
+			t.Errorf("piece %d: first packet keyframe %v, %d keyframes", n, key, keys)
+		}
+		if math.Abs(at-float64(n)*Seg) > 0.05 {
+			t.Errorf("piece %d starts at %.3f, want %.3f", n, at, float64(n)*Seg)
+		}
+		if n < p.segs-1 && math.Abs(last-first-Seg) > 0.1 {
+			t.Errorf("piece %d is %.3f s long", n, last-first)
+		}
+	}
+	// another quality, at a piece already made at the first: its own run, lined up too
+	if len(p.Rungs) > 1 {
+		path, err := p.Segment(nil, p.Rungs[0].Name, 2)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if first, key, _, _ := inspectPiece(t, path); !key || math.Abs(first-offset-2*Seg) > 0.05 {
+			t.Errorf("%s piece 2 starts %.3f (keyframe %v)", p.Rungs[0].Name, first-offset, key)
+		}
+	}
+	if _, err := p.Segment(nil, low, p.segs); err != ErrNotFound {
+		t.Errorf("past the end: %v", err)
+	}
+	if _, err := p.Segment(nil, "999", 0); err != ErrNotFound {
+		t.Errorf("no such quality: %v", err)
+	}
+}

internal/media/thumbs.go

@@ -0,0 +1,656 @@
+// Package thumbs makes the Files tab's previews: one small JPEG for an image or a video,
+// by ffmpeg, decoded on a GPU where the machine has one it can use and on the CPU
+// otherwise.
+//
+// Nothing about the machine is assumed. A probe looks ffmpeg and ffprobe up, opens every
+// /dev/dri/renderD* and exercises it (a VAAPI upload and download of a synthetic frame),
+// so a node the daemon's user cannot open, or a driver that does not speak VAAPI, is
+// reported once rather than tried per file. vainfo, where installed, says which codecs
+// each node decodes, and a video goes to the first node that lists its codec; without
+// vainfo the first working node is tried and ffmpeg falls back to software on its own when
+// the stream turns out unsupported. A hardware run that fails outright is retried on the
+// CPU before the file is called undecodable. Images are always decoded on the CPU: one
+// frame of a JPEG at a reduced DCT size costs less than the trip through a GPU.
+package media
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"hamlab/internal/metrics"
+	"hamlab/internal/priv"
+)
+
+// GPU is one hardware decoder as the probe found it.
+type GPU struct {
+	API        string   `json:"api"`                  // vaapi | cuda
+	Device     string   `json:"device"`               // /dev/dri/renderD128; "0" for cuda (its device index)
+	Name       string   `json:"name,omitempty"`       // "Intel Arc A380"
+	Codecs     []string `json:"codecs,omitempty"`     // ffmpeg codec names it decodes; nil when nothing could say
+	Encodes    []string `json:"encodes,omitempty"`    // ffmpeg codec names it encodes, from vainfo
+	Integrated bool     `json:"integrated,omitempty"` // on the CPU die; a card on the bus is preferred for encoding
+	Reason     string   `json:"reason,omitempty"`     // Unusable only: why
+	Permission bool     `json:"permission,omitempty"` // Unusable only: the node exists but this user may not open it
+}
+
+// Caps is what the machine can make previews with, as probed.
+type Caps struct {
+	FFmpeg   string    `json:"ffmpeg,omitempty"`
+	FFprobe  string    `json:"ffprobe,omitempty"`
+	Nice     string    `json:"nice,omitempty"`
+	Version  string    `json:"version,omitempty"`
+	GPUs     []GPU     `json:"gpus"`               // usable, in node order
+	Encoders []string  `json:"encoders,omitempty"` // the encoders ffmpeg itself was built with that matter here
+	Unusable []GPU     `json:"unusable,omitempty"` // render nodes that exist but cannot be used, with the reason
+	Error    string    `json:"error,omitempty"`    // why nothing can be made at all
+	ProbedAt time.Time `json:"probed_at"`
+}
+
+// Opts shapes one preview.
+type Opts struct {
+	Size    int           // the long edge in pixels; 256 when zero
+	Timeout time.Duration // for the whole job, ffprobe and every ffmpeg attempt; 30 s when zero
+}
+
+func (o Opts) defaults() Opts {
+	if o.Size <= 0 {
+		o.Size = 256
+	}
+	if o.Timeout <= 0 {
+		o.Timeout = 30 * time.Second
+	}
+	return o
+}
+
+// Result is a finished preview.
+type Result struct {
+	JPEG   []byte `json:"-"`
+	Engine string `json:"engine"` // "cpu", or "vaapi:/dev/dri/renderD129"
+	Codec  string `json:"codec"`
+	Width  int    `json:"width"`
+	Height int    `json:"height"`
+}
+
+// ErrUnsupported: not an image or a video by its name.
+var ErrUnsupported = errors.New("not an image or video")
+
+// A DecodeError is ffmpeg's verdict on the file itself. It will not change until the
+// file does, so the caller may remember it.
+type DecodeError struct{ Msg string }
+
+func (e *DecodeError) Error() string { return e.Msg }
+
+// ---- what gets a preview ----
+
+var imageExt = set("png jpg jpeg jpe jfif gif webp bmp tif tiff avif heic heif hif jxl svg ico psd tga thm")
+var videoExt = set("mp4 m4v mkv webm mov avi wmv flv mpg mpeg mpe m2v ts m2ts mts 3gp 3g2 ogv ogm mxf vob asf rm rmvb divx f4v mjpeg mjpg 360 osv insv lrf")
+var audioExt = set("mp3 flac m4a m4b aac ogg oga opus wav wma aiff aif alac ape wv mka")
+
+func set(s string) map[string]bool {
+	m := map[string]bool{}
+	for _, w := range strings.Fields(s) {
+		m[w] = true
+	}
+	return m
+}
+
+// Kind is "image", "video", "audio" or "" for a file name. An audio file's preview is its
+// cover art, when it carries any.
+func Kind(name string) string {
+	ext := strings.ToLower(strings.TrimPrefix(filepath.Ext(name), "."))
+	switch {
+	case imageExt[ext]:
+		return "image"
+	case videoExt[ext]:
+		return "video"
+	case audioExt[ext]:
+		return "audio"
+	}
+	return ""
+}
+
+// ---- the probe ----
+
+// Probe finds out what this process can make previews with. It runs ffmpeg against every
+// render node, so it takes a few hundred milliseconds; callers keep the answer.
+func Probe(ctx context.Context) Caps {
+	c := Caps{ProbedAt: time.Now(), GPUs: []GPU{}}
+	c.FFmpeg, _ = exec.LookPath("ffmpeg")
+	c.FFprobe, _ = exec.LookPath("ffprobe")
+	c.Nice, _ = exec.LookPath("nice")
+	switch {
+	case c.FFmpeg == "" && c.FFprobe == "":
+		c.Error = "ffmpeg is not installed"
+	case c.FFmpeg == "":
+		c.Error = "ffmpeg is not installed (ffprobe is)"
+	case c.FFprobe == "":
+		c.Error = "ffprobe is not installed (ffmpeg is)"
+	}
+	if c.Error != "" {
+		return c
+	}
+	c.Version = ffmpegVersion(ctx, c.FFmpeg)
+	c.Encoders = encoders(ctx, c.FFmpeg)
+	accels := hwaccels(ctx, c.FFmpeg)
+	if accels["vaapi"] {
+		nodes, _ := filepath.Glob("/dev/dri/renderD*")
+		sort.Strings(nodes)
+		vainfo, _ := exec.LookPath("vainfo")
+		for _, dev := range nodes {
+			g := GPU{API: "vaapi", Device: dev, Name: metrics.RenderNodeName(dev), Integrated: metrics.RenderNodeIntegrated(dev)}
+			if err := openable(dev); err != nil {
+				g.Reason, g.Permission = err.Error(), errors.Is(err, os.ErrPermission)
+				c.Unusable = append(c.Unusable, g)
+				continue
+			}
+			if msg := hwWorks(ctx, c.FFmpeg, "vaapi=va:"+dev); msg != "" {
+				g.Reason = msg
+				c.Unusable = append(c.Unusable, g)
+				continue
+			}
+			if vainfo != "" {
+				g.Codecs, g.Encodes = vainfoCodecs(ctx, vainfo, dev)
+			}
+			c.GPUs = append(c.GPUs, g)
+		}
+	}
+	if accels["cuda"] && exists("/dev/nvidiactl") {
+		g := GPU{API: "cuda", Device: "0", Name: "NVIDIA GPU"}
+		if msg := hwWorks(ctx, c.FFmpeg, "cuda=cu:0"); msg != "" {
+			g.Reason = msg
+			c.Unusable = append(c.Unusable, g)
+		} else {
+			c.GPUs = append(c.GPUs, g)
+		}
+	}
+	return c
+}
+
+// openable: the node can be opened read-write, which is what a VAAPI driver needs. The
+// usual reason it can't be is the owning group: a render node is root:render 0660 on
+// most distributions, and a daemon running as an ordinary user is not in render.
+func openable(dev string) error {
+	f, err := os.OpenFile(dev, os.O_RDWR, 0)
+	if err != nil {
+		if errors.Is(err, os.ErrPermission) {
+			owner := ""
+			if st, serr := os.Stat(dev); serr == nil {
+				owner = ownerOf(st)
+			}
+			if owner != "" {
+				return fmt.Errorf("%w: %s is %s", os.ErrPermission, dev, owner)
+			}
+			return fmt.Errorf("%w: cannot open %s", os.ErrPermission, dev)
+		}
+		return err
+	}
+	f.Close()
+	return nil
+}
+
+// hwWorks initialises a hardware device in ffmpeg and moves one synthetic frame through
+// it. "" when it works, else the last thing ffmpeg said.
+func hwWorks(ctx context.Context, ffmpeg, device string) string {
+	ctx, cancel := context.WithTimeout(ctx, 15*time.Second)
+	defer cancel()
+	name, rest, _ := strings.Cut(device, "=") // "vaapi", "va:/dev/…"
+	label, _, _ := strings.Cut(rest, ":")     // "va"
+	cmd := exec.CommandContext(ctx, ffmpeg, "-nostdin", "-hide_banner", "-v", "error", "-init_hw_device", device, "-filter_hw_device", label,
+		"-f", "lavfi", "-i", "color=c=black:s=64x64:r=1:d=1", "-vf", "format=nv12,hwupload,hwdownload,format=nv12", "-frames:v", "1", "-f", "null", "-")
+	var errb bytes.Buffer
+	cmd.Stderr = &errb
+	if err := cmd.Run(); err != nil {
+		msg := lastLine(errb.String())
+		if msg == "" {
+			msg = err.Error()
+		}
+		return name + ": " + msg
+	}
+	return ""
+}
+
+func ffmpegVersion(ctx context.Context, ffmpeg string) string {
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	out, _ := exec.CommandContext(ctx, ffmpeg, "-version").Output()
+	f := strings.Fields(string(out)) // "ffmpeg version 7.1.5-0+deb13u1 Copyright …"
+	if len(f) >= 3 && f[1] == "version" {
+		v := f[2]
+		if i := strings.IndexAny(v, "-+~"); i > 0 {
+			v = v[:i]
+		}
+		return v
+	}
+	return ""
+}
+
+func hwaccels(ctx context.Context, ffmpeg string) map[string]bool {
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	out, _ := exec.CommandContext(ctx, ffmpeg, "-hide_banner", "-hwaccels").Output()
+	m := map[string]bool{}
+	for _, l := range strings.Split(string(out), "\n") {
+		l = strings.TrimSpace(l)
+		if l != "" && !strings.HasPrefix(l, "Hardware acceleration methods") {
+			m[l] = true
+		}
+	}
+	return m
+}
+
+var vaProfileRe = regexp.MustCompile(`VAProfile([A-Za-z0-9]+?)(?:Simple|Main|High|Profile|Baseline|Constrained|Scc|Advanced|Version|Stereo|Multiview)\w*\s*:\s*VAEntrypoint(VLD|EncSlice|EncSliceLP)\b`)
+
+// wantedEncoders are the encoders this package may ask ffmpeg for.
+var wantedEncoders = set("libx264 libx265 libsvtav1 libaom-av1 libopenh264 h264_vaapi hevc_vaapi av1_vaapi aac")
+
+// encoders lists the wanted encoders this ffmpeg was built with.
+func encoders(ctx context.Context, ffmpeg string) []string {
+	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+	defer cancel()
+	out, _ := exec.CommandContext(ctx, ffmpeg, "-hide_banner", "-encoders").Output()
+	var found []string
+	for _, l := range strings.Split(string(out), "\n") {
+		f := strings.Fields(l)
+		if len(f) >= 2 && wantedEncoders[f[1]] {
+			found = append(found, f[1])
+		}
+	}
+	sort.Strings(found)
+	return found
+}
+
+// vaCodec maps a VAProfile family to the ffmpeg codec it decodes.
+var vaCodec = map[string]string{"H264": "h264", "HEVC": "hevc", "VP9": "vp9", "AV1": "av1", "MPEG2": "mpeg2video", "VC1": "vc1", "VP8": "vp8", "JPEG": "mjpeg", "MPEG4": "mpeg4", "H263": "h263"}
+
+func vainfoCodecs(ctx context.Context, vainfo, dev string) (decodes, encodes []string) {
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	out, _ := exec.CommandContext(ctx, vainfo, "--display", "drm", "--device", dev).Output()
+	return parseVainfo(string(out))
+}
+
+// parseVainfo names the codecs the decode (VLD) and encode (EncSlice) profiles cover,
+// the way ffmpeg names them.
+func parseVainfo(text string) (decodes, encodes []string) {
+	dec, enc := map[string]bool{}, map[string]bool{}
+	for _, m := range vaProfileRe.FindAllStringSubmatch(text, -1) {
+		c, ok := vaCodec[m[1]]
+		if !ok {
+			continue
+		}
+		if m[2] == "VLD" {
+			dec[c] = true
+		} else {
+			enc[c] = true
+		}
+	}
+	return keys(dec), keys(enc)
+}
+
+func keys(m map[string]bool) []string {
+	if len(m) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(m))
+	for c := range m {
+		out = append(out, c)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// pick is the GPU for a codec: the first that lists it, else the first that could not
+// say (ffmpeg will fall back to software by itself if that guess is wrong), else none.
+func (c Caps) pick(codec string) *GPU {
+	var unknown *GPU
+	for i := range c.GPUs {
+		g := &c.GPUs[i]
+		if g.Codecs == nil {
+			if unknown == nil {
+				unknown = g
+			}
+			continue
+		}
+		for _, x := range g.Codecs {
+			if x == codec {
+				return g
+			}
+		}
+	}
+	return unknown
+}
+
+// ---- making one ----
+
+type fileInfo struct {
+	index    string // the stream to take
+	codec    string
+	w, h     int
+	duration float64
+}
+
+type attempt struct {
+	gpu    *GPU
+	lowres int
+	seek   float64
+}
+
+func (a attempt) engine() string {
+	if a.gpu == nil {
+		return "cpu"
+	}
+	return a.gpu.API + ":" + a.gpu.Device
+}
+
+// Make produces the preview of one file.
+func Make(ctx context.Context, c Caps, path string, o Opts) (Result, error) {
+	kind := Kind(path)
+	if kind == "" {
+		return Result{}, ErrUnsupported
+	}
+	if c.Error != "" {
+		return Result{}, errors.New(c.Error)
+	}
+	o = o.defaults()
+	ctx, cancel := context.WithTimeout(ctx, o.Timeout)
+	defer cancel()
+	fi, err := probeFile(ctx, c, path)
+	if err != nil {
+		return Result{}, err
+	}
+	var last string
+	for _, eng := range engines(c, kind, fi) {
+		for _, a := range attempts(eng, kind, fi, o.Size) {
+			data, msg, err := run(ctx, c, a, path, fi, o.Size)
+			if err == nil && len(data) > 0 {
+				return Result{JPEG: data, Engine: a.engine(), Codec: fi.codec, Width: fi.w, Height: fi.h}, nil
+			}
+			if ctx.Err() != nil {
+				return Result{}, ctx.Err() // the clock ran out: not the file's fault
+			}
+			if err != nil { // the decoder refused: try the next engine, not another seek
+				last = msg
+				break
+			}
+			last = "no frame at " + strconv.FormatFloat(a.seek, 'f', 1, 64) + " s"
+		}
+	}
+	if last == "" {
+		last = "could not decode"
+	}
+	return Result{}, &DecodeError{Msg: last}
+}
+
+// engines is the order to try: the fitting GPU first for a video, then the CPU.
+func engines(c Caps, kind string, fi fileInfo) []*GPU {
+	if kind == "video" {
+		if g := c.pick(fi.codec); g != nil {
+			return []*GPU{g, nil}
+		}
+	}
+	return []*GPU{nil}
+}
+
+// attempts for one engine: a seek into a video, then from its start if that found no
+// frame (a wrong duration in the header); a reduced-size decode of a JPEG, then full size.
+func attempts(gpu *GPU, kind string, fi fileInfo, size int) []attempt {
+	if kind == "video" {
+		s := seekFor(fi.duration)
+		if s > 0 {
+			return []attempt{{gpu: gpu, seek: s}, {gpu: gpu}}
+		}
+		return []attempt{{gpu: gpu}}
+	}
+	if fi.codec == "mjpeg" && gpu == nil {
+		if l := lowresFor(fi.w, fi.h, size); l > 0 {
+			return []attempt{{lowres: l}, {}}
+		}
+	}
+	return []attempt{{gpu: gpu}}
+}
+
+// seekFor: a tenth of the way in, never more than 30 s, so a title card or a black lead-in
+// is skipped and a long file still seeks to a keyframe near its start.
+func seekFor(duration float64) float64 {
+	if duration <= 0 {
+		return 0
+	}
+	s := duration / 10
+	if s > 30 {
+		s = 30
+	}
+	if s < 0.5 {
+		return 0
+	}
+	return s
+}
+
+// lowresFor: how many halvings a JPEG decoder may take while the picture stays at least
+// twice the preview size. libjpeg does this in the DCT, so a 24 MP photo decodes at 1.5 MP.
+func lowresFor(w, h, size int) int {
+	m := w
+	if h < m {
+		m = h
+	}
+	l := 0
+	for l < 3 && m>>(l+1) >= size*2 {
+		l++
+	}
+	return l
+}
+
+type probeOut struct {
+	Streams []struct {
+		Index       int    `json:"index"`
+		Codec       string `json:"codec_name"`
+		Width       int    `json:"width"`
+		Height      int    `json:"height"`
+		Disposition struct {
+			AttachedPic int `json:"attached_pic"`
+		} `json:"disposition"`
+	} `json:"streams"`
+	Format struct {
+		Duration string `json:"duration"`
+	} `json:"format"`
+}
+
+// probeFile asks ffprobe which stream to take and what is in it.
+func probeFile(ctx context.Context, c Caps, path string) (fileInfo, error) {
+	cmd := exec.CommandContext(ctx, c.FFprobe, "-v", "error", "-select_streams", "v", "-show_entries", "stream=index,codec_name,width,height,disposition:format=duration", "-of", "json", path)
+	var errb bytes.Buffer
+	cmd.Stderr = &errb
+	out, err := cmd.Output()
+	if err != nil {
+		if ctx.Err() != nil {
+			return fileInfo{}, ctx.Err()
+		}
+		msg := lastLine(errb.String())
+		if msg == "" {
+			msg = "ffprobe: " + err.Error()
+		}
+		return fileInfo{}, &DecodeError{Msg: msg}
+	}
+	var po probeOut
+	if err := json.Unmarshal(out, &po); err != nil {
+		return fileInfo{}, &DecodeError{Msg: "ffprobe: unreadable answer"}
+	}
+	if len(po.Streams) == 0 {
+		return fileInfo{}, &DecodeError{Msg: "no video stream"}
+	}
+	s := po.Streams[0]
+	for _, x := range po.Streams { // cover art rides along as a video stream; the picture is not the film
+		if x.Disposition.AttachedPic == 0 {
+			s = x
+			break
+		}
+	}
+	fi := fileInfo{index: strconv.Itoa(s.Index), codec: s.Codec, w: s.Width, h: s.Height}
+	fi.duration, _ = strconv.ParseFloat(po.Format.Duration, 64)
+	return fi, nil
+}
+
+// run is one ffmpeg: the JPEG on success; on failure what ffmpeg said and the error.
+// Empty output with a clean exit means the seek found nothing.
+func run(ctx context.Context, c Caps, a attempt, path string, fi fileInfo, size int) ([]byte, string, error) {
+	args := []string{"-nostdin", "-hide_banner", "-loglevel", "error", "-y"}
+	if a.gpu != nil {
+		args = append(args, "-hwaccel", a.gpu.API, "-hwaccel_device", a.gpu.Device)
+	}
+	if a.lowres > 0 {
+		args = append(args, "-lowres", strconv.Itoa(a.lowres))
+	}
+	if a.seek > 0 {
+		args = append(args, "-noaccurate_seek", "-ss", strconv.FormatFloat(a.seek, 'f', 3, 64))
+	}
+	args = append(args, "-i", path, "-map", "0:"+fi.index, "-frames:v", "1",
+		"-vf", fmt.Sprintf("scale=w=%d:h=%d:force_original_aspect_ratio=decrease:flags=bicubic", size, size),
+		"-f", "image2pipe", "-c:v", "mjpeg", "-q:v", "4", "pipe:1")
+	name, argv := c.FFmpeg, args
+	if c.Nice != "" { // a burst of previews must not crowd out what the machine is for
+		name, argv = c.Nice, append([]string{"-n", "10", c.FFmpeg}, args...)
+	}
+	cmd := exec.CommandContext(ctx, name, argv...)
+	var out, errb bytes.Buffer
+	cmd.Stdout, cmd.Stderr = &out, &errb
+	if err := cmd.Run(); err != nil {
+		msg := lastLine(errb.String())
+		if msg == "" {
+			msg = err.Error()
+		}
+		return nil, msg, err
+	}
+	return out.Bytes(), "", nil
+}
+
+// ---- the same, as root ----
+
+// ProbeRoot is Probe run as root through this binary, for the Files tab's root mode: root
+// opens every render node, whatever group the daemon's user is in.
+func ProbeRoot(ctx context.Context, self string) (Caps, error) {
+	full := priv.Wrap(self, "thumb", "--probe")
+	cmd := exec.CommandContext(ctx, full[0], full[1:]...)
+	var errb bytes.Buffer
+	cmd.Stderr = &errb
+	out, err := cmd.Output()
+	if err != nil {
+		if msg := lastLine(errb.String()); msg != "" {
+			return Caps{}, errors.New(msg)
+		}
+		return Caps{}, err
+	}
+	var c Caps
+	if err := json.Unmarshal(out, &c); err != nil {
+		return Caps{}, err
+	}
+	return c, nil
+}
+
+type helperOut struct {
+	Engine    string `json:"engine,omitempty"`
+	Codec     string `json:"codec,omitempty"`
+	Width     int    `json:"width,omitempty"`
+	Height    int    `json:"height,omitempty"`
+	JPEG      []byte `json:"jpeg,omitempty"`
+	Error     string `json:"error,omitempty"`
+	Permanent bool   `json:"permanent,omitempty"` // a DecodeError: the file, not the moment
+}
+
+// MakeRoot is Make run as root through this binary, with the caps ProbeRoot found.
+func MakeRoot(ctx context.Context, self string, c Caps, path string, o Opts) (Result, error) {
+	o = o.defaults()
+	caps, _ := json.Marshal(c)
+	full := priv.Wrap(self, "thumb", "--size", strconv.Itoa(o.Size), "--timeout", o.Timeout.String(), path)
+	cmd := exec.CommandContext(ctx, full[0], full[1:]...)
+	cmd.Stdin = bytes.NewReader(caps)
+	var errb bytes.Buffer
+	cmd.Stderr = &errb
+	out, err := cmd.Output()
+	if err != nil {
+		if ctx.Err() != nil {
+			return Result{}, ctx.Err()
+		}
+		if msg := lastLine(errb.String()); msg != "" {
+			return Result{}, errors.New(msg)
+		}
+		return Result{}, err
+	}
+	var h helperOut
+	if err := json.Unmarshal(out, &h); err != nil {
+		return Result{}, err
+	}
+	if h.Error != "" {
+		if h.Permanent {
+			return Result{}, &DecodeError{Msg: h.Error}
+		}
+		return Result{}, errors.New(h.Error)
+	}
+	return Result{JPEG: h.JPEG, Engine: h.Engine, Codec: h.Codec, Width: h.Width, Height: h.Height}, nil
+}
+
+// Helper implements `hamlab thumb …`, the root side of the above. `--probe` prints Caps;
+// `[--size N] [--timeout D] <path>` reads Caps from stdin and prints the preview as JSON.
+// Returns the exit code.
+func Helper(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
+	fail := func(err error) int { fmt.Fprintln(stderr, err.Error()); return 1 }
+	ctx := context.Background()
+	o := Opts{}
+	path := ""
+	for i := 0; i < len(args); i++ {
+		switch a := args[i]; {
+		case a == "--probe":
+			return emit(stdout, Probe(ctx), stderr)
+		case a == "--size" && i+1 < len(args):
+			o.Size, _ = strconv.Atoi(args[i+1])
+			i++
+		case a == "--timeout" && i+1 < len(args):
+			o.Timeout, _ = time.ParseDuration(args[i+1])
+			i++
+		case strings.HasPrefix(a, "-"):
+			return fail(errors.New("usage: hamlab thumb --probe | [--size N] [--timeout D] <path>"))
+		default:
+			path = a
+		}
+	}
+	if path == "" || !filepath.IsAbs(path) {
+		return fail(errors.New("usage: hamlab thumb --probe | [--size N] [--timeout D] <absolute path>"))
+	}
+	var c Caps
+	if err := json.NewDecoder(io.LimitReader(stdin, 1<<20)).Decode(&c); err != nil {
+		return fail(fmt.Errorf("caps on stdin: %w", err))
+	}
+	res, err := Make(ctx, c, path, o)
+	if err != nil {
+		var de *DecodeError
+		return emit(stdout, helperOut{Error: err.Error(), Permanent: errors.As(err, &de)}, stderr)
+	}
+	return emit(stdout, helperOut{Engine: res.Engine, Codec: res.Codec, Width: res.Width, Height: res.Height, JPEG: res.JPEG}, stderr)
+}
+
+func emit(w io.Writer, v any, stderr io.Writer) int {
+	if err := json.NewEncoder(w).Encode(v); err != nil {
+		fmt.Fprintln(stderr, err.Error())
+		return 1
+	}
+	return 0
+}
+
+// ---- small helpers ----
+
+func lastLine(s string) string {
+	lines := strings.Split(strings.TrimSpace(s), "\n")
+	return strings.TrimSpace(lines[len(lines)-1])
+}
+
+func exists(p string) bool { _, err := os.Stat(p); return err == nil }

internal/media/thumbs_test.go

@@ -0,0 +1,253 @@
+package media
+
+import (
+	"bytes"
+	"context"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"image/png"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestKind(t *testing.T) {
+	for name, want := range map[string]string{"a.JPG": "image", "b.heic": "image", "c.mkv": "video", "GH010098.MP4": "video", "x.OSV": "video", "d.txt": "", "e": "", ".jpg": "image"} {
+		if got := Kind(name); got != want {
+			t.Errorf("Kind(%q) = %q, want %q", name, got, want)
+		}
+	}
+}
+
+func TestKeyFollowsTheFile(t *testing.T) {
+	a := Key("/x/a.jpg", 10, 20)
+	if a != Key("/x/a.jpg", 10, 20) || len(a) != 64 {
+		t.Fatal("key is not stable")
+	}
+	for _, b := range []string{Key("/x/b.jpg", 10, 20), Key("/x/a.jpg", 11, 20), Key("/x/a.jpg", 10, 21)} {
+		if b == a {
+			t.Fatal("key ignores part of the file's identity")
+		}
+	}
+}
+
+func TestParseVainfo(t *testing.T) {
+	text := `vainfo: Driver version: Intel iHD driver for Intel(R) Gen Graphics - 25.2.3 ()
+      VAProfileMPEG2Simple            :	VAEntrypointVLD
+      VAProfileH264Main               :	VAEntrypointVLD
+      VAProfileH264High               :	VAEntrypointEncSliceLP
+      VAProfileJPEGBaseline           :	VAEntrypointVLD
+      VAProfileHEVCMain10             :	VAEntrypointVLD
+      VAProfileHEVCMain10             :	VAEntrypointEncSlice
+      VAProfileHEVCMain444_12         :	VAEntrypointVLD
+      VAProfileVP9Profile2            :	VAEntrypointVLD
+      VAProfileAV1Profile0            :	VAEntrypointEncSliceLP
+`
+	dec, enc := parseVainfo(text)
+	same := func(got, want []string) bool {
+		if len(got) != len(want) {
+			return false
+		}
+		for i := range want {
+			if got[i] != want[i] {
+				return false
+			}
+		}
+		return true
+	}
+	if !same(dec, []string{"h264", "hevc", "mjpeg", "mpeg2video", "vp9"}) {
+		t.Fatalf("decodes = %v", dec)
+	}
+	if !same(enc, []string{"av1", "h264", "hevc"}) {
+		t.Fatalf("encodes = %v", enc)
+	}
+	if d, e := parseVainfo(""); d != nil || e != nil {
+		t.Fatal("nothing from nothing")
+	}
+}
+
+func TestPickAndEngines(t *testing.T) {
+	igpu := GPU{API: "vaapi", Device: "/dev/dri/renderD128", Codecs: []string{"h264", "hevc"}}
+	arc := GPU{API: "vaapi", Device: "/dev/dri/renderD129", Codecs: []string{"av1", "h264", "hevc"}}
+	c := Caps{FFmpeg: "ffmpeg", FFprobe: "ffprobe", GPUs: []GPU{igpu, arc}}
+	if g := c.pick("av1"); g == nil || g.Device != arc.Device {
+		t.Fatal("av1 should go to the card that lists it")
+	}
+	if g := c.pick("h264"); g == nil || g.Device != igpu.Device {
+		t.Fatal("h264 should go to the first card that lists it")
+	}
+	if g := c.pick("vc1"); g != nil {
+		t.Fatal("a codec nobody lists is software")
+	}
+	// a card nothing could describe is tried, after the ones that answered
+	c.GPUs = append(c.GPUs, GPU{API: "cuda", Device: "0"})
+	if g := c.pick("vc1"); g == nil || g.API != "cuda" {
+		t.Fatal("an undescribed card is the guess of last resort")
+	}
+	// videos: GPU then CPU; images: CPU only
+	if e := engines(c, "video", fileInfo{codec: "hevc"}); len(e) != 2 || e[0] == nil || e[1] != nil {
+		t.Fatal("a video tries the GPU, then the CPU")
+	}
+	if e := engines(c, "image", fileInfo{codec: "mjpeg"}); len(e) != 1 || e[0] != nil {
+		t.Fatal("an image is CPU only")
+	}
+}
+
+func TestAttempts(t *testing.T) {
+	a := attempts(nil, "video", fileInfo{duration: 120}, 256)
+	if len(a) != 2 || a[0].seek != 12 || a[1].seek != 0 {
+		t.Fatalf("video attempts = %+v", a)
+	}
+	if a := attempts(nil, "video", fileInfo{duration: 7200}, 256); a[0].seek != 30 {
+		t.Fatalf("seek capped at 30 s, got %v", a[0].seek)
+	}
+	if a := attempts(nil, "video", fileInfo{duration: 2}, 256); len(a) != 1 || a[0].seek != 0 {
+		t.Fatalf("a short clip is taken from its start, got %+v", a)
+	}
+	if a := attempts(nil, "image", fileInfo{codec: "mjpeg", w: 6000, h: 4000}, 256); len(a) != 2 || a[0].lowres != 2 || a[1].lowres != 0 {
+		t.Fatalf("jpeg attempts = %+v", a)
+	}
+	if a := attempts(nil, "image", fileInfo{codec: "mjpeg", w: 800, h: 600}, 256); len(a) != 1 || a[0].lowres != 0 {
+		t.Fatalf("a small jpeg decodes whole, got %+v", a)
+	}
+	if a := attempts(nil, "image", fileInfo{codec: "png", w: 6000, h: 4000}, 256); len(a) != 1 || a[0].lowres != 0 {
+		t.Fatalf("only jpeg has lowres, got %+v", a)
+	}
+}
+
+func TestCache(t *testing.T) {
+	c := NewCache(filepath.Join(t.TempDir(), "thumbs.db"))
+	k := Key("/a", 1, 2)
+	if _, found, err := c.Get(k); found || err != nil {
+		t.Fatal("an empty cache found something, or complained")
+	}
+	if _, err := os.Stat(c.Path); err == nil {
+		t.Fatal("a miss must not create the database")
+	}
+	if n, b := c.Stats(); n != 0 || b != 0 {
+		t.Fatal("stats of nothing")
+	}
+	if err := c.Put(k, Entry{Path: "/a", Engine: "cpu", Codec: "png", Width: 640, Height: 360, JPEG: []byte("jpeg")}); err != nil {
+		t.Fatal(err)
+	}
+	e, found, err := c.Get(k)
+	if err != nil || !found || string(e.JPEG) != "jpeg" || e.Engine != "cpu" || e.Width != 640 || e.Path != "/a" || e.Made.IsZero() {
+		t.Fatalf("put then get: %+v %v %v", e, found, err)
+	}
+	k2 := Key("/b", 1, 2)
+	if err := c.Put(k2, Entry{Path: "/b", Failure: "no video stream"}); err != nil {
+		t.Fatal(err)
+	}
+	if e, found, _ := c.Get(k2); !found || e.JPEG != nil || e.Failure != "no video stream" {
+		t.Fatal("a failure is remembered with its reason")
+	}
+	if err := c.Put(k, Entry{}); err == nil {
+		t.Fatal("an empty preview must not be kept")
+	}
+	// replacing an entry does not count it twice
+	if err := c.Put(k, Entry{Path: "/a", JPEG: []byte("jpeg2")}); err != nil {
+		t.Fatal(err)
+	}
+	n, b := c.Stats()
+	if n != 2 || b == 0 {
+		t.Fatalf("stats = %d entries, %d bytes", n, b)
+	}
+	// survives a reopen
+	if err := c.Close(); err != nil {
+		t.Fatal(err)
+	}
+	c2 := NewCache(c.Path)
+	if e, found, _ := c2.Get(k); !found || string(e.JPEG) != "jpeg2" {
+		t.Fatal("not there after reopening")
+	}
+	if n, _ := c2.Stats(); n != 2 {
+		t.Fatal("count lost on reopen")
+	}
+	c2.Close()
+}
+
+// The real thing, when ffmpeg is here: a PNG and a generated video each come back as a
+// JPEG no larger than the asked size, with the aspect kept.
+func TestMakeWithFFmpeg(t *testing.T) {
+	if _, err := exec.LookPath("ffmpeg"); err != nil {
+		t.Skip("no ffmpeg")
+	}
+	c := Probe(context.Background())
+	if c.Error != "" {
+		t.Skip(c.Error)
+	}
+	dir := t.TempDir()
+	img := image.NewRGBA(image.Rect(0, 0, 640, 360))
+	for y := 0; y < 360; y++ {
+		for x := 0; x < 640; x++ {
+			img.Set(x, y, color.RGBA{uint8(x / 3), uint8(y), 90, 255})
+		}
+	}
+	pngPath := filepath.Join(dir, "a.png")
+	f, _ := os.Create(pngPath)
+	_ = png.Encode(f, img)
+	f.Close()
+	res, err := Make(context.Background(), c, pngPath, Opts{Size: 200})
+	if err != nil {
+		t.Fatal(err)
+	}
+	check(t, res, 200, 112, "cpu")
+
+	// a two-second test pattern, with the always-built-in mpeg4 encoder
+	vid := filepath.Join(dir, "v.mp4")
+	out, err := exec.Command("ffmpeg", "-nostdin", "-v", "error", "-f", "lavfi", "-i", "testsrc=size=320x180:rate=10:duration=2", "-c:v", "mpeg4", "-q:v", "5", vid).CombinedOutput()
+	if err != nil {
+		t.Skipf("could not make a test video: %s", out)
+	}
+	res, err = Make(context.Background(), c, vid, Opts{Size: 100})
+	if err != nil {
+		t.Fatal(err)
+	}
+	check(t, res, 100, 56, "")
+	if res.Codec != "mpeg4" || res.Width != 320 {
+		t.Fatalf("probe said %s %dx%d", res.Codec, res.Width, res.Height)
+	}
+
+	// not media, and media that isn't
+	if _, err := Make(context.Background(), c, filepath.Join(dir, "x.txt"), Opts{}); err != ErrUnsupported {
+		t.Fatalf("a .txt is unsupported, got %v", err)
+	}
+	bad := filepath.Join(dir, "bad.mp4")
+	_ = os.WriteFile(bad, []byte("not a video at all"), 0o644)
+	_, err = Make(context.Background(), c, bad, Opts{})
+	var de *DecodeError
+	if err == nil || !isDecodeErr(err, &de) {
+		t.Fatalf("garbage should be a DecodeError, got %v", err)
+	}
+	// the clock: a cancelled context is not the file's fault
+	ctx, cancel := context.WithTimeout(context.Background(), time.Nanosecond)
+	defer cancel()
+	if _, err := Make(ctx, c, pngPath, Opts{}); err == nil || isDecodeErr(err, &de) {
+		t.Fatalf("a timeout must not read as a decode failure, got %v", err)
+	}
+}
+
+func check(t *testing.T, res Result, w, h int, engine string) {
+	t.Helper()
+	im, err := jpeg.Decode(bytes.NewReader(res.JPEG))
+	if err != nil {
+		t.Fatalf("not a jpeg: %v", err)
+	}
+	if b := im.Bounds(); b.Dx() != w || b.Dy() < h-1 || b.Dy() > h+1 { // the short side rounds either way
+		t.Fatalf("got %dx%d, want %dx%d", b.Dx(), b.Dy(), w, h)
+	}
+	if engine != "" && res.Engine != engine {
+		t.Fatalf("engine %q, want %q", res.Engine, engine)
+	}
+}
+
+func isDecodeErr(err error, de **DecodeError) bool {
+	x, ok := err.(*DecodeError)
+	if ok {
+		*de = x
+	}
+	return ok
+}

internal/metrics/arc.go

@@ -0,0 +1,113 @@
+package metrics
+
+// The ZFS ARC — the read cache in RAM — read live from /proc/spl/kstat/zfs/arcstats on a
+// machine that has the module loaded, and left out of the sample everywhere else. The kstat
+// file is counters since boot; the hit rate here is over the sampling interval, which is the
+// number that says whether the cache is doing its job *now*. The lifetime figures and the
+// pool's caching tiers (L2ARC, SLOG, special vdevs) are the storage package's business.
+
+import (
+	"strconv"
+	"strings"
+	"time"
+)
+
+const arcstatsPath = "/proc/spl/kstat/zfs/arcstats"
+
+// ARC is the read cache as one sample sees it. Sizes are bytes.
+type ARC struct {
+	Size   uint64 `json:"size"`
+	Target uint64 `json:"target"` // c: what the ARC is currently allowed to hold
+	Min    uint64 `json:"min"`    // c_min: the floor it will not shrink below
+	Max    uint64 `json:"max"`    // c_max: the ceiling (zfs_arc_max, or half of RAM)
+	// what is in it
+	MRU          uint64 `json:"mru"`      // recently used once
+	MFU          uint64 `json:"mfu"`      // used more than once
+	Anon         uint64 `json:"anon"`     // in flight: dirty, not yet on disk
+	Data         uint64 `json:"data"`     // file contents
+	Metadata     uint64 `json:"metadata"` // dnodes, indirect blocks, dbufs, bonus buffers
+	MetaUsed     uint64 `json:"meta_used"`
+	Headers      uint64 `json:"headers"`
+	Compressed   uint64 `json:"compressed"`
+	Uncompressed uint64 `json:"uncompressed"`
+	MRUGhost     uint64 `json:"mru_ghost"` // what it recently evicted and still remembers
+	MFUGhost     uint64 `json:"mfu_ghost"`
+	// L2ARC, the cache devices (0 when there are none)
+	L2Size  uint64 `json:"l2_size"`
+	L2ASize uint64 `json:"l2_asize"` // as stored on the device, after compression
+	// over this interval
+	ReadsPerSec  float64 `json:"reads_per_sec"`
+	MissesPerSec float64 `json:"misses_per_sec"`
+	HitPct       float64 `json:"hit_pct"`       // of the interval's reads; an idle interval keeps the last one
+	HitPctKnown  bool    `json:"hit_pct_known"` // false until an interval has had any reads
+	L2HitPct     float64 `json:"l2_hit_pct"`
+	// since boot
+	Hits           uint64  `json:"hits"`
+	Misses         uint64  `json:"misses"`
+	LifetimeHitPct float64 `json:"lifetime_hit_pct"`
+	// pressure
+	NoGrow    bool   `json:"no_grow"`   // arc_no_grow: memory pressure is stopping it growing
+	Throttles uint64 `json:"throttles"` // memory_throttle_count since boot
+	Prunes    uint64 `json:"prunes"`    // arc_prune: metadata evictions asked of the filesystems
+	EvictSkip uint64 `json:"evict_skip"`
+}
+
+type arcPrev struct {
+	hits, misses, l2hits, l2misses uint64
+	hitPct                         float64
+	known                          bool
+	at                             time.Time
+}
+
+// readKstat parses a kstat table ("name type data" rows after two header lines).
+func readKstat(p string) map[string]uint64 {
+	s := readStr(p)
+	if s == "" {
+		return nil
+	}
+	out := map[string]uint64{}
+	for _, line := range strings.Split(s, "\n") {
+		f := strings.Fields(line)
+		if len(f) != 3 || f[1] != "4" { // type 4 is KSTAT_DATA_UINT64
+			continue
+		}
+		v, err := strconv.ParseUint(f[2], 10, 64)
+		if err == nil {
+			out[f[0]] = v
+		}
+	}
+	return out
+}
+
+// arc reads the ARC; nil when this machine has no ZFS module loaded.
+func (c *Collector) arc(now time.Time) *ARC {
+	k := readKstat(arcstatsPath)
+	if k == nil {
+		return nil
+	}
+	a := &ARC{Size: k["size"], Target: k["c"], Min: k["c_min"], Max: k["c_max"],
+		MRU: k["mru_size"], MFU: k["mfu_size"], Anon: k["anon_size"], Data: k["data_size"], Metadata: k["metadata_size"],
+		MetaUsed: k["arc_meta_used"], Headers: k["hdr_size"], Compressed: k["compressed_size"], Uncompressed: k["uncompressed_size"],
+		MRUGhost: k["mru_ghost_size"], MFUGhost: k["mfu_ghost_size"], L2Size: k["l2_size"], L2ASize: k["l2_asize"],
+		Hits: k["hits"], Misses: k["misses"], NoGrow: k["arc_no_grow"] != 0, Throttles: k["memory_throttle_count"], Prunes: k["arc_prune"], EvictSkip: k["evict_skip"]}
+	if n := a.Hits + a.Misses; n > 0 {
+		a.LifetimeHitPct = round1(float64(a.Hits) / float64(n) * 100)
+	}
+	p := c.prevARC
+	if !p.at.IsZero() && a.Hits >= p.hits && a.Misses >= p.misses {
+		if dt := now.Sub(p.at).Seconds(); dt > 0 {
+			hits, misses := a.Hits-p.hits, a.Misses-p.misses
+			a.ReadsPerSec = round1(float64(hits+misses) / dt)
+			a.MissesPerSec = round1(float64(misses) / dt)
+			if hits+misses > 0 {
+				p.hitPct, p.known = round1(float64(hits)/float64(hits+misses)*100), true
+			}
+			if l2 := (k["l2_hits"] - p.l2hits) + (k["l2_misses"] - p.l2misses); l2 > 0 && k["l2_hits"] >= p.l2hits {
+				a.L2HitPct = round1(float64(k["l2_hits"]-p.l2hits) / float64(l2) * 100)
+			}
+		}
+	}
+	a.HitPct, a.HitPctKnown = p.hitPct, p.known
+	c.prevARC = arcPrev{hits: a.Hits, misses: a.Misses, l2hits: k["l2_hits"], l2misses: k["l2_misses"], hitPct: p.hitPct, known: p.known, at: now}
+	return a
+}

internal/metrics/cpupower.go

@@ -0,0 +1,259 @@
+package metrics
+
+// CPU power, from the RAPL energy counters the kernel keeps under /sys/class/powercap: Intel
+// since Sandy Bridge, and AMD Zen through the same driver. Each counter is a running total in
+// µJ, so power is the difference between two readings over the time between them. Every
+// package is summed (`package-0`, and `package-1` on a two-socket board). The other top-level
+// domains are left out. `psys` claims the whole platform but is only as good as the firmware's
+// calibration, and on one machine here it reads lower than the package inside it. The MMIO
+// copy of a package (`intel-rapl-mmio:0`) measures the same thing again. This is the CPU's own
+// figure, shown beside its clock: cores, built-in graphics and memory controller, not disks,
+// fans or the power supply.
+//
+// The counters are root-only since the PLATYPUS side channel (2020). So, like the GPU client
+// walk, they are read in-process when the daemon is root, and otherwise by a root helper,
+// `hamlab cpu-energy`, started once through sudo or doas and asked over a pipe at every
+// sample: one privilege escalation per daemon, not one a second in the auth log. The helper
+// takes nothing from the daemon but the newline that asks; it finds and reads the counters
+// itself. Without root there is no reading, and nothing is shown.
+
+import (
+	"bufio"
+	"encoding/json"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"hamlab/internal/priv"
+)
+
+const raplRoot = "/sys/class/powercap"
+
+var raplPkgRe = regexp.MustCompile(`^package-\d+$`)
+
+// raplCount is one package's counter at one moment.
+type raplCount struct {
+	Dir string `json:"d"`
+	UJ  uint64 `json:"uj"`
+}
+
+type cpuPowerState struct {
+	probed    bool
+	dirs      []string          // the package domains, found at the first sample
+	max       map[string]uint64 // each counter's range: where it wraps to zero
+	useHelper bool              // the counters are not readable in-process
+	helper    *energyHelper
+	prev      []raplCount
+	prevAt    time.Time
+}
+
+// raplPackages lists the package domains under root, sorted. intel-rapl:0 is a package;
+// intel-rapl:0:0 is a part of one (core, uncore, dram).
+func raplPackages(root string) []string {
+	ents, err := os.ReadDir(root)
+	if err != nil {
+		return nil
+	}
+	var out []string
+	for _, e := range ents {
+		n := e.Name()
+		if !strings.HasPrefix(n, "intel-rapl:") || strings.Count(n, ":") != 1 {
+			continue
+		}
+		if raplPkgRe.MatchString(strings.TrimSpace(readStr(filepath.Join(root, n, "name")))) {
+			out = append(out, n)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+func readRAPL(root string, dirs []string) ([]raplCount, bool) {
+	out := make([]raplCount, 0, len(dirs))
+	for _, d := range dirs {
+		b, err := os.ReadFile(filepath.Join(root, d, "energy_uj"))
+		if err != nil {
+			return nil, false
+		}
+		v, err := strconv.ParseUint(strings.TrimSpace(string(b)), 10, 64)
+		if err != nil {
+			return nil, false
+		}
+		out = append(out, raplCount{d, v})
+	}
+	return out, len(out) > 0
+}
+
+// raplWatts is the power between two readings of the same counters. A counter that wrapped
+// is carried across its range. One that went backwards with no known range, or a set of
+// counters that changed between readings, gives no answer rather than a wrong one.
+func raplWatts(prev, cur []raplCount, max map[string]uint64, dt float64) (float64, bool) {
+	if dt <= 0 || len(prev) == 0 || len(prev) != len(cur) {
+		return 0, false
+	}
+	var uj float64
+	for i := range cur {
+		if cur[i].Dir != prev[i].Dir {
+			return 0, false
+		}
+		if cur[i].UJ >= prev[i].UJ {
+			uj += float64(cur[i].UJ - prev[i].UJ)
+			continue
+		}
+		m := max[cur[i].Dir]
+		if m == 0 || prev[i].UJ > m {
+			return 0, false
+		}
+		uj += float64(m - prev[i].UJ + cur[i].UJ)
+	}
+	return uj / 1e6 / dt, true
+}
+
+// cpuPower is the CPU packages' power since the previous sample, in watts; 0 when this
+// machine has no counters or no way to read them.
+func (c *Collector) cpuPower(now time.Time) float64 {
+	p := &c.power
+	if !p.probed {
+		p.probed = true
+		p.dirs = raplPackages(raplRoot)
+		p.max = map[string]uint64{}
+		for _, d := range p.dirs {
+			if v, ok := readInt(filepath.Join(raplRoot, d, "max_energy_range_uj")); ok && v > 0 {
+				p.max[d] = uint64(v)
+			}
+		}
+	}
+	if len(p.dirs) == 0 {
+		return 0
+	}
+	var cur []raplCount
+	ok := false
+	if !p.useHelper {
+		if cur, ok = readRAPL(raplRoot, p.dirs); !ok && priv.Mode() != "root" && priv.Available() {
+			p.useHelper = true
+		}
+	}
+	if p.useHelper {
+		if p.helper == nil {
+			p.helper = &energyHelper{}
+		}
+		cur, ok = p.helper.read()
+	}
+	if !ok {
+		p.prev = nil
+		return 0
+	}
+	w, good := raplWatts(p.prev, cur, p.max, now.Sub(p.prevAt).Seconds())
+	p.prev, p.prevAt = cur, now
+	if !good {
+		return 0
+	}
+	return round1(w)
+}
+
+// energyHelper is the root child that answers each newline with the package counters, one
+// JSON line. The same shape as the GPU client walk's helper, kept separate from it.
+type energyHelper struct {
+	mu       sync.Mutex
+	cmd      *exec.Cmd
+	in       io.WriteCloser
+	out      *bufio.Reader
+	failedAt time.Time
+}
+
+func (h *energyHelper) read() ([]raplCount, bool) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.cmd == nil {
+		if !h.failedAt.IsZero() && time.Since(h.failedAt) < helperRetry {
+			return nil, false
+		}
+		if !h.start() {
+			h.failedAt = time.Now()
+			return nil, false
+		}
+	}
+	// a stuck child must not stall the sampler: it is killed, and tried again later
+	cmd := h.cmd
+	stop := time.AfterFunc(5*time.Second, func() { cmd.Process.Kill() })
+	defer stop.Stop()
+	if _, err := io.WriteString(h.in, "\n"); err != nil {
+		h.fail()
+		return nil, false
+	}
+	line, err := h.out.ReadBytes('\n')
+	if err != nil {
+		h.fail()
+		return nil, false
+	}
+	var cs []raplCount
+	if json.Unmarshal(line, &cs) != nil {
+		h.fail()
+		return nil, false
+	}
+	return cs, len(cs) > 0
+}
+
+func (h *energyHelper) start() bool {
+	self, err := os.Executable()
+	if err != nil {
+		return false
+	}
+	full := priv.Wrap(self, "cpu-energy")
+	cmd := exec.Command(full[0], full[1:]...)
+	in, err := cmd.StdinPipe()
+	if err != nil {
+		return false
+	}
+	out, err := cmd.StdoutPipe()
+	if err != nil {
+		return false
+	}
+	if err := cmd.Start(); err != nil {
+		return false
+	}
+	h.cmd, h.in, h.out = cmd, in, bufio.NewReader(out)
+	return true
+}
+
+func (h *energyHelper) fail() {
+	if h.cmd != nil {
+		h.in.Close()
+		h.cmd.Process.Kill()
+		go h.cmd.Wait()
+	}
+	h.cmd, h.in, h.out = nil, nil, nil
+	h.failedAt = time.Now()
+}
+
+// CPUEnergyHelper is `hamlab cpu-energy`: for every line read on stdin, one JSON line of the
+// package counters on stdout. Ends when stdin does — when the daemon that started it has gone.
+func CPUEnergyHelper(stdin io.Reader, stdout io.Writer) int {
+	return cpuEnergyHelper(raplRoot, stdin, stdout)
+}
+
+func cpuEnergyHelper(root string, stdin io.Reader, stdout io.Writer) int {
+	dirs := raplPackages(root)
+	sc := bufio.NewScanner(stdin)
+	w := bufio.NewWriter(stdout)
+	for sc.Scan() {
+		cs, ok := readRAPL(root, dirs)
+		if !ok {
+			cs = []raplCount{}
+		}
+		b, _ := json.Marshal(cs)
+		w.Write(b)
+		w.WriteByte('\n')
+		if w.Flush() != nil {
+			return 1
+		}
+	}
+	return 0
+}

internal/metrics/cpupower_test.go

@@ -0,0 +1,106 @@
+package metrics
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// A fake /sys/class/powercap: a package with its parts, the platform domain, and the MMIO
+// copy of the same package. Only the package counts.
+func fakeRAPL(t *testing.T, domains map[string][2]string) string {
+	t.Helper()
+	root := t.TempDir()
+	for dir, v := range domains {
+		d := filepath.Join(root, dir)
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		os.WriteFile(filepath.Join(d, "name"), []byte(v[0]+"\n"), 0o644)
+		os.WriteFile(filepath.Join(d, "energy_uj"), []byte(v[1]+"\n"), 0o644)
+	}
+	return root
+}
+
+func TestRAPLPackagesOnlyCountsPackages(t *testing.T) {
+	root := fakeRAPL(t, map[string][2]string{
+		"intel-rapl:0":      {"package-0", "1000"},
+		"intel-rapl:0:0":    {"core", "600"},
+		"intel-rapl:0:1":    {"uncore", "10"},
+		"intel-rapl:1":      {"psys", "300"},
+		"intel-rapl-mmio:0": {"package-0", "1000"},
+	})
+	if got := raplPackages(root); len(got) != 1 || got[0] != "intel-rapl:0" {
+		t.Fatalf("packages = %v, want [intel-rapl:0]", got)
+	}
+
+	two := fakeRAPL(t, map[string][2]string{"intel-rapl:0": {"package-0", "5"}, "intel-rapl:1": {"package-1", "7"}})
+	got := raplPackages(two)
+	if strings.Join(got, ",") != "intel-rapl:0,intel-rapl:1" {
+		t.Fatalf("two sockets: packages = %v", got)
+	}
+	cs, ok := readRAPL(two, got)
+	if !ok || len(cs) != 2 || cs[0].UJ != 5 || cs[1].UJ != 7 {
+		t.Fatalf("readRAPL = %+v, %v", cs, ok)
+	}
+	if got := raplPackages(filepath.Join(two, "nope")); len(got) != 0 {
+		t.Fatalf("no powercap: packages = %v, want none", got)
+	}
+}
+
+func TestRAPLWatts(t *testing.T) {
+	c := func(d string, uj uint64) raplCount { return raplCount{d, uj} }
+	max := map[string]uint64{"intel-rapl:0": 1_000_000_000}
+	cases := []struct {
+		name      string
+		prev, cur []raplCount
+		dt        float64
+		want      float64
+		ok        bool
+	}{
+		{"steady", []raplCount{c("intel-rapl:0", 0)}, []raplCount{c("intel-rapl:0", 10_000_000)}, 2, 5, true},
+		{"two packages add", []raplCount{c("intel-rapl:0", 0), c("intel-rapl:1", 0)}, []raplCount{c("intel-rapl:0", 4_000_000), c("intel-rapl:1", 6_000_000)}, 1, 10, true},
+		{"wrapped", []raplCount{c("intel-rapl:0", 999_000_000)}, []raplCount{c("intel-rapl:0", 1_000_000)}, 1, 2, true},
+		{"backwards, range unknown", []raplCount{c("intel-rapl:1", 5_000_000)}, []raplCount{c("intel-rapl:1", 1)}, 1, 0, false},
+		{"counters changed", []raplCount{c("intel-rapl:0", 0)}, []raplCount{c("intel-rapl:1", 9)}, 1, 0, false},
+		{"first reading", nil, []raplCount{c("intel-rapl:0", 9)}, 1, 0, false},
+		{"no time passed", []raplCount{c("intel-rapl:0", 0)}, []raplCount{c("intel-rapl:0", 9)}, 0, 0, false},
+	}
+	for _, tc := range cases {
+		got, ok := raplWatts(tc.prev, tc.cur, max, tc.dt)
+		if ok != tc.ok || (ok && (got < tc.want-1e-9 || got > tc.want+1e-9)) {
+			t.Errorf("%s: got %v, %v; want %v, %v", tc.name, got, ok, tc.want, tc.ok)
+		}
+	}
+}
+
+// The helper answers every newline with the counters it found itself, and stops at EOF.
+func TestCPUEnergyHelper(t *testing.T) {
+	root := fakeRAPL(t, map[string][2]string{"intel-rapl:0": {"package-0", "42"}, "intel-rapl:0:0": {"core", "7"}})
+	var out bytes.Buffer
+	if code := cpuEnergyHelper(root, strings.NewReader("\n\n"), &out); code != 0 {
+		t.Fatalf("exit %d", code)
+	}
+	lines := strings.Split(strings.TrimSpace(out.String()), "\n")
+	if len(lines) != 2 {
+		t.Fatalf("got %d lines, want 2: %q", len(lines), out.String())
+	}
+	var cs []raplCount
+	if err := json.Unmarshal([]byte(lines[1]), &cs); err != nil || len(cs) != 1 || cs[0] != (raplCount{"intel-rapl:0", 42}) {
+		t.Fatalf("line = %s (%v)", lines[1], err)
+	}
+}
+
+// History keeps the average of the samples that had a reading.
+func TestFoldCPUPower(t *testing.T) {
+	b := []Sample{{T: 1, CPUPower: 4}, {T: 2}, {T: 3, CPUPower: 8}}
+	if got := fold(b).CPUPower; got != 6 {
+		t.Fatalf("folded CPU power = %v, want 6", got)
+	}
+	if got := fold([]Sample{{T: 1}, {T: 2}}).CPUPower; got != 0 {
+		t.Fatalf("no readings folded to %v, want 0", got)
+	}
+}

internal/metrics/fold.go

@@ -32,6 +32,17 @@ func fold(b []Sample) Sample {
 		return t / uint64(len(b))
 	}
 	out.CPU = sum(func(s Sample) float64 { return s.CPU })
+	// CPU power: over the samples that have a reading, so a helper restart is not a dip to zero
+	var pw, pn float64
+	for _, s := range b {
+		if s.CPUPower > 0 {
+			pw, pn = pw+s.CPUPower, pn+1
+		}
+	}
+	out.CPUPower = 0
+	if pn > 0 {
+		out.CPUPower = round1(pw / pn)
+	}
 	out.Load[0] = sum(func(s Sample) float64 { return s.Load[0] })
 	out.Load[1] = sum(func(s Sample) float64 { return s.Load[1] })
 	out.Load[2] = sum(func(s Sample) float64 { return s.Load[2] })

internal/metrics/gpu.go

@@ -0,0 +1,839 @@
+package metrics
+
+// GPU telemetry, the way btop and intel_gpu_top get it without a vendor library: the
+// device from sysfs, and who is using it from DRM fdinfo.
+//
+//   - The device: /sys/class/drm/card<n> with a driver we know to be a GPU. Clock from the
+//     driver's frequency files, temperature/power/fan from the hwmon under the device, and
+//     how busy it is from the one counter every Intel GT exports without root — RC6 idle
+//     residency, so busy = 100 − idle. amdgpu says it outright (gpu_busy_percent).
+//   - The clients: every process holding /dev/dri/* open has a drm-engine-<name> running
+//     total (nanoseconds) in /proc/<pid>/fdinfo/<fd>; the delta between two reads is that
+//     process's share of each engine, and the sum across clients is the engine's load. Other
+//     users' fdinfo is unreadable, so when the daemon isn't root it keeps one root child
+//     (`hamlab drm-clients`) that does the walk, asked over a pipe — one sudo per daemon
+//     start, not one per second.
+//
+// A GPU with no counter of either kind (Asahi, today) is still listed: a name is better
+// than silence about hardware the machine has.
+
+import (
+	"bufio"
+	"encoding/json"
+	"io"
+	"log"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"hamlab/internal/priv"
+)
+
+// GPU is one graphics device as a Sample reports it.
+type GPU struct {
+	Name       string             `json:"name"`
+	Driver     string             `json:"driver"`
+	Bus        string             `json:"bus,omitempty"` // PCI address; empty for a platform device
+	Integrated bool               `json:"integrated,omitempty"`
+	Usage      float64            `json:"usage"`               // % busy
+	UsageSrc   string             `json:"usage_src,omitempty"` // "idle" (100 − idle residency), "busy" (the driver's own %), "clients" (the busiest engine); "" when nothing measures it
+	Engines    map[string]float64 `json:"engines,omitempty"`   // render/video/copy/enhance… % from the clients, normalised by engine count
+	Temp       float64            `json:"temp,omitempty"`
+	TempSrc    string             `json:"temp_src,omitempty"` // "gpu" from the device's own sensor, "package" the CPU die an integrated GPU shares
+	PowerW     float64            `json:"power_w,omitempty"`
+	PowerCapW  float64            `json:"power_cap_w,omitempty"`
+	FanRPM     int                `json:"fan_rpm,omitempty"`
+	MHz        float64            `json:"mhz,omitempty"`     // actual clock (0 when power-gated)
+	ReqMHz     float64            `json:"req_mhz,omitempty"` // what the driver asked for
+	MaxMHz     float64            `json:"max_mhz,omitempty"`
+	MemUsed    uint64             `json:"mem_used,omitempty"` // VRAM used, or the clients' resident bytes where the driver has no VRAM counter
+	MemTotal   uint64             `json:"mem_total,omitempty"`
+	Clients    []GPUClient        `json:"clients"`
+	ClientsOK  bool               `json:"clients_ok"`        // false when fdinfo of other users' processes could not be read
+	Stalled    bool               `json:"stalled,omitempty"` // a sysfs read of this card never returned; its readings are paused until restart
+}
+
+// GPUClient is one process with the device open.
+type GPUClient struct {
+	PID     int                `json:"pid"`
+	Name    string             `json:"name"`
+	Usage   float64            `json:"usage"` // its busiest engine, %
+	Engines map[string]float64 `json:"engines,omitempty"`
+	Mem     uint64             `json:"mem,omitempty"` // resident bytes
+}
+
+// gpuDrivers are DRM drivers that drive a GPU, not just a scanout (simpledrm, ast, the
+// Apple display coprocessor) — those have no engines and nothing to say.
+var gpuDrivers = map[string]bool{"i915": true, "xe": true, "amdgpu": true, "radeon": true, "nouveau": true, "nvidia-drm": true, "nvidia": true,
+	"asahi": true, "panfrost": true, "panthor": true, "v3d": true, "msm": true, "etnaviv": true, "lima": true, "powervr": true, "virtio_gpu": true}
+
+type gpuDev struct {
+	card, dev, key, bus, driver, name, hwmon string
+	integrated, stalled                      bool
+	prevIdle, prevEnergy                     float64
+	prevAt                                   time.Time
+	nv                                       []GPUClient // nvidia: the process table from the last read (pmon), fdinfo says nothing there
+}
+
+type gpuState struct {
+	devs     []*gpuDev
+	listedAt time.Time
+	clients  map[string]clientPrev  // device key + client id → engine totals at the previous scan
+	last     []drmFD                // the newest client walk
+	scan     func() ([]drmFD, bool) // the walk; nil is scanClients (tests stand a fake list in)
+	helper   *drmHelper
+	ok       bool // the last walk saw every process
+}
+
+type clientPrev struct {
+	ns map[string]uint64
+	at time.Time
+}
+
+const gpuRelist = time.Minute // how often the card list is re-read: hotplug is rare, the readdir is cheap
+
+// gpus is the GPU section of a sample. cpuTemp stands in for an integrated GPU's
+// temperature: it is the same die.
+func (c *Collector) gpus(now time.Time, cpuTemp float64) []GPU {
+	g := &c.gpu
+	if g.devs == nil || now.Sub(g.listedAt) >= gpuRelist {
+		g.devs, g.listedAt = listGPUs(g.devs), now
+	}
+	if len(g.devs) == 0 {
+		return []GPU{}
+	}
+	if g.clients == nil {
+		g.clients = map[string]clientPrev{}
+	}
+	// The clients are read on every sample, like everything else in it: their engine shares
+	// move on the same tick as the device's own numbers, at whatever rate is set.
+	scan := c.scanClients
+	if g.scan != nil {
+		scan = g.scan
+	}
+	g.last, g.ok = scan()
+	out := make([]GPU, 0, len(g.devs))
+	live := map[string]bool{}
+	for _, d := range g.devs {
+		x := GPU{Name: d.name, Driver: d.driver, Bus: d.bus, Integrated: d.integrated, Clients: []GPUClient{}, ClientsOK: g.ok}
+		d.readWithin(&x, now)
+		if x.Temp == 0 && d.integrated && cpuTemp > 0 {
+			x.Temp, x.TempSrc = cpuTemp, "package"
+		}
+		// the clients: one entry per client id, under the first pid that holds it (a child
+		// that inherited the fd shares the client)
+		byID := map[string]*GPUClient{}
+		var order []string
+		engines := map[string]float64{}
+		var resident uint64
+		if d.driver == "nvidia" { // no engine counters in its fdinfo; nvidia-smi pmon is the client list
+			x.Clients, x.ClientsOK = append(x.Clients, d.nv...), true
+		}
+		for _, f := range g.last {
+			if d.driver == "nvidia" {
+				break
+			}
+			fi := parseFdinfo(f.Info)
+			if fi.pdev != "" && fi.pdev != d.bus || fi.pdev == "" && fi.driver != d.driver {
+				continue
+			}
+			key := d.key + "/" + fi.client
+			live[key] = true
+			if byID[fi.client] != nil {
+				continue
+			}
+			cl := &GPUClient{PID: f.PID, Name: f.Comm, Mem: fi.mem}
+			byID[fi.client] = cl
+			order = append(order, fi.client)
+			resident += fi.mem
+			if prev, ok := g.clients[key]; ok {
+				if dt := now.Sub(prev.at).Nanoseconds(); dt > 0 {
+					for e, ns := range fi.engines {
+						p, ok := prev.ns[e]
+						if !ok || ns < p {
+							continue
+						}
+						pct := float64(ns-p) / float64(dt) * 100
+						if n := fi.capacity[e]; n > 1 {
+							pct /= float64(n)
+						}
+						pct = round1(pct)
+						if cl.Engines == nil {
+							cl.Engines = map[string]float64{}
+						}
+						cl.Engines[e] = pct
+						engines[e] += pct
+						if pct > cl.Usage {
+							cl.Usage = pct
+						}
+					}
+				}
+			}
+			g.clients[key] = clientPrev{ns: fi.engines, at: now}
+		}
+		for _, id := range order {
+			x.Clients = append(x.Clients, *byID[id])
+		}
+		sort.SliceStable(x.Clients, func(i, j int) bool { return x.Clients[i].Usage > x.Clients[j].Usage })
+		if len(engines) > 0 {
+			x.Engines = map[string]float64{}
+			for e, v := range engines {
+				if v > 100 {
+					v = 100
+				}
+				x.Engines[e] = round1(v)
+			}
+		}
+		if x.UsageSrc == "" && len(x.Engines) > 0 {
+			for _, v := range x.Engines {
+				if v > x.Usage {
+					x.Usage = v
+				}
+			}
+			x.UsageSrc = "clients"
+		}
+		if x.MemTotal == 0 && x.MemUsed == 0 {
+			x.MemUsed = resident
+		}
+		out = append(out, x)
+	}
+	for k := range g.clients { // a client that closed the device
+		if !live[k] {
+			delete(g.clients, k)
+		}
+	}
+	return out
+}
+
+// listGPUs enumerates the cards, keeping the counters of those already known.
+func listGPUs(known []*gpuDev) []*gpuDev {
+	ents, _ := os.ReadDir("/sys/class/drm")
+	old := map[string]*gpuDev{}
+	for _, d := range known {
+		old[d.card] = d
+	}
+	out := []*gpuDev{}
+	for _, e := range ents {
+		n := e.Name()
+		if !strings.HasPrefix(n, "card") || strings.Contains(n, "-") {
+			continue
+		}
+		card := "/sys/class/drm/" + n
+		dev, err := filepath.EvalSymlinks(card + "/device")
+		if err != nil {
+			continue
+		}
+		driver := ueventValue(dev+"/uevent", "DRIVER")
+		if driver == "" { // some drivers hang the DRIVER key off the parent
+			driver = filepath.Base(readLink(dev + "/driver"))
+		}
+		if !gpuDrivers[driver] {
+			continue
+		}
+		if d, ok := old[card]; ok && d.dev == dev {
+			out = append(out, d)
+			continue
+		}
+		d := &gpuDev{card: card, dev: dev, driver: driver}
+		if pci := ueventValue(dev+"/uevent", "PCI_SLOT_NAME"); pci != "" {
+			d.bus, d.key = pci, pci
+			// an on-die GPU hangs off root bus 0 (Intel's 00:02.0, an AMD APU's 00:08.0 bridge)
+			d.integrated = strings.HasPrefix(pci, "0000:00:")
+		} else {
+			d.key = "driver:" + driver
+			d.integrated = true
+		}
+		if hw, _ := filepath.Glob(dev + "/hwmon/hwmon*"); len(hw) > 0 {
+			d.hwmon = hw[0]
+		}
+		d.name = gpuName(dev, d.bus, driver)
+		out = append(out, d)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].card < out[j].card })
+	return out
+}
+
+// RenderNodeName is the GPU behind a render node ("/dev/dri/renderD128" → "Intel Arc A380"),
+// named the same way the Processes tab names it; "" when sysfs has nothing for it.
+func RenderNodeName(node string) string {
+	dev, err := filepath.EvalSymlinks("/sys/class/drm/" + filepath.Base(node) + "/device")
+	if err != nil {
+		return ""
+	}
+	driver := ueventValue(dev+"/uevent", "DRIVER")
+	if driver == "" {
+		driver = filepath.Base(readLink(dev + "/driver"))
+	}
+	return gpuName(dev, ueventValue(dev+"/uevent", "PCI_SLOT_NAME"), driver)
+}
+
+// RenderNodeIntegrated reports a render node whose GPU sits on the CPU die (PCI root bus 0,
+// or no PCI bus at all), as opposed to a card on the bus.
+func RenderNodeIntegrated(node string) bool {
+	dev, err := filepath.EvalSymlinks("/sys/class/drm/" + filepath.Base(node) + "/device")
+	if err != nil {
+		return true
+	}
+	pci := ueventValue(dev+"/uevent", "PCI_SLOT_NAME")
+	return pci == "" || strings.HasPrefix(pci, "0000:00:")
+}
+
+var gpuVendors = map[string]string{"0x8086": "Intel", "0x1002": "AMD", "0x10de": "NVIDIA", "0x1af4": "Virtio", "0x106b": "Apple"}
+
+var (
+	revRe     = regexp.MustCompile(`\s*\(rev [^)]*\)`)
+	bracketRe = regexp.MustCompile(`\[([^\]]+)\]`)
+)
+
+// gpuName is "Intel Arc A380": from the embedded PCI ID table first, so the name is the
+// same on every machine; from lspci for a card newer than the table; and failing both,
+// the vendor and the raw device ID.
+func gpuName(dev, bus, driver string) string {
+	if bus != "" {
+		vid := strings.TrimPrefix(strings.TrimSpace(readStr(dev+"/vendor")), "0x")
+		did := strings.TrimPrefix(strings.TrimSpace(readStr(dev+"/device")), "0x")
+		if vn, dn := pciName(vid, did); dn != "" {
+			return lspciName(vn + " " + dn)
+		}
+		if out, ok := runOut("lspci", "-s", bus); ok {
+			if _, desc, found := strings.Cut(out, ": "); found {
+				return lspciName(desc)
+			}
+		}
+	}
+	vendor := gpuVendors[strings.TrimSpace(readStr(dev+"/vendor"))]
+	if compat := readStr(dev + "/of_node/compatible"); compat != "" { // "apple,agx-t8103\0apple,agx-g13g"
+		first := strings.SplitN(compat, "\x00", 2)[0]
+		if v, model, ok := strings.Cut(first, ","); ok {
+			if vendor == "" && v != "" {
+				vendor = strings.ToUpper(v[:1]) + v[1:]
+			}
+			return vendor + " GPU (" + model + ")"
+		}
+	}
+	if vendor == "" && driver != "" {
+		vendor = strings.ToUpper(driver[:1]) + driver[1:]
+	}
+	if id := strings.TrimPrefix(strings.TrimSpace(readStr(dev+"/device")), "0x"); id != "" {
+		return strings.TrimSpace(vendor + " GPU " + id)
+	}
+	return strings.TrimSpace(vendor + " GPU")
+}
+
+// lspciName turns "Intel Corporation DG2 [Arc A380] (rev 05)" into "Intel Arc A380".
+func lspciName(desc string) string {
+	desc = revRe.ReplaceAllString(strings.TrimSpace(desc), "")
+	vendor := ""
+	for _, v := range []struct{ long, short string }{{"Intel Corporation", "Intel"}, {"Advanced Micro Devices, Inc. [AMD/ATI]", "AMD"}, {"Advanced Micro Devices, Inc. [AMD]", "AMD"}, {"NVIDIA Corporation", "NVIDIA"}, {"Red Hat, Inc.", "Virtio"}} {
+		if strings.HasPrefix(desc, v.long) {
+			vendor = v.short
+			desc = strings.TrimSpace(desc[len(v.long):])
+			break
+		}
+	}
+	if vendor == "" { // vendor not recognised: its first word
+		if i := strings.IndexByte(desc, ' '); i > 0 {
+			vendor, desc = desc[:i], strings.TrimSpace(desc[i+1:])
+		}
+	}
+	if m := bracketRe.FindStringSubmatch(desc); m != nil {
+		desc = m[1]
+	}
+	return strings.TrimSpace(vendor + " " + desc)
+}
+
+// readWithin is read with a deadline. A sysfs read that does not come back must not take
+// the whole sampler with it — every graph on every page of this machine stops — so the
+// device is marked stalled, its goroutine abandoned, and the rest of the sample goes on.
+const gpuReadWithin = 3 * time.Second
+
+func (d *gpuDev) readWithin(x *GPU, now time.Time) {
+	if d.stalled {
+		x.Stalled = true
+		return
+	}
+	done := make(chan GPU, 1)
+	go func() {
+		y := *x
+		d.read(&y, now)
+		done <- y
+	}()
+	select {
+	case y := <-done:
+		*x = y
+	case <-time.After(gpuReadWithin):
+		d.stalled, x.Stalled = true, true
+		log.Printf("gpu: %s (%s): a sysfs read did not return within %s; its readings are paused until restart", d.name, d.card, gpuReadWithin)
+	}
+}
+
+// read fills the device-level numbers: clock, idle/busy, hwmon.
+func (d *gpuDev) read(x *GPU, now time.Time) {
+	dt := now.Sub(d.prevAt).Seconds()
+	switch d.driver {
+	case "nvidia":
+		d.readNvidia(x)
+	case "i915":
+		x.MHz = readF(d.card + "/gt_act_freq_mhz")
+		x.ReqMHz = readF(d.card + "/gt_cur_freq_mhz")
+		x.MaxMHz = readF(d.card + "/gt_max_freq_mhz")
+		idle, ok := readInt(d.card + "/gt/gt0/rc6_residency_ms")
+		if !ok {
+			idle, ok = readInt(d.card + "/power/rc6_residency_ms")
+		}
+		if ok {
+			d.busyFromIdle(x, float64(idle), dt)
+		}
+	case "xe":
+		gt := d.dev + "/tile0/gt0"
+		x.MHz = readF(gt + "/freq0/act_freq")
+		x.ReqMHz = readF(gt + "/freq0/cur_freq")
+		x.MaxMHz = readF(gt + "/freq0/max_freq")
+		if idle, ok := readInt(gt + "/gtidle/idle_residency_ms"); ok {
+			d.busyFromIdle(x, float64(idle), dt)
+		}
+	case "amdgpu":
+		if v, ok := readInt(d.dev + "/gpu_busy_percent"); ok {
+			x.Usage, x.UsageSrc = float64(v), "busy"
+		}
+		x.MemUsed = uint64(readF(d.dev + "/mem_info_vram_used"))
+		x.MemTotal = uint64(readF(d.dev + "/mem_info_vram_total"))
+		// "1: 1800Mhz *" — the starred level is the current one, the last the highest
+		for _, line := range strings.Split(readStr(d.dev+"/pp_dpm_sclk"), "\n") {
+			f := strings.Fields(line)
+			if len(f) < 2 {
+				continue
+			}
+			mhz := leadingNum(f[1])
+			x.MaxMHz = mhz
+			if strings.HasSuffix(line, "*") {
+				x.MHz = mhz
+			}
+		}
+	}
+	if d.hwmon != "" {
+		if t := readF(d.hwmon + "/temp1_input"); t > 0 {
+			x.Temp, x.TempSrc = t/1000, "gpu"
+		}
+		if p := readF(d.hwmon + "/power1_input"); p > 0 {
+			x.PowerW = round1(p / 1e6)
+		} else if p := readF(d.hwmon + "/power1_average"); p > 0 {
+			x.PowerW = round1(p / 1e6)
+		} else if e := readF(d.hwmon + "/energy1_input"); e > 0 { // µJ, cumulative
+			if d.prevEnergy > 0 && e >= d.prevEnergy && dt > 0 && !d.prevAt.IsZero() {
+				x.PowerW = round1((e - d.prevEnergy) / 1e6 / dt)
+			}
+			d.prevEnergy = e
+		}
+		if p := readF(d.hwmon + "/power1_cap"); p > 0 {
+			x.PowerCapW = p / 1e6
+		} else if p := readF(d.hwmon + "/power1_max"); p > 0 {
+			x.PowerCapW = p / 1e6
+		}
+		x.FanRPM = int(readF(d.hwmon + "/fan1_input"))
+	}
+	d.prevAt = now
+}
+
+// busyFromIdle: the GT's idle residency is a running ms total; the share of the interval
+// it did not cover is how busy the device was.
+func (d *gpuDev) busyFromIdle(x *GPU, idle, dt float64) {
+	x.UsageSrc = "idle"
+	if d.prevAt.IsZero() || dt <= 0 || idle < d.prevIdle {
+		d.prevIdle = idle
+		return
+	}
+	busy := 100 - (idle-d.prevIdle)/(dt*1000)*100
+	if busy < 0 {
+		busy = 0
+	}
+	if busy > 100 {
+		busy = 100
+	}
+	x.Usage = round1(busy)
+	d.prevIdle = idle
+}
+
+// ---- DRM fdinfo: who has the device open ----
+
+// drmFD is one client of a DRM device: the fdinfo text of one open fd, with its owner.
+type drmFD struct {
+	PID  int    `json:"pid"`
+	Comm string `json:"comm"`
+	Info string `json:"info"`
+}
+
+type fdinfo struct {
+	driver, pdev, client string
+	engines              map[string]uint64 // ns, cumulative
+	capacity             map[string]int
+	mem                  uint64 // bytes
+}
+
+func parseFdinfo(s string) fdinfo {
+	fi := fdinfo{engines: map[string]uint64{}, capacity: map[string]int{}}
+	var resident, memory uint64
+	for _, line := range strings.Split(s, "\n") {
+		k, v, ok := strings.Cut(line, ":")
+		if !ok || !strings.HasPrefix(k, "drm-") {
+			continue
+		}
+		v = strings.TrimSpace(v)
+		switch {
+		case k == "drm-driver":
+			fi.driver = v
+		case k == "drm-pdev":
+			fi.pdev = v
+		case k == "drm-client-id":
+			fi.client = v
+		case strings.HasPrefix(k, "drm-engine-capacity-"):
+			fi.capacity[k[len("drm-engine-capacity-"):]], _ = strconv.Atoi(v)
+		case strings.HasPrefix(k, "drm-engine-"):
+			n, _ := strconv.ParseUint(strings.TrimSuffix(v, " ns"), 10, 64)
+			fi.engines[k[len("drm-engine-"):]] = n
+		case strings.HasPrefix(k, "drm-resident-"):
+			resident += kib(v)
+		case strings.HasPrefix(k, "drm-memory-"):
+			memory += kib(v)
+		}
+	}
+	fi.mem = resident
+	if fi.mem == 0 {
+		fi.mem = memory
+	}
+	return fi
+}
+
+// kib parses "52624 KiB" (or MiB, or a bare count of bytes) to bytes.
+func kib(v string) uint64 {
+	f := strings.Fields(v)
+	if len(f) == 0 {
+		return 0
+	}
+	n, _ := strconv.ParseUint(f[0], 10, 64)
+	if len(f) > 1 {
+		switch f[1] {
+		case "KiB":
+			n <<= 10
+		case "MiB":
+			n <<= 20
+		case "GiB":
+			n <<= 30
+		}
+	}
+	return n
+}
+
+// drmScan walks /proc for every fd open on /dev/dri/*, one entry per client per process.
+// Run as root it sees everyone; as a user, only that user's processes.
+func drmScan() (out []drmFD, complete bool) {
+	ents, err := os.ReadDir("/proc")
+	if err != nil {
+		return []drmFD{}, false
+	}
+	complete = true
+	out = []drmFD{}
+	for _, e := range ents {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue
+		}
+		fds, err := os.ReadDir("/proc/" + e.Name() + "/fd")
+		if err != nil {
+			if !os.IsNotExist(err) {
+				complete = false
+			}
+			continue
+		}
+		seen := map[string]bool{}
+		comm := ""
+		for _, fd := range fds {
+			target, err := os.Readlink("/proc/" + e.Name() + "/fd/" + fd.Name())
+			if err != nil || !strings.HasPrefix(target, "/dev/dri/") {
+				continue
+			}
+			info := readStr("/proc/" + e.Name() + "/fdinfo/" + fd.Name())
+			_, rest, ok := strings.Cut(info, "drm-client-id:")
+			if !ok {
+				continue
+			}
+			id := strings.TrimSpace(strings.SplitN(rest, "\n", 2)[0])
+			if seen[id] {
+				continue
+			}
+			seen[id] = true
+			if comm == "" {
+				comm = strings.TrimSpace(readStr("/proc/" + e.Name() + "/comm"))
+			}
+			out = append(out, drmFD{PID: pid, Comm: comm, Info: info})
+		}
+	}
+	sort.SliceStable(out, func(i, j int) bool { return out[i].PID < out[j].PID })
+	return out, complete
+}
+
+// scanClients walks in-process when that sees everything (root), else through the helper.
+func (c *Collector) scanClients() ([]drmFD, bool) {
+	if priv.Mode() == "root" || !priv.Available() {
+		return drmScan()
+	}
+	if c.gpu.helper == nil {
+		c.gpu.helper = &drmHelper{}
+	}
+	if fds, ok := c.gpu.helper.scan(); ok {
+		return fds, true
+	}
+	return drmScan() // the helper is down: our own processes are better than nothing
+}
+
+// drmHelper is the root child that answers "scan" requests. One line in, one JSON line out.
+type drmHelper struct {
+	mu       sync.Mutex
+	cmd      *exec.Cmd
+	in       io.WriteCloser
+	out      *bufio.Reader
+	failedAt time.Time
+}
+
+const helperRetry = 30 * time.Second
+
+func (h *drmHelper) scan() ([]drmFD, bool) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.cmd == nil {
+		if !h.failedAt.IsZero() && time.Since(h.failedAt) < helperRetry {
+			return nil, false
+		}
+		if !h.start() {
+			h.failedAt = time.Now()
+			return nil, false
+		}
+	}
+	// a stuck child must not stall the sampler: it is killed, and tried again later
+	cmd := h.cmd
+	stop := time.AfterFunc(5*time.Second, func() { cmd.Process.Kill() })
+	defer stop.Stop()
+	if _, err := io.WriteString(h.in, "\n"); err != nil {
+		h.fail()
+		return nil, false
+	}
+	line, err := h.out.ReadBytes('\n')
+	if err != nil {
+		h.fail()
+		return nil, false
+	}
+	var fds []drmFD
+	if json.Unmarshal(line, &fds) != nil {
+		h.fail()
+		return nil, false
+	}
+	if fds == nil {
+		fds = []drmFD{}
+	}
+	return fds, true
+}
+
+func (h *drmHelper) start() bool {
+	self, err := os.Executable()
+	if err != nil {
+		return false
+	}
+	full := priv.Wrap(self, "drm-clients")
+	cmd := exec.Command(full[0], full[1:]...)
+	in, err := cmd.StdinPipe()
+	if err != nil {
+		return false
+	}
+	out, err := cmd.StdoutPipe()
+	if err != nil {
+		return false
+	}
+	if err := cmd.Start(); err != nil {
+		return false
+	}
+	h.cmd, h.in, h.out = cmd, in, bufio.NewReaderSize(out, 1<<20)
+	return true
+}
+
+func (h *drmHelper) fail() {
+	if h.cmd != nil {
+		h.in.Close()
+		h.cmd.Process.Kill()
+		go h.cmd.Wait()
+	}
+	h.cmd, h.in, h.out = nil, nil, nil
+	h.failedAt = time.Now()
+}
+
+// DRMClientsHelper is `hamlab drm-clients`: for every line read on stdin, one JSON line of
+// drmFD on stdout. Ends when stdin does — when the daemon that started it has gone.
+func DRMClientsHelper(stdin io.Reader, stdout io.Writer) int {
+	sc := bufio.NewScanner(stdin)
+	w := bufio.NewWriter(stdout)
+	for sc.Scan() {
+		fds, _ := drmScan()
+		b, _ := json.Marshal(fds)
+		w.Write(b)
+		w.WriteByte('\n')
+		if w.Flush() != nil {
+			return 1
+		}
+	}
+	return 0
+}
+
+// ---- small helpers ----
+
+func readF(p string) float64 {
+	v, err := strconv.ParseFloat(strings.TrimSpace(readStr(p)), 64)
+	if err != nil {
+		return 0
+	}
+	return v
+}
+
+func readLink(p string) string {
+	t, err := os.Readlink(p)
+	if err != nil {
+		return ""
+	}
+	return t
+}
+
+func ueventValue(p, key string) string {
+	for _, line := range strings.Split(readStr(p), "\n") {
+		if k, v, ok := strings.Cut(line, "="); ok && k == key {
+			return strings.TrimSpace(v)
+		}
+	}
+	return ""
+}
+
+// The proprietary NVIDIA driver exports no busy counter in sysfs and no engine totals in
+// fdinfo, so the device and its processes come from nvidia-smi — two short invocations per
+// sample (~20 ms and ~75 ms on a GTX 965M), no root needed. The PCI address selects the
+// card, so two NVIDIA GPUs stay apart.
+func (d *gpuDev) readNvidia(x *GPU) {
+	if out, ok := runOut("nvidia-smi", "--id="+d.bus, "--query-gpu=utilization.gpu,utilization.encoder,utilization.decoder,memory.used,memory.total,clocks.sm,clocks.max.sm,temperature.gpu,power.draw,power.limit", "--format=csv,noheader,nounits"); ok {
+		parseNvidiaQuery(x, out)
+	}
+	if out, ok := runOut("nvidia-smi", "pmon", "-c", "1", "-s", "um", "--id="+d.bus); ok {
+		d.nv = parseNvidiaPmon(out)
+	}
+}
+
+// nvNum is one nvidia-smi CSV field; "[N/A]" (no sensor, no limit) is "nothing".
+func nvNum(s string) (float64, bool) {
+	s = strings.TrimSpace(s)
+	if s == "" || strings.Contains(s, "N/A") {
+		return 0, false
+	}
+	v, err := strconv.ParseFloat(s, 64)
+	return v, err == nil
+}
+
+// parseNvidiaQuery fills a GPU from one --query-gpu line in the field order readNvidia asks
+// for: gpu%, encoder%, decoder%, mem used MiB, mem total MiB, SM MHz, max SM MHz, °C, W, W cap.
+func parseNvidiaQuery(x *GPU, line string) {
+	f := strings.Split(strings.TrimSpace(line), ",")
+	if len(f) < 10 {
+		return
+	}
+	if v, ok := nvNum(f[0]); ok {
+		x.Usage, x.UsageSrc = v, "busy"
+		x.Engines = map[string]float64{"render": v}
+		enc, okE := nvNum(f[1])
+		dec, okD := nvNum(f[2])
+		if okE || okD {
+			x.Engines["video"] = max(enc, dec)
+		}
+	}
+	if v, ok := nvNum(f[3]); ok {
+		x.MemUsed = uint64(v) << 20
+	}
+	if v, ok := nvNum(f[4]); ok {
+		x.MemTotal = uint64(v) << 20
+	}
+	if v, ok := nvNum(f[5]); ok {
+		x.MHz = v
+	}
+	if v, ok := nvNum(f[6]); ok {
+		x.MaxMHz = v
+	}
+	if v, ok := nvNum(f[7]); ok && v > 0 {
+		x.Temp, x.TempSrc = v, "gpu"
+	}
+	if v, ok := nvNum(f[8]); ok {
+		x.PowerW = round1(v)
+	}
+	if v, ok := nvNum(f[9]); ok {
+		x.PowerCapW = v
+	}
+}
+
+// parseNvidiaPmon reads `nvidia-smi pmon -c 1 -s um`: a header naming the columns, then one
+// row per process — "-" where a process has no share. Columns vary between driver versions,
+// so they are taken by name. Busiest first, like the fdinfo clients.
+func parseNvidiaPmon(out string) []GPUClient {
+	col := map[string]int{}
+	var clients []GPUClient
+	for _, line := range strings.Split(out, "\n") {
+		f := strings.Fields(line)
+		if len(f) == 0 {
+			continue
+		}
+		if f[0] == "#" {
+			if len(f) > 1 && f[1] == "gpu" { // "# gpu pid type sm mem enc dec jpg ofa fb ccpm command"
+				col = map[string]int{}
+				for i, name := range f[1:] {
+					col[name] = i
+				}
+			}
+			continue
+		}
+		get := func(name string) (float64, bool) {
+			i, ok := col[name]
+			if !ok || i >= len(f) || f[i] == "-" {
+				return 0, false
+			}
+			v, err := strconv.ParseFloat(f[i], 64)
+			return v, err == nil
+		}
+		pid, ok := get("pid")
+		if !ok || pid <= 0 {
+			continue
+		}
+		cl := GPUClient{PID: int(pid), Engines: map[string]float64{}}
+		if i, ok := col["command"]; ok && i < len(f) {
+			cl.Name = strings.Join(f[i:], " ")
+		}
+		if v, ok := get("sm"); ok {
+			cl.Engines["render"] = v
+		}
+		enc, okE := get("enc")
+		dec, okD := get("dec")
+		if okE || okD {
+			cl.Engines["video"] = max(enc, dec)
+		}
+		for _, v := range cl.Engines {
+			if v > cl.Usage {
+				cl.Usage = v
+			}
+		}
+		if len(cl.Engines) == 0 {
+			cl.Engines = nil
+		}
+		if v, ok := get("fb"); ok {
+			cl.Mem = uint64(v) << 20
+		}
+		clients = append(clients, cl)
+	}
+	sort.SliceStable(clients, func(i, j int) bool { return clients[i].Usage > clients[j].Usage })
+	return clients
+}

internal/metrics/gpu_test.go

@@ -0,0 +1,219 @@
+package metrics
+
+import (
+	"encoding/json"
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+const fdinfoA = `pos:	0
+flags:	02100002
+drm-driver:	i915
+drm-client-id:	544
+drm-pdev:	0000:00:02.0
+drm-total-system0:	52624 KiB
+drm-resident-system0:	50140 KiB
+drm-resident-stolen-system0:	32 KiB
+drm-engine-render:	1000000000 ns
+drm-engine-copy:	0 ns
+drm-engine-video:	2000000000 ns
+drm-engine-capacity-video:	2
+drm-engine-video-enhance:	0 ns
+`
+
+func TestParseFdinfo(t *testing.T) {
+	fi := parseFdinfo(fdinfoA)
+	if fi.driver != "i915" || fi.pdev != "0000:00:02.0" || fi.client != "544" {
+		t.Fatalf("identity: %+v", fi)
+	}
+	if fi.engines["video"] != 2000000000 || fi.capacity["video"] != 2 {
+		t.Errorf("video engine: %+v", fi)
+	}
+	if fi.mem != (50140+32)<<10 {
+		t.Errorf("resident = %d", fi.mem)
+	}
+}
+
+func TestLspciName(t *testing.T) {
+	for in, want := range map[string]string{
+		"Intel Corporation DG2 [Arc A380] (rev 05)":                                              "Intel Arc A380",
+		"Intel Corporation RocketLake-S GT1 [UHD Graphics 750] (rev 04)":                         "Intel UHD Graphics 750",
+		"Intel Corporation Alder Lake-N [UHD Graphics]":                                          "Intel UHD Graphics",
+		"Advanced Micro Devices, Inc. [AMD/ATI] Navi 23 [Radeon RX 6600/6600 XT/6600M] (rev c7)": "AMD Radeon RX 6600/6600 XT/6600M",
+		"NVIDIA Corporation GA106 [GeForce RTX 3060 Lite Hash Rate] (rev a1)":                    "NVIDIA GeForce RTX 3060 Lite Hash Rate",
+		"Moore Threads Technology Co.,Ltd MTT S80":                                               "Moore Threads Technology Co.,Ltd MTT S80",
+	} {
+		if got := lspciName(in); got != want {
+			t.Errorf("%q → %q, want %q", in, got, want)
+		}
+	}
+}
+
+// Two scans a second apart: a client that ran its render engine for half of it and both
+// video engines flat out reads 50% render, 100% video, and the device's engines follow.
+func TestGPUClientsShare(t *testing.T) {
+	c := NewCollector()
+	d := &gpuDev{card: "/nonexistent/card9", dev: "/nonexistent", key: "0000:00:02.0", bus: "0000:00:02.0", driver: "i915", name: "Test GPU", integrated: true}
+	c.gpu.devs = []*gpuDev{d}
+	c.gpu.listedAt = time.Now().Add(time.Hour) // keep the fake list
+	c.gpu.clients = map[string]clientPrev{}
+	t0 := time.Now()
+	c.gpu.last = []drmFD{{PID: 7, Comm: "ffmpeg", Info: fdinfoA}}
+	c.gpu.scan = func() ([]drmFD, bool) { return c.gpu.last, true } // no walk: the fake list stands
+	first := c.gpus(t0, 40)
+	if len(first) != 1 || len(first[0].Clients) != 1 || first[0].Clients[0].Usage != 0 {
+		t.Fatalf("first pass: %+v", first)
+	}
+	if first[0].Temp != 40 || first[0].TempSrc != "package" {
+		t.Errorf("an integrated GPU wears the package temperature: %+v", first[0])
+	}
+	later := fdinfoA
+	later = replace(later, "drm-engine-render:	1000000000 ns", "drm-engine-render:	1500000000 ns")
+	later = replace(later, "drm-engine-video:	2000000000 ns", "drm-engine-video:	4000000000 ns")
+	c.gpu.last = []drmFD{{PID: 7, Comm: "ffmpeg", Info: later}}
+	got := c.gpus(t0.Add(time.Second), 40)
+	cl := got[0].Clients[0]
+	if cl.Engines["render"] != 50 || cl.Engines["video"] != 100 || cl.Usage != 100 {
+		t.Errorf("client share: %+v", cl)
+	}
+	if got[0].Engines["video"] != 100 || got[0].Usage != 100 || got[0].UsageSrc != "clients" {
+		t.Errorf("device from clients: %+v", got[0])
+	}
+	if got[0].MemUsed != cl.Mem {
+		t.Errorf("resident memory should be the clients' sum: %d vs %d", got[0].MemUsed, cl.Mem)
+	}
+	// the Processes table joins the client to its row
+	c.ring = []Sample{{T: 1, GPUs: got}}
+	c.prevProc = nil
+	table := c.Processes()
+	if len(table.GPUs) != 1 {
+		t.Errorf("table carries the GPUs: %+v", table.GPUs)
+	}
+}
+
+func TestFlattenGPU(t *testing.T) {
+	s := Sample{T: 5, GPUs: []GPU{{Name: "Intel Arc A380", Driver: "i915", Bus: "0000:03:00.0", Usage: 12, UsageSrc: "idle", Engines: map[string]float64{"video": 30}, PowerW: 9.5, PowerCapW: 55, MHz: 2450, MaxMHz: 2450, Clients: []GPUClient{{PID: 1}}}}}
+	got := map[string]any{}
+	for _, x := range flatten(s, nil) {
+		got[x.ID] = x.Value
+	}
+	for id, want := range map[string]any{"gpu.intel_arc_a380.usage": 12.0, "gpu.intel_arc_a380.video": 30.0, "gpu.intel_arc_a380.power": 9.5, "gpu.intel_arc_a380.freq": 2450.0, "gpu.intel_arc_a380.clients": 1.0} {
+		if got[id] != want {
+			t.Errorf("%s = %v, want %v", id, got[id], want)
+		}
+	}
+	if _, ok := got["gpu.intel_arc_a380.temp"]; ok {
+		t.Error("no temperature sensor, no temperature")
+	}
+}
+
+func replace(s, old, new string) string {
+	for i := 0; i+len(old) <= len(s); i++ {
+		if s[i:i+len(old)] == old {
+			return s[:i] + new + s[i+len(old):]
+		}
+	}
+	return s
+}
+
+// TestLiveGPU reads this machine's GPUs for real: HAMLAB_LIVE=1 go test -run TestLiveGPU -v ./internal/metrics
+func TestLiveGPU(t *testing.T) {
+	if os.Getenv("HAMLAB_LIVE") == "" {
+		t.Skip("set HAMLAB_LIVE=1 to read the real hardware")
+	}
+	c := NewCollector()
+	c.sample()
+	time.Sleep(1100 * time.Millisecond)
+	c.sample()
+	s, _ := c.Latest()
+	b, _ := json.MarshalIndent(s.GPUs, "", "  ")
+	t.Logf("%s", b)
+	for _, x := range flatten(s, func(id string) bool { return len(id) > 4 && id[:4] == "gpu." }) {
+		t.Logf("%s = %v %s", x.ID, x.Value, x.Unit)
+	}
+}
+
+// TestLiveARC: HAMLAB_LIVE=1 go test -run TestLiveARC -v ./internal/metrics
+func TestLiveARC(t *testing.T) {
+	if os.Getenv("HAMLAB_LIVE") == "" {
+		t.Skip("set HAMLAB_LIVE=1 to read the real machine")
+	}
+	c := NewCollector()
+	c.sample()
+	time.Sleep(1100 * time.Millisecond)
+	c.sample()
+	s, _ := c.Latest()
+	b, _ := json.MarshalIndent(s.ARC, "", "  ")
+	t.Logf("%s", b)
+	for _, x := range flatten(s, func(id string) bool { return strings.HasPrefix(id, "zfs.arc.") }) {
+		t.Logf("%s = %v %s", x.ID, x.Value, x.Unit)
+	}
+}
+
+// The embedded table names the lab's four GPUs the way lspci would, so a machine without
+// pciutils (the router) agrees with one that has it.
+func TestPCIName(t *testing.T) {
+	for id, want := range map[string]string{"8086:3185": "Intel UHD Graphics 600", "8086:56a5": "Intel Arc A380", "8086:46d1": "Intel UHD Graphics", "8086:4c8a": "Intel UHD Graphics 750", "10de:2684": "NVIDIA GeForce RTX 4090"} {
+		v, d := pciName(id[:4], id[5:])
+		if d == "" {
+			t.Errorf("%s: not in the table", id)
+			continue
+		}
+		if got := lspciName(v + " " + d); got != want {
+			t.Errorf("%s → %q, want %q", id, got, want)
+		}
+	}
+	if _, d := pciName("8086", "ffff"); d != "" {
+		t.Errorf("an unknown device should be empty, got %q", d)
+	}
+}
+
+func TestParseNvidiaQuery(t *testing.T) {
+	var g GPU
+	parseNvidiaQuery(&g, "31, 0, 12, 1488, 2048, 949, 1097, 57, 23.41, [N/A]\n")
+	if g.Usage != 31 || g.UsageSrc != "busy" || g.Engines["render"] != 31 || g.Engines["video"] != 12 {
+		t.Errorf("usage: %+v", g)
+	}
+	if g.MemUsed != 1488<<20 || g.MemTotal != 2048<<20 || g.MHz != 949 || g.MaxMHz != 1097 {
+		t.Errorf("mem/clock: %+v", g)
+	}
+	if g.Temp != 57 || g.TempSrc != "gpu" || g.PowerW != 23.4 || g.PowerCapW != 0 {
+		t.Errorf("temp/power (cap must stay 0 for [N/A]): %+v", g)
+	}
+	var short GPU
+	parseNvidiaQuery(&short, "garbage")
+	if short.UsageSrc != "" {
+		t.Errorf("a short line must leave the GPU untouched: %+v", short)
+	}
+}
+
+const pmonA = `# gpu         pid   type     sm    mem    enc    dec    jpg    ofa     fb   ccpm    command 
+# Idx           #    C/G      %      %      %      %      %      %     MB     MB    name 
+    0       1063     G      -      -      -      -      -      -    701      0    Xorg           
+    0       1480     G     27     22      -      -      -      -    270      0    cinnamon       
+    0      13318     G      9      7     40      -      -      -    454      0    firefox-esr    
+`
+
+func TestParseNvidiaPmon(t *testing.T) {
+	cl := parseNvidiaPmon(pmonA)
+	if len(cl) != 3 {
+		t.Fatalf("want 3 clients, got %+v", cl)
+	}
+	// busiest first: firefox's encoder share (40) beats cinnamon's sm (27)
+	if cl[0].PID != 13318 || cl[0].Name != "firefox-esr" || cl[0].Usage != 40 || cl[0].Engines["render"] != 9 || cl[0].Engines["video"] != 40 || cl[0].Mem != 454<<20 {
+		t.Errorf("firefox: %+v", cl[0])
+	}
+	if cl[1].PID != 1480 || cl[1].Usage != 27 || cl[1].Engines["render"] != 27 {
+		t.Errorf("cinnamon: %+v", cl[1])
+	}
+	if cl[2].PID != 1063 || cl[2].Usage != 0 || cl[2].Engines != nil || cl[2].Mem != 701<<20 {
+		t.Errorf("xorg (no shares, only memory): %+v", cl[2])
+	}
+	// an older driver without the jpg/ofa/ccpm columns
+	old := "# gpu        pid  type    sm   mem   enc   dec   fb   command\n# Idx          #   C/G     %     %     %     %   MB   name\n    0      42    C    55    10     -     -  100   python3\n"
+	if cl := parseNvidiaPmon(old); len(cl) != 1 || cl[0].PID != 42 || cl[0].Usage != 55 || cl[0].Mem != 100<<20 || cl[0].Name != "python3" {
+		t.Errorf("old layout: %+v", cl)
+	}
+}

internal/metrics/metrics.go

@@ -6,7 +6,9 @@
 // lm-sensors, smartmontools or root. Sections whose source is absent (no fans, no
 // UPS daemon, no hwmon at all on a VM) simply come back empty rather than failing.
 // The only external commands are optional UPS daemons: pwrstat (CyberPower), upsc
-// (NUT) and apcaccess (apcupsd), tried in that order.
+// (NUT) and apcaccess (apcupsd), tried in that order. Two readings are root-only, the GPU
+// client walk and the CPU energy counters; without root they come from small helpers of
+// this binary started once through sudo or doas (gpu.go, cpupower.go), or not at all.
 package metrics
 
 import (
@@ -90,6 +92,15 @@ type FS struct {
 	Type  string `json:"type"`
 	Size  uint64 `json:"size"`
 	Used  uint64 `json:"used"`
+	// Remote is set when the filesystem lives on another machine — a CIFS or NFS share,
+	// sshfs, and so on. Its bytes are somebody else's disk, so a panel about this machine's
+	// hardware leaves it out, while the sensor stays for anyone who does want it.
+	Remote bool `json:"remote,omitempty"`
+	// Disk is the physical drive these bytes are on ("nvme0", "sda"), named as the sampler
+	// names it; empty when that cannot be
+	// said honestly: a ZFS pool or an md array spreads a filesystem over several drives, and
+	// a remote mount is on none of them.
+	Disk string `json:"disk,omitempty"`
 }
 
 type UPS struct {
@@ -114,6 +125,7 @@ type Proc struct {
 	Cmd     string  `json:"cmd,omitempty"`
 	User    string  `json:"user"`
 	CPU     float64 `json:"cpu"`           // percent of one core
+	GPU     float64 `json:"gpu,omitempty"` // its busiest GPU engine, percent; summed over the GPUs it has open
 	CPUTime float64 `json:"cpu_time"`      // seconds, lifetime
 	RSS     uint64  `json:"rss"`           // bytes
 	Threads int     `json:"threads"`
@@ -127,6 +139,7 @@ type Sample struct {
 	Interval int64      `json:"interval_ms"` // sampling interval in effect
 	CPU      float64    `json:"cpu"`
 	Cores    []float64  `json:"cores"`
+	CPUPower float64    `json:"cpu_power_w,omitempty"` // the CPU packages' own energy counters; 0 = no reading
 	Load     [3]float64 `json:"load"`
 	Mem      Mem        `json:"mem"`
 	Swap     Mem        `json:"swap"`
@@ -136,6 +149,8 @@ type Sample struct {
 	Disks    []Disk     `json:"disks"`
 	FS       []FS       `json:"fs"`
 	UPS      *UPS       `json:"ups"`
+	GPUs     []GPU      `json:"gpus"`
+	ARC      *ARC       `json:"arc"` // the ZFS read cache; nil without the module
 	Uptime   float64    `json:"uptime"`
 
 	fsT, upsT int64 // when the slow sections were really read; sensors report these, not T
@@ -164,6 +179,9 @@ type Collector struct {
 	procAt    time.Time
 	lastTable *ProcTable
 	upsProbe  func() *UPS // nil when no UPS daemon is installed
+	gpu       gpuState
+	power     cpuPowerState
+	prevARC   arcPrev
 
 	subMu sync.Mutex
 	subs  map[chan struct{}]struct{} // told after every sample; see Subscribe
@@ -329,6 +347,7 @@ func (c *Collector) sample() {
 
 	s := Sample{T: now.UnixMilli(), Interval: c.Interval().Milliseconds(), Temps: []Temp{}, Fans: []Fan{}, Net: []Net{}, Disks: []Disk{}}
 	s.CPU, s.Cores = c.cpu()
+	s.CPUPower = c.cpuPower(now)
 	s.Load = loadavg()
 	s.Mem, s.Swap = meminfo()
 	s.Uptime = uptime()
@@ -347,6 +366,8 @@ func (c *Collector) sample() {
 		c.lastUPS, c.upsAt = c.upsProbe(), now
 	}
 	s.UPS, s.upsT = c.lastUPS, c.upsAt.UnixMilli()
+	s.GPUs = c.gpus(now, cpuTemp(s.Temps))
+	s.ARC = c.arc(now)
 
 	if first {
 		return // deltas are meaningless on the priming pass
@@ -766,6 +787,15 @@ func foldNVMe(devs []Disk) []Disk {
 
 // Kernel/virtual filesystems that aren't storage. Anything else that's mounted is
 // shown, so new real filesystems (bcachefs, exotic FUSE) work without a code change.
+// remoteFS is every filesystem type whose storage is not in this machine.
+var remoteFS = map[string]bool{
+	"cifs": true, "smb3": true, "smbfs": true, "nfs": true, "nfs4": true, "afs": true,
+	"ceph": true, "glusterfs": true, "9p": true, "afpfs": true, "davfs": true,
+	"fuse.sshfs": true, "sshfs": true, "fuse.rclone": true, "fuse.s3fs": true,
+	"fuse.davfs2": true, "fuse.curlftpfs": true, "fuse.gcsfuse": true, "beegfs": true,
+	"lustre": true, "orangefs": true, "pvfs2": true, "coda": true, "ncpfs": true,
+}
+
 var pseudoFS = map[string]bool{
 	"proc": true, "sysfs": true, "devtmpfs": true, "devpts": true, "tmpfs": true, "ramfs": true,
 	"cgroup": true, "cgroup2": true, "pstore": true, "bpf": true, "securityfs": true, "debugfs": true,
@@ -812,7 +842,7 @@ func filesystems() []FS {
 				return
 			}
 			bs := uint64(st.Bsize)
-			done <- FS{Mount: mount, Type: fs[2], Size: st.Blocks * bs, Used: (st.Blocks - st.Bfree) * bs}
+			done <- FS{Mount: mount, Type: fs[2], Size: st.Blocks * bs, Used: (st.Blocks - st.Bfree) * bs, Remote: remoteFS[fs[2]], Disk: diskOf(fs[0])}
 		}()
 		select {
 		case r := <-done:
@@ -820,12 +850,52 @@ func filesystems() []FS {
 				out = append(out, r)
 			}
 		case <-time.After(3 * time.Second):
-			out = append(out, FS{Mount: mount, Type: fs[2]}) // unreachable: size 0 signals it
+			out = append(out, FS{Mount: mount, Type: fs[2], Remote: remoteFS[fs[2]]}) // unreachable: size 0 signals it
 		}
 	}
 	return out
 }
 
+// diskOf names the physical drive a mount's source device sits on — "/dev/nvme0n1p2" is on
+// "nvme0n1". It follows one layer of device-mapper or md (LUKS on a partition, say) but
+// gives up when a thing spans several drives, because then no single drive is the answer.
+func diskOf(source string) string {
+	if !strings.HasPrefix(source, "/dev/") {
+		return "" // a ZFS pool, a network share, a tmpfs: not a block device at all
+	}
+	d := parentDisk(strings.TrimPrefix(source, "/dev/"), 0)
+	// the sampler reports one drive per NVMe controller, so name it the same way
+	if m := nsRe.FindStringSubmatch(d); m != nil {
+		return m[1]
+	}
+	return d
+}
+
+func parentDisk(name string, depth int) string {
+	if name == "" || depth > 4 || strings.Contains(name, "/") {
+		return ""
+	}
+	base := "/sys/class/block/" + name
+	if _, err := os.Stat(base); err != nil {
+		return ""
+	}
+	// a partition: its parent directory in sysfs is the whole drive
+	if _, err := os.Stat(base + "/partition"); err == nil {
+		if target, err := os.Readlink(base); err == nil {
+			return filepath.Base(filepath.Dir(target))
+		}
+		return ""
+	}
+	// device-mapper or md: one drive underneath is an answer, several is not
+	if ents, err := os.ReadDir(base + "/slaves"); err == nil && len(ents) > 0 {
+		if len(ents) > 1 {
+			return ""
+		}
+		return parentDisk(ents[0].Name(), depth+1)
+	}
+	return name // a whole drive, used without partitioning
+}
+
 // ---- UPS ----
 
 func runOut(args ...string) (string, bool) {
@@ -1048,12 +1118,14 @@ type ProcTable struct {
 	CPUModel  string     `json:"cpu_model,omitempty"`
 	CPUMHz    float64    `json:"cpu_mhz,omitempty"`
 	CPUMaxMHz float64    `json:"cpu_max_mhz,omitempty"`
+	CPUPowerW float64    `json:"cpu_power_w,omitempty"`
 	CPUTemp   float64    `json:"cpu_temp,omitempty"`
 	CoreIDs   []int      `json:"core_ids,omitempty"` // for each logical CPU, the physical core it is a thread of (what the temperature sensors are named by)
 	Load      [3]float64 `json:"load"`
 	Mem       Mem        `json:"mem"`
 	Swap      Mem        `json:"swap"`
 	Net       []Net      `json:"net"`
+	GPUs      []GPU      `json:"gpus"`
 	Uptime    float64    `json:"uptime"`
 	Procs     []Proc     `json:"procs"`
 	Total     int        `json:"total"`
@@ -1216,6 +1288,20 @@ func (c *Collector) Processes() ProcTable {
 		}
 	}
 	c.prevProc, c.procAt = cur, now
+	// what each process is doing on the GPUs, from the newest sample's client lists
+	gpuBy := map[int]float64{}
+	gpus := []GPU{}
+	if n := len(c.ring); n > 0 && c.ring[n-1].GPUs != nil {
+		gpus = c.ring[n-1].GPUs
+		for _, g := range gpus {
+			for _, cl := range g.Clients {
+				gpuBy[cl.PID] += cl.Usage
+			}
+		}
+	}
+	for i := range procs {
+		procs[i].GPU = round1(gpuBy[procs[i].PID])
+	}
 	sort.Slice(procs, func(i, j int) bool {
 		if procs[i].CPU != procs[j].CPU {
 			return procs[i].CPU > procs[j].CPU
@@ -1223,7 +1309,7 @@ func (c *Collector) Processes() ProcTable {
 		return procs[i].RSS > procs[j].RSS
 	})
 	t := ProcTable{T: now.UnixMilli(), Procs: procs, Total: len(procs), Uptime: uptime(), Load: loadavg(),
-		CPUModel: cpuModel, CPUMHz: round1(cpuMHz()), CPUMaxMHz: cpuMaxMHz, CPUHist: []float64{}, Net: []Net{}}
+		CPUModel: cpuModel, CPUMHz: round1(cpuMHz()), CPUMaxMHz: cpuMaxMHz, CPUHist: []float64{}, Net: []Net{}, GPUs: gpus}
 	for _, p := range procs {
 		if p.State == "R" {
 			t.Running++
@@ -1232,7 +1318,7 @@ func (c *Collector) Processes() ProcTable {
 	t.Mem, t.Swap = meminfo()
 	if n := len(c.ring); n > 0 {
 		last := c.ring[n-1]
-		t.CPU, t.Cores, t.Net, t.CPUTemp = last.CPU, last.Cores, last.Net, cpuTemp(last.Temps)
+		t.CPU, t.Cores, t.Net, t.CPUTemp, t.CPUPowerW = last.CPU, last.Cores, last.Net, cpuTemp(last.Temps), last.CPUPower
 		t.CoreIDs = coreIDs(len(last.Cores))
 		from := n - 90
 		if from < 0 {
@@ -1272,12 +1358,32 @@ func Signal(pid int, sig syscall.Signal) error {
 
 // ---- small helpers ----
 
+// readStr reads a /proc or /sys file whole, with plain blocking syscalls and never through
+// the runtime poller. os.ReadFile would hand a sysfs file to the poller — kernfs accepts
+// epoll — and a driver that answers a non-blocking read with EAGAIN (i915's fan attribute
+// did, on grid, 2026-10-02) then leaves the reader waiting for a readiness kernfs only
+// signals on sysfs_notify: never. The sampler sat in that wait for 42 minutes.
 func readStr(p string) string {
-	b, err := os.ReadFile(p)
+	fd, err := syscall.Open(p, syscall.O_RDONLY|syscall.O_CLOEXEC, 0)
 	if err != nil {
 		return ""
 	}
-	return string(b)
+	defer syscall.Close(fd)
+	var out []byte
+	buf := make([]byte, 4096)
+	for {
+		n, err := syscall.Read(fd, buf)
+		if n > 0 {
+			out = append(out, buf[:n]...)
+		}
+		if err == syscall.EINTR {
+			continue
+		}
+		if err != nil || n == 0 {
+			break
+		}
+	}
+	return string(out)
 }
 
 func readInt(p string) (int64, bool) {

internal/metrics/pciids.go

@@ -0,0 +1,47 @@
+package metrics
+
+// A trimmed PCI ID database, embedded, so a GPU is named the same on every machine —
+// "Intel UHD Graphics 600" — whether or not that machine has pciutils. OpenWrt has neither
+// lspci nor pci.ids, and the router's GPU came up as "Intel GPU 3185" beside its twin's
+// "Intel UHD Graphics 600" until this. scripts/pci-ids-gpu.sh regenerates the file.
+
+import (
+	_ "embed"
+	"strings"
+	"sync"
+)
+
+//go:embed pciids_gpu.txt
+var pciIDsGPU string
+
+var pciTable struct {
+	once    sync.Once
+	vendors map[string]string // "8086" → "Intel Corporation"
+	devices map[string]string // "8086:3185" → "GeminiLake [UHD Graphics 600]"
+}
+
+// pciName looks a vendor and device ID up (hex, lower case, no 0x): the vendor's name and
+// the device's; empty where unknown.
+func pciName(vendor, device string) (string, string) {
+	pciTable.once.Do(func() {
+		pciTable.vendors, pciTable.devices = map[string]string{}, map[string]string{}
+		cur := ""
+		for _, line := range strings.Split(pciIDsGPU, "\n") {
+			switch {
+			case line == "" || line[0] == '#':
+			case line[0] == '\t':
+				if cur == "" || len(line) < 7 || line[1] == '\t' {
+					continue // a subsystem, or a device before any vendor
+				}
+				pciTable.devices[cur+":"+line[1:5]] = strings.TrimSpace(line[5:])
+			default:
+				if len(line) >= 6 {
+					cur = line[:4]
+					pciTable.vendors[cur] = strings.TrimSpace(line[4:])
+				}
+			}
+		}
+	})
+	vendor, device = strings.ToLower(vendor), strings.ToLower(device)
+	return pciTable.vendors[vendor], pciTable.devices[vendor+":"+device]
+}

internal/metrics/sensors.go

@@ -62,6 +62,9 @@ func flatten(s Sample, want func(id string) bool) []sensors.Sensor {
 	if c := cpuTemp(s.Temps); c > 0 {
 		f.add("cpu.temp", "CPU temperature", "temperature", "°C", c, t, none)
 	}
+	if s.CPUPower > 0 {
+		f.add("cpu.power", "CPU power", "power", "W", s.CPUPower, t, none)
+	}
 	for i, w := range []string{"1", "5", "15"} {
 		f.add("load."+w, "Load "+w+" min", "load", "", s.Load[i], t, none)
 	}
@@ -117,9 +120,87 @@ func flatten(s Sample, want func(id string) bool) []sensors.Sensor {
 
 	for _, x := range s.FS {
 		p := "fs." + sensors.Seg(x.Mount)
-		f.add(p+".size", x.Mount+" size", "bytes", "B", float64(x.Size), s.fsT, none, "mount", x.Mount, "fstype", x.Type)
-		f.add(p+".used", x.Mount+" used", "bytes", "B", float64(x.Used), s.fsT, upTo(float64(x.Size)), "mount", x.Mount, "fstype", x.Type)
-		f.add(p+".used_pct", x.Mount+" used", "usage", "%", ratio(x.Used, x.Size), s.fsT, pct, "mount", x.Mount, "fstype", x.Type)
+		// remote says the bytes are on another machine (a CIFS or NFS share), so a view of
+		// this machine's hardware can leave it out without losing the sensor
+		lbl := []string{"mount", x.Mount, "fstype", x.Type}
+		if x.Remote {
+			lbl = append(lbl, "remote", "1")
+		}
+		if x.Disk != "" {
+			lbl = append(lbl, "disk", x.Disk)
+		}
+		f.add(p+".size", x.Mount+" size", "bytes", "B", float64(x.Size), s.fsT, none, lbl...)
+		f.add(p+".used", x.Mount+" used", "bytes", "B", float64(x.Used), s.fsT, upTo(float64(x.Size)), lbl...)
+		f.add(p+".used_pct", x.Mount+" used", "usage", "%", ratio(x.Used, x.Size), s.fsT, pct, lbl...)
+	}
+
+	for _, g := range s.GPUs {
+		p := "gpu." + sensors.Seg(g.Name)
+		lbl := []string{"name", g.Name, "driver", g.Driver}
+		if g.Bus != "" {
+			lbl = append(lbl, "bus", g.Bus)
+		}
+		if g.Integrated {
+			lbl = append(lbl, "integrated", "1")
+		}
+		if g.UsageSrc != "" {
+			f.add(p+".usage", g.Name, "usage", "%", g.Usage, t, pct, lbl...)
+		}
+		for _, e := range []string{"render", "video", "copy", "video-enhance", "compute"} {
+			if v, ok := g.Engines[e]; ok {
+				f.add(p+"."+sensors.Seg(e), g.Name+" "+e, "usage", "%", v, t, pct, lbl...)
+			}
+		}
+		if g.Temp > 0 {
+			f.add(p+".temp", g.Name+" temperature", "temperature", "°C", g.Temp, t, none, append(lbl, "source", g.TempSrc)...)
+		}
+		if g.PowerW > 0 || g.PowerCapW > 0 {
+			b := none
+			if g.PowerCapW > 0 {
+				b = upTo(g.PowerCapW)
+			}
+			f.add(p+".power", g.Name+" power", "power", "W", g.PowerW, t, b, lbl...)
+		}
+		if g.FanRPM > 0 {
+			f.add(p+".fan", g.Name+" fan", "fan", "rpm", float64(g.FanRPM), t, none, lbl...)
+		}
+		if g.MaxMHz > 0 {
+			f.add(p+".freq", g.Name+" clock", "frequency", "MHz", g.MHz, t, upTo(g.MaxMHz), lbl...)
+		}
+		if g.MemTotal > 0 {
+			f.add(p+".mem_used", g.Name+" memory used", "bytes", "B", float64(g.MemUsed), t, upTo(float64(g.MemTotal)), lbl...)
+			f.add(p+".mem_total", g.Name+" memory", "bytes", "B", float64(g.MemTotal), t, none, lbl...)
+		} else if g.MemUsed > 0 {
+			f.add(p+".mem_used", g.Name+" memory used", "bytes", "B", float64(g.MemUsed), t, none, lbl...)
+		}
+		f.add(p+".clients", g.Name+" clients", "count", "", float64(len(g.Clients)), t, none, lbl...)
+	}
+
+	if a := s.ARC; a != nil {
+		p := "zfs.arc."
+		cap := upTo(float64(a.Max))
+		f.add(p+"size", "ARC size", "bytes", "B", float64(a.Size), t, cap)
+		f.add(p+"target", "ARC target", "bytes", "B", float64(a.Target), t, cap)
+		f.add(p+"min", "ARC floor", "bytes", "B", float64(a.Min), t, none)
+		f.add(p+"max", "ARC ceiling", "bytes", "B", float64(a.Max), t, none)
+		f.add(p+"mru", "ARC recently used", "bytes", "B", float64(a.MRU), t, cap)
+		f.add(p+"mfu", "ARC frequently used", "bytes", "B", float64(a.MFU), t, cap)
+		f.add(p+"metadata", "ARC metadata", "bytes", "B", float64(a.Metadata), t, cap)
+		f.add(p+"data", "ARC data", "bytes", "B", float64(a.Data), t, cap)
+		if a.HitPctKnown {
+			f.add(p+"hit_pct", "ARC hit rate", "usage", "%", a.HitPct, t, pct)
+		}
+		f.add(p+"reads", "ARC reads", "rate", "/s", a.ReadsPerSec, t, none)
+		f.add(p+"misses", "ARC misses", "rate", "/s", a.MissesPerSec, t, none)
+		f.add(p+"lifetime_hit_pct", "ARC hit rate since boot", "usage", "%", a.LifetimeHitPct, t, pct)
+		f.add(p+"no_grow", "ARC held by memory pressure", "state", "", a.NoGrow, t, none)
+		if a.Compressed > 0 {
+			f.add(p+"compress_ratio", "ARC compression", "ratio", "x", round1(float64(a.Uncompressed)/float64(a.Compressed)*10)/10, t, none)
+		}
+		if a.L2Size > 0 {
+			f.add(p+"l2_size", "L2ARC size", "bytes", "B", float64(a.L2Size), t, none)
+			f.add(p+"l2_hit_pct", "L2ARC hit rate", "usage", "%", a.L2HitPct, t, pct)
+		}
 	}
 
 	if u := s.UPS; u != nil {

internal/network/network.go

@@ -0,0 +1,360 @@
+// Package network is what the Network tab shows: the machine's interfaces as the kernel has
+// them, how the internet looks from out there, and a speed test that measures the line.
+//
+// Everything here is read from /proc and /sys, or measured against Cloudflare's public speed
+// endpoints — no tool to install, on any of the machines. That matters for the router, where
+// flash is small and `opkg install` is a decision.
+package network
+
+import (
+	"bufio"
+	"encoding/binary"
+	"fmt"
+	"net"
+	"os"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// Addr is one address on an interface.
+type Addr struct {
+	IP     string `json:"ip"`
+	Prefix int    `json:"prefix"` // network bits, as in /24
+	V6     bool   `json:"v6,omitempty"`
+}
+
+// Iface is one network interface: what it is, whether it is up, and what it has moved.
+type Iface struct {
+	Name string `json:"name"`
+	Kind string `json:"kind"` // ethernet | wifi | bridge | tunnel | loopback | virtual
+	MAC  string `json:"mac,omitempty"`
+	MTU  int    `json:"mtu"`
+	// Up is the administrative state, Carrier whether a cable (or an association) is actually
+	// there. Up without Carrier is the usual "it's plugged into nothing".
+	Up      bool `json:"up"`
+	Carrier bool `json:"carrier"`
+	// SpeedMbps is what the link negotiated, where the driver says: 0 for wireless, virtual
+	// and tunnel devices, which have no such number.
+	SpeedMbps int      `json:"speed_mbps,omitempty"`
+	Duplex    string   `json:"duplex,omitempty"`
+	Driver    string   `json:"driver,omitempty"`
+	SignalDbm *float64 `json:"signal_dbm,omitempty"` // wireless only, from /proc/net/wireless
+	Addrs     []Addr   `json:"addrs"`
+	RxTotal   uint64   `json:"rx_total"`
+	TxTotal   uint64   `json:"tx_total"`
+	// Default marks the interface the default route leaves by — the one that matters when
+	// the question is about the internet.
+	Default bool `json:"default,omitempty"`
+}
+
+// Report is the machine's network as it stands.
+type Report struct {
+	At         time.Time `json:"at"`
+	Host       string    `json:"host,omitempty"`
+	Ifaces     []Iface   `json:"ifaces"`
+	Gateway    string    `json:"gateway,omitempty"`
+	GatewayVia string    `json:"gateway_via,omitempty"` // the interface it is reached through
+	DNS        []string  `json:"dns,omitempty"`
+	Search     []string  `json:"search,omitempty"`
+}
+
+func readStr(path string) string {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+func readInt(path string) int {
+	n, err := strconv.Atoi(readStr(path))
+	if err != nil {
+		return 0
+	}
+	return n
+}
+
+// kindOf names what sort of device this is, from what the kernel exposes about it rather
+// than from its name — a bridge is a bridge whatever it is called.
+func kindOf(name string, flags net.Flags) string {
+	sys := "/sys/class/net/" + name + "/"
+	switch {
+	case flags&net.FlagLoopback != 0:
+		return "loopback"
+	case dirExists(sys + "wireless"), dirExists(sys + "phy80211"):
+		return "wifi"
+	case dirExists(sys + "bridge"):
+		return "bridge"
+	case dirExists(sys + "bonding"):
+		return "bond"
+	}
+	// DEVTYPE says vlan, bridge, wlan… for the devices that have one
+	for _, line := range strings.Split(readStr(sys+"uevent"), "\n") {
+		if v, ok := strings.CutPrefix(line, "DEVTYPE="); ok && v != "" {
+			return v
+		}
+	}
+	if !dirExists(sys + "device") { // no bus device behind it: veth, tun, wireguard, docker's own
+		return "virtual"
+	}
+	return "ethernet"
+}
+
+func dirExists(p string) bool {
+	st, err := os.Stat(p)
+	return err == nil && st.IsDir()
+}
+
+// driverOf is the module behind an interface, which is what names the hardware in one word.
+func driverOf(name string) string {
+	l, err := os.Readlink("/sys/class/net/" + name + "/device/driver")
+	if err != nil {
+		return ""
+	}
+	return l[strings.LastIndexByte(l, '/')+1:]
+}
+
+// wirelessSignal is the signal level of each wireless interface, in dBm.
+func wirelessSignal() map[string]float64 {
+	out := map[string]float64{}
+	f, err := os.Open("/proc/net/wireless")
+	if err != nil {
+		return out
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		name, rest, ok := strings.Cut(sc.Text(), ":")
+		if !ok {
+			continue
+		}
+		fs := strings.Fields(rest)
+		if len(fs) < 3 {
+			continue
+		}
+		if v, err := strconv.ParseFloat(strings.TrimSuffix(fs[2], "."), 64); err == nil {
+			out[strings.TrimSpace(name)] = v
+		}
+	}
+	return out
+}
+
+// counters is every interface's byte totals, from the same file the sampler reads.
+func counters() map[string][2]uint64 {
+	out := map[string][2]uint64{}
+	f, err := os.Open("/proc/net/dev")
+	if err != nil {
+		return out
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		name, rest, ok := strings.Cut(sc.Text(), ":")
+		if !ok {
+			continue
+		}
+		fs := strings.Fields(rest)
+		if len(fs) < 16 {
+			continue
+		}
+		rx, _ := strconv.ParseUint(fs[0], 10, 64)
+		tx, _ := strconv.ParseUint(fs[8], 10, 64)
+		out[strings.TrimSpace(name)] = [2]uint64{rx, tx}
+	}
+	return out
+}
+
+// defaultRoute is the gateway the machine sends the internet to, and the interface it
+// leaves by. Read from /proc/net/route, whose addresses are little-endian hex.
+func defaultRoute() (gw, via string) {
+	f, err := os.Open("/proc/net/route")
+	if err != nil {
+		return "", ""
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	best := -1
+	for sc.Scan() {
+		fs := strings.Fields(sc.Text())
+		if len(fs) < 8 || fs[0] == "Iface" {
+			continue
+		}
+		if fs[1] != "00000000" { // not a default route
+			continue
+		}
+		metric, _ := strconv.Atoi(fs[6])
+		if best >= 0 && metric >= best {
+			continue
+		}
+		ip, err := hexIP(fs[2])
+		if err != nil {
+			continue
+		}
+		best, gw, via = metric, ip, fs[0]
+	}
+	return gw, via
+}
+
+// hexIP reads one address out of /proc/net/route, where each is printed as a 32-bit word in
+// the host's byte order: 10.0.0.1 appears as "0100000A" on a little-endian machine. So the
+// text is parsed as a plain number, then written back out in native order to recover the four
+// bytes — which is right on either sort of machine, without asking which this is.
+func hexIP(h string) (string, error) {
+	v, err := strconv.ParseUint(h, 16, 32)
+	if err != nil || len(h) != 8 {
+		return "", fmt.Errorf("not an address: %q", h)
+	}
+	var b [4]byte
+	binary.NativeEndian.PutUint32(b[:], uint32(v))
+	return net.IPv4(b[0], b[1], b[2], b[3]).String(), nil
+}
+
+// resolvers is what /etc/resolv.conf points at.
+func resolvers() (servers, search []string) {
+	f, err := os.Open("/etc/resolv.conf")
+	if err != nil {
+		return nil, nil
+	}
+	defer f.Close()
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		fs := strings.Fields(sc.Text())
+		if len(fs) < 2 || strings.HasPrefix(fs[0], "#") {
+			continue
+		}
+		switch fs[0] {
+		case "nameserver":
+			servers = append(servers, fs[1])
+		case "search", "domain":
+			search = append(search, fs[1:]...)
+		}
+	}
+	return servers, search
+}
+
+// Interfaces is every interface the kernel has, with its addresses and totals.
+func Interfaces() []Iface {
+	list, err := net.Interfaces()
+	if err != nil {
+		return nil
+	}
+	_, via := defaultRoute()
+	sig, cnt := wirelessSignal(), counters()
+	out := make([]Iface, 0, len(list))
+	for _, in := range list {
+		sys := "/sys/class/net/" + in.Name + "/"
+		f := Iface{
+			Name: in.Name, Kind: kindOf(in.Name, in.Flags), MTU: in.MTU,
+			MAC: in.HardwareAddr.String(), Up: in.Flags&net.FlagUp != 0,
+			Driver: driverOf(in.Name), Default: in.Name == via, Addrs: []Addr{},
+		}
+		f.Carrier = readStr(sys+"carrier") == "1"
+		if f.Kind == "loopback" {
+			f.Carrier = f.Up
+		}
+		if sp := readInt(sys + "speed"); sp > 0 { // -1 when the driver doesn't know
+			f.SpeedMbps = sp
+		}
+		if d := readStr(sys + "duplex"); d != "" && d != "unknown" {
+			f.Duplex = d
+		}
+		if v, ok := sig[in.Name]; ok {
+			f.SignalDbm = &v
+		}
+		if c, ok := cnt[in.Name]; ok {
+			f.RxTotal, f.TxTotal = c[0], c[1]
+		}
+		addrs, _ := in.Addrs()
+		for _, a := range addrs {
+			n, ok := a.(*net.IPNet)
+			if !ok {
+				continue
+			}
+			ones, _ := n.Mask.Size()
+			f.Addrs = append(f.Addrs, Addr{IP: n.IP.String(), Prefix: ones, V6: n.IP.To4() == nil})
+		}
+		out = append(out, f)
+	}
+	// the interface the internet leaves by first, then the ones carrying addresses, then the rest
+	sort.SliceStable(out, func(i, j int) bool {
+		a, b := out[i], out[j]
+		if a.Default != b.Default {
+			return a.Default
+		}
+		ai, bi := len(a.Addrs) > 0 && a.Kind != "loopback", len(b.Addrs) > 0 && b.Kind != "loopback"
+		if ai != bi {
+			return ai
+		}
+		return a.Name < b.Name
+	})
+	return out
+}
+
+// Look is the machine's network now. Cheap: a handful of small files.
+func Look(host string) Report {
+	gw, via := defaultRoute()
+	dns, search := resolvers()
+	return Report{At: time.Now(), Host: host, Ifaces: Interfaces(), Gateway: gw, GatewayVia: via, DNS: dns, Search: search}
+}
+
+// ---- how the internet sees this machine ----
+
+// Outside is what the far end of the line says about this connection: the address the
+// internet sees, and where it came ashore. Refreshed on its own clock, because the public
+// address here is a DHCP lease and moves without warning.
+type Outside struct {
+	At      time.Time `json:"at"`
+	IP      string    `json:"ip,omitempty"`
+	Colo    string    `json:"colo,omitempty"` // the Cloudflare edge that answered — "SEA"
+	Country string    `json:"country,omitempty"`
+	Error   string    `json:"error,omitempty"`
+}
+
+// Watcher keeps the outside view fresh and holds the speed tester.
+type Watcher struct {
+	mu   sync.RWMutex
+	out  Outside
+	Test *Tester
+}
+
+const outsideEvery = 15 * time.Minute
+
+func NewWatcher(onResult func(Result)) *Watcher {
+	w := &Watcher{Test: NewTester(onResult)}
+	go func() {
+		for {
+			w.refresh()
+			time.Sleep(outsideEvery)
+		}
+	}()
+	return w
+}
+
+func (w *Watcher) refresh() {
+	o := probeOutside()
+	w.mu.Lock()
+	// a failed probe does not throw away a good answer; it is noted beside it
+	if o.IP == "" && w.out.IP != "" {
+		w.out.Error, w.out.At = o.Error, o.At
+	} else {
+		w.out = o
+	}
+	w.mu.Unlock()
+}
+
+// Outside is the last known view from outside, asking again if it has gone stale.
+func (w *Watcher) Outside() Outside {
+	w.mu.RLock()
+	o := w.out
+	w.mu.RUnlock()
+	if time.Since(o.At) > outsideEvery {
+		w.refresh()
+		w.mu.RLock()
+		o = w.out
+		w.mu.RUnlock()
+	}
+	return o
+}

internal/network/network_test.go

@@ -0,0 +1,317 @@
+package network
+
+import (
+	"context"
+	"errors"
+	"io"
+	"math"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestHexIP(t *testing.T) {
+	// /proc/net/route prints each address as a host-order word: on a little-endian machine
+	// 10.0.0.1 is written "0100000A". These cases are that machine, which is all of ours.
+	for hex, want := range map[string]string{
+		"0100000A": "10.0.0.1",
+		"00000000": "0.0.0.0",
+		"0101A8C0": "192.168.1.1",
+	} {
+		got, err := hexIP(hex)
+		if err != nil || got != want {
+			t.Errorf("hexIP(%q) = %q, %v; want %q", hex, got, err, want)
+		}
+	}
+	if _, err := hexIP("nonsense"); err == nil {
+		t.Error("hexIP accepted nonsense")
+	}
+}
+
+func TestServerTimeIsNotLatency(t *testing.T) {
+	h := http.Header{}
+	h.Add("Server-Timing", "cfSpeedEdge;dur=7, cfSpeedWorker;dur=36")
+	h.Add("Server-Timing", `cfL4;desc="?proto=TCP&rtt=3505&min_rtt=2856"`)
+	if got := serverMs(h); got != 43 {
+		t.Errorf("serverMs = %v, want 43 (7+36, and nothing from the cfL4 description)", got)
+	}
+	if got := serverMs(http.Header{}); got != 0 {
+		t.Errorf("serverMs with no header = %v, want 0", got)
+	}
+	h2 := http.Header{"Cf-Ray": {"a41f6720f966a36c-SEA"}, "Cf-Meta-Ip": {"50.47.252.221"}}
+	if m := readMeta(h2); m.Colo != "SEA" || m.IP != "50.47.252.221" {
+		t.Errorf("readMeta = %+v, want the edge SEA and the address", m)
+	}
+}
+
+func TestRates(t *testing.T) {
+	// a gibibyte in eight seconds is 1073.7 Mbps
+	if got := mbps(1<<30, 8); math.Abs(got-1073.7) > 0.1 {
+		t.Errorf("mbps(1GiB, 8s) = %v, want ~1073.7", got)
+	}
+	if got := best([]float64{12.5, 9.2, 40, 9.9}); got != 9.2 {
+		t.Errorf("best = %v, want 9.2 (the least of them)", got)
+	}
+	if got := jitter([]float64{10, 10, 10}); got != 0 {
+		t.Errorf("jitter of a steady line = %v, want 0", got)
+	}
+	if got := jitter([]float64{10}); got != 0 {
+		t.Errorf("jitter of one sample = %v, want 0", got)
+	}
+	if got := jitter([]float64{5, 50, 5, 50}); got != 45 {
+		t.Errorf("jitter of a line alternating by 45 = %v, want 45", got)
+	}
+	// one slow probe among steady ones moves it a little, not enormously
+	if got := jitter([]float64{10, 10, 10, 60, 10, 10}); got > 25 {
+		t.Errorf("jitter with a single outlier = %v, want it not to run away", got)
+	}
+}
+
+// The body an upload sends is a fixed size, counts itself, and costs nothing to make.
+func TestZerosBodyCountsItself(t *testing.T) {
+	var n atomic.Int64
+	z := &zeros{left: 100, n: &n}
+	buf := make([]byte, 30)
+	total := 0
+	for {
+		got, err := z.Read(buf)
+		total += got
+		if err != nil {
+			break
+		}
+	}
+	if total != 100 || n.Load() != 100 {
+		t.Errorf("read %d bytes and counted %d, want 100 and 100", total, n.Load())
+	}
+}
+
+// Interfaces has to work on whatever machine this runs on, and always name a loopback.
+func TestInterfacesHasLoopback(t *testing.T) {
+	ifs := Interfaces()
+	if len(ifs) == 0 {
+		t.Fatal("no interfaces at all")
+	}
+	lo := false
+	for _, f := range ifs {
+		if f.Kind == "loopback" {
+			lo = true
+			if !f.Up || len(f.Addrs) == 0 {
+				t.Errorf("loopback %s looks wrong: up=%v addrs=%v", f.Name, f.Up, f.Addrs)
+			}
+		}
+		if f.Name == "" {
+			t.Error("an interface with no name")
+		}
+	}
+	if !lo {
+		t.Error("no loopback among the interfaces")
+	}
+}
+
+// The real thing, against the real endpoint: skipped by default, because `make test` must
+// not need the internet. HAMLAB_NET_TEST=1 go test ./internal/network/ -run Live -v
+func TestLiveSpeedTest(t *testing.T) {
+	if os.Getenv("HAMLAB_NET_TEST") == "" {
+		t.Skip("set HAMLAB_NET_TEST=1 to measure the actual line")
+	}
+	tr := NewTester(nil)
+	if _, err := tr.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := tr.Start(); err == nil {
+		t.Error("a second test started while the first was running")
+	}
+	deadline := time.Now().Add(90 * time.Second)
+	for tr.Running() && time.Now().Before(deadline) {
+		time.Sleep(250 * time.Millisecond)
+	}
+	st := tr.State()
+	if st.Result == nil {
+		t.Fatal("no result")
+	}
+	r := *st.Result
+	t.Logf("down %s  up %s  latency %.1f ms  jitter %.1f ms  via %s  ip %s  %.0f MB moved in %.1fs",
+		Mbits(r.DownMbps), Mbits(r.UpMbps), r.LatencyMs, r.JitterMs, r.Colo, r.IP,
+		float64(r.DownBytes+r.UpBytes)/1e6, r.TookSec)
+	if r.Error != "" {
+		t.Fatalf("test failed: %s", r.Error)
+	}
+	if r.DownMbps <= 0 || r.UpMbps <= 0 || r.LatencyMs <= 0 {
+		t.Errorf("a figure came back zero: %+v", r)
+	}
+	if r.IP == "" {
+		t.Error("no public address reported")
+	}
+	if len(tr.History()) != 1 {
+		t.Errorf("history has %d results, want 1", len(tr.History()))
+	}
+}
+
+// A phase measured against a local server, at a rate the test controls. This is the part of
+// the speed test with arithmetic in it — the window after the ramp, the byte cap that ends it
+// early, and the rate that comes out — and none of it needs the internet to check.
+func TestPhaseMeasuresTheWindow(t *testing.T) {
+	const perTick = 1 << 20 // a mebibyte every 5 ms ≈ 1678 Mbps, whatever the machine is doing
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/up" {
+			_, _ = io.Copy(io.Discard, r.Body)
+			w.WriteHeader(204)
+			return
+		}
+		buf := make([]byte, perTick)
+		fl, _ := w.(http.Flusher)
+		for {
+			if _, err := w.Write(buf); err != nil {
+				return
+			}
+			if fl != nil {
+				fl.Flush()
+			}
+			select {
+			case <-time.After(5 * time.Millisecond):
+			case <-r.Context().Done():
+				return
+			}
+		}
+	}))
+	defer srv.Close()
+
+	defer func(up string, w, d, mw time.Duration, m int64) {
+		upURL, warmUp, downFor, minWindow, measureBytes = up, w, d, mw, m
+	}(upURL, warmUp, downFor, minWindow, measureBytes)
+	upURL = srv.URL + "/up"
+	warmUp, downFor, minWindow, measureBytes = 100*time.Millisecond, 3*time.Second, 200*time.Millisecond, 8<<20
+	here := Source{"local", func(int) string { return srv.URL + "/down" }}
+
+	tr := NewTester(nil)
+	began := time.Now()
+	mbps, moved, note, err := tr.phase(context.Background(), srv.Client(), "download", 2, downFor, 0, 1, here)
+	took := time.Since(began)
+	if err != nil {
+		t.Fatalf("phase: %v", err)
+	}
+	if note != "" {
+		t.Errorf("note = %q, want none — nothing went wrong", note)
+	}
+	// The cap must have ended it early rather than the clock: the phase was allowed three
+	// seconds and should be done in well under one, having moved at least the cap.
+	if moved < measureBytes {
+		t.Errorf("moved %d bytes, want at least the %d-byte cap", moved, measureBytes)
+	}
+	if took > time.Second {
+		t.Errorf("phase took %v of the %v it was allowed; the byte cap should have ended it", took.Round(time.Millisecond), downFor)
+	}
+	// The server hands out a mebibyte per 5 ms per stream, so the rate is in the hundreds of
+	// Mbps. The point is that it is a real quotient of what moved over how long, not that it
+	// hits a particular figure on a loaded test machine.
+	if mbps < 50 || mbps > 20000 {
+		t.Errorf("mbps = %v, which is not a believable quotient", mbps)
+	}
+	t.Logf("measured %.0f Mbps over %.1f MiB", mbps, float64(moved)/(1<<20))
+
+	// A phase whose server refuses outright fails, and says what it was told.
+	bad := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(429) }))
+	defer bad.Close()
+	refuser := Source{"refuser", func(int) string { return bad.URL + "/down" }}
+	_, _, _, err = tr.phase(context.Background(), bad.Client(), "download", 2, 300*time.Millisecond, 0, 1, refuser)
+	if err == nil {
+		t.Error("a phase against a server that refuses everything should fail")
+	} else if !refused(err) {
+		t.Errorf("error = %q, want the refusal that makes the fallback kick in", err)
+	}
+}
+
+// Stopping a test mid-flight is reported as cancelled, not as whatever the streams said on
+// their way out.
+func TestCancelIsReportedAsCancelled(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		buf := make([]byte, 1<<16)
+		for {
+			if _, err := w.Write(buf); err != nil {
+				return
+			}
+			select {
+			case <-time.After(time.Millisecond):
+			case <-r.Context().Done():
+				return
+			}
+		}
+	}))
+	defer srv.Close()
+	defer func(w, d time.Duration) { warmUp, downFor = w, d }(warmUp, downFor)
+	warmUp, downFor = 10*time.Millisecond, 10*time.Second
+	here := Source{"local", func(int) string { return srv.URL + "/down" }}
+
+	tr := NewTester(nil)
+	ctx, cancel := context.WithCancel(context.Background())
+	go func() { time.Sleep(200 * time.Millisecond); cancel() }()
+	_, _, _, err := tr.phase(ctx, srv.Client(), "download", 1, downFor, 0, 1, here)
+	// Cancelled after bytes moved: the figure stands, and the phase does not claim an error.
+	if err != nil && !errors.Is(err, context.Canceled) {
+		t.Errorf("err = %v, want nil or a cancellation", err)
+	}
+}
+
+// When the first source refuses, the download is taken from the next one and the result says
+// so. This is the whole reason there is more than one.
+func TestDownloadFallsBackWhenRefused(t *testing.T) {
+	serving := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/up" {
+			_, _ = io.Copy(io.Discard, r.Body)
+			w.WriteHeader(204)
+			return
+		}
+		// paced, so the phase is governed by its window and not by a loopback moving a
+		// gibibyte before the first tick
+		buf := make([]byte, 1<<20)
+		fl, _ := w.(http.Flusher)
+		for i := 0; i < 64; i++ {
+			if _, err := w.Write(buf); err != nil {
+				return
+			}
+			if fl != nil {
+				fl.Flush()
+			}
+			select {
+			case <-time.After(2 * time.Millisecond):
+			case <-r.Context().Done():
+				return
+			}
+		}
+	}))
+	defer serving.Close()
+	refusing := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(429) }))
+	defer refusing.Close()
+
+	defer func(srcs []Source, up string, w, d, mw time.Duration, m int64) {
+		downSources, upURL, warmUp, downFor, minWindow, measureBytes = srcs, up, w, d, mw, m
+	}(downSources, upURL, warmUp, downFor, minWindow, measureBytes)
+	downSources = []Source{
+		{"refuser", func(int) string { return refusing.URL + "/down" }},
+		{"the-other-one", func(int) string { return serving.URL + "/down" }},
+	}
+	upURL = serving.URL + "/up"
+	warmUp, downFor, upFor, minWindow, measureBytes = 50*time.Millisecond, time.Second, 300*time.Millisecond, 100*time.Millisecond, 4<<20
+
+	tr := NewTester(nil)
+	if _, err := tr.Start(); err != nil {
+		t.Fatal(err)
+	}
+	deadline := time.Now().Add(30 * time.Second)
+	for tr.Running() && time.Now().Before(deadline) {
+		time.Sleep(50 * time.Millisecond)
+	}
+	res := tr.State().Result
+	if res == nil {
+		t.Fatal("no result")
+	}
+	if res.Source != "the-other-one" {
+		t.Errorf("source = %q, want the second one — the first refused", res.Source)
+	}
+	if res.DownMbps <= 0 {
+		t.Errorf("download = %v, want a figure from the source that did serve: %+v", res.DownMbps, res)
+	}
+}

internal/network/speedtest.go

@@ -0,0 +1,687 @@
+package network
+
+// The speed test. It measures against Cloudflare's public speed endpoints, the same ones
+// speed.cloudflare.com uses: a plain GET of N bytes down, a plain POST of N bytes up, and a
+// zero-byte GET for the round trip. No account, no API key, nothing to install, and an edge
+// close to every one of these machines.
+//
+// The method, since a number without one means little — it is stated in the UI too:
+//
+//   - Latency is the round trip of a zero-byte response on a connection that is already open,
+//     less the time the far end says it spent on the request (its Server-Timing header). That
+//     subtraction is the difference between measuring the line and measuring Cloudflare's
+//     thinking time: a zero-byte response is almost entirely the latter — tens of
+//     milliseconds of worker, against a few of actual wire. The figure reported is the best of
+//     several probes; jitter is the average change from one to the next.
+//   - Download and upload each run several streams at once for a fixed few seconds. One
+//     stream measures one TCP connection's congestion window as much as the line, which is
+//     why every speed test ever made uses more than one.
+//   - The first second of each phase is thrown away. That is the ramp: counting it reports a
+//     number nobody's connection ever actually did.
+//   - Each phase is capped in bytes as well as seconds, so a very fast line cannot run away
+//     with the meter.
+//
+// The one thing to know about the far end: it rate-limits by volume, and a test moves a few
+// hundred megabytes. Several in a row will start earning 429s, which is why there is a
+// cooldown between tests and why a phase that gets refused says so instead of reporting the
+// decayed figure it would otherwise compute.
+//
+// HTTP/2 is deliberately off: over one HTTP/2 connection the streams would share a single
+// congestion window, which measures the window, not the line.
+
+import (
+	"context"
+	"crypto/tls"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"math"
+	"net"
+	"net/http"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// The endpoints, and the shape of a phase. Variables rather than constants only so the tests
+// can point them at a local server and shrink the windows; nothing else rebinds them.
+// Source is somewhere to pull bytes from. Cloudflare's endpoint is the first choice because
+// it is anycast — near wherever Ham Lab is running — and because the same host answers for
+// upload and for the trace. The fallback exists because that endpoint rate-limits by volume
+// and will refuse a connection that has been tested hard: a plain 100 MB file on a public
+// mirror has no such opinion. It is in Seattle, so on a machine far from there it will read
+// low, which is exactly why every result names the source it used.
+type Source struct {
+	Name string
+	// URL takes the number of bytes wanted, where the source can be asked; a fixed file
+	// ignores it and is fetched again each time round.
+	URL func(bytes int) string
+}
+
+var downSources = []Source{
+	{"cloudflare", func(b int) string { return fmt.Sprintf(cfDownURL, b) }},
+	{"linode-seattle", func(int) string { return "https://speedtest.seattle.linode.com/100MB-seattle.bin" }},
+}
+
+var (
+	cfDownURL = "https://speed.cloudflare.com/__down?bytes=%d"
+	upURL     = "https://speed.cloudflare.com/__up"
+	// traceURL is Cloudflare's standard trace: a few lines of key=value naming the address it
+	// sees, the edge that answered and the country. A few hundred bytes.
+	traceURL = "https://speed.cloudflare.com/cdn-cgi/trace"
+
+	warmUp  = time.Second
+	downFor = 4 * time.Second
+	upFor   = 4 * time.Second
+	// measureBytes ends a phase early once this much has moved inside the window. A fast line
+	// says what it is in well under the time allowed, and stopping there is what keeps a test
+	// down to a couple of hundred megabytes — which is the difference between the far end
+	// serving this happily and rate-limiting it. A slow line never reaches it and is timed out
+	// by downFor/upFor instead, which is the honest way round.
+	measureBytes = int64(64) << 20
+	// minWindow is how long the window must last whatever the byte cap says. Without it a very
+	// fast line fills the cap in a few hundredths of a second and the phase would be over
+	// before there was anything to divide by.
+	minWindow = time.Second
+)
+
+const (
+	latencyProbes = 8
+	downStreams   = 4
+	upStreams     = 3
+	downChunk     = 25 << 20 // bytes per download request; the far end refuses much more
+	upChunk       = 25 << 20 // and per upload request
+	// phaseBudget is the runaway guard, counting the ramp too: nothing measures forever.
+	phaseBudget = int64(512) << 20
+	httpTimeout = 90 * time.Second
+	// Cooldown is how long the line is left alone between tests. The far end rate-limits by
+	// volume, and two back-to-back tests are the surest way to be refused by it.
+	Cooldown = 20 * time.Second
+
+	// Method is what the UI tells the reader about the numbers it is showing.
+	Method = "Cloudflare's speed endpoints · 4 streams down, 3 up · a 1 s ramp, then up to 4 s or 64 MiB each way"
+)
+
+// Result is one finished speed test.
+type Result struct {
+	At        time.Time `json:"at"`
+	DownMbps  float64   `json:"down_mbps"`
+	UpMbps    float64   `json:"up_mbps"`
+	LatencyMs float64   `json:"latency_ms"`
+	JitterMs  float64   `json:"jitter_ms"`
+	DownBytes int64     `json:"down_bytes"`
+	UpBytes   int64     `json:"up_bytes"`
+	TookSec   float64   `json:"took_sec"`
+	// Colo is the Cloudflare edge that answered — "SEA" — and IP is this connection's public
+	// address as that edge saw it.
+	Colo string `json:"colo,omitempty"`
+	IP   string `json:"ip,omitempty"`
+	// Source is where the download came from, which matters because the fallback is not in the
+	// same place as the anycast one. Empty means the usual.
+	Source string `json:"source,omitempty"`
+	// Note is set when the figures are real but something went wrong along the way — a stream
+	// that was refused part-way, most often. The number is what was actually seen; the note is
+	// why it may be low.
+	Note  string `json:"note,omitempty"`
+	Error string `json:"error,omitempty"`
+}
+
+// Run is a test in progress, or the last one to have finished.
+type Run struct {
+	Started time.Time `json:"started"`
+	Running bool      `json:"running"`
+	// Phase is where it has got to: latency, download, upload, done.
+	Phase string `json:"phase"`
+	// Done is how far through the whole test, 0–1, so one bar can show all of it.
+	Done float64 `json:"done"`
+	// Mbps is the live figure for the phase under way — what the needle shows.
+	Mbps   float64 `json:"mbps"`
+	Bytes  int64   `json:"bytes"`
+	Result *Result `json:"result,omitempty"`
+}
+
+// Tester runs one speed test at a time and remembers what the last ones said.
+type Tester struct {
+	mu   sync.RWMutex
+	run  Run
+	hist []Result
+	// lastTry is when a test was last *started*, which is what the cooldown counts from — a
+	// test that was refused still used the line, and hammering retries at an endpoint that has
+	// just rate-limited us is the one thing guaranteed not to help.
+	lastTry time.Time
+	cancel  context.CancelFunc
+	onDone  func(Result)
+	maxHist int
+}
+
+func NewTester(onDone func(Result)) *Tester {
+	return &Tester{onDone: onDone, maxHist: 50}
+}
+
+// Load takes the results kept from before a restart, oldest first.
+func (t *Tester) Load(rs []Result) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.hist = append(t.hist[:0], rs...)
+	if n := len(t.hist); n > 0 {
+		last := t.hist[n-1]
+		t.run = Run{Started: last.At, Phase: "done", Done: 1, Result: &last}
+		t.lastTry = last.At
+	}
+}
+
+func (t *Tester) State() Run {
+	t.mu.RLock()
+	defer t.mu.RUnlock()
+	return t.run
+}
+
+func (t *Tester) History() []Result {
+	t.mu.RLock()
+	defer t.mu.RUnlock()
+	return append([]Result{}, t.hist...)
+}
+
+func (t *Tester) Running() bool {
+	t.mu.RLock()
+	defer t.mu.RUnlock()
+	return t.run.Running
+}
+
+// Cancel stops a test in progress. Reports whether there was one.
+func (t *Tester) Cancel() bool {
+	t.mu.Lock()
+	c := t.cancel
+	t.mu.Unlock()
+	if c == nil {
+		return false
+	}
+	c()
+	return true
+}
+
+var ErrBusy = errors.New("a speed test is already running")
+
+// Start begins a test in the background and returns its opening state.
+func (t *Tester) Start() (Run, error) {
+	t.mu.Lock()
+	if t.run.Running {
+		r := t.run
+		t.mu.Unlock()
+		return r, ErrBusy
+	}
+	if since := time.Since(t.lastTry); since < Cooldown && !t.lastTry.IsZero() {
+		r := t.run
+		t.mu.Unlock()
+		return r, fmt.Errorf("give the line %d more seconds — testing back to back is what gets this connection rate-limited", int((Cooldown-since).Seconds())+1)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	t.cancel = cancel
+	t.lastTry = time.Now()
+	t.run = Run{Started: t.lastTry, Running: true, Phase: "latency"}
+	r := t.run
+	t.mu.Unlock()
+	go t.measure(ctx, cancel)
+	return r, nil
+}
+
+func (t *Tester) set(fn func(*Run)) {
+	t.mu.Lock()
+	fn(&t.run)
+	t.mu.Unlock()
+}
+
+func (t *Tester) measure(ctx context.Context, cancel context.CancelFunc) {
+	defer cancel()
+	started := time.Now()
+	res := Result{At: started}
+
+	tr := newTransport(downStreams)
+	defer tr.CloseIdleConnections()
+	client := &http.Client{Transport: tr, Timeout: httpTimeout}
+
+	// latency, and the meta the same responses carry
+	lat, meta, err := t.latency(ctx, client)
+	if err == nil {
+		res.LatencyMs, res.JitterMs = best(lat), jitter(lat)
+		res.Colo, res.IP = meta.Colo, meta.IP
+	}
+	var note string
+	if err == nil {
+		t.set(func(r *Run) { r.Phase, r.Done, r.Mbps = "download", 0.1, 0 })
+		// Each source in turn: a refusal from the first is exactly what the second is for, and
+		// anything else (no route, no DNS) would fail the same way twice, so it stops there.
+		for i, src := range downSources {
+			res.Source = src.Name
+			res.DownMbps, res.DownBytes, note, err = t.phase(ctx, client, "download", downStreams, downFor, 0.1, 0.6, src)
+			if err == nil || !refused(err) || i == len(downSources)-1 {
+				break
+			}
+			log.Printf("speed test: %s refused the download, trying %s", src.Name, downSources[i+1].Name)
+		}
+		res.Note = join(res.Note, note)
+	}
+	if err == nil {
+		t.set(func(r *Run) { r.Phase, r.Done, r.Mbps = "upload", 0.7, 0 })
+		res.UpMbps, res.UpBytes, note, err = t.phase(ctx, client, "upload", upStreams, upFor, 0.7, 1.0, Source{Name: "cloudflare"})
+		res.Note = join(res.Note, note)
+	}
+	res.TookSec = round(time.Since(started).Seconds(), 1)
+	if err != nil {
+		if ctx.Err() != nil {
+			res.Error = "cancelled"
+		} else {
+			res.Error = err.Error()
+		}
+	}
+
+	t.mu.Lock()
+	t.cancel = nil
+	t.run = Run{Started: started, Phase: "done", Done: 1, Result: &res, Bytes: res.DownBytes + res.UpBytes}
+	if res.Error == "" || res.DownMbps > 0 { // a cancelled test that got a number is still a reading
+		t.hist = append(t.hist, res)
+		if len(t.hist) > t.maxHist {
+			t.hist = t.hist[len(t.hist)-t.maxHist:]
+		}
+	}
+	done, out := t.onDone, res
+	t.mu.Unlock()
+	if done != nil {
+		done(out)
+	}
+}
+
+// meta is what the edge says about the connection. The address comes from a header of the
+// speed endpoint's own; the edge's name is the tail of the ray ID, which every Cloudflare
+// response carries ("a41f6720f966a36c-SEA").
+type meta struct{ IP, Colo string }
+
+func readMeta(h http.Header) meta {
+	m := meta{IP: h.Get("cf-meta-ip")}
+	if ray := h.Get("cf-ray"); ray != "" {
+		if i := strings.LastIndexByte(ray, '-'); i >= 0 {
+			m.Colo = ray[i+1:]
+		}
+	}
+	return m
+}
+
+// serverMs is how long the far end says it spent on this request, from Server-Timing. The
+// cfL4 entry carries no dur= and contributes nothing, which is what we want — it is a
+// description of the connection, not time spent.
+func serverMs(h http.Header) float64 {
+	var total float64
+	for _, v := range h.Values("Server-Timing") {
+		for _, part := range strings.Split(v, ",") {
+			_, after, ok := strings.Cut(part, "dur=")
+			if !ok {
+				continue
+			}
+			end := 0
+			for end < len(after) && (after[end] == '.' || (after[end] >= '0' && after[end] <= '9')) {
+				end++
+			}
+			if f, err := strconv.ParseFloat(after[:end], 64); err == nil {
+				total += f
+			}
+		}
+	}
+	return total
+}
+
+// latency times several zero-byte responses on an already-open connection.
+func (t *Tester) latency(ctx context.Context, client *http.Client) ([]float64, meta, error) {
+	var m meta
+	var out []float64
+	for i := 0; i <= latencyProbes; i++ { // the first is the handshake, and is not counted
+		start := time.Now()
+		req, err := http.NewRequestWithContext(ctx, "GET", fmt.Sprintf(cfDownURL, 0), nil)
+		if err != nil {
+			return nil, m, err
+		}
+		resp, err := client.Do(req)
+		if err != nil {
+			return nil, m, err
+		}
+		_, _ = io.Copy(io.Discard, resp.Body)
+		resp.Body.Close()
+		if resp.StatusCode != 200 {
+			return nil, m, fmt.Errorf("speed endpoint answered %s", resp.Status)
+		}
+		if i == 0 {
+			m = readMeta(resp.Header)
+			continue
+		}
+		rtt := float64(time.Since(start).Microseconds())/1000 - serverMs(resp.Header)
+		if rtt < 0.01 { // the far end claimed more time than the whole request took
+			rtt = 0.01
+		}
+		out = append(out, rtt)
+		t.set(func(r *Run) { r.Done = 0.02 + 0.08*float64(i)/latencyProbes })
+	}
+	if len(out) == 0 {
+		return nil, m, errors.New("no reply from the speed endpoint")
+	}
+	return out, m, nil
+}
+
+// phase pushes traffic with several streams for a fixed spell and reports the rate over the
+// window after the ramp. from and to are where this phase sits in the whole test's progress.
+//
+// The window ends when the traffic does, not when the clock runs out: if the far end starts
+// refusing part-way, the figure is what was actually moved while it was moving, and the note
+// says what happened. Coasting to the end of the clock with no bytes arriving would report a
+// number a third of the truth.
+func (t *Tester) phase(parent context.Context, client *http.Client, dir string, streams int, forHow time.Duration, from, to float64, src Source) (float64, int64, string, error) {
+	// parent is the test's own context, which is cancelled when somebody presses Stop. ctx is
+	// this phase's, which *this function* cancels to shut the streams down — so the two are
+	// kept apart: asking ctx whether the test was cancelled would always say yes by then, and
+	// every failure would be reported as "context canceled" whatever really happened.
+	ctx, stop := context.WithCancel(parent)
+	defer stop()
+
+	var moved atomic.Int64
+	var firstErr error
+	var errOnce sync.Once
+	var alive atomic.Int32
+	alive.Store(int32(streams))
+	dead := make(chan struct{})
+	var deadOnce sync.Once
+
+	for i := 0; i < streams; i++ {
+		go func() {
+			defer func() {
+				if alive.Add(-1) == 0 {
+					deadOnce.Do(func() { close(dead) })
+				}
+			}()
+			tries := 0
+			for ctx.Err() == nil && moved.Load() < phaseBudget {
+				var err error
+				if dir == "download" {
+					err = stream(ctx, client, src, &moved)
+				} else {
+					err = upstream(ctx, client, &moved)
+				}
+				if err == nil {
+					tries = 0
+					continue
+				}
+				if ctx.Err() != nil {
+					return
+				}
+				errOnce.Do(func() { firstErr = err })
+				if tries++; tries > 2 { // refused three times: this stream is finished
+					return
+				}
+				select {
+				case <-time.After(400 * time.Millisecond):
+				case <-ctx.Done():
+					return
+				}
+			}
+		}()
+	}
+
+	// the ramp, measured and thrown away
+	select {
+	case <-time.After(warmUp):
+	case <-dead:
+	case <-ctx.Done():
+	}
+	mark, at := moved.Load(), time.Now()
+	last, lastAt := mark, at // the last time bytes were still arriving
+	deadline := at.Add(forHow)
+	tick := time.NewTicker(200 * time.Millisecond)
+	defer tick.Stop()
+
+	for time.Now().Before(deadline) {
+		select {
+		case <-tick.C:
+		case <-dead:
+		case <-ctx.Done():
+		}
+		if parent.Err() != nil {
+			break
+		}
+		now := moved.Load()
+		if now > last {
+			last, lastAt = now, time.Now()
+		}
+		// enough has moved to know, and it has been long enough to mean it
+		if (now-mark >= measureBytes && time.Since(at) >= minWindow) || now >= phaseBudget {
+			break
+		}
+		if secs := time.Since(at).Seconds(); secs > 0 {
+			live := mbps(now-mark, secs)
+			part := math.Min(1, secs/forHow.Seconds())
+			t.set(func(r *Run) { r.Mbps, r.Bytes, r.Done = live, now, from+(to-from)*part })
+		}
+		// every stream has given up and nothing more is coming
+		if alive.Load() == 0 {
+			break
+		}
+	}
+	total, secs := last-mark, lastAt.Sub(at).Seconds()
+	stop()
+
+	if total <= 0 {
+		switch {
+		case firstErr != nil: // what the far end said explains it better than anything else
+			return 0, moved.Load(), "", firstErr
+		case parent.Err() != nil:
+			return 0, moved.Load(), "", parent.Err()
+		}
+		return 0, moved.Load(), "", fmt.Errorf("nothing moved in the %s phase", dir)
+	}
+	if secs < 0.02 { // too short a window to divide by; the guard is against dividing by zero,
+		// not a judgement about how long a good measurement takes
+		return 0, moved.Load(), "", fmt.Errorf("the %s phase was over before it could be measured", dir)
+	}
+	note := ""
+	if firstErr != nil {
+		note = fmt.Sprintf("the %s phase was cut short: %s", dir, firstErr)
+	}
+	return mbps(total, secs), moved.Load(), note, nil
+}
+
+// join puts two notes together without leaving an empty one dangling.
+func join(a, b string) string {
+	switch {
+	case a == "":
+		return b
+	case b == "":
+		return a
+	}
+	return a + "; " + b
+}
+
+// stream fetches one chunk from src, counting bytes as they arrive.
+func stream(ctx context.Context, client *http.Client, src Source, n *atomic.Int64) error {
+	req, err := http.NewRequestWithContext(ctx, "GET", src.URL(downChunk), nil)
+	if err != nil {
+		return err
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != 200 {
+		return answered(resp.StatusCode, resp.Status)
+	}
+	buf := make([]byte, 64<<10)
+	for {
+		got, err := resp.Body.Read(buf)
+		if got > 0 {
+			n.Add(int64(got))
+		}
+		if err != nil {
+			if err == io.EOF {
+				return nil
+			}
+			return err
+		}
+	}
+}
+
+// upstream posts one chunk of nothing in particular, counting bytes as they go out.
+func upstream(ctx context.Context, client *http.Client, n *atomic.Int64) error {
+	body := &zeros{left: upChunk, n: n}
+	req, err := http.NewRequestWithContext(ctx, "POST", upURL, body)
+	if err != nil {
+		return err
+	}
+	req.ContentLength = upChunk
+	req.Header.Set("Content-Type", "application/octet-stream")
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	_, _ = io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+	if resp.StatusCode != 200 && resp.StatusCode != 204 {
+		return answered(resp.StatusCode, resp.Status)
+	}
+	return nil
+}
+
+// answered turns the far end's refusal into something worth reading. It rate-limits by
+// volume: enough testing in a short while and it stops serving the big transfers, which is
+// the only failure of this test anyone here is likely to meet.
+func answered(code int, status string) error {
+	if code == 429 || code == 403 {
+		return errRefused
+	}
+	return fmt.Errorf("the speed endpoint answered %s", status)
+}
+
+// errRefused is the far end rate-limiting this connection, which is the only failure of this
+// test anyone here is likely to meet: it limits by volume, and a test moves a few hundred
+// megabytes. It is recognisable so the download phase can try its other source.
+var errRefused = errors.New("the speed endpoint is rate-limiting this connection — it does that after a lot of testing; leave it a few minutes")
+
+func refused(err error) bool { return errors.Is(err, errRefused) }
+
+// zeros is a request body of a fixed size that costs nothing to produce, counting itself as
+// it is read out onto the wire.
+type zeros struct {
+	left int
+	n    *atomic.Int64
+}
+
+func (z *zeros) Read(p []byte) (int, error) {
+	if z.left <= 0 {
+		return 0, io.EOF
+	}
+	if len(p) > z.left {
+		p = p[:z.left]
+	}
+	for i := range p {
+		p[i] = 0
+	}
+	z.left -= len(p)
+	z.n.Add(int64(len(p)))
+	return len(p), nil
+}
+
+func newTransport(streams int) *http.Transport {
+	return &http.Transport{
+		Proxy:               http.ProxyFromEnvironment,
+		DialContext:         (&net.Dialer{Timeout: 10 * time.Second}).DialContext,
+		TLSHandshakeTimeout: 10 * time.Second,
+		MaxIdleConns:        streams * 2,
+		MaxIdleConnsPerHost: streams * 2,
+		// An empty map turns HTTP/2 off: see the note at the top of this file.
+		TLSNextProto: map[string]func(string, *tls.Conn) http.RoundTripper{},
+	}
+}
+
+// probeOutside asks the far end who it thinks we are. One small request.
+func probeOutside() Outside {
+	tr := newTransport(1)
+	defer tr.CloseIdleConnections()
+	client := &http.Client{Transport: tr, Timeout: 15 * time.Second}
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, "GET", traceURL, nil)
+	if err != nil {
+		return Outside{At: time.Now(), Error: err.Error()}
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return Outside{At: time.Now(), Error: shortErr(err)}
+	}
+	defer resp.Body.Close()
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 4<<10))
+	if resp.StatusCode != 200 {
+		return Outside{At: time.Now(), Error: "the trace endpoint answered " + resp.Status}
+	}
+	o := Outside{At: time.Now()}
+	for _, line := range strings.Split(string(body), "\n") {
+		k, v, ok := strings.Cut(line, "=")
+		if !ok {
+			continue
+		}
+		switch k {
+		case "ip":
+			o.IP = v
+		case "colo":
+			o.Colo = v
+		case "loc":
+			o.Country = v
+		}
+	}
+	if o.IP == "" {
+		o.Error = "the trace endpoint said nothing about this connection"
+	}
+	return o
+}
+
+// shortErr keeps the part of a network error a person can act on.
+func shortErr(err error) string {
+	s := err.Error()
+	if i := strings.LastIndex(s, ": "); i > 0 && len(s)-i < 60 {
+		return s[i+2:]
+	}
+	return s
+}
+
+func mbps(bytes int64, secs float64) float64 {
+	return round(float64(bytes)*8/secs/1e6, 1)
+}
+
+func best(v []float64) float64 {
+	m := v[0]
+	for _, x := range v {
+		if x < m {
+			m = x
+		}
+	}
+	return round(m, 1)
+}
+
+// jitter is how much the line wobbles: the average change from one round trip to the next,
+// which is the usual definition and, unlike a standard deviation, is not run away with by a
+// single slow probe.
+func jitter(v []float64) float64 {
+	if len(v) < 2 {
+		return 0
+	}
+	var sum float64
+	for i := 1; i < len(v); i++ {
+		sum += math.Abs(v[i] - v[i-1])
+	}
+	return round(sum/float64(len(v)-1), 1)
+}
+
+func round(v float64, places int) float64 {
+	p := math.Pow(10, float64(places))
+	return math.Round(v*p) / p
+}
+
+// Mbits renders a rate the way the line is sold, for a log line.
+func Mbits(v float64) string { return strconv.FormatFloat(v, 'f', 1, 64) + " Mbps" }

internal/nodes/nodes.go

@@ -404,6 +404,12 @@ func (m *Manager) Do(ctx context.Context, name, method, path string, body []byte
 	return resp.StatusCode, b, err
 }
 
+// URL is a managed machine's address, "" for one not managed here.
+func (m *Manager) URL(name string) string {
+	n, _ := m.node(name)
+	return n.URL
+}
+
 // Names lists the managed machines.
 func (m *Manager) Names() []string {
 	var out []string

internal/setup/hamlab.procd

@@ -0,0 +1,25 @@
+#!/bin/sh /etc/rc.common
+# Ham Lab web console (written by hamlab install)
+
+USE_PROCD=1
+# after network and firewall, before the tail of the boot
+START=95
+STOP=10
+
+start_service() {
+	procd_open_instance hamlab
+	procd_set_param command "@BIN@" serve
+	procd_set_param env HAMLAB_CONFIG="@CONFIG@" HOME="@HOME@" USER="@USER@"
+	procd_set_param user "@USER@"
+	procd_set_param group "@GROUP@"
+	procd_set_param pidfile /var/run/hamlab.pid
+	# respawn: settle 3s, 5 retries inside that window, then give up counting
+	procd_set_param respawn 3600 3 0
+	procd_set_param stdout 1
+	procd_set_param stderr 1
+	procd_close_instance
+}
+
+service_triggers() {
+	procd_add_reload_trigger network
+}

internal/setup/setup.go

@@ -37,9 +37,14 @@ var systemdUnit string
 //go:embed hamlab.openrc
 var openrcScript string
 
+//go:embed hamlab.procd
+var procdScript string
+
 const (
 	unitPath   = "/etc/systemd/system/hamlab.service"
 	openrcPath = "/etc/init.d/hamlab"
+	// procd (OpenWrt) uses the same path as OpenRC; the two are told apart by content.
+	procdPath   = "/etc/init.d/hamlab"
 	sudoersPath = "/etc/sudoers.d/hamlab-quiet"
 )
 
@@ -228,6 +233,19 @@ func Install(args []string, version string) error {
 				return err
 			}
 		}
+	case exists("/sbin/procd") && exists("/etc/rc.common"):
+		initSys = "procd"
+		if err := os.WriteFile(procdPath, []byte(fill(procdScript, vars)), 0o755); err != nil {
+			return err
+		}
+		if err := run(procdPath, "enable"); err != nil {
+			say("warning: %s enable: %v", procdPath, err)
+		}
+		if !o.noStart {
+			if err := run(procdPath, "restart"); err != nil {
+				return err
+			}
+		}
 	case exists("/sbin/openrc-run") || exists("/usr/sbin/openrc-run") || have("rc-service"):
 		initSys = "OpenRC"
 		if err := os.WriteFile(openrcPath, []byte(fill(openrcScript, vars)), 0o755); err != nil {
@@ -258,7 +276,7 @@ func Install(args []string, version string) error {
 	url := scheme + "://" + browseAddr(cfg.Listen)
 	switch {
 	case initSys == "":
-		say("\nNo systemd or OpenRC here, so nothing starts it at boot.\nRun it under your own supervisor, as %s:\n  HAMLAB_CONFIG=%s %s serve", acct.name, cfgPath, dest)
+		say("\nNo systemd, procd or OpenRC here, so nothing starts it at boot.\nRun it under your own supervisor, as %s:\n  HAMLAB_CONFIG=%s %s serve", acct.name, cfgPath, dest)
 	case o.noStart:
 	case healthy(cfg.Listen, cfg.TLS == "auto"):
 		say("\nHam Lab is up: %s", url)
@@ -294,9 +312,15 @@ func Uninstall(args []string) error {
 		_ = run("systemctl", "daemon-reload")
 	}
 	if b, err := os.ReadFile(openrcPath); err == nil {
+		if strings.Contains(string(b), "USE_PROCD=1") {
+			dataDir = configDirFrom(string(b), "HAMLAB_CONFIG=")
+			_ = run(procdPath, "stop")
+			_ = run(procdPath, "disable")
+		} else {
 			dataDir = configDirFrom(string(b), "export HAMLAB_CONFIG=")
 			_ = run("rc-service", "hamlab", "stop")
 			_ = run("rc-update", "del", "hamlab", "default")
+		}
 		os.Remove(openrcPath)
 	}
 	os.Remove(sudoersPath)

internal/space/walk.go

@@ -1,4 +1,6 @@
-// Package space measures what is using a disk: a parallel walk of the filesystems a disk
+// Package space measures what is using a disk — it is what the UI calls the **Usage** tab
+// (renamed from "Space" on 2026-09-24; the package and its /api/space endpoints kept the
+// old name rather than churn a working API): a parallel walk of the filesystems a disk
 // backs, kept as a tree of directories and the files worth seeing, the way WizTree does it.
 //
 // The walk never crosses a filesystem boundary by itself — /proc, /sys, another disk's

internal/storage/arc.go

@@ -0,0 +1,292 @@
+package storage
+
+// The ZFS caching tiers, for the ZFS tab: what the ARC has done since boot and how it is
+// tuned, and for each pool which cache devices it has — L2ARC, a separate log (SLOG), a
+// special allocation class, a dedup table — or, as is common, none of them, which the tab
+// should say plainly rather than leave a blank.
+//
+// The live numbers (size, the hit rate over the last interval) come from the sampler in
+// internal/metrics, which also publishes them as zfs.arc.* sensors; this is the slower,
+// fuller picture, read when the tab asks.
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// CacheDev is one member of a pool's cache, log, special, dedup or spare class.
+type CacheDev struct {
+	Name   string `json:"name"`
+	Size   uint64 `json:"size,omitempty"`
+	Alloc  uint64 `json:"alloc,omitempty"`
+	Health string `json:"health,omitempty"`
+}
+
+// PoolCaching is what one pool has beyond its data vdevs, and the properties that steer
+// what is cached.
+type PoolCaching struct {
+	Pool    string     `json:"pool"`
+	Cache   []CacheDev `json:"cache"`   // L2ARC
+	Log     []CacheDev `json:"log"`     // SLOG
+	Special []CacheDev `json:"special"` // metadata / small blocks
+	Dedup   []CacheDev `json:"dedup"`   // dedup table vdevs
+	Spare   []CacheDev `json:"spare"`
+	// dataset properties at the pool root
+	PrimaryCache   string `json:"primarycache"`
+	SecondaryCache string `json:"secondarycache"`
+	Sync           string `json:"sync"`
+	LogBias        string `json:"logbias"`
+	DedupProp      string `json:"dedup_prop"`
+	Compression    string `json:"compression"`
+	RecordSize     string `json:"recordsize"`
+	DedupRatio     string `json:"dedup_ratio"` // zpool's, e.g. "1.00x"
+}
+
+// ARCDetail is the full picture.
+type ARCDetail struct {
+	Available bool              `json:"available"`
+	MemTotal  uint64            `json:"mem_total"`
+	Tunables  map[string]string `json:"tunables"` // zfs module parameters that shape the cache; "" when unset
+	Lifetime  struct {
+		Hits, Misses                                   uint64 `json:",omitempty"`
+		DemandDataHits, DemandDataMisses               uint64
+		DemandMetaHits, DemandMetaMisses               uint64
+		PrefetchDataHits, PrefetchDataMisses           uint64
+		PrefetchMetaHits, PrefetchMetaMisses           uint64
+		L2Hits, L2Misses, L2ReadBytes, L2WriteBytes    uint64
+		L2Feeds, L2RebuildSize                         uint64
+		EvictL2Eligible                                uint64 // bytes evicted from RAM that an L2ARC could have caught
+		Deleted, EvictSkip, MutexMiss, Prune, Throttle uint64
+	} `json:"lifetime"`
+	Zfetch struct{ Hits, Misses, IOIssued uint64 } `json:"zfetch"` // the prefetcher
+	ZIL    struct {
+		Commits                  uint64 `json:"commits"`
+		NormalBytes, NormalWrite uint64 // written to the pool's own vdevs
+		SlogBytes, SlogWrite     uint64 // written to a separate log device
+	} `json:"zil"`
+	DBuf  struct{ Size, Target, Hits, Misses uint64 } `json:"dbuf"` // the dbuf cache in front of the ARC
+	Pools []PoolCaching                               `json:"pools"`
+}
+
+const kstatDir = "/proc/spl/kstat/zfs/"
+
+func readKstat(p string) map[string]uint64 {
+	b, err := os.ReadFile(p)
+	if err != nil {
+		return nil
+	}
+	out := map[string]uint64{}
+	for _, line := range strings.Split(string(b), "\n") {
+		f := strings.Fields(line)
+		if len(f) != 3 || f[1] != "4" {
+			continue
+		}
+		if v, err := strconv.ParseUint(f[2], 10, 64); err == nil {
+			out[f[0]] = v
+		}
+	}
+	return out
+}
+
+var arcTunables = []string{"zfs_arc_max", "zfs_arc_min", "zfs_arc_sys_free", "zfs_arc_meta_balance", "zfs_prefetch_disable", "l2arc_write_max", "l2arc_write_boost", "l2arc_noprefetch", "l2arc_rebuild_enabled", "zfs_dirty_data_max"}
+
+const poolCachingEvery = 30 * time.Second // zpool list -v and zfs get are an exec each
+
+// ARC reads the kstats now and the pool layout from a short cache.
+func (m *Manager) ARC(ctx context.Context) ARCDetail {
+	d := ARCDetail{Tunables: map[string]string{}, Pools: []PoolCaching{}}
+	k := readKstat(kstatDir + "arcstats")
+	if k == nil {
+		return d
+	}
+	d.Available = true
+	l := &d.Lifetime
+	l.Hits, l.Misses = k["hits"], k["misses"]
+	l.DemandDataHits, l.DemandDataMisses = k["demand_data_hits"], k["demand_data_misses"]
+	l.DemandMetaHits, l.DemandMetaMisses = k["demand_metadata_hits"], k["demand_metadata_misses"]
+	l.PrefetchDataHits, l.PrefetchDataMisses = k["prefetch_data_hits"], k["prefetch_data_misses"]
+	l.PrefetchMetaHits, l.PrefetchMetaMisses = k["prefetch_metadata_hits"], k["prefetch_metadata_misses"]
+	l.L2Hits, l.L2Misses, l.L2ReadBytes, l.L2WriteBytes = k["l2_hits"], k["l2_misses"], k["l2_read_bytes"], k["l2_write_bytes"]
+	l.L2Feeds, l.L2RebuildSize, l.EvictL2Eligible = k["l2_feeds"], k["l2_rebuild_size"], k["evict_l2_eligible"]
+	l.Deleted, l.EvictSkip, l.MutexMiss, l.Prune, l.Throttle = k["deleted"], k["evict_skip"], k["mutex_miss"], k["arc_prune"], k["memory_throttle_count"]
+	if z := readKstat(kstatDir + "zfetchstats"); z != nil {
+		d.Zfetch.Hits, d.Zfetch.Misses, d.Zfetch.IOIssued = z["hits"], z["misses"], z["io_issued"]
+	}
+	if z := readKstat(kstatDir + "zil"); z != nil {
+		d.ZIL.Commits = z["zil_commit_count"]
+		d.ZIL.NormalBytes, d.ZIL.NormalWrite = z["zil_itx_metaslab_normal_bytes"], z["zil_itx_metaslab_normal_write"]
+		d.ZIL.SlogBytes, d.ZIL.SlogWrite = z["zil_itx_metaslab_slog_bytes"], z["zil_itx_metaslab_slog_write"]
+	}
+	if z := readKstat(kstatDir + "dbufstats"); z != nil {
+		d.DBuf.Size, d.DBuf.Target, d.DBuf.Hits, d.DBuf.Misses = z["cache_size_bytes"], z["cache_target_bytes"], z["hash_hits"], z["hash_misses"]
+	}
+	for _, t := range arcTunables {
+		if b, err := os.ReadFile("/sys/module/zfs/parameters/" + t); err == nil {
+			d.Tunables[t] = strings.TrimSpace(string(b))
+		}
+	}
+	if b, err := os.ReadFile("/proc/meminfo"); err == nil {
+		for _, line := range strings.Split(string(b), "\n") {
+			if strings.HasPrefix(line, "MemTotal:") {
+				f := strings.Fields(line)
+				if len(f) >= 2 {
+					d.MemTotal = u64(f[1]) << 10
+				}
+				break
+			}
+		}
+	}
+	d.Pools = m.poolCaching(ctx)
+	return d
+}
+
+var cachingMu sync.Mutex
+var cachingAt time.Time
+var cachingLast []PoolCaching
+
+func (m *Manager) poolCaching(ctx context.Context) []PoolCaching {
+	cachingMu.Lock()
+	defer cachingMu.Unlock()
+	if cachingLast != nil && time.Since(cachingAt) < poolCachingEvery {
+		return cachingLast
+	}
+	out := []PoolCaching{}
+	bin, ok := lookPath("zpool")
+	if !ok {
+		return out
+	}
+	// zpool list -v needs no root; the vdev tree under each pool, with the class headers
+	raw, code, err := m.runPlain(ctx, bin, "list", "-Hpv", "-o", "name,size,alloc,free,health")
+	if err != nil || code != 0 {
+		return out
+	}
+	out = parsePoolCaching(string(raw))
+	if zfs, ok := lookPath("zfs"); ok {
+		for i := range out {
+			p := &out[i]
+			if props, code, err := m.runPlain(ctx, zfs, "get", "-Hp", "-o", "property,value", "primarycache,secondarycache,sync,logbias,dedup,compression,recordsize", p.Pool); err == nil && code == 0 {
+				for _, line := range strings.Split(strings.TrimSpace(string(props)), "\n") {
+					f := strings.Split(line, "\t")
+					if len(f) < 2 {
+						continue
+					}
+					switch f[0] {
+					case "primarycache":
+						p.PrimaryCache = f[1]
+					case "secondarycache":
+						p.SecondaryCache = f[1]
+					case "sync":
+						p.Sync = f[1]
+					case "logbias":
+						p.LogBias = f[1]
+					case "dedup":
+						p.DedupProp = f[1]
+					case "compression":
+						p.Compression = f[1]
+					case "recordsize":
+						p.RecordSize = humanSize(u64(f[1]))
+					}
+				}
+			}
+		}
+	}
+	for _, pool := range parsePools(func() []byte {
+		b, _, _ := m.runPlain(ctx, bin, "list", "-Hp", "-o", "name,size,alloc,free,frag,cap,health,dedup")
+		return b
+	}()) {
+		for i := range out {
+			if out[i].Pool == pool.Name {
+				out[i].DedupRatio = pool.Dedup
+			}
+		}
+	}
+	cachingLast, cachingAt = out, time.Now()
+	return out
+}
+
+// runPlain runs a command as ourselves, never through sudo: these are read-only zpool/zfs
+// queries that need no root on Linux, and a poll must not write to the auth log.
+func (m *Manager) runPlain(ctx context.Context, bin string, args ...string) ([]byte, int, error) {
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+	out, err := exec.CommandContext(ctx, bin, args...).Output()
+	if ee, ok := err.(*exec.ExitError); ok {
+		return out, ee.ExitCode(), nil
+	}
+	return out, 0, err
+}
+
+var cacheClasses = map[string]bool{"logs": true, "log": true, "cache": true, "special": true, "dedup": true, "spares": true, "spare": true}
+
+// parsePoolCaching reads `zpool list -Hpv -o name,size,alloc,free,health`: a pool line, then
+// its vdevs indented, with a bare class name ("logs", "cache", "special", "dedup", "spares")
+// introducing each extra class. Only those classes' members are kept; the data vdevs are the
+// pool and are shown elsewhere.
+func parsePoolCaching(text string) []PoolCaching {
+	var out []PoolCaching
+	var cur *PoolCaching
+	class := ""
+	for _, raw := range strings.Split(text, "\n") {
+		if strings.TrimSpace(raw) == "" {
+			continue
+		}
+		indented := strings.HasPrefix(raw, " ") || strings.HasPrefix(raw, "\t")
+		f := strings.Split(strings.TrimSpace(raw), "\t")
+		name := strings.TrimSpace(f[0])
+		if !indented {
+			out = append(out, PoolCaching{Pool: name, Cache: []CacheDev{}, Log: []CacheDev{}, Special: []CacheDev{}, Dedup: []CacheDev{}, Spare: []CacheDev{}})
+			cur, class = &out[len(out)-1], ""
+			continue
+		}
+		if cur == nil {
+			continue
+		}
+		if cacheClasses[name] && (len(f) < 2 || f[1] == "-" || f[1] == "") {
+			class = name
+			continue
+		}
+		if class == "" {
+			continue // a data vdev or one of its disks
+		}
+		// a mirror or raidz inside a class lists its members below it; keep them all, the
+		// grouping is visible in the vdev tree on the pool card
+		dev := CacheDev{Name: name}
+		if len(f) >= 5 {
+			dev.Size, dev.Alloc, dev.Health = u64(f[1]), u64(f[2]), strings.TrimSpace(f[4])
+			if f[1] == "-" {
+				dev.Size = 0
+			}
+		}
+		switch class {
+		case "logs", "log":
+			cur.Log = append(cur.Log, dev)
+		case "cache":
+			cur.Cache = append(cur.Cache, dev)
+		case "special":
+			cur.Special = append(cur.Special, dev)
+		case "dedup":
+			cur.Dedup = append(cur.Dedup, dev)
+		case "spares", "spare":
+			cur.Spare = append(cur.Spare, dev)
+		}
+	}
+	if out == nil {
+		out = []PoolCaching{}
+	}
+	return out
+}
+
+func humanSize(b uint64) string {
+	switch {
+	case b >= 1<<20 && b%(1<<20) == 0:
+		return strconv.FormatUint(b>>20, 10) + "M"
+	case b >= 1<<10 && b%(1<<10) == 0:
+		return strconv.FormatUint(b>>10, 10) + "K"
+	}
+	return strconv.FormatUint(b, 10)
+}

internal/storage/arc_test.go

@@ -0,0 +1,71 @@
+package storage
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"testing"
+)
+
+// zpool list -Hpv on a pool with every extra class; the data raidz and its disks are skipped
+const listV = "tank\t32000000000000\t23000000000000\t9000000000000\tONLINE\n" +
+	"\traidz2-0\t32000000000000\t23000000000000\t9000000000000\tONLINE\n" +
+	"\t\twwn-0x1\t4000000000000\t-\t-\tONLINE\n" +
+	"\t\twwn-0x2\t4000000000000\t-\t-\tONLINE\n" +
+	"\tspecial\t-\t-\t-\t-\n" +
+	"\t\tmirror-1\t500000000000\t120000000000\t380000000000\tONLINE\n" +
+	"\t\t\tnvme0n1p1\t500000000000\t-\t-\tONLINE\n" +
+	"\t\t\tnvme1n1p1\t500000000000\t-\t-\tONLINE\n" +
+	"\tlogs\t-\t-\t-\t-\n" +
+	"\t\tnvme2n1p1\t16000000000\t4000000\t15996000000\tONLINE\n" +
+	"\tcache\t-\t-\t-\t-\n" +
+	"\t\tnvme2n1p2\t400000000000\t210000000000\t190000000000\tONLINE\n" +
+	"\tspares\t-\t-\t-\t-\n" +
+	"\t\twwn-0x9\t4000000000000\t-\t-\tAVAIL\n" +
+	"scratch\t1000000000000\t1000000000\t999000000000\tONLINE\n" +
+	"\tsda\t1000000000000\t1000000000\t999000000000\tONLINE\n"
+
+func TestParsePoolCaching(t *testing.T) {
+	got := parsePoolCaching(listV)
+	if len(got) != 2 || got[0].Pool != "tank" || got[1].Pool != "scratch" {
+		t.Fatalf("pools: %+v", got)
+	}
+	tank := got[0]
+	if len(tank.Cache) != 1 || tank.Cache[0].Name != "nvme2n1p2" || tank.Cache[0].Alloc != 210000000000 {
+		t.Errorf("cache: %+v", tank.Cache)
+	}
+	if len(tank.Log) != 1 || tank.Log[0].Name != "nvme2n1p1" {
+		t.Errorf("log: %+v", tank.Log)
+	}
+	if len(tank.Special) != 3 || tank.Special[0].Name != "mirror-1" || tank.Special[0].Alloc != 120000000000 {
+		t.Errorf("special: %+v", tank.Special)
+	}
+	if len(tank.Spare) != 1 || tank.Spare[0].Health != "AVAIL" {
+		t.Errorf("spares: %+v", tank.Spare)
+	}
+	if len(tank.Dedup) != 0 {
+		t.Errorf("no dedup class: %+v", tank.Dedup)
+	}
+	s := got[1]
+	if len(s.Cache)+len(s.Log)+len(s.Special)+len(s.Spare) != 0 {
+		t.Errorf("a plain pool has no extra classes: %+v", s)
+	}
+}
+
+func TestHumanSize(t *testing.T) {
+	for in, want := range map[uint64]string{131072: "128K", 1048576: "1M", 16384: "16K", 1000: "1000"} {
+		if got := humanSize(in); got != want {
+			t.Errorf("%d → %s, want %s", in, got, want)
+		}
+	}
+}
+
+// TestLiveARC reads this machine's ZFS for real: HAMLAB_LIVE=1 go test -run TestLiveARC -v ./internal/storage
+func TestLiveARC(t *testing.T) {
+	if os.Getenv("HAMLAB_LIVE") == "" {
+		t.Skip("set HAMLAB_LIVE=1 to read the real machine")
+	}
+	d := New(false).ARC(context.Background())
+	b, _ := json.MarshalIndent(d, "", "  ")
+	t.Logf("%s", b)
+}

internal/storage/snapshots.go

@@ -0,0 +1,492 @@
+package storage
+
+// Scheduled snapshots with a retention period: take a snapshot of a dataset on a schedule,
+// and drop the ones that have aged out.
+//
+// **The naming is zfSnap's, deliberately.** grid has run zfSnap v1.11.1 from root cron since
+// before this repo existed and it works well, so rather than invent a second convention and
+// have two tools disagree about what a snapshot is, this writes and reads exactly what
+// zfSnap does: `<dataset>@2026-09-24_02.30.01--6w`, with the retention encoded in the name.
+// That has three consequences worth knowing. Ham Lab can show and manage the snapshots
+// zfSnap already took. The two can run side by side without fighting, because both only
+// ever destroy snapshots that have passed the expiry written into their own name. And
+// changing a policy's retention does not retroactively re-date old snapshots — each one
+// carries the rule it was taken under, which is the behaviour you want from a backup.
+//
+// Two rules make this safe to run unattended. Only a snapshot whose name parses as a stamp
+// and a TTL is ever a candidate — anything taken by hand or named anything else is invisible
+// to it. And every policy can be asked what it would delete, before it deletes anything.
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"hamlab/internal/cron"
+	"hamlab/internal/priv"
+)
+
+// stampLayout is zfSnap's timestamp: 2026-09-24_02.30.01.
+const stampLayout = "2006-01-02_15.04.05"
+
+// ttlSep separates the stamp from the retention in a snapshot name, as zfSnap writes it.
+const ttlSep = "--"
+
+// Policy is a standing instruction: snapshot this dataset on this schedule, keep the
+// snapshots this long.
+type Policy struct {
+	ID      string `json:"id"`
+	Name    string `json:"name"`
+	Dataset string `json:"dataset"`
+	// Recursive takes one atomic snapshot of the dataset and everything under it (zfs -r).
+	Recursive bool `json:"recursive"`
+	// Every is hourly | daily | weekly | monthly | custom. At is "HH:MM" (the minute alone
+	// is used for hourly). Weekday is 0=Sunday, Day is 1–28. With "custom", Cron is a plain
+	// cron expression and the rest is ignored — the escape hatch for anything the four
+	// common shapes cannot say.
+	Every   string `json:"every"`
+	At      string `json:"at"`
+	Weekday int    `json:"weekday"`
+	Day     int    `json:"day"`
+	Cron    string `json:"cron,omitempty"`
+	// KeepFor is how long a snapshot lives: "6w", "30d", "12h". It is written into the
+	// snapshot's own name, zfSnap-style, so each one carries the rule it was taken under.
+	// KeepMin is a floor — that many newest snapshots survive however old they are, so a
+	// dataset is never left with none.
+	KeepFor string `json:"keep_for"`
+	KeepMin int    `json:"keep_min"`
+	Prefix  string `json:"prefix"`
+	Enabled bool   `json:"enabled"`
+}
+
+func (p *Policy) prefix() string { return strings.TrimSpace(p.Prefix) }
+
+// Validate reports what is wrong with a policy, or nil.
+func (p *Policy) Validate() error {
+	if !datasetRe.MatchString(p.Dataset) {
+		return errors.New("dataset: a pool or pool/dataset name")
+	}
+	if pre := p.prefix(); pre != "" && (!snapRe.MatchString(pre) || strings.Contains(pre, ttlSep)) {
+		return errors.New("prefix: letters, digits, . _ : and - only, and no --")
+	}
+	switch p.Every {
+	case "hourly", "daily", "weekly", "monthly":
+	case "custom":
+		if strings.TrimSpace(p.Cron) == "" {
+			return errors.New("a custom schedule needs a cron expression")
+		}
+	default:
+		return errors.New("every: hourly, daily, weekly, monthly or custom")
+	}
+	if _, err := p.CronExpr(); err != nil {
+		return err
+	}
+	if _, _, err := p.clock(); err != nil {
+		return err
+	}
+	if p.Every == "weekly" && (p.Weekday < 0 || p.Weekday > 6) {
+		return errors.New("weekday: 0 (Sunday) to 6")
+	}
+	if p.Every == "monthly" && (p.Day < 1 || p.Day > 28) {
+		return errors.New("day: 1 to 28, so every month has one")
+	}
+	if p.KeepFor != "" {
+		if _, err := ParseAge(p.KeepFor); err != nil {
+			return err
+		}
+	}
+	if p.KeepMin < 0 {
+		return errors.New("keep at least: 0 or more")
+	}
+	if p.KeepFor == "" {
+		return errors.New("a retention period is required — it is written into each snapshot's name, and is what lets it be cleaned up later")
+	}
+	return nil
+}
+
+func (p *Policy) clock() (hour, min int, err error) {
+	at := strings.TrimSpace(p.At)
+	if at == "" {
+		return 0, 0, nil
+	}
+	h, m, ok := strings.Cut(at, ":")
+	if !ok {
+		return 0, 0, errors.New("at: HH:MM")
+	}
+	hour, err = strconv.Atoi(h)
+	if err == nil {
+		min, err = strconv.Atoi(m)
+	}
+	if err != nil || hour < 0 || hour > 23 || min < 0 || min > 59 {
+		return 0, 0, errors.New("at: HH:MM, 00:00 to 23:59")
+	}
+	return hour, min, nil
+}
+
+// ParseAge reads "6w", "30d", "12h", "90m" as a duration. Weeks and days are what a
+// retention period is actually written in, and time.ParseDuration knows neither.
+func ParseAge(s string) (time.Duration, error) {
+	s = strings.TrimSpace(strings.ToLower(s))
+	if s == "" {
+		return 0, errors.New("empty period")
+	}
+	unit := s[len(s)-1]
+	n, err := strconv.Atoi(s[:len(s)-1])
+	if err != nil || n <= 0 {
+		return 0, fmt.Errorf("%q: a number and a unit, like 6w, 30d or 12h", s)
+	}
+	switch unit {
+	case 'm':
+		return time.Duration(n) * time.Minute, nil
+	case 'h':
+		return time.Duration(n) * time.Hour, nil
+	case 'd':
+		return time.Duration(n) * 24 * time.Hour, nil
+	case 'w':
+		return time.Duration(n) * 7 * 24 * time.Hour, nil
+	}
+	return 0, fmt.Errorf("%q: the unit is m, h, d or w", s)
+}
+
+// CronExpr renders the schedule as a cron expression — which is what actually runs it. The
+// four common shapes are sugar over this; a custom policy states it outright. One expression
+// is the only description of when a schedule fires, so the page, the cron file and the next
+// run can never disagree.
+func (p *Policy) CronExpr() (string, error) {
+	if p.Every == "custom" {
+		expr := strings.Join(strings.Fields(p.Cron), " ")
+		if err := cron.ValidSchedule(expr); err != nil {
+			return "", fmt.Errorf("cron expression: %w", err)
+		}
+		if strings.HasPrefix(expr, "@reboot") {
+			return "", errors.New("@reboot is not a schedule for snapshots")
+		}
+		return expr, nil
+	}
+	hour, min, err := p.clock()
+	if err != nil {
+		return "", err
+	}
+	switch p.Every {
+	case "hourly":
+		return fmt.Sprintf("%d * * * *", min), nil
+	case "daily":
+		return fmt.Sprintf("%d %d * * *", min, hour), nil
+	case "weekly":
+		return fmt.Sprintf("%d %d * * %d", min, hour, p.Weekday), nil
+	case "monthly":
+		return fmt.Sprintf("%d %d %d * *", min, hour, p.Day), nil
+	}
+	return "", errors.New("unknown schedule")
+}
+
+// NextRun is when cron will next fire this schedule, read with the same evaluator the Jobs
+// tab uses on everyone else's lines.
+func (p *Policy) NextRun(now time.Time) time.Time {
+	expr, err := p.CronExpr()
+	if err != nil {
+		return time.Time{}
+	}
+	t, ok := cron.NextRun(expr, now)
+	if !ok {
+		return time.Time{}
+	}
+	return t
+}
+
+// SnapTime reads a snapshot's name in zfSnap's convention and returns when it was taken,
+// when it expires, and whether the name parsed at all. A name without a TTL never expires.
+// An optional prefix in front of the stamp is allowed, so a policy can label its own.
+func SnapTime(name string) (taken time.Time, expires time.Time, ok bool) {
+	_, snap, cut := strings.Cut(name, "@")
+	if !cut {
+		return
+	}
+	body, ttl, hasTTL := strings.Cut(snap, ttlSep)
+	// an optional "<prefix>-" before the stamp
+	stamp := body
+	if len(body) > len(stampLayout) {
+		stamp = body[len(body)-len(stampLayout):]
+	}
+	t, err := time.ParseInLocation(stampLayout, stamp, time.Local)
+	if err != nil {
+		return time.Time{}, time.Time{}, false
+	}
+	taken, ok = t, true
+	if hasTTL {
+		if d, err := ParseAge(ttl); err == nil {
+			expires = t.Add(d)
+		}
+	}
+	return
+}
+
+// Doomed is which of this dataset's snapshots have passed the expiry written into their own
+// names, oldest first — exactly what zfSnap -d would remove. This is what the UI shows
+// before anything is deleted, and what Run then acts on. KeepMin holds back that many of the
+// newest whatever their names say, so a dataset is never left with none.
+func (m *Manager) Doomed(ctx context.Context, p *Policy) ([]Snapshot, error) {
+	if err := p.Validate(); err != nil {
+		return nil, err
+	}
+	all, err := m.Snapshots(ctx, p.Dataset)
+	if err != nil {
+		return nil, err
+	}
+	var dated []Snapshot
+	expiry := map[string]time.Time{}
+	for _, s := range all {
+		taken, exp, ok := SnapTime(s.Name)
+		if !ok || exp.IsZero() {
+			continue // hand-made, or kept forever: not ours to remove
+		}
+		_ = taken
+		dated = append(dated, s)
+		expiry[s.Name] = exp
+	}
+	sort.Slice(dated, func(i, j int) bool { return dated[i].Created > dated[j].Created }) // newest first
+	now := time.Now()
+	var doomed []Snapshot
+	for i, s := range dated {
+		if i < p.KeepMin {
+			continue // the floor: these survive however old they are
+		}
+		if expiry[s.Name].Before(now) {
+			doomed = append(doomed, s)
+		}
+	}
+	sort.Slice(doomed, func(i, j int) bool { return doomed[i].Created < doomed[j].Created }) // oldest first
+	return doomed, nil
+}
+
+// DestroySnapshot removes one snapshot. recursive also removes the same-named snapshot on
+// every dataset beneath it, which is what a recursive policy created.
+func (m *Manager) DestroySnapshot(ctx context.Context, full string, recursive bool) error {
+	dataset, snap, ok := strings.Cut(full, "@")
+	if !ok || !datasetRe.MatchString(dataset) || !snapRe.MatchString(snap) {
+		return errors.New("bad snapshot name")
+	}
+	args := []string{"zfs", "destroy"}
+	if recursive {
+		args = append(args, "-r")
+	}
+	out, code, err := m.run(ctx, append(args, full)...)
+	if err != nil {
+		return err
+	}
+	if code != 0 {
+		return errors.New(strings.TrimSpace(string(out)))
+	}
+	return nil
+}
+
+// SnapshotRecursive takes dataset@name, optionally of everything beneath it too.
+func (m *Manager) SnapshotRecursive(ctx context.Context, dataset, name string, recursive bool) error {
+	if !datasetRe.MatchString(dataset) || !snapRe.MatchString(name) {
+		return errors.New("bad snapshot name")
+	}
+	args := []string{"zfs", "snapshot"}
+	if recursive {
+		args = append(args, "-r")
+	}
+	out, code, err := m.run(ctx, append(args, dataset+"@"+name)...)
+	if err != nil {
+		return err
+	}
+	if code != 0 {
+		return errors.New(strings.TrimSpace(string(out)))
+	}
+	return nil
+}
+
+// RunResult is what one pass of a policy did.
+type RunResult struct {
+	Taken   string   `json:"taken"`
+	Pruned  []string `json:"pruned"`
+	Skipped int      `json:"skipped"` // snapshots that are not this policy's, left alone
+}
+
+// Run takes the snapshot and prunes what has aged out. It is the same code the scheduler
+// calls, so "Run now" and the timer cannot drift apart.
+func (m *Manager) Run(ctx context.Context, p *Policy) (RunResult, error) {
+	var res RunResult
+	if err := p.Validate(); err != nil {
+		return res, err
+	}
+	name := time.Now().Format(stampLayout)
+	if pre := strings.TrimSpace(p.Prefix); pre != "" {
+		name = pre + "-" + name
+	}
+	if p.KeepFor != "" {
+		name += ttlSep + strings.TrimSpace(strings.ToLower(p.KeepFor)) // zfSnap's convention: the retention lives in the name
+	}
+	if err := m.SnapshotRecursive(ctx, p.Dataset, name, p.Recursive); err != nil {
+		return res, err
+	}
+	res.Taken = p.Dataset + "@" + name
+	doomed, err := m.Doomed(ctx, p)
+	if err != nil {
+		return res, err // the snapshot was taken; the prune is what failed
+	}
+	for _, s := range doomed {
+		if err := m.DestroySnapshot(ctx, s.Name, p.Recursive); err != nil {
+			return res, fmt.Errorf("destroying %s: %w", s.Name, err)
+		}
+		res.Pruned = append(res.Pruned, s.Name)
+	}
+	return res, nil
+}
+
+// ---- what happened when it ran ----
+//
+// The policies are a definition the daemon owns; what a run did is written by whatever ran
+// it, which is a cron job in its own process. Keeping the two apart means the CLI never has
+// to write state.json behind the daemon's back — the last writer would win and one of them
+// would lose its work.
+
+// RunRecord is the outcome of one run of one schedule.
+type RunRecord struct {
+	At     time.Time `json:"at"`
+	Taken  string    `json:"taken,omitempty"`
+	Pruned []string  `json:"pruned,omitempty"`
+	Error  string    `json:"error,omitempty"`
+}
+
+func runPath(dir, id string) string { return filepath.Join(dir, "zfs-runs", id+".json") }
+
+// WriteRun records what a run did, beside the config.
+func WriteRun(dir, id string, r RunRecord) error {
+	if err := os.MkdirAll(filepath.Join(dir, "zfs-runs"), 0o700); err != nil {
+		return err
+	}
+	b, err := json.Marshal(r)
+	if err != nil {
+		return err
+	}
+	p := runPath(dir, id)
+	tmp := p + ".tmp"
+	if err := os.WriteFile(tmp, b, 0o600); err != nil {
+		return err
+	}
+	return os.Rename(tmp, p)
+}
+
+// ReadRun is the last thing a schedule did, or the zero value if it has never run.
+func ReadRun(dir, id string) RunRecord {
+	var r RunRecord
+	b, err := os.ReadFile(runPath(dir, id))
+	if err == nil {
+		_ = json.Unmarshal(b, &r)
+	}
+	return r
+}
+
+// ForgetRun drops a schedule's record, for when the schedule itself goes.
+func ForgetRun(dir, id string) { _ = os.Remove(runPath(dir, id)) }
+
+// ---- the cron file ----
+
+// CronFile is where Ham Lab writes the snapshot schedules. One file it owns entirely and
+// rewrites whole, so there is never a half-updated set of lines, and so a schedule removed
+// in the UI is removed from the machine.
+const CronFile = "/etc/cron.d/hamlab-zfs"
+
+// CronFileText renders every schedule as cron lines. user is who they run as — the account
+// Ham Lab itself runs as, which reaches zfs through sudo exactly as the daemon does, so the
+// files it writes stay owned by that account rather than by root.
+func CronFileText(policies []Policy, user, exe, config string) (string, error) {
+	var b strings.Builder
+	b.WriteString("# Ham Lab snapshot schedules — written by the ZFS tab, rewritten whole on every change.\n")
+	b.WriteString("# Edit them there, not here: anything added by hand is lost the next time a schedule changes.\n")
+	b.WriteString("SHELL=/bin/sh\n")
+	b.WriteString("PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\n\n")
+	for i := range policies {
+		p := &policies[i]
+		if !p.Enabled {
+			b.WriteString("# " + p.Name + " — paused\n")
+			continue
+		}
+		expr, err := p.CronExpr()
+		if err != nil {
+			return "", fmt.Errorf("%s: %w", p.Name, err)
+		}
+		name := strings.ReplaceAll(p.Name, "\n", " ")
+		fmt.Fprintf(&b, "# %s — %s, keep %s\n", name, p.Dataset, p.KeepFor)
+		fmt.Fprintf(&b, "%s %s %s -config %s zfs-snapshot %s\n\n", expr, user, exe, config, p.ID)
+	}
+	return b.String(), nil
+}
+
+// WriteCronFile puts the schedules on the machine, or removes the file when there are none.
+func (m *Manager) WriteCronFile(ctx context.Context, policies []Policy, user, exe, config string) error {
+	live := false
+	for i := range policies {
+		if policies[i].Enabled {
+			live = true
+		}
+	}
+	if !live {
+		out, code, err := m.run(ctx, "rm", "-f", CronFile)
+		if err != nil {
+			return err
+		}
+		if code != 0 {
+			return errors.New(strings.TrimSpace(string(out)))
+		}
+		return nil
+	}
+	text, err := CronFileText(policies, user, exe, config)
+	if err != nil {
+		return err
+	}
+	return m.writeRoot(ctx, CronFile, text)
+}
+
+// WriteRootFile puts text at a root-owned path, through the same privilege escalation every
+// other write here uses. Shared by the snapshot schedules and the image-update schedules,
+// which both own a file in /etc/cron.d.
+func (m *Manager) WriteRootFile(ctx context.Context, path, text string) error {
+	return m.writeRoot(ctx, path, text)
+}
+
+// RemoveRootFile deletes one, for when the last schedule of a kind goes away.
+func (m *Manager) RemoveRootFile(ctx context.Context, path string) error {
+	out, code, err := m.run(ctx, "rm", "-f", path)
+	if err != nil {
+		return err
+	}
+	if code != 0 {
+		return errors.New(strings.TrimSpace(string(out)))
+	}
+	return nil
+}
+
+func (m *Manager) writeRoot(ctx context.Context, path, text string) error {
+	args := []string{"tee", path}
+	if m.sudo {
+		args = priv.Wrap(args...)
+	}
+	ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, args[0], args[1:]...)
+	cmd.Stdin = strings.NewReader(text)
+	var errb bytes.Buffer
+	cmd.Stdout, cmd.Stderr = nil, &errb
+	if err := cmd.Run(); err != nil {
+		msg := strings.TrimSpace(errb.String())
+		if msg == "" {
+			msg = err.Error()
+		}
+		return errors.New(msg)
+	}
+	return nil
+}

internal/storage/snapshots_test.go

@@ -0,0 +1,135 @@
+package storage
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"hamlab/internal/cron"
+)
+
+func TestSnapTimeReadsZfSnapNames(t *testing.T) {
+	// the real thing off grid
+	taken, exp, ok := SnapTime("tank@2026-09-24_02.30.01--6w")
+	if !ok {
+		t.Fatal("zfSnap's own name must parse")
+	}
+	if taken.Format("2006-01-02 15:04:05") != "2026-09-24 02:30:01" {
+		t.Fatalf("taken = %v", taken)
+	}
+	if got := exp.Sub(taken); got != 6*7*24*time.Hour {
+		t.Fatalf("ttl = %v, want 6w", got)
+	}
+	// a labelled one from a policy with a prefix
+	if _, e, ok := SnapTime("tank/apps@nightly-2026-09-24_02.30.01--30d"); !ok || e.IsZero() {
+		t.Fatal("a prefixed name must parse and expire")
+	}
+	// no TTL: never expires
+	if _, e, ok := SnapTime("tank@2026-09-24_02.30.01"); !ok || !e.IsZero() {
+		t.Fatal("a name without a TTL must parse and never expire")
+	}
+	// things that are not ours
+	for _, n := range []string{"tank@before-upgrade", "tank@manual", "tank", "tank@2026-13-45_99.99.99--6w"} {
+		if _, _, ok := SnapTime(n); ok {
+			t.Errorf("%q must not parse as a scheduled snapshot", n)
+		}
+	}
+}
+
+func TestCronExprAndNextRun(t *testing.T) {
+	now := time.Date(2026, 9, 24, 9, 15, 0, 0, time.Local)
+	for _, c := range []struct {
+		p    Policy
+		want string
+	}{
+		{Policy{Every: "daily", At: "02:30"}, "30 2 * * *"},
+		{Policy{Every: "hourly", At: "00:30"}, "30 * * * *"},
+		{Policy{Every: "weekly", At: "04:00", Weekday: 0}, "0 4 * * 0"},
+		{Policy{Every: "monthly", At: "05:15", Day: 12}, "15 5 12 * *"},
+		{Policy{Every: "custom", Cron: "*/15  9-17 * * 1-5"}, "*/15 9-17 * * 1-5"},
+	} {
+		got, err := c.p.CronExpr()
+		if err != nil || got != c.want {
+			t.Errorf("CronExpr(%+v) = %q, %v; want %q", c.p.Every, got, err, c.want)
+		}
+	}
+	// the next run is read with the same evaluator the Jobs tab uses
+	daily := Policy{Every: "daily", At: "02:30"}
+	if n := daily.NextRun(now); n.Hour() != 2 || n.Minute() != 30 || n.Day() != 25 {
+		t.Fatalf("NextRun = %v, want 25th 02:30", n)
+	}
+	// a custom expression that does not parse is refused, not silently ignored
+	if _, err := (&Policy{Every: "custom", Cron: "not a schedule"}).CronExpr(); err == nil {
+		t.Fatal("a bad cron expression must be refused")
+	}
+	if _, err := (&Policy{Every: "custom", Cron: "@reboot"}).CronExpr(); err == nil {
+		t.Fatal("@reboot is not a snapshot schedule")
+	}
+}
+
+func TestCronFileText(t *testing.T) {
+	ps := []Policy{
+		{ID: "abc", Name: "tank nightly", Dataset: "tank", Every: "daily", At: "02:30", KeepFor: "6w", Enabled: true},
+		{ID: "def", Name: "paused one", Dataset: "tank/apps", Every: "hourly", At: "00:05", KeepFor: "2d"},
+	}
+	text, err := CronFileText(ps, "core", "/usr/local/bin/hamlab", "/home/core/apps/hamlab/config.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(text, "30 2 * * * core /usr/local/bin/hamlab -config /home/core/apps/hamlab/config.json zfs-snapshot abc") {
+		t.Fatalf("the enabled schedule is missing or malformed:\n%s", text)
+	}
+	if strings.Contains(text, "zfs-snapshot def") {
+		t.Fatalf("a paused schedule must not be scheduled:\n%s", text)
+	}
+	// every line cron will read must parse as a schedule
+	for _, line := range strings.Split(text, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") || strings.Contains(line, "=") {
+			continue
+		}
+		f := strings.Fields(line)
+		if err := cron.ValidSchedule(strings.Join(f[:5], " ")); err != nil {
+			t.Errorf("line %q: %v", line, err)
+		}
+	}
+}
+
+func TestValidateRefusesNonsense(t *testing.T) {
+	ok := Policy{Dataset: "tank/apps", Every: "daily", At: "02:30", KeepFor: "6w"}
+	if err := ok.Validate(); err != nil {
+		t.Fatalf("a sane policy: %v", err)
+	}
+	bad := []Policy{
+		{Dataset: "", Every: "daily", At: "02:30", KeepFor: "6w"},
+		{Dataset: "tank", Every: "yearly", At: "02:30", KeepFor: "6w"},
+		{Dataset: "tank", Every: "custom", KeepFor: "6w"},
+		{Dataset: "tank", Every: "custom", Cron: "not a schedule", KeepFor: "6w"},
+		{Dataset: "tank", Every: "daily", At: "25:00", KeepFor: "6w"},
+		{Dataset: "tank", Every: "daily", At: "02:30"},                           // no retention
+		{Dataset: "tank", Every: "daily", At: "02:30", KeepFor: "6 weeks"},       // unparseable
+		{Dataset: "tank", Every: "monthly", At: "02:30", Day: 31, KeepFor: "6w"}, // not every month has one
+		{Dataset: "tank", Every: "daily", At: "02:30", KeepFor: "6w", Prefix: "a--b"},
+	}
+	for i, p := range bad {
+		if err := p.Validate(); err == nil {
+			t.Errorf("bad policy %d was accepted: %+v", i, p)
+		}
+	}
+}
+
+func TestParseAge(t *testing.T) {
+	for s, want := range map[string]time.Duration{
+		"6w": 6 * 7 * 24 * time.Hour, "30d": 30 * 24 * time.Hour,
+		"12h": 12 * time.Hour, "90m": 90 * time.Minute,
+	} {
+		if got, err := ParseAge(s); err != nil || got != want {
+			t.Errorf("ParseAge(%q) = %v, %v; want %v", s, got, err, want)
+		}
+	}
+	for _, s := range []string{"", "6", "w", "-1d", "0w", "6y", "six weeks"} {
+		if _, err := ParseAge(s); err == nil {
+			t.Errorf("ParseAge(%q) should fail", s)
+		}
+	}
+}

internal/store/store.go

@@ -41,21 +41,50 @@ func (s *Session) UnmarshalJSON(b []byte) error {
 // UserState is what follows an account rather than the machine: how the console looks
 // to that person and how their dashboard is laid out.
 type UserState struct {
-	Dashboard json.RawMessage `json:"dashboard,omitempty"` // layout prefs, opaque to the server
 	UI json.RawMessage `json:"ui,omitempty"` // theme, accents; opaque to the server
 }
 
+// RememberedMount is one bind mount of a container that was running when Ham Lab last
+// looked. A compose stack records the path its file had *inside* whatever deployed it, so
+// when that container is gone the path is the only way back to the file on disk.
+type RememberedMount struct {
+	Container string    `json:"container"`
+	Dest      string    `json:"dest"` // the path inside the container
+	Src       string    `json:"src"`  // the path on the machine
+	Seen      time.Time `json:"seen"`
+}
+
 type State struct {
 	Terminals []Terminal            `json:"terminals"`
 	Sessions  map[string]Session    `json:"sessions"` // token -> session
 	Users     map[string]*UserState `json:"users,omitempty"`
-	// Dashboard and UI are the pre-users machine-wide prefs; on first boot with users they
-	// move to the first account. Kept so an old state file still reads.
-	Dashboard  json.RawMessage `json:"dashboard,omitempty"`
+	// UI is the pre-users machine-wide look; on first boot with users it moves to the first
+	// account. Kept so an old state file still reads.
 	UI         json.RawMessage `json:"ui,omitempty"`
 	Alerts     json.RawMessage `json:"alerts,omitempty"`      // rules, channels and recent events (internal/api/alerts.go)
+	ZFS        json.RawMessage `json:"zfs,omitempty"`         // snapshot schedules (internal/api/zfs.go)
+	DockerJobs json.RawMessage `json:"docker_jobs,omitempty"` // image-update schedules (internal/api/dockersched.go)
+	Network    json.RawMessage `json:"network,omitempty"`     // speed test results (internal/api/network.go)
+	// Mounts remembers where a container's bind mounts pointed, so a stack deployed by an
+	// orchestrator that has since been removed can still be found on disk. See
+	// internal/api/stacks.go.
+	Mounts []RememberedMount `json:"mounts,omitempty"`
+	// KVMCookies is each KVM's own login, as the cookies its page set in a browser: kept so
+	// the next browser — or this one after it has forgotten them — is signed into the device
+	// already. See internal/api/kvm.go.
+	KVMCookies map[string]map[string]string `json:"kvm_cookies,omitempty"`
 	SamplerMs  int                          `json:"sampler_ms,omitempty"`  // how often this machine samples; the hub keeps every machine on the console's refresh rate
 	HistorySec int                          `json:"history_sec,omitempty"` // how far back the graphs reach; the hub keeps every machine on the same one
+	// Transcode is where videos played in the Files viewer are made (internal/api/play.go):
+	// a machine and a device on it. nil is the machine the file is on, its best device.
+	Transcode *Transcode `json:"transcode,omitempty"`
+}
+
+// Transcode names a device on a machine: Node "" is the hub itself; Device is a render node
+// or "cpu".
+type Transcode struct {
+	Node   string `json:"node"`
+	Device string `json:"device"`
 }
 
 // UserState returns the prefs of an account, making an empty one if needed.

internal/tasks/tasks.go

@@ -146,7 +146,7 @@ func (m *Manager) prune() {
 	}
 	var finished []*Task
 	for _, t := range m.tasks {
-		if !t.Running {
+		if !t.running() {
 			finished = append(finished, t)
 		}
 	}
@@ -184,13 +184,20 @@ func (m *Manager) RunningOf(kind string) (*Task, bool) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
 	for _, t := range m.tasks {
-		if t.Kind == kind && t.Running {
+		if t.Kind == kind && t.running() {
 			return t, true
 		}
 	}
 	return nil, false
 }
 
+// running reads the flag the waiter goroutine clears, under the task's own lock.
+func (t *Task) running() bool {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	return t.Running
+}
+
 func (t *Task) Snapshot(withOutput bool) Snapshot {
 	t.mu.Lock()
 	defer t.mu.Unlock()

internal/term/manager.go

@@ -84,10 +84,21 @@ func newID() string {
 
 // Create starts a new login shell. id may be empty.
 func (m *Manager) Create(id, name string) (*Session, error) {
+	return m.CreateCmd(id, name, nil)
+}
+
+// CreateCmd is Create with something other than a login shell: argv nil is the shell, and
+// anything else runs that instead — `docker exec -it …` for a container's console. Every
+// session is the same thing afterwards, so attach, resize, the scrollback ring and the tab
+// strip work without knowing which it is.
+func (m *Manager) CreateCmd(id, name string, argv []string) (*Session, error) {
 	if id == "" {
 		id = newID()
 	}
 	cmd := exec.Command(m.shell, "-l")
+	if len(argv) > 0 {
+		cmd = exec.Command(argv[0], argv[1:]...)
+	}
 	cmd.Dir = m.home
 	cmd.Env = append(os.Environ(), "TERM=xterm-256color", "COLORTERM=truecolor", "HAMLAB=1")
 	ptmx, err := pty.StartWithSize(cmd, &pty.Winsize{Cols: defaultCol, Rows: defaultRow})

internal/updates/updates.go

@@ -64,6 +64,9 @@ func New(sudo bool, tm *tasks.Manager) *Manager {
 	return m
 }
 
+// PM is the package manager found: apt | dnf | zypper | pacman | apk, or "".
+func (m *Manager) PM() string { return m.pm }
+
 func (m *Manager) sudoArgs(args ...string) []string {
 	if m.sudo {
 		return priv.Wrap(args...)

internal/vpn/edit.go

@@ -0,0 +1,575 @@
+package vpn
+
+// Adding, renaming and removing the devices that dial in.
+//
+// Only OpenWrt's UCI is written, because that is where the server here is configured and
+// because a half-supported second path is worse than an honest refusal. A wg-quick host is
+// reported as unmanaged and the buttons do not appear.
+//
+// Two things happen for every change, in the order that fails safest:
+//
+//   - Adding: the configuration is written first and committed, then the peer is applied to
+//     the running tunnel. If applying fails the configuration is rolled back, so the two never
+//     disagree silently — a peer that works only after the next reboot is the worst outcome
+//     of the three.
+//   - Removing: the running tunnel first, because that is the moment access actually ends,
+//     then the configuration. If the second half fails the caller is told plainly that the
+//     device is off now but would return on a reboot.
+//
+// Nothing here restarts the network. `wg set` changes one peer on a live interface and
+// touches nothing else, which matters rather a lot when the interface belongs to the router
+// the house is behind.
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/netip"
+	"os"
+	"os/exec"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// NameRe is what a device may be called: a short slug, because it also names the config
+// section it is stored in.
+var NameRe = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9 ._-]{0,30}$`)
+
+// sectionRe guards the identifier that goes into a uci path.
+var sectionRe = regexp.MustCompile(`^[a-zA-Z0-9_]{1,48}$`)
+
+const sectionPrefix = "wgpeer_"
+
+var (
+	ErrUnmanaged = errors.New("this tunnel is not configured through UCI, so Ham Lab will not edit it here")
+	ErrNoRoom    = errors.New("no free address is left in this tunnel's range")
+)
+
+// NewPeer is what the caller asks for.
+type NewPeer struct {
+	Iface string `json:"-"`
+	Name  string `json:"name"`
+	// Address is the tunnel address to give the device, with or without a prefix. Empty means
+	// the next free one.
+	Address string `json:"address"`
+	// Endpoint is what the device will dial: the house's name or address, and the port.
+	Endpoint string `json:"endpoint"`
+	// DNS is what the device should use while connected. Empty leaves the line out.
+	DNS string `json:"dns"`
+	// Split routes only the home networks through the tunnel instead of everything.
+	Split bool `json:"split"`
+}
+
+// Created is a new device, and the one chance to read its configuration.
+type Created struct {
+	Section   string `json:"section"`
+	Name      string `json:"name"`
+	PublicKey string `json:"public_key"`
+	Address   string `json:"address"`
+	// Config is the complete client profile. It holds the private key, which exists nowhere
+	// else: it is generated here, handed over once and never stored.
+	Config string `json:"config"`
+}
+
+// uciPeer is one peer section as UCI holds it.
+type uciPeer struct {
+	Section    string
+	Iface      string // the wireguard_<iface> type it belongs to
+	Desc       string
+	PublicKey  string
+	AllowedIPs []string
+}
+
+// uciPeers reads every peer section. The type of a peer section names its interface
+// ("wireguard_wg0"), which is how a peer is tied to a tunnel.
+func uciPeers(ctx context.Context) ([]uciPeer, error) {
+	if _, err := exec.LookPath("uci"); err != nil {
+		return nil, ErrUnmanaged
+	}
+	b, err := exec.CommandContext(ctx, "uci", "-q", "show", "network").Output()
+	if err != nil {
+		return nil, err
+	}
+	by := map[string]*uciPeer{}
+	var order []string
+	for _, line := range strings.Split(string(b), "\n") {
+		lhs, rhs, ok := strings.Cut(line, "=")
+		if !ok || !strings.HasPrefix(lhs, "network.") {
+			continue
+		}
+		parts := strings.Split(strings.TrimPrefix(lhs, "network."), ".")
+		v := strings.Trim(rhs, "'")
+		section := parts[0]
+		if len(parts) == 1 { // the section's own type
+			if !strings.HasPrefix(v, "wireguard_") {
+				continue
+			}
+			by[section] = &uciPeer{Section: section, Iface: strings.TrimPrefix(v, "wireguard_")}
+			order = append(order, section)
+			continue
+		}
+		p := by[section]
+		if p == nil {
+			continue
+		}
+		switch parts[1] {
+		case "description":
+			p.Desc = v
+		case "public_key":
+			p.PublicKey = v
+		case "allowed_ips":
+			p.AllowedIPs = strings.Fields(strings.ReplaceAll(v, ",", " "))
+		}
+	}
+	out := make([]uciPeer, 0, len(order))
+	for _, s := range order {
+		out = append(out, *by[s])
+	}
+	return out, nil
+}
+
+// Managed reports whether this tunnel's peers can be edited here, and labels each peer with
+// the section that holds it so the caller has a safe identifier to act on.
+func Managed(ctx context.Context, t *Tunnel) bool {
+	peers, err := uciPeers(ctx)
+	if err != nil {
+		return false
+	}
+	found := false
+	byKey := map[string]string{}
+	for _, p := range peers {
+		if p.Iface == t.Name {
+			byKey[p.PublicKey] = p.Section
+			found = true
+		}
+	}
+	for i := range t.Peers {
+		t.Peers[i].Section = byKey[t.Peers[i].PublicKey]
+	}
+	// A tunnel with no peers at all is still manageable if UCI is the thing configuring it.
+	if !found {
+		for _, line := range uciInterfaces(ctx) {
+			if line == t.Name {
+				return true
+			}
+		}
+	}
+	return found
+}
+
+// uciInterfaces is every interface UCI configures as wireguard.
+func uciInterfaces(ctx context.Context) []string {
+	var out []string
+	if _, err := exec.LookPath("uci"); err != nil {
+		return out
+	}
+	b, err := exec.CommandContext(ctx, "uci", "-q", "show", "network").Output()
+	if err != nil {
+		return out
+	}
+	for _, line := range strings.Split(string(b), "\n") {
+		lhs, rhs, ok := strings.Cut(line, "=")
+		if !ok || strings.Trim(rhs, "'") != "wireguard" {
+			continue
+		}
+		parts := strings.Split(strings.TrimPrefix(lhs, "network."), ".")
+		if len(parts) == 2 && parts[1] == "proto" {
+			out = append(out, parts[0])
+		}
+	}
+	return out
+}
+
+// NextAddress is the lowest address in the tunnel's range that nothing is using. The
+// interface's own address is taken, as is every address any peer is allowed.
+func NextAddress(t Tunnel) (string, error) {
+	var base netip.Prefix
+	for _, a := range t.Addrs {
+		p, err := netip.ParsePrefix(a)
+		if err != nil || !p.Addr().Is4() {
+			continue
+		}
+		base = p
+		break
+	}
+	if !base.IsValid() {
+		return "", errors.New("this tunnel has no IPv4 range to allocate from")
+	}
+	taken := map[netip.Addr]bool{base.Addr(): true}
+	for _, p := range t.Peers {
+		for _, a := range p.AllowedIPs {
+			if ip, err := netip.ParsePrefix(strings.TrimSpace(a)); err == nil {
+				taken[ip.Addr()] = true
+			} else if ip, err := netip.ParseAddr(strings.TrimSpace(a)); err == nil {
+				taken[ip] = true
+			}
+		}
+	}
+	ip := base.Masked().Addr().Next() // .0 is the network
+	for base.Contains(ip) {
+		next := ip.Next()
+		if !base.Contains(next) { // the last address in the range is the broadcast
+			break
+		}
+		if !taken[ip] {
+			return ip.String(), nil
+		}
+		ip = next
+	}
+	return "", ErrNoRoom
+}
+
+// slug turns a device name into a section name, which may hold rather less.
+func slug(name string) string {
+	var b strings.Builder
+	for _, r := range strings.ToLower(name) {
+		switch {
+		case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
+			b.WriteRune(r)
+		case r == ' ', r == '-', r == '.', r == '_':
+			b.WriteByte('_')
+		}
+	}
+	s := strings.Trim(b.String(), "_")
+	if s == "" {
+		s = "peer"
+	}
+	if len(s) > 24 {
+		s = s[:24]
+	}
+	return s
+}
+
+// genKeys makes a private key, its public half and a pre-shared key. The private key is
+// returned to be handed over once and is never written anywhere by this daemon.
+func genKeys(ctx context.Context) (priv, pub, psk string, err error) {
+	run := func(name string, stdin string, args ...string) (string, error) {
+		cmd := exec.CommandContext(ctx, name, args...)
+		if stdin != "" {
+			cmd.Stdin = strings.NewReader(stdin)
+		}
+		out, err := cmd.Output()
+		return strings.TrimSpace(string(out)), err
+	}
+	if priv, err = run("wg", "", "genkey"); err != nil {
+		return "", "", "", fmt.Errorf("generating a key: %w", err)
+	}
+	if pub, err = run("wg", priv+"\n", "pubkey"); err != nil {
+		return "", "", "", fmt.Errorf("deriving the public key: %w", err)
+	}
+	if psk, err = run("wg", "", "genpsk"); err != nil {
+		return "", "", "", fmt.Errorf("generating a pre-shared key: %w", err)
+	}
+	return priv, pub, psk, nil
+}
+
+// AddPeer creates a device: it writes the peer into the configuration, applies it to the
+// running tunnel, and returns the client profile once.
+func AddPeer(ctx context.Context, t Tunnel, n NewPeer) (*Created, error) {
+	if !NameRe.MatchString(strings.TrimSpace(n.Name)) {
+		return nil, errors.New("a device name is 1–31 letters, digits, spaces, dots, dashes or underscores")
+	}
+	name := strings.TrimSpace(n.Name)
+	if strings.TrimSpace(n.Endpoint) == "" {
+		return nil, errors.New("the device needs an endpoint to dial: the house's address or name, and the port")
+	}
+	endpoint, err := checkEndpoint(n.Endpoint)
+	if err != nil {
+		return nil, err
+	}
+	addr := strings.TrimSpace(n.Address)
+	if addr == "" {
+		if addr, err = NextAddress(t); err != nil {
+			return nil, err
+		}
+	}
+	host, err := hostOf(addr)
+	if err != nil {
+		return nil, err
+	}
+	for _, p := range t.Peers {
+		for _, a := range p.AllowedIPs {
+			if strings.HasPrefix(strings.TrimSpace(a), host+"/") {
+				return nil, fmt.Errorf("%s is already used by %s", host, firstNonEmpty(p.Name, "another device"))
+			}
+		}
+	}
+	section := sectionPrefix + slug(name)
+	existing, err := uciPeers(ctx)
+	if err != nil {
+		return nil, ErrUnmanaged
+	}
+	taken := map[string]bool{}
+	for _, p := range existing {
+		taken[p.Section] = true
+	}
+	for i := 2; taken[section]; i++ {
+		section = fmt.Sprintf("%s%s%d", sectionPrefix, slug(name), i)
+	}
+	if !sectionRe.MatchString(section) {
+		return nil, errors.New("that name cannot be turned into a configuration section")
+	}
+
+	priv, pub, psk, err := genKeys(ctx)
+	if err != nil {
+		return nil, err
+	}
+	allowed := host + "/32"
+
+	// the configuration first, so a peer can never be live but unrecorded
+	set := [][]string{
+		{"set", "network." + section + "=wireguard_" + t.Name},
+		{"set", "network." + section + ".description=" + name},
+		{"set", "network." + section + ".public_key=" + pub},
+		{"set", "network." + section + ".preshared_key=" + psk},
+		{"set", "network." + section + ".allowed_ips=" + allowed},
+	}
+	for _, args := range set {
+		if err := uci(ctx, args...); err != nil {
+			_ = uci(ctx, "revert", "network")
+			return nil, fmt.Errorf("writing the configuration: %w", err)
+		}
+	}
+	if err := uci(ctx, "commit", "network"); err != nil {
+		_ = uci(ctx, "revert", "network")
+		return nil, fmt.Errorf("saving the configuration: %w", err)
+	}
+
+	// then the running tunnel; if this fails the configuration goes back as it was
+	if err := wgSet(ctx, t.Name, pub, psk, allowed); err != nil {
+		_ = uci(ctx, "delete", "network."+section)
+		_ = uci(ctx, "commit", "network")
+		return nil, fmt.Errorf("applying it to the running tunnel: %w", err)
+	}
+
+	return &Created{
+		Section: section, Name: name, PublicKey: pub, Address: host,
+		Config: profile(priv, psk, t, host, endpoint, n.DNS, n.Split),
+	}, nil
+}
+
+// EditPeer changes a device's label or the address it is allowed. The section keeps the name
+// it was created with; the description is what is shown.
+func EditPeer(ctx context.Context, t Tunnel, section, name, address string) error {
+	if !sectionRe.MatchString(section) {
+		return errors.New("that is not a device this can edit")
+	}
+	peers, err := uciPeers(ctx)
+	if err != nil {
+		return ErrUnmanaged
+	}
+	var me *uciPeer
+	for i := range peers {
+		if peers[i].Section == section && peers[i].Iface == t.Name {
+			me = &peers[i]
+		}
+	}
+	if me == nil {
+		return errors.New("no such device on this tunnel")
+	}
+	if name = strings.TrimSpace(name); name != "" {
+		if !NameRe.MatchString(name) {
+			return errors.New("a device name is 1–31 letters, digits, spaces, dots, dashes or underscores")
+		}
+		if err := uci(ctx, "set", "network."+section+".description="+name); err != nil {
+			_ = uci(ctx, "revert", "network")
+			return err
+		}
+	}
+	allowed := ""
+	if address = strings.TrimSpace(address); address != "" {
+		host, err := hostOf(address)
+		if err != nil {
+			_ = uci(ctx, "revert", "network")
+			return err
+		}
+		for _, p := range t.Peers {
+			if p.Section == section {
+				continue
+			}
+			for _, a := range p.AllowedIPs {
+				if strings.HasPrefix(strings.TrimSpace(a), host+"/") {
+					_ = uci(ctx, "revert", "network")
+					return fmt.Errorf("%s is already used by %s", host, firstNonEmpty(p.Name, "another device"))
+				}
+			}
+		}
+		allowed = host + "/32"
+		if err := uci(ctx, "set", "network."+section+".allowed_ips="+allowed); err != nil {
+			_ = uci(ctx, "revert", "network")
+			return err
+		}
+	}
+	if err := uci(ctx, "commit", "network"); err != nil {
+		_ = uci(ctx, "revert", "network")
+		return err
+	}
+	if allowed != "" { // the running tunnel has to be told, or the device keeps the old address
+		if err := wgSet(ctx, t.Name, me.PublicKey, "", allowed); err != nil {
+			return fmt.Errorf("saved, but the running tunnel refused the new address: %w", err)
+		}
+	}
+	return nil
+}
+
+// DeletePeer removes a device. The running tunnel goes first, because that is the moment the
+// device actually loses its way in.
+func DeletePeer(ctx context.Context, t Tunnel, section string) error {
+	if !sectionRe.MatchString(section) {
+		return errors.New("that is not a device this can remove")
+	}
+	peers, err := uciPeers(ctx)
+	if err != nil {
+		return ErrUnmanaged
+	}
+	var me *uciPeer
+	for i := range peers {
+		if peers[i].Section == section && peers[i].Iface == t.Name {
+			me = &peers[i]
+		}
+	}
+	if me == nil {
+		return errors.New("no such device on this tunnel")
+	}
+	if err := wgRemove(ctx, t.Name, me.PublicKey); err != nil {
+		return fmt.Errorf("removing it from the running tunnel: %w", err)
+	}
+	if err := uci(ctx, "delete", "network."+section); err != nil {
+		return fmt.Errorf("the device is disconnected, but removing it from the configuration failed, so it would come back on a reboot: %w", err)
+	}
+	if err := uci(ctx, "commit", "network"); err != nil {
+		return fmt.Errorf("the device is disconnected, but saving the configuration failed, so it would come back on a reboot: %w", err)
+	}
+	return nil
+}
+
+// ---- the small dangerous bits, each in one place ----
+
+func uci(ctx context.Context, args ...string) error {
+	out, err := exec.CommandContext(ctx, "uci", args...).CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("uci %s: %s", strings.Join(args, " "), strings.TrimSpace(string(out)))
+	}
+	return nil
+}
+
+// wgSet applies a peer to the running interface. The pre-shared key goes in through a file
+// because that is the only way wg takes one, so the file is made readable by nobody else and
+// removed immediately.
+func wgSet(ctx context.Context, iface, pub, psk, allowed string) error {
+	args := []string{"set", iface, "peer", pub}
+	if psk != "" {
+		f, err := os.CreateTemp("", "hamlab-psk")
+		if err != nil {
+			return err
+		}
+		defer os.Remove(f.Name())
+		if err := f.Chmod(0o600); err != nil {
+			f.Close()
+			return err
+		}
+		if _, err := f.WriteString(psk + "\n"); err != nil {
+			f.Close()
+			return err
+		}
+		f.Close()
+		args = append(args, "preshared-key", f.Name())
+	}
+	args = append(args, "allowed-ips", allowed)
+	out, err := exec.CommandContext(ctx, "wg", args...).CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("wg set: %s", strings.TrimSpace(string(out)))
+	}
+	return nil
+}
+
+func wgRemove(ctx context.Context, iface, pub string) error {
+	out, err := exec.CommandContext(ctx, "wg", "set", iface, "peer", pub, "remove").CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("wg set: %s", strings.TrimSpace(string(out)))
+	}
+	return nil
+}
+
+// profile is the client's own configuration file, which is the only place its private key
+// ever appears.
+func profile(priv, psk string, t Tunnel, addr, endpoint, dns string, split bool) string {
+	prefix := 24
+	for _, a := range t.Addrs {
+		if p, err := netip.ParsePrefix(a); err == nil && p.Addr().Is4() {
+			prefix = p.Bits()
+			break
+		}
+	}
+	allowed := "0.0.0.0/0"
+	if split {
+		nets := []string{}
+		for _, a := range t.Addrs {
+			if p, err := netip.ParsePrefix(a); err == nil && p.Addr().Is4() {
+				nets = append(nets, p.Masked().String())
+			}
+		}
+		nets = append(nets, "10.0.0.0/8", "192.168.0.0/16", "172.16.0.0/12")
+		allowed = strings.Join(dedupe(nets), ", ")
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "[Interface]\nPrivateKey = %s\nAddress = %s/%d\n", priv, addr, prefix)
+	if dns = strings.TrimSpace(dns); dns != "" {
+		fmt.Fprintf(&b, "DNS = %s\n", dns)
+	}
+	fmt.Fprintf(&b, "\n[Peer]\nPublicKey = %s\n", t.PublicKey)
+	if psk != "" {
+		fmt.Fprintf(&b, "PresharedKey = %s\n", psk)
+	}
+	fmt.Fprintf(&b, "Endpoint = %s\nAllowedIPs = %s\n", endpoint, allowed)
+	return b.String()
+}
+
+func dedupe(in []string) []string {
+	seen := map[string]bool{}
+	out := in[:0:0]
+	for _, s := range in {
+		if !seen[s] {
+			seen[s] = true
+			out = append(out, s)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// hostOf takes an address with or without a prefix and returns the bare address.
+func hostOf(s string) (string, error) {
+	s = strings.TrimSpace(s)
+	if p, err := netip.ParsePrefix(s); err == nil {
+		return p.Addr().String(), nil
+	}
+	a, err := netip.ParseAddr(s)
+	if err != nil {
+		return "", fmt.Errorf("%q is not an address", s)
+	}
+	return a.String(), nil
+}
+
+// checkEndpoint makes sure what the device will dial looks like a host and a port.
+func checkEndpoint(s string) (string, error) {
+	s = strings.TrimSpace(s)
+	host, port, err := net.SplitHostPort(s)
+	if err != nil || host == "" {
+		return "", fmt.Errorf("%q should be a name or address and a port, like home.example.com:51820", s)
+	}
+	if n, err := strconv.Atoi(port); err != nil || n < 1 || n > 65535 {
+		return "", fmt.Errorf("%q is not a port", port)
+	}
+	return s, nil
+}
+
+func firstNonEmpty(a, b string) string {
+	if a != "" {
+		return a
+	}
+	return b
+}

internal/vpn/edit_test.go

@@ -0,0 +1,126 @@
+package vpn
+
+import (
+	"strings"
+	"testing"
+)
+
+func tunnel(addrs []string, peers ...string) Tunnel {
+	t := Tunnel{Name: "wg0", PublicKey: "SERVERKEY=", Addrs: addrs}
+	for _, p := range peers {
+		t.Peers = append(t.Peers, Peer{PublicKey: p + "KEY=", AllowedIPs: []string{p}})
+	}
+	return t
+}
+
+func TestNextAddress(t *testing.T) {
+	// .1 is the interface itself and .2 and .3 are taken, so the next free one is .4
+	got, err := NextAddress(tunnel([]string{"172.21.46.1/24"}, "172.21.46.3/32", "172.21.46.2/32"))
+	if err != nil || got != "172.21.46.4" {
+		t.Errorf("NextAddress = %q, %v; want 172.21.46.4", got, err)
+	}
+	// a gap is filled before the end is reached
+	got, _ = NextAddress(tunnel([]string{"172.21.46.1/24"}, "172.21.46.2/32", "172.21.46.4/32"))
+	if got != "172.21.46.3" {
+		t.Errorf("NextAddress = %q, want the gap at .3", got)
+	}
+	// an empty tunnel starts after the server
+	got, _ = NextAddress(tunnel([]string{"10.9.0.1/24"}))
+	if got != "10.9.0.2" {
+		t.Errorf("NextAddress = %q, want 10.9.0.2", got)
+	}
+	// a full one says so rather than handing out a duplicate
+	full := tunnel([]string{"10.9.0.1/30"}, "10.9.0.2/32")
+	if _, err := NextAddress(full); err != ErrNoRoom {
+		t.Errorf("err = %v, want ErrNoRoom on a full range", err)
+	}
+	// IPv6-only, or nothing at all, is refused rather than guessed
+	if _, err := NextAddress(tunnel([]string{"fc00::1/64"})); err == nil {
+		t.Error("want an error when there is no IPv4 range")
+	}
+}
+
+func TestSlug(t *testing.T) {
+	for in, want := range map[string]string{
+		"ip12":                  "ip12",
+		"Mitchell's iPad":       "mitchells_ipad",
+		"my-phone":              "my_phone",
+		"  spaced  out  ":       "spaced__out",
+		"!!!":                   "peer",
+		strings.Repeat("a", 40): strings.Repeat("a", 24),
+	} {
+		if got := slug(in); got != want {
+			t.Errorf("slug(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestProfile(t *testing.T) {
+	tun := tunnel([]string{"172.21.46.1/24"})
+	got := profile("PRIV=", "PSK=", tun, "172.21.46.4", "home.example.com:51820", "1.1.1.1, 1.0.0.1", false)
+	for _, want := range []string{
+		"PrivateKey = PRIV=",
+		"Address = 172.21.46.4/24", // the interface's own prefix, not a bare /32
+		"DNS = 1.1.1.1, 1.0.0.1",
+		"PublicKey = SERVERKEY=",
+		"PresharedKey = PSK=",
+		"Endpoint = home.example.com:51820",
+		"AllowedIPs = 0.0.0.0/0",
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("profile is missing %q:\n%s", want, got)
+		}
+	}
+	// no DNS line at all when none was asked for, rather than an empty one
+	if strings.Contains(profile("P=", "", tun, "172.21.46.4", "h:1", "", false), "DNS") {
+		t.Error("an empty DNS should leave the line out")
+	}
+	// split routes the private ranges instead of everything
+	split := profile("P=", "", tun, "172.21.46.4", "h:1", "", true)
+	if strings.Contains(split, "0.0.0.0/0") {
+		t.Errorf("a split tunnel must not route everything:\n%s", split)
+	}
+	if !strings.Contains(split, "172.21.46.0/24") {
+		t.Errorf("a split tunnel should include the tunnel's own range:\n%s", split)
+	}
+}
+
+func TestCheckEndpoint(t *testing.T) {
+	for _, ok := range []string{"bigham.dev:51820", "1.2.3.4:51820", "[2001:db8::1]:51820"} {
+		if _, err := checkEndpoint(ok); err != nil {
+			t.Errorf("checkEndpoint(%q) = %v, want it accepted", ok, err)
+		}
+	}
+	for _, bad := range []string{"", "bigham.dev", ":51820", "bigham.dev:0", "bigham.dev:notaport", "bigham.dev:99999"} {
+		if _, err := checkEndpoint(bad); err == nil {
+			t.Errorf("checkEndpoint(%q) was accepted, want refused", bad)
+		}
+	}
+}
+
+func TestHostOf(t *testing.T) {
+	for in, want := range map[string]string{"172.21.46.4": "172.21.46.4", "172.21.46.4/32": "172.21.46.4", " 10.0.0.9/24 ": "10.0.0.9"} {
+		got, err := hostOf(in)
+		if err != nil || got != want {
+			t.Errorf("hostOf(%q) = %q, %v; want %q", in, got, err, want)
+		}
+	}
+	if _, err := hostOf("not-an-address"); err == nil {
+		t.Error("hostOf accepted nonsense")
+	}
+}
+
+// The name is what becomes a configuration section, so it is the input worth being strict
+// about; everything refused here is refused before anything is written.
+func TestNameRe(t *testing.T) {
+	for _, ok := range []string{"ip12", "My Phone", "a", "work-laptop.2"} {
+		if !NameRe.MatchString(ok) {
+			t.Errorf("%q should be a valid name", ok)
+		}
+	}
+	for _, bad := range []string{"", " leading", "semi;colon", "quote'd", "back`tick", "new\nline", "$(whoami)", strings.Repeat("a", 32)} {
+		if NameRe.MatchString(bad) {
+			t.Errorf("%q should be refused as a name", bad)
+		}
+	}
+}

internal/vpn/vpn.go

@@ -0,0 +1,372 @@
+// Package vpn reads this machine's WireGuard tunnels: the interfaces, and the peers on them
+// with names put back on.
+//
+// The live state comes from `wg show all dump`, which is the kernel's own answer and the only
+// place handshakes and byte counts exist. The kernel knows nothing about names, though — a
+// peer there is a public key — so the configuration is read alongside it purely to label
+// them: `# comments` in a wg-quick .conf, or the `description` of a UCI peer section on
+// OpenWrt. Everything here is read-only, and no private or pre-shared key is ever read, let
+// alone returned.
+package vpn
+
+import (
+	"bufio"
+	"context"
+	"net"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"hamlab/internal/priv"
+)
+
+// Peer is one end of a tunnel: a device that dials in, or the server this machine dials out
+// to. Which it is depends on the tunnel; see Tunnel.Kind.
+type Peer struct {
+	// Name is what the configuration calls it, where it says at all. The kernel has no idea.
+	Name      string `json:"name,omitempty"`
+	PublicKey string `json:"public_key"`
+	// Endpoint is where its packets come from, empty until it has been heard from.
+	Endpoint   string   `json:"endpoint,omitempty"`
+	AllowedIPs []string `json:"allowed_ips"`
+	// Handshake is the last completed handshake, absent when there has never been one — a peer
+	// that is configured but has not connected since this tunnel came up. A pointer because
+	// omitempty does nothing for a zero time.Time, and a peer that has never been heard from
+	// would otherwise be reported as having last spoken in the year one.
+	Handshake *time.Time `json:"handshake,omitempty"`
+	// Online is a handshake inside the last three minutes. WireGuard is silent when idle, so
+	// this means "was talking recently", not "is connected" — there is no such thing here.
+	Online    bool  `json:"online"`
+	Rx        int64 `json:"rx"`
+	Tx        int64 `json:"tx"`
+	Keepalive int   `json:"keepalive,omitempty"`
+	// PSK notes that a pre-shared key is in use, without the key itself going anywhere.
+	PSK bool `json:"psk,omitempty"`
+	// Section is the configuration section holding this peer, and the identifier anything that
+	// edits it uses. Empty when the peer is not in a configuration this can edit.
+	Section string `json:"section,omitempty"`
+}
+
+// Tunnel is one WireGuard interface.
+type Tunnel struct {
+	Name string `json:"name"`
+	// Managed is whether devices on this tunnel can be added and removed from here, which
+	// today means its peers are configured through OpenWrt's UCI.
+	Managed   bool   `json:"managed"`
+	PublicKey string `json:"public_key"`
+	// Kind is "server" when peers dial in to this machine, "client" when this machine dials
+	// out through a peer, and "" when it is too new or too odd to tell. It is worked out from
+	// the shape of the peers, not from anything WireGuard states: a peer that is routed
+	// everything and has an endpoint of its own is an exit, and a tunnel with one of those is
+	// this machine going out through it.
+	Kind       string   `json:"kind"`
+	ListenPort int      `json:"listen_port,omitempty"`
+	FwMark     string   `json:"fwmark,omitempty"`
+	Addrs      []string `json:"addrs"`
+	MTU        int      `json:"mtu,omitempty"`
+	Peers      []Peer   `json:"peers"`
+	// Exit is the peer this machine goes out through, for a client tunnel.
+	Exit string `json:"exit,omitempty"`
+}
+
+// Report is every tunnel on this machine, and why there are none when there are none.
+type Report struct {
+	At      time.Time `json:"at"`
+	Tunnels []Tunnel  `json:"tunnels"`
+	// Tool is false when wireguard-tools is not installed, Root false when the daemon cannot
+	// reach root — either one means the peers cannot be read, and the tab should say which.
+	Tool bool   `json:"tool"`
+	Root bool   `json:"root"`
+	Note string `json:"note,omitempty"`
+}
+
+const onlineWithin = 3 * time.Minute
+
+// Look reads the tunnels on this machine.
+func Look(ctx context.Context) Report {
+	r := Report{At: time.Now(), Tunnels: []Tunnel{}, Root: priv.Available()}
+	if _, err := exec.LookPath("wg"); err != nil {
+		r.Note = "wireguard-tools is not installed here, so there is nothing to read"
+		return r
+	}
+	r.Tool = true
+	args := []string{"wg", "show", "all", "dump"}
+	if priv.Available() {
+		args = priv.Wrap(args...)
+	}
+	cmd := exec.CommandContext(ctx, args[0], args[1:]...)
+	out, err := cmd.Output()
+	if err != nil {
+		if !r.Root {
+			r.Note = "reading WireGuard needs root, and this daemon has no way to it"
+		} else {
+			r.Note = "wg show failed: " + strings.TrimSpace(err.Error())
+		}
+		return r
+	}
+	r.Tunnels = parseDump(string(out))
+	names := peerNames()
+	for i := range r.Tunnels {
+		t := &r.Tunnels[i]
+		t.Addrs, t.MTU = ifaceAddrs(t.Name)
+		for j := range t.Peers {
+			p := &t.Peers[j]
+			p.Name = names[p.PublicKey]
+			p.Online = p.Handshake != nil && time.Since(*p.Handshake) < onlineWithin
+		}
+		t.Kind, t.Exit = classify(*t)
+		t.Managed = Managed(ctx, t)
+		sort.SliceStable(t.Peers, func(a, b int) bool {
+			pa, pb := t.Peers[a], t.Peers[b]
+			if pa.Online != pb.Online {
+				return pa.Online
+			}
+			if ha, hb := shookAt(pa), shookAt(pb); !ha.Equal(hb) {
+				return ha.After(hb)
+			}
+			return pa.Name < pb.Name
+		})
+	}
+	if len(r.Tunnels) == 0 {
+		r.Note = "no WireGuard interfaces are up on this machine"
+	}
+	return r
+}
+
+// parseDump reads `wg show all dump`. The first line of each interface is the interface
+// itself, the rest are its peers; every line is tab-separated and positional.
+//
+//	interface: name  private-key  public-key  listen-port  fwmark
+//	peer:      name  public-key   psk         endpoint     allowed-ips  handshake  rx  tx  keepalive
+//
+// The private key is in the second column and is read past without being kept.
+func parseDump(out string) []Tunnel {
+	// An empty list, never nil: this is JSON to a browser that will take its length, and a
+	// null there is a blank page rather than "no tunnels".
+	tunnels := []Tunnel{}
+	byName := map[string]int{}
+	sc := bufio.NewScanner(strings.NewReader(out))
+	sc.Buffer(make([]byte, 0, 64<<10), 1<<20)
+	for sc.Scan() {
+		f := strings.Split(sc.Text(), "\t")
+		if len(f) < 5 {
+			continue
+		}
+		name := f[0]
+		if len(f) == 5 { // an interface line
+			port, _ := strconv.Atoi(f[3])
+			byName[name] = len(tunnels)
+			tunnels = append(tunnels, Tunnel{Name: name, PublicKey: f[2], ListenPort: port, FwMark: off(f[4]), Peers: []Peer{}})
+			continue
+		}
+		if len(f) < 9 {
+			continue
+		}
+		i, ok := byName[name]
+		if !ok {
+			continue
+		}
+		hs, _ := strconv.ParseInt(f[5], 10, 64)
+		rx, _ := strconv.ParseInt(f[6], 10, 64)
+		tx, _ := strconv.ParseInt(f[7], 10, 64)
+		ka, _ := strconv.Atoi(f[8])
+		p := Peer{PublicKey: f[1], PSK: f[2] != "(none)", Endpoint: off(f[3]), Rx: rx, Tx: tx, Keepalive: ka}
+		if f[4] != "(none)" {
+			p.AllowedIPs = strings.Split(f[4], ",")
+		}
+		if hs > 0 {
+			at := time.Unix(hs, 0)
+			p.Handshake = &at
+		}
+		tunnels[i].Peers = append(tunnels[i].Peers, p)
+	}
+	return tunnels
+}
+
+// shookAt is a peer's last handshake, or the zero time when there has never been one.
+func shookAt(p Peer) time.Time {
+	if p.Handshake == nil {
+		return time.Time{}
+	}
+	return *p.Handshake
+}
+
+// off turns wg's placeholders into an empty string.
+func off(v string) string {
+	if v == "(none)" || v == "off" {
+		return ""
+	}
+	return v
+}
+
+// classify decides whether this machine is the one being dialled or the one dialling. A peer
+// that is allowed every address and has an endpoint is a way out to the internet; a tunnel
+// with one of those is this machine using it. Otherwise, if anything can reach us here, it is
+// a server.
+func classify(t Tunnel) (kind, exit string) {
+	for _, p := range t.Peers {
+		for _, a := range p.AllowedIPs {
+			if a == "0.0.0.0/0" || a == "::/0" {
+				if p.Endpoint != "" {
+					name := p.Name
+					if name == "" {
+						name = p.Endpoint
+					}
+					return "client", name
+				}
+			}
+		}
+	}
+	if t.ListenPort > 0 && len(t.Peers) > 0 {
+		return "server", ""
+	}
+	return "", ""
+}
+
+// ifaceAddrs is what the interface carries, and its MTU.
+func ifaceAddrs(name string) ([]string, int) {
+	addrs := []string{}
+	mtu := 0
+	ifi, err := net.InterfaceByName(name)
+	if err != nil {
+		return addrs, mtu
+	}
+	mtu = ifi.MTU
+	got, err := ifi.Addrs()
+	if err != nil {
+		return addrs, mtu
+	}
+	for _, a := range got {
+		addrs = append(addrs, a.String())
+	}
+	return addrs, mtu
+}
+
+// ---- names ----
+
+// peerNames maps a public key to what the configuration calls that peer. Two shapes are
+// understood, which between them cover every machine here: wg-quick's .conf files, where the
+// name is a comment, and OpenWrt's UCI, where it is the peer section's description.
+func peerNames() map[string]string {
+	out := map[string]string{}
+	for k, v := range confNames() {
+		out[k] = v
+	}
+	for k, v := range uciNames() { // UCI wins: on OpenWrt it is the live configuration
+		out[k] = v
+	}
+	return out
+}
+
+// confNames reads /etc/wireguard/*.conf. In a wg-quick file a peer is named by the comment
+// that introduces it, which is the convention every tool that writes these files follows:
+//
+//	# phone
+//	[Peer]
+//	PublicKey = …
+//
+// confDir is where wg-quick keeps its files; a variable so the test can point it elsewhere.
+var confDir = "/etc/wireguard"
+
+func confNames() map[string]string {
+	out := map[string]string{}
+	files, _ := filepath.Glob(filepath.Join(confDir, "*.conf"))
+	for _, path := range files {
+		text, err := readMaybeRoot(path)
+		if err != nil {
+			continue
+		}
+		sc := bufio.NewScanner(strings.NewReader(text))
+		// last is the most recent comment line; when a [Peer] block opens, that comment becomes
+		// its pending name. Keeping the two apart is what lets each block take the comment that
+		// introduces it and ignore any comment written inside it.
+		last, pending := "", ""
+		inPeer := false
+		for sc.Scan() {
+			line := strings.TrimSpace(sc.Text())
+			switch {
+			case strings.EqualFold(line, "[Peer]"):
+				inPeer, pending, last = true, last, ""
+			case strings.HasPrefix(line, "["):
+				inPeer, pending, last = false, "", ""
+			case strings.HasPrefix(line, "#"):
+				if c := strings.TrimSpace(strings.TrimLeft(line, "#")); c != "" {
+					last = c
+				}
+			case inPeer && strings.HasPrefix(line, "PublicKey"):
+				// The separator is the first '='; the key's own base64 padding is the rest of
+				// the line, so everything after that first one is the key.
+				if _, v, ok := strings.Cut(line, "="); ok && pending != "" {
+					out[strings.TrimSpace(v)] = pending
+				}
+				pending = ""
+			}
+		}
+	}
+	return out
+}
+
+// readMaybeRoot reads a file, falling back to root when it is not ours to read — which
+// /etc/wireguard always is, since it holds private keys. Only the comments and public keys in
+// it are looked at; nothing else in the file is kept or returned.
+func readMaybeRoot(path string) (string, error) {
+	b, err := os.ReadFile(path)
+	if err == nil {
+		return string(b), nil
+	}
+	if !os.IsPermission(err) || !priv.Available() {
+		return "", err
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	args := priv.Wrap("cat", path)
+	out, cerr := exec.CommandContext(ctx, args[0], args[1:]...).Output()
+	if cerr != nil {
+		return "", cerr
+	}
+	return string(out), nil
+}
+
+// uciNames reads OpenWrt's configuration: each peer is a section with a description and a
+// public key. `uci show` is used rather than the file, so includes and overrides are applied.
+func uciNames() map[string]string {
+	out := map[string]string{}
+	if _, err := exec.LookPath("uci"); err != nil {
+		return out
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	b, err := exec.CommandContext(ctx, "uci", "-q", "show", "network").Output()
+	if err != nil {
+		return out
+	}
+	desc, key := map[string]string{}, map[string]string{}
+	for _, line := range strings.Split(string(b), "\n") {
+		lhs, rhs, ok := strings.Cut(line, "=")
+		if !ok || !strings.HasPrefix(lhs, "network.") {
+			continue
+		}
+		parts := strings.Split(strings.TrimPrefix(lhs, "network."), ".")
+		if len(parts) != 2 {
+			continue
+		}
+		section, option := parts[0], parts[1]
+		v := strings.Trim(rhs, "'")
+		switch option {
+		case "description":
+			desc[section] = v
+		case "public_key":
+			key[section] = v
+		}
+	}
+	for section, k := range key {
+		if d := desc[section]; d != "" {
+			out[k] = d
+		}
+	}
+	return out
+}

internal/vpn/vpn_test.go

@@ -0,0 +1,193 @@
+package vpn
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Real output of `wg show all dump`, from the two machines here: gate, where devices dial in,
+// and hamtv, which dials out through Mullvad. Keys are the real public ones, which are public.
+const gateDump = "wg0\tPRIVATEKEYWOULDBEHERE=\t4VwqgzHyelmVmNY+EANRWQggSSxvYYguJQMvUty9Sns=\t51820\toff\n" +
+	"wg0\tNeWxo9wfqgipBQLuP676WFcMlW5RDrOcanc9y8sT7kU=\t3KWsu0mdVb2l5B/j0qHE03yE9LXi3FJ1WAjWMuxaLAw=\t10.0.0.33:63573\t172.21.46.3/32\t1790565744\t134192164\t415977404\toff\n" +
+	"wg0\twUnRD990c6aglU0TCREtmfuUTPzqSmHrd3qTORpRJBg=\t4Pd5u2t6U9EdHlFlneg+hMr0G2v+IvoE/EqGfFdDPI8=\t(none)\t172.21.46.2/32\t0\t0\t0\toff\n"
+
+const hamtvDump = "wg0\tPRIVATEKEYWOULDBEHERE=\tF/rgcHi+ZiaWPoSQ9iPcldIUbbMotE1hwSB/74Y9Qi4=\t39281\toff\n" +
+	"wg0\tzqsfGglzJPY657WMRxf/S4omG7+ZkSDIpDq+ggbc9yo=\t(none)\t23.234.72.2:51820\t0.0.0.0/0,::/0\t1790571246\t18206675520\t2687837240\t25\n"
+
+func TestParseServerDump(t *testing.T) {
+	ts := parseDump(gateDump)
+	if len(ts) != 1 {
+		t.Fatalf("got %d tunnels, want 1", len(ts))
+	}
+	w := ts[0]
+	if w.Name != "wg0" || w.ListenPort != 51820 {
+		t.Errorf("interface = %s:%d, want wg0:51820", w.Name, w.ListenPort)
+	}
+	if w.PublicKey != "4VwqgzHyelmVmNY+EANRWQggSSxvYYguJQMvUty9Sns=" {
+		t.Errorf("public key = %q; the third column is the public one", w.PublicKey)
+	}
+	// The private key is column two of the interface line and must not appear anywhere.
+	if w.PublicKey == "PRIVATEKEYWOULDBEHERE=" || w.FwMark == "PRIVATEKEYWOULDBEHERE=" {
+		t.Error("the private key was kept")
+	}
+	if len(w.Peers) != 2 {
+		t.Fatalf("got %d peers, want 2", len(w.Peers))
+	}
+	p := w.Peers[0]
+	if p.PublicKey != "NeWxo9wfqgipBQLuP676WFcMlW5RDrOcanc9y8sT7kU=" || p.Endpoint != "10.0.0.33:63573" {
+		t.Errorf("first peer = %+v", p)
+	}
+	if !p.PSK {
+		t.Error("first peer has a pre-shared key and should say so")
+	}
+	if got := p.AllowedIPs; len(got) != 1 || got[0] != "172.21.46.3/32" {
+		t.Errorf("allowed ips = %v", got)
+	}
+	if p.Rx != 134192164 || p.Tx != 415977404 {
+		t.Errorf("counters = %d/%d", p.Rx, p.Tx)
+	}
+	if p.Handshake == nil || p.Handshake.Unix() != 1790565744 {
+		t.Errorf("handshake = %v", p.Handshake)
+	}
+	// The second peer has never connected: no endpoint, no handshake, nothing moved.
+	if q := w.Peers[1]; q.Endpoint != "" || q.Handshake != nil || q.Rx != 0 {
+		t.Errorf("second peer = %+v, want one that has never been heard from", q)
+	}
+	if kind, exit := classify(w); kind != "server" || exit != "" {
+		t.Errorf("classify = %q/%q, want server", kind, exit)
+	}
+}
+
+func TestParseClientDump(t *testing.T) {
+	ts := parseDump(hamtvDump)
+	if len(ts) != 1 || len(ts[0].Peers) != 1 {
+		t.Fatalf("got %d tunnels", len(ts))
+	}
+	w := ts[0]
+	p := w.Peers[0]
+	if len(p.AllowedIPs) != 2 || p.AllowedIPs[0] != "0.0.0.0/0" {
+		t.Errorf("allowed ips = %v, want everything", p.AllowedIPs)
+	}
+	if p.Keepalive != 25 {
+		t.Errorf("keepalive = %d, want 25", p.Keepalive)
+	}
+	if p.PSK {
+		t.Error("this peer has no pre-shared key")
+	}
+	// It routes everything and has an endpoint, so this machine goes out through it.
+	kind, exit := classify(w)
+	if kind != "client" || exit != "23.234.72.2:51820" {
+		t.Errorf("classify = %q/%q, want client through the endpoint", kind, exit)
+	}
+}
+
+// A tunnel that is up but has no peers at all is neither, and must not be guessed at.
+func TestClassifyUndecided(t *testing.T) {
+	if kind, _ := classify(Tunnel{Name: "wg0", ListenPort: 51820}); kind != "" {
+		t.Errorf("classify with no peers = %q, want no opinion", kind)
+	}
+}
+
+// Peers are named by the comment above them in a wg-quick file. The public key's own base64
+// padding is an '=' too, which is the thing to get wrong.
+func TestConfNames(t *testing.T) {
+	dir := t.TempDir()
+	conf := `[Interface]
+Address = 172.21.46.1/24
+PrivateKey = SECRETSECRETSECRETSECRETSECRETSECRETSECRET=
+ListenPort = 51820
+
+# phone
+[Peer]
+PublicKey = NeWxo9wfqgipBQLuP676WFcMlW5RDrOcanc9y8sT7kU=
+AllowedIPs = 172.21.46.3/32
+
+# the laptop
+[Peer]
+PublicKey = wUnRD990c6aglU0TCREtmfuUTPzqSmHrd3qTORpRJBg=
+AllowedIPs = 172.21.46.2/32
+`
+	if err := os.WriteFile(filepath.Join(dir, "wg0.conf"), []byte(conf), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	old := confDir
+	confDir = dir
+	defer func() { confDir = old }()
+
+	names := confNames()
+	if got := names["NeWxo9wfqgipBQLuP676WFcMlW5RDrOcanc9y8sT7kU="]; got != "phone" {
+		t.Errorf("first peer named %q, want phone", got)
+	}
+	if got := names["wUnRD990c6aglU0TCREtmfuUTPzqSmHrd3qTORpRJBg="]; got != "the laptop" {
+		t.Errorf("second peer named %q, want the laptop", got)
+	}
+	for k := range names {
+		if k == "SECRETSECRETSECRETSECRETSECRETSECRETSECRET=" {
+			t.Error("the private key was read as if it were a peer")
+		}
+	}
+	if len(names) != 2 {
+		t.Errorf("%d names, want 2: %v", len(names), names)
+	}
+}
+
+func TestOnlineIsRecentHandshake(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		hs   time.Time
+		want bool
+	}{
+		{"just now", time.Now().Add(-30 * time.Second), true},
+		{"a while back", time.Now().Add(-10 * time.Minute), false},
+		{"never", time.Time{}, false},
+	} {
+		got := !tc.hs.IsZero() && time.Since(tc.hs) < onlineWithin
+		if got != tc.want {
+			t.Errorf("%s: online = %v, want %v", tc.name, got, tc.want)
+		}
+	}
+}
+
+// A peer that has never handshaken must carry no time at all, not the zero one. omitempty
+// does nothing for a time.Time, so this is the difference between the page saying "never
+// connected" and saying the device was last seen in the year one.
+func TestNeverConnectedHasNoTimestamp(t *testing.T) {
+	w := parseDump(gateDump)[0]
+	b, err := json.Marshal(w.Peers[1])
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(b), "handshake") {
+		t.Errorf("json = %s, want no handshake field at all", b)
+	}
+	if strings.Contains(string(b), "0001-01-01") {
+		t.Errorf("json = %s, want no year-one timestamp", b)
+	}
+	// and the one that has connected still carries its time
+	if b, _ := json.Marshal(w.Peers[0]); !strings.Contains(string(b), "handshake") {
+		t.Errorf("json = %s, want the handshake of a peer that has one", b)
+	}
+}
+
+// A machine with wireguard-tools installed but no tunnel up produces an empty dump. That has
+// to marshal as [] and not as null: the page takes the length of it, and null blanks the
+// whole console rather than saying "no tunnels".
+func TestEmptyDumpIsAnEmptyList(t *testing.T) {
+	for _, dump := range []string{"", "\n", "   \n\n"} {
+		got := parseDump(dump)
+		if got == nil {
+			t.Fatalf("parseDump(%q) = nil, want an empty list", dump)
+		}
+		b, err := json.Marshal(got)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if string(b) != "[]" {
+			t.Errorf("parseDump(%q) marshals to %s, want []", dump, b)
+		}
+	}
+}

scripts/pci-ids-gpu.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+# Trim the PCI ID database to the graphics devices of the GPU vendors, for embedding in
+# the binary (internal/metrics/pciids_gpu.txt): a machine without pciutils — OpenWrt has
+# neither lspci nor pci.ids — then names its GPU exactly as every other machine does.
+#
+#   scripts/pci-ids-gpu.sh [/path/to/pci.ids]     default: /usr/share/misc/pci.ids
+#
+# Kept: the vendor lines and device lines (never subsystems) of Intel 8086, AMD 1002 and
+# NVIDIA 10de whose name is bracketed (how pci.ids writes a marketing name) or mentions
+# graphics, and everything of the three virtual-GPU vendors (virtio 1af4, VMware 15ad,
+# Bochs 1234). A non-GPU device slipping through costs a line; it is only ever consulted
+# for a card the kernel already drives as a GPU.
+set -eu
+src=${1:-/usr/share/misc/pci.ids}
+out=$(dirname "$0")/../internal/metrics/pciids_gpu.txt
+{
+  echo "# Trimmed from pci.ids ($(grep -m1 -i 'version:' "$src" | sed 's/^#[[:space:]]*//')) by scripts/pci-ids-gpu.sh."
+  echo "# Vendor lines and the graphics device lines of Intel, AMD and NVIDIA, plus the virtual GPUs."
+  echo "# pci.ids is distributed under the 3-clause BSD license (https://pci-ids.ucw.cz/)."
+  awk '
+    /^[0-9a-f][0-9a-f][0-9a-f][0-9a-f]  / {
+      vendor = substr($0, 1, 4)
+      keep = (vendor == "8086" || vendor == "1002" || vendor == "10de")
+      all = (vendor == "1af4" || vendor == "15ad" || vendor == "1234")
+      if (keep || all) print
+      next
+    }
+    /^\t[0-9a-f][0-9a-f][0-9a-f][0-9a-f]  / {
+      if (all) { print; next }
+      if (!keep) next
+      if ($0 ~ /\[/ || $0 ~ /Graphics|Radeon|GeForce|Quadro|Tesla|Arc |Iris|Xe |GPU|Display|VGA|FirePro|Instinct|Data Center/) print
+    }
+  ' "$src"
+} > "$out"
+echo "$out: $(wc -l < "$out") lines, $(wc -c < "$out") bytes"

web/package-lock.json

@@ -11,6 +11,8 @@
         "@xterm/addon-fit": "^0.10.0",
         "@xterm/addon-web-links": "^0.11.0",
         "@xterm/xterm": "^5.5.0",
+        "hls.js": "^1.7.3",
+        "qrcode-generator": "^2.0.4",
         "react": "^18.3.1",
         "react-dom": "^18.3.1"
       },
@@ -1425,6 +1427,12 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/hls.js": {
+      "version": "1.7.3",
+      "resolved": "https://registry.npmjs.org/hls.js/-/hls.js-1.7.3.tgz",
+      "integrity": "sha512-MsPlx6yVW4Qv4C7mEVou4/gk/5cN2dVxOTnrNjPSmyH2f0Ln+/UkG10Ax1PE6OvrmTVPKgQYozTtBaPOuCzq7A==",
+      "license": "Apache-2.0"
+    },
     "node_modules/js-tokens": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -1551,6 +1559,12 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/qrcode-generator": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/qrcode-generator/-/qrcode-generator-2.0.4.tgz",
+      "integrity": "sha512-mZSiP6RnbHl4xL2Ap5HfkjLnmxfKcPWpWe/c+5XxCuetEenqmNFf1FH/ftXPCtFG5/TDobjsjz6sSNL0Sr8Z9g==",
+      "license": "MIT"
+    },
     "node_modules/react": {
       "version": "18.3.1",
       "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",

web/package.json

@@ -7,12 +7,14 @@
     "dev": "vite",
     "build": "tsc --noEmit && vite build",
     "icons": "node scripts/icons.mjs",
-    "test": "node scripts/test-graphcols.mjs"
+    "test": "node scripts/test-graphcols.mjs && node scripts/test-css-imports.mjs && node scripts/test-resolve-path.mjs"
   },
   "dependencies": {
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/addon-web-links": "^0.11.0",
     "@xterm/xterm": "^5.5.0",
+    "hls.js": "^1.7.3",
+    "qrcode-generator": "^2.0.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },

web/scripts/e2e-player.mjs

@@ -0,0 +1,107 @@
+// The Files player, end to end in Chromium against a running hub. Playwright is borrowed from
+// the wedding site.
+//
+//   BASE=http://10.0.0.234:8100 USER=… PASS=… MACHINE=hub FILE=/path/to/video node scripts/e2e-player.mjs
+//
+// Opens FILE in the Files viewer on MACHINE ("hub" for the hub itself), plays it on Auto,
+// checks the 360 view if it is one, seeks into the middle, picks the lowest quality, tries
+// Original, and reads the menu's "Made on …". Changes nothing. DEVICE="Pixel 7" for a phone;
+// TRACE=1 prints every piece asked for. Screenshots land in $SHOTS (default /tmp/hamlab-shots).
+import { createRequire } from 'node:module'
+import { mkdirSync } from 'node:fs'
+const require = createRequire(import.meta.url)
+const { chromium, devices } = require('/home/core/projects/wedding-website/node_modules/playwright')
+
+const { BASE = 'http://10.0.0.234:8100', USER, PASS, MACHINE = 'hub', FILE, DEVICE, TRACE } = process.env
+const SHOTS = process.env.SHOTS ?? '/tmp/hamlab-shots'
+if (!USER || !PASS || !FILE) { console.error('USER, PASS and FILE are required'); process.exit(2) }
+mkdirSync(SHOTS, { recursive: true })
+
+let failed = 0
+const check = (name, ok, extra = '') => { console.log(`${ok ? 'ok  ' : 'FAIL'} ${name}${extra ? ' — ' + extra : ''}`); if (!ok) failed++ }
+const browser = await chromium.launch({ args: ['--autoplay-policy=no-user-gesture-required', '--use-gl=angle', '--use-angle=swiftshader', '--enable-unsafe-swiftshader'] })
+const ctx = await browser.newContext({ ...(DEVICE ? devices[DEVICE] : { viewport: { width: 1280, height: 860 } }), colorScheme: 'dark' })
+check('signs in', (await ctx.request.post(BASE + '/api/login', { data: { username: USER, password: PASS } })).ok())
+const page = await ctx.newPage()
+const errors = []
+page.on('pageerror', (e) => errors.push(String(e)))
+page.on('console', (m) => { if (m.type() === 'error' && !/401|404|favicon/.test(m.text())) errors.push(m.text()) })
+const T0 = Date.now(), trace = []
+const short = (u) => u.replace(/.*\/files\/play\/[0-9a-f]+\//, '')
+page.on('request', (r) => { if (/\/files\/play\/.*\.ts$/.test(r.url())) trace.push(`${((Date.now() - T0) / 1000).toFixed(1)} ask ${short(r.url())}`) })
+page.on('requestfinished', (r) => { if (/\/files\/play\/.*\.ts$/.test(r.url())) trace.push(`${((Date.now() - T0) / 1000).toFixed(1)} got ${short(r.url())}`) })
+const mark = (m) => trace.push(`${((Date.now() - T0) / 1000).toFixed(1)} -- ${m}`)
+
+const dir = FILE.slice(0, FILE.lastIndexOf('/')) || '/', name = FILE.slice(FILE.lastIndexOf('/') + 1)
+await page.goto(`${BASE}/#/${MACHINE}/files/${encodeURIComponent(dir)}`)
+await page.locator('.file-row', { hasText: name }).first().click()
+await page.locator('.vp').waitFor()
+
+const vstate = () => page.evaluate(() => { const v = document.querySelector('.vp video'); return v ? { t: v.currentTime, paused: v.paused, w: v.videoWidth, h: v.videoHeight, rs: v.readyState, d: v.duration } : null })
+async function playingPast(t, ms = 60000) {
+  const t0 = Date.now()
+  while (Date.now() - t0 < ms) {
+    const s = await vstate()
+    if (s && s.t > t && !s.paused && s.rs >= 3) return Date.now() - t0
+    await page.waitForTimeout(200)
+  }
+  return -1
+}
+async function controls() {
+  if (await page.locator('.vp.bare').count()) {
+    const b = await page.locator('.vp').boundingBox()
+    if (DEVICE) await page.touchscreen.tap(b.x + 40, b.y + 40)
+    else await page.mouse.move(b.x + b.width / 2 + Math.random() * 40, b.y + b.height / 3)
+    await page.waitForTimeout(300)
+  }
+}
+
+let took = await playingPast(1)
+check('plays on Auto', took >= 0, `${((Date.now() - T0) / 1000).toFixed(1)} s from opening`)
+await page.waitForTimeout(6000)
+let s = await vstate()
+check('Auto settles on a quality', s?.w > 0, `${s?.w}×${s?.h}; “${await page.locator('.vp-q span').textContent()}”`)
+if (await page.locator('canvas.vp-sphere').count()) {
+  const px = await page.evaluate(() => { const c = document.querySelector('canvas.vp-sphere'); const g = c.getContext('webgl'); const d = new Uint8Array(64); g.readPixels(c.width >> 1, c.height >> 1, 4, 4, g.RGBA, g.UNSIGNED_BYTE, d); return d.reduce((a, b) => a + b, 0) })
+  check('the 360° view draws', px > 0)
+}
+await page.screenshot({ path: `${SHOTS}/h1-auto.png` })
+
+const mid = Math.floor(s.d / 2)
+mark('seek')
+await page.evaluate((m) => { document.querySelector('.vp video').currentTime = m }, mid)
+took = await playingPast(mid + 0.5)
+check('a seek into the middle plays again', took >= 0, `${(took / 1000).toFixed(1)} s`)
+
+await controls()
+await page.locator('.vp-q').click()
+await page.waitForTimeout(2500) // the menu asks the machine what it is doing
+const items = page.locator('.vp-menu button')
+const n = await items.count()
+check('the menu lists Auto, Original and the qualities', n >= 3, (await items.allTextContents()).join(' | '))
+const foot = await page.locator('.vp-menu-f').textContent()
+check('it says where it is made', /Made on \S+/.test(foot), foot)
+await page.screenshot({ path: `${SHOTS}/h2-menu.png` })
+const lowLabel = await items.nth(n - 1).locator('span').nth(1).textContent()
+mark('pick ' + lowLabel)
+const before = (await vstate()).t
+const t0 = Date.now()
+await items.nth(n - 1).click()
+let ok = false
+for (let i = 0; i < 200 && !ok; i++) { await page.waitForTimeout(200); s = await vstate(); ok = s.t > before + 1 && !s.paused && (await page.locator('.vp-q span').textContent()) === lowLabel }
+check(`picking ${lowLabel} switches to it`, ok, `${s.w}×${s.h} after ${((Date.now() - t0) / 1000).toFixed(1)} s`)
+
+await controls()
+await page.locator('.vp-q').click()
+await page.locator('.vp-menu button', { hasText: 'Original' }).click()
+await page.waitForTimeout(4000)
+const label = await page.locator('.vp-q span').textContent()
+const note = await page.locator('.vp-note').count() ? await page.locator('.vp-note').textContent() : ''
+check('Original plays, or falls back to Auto and says so', label === 'Original' || (/^Auto/.test(label) && /can’t play/.test(note)), `${label}${note ? ' — ' + note : ''}`)
+check('still playing', (await playingPast((await vstate()).t + 0.5)) >= 0)
+await page.screenshot({ path: `${SHOTS}/h3-after-original.png` })
+check('no page errors', errors.length === 0, errors.slice(0, 3).join(' / '))
+if (TRACE) console.log(trace.join('\n'))
+await browser.close()
+console.log(failed ? `${failed} failed` : 'all ok')
+process.exit(failed ? 1 : 0)

web/scripts/test-css-imports.mjs

@@ -0,0 +1,20 @@
+// node scripts/test-css-imports.mjs — every stylesheet the UI imports is one somebody has read.
+// A third-party stylesheet usually carries its demo page's global rules (body, *, button); on
+// 2026-10-09 one restyled every button in the app. Add a file here only once its rules are
+// known to touch nothing but its own component.
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+const allowed = new Set(['./styles.css', '@xterm/xterm/css/xterm.css'])
+const src = new URL('../src', import.meta.url).pathname
+const files = []
+const walk = (d) => { for (const n of readdirSync(d)) { const p = join(d, n); if (statSync(p).isDirectory()) { if (n !== 'vendor') walk(p) } else if (/\.(ts|tsx)$/.test(n)) files.push(p) } }
+walk(src)
+const fails = []
+for (const f of files) {
+  for (const m of readFileSync(f, 'utf8').matchAll(/import\s+(?:[^'"]*from\s+)?['"]([^'"]+\.css)['"]/g)) {
+    if (!allowed.has(m[1])) fails.push(`${relative(src, f)} imports ${m[1]}`)
+  }
+}
+if (fails.length) { console.error('css imports: not allowed:\n  ' + fails.join('\n  ')); process.exit(1) }
+console.log(`css imports: ok (${files.length} files)`)

web/scripts/test-graphcols.mjs

@@ -8,7 +8,7 @@ import { join } from 'node:path'
 
 const out = join(mkdtempSync(join(tmpdir(), 'graphcols-')), 'graphcols.mjs')
 buildSync({ entryPoints: [new URL('../src/graphcols.ts', import.meta.url).pathname], outfile: out, format: 'esm', logLevel: 'error' })
-const { columnsOf } = await import(pathToFileURL(out).href)
+const { columnsOf, columnsAt } = await import(pathToFileURL(out).href)
 
 const fails = []
 const check = (ok, what, detail) => { if (!ok) fails.push(what + (detail !== undefined ? ' — ' + JSON.stringify(detail).slice(0, 200) : '')) }
@@ -38,5 +38,28 @@ const wide = columnsOf(base, CAP - 1, CAP, 390)
 check(wide.length === 390 && Math.max(...wide) === 900, 'a box wider than the history is filled, nothing invented', wide.length)
 check(columnsOf([], 0, CAP, COLS).length === 0 && columnsOf([5], 0, 2, 50).length >= 1, 'empty and single-point curves')
 
+// Sliding with the ticks: four ticks to a point (a 250 ms rate, a 1 s stride). Every tick moves
+// the graph left by the same fraction of a column, the newest column grows in from the right, and
+// a column, once finished, keeps its value wherever it has slid to.
+for (const cols of [COLS, 390]) {
+  let v = base.slice(), adv = CAP - 1, prevAt = null, back = 0, jump = 0, held = 0
+  const was = new Map() // a finished column's value, by its number
+  for (let t = 0; t < 4 * 30; t++) {
+    const now = adv + ((t % 4) + 1) / 4
+    const { cols: seen, edge, last } = columnsAt(v, adv, now, CAP, cols)
+    check(edge > 0 && edge <= 1, `edge in (0, 1] (${cols} cols)`, edge)
+    check(seen.length >= cols - 2 && seen.length <= cols + 1, `the box is filled, give or take the sliver (${cols} cols)`, seen.length)
+    const at = last + edge // how far the graph has slid, in columns
+    if (prevAt !== null) { if (at < prevAt - 1e-9) back++; if (at > prevAt + 1 + 1e-9) jump++; if (Math.abs(at - prevAt) < 1e-9) held++ }
+    prevAt = at
+    seen.forEach((x, i) => { const k = last - (seen.length - 1 - i); if (k < last - 1) { if (was.has(k) && was.get(k) !== x) fails.push(`column ${k} changed after it was finished`); was.set(k, x) } })
+    if ((t % 4) === 3) { v.push(10); v.shift(); adv++ }
+  }
+  check(back === 0 && jump === 0, `the graph only slides left, less than a column a tick (${cols} cols)`, { back, jump })
+  check(held < 4 * 30 / 4, `the graph moves on almost every tick, not once a point (${cols} cols)`, held)
+}
+// a point per tick (stride == rate) is the old layout exactly
+check(JSON.stringify(columnsAt(base, CAP - 1, CAP, CAP, COLS).cols.slice(-COLS)) === JSON.stringify(columnsOf(base, CAP - 1, CAP, COLS)), 'columnsOf is columnsAt at a whole point')
+
 if (fails.length) { console.error('graphcols: FAIL\n  ' + fails.join('\n  ')); process.exit(1) }
 console.log('graphcols: ok')

web/scripts/test-resolve-path.mjs

@@ -0,0 +1,16 @@
+// node scripts/test-resolve-path.mjs — the path box resolves like a shell: relative to here,
+// . and .. applied, trailing slashes dropped, never anything but an absolute path.
+import { readFileSync } from 'node:fs'
+const src = readFileSync(new URL('../src/Files.tsx', import.meta.url), 'utf8')
+const m = src.match(/export function resolvePath[\s\S]*?\n}\n/)
+if (!m) { console.error('resolvePath not found'); process.exit(1) }
+const resolvePath = new Function(m[0].replace('export function', 'return function').replace(/: string\[\]/g, '').replace(/: string/g, '') + ' ')()
+const cases = [
+  ['/tank/media', '/x', '/tank/media'], ['/tank/media/', '/x', '/tank/media'], ['', '/here', '/here'], ['   ', '/here', '/here'],
+  ['sub', '/here', '/here/sub'], ['./sub/', '/here', '/here/sub'], ['..', '/a/b', '/a'], ['../..', '/a/b', '/'], ['../../..', '/a', '/'],
+  ['/', '/a', '/'], ['a//b', '/', '/a/b'], ['/tank/./x/../y', '/', '/tank/y'], ['sp ace #1', '/d', '/d/sp ace #1'],
+]
+let bad = 0
+for (const [input, here, want] of cases) { const got = resolvePath(input, here); if (got !== want) { bad++; console.error(`resolvePath(${JSON.stringify(input)}, ${here}) = ${got}, want ${want}`) } }
+if (bad) process.exit(1)
+console.log(`resolve path: ok (${cases.length} cases)`)

web/src/CodeEditor.tsx

@@ -0,0 +1,150 @@
+// A textarea that knows what it is holding: line numbers in a gutter, YAML (or a .env)
+// coloured underneath the text, and the keys a compose file needs — Tab indents by two,
+// Shift+Tab outdents, Enter keeps the indentation of the line above (one step deeper after
+// a key or a list dash), and a phone, whose keyboard has none of those, gets a small bar of
+// them. The text itself stays in a real textarea, so selection, undo and the keyboard are
+// the browser's own; the colour is a <pre> drawn behind it, kept in step line for line.
+import { useEffect, useMemo, useRef, useState, ReactNode } from 'react'
+
+export type Language = 'yaml' | 'env' | 'plain'
+
+interface Props {
+  value: string; onChange: (v: string) => void; language?: Language; className?: string
+  readOnly?: boolean; placeholder?: string; spellCheck?: boolean
+}
+
+const INDENT = '  '
+const coarse = () => typeof window !== 'undefined' && window.matchMedia('(pointer: coarse)').matches
+
+// One line of YAML, split into spans by what each part is. Deliberately shallow: a compose
+// file is keys, scalars, lists and comments; anything cleverer is a parser, which this is not.
+function yamlLine(line: string): ReactNode[] {
+  const out: ReactNode[] = []
+  let i = 0
+  const push = (cls: string, text: string) => { if (text) out.push(cls ? <span key={out.length} className={cls}>{text}</span> : text) }
+  const m = /^(\s*)(-\s+)?/.exec(line)!
+  push('', m[1]); push('y-dash', m[2] ?? ''); i = m[0].length
+  const rest = line.slice(i)
+  if (rest.startsWith('#')) { push('y-comment', rest); return out }
+  // a key: up to the first colon that is followed by a space or the end
+  const key = /^("[^"]*"|'[^']*'|[^\s:#][^:#]*?)(:)(?=\s|$)/.exec(rest)
+  let tail = rest
+  if (key) { push('y-key', key[1]); push('y-colon', ':'); tail = rest.slice(key[0].length) }
+  // the value, with a trailing comment cut off
+  let value = tail, comment = ''
+  const c = / #.*$/.exec(tail) ?? (tail.startsWith('#') ? /#.*$/.exec(tail) : null)
+  if (c) { value = tail.slice(0, c.index); comment = tail.slice(c.index) }
+  const v = value.trim()
+  const lead = value.slice(0, value.length - value.trimStart().length)
+  push('', lead)
+  if (!v) { /* nothing */ }
+  else if (/^(["']).*\1$/.test(v)) push('y-string', v)
+  else if (/^(true|false|yes|no|on|off|null|~)$/i.test(v)) push('y-bool', v)
+  else if (/^[-+]?(\d[\d_]*(\.\d+)?|\.\d+)([eE][-+]?\d+)?$/.test(v) || /^0x[0-9a-fA-F]+$/.test(v)) push('y-number', v)
+  else if (/^[&*!]/.test(v)) push('y-anchor', v)
+  else if (/^[|>][-+]?\d*$/.test(v)) push('y-block', v)
+  else push(key ? 'y-value' : (m[2] ? 'y-value' : ''), v)
+  push('', value.slice(lead.length + v.length))
+  push('y-comment', comment)
+  return out
+}
+
+function envLine(line: string): ReactNode[] {
+  if (/^\s*#/.test(line)) return [<span key="c" className="y-comment">{line}</span>]
+  const m = /^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_.-]*)(=)(.*)$/.exec(line)
+  if (!m) return [line]
+  return [m[1], <span key="k" className="y-key">{m[2]}</span>, <span key="e" className="y-colon">=</span>, <span key="v" className="y-string">{m[4]}</span>]
+}
+
+function highlight(text: string, lang: Language): ReactNode[] {
+  const lines = text.split('\n')
+  const f = lang === 'yaml' ? yamlLine : lang === 'env' ? envLine : (l: string) => [l] as ReactNode[]
+  return lines.map((l, i) => <div key={i} className="code-line">{f(l)}{l === '' ? '​' : ''}</div>)
+}
+
+// setText replaces [start, end) in a textarea with s, through the browser's own edit so Undo
+// still works, and leaves the caret where asked.
+function setText(ta: HTMLTextAreaElement, start: number, end: number, s: string, caret: number | [number, number]) {
+  ta.focus()
+  ta.setSelectionRange(start, end)
+  let done = false
+  try { done = document.execCommand('insertText', false, s) } catch { /* not every browser */ }
+  if (!done || ta.value.slice(start, start + s.length) !== s) { ta.setRangeText(s, start, end, 'end'); ta.dispatchEvent(new Event('input', { bubbles: true })) }
+  if (Array.isArray(caret)) ta.setSelectionRange(caret[0], caret[1]); else ta.setSelectionRange(caret, caret)
+}
+
+export default function CodeEditor({ value, onChange, language = 'yaml', className = '', readOnly, placeholder, spellCheck = false }: Props) {
+  const ta = useRef<HTMLTextAreaElement>(null)
+  const pre = useRef<HTMLPreElement>(null)
+  const gutter = useRef<HTMLDivElement>(null)
+  const [touch] = useState(coarse)
+  const lines = useMemo(() => value.split('\n').length, [value])
+  const painted = useMemo(() => highlight(value, language), [value, language])
+
+  // the colour and the numbers follow the text's own scrolling
+  const sync = () => { const t = ta.current; if (!t) return; if (pre.current) { pre.current.scrollTop = t.scrollTop; pre.current.scrollLeft = t.scrollLeft } if (gutter.current) gutter.current.scrollTop = t.scrollTop }
+  useEffect(sync, [value])
+
+  // lines touched by the selection, for indent and outdent
+  const lineRange = (t: HTMLTextAreaElement) => {
+    const s = t.value.lastIndexOf('\n', t.selectionStart - 1) + 1
+    let e = t.value.indexOf('\n', Math.max(t.selectionEnd - (t.selectionEnd > t.selectionStart && t.value[t.selectionEnd - 1] === '\n' ? 1 : 0), t.selectionStart))
+    if (e < 0) e = t.value.length
+    return [s, e] as const
+  }
+  const indent = (out: boolean) => {
+    const t = ta.current; if (!t || readOnly) return
+    const [s, e] = lineRange(t)
+    const block = t.value.slice(s, e)
+    const sel = t.selectionStart !== t.selectionEnd || block.includes('\n')
+    if (!sel && !out) { const at = t.selectionStart; setText(t, at, at, INDENT, at + INDENT.length); return }
+    const next = block.split('\n').map((l) => (out ? l.replace(/^ {1,2}/, '') : INDENT + l)).join('\n')
+    if (next === block) return
+    const d0 = out ? -(block.length - next.length) : INDENT.length
+    setText(t, s, e, next, sel ? [s, s + next.length] : [Math.max(s, t.selectionStart + d0), Math.max(s, t.selectionStart + d0)])
+  }
+  const comment = () => {
+    const t = ta.current; if (!t || readOnly) return
+    const [s, e] = lineRange(t)
+    const block = t.value.slice(s, e), ls = block.split('\n')
+    const all = ls.every((l) => /^\s*#/.test(l) || !l.trim())
+    const next = ls.map((l) => (!l.trim() ? l : all ? l.replace(/^(\s*)# ?/, '$1') : l.replace(/^(\s*)/, '$1# '))).join('\n')
+    setText(t, s, e, next, [s, s + next.length])
+  }
+  const newline = () => {
+    const t = ta.current; if (!t || readOnly) return
+    const at = t.selectionStart
+    const lineStart = t.value.lastIndexOf('\n', at - 1) + 1
+    const line = t.value.slice(lineStart, at)
+    let ind = /^\s*/.exec(line)![0]
+    // one step deeper after a key or a list item that opens a block
+    if (language === 'yaml' && /(:|^\s*-)\s*(#.*)?$/.test(line) && line.trim() && !/^\s*#/.test(line)) ind += INDENT
+    setText(t, at, t.selectionEnd, '\n' + ind, at + 1 + ind.length)
+  }
+  const onKey = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === 'Tab' && !e.ctrlKey && !e.metaKey && !e.altKey) { e.preventDefault(); indent(e.shiftKey) }
+    else if (e.key === 'Enter' && !e.ctrlKey && !e.metaKey && !e.altKey && !e.shiftKey) { e.preventDefault(); newline() }
+    else if (e.key === '/' && (e.ctrlKey || e.metaKey)) { e.preventDefault(); comment() }
+  }
+
+  return (
+    <div className={'code ' + className + (readOnly ? ' ro' : '')}>
+      <div className="code-gutter" ref={gutter} aria-hidden="true">{Array.from({ length: lines }, (_, i) => <div key={i}>{i + 1}</div>)}</div>
+      <div className="code-body">
+        <pre className="code-paint" ref={pre} aria-hidden="true">{painted}</pre>
+        <textarea ref={ta} className="code-text" value={value} onChange={(e) => onChange(e.target.value)} onScroll={sync} onKeyDown={onKey}
+          readOnly={readOnly} placeholder={placeholder} spellCheck={spellCheck} autoCapitalize="off" autoCorrect="off" autoComplete="off" wrap="off" />
+      </div>
+      {touch && !readOnly && (
+        <div className="code-keys" onMouseDown={(e) => e.preventDefault()}>
+          <button type="button" title="outdent" onClick={() => indent(true)}>⇤</button>
+          <button type="button" title="indent" onClick={() => indent(false)}>⇥</button>
+          <button type="button" title="comment" onClick={comment}>#</button>
+          <button type="button" title="list item" onClick={() => { const t = ta.current; if (t) setText(t, t.selectionStart, t.selectionEnd, '- ', t.selectionStart + 2) }}>-</button>
+          <button type="button" title="colon" onClick={() => { const t = ta.current; if (t) setText(t, t.selectionStart, t.selectionEnd, ': ', t.selectionStart + 2) }}>:</button>
+          <button type="button" title="quotes" onClick={() => { const t = ta.current; if (t) setText(t, t.selectionStart, t.selectionEnd, '"' + t.value.slice(t.selectionStart, t.selectionEnd) + '"', t.selectionEnd + 1) }}>"</button>
+        </div>
+      )}
+    </div>
+  )
+}

web/src/Dashboard.tsx

@@ -1,474 +0,0 @@
-import { ReactNode, useCallback, useEffect, useRef, useState } from 'react'
-import { api, DashPrefs, Sample, Series, Temp } from './api'
-import Sparkline from './Sparkline'
-import { Loading, Spinner, askYes, toast } from './ui'
-import { fmtMs, fmtWindowSec, nextPoint, strideMs, useHistorySec, useRefreshMs } from './prefs'
-import { fetchCatalog, fetchHistories, useSensorStream } from './sensors'
-import { Catalog, MONITOR_HISTORY, MONITOR_SHAPE, Values, mergeValues, sampleOf, seriesOf, stale } from './sampleAdapter'
-import { Widget, WidgetData, WidgetSpec, shapeOf } from './widgets'
-import WidgetPicker from './WidgetPicker'
-
-const MAX = 300
-const S1 = 'var(--s1)', S2 = 'var(--s2)'
-
-// ---- module registry: the customizable blocks, in default order ----
-type Kind = 'tile' | 'card'
-interface Module { id: string; label: string; kind: Kind }
-const MODULES: Module[] = [
-  { id: 'cpu', label: 'CPU', kind: 'tile' },
-  { id: 'mem', label: 'Memory', kind: 'tile' },
-  { id: 'load', label: 'Load', kind: 'tile' },
-  { id: 'uptime', label: 'Uptime', kind: 'tile' },
-  { id: 'temps', label: 'Temperatures', kind: 'card' },
-  { id: 'fans', label: 'Fans', kind: 'card' },
-  { id: 'net', label: 'Network', kind: 'card' },
-  { id: 'disks', label: 'Disks', kind: 'card' },
-  { id: 'fs', label: 'Filesystems', kind: 'card' },
-  { id: 'ups', label: 'UPS', kind: 'card' },
-]
-const byId = (id: string) => MODULES.find((m) => m.id === id)
-
-const DEFAULT_INTERVAL = 2000
-const clampSampler = (ms: number) => Math.min(10000, Math.max(100, ms))
-
-interface Layout { order: string[]; hidden: Set<string>; hiddenItems: Set<string>; intervalMs: number; widgets: WidgetSpec[] }
-
-// Unknown ids are dropped, missing ones appended, so an old saved layout survives new modules.
-function normalize(raw: DashPrefs): Layout {
-  // Saved prefs are whatever some client last wrote; a wrong shape must not take the page down.
-  const list = <T,>(v: unknown): T[] => (Array.isArray(v) ? (v as T[]) : [])
-  const p = { order: list<string>(raw?.order), hidden: list<string>(raw?.hidden), hiddenItems: list<string>(raw?.hiddenItems), widgets: list<WidgetSpec>(raw?.widgets), intervalMs: typeof raw?.intervalMs === 'number' ? raw.intervalMs : undefined }
-  const known = new Set(MODULES.map((m) => m.id))
-  const order = (p.order ?? []).filter((id) => known.has(id))
-  for (const m of MODULES) if (!order.includes(m.id)) order.push(m.id)
-  const iv = p.intervalMs && p.intervalMs >= 100 && p.intervalMs <= 2000 ? p.intervalMs : DEFAULT_INTERVAL
-  return { order, hidden: new Set((p.hidden ?? []).filter((id) => known.has(id))), hiddenItems: new Set(p.hiddenItems ?? []), intervalMs: iv,
-    widgets: (p.widgets ?? []).filter((w) => w && typeof w.id === 'string' && typeof w.sensor === 'string') }
-}
-const toPrefs = (l: Layout): DashPrefs => ({ order: l.order, hidden: [...l.hidden], hiddenItems: [...l.hiddenItems], intervalMs: l.intervalMs, widgets: l.widgets })
-
-// ---- formatting ----
-// A live value either starts a new point or is averaged into the one being built — the same
-// rule the machine itself uses to keep its history, so the tail of a six-hour graph isn't a
-// minute of 2-second samples crushed against the right edge. n is how many values this point
-// has had, including this one.
-function pushPoint(arr: number[], v: number, fresh: boolean, n: number) {
-  if (!fresh && arr.length) { arr[arr.length - 1] += (v - arr[arr.length - 1]) / n; return }
-  arr.push(v)
-  if (arr.length > MAX) arr.shift()
-}
-function pad(arr: number[], n: number) { while (arr.length < n) arr.unshift(0) }
-
-export function fmtBytes(b: number): string {
-  const u = ['B', 'KiB', 'MiB', 'GiB', 'TiB']
-  let i = 0
-  while (b >= 1024 && i < u.length - 1) { b /= 1024; i++ }
-  return `${b < 10 && i > 0 ? b.toFixed(1) : Math.round(b)} ${u[i]}`
-}
-export function fmtRate(bps: number): string {
-  const u = ['B/s', 'kB/s', 'MB/s', 'GB/s']
-  let i = 0
-  while (bps >= 1000 && i < u.length - 1) { bps /= 1000; i++ }
-  return `${bps < 10 && i > 0 ? bps.toFixed(1) : Math.round(bps)} ${u[i]}`
-}
-function fmtUptime(s: number): string {
-  const d = Math.floor(s / 86400), h = Math.floor((s % 86400) / 3600), m = Math.floor((s % 3600) / 60)
-  return d > 0 ? `${d}d ${h}h` : h > 0 ? `${h}h ${m}m` : `${m}m`
-}
-const pct = (v: number) => `${Math.round(v)}%`
-function level(frac: number, warn = 0.85, bad = 0.95): '' | 'warn' | 'bad' { return frac >= bad ? 'bad' : frac >= warn ? 'warn' : '' }
-
-// Chips with many sensors (per-core temps on a big CPU) collapse to one row showing the hottest.
-function collapseTemps(temps: Temp[]): (Temp & { key: string })[] {
-  const byChip = new Map<string, Temp[]>()
-  for (const t of temps) (byChip.get(t.chip) ?? byChip.set(t.chip, []).get(t.chip)!).push(t)
-  const out: (Temp & { key: string })[] = []
-  for (const [chip, list] of byChip) {
-    if (list.length <= 8) { out.push(...list.map((t) => ({ ...t, key: `${t.chip}/${t.label}` }))); continue }
-    const hot = list.reduce((a, b) => (b.c > a.c ? b : a))
-    out.push({ ...hot, label: `${list.length} sensors · hottest ${hot.label}`, chip, key: `${chip}/*` })
-  }
-  return out
-}
-
-// ---- small building blocks ----
-function Meter({ frac, cls }: { frac: number; cls?: string }) {
-  return <div className="meter"><div className={'fill ' + (cls ?? level(frac))} style={{ width: `${Math.min(100, Math.max(0, frac * 100))}%` }} /></div>
-}
-function Legend({ items }: { items: { name: string; color: string }[] }) {
-  return <div className="legend">{items.map((i) => <span key={i.name}><span className="sw" style={{ background: i.color }} />{i.name}</span>)}</div>
-}
-
-interface Edit {
-  on: boolean
-  hideItem: (key: string) => void
-  unhideItem: (key: string) => void
-  hiddenItems: Set<string>
-}
-// In customize mode every row gets a ✕; hidden rows come back as chips under the module.
-function HideBtn({ k, edit }: { k: string; edit: Edit }) {
-  return edit.on ? <button className="hide-item" title="hide" onClick={() => edit.hideItem(k)}>✕</button> : null
-}
-function HiddenChips({ prefix, edit, label }: { prefix: string; edit: Edit; label: (k: string) => string }) {
-  if (!edit.on) return null
-  const keys = [...edit.hiddenItems].filter((k) => k.startsWith(prefix + ':'))
-  if (keys.length === 0) return null
-  return <div className="chips inline">{keys.map((k) => <button key={k} className="chip" title="show again" onClick={() => edit.unhideItem(k)}>+ {label(k.slice(prefix.length + 1))}</button>)}</div>
-}
-
-// ---- module bodies ----
-interface Ctx { s: Sample; h: Series | null; edit: Edit }
-
-function Tile({ label, value, sub, children }: { label: string; value: string; sub?: string; children?: ReactNode }) {
-  return <><div className="label">{label}</div><div className="value">{value}</div>{sub && <div className="sub">{sub}</div>}{children}</>
-}
-
-function body(id: string, { s, h, edit }: Ctx): ReactNode {
-  const shown = (key: string) => !edit.hiddenItems.has(key)
-  const memFrac = s.mem.total ? s.mem.used / s.mem.total : 0
-  switch (id) {
-    case 'cpu':
-      return (
-        <Tile label="CPU" value={pct(s.cpu)} sub={s.cores.length === 0 ? undefined : s.cores.length <= 16 ? `cores ${s.cores.map((c) => Math.round(c)).join(' · ')}` : `${s.cores.length} cores · busiest ${pct(Math.max(...s.cores))}`}>
-          {h && <Sparkline series={[{ name: 'cpu', values: h.cpu, color: S1 }]} max={100} format={pct} height={36} />}
-        </Tile>
-      )
-    case 'mem':
-      return (
-        <Tile label="Memory" value={fmtBytes(s.mem.used)} sub={`of ${fmtBytes(s.mem.total)} · ${pct(memFrac * 100)}${s.swap.total ? ` · swap ${fmtBytes(s.swap.used)}` : ''}`}>
-          {h && <Sparkline series={[{ name: 'used', values: h.mem, color: S1 }]} max={s.mem.total} format={fmtBytes} height={36} />}
-        </Tile>
-      )
-    case 'load':
-      return <Tile label="Load" value={s.load.map((l) => l.toFixed(2)).join('  ')} sub={`1 · 5 · 15 min, ${s.cores.length || '?'} cores`} />
-    case 'uptime':
-      return <Tile label="Uptime" value={fmtUptime(s.uptime)} sub={new Date(s.t).toLocaleTimeString()} />
-
-    case 'temps': {
-      const rows = collapseTemps(s.temps).filter((t) => shown(`temp:${t.key}`))
-      return (
-        <>
-          <h2>Temperatures</h2>
-          {s.temps.length === 0 && <div className="empty">No temperature sensors reported by this host.</div>}
-          {rows.map((t) => {
-            const limit = t.crit || t.max || 100
-            const cls = t.c >= limit - 5 ? 'bad' : t.max && t.c >= t.max - 15 ? 'warn' : ''
-            return (
-              <div className="row" key={t.key}>
-                <span className="k">{t.label}<small>{t.chip}</small></span>
-                <Meter frac={t.c / limit} cls={cls} />
-                <span className="num">{t.c.toFixed(0)}°C{t.max ? ` / ${t.max.toFixed(0)}` : ''}<HideBtn k={`temp:${t.key}`} edit={edit} /></span>
-              </div>
-            )
-          })}
-          <HiddenChips prefix="temp" edit={edit} label={(k) => k.replace('/*', '')} />
-        </>
-      )
-    }
-    case 'fans': {
-      const rows = s.fans.filter((f) => shown(`fan:${f.chip}/${f.label}`))
-      return (
-        <>
-          <h2>Fans</h2>
-          {s.fans.length === 0 && <div className="empty">No fan sensors reported by this host.</div>}
-          {rows.map((f) => (
-            <div className="row" key={`${f.chip}/${f.label}`}>
-              <span className="k">{f.label}<small>{f.chip}</small></span>
-              <span />
-              <span className="num">{f.rpm} rpm<HideBtn k={`fan:${f.chip}/${f.label}`} edit={edit} /></span>
-            </div>
-          ))}
-          <HiddenChips prefix="fan" edit={edit} label={(k) => k} />
-        </>
-      )
-    }
-    case 'net':
-      return (
-        <>
-          <h2>Network</h2>
-          {s.net.filter((x) => shown(`net:${x.iface}`)).map((x) => (
-            <div className="sub-card" key={x.iface}>
-              <div className="sub-head">
-                <span className={'dot ' + (x.up ? 'ok' : '')} />
-                <span>{x.iface}</span>
-                {!x.up && <span className="muted small">down</span>}
-                <span className="spacer" />
-                {x.up && <span className="num">↓ {fmtRate(x.rx_bps)}  ↑ {fmtRate(x.tx_bps)}</span>}
-                <HideBtn k={`net:${x.iface}`} edit={edit} />
-              </div>
-              {x.up && h?.net[x.iface] && (
-                <Sparkline series={[{ name: 'rx', values: h.net[x.iface].rx, color: S1 }, { name: 'tx', values: h.net[x.iface].tx, color: S2 }]} format={fmtRate} />
-              )}
-              {x.up && <div className="legend">
-                <span><span className="sw" style={{ background: S1 }} />rx · {fmtBytes(x.rx_total)} total</span>
-                <span><span className="sw" style={{ background: S2 }} />tx · {fmtBytes(x.tx_total)} total</span>
-              </div>}
-            </div>
-          ))}
-          <HiddenChips prefix="net" edit={edit} label={(k) => k} />
-        </>
-      )
-    case 'disks':
-      return (
-        <>
-          <h2>Disks</h2>
-          {s.disks.length === 0 && <div className="empty">No block devices found.</div>}
-          {s.disks.filter((d) => shown(`disk:${d.name}`)).map((d) => (
-            <div className="sub-card" key={d.name}>
-              <div className="sub-head">
-                <span>{d.name}</span>
-                <span className="model">{d.model}</span>
-                <span className="spacer" />
-                <span className="num">{fmtBytes(d.size)} · {d.temp ? `${d.temp.toFixed(0)}°C · ` : ''}{pct(d.util_pct)} busy</span>
-                <HideBtn k={`disk:${d.name}`} edit={edit} />
-              </div>
-              <div className="sub-head num">read {fmtRate(d.read_bps)}<span className="spacer" />write {fmtRate(d.write_bps)}</div>
-              {h?.disk[d.name] && (
-                <Sparkline series={[{ name: 'read', values: h.disk[d.name].r, color: S1 }, { name: 'write', values: h.disk[d.name].w, color: S2 }]} format={fmtRate} />
-              )}
-              <Legend items={[{ name: 'read', color: S1 }, { name: 'write', color: S2 }]} />
-            </div>
-          ))}
-          <HiddenChips prefix="disk" edit={edit} label={(k) => k} />
-        </>
-      )
-    case 'fs':
-      return (
-        <>
-          <h2>Filesystems</h2>
-          {s.fs.filter((f) => shown(`fs:${f.mount}`)).map((f) => (
-            <div className="row" key={f.mount}>
-              <span className="k">{f.mount}<small>{f.type}</small></span>
-              {f.size ? <Meter frac={f.used / f.size} /> : <span className="muted">unreachable</span>}
-              <span className="num">{f.size ? `${fmtBytes(f.used)} / ${fmtBytes(f.size)}` : ''}<HideBtn k={`fs:${f.mount}`} edit={edit} /></span>
-            </div>
-          ))}
-          <HiddenChips prefix="fs" edit={edit} label={(k) => k} />
-        </>
-      )
-    case 'ups':
-      return (
-        <>
-          <h2>UPS</h2>
-          {!s.ups && <div className="empty">No UPS daemon found (looks for pwrstat, NUT upsc, or apcaccess).</div>}
-          {s.ups && (
-            <>
-              <div className="sub-head">
-                <span className={'dot ' + (s.ups.on_battery ? 'bad' : 'ok')} />
-                <span>{s.ups.state} · {s.ups.source}</span>
-                <span className="spacer" />
-                <span className="model">{s.ups.model} · {s.ups.driver}</span>
-              </div>
-              <div className="row"><span className="k">Battery</span><Meter frac={s.ups.battery_pct / 100} cls={s.ups.battery_pct < 20 ? 'bad' : s.ups.battery_pct < 50 ? 'warn' : ''} /><span className="num">{pct(s.ups.battery_pct)} · {s.ups.runtime_min} min</span></div>
-              <div className="row"><span className="k">Load</span><Meter frac={s.ups.load_pct / 100} /><span className="num">{s.ups.load_w} W · {pct(s.ups.load_pct)}</span></div>
-              <div className="row"><span className="k">Voltage</span><span /><span className="num">in {s.ups.in_v} V · out {s.ups.out_v} V</span></div>
-              {s.ups.last_event && <div className="row"><span className="k">Last event</span><span className="num" style={{ gridColumn: '2 / 4', whiteSpace: 'normal' }}>{s.ups.last_event}</span></div>}
-            </>
-          )}
-        </>
-      )
-  }
-  return null
-}
-
-// ---- the dashboard ----
-export default function Dashboard() {
-  const [latest, setLatest] = useState<Sample | null>(null)
-  const [err, setErr] = useState('')
-  const [layout, setLayout] = useState<Layout>(() => normalize({}))
-  const [editing, setEditing] = useState(false)
-  const [loaded, setLoaded] = useState(false)
-  const [saving, setSaving] = useState<'' | 'saving' | 'saved'>('')
-  const savedTimer = useRef<number | undefined>(undefined)
-  const hist = useRef<Series | null>(null)
-  const saveTimer = useRef<number | undefined>(undefined)
-  const refreshMs = useRefreshMs()
-  const historySec = useHistorySec()
-
-  // Persist layout changes server-side (debounced) so every device sees the same dashboard.
-  const update = useCallback((fn: (l: Layout) => Layout) => {
-    setLayout((prev) => {
-      const next = fn(prev)
-      clearTimeout(saveTimer.current)
-      setSaving('saving')
-      saveTimer.current = window.setTimeout(async () => {
-        try {
-          await api.saveDashPrefs(toPrefs(next))
-          setSaving('saved')
-          clearTimeout(savedTimer.current)
-          savedTimer.current = window.setTimeout(() => setSaving(''), 1500)
-        } catch (e) { setSaving(''); toast(`layout not saved — ${e instanceof Error ? e.message : 'failed'}`, 'err') }
-      }, 300)
-      return next
-    })
-  }, [])
-
-  useEffect(() => {
-    let stop = false
-    api.dashPrefs().then((p) => { if (!stop) { setLayout(normalize(p)); setLoaded(true) } }).catch(() => setErr('could not load layout'))
-    return () => { stop = true }
-  }, [])
-
-  // Everything on this page comes from the sensor API: the catalog for names, labels and
-  // thresholds; one batch of histories to seed the curves; one stream for the values.
-  const catalog = useRef<Catalog>(new Map())
-  const refetching = useRef(false)
-  const binN = useRef(1) // values averaged into the point currently being built
-  const lastPush = useRef(0) // when that point was started, by this browser's clock
-  const stock = useSensorStream<unknown[]>(MONITOR_SHAPE, { full: false, everyMs: refreshMs })
-  const seed = useCallback(async () => {
-    try {
-      catalog.current = new Map((await fetchCatalog()).map((x) => [x.id, x]))
-      hist.current = seriesOf(await fetchHistories(MONITOR_HISTORY), catalog.current)
-      lastPush.current = Date.now(); binN.current = 1
-      setErr('')
-    } catch (e) { setErr(e instanceof Error ? e.message : 'failed') }
-  }, [])
-  useEffect(() => { seed() }, [seed, stock.resumed]) // on load, and again after the page was hidden: the curves have a gap to refill
-  useEffect(() => {
-    if (!stock.data || catalog.current.size === 0) return
-    const v: Values = mergeValues(stock.data)
-    if (stale(v, catalog.current) && !refetching.current) { // something appeared (a disk, an interface): learn its labels
-      refetching.current = true
-      fetchCatalog().then((c) => { catalog.current = new Map(c.map((x) => [x.id, x])) }).catch(() => {}).finally(() => window.setTimeout(() => { refetching.current = false }, 10000))
-    }
-    const s = sampleOf(v, catalog.current)
-    const h = hist.current
-    if (h) {
-      // The stride is timed on this clock alone (lastPush), never against the history's own
-      // timestamps: those are the machine's, and a viewer whose clock runs minutes slow would
-      // otherwise wait those minutes before its curves gained a point.
-      const np = nextPoint(s.t, h.t.length === 0 ? 0 : lastPush.current, strideMs(historySec, refreshMs), refreshMs)
-      const fresh = np.fresh
-      lastPush.current = np.start
-      binN.current = fresh ? 1 : binN.current + 1
-      if (fresh) pushPoint(h.t, s.t, true, 1)
-      const n = h.t.length
-      // a curve that has no point in this one yet starts one, whatever the others are doing:
-      // an interface or disk that appeared mid-point must still line up with the time axis
-      const push = (arr: number[], x: number) => pushPoint(arr, x, fresh || arr.length < n, binN.current)
-      push(h.cpu, s.cpu); push(h.mem, s.mem.used)
-      for (const x of s.net) {
-        const c = (h.net[x.iface] ??= { rx: [], tx: [] })
-        pad(c.rx, n - 1); pad(c.tx, n - 1); push(c.rx, x.rx_bps); push(c.tx, x.tx_bps)
-      }
-      for (const d of s.disks) {
-        const c = (h.disk[d.name] ??= { r: [], w: [], u: [] })
-        pad(c.r, n - 1); pad(c.w, n - 1); pad(c.u, n - 1); push(c.r, d.read_bps); push(c.w, d.write_bps); push(c.u, d.util_pct)
-      }
-      for (const t of s.temps) {
-        const c = (h.temp[`${t.chip}/${t.label}`] ??= [])
-        pad(c, n - 1); push(c, t.c)
-      }
-    }
-    setLatest(s)
-  }, [stock.data, historySec, refreshMs])
-  useEffect(() => { if (stock.error && !latest) setErr(stock.error) }, [stock.error, latest])
-
-  // The sampler on this machine follows the global rate (clamped to what it supports).
-  useEffect(() => {
-    if (!loaded) return
-    const want = clampSampler(refreshMs)
-    if (layout.intervalMs !== want) update((l) => ({ ...l, intervalMs: want }))
-  }, [refreshMs, loaded]) // eslint-disable-line react-hooks/exhaustive-deps
-
-  // Custom widgets are fed by one shaped query over the sensor stream — the same API any outside dashboard uses.
-  const [picking, setPicking] = useState(false)
-  const [editingWidget, setEditingWidget] = useState<WidgetSpec | null>(null)
-  const live = useSensorStream<Record<string, WidgetData>>(shapeOf(layout.widgets))
-
-  if (!latest) return <div className="dash">{err ? <div className="error">{err}</div> : <Loading label="Collecting metrics…" />}</div>
-
-  const edit: Edit = {
-    on: editing,
-    hiddenItems: layout.hiddenItems,
-    hideItem: (k) => update((l) => ({ ...l, hiddenItems: new Set([...l.hiddenItems, k]) })),
-    unhideItem: (k) => update((l) => { const s = new Set(l.hiddenItems); s.delete(k); return { ...l, hiddenItems: s } }),
-  }
-  const ctx: Ctx = { s: latest, h: hist.current, edit }
-  // Modules with nothing to show on this host (no fans, no UPS…) stay out of the way unless customizing.
-  const empty = (id: string) => (id === 'fans' && latest.fans.length === 0) || (id === 'ups' && !latest.ups) || (id === 'temps' && latest.temps.length === 0) || (id === 'disks' && latest.disks.length === 0)
-  const visible = (kind: Kind) => layout.order.filter((id) => byId(id)?.kind === kind && !layout.hidden.has(id) && (editing || !empty(id)))
-  const hiddenMods = layout.order.filter((id) => layout.hidden.has(id))
-
-  // Move a module past its nearest same-kind neighbour (tiles stay with tiles, cards with cards).
-  const move = (id: string, dir: -1 | 1) => update((l) => {
-    const kind = byId(id)!.kind
-    const same = l.order.filter((x) => byId(x)?.kind === kind && !l.hidden.has(x))
-    const i = same.indexOf(id), j = i + dir
-    if (j < 0 || j >= same.length) return l
-    const order = [...l.order]
-    const a = order.indexOf(id), b = order.indexOf(same[j])
-    ;[order[a], order[b]] = [order[b], order[a]]
-    return { ...l, order }
-  })
-  const hideMod = (id: string) => update((l) => ({ ...l, hidden: new Set([...l.hidden, id]) }))
-  const showMod = (id: string) => update((l) => { const s = new Set(l.hidden); s.delete(id); return { ...l, hidden: s } })
-  const reset = async () => { if (await askYes(layout.widgets.length ? `Reset the layout and remove ${layout.widgets.length} custom widget${layout.widgets.length > 1 ? 's' : ''}?` : 'Reset the layout to the default?')) update(() => normalize({})) }
-
-  const tools = (id: string, kind: Kind) => {
-    if (!editing) return null
-    const same = visible(kind), i = same.indexOf(id)
-    return (
-      <div className="mod-tools">
-        <button title="move up" disabled={i === 0} onClick={() => move(id, -1)}>▲</button>
-        <button title="move down" disabled={i === same.length - 1} onClick={() => move(id, 1)}>▼</button>
-        <button title="hide module" onClick={() => hideMod(id)}>hide</button>
-      </div>
-    )
-  }
-
-  return (
-    <div className={'dash' + (editing ? ' editing' : '')}>
-      <div className="dash-bar">
-        {err && <span className="error">{err}</span>}
-        {editing ? <span className="hint">last {fmtWindowSec(historySec)} · ▲▼ reorder · ✕ hide · refresh rate is in Settings</span>
-          : <span className="hint">last {fmtWindowSec(historySec)} · {fmtMs(latest.interval_ms || layout.intervalMs)}</span>}
-        <span className="spacer" />
-        {saving === 'saving' && <span className="saved"><Spinner /> saving</span>}
-        {saving === 'saved' && <span className="saved">saved ✓</span>}
-        {editing && <button className="btn" onClick={reset}>Reset</button>}
-        <button className={'btn' + (editing ? ' on' : '')} disabled={!loaded} title={loaded ? '' : 'layout not loaded'} onClick={() => setEditing(!editing)}>{editing ? 'Done' : 'Customize'}</button>
-      </div>
-
-      {visible('tile').length > 0 && (
-        <div className="kpis">
-          {visible('tile').map((id) => <div className="tile" key={id}>{tools(id, 'tile')}{body(id, ctx)}</div>)}
-        </div>
-      )}
-      {(layout.widgets.length > 0 || editing) && (
-        <div className="kpis widgets">
-          {layout.widgets.map((w, i) => (
-            <div className={'tile w-' + w.type} key={w.id}>
-              {editing && (
-                <div className="mod-tools">
-                  <button title="move left" disabled={i === 0} onClick={() => update((l) => { const a = [...l.widgets]; [a[i - 1], a[i]] = [a[i], a[i - 1]]; return { ...l, widgets: a } })}>◀</button>
-                  <button title="move right" disabled={i === layout.widgets.length - 1} onClick={() => update((l) => { const a = [...l.widgets]; [a[i + 1], a[i]] = [a[i], a[i + 1]]; return { ...l, widgets: a } })}>▶</button>
-                  <button title="change its sensor, type or title" onClick={() => setEditingWidget(w)}>edit</button>
-                  <button title="remove widget" onClick={() => update((l) => ({ ...l, widgets: l.widgets.filter((x) => x.id !== w.id) }))}>remove</button>
-                </div>
-              )}
-              <Widget spec={w} data={live.data ? live.data[w.id] : undefined} />
-            </div>
-          ))}
-          {editing && <button className="tile add-widget" onClick={() => setPicking(true)}>+ Add widget</button>}
-          {live.error && !live.data && layout.widgets.length > 0 && <div className="notice attn" style={{ gridColumn: '1 / -1' }}>The widgets' stream isn't answering: {live.error}.</div>}
-        </div>
-      )}
-      {editingWidget && <WidgetPicker initial={editingWidget} onClose={() => setEditingWidget(null)} onAdd={(w) => { update((l) => ({ ...l, widgets: l.widgets.map((x) => (x.id === w.id ? w : x)) })); setEditingWidget(null) }} />}
-      {picking && <WidgetPicker onClose={() => setPicking(false)} onAdd={(w) => { update((l) => ({ ...l, widgets: [...l.widgets, w] })); setPicking(false) }} />}
-      {visible('card').length > 0 && (
-        <div className="cards">
-          {visible('card').map((id) => <section className="card" key={id}>{tools(id, 'card')}{body(id, ctx)}</section>)}
-        </div>
-      )}
-
-      {editing && hiddenMods.length > 0 && (
-        <div className="card">
-          <h2>Hidden modules</h2>
-          <div className="chips">{hiddenMods.map((id) => <button key={id} className="chip" onClick={() => showMod(id)}>+ {byId(id)!.label}</button>)}</div>
-        </div>
-      )}
-    </div>
-  )
-}

web/src/Disks.tsx

@@ -1,8 +1,8 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
-import { api, SmartInfo, StorageDevice, ZFSInfo, ZFSSnapshot } from './api'
-import { fmtBytes, fmtRate } from './Dashboard'
+import { api, SmartInfo, StorageDevice } from './api'
+import { fmtBytes, fmtRate } from './fmt'
 import TaskOutput from './TaskOutput'
-import { Btn, Loading, Spinner, askText, toast } from './ui'
+import { askText, Btn, Loading, Meter, Spinner, toast } from './ui'
 import { useRefreshMs } from './prefs'
 import { Sensor, useSensorStream } from './sensors'
 
@@ -11,10 +11,6 @@ const KIND: Record<string, string> = { nvme: 'NVMe', ssd: 'SSD', hdd: 'HDD', usb
 const hours = (h: number) => (h >= 24 * 365 ? `${(h / 8760).toFixed(1)} y` : h >= 48 ? `${Math.round(h / 24)} d` : `${h} h`)
 const ago = (ms: number) => { const s = (Date.now() - ms) / 1000; return s < 3600 ? `${Math.round(s / 60)}m ago` : s < 86400 ? `${Math.round(s / 3600)}h ago` : `${Math.round(s / 86400)}d ago` }
 
-function Meter({ frac, cls }: { frac: number; cls?: string }) {
-  const c = cls ?? (frac >= 0.95 ? 'bad' : frac >= 0.85 ? 'warn' : '')
-  return <div className="meter"><div className={'fill ' + c} style={{ width: `${Math.min(100, Math.max(0, frac * 100))}%` }} /></div>
-}
 
 // ---- SMART panel ----
 function SmartPanel({ dev, rotational }: { dev: string; rotational: boolean }) {
@@ -109,82 +105,9 @@ function DeviceCard({ d, live, forceOpen }: { d: StorageDevice; live?: { read_bp
   )
 }
 
-// ---- ZFS ----
-function PoolCard({ p, onChanged }: { p: ZFSInfo['pools'][number]; onChanged: () => void }) {
-  const scrubbing = /scrub in progress/i.test(p.scan ?? '')
-  const paused = /scrub paused/i.test(p.scan ?? '')
-  const [cfg, setCfg] = useState(false)
-  const act = (a: 'start' | 'pause' | 'stop') => async () => {
-    try { await api.zfsScrub(p.name, a); toast(`scrub ${a}: ok`); onChanged() } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') }
-  }
-  return (
-    <section className="card">
-      <div className="sub-head">
-        <span className={'dot ' + (p.health === 'ONLINE' ? 'ok' : p.health === 'DEGRADED' ? 'warn' : 'bad')} />
-        <span className="dname">{p.name}</span>
-        <span className="badge">{p.health}</span>
-        <span className="spacer" />
-        <span className="num">{fmtBytes(p.alloc)} / {fmtBytes(p.size)} · {p.cap}%</span>
-      </div>
-      <Meter frac={p.cap / 100} cls={p.cap >= 90 ? 'bad' : p.cap >= 80 ? 'warn' : ''} />
-      <div className="props" style={{ marginTop: 8 }}>
-        <div><span className="k">Free</span><span>{fmtBytes(p.free)} · fragmentation {p.frag}% · dedup {p.dedup}</span></div>
-        {p.scan && <div><span className="k">Scan</span><span style={{ whiteSpace: 'normal' }}>{p.scan}</span></div>}
-        {p.errors && <div><span className="k">Errors</span><span className={p.errors.startsWith('No known') ? '' : 'warn-text'}>{p.errors}</span></div>}
-      </div>
-      <div className="svc-actions">
-        {!scrubbing && <Btn className="btn" confirm={`Start a scrub of ${p.name}? It reads the whole pool and can take many hours.`} onClick={act('start')}>{paused ? 'Resume scrub' : 'Scrub'}</Btn>}
-        {scrubbing && <Btn className="btn" onClick={act('pause')}>Pause scrub</Btn>}
-        {(scrubbing || paused) && <Btn className="btn" confirm="Stop the scrub?" onClick={act('stop')}>Stop scrub</Btn>}
-        <button className="btn" onClick={() => setCfg(!cfg)}>{cfg ? 'Hide vdevs' : 'Vdevs'}</button>
-      </div>
-      {cfg && <pre className="unit-file">{p.config}</pre>}
-    </section>
-  )
-}
-
-function DatasetRow({ d, onChanged }: { d: ZFSInfo['datasets'][number]; onChanged: () => void }) {
-  const [snaps, setSnaps] = useState<ZFSSnapshot[] | null>(null)
-  const [open, setOpen] = useState(false)
-  async function toggle() {
-    setOpen(!open)
-    if (!open && !snaps) { try { setSnaps(await api.zfsSnapshots(d.name)) } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err'); setSnaps([]) } }
-  }
-  async function snapshot() {
-    const def = 'hamlab-' + new Date().toISOString().slice(0, 16).replace(/[-:T]/g, '').replace(/(\d{8})(\d{4})/, '$1-$2')
-    const name = await askText(`Snapshot name for ${d.name}@`, def)
-    if (!name) return
-    try { await api.zfsSnapshot(d.name, name.trim()); toast(`${d.name}@${name.trim()} created`); setSnaps(null); onChanged() }
-    catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') }
-  }
-  const depth = d.name.split('/').length - 1
-  return (
-    <>
-      <div className="ds-row" style={{ paddingLeft: 12 + depth * 16 }}>
-        <span className="ds-name" onClick={toggle}><span className="chev">{open ? '▾' : '▸'}</span>{d.name.split('/').pop()}{d.type === 'volume' && <span className="badge">zvol</span>}</span>
-        <span className="num">{fmtBytes(d.used)}</span>
-        <span className="num muted">{fmtBytes(d.refer)}</span>
-        <span className="num muted">{d.used_by_snapshots ? fmtBytes(d.used_by_snapshots) : '—'}</span>
-        <span className="num muted">{d.snapshots}</span>
-        <span className="num muted">{d.compressratio}</span>
-        <span className="ds-mount muted">{d.mount}</span>
-      </div>
-      {open && (
-        <div className="ds-snaps">
-          <div className="svc-actions"><Btn className="btn" onClick={snapshot}>Snapshot now</Btn><span className="muted">avail {fmtBytes(d.avail)}</span></div>
-          {snaps === null ? <div className="muted"><Spinner /> listing…</div> : snaps.length === 0 ? <div className="muted">No snapshots.</div> : (
-            <div className="snap-list">{snaps.slice().reverse().map((s) => <div key={s.name} className="snap"><span className="mono">{s.name.split('@')[1]}</span><span className="num muted">{new Date(s.created).toLocaleString()} · {fmtBytes(s.used)}</span></div>)}</div>
-          )}
-        </div>
-      )}
-    </>
-  )
-}
-
 // ---- page ----
 export default function Disks() {
   const [devs, setDevs] = useState<StorageDevice[] | null>(null)
-  const [zfs, setZfs] = useState<ZFSInfo | null>(null)
   const [hasSmart, setHasSmart] = useState(true)
   const [err, setErr] = useState('')
   const [task, setTask] = useState<string | null>(null)
@@ -194,7 +117,7 @@ export default function Disks() {
   const load = useCallback(async () => {
     try {
       const r = await api.storage()
-      setDevs(r.devices); setZfs(r.zfs); setHasSmart(r.smartctl); setErr('')
+      setDevs(r.devices); setHasSmart(r.smartctl); setErr('')
     } catch (e) { setErr(e instanceof Error ? e.message : 'failed') }
   }, [])
   useEffect(() => { load() }, [load])
@@ -237,18 +160,6 @@ export default function Disks() {
         {devs.map((d) => <DeviceCard key={d.name} d={d} live={liveFor(d)} forceOpen={allSmart ? true : null} />)}
       </div>
 
-      <div className="dash-bar"><h2 className="section">ZFS</h2></div>
-      {zfs && !zfs.available && <div className="notice">{zfs.message || 'No ZFS pools on this host.'}</div>}
-      {zfs?.available && zfs.pools.length === 0 && <div className="notice">ZFS is present but no pools are imported.</div>}
-      {zfs?.available && zfs.pools.length > 0 && (
-        <>
-          <div className="cards">{zfs.pools.map((p) => <PoolCard key={p.name} p={p} onChanged={load} />)}</div>
-          <section className="card datasets">
-            <div className="ds-row head"><span>Dataset</span><span className="num">Used</span><span className="num">Refer</span><span className="num">In snaps</span><span className="num">Snaps</span><span className="num">Ratio</span><span>Mount</span></div>
-            {zfs.datasets.map((d) => <DatasetRow key={d.name} d={d} onChanged={load} />)}
-          </section>
-        </>
-      )}
     </div>
   )
 }

web/src/Docker.tsx

@@ -1,67 +1,120 @@
 // Docker: containers grouped by the stack that deployed them, with start / stop / restart,
 // logs that follow, and inspect — then images, volumes and networks. Live CPU and memory
 // come from the same container sensors everything else uses.
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { api, DockerContainer, DockerInfo, ImageCheck, Stack, StackDiff } from './api'
+import { FormEvent, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { api, DockerContainer, DockerEvent, DockerHealth, DockerInfo, DockerLogLine, ImageCheck, MachineUpdates, Stack, StackDiff, UpdateJob, UpdateJobRow, wsURLPath } from './api'
 import TaskOutput from './TaskOutput'
 import StackNew, { DupFrom } from './StackNew'
-import { Sensor, fmtValue, useSensorStream } from './sensors'
+import CodeEditor from './CodeEditor'
+import { Sensor, fetchHistories, fmtValue, useSensorStream } from './sensors'
 import { useHashSel } from './hashsel'
-import { useRefreshMs } from './prefs'
-import { askText, askYes, Btn, CloseBtn, Loading, setUnsaved, toast } from './ui'
+import { fmtWindowSec, useHistorySec, useRefreshMs } from './prefs'
+import Sparkline from './Sparkline'
+import { fmtBytes } from './fmt'
+import { describeCron } from './crontext'
+import { askText, askYes, Btn, CloseBtn, Loading, setUnsaved, toast, useEscape } from './ui'
 
-type Tab = 'containers' | 'stacks' | 'images' | 'volumes' | 'networks'
+type Tab = 'containers' | 'stacks' | 'updates' | 'images' | 'volumes' | 'networks'
 const dot = (c: DockerContainer) => (c.state !== 'running' ? (c.state === 'exited' || c.state === 'dead' ? 'bad' : 'warn') : c.health === 'unhealthy' ? 'bad' : c.health === 'starting' ? 'warn' : 'ok')
 const ports = (p: string) => [...new Set(p.split(', ').map((x) => x.replace(/^\[?::\]?:/, '').replace(/^0\.0\.0\.0:/, '').replace(/^[\d.]+:/, '')).filter((x) => x.includes('->')))].join('  ')
 
+// A container's output, followed over a held connection the way the Services tab follows a
+// journal. A reconnect resumes from the last line's timestamp, so a container that restarts
+// — or a phone that slept — doesn't replay what is already on screen.
 function LogView({ id }: { id: string }) {
-  const [lines, setLines] = useState<{ t: string; m: string }[]>([])
+  const [lines, setLines] = useState<DockerLogLine[]>([])
   const [err, setErr] = useState('')
+  const [live, setLive] = useState(false)
   const [follow, setFollow] = useState(true)
+  const [paused, setPaused] = useState(false)
   const box = useRef<HTMLDivElement>(null)
   const last = useRef('')
+  const pausedRef = useRef(false)
+  pausedRef.current = paused
+  const pending = useRef<DockerLogLine[]>([])
+  // What a resume has already shown: `--since` is inclusive, and two lines can share a
+  // timestamp (a container writing to both streams at once), so the boundary is a set of
+  // lines rather than a moment. Bounded — only the lines around a reconnect can repeat.
+  const seen = useRef<{ set: Set<string>; q: string[] }>({ set: new Set(), q: [] })
   useEffect(() => {
-    let stop = false; setLines([]); last.current = ''
-    const tick = async () => {
-      if (stop) return
-      if (document.visibilityState === 'visible') {
-        try {
-          const r = await api.dockerLogs(id, last.current)
-          const fresh = last.current ? r.lines.filter((l) => l.t > last.current) : r.lines
-          if (fresh.length) { last.current = fresh[fresh.length - 1].t || last.current; setLines((old) => [...old, ...fresh].slice(-2000)) }
-          setErr('')
-        } catch (e) { setErr(e instanceof Error ? e.message : 'failed') }
+    setLines([]); setErr(''); setLive(false); last.current = ''; pending.current = []
+    seen.current = { set: new Set(), q: [] }
+    let closed = false
+    let sock: WebSocket | null = null
+    let retry: number | undefined
+    let attempt = 0
+    const connect = () => {
+      if (closed) return
+      const q = last.current ? `since=${encodeURIComponent(last.current)}` : 'n=300'
+      // fixed when the log opens: a reconnect must not follow the console to another machine
+      const s = new WebSocket(wsURLPath(`/api/docker/containers/${encodeURIComponent(id)}/logs/tail?${q}`))
+      sock = s
+      s.onopen = () => { attempt = 0; setLive(true); setErr('') }
+      s.onmessage = (ev) => {
+        const l = JSON.parse(ev.data) as DockerLogLine
+        if (l.t) {
+          const k = l.t + '|' + (l.err ? 'e' : 'o') + '|' + l.m
+          const { set, q } = seen.current
+          if (set.has(k)) return
+          set.add(k); q.push(k)
+          if (q.length > 1000) for (const old of q.splice(0, 500)) set.delete(old)
+          if (l.t > last.current) last.current = l.t
         }
-      window.setTimeout(tick, 2000)
+        if (pausedRef.current) { pending.current.push(l); return }
+        setLines((prev) => (prev.length > 2000 ? [...prev.slice(-1500), l] : [...prev, l]))
       }
-    tick()
-    return () => { stop = true }
+      // a container that has stopped — or was never there — ends the stream at once, so
+      // back off rather than asking Docker the same question twice a second forever
+      s.onclose = () => { if (closed) return; setLive(false); retry = window.setTimeout(connect, Math.min(15000, 1000 * 2 ** attempt++)) }
+      s.onerror = () => { setErr('log stream disconnected'); s.close() }
+    }
+    connect()
+    return () => { closed = true; clearTimeout(retry); sock?.close() }
   }, [id])
-  useEffect(() => { if (follow && box.current) box.current.scrollTop = box.current.scrollHeight }, [lines, follow])
+  // Resume: flush what arrived while paused.
+  useEffect(() => {
+    if (paused || pending.current.length === 0) return
+    const p = pending.current; pending.current = []
+    setLines((prev) => [...prev, ...p].slice(-2000))
+  }, [paused])
+  useEffect(() => { if (follow && !paused && box.current) box.current.scrollTop = box.current.scrollHeight }, [lines, follow, paused])
   return (
     <div className="logs">
-      <div className="logs-bar"><span className="muted">{lines.length} lines</span><span className="spacer" /><button className={'chip' + (follow ? ' on' : '')} onClick={() => setFollow(!follow)}>follow</button><button className="chip" onClick={() => setLines([])}>Clear</button></div>
-      {err && <div className="error">{err}</div>}
+      <div className="logs-bar">
+        <span className={'dot ' + (live ? 'ok' : 'bad')} /> <span className="muted">{live ? 'following' : 'reconnecting…'} · {lines.length} lines{err && ` · ${err}`}</span>
+        <span className="spacer" />
+        <button className={'chip' + (follow ? ' on' : '')} onClick={() => setFollow(!follow)}>follow</button>
+        <button className="chip" onClick={() => setPaused(!paused)}>{paused ? `Resume${pending.current.length ? ` (${pending.current.length})` : ''}` : 'Pause'}</button>
+        <button className="chip" onClick={() => setLines([])}>Clear</button>
+      </div>
       <div className="log-lines" ref={box} onScroll={(e) => { const el = e.currentTarget; if (el.scrollHeight - el.scrollTop - el.clientHeight > 40) setFollow(false) }}>
-        {lines.map((l, i) => <div className="log" key={i}><span className="lt">{l.t ? new Date(l.t).toLocaleTimeString() : ''}</span><span className="lm">{l.m}</span></div>)}
+        {lines.map((l, i) => <div className={'log' + (l.err ? ' err' : '')} key={i}><span className="lt">{l.t ? new Date(l.t).toLocaleTimeString() : ''}</span><span className="lm">{l.m}</span></div>)}
         {lines.length === 0 && !err && <div className="muted small" style={{ padding: 8 }}>No output yet.</div>}
       </div>
     </div>
   )
 }
 
+// What a container is doing, and what can be done to it: its numbers over time, its health
+// checks, what has happened to it lately, a shell inside it, and its limits.
 function Detail({ c, live, onBack, onChanged }: { c: DockerContainer; live: Record<string, Sensor>; onBack: () => void; onChanged: () => void }) {
-  const [tab, setTab] = useState<'logs' | 'inspect'>('logs')
+  const [tab, setTab] = useState<'logs' | 'stats' | 'health' | 'events' | 'inspect'>('logs')
   const [info, setInfo] = useState<Record<string, unknown> | null>(null)
-  useEffect(() => { setInfo(null); if (tab === 'inspect') api.dockerInspect(c.name).then(setInfo).catch((e) => toast(e instanceof Error ? e.message : 'failed', 'err')) }, [tab, c.name])
+  const [limits, setLimits] = useState(false)
+  useEffect(() => { setInfo(null); if (tab === 'inspect' || limits) api.dockerInspect(c.name).then(setInfo).catch((e) => toast(e instanceof Error ? e.message : 'failed', 'err')) }, [tab, limits, c.name])
   const act = (a: 'start' | 'stop' | 'restart' | 'remove') => async () => { try { await api.dockerAction(c.name, a); toast(`${c.name}: ${a} ok`); onChanged() } catch (e) { toast(`${c.name}: ${e instanceof Error ? e.message : 'failed'}`, 'err') } }
   const running = c.state === 'running'
-  const s = (k: string) => live[`container.${c.name.toLowerCase().replace(/[^a-z0-9-]+/g, '_').replace(/^_|_$/g, '')}.${k}`]
+  const seg = c.name.toLowerCase().replace(/[^a-z0-9-]+/g, '_').replace(/^_|_$/g, '')
+  const s = (k: string) => live[`container.${seg}.${k}`]
   const mounts = (info?.mounts as { Source: string; Destination: string; RW: boolean }[] | undefined) ?? []
+  const shell = async () => {
+    try { const t = await api.dockerExec(c.name); toast(`shell open as “${t.name}” on the Terminal tab`); window.dispatchEvent(new CustomEvent('hamlab:terminal', { detail: t.id })) }
+    catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') }
+  }
   return (
     <div className="svc-detail">
       <CloseBtn onClick={onBack} />
-      <div className="svc-head"><button className="btn back" onClick={onBack}>‹ Back</button><span className={'sdot ' + dot(c)} /><span className="dname">{c.name}</span></div>
+      <div className="svc-head"><button className="btn back" onClick={onBack}>‹ Back</button><span className={'sdot ' + dot(c)} /><span className="dname">{c.name}</span>{c.health && c.health !== 'none' && <span className={'badge' + (c.health === 'healthy' ? '' : ' bad')}>{c.health}</span>}</div>
       <div className="props">
         <div><span className="k">Image</span><span className="mono small">{c.image}</span></div>
         <div><span className="k">Status</span><span>{c.status}</span></div>
@@ -72,27 +125,181 @@ function Detail({ c, live, onBack, onChanged }: { c: DockerContainer; live: Reco
       <div className="svc-actions">
         {!running && <Btn className="btn on" onClick={act('start')}>Start</Btn>}
         {!running && <Btn className="btn danger" confirm={`Remove the container ${c.name}? Its image, volumes and bind-mounted data stay; anything written inside the container itself is lost.${c.stack ? ` Deploying the ${c.stack} stack makes it again.` : ''}`} onClick={async () => { await act('remove')(); onBack() }}>Remove</Btn>}
+        {running && <Btn className="btn" onClick={shell}>Shell</Btn>}
         {running && <Btn className="btn" confirm={`Restart ${c.name}?`} onClick={act('restart')}>Restart</Btn>}
+        <Btn className="btn" onClick={() => setLimits(true)}>Limits</Btn>
         {running && <Btn className="btn danger" confirm={`Stop ${c.name}? It stays stopped until something starts it.`} onClick={act('stop')}>Stop</Btn>}
       </div>
-      <div className="tabs"><button className={tab === 'logs' ? 'on' : ''} onClick={() => setTab('logs')}>Logs</button><button className={tab === 'inspect' ? 'on' : ''} onClick={() => setTab('inspect')}>Inspect</button></div>
+      <div className="tabs">
+        <button className={tab === 'logs' ? 'on' : ''} onClick={() => setTab('logs')}>Logs</button>
+        <button className={tab === 'stats' ? 'on' : ''} onClick={() => setTab('stats')}>Stats</button>
+        <button className={tab === 'health' ? 'on' : ''} onClick={() => setTab('health')}>Health</button>
+        <button className={tab === 'events' ? 'on' : ''} onClick={() => setTab('events')}>Events</button>
+        <button className={tab === 'inspect' ? 'on' : ''} onClick={() => setTab('inspect')}>Inspect</button>
+      </div>
       {tab === 'logs' && <LogView id={c.name} />}
+      {tab === 'stats' && <Stats seg={seg} live={live} />}
+      {tab === 'health' && <Health id={c.name} />}
+      {tab === 'events' && <Events id={c.name} />}
       {tab === 'inspect' && (!info ? <Loading label="Inspecting…" /> : (
-        <div className="props">
+        <div className="props stacked">
           <div><span className="k">Restarts</span><span>{String(info.restart || 'no')} policy · restarted {String(info.restarts ?? 0)}×</span></div>
           <div><span className="k">Network</span><span className="mono small">{Object.keys((info.networks as object) ?? {}).join(', ') || String(info.network_mode)}</span></div>
           {Number(info.memory_limit) > 0 && <div><span className="k">Mem limit</span><span>{fmtValue(Number(info.memory_limit), 'B')}</span></div>}
           {!!info.error && <div><span className="k">Error</span><span className="warn-text">{String(info.error)}</span></div>}
           {!!info.compose_file && <div><span className="k">Compose</span><span className="mono small">{String(info.compose_file)}</span></div>}
-          {mounts.map((m) => <div key={m.Destination}><span className="k">Mount</span><span className="mono small">{m.Source} → {m.Destination}{m.RW ? '' : ' (ro)'}</span></div>)}
-          <div><span className="k">Env</span><span className="mono small muted">{((info.env_names as string[]) ?? []).join('  ')} <span className="muted">(names only)</span></span></div>
+          {mounts.length > 0 && <div><span className="k">Mounts</span><span className="mono small">{mounts.map((m) => <div key={m.Destination}>{m.Source} → {m.Destination}{m.RW ? '' : ' (read only)'}</div>)}</span></div>}
+          <div><span className="k">Env <span className="muted">names only</span></span><span className="mono small muted">{((info.env_names as string[]) ?? []).join('  ') || '—'}</span></div>
         </div>
       ))}
+      {limits && <LimitsDialog c={c} info={info} onClose={() => setLimits(false)} onSaved={() => { setLimits(false); onChanged() }} />}
+    </div>
+  )
+}
+
+// CPU and memory over time, from the container sensors the sampler already keeps.
+function Stats({ seg, live }: { seg: string; live: Record<string, Sensor> }) {
+  const [hist, setHist] = useState<{ id: string; t: number[]; v: number[] }[] | null>(null)
+  const historySec = useHistorySec()
+  useEffect(() => {
+    let alive = true
+    fetchHistories(`container.${seg}.cpu,container.${seg}.mem`)
+      .then((h) => { if (alive) setHist(h) })
+      .catch(() => { if (alive) setHist([]) })
+    return () => { alive = false }
+  }, [seg])
+  const css = (n: string) => getComputedStyle(document.documentElement).getPropertyValue(n).trim() || '#3987e5'
+  const of = (k: string) => hist?.find((h) => h.id === `container.${seg}.${k}`)?.v ?? []
+  const cpu = of('cpu'), mem = of('mem')
+  if (hist === null) return <Loading label="Reading the history…" />
+  if (cpu.length < 2 && mem.length < 2) return <div className="notice">No history yet for this container — it is sampled while it runs, so give it a moment.</div>
+  return (
+    <div className="cards">
+      <section className="card">
+        <div className="sub-head"><span className="dname">CPU</span><span className="spacer" /><span className="num">{fmtValue(live[`container.${seg}.cpu`]?.value, '%')} of a core</span></div>
+        <Sparkline series={[{ name: 'cpu', values: cpu, color: css('--s1') }]} format={(v) => `${v.toFixed(1)}%`} height={64} />
+        <div className="muted small">the last {fmtWindowSec(historySec)}</div>
+      </section>
+      <section className="card">
+        <div className="sub-head"><span className="dname">Memory</span><span className="spacer" /><span className="num">{fmtValue(live[`container.${seg}.mem`]?.value, 'B')}</span></div>
+        <Sparkline series={[{ name: 'mem', values: mem, color: css('--s2') }]} format={(v) => fmtBytes(v)} height={64} />
+        <div className="muted small">the last {fmtWindowSec(historySec)}</div>
+      </section>
+    </div>
+  )
+}
+
+// The health check's verdict, and what its last few probes actually said.
+function Health({ id }: { id: string }) {
+  const [h, setH] = useState<DockerHealth | null>(null)
+  const [err, setErr] = useState('')
+  useEffect(() => { setH(null); api.dockerHealth(id).then(setH).catch((e) => setErr(e instanceof Error ? e.message : 'failed')) }, [id])
+  if (err) return <div className="error">{err}</div>
+  if (!h) return <Loading label="Asking…" />
+  if (!h.configured) return <div className="notice">This image defines no health check, so Docker only knows whether the process is running — which it is ({h.state}). A health check is a <span className="mono">healthcheck:</span> block in the compose file.</div>
+  return (
+    <>
+      <div className="props">
+        <div><span className="k">Health</span><span className={h.status === 'healthy' ? '' : 'warn-text'}>{h.status}</span></div>
+        <div><span className="k">State</span><span>{h.state}</span></div>
+        {!!h.failing_streak && <div><span className="k">Failing</span><span className="warn-text">{h.failing_streak} probe{h.failing_streak === 1 ? '' : 's'} in a row</span></div>}
+      </div>
+      <div className="muted small" style={{ marginTop: 8 }}>The last {h.log?.length ?? 0} probes — Docker keeps five.</div>
+      {(h.log ?? []).slice().reverse().map((p, i) => (
+        <section className="card" key={i} style={{ marginTop: 6 }}>
+          <div className="sub-head">
+            <span className={'sdot ' + (p.ExitCode === 0 ? 'ok' : 'bad')} />
+            <span>{new Date(p.Start).toLocaleString()}</span>
+            <span className="spacer" />
+            <span className="muted small">exit {p.ExitCode} · {Math.max(0, new Date(p.End).getTime() - new Date(p.Start).getTime())} ms</span>
+          </div>
+          {p.Output.trim() && <pre className="run-out" style={{ maxHeight: 140 }}>{p.Output.trim()}</pre>}
+        </section>
+      ))}
+    </>
+  )
+}
+
+// What has happened to this container lately, asked of Docker rather than kept here.
+function Events({ id }: { id: string }) {
+  const [ev, setEv] = useState<DockerEvent[] | null>(null)
+  const [kept, setKept] = useState(0)
+  const [since, setSince] = useState('7d')
+  const [err, setErr] = useState('')
+  useEffect(() => { setEv(null); setErr(''); api.dockerEvents(id, since).then((r) => { setEv(r.events); setKept(r.kept) }).catch((e) => setErr(e instanceof Error ? e.message : 'failed')) }, [id, since])
+  const bad = (a: string, h?: string) => /die|kill|oom|destroy/.test(a) || (h !== undefined && h !== 'healthy')
+  return (
+    <>
+      <div className="chips" style={{ marginBottom: 8 }}>
+        {['24h', '7d', '30d'].map((x) => <button key={x} className={'chip' + (since === x ? ' on' : '')} onClick={() => setSince(x)}>{x}</button>)}
+      </div>
+      {err && <div className="error">{err}</div>}
+      {!ev && !err && <Loading label="Asking Docker…" />}
+      {ev && ev.length === 0 && <div className="notice">Nothing for this container in the last {since}. Ham Lab keeps its own record — Docker's own only reaches back a few minutes — so history starts from when this version was installed. {kept} events kept across every container.</div>}
+      {ev && ev.length > 0 && (
+        <div className="snap-list">
+          {ev.map((e, i) => (
+            <div className="snap" key={i}>
+              <span className={bad(e.action, e.health) ? 'warn-text' : ''}>{e.action}{e.health ? `: ${e.health}` : ''}</span>
+              <span className="muted">{new Date(e.t).toLocaleString()}</span>
+              <span className="muted small">{e.exit_code ? `exit ${e.exit_code}` : ''}{e.signal ? ` signal ${e.signal}` : ''}</span>
+              <span />
+              <span />
+            </div>
+          ))}
+        </div>
+      )}
+    </>
+  )
+}
+
+// Memory, CPU and restart policy, changed on the running container. Docker does this live,
+// which is the point — and also the catch, said plainly below.
+function LimitsDialog({ c, info, onClose, onSaved }: { c: DockerContainer; info: Record<string, unknown> | null; onClose: () => void; onSaved: () => void }) {
+  const curMem = Number(info?.memory_limit ?? 0)
+  const [mem, setMem] = useState(curMem > 0 ? String(Math.round(curMem / (1 << 20))) + 'm' : '')
+  const [cpus, setCpus] = useState('')
+  const [restart, setRestart] = useState(String(info?.restart ?? ''))
+  const [err, setErr] = useState('')
+  const [busy, setBusy] = useState(false)
+  useEscape(onClose)
+  const save = async (e: FormEvent) => {
+    e.preventDefault(); setErr(''); setBusy(true)
+    try { await api.dockerLimits(c.name, { memory: mem, cpus, restart }); toast(`${c.name} updated`); onSaved() }
+    catch (e) { setErr(e instanceof Error ? e.message : 'failed'); setBusy(false) }
+  }
+  return (
+    <div className="modal-back" onClick={onClose}>
+      <form className="modal" onClick={(e) => e.stopPropagation()} onSubmit={save}>
+        <h3>Limits for {c.name}</h3>
+        <label className="muted">Memory — 512m, 2g, or 0 for no limit{curMem > 0 ? ` (now ${fmtBytes(curMem)})` : ' (no limit now)'}
+          <input className="mono" value={mem} onChange={(e) => setMem(e.target.value)} placeholder="leave blank to keep" spellCheck={false} />
+        </label>
+        <label className="muted">CPUs — 1.5 means one and a half cores, 0 for no limit
+          <input className="mono" value={cpus} onChange={(e) => setCpus(e.target.value)} placeholder="leave blank to keep" spellCheck={false} />
+        </label>
+        <label className="muted">Restart policy
+          <select value={restart} onChange={(e) => setRestart(e.target.value)}>
+            <option value="">leave as it is</option>
+            {['no', 'on-failure', 'unless-stopped', 'always'].map((p) => <option key={p} value={p}>{p}</option>)}
+          </select>
+        </label>
+        <div className="notice attn">
+          This changes the running container now, without recreating it. It does <b>not</b> edit the
+          compose file{c.stack ? <> — so deploying <b>{c.stack}</b> puts back whatever the file says</> : ''}.
+          Edit the stack to make it stick.
+        </div>
+        {err && <div className="error">{err}</div>}
+        <div className="svc-actions">
+          <button type="submit" className="btn on" disabled={busy || (!mem && !cpus && !restart)}>Apply</button>
+          <span className="spacer" />
+          <button type="button" className="btn" onClick={onClose}>Cancel</button>
+        </div>
+      </form>
     </div>
   )
 }
 
-// A plain line diff (longest common subsequence): compose files are short, so the simple way is fine.
 function lineDiff(a: string, b: string): { s: ' ' | '+' | '-'; t: string }[] {
   const x = a.split('\n'), y = b.split('\n'); const n = x.length, m = y.length
   const L = Array.from({ length: n + 1 }, () => new Uint16Array(m + 1))
@@ -120,6 +327,7 @@ const maskEnv = (text: string) => text.split('\n').map((l) => { const i = l.inde
 
 // One stack: its compose file to edit, and the four things to do with it. Saving validates
 // with compose itself and keeps the previous file beside it; deploying is a separate, asked-for act.
+
 function StackDetail({ name, startTask, onBack, onChanged, onDuplicate }: { name: string; startTask?: string; onBack: () => void; onChanged: () => void; onDuplicate: (from: DupFrom) => void }) {
   const [st, setSt] = useState<Stack | null>(null)
   const [text, setText] = useState(''); const [orig, setOrig] = useState('')
@@ -140,17 +348,17 @@ function StackDetail({ name, startTask, onBack, onChanged, onDuplicate }: { name
     try { const r = await api.deleteStack(name); toast(`${name} deleted — its files are in ${r.trash}`); setUnsaved(''); onChanged(); onBack() } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') }
   }
   const duplicate = async () => { if (!st) return; try { onDuplicate({ name, text: file === 0 ? orig : (await api.stackFile(name, 0)).text, hasEnv: !!st.has_env, files: st.host_files?.length ?? 1 }) } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') } }
-  const run = (a: 'deploy' | 'update' | 'restart' | 'stop' | 'down') => async () => { try { setTask((await api.stackAction(name, a)).id) } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') } }
+  const run = (a: 'deploy' | 'update' | 'recreate' | 'restart' | 'stop' | 'down') => async () => { try { setTask((await api.stackAction(name, a)).id) } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') } }
   if (err && !st) return <div className="svc-detail"><CloseBtn onClick={onBack} /><button className="btn back" onClick={onBack}>‹ Back</button><div className="notice">{err}</div></div>
   if (!st) return <div className="svc-detail"><Loading label="Reading the compose file…" /></div>
   return (
     <div className="svc-detail">
       <CloseBtn onClick={onBack} />
       <div className="svc-head"><button className="btn back" onClick={onBack}>‹ Back</button><span className={'sdot ' + (st.containers.length === 0 ? '' : st.running === st.containers.length ? 'ok' : st.running ? 'warn' : 'bad')} /><span className="dname">{st.name}</span><span className="muted small">{st.running}/{st.containers.length} running</span></div>
-      <div className="muted small mono" style={{ overflowWrap: 'anywhere' }}>{file === 'env' ? (st.host_file.replace(/[^/]+$/, '') + '.env') : (st.host_files?.[file] ?? st.host_file)}{st.held_by && <span className="muted"> · kept on <b>{st.held_by}</b>, deployed to this machine over {st.remote}</span>}{st.via && <span className="muted"> · compose runs inside <b>{st.via}</b>, as it was deployed</span>}{st.has_env && ' · has a .env beside it'}</div>
+      <div className="muted small mono" style={{ overflowWrap: 'anywhere' }}>{file === 'env' ? (st.host_file.replace(/[^/]+$/, '') + '.env') : (st.host_files?.[file] ?? st.host_file)}{st.via && <span className="muted"> · compose runs inside <b>{st.via}</b>, as it was deployed</span>}{st.has_env && ' · has a .env beside it'}</div>
       {((st.host_files?.length ?? 0) > 1 || st.has_env) && <div className="chips" title="this stack is deployed from several files, in this order; Deploy uses all of them">{st.host_files!.map((f, i) => <button key={f} className={'chip' + (i === file ? ' on' : '')} onClick={async () => { if (dirty && !(await askYes('Discard unsaved changes to this file?', 'Discard'))) return; setFile(i) }}>{f.split('/').pop()}</button>)}{st.has_env && <button className={'chip' + (file === 'env' ? ' on' : '')} title="the .env beside the compose file: variables compose substitutes" onClick={async () => { if (dirty && !(await askYes('Discard unsaved changes to this file?', 'Discard'))) return; setFile('env') }}>.env</button>}</div>}
       {file === 'env' && !reveal ? <div className="env-masked"><pre className="editor stack-editor">{maskEnv(text)}</pre><button className="btn" onClick={() => setReveal(true)}>Reveal and edit</button></div> :
-      <textarea className="editor stack-editor" value={text} onChange={(e) => setText(e.target.value)} spellCheck={false} autoCapitalize="off" autoCorrect="off" />}
+      <CodeEditor className="stack-editor" language={file === 'env' ? 'env' : 'yaml'} value={text} onChange={setText} />}
       {err && <div className="error" style={{ whiteSpace: 'pre-wrap' }}>{err}{/changed on disk/.test(err) && <> <button className="link" onClick={async () => { if (await askYes('Reload the file from disk? Your text in the box is replaced.', 'Reload')) load() }}>reload it</button></>}</div>}
       <div className="svc-actions">
         <Btn className="btn on" disabled={!dirty} onClick={save}>Save</Btn>
@@ -159,6 +367,7 @@ function StackDetail({ name, startTask, onBack, onChanged, onDuplicate }: { name
         <Btn className="btn" disabled={dirty} title={dirty ? 'save first' : 'recreate what changed: docker compose up -d'} confirm={`Deploy ${st.name}? Containers whose definition changed are recreated (a few seconds down each).`} onClick={run('deploy')}>Deploy</Btn>
         {st.containers.length > 0 && <Btn className="btn" disabled={dirty} title="pull newer images, then deploy" confirm={`Pull newer images for ${st.name} and redeploy? Anything with a new image is recreated.`} onClick={run('update')}>Update</Btn>}
         {st.containers.length > 0 && <Btn className="btn" confirm={`Restart every container in ${st.name}?`} onClick={run('restart')}>Restart</Btn>}
+        {st.containers.length > 0 && <Btn className="btn" disabled={dirty} title="build the containers again from scratch: docker compose up -d --force-recreate" confirm={`Recreate every container in ${st.name}?\n\nThis is the way out of a container Docker refuses to start — one pinned to a network that no longer exists, say, which answers "network … not found" to an ordinary Deploy. Nothing in a volume or a bind mount is touched.`} onClick={run('recreate')}>Recreate</Btn>}
         {st.running > 0 && <Btn className="btn danger" confirm={`Stop every container in ${st.name}? They stay stopped until deployed or started again.`} onClick={run('stop')}>Stop</Btn>}
       </div>
       <div className="svc-actions">
@@ -193,7 +402,7 @@ export default function Docker() {
   const rate = useRefreshMs()
   const load = useCallback(async () => { try { setD(await api.docker()); setErr('') } catch (e) { setErr(e instanceof Error ? e.message : 'failed') } api.stacks().then((r) => setStacks(r.stacks)).catch(() => setStacks([])) }, [])
   useEffect(() => { load(); const t = setInterval(() => { if (document.visibilityState === 'visible') load() }, Math.max(5000, rate)); return () => clearInterval(t) }, [load, rate])
-  const live = useSensorStream<{ c: Record<string, Sensor> }>({ c: 'container.*' }, { everyMs: Math.max(2000, rate) })
+  const live = useSensorStream<{ c: Record<string, Sensor> }>({ c: 'container.*' }, { everyMs: rate })
   const sensors = live.data?.c ?? {}
   const byStack = useMemo(() => {
     const f = filter.trim().toLowerCase(); const out = new Map<string, DockerContainer[]>()
@@ -203,6 +412,15 @@ export default function Docker() {
   // what a new stack could join, and what it could collide with
   const nets = useMemo(() => (d?.networks ?? []).map((n) => String(n.Name)).filter((n) => !['bridge', 'host', 'none'].includes(n)).sort(), [d])
   const taken = useMemo(() => { const ports: Record<string, string> = {}; for (const c of d?.containers ?? []) for (const m of (c.ports ?? '').matchAll(/:(\d+)->/g)) ports[m[1]] = c.name; return { names: (d?.containers ?? []).map((c) => c.name), ports } }, [d])
+  // What the registry last said about each image, so a container can be marked without
+  // asking again. Only ever read from the cache here — checking is a deliberate act.
+  // Re-read after a stack task too: an update changes this machine's side of the answer.
+  const [upd, setUpd] = useState<MachineUpdates | null>(null)
+  const readUpd = useCallback(() => { api.machineUpdates().then(setUpd).catch(() => {}) }, [])
+  useEffect(() => { api.machineUpdates().then(setUpd).catch(() => setUpd(null)) }, [])
+  const stackChanged = useCallback(() => { load(); readUpd() }, [load, readUpd])
+  const imgState = useMemo(() => Object.fromEntries((upd?.images ?? []).map((i) => [i.image, i.state])), [upd])
+  const behind = (upd?.images ?? []).filter((i) => i.state === 'update').length
   if (!d) return <div className="dash">{err ? <div className="notice">{err === 'not found' ? "This machine's Ham Lab is older than the Docker tab. Update it from Machines." : err}</div> : <Loading label="Asking Docker…" />}</div>
   if (!d.available) return <div className="dash"><div className="notice">{d.message}</div></div>
   const selStack = sel.startsWith('stack:') ? sel.slice(6) : ''
@@ -210,12 +428,12 @@ export default function Docker() {
   const shownTab: Tab = selStack ? 'stacks' : tab
   const up = d.containers.filter((c) => c.state === 'running').length
   const sid = (c: DockerContainer, k: string) => sensors[`container.${c.name.toLowerCase().replace(/[^a-z0-9-]+/g, '_').replace(/^_|_$/g, '')}.${k}`]
-  const cols: Record<Exclude<Tab, 'containers' | 'stacks'>, [string, string][]> = { images: [['Repository', 'Repository'], ['Tag', 'Tag'], ['Size', 'Size'], ['CreatedSince', 'Created']], volumes: [['Name', 'Name'], ['Driver', 'Driver'], ['Mountpoint', 'Mountpoint']], networks: [['Name', 'Name'], ['Driver', 'Driver'], ['Scope', 'Scope']] }
+  const imageCols: [string, string][] = [['Repository', 'Repository'], ['Tag', 'Tag'], ['Size', 'Size'], ['CreatedSince', 'Created']]
   return (
-    <div className={'svc docker' + (((cur || sel) && shownTab === 'containers') || selStack ? ' has-sel' : '')}>
+    <div className={'svc docker' + (((cur || sel) && shownTab === 'containers') || selStack ? ' has-sel' : '') + (shownTab === 'updates' ? ' wide' : '')}>
       <div className="svc-list">
         <div className="svc-tools">
-          <div className="chips">{(['containers', 'stacks', 'images', 'volumes', 'networks'] as Tab[]).map((t) => <button key={t} className={'chip' + (shownTab === t ? ' on' : '')} onClick={() => { setTab(t); if (sel) setSel('') }}>{t} · {t === 'containers' ? `${up}/${d.containers.length}` : t === 'stacks' ? (stacks?.length ?? '…') : d[t].length}</button>)}</div>
+          <div className="chips">{(['containers', 'stacks', 'updates', 'images', 'volumes', 'networks'] as Tab[]).map((t) => <button key={t} className={'chip' + (shownTab === t ? ' on' : '')} onClick={() => { setTab(t); if (sel) setSel('') }}>{t}{t === 'containers' ? ` · ${up}/${d.containers.length}` : t === 'stacks' ? ` · ${stacks?.length ?? '…'}` : t === 'updates' ? (behind > 0 ? ` · ${behind}` : '') : ` · ${d[t].length}`}</button>)}</div>
           {(shownTab === 'containers' || shownTab === 'stacks') && <div className="svc-actions"><button className="btn" onClick={() => setMaking(shownTab === 'stacks' ? 'stack' : 'container')}>{shownTab === 'stacks' ? '+ New stack' : '+ New container'}</button></div>}
           {shownTab === 'images' && <form className="chan-add" onSubmit={async (e) => { e.preventDefault(); try { setPullTask((await api.pullImage(pull.trim())).id) } catch (er) { toast(er instanceof Error ? er.message : 'failed', 'err') } }}>
             <input className="mono" value={pull} onChange={(e) => setPull(e.target.value)} placeholder="pull an image — nginx:alpine, ghcr.io/owner/name:tag" spellCheck={false} autoCapitalize="off" autoCorrect="off" />
@@ -224,6 +442,7 @@ export default function Docker() {
             <Btn className="btn" title="remove dangling images: layers no tag points at any more" confirm="Remove dangling images? Only layers that no tag points at any more — nothing a container or a tag uses." onClick={async () => { try { toast((await api.pruneImages()).result); load() } catch (er) { toast(er instanceof Error ? er.message : 'failed', 'err') } }}>Prune</Btn>
           </form>}
           {shownTab === 'volumes' && (() => { const n = d.volumes.filter((v) => v.anonymous && !((v.used_by as string[] | undefined) ?? []).length).length; return <div className="svc-actions"><span className="muted small">Deleting a volume deletes its data. Only one nothing uses can be deleted.</span><span className="spacer" />{n > 0 && <Btn className="btn danger" title="the nameless volumes an image's VOLUME line leaves behind each time its container is recreated" confirm={`Delete ${n} unused anonymous volume${n === 1 ? '' : 's'} and what is in them? Named volumes are not touched.`} onClick={async () => { try { toast((await api.pruneVolumes()).result); load() } catch (er) { toast(er instanceof Error ? er.message : 'failed', 'err') } }}>Prune anonymous · {n}</Btn>}</div> })()}
+          {shownTab === 'networks' && (() => { const n = d.networks.filter((x) => !x.predefined && !((x.used_by as string[] | undefined) ?? []).length).length; return <div className="svc-actions"><span className="muted small">A network holds no data. Only one nothing is attached to can be removed.</span><span className="spacer" />{n > 0 && <Btn className="btn" title="remove every network no container is attached to" confirm={`Remove ${n} network${n === 1 ? '' : 's'} nothing is attached to? A stack that is only down counts as unattached — its network comes back on the next deploy, with a new subnet.`} onClick={async () => { try { toast((await api.pruneNetworks()).result || 'nothing to remove'); load() } catch (er) { toast(er instanceof Error ? er.message : 'failed', 'err') } }}>Prune · {n}</Btn>}</div> })()}
           {shownTab === 'images' && pullTask && <TaskOutput id={pullTask} onDone={() => load()} />}
           {shownTab === 'containers' && <input value={filter} onChange={(e) => setFilter(e.target.value)} placeholder="filter containers, images, stacks" />}
         </div>
@@ -231,7 +450,7 @@ export default function Docker() {
           {shownTab === 'stacks' && (stacks ?? []).map((st) => (
             <div key={st.name} className={'svc-row' + (st.name === selStack ? ' active' : '')} onClick={() => st.editable ? setSel('stack:' + st.name) : toast(st.note ?? 'not editable here', 'info')}>
               <span className={'sdot ' + (st.containers.length === 0 ? '' : st.running === st.containers.length ? 'ok' : st.running ? 'warn' : 'bad')} />
-              <div className="svc-name"><div className="n">{st.name}</div><div className="d">{st.editable ? (st.held_by ? `on ${st.held_by}: ` : '') + st.host_file : st.note}</div></div>
+              <div className="svc-name"><div className="n">{st.name}</div><div className="d">{st.editable ? st.host_file : st.note}</div></div>
               <div className="svc-state">{st.containers.length === 0 ? 'not deployed' : `${st.running}/${st.containers.length}`}{!st.editable && <><br />read-only</>}</div>
             </div>
           ))}
@@ -242,7 +461,7 @@ export default function Docker() {
               {list.map((c) => (
                 <div key={c.id} className={'svc-row' + (c.name === sel ? ' active' : '')} onClick={() => setSel(c.name)}>
                   <span className={'sdot ' + dot(c)} />
-                  <div className="svc-name"><div className="n">{c.name}</div><div className="d">{c.image}</div></div>
+                  <div className="svc-name"><div className="n">{c.name}<UpdateDot state={imgState[c.image]} /></div><div className="d">{c.image}</div></div>
                   <div className="svc-state">{c.state === 'running' ? <>{fmtValue(sid(c, 'mem')?.value ?? c.mem, 'B')}<br />{fmtValue(sid(c, 'cpu')?.value, '%')}</> : c.state}</div>
                 </div>
               ))}
@@ -260,16 +479,207 @@ export default function Docker() {
                 return <tr key={name}><td className="mono small" title={String(row.Mountpoint ?? '')}>{anon ? <>{name.slice(0, 12)}… <span className="muted">anonymous</span></> : name}</td><td className="small">{users.length ? users.join(', ') : <span className="muted">nothing</span>}</td><td className="row-end">{users.length ? <span className="badge">in use</span> : <button className="icon-btn" title="delete this volume and its data" onClick={remove}>✕</button>}</td></tr> })}
                 {d.volumes.length === 0 && <tr><td colSpan={3} className="muted small">No volumes.</td></tr>}</tbody></table>
           )}
-          {shownTab !== 'containers' && shownTab !== 'stacks' && shownTab !== 'volumes' && (
-            <table className="dtable"><thead><tr>{cols[shownTab as Exclude<Tab, 'containers' | 'stacks'>].map(([, h]) => <th key={h}>{h}</th>)}{shownTab === 'images' && <th />}</tr></thead>
-              <tbody>{d[shownTab as Exclude<Tab, 'containers' | 'stacks'>].map((row, i) => <tr key={i}>{cols[shownTab as Exclude<Tab, 'containers' | 'stacks'>].map(([k]) => <td key={k} className="mono small">{String(row[k] ?? '')}</td>)}{shownTab === 'images' && <td className="row-end">{row.in_use ? <span className="badge" title="a container uses this image">in use</span> : <Btn className="icon-btn" title="remove this image" confirm={`Remove the image ${row.Repository}:${row.Tag}? Docker refuses if a container still uses it.`} onClick={async () => { const ref = row.Tag && row.Tag !== '<none>' ? `${row.Repository}:${row.Tag}` : String(row.ID); try { await api.removeImage(ref); toast(`${ref} removed`); load() } catch (er) { toast(er instanceof Error ? er.message : 'failed', 'err') } }}>✕</Btn>}</td>}</tr>)}</tbody></table>
+          {shownTab === 'networks' && (
+            <table className="dtable"><thead><tr><th>Network</th><th>Driver</th><th>Used by</th><th /></tr></thead>
+              <tbody>{d.networks.map((row, i) => { const name = String(row.Name), users = (row.used_by as string[] | undefined) ?? [], own = !!row.predefined
+                return <tr key={i}><td className="mono small">{name}{own && <span className="muted"> · Docker's own</span>}</td><td className="mono small">{String(row.Driver ?? '')}</td><td className="small">{users.length ? users.join(', ') : <span className="muted">nothing</span>}</td><td className="row-end">{users.length ? <span className="badge" title="a container is attached to this network">in use</span> : own ? null : <Btn className="icon-btn" title="remove this network" confirm={`Remove the network ${name}? Nothing is attached to it. A stack that wants it back gets it recreated on its next deploy, with a new subnet.`} onClick={async () => { try { await api.removeNetwork(name); toast(`${name} removed`); load() } catch (er) { toast(er instanceof Error ? er.message : 'failed', 'err') } }}>✕</Btn>}</td></tr> })}
+                {d.networks.length === 0 && <tr><td colSpan={4} className="muted small">No networks.</td></tr>}</tbody></table>
+          )}
+          {shownTab === 'images' && (
+            <table className="dtable"><thead><tr>{imageCols.map(([, h]) => <th key={h}>{h}</th>)}<th /></tr></thead>
+              <tbody>{d.images.map((row, i) => <tr key={i}>{imageCols.map(([k]) => <td key={k} className="mono small">{String(row[k] ?? '')}</td>)}<td className="row-end">{row.in_use ? <span className="badge" title="a container uses this image">in use</span> : <Btn className="icon-btn" title="remove this image" confirm={`Remove the image ${row.Repository}:${row.Tag}? Docker refuses if a container still uses it.`} onClick={async () => { const ref = row.Tag && row.Tag !== '<none>' ? `${row.Repository}:${row.Tag}` : String(row.ID); try { await api.removeImage(ref); toast(`${ref} removed`); load() } catch (er) { toast(er instanceof Error ? er.message : 'failed', 'err') } }}>✕</Btn>}</td></tr>)}</tbody></table>
           )}
         </div>
       </div>
       {shownTab === 'containers' && !cur && sel && !selStack && <div className="svc-detail"><CloseBtn onClick={() => setSel('')} /><button className="btn back" onClick={() => setSel('')}>‹ Back</button><div className="notice">There is no container called <b className="mono">{sel}</b> on this machine. It may have been removed, renamed or recreated under another name. <button className="link" onClick={() => setSel('')}>Show them all</button></div></div>}
       {shownTab === 'containers' && (cur ? <Detail c={cur} live={sensors} onBack={() => setSel('')} onChanged={load} /> : (sel && !selStack ? null : <div className="svc-empty muted">Select a container.</div>))}
       {making && <StackNew key={'new:' + (dup?.name ?? making)} mode={making} from={dup ?? undefined} networks={nets} taken={taken} onClose={() => { setMaking(''); setDup(null) }} onCreated={async (name, deploy) => { setMaking(''); setDup(null); setTab('stacks'); if (deploy) { try { setStartTask({ name, id: (await api.stackAction(name, 'deploy')).id }) } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') } } else setStartTask(null); await load(); setSel('stack:' + name) }} />}
-      {shownTab === 'stacks' && (selStack ? <StackDetail key={selStack + (startTask?.name === selStack ? startTask.id : '')} name={selStack} startTask={startTask?.name === selStack ? startTask.id : undefined} onBack={() => setSel('')} onChanged={load} onDuplicate={(f) => { setDup(f); setMaking('stack') }} /> : <div className="svc-empty muted">Select a stack to edit its compose file.</div>)}
+      {shownTab === 'updates' && <Updates upd={upd} onChecked={setUpd} />}
+      {shownTab === 'stacks' && (selStack ? <StackDetail key={selStack + (startTask?.name === selStack ? startTask.id : '')} name={selStack} startTask={startTask?.name === selStack ? startTask.id : undefined} onBack={() => setSel('')} onChanged={stackChanged} onDuplicate={(f) => { setDup(f); setMaking('stack') }} /> : <div className="svc-empty muted">Select a stack to edit its compose file.</div>)}
+    </div>
+  )
+}
+
+// A container's image against the registry, as a single mark: nothing when nobody has
+// asked, so an uncoloured list means "not checked" rather than "all current".
+function UpdateDot({ state }: { state?: string }) {
+  if (!state || state === 'current') return null
+  const known = state === 'update'
+  return <span className={'updot' + (known ? ' behind' : ' unknown')} title={known ? 'a newer image has been published' : 'the registry could not say'}>{known ? '↑' : '?'}</span>
+}
+
+// What is out of date here, and the schedules that keep it from happening again.
+function Updates({ upd, onChecked }: { upd: MachineUpdates | null; onChecked: (u: MachineUpdates) => void }) {
+  const [busy, setBusy] = useState(false)
+  const [jobs, setJobs] = useState<UpdateJobRow[] | null>(null)
+  const [file, setFile] = useState('')
+  const [editing, setEditing] = useState<Partial<UpdateJob> | null>(null)
+  const [stacks, setStacks] = useState<string[]>([])
+  const loadJobs = useCallback(async () => {
+    try { const r = await api.updateJobs(); setJobs(r.jobs); setFile(r.file) } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err'); setJobs([]) }
+  }, [])
+  useEffect(() => { loadJobs(); api.stacks().then((r) => setStacks(r.stacks.map((s) => s.name))).catch(() => {}) }, [loadJobs])
+  const check = async () => {
+    setBusy(true)
+    try { onChecked(await api.machineUpdates(true)); toast('checked') } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') } finally { setBusy(false) }
+  }
+  const run = async (j: UpdateJob) => {
+    if (!await askYes(`Run “${j.name}” now? It pulls ${j.stack}'s images${j.apply ? ' and deploys them, which restarts its containers' : ', without deploying them'}.`, 'Run now')) return
+    try { await api.runUpdateJob(j.id); toast(`${j.name}: done`); loadJobs(); api.machineUpdates().then(onChecked).catch(() => {}) } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') }
+  }
+  const remove = async (j: UpdateJob) => {
+    if (!await askYes(`Remove the schedule “${j.name}”? Nothing is updated or rolled back — the schedule simply stops.`, 'Remove')) return
+    try { await api.deleteUpdateJob(j.id); toast('removed'); loadJobs() } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') }
+  }
+  const imgs = upd?.images ?? []
+  const behind = imgs.filter((i) => i.state === 'update')
+  // Updating is per stack — that is what compose can do — so an image row acts on whichever
+  // stacks use it, and a queue runs them one at a time rather than recreating half the
+  // machine at once.
+  const [queue, setQueue] = useState<string[]>([])
+  const [running, setRunning] = useState<{ stack: string; id: string } | null>(null)
+  const stacksFor = useCallback((img: string) => upd?.stacks?.[img] ?? [], [upd])
+  const startNext = useCallback(async (rest: string[]) => {
+    const next = rest[0]
+    if (!next) { setRunning(null); setQueue([]); return }
+    setQueue(rest.slice(1))
+    try { setRunning({ stack: next, id: (await api.stackAction(next, 'update')).id }) }
+    catch (e) { toast(`${next}: ${e instanceof Error ? e.message : 'failed'}`, 'err'); setRunning(null); startNext(rest.slice(1)) }
+  }, [])
+  const updateStacks = async (names: string[], what: string) => {
+    const uniq = [...new Set(names)]
+    if (uniq.length === 0) { toast('nothing here names a stack this console can deploy', 'info'); return }
+    if (!await askYes(`Update ${what}?\n\nThis pulls the newer image${uniq.length > 1 ? 's' : ''} and recreates ${uniq.length === 1 ? `the ${uniq[0]} stack` : `these stacks, one at a time: ${uniq.join(', ')}`}. Their containers restart.`, 'Update')) return
+    startNext(uniq)
+  }
+  const behindStacks = [...new Set(behind.flatMap((i) => stacksFor(i.image)))]
+  return (
+    <div className="svc-detail">
+      <div className="dash-bar"><h2 className="section">What is out of date</h2><span className="spacer" />
+        <span className="muted small">{upd?.checked ? `checked ${new Date(upd.checked).toLocaleString()}` : 'not checked yet'}</span>
+        {behindStacks.length > 0 && <Btn className="btn on" disabled={!!running} onClick={() => updateStacks(behindStacks, `everything out of date — ${behind.length} image${behind.length === 1 ? '' : 's'} across ${behindStacks.length} stack${behindStacks.length === 1 ? '' : 's'}`)}>Update all · {behind.length}</Btn>}
+        <Btn className="btn" busy={busy} onClick={check}>Check now</Btn>
+      </div>
+      <div className="muted small">Each check is one request per image, which registries count — so it happens when asked, and the answer is kept for six hours.</div>
+      {imgs.length === 0 && <div className="notice" style={{ marginTop: 8 }}>Nothing checked yet on this machine.</div>}
+      {imgs.length > 0 && (
+        <section className="card" style={{ marginTop: 8 }}>
+          {behind.length === 0 && <div className="muted">Every image that could be checked is current.</div>}
+          <div className="upd-list">
+          {imgs.filter((i) => i.state !== 'current').map((i) => (
+            <div className="row" key={i.image}>
+              <span className="k mono small">{i.image}</span>
+              <span className={i.state === 'update' ? 'warn-text' : 'muted small'}>{i.state === 'update' ? 'a newer image is published' : i.detail || 'unknown'}</span>
+              <span className="muted small">{stacksFor(i.image).join(' ')}</span>
+              {i.state === 'update' && (
+                <Btn className="btn" disabled={!!running || stacksFor(i.image).length === 0} title={stacksFor(i.image).length ? `pull it and recreate ${stacksFor(i.image).join(', ')}` : 'no stack here uses this image'}
+                  onClick={() => updateStacks(stacksFor(i.image), `${i.image}`)}>Update</Btn>
+              )}
+            </div>
+          ))}
+          </div>
+          {behind.length === 0 && imgs.some((i) => i.state === 'current') && <div className="muted small" style={{ marginTop: 6 }}>{imgs.filter((i) => i.state === 'current').length} current.</div>}
+          {running && (
+            <div style={{ marginTop: 8 }}>
+              <div className="sub-head"><span className="dname">Updating {running.stack}</span><span className="spacer" /><span className="muted small">{queue.length > 0 ? `${queue.length} to follow` : 'last one'}</span></div>
+              <TaskOutput id={running.id} onDone={(t) => {
+                if (t.exit_code !== 0 || t.error) toast(`${running.stack}: update failed`, 'err')
+                api.machineUpdates().then(onChecked).catch(() => {}) // an image now held drops off the list
+                startNext(queue)
+              }} />
+            </div>
+          )}
+        </section>
+      )}
+
+      <div className="dash-bar" style={{ marginTop: 14 }}><h2 className="section">Schedules</h2><span className="spacer" />
+        <Btn className="btn on" onClick={() => setEditing({ cron: '0 3 * * *', apply: true, enabled: true })}>+ New schedule</Btn>
+      </div>
+      <div className="muted small">Written to <span className="mono">{file || '/etc/cron.d/hamlab-docker'}</span>, which Ham Lab owns — so they keep running whether or not this console is up.</div>
+      {jobs === null && <Loading label="Reading…" />}
+      {jobs?.length === 0 && <div className="notice" style={{ marginTop: 8 }}>No schedule yet. Nothing on this machine updates itself.</div>}
+      <div className="cards" style={{ marginTop: 8 }}>
+        {(jobs ?? []).map(({ job, next, last }) => (
+          <section className="card" key={job.id}>
+            <div className="sub-head">
+              <span className={'dot ' + (last?.error ? 'bad' : job.enabled ? 'ok' : '')} />
+              <span className="dname">{job.name}</span>
+              {!job.enabled && <span className="badge">paused</span>}
+              <span className="spacer" />
+              <span className="muted small">{job.enabled && next ? new Date(next).toLocaleString() : 'not scheduled'}</span>
+            </div>
+            <div className="props" style={{ marginTop: 6 }}>
+              <div><span className="k">Stack</span><span>{job.stack}{job.services?.length ? ` · ${job.services.join(' ')}` : ''}</span></div>
+              <div><span className="k">Runs</span><span>{describeCron(job.cron) || <span className="mono small">{job.cron}</span>}{describeCron(job.cron) && <span className="muted mono small"> · {job.cron}</span>}</span></div>
+              <div><span className="k">Does</span><span>{job.apply ? 'pulls and deploys' : 'pulls only — you deploy'}</span></div>
+              <div><span className="k">Last run</span><span>{last?.at ? new Date(last.at).toLocaleString() : 'never'}</span></div>
+            </div>
+            {last?.error && <div className="error" style={{ marginTop: 6 }}>{last.error}</div>}
+            <div className="svc-actions">
+              <Btn className="btn on" onClick={() => run(job)}>Run now</Btn>
+              <button className="btn" onClick={() => setEditing(job)}>Edit</button>
+              <Btn className="btn" onClick={async () => { await api.saveUpdateJob({ ...job, enabled: !job.enabled }); loadJobs() }}>{job.enabled ? 'Pause' : 'Resume'}</Btn>
+              <Btn className="btn danger" onClick={() => remove(job)}>Remove</Btn>
+            </div>
+          </section>
+        ))}
+      </div>
+      {editing && <JobDialog j={editing} stacks={stacks} onClose={() => setEditing(null)} onSaved={() => { setEditing(null); loadJobs() }} />}
+    </div>
+  )
+}
+
+function JobDialog({ j, stacks, onClose, onSaved }: { j: Partial<UpdateJob>; stacks: string[]; onClose: () => void; onSaved: () => void }) {
+  const [f, setF] = useState<Partial<UpdateJob>>(j)
+  const [svc, setSvc] = useState((j.services ?? []).join(' '))
+  const [err, setErr] = useState('')
+  const [busy, setBusy] = useState(false)
+  useEscape(onClose)
+  const set = (k: keyof UpdateJob, v: unknown) => setF((x) => ({ ...x, [k]: v }))
+  const save = async (e: FormEvent) => {
+    e.preventDefault(); setErr(''); setBusy(true)
+    try { await api.saveUpdateJob({ ...f, services: svc.split(/\s+/).filter(Boolean) }); onSaved() }
+    catch (e) { setErr(e instanceof Error ? e.message : 'failed'); setBusy(false) }
+  }
+  return (
+    <div className="modal-back" onClick={onClose}>
+      <form className="modal" onClick={(e) => e.stopPropagation()} onSubmit={save}>
+        <h3>{f.id ? 'Edit schedule' : 'Keep a stack up to date'}</h3>
+        <label className="muted">Stack
+          <select value={f.stack ?? ''} onChange={(e) => set('stack', e.target.value)} required>
+            <option value="">choose…</option>
+            {stacks.map((s) => <option key={s} value={s}>{s}</option>)}
+          </select>
+        </label>
+        <label className="muted">Name — optional
+          <input value={f.name ?? ''} onChange={(e) => set('name', e.target.value)} placeholder={f.stack ?? 'nightly'} maxLength={64} />
+        </label>
+        <label className="muted">Only these services — optional, space separated; blank means the whole stack
+          <input className="mono" value={svc} onChange={(e) => setSvc(e.target.value)} placeholder="all of them" spellCheck={false} />
+        </label>
+        <label className="muted">When — a cron expression
+          <input className="mono" value={f.cron ?? ''} onChange={(e) => set('cron', e.target.value)} placeholder="0 3 * * *" spellCheck={false} required />
+        </label>
+        <label className="muted" style={{ flexDirection: 'row', alignItems: 'center', gap: 8 }}>
+          <input type="checkbox" checked={!!f.apply} onChange={(e) => set('apply', e.target.checked)} style={{ width: 'auto' }} />
+          Deploy the new image, not just fetch it
+        </label>
+        <label className="muted" style={{ flexDirection: 'row', alignItems: 'center', gap: 8 }}>
+          <input type="checkbox" checked={!!f.enabled} onChange={(e) => set('enabled', e.target.checked)} style={{ width: 'auto' }} />
+          Enabled
+        </label>
+        <div className="notice">
+          {f.apply
+            ? 'Deploying restarts the stack’s containers. On something that carries DNS or ingress, pick an hour you are asleep.'
+            : 'Pulling only means the new image is on the machine and the list shows it as available — nothing restarts until you deploy.'}
+        </div>
+        {err && <div className="error">{err}</div>}
+        <div className="svc-actions">
+          <button type="submit" className="btn on" disabled={busy || !f.stack || !f.cron}>Save</button>
+          <span className="spacer" />
+          <button type="button" className="btn" onClick={onClose}>Cancel</button>
+        </div>
+      </form>
     </div>
   )
 }

web/src/Files.tsx

@@ -1,10 +1,25 @@
-import { DragEvent, useCallback, useEffect, useRef, useState } from 'react'
-import { api, FileEntry, FileInfo } from './api'
-import { fmtBytes } from './Dashboard'
+import { DragEvent, useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { api, FileEntry, FileInfo, TaskInfo, ThumbStatus } from './api'
+import { fmtBytes } from './fmt'
 import { Btn, Loading, Spinner, askText, askYes, setUnsaved, toast, useEscape } from './ui'
 import { useHashSel } from './hashsel'
+import TaskOutput from './TaskOutput'
+import Player from './Player'
 
 const join = (dir: string, name: string) => (dir === '/' ? '/' + name : dir + '/' + name)
+// A typed path, made absolute: relative to the folder being looked at, "." and ".." applied,
+// trailing slashes dropped — what a shell would make of it.
+export function resolvePath(input: string, here: string): string {
+  const raw = input.trim()
+  if (!raw) return here
+  const parts = (raw.startsWith('/') ? [] : here.split('/')).concat(raw.split('/'))
+  const out: string[] = []
+  for (const p of parts) {
+    if (p === '' || p === '.') continue
+    if (p === '..') out.pop(); else out.push(p)
+  }
+  return '/' + out.join('/')
+}
 const fmtTime = (ms: number) => { const d = new Date(ms); const now = new Date(); return d.toDateString() === now.toDateString() ? d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) : d.toLocaleDateString(undefined, { year: d.getFullYear() === now.getFullYear() ? undefined : 'numeric', month: 'short', day: '2-digit' }) }
 const isImage = (n: string) => /\.(png|jpe?g|gif|webp|svg|bmp|ico|avif)$/i.test(n)
 const shellQuote = (s: string) => "'" + s.replace(/'/g, "'\\''") + "'"
@@ -14,7 +29,9 @@ function icon(e: FileEntry): string {
   if (e.type === 'dir') return e.target ? '🔗' : '📁'
   if (e.type === 'link') return e.broken ? '⛓️‍💥' : '🔗'
   if (e.type === 'other') return '⚙️'
-  if (isImage(e.name)) return '🖼️'
+  if (e.preview === 'image' || isImage(e.name)) return '🖼️'
+  if (e.preview === 'video') return '🎞️'
+  if (e.preview === 'audio') return '🎵'
   if (/\.(zip|gz|bz2|xz|zst|tar|tgz|7z|rar)$/i.test(e.name)) return '🗜️'
   if (/\.(sh|bash|zsh|py|go|js|ts|tsx|rb|pl|php|rs|c|h|cpp|java|lua)$/i.test(e.name) || e.mode.includes('x')) return '📜'
   if (/\.(log|txt|md|json|ya?ml|toml|ini|conf|cfg|env|service|timer)$/i.test(e.name)) return '📄'
@@ -22,6 +39,163 @@ function icon(e: FileEntry): string {
 }
 
 type Sort = 'name' | 'size' | 'mtime'
+const PREVIEWS_KEY = 'hamlab.files.previews'
+const byName = (a: FileEntry, b: FileEntry) => a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: 'base' })
+// A name is one path segment. ("../x" and "a/b" would quietly act somewhere else.)
+const okName = (n?: string | null): n is string => { const t = n?.trim(); if (!t) return false; if (t.includes('/') || t === '.' || t === '..') { toast('a name can\'t contain / or be . or .. — use Move… to put it elsewhere', 'err'); return false } return true }
+
+// ---- move: walk to the destination, then "Move here" ----
+function MovePicker({ item, from, sudo, hidden, onClose, onMoved }: { item: FileEntry; from: string; sudo: boolean; hidden: boolean; onClose: () => void; onMoved: (task?: TaskInfo) => void }) {
+  const src = join(from, item.name)
+  const isFolder = item.type === 'dir' && !item.target
+  const [hist, setHist] = useState<string[]>([from]) // where the picker has been, for back and forward
+  const [at, setAt] = useState(0)
+  const dir = hist[at]
+  const [entries, setEntries] = useState<FileEntry[] | null>(null)
+  const [err, setErr] = useState('')
+  const [pathInput, setPathInput] = useState(from)
+  const [busy, setBusy] = useState(false)
+  const load = useCallback(async (p: string) => {
+    setEntries(null); setErr('')
+    try { const l = await api.files(p, sudo); setEntries(l.entries) } catch (e) { setErr(e instanceof Error ? e.message : 'failed'); setEntries([]) }
+  }, [sudo])
+  useEffect(() => { setPathInput(dir); load(dir) }, [dir, load])
+  useEscape(onClose)
+  const go = (input: string) => {
+    const p = resolvePath(input, dir)
+    if (p === dir) return
+    setHist((h) => [...h.slice(0, at + 1), p]); setAt(at + 1)
+  }
+  const up = () => { if (dir !== '/') go(dir.slice(0, dir.lastIndexOf('/')) || '/') }
+  const folders = (entries ?? []).filter((e) => e.type === 'dir' && (hidden || !e.name.startsWith('.'))).sort(byName)
+  const crumbs = dir === '/' ? [] : dir.slice(1).split('/')
+  const dest = join(dir, item.name)
+  const why = dir === from ? 'it is already here'
+    : isFolder && (dir === src || dir.startsWith(src + '/')) ? 'a folder can\'t move into itself'
+    : (entries ?? []).some((e) => e.name === item.name) ? `something called ${item.name} is already there` : ''
+  const move = async () => {
+    setBusy(true)
+    try {
+      const t = await api.fileMove(src, dest, sudo)
+      if (t) toast(`${dir} is on another filesystem — copying ${item.name} there, then removing it here`, 'info')
+      else toast(`moved ${item.name} to ${dir}`)
+      onMoved(t)
+    } catch (e) { toast(`move — ${e instanceof Error ? e.message : 'failed'}`, 'err'); setBusy(false) }
+  }
+  const mkdir = async () => {
+    const n = await askText('New folder name')
+    if (!okName(n)) return
+    try { await api.fileMkdir(join(dir, n.trim()), sudo); go(join(dir, n.trim())) } catch (e) { toast(`create folder — ${e instanceof Error ? e.message : 'failed'}`, 'err') }
+  }
+  return (
+    <div className="modal-back" onClick={onClose}>
+      <div className="modal mover" onClick={(e) => e.stopPropagation()}>
+        <h3>Move {isFolder ? 'folder ' : ''}<span className="mono">{item.name}</span></h3>
+        <div className="mover-nav">
+          <button className="icon-btn" title="back" disabled={at === 0} onClick={() => setAt(at - 1)}>‹</button>
+          <button className="icon-btn" title="forward" disabled={at >= hist.length - 1} onClick={() => setAt(at + 1)}>›</button>
+          <button className="icon-btn" title="up one level" disabled={dir === '/'} onClick={up}>↑</button>
+          <form className="crumbs" onSubmit={(e) => { e.preventDefault(); go(pathInput) }}>
+            <button type="button" className="crumb" onClick={() => go('/')}>/</button>
+            {crumbs.map((c, i) => <button type="button" key={i} className="crumb" onClick={() => go('/' + crumbs.slice(0, i + 1).join('/'))}>{c}</button>)}
+            <input className="path-input" value={pathInput} onChange={(e) => setPathInput(e.target.value)} onBlur={() => setPathInput(dir)} spellCheck={false} autoCapitalize="off" autoCorrect="off" />
+          </form>
+        </div>
+        <div className="mover-list">
+          {entries === null && <Loading label="Listing…" />}
+          {err && <div className="error" style={{ margin: 10 }}>{err}</div>}
+          {folders.map((e) => {
+            const self = dir === from && e.name === item.name
+            return (
+              <div key={e.name} className={'mover-row' + (self ? ' self' : '')} onClick={() => { if (!self) go(join(dir, e.name)) }}>
+                <span className="ficon">{e.target ? '🔗' : '📁'}</span>
+                <span className="fname">{e.name}</span>
+                {self && <span className="muted small">this is what's moving</span>}
+              </div>
+            )
+          })}
+          {entries !== null && folders.length === 0 && !err && <div className="muted small" style={{ padding: 12 }}>No folders here — “Move here” puts it in this one.</div>}
+        </div>
+        <div className="modal-foot">
+          <div className="svc-actions">
+            <button className="btn" onClick={mkdir}>+ folder</button>
+            <span className="spacer" />
+            <button className="btn" onClick={onClose}>Cancel</button>
+            <Btn className="btn on" disabled={!!why || entries === null} busy={busy} onClick={move}>Move here</Btn>
+          </div>
+          <div className="muted small mono mover-dest">{why || `→ ${dest}`}</div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ---- previews ----
+
+// Rows ask for their thumbnail only as they scroll near: a browser's own lazy loading
+// watches the window, and this list scrolls inside a box of its own. One observer for the
+// list, a callback per row, each fired once.
+class Near {
+  private obs: IntersectionObserver
+  private cbs = new Map<Element, () => void>()
+  constructor(root: Element) {
+    this.obs = new IntersectionObserver((ents) => {
+      for (const e of ents) if (e.isIntersecting) { const cb = this.cbs.get(e.target); if (cb) { this.forget(e.target); cb() } }
+    }, { root, rootMargin: '400px 0px' })
+  }
+  watch(el: Element, cb: () => void) { this.cbs.set(el, cb); this.obs.observe(el); return () => this.forget(el) }
+  private forget(el: Element) { this.cbs.delete(el); this.obs.unobserve(el) }
+}
+
+function Thumb({ url, kind, near, fallback }: { url: string; kind: 'image' | 'video' | 'audio'; near: Near | null; fallback: string }) {
+  const ref = useRef<HTMLSpanElement>(null)
+  const [show, setShow] = useState(false)
+  const [failed, setFailed] = useState('')
+  useEffect(() => { const el = ref.current; if (!el || !near || show) return; return near.watch(el, () => setShow(true)) }, [near, show])
+  useEffect(() => { setFailed('') }, [url]) // a changed file is a new URL, and worth another try
+  const broken = failed === url
+  return (
+    <span ref={ref} className={'fthumb ' + kind} title={broken ? 'no preview for this file' : undefined}>
+      {show && !broken && <img src={url} alt="" decoding="async" onError={() => setFailed(url)} />}
+      {(!show || broken) && <span className="ficon">{fallback}</span>}
+    </span>
+  )
+}
+
+// What the previews button says about how they get made here, and the one-tap fixes.
+function ThumbNote({ st, sudo, onChanged }: { st: ThumbStatus | null; sudo: boolean; onChanged: () => void }) {
+  const [task, setTask] = useState<{ id: string; restart: boolean } | null>(null)
+  const [waiting, setWaiting] = useState(false)
+  // the GPU fix ends by restarting Ham Lab: poll until it answers again, then re-read the status
+  useEffect(() => {
+    if (!waiting) return
+    const t = setInterval(async () => { try { await api.thumbStatus(sudo, true); setWaiting(false); onChanged() } catch { /* restarting */ } }, 3000)
+    return () => clearInterval(t)
+  }, [waiting, sudo, onChanged])
+  if (!st) return null
+  const blocked = (st.unusable ?? []).filter((g) => g.permission)
+  const start = async (label: string, fn: () => Promise<{ id: string }>, restart: boolean) => {
+    try { const t = await fn(); setTask({ id: t.id, restart }) } catch (e) { toast(`${label} — ${e instanceof Error ? e.message : 'failed'}`, 'err') }
+  }
+  return (
+    <>
+      {!st.ok && (
+        <div className="thumb-note notice">
+          <span>Previews need ffmpeg: {st.error || 'it is not installed on this machine'}.</span>
+          {st.install && !task && <Btn className="btn on" onClick={() => start('install', api.thumbInstall, false)}>Install ffmpeg with {st.install.pm}</Btn>}
+        </div>
+      )}
+      {st.ok && blocked.length > 0 && (
+        <div className="thumb-note notice">
+          <span>{blocked.map((g) => g.name || g.device).join(', ')} is here, but Ham Lab runs as {st.user} and can't open {blocked.length > 1 ? 'them' : 'it'} ({blocked[0].reason}). Previews of videos are on the CPU until it can.</span>
+          {st.gpu_fix && !task && !waiting && <Btn className="btn on" confirm="Ham Lab adds itself to the GPU's group and restarts. Open terminals are interrupted. Continue?" onClick={() => start('GPU access', api.thumbGPUAccess, true)}>Allow GPU access</Btn>}
+          {waiting && <span className="muted small"><Spinner /> Ham Lab is restarting; the page reconnects by itself.</span>}
+        </div>
+      )}
+      {task && <TaskOutput id={task.id} onDone={(t) => { const ok = t.exit_code === 0 && !t.error; if (ok && task.restart) setWaiting(true); else if (ok) onChanged(); else toast('failed — the output says where', 'err'); setTask(null) }} />}
+    </>
+  )
+}
 
 // ---- editor / viewer ----
 function Viewer({ path, sudo, onClose, onChanged }: { path: string; sudo: boolean; onClose: () => void; onChanged: () => void }) {
@@ -30,11 +204,12 @@ function Viewer({ path, sudo, onClose, onChanged }: { path: string; sudo: boolea
   const [orig, setOrig] = useState('')
   const [err, setErr] = useState('')
   const [saving, setSaving] = useState(false)
+  const [cantPlay, setCantPlay] = useState(false) // the browser tried the file as it is and gave up
   const name = path.split('/').pop() ?? path
   const dirty = text !== null && text !== orig
 
   useEffect(() => {
-    setInfo(null); setText(null); setErr('')
+    setInfo(null); setText(null); setErr(''); setCantPlay(false)
     let stop = false
     ;(async () => {
       try {
@@ -92,8 +267,16 @@ function Viewer({ path, sudo, onClose, onChanged }: { path: string; sudo: boolea
         <textarea className="editor file-editor" value={text} spellCheck={false} onChange={(e) => setText(e.target.value)} />
       )}
       {info && text === null && isImage(name) && <div className="preview"><img src={api.fileReadURL(path, sudo)} alt={name} /></div>}
-      {info && text === null && !isImage(name) && !err && (
-        <div className="notice">{info.type === 'dir' ? 'This is a directory.' : info.size > MAX_EDIT ? `Too large to edit here (${fmtBytes(info.size)}). Download it instead.` : 'Binary file. Download it instead.'}</div>
+      {/* Video: the player (Auto, by hand, or the file as it is), made on the Transcode device. Audio as it is. */}
+      {info && text === null && !isImage(name) && info.preview === 'video' && <Player path={path} sudo={sudo} name={name} />}
+      {info && text === null && !isImage(name) && info.preview === 'audio' && !cantPlay && (
+        <div className="preview audio"><div className="audio-box"><div className="ficon">🎵</div><div className="mono small">{name}</div><audio controls preload="metadata" src={api.fileReadURL(path, sudo)} onError={() => setCantPlay(true)} /></div></div>
+      )}
+      {info && text === null && !isImage(name) && info.preview === 'audio' && cantPlay && (
+        <div className="notice">This browser can't play {name} as it is — the codec isn't one it decodes. Download it instead.</div>
+      )}
+      {info && text === null && !isImage(name) && !info.preview && !err && (
+        <div className="notice">{info.type === 'dir' ? 'This is a directory.' : info.type === 'other' ? 'This is a device, pipe or socket — nothing to show.' : info.broken ? `This link points at nothing (${info.target}).` : info.size > MAX_EDIT ? `Too large to edit here (${fmtBytes(info.size)}). Download it instead.` : 'Binary file. Download it instead.'}</div>
       )}
     </div>
   )
@@ -114,10 +297,19 @@ export default function Files({ onOpenInTerminal }: { onOpenInTerminal?: (cmd: s
   const [pathInput, setPathInput] = useState(path)
   const [open, setOpen] = useState<string | null>(null)
   const [menu, setMenu] = useState<string | null>(null)
+  const [moving, setMoving] = useState<FileEntry | null>(null)
+  const [moveTask, setMoveTask] = useState<TaskInfo | null>(null)
   const [upload, setUpload] = useState<{ name: string; pct: number; n: number; of: number } | null>(null)
   const [drag, setDrag] = useState(false)
   const fileInput = useRef<HTMLInputElement>(null)
   const canSudo = useRef(true)
+  const [previews, setPreviews] = useState<boolean>(() => { try { return localStorage.getItem(PREVIEWS_KEY) === '1' } catch { return false } })
+  const [thumbs, setThumbs] = useState<ThumbStatus | null>(null)
+  const [listEl, setListEl] = useState<HTMLDivElement | null>(null)
+  const near = useMemo(() => (listEl && previews ? new Near(listEl) : null), [listEl, previews])
+  const readThumbs = useCallback((refresh = false) => { api.thumbStatus(sudo, refresh).then(setThumbs).catch((e) => setThumbs({ ok: false, engine: '', summary: '', gpus: [], error: e instanceof Error ? e.message : 'failed', user: '', cache: { path: '', entries: 0, bytes: 0 } })) }, [sudo])
+  useEffect(() => { try { localStorage.setItem(PREVIEWS_KEY, previews ? '1' : '0') } catch { /* private mode */ } }, [previews])
+  useEffect(() => { if (previews) readThumbs(); else setThumbs(null) }, [previews, readThumbs])
 
   const load = useCallback(async (p = path, s = sudo) => {
     try {
@@ -127,15 +319,22 @@ export default function Files({ onOpenInTerminal }: { onOpenInTerminal?: (cmd: s
       sessionStorage.setItem('hamlab.files.path', p) // only a folder that opened is worth coming back to
     } catch (e) {
       const msg = e instanceof Error ? e.message : 'failed'
+      if (/not a directory/i.test(msg) && p !== '/') { // a file was typed: open it, from its folder
+        setPath(p.slice(0, p.lastIndexOf('/')) || '/'); setOpen(p); return
+      }
+      if (/no such file/i.test(msg) && p !== '/' && !sessionStorage.getItem('hamlab.files.lost')) { // gone since last time (another machine, a deleted folder)
+        sessionStorage.setItem('hamlab.files.lost', '1'); toast(`${p} isn't here — showing /`, 'info'); setPath('/'); return
+      }
       setErr(msg); setEntries([])
     }
+    sessionStorage.removeItem('hamlab.files.lost')
   }, [path, sudo])
 
   useEffect(() => { setEntries(null); setPathInput(path); setMenu(null); load(path, sudo); sessionStorage.setItem('hamlab.files.sudo', sudo ? '1' : '0') }, [path, sudo, load])
   useEffect(() => { const h = () => setMenu(null); window.addEventListener('click', h); return () => window.removeEventListener('click', h) }, [])
   useEscape(() => setMenu(null), menu !== null)
 
-  const go = (p: string) => { setOpen(null); setPath(p || '/') }
+  const go = (p: string) => { setOpen(null); setPath(resolvePath(p, path)) }
   const crumbs = path === '/' ? [] : path.slice(1).split('/')
 
   const shown = (entries ?? []).filter((e) => (hidden || !e.name.startsWith('.')) && (!q || e.name.toLowerCase().includes(q.toLowerCase())))
@@ -147,15 +346,13 @@ export default function Files({ onOpenInTerminal }: { onOpenInTerminal?: (cmd: s
     })
 
   // ---- actions ----
-  const act = async (label: string, fn: () => Promise<unknown>) => {
-    try { await fn(); toast(label); await load() } catch (e) { toast(`${label} — ${e instanceof Error ? e.message : 'failed'}`, 'err') }
+  const act = async (label: string, fn: () => Promise<unknown>): Promise<boolean> => {
+    try { await fn(); toast(label); await load(); return true } catch (e) { toast(`${label} — ${e instanceof Error ? e.message : 'failed'}`, 'err'); return false }
   }
-  // A name is one path segment. ("../x" and "a/b" would quietly act somewhere else.)
-  const okName = (n?: string | null): n is string => { const t = n?.trim(); if (!t) return false; if (t.includes('/') || t === '.' || t === '..') { toast('a name can\'t contain / or be . or .. — use Move… to put it elsewhere', 'err'); return false } return true }
   const mkdir = async () => { const n = await askText('New folder name'); if (okName(n)) act(`created ${n.trim()}`, () => api.fileMkdir(join(path, n.trim()), sudo)) }
-  const touch = async () => { const n = await askText('New file name'); if (okName(n)) act(`created ${n.trim()}`, () => api.fileTouch(join(path, n.trim()), sudo)).then(() => setOpen(join(path, n.trim()))) }
+  const touch = async () => { const n = await askText('New file name'); if (okName(n) && await act(`created ${n.trim()}`, () => api.fileTouch(join(path, n.trim()), sudo))) setOpen(join(path, n.trim())) } // opened only once it exists
   const rename = async (e: FileEntry) => { const n = await askText('Rename to', e.name); if (okName(n) && n.trim() !== e.name) act(`renamed to ${n.trim()}`, () => api.fileRename(join(path, e.name), join(path, n.trim()), sudo)) }
-  const move = async (e: FileEntry) => { const n = await askText('Move to (absolute path)', join(path, e.name)); if (n?.trim() && n.trim() !== join(path, e.name)) act(`moved to ${n.trim()}`, () => api.fileRename(join(path, e.name), n.trim(), sudo)) }
+  const move = (e: FileEntry) => setMoving(e)
   const chmod = async (e: FileEntry) => { const n = await askText(`Permissions for ${e.name} (octal)`, e.perm); if (n?.trim() && n.trim() !== e.perm) act(`chmod ${n.trim()} ${e.name}`, () => api.fileChmod(join(path, e.name), n.trim(), sudo)) }
   const del = async (e: FileEntry) => {
     const full = join(path, e.name)
@@ -171,6 +368,7 @@ export default function Files({ onOpenInTerminal }: { onOpenInTerminal?: (cmd: s
   // ---- upload ----
   const uploadFiles = async (files: FileList | File[]) => {
     const list = Array.from(files)
+    let done = 0
     for (let i = 0; i < list.length; i++) {
       const f = list[i]
       let overwrite = false
@@ -181,13 +379,22 @@ export default function Files({ onOpenInTerminal }: { onOpenInTerminal?: (cmd: s
       setUpload({ name: f.name, pct: 0, n: i + 1, of: list.length })
       try {
         await api.fileUpload(path, f, sudo, (pct) => setUpload({ name: f.name, pct, n: i + 1, of: list.length }), overwrite)
+        done++
       } catch (e) { toast(`upload ${f.name} — ${e instanceof Error ? e.message : 'failed'}`, 'err'); break }
     }
     setUpload(null)
-    toast(list.length === 1 ? `uploaded ${list[0].name}` : `uploaded ${list.length} files`)
-    load()
+    if (done === 1) toast(`uploaded ${list.length === 1 ? list[0].name : '1 file'}`)
+    else if (done > 1) toast(`uploaded ${done} files`)
+    if (done > 0) load()
+  }
+  // A dropped folder arrives as a nameless 0-byte "file"; the browser gives no way to read it here.
+  const onDrop = (e: DragEvent) => {
+    e.preventDefault(); setDrag(false)
+    const items = Array.from(e.dataTransfer.items ?? [])
+    const files = Array.from(e.dataTransfer.files).filter((_, i) => !(items[i]?.webkitGetAsEntry?.()?.isDirectory))
+    if (files.length < e.dataTransfer.files.length) toast('folders can\'t be dropped — drop the files inside, or upload a zip', 'err')
+    if (files.length) uploadFiles(files)
   }
-  const onDrop = (e: DragEvent) => { e.preventDefault(); setDrag(false); if (e.dataTransfer.files.length) uploadFiles(e.dataTransfer.files) }
 
   if (open) return <div className="files"><Viewer path={open} sudo={sudo} onClose={() => setOpen(null)} onChanged={() => load()} /></div>
 
@@ -202,6 +409,7 @@ export default function Files({ onOpenInTerminal }: { onOpenInTerminal?: (cmd: s
         <div className="files-tools">
           <button className={'btn' + (sudo ? ' on' : '')} title="browse as root" onClick={() => setSudo(!sudo)}>{sudo ? 'root' : 'sudo'}</button>
           <button className={'btn' + (hidden ? ' on' : '')} title="show hidden files" onClick={() => setHidden(!hidden)}>.hidden</button>
+          <button className={'btn' + (previews ? ' on' : '')} title={'thumbnails for images and videos' + (thumbs ? ` — ${thumbs.summary}` + (thumbs.cache.entries ? ` · ${thumbs.cache.entries} kept (${fmtBytes(thumbs.cache.bytes)})` : '') : '')} onClick={() => setPreviews(!previews)}>previews</button>
           <select className="btn" value={sort} onChange={(e) => setSort(e.target.value as Sort)}><option value="name">name</option><option value="size">size</option><option value="mtime">modified</option></select>
           <input className="filter" placeholder="filter" value={q} onChange={(e) => setQ(e.target.value)} />
           <button className="btn" onClick={mkdir}>+ folder</button>
@@ -213,10 +421,13 @@ export default function Files({ onOpenInTerminal }: { onOpenInTerminal?: (cmd: s
         </div>
       </div>
 
+      {previews && <ThumbNote st={thumbs} sudo={sudo} onChanged={() => readThumbs(true)} />}
+      {moveTask && <TaskOutput id={moveTask.id} onDone={(t) => { load(); if (t.exit_code === 0 && !t.error) toast(`${moveTask.title}: done`); else toast(`${moveTask.title}: failed`, 'err') }} />}
+      {moveTask && <div className="thumb-note"><button className="btn" onClick={() => setMoveTask(null)}>Hide output</button></div>}
       {upload && <div className="upload-bar"><Spinner /> {upload.of > 1 ? `${upload.n}/${upload.of} · ` : ''}{upload.name} · {upload.pct}%<div className="meter"><div className="fill" style={{ width: `${upload.pct}%` }} /></div></div>}
       {err && <div className="error" style={{ padding: '6px 12px' }}>{err}{/permission denied/i.test(err) && !sudo && <> · <button className="link" onClick={() => setSudo(true)}>retry as root</button></>}</div>}
 
-      <div className="file-list">
+      <div className={'file-list' + (previews ? ' thumbs' : '')} ref={setListEl}>
         {entries === null && <Loading label="Listing…" />}
         {path !== '/' && entries !== null && (
           <div className="file-row up" onClick={() => go(path.slice(0, path.lastIndexOf('/')) || '/')}><span className="ficon">↩</span><span className="fname">..</span></div>
@@ -226,7 +437,9 @@ export default function Files({ onOpenInTerminal }: { onOpenInTerminal?: (cmd: s
           const isDir = e.type === 'dir'
           return (
             <div key={e.name} className={'file-row' + (e.broken ? ' broken' : '')} onClick={() => (isDir ? go(full) : setOpen(full))}>
-              <span className="ficon">{icon(e)}</span>
+              {previews && e.preview && thumbs?.ok
+                ? <Thumb url={api.fileThumbURL(full, sudo, e.mtime, e.size)} kind={e.preview} near={near} fallback={icon(e)} />
+                : <span className="ficon">{icon(e)}</span>}
               <span className="fname" title={e.target ? `→ ${e.target}` : e.name}>{e.name}{e.target && <span className="muted"> → {e.target}</span>}</span>
               <span className="fmeta num">{isDir ? '' : fmtBytes(e.size)}</span>
               <span className="fmeta num">{fmtTime(e.mtime)}</span>
@@ -249,6 +462,7 @@ export default function Files({ onOpenInTerminal }: { onOpenInTerminal?: (cmd: s
         {entries !== null && shown.length === 0 && !err && <div className="muted" style={{ padding: 12 }}>{q ? 'Nothing matches.' : 'Empty folder.'}{!hidden && entries.some((e) => e.name.startsWith('.')) ? ' (hidden files not shown)' : ''}</div>}
       </div>
       {drag && <div className="drop-hint">Drop to upload into {path}</div>}
+      {moving && <MovePicker item={moving} from={path} sudo={sudo} hidden={hidden} onClose={() => setMoving(null)} onMoved={(t) => { setMoving(null); if (t) setMoveTask(t); load() }} />}
     </div>
   )
 }

web/src/Gallery.tsx

@@ -37,8 +37,8 @@ export default function Gallery() {
   const rate = useRefreshMs()
   const [find, setFind] = useState('')
   useEffect(() => { fetchCatalog().then(setCat).catch((e) => setErr(e instanceof Error ? e.message : 'failed')) }, [])
-  // Values only, at most once a second: the catalog already holds everything that doesn't change.
-  const live = useSensorStream<[Record<string, Sensor['value']>]>(['*'], { full: false, everyMs: Math.max(1000, rate) })
+  // Values only, at the rate: the catalog already holds everything that doesn't change.
+  const live = useSensorStream<[Record<string, Sensor['value']>]>(['*'], { full: false, everyMs: rate })
   const now = Date.now()
   const sensors = useMemo(() => {
     const v = live.data?.[0]
@@ -57,6 +57,13 @@ export default function Gallery() {
 
   return (
     <div className="dash gallery">
+      <div className="notice" style={{ marginBottom: 10 }}>
+        These widgets are for <b>dashboards outside Ham Lab</b> — Glance, Home Assistant, a wall
+        display. Each one is a page at <span className="mono">/embed/widget</span> you put in an
+        iframe, reading this machine through a <b>read-only sensor token</b> (Settings → Access
+        tokens). Ham Lab shows you these numbers on its own pages; this tab is for handing them
+        to something else.
+      </div>
       <div className="dash-bar">
         <span className="hint">{needle ? `${shown.length} of ${sensors.length}` : sensors.length} sensors on this machine · live · tap a tile to copy its ID</span>
         <input className="gallery-find" value={find} onChange={(e) => setFind(e.target.value)} placeholder="find — gitea, temp, enp3s0…" spellCheck={false} autoCapitalize="off" />

web/src/Hardware.tsx

@@ -0,0 +1,262 @@
+// Hardware: what this machine is made of — the board, the processor, the memory modules in
+// their slots, the drives and the graphics. None of it moves, so the page is a read rather
+// than a monitor: what is live (temperature, usage, SMART) belongs to Dashboard and Disks.
+import { useCallback, useEffect, useState } from 'react'
+import { api, Hardware as HW, HWBoard, HWDrive, HWGPU, HWModule } from './api'
+import { fmtBytes } from './fmt'
+import { Btn, Loading } from './ui'
+
+const KIND: Record<string, string> = { nvme: 'NVMe', ssd: 'SSD', hdd: 'HDD', usb: 'USB', emmc: 'eMMC', sd: 'SD', other: 'disk' }
+const ghz = (mhz?: number) => (mhz ? `${(mhz / 1000).toFixed(mhz >= 1000 ? 2 : 1)} GHz` : '')
+
+// A row of the "key: value" kind, dropped entirely when there is no value — a machine that
+// doesn't report its serial should show one fewer line, not an empty one.
+function P({ k, v, mono }: { k: string; v?: string | number | null | false; mono?: boolean }) {
+  if (v === undefined || v === null || v === false || v === '' || v === 0) return null
+  return <div><span className="k">{k}</span><span className={mono ? 'mono' : undefined} title={String(v)}>{v}</span></div>
+}
+
+function Module({ m }: { m: HWModule }) {
+  if (m.empty) {
+    return (
+      <div className="sub-card">
+        <div className="sub-head"><span className="dname muted">{m.locator}</span><span className="spacer" /><span className="badge">empty</span></div>
+      </div>
+    )
+  }
+  const speed = m.running_mts && m.speed_mts && m.running_mts !== m.speed_mts
+    ? `${m.running_mts} MT/s (rated ${m.speed_mts})` // the board is running it slower than it could
+    : m.running_mts || m.speed_mts ? `${m.running_mts || m.speed_mts} MT/s` : ''
+  return (
+    <div className="sub-card">
+      <div className="sub-head">
+        <span className="dname">{fmtBytes(m.size ?? 0)} {m.type}</span>
+        <span className="spacer" />
+        <span className="model mono">{m.locator}</span>
+      </div>
+      <div className="props">
+        <P k="Maker" v={m.maker} />
+        <P k="Form" v={m.form_factor} />
+        <P k="Part" v={m.part} mono />
+        <P k="Speed" v={speed} />
+        <P k="Rank" v={m.rank ? `${m.rank}R` : ''} />
+        <P k="Voltage" v={m.voltage} />
+        <P k="Serial" v={m.serial} mono />
+      </div>
+    </div>
+  )
+}
+
+function Drive({ d }: { d: HWDrive }) {
+  return (
+    <div className="sub-card">
+      <div className="sub-head">
+        <span className="dname">{d.model || d.name}</span>
+        <span className="spacer" />
+        <span className="badge">{KIND[d.kind] ?? d.kind}</span>
+      </div>
+      <div className="props">
+        <P k="Size" v={fmtBytes(d.size)} />
+        <P k="Device" v={`/dev/${d.name}`} mono />
+        <P k="Bus" v={d.tran ? d.tran.toUpperCase() : ''} />
+        <P k="Spins" v={d.rotational ? 'yes — mechanical' : 'no — solid state'} />
+        <P k="Firmware" v={d.firmware} mono />
+        <P k="Serial" v={d.serial} mono />
+        <P k="Vendor" v={d.vendor} />
+      </div>
+    </div>
+  )
+}
+
+function Gpu({ g }: { g: HWGPU }) {
+  return (
+    <div className="sub-card">
+      <div className="sub-head">
+        <span className="dname">{g.model}</span>
+        <span className="spacer" />
+        {g.class && <span className="badge">{g.class}</span>}
+      </div>
+      <div className="props">
+        <P k="Vendor" v={g.vendor} />
+        <P k="Driver" v={g.driver} mono />
+        <P k="Memory" v={g.memory ? fmtBytes(g.memory) : ''} />
+        <P k="Slot" v={g.slot} mono />
+        <P k="Node" v={g.node} mono />
+      </div>
+    </div>
+  )
+}
+
+// The board and the firmware on it. Everything here is SMBIOS, so a machine without one
+// — a Mac, a Pi — gets a card that says as much instead of a column of blanks.
+function Motherboard({ b }: { b: HWBoard }) {
+  const named = b.maker || b.product || b.bios
+  // A board that reports every slot "Available" is not telling us anything — mini PCs
+  // copy the slot table out of a reference design and list slots the case has no room
+  // for. Only worth showing when the firmware actually tracks what is plugged in.
+  const slots = (b.slots ?? []).some((s) => s.usage === 'In Use') ? (b.slots ?? []) : []
+  return (
+    <section className="card">
+      <h2>Motherboard</h2>
+      {!named && <div className="empty">This machine has no SMBIOS table, so its firmware doesn't say what board it is.</div>}
+      {named && (
+        <div className="props">
+          <P k="Maker" v={b.maker} />
+          <P k="Model" v={b.product} />
+          <P k="Version" v={b.version} />
+          <P k="Kind" v={b.type} />
+          <P k="Chassis" v={[b.chassis_maker, b.chassis].filter(Boolean).join(' ')} />
+          <P k="In chassis" v={b.location} />
+          <P k="Serial" v={b.serial} mono />
+          <P k="Asset tag" v={b.asset_tag} mono />
+        </div>
+      )}
+      {(b.bios || b.bios_date) && (
+        <div className="props" style={{ marginTop: 8 }}>
+          <P k="Firmware" v={b.bios} />
+          <P k="Revision" v={b.bios_revision} />
+          <P k="Dated" v={b.bios_date} />
+          <P k="ROM" v={b.rom_size} />
+          <P k="Boots" v={b.uefi ? 'UEFI' : ''} />
+        </div>
+      )}
+      {slots.length > 0 && (
+        <div style={{ marginTop: 8 }}>
+          <div className="sub-head"><span className="dname">Expansion slots</span><span className="spacer" /><span className="muted small">as the firmware lists them</span></div>
+          <table className="dtable">
+            <thead><tr><th>Slot</th><th>Type</th><th>What is in it</th></tr></thead>
+            <tbody>{slots.map((s, i) => (
+              <tr key={s.designation + i}>
+                <td className="mono small">{s.designation}</td>
+                <td className="mono small">{[s.type, s.length && s.length !== 'Other' ? s.length.toLowerCase() : ''].filter(Boolean).join(' · ')}</td>
+                <td className="small" title={s.bus}>{s.usage === 'In Use' ? (s.device ?? s.bus ?? 'in use') : <span className="muted">{(s.usage ?? '').toLowerCase() || '—'}</span>}</td>
+              </tr>
+            ))}</tbody>
+          </table>
+        </div>
+      )}
+    </section>
+  )
+}
+
+export default function Hardware() {
+  const [hw, setHw] = useState<HW | null>(null)
+  const [err, setErr] = useState('')
+  const [busy, setBusy] = useState(false)
+  const load = useCallback(async (refresh = false) => {
+    if (refresh) setBusy(true)
+    try { setHw(await api.hardware(refresh)); setErr('') } catch (e) { setErr(e instanceof Error ? e.message : 'failed') } finally { setBusy(false) }
+  }, [])
+  useEffect(() => { load() }, [load])
+
+  if (err) return <div className="dash"><div className="notice">{err === 'not found' ? "This machine's Ham Lab is older than the Hardware tab. Update it from Machines." : err}</div></div>
+  if (!hw) return <div className="dash"><Loading label="Reading the machine…" /></div>
+
+  const { system: sys, board, cpu, memory: mem } = hw
+  const drives = hw.drives ?? []
+  const gpus = hw.gpus ?? []
+  const capacity = drives.reduce((n, d) => n + d.size, 0)
+  const threads = cpu.threads ?? 0
+  const cores = cpu.cores ?? 0
+
+  return (
+    <div className="dash">
+      <div className="dash-bar">
+        <span className="status"><b>{sys.model || 'this machine'}</b></span>
+        {sys.virt && <span className="badge" title="this is a virtual machine, so the parts below are what the host handed it">{sys.virt}</span>}
+        <span className="spacer" style={{ flex: 1 }} />
+        <Btn className="btn" busy={busy} onClick={() => load(true)}>Re-read</Btn>
+      </div>
+
+      <div className="kpis">
+        <div className="tile">
+          <div className="label">Processor</div>
+          <div className="value" title={cpu.model} style={(cpu.model?.length ?? 0) > 20 ? { fontSize: 16 } : undefined}>{cpu.model}</div>
+          <div className="sub">{[cores ? `${cores} core${cores === 1 ? '' : 's'}` : '', threads && threads !== cores ? `${threads} threads` : '', cpu.max_mhz ? `up to ${ghz(cpu.max_mhz)}` : ''].filter(Boolean).join(' · ')}</div>
+        </div>
+        <div className="tile">
+          <div className="label">Memory</div>
+          <div className="value">{fmtBytes(mem.installed || mem.total)}</div>
+          <div className="sub">{mem.slots ? `${mem.filled ?? 0} of ${mem.slots} slot${mem.slots === 1 ? '' : 's'} filled` : 'slots unknown'}{mem.ecc ? ` · ${mem.ecc}` : ''}</div>
+        </div>
+        <div className="tile">
+          <div className="label">Storage</div>
+          <div className="value">{fmtBytes(capacity)}</div>
+          <div className="sub">{drives.length} drive{drives.length === 1 ? '' : 's'}</div>
+        </div>
+        <div className="tile">
+          <div className="label">Graphics</div>
+          <div className="value" title={gpus[0]?.model} style={(gpus[0]?.model?.length ?? 0) > 20 ? { fontSize: 16 } : undefined}>{gpus[0]?.model ?? 'none found'}</div>
+          <div className="sub">{gpus.length > 1 ? `${gpus.length} adapters` : gpus[0]?.driver ? `${gpus[0].driver} driver` : ''}</div>
+        </div>
+      </div>
+
+      {(hw.notes ?? []).map((n, i) => <div className="notice" key={i}>{n}</div>)}
+
+      <div className="cards">
+        <section className="card">
+          <h2>Processor</h2>
+          <div className="props">
+            <P k="Model" v={cpu.model} />
+            <P k="Vendor" v={cpu.vendor} />
+            <P k="Cores" v={cores ? `${cores}${cpu.threads_per_core && cpu.threads_per_core > 1 ? ` · ${cpu.threads_per_core} threads each` : ''}` : ''} />
+            <P k="Clock" v={cpu.min_mhz && cpu.max_mhz ? `${ghz(cpu.min_mhz)} – ${ghz(cpu.max_mhz)}` : ghz(cpu.max_mhz)} />
+            <P k="Socket" v={(cpu.socket_names ?? []).join(', ')} />
+            <P k="Arch" v={cpu.arch} />
+            <P k="Family" v={[cpu.family && `family ${cpu.family}`, cpu.model_id && `model ${cpu.model_id}`, cpu.stepping && `stepping ${cpu.stepping}`].filter(Boolean).join(' · ')} />
+            <P k="Microcode" v={cpu.microcode} mono />
+            <P k="Virt" v={cpu.virtualization} />
+          </div>
+          {(cpu.caches ?? []).length > 0 && (
+            <div className="props" style={{ marginTop: 8 }}>
+              {(cpu.caches ?? []).map((c) => <P key={c.level} k={c.level} v={c.size} />)}
+            </div>
+          )}
+          {(cpu.flags ?? []).length > 0 && (
+            <div className="chips" style={{ marginTop: 8 }}>{(cpu.flags ?? []).map((f) => <span className="badge" key={f}>{f}</span>)}</div>
+          )}
+        </section>
+
+        <section className="card">
+          <h2>Memory</h2>
+          <div className="props">
+            <P k="Installed" v={mem.installed ? fmtBytes(mem.installed) : ''} />
+            <P k="Usable" v={fmtBytes(mem.total)} />
+            <P k="Board takes" v={mem.max_capacity ? fmtBytes(mem.max_capacity) : ''} />
+            <P k="ECC" v={mem.ecc} />
+          </div>
+          <div style={{ marginTop: 8 }}>
+            {(mem.modules ?? []).map((m, i) => <Module key={m.locator + i} m={m} />)}
+            {(mem.modules ?? []).length === 0 && <div className="empty">The firmware doesn't say what is in the slots.</div>}
+          </div>
+        </section>
+
+        <section className="card">
+          <h2>Drives</h2>
+          {drives.map((d) => <Drive key={d.name} d={d} />)}
+          {drives.length === 0 && <div className="empty">No drives found.</div>}
+        </section>
+
+        <section className="card">
+          <h2>Graphics</h2>
+          {gpus.map((g, i) => <Gpu key={(g.slot ?? '') + i} g={g} />)}
+          {gpus.length === 0 && <div className="empty">No display adapter found.</div>}
+        </section>
+
+        <Motherboard b={board} />
+
+        <section className="card">
+          <h2>System</h2>
+          <div className="props">
+            <P k="Model" v={sys.model} />
+            <P k="Family" v={sys.family} />
+            <P k="Serial" v={sys.serial} mono />
+            <P k="Kernel" v={sys.kernel} mono />
+            <P k="Arch" v={sys.arch} />
+            <P k="Virtual" v={sys.virt} />
+          </div>
+        </section>
+      </div>
+    </div>
+  )
+}

web/src/Jobs.tsx

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
+import { describeCron } from './crontext'
 import { api, CronJob, CronOverview, CronRun, CronTimer, LogEntry } from './api'
 import { Logs } from './Services'
 import { askYes, Btn, CloseBtn, Loading, Spinner, toast } from './ui'
@@ -13,22 +14,7 @@ function rel(ms: number): string {
   return s >= 0 ? `in ${txt}` : `${txt} ago`
 }
 
-// Plain-English reading of the common five-field shapes; anything else shows the raw expression.
-function describe(expr: string): string {
-  const alias: Record<string, string> = { '@reboot': 'at boot', '@hourly': 'every hour', '@daily': 'every day at 00:00', '@midnight': 'every day at 00:00', '@weekly': 'every Sunday at 00:00', '@monthly': 'on the 1st at 00:00', '@yearly': 'every 1 Jan', '@annually': 'every 1 Jan' }
-  if (alias[expr]) return alias[expr]
-  const f = expr.split(/\s+/)
-  if (f.length !== 5) return expr
-  const [mi, h, dom, mon, dow] = f
-  const days = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
-  const at = /^\d+$/.test(mi) && /^\d+$/.test(h) ? `at ${h.padStart(2, '0')}:${mi.padStart(2, '0')}` : /^\d+$/.test(mi) && h === '*' ? `every hour at :${mi.padStart(2, '0')}` : mi.startsWith('*/') && h === '*' ? `every ${mi.slice(2)} min` : null
-  if (!at) return expr
-  const dowTxt = dow === '*' ? '' : /^\d$/.test(dow) ? `every ${days[+dow]}` : `on days ${dow}`
-  const domTxt = dom === '*' ? '' : /^\d+$/.test(dom) ? `on the ${dom}${['st', 'nd', 'rd'][+dom - 1] ?? 'th'}` : `on days ${dom}`
-  const monTxt = mon === '*' ? '' : `in month ${mon}`
-  const when = [dowTxt, domTxt, monTxt].filter(Boolean).join(', ')
-  return (when ? `${when} ` : dow === '*' && dom === '*' && !at.startsWith('every') ? 'every day ' : '') + at
-}
+const describe = (expr: string) => describeCron(expr) || expr
 
 const srcLabel = (s: string) => (s.startsWith('crontab:') ? `${s.slice(8)}'s crontab` : s)
 
@@ -175,11 +161,11 @@ function TimerDetail({ t, onChanged, onBack }: { t: CronTimer; onChanged: () =>
 }
 
 // ---- page ----
-export default function Cron() {
+export default function Jobs() {
   const [ov, setOv] = useState<CronOverview | null>(null)
   const [err, setErr] = useState('')
   const [q, setQ] = useState('')
-  const [hashSel, setHashSel] = useHashSel('cron') // "job:<id>" or "timer:<unit>", in the URL
+  const [hashSel, setHashSel] = useHashSel('jobs') // "job:<id>" or "timer:<unit>", in the URL
   const sel = /^(job|timer):./.test(hashSel) ? { kind: hashSel.split(':')[0] as 'job' | 'timer', id: hashSel.slice(hashSel.indexOf(':') + 1) } : null
   const setSel = (v: { kind: 'job' | 'timer'; id: string } | null) => setHashSel(v ? `${v.kind}:${v.id}` : '')
   const [editing, setEditing] = useState<string | null>(null)
@@ -206,7 +192,7 @@ export default function Cron() {
   else pane = <div className="svc-empty muted">Select a job or timer.</div>
 
   return (
-    <div className={'cron' + (sel || editing ? ' has-sel' : '')}>
+    <div className={'cron jobs' + (sel || editing ? ' has-sel' : '')}>
       <div className="cron-list">
         <div className="svc-tools">
           <div className="tools-row"><input placeholder="filter jobs and timers" value={q} onChange={(e) => setQ(e.target.value)} /><Btn className="btn" title="reload" onClick={load}>↻</Btn></div>
@@ -218,7 +204,7 @@ export default function Cron() {
         {ov && !ov.logging && <div className="notice" style={{ margin: 8 }}>cron isn’t logging to the journal on this host, so “last run” is unavailable for cron jobs.</div>}
         <div className="cron-rows">
           {!ov && !err && <Loading label="Reading crontabs…" />}
-          {ov && <h3>Cron jobs · {jobs.length}</h3>}
+          {ov && <h3>Scheduled jobs · {jobs.length}</h3>}
           {jobs.map((j) => (
             <div key={j.id} className={'cron-row' + (sel?.kind === 'job' && sel.id === j.id ? ' active' : '') + (j.enabled ? '' : ' off')} onClick={() => { setEditing(null); setSel({ kind: 'job', id: j.id }) }}>
               <span className={'sdot ' + (j.enabled ? 'ok' : '')} />

web/src/KVM.tsx

@@ -0,0 +1,187 @@
+// The KVM of the machine you are looking at: the device's own web page, shown in the tab.
+//
+// One per machine, and it follows the machine switcher — switch to `grid` and you get
+// grid's KVM. The address is held on the **hub**, not on the machine, because a KVM earns
+// its keep exactly when that machine is down and cannot answer for itself; the hub proxies
+// the device either way.
+//
+// Nothing here knows anything about any particular KVM. It is an iframe pointed at Ham
+// Lab's own proxy, so whatever web UI the device serves is what you get.
+//
+// On the keyboard: a page cannot capture keys and forward them into an iframe, and does not
+// need to. An iframe with focus receives them directly. What the browser itself swallows —
+// Escape, Tab, Ctrl-W, the function keys — is what `navigator.keyboard.lock()` releases,
+// and that needs fullscreen and only exists in Chromium. Everywhere else you get the plain
+// version, which is most keys, and the device's own on-screen buttons for the rest.
+import { FormEvent, useCallback, useEffect, useRef, useState } from 'react'
+import { KVM as Device, api } from './api'
+import { Btn, Loading, askYes, toast, useEscape } from './ui'
+
+// lock() releases the keys the browser would otherwise keep for itself. Chromium only; a
+// browser without it simply does not get the extra keys.
+type KeyboardLock = { lock?: (keys?: string[]) => Promise<void>; unlock?: () => void }
+const keyboardAPI = (): KeyboardLock | undefined => (navigator as unknown as { keyboard?: KeyboardLock }).keyboard
+
+// Fullscreen, across the three ways browsers spell it. Safari on a Mac wants the webkit
+// prefix; Safari on iOS has no fullscreen for an ordinary element at all — only for a
+// <video> — so there the page expands inside the viewport instead, which is the same thing
+// minus the browser's own chrome.
+type FSElement = HTMLElement & { webkitRequestFullscreen?: () => Promise<void> | void }
+type FSDocument = Document & { webkitFullscreenElement?: Element | null; webkitExitFullscreen?: () => Promise<void> | void }
+const nativeFullscreen = () => {
+  if (typeof document === 'undefined') return false
+  const el = document.documentElement as FSElement
+  return typeof el.requestFullscreen === 'function' || typeof el.webkitRequestFullscreen === 'function'
+}
+const fullscreenElement = () => (document as FSDocument).fullscreenElement ?? (document as FSDocument).webkitFullscreenElement ?? null
+async function enterFullscreen(el: FSElement) {
+  if (typeof el.requestFullscreen === 'function') return el.requestFullscreen()
+  if (typeof el.webkitRequestFullscreen === 'function') return el.webkitRequestFullscreen()
+  throw new Error('this browser has no fullscreen for a page element')
+}
+function exitFullscreen() {
+  const d = document as FSDocument
+  if (typeof d.exitFullscreen === 'function') return d.exitFullscreen()
+  if (typeof d.webkitExitFullscreen === 'function') return d.webkitExitFullscreen()
+}
+
+export default function KVM({ machine, title }: { machine: string | null; title: string }) {
+  const [kvm, setKvm] = useState<Device | null | undefined>(undefined)
+  const [adding, setAdding] = useState(false)
+  const [err, setErr] = useState('')
+  const [full, setFull] = useState(false)   // native fullscreen is on
+  const [expanded, setExpanded] = useState(false) // the fallback: filling the viewport in-page
+  const box = useRef<HTMLDivElement>(null)
+  const frame = useRef<HTMLIFrameElement>(null)
+  const key = machine ?? '' // the hub is a machine too, and its key is the empty one
+
+  const load = useCallback(async () => {
+    try { setKvm((await api.kvms()).find((k) => k.machine === key) ?? null) }
+    catch (e) { setErr(e instanceof Error ? e.message : 'failed') }
+  }, [key])
+  useEffect(() => { load() }, [load])
+
+  // Fullscreen plus a keyboard lock is what makes Escape and Tab reach the machine rather
+  // than the browser. Both are undone together when fullscreen ends, however it ends.
+  useEffect(() => {
+    const onChange = () => {
+      const on = !!fullscreenElement()
+      setFull(on)
+      if (!on) keyboardAPI()?.unlock?.()
+    }
+    document.addEventListener('fullscreenchange', onChange)
+    document.addEventListener('webkitfullscreenchange', onChange)
+    return () => {
+      document.removeEventListener('fullscreenchange', onChange)
+      document.removeEventListener('webkitfullscreenchange', onChange)
+      keyboardAPI()?.unlock?.()
+    }
+  }, [])
+  // Expanding is in-page, so Escape is ours to handle.
+  useEscape(() => setExpanded(false), expanded)
+
+  const goBig = async () => {
+    if (!nativeFullscreen()) { setExpanded(true); frame.current?.focus(); return }
+    try {
+      if (box.current) await enterFullscreen(box.current)
+      await keyboardAPI()?.lock?.()
+      frame.current?.focus()
+    } catch {
+      setExpanded(true) // refused (an iframe policy, a permissions policy): fill the page instead
+      frame.current?.focus()
+    }
+  }
+  const goSmall = () => { setExpanded(false); if (fullscreenElement()) exitFullscreen() }
+
+  const remove = async () => {
+    if (!kvm || !await askYes(`Forget ${title}'s KVM? The device itself is not touched — this only removes its address.`, 'Remove')) return
+    try { await api.removeKVM(kvm.id); toast('removed'); await load() } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') }
+  }
+
+  if (err && kvm === undefined) return <div className="dash"><div className="error">{err}</div></div>
+  if (kvm === undefined) return <div className="dash"><Loading label="Looking…" /></div>
+
+  const locks = !!keyboardAPI()?.lock
+  const big = full || expanded
+
+  return (
+    <div className="kvm">
+      <div className="kvm-bar">
+        <span className="dname">{title}</span>
+        {kvm
+          ? <span className="muted small mono kvm-url" title={kvm.url}>{kvm.name !== kvm.url ? `${kvm.name} · ` : ''}{kvm.url}</span>
+          : <span className="muted small">no KVM</span>}
+        <span className="spacer" />
+        {kvm && <>
+          <Btn className="btn" onClick={goBig} title={!nativeFullscreen() ? 'fill the screen — this browser has no true fullscreen for a page element' : locks ? 'fullscreen, and the browser stops keeping Escape, Tab and Ctrl-W for itself' : 'fullscreen — this browser will still keep some keys for itself'}>{nativeFullscreen() ? 'Fullscreen' : 'Expand'}</Btn>
+          <a className="btn" href={kvm.url} target="_blank" rel="noreferrer" title="the device directly, outside Ham Lab — only works on the LAN">Open ↗</a>
+          <Btn className="btn" onClick={() => setAdding(true)}>Change</Btn>
+          <Btn className="btn danger" onClick={remove}>Remove</Btn>
+        </>}
+        {!kvm && <Btn className="btn on" onClick={() => setAdding(true)}>+ Add a KVM for {title}</Btn>}
+      </div>
+
+      {kvm ? (
+        <div className={'kvm-frame' + (full ? ' full' : '') + (expanded ? ' expanded' : '')} ref={box}>
+          <iframe ref={frame} key={kvm.id} src={`/kvm/${kvm.id}/`} title={kvm.name}
+            allow="fullscreen; clipboard-read; clipboard-write" />
+          {expanded && <button className="btn kvm-shrink" onClick={goSmall} title="back to the console">Done</button>}
+        </div>
+      ) : (
+        <div className="svc-empty muted kvm-none">
+          <div>
+            <p>No KVM for <b>{title}</b>.</p>
+            <p className="small">Add one with its address and its page appears here. The address is kept on the hub,
+              so it still works when {title} does not — which is when you will want it.</p>
+          </div>
+        </div>
+      )}
+      {kvm && !big && (
+        <div className="kvm-hint muted small">
+          Click the picture, then type — the keys go to {title}.
+          {locks ? ' Fullscreen also takes Escape, Tab and Ctrl-W back from the browser.' : ' This browser keeps Escape, Tab and Ctrl-W for itself; use the device’s own on-screen keys for those, or a Chromium browser.'}
+        </div>
+      )}
+      {adding && <AddDialog machine={key} title={title} existing={kvm} onClose={() => setAdding(false)} onAdded={() => { setAdding(false); load() }} />}
+    </div>
+  )
+}
+
+function AddDialog({ machine, title, existing, onClose, onAdded }: { machine: string; title: string; existing: Device | null; onClose: () => void; onAdded: () => void }) {
+  const [url, setUrl] = useState(existing?.url ?? '')
+  const [name, setName] = useState(existing?.name ?? '')
+  const [err, setErr] = useState('')
+  const [busy, setBusy] = useState(false)
+  useEscape(onClose)
+  const save = async (e: FormEvent) => {
+    e.preventDefault(); setErr(''); setBusy(true)
+    try { await api.addKVM(name.trim(), url.trim(), machine); onAdded() }
+    catch (e) { setErr(e instanceof Error ? e.message : 'failed'); setBusy(false) }
+  }
+  return (
+    <div className="modal-back" onClick={onClose}>
+      <form className="modal" onClick={(e) => e.stopPropagation()} onSubmit={save}>
+        <h3>{existing ? `Change ${title}'s KVM` : `A KVM for ${title}`}</h3>
+        <label className="muted">Address — whatever you would type into a browser
+          <input autoFocus className="mono" value={url} onChange={(e) => setUrl(e.target.value)} placeholder="10.0.0.217" spellCheck={false} autoCapitalize="off" required />
+        </label>
+        <label className="muted">Name — optional; the address is used otherwise
+          <input value={name} onChange={(e) => setName(e.target.value)} placeholder={`${title} KVM`} maxLength={64} />
+        </label>
+        <div className="muted small">
+          Ham Lab serves the device from its own address, so a KVM that speaks only plain HTTP
+          still works here, and it is behind this login rather than needing a second one. The
+          address is kept on the hub, so it still reaches the device when {title} is down. The
+          device itself is not changed and is never reachable from outside.
+          {existing && <> Saving replaces the one there now — a machine has one KVM.</>}
+        </div>
+        {err && <div className="error">{err}</div>}
+        <div className="svc-actions">
+          <button type="submit" className="btn on" disabled={busy || !url.trim()}>{existing ? 'Save' : 'Add'}</button>
+          <span className="spacer" />
+          <button type="button" className="btn" onClick={onClose}>Cancel</button>
+        </div>
+      </form>
+    </div>
+  )
+}

web/src/Login.tsx

@@ -2,6 +2,19 @@ import { FormEvent, useState } from 'react'
 import { api } from './api'
 import { Spinner } from './ui'
 
+// Drawn, not typed: 👁 is an emoji on phones, full colour and its own size. Outline strokes
+// match the glyphs in the rail and the power button.
+const EyeIcon = (
+  <svg viewBox="0 0 16 16" width="17" height="17" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+    <path d="M1.2 8S3.9 3.6 8 3.6 14.8 8 14.8 8 12.1 12.4 8 12.4 1.2 8 1.2 8z" /><circle cx="8" cy="8" r="2.1" />
+  </svg>
+)
+const EyeOffIcon = (
+  <svg viewBox="0 0 16 16" width="17" height="17" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+    <path d="M1.2 8S3.9 3.6 8 3.6 14.8 8 14.8 8 12.1 12.4 8 12.4 1.2 8 1.2 8z" /><circle cx="8" cy="8" r="2.1" /><path d="M2.4 13.6 13.6 2.4" />
+  </svg>
+)
+
 const USER_KEY = 'hamlab.user' // the last account signed in on this device, offered again
 
 export default function Login({ onLogin }: { onLogin: () => void }) {
@@ -9,6 +22,9 @@ export default function Login({ onLogin }: { onLogin: () => void }) {
   const [pw, setPw] = useState('')
   const [err, setErr] = useState('')
   const [busy, setBusy] = useState(false)
+  // Shown on request: a generated password is typed by hand off a message, and a wrong
+  // character looks exactly like a wrong password from here.
+  const [show, setShow] = useState(false)
 
   async function submit(e: FormEvent) {
     e.preventDefault()
@@ -26,8 +42,17 @@ export default function Login({ onLogin }: { onLogin: () => void }) {
         <img className="login-logo" src="/icons/logo.png" alt="Ham Lab" width={176} height={176} />
         <input type="text" autoFocus={!user} autoComplete="username" placeholder="user" spellCheck={false} autoCapitalize="off" autoCorrect="off"
           value={user} onChange={(e) => setUser(e.target.value)} disabled={busy} />
-        <input type="password" autoFocus={!!user} autoComplete="current-password" placeholder="password"
+        <div className="pwfield">
+          {/* revealed, the field is a text field, so the keyboard would otherwise offer to
+              capitalise and correct what is typed into it */}
+          <input type={show ? 'text' : 'password'} autoFocus={!!user} autoComplete="current-password" placeholder="password"
+            spellCheck={false} autoCapitalize="off" autoCorrect="off"
             value={pw} onChange={(e) => setPw(e.target.value)} disabled={busy} />
+          <button type="button" className="pweye" onClick={() => setShow(!show)} disabled={busy}
+            aria-label={show ? 'hide the password' : 'show the password'} aria-pressed={show} title={show ? 'hide' : 'show'}>
+            {show ? EyeOffIcon : EyeIcon}
+          </button>
+        </div>
         <button disabled={busy || !pw}>{busy && <Spinner />}{busy ? 'Signing in…' : 'Sign in'}</button>
         {err && <div className="error">{err}</div>}
       </form>

web/src/Machines.tsx

@@ -54,7 +54,10 @@ export default function Machines({ hub, onChanged, onOpen }: { hub: Me; onChange
     try {
       let res = await api.updateAllMachines()
       const busy = res.filter((r) => !r.ok && (r.error ?? '').startsWith('busy:'))
-      if (busy.length && await askYes(`${busy.map((r) => r.name).join(', ')}: ${busy[0].error?.slice(6)}\n\nForce those too?`)) res = res.map((r) => r).concat(await api.updateAllMachines(true))
+      if (busy.length && await askYes(`${busy.map((r) => r.name).join(', ')}: ${busy[0].error?.slice(6)}\n\nForce those too?`)) {
+        const forced = await api.updateAllMachines(true)
+        res = res.filter((r) => !forced.some((f) => f.name === r.name)).concat(forced) // one line per machine, the forced answer winning
+      }
       for (const r of res) toast(r.ok ? `${r.name} → ${r.version}` : `${r.name}: ${r.error}`, r.ok ? 'ok' : 'err')
       setTimeout(load, 4000)
     } catch (e) { toast(e instanceof Error ? e.message : 'failed', 'err') }