Phase 3: asus-zephyrus-g14 and memory-pressure, with Go tools and long-running code

The laptop model's hardware module and a memory-pressure module for any machine (hq research 027/03, 026/05, to-be 42 phase 3). The predecessor's polling auto-profile and mem-guard user scripts become each module's own Go code launched by the node runtime (ADR 0198): a profile switcher woken by the kernel's power-supply uevents, and a guard that warns on RAM, swap or PSI before systemd-oomd acts, on the desktop over the account's bus and always as an event. supergfxctl and triggerhappy are kept as found (research 027 Q1).
Merge pull request 'The photo clients publish the endpoint they declare (hq issue 227)' (#263 ) from fix/the-photo-admin-client-publishes-the-port-it-declares into main
2026-10-04 12:56:23 +02:00 · 2026-10-04 10:27:22 +00:00 · 2026-10-04 12:25:28 +02:00 · 2026-10-04 10:17:23 +00:00 · 2026-10-04 12:17:08 +02:00 · 2026-10-04 10:01:17 +00:00
167 changed files with 42866 additions and 13 deletions
@@ -0,0 +1,257 @@
+# asus-zephyrus-g14
+
+The hardware module for the **ASUS ROG Zephyrus G14** laptop: its vendor daemon and platform
+profiles, the hybrid GPU's mode and driver options, suspend, the lid and power key, low battery,
+the backlights, the vendor keys and the touchpad (novox/hq research 027/03 *Power management on
+the laptop*, research 026/05, to-be 42 phase 3).
+
+## Why this name
+
+A module is named after the hardware model, never the node (novox/hq ADR 0112; research 026/03:
+no flavors, no machine names). `asus-zephyrus-g14` is the model family exactly as the firmware
+reports it (`/sys/class/dmi/id/product_family` = `ROG Zephyrus G14`). The module's code checks that
+value and its switcher does nothing on any other model, and `zephyrus_check` reports it.
+
+A wider name such as `asus-rog-laptop` would promise what this module cannot keep. Its contents
+belong to this family: the vendor-key scan codes, the eDP panel beside an NVIDIA dGPU, and the NVIDIA
+D3 workaround. A second G14 is assigned the same module. Another ROG model gets its own.
+
+Written against the GA403 (2024, Ryzen 8945HS, RTX 4070 Laptop, hybrid). Older G14 years have the same
+daemons and probably the same keys. Their GPU options are unverified.
+
+## What it owns
+
+| | what | how |
+|---|---|---|
+| package | `asusctl` (asusd + client) | the distribution's package (`extra`). The machine was found with a local build of 6.4.0. The host only asserts *present*, so the switch to 6.5.0 from `extra` happens at the next `pacman -Syu` (or `pacman -S asusctl`). `zephyrus_check` flags a local build |
+| package | `upower`, `playerctl`, `xorg-xinput` | what the low-battery drop-in, the media keys and the touchpad key use |
+| service | `asusd` running (static unit: no boot state to declare), `supergfxd` running and enabled | |
+| archive | `/usr/local/lib/asus-zephyrus-g14/bin/` | the module's scripts, from `files/bin` (below) |
+| file | `/etc/modprobe.d/g14-nvidia-power.conf` | `NVreg_DynamicPowerManagement=0x00` (runtime D3 off: the ACPI D-Notifier hang) and `NVreg_PreserveVideoMemoryAllocations=1`. The path is adopted (ADR 0182) |
+| file | `/etc/modprobe.d/video-brightness-switch.conf` | `video.brightness_switch_enabled=0`, so the ACPI video driver does not also move a backlight on the keys. The file was on the machine and owned by nothing |
+| file ×3 | `systemd-{suspend,hibernate,suspend-then-hibernate}.service.d/asus-zephyrus-g14-nvidia.conf` | `Wants=` the matching `nvidia-*` sleep units and `nvidia-resume` (see *suspend units* below) |
+| file | `nvidia-powerd.service.d/asus-zephyrus-g14.conf` | `ConditionKernelCommandLine=zephyrus.nvidia-powerd`: Dynamic Boost runs only when the operator opts in at boot |
+| file | `/etc/systemd/logind.conf.d/power.conf` | the power key and the lid suspend, on battery, on mains and docked. `systemd-logind` is reloaded, never restarted |
+| file | `/etc/udev/rules.d/90-backlight.rules` | backlights writable by the `video` group. `systemd-udevd` is reloaded |
+| file | `triggerhappy.service.d/asus-zephyrus-g14.conf` | `thd … --user ${machine:account}`: the triggers run as the operator's account (below) |
+| file | `/etc/triggerhappy/triggers.d/asus-g14.conf` | the vendor keys: media (`KEY_PROG1/3/4`), panel brightness, touchpad (`KEY_F21`). The path is adopted, because two trigger files would fire every key twice |
+| file | `/etc/UPower/UPower.conf.d/50-asus-zephyrus-g14.conf` | low battery at 15/10/7 %; at 7 % **suspend**, not power off. A drop-in over the package's own file |
+| file | `/etc/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf` | tap to click, natural scrolling, acceleration 0.15, as an X input class |
+
+**What it does not own, on purpose:**
+
+- `/etc/asusd/*.ron` belong to asusd, which rewrites them whenever a setting changes. RON is not a
+  format the host writes into (ADR 0102 speaks JSON and marked blocks). Owning the file whole would
+  repeat the predecessor's freeze: the measured file already differs from the one the predecessor
+  shipped. The settings the module needs are set through asusd, by its code (below).
+- `/etc/supergfxd.conf` and `/etc/modprobe.d/supergfxd.conf` belong to supergfxd, which writes both.
+- The swap file, its unit and the swap partition are the machine's swap layout (research 027,
+  question 3). They are not this module's, nor `memory-pressure`'s.
+- The i3 fragments (`~/.config/i3/config.d/10-asus.conf`, `20-g14.conf`) and the keyboard-backlight
+  notifier they start belong to phase 2 (the `i3` module).
+
+## Software outside the distribution (ADR 0205, research 027 question 1)
+
+`supergfxctl` (5.2.7, from the asus-linux repository, which is no longer configured) and
+`triggerhappy` (AUR) are **kept as found, and depended on**. The module declares no package for
+either, because the host installs from the official repositories only. It declares their services
+(`supergfxd` running, `triggerhappy` running), so on a machine without them the host refuses the
+service by name: *does not exist on this machine*. The refusal is loud, never a silent pass.
+`zephyrus_check` names both as foreign.
+
+This module does not choose between the options of research 027 question 1. Under the starting
+position (P2: the build machine builds AUR packages into a repository the mesh serves), both become
+`package` resources here, and a fresh G14 installs them. **Until P2 exists, a fresh G14 is blocked
+on installing these two by hand.** ADR 0205's vendored archive (P1) does not fit: supergfxctl is a
+daemon with a system-bus policy and udev rules, and triggerhappy is C.
+
+A later option for the keys: the module's own Go code could read the vendor keys from evdev, which
+the operator's account may do through the `input` group. That would retire triggerhappy entirely.
+It is not done here, because it would put the keys behind the node's runtime, and the runtime
+restarts a bundle that dies only on its next call (below).
+
+## The long-running code: the profile switcher (ADR 0198)
+
+The module's Go bundle serves the tools and runs the platform-profile switcher in the same process.
+The node's runtime launches the bundle at the runtime's start. It replaces the predecessor's
+`auto-profile`, a user unit that woke every five seconds, on battery too.
+
+- **Policy** (constants until settings exist, issue 168): battery → `Quiet`; mains → `Balanced`;
+  mains with the CPU at or above 50 % for 3 samples of 10 s → `Performance`, back to `Balanced` after
+  3 samples at or below 20 %. Between the lines nothing moves (hysteresis). iowait counts as idle.
+- **Woken by events, not a poll.** The kernel's power-supply uevents (netlink, group 1) wake the
+  switcher. Any account may listen on that group, and it needs no daemon, bus client or dependency;
+  upower re-announces the same changes but would need a D-Bus client in the bundle. The CPU is
+  sampled only on mains, every 10 s, because only there does the answer depend on it. On battery,
+  a safety re-read every 5 minutes covers an event lost across a suspend. If the uevent socket
+  cannot be opened, the switcher polls every 10 s and says so in `zephyrus_profile_policy`.
+- **The battery decides the source.** A battery that is *discharging* means battery, whatever any
+  adapter says. The predecessor took any `online` file reading 1 as mains, and on this model the USB-C
+  ports report `online`. Batteries of `scope=Device` (a mouse, a headset) are ignored.
+- **It acts on a change of its decision, never to restore one.** A profile someone chose by hand (the
+  profile key, asusctl, `zephyrus_profile`) stays until the power source changes or the load crosses
+  a line. The predecessor re-asserted its choice every five seconds, which made the profile key
+  useless. **Starting is not a decision**: the runtime restarts the bundle on every push that changes
+  one, and a push must not reset the operator's profile.
+- **A hold.** `zephyrus_profile` holds the profile it sets for 60 min (`hold_minutes`). A change of
+  power source ends the hold.
+- **One assertion at start:** through asusctl, the charge limit (80 %) and asusd's own on-mains and
+  on-battery profiles (`Balanced`, `Quiet`), each read first and set only if it differs. asusd's own
+  switching on a change of power source then agrees with the switcher's. A limit set later with
+  `zephyrus_charge_limit` stands until the bundle next starts. For a one-off full charge, use its
+  `oneshot`.
+- **Events:** `profile.switched` (`profile`, `from`, `reason`, `source`), published through the
+  runtime.
+
+No root is involved. asusd's and supergfxd's bus policies admit the `users` and `wheel` groups, and the
+runtime runs as the operator's account. The one write that may escalate is the panel's backlight,
+when the udev rule has not run yet. It uses `sudo -n` and never prompts. Every command is bounded at
+20 s.
+
+**Known limit.** The runtime restarts a launched bundle that exits *on its next tool call*, not at
+once (mesh-tools `launch.ts`), so a crashed switcher stays down until a tool is called. ADR 0198 §1
+says *started again when it exits*. The switcher recovers from a panic and reports it in
+`zephyrus_profile_policy` and `zephyrus_check`, but a crash of the process is the runtime's to restart.
+
+## The vendor keys and the scripts
+
+triggerhappy opens the input devices as root, then **drops to the operator's account with its groups**
+(`initgroups`: `input`, `video`). The packaged unit already drops to `nobody`, and the module's drop-in
+names the account instead. The predecessor replaced the packaged unit with one that ran every trigger
+as root, then `su`-ed to a named person with a hard-coded uid and display, and sourced a file of
+secrets on the way (research 027 question 2). Now:
+
+- `zephyrus-session CMD…`: runs a command in the account's graphical session. It sets the account's
+  own bus (`/run/user/<uid>/bus`) and finds the display from logind, or from a process of the account
+  that has one. Nothing is sourced.
+- `zephyrus-backlight + | - | N`: the panel in 5 % steps, never below 1 %. **The panel is the
+  backlight under the eDP connector**, because this model also registers `nvidia_0`, which moves
+  nothing. The predecessor named `amdgpu_bl1` literally.
+- `zephyrus-notify ID TEXT`: one replacing notification, through `busctl` (the service manager's
+  client, so no libnotify).
+- `zephyrus-touchpad reset | toggle`: bound to the touchpad key (`KEY_F21`).
+
+**Media keys** go to MPRIS through `playerctl`. The predecessor's Plex fallback needed a Plex token
+from the secrets file and is dropped until a module can be handed a secret (research 027 question 2).
+
+## The touchpad: an input class instead of a sleep hook
+
+The predecessor re-ran `xinput` from `/etc/systemd/system-sleep/` after every resume, as a named person
+on a guessed display, because settings made with `xinput` are lost when the device initialises again.
+An X input class is applied by X **every time the device appears**: at login, on hotplug and after a
+resume. So the cause is fixed, and the hook is gone. The class matches any touchpad on the machine,
+which is the model's, so it holds across G14 years whose touchpads differ. It takes effect at the next
+X start. `zephyrus-touchpad reset` stays as the manual form.
+
+## Suspend units without enabling them
+
+`nvidia-suspend`, `-hibernate`, `-suspend-then-hibernate` and `-resume` are enabled with links in the
+sleep services' `.wants` directories. The mesh makes no links (ADR 0012). The host's service shape
+cannot declare them either: it may only say *running* or *stopped*, and *running* on a one-shot that
+last failed would start `nvidia-sleep.sh suspend` with the machine awake. So the module asks for them
+from the other side: a drop-in on each sleep service that `Wants=` them. The units' own
+`Before=`/`After=` order them. The found links stay and are harmless.
+
+`suspend-then-hibernate` now also gets `nvidia-suspend-then-hibernate`, which the machine lacked.
+
+The drop-ins take effect at the service manager's next `daemon-reload`. In the same apply, the restart
+of `triggerhappy` (whose drop-in changes) performs one.
+
+## Tools
+
+| tool | r/a | what |
+|---|---|---|
+| `zephyrus_brightness` | r/a | panel (percent or ±step, floor 1 %) and keyboard (off/low/med/high, 0-3, ±) through asusd |
+| `zephyrus_battery` | r | charge, energy in Wh, health (full ÷ design), cycles (the firmware reports 0, and this is said), limit, watts, hours left |
+| `zephyrus_charge_limit` | r/a | 20-100 through asusd; `oneshot` |
+| `zephyrus_gpu_mode` | r/a | mode, supported modes, dGPU power, the pending mode and action; says that asusd switches the mode on every change of power source |
+| `zephyrus_profile` | r/a | active, on-mains and on-battery profile, kernel platform profile; set with a hold |
+| `zephyrus_thermals` | r | every hwmon temperature and fan, the hottest, the dGPU's temperature **only when it is awake** (nvidia-smi wakes a suspended GPU) |
+| `zephyrus_power_draw` | r | battery flow, APU package power (PPT), dGPU draw when awake, power source and why |
+| `zephyrus_profile_policy` | r | what the switcher would choose now and why: source, recent load against the thresholds, decision, hold, last switch, what woke it, what it asserted at start, and whether the predecessor's switcher still runs |
+| `zephyrus_fan_curves` | r | asusd's curves per profile and fan |
+| `zephyrus_check` | r | every expectation: model, packages (local or foreign), daemons, nvidia-powerd, sleep units, the NVIDIA options **in force** (`/proc/driver/nvidia/params`), charge limit, one authority each over the profile and the GPU mode, predecessor leftovers. It also lists what it did not check |
+
+`profile` is a candidate verb for a future `node-power-profile` seat (research 027/03). That seat has
+no record yet, so this is the module's own tool.
+
+## Found on the laptop, 2026-10-04 (read-only)
+
+- **Two authorities over the GPU mode.** `asusd.ron` has `ac_command: "supergfxctl -m Hybrid"` and
+  `bat_command: "supergfxctl -m Integrated"`, so asusd switches the GPU mode on every change of power
+  source. **supergfxd 5.2.7 cannot read logind's sessions** (`manager is an invalid variant`, every
+  boot), so a switch that needs a logout times out. `zephyrus_check` reports both. The fix is the
+  operator's, in asusd's file: clear both commands, or update supergfxctl once it can be packaged.
+- **`brightness.conf` did nothing.** `HandleBrightnessKey` is not a logind key, and logind logs
+  *Unknown key … ignoring* at every start. The module does not carry it. The brightness keys were
+  always triggerhappy's, with the ACPI video switch off.
+- **Two profile switchers** would run at once until `auto-profile` is stopped (below).
+- **asusctl is a local build** (6.4.0, *Unknown Packager*) beside a foreign `asusctl-debug`.
+
+## When assigned to the laptop: what changes
+
+1. `/usr/local/lib/asus-zephyrus-g14/` appears (four scripts).
+2. Written over found files (each original kept once by the host): `g14-nvidia-power.conf` and
+   `video-brightness-switch.conf` (same options, so no change until the next boot either),
+   `logind.conf.d/power.conf` (same keys; logind reloaded), `90-backlight.rules` (same effect;
+   udevd reloaded), `triggers.d/asus-g14.conf` (now the module's scripts).
+3. New: the three sleep drop-ins (behaviour gained: `nvidia-suspend-then-hibernate`), the
+   nvidia-powerd drop-in (no effect while it is masked), the triggerhappy drop-in, the UPower drop-in
+   (same values as today), and the touchpad input class (at the next X start).
+4. `daemon-reload` and a `triggerhappy` restart. thd now runs as the account and the keys run the
+   module's scripts. `upower` restarts.
+5. Packages, asusd and supergfxd: already as declared, so nothing changes. asusctl stays the local
+   6.4.0 until the next upgrade.
+6. The node runtime restarts with the new bundle. The switcher asserts the limit (80, already) and
+   asusd's profiles (Balanced and Quiet, already), so it sets nothing. It takes the current decision
+   as applied and acts from the first event on.
+
+## Predecessor files this module makes redundant — the operator removes them once (ADR 0182)
+
+**On the laptop:**
+
+1. `systemctl --user disable --now auto-profile.service`, then delete
+   `~/.config/systemd/user/auto-profile.service` and `~/scripts/auto-profile`. **Do this right after
+   the push**, or two switchers run at once.
+2. `~/scripts/asus-bright`, `~/scripts/asusctl-kbd-bright`, `~/scripts/xrandr-bright`,
+   `~/scripts/as-user`, `~/scripts/media-control`: no trigger and no i3 binding uses them any more.
+3. `~/scripts/xinput-reset-touchpad`: still started and bound by `~/.config/i3/config.d/20-g14.conf`.
+   Point those two lines at `/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset`, or wait for
+   the i3 module (phase 2) to rewrite the fragment.
+4. `/etc/systemd/system/triggerhappy.service`: the predecessor's replacement of the packaged unit. The
+   module's drop-in works over either, so delete it and `systemctl daemon-reload` to return to the
+   packaged unit (`Type=notify`, socket).
+5. `/etc/systemd/logind.conf.d/brightness.conf`: the unknown key, which does nothing.
+6. `/etc/systemd/system-sleep/xinput-reset-touchpad.sh`: replaced by the input class.
+7. `/etc/UPower/UPower.conf`: the predecessor's replacement of the package's file. Its values are now
+   the module's drop-in. Restore the package's copy (`rm` it, then `pacman -S upower`).
+8. Optional: `systemctl disable nvidia-suspend nvidia-resume nvidia-hibernate` (the drop-ins carry them
+   now), `/etc/asusd/*.ron-old` and `fan_curves.ron.bak`, the foreign `asusctl-debug` package, and
+   `pacman -S asusctl` for the distribution's build.
+
+**Stays the machine's:** `/swapfile` and `/etc/systemd/system/swapfile.swap` (the swap layout),
+`/etc/udev/rules.d/91-monitor-hotplug.rules` (the display's, phase 2), and the i3 fragments.
+
+**On the desktop** (the predecessor's G14 flavor reached it; part was removed on 2026-10-04): none of
+this module applies there. Still present and to be deleted:
+`/etc/systemd/logind.conf.d/brightness.conf`, `/etc/systemd/system-sleep/xinput-reset-touchpad.sh`,
+`~/scripts/xinput-reset-touchpad`, `~/scripts/xrandr-bright` and
+`~/.config/i3/scripts/kbd-brightness-notify.sh`.
+
+## Tests
+
+`go test ./...` in this directory. Every tool runs against a tree standing in for `/sys`, `/proc` and
+`/etc`, and an injected runner answering with what asusctl 6.4 and supergfxctl 5.2 said on the laptop.
+The tests cover:
+
+- the power-source rule;
+- battery arithmetic from `charge_*`;
+- the eDP panel choice;
+- brightness bounds;
+- the policy's sustain, relax and hysteresis, with iowait counted as idle;
+- the switcher: no act at start, one switch per change of source, a published event, boost from
+  samples, holds, retry after failure, start-up assertions only where they differ, inert on another
+  model;
+- the uevent filter;
+- the manifest: tools listed equal tools served, no machine named, triggers exist, every key runs a
+  shipped executable script, every script passes `bash -n`.
@@ -0,0 +1,264 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+// The vendor daemons are reached through their own command-line clients, which speak to them on the
+// system bus. Their bus policy admits the `users` and `wheel` groups, so none of this needs root.
+
+// Profiles are the platform profiles asusd offers on this model, in its spelling.
+var Profiles = []string{"Quiet", "Balanced", "Performance"}
+
+// canonicalProfile accepts any case and answers asusd's spelling, or an error naming the choices.
+func canonicalProfile(s string) (string, error) {
+	for _, p := range Profiles {
+		if strings.EqualFold(strings.TrimSpace(s), p) {
+			return p, nil
+		}
+	}
+	return "", fmt.Errorf("profile %q is not one of %s", s, strings.Join(Profiles, ", "))
+}
+
+// ProfileState is what asusd says about the platform profile.
+type ProfileState struct {
+	Active   string `json:"active"`
+	OnAC     string `json:"on_ac,omitempty"`
+	Battery  string `json:"on_battery,omitempty"`
+	Platform string `json:"platform_profile,omitempty"`
+	Choices  string `json:"platform_profile_choices,omitempty"`
+}
+
+var (
+	activeProfile  = regexp.MustCompile(`(?m)^Active profile:\s*(\S+)`)
+	acProfile      = regexp.MustCompile(`(?m)^AC profile\s+(\S+)`)
+	batteryProfile = regexp.MustCompile(`(?m)^Battery profile\s+(\S+)`)
+)
+
+// ParseProfileGet reads `asusctl profile get`.
+func ParseProfileGet(out string) (ProfileState, error) {
+	var p ProfileState
+	if m := activeProfile.FindStringSubmatch(out); m != nil {
+		p.Active = m[1]
+	} else {
+		return p, fmt.Errorf("asusctl profile get said no active profile: %q", strings.TrimSpace(out))
+	}
+	if m := acProfile.FindStringSubmatch(out); m != nil {
+		p.OnAC = m[1]
+	}
+	if m := batteryProfile.FindStringSubmatch(out); m != nil {
+		p.Battery = m[1]
+	}
+	return p, nil
+}
+
+// Profile reads the platform profile from asusd and the kernel.
+func (m *Machine) Profile(ctx context.Context) (ProfileState, error) {
+	out, err := m.Run(ctx, "asusctl", "profile", "get")
+	if err != nil {
+		return ProfileState{}, vendor("asusctl", err)
+	}
+	p, err := ParseProfileGet(out)
+	if err != nil {
+		return p, err
+	}
+	p.Platform = m.read("/sys/firmware/acpi/platform_profile")
+	p.Choices = m.read("/sys/firmware/acpi/platform_profile_choices")
+	return p, nil
+}
+
+// SetProfile has asusd switch the active profile.
+func (m *Machine) SetProfile(ctx context.Context, profile string) error {
+	_, err := m.Run(ctx, "asusctl", "profile", "set", profile)
+	return vendor("asusctl", err)
+}
+
+var chargeLimit = regexp.MustCompile(`charge limit:\s*(\d+)\s*%`)
+
+// ChargeLimit is the battery's charge limit as asusd reports it.
+func (m *Machine) ChargeLimit(ctx context.Context) (int, error) {
+	out, err := m.Run(ctx, "asusctl", "battery", "info")
+	if err != nil {
+		return 0, vendor("asusctl", err)
+	}
+	g := chargeLimit.FindStringSubmatch(out)
+	if g == nil {
+		return 0, fmt.Errorf("asusctl battery info said no limit: %q", strings.TrimSpace(out))
+	}
+	n, _ := strconv.Atoi(g[1])
+	return n, nil
+}
+
+// Keyboard backlight levels in asusd's spelling, index = the kernel's brightness value.
+var KeyboardLevels = []string{"off", "low", "med", "high"}
+
+var ledLevel = regexp.MustCompile(`(?i)brightness:\s*(off|low|med|high)`)
+
+// ParseLeds reads `asusctl leds get`.
+func ParseLeds(out string) (string, error) {
+	g := ledLevel.FindStringSubmatch(out)
+	if g == nil {
+		return "", fmt.Errorf("asusctl leds get said no level: %q", strings.TrimSpace(out))
+	}
+	return strings.ToLower(g[1]), nil
+}
+
+// FanCurve is one fan's curve in one profile: eight points of temperature (°C) and duty (0-255).
+type FanCurve struct {
+	Fan     string `json:"fan"`
+	Enabled bool   `json:"enabled"`
+	Temp    []int  `json:"temp_c"`
+	PWM     []int  `json:"pwm"`
+}
+
+var (
+	fanBlock = regexp.MustCompile(`(?s)fan:\s*(\w+),\s*pwm:\s*\(([^)]*)\),\s*temp:\s*\(([^)]*)\),\s*enabled:\s*(true|false)`)
+)
+
+// ParseFanCurves reads `asusctl fan-curve --mod-profile <p>`.
+func ParseFanCurves(out string) []FanCurve {
+	var curves []FanCurve
+	for _, g := range fanBlock.FindAllStringSubmatch(out, -1) {
+		curves = append(curves, FanCurve{Fan: g[1], PWM: ints(g[2]), Temp: ints(g[3]), Enabled: g[4] == "true"})
+	}
+	return curves
+}
+
+func ints(list string) []int {
+	var out []int
+	for _, f := range strings.Split(list, ",") {
+		if n, err := strconv.Atoi(strings.TrimSpace(f)); err == nil {
+			out = append(out, n)
+		}
+	}
+	return out
+}
+
+// GPUState is what supergfxd says about the hybrid GPU.
+type GPUState struct {
+	Mode          string   `json:"mode"`
+	Supported     []string `json:"supported"`
+	Power         string   `json:"dgpu_power,omitempty"`
+	PendingAction string   `json:"pending_action,omitempty"`
+	PendingMode   string   `json:"pending_mode,omitempty"`
+	Vendor        string   `json:"dgpu_vendor,omitempty"`
+}
+
+// ParseSupported reads `supergfxctl -s`: `[Integrated, Hybrid, AsusMuxDgpu]`.
+func ParseSupported(out string) []string {
+	out = strings.Trim(strings.TrimSpace(out), "[]")
+	var modes []string
+	for _, f := range strings.Split(out, ",") {
+		if f = strings.TrimSpace(f); f != "" {
+			modes = append(modes, f)
+		}
+	}
+	return modes
+}
+
+// GPU reads supergfxd.
+func (m *Machine) GPU(ctx context.Context) (GPUState, error) {
+	var g GPUState
+	mode, err := m.Run(ctx, "supergfxctl", "-g")
+	if err != nil {
+		return g, vendor("supergfxctl", err)
+	}
+	g.Mode = strings.TrimSpace(mode)
+	if s, err := m.Run(ctx, "supergfxctl", "-s"); err == nil {
+		g.Supported = ParseSupported(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-S"); err == nil {
+		g.Power = strings.TrimSpace(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-p"); err == nil {
+		g.PendingAction = strings.TrimSpace(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-P"); err == nil {
+		g.PendingMode = strings.TrimSpace(s)
+	}
+	if s, err := m.Run(ctx, "supergfxctl", "-V"); err == nil {
+		g.Vendor = strings.TrimSpace(s)
+	}
+	return g, nil
+}
+
+// vendor names a vendor client that is not installed, rather than passing on "executable file not
+// found". asusctl is in the distribution's repositories; supergfxctl is not, and the module keeps it as
+// it was found until the mesh can build packages from the user repository (research 027, question 1).
+func vendor(name string, err error) error {
+	if err == nil {
+		return nil
+	}
+	if notInstalled(err) {
+		switch name {
+		case "supergfxctl":
+			return fmt.Errorf("supergfxctl is not installed: it is not in the distribution's repositories, " +
+				"and this module keeps the copy it finds rather than install one (novox/hq research 027, question 1)")
+		default:
+			return fmt.Errorf("%s is not installed; the module's package resource installs it", name)
+		}
+	}
+	return err
+}
+
+// AsusdConfig is the few settings of asusd's own file that decide what this module's code does. The
+// file is asusd's: it rewrites it whenever a setting changes, so the module reads it and never writes
+// it.
+type AsusdConfig struct {
+	ChargeLimit          *int   `json:"charge_control_end_threshold,omitempty"`
+	ProfileOnAC          string `json:"platform_profile_on_ac,omitempty"`
+	ProfileOnBattery     string `json:"platform_profile_on_battery,omitempty"`
+	ChangesProfileOnAC   *bool  `json:"change_platform_profile_on_ac,omitempty"`
+	ChangesProfileOnBatt *bool  `json:"change_platform_profile_on_battery,omitempty"`
+	ACCommand            string `json:"ac_command,omitempty"`
+	BatteryCommand       string `json:"bat_command,omitempty"`
+	DisablesPowerdOnBatt *bool  `json:"disable_nvidia_powerd_on_battery,omitempty"`
+}
+
+var ronField = regexp.MustCompile(`(?m)^\s{4}([a-z_]+):\s*(.*?),?\s*$`)
+
+// ParseAsusdRon reads the top-level scalar fields of asusd.ron. RON is not a format the mesh
+// speaks; these are one line each, and nothing nested is read.
+func ParseAsusdRon(text string) AsusdConfig {
+	var c AsusdConfig
+	for _, g := range ronField.FindAllStringSubmatch(text, -1) {
+		key, value := g[1], strings.TrimSuffix(strings.TrimSpace(g[2]), ",")
+		unquoted := strings.Trim(value, `"`)
+		boolean := func() *bool { b := value == "true"; return &b }
+		switch key {
+		case "charge_control_end_threshold":
+			if n, err := strconv.Atoi(value); err == nil {
+				c.ChargeLimit = &n
+			}
+		case "platform_profile_on_ac":
+			c.ProfileOnAC = unquoted
+		case "platform_profile_on_battery":
+			c.ProfileOnBattery = unquoted
+		case "change_platform_profile_on_ac":
+			c.ChangesProfileOnAC = boolean()
+		case "change_platform_profile_on_battery":
+			c.ChangesProfileOnBatt = boolean()
+		case "ac_command":
+			c.ACCommand = unquoted
+		case "bat_command":
+			c.BatteryCommand = unquoted
+		case "disable_nvidia_powerd_on_battery":
+			c.DisablesPowerdOnBatt = boolean()
+		}
+	}
+	return c
+}
+
+// Asusd reads asusd's file; nil when it is not there.
+func (m *Machine) Asusd() *AsusdConfig {
+	text := m.read("/etc/asusd/asusd.ron")
+	if text == "" {
+		return nil
+	}
+	c := ParseAsusdRon(text)
+	return &c
+}
@@ -0,0 +1,146 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// What asusctl 6.4 and supergfxctl 5.2 said on the laptop on 2026-10-04.
+const fanCurveQuiet = `
+Fan curves for Quiet
+
+[
+    (
+        fan: CPU,
+        pwm: (2, 0, 10, 20, 35, 55, 80, 100),
+        temp: (35, 45, 50, 55, 60, 65, 70, 80),
+        enabled: true,
+    ),
+    (
+        fan: GPU,
+        pwm: (0, 0, 10, 20, 35, 65, 90, 115),
+        temp: (35, 45, 50, 55, 60, 65, 70, 80),
+        enabled: false,
+    ),
+]
+`
+
+const asusdRon = `(
+    charge_control_end_threshold: 80,
+    base_charge_control_end_threshold: 0,
+    disable_nvidia_powerd_on_battery: true,
+    ac_command: "supergfxctl -m Hybrid",
+    bat_command: "supergfxctl -m Integrated",
+    platform_profile_linked_epp: true,
+    platform_profile_on_battery: Quiet,
+    change_platform_profile_on_battery: true,
+    platform_profile_on_ac: Balanced,
+    change_platform_profile_on_ac: true,
+    ac_profile_tunings: {
+        Quiet: (
+            enabled: false,
+            group: {},
+        ),
+    },
+)`
+
+func TestAsusctlsAnswersAreRead(t *testing.T) {
+	p, err := ParseProfileGet(profileGetBalanced)
+	if err != nil || p.Active != "Balanced" || p.OnAC != "Balanced" || p.Battery != "Quiet" {
+		t.Fatalf("%+v %v", p, err)
+	}
+	if _, err := ParseProfileGet("something else"); err == nil {
+		t.Fatal("an answer with no profile was read as one")
+	}
+	if l, err := ParseLeds("Current keyboard led brightness: High\n"); err != nil || l != "high" {
+		t.Fatalf("%q %v", l, err)
+	}
+	curves := ParseFanCurves(fanCurveQuiet)
+	if len(curves) != 2 || curves[0].Fan != "CPU" || curves[0].PWM[7] != 100 || curves[0].Temp[0] != 35 || curves[1].Enabled {
+		t.Fatalf("%+v", curves)
+	}
+	if got := ParseSupported("[Integrated, Hybrid, AsusMuxDgpu]\n"); strings.Join(got, ",") != "Integrated,Hybrid,AsusMuxDgpu" {
+		t.Fatalf("%v", got)
+	}
+}
+
+func TestAsusdsFileIsReadForWhatDecidesTheModulesCodeAndNothingNested(t *testing.T) {
+	c := ParseAsusdRon(asusdRon)
+	if *c.ChargeLimit != 80 || c.ProfileOnAC != "Balanced" || c.ProfileOnBattery != "Quiet" ||
+		c.ACCommand != "supergfxctl -m Hybrid" || c.BatteryCommand != "supergfxctl -m Integrated" ||
+		!*c.ChangesProfileOnAC || !*c.DisablesPowerdOnBatt {
+		t.Fatalf("%+v", c)
+	}
+}
+
+func TestAMissingVendorClientIsNamedWithWhyItIsMissing(t *testing.T) {
+	f := newFake(t)
+	f.fails["supergfxctl"] = notFound
+	_, err := f.machine().GPU(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "research 027") {
+		t.Fatalf("%v", err)
+	}
+	f.fails["asusctl"] = notFound
+	_, err = f.machine().Profile(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "package resource installs it") {
+		t.Fatalf("%v", err)
+	}
+}
+
+func TestAGPUModeIsSetOnlyWhenTheMachineSupportsItAndAsusdsSwitchingIsSaid(t *testing.T) {
+	f := newFake(t)
+	f.answers["supergfxctl -g"] = "Hybrid\n"
+	f.answers["supergfxctl -s"] = "[Integrated, Hybrid, AsusMuxDgpu]\n"
+	f.file("/etc/asusd/asusd.ron", asusdRon)
+	m := f.machine()
+	if _, err := GPUModeTool(context.Background(), m, map[string]any{"mode": "Vfio"}); err == nil {
+		t.Fatal("an unsupported mode was accepted")
+	}
+	out, err := GPUModeTool(context.Background(), m, map[string]any{"mode": "integrated"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !f.called("supergfxctl -m Integrated") {
+		t.Fatalf("calls %v", f.calls)
+	}
+	if _, said := out.(map[string]any)["asusd_switches_it"]; !said {
+		t.Fatalf("asusd's own switching of the mode was not said: %+v", out)
+	}
+}
+
+func TestTheChargeLimitIsBoundedAndSetThroughAsusd(t *testing.T) {
+	f := newFake(t)
+	f.answers["asusctl battery info"] = "Current battery charge limit: 60%\n"
+	m := f.machine()
+	for _, bad := range []any{float64(10), float64(101), "x", 55.5} {
+		if _, err := ChargeLimitTool(context.Background(), m, map[string]any{"limit": bad}); err == nil {
+			t.Errorf("limit %v was accepted", bad)
+		}
+	}
+	out, err := ChargeLimitTool(context.Background(), m, map[string]any{"limit": float64(60)})
+	if err != nil || !f.called("asusctl battery limit 60") || out.(map[string]any)["asusd_limit_percent"] != 60 {
+		t.Fatalf("%+v %v %v", out, err, f.calls)
+	}
+}
+
+func TestAProfileSetByToolIsHeldAndAnUnknownOneRefused(t *testing.T) {
+	f := newFake(t)
+	f.onMains()
+	f.answers["asusctl profile get"] = profileGetBalanced
+	m := f.machine()
+	sw := NewSwitcher(m, nil)
+	if _, err := ProfileTool(context.Background(), m, sw, map[string]any{"profile": "Turbo"}); err == nil {
+		t.Fatal("an unknown profile was accepted")
+	}
+	out, err := ProfileTool(context.Background(), m, sw, map[string]any{"profile": "performance", "hold_minutes": float64(30)})
+	if err != nil || !f.called("asusctl profile set Performance") {
+		t.Fatalf("%v %v", err, f.calls)
+	}
+	if _, held := out.(map[string]any)["held_until"]; !held {
+		t.Fatalf("not held: %+v", out)
+	}
+	if r := sw.Report(); r.Held != "Performance" {
+		t.Fatalf("%+v", r)
+	}
+}
@@ -0,0 +1,184 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// Check is one thing the module expects of the machine, and whether it holds.
+type Check struct {
+	Name   string `json:"name"`
+	OK     bool   `json:"ok"`
+	Detail string `json:"detail"`
+}
+
+// CheckReport is what zephyrus_check answers. NotChecked says what it did not look at, because a
+// check that reads as clean while skipping something is the predecessor's verifier again.
+type CheckReport struct {
+	Model      string   `json:"model"`
+	Checks     []Check  `json:"checks"`
+	Failing    int      `json:"failing"`
+	NotChecked []string `json:"not_checked"`
+}
+
+var (
+	pacmanVersion  = regexp.MustCompile(`(?m)^Version\s*:\s*(\S+)`)
+	pacmanPackager = regexp.MustCompile(`(?m)^Packager\s*:\s*(.+)$`)
+	nvidiaParam    = regexp.MustCompile(`(?m)^(\w+):\s*(\S+)`)
+)
+
+// ParseNvidiaParams reads /proc/driver/nvidia/params.
+func ParseNvidiaParams(text string) map[string]string {
+	out := map[string]string{}
+	for _, g := range nvidiaParam.FindAllStringSubmatch(text, -1) {
+		out[g[1]] = g[2]
+	}
+	return out
+}
+
+// predecessorProcess finds a running process whose command line names the predecessor's script.
+func (m *Machine) predecessorProcess(name string) (int, bool) {
+	for _, dir := range m.glob("/proc/[0-9]*") {
+		cmd := strings.ReplaceAll(m.read(dir+"/cmdline"), "\x00", " ")
+		if strings.Contains(cmd, "/"+name) && !strings.Contains(cmd, "zephyrus") {
+			var pid int
+			fmt.Sscanf(filepath.Base(dir), "%d", &pid)
+			return pid, true
+		}
+	}
+	return 0, false
+}
+
+func (m *Machine) unitIs(ctx context.Context, verb, unit string) string {
+	out, _ := m.Run(ctx, "systemctl", verb, unit)
+	return strings.TrimSpace(out)
+}
+
+// Check reads every expectation and reports each.
+func (m *Machine) Check(ctx context.Context, sw *Switcher) CheckReport {
+	r := CheckReport{Model: m.Model(), NotChecked: []string{
+		"the fan curves (asusd's own, read them with zephyrus_fan_curves)",
+		"whether the initramfs carries the NVIDIA options (they are read from the running driver instead)",
+		"the vendor keys themselves (press them)",
+	}}
+	add := func(name string, ok bool, format string, a ...any) {
+		r.Checks = append(r.Checks, Check{Name: name, OK: ok, Detail: fmt.Sprintf(format, a...)})
+		if !ok {
+			r.Failing++
+		}
+	}
+	add("model", m.ThisModel(), "the firmware reports %q; this module is for %q", r.Model, ModelFamily)
+
+	// asusctl: present, and from the distribution rather than a local build.
+	if info, err := m.Run(ctx, "pacman", "-Qi", "asusctl"); err != nil {
+		add("asusctl package", false, "not installed: %v", err)
+	} else {
+		v, p := "", ""
+		if g := pacmanVersion.FindStringSubmatch(info); g != nil {
+			v = g[1]
+		}
+		if g := pacmanPackager.FindStringSubmatch(info); g != nil {
+			p = strings.TrimSpace(g[1])
+		}
+		local := p == "Unknown Packager"
+		add("asusctl package", !local, "version %s, packager %s%s", v, p,
+			map[bool]string{true: "; a local build — the distribution's package replaces it at the next upgrade (pacman -S asusctl)", false: ""}[local])
+	}
+	for _, foreign := range []string{"supergfxctl", "triggerhappy"} {
+		_, err := m.Run(ctx, "pacman", "-Q", foreign)
+		add(foreign+" package", err == nil, "%s; not in the distribution's repositories, kept as found (novox/hq research 027, question 1)",
+			map[bool]string{true: "installed", false: "NOT installed"}[err == nil])
+	}
+	for _, unit := range []string{"asusd.service", "supergfxd.service", "triggerhappy.service"} {
+		state := m.unitIs(ctx, "is-active", unit)
+		add(unit, state == "active", "%s", state)
+	}
+	powerd := m.unitIs(ctx, "is-enabled", "nvidia-powerd.service")
+	add("nvidia-powerd.service", powerd == "masked" || powerd == "disabled" || powerd == "" || strings.Contains(powerd, "not-found"),
+		"%s; the module's drop-in keeps it from starting unless the kernel command line says zephyrus.nvidia-powerd", orNone(powerd))
+	wants, _ := m.Run(ctx, "systemctl", "show", "-p", "Wants", "systemd-suspend.service")
+	add("nvidia suspend and resume", strings.Contains(wants, "nvidia-suspend.service") && strings.Contains(wants, "nvidia-resume.service"),
+		"systemd-suspend.service %s", strings.TrimSpace(wants))
+
+	params := ParseNvidiaParams(m.read("/proc/driver/nvidia/params"))
+	if len(params) == 0 {
+		add("nvidia options", false, "the NVIDIA driver is not loaded (no /proc/driver/nvidia/params)")
+	} else {
+		add("nvidia options", params["PreserveVideoMemoryAllocations"] == "1" && params["DynamicPowerManagement"] == "0",
+			"PreserveVideoMemoryAllocations=%s DynamicPowerManagement=%s (want 1 and 0; a change applies when the driver loads again)",
+			params["PreserveVideoMemoryAllocations"], params["DynamicPowerManagement"])
+	}
+
+	for _, b := range m.Batteries() {
+		ok := b.LimitPercent != nil && *b.LimitPercent == ChargeLimitPercent
+		have := "unknown"
+		if b.LimitPercent != nil {
+			have = fmt.Sprintf("%d%%", *b.LimitPercent)
+		}
+		add("charge limit", ok, "%s is %s, the module's is %d%%", b.Name, have, ChargeLimitPercent)
+	}
+
+	if c := m.Asusd(); c != nil && (c.ACCommand != "" || c.BatteryCommand != "") {
+		add("one authority over the GPU mode", false,
+			"asusd runs %q on mains and %q on battery: it switches the GPU mode on every change of power source, "+
+				"so a mode set with zephyrus_gpu_mode lasts until the next one. Clear ac_command and bat_command in /etc/asusd/asusd.ron (asusd's file) to make it the operator's alone",
+			c.ACCommand, c.BatteryCommand)
+	}
+	if out, err := m.Run(ctx, "journalctl", "-b", "-u", "supergfxd.service", "-g", "invalid variant", "-n", "1", "-q", "-o", "cat"); err == nil && strings.TrimSpace(out) != "" {
+		add("supergfxd and logind", false, "supergfxd cannot read logind's sessions this boot (%s): a mode change that needs a logout times out", strings.TrimSpace(out))
+	}
+
+	if pid, ok := m.predecessorProcess("auto-profile"); ok {
+		add("one profile switcher", false, "the predecessor's auto-profile still runs (pid %d) and switches the profile every five seconds; "+
+			"stop it: systemctl --user disable --now auto-profile.service", pid)
+	} else {
+		add("one profile switcher", true, "no predecessor auto-profile is running")
+	}
+	if sw != nil {
+		rep := sw.Report()
+		add("profile switcher", rep.Running, "%s", orNone(firstNonEmpty(rep.Disabled, rep.LastError, "woken by "+rep.Watching)))
+	}
+	if home := os.Getenv("MESH_OPERATOR_HOME"); home != "" {
+		var left []string
+		for _, p := range PredecessorHomeFiles {
+			if _, err := os.Stat(filepath.Join(m.Root, home, p)); err == nil {
+				left = append(left, "~/"+p)
+			}
+		}
+		add("predecessor files in the home", len(left) == 0, "%s", orNone(strings.Join(left, ", ")))
+	} else {
+		r.NotChecked = append(r.NotChecked, "the predecessor's files in the operator's home (MESH_OPERATOR_HOME is not set)")
+	}
+	return r
+}
+
+// PredecessorHomeFiles are what the predecessor placed in the operator's home for this model and this
+// module replaces. The mesh removes nothing it did not make (novox/hq ADR 0182): the operator does,
+// once, and this list is how the check knows.
+var PredecessorHomeFiles = []string{
+	"scripts/auto-profile",
+	".config/systemd/user/auto-profile.service",
+	"scripts/asus-bright",
+	"scripts/asusctl-kbd-bright",
+	"scripts/xrandr-bright",
+}
+
+func orNone(s string) string {
+	if strings.TrimSpace(s) == "" {
+		return "none"
+	}
+	return s
+}
+
+func firstNonEmpty(ss ...string) string {
+	for _, s := range ss {
+		if s != "" {
+			return s
+		}
+	}
+	return ""
+}
@@ -0,0 +1,202 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"os"
+	"path"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// MinPanelPercent is the floor a brightness change never goes below: a panel at zero is a black
+// screen that looks like a dead machine, and the keys cannot be seen to bring it back.
+const MinPanelPercent = 1
+
+// Panel is the internal display's backlight.
+type Panel struct {
+	Device  string   `json:"device"`
+	Percent float64  `json:"percent"`
+	Raw     int64    `json:"raw"`
+	Max     int64    `json:"max"`
+	Others  []string `json:"other_backlights,omitempty"`
+}
+
+// panelDevice chooses the backlight that drives the internal panel.
+//
+// **This model registers two.** In hybrid mode the integrated GPU drives the panel (amdgpu_bl1,
+// beneath the eDP connector) and the discrete GPU's driver registers one of its own (nvidia_0) that
+// moves nothing. The predecessor's scripts named amdgpu_bl1 literally, which is right until the GPU
+// mode puts the panel on the other GPU. The one that sits under an eDP connector is the panel's; failing
+// that, the kernel's own preference: firmware, then platform, then raw.
+func (m *Machine) panelDevice() (string, []string, error) {
+	all := m.glob("/sys/class/backlight/*")
+	if len(all) == 0 {
+		return "", nil, fmt.Errorf("this machine has no backlight in /sys/class/backlight")
+	}
+	names := make([]string, 0, len(all))
+	for _, d := range all {
+		names = append(names, path.Base(d))
+	}
+	sort.Strings(names)
+	rank := func(name string) int {
+		dir := "/sys/class/backlight/" + name
+		if target, err := os.Readlink(m.path(dir)); err == nil && strings.Contains(target, "-eDP-") {
+			return 0
+		}
+		switch m.read(dir + "/type") {
+		case "firmware":
+			return 1
+		case "platform":
+			return 2
+		}
+		return 3
+	}
+	best := names[0]
+	for _, n := range names[1:] {
+		if rank(n) < rank(best) {
+			best = n
+		}
+	}
+	var others []string
+	for _, n := range names {
+		if n != best {
+			others = append(others, n)
+		}
+	}
+	return best, others, nil
+}
+
+// PanelBrightness reads the panel.
+func (m *Machine) PanelBrightness() (Panel, error) {
+	dev, others, err := m.panelDevice()
+	if err != nil {
+		return Panel{}, err
+	}
+	dir := "/sys/class/backlight/" + dev
+	raw, ok1 := m.readInt(dir + "/brightness")
+	max, ok2 := m.readInt(dir + "/max_brightness")
+	if !ok1 || !ok2 || max <= 0 {
+		return Panel{}, fmt.Errorf("%s does not say its brightness", dir)
+	}
+	return Panel{Device: dev, Raw: raw, Max: max, Percent: round1(float64(raw) / float64(max) * 100), Others: others}, nil
+}
+
+// PanelTarget turns a request — "40", "40%", "+5", "-10" — into the percentage to set, clamped to
+// [MinPanelPercent, 100].
+func PanelTarget(current float64, request string) (float64, error) {
+	r := strings.TrimSuffix(strings.TrimSpace(request), "%")
+	if r == "" {
+		return 0, fmt.Errorf("panel needs a percentage (40) or a step (+5, -5)")
+	}
+	n, err := strconv.ParseFloat(r, 64)
+	if err != nil || math.IsNaN(n) || math.IsInf(n, 0) {
+		return 0, fmt.Errorf("panel %q is not a percentage or a step", request)
+	}
+	target := n
+	if strings.HasPrefix(r, "+") || strings.HasPrefix(r, "-") {
+		target = current + n
+	}
+	return math.Max(MinPanelPercent, math.Min(100, target)), nil
+}
+
+// SetPanel sets the panel to a percentage.
+func (m *Machine) SetPanel(ctx context.Context, request string) (Panel, error) {
+	p, err := m.PanelBrightness()
+	if err != nil {
+		return p, err
+	}
+	target, err := PanelTarget(p.Percent, request)
+	if err != nil {
+		return p, err
+	}
+	raw := int64(math.Round(target / 100 * float64(p.Max)))
+	if raw < 1 {
+		raw = 1
+	}
+	if err := m.write(ctx, "/sys/class/backlight/"+p.Device+"/brightness", strconv.FormatInt(raw, 10)); err != nil {
+		return p, err
+	}
+	return m.PanelBrightness()
+}
+
+// Keyboard is the keyboard's backlight.
+type Keyboard struct {
+	Device string `json:"device"`
+	Level  string `json:"level"`
+	Value  int64  `json:"value"`
+	Max    int64  `json:"max"`
+}
+
+// KeyboardBrightness reads the keyboard backlight from the kernel.
+func (m *Machine) KeyboardBrightness() (Keyboard, error) {
+	found := m.glob("/sys/class/leds/*kbd_backlight*")
+	if len(found) == 0 {
+		return Keyboard{}, fmt.Errorf("this machine has no keyboard backlight in /sys/class/leds")
+	}
+	dir := found[0]
+	v, ok1 := m.readInt(dir + "/brightness")
+	max, ok2 := m.readInt(dir + "/max_brightness")
+	if !ok1 || !ok2 {
+		return Keyboard{}, fmt.Errorf("%s does not say its brightness", dir)
+	}
+	k := Keyboard{Device: path.Base(dir), Value: v, Max: max}
+	if max == int64(len(KeyboardLevels)-1) && v >= 0 && v <= max {
+		k.Level = KeyboardLevels[v]
+	}
+	return k, nil
+}
+
+// KeyboardTarget turns a request — off/low/med/high, 0-3, "+", "-" — into asusd's level name.
+func KeyboardTarget(current int64, request string) (string, error) {
+	r := strings.ToLower(strings.TrimSpace(request))
+	switch r {
+	case "medium":
+		r = "med"
+	case "+", "up":
+		r = strconv.FormatInt(min64(current+1, int64(len(KeyboardLevels)-1)), 10)
+	case "-", "down":
+		r = strconv.FormatInt(max64(current-1, 0), 10)
+	}
+	for _, l := range KeyboardLevels {
+		if r == l {
+			return l, nil
+		}
+	}
+	if n, err := strconv.Atoi(r); err == nil && n >= 0 && n < len(KeyboardLevels) {
+		return KeyboardLevels[n], nil
+	}
+	return "", fmt.Errorf("keyboard %q is not one of off, low, med, high, 0-3, + or -", request)
+}
+
+// SetKeyboard has asusd set the keyboard backlight, so its own record of the level stays true.
+func (m *Machine) SetKeyboard(ctx context.Context, request string) (Keyboard, error) {
+	k, err := m.KeyboardBrightness()
+	if err != nil {
+		return k, err
+	}
+	level, err := KeyboardTarget(k.Value, request)
+	if err != nil {
+		return k, err
+	}
+	if _, err := m.Run(ctx, "asusctl", "leds", "set", level); err != nil {
+		return k, vendor("asusctl", err)
+	}
+	return m.KeyboardBrightness()
+}
+
+func min64(a, b int64) int64 {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+func max64(a, b int64) int64 {
+	if a > b {
+		return a
+	}
+	return b
+}
@@ -0,0 +1,91 @@
+package main
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// backlight makes a backlight the way sysfs does: a link from /sys/class/backlight into the device
+// tree, which is where the eDP connector shows.
+func (f *fake) backlight(name, device string, raw, max string) {
+	dev := "/sys/devices/" + device + "/" + name
+	f.file(dev+"/brightness", raw)
+	f.file(dev+"/max_brightness", max)
+	f.file(dev+"/type", "raw")
+	link := filepath.Join(f.root, "/sys/class/backlight", name)
+	os.MkdirAll(filepath.Dir(link), 0o755)
+	if err := os.Symlink(filepath.Join(f.root, dev), link); err != nil {
+		f.t.Fatal(err)
+	}
+}
+
+func TestThePanelIsTheBacklightUnderTheEDPConnectorNotTheDiscreteGPUs(t *testing.T) {
+	f := newFake(t)
+	f.backlight("amdgpu_bl1", "pci0000:00/0000:65:00.0/drm/card1/card1-eDP-1", "199500", "399000")
+	f.backlight("nvidia_0", "pci0000:00/0000:01:00.0/backlight", "100", "100")
+	p, err := f.machine().PanelBrightness()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if p.Device != "amdgpu_bl1" || p.Percent != 50 || len(p.Others) != 1 || p.Others[0] != "nvidia_0" {
+		t.Fatalf("%+v", p)
+	}
+}
+
+func TestAPanelRequestIsAPercentageOrAStepAndNeverGoesDark(t *testing.T) {
+	for _, c := range []struct {
+		cur  float64
+		req  string
+		want float64
+	}{{50, "40", 40}, {50, "40%", 40}, {50, "+5", 55}, {50, "-10", 40}, {3, "-10", 1}, {98, "+5", 100}, {50, "0", 1}} {
+		got, err := PanelTarget(c.cur, c.req)
+		if err != nil || got != c.want {
+			t.Errorf("%v %q: %v %v, want %v", c.cur, c.req, got, err, c.want)
+		}
+	}
+	for _, bad := range []string{"", "bright", "NaN"} {
+		if _, err := PanelTarget(50, bad); err == nil {
+			t.Errorf("%q was accepted", bad)
+		}
+	}
+}
+
+func TestSettingThePanelWritesTheRawValue(t *testing.T) {
+	f := newFake(t)
+	f.backlight("amdgpu_bl1", "card1-eDP-1", "399000", "399000")
+	p, err := f.machine().SetPanel(context.Background(), "25")
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, _ := os.ReadFile(filepath.Join(f.root, "/sys/devices/card1-eDP-1/amdgpu_bl1/brightness"))
+	if strings.TrimSpace(string(raw)) != "99750" || p.Percent != 25 {
+		t.Fatalf("wrote %q, read back %+v", raw, p)
+	}
+}
+
+func TestTheKeyboardIsSetThroughAsusdByLevel(t *testing.T) {
+	f := newFake(t)
+	f.file("/sys/class/leds/asus::kbd_backlight/brightness", "1")
+	f.file("/sys/class/leds/asus::kbd_backlight/max_brightness", "3")
+	k, err := f.machine().KeyboardBrightness()
+	if err != nil || k.Level != "low" {
+		t.Fatalf("%+v %v", k, err)
+	}
+	if _, err := f.machine().SetKeyboard(context.Background(), "+"); err != nil {
+		t.Fatal(err)
+	}
+	if !f.called("asusctl leds set med") {
+		t.Fatalf("calls: %v", f.calls)
+	}
+	for req, want := range map[string]string{"high": "high", "0": "off", "medium": "med", "-": "off"} {
+		if got, err := KeyboardTarget(1, req); err != nil || got != want {
+			t.Errorf("%q: %q %v", req, got, err)
+		}
+	}
+	if _, err := KeyboardTarget(1, "7"); err == nil {
+		t.Error("level 7 was accepted")
+	}
+}
@@ -0,0 +1,103 @@
+package main
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// fake is a machine for a test: a tree standing in for /, and a runner answering from a table and
+// recording every command it was asked to run.
+type fake struct {
+	t       *testing.T
+	root    string
+	mu      sync.Mutex
+	answers map[string]string
+	fails   map[string]error
+	calls   []string
+}
+
+func newFake(t *testing.T) *fake {
+	t.Helper()
+	return &fake{t: t, root: t.TempDir(), answers: map[string]string{}, fails: map[string]error{}}
+}
+
+func (f *fake) machine() *Machine { return &Machine{Root: f.root, Run: f.run} }
+
+func (f *fake) run(_ context.Context, name string, args ...string) (string, error) {
+	line := strings.TrimSpace(name + " " + strings.Join(args, " "))
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.calls = append(f.calls, line)
+	if err, ok := f.fails[line]; ok {
+		return "", err
+	}
+	if out, ok := f.answers[line]; ok {
+		return out, nil
+	}
+	if err, ok := f.fails[name]; ok {
+		return "", err
+	}
+	return "", nil
+}
+
+func (f *fake) called(line string) bool {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	for _, c := range f.calls {
+		if c == line {
+			return true
+		}
+	}
+	return false
+}
+
+func (f *fake) callsLike(prefix string) []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	var out []string
+	for _, c := range f.calls {
+		if strings.HasPrefix(c, prefix) {
+			out = append(out, c)
+		}
+	}
+	return out
+}
+
+// file writes a file under the fake root.
+func (f *fake) file(path, content string) {
+	f.t.Helper()
+	full := filepath.Join(f.root, path)
+	if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+		f.t.Fatal(err)
+	}
+	if err := os.WriteFile(full, []byte(content), 0o644); err != nil {
+		f.t.Fatal(err)
+	}
+}
+
+// supply writes one power supply's attributes.
+func (f *fake) supply(name string, attrs map[string]string) {
+	for k, v := range attrs {
+		f.file("/sys/class/power_supply/"+name+"/"+k, v+"\n")
+	}
+}
+
+// onMains and onBattery are this model's two states as measured on 2026-10-04.
+func (f *fake) onMains() {
+	f.supply("ACAD", map[string]string{"type": "Mains", "online": "1"})
+	f.supply("BAT1", map[string]string{"type": "Battery", "status": "Not charging", "capacity": "80"})
+}
+
+func (f *fake) onBattery() {
+	f.supply("ACAD", map[string]string{"type": "Mains", "online": "0"})
+	f.supply("BAT1", map[string]string{"type": "Battery", "status": "Discharging", "capacity": "79"})
+}
+
+var notFound = &exec.Error{Name: "x", Err: exec.ErrNotFound}
+
+const profileGetBalanced = "Active profile: Balanced\n\nAC profile Balanced\nBattery profile Quiet\n"
@@ -0,0 +1,124 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// CommandTimeout bounds every command a tool or the switcher runs: a vendor daemon that hangs on its
+// bus must cost a tool call twenty seconds, never the runtime's thirty.
+const CommandTimeout = 20 * time.Second
+
+// Runner runs one command and answers its standard output. It is injected so that every tool is
+// tested against recorded answers rather than this machine's daemons.
+type Runner func(ctx context.Context, name string, args ...string) (string, error)
+
+// ExecRunner runs a command on the machine, bounded by CommandTimeout. A failure carries what the
+// command said on stderr, because "exit status 1" names nothing.
+func ExecRunner(ctx context.Context, name string, args ...string) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, CommandTimeout)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, name, args...)
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout, cmd.Stderr = &stdout, &stderr
+	err := cmd.Run()
+	if ctx.Err() == context.DeadlineExceeded {
+		return stdout.String(), fmt.Errorf("%s did not answer within %s", name, CommandTimeout)
+	}
+	if err != nil {
+		said := strings.TrimSpace(stderr.String())
+		if said == "" {
+			said = strings.TrimSpace(stdout.String())
+		}
+		if said != "" {
+			return stdout.String(), fmt.Errorf("%s %s: %w: %s", name, strings.Join(args, " "), err, said)
+		}
+		return stdout.String(), fmt.Errorf("%s %s: %w", name, strings.Join(args, " "), err)
+	}
+	return stdout.String(), nil
+}
+
+// Machine is what the module reads and acts on: a filesystem root (the real one, or a test's tree of
+// /sys and /proc and /etc) and a way to run commands.
+type Machine struct {
+	Root string
+	Run  Runner
+}
+
+// Here is the machine this process runs on.
+func Here() *Machine { return &Machine{Root: "/", Run: ExecRunner} }
+
+func (m *Machine) path(p string) string { return filepath.Join(m.Root, p) }
+
+// read is a file's content, trimmed; "" when it cannot be read.
+func (m *Machine) read(p string) string {
+	b, err := os.ReadFile(m.path(p))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+// readInt is a file holding one integer; ok false when it is absent or not a number.
+func (m *Machine) readInt(p string) (int64, bool) {
+	s := m.read(p)
+	if s == "" {
+		return 0, false
+	}
+	n, err := strconv.ParseInt(s, 10, 64)
+	return n, err == nil
+}
+
+func (m *Machine) glob(pattern string) []string {
+	found, _ := filepath.Glob(m.path(pattern))
+	out := make([]string, 0, len(found))
+	for _, f := range found {
+		rel, err := filepath.Rel(m.Root, f)
+		if err != nil {
+			continue
+		}
+		out = append(out, "/"+filepath.ToSlash(rel))
+	}
+	return out
+}
+
+// write puts a value into a file of the kernel's (a backlight). Where the account may not write it
+// — the udev rule that gives the video group the panel has not run yet — it escalates with `sudo -n`,
+// which never prompts: the operator's account may escalate without one, and when it may not, the
+// tool says so in sudo's words.
+func (m *Machine) write(ctx context.Context, p, value string) error {
+	err := os.WriteFile(m.path(p), []byte(value), 0)
+	if err == nil {
+		return nil
+	}
+	if !errors.Is(err, os.ErrPermission) {
+		return err
+	}
+	if _, serr := m.Run(ctx, "sudo", "-n", "sh", "-c", `printf '%s' "$1" > "$2"`, "sh", value, m.path(p)); serr != nil {
+		return fmt.Errorf("%s is not writable by this account and sudo -n refused: %v", p, serr)
+	}
+	return nil
+}
+
+// notInstalled says a command failed because it is not on this machine at all.
+func notInstalled(err error) bool { return errors.Is(err, exec.ErrNotFound) }
+
+// round to one decimal, for watts and percentages a person reads.
+func round1(f float64) float64 {
+	return float64(int64(f*10+sign(f)*0.5)) / 10
+}
+
+func sign(f float64) float64 {
+	if f < 0 {
+		return -1
+	}
+	return 1
+}
@@ -0,0 +1,25 @@
+// The asus-zephyrus-g14 module's Go bundle (novox/hq ADR 0188, ADR 0193, ADR 0198): one process the
+// node's runtime launches, serving the module's tools over MCP on stdio and running its long-running
+// code — the platform-profile switcher — beside them.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	m := Here()
+	sw := NewSwitcher(m, func(eventType string, body any) error { return stdio.Emit(eventType, body) })
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go sw.Run(ctx)
+	// An empty name serves as the module the runtime names (MESH_SERVED_MODULE).
+	if err := stdio.Serve("", Tools(m, sw)); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
@@ -0,0 +1,110 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+)
+
+type manifest struct {
+	Module    string           `json:"module"`
+	Tools     []string         `json:"tools"`
+	Emits     []string         `json:"emits"`
+	Resources []map[string]any `json:"resources"`
+}
+
+func readManifest(t *testing.T) manifest {
+	t.Helper()
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m manifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func TestTheManifestNamesExactlyTheToolsTheBundleServes(t *testing.T) {
+	m := readManifest(t)
+	var served []string
+	for _, tool := range Tools(&Machine{Root: t.TempDir(), Run: newFake(t).run}, nil) {
+		served = append(served, tool.Name)
+	}
+	sort.Strings(served)
+	listed := append([]string(nil), m.Tools...)
+	sort.Strings(listed)
+	if strings.Join(served, ",") != strings.Join(listed, ",") {
+		t.Fatalf("served %v, listed %v", served, listed)
+	}
+	if len(m.Emits) != 1 || m.Emits[0] != "profile.switched" {
+		t.Fatalf("emits %v", m.Emits)
+	}
+}
+
+// The module names the model, never a node, a person or a user id (novox/hq ADR 0112), and every
+// trigger it names a service restart or reload on is one of its own resources.
+func TestTheManifestNamesNoMachineAndItsTriggersExist(t *testing.T) {
+	m := readManifest(t)
+	ids := map[string]bool{}
+	for _, r := range m.Resources {
+		ids[r["id"].(string)] = true
+	}
+	raw, _ := os.ReadFile("../../module.json")
+	for _, banned := range []string{"jochen", "/home/", "/run/user/1000", "\"g14\"", "shanks"} {
+		if strings.Contains(string(raw), banned) {
+			t.Errorf("the manifest says %q", banned)
+		}
+	}
+	for _, r := range m.Resources {
+		for _, key := range []string{"restart-on", "reload-on"} {
+			list, _ := r[key].([]any)
+			for _, id := range list {
+				if !ids[id.(string)] {
+					t.Errorf("%s %s names %v, which is not a resource", r["id"], key, id)
+				}
+			}
+		}
+	}
+}
+
+// Every trigger runs a script the module ships, and every script parses.
+func TestTheVendorKeysRunTheModulesOwnScriptsAndTheyParse(t *testing.T) {
+	m := readManifest(t)
+	var triggers string
+	for _, r := range m.Resources {
+		if r["id"] == "vendor-keys" {
+			triggers = r["content"].(string)
+		}
+	}
+	if triggers == "" {
+		t.Fatal("no vendor-keys resource")
+	}
+	for _, line := range strings.Split(triggers, "\n") {
+		f := strings.Split(line, "\t")
+		if strings.HasPrefix(line, "#") || len(f) < 3 {
+			continue
+		}
+		script := strings.Fields(f[2])[0]
+		local := filepath.Join("../../files/bin", filepath.Base(script))
+		if !strings.HasPrefix(script, "/usr/local/lib/asus-zephyrus-g14/bin/") {
+			t.Errorf("%s runs %s, which the module does not ship", f[0], script)
+		} else if st, err := os.Stat(local); err != nil || st.Mode()&0o111 == 0 {
+			t.Errorf("%s: %s is missing or not executable", f[0], local)
+		}
+	}
+	scripts, _ := filepath.Glob("../../files/bin/*")
+	if len(scripts) == 0 {
+		t.Fatal("no scripts")
+	}
+	for _, s := range scripts {
+		if out, err := exec.Command("bash", "-n", s).CombinedOutput(); err != nil {
+			t.Errorf("%s: %v %s", s, err, out)
+		}
+	}
+}
@@ -0,0 +1,137 @@
+package main
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// The policy, as constants until the mesh has settings a module can read (novox/hq issue 168). The
+// values are the predecessor's, made explicit, and two of its behaviours are changed on purpose:
+//
+//   - **Sustained, not momentary.** The predecessor boosted on one five-second sample above 50 %: a
+//     compile's first second, a browser's tab restore. Here the load must stay above the line for
+//     SustainSamples samples in a row, and below the lower line as long, before the profile moves.
+//   - **Waiting on a disk is not load.** iowait is counted as idle: a machine stalled on its SSD does
+//     not get faster with a higher power limit, only hotter.
+const (
+	ProfileOnBattery = "Quiet"
+	ProfileOnAC      = "Balanced"
+	ProfileUnderLoad = "Performance"
+
+	CPUHighPercent = 50.0 // on mains, sustained at or above this boosts to ProfileUnderLoad
+	CPULowPercent  = 20.0 // and sustained at or below this goes back to ProfileOnAC
+
+	SampleEvery    = 10 * time.Second // CPU is sampled only on mains; on battery nothing is sampled
+	SustainSamples = 3                // 30 s above CPUHighPercent to boost
+	RelaxSamples   = 3                // 30 s below CPULowPercent to relax
+
+	// SafetyRecheck is how often the power source is read when no event has said it changed: the
+	// kernel's event is the trigger, and this only covers one lost across a suspend.
+	SafetyRecheck = 5 * time.Minute
+
+	// DefaultHold is how long a profile chosen through the profile tool is kept before the switcher
+	// may move it again. A change of power source ends a hold at once.
+	DefaultHold = 60 * time.Minute
+
+	// ChargeLimitPercent is the battery charge limit the module asserts through asusd at start.
+	ChargeLimitPercent = 80
+)
+
+// Policy is the switcher's memory of recent load: how many samples in a row were above the upper line
+// or below the lower one, and whether it is boosted.
+type Policy struct {
+	Boosted      bool      `json:"boosted"`
+	Above        int       `json:"samples_above"`
+	Below        int       `json:"samples_below"`
+	Recent       []float64 `json:"recent_cpu_percent"`
+	BoostedSince time.Time `json:"boosted_since,omitempty"`
+}
+
+// Observe takes one CPU sample (busy percent since the previous one) taken on mains.
+func (p *Policy) Observe(cpu float64, at time.Time) {
+	p.Recent = append(p.Recent, round1(cpu))
+	if len(p.Recent) > 6 {
+		p.Recent = p.Recent[len(p.Recent)-6:]
+	}
+	switch {
+	case cpu >= CPUHighPercent:
+		p.Above++
+		p.Below = 0
+		if !p.Boosted && p.Above >= SustainSamples {
+			p.Boosted = true
+			p.BoostedSince = at
+		}
+	case cpu <= CPULowPercent:
+		p.Below++
+		p.Above = 0
+		if p.Boosted && p.Below >= RelaxSamples {
+			p.Boosted = false
+			p.BoostedSince = time.Time{}
+		}
+	default:
+		// Between the lines: no direction is sustained, and the profile stays where it is.
+		p.Above, p.Below = 0, 0
+	}
+}
+
+// Reset forgets the load, for a change of power source.
+func (p *Policy) Reset() { *p = Policy{} }
+
+// Decision is what the switcher would choose, and why.
+type Decision struct {
+	Profile string `json:"profile"`
+	Reason  string `json:"reason"`
+}
+
+// Decide is the policy: battery → ProfileOnBattery; mains → ProfileOnAC, or ProfileUnderLoad while
+// boosted.
+func (p *Policy) Decide(src Source) Decision {
+	if !src.OnAC {
+		return Decision{ProfileOnBattery, "on battery (" + src.Reason + ")"}
+	}
+	if p.Boosted {
+		return Decision{ProfileUnderLoad, fmt.Sprintf("on mains (%s) and CPU load sustained at or above %s%% for %d samples of %s",
+			src.Reason, strconv.FormatFloat(CPUHighPercent, 'f', -1, 64), SustainSamples, SampleEvery)}
+	}
+	return Decision{ProfileOnAC, fmt.Sprintf("on mains (%s), and CPU load not sustained at or above %s%%",
+		src.Reason, strconv.FormatFloat(CPUHighPercent, 'f', -1, 64))}
+}
+
+// CPUTimes is the first line of /proc/stat: total and idle jiffies (iowait counted as idle).
+type CPUTimes struct{ Total, Idle uint64 }
+
+// ParseProcStat reads the aggregate cpu line of /proc/stat.
+func ParseProcStat(text string) (CPUTimes, error) {
+	line := strings.SplitN(text, "\n", 2)[0]
+	f := strings.Fields(line)
+	if len(f) < 6 || f[0] != "cpu" {
+		return CPUTimes{}, fmt.Errorf("/proc/stat does not start with the cpu line")
+	}
+	var t CPUTimes
+	for i, s := range f[1:] {
+		if i >= 8 { // user nice system idle iowait irq softirq steal; guest is already in user
+			break
+		}
+		n, err := strconv.ParseUint(s, 10, 64)
+		if err != nil {
+			return CPUTimes{}, fmt.Errorf("/proc/stat: %v", err)
+		}
+		t.Total += n
+		if i == 3 || i == 4 {
+			t.Idle += n
+		}
+	}
+	return t, nil
+}
+
+// Busy is the percentage of time not idle between two readings.
+func Busy(before, after CPUTimes) (float64, bool) {
+	if after.Total <= before.Total {
+		return 0, false
+	}
+	total := float64(after.Total - before.Total)
+	idle := float64(after.Idle - before.Idle)
+	return (total - idle) / total * 100, true
+}
@@ -0,0 +1,180 @@
+package main
+
+import (
+	"path"
+	"sort"
+	"strings"
+)
+
+// Supply is one entry of /sys/class/power_supply as the kernel reports it.
+type Supply struct {
+	Name   string `json:"name"`
+	Type   string `json:"type"`
+	Scope  string `json:"scope,omitempty"`
+	Status string `json:"status,omitempty"`
+	Online *bool  `json:"online,omitempty"`
+}
+
+// Supplies is every power supply the kernel knows, sorted by name.
+func (m *Machine) Supplies() []Supply {
+	var out []Supply
+	for _, dir := range m.glob("/sys/class/power_supply/*") {
+		s := Supply{
+			Name:   path.Base(dir),
+			Type:   m.read(dir + "/type"),
+			Scope:  m.read(dir + "/scope"),
+			Status: m.read(dir + "/status"),
+		}
+		if v, ok := m.readInt(dir + "/online"); ok {
+			on := v == 1
+			s.Online = &on
+		}
+		out = append(out, s)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out
+}
+
+// system is a supply that powers this machine. A mouse's or a headset's battery reports scope
+// Device, and it says nothing about whether the laptop is on mains.
+func (s Supply) system() bool { return !strings.EqualFold(s.Scope, "Device") }
+
+// Source is where the machine draws its power from, and why that was concluded.
+type Source struct {
+	OnAC   bool   `json:"on_ac"`
+	Source string `json:"source"`
+	Reason string `json:"reason"`
+}
+
+// PowerSource decides mains or battery.
+//
+// **A battery that says it is discharging wins over any adapter that says it is online.** The
+// predecessor's script took any `online` file reading 1 as mains, and a USB-C port reports `online`
+// for things that do not power the machine. The battery's own status is the one fact that cannot be
+// misread: it discharges exactly when nothing outside is carrying the load. Only when no battery says
+// so are the adapters asked, and a machine with no system battery at all is on mains.
+func PowerSource(supplies []Supply) Source {
+	batteries := 0
+	for _, s := range supplies {
+		if s.Type == "Battery" && s.system() {
+			batteries++
+			if strings.EqualFold(s.Status, "Discharging") {
+				return Source{OnAC: false, Source: "battery", Reason: s.Name + " is discharging"}
+			}
+		}
+	}
+	for _, s := range supplies {
+		if (s.Type == "Mains" || strings.HasPrefix(s.Type, "USB")) && s.system() && s.Online != nil && *s.Online {
+			return Source{OnAC: true, Source: "ac", Reason: s.Name + " (" + s.Type + ") is online"}
+		}
+	}
+	if batteries == 0 {
+		return Source{OnAC: true, Source: "ac", Reason: "this machine has no system battery"}
+	}
+	return Source{OnAC: false, Source: "battery", Reason: "no mains or USB supply is online"}
+}
+
+// Battery is what the battery tool answers.
+type Battery struct {
+	Name           string   `json:"name"`
+	Status         string   `json:"status"`
+	ChargePercent  *int64   `json:"charge_percent,omitempty"`
+	EnergyWh       *float64 `json:"energy_wh,omitempty"`
+	FullWh         *float64 `json:"full_wh,omitempty"`
+	DesignWh       *float64 `json:"design_wh,omitempty"`
+	HealthPercent  *float64 `json:"health_percent,omitempty"`
+	Cycles         *int64   `json:"cycles"`
+	CyclesNote     string   `json:"cycles_note,omitempty"`
+	LimitPercent   *int64   `json:"charge_limit_percent,omitempty"`
+	PowerW         *float64 `json:"power_w,omitempty"`
+	HoursRemaining *float64 `json:"hours_remaining,omitempty"`
+	Technology     string   `json:"technology,omitempty"`
+	Model          string   `json:"model,omitempty"`
+	Manufacturer   string   `json:"manufacturer,omitempty"`
+}
+
+// Batteries reads every system battery.
+func (m *Machine) Batteries() []Battery {
+	var out []Battery
+	for _, s := range m.Supplies() {
+		if s.Type != "Battery" || !s.system() {
+			continue
+		}
+		out = append(out, m.battery(s))
+	}
+	return out
+}
+
+func (m *Machine) battery(s Supply) Battery {
+	dir := "/sys/class/power_supply/" + s.Name
+	b := Battery{
+		Name: s.Name, Status: s.Status,
+		Technology:   m.read(dir + "/technology"),
+		Model:        m.read(dir + "/model_name"),
+		Manufacturer: strings.TrimSpace(m.read(dir + "/manufacturer")),
+	}
+	if v, ok := m.readInt(dir + "/capacity"); ok {
+		b.ChargePercent = &v
+	}
+	// Energy in Wh: energy_* (µWh) where the firmware reports it, else charge_* (µAh) times the
+	// design minimum voltage, which is how upower converts it too.
+	wh := func(energy, charge string) *float64 {
+		if v, ok := m.readInt(dir + "/" + energy); ok {
+			f := round1(float64(v) / 1e6)
+			return &f
+		}
+		c, okc := m.readInt(dir + "/" + charge)
+		volts, okv := m.readInt(dir + "/voltage_min_design")
+		if okc && okv {
+			f := round1(float64(c) * float64(volts) / 1e12)
+			return &f
+		}
+		return nil
+	}
+	b.EnergyWh = wh("energy_now", "charge_now")
+	b.FullWh = wh("energy_full", "charge_full")
+	b.DesignWh = wh("energy_full_design", "charge_full_design")
+	if b.FullWh != nil && b.DesignWh != nil && *b.DesignWh > 0 {
+		h := round1(*b.FullWh / *b.DesignWh * 100)
+		b.HealthPercent = &h
+	}
+	if v, ok := m.readInt(dir + "/cycle_count"); ok && v > 0 {
+		b.Cycles = &v
+	} else {
+		b.CyclesNote = "the firmware does not report a cycle count (it reads 0)"
+	}
+	if v, ok := m.readInt(dir + "/charge_control_end_threshold"); ok {
+		b.LimitPercent = &v
+	}
+	if w := m.batteryWatts(dir); w != nil {
+		b.PowerW = w
+		if strings.EqualFold(s.Status, "Discharging") && b.EnergyWh != nil && *w > 0.5 {
+			h := round1(*b.EnergyWh / *w)
+			b.HoursRemaining = &h
+		}
+	}
+	return b
+}
+
+// batteryWatts is how much the battery is giving or taking, in watts, unsigned: power_now where the
+// firmware reports it, else current times voltage.
+func (m *Machine) batteryWatts(dir string) *float64 {
+	if v, ok := m.readInt(dir + "/power_now"); ok {
+		f := round1(abs(float64(v)) / 1e6)
+		return &f
+	}
+	i, oki := m.readInt(dir + "/current_now")
+	u, oku := m.readInt(dir + "/voltage_now")
+	if oki && oku {
+		f := round1(abs(float64(i)) * float64(u) / 1e12)
+		return &f
+	}
+	return nil
+}
+
+func abs(f float64) float64 {
+	if f < 0 {
+		return -f
+	}
+	return f
+}
@@ -0,0 +1,73 @@
+package main
+
+import "testing"
+
+func on(b bool) *bool { return &b }
+
+func TestADischargingBatteryWinsOverAnAdapterThatSaysOnline(t *testing.T) {
+	got := PowerSource([]Supply{
+		{Name: "BAT1", Type: "Battery", Status: "Discharging"},
+		{Name: "ucsi-source-psy-USBC000:001", Type: "USB", Scope: "System", Online: on(true)},
+	})
+	if got.OnAC {
+		t.Fatalf("a USB-C port reporting online while the battery discharges was read as mains: %+v", got)
+	}
+}
+
+func TestMainsOnlineIsAC(t *testing.T) {
+	got := PowerSource([]Supply{
+		{Name: "ACAD", Type: "Mains", Online: on(true)},
+		{Name: "BAT1", Type: "Battery", Status: "Not charging"},
+	})
+	if !got.OnAC || got.Reason != "ACAD (Mains) is online" {
+		t.Fatalf("%+v", got)
+	}
+}
+
+func TestAPeripheralsBatteryDecidesNothing(t *testing.T) {
+	got := PowerSource([]Supply{
+		{Name: "hidpp_battery_0", Type: "Battery", Scope: "Device", Status: "Discharging"},
+		{Name: "ACAD", Type: "Mains", Online: on(true)},
+		{Name: "BAT1", Type: "Battery", Status: "Charging"},
+	})
+	if !got.OnAC {
+		t.Fatalf("a mouse's discharging battery put the laptop on battery: %+v", got)
+	}
+}
+
+func TestNoSupplyOnlineWithABatteryIsBatteryAndNoBatteryIsMains(t *testing.T) {
+	if got := PowerSource([]Supply{{Name: "ACAD", Type: "Mains", Online: on(false)}, {Name: "BAT1", Type: "Battery", Status: "Unknown"}}); got.OnAC {
+		t.Fatalf("%+v", got)
+	}
+	if got := PowerSource(nil); !got.OnAC {
+		t.Fatalf("a machine with no battery is on mains: %+v", got)
+	}
+}
+
+func TestTheBatteryIsReadInWattHoursFromChargeAndHealthAgainstDesign(t *testing.T) {
+	f := newFake(t)
+	// The laptop's own battery, as measured: charge_* in µAh, no energy_* and no power_now.
+	f.supply("BAT1", map[string]string{
+		"type": "Battery", "status": "Discharging", "capacity": "80",
+		"charge_now": "3073000", "charge_full": "3865000", "charge_full_design": "4580000",
+		"voltage_min_design": "15939000", "current_now": "1000000", "voltage_now": "16000000",
+		"cycle_count": "0", "charge_control_end_threshold": "80", "manufacturer": "ASUS ",
+	})
+	bs := f.machine().Batteries()
+	if len(bs) != 1 {
+		t.Fatalf("%+v", bs)
+	}
+	b := bs[0]
+	if *b.EnergyWh != 49 || *b.FullWh != 61.6 || *b.DesignWh != 73 || *b.HealthPercent != 84.4 {
+		t.Fatalf("energy %v full %v design %v health %v", *b.EnergyWh, *b.FullWh, *b.DesignWh, *b.HealthPercent)
+	}
+	if b.Cycles != nil || b.CyclesNote == "" {
+		t.Fatal("a cycle count of 0 is the firmware not reporting one, and said so")
+	}
+	if *b.LimitPercent != 80 || *b.PowerW != 16 || b.HoursRemaining == nil || *b.HoursRemaining != 3.1 {
+		t.Fatalf("limit %v power %v hours %v", *b.LimitPercent, *b.PowerW, b.HoursRemaining)
+	}
+	if b.Manufacturer != "ASUS" {
+		t.Fatalf("manufacturer %q", b.Manufacturer)
+	}
+}
@@ -0,0 +1,303 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// The module's long-running code (novox/hq ADR 0198): the profile switcher, launched with the tools
+// by the node's runtime and running beside them in the same process.
+//
+// It replaces the predecessor's `auto-profile`, a user unit that woke every five seconds for ever —
+// read the adapters, read /proc/stat, maybe call asusctl — on battery too, where its only possible
+// answer was the one it had already given. Here the kernel's power-supply event is the trigger; the
+// CPU is sampled only on mains, where the answer depends on it; and on battery the process sleeps
+// until the adapter comes back.
+//
+// **It acts on a change of its decision, never to restore one.** A profile chosen by hand — the
+// vendor's profile key, asusctl in a terminal, the profile tool — stays until the power source
+// changes or the load crosses a line. The predecessor re-asserted its choice every five seconds and so
+// made the profile key useless on battery.
+
+// Emitter publishes an event as the module; nil when the process is not under the runtime.
+type Emitter func(eventType string, body any) error
+
+// Switcher is the switcher's state, shared with the tools that report it.
+type Switcher struct {
+	m    *Machine
+	now  func() time.Time
+	emit Emitter
+
+	mu        sync.Mutex
+	policy    Policy
+	source    *Source
+	decision  *Decision
+	applied   string
+	appliedAt time.Time
+	lastError string
+	holdUntil time.Time
+	holdOf    string
+	watching  string
+	cpuPrev   *CPUTimes
+	disabled  string
+	asserted  []string
+}
+
+func NewSwitcher(m *Machine, emit Emitter) *Switcher {
+	return &Switcher{m: m, now: time.Now, emit: emit}
+}
+
+// Model is the machine's product family as its firmware reports it.
+func (m *Machine) Model() string { return m.read("/sys/class/dmi/id/product_family") }
+
+// ModelFamily is the family this module is written for.
+const ModelFamily = "ROG Zephyrus G14"
+
+// ThisModel says whether the machine is the model this module is written for.
+func (m *Machine) ThisModel() bool { return strings.EqualFold(m.Model(), ModelFamily) }
+
+// sampleCPU reads /proc/stat and answers the busy percentage since the previous reading.
+func (s *Switcher) sampleCPU() (float64, bool) {
+	t, err := ParseProcStat(s.m.read("/proc/stat"))
+	if err != nil {
+		return 0, false
+	}
+	prev := s.cpuPrev
+	s.cpuPrev = &t
+	if prev == nil {
+		return 0, false
+	}
+	return Busy(*prev, t)
+}
+
+// Evaluate reads the power source, takes a CPU sample when asked and on mains, decides, and applies
+// the decision when it changed. It is the whole of one wake-up and what the tests drive.
+func (s *Switcher) Evaluate(ctx context.Context, sample bool) {
+	if body := s.evaluate(ctx, sample); body != nil && s.emit != nil {
+		// Outside the lock: publishing waits for the bus, and the tools that report the switcher
+		// must not wait with it.
+		if err := s.emit("profile.switched", body); err != nil {
+			fmt.Fprintf(os.Stderr, "profile.switched not published: %v\n", err)
+		}
+	}
+}
+
+// evaluate is Evaluate under the lock; it answers the event to publish when it switched.
+func (s *Switcher) evaluate(ctx context.Context, sample bool) map[string]any {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.disabled != "" {
+		return nil
+	}
+	src := PowerSource(s.m.Supplies())
+	now := s.now()
+	first := s.source == nil
+	if first || s.source.OnAC != src.OnAC {
+		// A new power source: what was learnt about load on the other one says nothing here, and a
+		// hold was for the source it was asked on.
+		s.policy.Reset()
+		s.cpuPrev = nil
+		s.holdUntil = time.Time{}
+		s.holdOf = ""
+		s.sampleCPU() // the first reading on this source, so the next sample is a difference
+	} else if sample && src.OnAC {
+		if busy, ok := s.sampleCPU(); ok {
+			s.policy.Observe(busy, now)
+		}
+	}
+	s.source = &src
+	d := s.policy.Decide(src)
+	s.decision = &d
+	// **Starting is not a reason to switch.** The runtime starts this process on every push that
+	// changes a bundle; at boot and at every change of power source asusd has already applied its own
+	// profile for the source, which AssertVendorSettings made the policy's. So the first decision is
+	// taken as applied, and a profile someone chose by hand survives a push.
+	if first {
+		s.applied = d.Profile
+		return nil
+	}
+	// Compared with what the switcher itself last applied, never with the profile in force: a profile
+	// someone chose by hand is not a reason to act, a new decision is.
+	if d.Profile == s.applied || now.Before(s.holdUntil) {
+		return nil
+	}
+	from := s.applied
+	if err := s.m.SetProfile(ctx, d.Profile); err != nil {
+		s.lastError = err.Error() // and tried again at the next wake-up, since applied did not move
+		return nil
+	}
+	s.lastError = ""
+	s.applied, s.appliedAt = d.Profile, now
+	body := map[string]any{"profile": d.Profile, "reason": d.Reason, "source": src.Source}
+	if from != "" {
+		body["from"] = from
+	}
+	return body
+}
+
+// Hold keeps a profile chosen through the tool for a while: the switcher does not move it until the
+// hold ends or the power source changes.
+func (s *Switcher) Hold(profile string, d time.Duration) time.Time {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if d <= 0 {
+		s.holdUntil, s.holdOf = time.Time{}, ""
+		return time.Time{}
+	}
+	s.holdUntil, s.holdOf = s.now().Add(d), profile
+	return s.holdUntil
+}
+
+// Run is the switcher's life: assert asusd's settings once, then wake on each power-supply event, on
+// each CPU sample while on mains, and at SafetyRecheck otherwise.
+func (s *Switcher) Run(ctx context.Context) {
+	defer func() {
+		if r := recover(); r != nil {
+			s.mu.Lock()
+			s.disabled = fmt.Sprintf("the switcher stopped on a fault: %v", r)
+			s.mu.Unlock()
+			fmt.Fprintln(os.Stderr, s.disabled)
+		}
+	}()
+	if !s.m.ThisModel() {
+		s.mu.Lock()
+		s.disabled = fmt.Sprintf("this machine reports %q, not %q: the switcher does not act on another model",
+			s.m.Model(), ModelFamily)
+		s.mu.Unlock()
+		fmt.Fprintln(os.Stderr, s.disabled)
+		return
+	}
+	s.AssertVendorSettings(ctx)
+
+	events, err := listenPowerSupply(ctx)
+	s.mu.Lock()
+	if err != nil {
+		s.watching = "polling every " + SampleEvery.String() + ": " + err.Error()
+	} else {
+		s.watching = "the kernel's power-supply events"
+	}
+	s.mu.Unlock()
+
+	s.Evaluate(ctx, false)
+	timer := time.NewTimer(s.interval(err != nil))
+	defer timer.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case _, open := <-events:
+			if !open {
+				events = nil
+				s.mu.Lock()
+				s.watching = "polling every " + SampleEvery.String() + ": the uevent socket closed"
+				s.mu.Unlock()
+				err = fmt.Errorf("closed")
+				continue
+			}
+			// Settle: an adapter change arrives as several events within a moment.
+			time.Sleep(time.Second)
+			s.Evaluate(ctx, false)
+		case <-timer.C:
+			s.Evaluate(ctx, true)
+			timer.Reset(s.interval(err != nil))
+		}
+	}
+}
+
+// interval is how long to sleep: a CPU sample's period on mains (or with no events to wake on), the
+// safety recheck on battery.
+func (s *Switcher) interval(polling bool) time.Duration {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if polling || s.source == nil || s.source.OnAC {
+		return SampleEvery
+	}
+	return SafetyRecheck
+}
+
+// AssertVendorSettings puts asusd's own settings where the module wants them, once at start: the
+// battery charge limit, and the profiles asusd itself switches to on mains and on battery, so that the
+// vendor daemon's own switching and this module's never disagree. Each is read first and set only if
+// it differs. A value changed later with a tool stands until the next start.
+func (s *Switcher) AssertVendorSettings(ctx context.Context) []string {
+	var said []string
+	if limit, err := s.m.ChargeLimit(ctx); err != nil {
+		said = append(said, "charge limit not read: "+err.Error())
+	} else if limit != ChargeLimitPercent {
+		if _, err := s.m.Run(ctx, "asusctl", "battery", "limit", strconv.Itoa(ChargeLimitPercent)); err != nil {
+			said = append(said, "charge limit not set: "+vendor("asusctl", err).Error())
+		} else {
+			said = append(said, fmt.Sprintf("charge limit %d%% → %d%%", limit, ChargeLimitPercent))
+		}
+	} else {
+		said = append(said, fmt.Sprintf("charge limit already %d%%", ChargeLimitPercent))
+	}
+	p, err := s.m.Profile(ctx)
+	if err != nil {
+		said = append(said, "asusd's profiles not read: "+err.Error())
+	} else {
+		for _, want := range []struct{ flag, have, want, what string }{
+			{"-a", p.OnAC, ProfileOnAC, "on mains"},
+			{"-b", p.Battery, ProfileOnBattery, "on battery"},
+		} {
+			if want.have == "" || strings.EqualFold(want.have, want.want) {
+				continue
+			}
+			if _, err := s.m.Run(ctx, "asusctl", "profile", "set", want.flag, want.want); err != nil {
+				said = append(said, "asusd's profile "+want.what+" not set: "+err.Error())
+			} else {
+				said = append(said, fmt.Sprintf("asusd's profile %s %s → %s", want.what, want.have, want.want))
+			}
+		}
+	}
+	s.mu.Lock()
+	s.asserted = said
+	s.mu.Unlock()
+	for _, line := range said {
+		fmt.Fprintln(os.Stderr, line)
+	}
+	return said
+}
+
+// SwitcherReport is the switcher's state as the profile-policy tool shows it.
+type SwitcherReport struct {
+	Running         bool       `json:"running"`
+	Disabled        string     `json:"disabled,omitempty"`
+	Watching        string     `json:"woken_by,omitempty"`
+	Source          *Source    `json:"source,omitempty"`
+	Decision        *Decision  `json:"decision,omitempty"`
+	Load            Policy     `json:"load"`
+	LastApplied     string     `json:"last_applied,omitempty"`
+	LastAppliedAt   *time.Time `json:"last_applied_at,omitempty"`
+	LastError       string     `json:"last_error,omitempty"`
+	HeldUntil       *time.Time `json:"held_until,omitempty"`
+	Held            string     `json:"held_profile,omitempty"`
+	AssertedAtStart []string   `json:"asserted_at_start,omitempty"`
+}
+
+func (s *Switcher) Report() SwitcherReport {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	r := SwitcherReport{
+		Running: s.watching != "" && s.disabled == "", Disabled: s.disabled, Watching: s.watching,
+		Source: s.source, Decision: s.decision, Load: s.policy, LastApplied: s.applied,
+		LastAppliedAt: when(s.appliedAt), LastError: s.lastError, AssertedAtStart: s.asserted,
+	}
+	if s.now().Before(s.holdUntil) {
+		r.HeldUntil, r.Held = when(s.holdUntil), s.holdOf
+	}
+	return r
+}
+
+// when is a time for a report: absent rather than the zero time.
+func when(t time.Time) *time.Time {
+	if t.IsZero() {
+		return nil
+	}
+	return &t
+}
@@ -0,0 +1,190 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"strconv"
+	"testing"
+	"time"
+)
+
+func TestTheLoadMustBeSustainedToBoostAndToRelaxAndBetweenTheLinesNothingMoves(t *testing.T) {
+	var p Policy
+	at := time.Now()
+	mains := Source{OnAC: true, Reason: "ACAD (Mains) is online"}
+	for i := 0; i < SustainSamples-1; i++ {
+		p.Observe(90, at)
+	}
+	if p.Decide(mains).Profile != ProfileOnAC {
+		t.Fatal("boosted before the load was sustained")
+	}
+	p.Observe(35, at) // between the lines breaks the run
+	p.Observe(90, at)
+	if p.Boosted {
+		t.Fatal("a broken run still counted")
+	}
+	for i := 0; i < SustainSamples; i++ {
+		p.Observe(CPUHighPercent, at)
+	}
+	if d := p.Decide(mains); d.Profile != ProfileUnderLoad {
+		t.Fatalf("%+v", d)
+	}
+	p.Observe(35, at)
+	if !p.Boosted {
+		t.Fatal("load between the lines relaxed the boost")
+	}
+	for i := 0; i < RelaxSamples; i++ {
+		p.Observe(5, at)
+	}
+	if p.Decide(mains).Profile != ProfileOnAC {
+		t.Fatal("did not relax after a sustained low")
+	}
+	p.Boosted = true
+	if d := p.Decide(Source{OnAC: false, Reason: "BAT1 is discharging"}); d.Profile != ProfileOnBattery {
+		t.Fatalf("battery: %+v", d)
+	}
+}
+
+func TestIOWaitIsIdle(t *testing.T) {
+	a, err := ParseProcStat("cpu  100 0 100 700 100 0 0 0 0 0\ncpu0 1 2 3\n")
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, _ := ParseProcStat("cpu  150 0 150 700 200 0 0 0 0 0\n")
+	busy, ok := Busy(a, b)
+	if !ok || busy != 50 {
+		t.Fatalf("%v %v", busy, ok)
+	}
+	if _, ok := Busy(b, b); ok {
+		t.Fatal("no time passed and a load was answered")
+	}
+	if _, err := ParseProcStat("intr 1 2"); err == nil {
+		t.Fatal("a file without the cpu line was read")
+	}
+}
+
+func switcherOn(t *testing.T) (*fake, *Switcher, *[]map[string]any) {
+	f := newFake(t)
+	f.onMains()
+	f.file("/proc/stat", "cpu  0 0 0 0 0 0 0 0\n")
+	var emitted []map[string]any
+	sw := NewSwitcher(f.machine(), func(_ string, body any) error {
+		emitted = append(emitted, body.(map[string]any))
+		return nil
+	})
+	return f, sw, &emitted
+}
+
+func TestStartingIsNotAReasonToSwitch(t *testing.T) {
+	f, sw, emitted := switcherOn(t)
+	sw.Evaluate(context.Background(), false)
+	if calls := f.callsLike("asusctl profile set"); len(calls) != 0 || len(*emitted) != 0 {
+		t.Fatalf("the first decision acted: %v %v", calls, *emitted)
+	}
+}
+
+func TestAChangeOfPowerSourceSwitchesOnceAndPublishesIt(t *testing.T) {
+	f, sw, emitted := switcherOn(t)
+	ctx := context.Background()
+	sw.Evaluate(ctx, false)
+	f.onBattery()
+	sw.Evaluate(ctx, false)
+	sw.Evaluate(ctx, true) // nothing changed: nothing done, and on battery nothing sampled
+	if calls := f.callsLike("asusctl profile set"); len(calls) != 1 || calls[0] != "asusctl profile set Quiet" {
+		t.Fatalf("%v", calls)
+	}
+	if len(*emitted) != 1 || (*emitted)[0]["profile"] != "Quiet" || (*emitted)[0]["from"] != "Balanced" {
+		t.Fatalf("%v", *emitted)
+	}
+	f.onMains()
+	sw.Evaluate(ctx, false)
+	if calls := f.callsLike("asusctl profile set"); len(calls) != 2 || calls[1] != "asusctl profile set Balanced" {
+		t.Fatalf("%v", calls)
+	}
+}
+
+func TestSustainedLoadOnMainsBoostsFromSamples(t *testing.T) {
+	f, sw, _ := switcherOn(t)
+	ctx := context.Background()
+	sw.Evaluate(ctx, false)
+	var user int
+	for i := 1; i <= SustainSamples; i++ {
+		user += 90
+		f.file("/proc/stat", "cpu  "+itoa(user)+" 0 0 "+itoa(i*10)+" 0 0 0 0\n")
+		sw.Evaluate(ctx, true)
+	}
+	if !f.called("asusctl profile set Performance") {
+		t.Fatalf("%v", f.calls)
+	}
+}
+
+func TestAHoldKeepsTheProfileUntilItEndsAndAFailureIsTriedAgain(t *testing.T) {
+	f, sw, _ := switcherOn(t)
+	ctx := context.Background()
+	now := time.Now()
+	sw.now = func() time.Time { return now }
+	sw.Evaluate(ctx, false)
+	f.onBattery()
+	sw.Evaluate(ctx, false) // source change ends any hold; switches to Quiet
+	sw.Hold("Performance", time.Hour)
+	f.fails["asusctl profile set Balanced"] = errors.New("asusd is restarting")
+	f.onMains()
+	sw.Evaluate(ctx, false) // a change of source: the hold ends, the switch is attempted and fails
+	if r := sw.Report(); r.LastError == "" || r.Held != "" {
+		t.Fatalf("%+v", r)
+	}
+	delete(f.fails, "asusctl profile set Balanced")
+	sw.Evaluate(ctx, false)
+	if r := sw.Report(); r.LastApplied != "Balanced" || r.LastError != "" {
+		t.Fatalf("not tried again: %+v", r)
+	}
+	// A hold on the same source keeps a new decision from acting until it ends.
+	sw.Hold("Quiet", time.Hour)
+	sw.policy.Boosted = true
+	sw.Evaluate(ctx, false)
+	if f.called("asusctl profile set Performance") {
+		t.Fatal("switched during a hold")
+	}
+	now = now.Add(2 * time.Hour)
+	sw.Evaluate(ctx, false)
+	if !f.called("asusctl profile set Performance") {
+		t.Fatal("did not act once the hold ended")
+	}
+}
+
+func TestAsusdsSettingsAreSetOnlyWhereTheyDiffer(t *testing.T) {
+	f := newFake(t)
+	f.answers["asusctl battery info"] = "Current battery charge limit: 100%\n"
+	f.answers["asusctl profile get"] = "Active profile: Balanced\nAC profile Performance\nBattery profile Quiet\n"
+	sw := NewSwitcher(f.machine(), nil)
+	sw.AssertVendorSettings(context.Background())
+	if !f.called("asusctl battery limit 80") || !f.called("asusctl profile set -a Balanced") || f.called("asusctl profile set -b Quiet") {
+		t.Fatalf("%v", f.calls)
+	}
+}
+
+func TestTheSwitcherDoesNotActOnAnotherModel(t *testing.T) {
+	f := newFake(t)
+	f.file("/sys/class/dmi/id/product_family", "ROG Strix\n")
+	sw := NewSwitcher(f.machine(), nil)
+	done := make(chan struct{})
+	go func() { sw.Run(context.Background()); close(done) }()
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("the switcher ran on another model")
+	}
+	if r := sw.Report(); r.Running || r.Disabled == "" || len(f.calls) != 0 {
+		t.Fatalf("%+v %v", r, f.calls)
+	}
+}
+
+func TestOnlyPowerSupplyUeventsWake(t *testing.T) {
+	yes := []byte("change@/devices/LNXSYSTM:00/ACPI0003:00/power_supply/ACAD\x00ACTION=change\x00SUBSYSTEM=power_supply\x00POWER_SUPPLY_ONLINE=0\x00")
+	no := []byte("change@/devices/virtual/net/wlan0\x00ACTION=change\x00SUBSYSTEM=net\x00")
+	if !powerSupplyEvent(yes) || powerSupplyEvent(no) {
+		t.Fatal("the uevent filter")
+	}
+}
+
+func itoa(n int) string { return strconv.Itoa(n) }
@@ -0,0 +1,168 @@
+package main
+
+import (
+	"context"
+	"path"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// Sensor is one temperature, fan or power reading from hwmon.
+type Sensor struct {
+	Chip  string  `json:"chip"`
+	Label string  `json:"label"`
+	Value float64 `json:"value"`
+}
+
+// DGPU is the discrete GPU as the PCI bus and its driver see it.
+type DGPU struct {
+	Address string   `json:"pci_address"`
+	Runtime string   `json:"runtime_status"`
+	Name    string   `json:"name,omitempty"`
+	TempC   *float64 `json:"temp_c,omitempty"`
+	PowerW  *float64 `json:"power_w,omitempty"`
+	PState  string   `json:"pstate,omitempty"`
+	Note    string   `json:"note,omitempty"`
+}
+
+// hwmon reads every hwmon reading of one kind: "temp" (°C), "fan" (RPM) or "power" (W).
+func (m *Machine) hwmon(kind string) []Sensor {
+	var out []Sensor
+	for _, dir := range m.glob("/sys/class/hwmon/hwmon*") {
+		chip := m.read(dir + "/name")
+		inputs := m.glob(dir + "/" + kind + "*_input")
+		if kind == "power" {
+			inputs = append(inputs, m.glob(dir+"/power*_average")...)
+		}
+		for _, in := range inputs {
+			v, ok := m.readInt(in)
+			if !ok {
+				continue
+			}
+			base := path.Base(in)
+			stem := base[:strings.LastIndex(base, "_")]
+			label := m.read(dir + "/" + stem + "_label")
+			if label == "" {
+				label = base
+			} else if strings.HasSuffix(base, "_average") {
+				label += " (average)"
+			}
+			value := float64(v)
+			switch kind {
+			case "temp":
+				value = round1(value / 1000)
+			case "power":
+				value = round1(value / 1e6)
+			}
+			out = append(out, Sensor{Chip: chip, Label: label, Value: value})
+		}
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Chip != out[j].Chip {
+			return out[i].Chip < out[j].Chip
+		}
+		return out[i].Label < out[j].Label
+	})
+	return out
+}
+
+// dgpu finds the NVIDIA display controller and, only when it is already awake, asks its driver for
+// its temperature and draw. **Asking wakes it**: nvidia-smi brings a suspended GPU out of D3, which
+// is the power a reading of power draw should not cost.
+func (m *Machine) dgpu(ctx context.Context) *DGPU {
+	for _, dir := range m.glob("/sys/bus/pci/devices/*") {
+		if m.read(dir+"/vendor") != "0x10de" || !strings.HasPrefix(m.read(dir+"/class"), "0x03") {
+			continue
+		}
+		g := &DGPU{Address: path.Base(dir), Runtime: m.read(dir + "/power/runtime_status")}
+		if g.Runtime != "active" {
+			g.Note = "the discrete GPU is " + g.Runtime + "; not woken to be read"
+			return g
+		}
+		out, err := m.Run(ctx, "nvidia-smi", "--query-gpu=name,temperature.gpu,power.draw,pstate", "--format=csv,noheader,nounits")
+		if err != nil {
+			g.Note = "nvidia-smi: " + err.Error()
+			return g
+		}
+		f := strings.Split(strings.TrimSpace(strings.SplitN(out, "\n", 2)[0]), ",")
+		if len(f) >= 4 {
+			g.Name = strings.TrimSpace(f[0])
+			if t, err := strconv.ParseFloat(strings.TrimSpace(f[1]), 64); err == nil {
+				g.TempC = &t
+			}
+			if w, err := strconv.ParseFloat(strings.TrimSpace(f[2]), 64); err == nil {
+				w = round1(w)
+				g.PowerW = &w
+			}
+			g.PState = strings.TrimSpace(f[3])
+		}
+		return g
+	}
+	return nil
+}
+
+// Thermals is what the thermals tool answers.
+type Thermals struct {
+	Temperatures []Sensor `json:"temperatures_c"`
+	Fans         []Sensor `json:"fans_rpm"`
+	DGPU         *DGPU    `json:"dgpu,omitempty"`
+	Profile      string   `json:"platform_profile,omitempty"`
+	Hottest      *Sensor  `json:"hottest,omitempty"`
+}
+
+func (m *Machine) Thermals(ctx context.Context) Thermals {
+	t := Thermals{Temperatures: m.hwmon("temp"), Fans: m.hwmon("fan"), DGPU: m.dgpu(ctx),
+		Profile: m.read("/sys/firmware/acpi/platform_profile")}
+	if t.Temperatures == nil {
+		t.Temperatures = []Sensor{}
+	}
+	if t.Fans == nil {
+		t.Fans = []Sensor{}
+	}
+	for i := range t.Temperatures {
+		if t.Hottest == nil || t.Temperatures[i].Value > t.Hottest.Value {
+			h := t.Temperatures[i]
+			t.Hottest = &h
+		}
+	}
+	return t
+}
+
+// PowerDraw is what the power-draw tool answers.
+type PowerDraw struct {
+	Source      Source   `json:"source"`
+	BatteryW    *float64 `json:"battery_w,omitempty"`
+	BatteryFlow string   `json:"battery_flow,omitempty"`
+	CPUPackageW *float64 `json:"apu_package_w,omitempty"`
+	DGPU        *DGPU    `json:"dgpu,omitempty"`
+	Note        string   `json:"note"`
+}
+
+func (m *Machine) PowerDraw(ctx context.Context) PowerDraw {
+	p := PowerDraw{Source: PowerSource(m.Supplies()), DGPU: m.dgpu(ctx),
+		Note: "on battery, battery_w is what the whole machine draws; on mains it is only what the battery takes or gives"}
+	for _, b := range m.Batteries() {
+		if b.PowerW != nil {
+			w := *b.PowerW
+			p.BatteryW = &w
+			switch strings.ToLower(b.Status) {
+			case "discharging":
+				p.BatteryFlow = "discharging"
+			case "charging":
+				p.BatteryFlow = "charging"
+			default:
+				p.BatteryFlow = strings.ToLower(b.Status)
+			}
+			break
+		}
+	}
+	// The integrated GPU's hwmon reports the whole APU's package power (PPT) on this model.
+	for _, s := range m.hwmon("power") {
+		if s.Chip == "amdgpu" && s.Label == "PPT" {
+			w := s.Value
+			p.CPUPackageW = &w
+		}
+	}
+	return p
+}
@@ -0,0 +1,308 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+	"time"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// Tools is the module's tools, over one machine and its switcher.
+func Tools(m *Machine, sw *Switcher) []stdio.Tool {
+	ctx := context.Background
+	return []stdio.Tool{
+		{
+			Name: "zephyrus_brightness",
+			Description: "Read or set the internal panel's and the keyboard's backlight. With no argument, reads both. " +
+				"panel is a percentage (40) or a step (+5, -10), never below 1 %; keyboard is off, low, med, high, 0-3, + or -.",
+			Input: map[string]any{
+				"panel":    map[string]any{"type": "string", "description": "percentage or step, e.g. 40, +5, -10"},
+				"keyboard": map[string]any{"type": "string", "description": "off, low, med, high, 0-3, + or -"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				out := map[string]any{}
+				if p := str(args, "panel"); p != "" {
+					got, err := m.SetPanel(ctx(), p)
+					if err != nil {
+						return nil, err
+					}
+					out["panel"] = got
+				} else if got, err := m.PanelBrightness(); err == nil {
+					out["panel"] = got
+				} else {
+					out["panel_error"] = err.Error()
+				}
+				if k := str(args, "keyboard"); k != "" {
+					got, err := m.SetKeyboard(ctx(), k)
+					if err != nil {
+						return nil, err
+					}
+					out["keyboard"] = got
+				} else if got, err := m.KeyboardBrightness(); err == nil {
+					out["keyboard"] = got
+				} else {
+					out["keyboard_error"] = err.Error()
+				}
+				return out, nil
+			},
+		},
+		{
+			Name:        "zephyrus_battery",
+			Description: "The battery: charge, energy, health (full against design), cycles, the charge limit, the power it gives or takes, and time left when discharging.",
+			Run: func(map[string]any) (any, error) {
+				return map[string]any{"source": PowerSource(m.Supplies()), "batteries": orEmpty(m.Batteries())}, nil
+			},
+		},
+		{
+			Name: "zephyrus_charge_limit",
+			Description: fmt.Sprintf("Read or set the battery charge limit through asusd. limit is 20-100; oneshot charges to full once "+
+				"and goes back to the limit. The module asserts %d %% again when its process next starts.", ChargeLimitPercent),
+			Input: map[string]any{
+				"limit":   map[string]any{"type": "integer", "description": "20-100"},
+				"oneshot": map[string]any{"type": "boolean", "description": "charge to full once, keeping the limit"},
+			},
+			Run: func(args map[string]any) (any, error) { return ChargeLimitTool(ctx(), m, args) },
+		},
+		{
+			Name: "zephyrus_gpu_mode",
+			Description: "Read or set the hybrid GPU's mode through supergfxd: Integrated, Hybrid or AsusMuxDgpu as the machine supports. " +
+				"Answers the mode, the discrete GPU's power state, any pending mode and the action it waits for (a logout, a reboot), " +
+				"and whether asusd will switch it again on the next change of power source.",
+			Input: map[string]any{
+				"mode": map[string]any{"type": "string", "description": "a supported mode, e.g. Integrated or Hybrid"},
+			},
+			Run: func(args map[string]any) (any, error) { return GPUModeTool(ctx(), m, args) },
+		},
+		{
+			Name: "zephyrus_profile",
+			Description: "Read or set the platform profile (Quiet, Balanced, Performance) through asusd. A profile set here is held " +
+				fmt.Sprintf("for hold_minutes (default %d, 0 for none) before the module's switcher may move it; a change of power source ends the hold.", int(DefaultHold.Minutes())),
+			Input: map[string]any{
+				"profile":      map[string]any{"type": "string", "enum": Profiles},
+				"hold_minutes": map[string]any{"type": "integer", "description": "how long the switcher leaves it (default 60, at most 1440)"},
+			},
+			Run: func(args map[string]any) (any, error) { return ProfileTool(ctx(), m, sw, args) },
+		},
+		{
+			Name:        "zephyrus_thermals",
+			Description: "Every temperature and fan the hardware reports (°C, RPM), the hottest, the platform profile, and the discrete GPU's temperature when it is awake (it is not woken to be read).",
+			Run:         func(map[string]any) (any, error) { return m.Thermals(ctx()), nil },
+		},
+		{
+			Name:        "zephyrus_power_draw",
+			Description: "What the machine draws: the battery's flow in watts, the APU's package power, the discrete GPU's draw when awake, and the power source with the reason it was decided.",
+			Run:         func(map[string]any) (any, error) { return m.PowerDraw(ctx()), nil },
+		},
+		{
+			Name: "zephyrus_profile_policy",
+			Description: "What the module's profile switcher would choose now and why: the power source, recent CPU load against the thresholds, " +
+				"the decision, the profile in force, any hold, what woke it, and what it asserted in asusd at start.",
+			Run: func(map[string]any) (any, error) { return PolicyTool(ctx(), m, sw), nil },
+		},
+		{
+			Name:        "zephyrus_fan_curves",
+			Description: "The fan curves asusd holds for each profile (or one profile): per fan, eight points of temperature and duty.",
+			Input: map[string]any{
+				"profile": map[string]any{"type": "string", "enum": Profiles},
+			},
+			Run: func(args map[string]any) (any, error) { return FanCurvesTool(ctx(), m, args) },
+		},
+		{
+			Name: "zephyrus_check",
+			Description: "Check what this module expects of the machine: the model, the vendor packages and daemons, the NVIDIA options in force, " +
+				"suspend and resume, the charge limit, one authority each over the profile and the GPU mode, and the predecessor's leftovers. Says what it did not check.",
+			Run: func(map[string]any) (any, error) { return m.Check(ctx(), sw), nil },
+		},
+	}
+}
+
+// ChargeLimitTool reads or sets the limit.
+func ChargeLimitTool(ctx context.Context, m *Machine, args map[string]any) (any, error) {
+	out := map[string]any{"module_limit_percent": ChargeLimitPercent}
+	if v, given := args["limit"]; given && v != nil {
+		n, err := whole(v, "limit")
+		if err != nil {
+			return nil, err
+		}
+		if n < 20 || n > 100 {
+			return nil, fmt.Errorf("limit %d is outside 20-100", n)
+		}
+		if _, err := m.Run(ctx, "asusctl", "battery", "limit", strconv.Itoa(n)); err != nil {
+			return nil, vendor("asusctl", err)
+		}
+		out["set"] = n
+	}
+	if b, _ := args["oneshot"].(bool); b {
+		if _, err := m.Run(ctx, "asusctl", "battery", "oneshot"); err != nil {
+			return nil, vendor("asusctl", err)
+		}
+		out["oneshot"] = "charging to full once; the limit returns after"
+	}
+	if n, err := m.ChargeLimit(ctx); err == nil {
+		out["asusd_limit_percent"] = n
+	} else {
+		out["asusd_error"] = err.Error()
+	}
+	for _, b := range m.Batteries() {
+		if b.LimitPercent != nil {
+			out["kernel_limit_percent"] = *b.LimitPercent
+		}
+	}
+	return out, nil
+}
+
+// GPUModeTool reads or sets the GPU mode.
+func GPUModeTool(ctx context.Context, m *Machine, args map[string]any) (any, error) {
+	g, err := m.GPU(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out := map[string]any{}
+	if want := str(args, "mode"); want != "" {
+		mode := ""
+		for _, s := range g.Supported {
+			if strings.EqualFold(s, want) {
+				mode = s
+			}
+		}
+		if mode == "" {
+			return nil, fmt.Errorf("mode %q is not one this machine supports (%s)", want, strings.Join(g.Supported, ", "))
+		}
+		said, err := m.Run(ctx, "supergfxctl", "-m", mode)
+		if err != nil {
+			return nil, vendor("supergfxctl", err)
+		}
+		out["requested"] = mode
+		if s := strings.TrimSpace(said); s != "" {
+			out["supergfxctl_said"] = s
+		}
+		if g, err = m.GPU(ctx); err != nil {
+			return nil, err
+		}
+	}
+	out["gpu"] = g
+	if c := m.Asusd(); c != nil && (c.ACCommand != "" || c.BatteryCommand != "") {
+		out["asusd_switches_it"] = map[string]string{"on_ac": c.ACCommand, "on_battery": c.BatteryCommand,
+			"note": "asusd runs these on every change of power source, so a mode set here lasts until the next one"}
+	}
+	return out, nil
+}
+
+// ProfileTool reads or sets the profile.
+func ProfileTool(ctx context.Context, m *Machine, sw *Switcher, args map[string]any) (any, error) {
+	out := map[string]any{}
+	if want := str(args, "profile"); want != "" {
+		p, err := canonicalProfile(want)
+		if err != nil {
+			return nil, err
+		}
+		hold := DefaultHold
+		if v, given := args["hold_minutes"]; given && v != nil {
+			n, err := whole(v, "hold_minutes")
+			if err != nil {
+				return nil, err
+			}
+			if n < 0 {
+				return nil, fmt.Errorf("hold_minutes must not be negative")
+			}
+			hold = time.Duration(min(n, 1440)) * time.Minute
+		}
+		if err := m.SetProfile(ctx, p); err != nil {
+			return nil, err
+		}
+		out["set"] = p
+		if sw != nil {
+			if until := sw.Hold(p, hold); !until.IsZero() {
+				out["held_until"] = until
+			}
+		}
+	}
+	state, err := m.Profile(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out["profile"] = state
+	return out, nil
+}
+
+// PolicyTool reports the switcher and, independently of it, what the policy says now.
+func PolicyTool(ctx context.Context, m *Machine, sw *Switcher) any {
+	out := map[string]any{
+		"thresholds": map[string]any{
+			"on_battery": ProfileOnBattery, "on_ac": ProfileOnAC, "under_load": ProfileUnderLoad,
+			"cpu_high_percent": CPUHighPercent, "cpu_low_percent": CPULowPercent,
+			"sample_every": SampleEvery.String(), "sustain_samples": SustainSamples, "relax_samples": RelaxSamples,
+			"set_by": "constants until settings exist (novox/hq issue 168)",
+		},
+	}
+	if sw != nil {
+		out["switcher"] = sw.Report()
+	} else {
+		var p Policy
+		out["decision_now"] = p.Decide(PowerSource(m.Supplies()))
+	}
+	if state, err := m.Profile(ctx); err == nil {
+		out["in_force"] = state
+	} else {
+		out["in_force_error"] = err.Error()
+	}
+	if pid, ok := m.predecessorProcess("auto-profile"); ok {
+		out["second_switcher"] = fmt.Sprintf("the predecessor's auto-profile still runs (pid %d) and overrides this every five seconds", pid)
+	}
+	return out
+}
+
+// FanCurvesTool reads asusd's fan curves.
+func FanCurvesTool(ctx context.Context, m *Machine, args map[string]any) (any, error) {
+	profiles := Profiles
+	if want := str(args, "profile"); want != "" {
+		p, err := canonicalProfile(want)
+		if err != nil {
+			return nil, err
+		}
+		profiles = []string{p}
+	}
+	out := map[string]any{}
+	for _, p := range profiles {
+		said, err := m.Run(ctx, "asusctl", "fan-curve", "--mod-profile", strings.ToLower(p))
+		if err != nil {
+			return nil, vendor("asusctl", err)
+		}
+		out[p] = orEmpty(ParseFanCurves(said))
+	}
+	return out, nil
+}
+
+func str(args map[string]any, key string) string {
+	s, _ := args[key].(string)
+	return strings.TrimSpace(s)
+}
+
+// whole is an integer argument given as a JSON number or a numeric string.
+func whole(v any, key string) (int, error) {
+	switch n := v.(type) {
+	case float64:
+		if n != math.Trunc(n) {
+			return 0, fmt.Errorf("%s must be a whole number, not %v", key, n)
+		}
+		return int(n), nil
+	case string:
+		i, err := strconv.Atoi(strings.TrimSpace(n))
+		if err != nil {
+			return 0, fmt.Errorf("%s must be a whole number, not %q", key, n)
+		}
+		return i, nil
+	}
+	return 0, fmt.Errorf("%s must be a whole number", key)
+}
+
+func orEmpty[T any](s []T) []T {
+	if s == nil {
+		return []T{}
+	}
+	return s
+}
@@ -0,0 +1,72 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"syscall"
+)
+
+// The kernel announces every change of a power supply — an adapter plugged or pulled, a battery
+// starting or stopping to discharge — as a uevent on a netlink socket that any account may listen
+// on. That is the event the switcher reacts to: no daemon, no bus client, no polling.
+//
+// upower re-announces the same changes on the system bus, and listening there would need a D-Bus
+// client in the bundle; udev's re-broadcast (netlink group 2) carries a libudev header. The kernel's
+// own group (1) is the source both of them read.
+
+// powerSupplyEvent says whether a uevent is about a power supply.
+func powerSupplyEvent(msg []byte) bool {
+	for _, field := range bytes.Split(msg, []byte{0}) {
+		if bytes.Equal(field, []byte("SUBSYSTEM=power_supply")) {
+			return true
+		}
+	}
+	return false
+}
+
+// listenPowerSupply opens the kernel's uevent socket and sends on the channel for each power-supply
+// event, never blocking: a burst of events is one wake-up. It stops when ctx ends.
+func listenPowerSupply(ctx context.Context) (<-chan struct{}, error) {
+	fd, err := syscall.Socket(syscall.AF_NETLINK, syscall.SOCK_RAW|syscall.SOCK_CLOEXEC, syscall.NETLINK_KOBJECT_UEVENT)
+	if err != nil {
+		return nil, fmt.Errorf("opening the kernel's uevent socket: %w", err)
+	}
+	if err := syscall.Bind(fd, &syscall.SockaddrNetlink{Family: syscall.AF_NETLINK, Groups: 1}); err != nil {
+		syscall.Close(fd)
+		return nil, fmt.Errorf("joining the kernel's uevent group: %w", err)
+	}
+	events := make(chan struct{}, 1)
+	go func() {
+		<-ctx.Done()
+		syscall.Close(fd)
+	}()
+	go func() {
+		defer close(events)
+		buf := make([]byte, 64*1024)
+		for {
+			n, _, err := syscall.Recvfrom(fd, buf, 0)
+			if err != nil {
+				if err == syscall.EINTR || err == syscall.ENOBUFS {
+					// ENOBUFS: events were dropped. Treat it as one, since a dropped one may have
+					// been the adapter.
+					if err == syscall.ENOBUFS {
+						select {
+						case events <- struct{}{}:
+						default:
+						}
+					}
+					continue
+				}
+				return
+			}
+			if powerSupplyEvent(buf[:n]) {
+				select {
+				case events <- struct{}{}:
+				default:
+				}
+			}
+		}
+	}()
+	return events, nil
+}
@@ -0,0 +1,33 @@
+#!/bin/bash
+# zephyrus-backlight + | - | PERCENT — step or set the internal panel's backlight, never below 1 %.
+# Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+# The panel is the backlight beneath the eDP connector, not a name: in hybrid mode this model also
+# registers the discrete GPU's backlight (nvidia_0), which moves nothing. Writable by the video group
+# through the module's udev rule, so the vendor-key trigger needs no root.
+set -u
+STEP=5
+dev=""
+for d in /sys/class/backlight/*; do
+	[ -e "$d" ] || continue
+	case "$(readlink -f "$d")" in *-eDP-*) dev=$d; break ;; esac
+done
+if [ -z "$dev" ]; then
+	for d in /sys/class/backlight/*; do [ -e "$d" ] && { dev=$d; break; }; done
+fi
+[ -n "$dev" ] || { echo "zephyrus-backlight: no backlight" >&2; exit 1; }
+cur=$(cat "$dev/brightness")
+max=$(cat "$dev/max_brightness")
+pct=$(( cur * 100 / max ))
+case "${1:-}" in
+	+|up|Up) pct=$(( pct + STEP )) ;;
+	-|down|Down) pct=$(( pct - STEP )) ;;
+	''|*[!0-9]*) echo "usage: zephyrus-backlight + | - | PERCENT" >&2; exit 2 ;;
+	*) pct=$1 ;;
+esac
+(( pct < 1 )) && pct=1
+(( pct > 100 )) && pct=100
+new=$(( max * pct / 100 ))
+(( new < 1 )) && new=1
+printf '%s' "$new" >"$dev/brightness" || exit 1
+exec "$(dirname "$0")/zephyrus-notify" 5555 "Brightness: ${pct}%"
@@ -0,0 +1,12 @@
+#!/bin/bash
+# zephyrus-notify ID SUMMARY — a short desktop notification that replaces the previous one with the
+# same ID, through the session's notification service on its bus. busctl is the service manager's
+# own client, so nothing is installed for it. Shipped by the mesh's asus-zephyrus-g14 module.
+set -u
+id=${1:-0}
+summary=${2:-}
+uid=$(id -u)
+DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/${uid}/bus" \
+	busctl --user call org.freedesktop.Notifications /org/freedesktop/Notifications \
+	org.freedesktop.Notifications Notify susssasa{sv}i \
+	asus-zephyrus-g14 "$id" "" "$summary" "" 0 1 urgency y 0 1500 >/dev/null 2>&1 || true
@@ -0,0 +1,38 @@
+#!/bin/bash
+# zephyrus-session COMMAND [ARG...] — run a command in the operator's graphical session from outside
+# it: from a vendor-key trigger, which triggerhappy runs as the operator's account but with none of
+# the session's environment. Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+# What it replaces: the predecessor's `as-user`, which triggerhappy ran as root and which `su`-ed to
+# a named person with a hard-coded user id and display, and sourced a file of secrets on the way.
+# Here the account is whoever runs it, the bus is that account's, and the display is the one the
+# account's own session uses. Nothing is sourced.
+set -u
+uid=$(id -u)
+export XDG_RUNTIME_DIR="/run/user/${uid}"
+export DBUS_SESSION_BUS_ADDRESS="unix:path=${XDG_RUNTIME_DIR}/bus"
+home=$(getent passwd "$uid" | cut -d: -f6)
+[ -n "$home" ] && export HOME="$home"
+if [ -z "${DISPLAY:-}" ]; then
+	# The login manager may not record the display with logind; any process of this account that
+	# has one says which it is.
+	for s in $(loginctl list-sessions --no-legend 2>/dev/null | awk -v u="$uid" '$2 == u { print $1 }'); do
+		d=$(loginctl show-session "$s" -p Display --value 2>/dev/null)
+		if [ -n "$d" ]; then export DISPLAY="$d"; break; fi
+	done
+fi
+if [ -z "${DISPLAY:-}" ]; then
+	for pid in $(pgrep -u "$uid" 2>/dev/null); do
+		env=$(tr '\0' '\n' <"/proc/$pid/environ" 2>/dev/null) || continue
+		d=$(printf '%s\n' "$env" | sed -n 's/^DISPLAY=//p' | head -n1)
+		if [ -n "$d" ]; then
+			export DISPLAY="$d"
+			a=$(printf '%s\n' "$env" | sed -n 's/^XAUTHORITY=//p' | head -n1)
+			[ -n "$a" ] && export XAUTHORITY="$a"
+			break
+		fi
+	done
+fi
+: "${XAUTHORITY:=${HOME}/.Xauthority}"
+export XAUTHORITY
+exec "$@"
@@ -0,0 +1,29 @@
+#!/bin/bash
+# zephyrus-touchpad reset | toggle — apply the touchpad's settings again, or switch it on or off.
+# Shipped by the mesh's asus-zephyrus-g14 module; edit the catalogue.
+#
+# The settings themselves are an X input class (/etc/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf),
+# which X applies every time the device appears — after a resume too, which is what the predecessor's
+# sleep hook existed for. This is the manual form, bound to the touchpad key.
+set -u
+here=$(dirname "$0")
+name=$("$here/zephyrus-session" xinput list --name-only 2>/dev/null | grep -m1 -i 'touchpad')
+[ -n "$name" ] || { echo "zephyrus-touchpad: no touchpad in this session" >&2; exit 1; }
+x() { "$here/zephyrus-session" xinput "$@"; }
+case "${1:-reset}" in
+	reset)
+		x set-prop "$name" "libinput Tapping Enabled" 1
+		x set-prop "$name" "libinput Natural Scrolling Enabled" 1
+		x set-prop "$name" "libinput Accel Speed" 0.15
+		x enable "$name"
+		"$here/zephyrus-session" "$here/zephyrus-notify" 7779 "Touchpad: reset"
+		;;
+	toggle)
+		if x list-props "$name" | grep -q 'Device Enabled ([0-9]*):[[:space:]]*1'; then
+			x disable "$name"; "$here/zephyrus-session" "$here/zephyrus-notify" 7779 "Touchpad: off"
+		else
+			x enable "$name"; "$here/zephyrus-session" "$here/zephyrus-notify" 7779 "Touchpad: on"
+		fi
+		;;
+	*) echo "usage: zephyrus-touchpad reset | toggle" >&2; exit 2 ;;
+esac
@@ -0,0 +1,5 @@
+module asuszephyrusg14
+
+go 1.22
+
+require git.novox.be/novox/mesh-sdk/go v0.1.6
@@ -0,0 +1,2 @@
+git.novox.be/novox/mesh-sdk/go v0.1.6 h1:9qzdYONYbJdWcu6sxQcq9v1LI0JxcfkiKYkMUzJSkVQ=
+git.novox.be/novox/mesh-sdk/go v0.1.6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
@@ -0,0 +1,254 @@
+{
+  "module": "asus-zephyrus-g14",
+  "version": "1",
+  "capabilities": [
+    "package-manager",
+    "service-manager"
+  ],
+  "emits": [
+    "profile.switched"
+  ],
+  "tools": [
+    "zephyrus_brightness",
+    "zephyrus_battery",
+    "zephyrus_charge_limit",
+    "zephyrus_gpu_mode",
+    "zephyrus_profile",
+    "zephyrus_thermals",
+    "zephyrus_power_draw",
+    "zephyrus_profile_policy",
+    "zephyrus_fan_curves",
+    "zephyrus_check"
+  ],
+  "resources": [
+    {
+      "id": "asusctl",
+      "type": "package",
+      "package": "asusctl"
+    },
+    {
+      "id": "playerctl",
+      "type": "package",
+      "package": "playerctl"
+    },
+    {
+      "id": "xinput",
+      "type": "package",
+      "package": "xorg-xinput"
+    },
+    {
+      "id": "asusd",
+      "type": "service",
+      "unit": "asusd.service",
+      "state": "running"
+    },
+    {
+      "id": "supergfxd",
+      "type": "service",
+      "unit": "supergfxd.service",
+      "state": "running",
+      "boot": "enabled"
+    },
+    {
+      "id": "scripts",
+      "type": "archive",
+      "path": "/usr/local/lib/asus-zephyrus-g14",
+      "artifact": "scripts"
+    },
+    {
+      "id": "nvidia-options",
+      "type": "file",
+      "path": "/etc/modprobe.d/g14-nvidia-power.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The discrete GPU's driver options on the ROG Zephyrus G14 (GA403, RTX 40 series, hybrid graphics).\n#\n# NVreg_DynamicPowerManagement=0x00 turns runtime D3 off. With it on, a change of power source sends\n# the driver an ACPI notification it fails to handle on this model (\"RmHandleDNotifierEvent: Failed to\n# handle ACPI D-Notifier event, status=0x62\"), and the GPU stops making progress until the machine is\n# powered off. Off costs a few idle watts in hybrid mode and keeps the machine up.\n#\n# NVreg_PreserveVideoMemoryAllocations=1 saves video memory across suspend, so what used the GPU still\n# works after waking. It needs nvidia-suspend, -hibernate and -resume to run around a sleep, which this\n# module's drop-ins on the sleep services ask for.\n#\n# A change here applies when the driver next loads: at the next boot.\noptions nvidia NVreg_PreserveVideoMemoryAllocations=1\noptions nvidia NVreg_DynamicPowerManagement=0x00\n"
+    },
+    {
+      "id": "video-options",
+      "type": "file",
+      "path": "/etc/modprobe.d/video-brightness-switch.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The ACPI video driver does not change the backlight itself on the brightness keys: on this model it\n# moves the wrong one. The keys are triggerhappy's (see /etc/triggerhappy/triggers.d/asus-g14.conf).\n# Applies when the module next loads: at the next boot.\noptions video brightness_switch_enabled=0\n"
+    },
+    {
+      "id": "suspend-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/systemd-suspend.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "nvidia-on-suspend",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-suspend.service.d/asus-zephyrus-g14-nvidia.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-suspend.service nvidia-resume.service\n"
+    },
+    {
+      "id": "hibernate-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/systemd-hibernate.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "nvidia-on-hibernate",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-hibernate.service.d/asus-zephyrus-g14-nvidia.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-hibernate.service nvidia-resume.service\n"
+    },
+    {
+      "id": "suspend-then-hibernate-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/systemd-suspend-then-hibernate.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "nvidia-on-suspend-then-hibernate",
+      "type": "file",
+      "path": "/etc/systemd/system/systemd-suspend-then-hibernate.service.d/asus-zephyrus-g14-nvidia.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-suspend-then-hibernate.service nvidia-resume.service\n"
+    },
+    {
+      "id": "powerd-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/nvidia-powerd.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "powerd-opt-in",
+      "type": "file",
+      "path": "/etc/systemd/system/nvidia-powerd.service.d/asus-zephyrus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# nvidia-powerd (Dynamic Boost) was the first error in the chain that hung this model's GPU on a change\n# of power source, and asusd starts it on mains. It runs only when the kernel command line says\n# zephyrus.nvidia-powerd — an explicit opt-in, at boot.\n[Unit]\nConditionKernelCommandLine=zephyrus.nvidia-powerd\n"
+    },
+    {
+      "id": "logind-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/logind.conf.d",
+      "mode": "0755"
+    },
+    {
+      "id": "logind-power",
+      "type": "file",
+      "path": "/etc/systemd/logind.conf.d/power.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The power key and the lid suspend, on battery, on mains and docked alike.\n[Login]\nHandlePowerKey=suspend\nHandleLidSwitch=suspend\nHandleLidSwitchExternalPower=suspend\nHandleLidSwitchDocked=suspend\n"
+    },
+    {
+      "id": "logind",
+      "type": "service",
+      "unit": "systemd-logind.service",
+      "reload-on": [
+        "logind-power"
+      ]
+    },
+    {
+      "id": "backlight-rule",
+      "type": "file",
+      "path": "/etc/udev/rules.d/90-backlight.rules",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The backlights are writable by the video group, so the brightness keys and the module's brightness tool\n# move the panel without root.\nACTION==\"add\", SUBSYSTEM==\"backlight\", RUN+=\"/usr/bin/chgrp video /sys/class/backlight/%k/brightness\", RUN+=\"/usr/bin/chmod g+w /sys/class/backlight/%k/brightness\"\n"
+    },
+    {
+      "id": "udev",
+      "type": "service",
+      "unit": "systemd-udevd.service",
+      "reload-on": [
+        "backlight-rule"
+      ]
+    },
+    {
+      "id": "triggerhappy-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/triggerhappy.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "triggerhappy-as-account",
+      "type": "file",
+      "path": "/etc/systemd/system/triggerhappy.service.d/asus-zephyrus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# triggerhappy runs the vendor-key triggers as the operator's account, not as root: it opens the input\n# devices first and then drops to the account with its groups (input, video), so the triggers reach the\n# account's own session bus and the panel through the video group, with no su and no hard-coded user.\n[Service]\nExecStart=\nExecStart=/usr/bin/thd --triggers /etc/triggerhappy/triggers.d/ --socket /run/thd.socket --user ${machine:account} --deviceglob /dev/input/event*\n"
+    },
+    {
+      "id": "vendor-keys",
+      "type": "file",
+      "path": "/etc/triggerhappy/triggers.d/asus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The ROG Zephyrus G14's vendor keys, which reach no X client. Run as the operator's account (see the\n# module's drop-in on triggerhappy.service).\nKEY_PROG1\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session playerctl play-pause\nKEY_PROG3\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session playerctl previous\nKEY_PROG4\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session playerctl next\nKEY_BRIGHTNESSDOWN\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight -\nKEY_BRIGHTNESSDOWN\t2\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight -\nKEY_BRIGHTNESSUP\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight +\nKEY_BRIGHTNESSUP\t2\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight +\nKEY_F21\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset\n"
+    },
+    {
+      "id": "triggerhappy",
+      "type": "service",
+      "unit": "triggerhappy.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "triggerhappy-as-account",
+        "vendor-keys",
+        "scripts"
+      ]
+    },
+    {
+      "id": "upower-package",
+      "type": "package",
+      "package": "upower"
+    },
+    {
+      "id": "upower-drop-ins",
+      "type": "directory",
+      "path": "/etc/UPower/UPower.conf.d",
+      "mode": "0755"
+    },
+    {
+      "id": "low-battery",
+      "type": "file",
+      "path": "/etc/UPower/UPower.conf.d/50-asus-zephyrus-g14.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# On low battery the machine suspends rather than powering off, at 7 % — s2idle still draws a little,\n# so it leaves headroom. A drop-in over the package's own UPower.conf, which stays the package's.\n[UPower]\nUsePercentageForPolicy=true\nPercentageLow=15.0\nPercentageCritical=10.0\nPercentageAction=7.0\nCriticalPowerAction=Suspend\nAllowRiskyCriticalPowerAction=true\n"
+    },
+    {
+      "id": "upower",
+      "type": "service",
+      "unit": "upower.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "low-battery"
+      ]
+    },
+    {
+      "id": "xorg-drop-ins",
+      "type": "directory",
+      "path": "/etc/X11/xorg.conf.d",
+      "mode": "0755"
+    },
+    {
+      "id": "touchpad",
+      "type": "file",
+      "path": "/etc/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The touchpad's settings, applied by X every time the device appears — at login and after every\n# resume, when the device is initialised again. This replaces the predecessor's sleep hook, which ran\n# xinput after a resume as a named person on a guessed display.\nSection \"InputClass\"\n    Identifier \"asus-zephyrus-g14 touchpad\"\n    MatchIsTouchpad \"on\"\n    Option \"Tapping\" \"on\"\n    Option \"NaturalScrolling\" \"true\"\n    Option \"AccelSpeed\" \"0.15\"\nEndSection\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools-go",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/zephyrus",
+        "binary": "zephyrus",
+        "loads": [
+          "zephyrus"
+        ]
+      },
+      {
+        "name": "scripts",
+        "kind": "archive",
+        "from": "files"
+      }
+    ]
+  }
+}
@@ -0,0 +1,74 @@
+# claude-code
+
+The operator's agent on a machine (novox/hq design 36): its package, its machine-wide managed
+configuration, and the consumer side of the Anthropic licence manager (design 39, ADR 0183).
+
+## What it owns
+
+Two directories, declared, so the mesh refuses a second module owning either:
+
+- `/etc/claude-code`, the agent's machine-wide managed directory, root's, `0755`.
+- `~/.claude` under the operator account's home, the operator's, `0700`. The module owns the directory —
+  that it exists, who owns it, its mode — and of what is inside only what it writes. Everything else
+  in it (memory, history, projects, local settings, a person's own rules and skills) is the person's
+  and is never read or written (hq ADR 0182). Unassigned, the module leaves the directory: the host
+  removes a directory only when it is empty.
+
+## What it writes
+
+Under the agent's managed directory, `/etc/claude-code`, owned whole by this module and rewritten
+whenever the node's tool runtime collects the module's tools:
+
+| file | holds |
+|---|---|
+| `managed-mcp.json` | the tool servers every session loads: the mesh's console as `mesh`, and the servers set in this module's `mcp_servers` setting. **Exclusive**: a server not listed here does not load — not one added with `claude mcp add`, not a project's `.mcp.json`, not a plugin's |
+| `managed-settings.json` | the repositories' attribution convention, the claude.ai connectors kept beside the managed servers, and the key-helper while the node holds an API-key licence |
+| `CLAUDE.md` | how a session on this mesh works, this node's name and role, the conventions |
+
+Under the operator's home, only `~/.claude/.credentials.json`, and only when the licence manager hands
+this node a subscription token. Nothing else under the home is read or written.
+
+## Over NATS
+
+Everything between this module and the rest of the mesh is NATS, in three kinds: an **event** says that
+something happened and carries no secret, because a stream keeps it; a **request** carries a token,
+because nothing keeps it (hq design 32 §10); and **state** is the current value of something every node
+must see, a node that joins later included — kept, so it carries no secret either (hq ADR 0201).
+
+| what | how |
+|---|---|
+| the licence manager rotated a licence, or switched this node | its `licence.rotated` / `licence.switched` event; this module then asks `anthropic-licence-manager.current` for its token, sealed to the key it sends |
+| this node starts | it asks `current` once, so a node that was off catches up |
+| a person ran `/login` here | the credentials file gains a refresh token this module never writes; it asks `anthropic-licence-manager.adopt` at once with the grant sealed to the manager's key — the one time a refresh token travels, because the login made the manager's stale |
+| an MCP server registered through this module | a key in the module's `servers` state — `all.<server>` for every node, `<node>.<server>` for one; every node watches it and renders what applies to it, a node's own entry over the one for every node. A node that joins later, or was off, reads the whole current set at start; unregistering is a delete. An entry with a secret in its `env` or `headers` is refused by the runtime |
+
+## Tools
+
+`claude_code_status`, `claude_code_render`, `claude_code_pull`, `claude_code_mcp_list`,
+`claude_code_mcp_register` (this node by default; `nodes: "all"` or a list for more — called for this
+node alone, its answer names the other nodes running claude-code), `claude_code_mcp_unregister`.
+
+## Settings
+
+Per node or for the whole mesh, through `mesh-controller.settings module=claude-code`:
+
+- `role` — what this node is, in a few words; shown to every session.
+- `mcp_servers` — extra tool servers, set by the operator for the mesh or a node, beside the ones
+  registered through the tools; keyed by name, in the vendor's `.mcp.json` entry shape
+  (`{"type":"http","url":…}` or `{"type":"stdio","command":…,"args":[…]}`). The name `mesh` is the
+  module's own and cannot be set. Put a person's own servers here, or they stop loading.
+
+## On a machine that carried the predecessor
+
+Remove these by hand, once; the mesh removes nothing it did not make (ADR 0182):
+
+- `~/.claude/CLAUDE.md`
+- `~/.claude/rules/00-hal-mesh.md`, `~/.claude/rules/conventions.md`
+- `~/.claude/skills/cleanup/`, `~/.claude/skills/hal-switch-license/`
+- the hand-made console entry in `~/.claude.json` under `mcpServers` — it is ignored now anyway
+
+## Escalation
+
+Writing `/etc/claude-code` needs root. The runtime runs as the operator account, and the module uses
+that account's passwordless `sudo`; on a machine without it, `claude_code_render` says so and nothing
+is written.
@@ -0,0 +1,112 @@
+// The agent's credentials file, and whether an offered grant may replace what it holds (novox/hq
+// ADR 0183, design 36 §5). Pure where it decides, so the rules are tested without a file.
+//
+// The file is the vendor's: `{ claudeAiOauth: { accessToken, expiresAt, refreshTokenExpiresAt?,
+// scopes?, subscriptionType?, rateLimitTier? }, ... }`. A node never holds a refresh token, so the
+// one this module writes never carries one, and a full grant a login left behind is stripped the
+// moment the manager hands the node its own.
+//
+// The lineage rule is the predecessor's, with the incidents that earned it: a rotation of the same
+// licence is applied only if newer; a grant re-issued by a login is adopted whatever its expiry; a
+// switch to another licence is applied regardless, because across licences the expiries are
+// unrelated numbers.
+
+import { readFileSync, renameSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface Grant {
+  readonly accessToken: string;
+  readonly expiresAt: number;
+  readonly refreshTokenExpiresAt?: number | null;
+  readonly scopes?: readonly string[] | null;
+  readonly subscriptionType?: string | null;
+  readonly rateLimitTier?: string | null;
+}
+
+export type ApplySource = "rotation" | "switch";
+
+export type ApplyDecision =
+  | { apply: true; reissued?: boolean }
+  | { apply: false; reason: "already-current" }
+  | { apply: false; reason: "not-newer"; localExpiresAt: number };
+
+/** Two refresh-token expiries within a day are one lineage; a login starts a fresh window weeks away. */
+export const GENERATION_TOLERANCE_MS = 24 * 60 * 60 * 1000;
+
+export function sameGeneration(a?: number | null, b?: number | null): boolean {
+  if (a == null || b == null) return true;
+  return Math.abs(Number(a) - Number(b)) <= GENERATION_TOLERANCE_MS;
+}
+
+export function decideApply(local: Grant | null | undefined, offered: Grant, source: ApplySource): ApplyDecision {
+  if (!local?.accessToken) return { apply: true };
+  if (local.accessToken === offered.accessToken) return { apply: false, reason: "already-current" };
+  const reissued = !sameGeneration(local.refreshTokenExpiresAt, offered.refreshTokenExpiresAt);
+  if (source === "rotation" && !reissued && Number(local.expiresAt) >= Number(offered.expiresAt)) {
+    return { apply: false, reason: "not-newer", localExpiresAt: Number(local.expiresAt) };
+  }
+  return reissued ? { apply: true, reissued: true } : { apply: true };
+}
+
+type Oauth = Record<string, unknown> & { accessToken?: string; refreshToken?: string; expiresAt?: number };
+type Credentials = Record<string, unknown> & { claudeAiOauth?: Oauth };
+
+export function readCredentials(path: string): Credentials | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Credentials;
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The grant the file holds, or null. */
+export function grantOf(creds: Credentials | null): Grant | null {
+  const o = creds?.claudeAiOauth;
+  if (!o?.accessToken) return null;
+  return {
+    accessToken: o.accessToken,
+    expiresAt: Number(o.expiresAt ?? 0),
+    refreshTokenExpiresAt: o.refreshTokenExpiresAt == null ? null : Number(o.refreshTokenExpiresAt),
+  };
+}
+
+/** Does the file hold a full grant — a refresh token this module never writes, so a person's login? */
+export function holdsLogin(creds: Credentials | null): boolean {
+  return typeof creds?.claudeAiOauth?.refreshToken === "string" && creds.claudeAiOauth.refreshToken.length > 0;
+}
+
+/**
+ * The handed grant laid over what is there — a rotation of the licence the node already holds — or,
+ * for a switch, in place of it: the old licence's grant goes whole, scopes and subscription included,
+ * and only keys outside the grant (another kind of credential the vendor keeps in the file) stay.
+ * Either way, no refresh token survives.
+ */
+export function replacedBy(local: Credentials | null, grant: Grant): Credentials {
+  const next: Credentials = { ...(local ?? {}) };
+  delete next.claudeAiOauth;
+  return withGrant(next, grant);
+}
+
+/** Overlay the handed grant on what is there, and delete any refresh token. */
+export function withGrant(local: Credentials | null, grant: Grant): Credentials {
+  const next: Credentials = { ...(local ?? {}) };
+  const oauth: Oauth = { ...(local?.claudeAiOauth ?? {}) };
+  oauth.accessToken = grant.accessToken;
+  oauth.expiresAt = grant.expiresAt;
+  for (const k of ["refreshTokenExpiresAt", "scopes", "subscriptionType", "rateLimitTier"] as const) {
+    const v = grant[k];
+    if (v != null) oauth[k] = v as unknown;
+  }
+  delete oauth.refreshToken;
+  next.claudeAiOauth = oauth;
+  return next;
+}
+
+/** Write atomically at 0600: a partial credentials file must never be read as a whole one. */
+export function writeCredentials(path: string, creds: Credentials): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.mesh-tmp`;
+  writeFileSync(tmp, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 });
+  renameSync(tmp, path);
+}
@@ -0,0 +1,50 @@
+// Which account the agent is logged in as (novox/hq ADR 0183): not in the token, but in the agent's
+// own state file beside the home, `~/.claude.json` → `oauthAccount`. Read to attribute a login; written,
+// three keys and nothing else, when a licence is switched, so the file Claude Code shows the account from
+// names the account whose token it now holds (as the predecessor learned: two files that disagree make
+// a later login look like the wrong account).
+
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+
+export interface Identity {
+  readonly accountUuid: string;
+  readonly emailAddress?: string;
+  readonly organizationUuid?: string;
+}
+
+export function readIdentity(stateFile: string): Identity | null {
+  try {
+    const raw = JSON.parse(readFileSync(stateFile, "utf8")) as { oauthAccount?: Record<string, unknown> };
+    const a = raw.oauthAccount;
+    if (!a || typeof a.accountUuid !== "string") return null;
+    return {
+      accountUuid: a.accountUuid,
+      emailAddress: typeof a.emailAddress === "string" ? a.emailAddress : undefined,
+      organizationUuid: typeof a.organizationUuid === "string" ? a.organizationUuid : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Point the state file's account at `id`, keeping every other key as found. Returns whether the file
+ * changed; a file that cannot be read as an object is left alone rather than replaced.
+ */
+export function writeIdentity(stateFile: string, id: Identity): boolean {
+  let raw: Record<string, unknown>;
+  try {
+    raw = JSON.parse(readFileSync(stateFile, "utf8")) as Record<string, unknown>;
+    if (!raw || typeof raw !== "object") return false;
+  } catch {
+    raw = {};
+  }
+  const current = (raw.oauthAccount ?? {}) as Record<string, unknown>;
+  if (current.accountUuid === id.accountUuid && current.emailAddress === id.emailAddress
+      && current.organizationUuid === id.organizationUuid) return false;
+  raw.oauthAccount = { ...current, accountUuid: id.accountUuid, emailAddress: id.emailAddress, organizationUuid: id.organizationUuid };
+  const tmp = `${stateFile}.mesh-tmp`;
+  writeFileSync(tmp, JSON.stringify(raw, null, 2), { mode: 0o600 });
+  renameSync(tmp, stateFile);
+  return true;
+}
@@ -0,0 +1,90 @@
+{
+  "module": "claude-code",
+  "version": "1",
+  "slug": "agent",
+  "capabilities": [
+    "package-manager"
+  ],
+  "requires": [
+    "mcp-endpoint"
+  ],
+  "binds": {
+    "mcp-endpoint": "${dir:state}/mcp-endpoint.json"
+  },
+  "consumes": [
+    "claude-licence-manager.licence.rotated",
+    "claude-licence-manager.licence.switched"
+  ],
+  "state": [
+    "servers"
+  ],
+  "tools": [
+    "claude_code_status",
+    "claude_code_render",
+    "claude_code_pull",
+    "claude_code_mcp_list",
+    "claude_code_mcp_register",
+    "claude_code_mcp_unregister"
+  ],
+  "resources": [
+    {
+      "id": "package",
+      "type": "package",
+      "package": "claude-code"
+    },
+    {
+      "id": "managed",
+      "type": "directory",
+      "path": "/etc/claude-code",
+      "mode": "0755"
+    },
+    {
+      "id": "agent-home",
+      "type": "directory",
+      "path": "${machine:account-home}/.claude",
+      "mode": "0700",
+      "owner": "${machine:account}"
+    },
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "owner": "${machine:account}",
+      "place": "."
+    },
+    {
+      "id": "facts",
+      "type": "file",
+      "path": "${dir:state}/facts.json",
+      "mode": "0600",
+      "owner": "${machine:account}",
+      "content": "{\n  \"node\": \"${machine:name}\",\n  \"console\": \"http://127.0.0.1:${bound:mcp-endpoint:port}/mcp\"\n}\n"
+    },
+    {
+      "id": "settings",
+      "type": "file",
+      "path": "${dir:state}/settings.json",
+      "mode": "0600",
+      "owner": "${machine:account}",
+      "merge": "json",
+      "content": "{\n  \"role\": \"\",\n  \"mcp_servers\": {}\n}\n"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": [
+          "tools/index.js"
+        ],
+        "env": {
+          "MESH_CLAUDE_CODE_STATE": "${dir:state}",
+          "MESH_CLAUDE_CODE_FACTS": "${dir:state}/facts.json",
+          "MESH_CLAUDE_CODE_SETTINGS": "${dir:state}/settings.json"
+        }
+      }
+    ]
+  }
+}
@@ -0,0 +1,271 @@
+// What claude-code does on a node, written against two things it is handed — a way to ask a tool on the
+// bus and a way to emit an event — so every path is tested without a bus (novox/hq design 36 §4–§5,
+// ADR 0183, ADR 0198).
+//
+// **Over NATS, in two kinds** (design 32 §10): an event says that something happened and carries no
+// secret, because a stream keeps it; a token travels on a request, which nothing keeps. So:
+//   - the licence manager's `licence.rotated` and `licence.switched` events tell this module to ask the
+//     seat for its current token, sealed to the key it sends with the request;
+//   - a login a person made here — a refresh token this module never writes — is offered to the seat at
+//     once, sealed to the seat's key: the one moment a refresh token travels, because the login made the
+//     manager's stale;
+//   - an MCP server registered through this module is **state, not an event** (novox/hq ADR 0201): one
+//     key per server in the module's `servers` bucket — `all.<server>` for every node, `<node>.<server>`
+//     for one — which every node watches. A node that joins later, or was off, reads the whole current set
+//     at start; unregistering is a delete. A secret never goes in an entry: the runtime refuses one.
+
+import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { render, entryProblem, MANAGED_DIR, type Binding, type Facts, type Settings, type Servers } from "./render.js";
+import { generateKeyPair, open, seal, type SealedBox } from "./seal.js";
+import { decideApply, grantOf, holdsLogin, readCredentials, replacedBy, withGrant, writeCredentials, type Grant } from "./grant.js";
+import { readIdentity, writeIdentity, type Identity } from "./identity.js";
+
+export const SEAT = "anthropic-licence-manager";
+
+export interface Paths {
+  state: string;
+  facts: string;
+  settings: string;
+  home: string;
+  node: string;
+}
+
+/** A tool on the bus: its address and arguments in, its JSON answer out. */
+export type Ask = (address: string, args: Record<string, unknown>) => Promise<unknown>;
+/** An event of this module's, by its local name. */
+export type Emit = (type: string, body: unknown) => Promise<void>;
+/** Write one managed file; answers what happened. */
+export type WriteManaged = (name: string, content: string) => string;
+
+export const readJson = <T>(p: string, fallback: T): T => {
+  try {
+    return JSON.parse(readFileSync(p, "utf8")) as T;
+  } catch {
+    return fallback;
+  }
+};
+
+const credentialsPath = (p: Paths) => join(p.home, ".claude", ".credentials.json");
+const accountPath = (p: Paths) => join(p.home, ".claude.json");
+const bindingPath = (p: Paths) => join(p.state, "licence.json");
+const apiKeyPath = (p: Paths) => join(p.state, "api-key");
+export const helperPath = (p: Paths) => join(p.state, "api-key-helper");
+const keyPath = (p: Paths) => join(p.state, "key.pem");
+const pubPath = (p: Paths) => join(p.state, "key.pub.pem");
+const registryPath = (p: Paths) => join(p.state, "mcp-servers.json");
+
+export function keypair(p: Paths): { publicKey: string; privateKey: string } {
+  if (!existsSync(keyPath(p))) {
+    const k = generateKeyPair();
+    writeFileSync(keyPath(p), k.privateKey, { mode: 0o600 });
+    writeFileSync(pubPath(p), k.publicKey, { mode: 0o644 });
+  }
+  return { privateKey: readFileSync(keyPath(p), "utf8"), publicKey: readFileSync(pubPath(p), "utf8") };
+}
+
+export function registered(p: Paths): Servers {
+  return readJson<Servers>(registryPath(p), {});
+}
+
+export function renderNow(p: Paths, write: WriteManaged): string[] {
+  const facts = readJson<Facts | null>(p.facts, null);
+  if (!facts?.console) throw new Error(`the mesh has not rendered ${p.facts} yet; nothing to write`);
+  const files = render(facts, readJson<Settings>(p.settings, {}), readJson<Binding | null>(bindingPath(p), null),
+    helperPath(p), registered(p));
+  return Object.entries(files).map(([name, content]) => write(name, content));
+}
+
+// ---- the licence ----------------------------------------------------------------------------------
+
+/** What the seat answers to `current`: the licence this node is bound to and its token, sealed. */
+export interface Current {
+  licence: string;
+  kind: "subscription" | "api-key";
+  sealed: SealedBox;
+  identity?: Identity | null;
+}
+
+/** Ask the seat for this node's current token and apply it. */
+export async function pull(p: Paths, ask: Ask, write: WriteManaged): Promise<Record<string, unknown>> {
+  const answer = (await ask(`${SEAT}.current`, { node: p.node, public_key: keypair(p).publicKey })) as Current | null;
+  if (!answer?.sealed) return { applied: false, reason: "the seat holds no licence for this node" };
+  return apply(p, answer, write);
+}
+
+/** Apply what the seat handed over. A switch replaces the grant whole and cleans up after the old licence. */
+export function apply(p: Paths, handed: Current, write: WriteManaged): Record<string, unknown> {
+  const plain = open(handed.sealed, keypair(p).privateKey);
+  const previous = readJson<Binding | null>(bindingPath(p), null);
+  const switched = previous?.licence !== handed.licence;
+  let outcome: Record<string, unknown> = { applied: true, licence: handed.licence, kind: handed.kind, switched };
+  if (handed.kind === "api-key") {
+    writeFileSync(apiKeyPath(p), plain.trim() + "\n", { mode: 0o600 });
+    writeFileSync(helperPath(p), `#!/bin/sh\nexec cat '${apiKeyPath(p)}'\n`, { mode: 0o700 });
+    chmodSync(helperPath(p), 0o700);
+  } else {
+    const grant = JSON.parse(plain) as Grant;
+    const local = readCredentials(credentialsPath(p));
+    const d = decideApply(grantOf(local), grant, switched ? "switch" : "rotation");
+    if (d.apply) writeCredentials(credentialsPath(p), switched ? replacedBy(local, grant) : withGrant(local, grant));
+    else outcome = { applied: false, licence: handed.licence, reason: "reason" in d ? d.reason : undefined }; // narrowed by hand: the build compiles without strict
+    // Away from the API key: it goes, with its helper.
+    rmSync(apiKeyPath(p), { force: true });
+    rmSync(helperPath(p), { force: true });
+  }
+  if (switched && handed.identity?.accountUuid) {
+    outcome.account = writeIdentity(accountPath(p), handed.identity) ? "updated" : "unchanged";
+  }
+  writeFileSync(bindingPath(p), JSON.stringify({ licence: handed.licence, kind: handed.kind }) + "\n", { mode: 0o600 });
+  try {
+    outcome.rendered = renderNow(p, write); // the key-helper comes or goes with the licence's kind
+  } catch (err) {
+    outcome.rendered = { failed: err instanceof Error ? err.message : String(err) };
+  }
+  return outcome;
+}
+
+/** A licence event from the manager: is it for this node? */
+export function concerns(p: Paths, type: string, body: { licence?: string; node?: string }): boolean {
+  if (type.endsWith("licence.switched")) return body.node === p.node;
+  if (type.endsWith("licence.rotated")) return body.licence === readJson<Binding | null>(bindingPath(p), null)?.licence;
+  return false;
+}
+
+/** A refresh token in the credentials file is a login: this module never writes one. Offer it to the seat. */
+export async function offerLogin(p: Paths, ask: Ask): Promise<Record<string, unknown> | null> {
+  const creds = readCredentials(credentialsPath(p));
+  if (!holdsLogin(creds)) return null;
+  const key = (await ask(`${SEAT}.public_key`, {})) as { public_key?: string } | null;
+  if (!key?.public_key) throw new Error("the licence manager did not say what key to seal a login to");
+  return (await ask(`${SEAT}.adopt`, {
+    node: p.node,
+    identity: readIdentity(accountPath(p)),
+    sealed: seal(JSON.stringify(creds!.claudeAiOauth), key.public_key),
+  })) as Record<string, unknown>;
+}
+
+// ---- MCP servers ----------------------------------------------------------------------------------
+
+export interface Registration {
+  name: string;
+  entry?: Record<string, unknown>;
+  /** Which nodes: this one (absent), every node running the module ("all"), or a list. */
+  nodes?: "all" | string[];
+}
+
+/** The `servers` state, as this module reaches it through the runtime (`state("servers")` in the SDK). */
+export interface ServerState {
+  put(key: string, value: Record<string, unknown>): Promise<number>;
+  delete(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+}
+
+/** One change to the `servers` state, as a watch hands it over. */
+export interface ServerChange {
+  key: string;
+  op: "put" | "delete";
+  value?: Record<string, unknown>;
+}
+
+/** The key a registration lives at: `all.<server>` for every node, `<node>.<server>` for one. */
+export const keyOf = (scope: string, name: string) => `${scope}.${name}`;
+
+/**
+ * What this node takes from the `servers` state: the entries for every node and for this one, by key —
+ * kept in memory from the watch, and written through to the module's own file whenever what applies here
+ * changes, so the managed directory can be rendered without the bus.
+ */
+export class ServerView {
+  private readonly entries = new Map<string, Record<string, unknown>>();
+  constructor(private readonly p: Paths) {}
+
+  /** Take one change; answers whether what applies to this node changed. */
+  take(c: ServerChange): boolean {
+    const dot = c.key.indexOf(".");
+    const scope = c.key.slice(0, dot), name = c.key.slice(dot + 1);
+    if (dot <= 0 || (scope !== "all" && scope !== this.p.node)) return false;
+    if (c.op === "put" && c.value && entryProblem(name, c.value) === null) this.entries.set(c.key, c.value);
+    else this.entries.delete(c.key);
+    return this.writeThrough();
+  }
+
+  /** What applies here: every node's entries, with this node's own laid over them by server name. */
+  effective(): Servers {
+    const out: Record<string, Record<string, unknown>> = {};
+    for (const scope of ["all", this.p.node]) {
+      for (const [key, entry] of [...this.entries].sort(([a], [b]) => a.localeCompare(b))) {
+        if (key.startsWith(scope + ".")) out[key.slice(scope.length + 1)] = entry;
+      }
+    }
+    return out;
+  }
+
+  private writeThrough(): boolean {
+    const now = JSON.stringify(this.effective(), null, 2) + "\n";
+    let before = "";
+    try {
+      before = readFileSync(registryPath(this.p), "utf8");
+    } catch {
+      /* none yet */
+    }
+    if (now === before) return false;
+    writeFileSync(registryPath(this.p), now, { mode: 0o600 });
+    return true;
+  }
+}
+
+/** A change from the watch: take it, and render when what applies here changed. */
+export function onServerChange(view: ServerView, c: ServerChange, p: Paths, write: WriteManaged): string | null {
+  if (!view.take(c)) return null;
+  renderNow(p, write);
+  return `${c.op === "put" ? "registered" : "unregistered"} ${c.key}`;
+}
+
+const scopesOf = (p: Paths, nodes: Registration["nodes"]): string[] =>
+  nodes === undefined ? [p.node] : nodes === "all" ? ["all"] : nodes;
+
+/**
+ * Register (or with no entry, unregister) a server: a put (or delete) per scope in the `servers` state.
+ * Taken into this node's view at once, so the answer says what it did here; every other node takes it
+ * from its watch, and a node that joins later from the current state.
+ */
+export async function registerServer(p: Paths, r: Registration, servers: ServerState, view: ServerView,
+                                     write: WriteManaged, others: () => Promise<string[]>): Promise<Record<string, unknown>> {
+  if (r.entry) {
+    const problem = entryProblem(r.name, r.entry);
+    if (problem) return { registered: false, reason: problem };
+  }
+  const scopes = scopesOf(p, r.nodes);
+  // Compared before and after rather than read from take(): this node's own watch may hand the view the
+  // same change first, and then take() here finds nothing new although this call made it.
+  const before = JSON.stringify(view.effective());
+  for (const scope of scopes) {
+    const key = keyOf(scope, r.name);
+    if (r.entry) await servers.put(key, r.entry);
+    else await servers.delete(key);
+    view.take({ key, op: r.entry ? "put" : "delete", value: r.entry });
+  }
+  const changedHere = JSON.stringify(view.effective()) !== before;
+  const here = scopes.includes("all") || scopes.includes(p.node);
+  const answer: Record<string, unknown> = {
+    [r.entry ? "registered" : "unregistered"]: r.name,
+    on: r.nodes === undefined ? [p.node] : r.nodes,
+    here: here ? (changedHere ? "changed" : "already so") : "not this node",
+    rendered: changedHere ? renderNow(p, write) : [],
+  };
+  if (!r.entry && view.effective()[r.name]) {
+    answer.still = `${r.name} still applies here from another registration (for every node, or for this one); unregister that too`;
+  }
+  if (r.nodes === undefined) {
+    // The question the operator wanted asked: here only, or more?
+    const elsewhere = (await others().catch(() => [] as string[])).filter((n) => n !== p.node);
+    answer.also = elsewhere.length
+      ? `claude-code also runs on ${elsewhere.join(", ")}. To ${r.entry ? "register" : "unregister"} it there too, call again with nodes: "all" or a list of those nodes.`
+      : `To do the same on every node running claude-code, call again with nodes: "all".`;
+  }
+  return answer;
+}
+
+export { MANAGED_DIR };
@@ -0,0 +1,18 @@
+{
+  "name": "@novox/module-claude-code",
+  "version": "0.1.0",
+  "description": "claude-code — the operator's agent on a machine: its managed configuration, and the consumer side of the Anthropic licence manager (novox/hq design 36).",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "tsc seal.ts grant.ts identity.ts render.ts node.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --rootDir . --outDir dist",
+    "test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
+  },
+  "dependencies": {
+    "@novox/mesh-sdk": "^0.1.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}
@@ -0,0 +1,135 @@
+// What the module writes into the agent's machine-wide managed directory (novox/hq design 36 §1–§4).
+// Pure: composed from the facts the mesh rendered, the settings the operator set and the licence the
+// node holds, so what lands under /etc is tested without a machine.
+//
+// Three files, owned whole by this module:
+//   managed-mcp.json        the tool servers every session loads: the mesh's console as `mesh`, and the
+//                           servers the operator declared for the mesh or this node. Exclusive by the
+//                           vendor's rule — a server not listed here does not load — which is why the
+//                           list is the module's settings and nothing else (operator's choice, 2026-10-03).
+//   managed-settings.json   the mesh's keys only: the repositories' attribution convention, the
+//                           claude.ai connectors kept beside the managed servers, and — for an API-key
+//                           licence only — the key-helper. A person's preferences are theirs.
+//   CLAUDE.md               how a session on this mesh works, who this node is, the conventions.
+
+export const MANAGED_DIR = "/etc/claude-code";
+
+export interface Facts {
+  readonly node: string;
+  readonly console: string;
+}
+
+export interface Settings {
+  readonly role?: string;
+  /** Extra tool servers, in the vendor's `.mcp.json` entry shape, keyed by name. */
+  readonly mcp_servers?: Readonly<Record<string, Record<string, unknown>>>;
+}
+
+export interface Binding {
+  readonly licence: string;
+  readonly kind: "subscription" | "api-key";
+}
+
+export interface Rendered {
+  readonly [file: string]: string;
+}
+
+const MESH_ENTRY = "mesh";
+
+export type Servers = Readonly<Record<string, Record<string, unknown>>>;
+
+/** Whether an entry is one the vendor's managed file takes: a name of letters, digits, `-` and `_`, and
+ *  an http/sse server with a url or a stdio server with a command. Returns why not, or null. */
+export function entryProblem(name: string, entry: Record<string, unknown>): string | null {
+  if (!/^[A-Za-z0-9_-]+$/.test(name)) return `"${name}" is not a name the agent takes: letters, digits, - and _`;
+  if (name === MESH_ENTRY) return `"${MESH_ENTRY}" is the mesh's own entry`;
+  const type = entry?.type ?? "stdio";
+  if (type === "http" || type === "sse" || type === "streamable-http") {
+    return typeof entry.url === "string" && entry.url ? null : `an ${type} server needs a url`;
+  }
+  if (type === "stdio") return typeof entry.command === "string" && entry.command ? null : "a stdio server needs a command";
+  return `"${String(type)}" is not a server type the agent knows (http, sse, stdio)`;
+}
+
+/**
+ * Compose the three files. `registered` is the module's own list on this node — what was registered
+ * through its tools — laid over the servers the operator set in its settings.
+ */
+export function render(facts: Facts, settings: Settings, binding: Binding | null, helperPath: string,
+                       registered: Servers = {}): Rendered {
+  const servers: Record<string, unknown> = {};
+  for (const [name, entry] of Object.entries({ ...(settings.mcp_servers ?? {}), ...registered })) {
+    if (entryProblem(name, entry) !== null) continue; // the mesh's own entry, or one the agent would refuse
+    servers[name] = entry;
+  }
+  servers[MESH_ENTRY] = { type: "http", url: facts.console };
+
+  const managed: Record<string, unknown> = {
+    attribution: { commit: "", pr: "" },
+    allowAllClaudeAiMcps: true,
+  };
+  if (binding?.kind === "api-key") managed.apiKeyHelper = helperPath;
+
+  return {
+    "managed-mcp.json": json({ mcpServers: sortKeys(servers) }),
+    "managed-settings.json": json(managed),
+    "CLAUDE.md": instructions(facts, settings),
+  };
+}
+
+function json(v: unknown): string {
+  return JSON.stringify(v, null, 2) + "\n";
+}
+
+function sortKeys(o: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.keys(o).sort().map((k) => [k, o[k]]));
+}
+
+export function instructions(facts: Facts, settings: Settings): string {
+  const role = settings.role?.trim() ? settings.role.trim() : "not stated — set it in this module's settings for the node";
+  return `# This machine is a node of a Novox mesh
+
+Written by the mesh's \`claude-code\` module. Edit the module's settings or the catalogue, never this file:
+it is rewritten whenever the module renders.
+
+## Who this node is
+
+- **Node:** \`${facts.node}\`
+- **Role:** ${role}
+- The other nodes, their roles and what runs where: ask the controller (\`mesh-controller.nodes\`,
+  \`mesh-controller.node\`). Nothing here lists them, because a copy drifts.
+
+## How a session on this mesh works
+
+The console is the only way to the mesh: the MCP server named \`mesh\`. It offers five tools, and
+everything else is an address you find and call through them:
+
+- \`mesh_search\` — words in, matching addresses out. \`mesh_describe\` — one address's arguments.
+- \`mesh_call\` — call an address. A seat the mesh holds once is \`<seat>.<verb>\` (the mesh's own verbs
+  are \`mesh-controller.<verb>\`: \`status\`, \`plan\`, \`node\`, \`assign\`, \`push\`, \`settings\`);
+  a module on a machine is \`<node>/<module>.<tool>\`.
+- \`mesh_overview\` and \`mesh_machine\` — the mesh's seats and machines, and what one machine runs.
+
+- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the
+  literal text before forming a hypothesis: the records module's \`records_search\`, then
+  \`records_read\`.
+- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.
+- **A licence** through the \`anthropic-licence-manager\` seat's verbs. Never edit the agent's credentials
+  file by hand, never print or ask for a token.
+
+## Hard rules
+
+- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If
+  unsure, \`mesh-controller.plan\` for the node says what the mesh writes there.
+- Never write to a store's database by hand; schema changes are numbered migrations.
+- Never push to a main branch: a branch, a pull request, and a human approval for every merge.
+- The mesh creates no symlinks, and nobody else does either.
+- A package is declared in a module, never installed by hand.
+
+## Conventions
+
+- Commit messages are concise, in the imperative, about why.
+- Test before pushing: nodes update unattended.
+- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.
+`;
+}
@@ -0,0 +1,77 @@
+// Sealing a token to one recipient (novox/hq ADR 0183): the manager seals what it hands a node to that
+// node's agent module key, and a node seals a waiting login to the key the manager names. X25519 for
+// the agreement, HKDF-SHA256 for the key, AES-256-GCM for the box — all from Node's own library, so a
+// bundle carries no dependency and no secret ever crosses the bus in the clear.
+//
+// A sealed box is `{ v: 1, eph, iv, tag, ct }`, every field base64. `eph` is a one-time public key, so
+// two boxes of one value to one recipient share nothing, and only the recipient's private key opens it.
+
+import {
+  createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman,
+  generateKeyPairSync, hkdfSync, randomBytes, type KeyObject,
+} from "node:crypto";
+
+export interface SealedBox {
+  readonly v: 1;
+  readonly eph: string;
+  readonly iv: string;
+  readonly tag: string;
+  readonly ct: string;
+}
+
+/** A recipient's keypair, as the two PEM strings it is kept and published as. */
+export interface KeyPairPem {
+  readonly publicKey: string;
+  readonly privateKey: string;
+}
+
+const INFO = Buffer.from("novox-mesh sealed box v1");
+
+export function generateKeyPair(): KeyPairPem {
+  const { publicKey, privateKey } = generateKeyPairSync("x25519");
+  return {
+    publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
+    privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+  };
+}
+
+function keyFor(secret: Buffer, eph: Buffer, recipient: Buffer): Buffer {
+  // The ephemeral and the recipient's public halves are bound into the key, so a box cannot be
+  // re-addressed to another recipient by swapping its `eph`.
+  return Buffer.from(hkdfSync("sha256", secret, Buffer.concat([eph, recipient]), INFO, 32));
+}
+
+function rawPublic(key: KeyObject): Buffer {
+  return key.export({ type: "spki", format: "der" }).subarray(-32);
+}
+
+export function seal(plaintext: string, recipientPublicPem: string): SealedBox {
+  const recipient = createPublicKey(recipientPublicPem);
+  const eph = generateKeyPairSync("x25519");
+  const secret = diffieHellman({ privateKey: eph.privateKey, publicKey: recipient });
+  const ephRaw = eph.publicKey.export({ type: "spki", format: "der" });
+  const key = keyFor(secret, ephRaw, rawPublic(recipient));
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  return {
+    v: 1,
+    eph: ephRaw.toString("base64"),
+    iv: iv.toString("base64"),
+    tag: cipher.getAuthTag().toString("base64"),
+    ct: ct.toString("base64"),
+  };
+}
+
+/** Open a box with the recipient's private key. Throws on a box for another key or one tampered with. */
+export function open(box: SealedBox, privateKeyPem: string): string {
+  if (!box || box.v !== 1) throw new Error("not a sealed box this module can open");
+  const priv = createPrivateKey(privateKeyPem);
+  const ephRaw = Buffer.from(box.eph, "base64");
+  const eph = createPublicKey({ key: ephRaw, format: "der", type: "spki" });
+  const secret = diffieHellman({ privateKey: priv, publicKey: eph });
+  const key = keyFor(secret, ephRaw, rawPublic(createPublicKey(priv)));
+  const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(box.iv, "base64"));
+  decipher.setAuthTag(Buffer.from(box.tag, "base64"));
+  return Buffer.concat([decipher.update(Buffer.from(box.ct, "base64")), decipher.final()]).toString("utf8");
+}
@@ -0,0 +1,54 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  decideApply, grantOf, holdsLogin, readCredentials, withGrant, writeCredentials, type Grant,
+} from "../dist/grant.js";
+
+const NOW = 1_700_000_000_000;
+const HOUR = 3_600_000;
+const g = (over: Partial<Grant> = {}): Grant => ({
+  accessToken: "tok-A", expiresAt: NOW + HOUR, refreshTokenExpiresAt: NOW + 30 * 24 * HOUR, ...over,
+});
+
+test("a rotation applies a newer grant of the same licence", () => {
+  assert.deepEqual(decideApply(g(), g({ accessToken: "tok-B", expiresAt: NOW + 2 * HOUR }), "rotation"), { apply: true });
+});
+
+test("a rotation refuses a grant that arrived late and is older", () => {
+  const d = decideApply(g({ accessToken: "new", expiresAt: NOW + 2 * HOUR }), g({ accessToken: "old" }), "rotation");
+  assert.equal(d.apply === false && d.reason, "not-newer");
+});
+
+test("a grant re-issued by a login is adopted even though it expires sooner (2026-09-05)", () => {
+  const local = g({ expiresAt: NOW + 8 * HOUR, refreshTokenExpiresAt: NOW + 30 * 24 * HOUR });
+  const offered = g({ accessToken: "reissued", expiresAt: NOW + HOUR, refreshTokenExpiresAt: NOW + 5 * 24 * HOUR });
+  assert.deepEqual(decideApply(local, offered, "rotation"), { apply: true, reissued: true });
+});
+
+test("a switch to another licence applies whatever the expiries say", () => {
+  const local = g({ expiresAt: NOW + 8 * HOUR });
+  assert.equal(decideApply(local, g({ accessToken: "other", expiresAt: NOW + HOUR }), "switch").apply, true);
+});
+
+test("the same token is not rewritten", () => {
+  assert.deepEqual(decideApply(g(), g(), "switch"), { apply: false, reason: "already-current" });
+});
+
+test("a full grant left by a login is seen as a login, and stripped when the node's own is written", () => {
+  const dir = mkdtempSync(join(tmpdir(), "claude-code-"));
+  const path = join(dir, ".claude", ".credentials.json");
+  writeFileSync(join(dir, "x"), "");
+  const login = { claudeAiOauth: { accessToken: "at-login", refreshToken: "rt-login", expiresAt: NOW }, other: 1 };
+  assert.equal(holdsLogin(login), true);
+  writeCredentials(path, withGrant(login, g({ accessToken: "at-mesh", scopes: ["user:inference"] })));
+  const back = readCredentials(path)!;
+  assert.equal(holdsLogin(back), false);
+  assert.equal(grantOf(back)!.accessToken, "at-mesh");
+  assert.deepEqual(back.claudeAiOauth!.scopes, ["user:inference"]);
+  assert.equal(back.other, 1, "a key the module does not know was lost");
+  assert.ok(!readFileSync(path, "utf8").includes("rt-login"));
+  assert.equal(statSync(path).mode & 0o777, 0o600);
+});
@@ -0,0 +1,19 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readIdentity } from "../dist/identity.js";
+
+test("the account is read from the agent's state file", () => {
+  const p = join(mkdtempSync(join(tmpdir(), "cc-id-")), ".claude.json");
+  writeFileSync(p, JSON.stringify({ oauthAccount: { accountUuid: "u-1", emailAddress: "a@example.org" }, other: 2 }));
+  assert.deepEqual(readIdentity(p), { accountUuid: "u-1", emailAddress: "a@example.org", organizationUuid: undefined });
+});
+
+test("no state file, or no account in it, is no identity rather than a guess", () => {
+  assert.equal(readIdentity("/nonexistent/.claude.json"), null);
+  const p = join(mkdtempSync(join(tmpdir(), "cc-id-")), ".claude.json");
+  writeFileSync(p, "{}");
+  assert.equal(readIdentity(p), null);
+});
@@ -0,0 +1,173 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  apply, concerns, keypair, offerLogin, onServerChange, pull, registerServer, registered, ServerView, type Paths,
+  type ServerChange, type ServerState,
+} from "../dist/node.js";
+import { generateKeyPair, open, seal } from "../dist/seal.js";
+
+const NOW = Date.now();
+function node(name = "laptop"): { p: Paths; written: Record<string, string> } {
+  const root = mkdtempSync(join(tmpdir(), "cc-node-"));
+  const p = { state: join(root, "state"), facts: join(root, "state", "facts.json"), settings: join(root, "state", "settings.json"), home: join(root, "home"), node: name };
+  mkdirSync(p.state, { recursive: true });
+  mkdirSync(join(p.home, ".claude"), { recursive: true });
+  writeFileSync(p.facts, JSON.stringify({ node: name, console: "http://127.0.0.1:4270/mcp" }));
+  writeFileSync(p.settings, JSON.stringify({ role: "", mcp_servers: {} }));
+  return { p, written: {} };
+}
+const writer = (w: Record<string, string>) => (name: string, content: string) => { w[name] = content; return `${name}: written`; };
+const creds = (p: Paths) => JSON.parse(readFileSync(join(p.home, ".claude", ".credentials.json"), "utf8"));
+const grantFor = (p: Paths, licence: string, token: string, kind: "subscription" | "api-key" = "subscription", identity?: object) => ({
+  licence, kind, identity,
+  sealed: seal(kind === "api-key" ? token : JSON.stringify({ accessToken: token, expiresAt: NOW + 3_600_000, refreshTokenExpiresAt: NOW + 86_400_000, subscriptionType: licence }), keypair(p).publicKey),
+});
+
+test("a pull asks the seat with this node's key and applies what it answers", async () => {
+  const { p, written } = node();
+  let asked: [string, Record<string, unknown>] | null = null;
+  const r = await pull(p, async (address, args) => { asked = [address, args]; return grantFor(p, "personal", "at-1"); }, writer(written));
+  assert.equal(asked![0], "anthropic-licence-manager.current");
+  assert.equal(asked![1].node, "laptop");
+  assert.match(String(asked![1].public_key), /BEGIN PUBLIC KEY/);
+  assert.equal(r.applied, true);
+  assert.equal(creds(p).claudeAiOauth.accessToken, "at-1");
+  assert.ok(written["managed-mcp.json"]);
+});
+
+test("a switch replaces the old licence's grant whole and points the account at the new one", () => {
+  const { p, written } = node();
+  writeFileSync(join(p.home, ".claude.json"), JSON.stringify({ oauthAccount: { accountUuid: "old" }, projects: { keep: 1 } }));
+  apply(p, grantFor(p, "personal", "at-1"), writer(written));
+  const r = apply(p, grantFor(p, "work", "at-2", "subscription", { accountUuid: "new", emailAddress: "w@example.org" }), writer(written));
+  assert.equal(r.switched, true);
+  assert.equal(creds(p).claudeAiOauth.accessToken, "at-2");
+  assert.equal(creds(p).claudeAiOauth.subscriptionType, "work", "the old licence's subscription type survived the switch");
+  const account = JSON.parse(readFileSync(join(p.home, ".claude.json"), "utf8"));
+  assert.equal(account.oauthAccount.accountUuid, "new");
+  assert.deepEqual(account.projects, { keep: 1 });
+});
+
+test("switching to the API key adds the key-helper; switching away removes the key and the helper", () => {
+  const { p, written } = node();
+  apply(p, grantFor(p, "api", "sk-key", "api-key"), writer(written));
+  assert.ok(JSON.parse(written["managed-settings.json"]).apiKeyHelper);
+  assert.ok(existsSync(join(p.state, "api-key")));
+  apply(p, grantFor(p, "personal", "at-1"), writer(written));
+  assert.ok(!("apiKeyHelper" in JSON.parse(written["managed-settings.json"])));
+  assert.ok(!existsSync(join(p.state, "api-key")) && !existsSync(join(p.state, "api-key-helper")));
+});
+
+test("a rotation event concerns the node bound to that licence; a switch event the node it names", () => {
+  const { p, written } = node();
+  apply(p, grantFor(p, "personal", "at-1"), writer(written));
+  assert.equal(concerns(p, "claude-licence-manager.licence.rotated", { licence: "personal" }), true);
+  assert.equal(concerns(p, "claude-licence-manager.licence.rotated", { licence: "work" }), false);
+  assert.equal(concerns(p, "claude-licence-manager.licence.switched", { node: "laptop", licence: "work" }), true);
+  assert.equal(concerns(p, "claude-licence-manager.licence.switched", { node: "server" }), false);
+});
+
+test("a login is offered to the seat sealed to the seat's key, with the account it belongs to", async () => {
+  const { p } = node();
+  const manager = generateKeyPair();
+  writeFileSync(join(p.home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "at-login", refreshToken: "rt-login", expiresAt: NOW } }));
+  writeFileSync(join(p.home, ".claude.json"), JSON.stringify({ oauthAccount: { accountUuid: "u-9" } }));
+  const calls: [string, Record<string, unknown>][] = [];
+  await offerLogin(p, async (address, args) => { calls.push([address, args]); return address.endsWith("public_key") ? { public_key: manager.publicKey } : { adopted: true }; });
+  assert.deepEqual(calls.map((c) => c[0]), ["anthropic-licence-manager.public_key", "anthropic-licence-manager.adopt"]);
+  const adopt = calls[1][1] as { identity: { accountUuid: string }; sealed: never };
+  assert.equal(adopt.identity.accountUuid, "u-9");
+  assert.equal(JSON.parse(open(adopt.sealed, manager.privateKey)).refreshToken, "rt-login");
+  assert.ok(!JSON.stringify(adopt).includes("rt-login"), "the refresh token crossed in the clear");
+});
+
+test("no refresh token in the file is no login, and nothing is asked", async () => {
+  const { p } = node();
+  writeFileSync(join(p.home, ".claude", ".credentials.json"), JSON.stringify({ claudeAiOauth: { accessToken: "at", expiresAt: NOW } }));
+  assert.equal(await offerLogin(p, async () => { throw new Error("asked"); }), null);
+});
+
+/** The `servers` state as the bus holds it, shared by every node in a test, with each node's watch. */
+function bus() {
+  const kept = new Map<string, Record<string, unknown>>();
+  const watchers: ((c: ServerChange) => void)[] = [];
+  const state: ServerState = {
+    put: async (key, value) => { kept.set(key, value); watchers.forEach((w) => w({ key, op: "put", value })); return kept.size; },
+    delete: async (key) => { kept.delete(key); watchers.forEach((w) => w({ key, op: "delete" })); },
+    keys: async () => [...kept.keys()].sort(),
+  };
+  /** A node joining: its view takes the current state, then every change. */
+  const join = (n: { p: Paths; written: Record<string, string> }) => {
+    const view = new ServerView(n.p);
+    for (const [key, value] of kept) onServerChange(view, { key, op: "put", value }, n.p, writer(n.written));
+    watchers.push((c) => onServerChange(view, c, n.p, writer(n.written)));
+    return view;
+  };
+  return { state, join, kept };
+}
+
+test("registering a server here puts it under this node's key, renders it, and asks about the other nodes", async () => {
+  const n = node();
+  const b = bus();
+  const view = b.join(n);
+  const r = await registerServer(n.p, { name: "search", entry: { type: "http", url: "https://s.example/mcp" } },
+    b.state, view, writer(n.written), async () => ["laptop", "server", "desktop"]);
+  assert.equal(r.here, "changed");
+  assert.match(String(r.also), /server, desktop/);
+  assert.deepEqual([...b.kept.keys()], ["laptop.search"]);
+  assert.ok(JSON.parse(n.written["managed-mcp.json"]).mcpServers.search);
+});
+
+test("registering for every node reaches the others through their watch, and a node joining later reads it", async () => {
+  const a = node("laptop"), s = node("server");
+  const b = bus();
+  const va = b.join(a);
+  b.join(s);
+  await registerServer(a.p, { name: "docs", entry: { type: "stdio", command: "docs-mcp" }, nodes: "all" },
+    b.state, va, writer(a.written), async () => []);
+  assert.deepEqual([...b.kept.keys()], ["all.docs"]);
+  assert.deepEqual(registered(s.p).docs, { type: "stdio", command: "docs-mcp" });
+  assert.ok(JSON.parse(s.written["managed-mcp.json"]).mcpServers.docs);
+  // The gap events left: a node assigned after the registration takes the whole current set at start.
+  const late = node("desktop");
+  b.join(late);
+  assert.deepEqual(registered(late.p).docs, { type: "stdio", command: "docs-mcp" });
+  // Unregistering is a delete, and every node's view drops it.
+  await registerServer(a.p, { name: "docs", nodes: "all" }, b.state, va, writer(a.written), async () => []);
+  assert.equal(registered(s.p).docs, undefined);
+  assert.equal(registered(late.p).docs, undefined);
+});
+
+test("a node's own registration overrides the one for every node; other nodes' keys leave this one alone", async () => {
+  const a = node("laptop"), s = node("server");
+  const b = bus();
+  const va = b.join(a);
+  const vs = b.join(s);
+  await registerServer(a.p, { name: "x", entry: { type: "http", url: "https://all" }, nodes: "all" }, b.state, va, writer(a.written), async () => []);
+  await registerServer(a.p, { name: "x", entry: { type: "http", url: "https://laptop" } }, b.state, va, writer(a.written), async () => []);
+  assert.equal(registered(a.p).x.url, "https://laptop");
+  assert.equal(registered(s.p).x.url, "https://all");
+  await registerServer(a.p, { name: "only", entry: { type: "http", url: "https://o" }, nodes: ["server"] }, b.state, va, writer(a.written), async () => []);
+  assert.equal(registered(a.p).only, undefined);
+  assert.equal(registered(s.p).only.url, "https://o");
+  // Unregistering here leaves the every-node one applying, and says so.
+  const r = await registerServer(a.p, { name: "x" }, b.state, va, writer(a.written), async () => []);
+  assert.match(String(r.still), /still applies here/);
+  assert.equal(registered(a.p).x.url, "https://all");
+  assert.equal(vs.effective().x.url, "https://all");
+});
+
+test("a bad entry is refused before anything is put; a repeated change changes nothing", async () => {
+  const n = node();
+  const b = bus();
+  const view = b.join(n);
+  const r = await registerServer(n.p, { name: "mesh", entry: { type: "http", url: "https://x" } }, b.state, view, writer(n.written), async () => []);
+  assert.equal(r.registered, false);
+  assert.equal(b.kept.size, 0);
+  assert.equal(onServerChange(view, { key: "all.a", op: "put", value: { type: "http", url: "https://a" } }, n.p, writer(n.written)), "registered all.a");
+  assert.equal(onServerChange(view, { key: "all.a", op: "put", value: { type: "http", url: "https://a" } }, n.p, writer(n.written)), null);
+  assert.equal(onServerChange(view, { key: "server.b", op: "put", value: { type: "http", url: "https://b" } }, n.p, writer(n.written)), null);
+});
@@ -0,0 +1,40 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { render } from "../dist/render.js";
+
+const facts = { node: "workstation", console: "http://127.0.0.1:4270/mcp" };
+
+test("the console is the `mesh` server, and an operator's servers are listed beside it", () => {
+  const out = render(facts, { mcp_servers: { search: { type: "http", url: "https://s.example/mcp" } } }, null, "/h");
+  const mcp = JSON.parse(out["managed-mcp.json"]);
+  assert.deepEqual(Object.keys(mcp.mcpServers), ["mesh", "search"]);
+  assert.deepEqual(mcp.mcpServers.mesh, { type: "http", url: facts.console });
+});
+
+test("a setting cannot replace the mesh's own entry, and a name the vendor refuses is left out", () => {
+  const out = render(facts, { mcp_servers: { mesh: { type: "http", url: "http://evil" }, "bad name": {} } }, null, "/h");
+  const mcp = JSON.parse(out["managed-mcp.json"]);
+  assert.equal(mcp.mcpServers.mesh.url, facts.console);
+  assert.ok(!("bad name" in mcp.mcpServers));
+});
+
+test("managed settings carry the mesh's keys only, and the key-helper only for an API-key licence", () => {
+  const sub = JSON.parse(render(facts, {}, { licence: "personal", kind: "subscription" }, "/h")["managed-settings.json"]);
+  assert.deepEqual(sub, { attribution: { commit: "", pr: "" }, allowAllClaudeAiMcps: true });
+  const key = JSON.parse(render(facts, {}, { licence: "api", kind: "api-key" }, "/state/api-key-helper")["managed-settings.json"]);
+  assert.equal(key.apiKeyHelper, "/state/api-key-helper");
+  assert.ok(!("model" in key), "a preference is the person's");
+});
+
+test("the instruction file names the node and its role, and no other node", () => {
+  const md = render(facts, { role: "the laptop" }, null, "/h")["CLAUDE.md"];
+  assert.match(md, /\*\*Node:\*\* `workstation`/);
+  assert.match(md, /\*\*Role:\*\* the laptop/);
+  assert.match(md, /mesh_call/);
+  assert.match(md, /records_search/);
+});
+
+test("rendering is deterministic, so an unchanged input writes nothing", () => {
+  const s = { mcp_servers: { b: { type: "http", url: "https://b" }, a: { type: "http", url: "https://a" } } };
+  assert.deepEqual(render(facts, s, null, "/h"), render(facts, s, null, "/h"));
+});
@@ -0,0 +1,31 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPair, open, seal } from "../dist/seal.js";
+
+test("a box opens with its recipient's key and yields the value", () => {
+  const k = generateKeyPair();
+  assert.equal(open(seal("at-secret", k.publicKey), k.privateKey), "at-secret");
+});
+
+test("a box sealed for one node does not open with another node's key", () => {
+  const a = generateKeyPair();
+  const b = generateKeyPair();
+  assert.throws(() => open(seal("at-secret", a.publicKey), b.privateKey));
+});
+
+test("a tampered box is refused, not opened to garbage", () => {
+  const k = generateKeyPair();
+  const box = seal("at-secret", k.publicKey);
+  const ct = Buffer.from(box.ct, "base64");
+  ct[0] ^= 0xff;
+  assert.throws(() => open({ ...box, ct: ct.toString("base64") }, k.privateKey));
+});
+
+test("two boxes of one value share nothing a reader could compare", () => {
+  const k = generateKeyPair();
+  const x = seal("at-secret", k.publicKey);
+  const y = seal("at-secret", k.publicKey);
+  assert.notEqual(x.ct, y.ct);
+  assert.notEqual(x.eph, y.eph);
+  assert.ok(!JSON.stringify(x).includes("at-secret"));
+});
@@ -0,0 +1,224 @@
+// claude-code's bundle (novox/hq design 36, ADR 0183). The node's runtime launches it over stdio, as the
+// operator account (ADR 0193), and is its bus (ADR 0198): it asks tools, emits and consumes through the
+// runtime. It is given its state directory and two files the mesh renders into it (ADR 0192), beside the
+// runtime's own words. **stdout is the MCP channel**: everything this module says, it says on stderr.
+//
+// At start it renders the agent's managed directory, asks the licence manager for this node's token,
+// begins watching the credentials file for a login, takes the manager's licence events, and watches the
+// module's `servers` state — every node's MCP server registrations (novox/hq ADR 0201). node.ts holds the
+// logic.
+
+import { mkdtempSync, readFileSync, rmSync, watchFile, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
+import { broker } from "@novox/mesh-sdk/messaging";
+import { on } from "@novox/mesh-sdk/events";
+import { state } from "@novox/mesh-sdk/state";
+
+import {
+  MANAGED_DIR, SEAT, ServerView, concerns, keypair, offerLogin, onServerChange, pull, readJson, registerServer,
+  registered, renderNow, type Ask, type Paths, type Registration, type ServerChange, type ServerState, type WriteManaged,
+} from "../node.js";
+import { grantOf, holdsLogin, readCredentials } from "../grant.js";
+import { createHash } from "node:crypto";
+
+const say = (line: string) => console.error(`[claude-code] ${line}`);
+const fingerprint = (s: string) => "sha256:" + createHash("sha256").update(s).digest("hex").slice(0, 16);
+
+function pathsFrom(env: NodeJS.ProcessEnv): Paths | null {
+  const state = env.MESH_CLAUDE_CODE_STATE, facts = env.MESH_CLAUDE_CODE_FACTS;
+  const settings = env.MESH_CLAUDE_CODE_SETTINGS, home = env.MESH_OPERATOR_HOME, node = env.MESH_NODE;
+  if (!state || !facts || !settings || !home || !node) return null;
+  return { state, facts, settings, home, node };
+}
+
+/** Write one managed file as root, only when its content changed. */
+const writeManaged: WriteManaged = (name, content) => {
+  const path = join(MANAGED_DIR, name);
+  try {
+    if (readFileSync(path, "utf8") === content) return `${name}: unchanged`;
+  } catch {
+    /* absent */
+  }
+  // From a file, never /dev/stdin: Node hands a child its input over a socket, which /dev/stdin cannot
+  // open (ENXIO) — found on the first assignment, where nothing under /etc/claude-code was ever written.
+  const staged = mkdtempSync(join(tmpdir(), "claude-code-"));
+  const source = join(staged, name);
+  writeFileSync(source, content, { mode: 0o644 });
+  const asRoot = process.getuid?.() === 0;
+  const cmd = asRoot ? ["install", "-D", "-m", "0644", source, path] : ["sudo", "-n", "install", "-D", "-m", "0644", source, path];
+  const r = spawnSync(cmd[0], cmd.slice(1), { encoding: "utf8" });
+  rmSync(staged, { recursive: true, force: true });
+  if (r.status !== 0) {
+    throw new Error(`${name}: could not be written to ${MANAGED_DIR} (${(r.stderr || r.error?.message || "").trim()}); ` +
+      `the module writes there through the operator account's passwordless sudo`);
+  }
+  return `${name}: written`;
+};
+
+/** A tool on the bus, through the runtime; its MCP answer read back as JSON where it is JSON. */
+const ask: Ask = async (address, args) => {
+  const answer = (await broker().request<Record<string, unknown>, { content?: { text?: string }[]; isError?: boolean }>(address, args)) ?? {};
+  const text = answer.content?.map((c) => c.text ?? "").join("") ?? "";
+  if (answer.isError) throw new Error(`${address}: ${text}`);
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+};
+
+/** The nodes claude-code runs on, from the controller's list of modules — for the register tool's question. */
+async function nodesRunningMe(): Promise<string[]> {
+  const out = await ask("mesh-controller.modules", {});
+  const text = typeof out === "string" ? out : String((out as { output?: string })?.output ?? "");
+  const line = text.split("\n").find((l) => /^claude-code\s/.test(l)) ?? "";
+  const on = line.split(" on ")[1] ?? "";
+  return on.trim() === "nothing" ? [] : on.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+function status(p: Paths): Record<string, unknown> {
+  const creds = readCredentials(join(p.home, ".claude", ".credentials.json"));
+  const grant = grantOf(creds);
+  const managed = ["managed-mcp.json", "managed-settings.json", "CLAUDE.md"].map((f) => {
+    try {
+      return { file: join(MANAGED_DIR, f), fingerprint: fingerprint(readFileSync(join(MANAGED_DIR, f), "utf8")) };
+    } catch {
+      return { file: join(MANAGED_DIR, f), fingerprint: null };
+    }
+  });
+  return {
+    node: p.node,
+    licence: readJson(join(p.state, "licence.json"), null),
+    token: grant ? { fingerprint: fingerprint(grant.accessToken), expiresAt: new Date(grant.expiresAt).toISOString(),
+      loginWaiting: holdsLogin(creds) } : null,
+    managed,
+    registered: Object.keys(registered(p)),
+  };
+}
+
+/** The module's MCP servers on the bus (ADR 0201): its own state, which every node of it watches. */
+const servers = () => state<Record<string, unknown>>("servers") as unknown as ServerState;
+
+/** What this node takes from that state, kept from the watch. One per process. */
+let view: ServerView | null = null;
+const viewOf = (p: Paths) => (view ??= new ServerView(p));
+
+function tools(p: Paths): ToolDefinition[] {
+  const nodesArg = { type: "string", description: 'more nodes: "all" for every node running claude-code, or a comma-separated list; absent is this node only' };
+  const nodesOf = (v: unknown): Registration["nodes"] =>
+    v === undefined || v === "" ? undefined : v === "all" ? "all" : String(v).split(",").map((s) => s.trim()).filter(Boolean);
+  return [
+    {
+      name: "claude_code_status",
+      description: "Claude Code on this machine as the mesh configured it: the licence it holds and when its token expires, the managed files, the MCP servers registered here. Fingerprints only, never a token.",
+      input: {},
+      run: async () => status(p),
+    },
+    {
+      name: "claude_code_render",
+      description: "Write Claude Code's managed directory now, from the mesh's facts, this module's settings and the servers registered here.",
+      input: {},
+      run: async () => ({ rendered: renderNow(p, writeManaged) }),
+    },
+    {
+      name: "claude_code_pull",
+      description: "Ask the licence manager for this node's current token now and apply it, rather than waiting for its next event.",
+      input: {},
+      run: async () => pull(p, ask, writeManaged),
+    },
+    {
+      name: "claude_code_mcp_list",
+      description: "The MCP servers registered through this module: those that apply on this node (beside the console, `mesh`, and those set in the module's settings), and every registration on the mesh, by key — `all.<server>` for every node, `<node>.<server>` for one.",
+      input: {},
+      run: async () => ({ here: registered(p), everywhere: await servers().keys() }),
+    },
+    {
+      name: "claude_code_mcp_register",
+      description: "Register an MCP server with Claude Code on this node, every node, or a list — an http/sse server by url, or a stdio server by command. Kept on the bus, so a node that joins later takes it too. Never put a secret in env or headers: the mesh refuses one.",
+      input: {
+        name: { type: "string", description: "the server's name: letters, digits, - and _" },
+        type: { type: "string", description: "http, sse or stdio (default stdio when a command is given, http when a url is)" },
+        url: { type: "string", description: "an http or sse server's url" },
+        command: { type: "string", description: "a stdio server's program" },
+        args: { type: "array", description: "a stdio server's arguments" },
+        env: { type: "object", description: "a stdio server's environment" },
+        headers: { type: "object", description: "an http server's headers" },
+        nodes: nodesArg,
+      },
+      run: async (a) => {
+        const entry: Record<string, unknown> = { type: a.type ?? (a.url ? "http" : "stdio") };
+        for (const k of ["url", "command", "args", "env", "headers"]) if (a[k] !== undefined) entry[k] = a[k];
+        return registerServer(p, { name: String(a.name ?? ""), entry, nodes: nodesOf(a.nodes) }, servers(), viewOf(p), writeManaged, nodesRunningMe);
+      },
+    },
+    {
+      name: "claude_code_mcp_unregister",
+      description: "Remove an MCP server registered through this module, on this node or more.",
+      input: { name: { type: "string", description: "the server's name" }, nodes: nodesArg },
+      run: async (a) => registerServer(p, { name: String(a.name ?? ""), nodes: nodesOf(a.nodes) }, servers(), viewOf(p), writeManaged, nodesRunningMe),
+    },
+  ];
+}
+
+registerModuleTools("claude-code", (env) => {
+  const p = pathsFrom(env);
+  if (!p) return [];
+  try {
+    keypair(p);
+    for (const line of renderNow(p, writeManaged)) if (!line.endsWith("unchanged")) say(line);
+  } catch (err) {
+    say(err instanceof Error ? err.message : String(err));
+  }
+  return tools(p);
+});
+
+// Launched by the runtime: the bus is there from the first line (ADR 0198). Outside it — a test, a
+// build — nothing below runs.
+const p = process.env.MESH_SERVED_MODULE ? pathsFrom(process.env) : null;
+if (p) {
+  const loud = (what: string) => (err: unknown) => say(`${what}: ${err instanceof Error ? err.message : String(err)}`);
+
+  void on<{ licence?: string; node?: string }>("claude-licence-manager.licence.*", async (event) => {
+    if (!concerns(p, event.type, event.body ?? {})) return;
+    say(`${event.type} — asking ${SEAT} for this node's token`);
+    say(JSON.stringify(await pull(p, ask, writeManaged).catch((e) => ({ failed: String(e) }))));
+  }).catch(loud("the licence events"));
+
+  // Every node's MCP servers: the whole current set first, then each change (ADR 0201). **Not awaited
+  // where the module is imported**: the runtime waits on the handshake, and a bucket that is not on the
+  // bus yet — or a grant the bus has not reloaded — answers late; awaited here, that left the bundle
+  // unable to answer `initialize` in time and the module unserved (found on its first assignment). So it
+  // watches beside the handshake and asks again until the state answers; until then the managed
+  // directory holds what the file kept from the last run.
+  const watchServers = (attempt = 0): void => {
+    state<Record<string, unknown>>("servers").watch((c) => {
+      try {
+        const done = onServerChange(viewOf(p), c as ServerChange, p, writeManaged);
+        if (done) say(done);
+      } catch (err) {
+        loud(`taking ${c.op} ${c.key}`)(err); // the view took it; the next render writes it
+      }
+    }).then(
+      () => say(`watching the MCP servers${attempt ? ` (after ${attempt} refusal(s))` : ""}`),
+      (err) => {
+        const wait = [2, 5, 10, 30][attempt] ?? 60;
+        say(`the MCP servers cannot be watched yet (${err instanceof Error ? err.message : String(err)}); asking again in ${wait}s`);
+        setTimeout(() => watchServers(attempt + 1), wait * 1000);
+      });
+  };
+  watchServers();
+
+  // Catch up once at start: a node that was off takes its current token now.
+  void pull(p, ask, writeManaged).then((r) => say(`at start: ${JSON.stringify(r)}`), loud("asking for this node's token at start"));
+
+  // A login: a refresh token appears in the credentials file. Polled, because the file is replaced by
+  // rename and a watch on the old inode would go quiet.
+  const credentials = join(p.home, ".claude", ".credentials.json");
+  watchFile(credentials, { interval: 5000 }, () => {
+    void offerLogin(p, ask).then((r) => { if (r) say(`a login here was offered to ${SEAT}: ${JSON.stringify(r)}`); },
+      loud("offering a login to the licence manager"));
+  });
+}
@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["seal.ts", "grant.ts", "identity.ts", "render.ts", "node.ts", "tools/index.ts"]
+}
@@ -0,0 +1,120 @@
+# memory-pressure
+
+Compressed swap in RAM, systemd-oomd, and a guard that warns before the machine kills for memory. It
+can be assigned on any machine (novox/hq research 027/03, 026/05, to-be 42 phase 3). Memory pressure
+is not the laptop's alone.
+
+## What it owns
+
+| | what | notes |
+|---|---|---|
+| package | `zram-generator` | |
+| file | `/etc/systemd/zram-generator.conf` | `zram0`: `min(ram / 2, 16384)` MiB, zstd, swap priority 100. These are the laptop's values, adopted (the path too, ADR 0182). They scale with the machine: 15.3 GiB on 30 GiB of RAM, 16 GiB on the 125 GiB desktop. Read at boot, so a change applies at the next boot. Resizing a live device would mean swapping it off, which pushes what it holds back into RAM |
+| file | `/etc/sysctl.d/90-memory-pressure.conf` | `vm.page-cluster = 0` (no read-ahead on swap in RAM). Swappiness is left alone on purpose: the comment says why. `systemd-sysctl` is re-run |
+| file | `/etc/systemd/oomd.conf.d/memory-pressure.conf` | `SwapUsedLimit=90%`, `DefaultMemoryPressureLimit=60%`, `DefaultMemoryPressureDurationSec=20s` |
+| file | `/etc/systemd/system/-.slice.d/10-oomd.conf` | `ManagedOOMSwap=kill` |
+| file | `/etc/systemd/system/user@.service.d/10-oomd.conf` | `ManagedOOMMemoryPressure=kill`, limit 80 % |
+| service | `systemd-oomd` running, enabled | restarted on any of its drop-ins, after a `daemon-reload` |
+
+The swap on disk is not this module's. Whether there is a swap file or a partition, and how large, is
+the machine's swap layout (research 027 question 3, the `kernel` module). The two workstations differ:
+the laptop has a 32 GiB swap file (priority 10) and a 16 GiB partition, and the desktop a 128 GiB
+partition and no zram. This module adds the zram tier above whatever is there.
+
+## The long-running code: the guard (ADR 0198)
+
+The Go bundle serves the tools and runs the guard in the same process, launched by the node's runtime.
+It replaces the predecessor's `mem-guard` user unit, which checked used RAM every 30 s and called
+`notify-send`.
+
+- **Three signals:** RAM used ≥ 95 % (the predecessor's line, which it had raised from 90),
+  swap used ≥ 80 % (oomd kills at 90 %), or memory pressure (PSI `some` avg10) ≥ 40 % (oomd acts at
+  60 %, or 80 % for the user manager, over 20 s). Whichever comes first warns, and the warning says
+  which.
+- **Every 10 s**, not 30: oomd's window is 20 s, so a check every 30 s could warn after oomd had
+  already acted. Each check reads two files. PSI triggers would wake on pressure alone, but not on RAM
+  or swap filling, so one timer reads all three rather than run two mechanisms.
+- **Once per episode.** After a warning the guard re-arms only when every value is below its clearing
+  line: 88 % RAM, 70 % swap, 10 % pressure.
+- **The warning names what to close:** the three largest units by resident plus swapped memory, and
+  in each its largest process.
+- **The desktop, from outside the session.** The runtime runs as the operator's account but outside
+  the graphical session, with no session bus address and no `XDG_RUNTIME_DIR` (measured on the
+  laptop's runtime unit). The guard names the account's own bus, `/run/user/<uid>/bus`, and calls
+  `org.freedesktop.Notifications.Notify` with `busctl --user`. That client is the service manager's
+  own, so nothing is installed, and a server pulls in no libnotify. Measured on 2026-10-04: from a
+  clean environment as the account's uid, the notification service on that bus answered (dunst 1.13).
+  The account is the runtime's `MESH_OPERATOR_ACCOUNT`. A runtime running as another uid could not
+  authenticate on that bus, and the guard says so rather than try.
+- **And always an event:** `pressure.high` (reasons, percentages, the largest units) and
+  `pressure.cleared` (how long it lasted) are published through the runtime, whether or not anyone is
+  at a desktop. A machine without one has no session bus, and `memory_guard` says
+  *no session bus*.
+
+Thresholds are constants until settings exist (issue 168).
+
+**Known limit.** The runtime restarts a launched bundle that exits on its next tool call, not at once.
+The guard recovers from a panic and reports it, but a crashed process waits for a call.
+
+## Tools
+
+| tool | what |
+|---|---|
+| `memory_status` | RAM, swap and each device with its priority, zram and its ratio, PSI some/full, and the guard's verdict on them |
+| `memory_top` | the largest processes by resident plus swap, with their unit; `by=unit` sums per unit, which is what systemd-oomd chooses among |
+| `memory_oom_history` | what was killed, newest first, from the journal: the kernel's OOM killer, systemd-oomd, and the service manager's *killed by the OOM killer*. `since` is checked against a short grammar before it reaches `journalctl` |
+| `memory_zram` | each zram device (algorithm, size, stored, compressed, RAM used, ratio, same-filled and incompressible pages), the generator's configuration, swappiness and page-cluster |
+| `memory_oomd` | whether oomd runs, and what it watches (`oomctl`) |
+| `memory_guard` | the guard's thresholds, last verdict, whether a warning stands, and whether the desktop can be reached |
+
+## Found on 2026-10-04 (read-only)
+
+- **On the laptop, systemd-oomd guards almost nothing a person runs.** Every desktop application runs
+  in the login session's scope (`session-1.scope`), because the login manager and i3 start them there
+  and not in per-application scopes under `user@.service`. The pressure kill on `user@.service`
+  therefore watches 0.5 GiB. The swap kill on `-.slice`, when it fires, would choose the largest
+  cgroup, which is the whole session scope: X, i3 and every application at once. `memory_top by=unit`
+  shows it. **The fix is the graphical session's** (phase 2): launch applications in their own
+  scopes, for example `systemd-run --user --scope` from the launcher, and oomd then kills one
+  application. This module does not widen oomd's reach onto `user-.slice`, because there it would kill
+  the session.
+- The desktop has no zram and oomd disabled. Assigning the module there is a change of behaviour:
+  16 GiB of zram at the next boot, and oomd enabled with the same caveat about the session scope.
+
+## When assigned to the laptop: what changes
+
+1. Written over found files (originals kept once): `zram-generator.conf` (same values, so nothing
+   until the next boot either), `-.slice.d/10-oomd.conf` and `user@.service.d/10-oomd.conf` (same
+   keys).
+2. New: `sysctl.d/90-memory-pressure.conf` (the same `vm.page-cluster = 0` already in force) and
+   `oomd.conf.d/memory-pressure.conf` (the same values as the predecessor's file beside it).
+3. `systemd-sysctl` is re-run (the values are unchanged), and `daemon-reload` and `systemd-oomd` are
+   restarted.
+4. The node runtime restarts with the bundle, and the guard starts. **Until `mem-guard` is stopped,
+   two notifiers run.**
+
+## Predecessor files this module makes redundant — the operator removes them once (ADR 0182)
+
+On the laptop:
+
+1. `systemctl --user disable --now mem-guard.service`, then delete
+   `~/.config/systemd/user/mem-guard.service` and `~/scripts/mem-guard.sh`.
+2. `/etc/systemd/oomd.conf.d/g14-oomd.conf`: the same values as the module's drop-in.
+3. `/etc/sysctl.d/90-g14-zram.conf`: the same key as the module's file.
+
+The desktop had none of these.
+
+## Tests
+
+`go test ./...`. They read a tree standing in for `/proc` and `/sys`, using the laptop's own swaps,
+zram statistics and PSI lines. They cover:
+
+- the snapshot;
+- the guard's three lines, its once-per-episode latch and its clearing, with the largest named;
+- an unreachable desktop still publishing the event;
+- the notification being one `busctl` call on the account's bus;
+- grouping by unit;
+- the journal's three kinds of kill, with non-UTF-8 messages skipped;
+- `since` refused when it is an option;
+- *no match* read as no kills;
+- the manifest: tools listed equal tools served, events, no machine named, triggers exist.
@@ -0,0 +1,286 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/user"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// The module's long-running code (novox/hq ADR 0198): the guard that warns before the machine kills
+// something for memory. It replaces the predecessor's `mem-guard`, a user unit that checked used RAM
+// every thirty seconds and called notify-send.
+//
+// What changed, and why:
+//
+//   - **Three signals, not one.** Used RAM alone misses the two things that decide whether a kill is
+//     coming: swap filling (systemd-oomd kills at SwapUsedLimit) and stall pressure (it kills a unit
+//     whose pressure stays over its limit for twenty seconds). The guard warns on whichever comes
+//     first, and says which.
+//   - **Ten seconds, not thirty.** oomd's own window is twenty seconds; a check every thirty can
+//     notice only after oomd has acted. Reading two files every ten seconds costs nothing measurable.
+//     The kernel's PSI triggers would wake on pressure alone, but not on RAM or swap filling, so the
+//     guard reads all three on one timer rather than run two mechanisms.
+//   - **The notification names what to close.** It lists the largest units, not only a percentage.
+//   - **An event as well as a notification.** `pressure.high` and `pressure.cleared` reach the mesh
+//     whether or not anyone is at the desktop — a server has no desktop at all.
+//   - **No session needed.** The runtime runs as the operator's account but outside the graphical
+//     session, so it has no session bus address. The guard names the account's own bus,
+//     /run/user/<uid>/bus, and speaks to the notification service with busctl, the service manager's
+//     client: nothing is installed for it, and a machine without a desktop simply has no such bus.
+
+// Thresholds, as constants until settings exist (novox/hq issue 168). Used RAM is the predecessor's,
+// raised by it from 90 to 95 after the lower line fired during ordinary work.
+const (
+	WarnUsedPercent    = 95.0
+	ClearUsedPercent   = 88.0
+	WarnSwapPercent    = 80.0 // systemd-oomd's SwapUsedLimit is 90 %
+	ClearSwapPercent   = 70.0
+	WarnPressureAvg10  = 40.0 // "some" avg10; oomd acts at 60 % (80 % for the user manager) over 20 s
+	ClearPressureAvg10 = 10.0
+	CheckEvery         = 10 * time.Second
+	NotificationID     = 9010 // replaces the previous warning rather than stacking
+)
+
+// Verdict is what one check of the machine concluded.
+type Verdict struct {
+	High    bool     `json:"high"`
+	Reasons []string `json:"reasons"`
+	Clear   bool     `json:"clear"`
+}
+
+// Judge applies the thresholds to a snapshot. High is any warning line crossed; Clear is every value
+// below its clearing line, which is what re-arms the guard.
+func Judge(s Snapshot) Verdict {
+	v := Verdict{Reasons: []string{}}
+	clear := true
+	if s.UsedPercent >= WarnUsedPercent {
+		v.Reasons = append(v.Reasons, fmt.Sprintf("RAM %.0f%% used (warns at %.0f%%)", s.UsedPercent, WarnUsedPercent))
+	}
+	if s.UsedPercent > ClearUsedPercent {
+		clear = false
+	}
+	if s.SwapTotalGiB > 0 {
+		if s.SwapPercent >= WarnSwapPercent {
+			v.Reasons = append(v.Reasons, fmt.Sprintf("swap %.0f%% used (warns at %.0f%%; systemd-oomd kills at 90%%)", s.SwapPercent, WarnSwapPercent))
+		}
+		if s.SwapPercent > ClearSwapPercent {
+			clear = false
+		}
+	}
+	if s.PressureSome != nil {
+		if s.PressureSome.Avg10 >= WarnPressureAvg10 {
+			v.Reasons = append(v.Reasons, fmt.Sprintf("tasks stalled on memory %.0f%% of the last 10 s (warns at %.0f%%)", s.PressureSome.Avg10, WarnPressureAvg10))
+		}
+		if s.PressureSome.Avg10 > ClearPressureAvg10 {
+			clear = false
+		}
+	}
+	v.High = len(v.Reasons) > 0
+	v.Clear = clear
+	return v
+}
+
+// Guard is the notifier's state, shared with the tools that report it.
+type Guard struct {
+	m      *Machine
+	now    func() time.Time
+	emit   func(string, any) error
+	notify func(ctx context.Context, summary, body string) error
+
+	mu       sync.Mutex
+	latched  bool
+	since    time.Time
+	last     *Verdict
+	lastAt   time.Time
+	notified string
+	err      string
+	desktop  string
+	stopped  string
+}
+
+func NewGuard(m *Machine, emit func(string, any) error) *Guard {
+	g := &Guard{m: m, now: time.Now, emit: emit}
+	g.notify = g.desktopNotify
+	return g
+}
+
+// Check is one wake-up: read, judge, and on crossing a line warn once; on clearing every line, re-arm.
+func (g *Guard) Check(ctx context.Context) {
+	s, err := g.m.Snapshot()
+	g.mu.Lock()
+	if err != nil {
+		g.err = err.Error()
+		g.mu.Unlock()
+		return
+	}
+	v := Judge(s)
+	now := g.now()
+	g.last, g.lastAt, g.err = &v, now, ""
+	warn := v.High && !g.latched
+	cleared := g.latched && v.Clear
+	if warn {
+		g.latched, g.since = true, now
+	}
+	if cleared {
+		g.latched = false
+	}
+	since := g.since
+	g.mu.Unlock()
+
+	if warn {
+		largest := ByUnit(g.m.Processes(), 3)
+		var names []string
+		for _, u := range largest {
+			names = append(names, fmt.Sprintf("%s %.1f GiB", firstNonEmpty(u.Largest, u.Unit), (u.RSSMiB+u.SwapMiB)/1024))
+		}
+		body := strings.Join(v.Reasons, "; ")
+		if len(names) > 0 {
+			body += ". Largest: " + strings.Join(names, ", ")
+		}
+		body += ". systemd-oomd kills the worst unit if it climbs further."
+		g.publish("pressure.high", map[string]any{"reasons": v.Reasons, "used_percent": s.UsedPercent,
+			"swap_used_percent": s.SwapPercent, "pressure_some": s.PressureSome, "largest": largest})
+		err := g.notify(ctx, "Memory is running low", body)
+		g.mu.Lock()
+		if err != nil {
+			g.desktop = "not reached: " + err.Error()
+		} else {
+			g.desktop, g.notified = "reached", now.Format(time.RFC3339)
+		}
+		g.mu.Unlock()
+	}
+	if cleared {
+		g.publish("pressure.cleared", map[string]any{"used_percent": s.UsedPercent, "swap_used_percent": s.SwapPercent,
+			"lasted_seconds": int(now.Sub(since).Seconds())})
+	}
+}
+
+func (g *Guard) publish(eventType string, body map[string]any) {
+	if g.emit == nil {
+		return
+	}
+	if err := g.emit(eventType, body); err != nil {
+		fmt.Fprintf(os.Stderr, "%s not published: %v\n", eventType, err)
+	}
+}
+
+// Bus is the operator's session bus socket: the account the runtime names, else the one this process
+// runs as.
+func Bus() (string, error) {
+	uid := os.Getuid()
+	if name := os.Getenv("MESH_OPERATOR_ACCOUNT"); name != "" {
+		u, err := user.Lookup(name)
+		if err != nil {
+			return "", fmt.Errorf("the operator account %s: %w", name, err)
+		}
+		if n, err := strconv.Atoi(u.Uid); err == nil {
+			if n != uid && uid != 0 {
+				return "", fmt.Errorf("this process runs as uid %d and the operator's bus belongs to uid %d", uid, n)
+			}
+			uid = n
+		}
+	}
+	return fmt.Sprintf("/run/user/%d/bus", uid), nil
+}
+
+// desktopNotify sends one critical notification to the operator's session, replacing the previous one.
+func (g *Guard) desktopNotify(ctx context.Context, summary, body string) error {
+	bus, err := Bus()
+	if err != nil {
+		return err
+	}
+	if _, err := os.Stat(bus); err != nil {
+		return fmt.Errorf("no session bus at %s (nobody is logged in to a desktop)", bus)
+	}
+	_, err = g.m.Run(ctx, "env", "DBUS_SESSION_BUS_ADDRESS=unix:path="+bus,
+		"busctl", "--user", "call", "org.freedesktop.Notifications", "/org/freedesktop/Notifications",
+		"org.freedesktop.Notifications", "Notify", "susssasa{sv}i",
+		"memory-pressure", strconv.Itoa(NotificationID), "dialog-warning", summary, body, "0", "1", "urgency", "y", "2", "0")
+	return err
+}
+
+// Run is the guard's life: a check every CheckEvery.
+func (g *Guard) Run(ctx context.Context) {
+	defer func() {
+		if r := recover(); r != nil {
+			g.mu.Lock()
+			g.stopped = fmt.Sprintf("the guard stopped on a fault: %v", r)
+			g.mu.Unlock()
+			fmt.Fprintln(os.Stderr, g.stopped)
+		}
+	}()
+	t := time.NewTicker(CheckEvery)
+	defer t.Stop()
+	for {
+		g.Check(ctx)
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+		}
+	}
+}
+
+// GuardReport is the guard as the guard tool shows it.
+type GuardReport struct {
+	Running      bool           `json:"running"`
+	Stopped      string         `json:"stopped,omitempty"`
+	Warned       bool           `json:"warning_given"`
+	WarnedSince  *time.Time     `json:"warning_since,omitempty"`
+	LastCheck    *time.Time     `json:"last_check,omitempty"`
+	LastVerdict  *Verdict       `json:"last_verdict,omitempty"`
+	LastError    string         `json:"last_error,omitempty"`
+	Desktop      string         `json:"desktop"`
+	LastNotified string         `json:"last_notified,omitempty"`
+	Thresholds   map[string]any `json:"thresholds"`
+}
+
+func (g *Guard) Report() GuardReport {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	r := GuardReport{
+		Running: g.stopped == "" && !g.lastAt.IsZero(), Stopped: g.stopped, Warned: g.latched, LastCheck: when(g.lastAt),
+		LastVerdict: g.last, LastError: g.err, Desktop: g.desktop, LastNotified: g.notified,
+		Thresholds: map[string]any{
+			"warn_used_percent": WarnUsedPercent, "clear_used_percent": ClearUsedPercent,
+			"warn_swap_percent": WarnSwapPercent, "clear_swap_percent": ClearSwapPercent,
+			"warn_pressure_some_avg10": WarnPressureAvg10, "clear_pressure_some_avg10": ClearPressureAvg10,
+			"check_every": CheckEvery.String(), "set_by": "constants until settings exist (novox/hq issue 168)",
+		},
+	}
+	if g.latched {
+		r.WarnedSince = when(g.since)
+	}
+	if r.Desktop == "" {
+		if bus, err := Bus(); err != nil {
+			r.Desktop = "not reachable: " + err.Error()
+		} else if _, err := os.Stat(bus); err != nil {
+			r.Desktop = "no session bus at " + bus
+		} else {
+			r.Desktop = "reachable at " + bus + " (not yet used)"
+		}
+	}
+	return r
+}
+
+func firstNonEmpty(ss ...string) string {
+	for _, s := range ss {
+		if s != "" {
+			return s
+		}
+	}
+	return ""
+}
+
+// when is a time for a report: absent rather than the zero time.
+func when(t time.Time) *time.Time {
+	if t.IsZero() {
+		return nil
+	}
+	return &t
+}
@@ -0,0 +1,80 @@
+package main
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// fake is a machine for a test: a tree standing in for /, and a runner answering from a table and
+// recording every command it was asked to run.
+type fake struct {
+	t       *testing.T
+	root    string
+	mu      sync.Mutex
+	answers map[string]string
+	fails   map[string]error
+	calls   []string
+}
+
+func newFake(t *testing.T) *fake {
+	t.Helper()
+	return &fake{t: t, root: t.TempDir(), answers: map[string]string{}, fails: map[string]error{}}
+}
+
+func (f *fake) machine() *Machine { return &Machine{Root: f.root, Run: f.run} }
+
+func (f *fake) run(_ context.Context, name string, args ...string) (string, error) {
+	line := strings.TrimSpace(name + " " + strings.Join(args, " "))
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.calls = append(f.calls, line)
+	if err, ok := f.fails[line]; ok {
+		return "", err
+	}
+	if out, ok := f.answers[line]; ok {
+		return out, nil
+	}
+	if err, ok := f.fails[name]; ok {
+		return "", err
+	}
+	return "", nil
+}
+
+func (f *fake) called(line string) bool {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	for _, c := range f.calls {
+		if c == line {
+			return true
+		}
+	}
+	return false
+}
+
+func (f *fake) callsLike(prefix string) []string {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	var out []string
+	for _, c := range f.calls {
+		if strings.HasPrefix(c, prefix) {
+			out = append(out, c)
+		}
+	}
+	return out
+}
+
+// file writes a file under the fake root.
+func (f *fake) file(path, content string) {
+	f.t.Helper()
+	full := filepath.Join(f.root, path)
+	if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+		f.t.Fatal(err)
+	}
+	if err := os.WriteFile(full, []byte(content), 0o644); err != nil {
+		f.t.Fatal(err)
+	}
+}
@@ -0,0 +1,106 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// CommandTimeout bounds every command a tool or the guard runs: a journal that takes long to search
+// must cost a tool call twenty seconds, never the runtime's thirty.
+const CommandTimeout = 20 * time.Second
+
+// Runner runs one command and answers its standard output. It is injected so that every tool is
+// tested against recorded answers rather than this machine's daemons.
+type Runner func(ctx context.Context, name string, args ...string) (string, error)
+
+// ExecRunner runs a command on the machine, bounded by CommandTimeout. A failure carries what the
+// command said on stderr, because "exit status 1" names nothing.
+func ExecRunner(ctx context.Context, name string, args ...string) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, CommandTimeout)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, name, args...)
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout, cmd.Stderr = &stdout, &stderr
+	err := cmd.Run()
+	if ctx.Err() == context.DeadlineExceeded {
+		return stdout.String(), fmt.Errorf("%s did not answer within %s", name, CommandTimeout)
+	}
+	if err != nil {
+		said := strings.TrimSpace(stderr.String())
+		if said == "" {
+			said = strings.TrimSpace(stdout.String())
+		}
+		if said != "" {
+			return stdout.String(), fmt.Errorf("%s %s: %w: %s", name, strings.Join(args, " "), err, said)
+		}
+		return stdout.String(), fmt.Errorf("%s %s: %w", name, strings.Join(args, " "), err)
+	}
+	return stdout.String(), nil
+}
+
+// Machine is what the module reads and acts on: a filesystem root (the real one, or a test's tree of
+// /proc, /sys and /etc) and a way to run commands.
+type Machine struct {
+	Root string
+	Run  Runner
+}
+
+// Here is the machine this process runs on.
+func Here() *Machine { return &Machine{Root: "/", Run: ExecRunner} }
+
+func (m *Machine) path(p string) string { return filepath.Join(m.Root, p) }
+
+// read is a file's content, trimmed; "" when it cannot be read.
+func (m *Machine) read(p string) string {
+	b, err := os.ReadFile(m.path(p))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(b))
+}
+
+// readInt is a file holding one integer; ok false when it is absent or not a number.
+func (m *Machine) readInt(p string) (int64, bool) {
+	s := m.read(p)
+	if s == "" {
+		return 0, false
+	}
+	n, err := strconv.ParseInt(s, 10, 64)
+	return n, err == nil
+}
+
+func (m *Machine) glob(pattern string) []string {
+	found, _ := filepath.Glob(m.path(pattern))
+	out := make([]string, 0, len(found))
+	for _, f := range found {
+		rel, err := filepath.Rel(m.Root, f)
+		if err != nil {
+			continue
+		}
+		out = append(out, "/"+filepath.ToSlash(rel))
+	}
+	return out
+}
+
+// notInstalled says a command failed because it is not on this machine at all.
+func notInstalled(err error) bool { return errors.Is(err, exec.ErrNotFound) }
+
+// round to one decimal, for watts and percentages a person reads.
+func round1(f float64) float64 {
+	return float64(int64(f*10+sign(f)*0.5)) / 10
+}
+
+func sign(f float64) float64 {
+	if f < 0 {
+		return -1
+	}
+	return 1
+}
@@ -0,0 +1,24 @@
+// The memory-pressure module's Go bundle (novox/hq ADR 0188, ADR 0193, ADR 0198): one process the
+// node's runtime launches, serving the module's tools over MCP on stdio and running its long-running
+// code — the guard that warns before the machine kills for memory — beside them.
+package main
+
+import (
+	"context"
+	"fmt"
+	"os"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+func main() {
+	m := Here()
+	g := NewGuard(m, func(eventType string, body any) error { return stdio.Emit(eventType, body) })
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go g.Run(ctx)
+	if err := stdio.Serve("", Tools(m, g)); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
@@ -0,0 +1,54 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"sort"
+	"strings"
+	"testing"
+)
+
+func TestTheManifestNamesExactlyTheToolsTheBundleServesAndNoMachine(t *testing.T) {
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Tools     []string         `json:"tools"`
+		Emits     []string         `json:"emits"`
+		Resources []map[string]any `json:"resources"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	var served []string
+	for _, tool := range Tools(newFake(t).machine(), nil) {
+		served = append(served, tool.Name)
+	}
+	sort.Strings(served)
+	sort.Strings(m.Tools)
+	if strings.Join(served, ",") != strings.Join(m.Tools, ",") {
+		t.Fatalf("served %v, listed %v", served, m.Tools)
+	}
+	sort.Strings(m.Emits)
+	if strings.Join(m.Emits, ",") != "pressure.cleared,pressure.high" {
+		t.Fatalf("emits %v", m.Emits)
+	}
+	for _, banned := range []string{"g14", "jochen", "/home/", "shanks", "/run/user/1000"} {
+		if strings.Contains(string(raw), banned) {
+			t.Errorf("the manifest says %q", banned)
+		}
+	}
+	ids := map[string]bool{}
+	for _, r := range m.Resources {
+		ids[r["id"].(string)] = true
+	}
+	for _, r := range m.Resources {
+		list, _ := r["restart-on"].([]any)
+		for _, id := range list {
+			if !ids[id.(string)] {
+				t.Errorf("%s restarts on %v, which is not a resource", r["id"], id)
+			}
+		}
+	}
+}
@@ -0,0 +1,300 @@
+package main
+
+import (
+	"fmt"
+	"path"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+const kib = 1024
+
+// GiB turns bytes into gibibytes with one decimal, for a person reading.
+func GiB(bytes int64) float64 { return round1(float64(bytes) / (1 << 30)) }
+
+// ParseMeminfo reads /proc/meminfo into bytes by field.
+func ParseMeminfo(text string) map[string]int64 {
+	out := map[string]int64{}
+	for _, line := range strings.Split(text, "\n") {
+		key, rest, ok := strings.Cut(line, ":")
+		if !ok {
+			continue
+		}
+		f := strings.Fields(rest)
+		if len(f) == 0 {
+			continue
+		}
+		n, err := strconv.ParseInt(f[0], 10, 64)
+		if err != nil {
+			continue
+		}
+		if len(f) > 1 && f[1] == "kB" {
+			n *= kib
+		}
+		out[key] = n
+	}
+	return out
+}
+
+// Pressure is one line of a PSI file: the share of time some (or all) tasks stalled on memory.
+type Pressure struct {
+	Avg10  float64 `json:"avg10"`
+	Avg60  float64 `json:"avg60"`
+	Avg300 float64 `json:"avg300"`
+}
+
+// ParsePSI reads /proc/pressure/memory: its `some` and `full` lines.
+func ParsePSI(text string) (some, full *Pressure) {
+	for _, line := range strings.Split(text, "\n") {
+		f := strings.Fields(line)
+		if len(f) < 4 {
+			continue
+		}
+		p := &Pressure{}
+		for _, kv := range f[1:] {
+			k, v, _ := strings.Cut(kv, "=")
+			n, _ := strconv.ParseFloat(v, 64)
+			switch k {
+			case "avg10":
+				p.Avg10 = n
+			case "avg60":
+				p.Avg60 = n
+			case "avg300":
+				p.Avg300 = n
+			}
+		}
+		switch f[0] {
+		case "some":
+			some = p
+		case "full":
+			full = p
+		}
+	}
+	return some, full
+}
+
+// SwapDevice is one line of /proc/swaps.
+type SwapDevice struct {
+	Name     string  `json:"name"`
+	Type     string  `json:"type"`
+	SizeGiB  float64 `json:"size_gib"`
+	UsedGiB  float64 `json:"used_gib"`
+	Priority int     `json:"priority"`
+}
+
+// ParseSwaps reads /proc/swaps (sizes in KiB).
+func ParseSwaps(text string) []SwapDevice {
+	var out []SwapDevice
+	for i, line := range strings.Split(text, "\n") {
+		f := strings.Fields(line)
+		if i == 0 || len(f) < 5 {
+			continue
+		}
+		size, _ := strconv.ParseInt(f[2], 10, 64)
+		used, _ := strconv.ParseInt(f[3], 10, 64)
+		prio, _ := strconv.Atoi(f[4])
+		out = append(out, SwapDevice{Name: f[0], Type: f[1], SizeGiB: GiB(size * kib), UsedGiB: GiB(used * kib), Priority: prio})
+	}
+	return out
+}
+
+// Snapshot is the machine's memory at one moment: what the status tool answers and what the guard
+// judges.
+type Snapshot struct {
+	TotalGiB     float64      `json:"total_gib"`
+	AvailableGiB float64      `json:"available_gib"`
+	UsedPercent  float64      `json:"used_percent"`
+	SwapTotalGiB float64      `json:"swap_total_gib"`
+	SwapUsedGiB  float64      `json:"swap_used_gib"`
+	SwapPercent  float64      `json:"swap_used_percent"`
+	Swaps        []SwapDevice `json:"swap_devices"`
+	Zram         []Zram       `json:"zram"`
+	PressureSome *Pressure    `json:"pressure_some,omitempty"`
+	PressureFull *Pressure    `json:"pressure_full,omitempty"`
+}
+
+// Snapshot reads /proc and /sys.
+func (m *Machine) Snapshot() (Snapshot, error) {
+	mem := ParseMeminfo(m.read("/proc/meminfo"))
+	total, avail := mem["MemTotal"], mem["MemAvailable"]
+	if total <= 0 {
+		return Snapshot{}, fmt.Errorf("/proc/meminfo says no MemTotal")
+	}
+	s := Snapshot{
+		TotalGiB: GiB(total), AvailableGiB: GiB(avail),
+		UsedPercent:  round1(float64(total-avail) / float64(total) * 100),
+		SwapTotalGiB: GiB(mem["SwapTotal"]),
+		SwapUsedGiB:  GiB(mem["SwapTotal"] - mem["SwapFree"]),
+		Swaps:        ParseSwaps(m.read("/proc/swaps")),
+		Zram:         m.Zram(),
+	}
+	if mem["SwapTotal"] > 0 {
+		s.SwapPercent = round1(float64(mem["SwapTotal"]-mem["SwapFree"]) / float64(mem["SwapTotal"]) * 100)
+	}
+	if s.Swaps == nil {
+		s.Swaps = []SwapDevice{}
+	}
+	s.PressureSome, s.PressureFull = ParsePSI(m.read("/proc/pressure/memory"))
+	return s, nil
+}
+
+// Zram is one compressed swap device in RAM.
+type Zram struct {
+	Device        string   `json:"device"`
+	Algorithm     string   `json:"algorithm"`
+	DiskSizeGiB   float64  `json:"disk_size_gib"`
+	StoredGiB     float64  `json:"stored_gib"`
+	CompressedGiB float64  `json:"compressed_gib"`
+	RAMUsedGiB    float64  `json:"ram_used_gib"`
+	Ratio         *float64 `json:"compression_ratio,omitempty"`
+	SamePages     int64    `json:"same_filled_pages"`
+	HugePages     int64    `json:"incompressible_pages"`
+}
+
+// Zram reads every zram device's statistics from /sys/block.
+func (m *Machine) Zram() []Zram {
+	out := []Zram{}
+	for _, dir := range m.glob("/sys/block/zram*") {
+		z := Zram{Device: path.Base(dir), Algorithm: activeAlgorithm(m.read(dir + "/comp_algorithm"))}
+		if v, ok := m.readInt(dir + "/disksize"); ok {
+			z.DiskSizeGiB = GiB(v)
+		}
+		// mm_stat: orig_data_size compr_data_size mem_used_total mem_limit mem_used_max same_pages
+		// pages_compacted huge_pages …
+		f := strings.Fields(m.read(dir + "/mm_stat"))
+		n := func(i int) int64 {
+			if i >= len(f) {
+				return 0
+			}
+			v, _ := strconv.ParseInt(f[i], 10, 64)
+			return v
+		}
+		if len(f) >= 3 {
+			z.StoredGiB, z.CompressedGiB, z.RAMUsedGiB = GiB(n(0)), GiB(n(1)), GiB(n(2))
+			z.SamePages, z.HugePages = n(5), n(7)
+			if n(1) > 0 {
+				r := round1(float64(n(0)) / float64(n(1)))
+				z.Ratio = &r
+			}
+		}
+		out = append(out, z)
+	}
+	return out
+}
+
+// activeAlgorithm is the bracketed one of `lzo lz4 [zstd]`.
+func activeAlgorithm(s string) string {
+	for _, f := range strings.Fields(s) {
+		if strings.HasPrefix(f, "[") {
+			return strings.Trim(f, "[]")
+		}
+	}
+	return s
+}
+
+// Process is one process by the memory it holds.
+type Process struct {
+	PID     int     `json:"pid"`
+	Name    string  `json:"name"`
+	RSSMiB  float64 `json:"rss_mib"`
+	SwapMiB float64 `json:"swap_mib"`
+	Unit    string  `json:"unit,omitempty"`
+	Command string  `json:"command,omitempty"`
+}
+
+// Group is the memory of every process in one systemd unit or scope.
+type Group struct {
+	Unit      string  `json:"unit"`
+	Processes int     `json:"processes"`
+	RSSMiB    float64 `json:"rss_mib"`
+	SwapMiB   float64 `json:"swap_mib"`
+	Largest   string  `json:"largest"`
+}
+
+// unitOf is the last named unit in a process's cgroup path: the scope or service it lives in, which
+// is what systemd-oomd chooses among.
+func unitOf(cgroup string) string {
+	line := strings.TrimSpace(strings.SplitN(cgroup, "\n", 2)[0])
+	_, p, _ := strings.Cut(line, "::")
+	parts := strings.Split(p, "/")
+	for i := len(parts) - 1; i >= 0; i-- {
+		if strings.HasSuffix(parts[i], ".scope") || strings.HasSuffix(parts[i], ".service") || strings.HasSuffix(parts[i], ".slice") {
+			return parts[i]
+		}
+	}
+	return p
+}
+
+// Processes reads every process's resident and swapped memory. A process that ends while it is read
+// is skipped.
+func (m *Machine) Processes() []Process {
+	var out []Process
+	for _, dir := range m.glob("/proc/[0-9]*") {
+		status := m.read(dir + "/status")
+		if status == "" {
+			continue
+		}
+		fields := ParseMeminfo(status)
+		name := ""
+		for _, line := range strings.Split(status, "\n") {
+			if v, ok := strings.CutPrefix(line, "Name:"); ok {
+				name = strings.TrimSpace(v)
+				break
+			}
+		}
+		rss := fields["VmRSS"]
+		swap := fields["VmSwap"]
+		if rss == 0 && swap == 0 {
+			continue // a kernel thread
+		}
+		pid, _ := strconv.Atoi(path.Base(dir))
+		cmd := strings.TrimSpace(strings.ReplaceAll(m.read(dir+"/cmdline"), "\x00", " "))
+		if len(cmd) > 160 {
+			cmd = cmd[:160] + "…"
+		}
+		out = append(out, Process{PID: pid, Name: name, RSSMiB: mib(rss), SwapMiB: mib(swap),
+			Unit: unitOf(m.read(dir + "/cgroup")), Command: cmd})
+	}
+	return out
+}
+
+func mib(b int64) float64 { return round1(float64(b) / (1 << 20)) }
+
+// Top is the largest processes by resident plus swapped memory.
+func Top(ps []Process, limit int) []Process {
+	sort.Slice(ps, func(i, j int) bool { return ps[i].RSSMiB+ps[i].SwapMiB > ps[j].RSSMiB+ps[j].SwapMiB })
+	if len(ps) > limit {
+		ps = ps[:limit]
+	}
+	return ps
+}
+
+// ByUnit sums processes by their unit, largest first.
+func ByUnit(ps []Process, limit int) []Group {
+	groups := map[string]*Group{}
+	biggest := map[string]float64{}
+	for _, p := range ps {
+		g := groups[p.Unit]
+		if g == nil {
+			g = &Group{Unit: p.Unit}
+			groups[p.Unit] = g
+		}
+		g.Processes++
+		g.RSSMiB = round1(g.RSSMiB + p.RSSMiB)
+		g.SwapMiB = round1(g.SwapMiB + p.SwapMiB)
+		if p.RSSMiB+p.SwapMiB > biggest[p.Unit] {
+			biggest[p.Unit] = p.RSSMiB + p.SwapMiB
+			g.Largest = p.Name
+		}
+	}
+	out := make([]Group, 0, len(groups))
+	for _, g := range groups {
+		out = append(out, *g)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].RSSMiB+out[i].SwapMiB > out[j].RSSMiB+out[j].SwapMiB })
+	if len(out) > limit {
+		out = out[:limit]
+	}
+	return out
+}
@@ -0,0 +1,179 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+)
+
+const meminfo = `MemTotal:       32000000 kB
+MemFree:          905460 kB
+MemAvailable:    1000000 kB
+SwapTotal:      10000000 kB
+SwapFree:        5000000 kB
+`
+
+// As /proc/swaps and zram read on the laptop on 2026-10-04.
+const swaps = `Filename				Type		Size		Used		Priority
+/swapfile                               file		33554428	0		10
+/dev/zram0                              partition	16059900	7235584		100
+`
+
+func (f *fake) machineWith(mem, psi string) *Machine {
+	f.file("/proc/meminfo", mem)
+	f.file("/proc/swaps", swaps)
+	f.file("/proc/pressure/memory", psi)
+	f.file("/sys/block/zram0/comp_algorithm", "lzo-rle lzo lz4 lz4hc [zstd] deflate 842\n")
+	f.file("/sys/block/zram0/disksize", "16445341696\n")
+	f.file("/sys/block/zram0/mm_stat", "14368768  5341499  6680576        0  6680576        2        0        0        0\n")
+	return f.machine()
+}
+
+const calm = "some avg10=0.00 avg60=0.02 avg300=0.00 total=14487028\nfull avg10=0.00 avg60=0.01 avg300=0.00 total=14230772\n"
+
+func TestTheSnapshotReadsRAMSwapZramAndPressure(t *testing.T) {
+	f := newFake(t)
+	s, err := f.machineWith(meminfo, calm).Snapshot()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s.UsedPercent != 96.9 || s.SwapPercent != 50 || len(s.Swaps) != 2 || s.Swaps[1].Priority != 100 {
+		t.Fatalf("%+v", s)
+	}
+	z := s.Zram[0]
+	if z.Algorithm != "zstd" || *z.Ratio != 2.7 || z.DiskSizeGiB != 15.3 || z.SamePages != 2 {
+		t.Fatalf("%+v", z)
+	}
+	if s.PressureSome == nil || s.PressureSome.Avg60 != 0.02 || s.PressureFull == nil {
+		t.Fatalf("%+v %+v", s.PressureSome, s.PressureFull)
+	}
+}
+
+func TestTheGuardWarnsOnWhicheverLineIsCrossedFirst(t *testing.T) {
+	for name, c := range map[string]struct {
+		s    Snapshot
+		want string
+	}{
+		"ram":      {Snapshot{UsedPercent: 96}, "RAM"},
+		"swap":     {Snapshot{UsedPercent: 50, SwapTotalGiB: 10, SwapPercent: 85}, "swap"},
+		"pressure": {Snapshot{UsedPercent: 50, PressureSome: &Pressure{Avg10: 45}}, "stalled"},
+	} {
+		v := Judge(c.s)
+		if !v.High || len(v.Reasons) != 1 || !strings.Contains(v.Reasons[0], c.want) || v.Clear {
+			t.Errorf("%s: %+v", name, v)
+		}
+	}
+	if v := Judge(Snapshot{UsedPercent: 90}); v.High || v.Clear {
+		t.Errorf("between the lines is neither a warning nor clear: %+v", v)
+	}
+	if v := Judge(Snapshot{UsedPercent: 50, PressureSome: &Pressure{}}); v.High || !v.Clear {
+		t.Errorf("%+v", v)
+	}
+}
+
+func TestTheGuardWarnsOnceNamesTheLargestAndClearsOnlyBelowEveryLine(t *testing.T) {
+	f := newFake(t)
+	m := f.machineWith(meminfo, calm)
+	f.file("/proc/4242/status", "Name:\tfirefox\nVmRSS:\t 6291456 kB\nVmSwap:\t 1048576 kB\n")
+	f.file("/proc/4242/cgroup", "0::/user.slice/user-1000.slice/session-1.scope\n")
+	f.file("/proc/4242/cmdline", "/usr/lib/firefox/firefox\x00")
+	var events []string
+	g := NewGuard(m, func(t string, _ any) error { events = append(events, t); return nil })
+	var notes []string
+	g.notify = func(_ context.Context, summary, body string) error {
+		notes = append(notes, body)
+		return nil
+	}
+	ctx := context.Background()
+	g.Check(ctx)
+	g.Check(ctx)
+	if len(notes) != 1 || !strings.Contains(notes[0], "firefox 7.0 GiB") || !strings.Contains(notes[0], "RAM 97%") {
+		t.Fatalf("%v", notes)
+	}
+	// Between the lines: still latched, nothing new.
+	f.file("/proc/meminfo", strings.Replace(meminfo, "MemAvailable:    1000000", "MemAvailable:    3200000", 1))
+	g.Check(ctx)
+	if len(events) != 1 || !g.Report().Warned {
+		t.Fatalf("%v %+v", events, g.Report())
+	}
+	f.file("/proc/meminfo", "MemTotal: 32000000 kB\nMemAvailable: 20000000 kB\nSwapTotal: 10000000 kB\nSwapFree: 9000000 kB\n")
+	g.Check(ctx)
+	if strings.Join(events, ",") != "pressure.high,pressure.cleared" || g.Report().Warned {
+		t.Fatalf("%v", events)
+	}
+}
+
+func TestADesktopThatCannotBeReachedIsSaidAndTheEventStillGoes(t *testing.T) {
+	f := newFake(t)
+	m := f.machineWith(meminfo, calm)
+	var events []string
+	g := NewGuard(m, func(t string, _ any) error { events = append(events, t); return nil })
+	g.notify = func(context.Context, string, string) error { return errors.New("no session bus at /run/user/1000/bus") }
+	g.Check(context.Background())
+	if r := g.Report(); !strings.HasPrefix(r.Desktop, "not reached") || len(events) != 1 {
+		t.Fatalf("%+v %v", r, events)
+	}
+}
+
+func TestTheNotificationIsOneBusctlCallOnTheAccountsBus(t *testing.T) {
+	f := newFake(t)
+	g := NewGuard(f.machine(), nil)
+	bus, err := Bus()
+	if err != nil {
+		t.Skip(err)
+	}
+	err = g.desktopNotify(context.Background(), "s", "b")
+	calls := f.callsLike("env DBUS_SESSION_BUS_ADDRESS=unix:path=" + bus + " busctl --user call org.freedesktop.Notifications")
+	if err == nil && len(calls) != 1 {
+		t.Fatalf("%v", f.calls)
+	}
+	if err != nil && !strings.Contains(err.Error(), "no session bus") {
+		t.Fatal(err)
+	}
+}
+
+func TestTheLargestAreSummedByTheUnitOomdChoosesAmong(t *testing.T) {
+	ps := []Process{
+		{PID: 1, Name: "firefox", RSSMiB: 600, Unit: "session-1.scope"},
+		{PID: 2, Name: "Isolated Web Co", RSSMiB: 900, Unit: "session-1.scope"},
+		{PID: 3, Name: "postgres", RSSMiB: 100, Unit: "docker-abc.scope"},
+	}
+	g := ByUnit(ps, 10)
+	if len(g) != 2 || g[0].Unit != "session-1.scope" || g[0].RSSMiB != 1500 || g[0].Largest != "Isolated Web Co" || g[0].Processes != 2 {
+		t.Fatalf("%+v", g)
+	}
+	if top := Top(ps, 1); top[0].PID != 2 {
+		t.Fatalf("%+v", top)
+	}
+	if u := unitOf("0::/user.slice/user-1000.slice/user@1000.service/app.slice/app-foot-123.scope\n"); u != "app-foot-123.scope" {
+		t.Fatal(u)
+	}
+}
+
+func TestTheJournalIsReadForEveryKindOfKillAndSinceIsChecked(t *testing.T) {
+	journal := strings.Join([]string{
+		`{"__REALTIME_TIMESTAMP":"1759500000000000","MESSAGE":"Out of memory: Killed process 4242 (firefox) total-vm:1kB","_TRANSPORT":"kernel"}`,
+		`{"__REALTIME_TIMESTAMP":"1759600000000000","MESSAGE":"Killed /user.slice/user-1000.slice/session-1.scope due to memory pressure for /user.slice being 84.12% > 80.00% for > 20s with reclaim activity","_SYSTEMD_UNIT":"systemd-oomd.service"}`,
+		`{"__REALTIME_TIMESTAMP":"1759700000000000","MESSAGE":"docker.service: A process of this unit has been killed by the OOM killer.","_SYSTEMD_UNIT":"init.scope"}`,
+		`{"__REALTIME_TIMESTAMP":"1759800000000000","MESSAGE":"Killed something else entirely","_SYSTEMD_UNIT":"bash.service"}`,
+		`{"MESSAGE":[1,2,3]}`,
+	}, "\n")
+	kills := ParseJournal(journal)
+	if len(kills) != 3 || kills[0].By != "service manager" || kills[0].Victim != "docker.service" ||
+		kills[1].By != "systemd-oomd" || kills[2].Victim != "firefox (pid 4242)" || kills[2].Time.Year() != 2025 {
+		t.Fatalf("%+v", kills)
+	}
+	f := newFake(t)
+	m := f.machine()
+	if _, err := m.OOMHistory(context.Background(), "--output=x", 10); err == nil {
+		t.Fatal("an option was passed as since")
+	}
+	f.fails["journalctl --no-pager -q -o json --since -7 days -g Out of memory: Killed process|Killed .* due to|has been killed by the OOM killer"] = errors.New("journalctl: exit status 1")
+	k, err := m.OOMHistory(context.Background(), "7d", 10)
+	if err != nil || len(k) != 0 {
+		t.Fatalf("no match is no kills: %v %v", k, err)
+	}
+	_ = time.Now
+}
@@ -0,0 +1,129 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Kill is one thing the machine killed for memory, from the journal.
+type Kill struct {
+	Time    time.Time `json:"time"`
+	By      string    `json:"by"`
+	Victim  string    `json:"victim,omitempty"`
+	Message string    `json:"message"`
+}
+
+// The three voices that report a kill: the kernel's OOM killer, systemd-oomd, and the service manager
+// saying one of its units lost a process to the OOM killer.
+var (
+	kernelKill = regexp.MustCompile(`Out of memory: Killed process (\d+) \(([^)]*)\)`)
+	oomdKill   = regexp.MustCompile(`Killed (\S+) due to (.+)`)
+	unitKilled = regexp.MustCompile(`^(\S+): A process of this unit has been killed by the OOM killer`)
+)
+
+// sinceArg is a value journalctl understands after --since; anything else is refused before it
+// reaches the command line.
+var sinceArg = regexp.MustCompile(`^(-?\d+[smhdw]|today|yesterday|\d{4}-\d{2}-\d{2}( \d{2}:\d{2}(:\d{2})?)?)$`)
+
+// ParseJournal reads `journalctl -o json` lines into kills, newest first.
+func ParseJournal(text string) []Kill {
+	var out []Kill
+	for _, line := range strings.Split(text, "\n") {
+		if strings.TrimSpace(line) == "" {
+			continue
+		}
+		var e map[string]any
+		if json.Unmarshal([]byte(line), &e) != nil {
+			continue
+		}
+		msg, ok := e["MESSAGE"].(string) // a message that is not UTF-8 arrives as bytes; not one of these
+		if !ok {
+			continue
+		}
+		var k Kill
+		if us, err := strconv.ParseInt(fmt.Sprint(e["__REALTIME_TIMESTAMP"]), 10, 64); err == nil {
+			k.Time = time.UnixMicro(us).UTC()
+		}
+		switch {
+		case kernelKill.MatchString(msg):
+			g := kernelKill.FindStringSubmatch(msg)
+			k.By, k.Victim = "kernel", g[2]+" (pid "+g[1]+")"
+		case oomdKill.MatchString(msg) && strings.Contains(fmt.Sprint(e["_SYSTEMD_UNIT"], e["SYSLOG_IDENTIFIER"]), "oomd"):
+			g := oomdKill.FindStringSubmatch(msg)
+			k.By, k.Victim = "systemd-oomd", g[1]
+		case unitKilled.MatchString(msg):
+			k.By, k.Victim = "service manager", unitKilled.FindStringSubmatch(msg)[1]
+		default:
+			continue
+		}
+		k.Message = msg
+		out = append(out, k)
+	}
+	sort.SliceStable(out, func(i, j int) bool { return out[i].Time.After(out[j].Time) })
+	return out
+}
+
+// OOMHistory searches the journal since a time for every kill.
+func (m *Machine) OOMHistory(ctx context.Context, since string, limit int) ([]Kill, error) {
+	if !sinceArg.MatchString(since) {
+		return nil, fmt.Errorf("since %q is not -7d, 12h, today, yesterday or a date (2026-10-01)", since)
+	}
+	since = expandRelative(since)
+	out, err := m.Run(ctx, "journalctl", "--no-pager", "-q", "-o", "json", "--since", since,
+		"-g", "Out of memory: Killed process|Killed .* due to|has been killed by the OOM killer")
+	if err != nil && strings.TrimSpace(out) == "" {
+		if strings.HasSuffix(err.Error(), "exit status 1") {
+			return []Kill{}, nil // journalctl exits 1 when a grep matches nothing
+		}
+		return nil, err
+	}
+	kills := ParseJournal(out)
+	if kills == nil {
+		kills = []Kill{}
+	}
+	if len(kills) > limit {
+		kills = kills[:limit]
+	}
+	return kills, nil
+}
+
+// expandRelative turns -7d (or 7d) into the "-7 days" form journalctl's --since reads.
+func expandRelative(s string) string {
+	g := regexp.MustCompile(`^-?(\d+)([smhdw])$`).FindStringSubmatch(s)
+	if g == nil {
+		return s
+	}
+	unit := map[string]string{"s": "seconds", "m": "minutes", "h": "hours", "d": "days", "w": "weeks"}[g[2]]
+	return "-" + g[1] + " " + unit
+}
+
+// Oomd is what systemd-oomd says it watches.
+type Oomd struct {
+	Active  string   `json:"active"`
+	Enabled string   `json:"enabled"`
+	Report  []string `json:"oomctl"`
+	Note    string   `json:"note,omitempty"`
+}
+
+func (m *Machine) Oomd(ctx context.Context) Oomd {
+	o := Oomd{Report: []string{}}
+	a, _ := m.Run(ctx, "systemctl", "is-active", "systemd-oomd.service")
+	e, _ := m.Run(ctx, "systemctl", "is-enabled", "systemd-oomd.service")
+	o.Active, o.Enabled = strings.TrimSpace(a), strings.TrimSpace(e)
+	out, err := m.Run(ctx, "oomctl")
+	if err != nil {
+		o.Note = "oomctl: " + err.Error()
+	}
+	for _, line := range strings.Split(out, "\n") {
+		if strings.TrimSpace(line) != "" {
+			o.Report = append(o.Report, strings.TrimRight(strings.ReplaceAll(line, "\t", "  "), " "))
+		}
+	}
+	return o
+}
@@ -0,0 +1,145 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"strconv"
+	"strings"
+
+	stdio "git.novox.be/novox/mesh-sdk/go"
+)
+
+// Tools is the module's tools over one machine and its guard.
+func Tools(m *Machine, g *Guard) []stdio.Tool {
+	ctx := context.Background
+	return []stdio.Tool{
+		{
+			Name: "memory_status",
+			Description: "Memory now: RAM total, available and used, swap and each swap device with its priority, the compressed swap in RAM " +
+				"(zram) and its ratio, and pressure stall (PSI some/full, avg10/60/300) — with the guard's verdict on it.",
+			Run: func(map[string]any) (any, error) {
+				s, err := m.Snapshot()
+				if err != nil {
+					return nil, err
+				}
+				return map[string]any{"memory": s, "verdict": Judge(s)}, nil
+			},
+		},
+		{
+			Name:        "memory_top",
+			Description: "The largest processes by resident plus swapped memory, with the systemd unit each runs in; by=unit sums them per unit, which is what systemd-oomd chooses among.",
+			Input: map[string]any{
+				"limit": map[string]any{"type": "integer", "description": "how many (default 10, at most 50)"},
+				"by":    map[string]any{"type": "string", "enum": []string{"process", "unit"}},
+			},
+			Run: func(args map[string]any) (any, error) {
+				limit, err := bounded(args, "limit", 10, 50)
+				if err != nil {
+					return nil, err
+				}
+				ps := m.Processes()
+				switch str(args, "by") {
+				case "", "process":
+					return map[string]any{"processes": orEmpty(Top(ps, limit))}, nil
+				case "unit":
+					return map[string]any{"units": orEmpty(ByUnit(ps, limit))}, nil
+				}
+				return nil, fmt.Errorf("by is process or unit")
+			},
+		},
+		{
+			Name:        "memory_oom_history",
+			Description: "What was killed for memory, newest first, from the journal: the kernel's OOM killer, systemd-oomd, and units the service manager says lost a process to it.",
+			Input: map[string]any{
+				"since": map[string]any{"type": "string", "description": "-7d (default), 12h, today, yesterday or a date like 2026-10-01"},
+				"limit": map[string]any{"type": "integer", "description": "how many (default 20, at most 100)"},
+			},
+			Run: func(args map[string]any) (any, error) {
+				limit, err := bounded(args, "limit", 20, 100)
+				if err != nil {
+					return nil, err
+				}
+				since := str(args, "since")
+				if since == "" {
+					since = "-7d"
+				}
+				kills, err := m.OOMHistory(ctx(), since, limit)
+				if err != nil {
+					return nil, err
+				}
+				return map[string]any{"since": since, "kills": kills}, nil
+			},
+		},
+		{
+			Name:        "memory_zram",
+			Description: "The compressed swap in RAM: each zram device's algorithm, size, what it stores, what that costs in RAM and the ratio, the generator's configuration, and the swap tunables beside it.",
+			Run: func(map[string]any) (any, error) {
+				return map[string]any{
+					"devices":       m.Zram(),
+					"configuration": m.read("/etc/systemd/zram-generator.conf"),
+					"vm": map[string]string{
+						"swappiness":   m.read("/proc/sys/vm/swappiness"),
+						"page-cluster": m.read("/proc/sys/vm/page-cluster"),
+					},
+					"note": "a change to the configuration applies at the next boot: swapping the device off to resize it would push what it holds back into RAM",
+				}, nil
+			},
+		},
+		{
+			Name:        "memory_oomd",
+			Description: "systemd-oomd: whether it runs, and what it watches — the cgroups, their limits and their pressure, as oomctl reports them.",
+			Run:         func(map[string]any) (any, error) { return m.Oomd(ctx()), nil },
+		},
+		{
+			Name:        "memory_guard",
+			Description: "The module's guard that warns before the machine kills for memory: its thresholds, its last verdict, whether a warning stands, and whether the operator's desktop can be reached.",
+			Run: func(map[string]any) (any, error) {
+				if g == nil {
+					return nil, fmt.Errorf("the guard does not run in this process")
+				}
+				return g.Report(), nil
+			},
+		},
+	}
+}
+
+func str(args map[string]any, key string) string {
+	s, _ := args[key].(string)
+	return strings.TrimSpace(s)
+}
+
+// bounded is an integer argument, defaulted, at least 1 and at most most.
+func bounded(args map[string]any, key string, fallback, most int) (int, error) {
+	v, given := args[key]
+	if !given || v == nil {
+		return fallback, nil
+	}
+	var n int
+	switch x := v.(type) {
+	case float64:
+		if x != math.Trunc(x) {
+			return 0, fmt.Errorf("%s must be a whole number, not %v", key, x)
+		}
+		n = int(x)
+	case string:
+		i, err := strconv.Atoi(strings.TrimSpace(x))
+		if err != nil {
+			return 0, fmt.Errorf("%s must be a whole number, not %q", key, x)
+		}
+		n = i
+	default:
+		return 0, fmt.Errorf("%s must be a whole number", key)
+	}
+	if n < 1 {
+		return 0, fmt.Errorf("%s must be at least 1", key)
+	}
+	return min(n, most), nil
+}
+
+func orEmpty[T any](s []T) []T {
+	if s == nil {
+		return []T{}
+	}
+	return s
+}
@@ -0,0 +1,5 @@
+module memorypressure
+
+go 1.22
+
+require git.novox.be/novox/mesh-sdk/go v0.1.6
@@ -0,0 +1,2 @@
+git.novox.be/novox/mesh-sdk/go v0.1.6 h1:9qzdYONYbJdWcu6sxQcq9v1LI0JxcfkiKYkMUzJSkVQ=
+git.novox.be/novox/mesh-sdk/go v0.1.6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=
@@ -0,0 +1,121 @@
+{
+  "module": "memory-pressure",
+  "version": "1",
+  "capabilities": [
+    "package-manager",
+    "service-manager"
+  ],
+  "emits": [
+    "pressure.high",
+    "pressure.cleared"
+  ],
+  "tools": [
+    "memory_status",
+    "memory_top",
+    "memory_oom_history",
+    "memory_zram",
+    "memory_oomd",
+    "memory_guard"
+  ],
+  "resources": [
+    {
+      "id": "zram-generator",
+      "type": "package",
+      "package": "zram-generator"
+    },
+    {
+      "id": "zram",
+      "type": "file",
+      "path": "/etc/systemd/zram-generator.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module memory-pressure). Replaced on every push; edit the catalogue instead.\n#\n# Compressed swap in RAM: fast, at a higher priority than any swap on disk, so it takes the everyday\n# pressure before anything spills to a disk. Half the RAM, at most 16 GiB, compressed with zstd.\n# The swap on disk, its size and whether one exists at all are the machine's, not this module's.\n#\n# Read by the generator at boot: a change applies at the next boot.\n[zram0]\nzram-size = min(ram / 2, 16384)\ncompression-algorithm = zstd\nswap-priority = 100\n"
+    },
+    {
+      "id": "sysctl-drop-ins",
+      "type": "directory",
+      "path": "/etc/sysctl.d",
+      "mode": "0755"
+    },
+    {
+      "id": "swap-tunables",
+      "type": "file",
+      "path": "/etc/sysctl.d/90-memory-pressure.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module memory-pressure). Replaced on every push; edit the catalogue instead.\n#\n# Swap-in reads one page, not eight: read-ahead exists to amortise a disk's seek, and compressed swap in\n# RAM has none — the speculation only costs decompression and memory.\nvm.page-cluster = 0\n#\n# vm.swappiness is deliberately left alone. The usual zram advice (150-180) holds only while the\n# compressed swap has room; once it is full, a higher swappiness moves pages to the disk swap, the thing\n# being avoided. Raise it only together with zram-size.\n"
+    },
+    {
+      "id": "sysctl",
+      "type": "service",
+      "unit": "systemd-sysctl.service",
+      "restart-on": [
+        "swap-tunables"
+      ]
+    },
+    {
+      "id": "oomd-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/oomd.conf.d",
+      "mode": "0755"
+    },
+    {
+      "id": "oomd-limits",
+      "type": "file",
+      "path": "/etc/systemd/oomd.conf.d/memory-pressure.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module memory-pressure). Replaced on every push; edit the catalogue instead.\n#\n# systemd-oomd kills the worst unit before the kernel's OOM killer freezes the machine: when swap is\n# 90 % used, or when a watched unit stalls on memory for 20 s above its limit.\n[OOM]\nSwapUsedLimit=90%\nDefaultMemoryPressureLimit=60%\nDefaultMemoryPressureDurationSec=20s\n"
+    },
+    {
+      "id": "root-slice-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/-.slice.d",
+      "mode": "0755"
+    },
+    {
+      "id": "root-slice",
+      "type": "file",
+      "path": "/etc/systemd/system/-.slice.d/10-oomd.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module memory-pressure). Replaced on every push; edit the catalogue instead.\n#\n# systemd-oomd may act on swap exhaustion across the whole machine.\n[Slice]\nManagedOOMSwap=kill\n"
+    },
+    {
+      "id": "user-manager-drop-ins",
+      "type": "directory",
+      "path": "/etc/systemd/system/user@.service.d",
+      "mode": "0755"
+    },
+    {
+      "id": "user-manager",
+      "type": "file",
+      "path": "/etc/systemd/system/user@.service.d/10-oomd.conf",
+      "mode": "0644",
+      "content": "# Managed by the mesh (module memory-pressure). Replaced on every push; edit the catalogue instead.\n#\n# systemd-oomd may kill the worst unit in a person's service manager when its memory pressure stays\n# above 80 % — instead of the kernel freezing the machine.\n[Service]\nManagedOOMMemoryPressure=kill\nManagedOOMMemoryPressureLimit=80%\n"
+    },
+    {
+      "id": "oomd",
+      "type": "service",
+      "unit": "systemd-oomd.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "oomd-limits",
+        "root-slice",
+        "user-manager"
+      ]
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "tools-go",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/memory-pressure",
+        "binary": "memory-pressure",
+        "loads": [
+          "memory-pressure"
+        ]
+      }
+    ]
+  }
+}
@@ -305,7 +305,7 @@ export class MinioClient {

 // **Neither the access key nor the bucket is derived here any more.** `accessKeyFor` minted an id
 // of its own until the mesh took that over (ADR 0048: the login is the mesh's, handed to both
-// ends), and `bucketFor` derived the bucket until the mesh took that over too (ADR 0202: the rule
+// ends), and `bucketFor` derived the bucket until the mesh took that over too (ADR 0201: the rule
 // is a line of this module's manifest, filled per consumer and delivered to both ends). Both
 // survived with no callers, which is the state a rule comes back from; they are gone.

@@ -12,7 +12,7 @@
 // creates the service account under exactly that access key with exactly that secret — a credential
 // the provisioner invented is one the consumer could never present.
 //
-// **The bucket name is the mesh's too (ADR 0202).** It used to be computed here, from the login,
+// **The bucket name is the mesh's too (ADR 0201).** It used to be computed here, from the login,
 // and every consumer transcribed the same rule into its own definition by hand — two copies of
 // one rule with nothing comparing them, and one of three was wrong for months. Now the rule is a
 // line of this module's manifest (`serves.s3-bucket.bucket: ${consumer:as:dns}`), the mesh fills
@@ -79,7 +79,7 @@ function bucketNamed(derived: Readonly<Record<string, unknown>>): string {
  if (typeof bucket !== "string" || bucket === "") {
    throw new Error(
      "the mesh did not say which bucket this consumer gets: minio's manifest must serve " +
-        "`bucket` under s3-bucket (novox/hq ADR 0202)",
+        "`bucket` under s3-bucket (novox/hq ADR 0201)",
    );
  }
  return bucket;
@@ -0,0 +1,42 @@
+{
+  "module": "node-env",
+  "version": "1",
+  "claims": [
+    {
+      "name": "node-environment",
+      "scope": "node"
+    }
+  ],
+  "resources": [
+    {
+      "id": "mesh-config-dir",
+      "type": "directory",
+      "path": "${machine:account-home}/.config/mesh",
+      "owner": "${machine:account}",
+      "mode": "0755"
+    },
+    {
+      "id": "environment-d",
+      "type": "directory",
+      "path": "${machine:account-home}/.config/environment.d",
+      "owner": "${machine:account}",
+      "mode": "0755"
+    },
+    {
+      "id": "posix",
+      "type": "file",
+      "path": "${machine:account-home}/.config/mesh/environment.sh",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# The operator account's environment, generated by the mesh (module node-env, novox/hq ADR 0203).\n# Do not edit: this file is replaced at every push. Every line names the module that contributed it.\n# Sourced by the login shell from its always-read startup file (for zsh, ~/.zshenv), so a script, a\n# login and the shell's execute verb all see it. Your own variables belong in your shell's own lines.\n${environment:posix}"
+    },
+    {
+      "id": "systemd",
+      "type": "file",
+      "path": "${machine:account-home}/.config/environment.d/50-mesh.conf",
+      "owner": "${machine:account}",
+      "mode": "0644",
+      "content": "# The operator account's environment for its service manager and graphical session, generated by\n# the mesh (module node-env, novox/hq ADR 0203). Do not edit: this file is replaced at every push.\n# The same facts as ~/.config/mesh/environment.sh, in environment.d(5) syntax.\n${environment:systemd}"
+    }
+  ]
+}
@@ -45,7 +45,7 @@
      "image": "registry-api.novox.be/novox/photos-client@sha256:f87d63ee7bfb44c9f9748b99be6ba6dc0daf955a1d463699e9e7e3009693c0ab",
      "network": "photos-eef",
      "ports": [
-        "80"
+        "4012:80"
      ],
      "names-on-purpose": {
        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
@@ -45,7 +45,7 @@
      "image": "registry-api.novox.be/novox/photos-client@sha256:f87d63ee7bfb44c9f9748b99be6ba6dc0daf955a1d463699e9e7e3009693c0ab",
      "network": "photos-filip",
      "ports": [
-        "80"
+        "4013:80"
      ],
      "names-on-purpose": {
        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
@@ -89,7 +89,7 @@
      "image": "registry-api.novox.be/novox/photos-admin-client@sha256:f437fa9ed28b29a012f715fb8d9b809a15cff4a672794c620d5d400f57695580",
      "network": "photos",
      "ports": [
-        "80"
+        "4001:80"
      ],
      "names-on-purpose": {
        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
@@ -0,0 +1,46 @@
+# powerlevel10k
+
+The zsh prompt as a module (novox/hq ADR 0204, ADR 0205, to-be 41).
+
+- **Upstream:** https://github.com/romkatv/powerlevel10k
+- **Version:** v1.20.0, vendored verbatim from the release archive
+  (`archive/refs/tags/v1.20.0.tar.gz`, sha256
+  `d8187d44b697b3a37a8c4896678b4380e717cbf2850179529358348780a2d3d7`) into `theme/`. It is 86
+  files and 1,427,736 bytes.
+- **Licence:** MIT, in `theme/LICENSE`, which travels in the archive. gitstatus's own licence is
+  `theme/gitstatus/LICENSE`.
+
+The distribution does not package the theme, so the module carries a pinned release (ADR 0205). An
+upgrade is a change to this directory, reviewed like any other: replace `theme/` with the new
+release's contents, and update the version here and in the shell code's comment.
+
+## What it places
+
+| path under the account's home | what | class (ADR 0182) |
+|---|---|---|
+| `~/.local/share/powerlevel10k/` | the theme, unpacked from the `theme` archive | owned, whole |
+| `~/.config/powerlevel10k/p10k.zsh` | the prompt's configuration, unpacked from the `configuration` archive | owned, whole |
+
+The configuration is today's `~/.p10k.zsh`, byte for byte. It is the predecessor's file, and was
+identical on every machine. It ships as an archive of one file rather than as an inline file. At
+86 KB, inline content would ride in every declaration the node receives, and would be unreadable
+JSON in review. As its own file it is reviewed as a diff, and pinned by digest like the theme. The
+directory is the module's, so `p10k configure` writing `~/.p10k.zsh` does not touch it: to change
+the prompt, change `config/p10k.zsh` here.
+
+The module contributes zsh code to the `normal` slot of the login shell's block. That code sources
+the theme, then the configuration, each only if present. Instant prompt is not turned on: the
+operator's `.zshrc` has its cache line commented out today, and the configuration's own
+`POWERLEVEL9K_INSTANT_PROMPT` setting does nothing without that line.
+
+## What it does not do
+
+- **gitstatus downloads its binary on first use.** The theme's git status helper fetches
+  `gitstatusd` from upstream's releases into `~/.cache/gitstatus` the first time a prompt runs in a
+  git repository. ADR 0205 pins what the mesh ships, not what the software fetches for itself. A
+  machine without a route to upstream shows the prompt without git status.
+- **Fonts are not this module's.** The configuration uses Nerd Font icons. The terminal's font is the
+  desktop's concern.
+- **Moving from the predecessor:** once this module is assigned, `~/.zsh/themes/powerlevel10k` and
+  `~/.p10k.zsh` are no longer read, and the operator removes them, once (ADR 0182; the zsh module's
+  README lists the lines to delete from `.zshrc`).
@@ -0,0 +1,41 @@
+{
+  "module": "powerlevel10k",
+  "version": "1",
+  "shell": [
+    {
+      "for": "zsh",
+      "slot": "normal",
+      "code": "# The prompt: powerlevel10k v1.20.0, pinned in this module (novox/hq ADR 0205), and its configuration.\n[[ ! -f ~/.local/share/powerlevel10k/powerlevel10k.zsh-theme ]] || source ~/.local/share/powerlevel10k/powerlevel10k.zsh-theme\n[[ ! -f ~/.config/powerlevel10k/p10k.zsh ]] || source ~/.config/powerlevel10k/p10k.zsh\n"
+    }
+  ],
+  "resources": [
+    {
+      "id": "theme",
+      "type": "archive",
+      "path": "${machine:account-home}/.local/share/powerlevel10k",
+      "owner": "${machine:account}",
+      "artifact": "theme"
+    },
+    {
+      "id": "configuration",
+      "type": "archive",
+      "path": "${machine:account-home}/.config/powerlevel10k",
+      "owner": "${machine:account}",
+      "artifact": "configuration"
+    }
+  ],
+  "build": {
+    "artifacts": [
+      {
+        "name": "theme",
+        "kind": "archive",
+        "from": "theme"
+      },
+      {
+        "name": "configuration",
+        "kind": "archive",
+        "from": "config"
+      }
+    ]
+  }
+}
@@ -0,0 +1,13 @@
+{
+  "name": "@novox/module-powerlevel10k",
+  "version": "0.1.0",
+  "description": "powerlevel10k \u2014 the zsh prompt as a module: upstream v1.20.0 vendored and shipped as a pinned archive, its configuration as a second, and the zsh code that loads both in the normal slot (novox/hq ADR 0204, ADR 0205).",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  }
+}
@@ -0,0 +1,45 @@
+// The prompt module's shape (novox/hq ADR 0204, ADR 0205): the vendored release is pinned, carries
+// its licence in the archive, and is loaded with its configuration from the normal slot.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync, statSync } from "node:fs";
+
+const at = (p: string) => new URL(`../${p}`, import.meta.url);
+const m = JSON.parse(readFileSync(at("module.json"), "utf8"));
+const artifact = (name: string) => m.build.artifacts.find((a: { name: string }) => a.name === name);
+
+test("the theme archive is built from the vendored release and carries its licence", () => {
+  assert.deepEqual(artifact("theme"), { name: "theme", kind: "archive", from: "theme" });
+  assert.match(readFileSync(at("theme/LICENSE"), "utf8"), /Permission is hereby granted, free of charge/);
+  assert.ok(existsSync(at("theme/powerlevel10k.zsh-theme")));
+  assert.ok(existsSync(at("theme/gitstatus/LICENSE")));
+});
+
+test("the configuration archive holds the prompt's configuration and nothing else", () => {
+  assert.deepEqual(artifact("configuration"), { name: "configuration", kind: "archive", from: "config" });
+  assert.ok(statSync(at("config/p10k.zsh")).size > 0);
+});
+
+test("both are unpacked under the account's home, owned by the account", () => {
+  const byId = Object.fromEntries(m.resources.map((r: { id: string }) => [r.id, r]));
+  assert.deepEqual(byId.theme, { id: "theme", type: "archive", path: "${machine:account-home}/.local/share/powerlevel10k", owner: "${machine:account}", artifact: "theme" });
+  assert.deepEqual(byId.configuration, { id: "configuration", type: "archive", path: "${machine:account-home}/.config/powerlevel10k", owner: "${machine:account}", artifact: "configuration" });
+});
+
+test("the zsh code in the normal slot sources the theme, then the configuration, and turns on no instant prompt", () => {
+  assert.equal(m.shell.length, 1);
+  const [c] = m.shell;
+  assert.equal(c.for, "zsh");
+  assert.equal(c.slot, "normal");
+  const sourced = [...(c.code as string).matchAll(/\|\| source (\S+)/g)].map((x) => x[1]);
+  assert.deepEqual(sourced, ["~/.local/share/powerlevel10k/powerlevel10k.zsh-theme", "~/.config/powerlevel10k/p10k.zsh"]);
+  assert.doesNotMatch(c.code, /instant/);
+});
+
+test("the README names the upstream, the version and the licence", () => {
+  const readme = readFileSync(at("README.md"), "utf8");
+  assert.match(readme, /github\.com\/romkatv\/powerlevel10k/);
+  assert.match(readme, /v1\.20\.0/);
+  assert.match(readme, /MIT/);
+  assert.match(m.shell[0].code, /v1\.20\.0/, "the version in the shell code's comment matches");
+});
@@ -0,0 +1,5 @@
+* text=auto
+*.zsh text eol=lf
+*.zsh-theme text eol=lf
+/prompt_powerlevel9k_setup text eol=lf
+/prompt_powerlevel10k_setup text eol=lf
@@ -0,0 +1 @@
+*.zwc
@@ -0,0 +1,22 @@
+Copyright (c) 2009-2014 Robby Russell and contributors (see https://github.com/robbyrussell/oh-my-zsh/contributors)
+Copyright (c) 2014-2017 Ben Hilburn <bhilburn@gmail.com>
+Copyright (c) 2019 Roman Perepelitsa <roman.perepelitsa@gmail.com> and contributors (see https://github.com/romkatv/powerlevel10k/contributors)
+
+MIT LICENSE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,14 @@
+ZSH := $(shell command -v zsh 2> /dev/null)
+
+all:
+
+zwc:
+	$(MAKE) -C gitstatus zwc
+	$(or $(ZSH),:) -fc 'for f in *.zsh-theme internal/*.zsh; do zcompile -R -- $$f.zwc $$f || exit; done'
+
+minify:
+	$(MAKE) -C gitstatus minify
+	rm -rf -- .git .gitattributes .gitignore LICENSE Makefile README.md font.md powerlevel10k.png
+
+pkg: zwc
+	$(MAKE) -C gitstatus pkg
@@ -0,0 +1,193 @@
+# Config file for Powerlevel10k with the style of Pure (https://github.com/sindresorhus/pure).
+#
+# Differences from Pure:
+#
+#   - Git:
+#     - `@c4d3ec2c` instead of something like `v1.4.0~11` when in detached HEAD state.
+#     - No automatic `git fetch` (the same as in Pure with `PURE_GIT_PULL=0`).
+#
+# Apart from the differences listed above, the replication of Pure prompt is exact. This includes
+# even the questionable parts. For example, just like in Pure, there is no indication of Git status
+# being stale; prompt symbol is the same in command, visual and overwrite vi modes; when prompt
+# doesn't fit on one line, it wraps around with no attempt to shorten it.
+#
+# If you like the general style of Pure but not particularly attached to all its quirks, type
+# `p10k configure` and pick "Lean" style. This will give you slick minimalist prompt while taking
+# advantage of Powerlevel10k features that aren't present in Pure.
+
+# Temporarily change options.
+'builtin' 'local' '-a' 'p10k_config_opts'
+[[ ! -o 'aliases'         ]] || p10k_config_opts+=('aliases')
+[[ ! -o 'sh_glob'         ]] || p10k_config_opts+=('sh_glob')
+[[ ! -o 'no_brace_expand' ]] || p10k_config_opts+=('no_brace_expand')
+'builtin' 'setopt' 'no_aliases' 'no_sh_glob' 'brace_expand'
+
+() {
+  emulate -L zsh -o extended_glob
+
+  # Unset all configuration options.
+  unset -m '(POWERLEVEL9K_*|DEFAULT_USER)~POWERLEVEL9K_GITSTATUS_DIR'
+
+  # Zsh >= 5.1 is required.
+  [[ $ZSH_VERSION == (5.<1->*|<6->.*) ]] || return
+
+  # Prompt colors.
+  local grey=242
+  local red=1
+  local yellow=3
+  local blue=4
+  local magenta=5
+  local cyan=6
+  local white=7
+
+  # Left prompt segments.
+  typeset -g POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(
+    # =========================[ Line #1 ]=========================
+    context                   # user@host
+    dir                       # current directory
+    vcs                       # git status
+    command_execution_time    # previous command duration
+    # =========================[ Line #2 ]=========================
+    newline                   # \n
+    virtualenv                # python virtual environment
+    prompt_char               # prompt symbol
+  )
+
+  # Right prompt segments.
+  typeset -g POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=(
+    # =========================[ Line #1 ]=========================
+    # command_execution_time  # previous command duration
+    # virtualenv              # python virtual environment
+    # context                 # user@host
+    # time                    # current time
+    # =========================[ Line #2 ]=========================
+    newline                   # \n
+  )
+
+  # Basic style options that define the overall prompt look.
+  typeset -g POWERLEVEL9K_BACKGROUND=                            # transparent background
+  typeset -g POWERLEVEL9K_{LEFT,RIGHT}_{LEFT,RIGHT}_WHITESPACE=  # no surrounding whitespace
+  typeset -g POWERLEVEL9K_{LEFT,RIGHT}_SUBSEGMENT_SEPARATOR=' '  # separate segments with a space
+  typeset -g POWERLEVEL9K_{LEFT,RIGHT}_SEGMENT_SEPARATOR=        # no end-of-line symbol
+  typeset -g POWERLEVEL9K_VISUAL_IDENTIFIER_EXPANSION=           # no segment icons
+
+  # Add an empty line before each prompt except the first. This doesn't emulate the bug
+  # in Pure that makes prompt drift down whenever you use the Alt-C binding from fzf or similar.
+  typeset -g POWERLEVEL9K_PROMPT_ADD_NEWLINE=true
+
+  # Magenta prompt symbol if the last command succeeded.
+  typeset -g POWERLEVEL9K_PROMPT_CHAR_OK_{VIINS,VICMD,VIVIS}_FOREGROUND=$magenta
+  # Red prompt symbol if the last command failed.
+  typeset -g POWERLEVEL9K_PROMPT_CHAR_ERROR_{VIINS,VICMD,VIVIS}_FOREGROUND=$red
+  # Default prompt symbol.
+  typeset -g POWERLEVEL9K_PROMPT_CHAR_{OK,ERROR}_VIINS_CONTENT_EXPANSION='❯'
+  # Prompt symbol in command vi mode.
+  typeset -g POWERLEVEL9K_PROMPT_CHAR_{OK,ERROR}_VICMD_CONTENT_EXPANSION='❮'
+  # Prompt symbol in visual vi mode is the same as in command mode.
+  typeset -g POWERLEVEL9K_PROMPT_CHAR_{OK,ERROR}_VIVIS_CONTENT_EXPANSION='❮'
+  # Prompt symbol in overwrite vi mode is the same as in command mode.
+  typeset -g POWERLEVEL9K_PROMPT_CHAR_OVERWRITE_STATE=false
+
+  # Grey Python Virtual Environment.
+  typeset -g POWERLEVEL9K_VIRTUALENV_FOREGROUND=$grey
+  # Don't show Python version.
+  typeset -g POWERLEVEL9K_VIRTUALENV_SHOW_PYTHON_VERSION=false
+  typeset -g POWERLEVEL9K_VIRTUALENV_{LEFT,RIGHT}_DELIMITER=
+
+  # Blue current directory.
+  typeset -g POWERLEVEL9K_DIR_FOREGROUND=$blue
+
+  # Context format when root: user@host. The first part white, the rest grey.
+  typeset -g POWERLEVEL9K_CONTEXT_ROOT_TEMPLATE="%F{$white}%n%f%F{$grey}@%m%f"
+  # Context format when not root: user@host. The whole thing grey.
+  typeset -g POWERLEVEL9K_CONTEXT_TEMPLATE="%F{$grey}%n@%m%f"
+  # Don't show context unless root or in SSH.
+  typeset -g POWERLEVEL9K_CONTEXT_{DEFAULT,SUDO}_CONTENT_EXPANSION=
+
+  # Show previous command duration only if it's >= 5s.
+  typeset -g POWERLEVEL9K_COMMAND_EXECUTION_TIME_THRESHOLD=5
+  # Don't show fractional seconds. Thus, 7s rather than 7.3s.
+  typeset -g POWERLEVEL9K_COMMAND_EXECUTION_TIME_PRECISION=0
+  # Duration format: 1d 2h 3m 4s.
+  typeset -g POWERLEVEL9K_COMMAND_EXECUTION_TIME_FORMAT='d h m s'
+  # Yellow previous command duration.
+  typeset -g POWERLEVEL9K_COMMAND_EXECUTION_TIME_FOREGROUND=$yellow
+
+  # Grey Git prompt. This makes stale prompts indistinguishable from up-to-date ones.
+  typeset -g POWERLEVEL9K_VCS_FOREGROUND=$grey
+
+  # Disable async loading indicator to make directories that aren't Git repositories
+  # indistinguishable from large Git repositories without known state.
+  typeset -g POWERLEVEL9K_VCS_LOADING_TEXT=
+
+  # Don't wait for Git status even for a millisecond, so that prompt always updates
+  # asynchronously when Git state changes.
+  typeset -g POWERLEVEL9K_VCS_MAX_SYNC_LATENCY_SECONDS=0
+
+  # Cyan ahead/behind arrows.
+  typeset -g POWERLEVEL9K_VCS_{INCOMING,OUTGOING}_CHANGESFORMAT_FOREGROUND=$cyan
+  # Don't show remote branch, current tag or stashes.
+  typeset -g POWERLEVEL9K_VCS_GIT_HOOKS=(vcs-detect-changes git-untracked git-aheadbehind)
+  # Don't show the branch icon.
+  typeset -g POWERLEVEL9K_VCS_BRANCH_ICON=
+  # When in detached HEAD state, show @commit where branch normally goes.
+  typeset -g POWERLEVEL9K_VCS_COMMIT_ICON='@'
+  # Don't show staged, unstaged, untracked indicators.
+  typeset -g POWERLEVEL9K_VCS_{STAGED,UNSTAGED,UNTRACKED}_ICON=
+  # Show '*' when there are staged, unstaged or untracked files.
+  typeset -g POWERLEVEL9K_VCS_DIRTY_ICON='*'
+  # Show '⇣' if local branch is behind remote.
+  typeset -g POWERLEVEL9K_VCS_INCOMING_CHANGES_ICON=':⇣'
+  # Show '⇡' if local branch is ahead of remote.
+  typeset -g POWERLEVEL9K_VCS_OUTGOING_CHANGES_ICON=':⇡'
+  # Don't show the number of commits next to the ahead/behind arrows.
+  typeset -g POWERLEVEL9K_VCS_{COMMITS_AHEAD,COMMITS_BEHIND}_MAX_NUM=1
+  # Remove space between '⇣' and '⇡' and all trailing spaces.
+  typeset -g POWERLEVEL9K_VCS_CONTENT_EXPANSION='${${${P9K_CONTENT/⇣* :⇡/⇣⇡}// }//:/ }'
+
+  # Grey current time.
+  typeset -g POWERLEVEL9K_TIME_FOREGROUND=$grey
+  # Format for the current time: 09:51:02. See `man 3 strftime`.
+  typeset -g POWERLEVEL9K_TIME_FORMAT='%D{%H:%M:%S}'
+  # If set to true, time will update when you hit enter. This way prompts for the past
+  # commands will contain the start times of their commands rather than the end times of
+  # their preceding commands.
+  typeset -g POWERLEVEL9K_TIME_UPDATE_ON_COMMAND=false
+
+  # Transient prompt works similarly to the builtin transient_rprompt option. It trims down prompt
+  # when accepting a command line. Supported values:
+  #
+  #   - off:      Don't change prompt when accepting a command line.
+  #   - always:   Trim down prompt when accepting a command line.
+  #   - same-dir: Trim down prompt when accepting a command line unless this is the first command
+  #               typed after changing current working directory.
+  typeset -g POWERLEVEL9K_TRANSIENT_PROMPT=off
+
+  # Instant prompt mode.
+  #
+  #   - off:     Disable instant prompt. Choose this if you've tried instant prompt and found
+  #              it incompatible with your zsh configuration files.
+  #   - quiet:   Enable instant prompt and don't print warnings when detecting console output
+  #              during zsh initialization. Choose this if you've read and understood
+  #              https://github.com/romkatv/powerlevel10k/blob/master/README.md#instant-prompt.
+  #   - verbose: Enable instant prompt and print a warning when detecting console output during
+  #              zsh initialization. Choose this if you've never tried instant prompt, haven't
+  #              seen the warning, or if you are unsure what this all means.
+  typeset -g POWERLEVEL9K_INSTANT_PROMPT=verbose
+
+  # Hot reload allows you to change POWERLEVEL9K options after Powerlevel10k has been initialized.
+  # For example, you can type POWERLEVEL9K_BACKGROUND=red and see your prompt turn red. Hot reload
+  # can slow down prompt by 1-2 milliseconds, so it's better to keep it turned off unless you
+  # really need it.
+  typeset -g POWERLEVEL9K_DISABLE_HOT_RELOAD=true
+
+  # If p10k is already loaded, reload configuration.
+  # This works even with POWERLEVEL9K_DISABLE_HOT_RELOAD=true.
+  (( ! $+functions[p10k] )) || p10k reload
+}
+
+# Tell `p10k configure` which file it should overwrite.
+typeset -g POWERLEVEL9K_CONFIG_FILE=${${(%):-%x}:a}
+
+(( ${#p10k_config_opts} )) && setopt ${p10k_config_opts[@]}
+'builtin' 'unset' 'p10k_config_opts'
@@ -0,0 +1,111 @@
+# Config file for Powerlevel10k with the style of robbyrussell theme from Oh My Zsh.
+#
+# Original: https://github.com/ohmyzsh/ohmyzsh/wiki/Themes#robbyrussell.
+#
+# Replication of robbyrussell theme is exact. The only observable difference is in
+# performance. Powerlevel10k prompt is very fast everywhere, even in large Git repositories.
+#
+# Usage: Source this file either before or after loading Powerlevel10k.
+#
+#   source ~/powerlevel10k/config/p10k-robbyrussell.zsh
+#   source ~/powerlevel10k/powerlevel10k.zsh-theme
+
+# Temporarily change options.
+'builtin' 'local' '-a' 'p10k_config_opts'
+[[ ! -o 'aliases'         ]] || p10k_config_opts+=('aliases')
+[[ ! -o 'sh_glob'         ]] || p10k_config_opts+=('sh_glob')
+[[ ! -o 'no_brace_expand' ]] || p10k_config_opts+=('no_brace_expand')
+'builtin' 'setopt' 'no_aliases' 'no_sh_glob' 'brace_expand'
+
+() {
+  emulate -L zsh -o extended_glob
+
+  # Unset all configuration options.
+  unset -m '(POWERLEVEL9K_*|DEFAULT_USER)~POWERLEVEL9K_GITSTATUS_DIR'
+
+  # Zsh >= 5.1 is required.
+  [[ $ZSH_VERSION == (5.<1->*|<6->.*) ]] || return
+
+  # Left prompt segments.
+  typeset -g POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=(prompt_char dir vcs)
+  # Right prompt segments.
+  typeset -g POWERLEVEL9K_RIGHT_PROMPT_ELEMENTS=()
+
+  # Basic style options that define the overall prompt look.
+  typeset -g POWERLEVEL9K_BACKGROUND=                            # transparent background
+  typeset -g POWERLEVEL9K_{LEFT,RIGHT}_{LEFT,RIGHT}_WHITESPACE=  # no surrounding whitespace
+  typeset -g POWERLEVEL9K_{LEFT,RIGHT}_SUBSEGMENT_SEPARATOR=' '  # separate segments with a space
+  typeset -g POWERLEVEL9K_{LEFT,RIGHT}_SEGMENT_SEPARATOR=        # no end-of-line symbol
+  typeset -g POWERLEVEL9K_VISUAL_IDENTIFIER_EXPANSION=           # no segment icons
+
+  # Green prompt symbol if the last command succeeded.
+  typeset -g POWERLEVEL9K_PROMPT_CHAR_OK_{VIINS,VICMD,VIVIS}_FOREGROUND=green
+  # Red prompt symbol if the last command failed.
+  typeset -g POWERLEVEL9K_PROMPT_CHAR_ERROR_{VIINS,VICMD,VIVIS}_FOREGROUND=red
+  # Prompt symbol: bold arrow.
+  typeset -g POWERLEVEL9K_PROMPT_CHAR_CONTENT_EXPANSION='%B➜ '
+
+  # Cyan current directory.
+  typeset -g POWERLEVEL9K_DIR_FOREGROUND=cyan
+  # Show only the last segment of the current directory.
+  typeset -g POWERLEVEL9K_SHORTEN_STRATEGY=truncate_to_last
+  # Bold directory.
+  typeset -g POWERLEVEL9K_DIR_CONTENT_EXPANSION='%B$P9K_CONTENT'
+
+  # Git status formatter.
+  function my_git_formatter() {
+    emulate -L zsh
+    if [[ -n $P9K_CONTENT ]]; then
+      # If P9K_CONTENT is not empty, it's either "loading" or from vcs_info (not from
+      # gitstatus plugin). VCS_STATUS_* parameters are not available in this case.
+      typeset -g my_git_format=$P9K_CONTENT
+    else
+      # Use VCS_STATUS_* parameters to assemble Git status. See reference:
+      # https://github.com/romkatv/gitstatus/blob/master/gitstatus.plugin.zsh.
+      typeset -g my_git_format="${1+%B%4F}git:(${1+%1F}"
+      my_git_format+=${${VCS_STATUS_LOCAL_BRANCH:-${VCS_STATUS_COMMIT[1,8]}}//\%/%%}
+      my_git_format+="${1+%4F})"
+      if (( VCS_STATUS_NUM_CONFLICTED || VCS_STATUS_NUM_STAGED ||
+            VCS_STATUS_NUM_UNSTAGED   || VCS_STATUS_NUM_UNTRACKED )); then
+        my_git_format+=" ${1+%3F}✗"
+      fi
+    fi
+  }
+  functions -M my_git_formatter 2>/dev/null
+
+  # Disable the default Git status formatting.
+  typeset -g POWERLEVEL9K_VCS_DISABLE_GITSTATUS_FORMATTING=true
+  # Install our own Git status formatter.
+  typeset -g POWERLEVEL9K_VCS_CONTENT_EXPANSION='${$((my_git_formatter(1)))+${my_git_format}}'
+  typeset -g POWERLEVEL9K_VCS_LOADING_CONTENT_EXPANSION='${$((my_git_formatter()))+${my_git_format}}'
+  # Grey Git status when loading.
+  typeset -g POWERLEVEL9K_VCS_LOADING_FOREGROUND=246
+
+  # Instant prompt mode.
+  #
+  #   - off:     Disable instant prompt. Choose this if you've tried instant prompt and found
+  #              it incompatible with your zsh configuration files.
+  #   - quiet:   Enable instant prompt and don't print warnings when detecting console output
+  #              during zsh initialization. Choose this if you've read and understood
+  #              https://github.com/romkatv/powerlevel10k/blob/master/README.md#instant-prompt.
+  #   - verbose: Enable instant prompt and print a warning when detecting console output during
+  #              zsh initialization. Choose this if you've never tried instant prompt, haven't
+  #              seen the warning, or if you are unsure what this all means.
+  typeset -g POWERLEVEL9K_INSTANT_PROMPT=verbose
+
+  # Hot reload allows you to change POWERLEVEL9K options after Powerlevel10k has been initialized.
+  # For example, you can type POWERLEVEL9K_BACKGROUND=red and see your prompt turn red. Hot reload
+  # can slow down prompt by 1-2 milliseconds, so it's better to keep it turned off unless you
+  # really need it.
+  typeset -g POWERLEVEL9K_DISABLE_HOT_RELOAD=true
+
+  # If p10k is already loaded, reload configuration.
+  # This works even with POWERLEVEL9K_DISABLE_HOT_RELOAD=true.
+  (( ! $+functions[p10k] )) || p10k reload
+}
+
+# Tell `p10k configure` which file it should overwrite.
+typeset -g POWERLEVEL9K_CONFIG_FILE=${${(%):-%x}:a}
+
+(( ${#p10k_config_opts} )) && setopt ${p10k_config_opts[@]}
+'builtin' 'unset' 'p10k_config_opts'
@@ -0,0 +1,164 @@
+# Recommended font: Meslo Nerd Font patched for Powerlevel10k
+
+Gorgeous monospace font designed by Jim Lyles for Bitstream, customized by the same for Apple,
+further customized by André Berg, and finally patched by yours truly with customized scripts
+originally developed by Ryan L McIntyre of Nerd Fonts. Contains all glyphs and symbols that
+Powerlevel10k may need. Battle-tested in dozens of different terminals on all major operating
+systems.
+
+*FAQ*: [How was the recommended font created?](README.md#how-was-the-recommended-font-created)
+
+## Automatic font installation
+
+If you are using iTerm2 or Termux, `p10k configure` can install the recommended font for you.
+Simply answer `Yes` when asked whether to install *Meslo Nerd Font*.
+
+If you are using a different terminal, proceed with manual font installation. 👇
+
+## Manual font installation
+
+1. Download these four ttf files:
+   - [MesloLGS NF Regular.ttf](
+       https://github.com/romkatv/powerlevel10k-media/raw/master/MesloLGS%20NF%20Regular.ttf)
+   - [MesloLGS NF Bold.ttf](
+       https://github.com/romkatv/powerlevel10k-media/raw/master/MesloLGS%20NF%20Bold.ttf)
+   - [MesloLGS NF Italic.ttf](
+       https://github.com/romkatv/powerlevel10k-media/raw/master/MesloLGS%20NF%20Italic.ttf)
+   - [MesloLGS NF Bold Italic.ttf](
+       https://github.com/romkatv/powerlevel10k-media/raw/master/MesloLGS%20NF%20Bold%20Italic.ttf)
+1. Double-click on each file and click "Install". This will make `MesloLGS NF` font available to all
+   applications on your system.
+1. Configure your terminal to use this font:
+   - **iTerm2**: Type `p10k configure` and answer `Yes` when asked whether to install
+     *Meslo Nerd Font*. Alternatively, open *iTerm2 → Preferences → Profiles → Text* and set *Font* to
+     `MesloLGS NF`.
+   - **Apple Terminal**: Open *Terminal → Preferences → Profiles → Text*, click *Change* under *Font*
+     and select `MesloLGS NF` family.
+   - **Hyper**: Open *Hyper → Edit → Preferences* and change the value of `fontFamily` under
+     `module.exports.config` to `MesloLGS NF`.
+   - **Visual Studio Code**: Open *File → Preferences → Settings* (PC) or
+     *Code → Preferences → Settings* (Mac), enter `terminal.integrated.fontFamily` in the search box at
+     the top of *Settings* tab and set the value below to `MesloLGS NF`.
+     Consult [this screenshot](
+       https://raw.githubusercontent.com/romkatv/powerlevel10k-media/389133fb8c9a2347929a23702ce3039aacc46c3d/visual-studio-code-font-settings.jpg)
+     to see how it should look like or see [this issue](
+       https://github.com/romkatv/powerlevel10k/issues/671) for extra information.
+   - **GNOME Terminal** (the default Ubuntu terminal): Open *Terminal → Preferences* and click on the
+     selected profile under *Profiles*. Check *Custom font* under *Text Appearance* and select
+     `MesloLGS NF Regular`.
+   - **Konsole**: Open *Settings → Edit Current Profile → Appearance*, click *Select Font* and select
+     `MesloLGS NF Regular`.
+   - **Tilix**: Open *Tilix → Preferences* and click on the selected profile under *Profiles*. Check
+     *Custom font* under *Text Appearance* and select `MesloLGS NF Regular`.
+   - **Windows Console Host** (the old thing): Click the icon in the top left corner, then
+     *Properties → Font* and set *Font* to `MesloLGS NF`.
+   - **Windows Terminal** by Microsoft (the new thing): Open *Settings* (<kbd>Ctrl+,</kbd>), click
+     either on the selected profile under *Profiles* or on *Defaults*, click *Appearance* and set
+     *Font face* to `MesloLGS NF`.
+   - **IntelliJ** (and other IDEs by Jet Brains): Open *IDE → Edit → Preferences → Editor →
+     Color Scheme → Console Font*. Select *Use console font instead of the default* and set the font
+     name to `MesloLGS NF`.
+   - **Termux**: Type `p10k configure` and answer `Yes` when asked whether to install
+     *Meslo Nerd Font*.
+   - **Blink**: Type `config`, go to *Appearance*, tap *Add a new font*, tap *Open Gallery*, select
+     *MesloLGS NF.css*, tap *import* and type `exit` in the home view to reload the font.
+   - **Tabby** (formerly **Terminus**): Open *Settings → Appearance* and set *Font* to `MesloLGS NF`.
+   - **Terminator**: Open *Preferences* using the context menu. Under *Profiles* select the *General*
+     tab (should be selected already), uncheck *Use the system fixed width font* (if not already)
+     and select `MesloLGS NF Regular`. Exit the Preferences dialog by clicking *Close*.
+   - **Guake**: Right Click on an open terminal and open *Preferences*. Under *Appearance*
+     tab, uncheck *Use the system fixed width font* (if not already) and select `MesloLGS NF Regular`.
+     Exit the Preferences dialog by clicking *Close*.
+   - **MobaXterm**: Open *Settings* → *Configuration* → *Terminal* → (under *Terminal look and feel*)
+     and change *Font* to `MesloLGS NF`.
+   - **Asbrú Connection Manager**: Open *Preferences → Local Shell Options → Look and Feel*, enable
+     *Use these personal options* and change *Font:* under *Terminal UI* to `MesloLGS NF Regular`.
+     To change the font for the remote host connections, go to *Preferences → Terminal Options →
+     Look and Feel* and change *Font:* under *Terminal UI* to `MesloLGS NF Regular`.
+   - **WSLtty**: Right click on an open terminal and then on *Options*. In the *Text* section, under
+     *Font*, click *"Select..."* and set Font to `MesloLGS NF Regular`.
+   - **Yakuake**: Click *≡* → *Manage Profiles* → *New* → *Appearance*. Click *Choose* next to the
+     *Font* dropdown, select `MesloLGS NF` and click *OK*. Click *OK* to save the profile. Select the
+     new profile and click *Set as Default*.
+   - **Alacritty**: Create or open `~/.config/alacritty/alacritty.toml` and add the following
+     section to it:
+     ```toml
+     [font.normal]
+     family = "MesloLGS NF"
+     ```
+   - **foot**: Create or open `~/.config/foot/foot.ini` and add the following section to it:
+     ```ini
+     font=MesloLGS NF:size=12
+     ```
+   - **kitty**: Create or open `~/.config/kitty/kitty.conf` and add the following line to it:
+     ```text
+     font_family MesloLGS NF
+     ```
+     Restart kitty by closing all sessions and opening a new session.
+   - **puTTY**: Set *Window* → *Appearance* → *Font* to `MesloLGS NF`. Requires puTTY
+     version >= 0.75.
+   - **WezTerm**: Create or open `$HOME/.config/wezterm/wezterm.lua` and add the following:
+     ```lua
+     local wezterm = require 'wezterm';
+     return {
+         font = wezterm.font("MesloLGS NF"),
+     }
+     ```
+     If the file already exists, only add the line with the font to the existing return.
+     Also add the first line if it is not already present.
+   - **urxvt**: Create or open `~/.Xresources` and add the following line to it:
+     ```text
+     URxvt.font: xft:MesloLGS NF:size=11
+     ```
+     You can adjust the font size to your preference. After changing the config run
+     `xrdb ~/.Xresources` to reload it. The new config is applied to all new terminals.
+   - **xterm**: Create or open `~/.Xresources` and add the following line to it:
+     ```text
+     xterm*faceName: MesloLGS NF
+     ```
+     After changing the config run `xrdb ~/.Xresources` to reload it. The new config is applied to
+     all new terminals.
+   - **Zed**: Open `~/.config/zed/settings.json` and set `terminal.font_family` to `"MesloLGS NF"`.
+     ```jsonc
+     {
+       "terminal": {
+         "font_family": "MesloLGS NF"
+       },
+       // Other settings.
+     }
+     ```
+   - Crostini (Linux on Chrome OS): Open
+     chrome-untrusted://terminal/html/nassh_preferences_editor.html, set *Text font family* to
+      `'MesloLGS NF'` (including the quotes) and *Custom CSS (inline text)* to the following:
+     ```css
+     @font-face {
+      font-family: "MesloLGS NF";
+      src: url("https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/MesloLGS%20NF%20Regular.ttf");
+      font-weight: normal;
+      font-style: normal;
+     }
+     @font-face {
+         font-family: "MesloLGS NF";
+         src: url("https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/MesloLGS%20NF%20Bold.ttf");
+         font-weight: bold;
+         font-style: normal;
+     }
+     @font-face {
+         font-family: "MesloLGS NF";
+         src: url("https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/MesloLGS%20NF%20Italic.ttf");
+         font-weight: normal;
+         font-style: italic;
+     }
+     @font-face {
+         font-family: "MesloLGS NF";
+         src: url("https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/MesloLGS%20NF%20Bold%20Italic.ttf");
+         font-weight: bold;
+         font-style: italic;
+     }
+     ```
+     **_CAVEAT_**: If you open the normal terminal preferences these settings will be overwritten.
+1. Run `p10k configure` to generate a new `~/.p10k.zsh`. The old config may work
+   incorrectly with the new font.
+
+_Using a different terminal and know how to set the font for it? Share your knowledge by sending a
+PR to expand the list!_
@@ -0,0 +1,4 @@
+BasedOnStyle: Google
+ColumnLimit: 100
+DerivePointerAlignment: false
+PointerAlignment: Left
@@ -0,0 +1,16 @@
+* text=auto
+
+*.cc   text eol=lf
+*.h    text eol=lf
+*.info text eol=lf
+*.json text eol=lf
+*.md   text eol=lf
+*.sh   text eol=lf
+*.zsh  text eol=lf
+
+/.clang-format text eol=lf
+/LICENSE       text eol=lf
+/Makefile      text eol=lf
+/build         text eol=lf
+/install       text eol=lf
+/mbuild        text eol=lf
@@ -0,0 +1,8 @@
+*.zwc
+/core
+/deps/libgit2-*.tar.gz
+/locks
+/logs
+/obj
+/usrbin/gitstatusd*
+/.vscode/ipch
@@ -0,0 +1,17 @@
+{
+    "configurations": [
+        {
+            "name": "Linux",
+            "includePath": [
+                "${workspaceFolder}/src"
+            ],
+            "defines": [
+            ],
+            "compilerPath": "/usr/bin/g++",
+            "cStandard": "c11",
+            "cppStandard": "c++17",
+            "intelliSenseMode": "gcc-x64"
+        }
+    ],
+    "version": 4
+}
@@ -0,0 +1,72 @@
+{
+  "files.exclude": {
+    "*.zwc": true,
+    "core": true,
+    "locks/": true,
+    "logs/": true,
+    "obj/": true,
+    "usrbin/": true,
+  },
+  "files.associations": {
+    "array": "cpp",
+    "atomic": "cpp",
+    "*.tcc": "cpp",
+    "cctype": "cpp",
+    "chrono": "cpp",
+    "clocale": "cpp",
+    "cmath": "cpp",
+    "complex": "cpp",
+    "condition_variable": "cpp",
+    "cstddef": "cpp",
+    "cstdint": "cpp",
+    "cstdio": "cpp",
+    "cstdlib": "cpp",
+    "cstring": "cpp",
+    "ctime": "cpp",
+    "cwchar": "cpp",
+    "cwctype": "cpp",
+    "deque": "cpp",
+    "unordered_map": "cpp",
+    "unordered_set": "cpp",
+    "vector": "cpp",
+    "exception": "cpp",
+    "fstream": "cpp",
+    "functional": "cpp",
+    "future": "cpp",
+    "initializer_list": "cpp",
+    "iomanip": "cpp",
+    "iosfwd": "cpp",
+    "iostream": "cpp",
+    "istream": "cpp",
+    "limits": "cpp",
+    "memory": "cpp",
+    "mutex": "cpp",
+    "new": "cpp",
+    "numeric": "cpp",
+    "optional": "cpp",
+    "ostream": "cpp",
+    "ratio": "cpp",
+    "sstream": "cpp",
+    "stdexcept": "cpp",
+    "streambuf": "cpp",
+    "string_view": "cpp",
+    "system_error": "cpp",
+    "thread": "cpp",
+    "type_traits": "cpp",
+    "tuple": "cpp",
+    "typeinfo": "cpp",
+    "utility": "cpp",
+    "variant": "cpp",
+    "cstdarg": "cpp",
+    "charconv": "cpp",
+    "algorithm": "cpp",
+    "cinttypes": "cpp",
+    "iterator": "cpp",
+    "map": "cpp",
+    "memory_resource": "cpp",
+    "random": "cpp",
+    "string": "cpp",
+    "bit": "cpp",
+    "netfwd": "cpp"
+  }
+}
@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.
@@ -0,0 +1,57 @@
+APPNAME ?= gitstatusd
+OBJDIR ?= obj
+
+CXX ?= g++
+ZSH := $(shell command -v zsh 2> /dev/null)
+
+VERSION ?= $(shell . ./build.info && printf "%s" "$$gitstatus_version")
+
+# Note: -fsized-deallocation is not used to avoid binary compatibility issues on macOS.
+#
+# Sized delete is implemented as __ZdlPvm in /usr/lib/libc++.1.dylib but this symbol is
+# missing in macOS prior to 10.13.
+CXXFLAGS += -std=c++14 -funsigned-char -O3 -DNDEBUG -DGITSTATUS_VERSION=$(VERSION) -Wall -Werror # -g -fsanitize=thread
+LDFLAGS += -pthread # -fsanitize=thread
+LDLIBS += -lgit2 # -lprofiler -lunwind
+
+SRCS := $(shell find src -name "*.cc")
+OBJS := $(patsubst src/%.cc, $(OBJDIR)/%.o, $(SRCS))
+
+all: $(APPNAME)
+
+$(APPNAME): usrbin/$(APPNAME)
+
+usrbin/$(APPNAME): $(OBJS)
+	$(CXX) $(OBJS) $(LDFLAGS) $(LDLIBS) -o $@
+
+$(OBJDIR):
+	mkdir -p -- $(OBJDIR)
+
+$(OBJDIR)/%.o: src/%.cc Makefile build.info | $(OBJDIR)
+	$(CXX) $(CXXFLAGS) -MM -MT $@ src/$*.cc >$(OBJDIR)/$*.dep
+	$(CXX) $(CXXFLAGS) -Wall -c -o $@ src/$*.cc
+
+clean:
+	rm -rf -- $(OBJDIR)
+
+zwc:
+	$(or $(ZSH),:) -fc 'for f in *.zsh install; do zcompile -R -- $$f.zwc $$f || exit; done'
+
+minify:
+	rm -rf -- .clang-format .git .gitattributes .gitignore .vscode deps docs src usrbin/.gitkeep LICENSE Makefile README.md build mbuild
+
+pkg: zwc
+	GITSTATUS_DAEMON= GITSTATUS_CACHE_DIR=$(shell pwd)/usrbin ./install -f
+
+-include $(OBJS:.o=.dep)
+
+.PHONY: help
+
+help:
+	@echo "Usage: make [TARGET]"
+	@echo "Available targets:"
+	@echo "  all         Build $(APPNAME) (default target)"
+	@echo "  clean       Remove generated files and directories"
+	@echo "  zwc         Compile Zsh files"
+	@echo "  minify      Remove unnecessary files and folders"
+	@echo "  pkg         Create a package"
@@ -0,0 +1,530 @@
+# gitstatus
+
+**gitstatus** is a 10x faster alternative to `git status` and `git describe`. Its primary use
+case is to enable fast git prompt in interactive shells.
+
+Heavy lifting is done by **gitstatusd** -- a custom binary written in C++. It comes with Zsh and
+Bash bindings for integration with shell.
+
+## Table of Contents
+
+1. [Using from Zsh](#using-from-zsh)
+1. [Using from Bash](#using-from-bash)
+2. [Using from other shells](#using-from-other-shells)
+1. [How it works](#how-it-works)
+1. [Benchmarks](#benchmarks)
+1. [Why fast](#why-fast)
+1. [Requirements](#requirements)
+1. [Compiling](#compiling)
+1. [License](#license)
+
+## Using from Zsh
+
+The easiest way to take advantage of gitstatus from Zsh is to use a theme that's already integrated
+with it. For example, [Powerlevel10k](https://github.com/romkatv/powerlevel10k) is a flexible and
+fast theme with first-class gitstatus integration. If you install Powerlevel10k, you don't need to
+install gitstatus.
+
+![Powerlevel10k Zsh Theme](
+  https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/prompt-styles-high-contrast.png)
+
+For those who wish to use gitstatus without a theme, there is
+[gitstatus.prompt.zsh](gitstatus.prompt.zsh). Install it as follows:
+
+```zsh
+git clone --depth=1 https://github.com/romkatv/gitstatus.git ~/gitstatus
+echo 'source ~/gitstatus/gitstatus.prompt.zsh' >>! ~/.zshrc
+```
+
+Users in China can use the official mirror on gitee.com for faster download.<br>
+中国大陆用户可以使用 gitee.com 上的官方镜像加速下载.
+
+```zsh
+git clone --depth=1 https://gitee.com/romkatv/gitstatus.git ~/gitstatus
+echo 'source ~/gitstatus/gitstatus.prompt.zsh' >>! ~/.zshrc
+```
+
+Alternatively, if you have Homebrew installed:
+
+```zsh
+brew install romkatv/gitstatus/gitstatus
+echo "source $(brew --prefix)/opt/gitstatus/gitstatus.prompt.zsh" >>! ~/.zshrc
+```
+
+(If you choose this option, replace `~/gitstatus` with `$(brew --prefix)/opt/gitstatus/gitstatus`
+in all code snippets below.)
+
+_Make sure to disable your current theme if you have one._
+
+This will give you a basic yet functional prompt with git status in it. It's
+[over 10x faster](#benchmarks) than any alternative that can give you comparable prompt. In order
+to customize it, set `PROMPT` and/or `RPROMPT` at the end of `~/.zshrc` after sourcing
+`gitstatus.prompt.zsh`. Insert `${GITSTATUS_PROMPT}` where you want git status to go. For example:
+
+```zsh
+source ~/gitstatus/gitstatus.prompt.zsh
+
+PROMPT='%~%# '               # left prompt: directory followed by %/# (normal/root)
+RPROMPT='$GITSTATUS_PROMPT'  # right prompt: git status
+```
+
+The expansion of `${GITSTATUS_PROMPT}` can contain the following bits:
+
+| segment     |  meaning                                              |
+|-------------|-------------------------------------------------------|
+| `master`    | current branch                                        |
+| `#v1`       | HEAD is tagged with `v1`; not shown when on a branch  |
+| `@5fc6fca4` | current commit; not shown when on a branch or tag     |
+| `⇣1`        | local branch is behind the remote by 1 commit         |
+| `⇡2`        | local branch is ahead of the remote by 2 commits      |
+| `⇠3`        | local branch is behind the push remote by 3 commits   |
+| `⇢4`        | local branch is ahead of the push remote by 4 commits |
+| `*5`        | there are 5 stashes                                   |
+| `merge`     | merge is in progress (could be some other action)     |
+| `~6`        | there are 6 merge conflicts                           |
+| `+7`        | there are 7 staged changes                            |
+| `!8`        | there are 8 unstaged changes                          |
+| `?9`        | there are 9 untracked files                           |
+
+`$GITSTATUS_PROMPT_LEN` tells you how long `$GITSTATUS_PROMPT` is when printed to the console.
+[gitstatus.prompt.zsh](gitstatus.prompt.zsh) has an example of using it to truncate the current
+directory.
+
+If you'd like to change the format of git status, or want to have greater control over the
+process of assembling `PROMPT`, you can copy and modify parts of
+[gitstatus.prompt.zsh](gitstatus.prompt.zsh) instead of sourcing the script. Your `~/.zshrc`
+might look something like this:
+
+```zsh
+source ~/gitstatus/gitstatus.plugin.zsh
+
+function my_set_prompt() {
+  PROMPT='%~%# '
+  RPROMPT=''
+
+  if gitstatus_query MY && [[ $VCS_STATUS_RESULT == ok-sync ]]; then
+    RPROMPT=${${VCS_STATUS_LOCAL_BRANCH:-@${VCS_STATUS_COMMIT}}//\%/%%}  # escape %
+    (( VCS_STATUS_NUM_STAGED    )) && RPROMPT+='+'
+    (( VCS_STATUS_NUM_UNSTAGED  )) && RPROMPT+='!'
+    (( VCS_STATUS_NUM_UNTRACKED )) && RPROMPT+='?'
+  fi
+
+  setopt no_prompt_{bang,subst} prompt_percent  # enable/disable correct prompt expansions
+}
+
+gitstatus_stop 'MY' && gitstatus_start -s -1 -u -1 -c -1 -d -1 'MY'
+autoload -Uz add-zsh-hook
+add-zsh-hook precmd my_set_prompt
+```
+
+This snippet is sourcing `gitstatus.plugin.zsh` rather than `gitstatus.prompt.zsh`. The former
+defines low-level bindings that communicate with gitstatusd over pipes. The latter is a simple
+script that uses these bindings to assemble git prompt.
+
+Unlike [Powerlevel10k](https://github.com/romkatv/powerlevel10k), code based on
+[gitstatus.prompt.zsh](gitstatus.prompt.zsh) is communicating with gitstatusd synchronously. This
+can make your prompt slow when working in a large git repository or on a slow machine. To avoid
+this problem, call `gitstatus_query` asynchronously as documented in
+[gitstatus.plugin.zsh](gitstatus.plugin.zsh). This can be quite challenging.
+
+## Using from Bash
+
+The easiest way to take advantage of gitstatus from Bash is via
+[gitstatus.prompt.sh](gitstatus.prompt.sh). Install it as follows:
+
+```bash
+git clone --depth=1 https://github.com/romkatv/gitstatus.git ~/gitstatus
+echo 'source ~/gitstatus/gitstatus.prompt.sh' >> ~/.bashrc
+```
+
+Users in China can use the official mirror on gitee.com for faster download.<br>
+中国大陆用户可以使用 gitee.com 上的官方镜像加速下载.
+
+```bash
+git clone --depth=1 https://gitee.com/romkatv/gitstatus.git ~/gitstatus
+echo 'source ~/gitstatus/gitstatus.prompt.sh' >> ~/.bashrc
+```
+
+Alternatively, if you have Homebrew installed:
+
+```zsh
+brew install romkatv/gitstatus/gitstatus
+echo "source $(brew --prefix)/opt/gitstatus/gitstatus.prompt.sh" >> ~/.bashrc
+```
+
+(If you choose this option, replace `~/gitstatus` with `$(brew --prefix)/opt/gitstatus/gitstatus`
+in all code snippets below.)
+
+This will give you a basic yet functional prompt with git status in it. It's
+[over 10x faster](#benchmarks) than any alternative that can give you comparable prompt.
+
+![Bash Prompt with GitStatus](
+  https://raw.githubusercontent.com/romkatv/gitstatus/1ac366952366d89980b3f3484f270b4fa5ae4293/bash-prompt.png)
+
+In order to customize your prompt, set `PS1` at the end of `~/.bashrc` after sourcing
+`gitstatus.prompt.sh`. Insert `${GITSTATUS_PROMPT}` where you want git status to go. For example:
+
+```bash
+source ~/gitstatus/gitstatus.prompt.sh
+
+PS1='\w ${GITSTATUS_PROMPT}\n\$ ' # directory followed by git status and $/# (normal/root)
+```
+
+The expansion of `${GITSTATUS_PROMPT}` can contain the following bits:
+
+| segment     |  meaning                                              |
+|-------------|-------------------------------------------------------|
+| `master`    | current branch                                        |
+| `#v1`       | HEAD is tagged with `v1`; not shown when on a branch  |
+| `@5fc6fca4` | current commit; not shown when on a branch or tag     |
+| `⇣1`        | local branch is behind the remote by 1 commit         |
+| `⇡2`        | local branch is ahead of the remote by 2 commits      |
+| `⇠3`        | local branch is behind the push remote by 3 commits   |
+| `⇢4`        | local branch is ahead of the push remote by 4 commits |
+| `*5`        | there are 5 stashes                                   |
+| `merge`     | merge is in progress (could be some other action)     |
+| `~6`        | there are 6 merge conflicts                           |
+| `+7`        | there are 7 staged changes                            |
+| `!8`        | there are 8 unstaged changes                          |
+| `?9`        | there are 9 untracked files                           |
+
+If you'd like to change the format of git status, or want to have greater control over the
+process of assembling `PS1`, you can copy and modify parts of
+[gitstatus.prompt.sh](gitstatus.prompt.sh) instead of sourcing the script. Your `~/.bashrc` might
+look something like this:
+
+```bash
+source ~/gitstatus/gitstatus.plugin.sh
+
+function my_set_prompt() {
+  PS1='\w'
+
+  if gitstatus_query && [[ "$VCS_STATUS_RESULT" == ok-sync ]]; then
+    if [[ -n "$VCS_STATUS_LOCAL_BRANCH" ]]; then
+      PS1+=" ${VCS_STATUS_LOCAL_BRANCH//\\/\\\\}"  # escape backslash
+    else
+      PS1+=" @${VCS_STATUS_COMMIT//\\/\\\\}"       # escape backslash
+    fi
+    (( VCS_STATUS_HAS_STAGED"    )) && PS1+='+'
+    (( VCS_STATUS_HAS_UNSTAGED"  )) && PS1+='!'
+    (( VCS_STATUS_HAS_UNTRACKED" )) && PS1+='?'
+  fi
+
+  PS1+='\n\$ '
+
+  shopt -u promptvars  # disable expansion of '$(...)' and the like
+}
+
+gitstatus_stop && gitstatus_start
+PROMPT_COMMAND=my_set_prompt
+```
+
+This snippet is sourcing `gitstatus.plugin.sh` rather than `gitstatus.prompt.sh`. The former
+defines low-level bindings that communicate with gitstatusd over pipes. The latter is a simple
+script that uses these bindings to assemble git prompt.
+
+Note: Bash bindings, unlike Zsh bindings, don't support asynchronous calls.
+
+## Using from other shells
+
+If there are no gitstatusd bindings for your shell, you'll need to get your hands dirty.
+Use the existing bindings for inspiration; run `gitstatusd --help` or read the same thing in
+[options.cc](src/options.cc).
+
+## How it works
+
+gitstatusd reads requests from stdin and prints responses to stdout. Requests contain an ID and
+a directory. Responses contain the same ID and machine-readable git status for the directory.
+gitstatusd keeps some state in memory for the directories it has seen in order to serve future
+requests faster.
+
+[Zsh bindings](gitstatus.plugin.zsh) and [Bash bindings](gitstatus.plugin.sh) start gitstatusd in
+the background and communicate with it via pipes. Themes such as
+[Powerlevel10k](https://github.com/romkatv/powerlevel10k) use these bindings to put git status in
+`PROMPT`.
+
+Note that gitstatus cannot be used as a drop-in replacement for `git status` command as it doesn't
+produce output in the same format. It does perform the same computation though.
+
+## Benchmarks
+
+The following benchmark results were obtained on Intel i9-7900X running Ubuntu 18.04 in
+a clean [chromium](https://github.com/chromium/chromium) repository synced to `9394e49a`. The
+repository was checked out to an ext4 filesystem on M.2 SSD.
+
+Three functionally equivalent tools for computing git status were benchmarked:
+
+* `gitstatusd`
+* `git` with `core.untrackedcache` enabled and `core.fsmonitor` disabled
+* `lg2` -- a demo/example executable from [libgit2](https://github.com/romkatv/libgit2) that
+  implements a subset of `git` functionality on top of libgit2 API; for the purposes of this
+  benchmark the subset is sufficient to generate the same data as the other tools
+
+Every tool was benchmark in cold and hot conditions. For `git` the first run in a repository was
+considered cold, with the following runs considered hot. `lg2` was patched to compute results twice
+in a single invocation without freeing the repository in between; the second run was considered hot.
+The same patching was not done for `git` because `git` cannot be easily modified to refresh inmemory
+index state between invocations; in fact, this limitation is one of the primary reasons developers
+use libgit2. `gitstatusd` was benchmarked similarly to `lg2` with two result computations in the
+same invocation.
+
+Two commands were benchmarked: `status` and `describe`.
+
+### Status
+
+In this benchmark all tools were computing the equivalent of `git status`. Lower numbers are better.
+
+| Tool          |      Cold  |         Hot |
+|---------------|-----------:|------------:|
+| **gitstatus** | **291 ms** | **30.9 ms** |
+| git           |     876 ms |      295 ms |
+| lg2           |    1730 ms |     1310 ms |
+
+gitstatusd is substantially faster than the alternatives, especially on hot runs. Note that hot runs
+are of primary importance to the main use case of gitstatus in interactive shells.
+
+The performance of `git status` fluctuated wildly in this benchmarks for reasons unknown to the
+author. Moreover, performance is sticky -- once `git status` settles around a number, it stays
+there for a long time. Numbers as diverse as 295, 352, 663 and 730 had been observed on hot runs on
+the same repository. The number in the table is the lowest (fastest or best) that `git status` had
+shown.
+
+### Describe
+
+In this benchmark all tools were computing the equivalent of `git describe --tags --exact-match`
+to find tags that resolve to the same commit as `HEAD`. Lower numbers are better.
+
+| Tool          |       Cold  |           Hot |
+|---------------|------------:|--------------:|
+| **gitstatus** | **4.04 ms** | **0.0345 ms** |
+| git           |     18.0 ms |       14.5 ms |
+| lg2           |      185 ms |       45.2 ms |
+
+gitstatusd is once again faster than the alternatives, more so on hot runs.
+
+## Why fast
+
+Since gitstatusd doesn't have to print all staged/unstaged/untracked files but only report
+whether there are any, it can terminate repository scan early. It can also remember which files
+were dirty on the previous run and check them first on the next run to avoid the scan entirely if
+the files are still dirty. However, the benchmarks above were performed in a clean repository where
+these shortcuts do not trigger. All benchmarked tools had to do the same work -- check the status
+of every file in the index to see if it has changed, check every directory for newly created files,
+etc. And yet, gitstatusd came ahead by a large margin. This section describes what it does that
+makes it so fast.
+
+Most of the following comparisons are done against libgit2 rather than git because of the author's
+familiarity with the former but not the with latter. libgit2 has clean, well-documented APIs and an
+elegant implementation, which makes it so much easier to work with and to analyze performance
+bottlenecks.
+
+### Summary for the impatient
+
+Under the benchmark conditions described above, the equivalent of libgit2's
+`git_diff_index_to_workdir` (the most expensive part of `status` command) is 46.3 times faster in
+gitstatusd. The speedup comes from the following sources.
+
+* gitstatusd uses more efficient data structures and algorithms and employs performance-conscious
+coding style throughout the codebase. This reduces CPU time in userspace by 32x compared to libgit2.
+* gitstatusd uses less expensive system calls and makes fewer of them. This reduces CPU time spent
+in kernel by 1.9x.
+* gitstatusd can utilize multiple cores to scan index and workdir in parallel with almost perfect
+scaling. This reduces total run time by 12.4x while having virtually no effect on total CPU time.
+
+### Problem statement
+
+The most resource-intensive part of the `status` command is finding the difference between _index_
+and _workdir_ (`git_diff_index_to_workdir` in libgit2). Index is a list of all files in the git
+repository with their last modification times. This is an obvious simplification but it suffices for
+this exposition. On disk, index is stored sorted by file path. Here's an example of git index:
+
+| File        | Last modification time |
+|-------------|-----------------------:|
+| Makefile    |   2019-04-01T14:12:32Z |
+| src/hello.c |   2019-04-01T14:12:00Z |
+| src/hello.h |   2019-04-01T14:12:32Z |
+
+This list needs to be compared to the list of files in the working directory. If any of the files
+listed in the index are missing from the workdir or have different last modification time, they are
+"unstaged" in gitstatusd parlance. If you run `git status`, they'll be shown as "changes not staged
+for commit". Thus, any implementation of `status` command has to call `stat()` or one of its
+variants on every file in the index.
+
+In addition, all files in the working directory for which there is no entry in the index at all are
+"untracked". `git status` will show them as "untracked files". Finding untracked files requires some
+form of work directory traversal.
+
+### Single-threaded scan
+
+Let's see how `git_diff_index_to_workdir` from libgit2 accomplishes these tasks. Here's its CPU
+profile from 200 hot runs over chromium repository.
+
+![libgit2 CPU profile (hot)](
+  https://raw.githubusercontent.com/romkatv/gitstatus/1ac366952366d89980b3f3484f270b4fa5ae4293/cpu-profile-libgit2.png)
+
+(The CPU profile was created with [gperftools](https://github.com/gperftools/gperftools) and
+rendered with [pprof](https://github.com/google/pprof)).
+
+We can see `__GI__lxstat` taking a lot of time. This is the `stat()` call for every file in the
+index. We can also identify `__opendir`, `__readdir` and `__GI___close_nocancel` -- glibc wrappers
+for reading the contents of a directory. This is for finding untracked files. Out of the total 232
+seconds, 111 seconds -- or 47.7% -- was spent on these calls. The rest is computation -- comparing
+strings, sorting arrays, etc.
+
+Now let's take a look at the CPU profile of gitstatusd on the same task.
+
+![gitstatusd CPU profile (hot)](
+  https://raw.githubusercontent.com/romkatv/gitstatus/1ac366952366d89980b3f3484f270b4fa5ae4293/cpu-profile-gitstatusd-hot.png)
+
+The first impression is that this profile looks pruned. This isn't an artifact. The profile was
+generated with the same tools and the same flags as the profile of libgit2.
+
+Since both profiles were generated from the same workload, absolute numbers can be compared. We can
+see that gitstatusd took 62 seconds in total compared to libgit2's 232 seconds. System calls at the
+core of the algorithm are clearly visible. `__GI___fxstatat` is a flavor of `stat()`, and the other
+three calls -- `__libc_openat64`, `__libc_close` and `__GI___fxstat` are responsible for opening
+directories and finding untracked files. Notice that there is almost nothing else in the profile
+apart from these calls. The rest of the code accounts for 3.77 seconds of CPU time -- 32 times less
+than in libgit2.
+
+So, one reason gitstatusd is fast is that it has efficient diffing code -- very little time is spent
+outside of kernel. However, if we look closely, we can notice that system calls in gitstatusd are
+_also_ faster than in libgit2. For example, libgit2 spent 72.07 seconds in `__GI__lxstat` while
+gitstatusd spent only 48.82 seconds in `__GI___fxstatat`. There are two reasons for this difference.
+First, libgit2 makes more `stat()` calls than is strictly required. It's not necessary to stat
+directories because index only has files. There are 25k directories in chromium repository (and 300k
+files) -- that's 25k `stat()` calls that could be avoided. The second reason is that libgit2 and
+gitstatusd use different flavors of `stat()`. libgit2 uses `lstat()`, which takes a path to the file
+as input. Its performance is linear in the number of subdirectories in the path because it needs to
+perform a lookup for every one of them and to check permissions. gitstatusd uses `fstatat()`, which
+takes a file descriptor to the parent directory and a name of the file. Just a single lookup, less
+CPU time.
+
+Similarly to `lstat()` vs `fstatat()`, it's faster to open files and directories with `openat()`
+from the parent directory file descriptor than with regular `open()` that accepts full file path.
+gitstatusd takes advantage of `openat()` to open directories as fast as possible. It opens about 90%
+of the directories (this depends on the actual directory structure of the repository) from the
+immediate parent -- the most efficient way -- and the remaining 10% it opens from the repository's
+root directory. The reason it's done this way is to keep the maximum number of simultaneously open
+file descriptors bounded. libgit2 can have O(repository depth) simultaneously open file descriptors,
+which may be OK for a single-threaded application but can balloon to a large number when scans are
+done by many threads simultaneously, like in gitstatusd.
+
+There is no equivalent to `__opendir` or `__readdir` in the gitstatusd profile because it uses the
+equivalent of [untracked cache](https://git-scm.com/docs/git-update-index#_untracked_cache) from
+git. On the first scan of the workdir gitstatusd lists all files just like libgit2. But, unlike
+libgit2, it remembers the last modification time of every directory along with the list of
+untracked files under it. On the next scan, gitstatusd can skip listing files in directories whose
+last modification time hasn't changed.
+
+To summarize, here's what gitstatusd was doing when the CPU profile was captured:
+
+1. `__libc_openat64`: Open every directory for which there are files in the index.
+2. `__GI___fxstat`: Check last modification time of the directory. Since it's the same as on the
+   last scan, this directory has the same list of untracked files as before, which is empty (the
+   repository is clean).
+3. `__GI___fxstatat`: Check last modification time for every file in the index that belongs to this
+   directory.
+4. `__libc_close`: Close the file descriptor to the directory.
+
+Here's how the very first scan of a repository looks like in gitstatusd:
+
+![gitstatusd CPU profile (cold)](
+  https://raw.githubusercontent.com/romkatv/gitstatus/1ac366952366d89980b3f3484f270b4fa5ae4293/cpu-profile-gitstatusd-cold.png)
+
+(Some glibc functions are mislabel on this profile. `explicit_bzero` and `__nss_passwd_lookup` are
+in reality `strcmp` and `memcmp`.)
+
+This is a superset of the previous -- hot -- profile, with an extra `syscall` and string sorting for
+directory listing. gitstatusd uses `getdents64` Linux system call directly, bypassing the glibc
+wrapper that libgit2 uses. This is 23% faster. The details of this optimization can be found in a
+[separate document](docs/listdir.md).
+
+### Multithreading
+
+The diffing algorithm in gitstatusd was designed from the ground up with the intention of using it
+concurrently from multiple threads. With a fast SSD, `status` is CPU bound, so taking advantage of
+all available CPU cores is an obvious way to yield results faster.
+
+gitstatusd exhibits almost perfect scaling from multithreading. Engaging all cores allows it to
+produce results 12.4 times faster than in single-threaded execution. This is on Intel i9-7900X with
+10 cores (20 with hyperthreading) with single-core frequency of 4.3GHz and all-core frequency of
+4.0GHz.
+
+Note: `git status` also uses all available cores in some parts of its algorithm while `lg2` does
+everything in a single thread.
+
+### Postprocessing
+
+Once the difference between the index and the workdir is found, we have a list of _candidates_ --
+files that may be unstaged or untracked. To make the final judgement, these files need to be checked
+against `.gitignore` rules and a few other things.
+
+gitstatusd uses [patched libgit2](https://github.com/romkatv/libgit2) for this step. This fork
+adds several optimizations that make libgit2 faster. The patched libgit2 performs more than twice
+as fast in the benchmark as the original even without changes in the user code (that is, in the
+code that uses the libgit2 APIs). The fork also adds several API extensions, most notable of which
+is the support for multi-threaded scans. If `lg2 status` is modified to take advantage of these
+extensions, it outperforms the original libgit2 by a factor of 18. Lastly, the fork fixes a score of
+bugs, most of which become apparent only when using libgit2 from multiple threads.
+
+_WARNING: Changes to libgit2 are extensive but the testing they underwent isn't. It is
+**not recommended** to use the patched libgit2 in production._
+
+## Requirements
+
+* To compile: binutils, cmake, gcc, g++, git and GNU make.
+* To run: Linux, macOS, FreeBSD, Android, WSL, Cygwin or MSYS2.
+
+## Compiling
+
+There are prebuilt `gitstatusd` binaries in [releases](
+  https://github.com/romkatv/gitstatus/releases). When using the official shell bindings
+provided by gitstatus, the right binary for your architecture gets downloaded automatically.
+
+If prebuilt binaries don't work for you, you'll need to get your hands dirty.
+
+### Compiling for personal use
+
+```zsh
+git clone --depth=1 https://github.com/romkatv/gitstatus.git
+cd gitstatus
+./build -w -s -d docker
+```
+
+Users in China can use the official mirror on gitee.com for faster download.<br>
+中国大陆用户可以使用 gitee.com 上的官方镜像加速下载.
+
+```zsh
+git clone --depth=1 https://gitee.com/romkatv/gitstatus.git
+cd gitstatus
+./build -w -s -d docker
+```
+
+- If it says that `-d docker` is not supported on your OS, remove this flag.
+- If it says that `-s` is not supported on your OS, remove this flag.
+- If it tell you to install docker but you cannot or don't want to, remove `-d docker`.
+- If it says that some command is missing, install it.
+
+If everything goes well, the newly built binary will appear in `./usrbin`. It'll be picked up
+by shell bindings automatically.
+
+When you update shell bindings, they may refuse to work with the binary you've built earlier. In
+this case you'll need to rebuild.
+
+If you are using gitstatus through [Powerlevel10k](https://github.com/romkatv/powerlevel10k), the
+instructions are the same except that you don't need to clone gitstatus. Instead, change your
+current directory to `/path/to/powerlevel10k/gitstatus` (`/path/to/powerlevel10k` is the directory
+where you've installed Powerlevel10k) and run `./build -w -s -d docker` from there as described
+above.
+
+### Compiling for distribution
+
+It's currently neither easy nor recommended to package and distribute gitstatus. There are no
+instructions you can follow that would allow you to easily update your package when new versions of
+gitstatus are released. This may change in the future but not soon.
+
+## License
+
+GNU General Public License v3.0. See [LICENSE](LICENSE). Contributions are covered by the same
+license.
@@ -0,0 +1,656 @@
+#!/bin/sh
+#
+# Type `build -h` for help and see https://github.com/romkatv/gitstatus
+# for full documentation.
+
+set -ue
+
+if [ -n "${ZSH_VERSION:-}" ]; then
+  emulate sh -o err_exit -o no_unset
+fi
+
+export LC_ALL=C
+
+if [ -z "${ZSH_VERSION-}" ] && command -v zsh >/dev/null 2>&1; then
+  # Avoid bash 3.*.
+  case "${BASH_VERSION-}" in
+    [0-3].*) exec zsh "$0" "$@";;
+  esac
+fi
+
+# Avoid ksh: https://github.com/romkatv/gitstatus/issues/282.
+if [ -n "${KSH_VERSION-}" ]; then
+  if [ -z "${ZSH_VERSION-}" ] && command -v zsh >/dev/null 2>&1; then
+    exec zsh "$0" "$@"
+  elif [ -z "${BASH_VERSION-}" ] && command -v bash >/dev/null 2>&1 &&
+       bash_version="$(bash --version 2>&1)"; then
+    case "$bash_version" in
+      *version\ [4-9]*|*version\ [1-9][0-9]*) exec bash "$0" "$@";;
+    esac
+  fi
+fi
+
+usage="$(command cat <<\END
+Usage: build [-m ARCH] [-c CPU] [-d CMD] [-i IMAGE] [-s] [-w]
+
+Options:
+
+  -m ARCH   `uname -m` from the target machine; defaults to `uname -m`
+            from the local machine
+  -c CPU    generate machine instructions for CPU of this type; this
+            value gets passed as `-march` (or `-mcpu` for ppc64le) to gcc;
+            inferred from ARCH if not set explicitly
+  -d CMD    build in a Docker container and use CMD as the `docker`
+            command; e.g., `-d docker` or `-d podman`
+  -i IMAGE  build in this Docker image; inferred from ARCH if not set
+            explicitly
+  -s        install whatever software is necessary for build to
+            succeed; on some operating systems this option is not
+            supported; on others it can have partial effect
+  -w        automatically download tarballs for dependencies if they
+            do not already exist in ./deps; dependencies are described
+            in ./build.info
+END
+)"
+
+build="$(command cat <<\END
+outdir="$(command pwd)"
+
+if command -v mktemp >/dev/null 2>&1; then
+  workdir="$(command mktemp -d "${TMPDIR:-/tmp}"/gitstatus-build.XXXXXXXXXX)"
+else
+  workdir="${TMPDIR:-/tmp}/gitstatus-build.tmp.$$"
+  command mkdir -- "$workdir"
+fi
+
+cd -- "$workdir"
+workdir="$(command pwd)"
+
+narg() { echo $#; }
+
+if [ "$(narg $workdir)" != 1 -o -z "${workdir##*:*}" -o -z "${workdir##*=*}" ]; then
+  >&2 echo "[error] cannot build in this directory: $workdir"
+  exit 1
+fi
+
+appname=gitstatusd
+libgit2_tmp="$outdir"/deps/"$appname".libgit2.tmp
+
+cleanup() {
+  trap - INT QUIT TERM ILL PIPE
+  cd /
+  if ! command rm -rf -- "$workdir" "$outdir"/usrbin/"$appname".tmp "$libgit2_tmp"; then
+    command sleep 5
+    command rm -rf -- "$workdir" "$outdir"/usrbin/"$appname".tmp "$libgit2_tmp"
+  fi
+}
+trap cleanup INT QUIT TERM ILL PIPE
+
+if [ -n "$gitstatus_install_tools" ]; then
+  case "$gitstatus_kernel" in
+    linux)
+      if command -v apk >/dev/null 2>&1; then
+        command apk update
+        command apk add binutils cmake gcc g++ git make musl-dev perl-utils
+      elif command -v apt-get >/dev/null 2>&1; then
+        apt-get update
+        apt-get install -y binutils cmake gcc g++ make wget
+      else
+        >&2 echo "[error] -s is not supported on this system"
+        exit 1
+      fi
+    ;;
+    freebsd|dragonfly)
+      command pkg install -y cmake gmake binutils git perl5 wget
+    ;;
+    openbsd)
+      command pkg_add cmake gmake gcc g++ git wget
+    ;;
+    netbsd)
+      command pkgin -y install cmake gmake binutils git
+    ;;
+    darwin)
+      if ! command -v make >/dev/null 2>&1 || ! command -v gcc >/dev/null 2>&1; then
+        >&2 echo "[error] please run 'xcode-select --install' and retry"
+        exit 1
+      fi
+      if command -v port >/dev/null 2>&1; then
+        sudo port -N install libiconv cmake wget
+      elif command -v brew >/dev/null 2>&1; then
+        for formula in libiconv cmake git wget; do
+          if command brew ls --version "$formula" &>/dev/null; then
+            command brew upgrade "$formula"
+          else
+            command brew install "$formula"
+          fi
+        done
+      else
+        >&2 echo "[error] please install MacPorts or Homebrew and retry"
+        exit 1
+      fi
+    ;;
+    msys*|mingw*)
+      command pacman -Syu --noconfirm
+      command pacman -S --needed --noconfirm binutils cmake gcc git make perl
+    ;;
+    *)
+      >&2 echo "[internal error] unhandled kernel: $gitstatus_kernel"
+      exit 1
+    ;;
+  esac
+fi
+
+cpus="$(command getconf _NPROCESSORS_ONLN 2>/dev/null)" ||
+  cpus="$(command sysctl -n hw.ncpu 2>/dev/null)"       ||
+  cpus=8
+
+case "$gitstatus_cpu" in
+  powerpc64|powerpc64le)
+    archflag="-mcpu"
+  ;;
+  *)
+    archflag="-march"
+  ;;
+esac
+
+cflags="$archflag=$gitstatus_cpu -fno-plt -D_FORTIFY_SOURCE=2 -Wformat -Werror=format-security -fpie"
+ldflags=
+static_pie=
+
+if [ -z "${CC-}" ]; then
+  case "$gitstatus_kernel" in
+    freebsd) export CC=clang;;
+    *)       export CC=cc;;
+  esac
+fi
+
+printf 'int main() {}\n' >"$workdir"/cc-test.c
+if 2>/dev/null "$CC"   \
+     -ffile-prefix-map=x=y   \
+     -Werror                 \
+     -c "$workdir"/cc-test.c \
+     -o "$workdir"/cc-test.o; then
+  cflags="$cflags -ffile-prefix-map=$workdir/="
+fi
+
+command rm -f -- "$workdir"/cc-test "$workdir"/cc-test.o
+if 2>/dev/null "$CC"          \
+     -fstack-clash-protection \
+     -Werror                  \
+     -c "$workdir"/cc-test.c  \
+     -o "$workdir"/cc-test.o; then
+  cflags="$cflags -fstack-clash-protection"
+fi
+
+command rm -f -- "$workdir"/cc-test "$workdir"/cc-test.o
+if 2>/dev/null "$CC"         \
+     -fcf-protection         \
+     -Werror                 \
+     -c "$workdir"/cc-test.c \
+     -o "$workdir"/cc-test.o; then
+  cflags="$cflags -fcf-protection"
+fi
+
+command rm -f -- "$workdir"/cc-test "$workdir"/cc-test.o
+if 2>/dev/null "$CC"                             \
+     -Wl,-O1,--sort-common,--as-needed,-z,relro,-z,now \
+     -Werror                                           \
+     "$workdir"/cc-test.c                              \
+     -o "$workdir"/cc-test; then
+  ldflags="$ldflags -Wl,-O1,--sort-common,--as-needed,-z,relro,-z,now"
+fi
+
+command rm -f -- "$workdir"/cc-test "$workdir"/cc-test.o
+if 2>/dev/null "$CC" \
+     -fpie -static-pie     \
+     -Werror               \
+     "$workdir"/cc-test.c  \
+     -o "$workdir"/cc-test; then
+  static_pie='-static-pie'
+fi
+
+if [ "$gitstatus_cpu" = x86-64 ]; then
+  cflags="$cflags -mtune=generic"
+fi
+
+libgit2_cmake_flags=
+libgit2_cflags="${CFLAGS-} $cflags -O3 -DNDEBUG"
+
+gitstatus_cxx=g++
+gitstatus_cxxflags="${CXXFLAGS-} $cflags -I${workdir}/libgit2/include -DGITSTATUS_ZERO_NSEC -D_GNU_SOURCE -D_GLIBCXX_ASSERTIONS"
+gitstatus_ldflags="${LDFLAGS-} $ldflags -L${workdir}/libgit2/build"
+gitstatus_ldlibs=
+gitstatus_make=make
+
+case "$gitstatus_kernel" in
+  linux)
+    gitstatus_ldflags="$gitstatus_ldflags ${static_pie:--static}"
+    libgit2_cmake_flags="$libgit2_cmake_flags -DENABLE_REPRODUCIBLE_BUILDS=ON"
+  ;;
+  freebsd)
+    gitstatus_cxx=clang++
+    gitstatus_make=gmake
+    gitstatus_ldflags="$gitstatus_ldflags ${static_pie:--static}"
+    libgit2_cmake_flags="$libgit2_cmake_flags -DENABLE_REPRODUCIBLE_BUILDS=ON"
+  ;;
+  dragonfly)
+    gitstatus_cxx=clang++12
+    gitstatus_make=gmake
+    gitstatus_ldflags="$gitstatus_ldflags ${static_pie:--static}"
+    libgit2_cmake_flags="$libgit2_cmake_flags -DENABLE_REPRODUCIBLE_BUILDS=ON"
+  ;;
+  openbsd)
+    gitstatus_cxx=eg++
+    gitstatus_make=gmake
+    gitstatus_ldflags="$gitstatus_ldflags ${static_pie:--static}"
+    libgit2_cmake_flags="$libgit2_cmake_flags -DENABLE_REPRODUCIBLE_BUILDS=ON"
+  ;;
+  netbsd)
+    gitstatus_make=gmake
+    gitstatus_ldflags="$gitstatus_ldflags ${static_pie:--static}"
+    libgit2_cmake_flags="$libgit2_cmake_flags -DENABLE_REPRODUCIBLE_BUILDS=ON"
+  ;;
+  darwin)
+    command mkdir -- "$workdir"/lib
+    if [ -e /opt/local/lib/libiconv.a ]; then
+      command ln -s -- /opt/local/lib/libiconv.a "$workdir"/lib
+      libgit2_cflags="$libgit2_cflags -I/opt/local/include"
+      gitstatus_cxxflags="$gitstatus_cxxflags -I/opt/local/include"
+    else
+      brew_prefix="$(command brew --prefix)"
+      command ln -s -- "$brew_prefix"/opt/libiconv/lib/libiconv.a "$workdir"/lib
+      libgit2_cflags="$libgit2_cflags -I"$brew_prefix"/opt/libiconv/include"
+      gitstatus_cxxflags="$gitstatus_cxxflags -I"$brew_prefix"/opt/libiconv/include"
+    fi
+    libgit2_cmake_flags="$libgit2_cmake_flags -DUSE_ICONV=ON"
+    gitstatus_ldlibs="$gitstatus_ldlibs -liconv"
+    gitstatus_ldflags="$gitstatus_ldflags -L${workdir}/lib"
+    libgit2_cmake_flags="$libgit2_cmake_flags -DENABLE_REPRODUCIBLE_BUILDS=OFF"
+  ;;
+  msys*|mingw*)
+    gitstatus_ldflags="$gitstatus_ldflags ${static_pie:--static}"
+    libgit2_cmake_flags="$libgit2_cmake_flags -DENABLE_REPRODUCIBLE_BUILDS=ON"
+  ;;
+  cygwin*)
+    gitstatus_ldflags="$gitstatus_ldflags ${static_pie:--static}"
+    libgit2_cmake_flags="$libgit2_cmake_flags -DENABLE_REPRODUCIBLE_BUILDS=ON"
+  ;;
+  *)
+    >&2 echo "[internal error] unhandled kernel: $gitstatus_kernel"
+    exit 1
+  ;;
+esac
+
+for cmd in cat cmake git ld ln mkdir rm strip tar "$gitstatus_make"; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    if [ -n "$gitstatus_install_tools" ]; then
+      >&2 echo "[internal error] $cmd not found"
+      exit 1
+    else
+      >&2 echo "[error] command not found: $cmd"
+      exit 1
+    fi
+  fi
+done
+
+. "$outdir"/build.info
+if [ -z "${libgit2_version:-}" ]; then
+  >&2 echo "[internal error] libgit2_version not set"
+  exit 1
+fi
+if [ -z "${libgit2_sha256:-}" ]; then
+  >&2 echo "[internal error] libgit2_sha256 not set"
+  exit 1
+fi
+libgit2_tarball="$outdir"/deps/libgit2-"$libgit2_version".tar.gz
+if [ ! -e "$libgit2_tarball" ]; then
+  if [ -n "$gitstatus_download_deps" ]; then
+    if ! command -v wget >/dev/null 2>&1; then
+      if [ -n "$gitstatus_install_tools" ]; then
+        >&2 echo "[internal error] wget not found"
+        exit 1
+      else
+        >&2 echo "[error] command not found: wget"
+        exit 1
+      fi
+    fi
+    libgit2_url=https://github.com/romkatv/libgit2/archive/"$libgit2_version".tar.gz
+    if ! >"$libgit2_tmp" command wget --no-config -qO- -- "$libgit2_url" &&
+       ! >"$libgit2_tmp" command wget             -qO- -- "$libgit2_url"; then
+      set -x
+      >&2 command which wget
+      >&2 command ls -lAd -- "$(command which wget)"
+      >&2 command ls -lAd -- "$outdir"
+      >&2 command ls -lA -- "$outdir"
+      >&2 command ls -lAd -- "$outdir"/deps
+      >&2 command ls -lA -- "$outdir"/deps
+      set +x
+      exit 1
+    fi
+    command mv -f -- "$libgit2_tmp" "$libgit2_tarball"
+  else
+    >&2 echo "[error] file not found: deps/libgit2-"$libgit2_version".tar.gz"
+    exit 1
+  fi
+fi
+
+libgit2_actual_sha256=
+if command -v shasum >/dev/null 2>/dev/null; then
+  libgit2_actual_sha256="$(command shasum -b -a 256 -- "$libgit2_tarball")"
+  libgit2_actual_sha256="${libgit2_actual_sha256%% *}"
+elif command -v sha256sum >/dev/null 2>/dev/null; then
+  libgit2_actual_sha256="$(command sha256sum -b -- "$libgit2_tarball")"
+  libgit2_actual_sha256="${libgit2_actual_sha256%% *}"
+elif command -v sha256 >/dev/null 2>/dev/null; then
+  libgit2_actual_sha256="$(command sha256 -- "$libgit2_tarball" </dev/null)"
+  # Ignore sha256 output if it's from hashalot. It's incompatible.
+  if [ ${#libgit2_actual_sha256} -lt 64 ]; then
+    libgit2_actual_sha256=
+  else
+    libgit2_actual_sha256="${libgit2_actual_sha256##* }"
+  fi
+fi
+
+if [ -z "$libgit2_actual_sha256" ]; then
+  >&2 echo "[error] command not found: shasum or sha256sum"
+  exit 1
+fi
+
+if [ "$libgit2_actual_sha256" != "$libgit2_sha256" ]; then
+  >&2 echo "[error] sha256 mismatch"
+  >&2 echo ""
+  >&2 echo "  file    : deps/libgit2-$libgit2_version.tar.gz"
+  >&2 echo "  expected: $libgit2_sha256"
+  >&2 echo "  actual  : $libgit2_actual_sha256"
+  exit 1
+fi
+
+cd -- "$workdir"
+command tar -xzf "$libgit2_tarball"
+command mv -- libgit2-"$libgit2_version" libgit2
+command mkdir libgit2/build
+cd libgit2/build
+
+CFLAGS="$libgit2_cflags" command cmake \
+  -DCMAKE_BUILD_TYPE=None              \
+  -DZERO_NSEC=ON                       \
+  -DTHREADSAFE=ON                      \
+  -DUSE_BUNDLED_ZLIB=ON                \
+  -DREGEX_BACKEND=builtin              \
+  -DUSE_HTTP_PARSER=builtin            \
+  -DUSE_SSH=OFF                        \
+  -DUSE_HTTPS=OFF                      \
+  -DBUILD_CLAR=OFF                     \
+  -DUSE_GSSAPI=OFF                     \
+  -DUSE_NTLMCLIENT=OFF                 \
+  -DBUILD_SHARED_LIBS=OFF              \
+  $libgit2_cmake_flags                 \
+  ..
+command make -j "$cpus" VERBOSE=1
+
+APPNAME="$appname".tmp           \
+  OBJDIR="$workdir"/gitstatus    \
+  CXX="${CXX:-$gitstatus_cxx}"   \
+  CXXFLAGS="$gitstatus_cxxflags" \
+  LDFLAGS="$gitstatus_ldflags"   \
+  LDLIBS="$gitstatus_ldlibs"     \
+  command "$gitstatus_make" -C "$outdir" -j "$cpus"
+
+app="$outdir"/usrbin/"$appname"
+
+command strip "$app".tmp
+
+command mkdir -- "$workdir"/repo
+printf '[init]\n  defaultBranch = master\n' >"$workdir"/.gitconfig
+(
+  cd -- "$workdir"/repo
+  GIT_CONFIG_NOSYSTEM=1 HOME="$workdir" command git init
+  GIT_CONFIG_NOSYSTEM=1 HOME="$workdir" command git config user.name "Your Name"
+  GIT_CONFIG_NOSYSTEM=1 HOME="$workdir" command git config user.email "you@example.com"
+  GIT_CONFIG_NOSYSTEM=1 HOME="$workdir" command git commit \
+    --allow-empty --allow-empty-message --no-gpg-sign -m ''
+)
+
+resp="$(printf "hello\037$workdir/repo\036" | "$app".tmp)"
+case "$resp" in
+  hello*1*/repo*master*);;
+  *)
+    >&2 echo 'error: invalid gitstatusd response for a git repo'
+    exit 1
+  ;;
+esac
+
+resp="$(printf 'hello\037\036' | "$app".tmp)"
+case "$resp" in
+  hello*0*);;
+  *)
+    >&2 echo 'error: invalid gitstatusd response for a non-repo'
+    exit 1
+  ;;
+esac
+
+command mv -f -- "$app".tmp "$app"
+
+cleanup
+
+command cat >&2 <<-END
+	-------------------------------------------------
+	SUCCESS: created usrbin/$appname
+	END
+END
+)"
+
+docker_image=
+docker_cmd=
+
+gitstatus_arch=
+gitstatus_cpu=
+gitstatus_install_tools=
+gitstatus_download_deps=
+
+while getopts ':m:c:i:d:swh' opt "$@"; do
+  case "$opt" in
+    h)
+      printf '%s\n' "$usage"
+      exit
+    ;;
+    m)
+      if [ -n "$gitstatus_arch" ]; then
+        >&2 echo "[error] duplicate option: -$opt"
+        exit 1
+      fi
+      if [ -z "$OPTARG" ]; then
+        >&2 echo "[error] incorrect value of -$opt: $OPTARG"
+        exit 1
+      fi
+      gitstatus_arch="$OPTARG"
+    ;;
+    c)
+      if [ -n "$gitstatus_cpu" ]; then
+        >&2 echo "[error] duplicate option: -$opt"
+        exit 1
+      fi
+      if [ -z "$OPTARG" ]; then
+        >&2 echo "[error] incorrect value of -$opt: $OPTARG"
+        exit 1
+      fi
+      gitstatus_cpu="$OPTARG"
+    ;;
+    i)
+      if [ -n "$docker_image" ]; then
+        >&2 echo "[error] duplicate option: -$opt"
+        exit 1
+      fi
+      if [ -z "$OPTARG" ]; then
+        >&2 echo "[error] incorrect value of -$opt: $OPTARG"
+        exit 1
+      fi
+      docker_image="$OPTARG"
+    ;;
+    d)
+      if [ -n "$docker_cmd" ]; then
+        >&2 echo "[error] duplicate option: -$opt"
+        exit 1
+      fi
+      if [ -z "$OPTARG" ]; then
+        >&2 echo "[error] incorrect value of -$opt: $OPTARG"
+        exit 1
+      fi
+      docker_cmd="$OPTARG"
+    ;;
+    s)
+      if [ -n "$gitstatus_install_tools" ]; then
+        >&2 echo "[error] duplicate option: -$opt"
+        exit 1
+      fi
+      gitstatus_install_tools=1
+    ;;
+    w)
+      if [ -n "$gitstatus_download_deps" ]; then
+        >&2 echo "[error] duplicate option: -$opt"
+        exit 1
+      fi
+      gitstatus_download_deps=1
+    ;;
+    \?) >&2 echo "[error] invalid option: -$OPTARG"           ; exit 1;;
+    :)  >&2 echo "[error] missing required argument: -$OPTARG"; exit 1;;
+    *)  >&2 echo "[internal error] unhandled option: -$opt"   ; exit 1;;
+  esac
+done
+
+if [ "$OPTIND" -le $# ]; then
+  >&2 echo "[error] unexpected positional argument"
+  exit 1
+fi
+
+if [ -n "$docker_image" -a -z "$docker_cmd" ]; then
+  >&2 echo "[error] cannot use -i without -d"
+  exit 1
+fi
+
+if [ -z "$gitstatus_arch" ]; then
+  gitstatus_arch="$(uname -m)"
+  gitstatus_arch="$(printf '%s' "$gitstatus_arch" | tr '[A-Z]' '[a-z]')"
+fi
+
+if [ -z "$gitstatus_cpu" ]; then
+  case "$gitstatus_arch" in
+    armel)          gitstatus_cpu=armv5;;
+    armv6l|armhf)   gitstatus_cpu=armv6;;
+    armv7l)         gitstatus_cpu=armv7;;
+    arm64|aarch64)  gitstatus_cpu=armv8-a;;
+    ppc64|ppc64le)  gitstatus_cpu=powerpc64le;;
+    riscv64)        gitstatus_cpu=rv64imafdc;;
+    loongarch64)    gitstatus_cpu=loongarch64;;
+    x86_64|amd64)   gitstatus_cpu=x86-64;;
+    x86)            gitstatus_cpu=i586;;
+    s390x)          gitstatus_cpu=z900;;
+    i386|i586|i686) gitstatus_cpu="$gitstatus_arch";;
+    *)
+      >&2 echo '[error] unable to infer target CPU architecture'
+      >&2 echo 'Please specify explicitly with `-c CPU`.'
+      exit 1
+    ;;
+  esac
+fi
+
+gitstatus_kernel="$(uname -s)"
+gitstatus_kernel="$(printf '%s' "$gitstatus_kernel" | tr '[A-Z]' '[a-z]')"
+
+case "$gitstatus_kernel" in
+  linux)
+    if [ -n "$docker_cmd" ]; then
+      if [ -z "${docker_cmd##*/*}" ]; then
+        if [ ! -x "$docker_cmd" ]; then
+          >&2 echo "[error] not an executable file: $docker_cmd"
+          exit 1
+        fi
+      else
+        if ! command -v "$docker_cmd" >/dev/null 2>&1; then
+          >&2 echo "[error] command not found: $docker_cmd"
+          exit 1
+        fi
+      fi
+      if [ -z "$docker_image" ]; then
+        case "$gitstatus_arch" in
+          x86_64)             docker_image=alpine:3.11.6;;
+          x86|i386|i586|i686) docker_image=i386/alpine:3.11.6;;
+          armv6l|armhf)       docker_image=arm32v6/alpine:3.11.6;;
+          armv7l)             docker_image=arm32v7/alpine:3.11.6;;
+          aarch64)            docker_image=arm64v8/alpine:3.11.6;;
+          ppc64|ppc64le)      docker_image=ppc64le/alpine:3.11.6;;
+          s390x)              docker_image=s390x/alpine:3.11.6;;
+          *)
+            >&2 echo '[error] unable to infer docker image'
+            >&2 echo 'Please specify explicitly with `-i IMAGE`.'
+            exit 1
+          ;;
+        esac
+      fi
+    fi
+  ;;
+  freebsd|openbsd|netbsd|darwin|dragonfly)
+    if [ -n "$docker_cmd" ]; then
+      >&2 echo "[error] docker (-d) is not supported on $gitstatus_kernel"
+      exit 1
+    fi
+  ;;
+  msys_nt-*|mingw32_nt-*|mingw64_nt-*|cygwin_nt-*)
+    if ! printf '%s' "$gitstatus_kernel" | grep -Eqx '[^-]+-[0-9]+\.[0-9]+(-.*)?'; then
+      >&2 echo '[error] unsupported kernel, sorry!'
+      exit 1
+    fi
+    gitstatus_kernel="$(printf '%s' "$gitstatus_kernel" | sed 's/^\([^-]*-[0-9]*\.[0-9]*\).*/\1/')"
+    if [ -n "$docker_cmd" ]; then
+      >&2 echo '[error] docker (-d) is not supported on windows'
+      exit 1
+    fi
+    if [ -n "$gitstatus_install_tools" -a -z "${gitstatus_kernel##cygwin_nt-*}" ]; then
+      >&2 echo '[error] -s is not supported on cygwin'
+      exit 1
+    fi
+  ;;
+  *)
+    >&2 echo '[error] unsupported kernel, sorry!'
+    exit 1
+  ;;
+esac
+
+dir="$(dirname -- "$0")"
+cd -- "$dir"
+dir="$(pwd)"
+
+>&2 echo "Building gitstatusd..."
+>&2 echo ""
+>&2 echo "  kernel := $gitstatus_kernel"
+>&2 echo "  arch := $gitstatus_arch"
+>&2 echo "  cpu := $gitstatus_cpu"
+[ -z "$docker_cmd" ] || >&2 echo "  docker command := $docker_cmd"
+[ -z "$docker_image"  ] || >&2 echo "  docker image := $docker_image"
+if [ -n "$gitstatus_install_tools" ]; then
+  >&2 echo "  install tools := yes"
+else
+  >&2 echo "  install tools := no"
+fi
+if [ -n "$gitstatus_download_deps" ]; then
+  >&2 echo "  download deps := yes"
+else
+  >&2 echo "  download deps := no"
+fi
+
+if [ -n "$docker_cmd" ]; then
+  "$docker_cmd" run                                       \
+    -e docker_cmd="$docker_cmd"                           \
+    -e docker_image="$docker_image"                       \
+    -e gitstatus_kernel="$gitstatus_kernel"               \
+    -e gitstatus_arch="$gitstatus_arch"                   \
+    -e gitstatus_cpu="$gitstatus_cpu"                     \
+    -e gitstatus_install_tools="$gitstatus_install_tools" \
+    -e gitstatus_download_deps="$gitstatus_download_deps" \
+    -v "$dir":/out                                        \
+    -w /out                                               \
+    --rm                                                  \
+    -- "$docker_image" /bin/sh -uexc "$build"
+else
+  eval "$build"
+fi
@@ -0,0 +1,22 @@
+# This value gets embedded in gitstatusd at build time. It is
+# read by ./Makefile. `gitstatusd --version` reports it back.
+#
+# This value is also read by shell bindings (indirectly, through
+# ./install) when using GITSTATUS_DAEMON or usrbin/gitstatusd.
+gitstatus_version="v1.5.4"
+
+# libgit2 is a build time dependency of gitstatusd. The values of
+# libgit2_version and libgit2_sha256 are read by ./build.
+#
+# If ./deps/libgit2-${libgit2_version}.tar.gz doesn't exist, build
+# downloads it from the following location:
+#
+#   https://github.com/romkatv/libgit2/archive/${libgit2_version}.tar.gz
+#
+# Once downloaded, the tarball is stored at the path indicated
+# above so that repeated builds don't consume network bandwidth.
+#
+# If sha256 of ./deps/libgit2-${libgit2_version}.tar.gz doesn't match,
+# build gets aborted.
+libgit2_version="tag-2ecf33948a4df9ef45a66c68b8ef24a5e60eaac6"
+libgit2_sha256="4ce11d71ee576dbbc410b9fa33a9642809cc1fa687b315f7c23eeb825b251e93"
@@ -0,0 +1,330 @@
+# Fast directory listing
+
+In order to find untracked files in a git repository, [gitstatusd](../README.md) needs to list the
+contents of every directory. gitstatusd does it 27% faster than a reasonable implementation that a
+seasoned C/C++ practitioner might write. This document explains the optimizations that went into it.
+As directory listing is a common operation, many other projects can benefit from applying these
+optimizations.
+
+## v1
+
+Given a path to a directory, `ListDir()` must produce the list of files in that directory. Moreover,
+the list must be sorted lexicographically to enable fast comparison with Git index.
+
+The following C++ implementation gets the job done. For simplicity, it returns an empty list on
+error.
+
+```c++
+vector<string> ListDir(const char* dirname) {
+  vector<string> entries;
+  if (DIR* dir = opendir(dirname)) {
+    while (struct dirent* ent = (errno = 0, readdir(dir))) {
+      if (!Dots(ent->d_name)) entries.push_back(ent->d_name);
+    }
+    if (errno) entries.clear();
+    sort(entries.begin(), entries.end());
+    closedir(dir);
+  }
+  return entries;
+}
+```
+
+Every directory has entries `"."` and `".."`, which we aren't interested in. We filter them out with
+a helper function `Dots()`.
+
+```c++
+bool Dots(const char* s) { return s[0] == '.' && (!s[1] || (s[1] == '.' && !s[2])); }
+```
+
+To check how fast `ListDir()` performs, we can run it many times on a typical directory. One million
+runs on a directory with 32 files with 16-character names takes 12.7 seconds.
+
+## v2
+
+Experienced C++ practitioners will scoff at our implementation of `ListDir()`. If it's meant to be
+efficient, returning `vector<string>` is an unaffordable convenience. To avoid heap allocations we
+can use a simple arena that will allow us to reuse memory between different `ListDir()` calls.
+
+(Changed and added lines are marked with comments.)
+
+```c++
+void ListDir(const char* dirname, string& arena, vector<char*>& entries) {  // +
+  entries.clear();                                                          // +
+  if (DIR* dir = opendir(dirname)) {
+    arena.clear();                                                          // +
+    while (struct dirent* ent = (errno = 0, readdir(dir))) {
+      if (!Dots(ent->d_name)) {
+        entries.push_back(reinterpret_cast<char*>(arena.size()));           // +
+        arena.append(ent->d_name, strlen(ent->d_name) + 1);                 // +
+      }
+    }
+    if (errno) entries.clear();
+    for (char*& p : entries) p = &arena[reinterpret_cast<size_t>(p)];      // +
+    sort(entries.begin(), entries.end(),                                   // +
+         [](const char* a, const char* b) { return strcmp(a, b) < 0; });   // +
+    closedir(dir);
+  }
+}
+```
+
+To make performance comparison easier, we can normalize them relative to the baseline. v1 will get
+performance score of 100. A twice-as-fast alternative will be 200.
+
+| version |     optimization           |     score |
+|---------|----------------------------|----------:|
+| v1      | baseline                   |     100.0 |
+| **v2**  | **avoid heap allocations** | **112.7** |
+
+Avoiding heap allocations makes `ListDir()` 12.7% faster. Not bad. As an added bonus, those casts
+will fend off the occasional frontend developer who accidentally wanders into the codebase.
+
+## v3
+
+`opendir()` is an expensive call whose performance is linear in the number of subdirectories in the
+path because it needs to perform a lookup for every one of them. We can replace it with `openat()`,
+which takes a file descriptor to the parent directory and a name of the subdirectory. Just a single
+lookup, less CPU time. This optimization assumes that callers already have a descriptor to the
+parent directory, which is indeed the case for gitstatusd, and is often the case in other
+applications that traverse filesystem.
+
+```c++
+void ListDir(int parent_fd, const char* dirname, string& arena, vector<char*>& entries) {   // +
+  entries.clear();
+  int dir_fd = openat(parent_fd, dirname, O_NOATIME | O_RDONLY | O_DIRECTORY | O_CLOEXEC);  // +
+  if (dir_fd < 0) return;                                                                   // +
+  if (DIR* dir = fdopendir(dir_fd)) {
+    arena.clear();
+    while (struct dirent* ent = (errno = 0, readdir(dir))) {
+      if (!Dots(ent->d_name)) {
+        entries.push_back(reinterpret_cast<char*>(arena.size()));
+        arena.append(ent->d_name, strlen(ent->d_name) + 1);
+      }
+    }
+    if (errno) entries.clear();
+    for (char*& p : entries) p = &arena[reinterpret_cast<size_t>(p)];
+    sort(entries.begin(), entries.end(),
+         [](const char* a, const char* b) { return strcmp(a, b) < 0; });
+    closedir(dir);
+  } else {                                                                                  // +
+    close(dir_fd);                                                                          // +
+  }                                                                                         // +
+}
+```
+
+This is worth about 3.5% in speed.
+
+| version | optimization                         |     score |
+|---------|--------------------------------------|----------:|
+| v1      | baseline                             |     100.0 |
+| v2      | avoid heap allocations               |     112.7 |
+| **v3**  | **open directories with `openat()`** | **116.2** |
+
+## v4
+
+Copying file names to the arena isn't free but it doesn't seem like we can avoid it. Poking around
+we can see that the POSIX API we are using is implemented on Linux on top of `getdents64` system
+call. Its documentation isn't very encouraging:
+
+```text
+These are not the interfaces you are interested in.  Look at
+readdir(3) for the POSIX-conforming C library interface.  This page
+documents the bare kernel system call interfaces.
+
+Note: There are no glibc wrappers for these system calls.
+```
+
+Hmm... The API looks like something we can take advantage of, so let's try it anyway.
+
+First, we'll need a simple `Arena` class that can allocate 8KB blocks of memory.
+
+```c++
+class Arena {
+ public:
+  enum { kBlockSize = 8 << 10 };
+
+  char* Alloc() {
+    if (cur_ == blocks_.size()) blocks_.emplace_back(kBlockSize, 0);
+    return blocks_[cur_++].data();
+  }
+
+  void Clear() { cur_ = 0; }
+
+ private:
+  size_t cur_ = 0;
+  vector<string> blocks_;
+};
+```
+
+Next, we need to define `struct dirent64_t` ourselves because there is no wrapper for the system
+call we are about to use.
+
+```c++
+struct dirent64_t {
+  ino64_t d_ino;
+  off64_t d_off;
+  unsigned short d_reclen;
+  unsigned char d_type;
+  char d_name[];
+};
+```
+
+Finally we can get to the implementation of `ListDir()`.
+
+```c++
+void ListDir(int parent_fd, Arena& arena, vector<char*>& entries) {                       // +
+  entries.clear();
+  int dir_fd = openat(parent_fd, dirname, O_NOATIME | O_RDONLY | O_DIRECTORY | O_CLOEXEC);
+  if (dir_fd < 0) return;
+  arena.Clear();                                                                          // +
+  while (true) {                                                                          // +
+    char* buf = arena.Alloc();                                                            // +
+    int n = syscall(SYS_getdents64, dir_fd, buf, Arena::kBlockSize);                      // +
+    if (n <= 0) {                                                                         // +
+      if (n) entries.clear();                                                             // +
+      break;                                                                              // +
+    }                                                                                     // +
+    for (int pos = 0; pos < n;) {                                                         // +
+      auto* ent = reinterpret_cast<dirent64_t*>(buf + pos);                               // +
+      if (!Dots(ent->d_name)) entries.push_back(ent->d_name);                             // +
+      pos += ent->d_reclen;                                                               // +
+    }                                                                                     // +
+  }                                                                                       // +
+  sort(entries.begin(), entries.end(),
+       [](const char* a, const char* b) { return strcmp(a, b) < 0; });
+  close(dir_fd);
+}
+```
+
+How are we doing with this one?
+
+| version | optimization                     |     score |
+|---------|----------------------------------|----------:|
+| v1      | baseline                         |     100.0 |
+| v2      | avoid heap allocations           |     112.7 |
+| v3      | open directories with `openat()` |     116.2 |
+| **v4**  | **call `getdents64()` directly** | **137.8** |
+
+Solid 20% speedup. Worth the trouble. Unfortunately, we now have just one `reinterpret_cast` instead
+of two, and it's not nearly as scary-looking. Hopefully with the next iteration we can get back some
+of that evil vibe of low-level code.
+
+As a bonus, every element in `entries` has `d_type` at offset -1. This can be useful to the callers
+that need to distinguish between regular files and directories (gitstatusd, in fact, needs this).
+Note how `ListDir()` implements this feature at zero cost, as a lucky accident of `dirent64_t`
+memory layout.
+
+## v5
+
+The CPU profile of `ListDir()` reveals that almost all userspace CPU time is spent in `strcmp()`.
+Digging into the source code of `std::sort()` we can see that it uses Insertion Sort for short
+collections. Our 32-element vector falls under the threshold. Insertion Sort makes `O(N^2)`
+comparisons, hence a lot of CPU time in `strcmp()`. Switching to `qsort()` or
+[Timsort](https://en.wikipedia.org/wiki/Timsort) is of no use as all good sorting algorithms fall
+back to Insertion Sort.
+
+If we cannot make fewer comparisons, perhaps we can make each of them faster? `strcmp()` compares
+characters one at a time. It cannot read ahead as it can be illegal to touch memory past the first
+null byte. But _we_ know that it's safe to read a few extra bytes past the end of `d_name` for every
+entry except the last in the buffer. And since we own the buffer, we can overallocate it so that
+reading past the end of the last entry is also safe.
+
+Combining these ideas with the fact that file names on Linux are at most 255 bytes long, we can
+invoke `getdents64()` like this:
+
+```c++
+int n = syscall(SYS_getdents64, dir_fd, buf, Arena::kBlockSize - 256);
+```
+
+And then compare entries like this:
+
+```c++
+[](const char* a, const char* b) { return memcmp(a, b, 255) < 0; }
+```
+
+This version doesn't give any speedup compared to the previous but it opens an avenue for another
+optimization. The pointers we pass to `memcmp()` aren't aligned. To be more specific, their
+numerical values are `N * 8 + 3` for some `N`. When given such a pointer, `memcmp()` will check the
+first 5 bytes one by one, and only then switch to comparing 8 bytes at a time. If we can handle the
+first 5 bytes ourselves, we can pass aligned memory to `memcmp()` and take full advantage of its
+vectorized loop.
+
+Here's the implementation:
+
+```c++
+uint64_t Read64(const void* p) {                                                          // +
+  uint64_t x;                                                                             // +
+  memcpy(&x, p, sizeof(x));                                                               // +
+  return x;                                                                               // +
+}                                                                                         // +
+
+void ByteSwap64(void* p) {                                                                // +
+  uint64_t x = __builtin_bswap64(Read64(p));                                              // +
+  memcpy(p, &x, sizeof(x));                                                               // +
+}                                                                                         // +
+
+void ListDir(int parent_fd, Arena& arena, vector<char*>& entries) {
+  entries.clear();
+  int dir_fd = openat(parent_fd, dirname, O_NOATIME | O_RDONLY | O_DIRECTORY | O_CLOEXEC);
+  if (dir_fd < 0) return;
+  arena.Clear();
+  while (true) {
+    char* buf = arena.Alloc();
+    int n = syscall(SYS_getdents64, dir_fd, buf, Arena::kBlockSize - 256);                // +
+    if (n <= 0) {
+      if (n) entries.clear();
+      break;
+    }
+    for (int pos = 0; pos < n;) {
+      auto* ent = reinterpret_cast<dirent64_t*>(buf + pos);
+      if (!Dots(ent->d_name)) {
+        ByteSwap64(ent->d_name);                                                          // +
+        entries.push_back(ent->d_name);
+      }
+      pos += ent->d_reclen;
+    }
+  }
+  sort(entries.begin(), entries.end(), [](const char* a, const char* b) {
+    uint64_t x = Read64(a);                                                               // +
+    uint64_t y = Read64(b);                                                               // +
+    return x < y || (x == y && a != b && memcmp(a + 5, b + 5, 256) < 0);                  // +
+  });
+  for (char* p : entries) ByteSwap64(p);                                                  // +
+  close(dir_fd);
+}
+```
+
+This is for Little Endian architecture. Big Endian doesn't need `ByteSwap64()`, so it'll be a bit
+faster.
+
+| version | optimization                     |     score |
+|---------|----------------------------------|----------:|
+| v1      | baseline                         |     100.0 |
+| v2      | avoid heap allocations           |     112.7 |
+| v3      | open directories with `openat()` |     116.2 |
+| v4      | call `getdents64()` directly     |     137.8 |
+| **v5**  | **hand-optimize `strcmp()`**     | **143.3** |
+
+Fast and respectably arcane.
+
+## Conclusion
+
+Through a series of incremental improvements we've sped up directory listing by 43.3% compared to a
+naive implementation (v1) and 27.2% compared to a reasonable implementation that a seasoned C/C++
+practitioner might write (v2).
+
+However, these numbers are based on an artificial benchmark while the real judge is always the real
+code. Our goal was to speed up gitstatusd. Benchmark was just a tool. Thankfully, the different
+versions of `ListDir()` have the same comparative performance within gitstatusd as in the benchmark.
+In truth, the directory chosen for the benchmark wasn't arbitrary. It was picked by sampling
+gitstatusd when it runs on [chromium](https://github.com/chromium/chromium) git repository.
+
+The final version of `ListDir()` spends 97% of its CPU time in the kernel. If we assume that it
+makes the minimum possible number of system calls and these calls are optimal (true to the best
+of my knowledge), it puts the upper bound on possible future performance improvements at just 3%.
+There is almost nothing left in `ListDir()` to optimize.
+
+![ListDir() CPU profile](
+  https://raw.githubusercontent.com/romkatv/gitstatus/1ac366952366d89980b3f3484f270b4fa5ae4293/cpu-profile-listdir.png)
+
+(The CPU profile was created with [gperftools](https://github.com/gperftools/gperftools) and
+rendered with [pprof](https://github.com/google/pprof)).
@@ -0,0 +1,474 @@
+# Bash bindings for gitstatus.
+
+[[ $- == *i* ]] || return  # non-interactive shell
+
+# Starts gitstatusd in the background. Does nothing and succeeds if gitstatusd
+# is already running.
+#
+# Usage: gitstatus_start [OPTION]...
+#
+#   -t FLOAT  Fail the self-check on initialization if not getting a response from
+#             gitstatusd for this this many seconds. Defaults to 5.
+#
+#   -s INT    Report at most this many staged changes; negative value means infinity.
+#             Defaults to 1.
+#
+#   -u INT    Report at most this many unstaged changes; negative value means infinity.
+#             Defaults to 1.
+#
+#   -c INT    Report at most this many conflicted changes; negative value means infinity.
+#             Defaults to 1.
+#
+#   -d INT    Report at most this many untracked files; negative value means infinity.
+#             Defaults to 1.
+#
+#   -m INT    Report -1 unstaged, untracked and conflicted if there are more than this many
+#             files in the index. Negative value means infinity. Defaults to -1.
+#
+#   -e        Count files within untracked directories like `git status --untracked-files`.
+#
+#   -U        Unless this option is specified, report zero untracked files for repositories
+#             with status.showUntrackedFiles = false.
+#
+#   -W        Unless this option is specified, report zero untracked files for repositories
+#             with bash.showUntrackedFiles = false.
+#
+#   -D        Unless this option is specified, report zero staged, unstaged and conflicted
+#             changes for repositories with bash.showDirtyState = false.
+#
+#   -r INT    Close git repositories that haven't been used for this many seconds. This is
+#             meant to release resources such as memory and file descriptors. The next request
+#             for a repo that's been closed is much slower than for a repo that hasn't been.
+#             Negative value means infinity. The default is 3600 (one hour).
+function gitstatus_start() {
+  if [[ "$BASH_VERSION" < 4 ]]; then
+    >&2 printf 'gitstatus_start: need bash version >= 4.0, found %s\n' "$BASH_VERSION"
+    >&2 printf '\n'
+    >&2 printf 'To see the version of the current shell, type:\n'
+    >&2 printf '\n'
+    >&2 printf '    \033[32mecho\033[0m \033[33m"$BASH_VERSION"\033[0m\n'
+    >&2 printf '\n'
+    >&2 printf 'The output of `\033[32mbash\033[0m --version` may be different and is not relevant.\n'
+    return 1
+  fi
+
+  unset OPTIND
+  local opt timeout=5 max_dirty=-1 ttl=3600 extra_flags=
+  local max_num_staged=1 max_num_unstaged=1 max_num_conflicted=1 max_num_untracked=1
+  while getopts "t:s:u:c:d:m:r:eUWD" opt; do
+    case "$opt" in
+      t) timeout=$OPTARG;;
+      s) max_num_staged=$OPTARG;;
+      u) max_num_unstaged=$OPTARG;;
+      c) max_num_conflicted=$OPTARG;;
+      d) max_num_untracked=$OPTARG;;
+      m) max_dirty=$OPTARG;;
+      r) ttl=$OPTARG;;
+      e) extra_flags+='--recurse-untracked-dirs ';;
+      U) extra_flags+='--ignore-status-show-untracked-files ';;
+      W) extra_flags+='--ignore-bash-show-untracked-files ';;
+      D) extra_flags+='--ignore-bash-show-dirty-state ';;
+      *) return 1;;
+    esac
+  done
+
+  (( OPTIND == $# + 1 )) || { echo "usage: gitstatus_start [OPTION]..." >&2; return 1; }
+
+  [[ -z "${GITSTATUS_DAEMON_PID:-}" ]] || return 0  # already started
+
+  if [[ "${BASH_SOURCE[0]}" == */* ]]; then
+    local gitstatus_plugin_dir="${BASH_SOURCE[0]%/*}"
+    if [[ "$gitstatus_plugin_dir" != /* ]]; then
+      gitstatus_plugin_dir="$PWD"/"$gitstatus_plugin_dir"
+    fi
+  else
+    local gitstatus_plugin_dir="$PWD"
+  fi
+
+  local tmpdir req_fifo resp_fifo culprit
+
+  function gitstatus_start_impl() {
+    local log_level="${GITSTATUS_LOG_LEVEL:-}"
+    [[ -n "$log_level" || "${GITSTATUS_ENABLE_LOGGING:-0}" != 1 ]] || log_level=INFO
+
+    local uname_sm
+    uname_sm="$(command uname -sm)" || return
+    uname_sm="${uname_sm,,}"
+    local uname_s="${uname_sm% *}"
+    local uname_m="${uname_sm#* }"
+
+    if [[ "${GITSTATUS_NUM_THREADS:-0}" -gt 0 ]]; then
+      local threads="$GITSTATUS_NUM_THREADS"
+    else
+      local cpus
+      if ! command -v sysctl &>/dev/null || [[ "$uname_s" == linux ]] ||
+         ! cpus="$(command sysctl -n hw.ncpu)"; then
+        if ! command -v getconf &>/dev/null || ! cpus="$(command getconf _NPROCESSORS_ONLN)"; then
+          cpus=8
+        fi
+      fi
+      local threads=$((cpus > 16 ? 32 : cpus > 0 ? 2 * cpus : 16))
+    fi
+
+    local daemon_args=(
+      --parent-pid="$$"
+      --num-threads="$threads"
+      --max-num-staged="$max_num_staged"
+      --max-num-unstaged="$max_num_unstaged"
+      --max-num-conflicted="$max_num_conflicted"
+      --max-num-untracked="$max_num_untracked"
+      --dirty-max-index-size="$max_dirty"
+      --repo-ttl-seconds="$ttl"
+      $extra_flags)
+
+    if [[ -n "$TMPDIR" && ( ( -d "$TMPDIR" && -w "$TMPDIR" ) || ! ( -d /tmp && -w /tmp ) ) ]]; then
+      local tmpdir=$TMPDIR
+    else
+      local tmpdir=/tmp
+    fi
+    tmpdir="$(command mktemp -d "$tmpdir"/gitstatus.bash.$$.XXXXXXXXXX)" || return
+
+    if [[ -n "$log_level" ]]; then
+      GITSTATUS_DAEMON_LOG="$tmpdir"/daemon.log
+      [[ "$log_level" == INFO ]] || daemon_args+=(--log-level="$log_level")
+    else
+      GITSTATUS_DAEMON_LOG=/dev/null
+    fi
+
+    req_fifo="$tmpdir"/req.fifo
+    resp_fifo="$tmpdir"/resp.fifo
+    command mkfifo -- "$req_fifo" "$resp_fifo" || return
+
+    {
+      (
+        trap '' INT QUIT TSTP
+        [[ "$GITSTATUS_DAEMON_LOG" == /dev/null ]] || set -x
+        builtin cd /
+
+        (
+          local fd_in fd_out
+          exec {fd_in}<"$req_fifo" {fd_out}>>"$resp_fifo" || exit
+          echo "$BASHPID" >&"$fd_out"
+
+          local _gitstatus_bash_daemon _gitstatus_bash_version _gitstatus_bash_downloaded
+
+          function _gitstatus_set_daemon() {
+            _gitstatus_bash_daemon="$1"
+            _gitstatus_bash_version="$2"
+            _gitstatus_bash_downloaded="$3"
+          }
+
+          set -- -d "$gitstatus_plugin_dir" -s "$uname_s" -m "$uname_m" \
+            -p "printf '.\036' >&$fd_out" -e "$fd_out" -- _gitstatus_set_daemon
+          [[ "${GITSTATUS_AUTO_INSTALL:-1}" -ne 0 ]]  || set -- -n "$@"
+          source "$gitstatus_plugin_dir"/install      || return
+          [[ -n "$_gitstatus_bash_daemon" ]]          || return
+          [[ -n "$_gitstatus_bash_version" ]]         || return
+          [[ "$_gitstatus_bash_downloaded" == [01] ]] || return
+
+          local sig=(TERM ILL PIPE)
+
+          if (( UID == EUID )); then
+            local home=~
+          else
+            local user
+            user="$(command id -un)"            || return
+            [[ "$user" =~ ^[a-zA-Z0-9_,.-]+$ ]] || return
+            eval "local home=~$user"
+            [[ -n "$home" ]]                    || return
+          fi
+
+          if [[ -x "$_gitstatus_bash_daemon" ]]; then
+            HOME="$home" "$_gitstatus_bash_daemon" \
+              -G "$_gitstatus_bash_version" "${daemon_args[@]}" <&"$fd_in" >&"$fd_out" &
+            local pid=$!
+            trap "trap - ${sig[*]}; kill $pid &>/dev/null" ${sig[@]}
+            wait "$pid"
+            local ret=$?
+            trap - ${sig[@]}
+            case "$ret" in
+              0|129|130|131|137|141|143|159)
+                echo -nE $'}bye\x1f0\x1e' >&"$fd_out"
+                exit "$ret"
+              ;;
+            esac
+          fi
+
+          (( ! _gitstatus_bash_downloaded ))         || return
+          [[ "${GITSTATUS_AUTO_INSTALL:-1}" -ne 0 ]] || return
+          [[ "$_gitstatus_bash_daemon" == \
+             "${GITSTATUS_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/gitstatus}"/* ]] || return
+
+          set -- -f "$@"
+          _gitstatus_bash_daemon=
+          _gitstatus_bash_version=
+          _gitstatus_bash_downloaded=
+          source "$gitstatus_plugin_dir"/install   || return
+          [[ -n "$_gitstatus_bash_daemon" ]]       || return
+          [[ -n "$_gitstatus_bash_version" ]]      || return
+          [[ "$_gitstatus_bash_downloaded" == 1 ]] || return
+
+          HOME="$home" "$_gitstatus_bash_daemon" \
+            -G "$_gitstatus_bash_version" "${daemon_args[@]}" <&"$fd_in" >&"$fd_out" &
+          local pid=$!
+          trap "trap - ${sig[*]}; kill $pid &>/dev/null" ${sig[@]}
+          wait "$pid"
+          trap - ${sig[@]}
+          echo -nE $'}bye\x1f0\x1e' >&"$fd_out"
+        ) & disown
+      ) & disown
+    } 0</dev/null &>"$GITSTATUS_DAEMON_LOG"
+
+    exec {_GITSTATUS_REQ_FD}>>"$req_fifo" {_GITSTATUS_RESP_FD}<"$resp_fifo"   || return
+    command rm -f -- "$req_fifo" "$resp_fifo"                                 || return
+    [[ "$GITSTATUS_DAEMON_LOG" != /dev/null ]] || command rmdir -- "$tmpdir" 2>/dev/null
+
+    IFS='' read -r -u $_GITSTATUS_RESP_FD GITSTATUS_DAEMON_PID || return
+    [[ "$GITSTATUS_DAEMON_PID" == [1-9]* ]] || return
+
+    local reply
+    echo -nE $'}hello\x1f\x1e' >&$_GITSTATUS_REQ_FD || return
+    local dl=
+    while true; do
+      reply=
+      if ! IFS='' read -rd $'\x1e' -u $_GITSTATUS_RESP_FD -t "$timeout" reply; then
+        culprit="$reply"
+        return 1
+      fi
+      [[ "$reply" == $'}hello\x1f0' ]] && break
+      if [[ -z "$dl" ]]; then
+        dl=1
+        if [[ -t 2 ]]; then
+          local spinner=('\b\033[33m-\033[0m' '\b\033[33m\\\033[0m' '\b\033[33m|\033[0m' '\b\033[33m/\033[0m')
+          >&2 printf '[\033[33mgitstatus\033[0m] fetching \033[32mgitstatusd\033[0m ..  '
+        else
+          local spinner=('.')
+          >&2 printf '[gitstatus] fetching gitstatusd ..'
+        fi
+      fi
+      >&2 printf "${spinner[0]}"
+      spinner=("${spinner[@]:1}" "${spinner[0]}")
+    done
+
+    if [[ -n "$dl" ]]; then
+      if [[ -t 2 ]]; then
+        >&2 printf '\b[\033[32mok\033[0m]\n'
+      else
+        >&2 echo ' [ok]'
+      fi
+    fi
+
+    _GITSTATUS_DIRTY_MAX_INDEX_SIZE=$max_dirty
+    _GITSTATUS_CLIENT_PID="$BASHPID"
+  }
+
+  if ! gitstatus_start_impl; then
+    >&2 printf '\n'
+    >&2 printf '[\033[31mERROR\033[0m]: gitstatus failed to initialize.\n'
+    if [[ -n "${culprit-}" ]]; then
+      >&2 printf '\n%s\n' "$culprit"
+    fi
+    [[ -z "${req_fifo:-}"  ]] || command rm -f "$req_fifo"
+    [[ -z "${resp_fifo:-}" ]] || command rm -f "$resp_fifo"
+    unset -f gitstatus_start_impl
+    gitstatus_stop
+    return 1
+  fi
+
+  export _GITSTATUS_CLIENT_PID _GITSTATUS_REQ_FD _GITSTATUS_RESP_FD GITSTATUS_DAEMON_PID
+  unset -f gitstatus_start_impl
+}
+
+# Stops gitstatusd if it's running.
+function gitstatus_stop() {
+  if [[ "${_GITSTATUS_CLIENT_PID:-$BASHPID}" == "$BASHPID" ]]; then
+    [[ -z "${_GITSTATUS_REQ_FD:-}"    ]] || exec {_GITSTATUS_REQ_FD}>&-              || true
+    [[ -z "${_GITSTATUS_RESP_FD:-}"   ]] || exec {_GITSTATUS_RESP_FD}>&-             || true
+    [[ -z "${GITSTATUS_DAEMON_PID:-}" ]] || kill "$GITSTATUS_DAEMON_PID" &>/dev/null || true
+  fi
+  unset _GITSTATUS_REQ_FD _GITSTATUS_RESP_FD GITSTATUS_DAEMON_PID
+  unset _GITSTATUS_DIRTY_MAX_INDEX_SIZE _GITSTATUS_CLIENT_PID
+}
+
+# Retrieves status of a git repository from a directory under its working tree.
+#
+# Usage: gitstatus_query [OPTION]...
+#
+#   -d STR    Directory to query. Defaults to $PWD. Has no effect if GIT_DIR is set.
+#   -t FLOAT  Timeout in seconds. Will block for at most this long. If no results
+#             are available by then, will return error.
+#   -p        Don't compute anything that requires reading Git index. If this option is used,
+#             the following parameters will be 0: VCS_STATUS_INDEX_SIZE,
+#             VCS_STATUS_{NUM,HAS}_{STAGED,UNSTAGED,UNTRACKED,CONFLICTED}.
+#
+# On success sets VCS_STATUS_RESULT to one of the following values:
+#
+#   norepo-sync  The directory doesn't belong to a git repository.
+#   ok-sync      The directory belongs to a git repository.
+#
+# If VCS_STATUS_RESULT is ok-sync, additional variables are set:
+#
+#   VCS_STATUS_WORKDIR              Git repo working directory. Not empty.
+#   VCS_STATUS_COMMIT               Commit hash that HEAD is pointing to. Either 40 hex digits or
+#                                   empty if there is no HEAD (empty repo).
+#   VCS_STATUS_COMMIT_ENCODING      Encoding of the HEAD's commit message. Empty value means UTF-8.
+#   VCS_STATUS_COMMIT_SUMMARY       The first paragraph of the HEAD's commit message as one line.
+#   VCS_STATUS_LOCAL_BRANCH         Local branch name or empty if not on a branch.
+#   VCS_STATUS_REMOTE_NAME          The remote name, e.g. "upstream" or "origin".
+#   VCS_STATUS_REMOTE_BRANCH        Upstream branch name. Can be empty.
+#   VCS_STATUS_REMOTE_URL           Remote URL. Can be empty.
+#   VCS_STATUS_ACTION               Repository state, A.K.A. action. Can be empty.
+#   VCS_STATUS_INDEX_SIZE           The number of files in the index.
+#   VCS_STATUS_NUM_STAGED           The number of staged changes.
+#   VCS_STATUS_NUM_CONFLICTED       The number of conflicted changes.
+#   VCS_STATUS_NUM_UNSTAGED         The number of unstaged changes.
+#   VCS_STATUS_NUM_UNTRACKED        The number of untracked files.
+#   VCS_STATUS_HAS_STAGED           1 if there are staged changes, 0 otherwise.
+#   VCS_STATUS_HAS_CONFLICTED       1 if there are conflicted changes, 0 otherwise.
+#   VCS_STATUS_HAS_UNSTAGED         1 if there are unstaged changes, 0 if there aren't, -1 if
+#                                   unknown.
+#   VCS_STATUS_NUM_STAGED_NEW       The number of staged new files. Note that renamed files
+#                                   are reported as deleted plus new.
+#   VCS_STATUS_NUM_STAGED_DELETED   The number of staged deleted files. Note that renamed files
+#                                   are reported as deleted plus new.
+#   VCS_STATUS_NUM_UNSTAGED_DELETED The number of unstaged deleted files. Note that renamed files
+#                                   are reported as deleted plus new.
+#   VCS_STATUS_HAS_UNTRACKED        1 if there are untracked files, 0 if there aren't, -1 if
+#                                   unknown.
+#   VCS_STATUS_COMMITS_AHEAD        Number of commits the current branch is ahead of upstream.
+#                                   Non-negative integer.
+#   VCS_STATUS_COMMITS_BEHIND       Number of commits the current branch is behind upstream.
+#                                   Non-negative integer.
+#   VCS_STATUS_STASHES              Number of stashes. Non-negative integer.
+#   VCS_STATUS_TAG                  The last tag (in lexicographical order) that points to the same
+#                                   commit as HEAD.
+#   VCS_STATUS_PUSH_REMOTE_NAME     The push remote name, e.g. "upstream" or "origin".
+#   VCS_STATUS_PUSH_REMOTE_URL      Push remote URL. Can be empty.
+#   VCS_STATUS_PUSH_COMMITS_AHEAD   Number of commits the current branch is ahead of push remote.
+#                                   Non-negative integer.
+#   VCS_STATUS_PUSH_COMMITS_BEHIND  Number of commits the current branch is behind push remote.
+#                                   Non-negative integer.
+#   VCS_STATUS_NUM_SKIP_WORKTREE    The number of files in the index with skip-worktree bit set.
+#                                   Non-negative integer.
+#   VCS_STATUS_NUM_ASSUME_UNCHANGED The number of files in the index with assume-unchanged bit set.
+#                                   Non-negative integer.
+#
+# The point of reporting -1 via VCS_STATUS_HAS_* is to allow the command to skip scanning files in
+# large repos. See -m flag of gitstatus_start.
+#
+# gitstatus_query returns an error if gitstatus_start hasn't been called in the same
+# shell or the call had failed.
+function gitstatus_query() {
+  unset OPTIND
+  local opt dir= timeout=() no_diff=0
+  while getopts "d:c:t:p" opt "$@"; do
+    case "$opt" in
+      d) dir=$OPTARG;;
+      t) timeout=(-t "$OPTARG");;
+      p) no_diff=1;;
+      *) return 1;;
+    esac
+  done
+  (( OPTIND == $# + 1 )) || { echo "usage: gitstatus_query [OPTION]..." >&2; return 1; }
+
+  [[ -n "${GITSTATUS_DAEMON_PID-}" ]] || return  # not started
+
+  local req_id="$RANDOM.$RANDOM.$RANDOM.$RANDOM"
+  if [[ -z "${GIT_DIR:-}" ]]; then
+    [[ "$dir" == /* ]] || dir="$(pwd -P)/$dir" || return
+  elif [[ "$GIT_DIR" == /* ]]; then
+    dir=:"$GIT_DIR"
+  else
+    dir=:"$(pwd -P)/$GIT_DIR" || return
+  fi
+  echo -nE "$req_id"$'\x1f'"$dir"$'\x1f'"$no_diff"$'\x1e' >&$_GITSTATUS_REQ_FD || return
+
+  local -a resp
+  while true; do
+    IFS=$'\x1f' read -rd $'\x1e' -a resp -u $_GITSTATUS_RESP_FD "${timeout[@]}" || return
+    [[ "${resp[0]}" == "$req_id" ]] && break
+  done
+
+  if [[ "${resp[1]}" == 1 ]]; then
+    VCS_STATUS_RESULT=ok-sync
+    VCS_STATUS_WORKDIR="${resp[2]}"
+    VCS_STATUS_COMMIT="${resp[3]}"
+    VCS_STATUS_LOCAL_BRANCH="${resp[4]}"
+    VCS_STATUS_REMOTE_BRANCH="${resp[5]}"
+    VCS_STATUS_REMOTE_NAME="${resp[6]}"
+    VCS_STATUS_REMOTE_URL="${resp[7]}"
+    VCS_STATUS_ACTION="${resp[8]}"
+    VCS_STATUS_INDEX_SIZE="${resp[9]}"
+    VCS_STATUS_NUM_STAGED="${resp[10]}"
+    VCS_STATUS_NUM_UNSTAGED="${resp[11]}"
+    VCS_STATUS_NUM_CONFLICTED="${resp[12]}"
+    VCS_STATUS_NUM_UNTRACKED="${resp[13]}"
+    VCS_STATUS_COMMITS_AHEAD="${resp[14]}"
+    VCS_STATUS_COMMITS_BEHIND="${resp[15]}"
+    VCS_STATUS_STASHES="${resp[16]}"
+    VCS_STATUS_TAG="${resp[17]}"
+    VCS_STATUS_NUM_UNSTAGED_DELETED="${resp[18]}"
+    VCS_STATUS_NUM_STAGED_NEW="${resp[19]:-0}"
+    VCS_STATUS_NUM_STAGED_DELETED="${resp[20]:-0}"
+    VCS_STATUS_PUSH_REMOTE_NAME="${resp[21]:-}"
+    VCS_STATUS_PUSH_REMOTE_URL="${resp[22]:-}"
+    VCS_STATUS_PUSH_COMMITS_AHEAD="${resp[23]:-0}"
+    VCS_STATUS_PUSH_COMMITS_BEHIND="${resp[24]:-0}"
+    VCS_STATUS_NUM_SKIP_WORKTREE="${resp[25]:-0}"
+    VCS_STATUS_NUM_ASSUME_UNCHANGED="${resp[26]:-0}"
+    VCS_STATUS_COMMIT_ENCODING="${resp[27]-}"
+    VCS_STATUS_COMMIT_SUMMARY="${resp[28]-}"
+    VCS_STATUS_HAS_STAGED=$((VCS_STATUS_NUM_STAGED > 0))
+    if (( _GITSTATUS_DIRTY_MAX_INDEX_SIZE >= 0 &&
+          VCS_STATUS_INDEX_SIZE > _GITSTATUS_DIRTY_MAX_INDEX_SIZE_ )); then
+      VCS_STATUS_HAS_UNSTAGED=-1
+      VCS_STATUS_HAS_CONFLICTED=-1
+      VCS_STATUS_HAS_UNTRACKED=-1
+    else
+      VCS_STATUS_HAS_UNSTAGED=$((VCS_STATUS_NUM_UNSTAGED > 0))
+      VCS_STATUS_HAS_CONFLICTED=$((VCS_STATUS_NUM_CONFLICTED > 0))
+      VCS_STATUS_HAS_UNTRACKED=$((VCS_STATUS_NUM_UNTRACKED > 0))
+    fi
+  else
+    VCS_STATUS_RESULT=norepo-sync
+    unset VCS_STATUS_WORKDIR
+    unset VCS_STATUS_COMMIT
+    unset VCS_STATUS_LOCAL_BRANCH
+    unset VCS_STATUS_REMOTE_BRANCH
+    unset VCS_STATUS_REMOTE_NAME
+    unset VCS_STATUS_REMOTE_URL
+    unset VCS_STATUS_ACTION
+    unset VCS_STATUS_INDEX_SIZE
+    unset VCS_STATUS_NUM_STAGED
+    unset VCS_STATUS_NUM_UNSTAGED
+    unset VCS_STATUS_NUM_CONFLICTED
+    unset VCS_STATUS_NUM_UNTRACKED
+    unset VCS_STATUS_HAS_STAGED
+    unset VCS_STATUS_HAS_UNSTAGED
+    unset VCS_STATUS_HAS_CONFLICTED
+    unset VCS_STATUS_HAS_UNTRACKED
+    unset VCS_STATUS_COMMITS_AHEAD
+    unset VCS_STATUS_COMMITS_BEHIND
+    unset VCS_STATUS_STASHES
+    unset VCS_STATUS_TAG
+    unset VCS_STATUS_NUM_UNSTAGED_DELETED
+    unset VCS_STATUS_NUM_STAGED_NEW
+    unset VCS_STATUS_NUM_STAGED_DELETED
+    unset VCS_STATUS_PUSH_REMOTE_NAME
+    unset VCS_STATUS_PUSH_REMOTE_URL
+    unset VCS_STATUS_PUSH_COMMITS_AHEAD
+    unset VCS_STATUS_PUSH_COMMITS_BEHIND
+    unset VCS_STATUS_NUM_SKIP_WORKTREE
+    unset VCS_STATUS_NUM_ASSUME_UNCHANGED
+    unset VCS_STATUS_COMMIT_ENCODING
+    unset VCS_STATUS_COMMIT_SUMMARY
+  fi
+}
+
+# Usage: gitstatus_check.
+#
+# Returns 0 if and only if gitstatus_start has succeeded previously.
+# If it returns non-zero, gitstatus_query is guaranteed to return non-zero.
+function gitstatus_check() {
+  [[ -n "$GITSTATUS_DAEMON_PID" ]]
+}
@@ -0,0 +1,908 @@
+# Zsh bindings for gitstatus.
+#
+# ------------------------------------------------------------------
+#
+# Example: Start gitstatusd, send it a request, wait for response and print it.
+#
+#   source ~/gitstatus/gitstatus.plugin.zsh
+#   gitstatus_start MY
+#   gitstatus_query -d $PWD MY
+#   typeset -m 'VCS_STATUS_*'
+#
+# Output:
+#
+#   VCS_STATUS_ACTION=''
+#   VCS_STATUS_COMMIT=c000eddcff0fb38df2d0137efe24d9d2d900f209
+#   VCS_STATUS_COMMITS_AHEAD=0
+#   VCS_STATUS_COMMITS_BEHIND=0
+#   VCS_STATUS_COMMIT_ENCODING=''
+#   VCS_STATUS_COMMIT_SUMMARY='pull upstream changes from gitstatus'
+#   VCS_STATUS_HAS_CONFLICTED=0
+#   VCS_STATUS_HAS_STAGED=0
+#   VCS_STATUS_HAS_UNSTAGED=1
+#   VCS_STATUS_HAS_UNTRACKED=1
+#   VCS_STATUS_INDEX_SIZE=33
+#   VCS_STATUS_LOCAL_BRANCH=master
+#   VCS_STATUS_NUM_ASSUME_UNCHANGED=0
+#   VCS_STATUS_NUM_CONFLICTED=0
+#   VCS_STATUS_NUM_STAGED=0
+#   VCS_STATUS_NUM_UNSTAGED=1
+#   VCS_STATUS_NUM_SKIP_WORKTREE=0
+#   VCS_STATUS_NUM_STAGED_NEW=0
+#   VCS_STATUS_NUM_STAGED_DELETED=0
+#   VCS_STATUS_NUM_UNSTAGED_DELETED=0
+#   VCS_STATUS_NUM_UNTRACKED=1
+#   VCS_STATUS_PUSH_COMMITS_AHEAD=0
+#   VCS_STATUS_PUSH_COMMITS_BEHIND=0
+#   VCS_STATUS_PUSH_REMOTE_NAME=''
+#   VCS_STATUS_PUSH_REMOTE_URL=''
+#   VCS_STATUS_REMOTE_BRANCH=master
+#   VCS_STATUS_REMOTE_NAME=origin
+#   VCS_STATUS_REMOTE_URL=git@github.com:romkatv/powerlevel10k.git
+#   VCS_STATUS_RESULT=ok-sync
+#   VCS_STATUS_STASHES=0
+#   VCS_STATUS_TAG=''
+#   VCS_STATUS_WORKDIR=/home/romka/powerlevel10k
+
+[[ -o 'interactive' ]] || 'return'
+
+# Temporarily change options.
+'builtin' 'local' '-a' '_gitstatus_opts'
+[[ ! -o 'aliases'         ]] || _gitstatus_opts+=('aliases')
+[[ ! -o 'sh_glob'         ]] || _gitstatus_opts+=('sh_glob')
+[[ ! -o 'no_brace_expand' ]] || _gitstatus_opts+=('no_brace_expand')
+'builtin' 'setopt' 'no_aliases' 'no_sh_glob' 'brace_expand'
+
+autoload -Uz add-zsh-hook        || return
+zmodload zsh/datetime zsh/system || return
+zmodload -F zsh/files b:zf_rm    || return
+
+typeset -g _gitstatus_plugin_dir"${1:-}"="${${(%):-%x}:A:h}"
+
+# Retrieves status of a git repo from a directory under its working tree.
+#
+## Usage: gitstatus_query [OPTION]... NAME
+#
+#   -d STR    Directory to query. Defaults to the current directory. Has no effect if GIT_DIR
+#             is set.
+#   -c STR    Callback function to call once the results are available. Called only after
+#             gitstatus_query returns 0 with VCS_STATUS_RESULT=tout.
+#   -t FLOAT  Timeout in seconds. Negative value means infinity. Will block for at most this long.
+#             If no results are available by then: if -c isn't specified, will return 1; otherwise
+#             will set VCS_STATUS_RESULT=tout and return 0.
+#   -p        Don't compute anything that requires reading Git index. If this option is used,
+#             the following parameters will be 0: VCS_STATUS_INDEX_SIZE,
+#             VCS_STATUS_{NUM,HAS}_{STAGED,UNSTAGED,UNTRACKED,CONFLICTED}.
+#
+# On success sets VCS_STATUS_RESULT to one of the following values:
+#
+#   tout         Timed out waiting for data; will call the user-specified callback later.
+#   norepo-sync  The directory isn't a git repo.
+#   ok-sync      The directory is a git repo.
+#
+# When the callback is called, VCS_STATUS_RESULT is set to one of the following values:
+#
+#   norepo-async  The directory isn't a git repo.
+#   ok-async      The directory is a git repo.
+#
+# If VCS_STATUS_RESULT is ok-sync or ok-async, additional variables are set:
+#
+#   VCS_STATUS_WORKDIR              Git repo working directory. Not empty.
+#   VCS_STATUS_COMMIT               Commit hash that HEAD is pointing to. Either 40 hex digits or
+#                                   empty if there is no HEAD (empty repo).
+#   VCS_STATUS_COMMIT_ENCODING      Encoding of the HEAD's commit message. Empty value means UTF-8.
+#   VCS_STATUS_COMMIT_SUMMARY       The first paragraph of the HEAD's commit message as one line.
+#   VCS_STATUS_LOCAL_BRANCH         Local branch name or empty if not on a branch.
+#   VCS_STATUS_REMOTE_NAME          The remote name, e.g. "upstream" or "origin".
+#   VCS_STATUS_REMOTE_BRANCH        Upstream branch name. Can be empty.
+#   VCS_STATUS_REMOTE_URL           Remote URL. Can be empty.
+#   VCS_STATUS_ACTION               Repository state, A.K.A. action. Can be empty.
+#   VCS_STATUS_INDEX_SIZE           The number of files in the index.
+#   VCS_STATUS_NUM_STAGED           The number of staged changes.
+#   VCS_STATUS_NUM_CONFLICTED       The number of conflicted changes.
+#   VCS_STATUS_NUM_UNSTAGED         The number of unstaged changes.
+#   VCS_STATUS_NUM_UNTRACKED        The number of untracked files.
+#   VCS_STATUS_HAS_STAGED           1 if there are staged changes, 0 otherwise.
+#   VCS_STATUS_HAS_CONFLICTED       1 if there are conflicted changes, 0 otherwise.
+#   VCS_STATUS_HAS_UNSTAGED         1 if there are unstaged changes, 0 if there aren't, -1 if
+#                                   unknown.
+#   VCS_STATUS_NUM_STAGED_NEW       The number of staged new files. Note that renamed files
+#                                   are reported as deleted plus new.
+#   VCS_STATUS_NUM_STAGED_DELETED   The number of staged deleted files. Note that renamed files
+#                                   are reported as deleted plus new.
+#   VCS_STATUS_NUM_UNSTAGED_DELETED The number of unstaged deleted files. Note that renamed files
+#                                   are reported as deleted plus new.
+#   VCS_STATUS_HAS_UNTRACKED        1 if there are untracked files, 0 if there aren't, -1 if
+#                                   unknown.
+#   VCS_STATUS_COMMITS_AHEAD        Number of commits the current branch is ahead of upstream.
+#                                   Non-negative integer.
+#   VCS_STATUS_COMMITS_BEHIND       Number of commits the current branch is behind upstream.
+#                                   Non-negative integer.
+#   VCS_STATUS_STASHES              Number of stashes. Non-negative integer.
+#   VCS_STATUS_TAG                  The last tag (in lexicographical order) that points to the same
+#                                   commit as HEAD.
+#   VCS_STATUS_PUSH_REMOTE_NAME     The push remote name, e.g. "upstream" or "origin".
+#   VCS_STATUS_PUSH_REMOTE_URL      Push remote URL. Can be empty.
+#   VCS_STATUS_PUSH_COMMITS_AHEAD   Number of commits the current branch is ahead of push remote.
+#                                   Non-negative integer.
+#   VCS_STATUS_PUSH_COMMITS_BEHIND  Number of commits the current branch is behind push remote.
+#                                   Non-negative integer.
+#   VCS_STATUS_NUM_SKIP_WORKTREE    The number of files in the index with skip-worktree bit set.
+#                                   Non-negative integer.
+#   VCS_STATUS_NUM_ASSUME_UNCHANGED The number of files in the index with assume-unchanged bit set.
+#                                   Non-negative integer.
+#
+# The point of reporting -1 via VCS_STATUS_HAS_* is to allow the command to skip scanning files in
+# large repos. See -m flag of gitstatus_start.
+#
+# gitstatus_query returns an error if gitstatus_start hasn't been called in the same shell or
+# the call had failed.
+#
+#       !!!!! WARNING: CONCURRENT CALLS WITH THE SAME NAME ARE NOT ALLOWED !!!!!
+#
+# It's illegal to call gitstatus_query if the last asynchronous call with the same NAME hasn't
+# completed yet. If you need to issue concurrent requests, use different NAME arguments.
+function gitstatus_query"${1:-}"() {
+  emulate -L zsh -o no_aliases -o extended_glob -o typeset_silent
+
+  local fsuf=${${(%):-%N}#gitstatus_query}
+
+  unset VCS_STATUS_RESULT
+
+  local opt dir callback OPTARG
+  local -i no_diff OPTIND
+  local -F timeout=-1
+  while getopts ":d:c:t:p" opt; do
+    case $opt in
+      +p) no_diff=0;;
+      p)  no_diff=1;;
+      d)  dir=$OPTARG;;
+      c)  callback=$OPTARG;;
+      t)
+        if [[ $OPTARG != (|+|-)<->(|.<->)(|[eE](|-|+)<->) ]]; then
+          print -ru2 -- "gitstatus_query: invalid -t argument: $OPTARG"
+          return 1
+        fi
+        timeout=OPTARG
+      ;;
+      \?) print -ru2 -- "gitstatus_query: invalid option: $OPTARG"           ; return 1;;
+      :)  print -ru2 -- "gitstatus_query: missing required argument: $OPTARG"; return 1;;
+      *)  print -ru2 -- "gitstatus_query: invalid option: $opt"              ; return 1;;
+    esac
+  done
+
+  if (( OPTIND != ARGC )); then
+    print -ru2 -- "gitstatus_query: exactly one positional argument is required"
+    return 1
+  fi
+
+  local name=$*[OPTIND]
+  if [[ $name != [[:IDENT:]]## ]]; then
+    print -ru2 -- "gitstatus_query: invalid positional argument: $name"
+    return 1
+  fi
+
+  (( _GITSTATUS_STATE_$name == 2 )) || return
+
+  if [[ -z $GIT_DIR ]]; then
+    if [[ $dir != /* ]]; then
+      if [[ $PWD == /* && $PWD -ef . ]]; then
+        dir=$PWD/$dir
+      else
+        dir=${dir:a}
+      fi
+    fi
+  else
+    if [[ $GIT_DIR == /* ]]; then
+      dir=:$GIT_DIR
+    elif [[ $PWD == /* && $PWD -ef . ]]; then
+      dir=:$PWD/$GIT_DIR
+    else
+      dir=:${GIT_DIR:a}
+    fi
+  fi
+
+  if [[ $dir != (|:)/* ]]; then
+    typeset -g VCS_STATUS_RESULT=norepo-sync
+    _gitstatus_clear$fsuf
+    return 0
+  fi
+
+  local -i req_fd=${(P)${:-_GITSTATUS_REQ_FD_$name}}
+  local req_id=$EPOCHREALTIME
+  print -rnu $req_fd -- $req_id' '$callback$'\x1f'$dir$'\x1f'$no_diff$'\x1e' || return
+
+  (( ++_GITSTATUS_NUM_INFLIGHT_$name ))
+
+  if (( timeout == 0 )); then
+    typeset -g VCS_STATUS_RESULT=tout
+    _gitstatus_clear$fsuf
+  else
+    while true; do
+      _gitstatus_process_response$fsuf $name $timeout $req_id || return
+      [[ $VCS_STATUS_RESULT == *-async ]] || break
+    done
+  fi
+
+  [[ $VCS_STATUS_RESULT != tout || -n $callback ]]
+}
+
+# If the last call to gitstatus_query timed out (VCS_STATUS_RESULT=tout), wait for the callback
+# to be called. Otherwise do nothing.
+#
+# Usage: gitstatus_process_results [OPTION]... NAME
+#
+#   -t FLOAT  Timeout in seconds. Negative value means infinity. Will block for at most this long.
+#
+# Returns an error only when invoked with incorrect arguments and when gitstatusd isn't running or
+# broken.
+#
+# If a callback gets called, VCS_STATUS_* parameters are set as in gitstatus_query.
+# VCS_STATUS_RESULT is either norepo-async or ok-async.
+function gitstatus_process_results"${1:-}"() {
+  emulate -L zsh -o no_aliases -o extended_glob -o typeset_silent
+
+  local fsuf=${${(%):-%N}#gitstatus_process_results}
+
+  local opt OPTARG
+  local -i OPTIND
+  local -F timeout=-1
+  while getopts ":t:" opt; do
+    case $opt in
+      t)
+        if [[ $OPTARG != (|+|-)<->(|.<->)(|[eE](|-|+)<->) ]]; then
+          print -ru2 -- "gitstatus_process_results: invalid -t argument: $OPTARG"
+          return 1
+        fi
+        timeout=OPTARG
+      ;;
+      \?) print -ru2 -- "gitstatus_process_results: invalid option: $OPTARG"           ; return 1;;
+      :)  print -ru2 -- "gitstatus_process_results: missing required argument: $OPTARG"; return 1;;
+      *)  print -ru2 -- "gitstatus_process_results: invalid option: $opt"              ; return 1;;
+    esac
+  done
+
+  if (( OPTIND != ARGC )); then
+    print -ru2 -- "gitstatus_process_results: exactly one positional argument is required"
+    return 1
+  fi
+
+  local name=$*[OPTIND]
+  if [[ $name != [[:IDENT:]]## ]]; then
+    print -ru2 -- "gitstatus_process_results: invalid positional argument: $name"
+    return 1
+  fi
+
+  (( _GITSTATUS_STATE_$name == 2 )) || return
+
+  while (( _GITSTATUS_NUM_INFLIGHT_$name )); do
+    _gitstatus_process_response$fsuf $name $timeout '' || return
+    [[ $VCS_STATUS_RESULT == *-async ]] || break
+  done
+
+  return 0
+}
+
+function _gitstatus_clear"${1:-}"() {
+  unset VCS_STATUS_{WORKDIR,COMMIT,LOCAL_BRANCH,REMOTE_BRANCH,REMOTE_NAME,REMOTE_URL,ACTION,INDEX_SIZE,NUM_STAGED,NUM_UNSTAGED,NUM_CONFLICTED,NUM_UNTRACKED,HAS_STAGED,HAS_UNSTAGED,HAS_CONFLICTED,HAS_UNTRACKED,COMMITS_AHEAD,COMMITS_BEHIND,STASHES,TAG,NUM_UNSTAGED_DELETED,NUM_STAGED_NEW,NUM_STAGED_DELETED,PUSH_REMOTE_NAME,PUSH_REMOTE_URL,PUSH_COMMITS_AHEAD,PUSH_COMMITS_BEHIND,NUM_SKIP_WORKTREE,NUM_ASSUME_UNCHANGED}
+}
+
+function _gitstatus_process_response"${1:-}"() {
+  local name=$1 timeout req_id=$3 buf
+  local -i resp_fd=_GITSTATUS_RESP_FD_$name
+  local -i dirty_max_index_size=_GITSTATUS_DIRTY_MAX_INDEX_SIZE_$name
+
+  (( $2 >= 0 )) && timeout=-t$2 && [[ -t $resp_fd ]]
+  sysread $timeout -i $resp_fd 'buf[$#buf+1]' || {
+    if (( $? == 4 )); then
+      if [[ -n $req_id ]]; then
+        typeset -g VCS_STATUS_RESULT=tout
+        _gitstatus_clear$fsuf
+      fi
+      return 0
+    else
+      gitstatus_stop$fsuf $name
+      return 1
+    fi
+  }
+  while [[ $buf != *$'\x1e' ]]; do
+    if ! sysread -i $resp_fd 'buf[$#buf+1]'; then
+      gitstatus_stop$fsuf $name
+      return 1
+    fi
+  done
+
+  local s
+  for s in ${(ps:\x1e:)buf}; do
+    local -a resp=("${(@ps:\x1f:)s}")
+    if (( resp[2] )); then
+      if [[ $resp[1] == $req_id' '* ]]; then
+        typeset -g VCS_STATUS_RESULT=ok-sync
+      else
+        typeset -g VCS_STATUS_RESULT=ok-async
+      fi
+      for VCS_STATUS_WORKDIR              \
+          VCS_STATUS_COMMIT               \
+          VCS_STATUS_LOCAL_BRANCH         \
+          VCS_STATUS_REMOTE_BRANCH        \
+          VCS_STATUS_REMOTE_NAME          \
+          VCS_STATUS_REMOTE_URL           \
+          VCS_STATUS_ACTION               \
+          VCS_STATUS_INDEX_SIZE           \
+          VCS_STATUS_NUM_STAGED           \
+          VCS_STATUS_NUM_UNSTAGED         \
+          VCS_STATUS_NUM_CONFLICTED       \
+          VCS_STATUS_NUM_UNTRACKED        \
+          VCS_STATUS_COMMITS_AHEAD        \
+          VCS_STATUS_COMMITS_BEHIND       \
+          VCS_STATUS_STASHES              \
+          VCS_STATUS_TAG                  \
+          VCS_STATUS_NUM_UNSTAGED_DELETED \
+          VCS_STATUS_NUM_STAGED_NEW       \
+          VCS_STATUS_NUM_STAGED_DELETED   \
+          VCS_STATUS_PUSH_REMOTE_NAME     \
+          VCS_STATUS_PUSH_REMOTE_URL      \
+          VCS_STATUS_PUSH_COMMITS_AHEAD   \
+          VCS_STATUS_PUSH_COMMITS_BEHIND  \
+          VCS_STATUS_NUM_SKIP_WORKTREE    \
+          VCS_STATUS_NUM_ASSUME_UNCHANGED \
+          VCS_STATUS_COMMIT_ENCODING      \
+          VCS_STATUS_COMMIT_SUMMARY in "${(@)resp[3,29]}"; do
+      done
+      typeset -gi VCS_STATUS_{INDEX_SIZE,NUM_STAGED,NUM_UNSTAGED,NUM_CONFLICTED,NUM_UNTRACKED,COMMITS_AHEAD,COMMITS_BEHIND,STASHES,NUM_UNSTAGED_DELETED,NUM_STAGED_NEW,NUM_STAGED_DELETED,PUSH_COMMITS_AHEAD,PUSH_COMMITS_BEHIND,NUM_SKIP_WORKTREE,NUM_ASSUME_UNCHANGED}
+      typeset -gi VCS_STATUS_HAS_STAGED=$((VCS_STATUS_NUM_STAGED > 0))
+      if (( dirty_max_index_size >= 0 && VCS_STATUS_INDEX_SIZE > dirty_max_index_size )); then
+        typeset -gi                    \
+          VCS_STATUS_HAS_UNSTAGED=-1   \
+          VCS_STATUS_HAS_CONFLICTED=-1 \
+          VCS_STATUS_HAS_UNTRACKED=-1
+      else
+        typeset -gi                                                    \
+          VCS_STATUS_HAS_UNSTAGED=$((VCS_STATUS_NUM_UNSTAGED > 0))     \
+          VCS_STATUS_HAS_CONFLICTED=$((VCS_STATUS_NUM_CONFLICTED > 0)) \
+          VCS_STATUS_HAS_UNTRACKED=$((VCS_STATUS_NUM_UNTRACKED > 0))
+      fi
+    else
+      if [[ $resp[1] == $req_id' '* ]]; then
+        typeset -g VCS_STATUS_RESULT=norepo-sync
+      else
+        typeset -g VCS_STATUS_RESULT=norepo-async
+      fi
+      _gitstatus_clear$fsuf
+    fi
+    (( --_GITSTATUS_NUM_INFLIGHT_$name ))
+    [[ $VCS_STATUS_RESULT == *-async ]] && emulate zsh -c "${resp[1]#* }"
+  done
+
+  return 0
+}
+
+function _gitstatus_daemon"${1:-}"() {
+  local -i pipe_fd
+  exec 0<&- {pipe_fd}>&1 1>>$daemon_log 2>&1 || return
+  local pgid=$sysparams[pid]
+  [[ $pgid == <1-> ]] || return
+  builtin cd -q /     || return
+
+  {
+    {
+      trap '' PIPE
+
+      local uname_sm
+      uname_sm="${${(L)$(command uname -sm)}//ı/i}" || return
+      [[ $uname_sm == [^' ']##' '[^' ']## ]]        || return
+      local uname_s=${uname_sm% *}
+      local uname_m=${uname_sm#* }
+
+      if [[ $GITSTATUS_NUM_THREADS == <1-> ]]; then
+        args+=(-t $GITSTATUS_NUM_THREADS)
+      else
+        local cpus
+        if (( ! $+commands[sysctl] )) || [[ $uname_s == linux ]] ||
+            ! cpus="$(command sysctl -n hw.ncpu)"; then
+          if (( ! $+commands[getconf] )) || ! cpus="$(command getconf _NPROCESSORS_ONLN)"; then
+            cpus=8
+          fi
+        fi
+        args+=(-t $((cpus > 16 ? 32 : cpus > 0 ? 2 * cpus : 16)))
+      fi
+
+      command mkfifo -- $file_prefix.fifo   || return
+      print -rnu $pipe_fd -- ${(l:20:)pgid} || return
+      exec <$file_prefix.fifo               || return
+      zf_rm -- $file_prefix.fifo            || return
+
+      local _gitstatus_zsh_daemon _gitstatus_zsh_version _gitstatus_zsh_downloaded
+
+      function _gitstatus_set_daemon$fsuf() {
+        _gitstatus_zsh_daemon="$1"
+        _gitstatus_zsh_version="$2"
+        _gitstatus_zsh_downloaded="$3"
+      }
+
+      local gitstatus_plugin_dir_var=_gitstatus_plugin_dir$fsuf
+      local gitstatus_plugin_dir=${(P)gitstatus_plugin_dir_var}
+      builtin set -- -d $gitstatus_plugin_dir -s $uname_s -m $uname_m \
+        -p "printf '\\001' >&$pipe_fd" -e $pipe_fd -- _gitstatus_set_daemon$fsuf
+      [[ ${GITSTATUS_AUTO_INSTALL:-1} == (|-|+)<1-> ]] || builtin set -- -n "$@"
+      builtin source $gitstatus_plugin_dir/install     || return
+      [[ -n $_gitstatus_zsh_daemon ]]                  || return
+      [[ -n $_gitstatus_zsh_version ]]                 || return
+      [[ $_gitstatus_zsh_downloaded == [01] ]]         || return
+
+      if (( UID == EUID )); then
+        local home=~
+      else
+        local user
+        user="$(command id -un)" || return
+        local home=${userdirs[$user]}
+        [[ -n $home ]] || return
+      fi
+
+      if [[ -x $_gitstatus_zsh_daemon ]]; then
+        HOME=$home $_gitstatus_zsh_daemon -G $_gitstatus_zsh_version "${(@)args}" >&$pipe_fd
+        local -i ret=$?
+        [[ $ret == (0|129|130|131|137|141|143|159) ]] && return ret
+      fi
+
+      (( ! _gitstatus_zsh_downloaded ))                || return
+      [[ ${GITSTATUS_AUTO_INSTALL:-1} == (|-|+)<1-> ]] || return
+      [[ $_gitstatus_zsh_daemon == \
+         ${GITSTATUS_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/gitstatus}/* ]] || return
+
+      builtin set -- -f "$@"
+      _gitstatus_zsh_daemon=
+      _gitstatus_zsh_version=
+      _gitstatus_zsh_downloaded=
+      builtin source $gitstatus_plugin_dir/install || return
+      [[ -n $_gitstatus_zsh_daemon ]]              || return
+      [[ -n $_gitstatus_zsh_version ]]             || return
+      [[ $_gitstatus_zsh_downloaded == 1 ]]        || return
+
+      HOME=$home $_gitstatus_zsh_daemon -G $_gitstatus_zsh_version "${(@)args}" >&$pipe_fd
+    } always {
+      local -i ret=$?
+      zf_rm -f -- $file_prefix.lock $file_prefix.fifo
+      kill -- -$pgid
+    }
+  } &!
+
+  (( lock_fd == -1 )) && return
+
+  {
+    if zsystem flock -- $file_prefix.lock && command sleep 5 && [[ -e $file_prefix.lock ]]; then
+      zf_rm -f -- $file_prefix.lock $file_prefix.fifo
+      kill -- -$pgid
+    fi
+  } &!
+}
+
+# Starts gitstatusd in the background. Does nothing and succeeds if gitstatusd is already running.
+#
+# Usage: gitstatus_start [OPTION]... NAME
+#
+#   -t FLOAT  Fail the self-check on initialization if not getting a response from gitstatusd for
+#             this this many seconds. Defaults to 5.
+#
+#   -s INT    Report at most this many staged changes; negative value means infinity.
+#             Defaults to 1.
+#
+#   -u INT    Report at most this many unstaged changes; negative value means infinity.
+#             Defaults to 1.
+#
+#   -c INT    Report at most this many conflicted changes; negative value means infinity.
+#             Defaults to 1.
+#
+#   -d INT    Report at most this many untracked files; negative value means infinity.
+#             Defaults to 1.
+#
+#   -m INT    Report -1 unstaged, untracked and conflicted if there are more than this many
+#             files in the index. Negative value means infinity. Defaults to -1.
+#
+#   -e        Count files within untracked directories like `git status --untracked-files`.
+#
+#   -U        Unless this option is specified, report zero untracked files for repositories
+#             with status.showUntrackedFiles = false.
+#
+#   -W        Unless this option is specified, report zero untracked files for repositories
+#             with bash.showUntrackedFiles = false.
+#
+#   -D        Unless this option is specified, report zero staged, unstaged and conflicted
+#             changes for repositories with bash.showDirtyState = false.
+function gitstatus_start"${1:-}"() {
+  emulate -L zsh -o no_aliases -o no_bg_nice -o extended_glob -o typeset_silent || return
+  print -rnu2 || return
+
+  local fsuf=${${(%):-%N}#gitstatus_start}
+
+  local opt OPTARG
+  local -i OPTIND
+  local -F timeout=5
+  local -i async=0
+  local -a args=()
+  local -i dirty_max_index_size=-1
+
+  while getopts ":t:s:u:c:d:m:eaUWD" opt; do
+    case $opt in
+      a)  async=1;;
+      +a) async=0;;
+      t)
+        if [[ $OPTARG != (|+)<->(|.<->)(|[eE](|-|+)<->) ]] || (( ${timeout::=OPTARG} <= 0 )); then
+          print -ru2 -- "gitstatus_start: invalid -t argument: $OPTARG"
+          return 1
+        fi
+      ;;
+      s|u|c|d|m)
+        if [[ $OPTARG != (|-|+)<-> ]]; then
+          print -ru2 -- "gitstatus_start: invalid -$opt argument: $OPTARG"
+          return 1
+        fi
+        args+=(-$opt $OPTARG)
+        [[ $opt == m ]] && dirty_max_index_size=OPTARG
+      ;;
+      e|U|W|D)    args+=-$opt;;
+      +(e|U|W|D)) args=(${(@)args:#-$opt});;
+      \?) print -ru2 -- "gitstatus_start: invalid option: $OPTARG"           ; return 1;;
+      :)  print -ru2 -- "gitstatus_start: missing required argument: $OPTARG"; return 1;;
+      *)  print -ru2 -- "gitstatus_start: invalid option: $opt"              ; return 1;;
+    esac
+  done
+
+  if (( OPTIND != ARGC )); then
+    print -ru2 -- "gitstatus_start: exactly one positional argument is required"
+    return 1
+  fi
+
+  local name=$*[OPTIND]
+  if [[ $name != [[:IDENT:]]## ]]; then
+    print -ru2 -- "gitstatus_start: invalid positional argument: $name"
+    return 1
+  fi
+
+  local -i lock_fd resp_fd stderr_fd
+  local file_prefix xtrace=/dev/null daemon_log=/dev/null culprit
+
+  {
+    if (( _GITSTATUS_STATE_$name )); then
+      (( async )) && return
+      (( _GITSTATUS_STATE_$name == 2 )) && return
+      lock_fd=_GITSTATUS_LOCK_FD_$name
+      resp_fd=_GITSTATUS_RESP_FD_$name
+      xtrace=${(P)${:-GITSTATUS_XTRACE_$name}}
+      daemon_log=${(P)${:-GITSTATUS_DAEMON_LOG_$name}}
+      file_prefix=${(P)${:-_GITSTATUS_FILE_PREFIX_$name}}
+    else
+      typeset -gi _GITSTATUS_START_COUNTER
+      local log_level=$GITSTATUS_LOG_LEVEL
+      if [[ -n "$TMPDIR" && ( ( -d "$TMPDIR" && -w "$TMPDIR" ) || ! ( -d /tmp && -w /tmp ) ) ]]; then
+        local tmpdir=$TMPDIR
+      else
+        local tmpdir=/tmp
+      fi
+      local file_prefix=${tmpdir:A}/gitstatus.$name.$EUID
+      file_prefix+=.$sysparams[pid].$EPOCHSECONDS.$((++_GITSTATUS_START_COUNTER))
+      (( GITSTATUS_ENABLE_LOGGING )) && : ${log_level:=INFO}
+      if [[ -n $log_level ]]; then
+        xtrace=$file_prefix.xtrace.log
+        daemon_log=$file_prefix.daemon.log
+      fi
+      args+=(-v ${log_level:-FATAL})
+      typeset -g GITSTATUS_XTRACE_$name=$xtrace
+      typeset -g GITSTATUS_DAEMON_LOG_$name=$daemon_log
+      typeset -g _GITSTATUS_FILE_PREFIX_$name=$file_prefix
+      typeset -gi _GITSTATUS_CLIENT_PID_$name="sysparams[pid]"
+      typeset -gi _GITSTATUS_DIRTY_MAX_INDEX_SIZE_$name=dirty_max_index_size
+    fi
+
+    () {
+      if [[ $xtrace != /dev/null && -o no_xtrace ]]; then
+        exec {stderr_fd}>&2 || return
+        exec 2>>$xtrace     || return
+        setopt xtrace
+      fi
+
+      setopt monitor || return
+
+      if (( ! _GITSTATUS_STATE_$name )); then
+        if [[ -r /proc/version && "$(</proc/version)" == *Microsoft* ]]; then
+          lock_fd=-1
+        else
+          print -rn >$file_prefix.lock               || return
+          zsystem flock -f lock_fd $file_prefix.lock || return
+          [[ $lock_fd == <1-> ]]                     || return
+        fi
+
+        typeset -gi _GITSTATUS_LOCK_FD_$name=lock_fd
+
+        if [[ $OSTYPE == cygwin* && -d /proc/self/fd ]]; then
+          # Work around bugs in Cygwin 32-bit.
+          #
+          # This hangs:
+          #
+          #   emulate -L zsh
+          #   () { exec {fd}< $1 } <(:)
+          #   =true  # hangs here
+          #
+          # This hangs:
+          #
+          #   sysopen -r -u fd <(:)
+          local -i fd
+          exec {fd}< <(_gitstatus_daemon$fsuf)                       || return
+          {
+            [[ -r /proc/self/fd/$fd ]]                               || return
+            sysopen -r -o cloexec -u resp_fd /proc/self/fd/$fd       || return
+          } always {
+            exec {fd} >&-                                            || return
+          }
+        else
+          sysopen -r -o cloexec -u resp_fd <(_gitstatus_daemon$fsuf) || return
+        fi
+
+        typeset -gi GITSTATUS_DAEMON_PID_$name="${sysparams[procsubstpid]:--1}"
+
+        [[ $resp_fd == <1-> ]] || return
+        typeset -gi _GITSTATUS_RESP_FD_$name=resp_fd
+        typeset -gi _GITSTATUS_STATE_$name=1
+      fi
+
+      if (( ! async )); then
+        (( _GITSTATUS_CLIENT_PID_$name == sysparams[pid] )) || return
+
+        local pgid
+        while (( $#pgid < 20 )); do
+          [[ -t $resp_fd ]]
+          sysread -s $((20 - $#pgid)) -t $timeout -i $resp_fd 'pgid[$#pgid+1]' || return
+        done
+        [[ $pgid == ' '#<1-> ]] || return
+        typeset -gi GITSTATUS_DAEMON_PID_$name=pgid
+
+        sysopen -w -o cloexec -u req_fd -- $file_prefix.fifo || return
+        [[ $req_fd == <1-> ]]                                || return
+        typeset -gi _GITSTATUS_REQ_FD_$name=req_fd
+
+        print -nru $req_fd -- $'}hello\x1f\x1e' || return
+        local expected=$'}hello\x1f0\x1e' actual
+        if (( $+functions[p10k] )) && [[ ! -t 1 && ! -t 0 ]]; then
+          local -F deadline='EPOCHREALTIME + 4'
+        else
+          local -F deadline='1'
+        fi
+        while true; do
+          [[ -t $resp_fd ]]
+          sysread -s 1 -t $timeout -i $resp_fd actual || return
+          [[ $expected == $actual* ]] && break
+          if [[ $actual != $'\1' ]]; then
+            [[ -t $resp_fd ]]
+            while sysread -t $timeout -i $resp_fd 'actual[$#actual+1]'; do
+              [[ -t $resp_fd ]]
+            done
+            culprit=$actual
+            return 1
+          fi
+          (( EPOCHREALTIME < deadline )) && continue
+          if (( deadline > 0 )); then
+            deadline=0
+            if (( stderr_fd )); then
+              unsetopt xtrace
+              exec 2>&$stderr_fd {stderr_fd}>&-
+              stderr_fd=0
+            fi
+            if (( $+functions[p10k] )); then
+              p10k clear-instant-prompt || return
+            fi
+            if [[ $name == POWERLEVEL9K ]]; then
+              local label=powerlevel10k
+            else
+              local label=gitstatus
+            fi
+            if [[ -t 2 ]]; then
+              local spinner=($'\b%3F-%f' $'\b%3F\\%f' $'\b%3F|%f' $'\b%3F/%f')
+              print -Prnu2 -- "[%3F$label%f] fetching %2Fgitstatusd%f ..  "
+            else
+              local spinner=('.')
+              print -rnu2 -- "[$label] fetching gitstatusd .."
+            fi
+          fi
+          print -Prnu2 -- $spinner[1]
+          spinner=($spinner[2,-1] $spinner[1])
+        done
+
+        if (( deadline == 0 )); then
+          if [[ -t 2 ]]; then
+            print -Pru2 -- $'\b[%2Fok%f]'
+          else
+            print -ru2 -- ' [ok]'
+          fi
+          if [[ $xtrace != /dev/null && -o no_xtrace ]]; then
+            exec {stderr_fd}>&2 || return
+            exec 2>>$xtrace     || return
+            setopt xtrace
+          fi
+        fi
+
+        while (( $#actual < $#expected )); do
+          [[ -t $resp_fd ]]
+          sysread -s $(($#expected - $#actual)) -t $timeout -i $resp_fd 'actual[$#actual+1]' || return
+        done
+        [[ $actual == $expected ]] || return
+
+        function _gitstatus_process_response_$name-$fsuf() {
+          emulate -L zsh -o no_aliases -o extended_glob -o typeset_silent
+          local pair=${${(%):-%N}#_gitstatus_process_response_}
+          local name=${pair%%-*}
+          local fsuf=${pair#*-}
+          [[ $name == POWERLEVEL9K && $fsuf == _p9k_ ]] && eval $__p9k_intro_base
+          if (( ARGC == 1 )); then
+            _gitstatus_process_response$fsuf $name 0 ''
+          else
+            gitstatus_stop$fsuf $name
+          fi
+        }
+        if ! zle -F $resp_fd _gitstatus_process_response_$name-$fsuf; then
+          unfunction _gitstatus_process_response_$name-$fsuf
+          return 1
+        fi
+
+        function _gitstatus_cleanup_$name-$fsuf() {
+          emulate -L zsh -o no_aliases -o extended_glob -o typeset_silent
+          local pair=${${(%):-%N}#_gitstatus_cleanup_}
+          local name=${pair%%-*}
+          local fsuf=${pair#*-}
+          (( _GITSTATUS_CLIENT_PID_$name == sysparams[pid] )) || return
+          gitstatus_stop$fsuf $name
+        }
+        if ! add-zsh-hook zshexit _gitstatus_cleanup_$name-$fsuf; then
+          unfunction _gitstatus_cleanup_$name-$fsuf
+          return 1
+        fi
+
+        if (( lock_fd != -1 )); then
+          zf_rm -- $file_prefix.lock || return
+          zsystem flock -u $lock_fd  || return
+        fi
+        unset _GITSTATUS_LOCK_FD_$name
+
+        typeset -gi _GITSTATUS_STATE_$name=2
+      fi
+    }
+  } always {
+    local -i err=$?
+    (( stderr_fd )) && exec 2>&$stderr_fd {stderr_fd}>&-
+    (( err == 0  )) && return
+
+    gitstatus_stop$fsuf $name
+
+    setopt prompt_percent no_prompt_subst no_prompt_bang
+    (( $+functions[p10k] )) && p10k clear-instant-prompt
+    print -ru2  -- ''
+    print -Pru2 -- '[%F{red}ERROR%f]: gitstatus failed to initialize.'
+    print -ru2  -- ''
+    if [[ -n $culprit ]]; then
+      print -ru2 -- $culprit
+      return err
+    fi
+    if [[ -s $xtrace ]]; then
+      print -ru2  -- ''
+      print -Pru2 -- "  Zsh log (%U${xtrace//\%/%%}%u):"
+      print -Pru2 -- '%F{yellow}'
+      print -lru2 -- "${(@)${(@f)$(<$xtrace)}/#/    }"
+      print -Pnru2 -- '%f'
+    fi
+    if [[ -s $daemon_log ]]; then
+      print -ru2   -- ''
+      print -Pru2  -- "  Daemon log (%U${daemon_log//\%/%%}%u):"
+      print -Pru2  -- '%F{yellow}'
+      print -lru2  -- "${(@)${(@f)$(<$daemon_log)}/#/    }"
+      print -Pnru2 -- '%f'
+    fi
+    if [[ $GITSTATUS_LOG_LEVEL == DEBUG ]]; then
+      print -ru2   -- ''
+      print -ru2   -- '  System information:'
+      print -Pru2  -- '%F{yellow}'
+      print -ru2   -- "    zsh:      $ZSH_VERSION"
+      print -ru2   -- "    uname -a: $(command uname -a)"
+      print -Pru2  -- '%f'
+      print -ru2   -- '  If you need help, open an issue and attach this whole error message to it:'
+      print -ru2   -- ''
+      print -Pru2  -- '    %Uhttps://github.com/romkatv/gitstatus/issues/new%u'
+    else
+      print -ru2   -- ''
+      local home=~
+      local zshrc=${${${(q)${ZDOTDIR:-~}}/#${(q)home}/'~'}//\%/%%}/.zshrc
+      print -Pru2   -- "  Add the following parameter to %U$zshrc%u for extra diagnostics on error:"
+      print -ru2   -- ''
+      print -Pru2  -- '    %BGITSTATUS_LOG_LEVEL=DEBUG%b'
+      print -ru2   -- ''
+      print -ru2   -- '  Restart Zsh to retry gitstatus initialization:'
+      print -ru2   -- ''
+      print -Pru2   -- '    %F{green}%Uexec%u zsh%f'
+    fi
+  }
+}
+
+# Stops gitstatusd if it's running.
+#
+# Usage: gitstatus_stop NAME.
+function gitstatus_stop"${1:-}"() {
+  emulate -L zsh -o no_aliases -o extended_glob -o typeset_silent
+
+  local fsuf=${${(%):-%N}#gitstatus_stop}
+
+  if (( ARGC != 1 )); then
+    print -ru2 -- "gitstatus_stop: exactly one positional argument is required"
+    return 1
+  fi
+
+  local name=$1
+  if [[ $name != [[:IDENT:]]## ]]; then
+    print -ru2 -- "gitstatus_stop: invalid positional argument: $name"
+    return 1
+  fi
+
+  local state_var=_GITSTATUS_STATE_$name
+  local req_fd_var=_GITSTATUS_REQ_FD_$name
+  local resp_fd_var=_GITSTATUS_RESP_FD_$name
+  local lock_fd_var=_GITSTATUS_LOCK_FD_$name
+  local client_pid_var=_GITSTATUS_CLIENT_PID_$name
+  local daemon_pid_var=GITSTATUS_DAEMON_PID_$name
+  local inflight_var=_GITSTATUS_NUM_INFLIGHT_$name
+  local file_prefix_var=_GITSTATUS_FILE_PREFIX_$name
+  local dirty_max_index_size_var=_GITSTATUS_DIRTY_MAX_INDEX_SIZE_$name
+
+  local req_fd=${(P)req_fd_var}
+  local resp_fd=${(P)resp_fd_var}
+  local lock_fd=${(P)lock_fd_var}
+  local daemon_pid=${(P)daemon_pid_var}
+  local file_prefix=${(P)file_prefix_var}
+
+  local cleanup=_gitstatus_cleanup_$name-$fsuf
+  local process=_gitstatus_process_response_$name-$fsuf
+
+  if (( $+functions[$cleanup] )); then
+    add-zsh-hook -d zshexit $cleanup
+    unfunction -- $cleanup
+  fi
+
+  if (( $+functions[$process] )); then
+    [[ -n $resp_fd ]] && zle -F $resp_fd
+    unfunction -- $process
+  fi
+
+  [[ $daemon_pid  == <1-> ]] && kill -- -$daemon_pid 2>/dev/null
+  [[ $file_prefix == /*   ]] && zf_rm -f -- $file_prefix.lock $file_prefix.fifo
+  [[ $lock_fd     == <1-> ]] && zsystem flock -u $lock_fd
+  [[ $req_fd      == <1-> ]] && exec {req_fd}>&-
+  [[ $resp_fd     == <1-> ]] && exec {resp_fd}>&-
+
+  unset $state_var $req_fd_var $lock_fd_var $resp_fd_var $client_pid_var $daemon_pid_var
+  unset $inflight_var $file_prefix_var $dirty_max_index_size_var
+
+  unset VCS_STATUS_RESULT
+  _gitstatus_clear$fsuf
+}
+
+# Usage: gitstatus_check NAME.
+#
+# Returns 0 if and only if `gitstatus_start NAME` has succeeded previously.
+# If it returns non-zero, gitstatus_query NAME is guaranteed to return non-zero.
+function gitstatus_check"${1:-}"() {
+  emulate -L zsh -o no_aliases -o extended_glob -o typeset_silent
+
+  local fsuf=${${(%):-%N}#gitstatus_check}
+
+  if (( ARGC != 1 )); then
+    print -ru2 -- "gitstatus_check: exactly one positional argument is required"
+    return 1
+  fi
+
+  local name=$1
+  if [[ $name != [[:IDENT:]]## ]]; then
+    print -ru2 -- "gitstatus_check: invalid positional argument: $name"
+    return 1
+  fi
+
+  (( _GITSTATUS_STATE_$name == 2 ))
+}
+
+(( ${#_gitstatus_opts} )) && setopt ${_gitstatus_opts[@]}
+'builtin' 'unset' '_gitstatus_opts'
@@ -0,0 +1,111 @@
+# Simple Bash prompt with Git status.
+
+# Source gitstatus.plugin.sh from $GITSTATUS_DIR or from the same directory
+# in which the current script resides if the variable isn't set.
+if [[ -n "${GITSTATUS_DIR-}" ]]; then
+  source "$GITSTATUS_DIR"                           || return
+elif [[ "${BASH_SOURCE[0]}" == */* ]]; then
+  source "${BASH_SOURCE[0]%/*}/gitstatus.plugin.sh" || return
+else
+  source gitstatus.plugin.sh                        || return
+fi
+
+# Sets GITSTATUS_PROMPT to reflect the state of the current git repository.
+# The value is empty if not in a git repository. Forwards all arguments to
+# gitstatus_query.
+#
+# Example value of GITSTATUS_PROMPT: master ⇣42⇡42 ⇠42⇢42 *42 merge ~42 +42 !42 ?42
+#
+#   master  current branch
+#      ⇣42  local branch is 42 commits behind the remote
+#      ⇡42  local branch is 42 commits ahead of the remote
+#      ⇠42  local branch is 42 commits behind the push remote
+#      ⇢42  local branch is 42 commits ahead of the push remote
+#      *42  42 stashes
+#    merge  merge in progress
+#      ~42  42 merge conflicts
+#      +42  42 staged changes
+#      !42  42 unstaged changes
+#      ?42  42 untracked files
+function gitstatus_prompt_update() {
+  GITSTATUS_PROMPT=""
+
+  gitstatus_query "$@"                  || return 1  # error
+  [[ "$VCS_STATUS_RESULT" == ok-sync ]] || return 0  # not a git repo
+
+  local      reset=$'\001\e[0m\002'         # no color
+  local      clean=$'\001\e[38;5;076m\002'  # green foreground
+  local  untracked=$'\001\e[38;5;014m\002'  # teal foreground
+  local   modified=$'\001\e[38;5;011m\002'  # yellow foreground
+  local conflicted=$'\001\e[38;5;196m\002'  # red foreground
+
+  local p
+
+  local where  # branch name, tag or commit
+  if [[ -n "$VCS_STATUS_LOCAL_BRANCH" ]]; then
+    where="$VCS_STATUS_LOCAL_BRANCH"
+  elif [[ -n "$VCS_STATUS_TAG" ]]; then
+    p+="${reset}#"
+    where="$VCS_STATUS_TAG"
+  else
+    p+="${reset}@"
+    where="${VCS_STATUS_COMMIT:0:8}"
+  fi
+
+  (( ${#where} > 32 )) && where="${where:0:12}…${where: -12}"  # truncate long branch names and tags
+  p+="${clean}${where}"
+
+  # ⇣42 if behind the remote.
+  (( VCS_STATUS_COMMITS_BEHIND )) && p+=" ${clean}⇣${VCS_STATUS_COMMITS_BEHIND}"
+  # ⇡42 if ahead of the remote; no leading space if also behind the remote: ⇣42⇡42.
+  (( VCS_STATUS_COMMITS_AHEAD && !VCS_STATUS_COMMITS_BEHIND )) && p+=" "
+  (( VCS_STATUS_COMMITS_AHEAD  )) && p+="${clean}⇡${VCS_STATUS_COMMITS_AHEAD}"
+  # ⇠42 if behind the push remote.
+  (( VCS_STATUS_PUSH_COMMITS_BEHIND )) && p+=" ${clean}⇠${VCS_STATUS_PUSH_COMMITS_BEHIND}"
+  (( VCS_STATUS_PUSH_COMMITS_AHEAD && !VCS_STATUS_PUSH_COMMITS_BEHIND )) && p+=" "
+  # ⇢42 if ahead of the push remote; no leading space if also behind: ⇠42⇢42.
+  (( VCS_STATUS_PUSH_COMMITS_AHEAD  )) && p+="${clean}⇢${VCS_STATUS_PUSH_COMMITS_AHEAD}"
+  # *42 if have stashes.
+  (( VCS_STATUS_STASHES        )) && p+=" ${clean}*${VCS_STATUS_STASHES}"
+  # 'merge' if the repo is in an unusual state.
+  [[ -n "$VCS_STATUS_ACTION"   ]] && p+=" ${conflicted}${VCS_STATUS_ACTION}"
+  # ~42 if have merge conflicts.
+  (( VCS_STATUS_NUM_CONFLICTED )) && p+=" ${conflicted}~${VCS_STATUS_NUM_CONFLICTED}"
+  # +42 if have staged changes.
+  (( VCS_STATUS_NUM_STAGED     )) && p+=" ${modified}+${VCS_STATUS_NUM_STAGED}"
+  # !42 if have unstaged changes.
+  (( VCS_STATUS_NUM_UNSTAGED   )) && p+=" ${modified}!${VCS_STATUS_NUM_UNSTAGED}"
+  # ?42 if have untracked files. It's really a question mark, your font isn't broken.
+  (( VCS_STATUS_NUM_UNTRACKED  )) && p+=" ${untracked}?${VCS_STATUS_NUM_UNTRACKED}"
+
+  GITSTATUS_PROMPT="${p}${reset}"
+}
+
+# Start gitstatusd in the background.
+gitstatus_stop && gitstatus_start -s -1 -u -1 -c -1 -d -1
+
+# On every prompt, fetch git status and set GITSTATUS_PROMPT.
+if [[ -z "${PROMPT_COMMAND[*]}" ]]; then
+  PROMPT_COMMAND=gitstatus_prompt_update
+elif [[ ! "${PROMPT_COMMAND[*]}" =~ [[:space:]\;]?gitstatus_prompt_update[[:space:]\;]? ]]; then
+  # Note: If PROMPT_COMMAND is an array, this will modify its first element.
+  PROMPT_COMMAND=$'gitstatus_prompt_update\n'"$PROMPT_COMMAND"
+fi
+
+# Retain 3 trailing components of the current directory.
+PROMPT_DIRTRIM=3
+
+# Enable promptvars so that ${GITSTATUS_PROMPT} in PS1 is expanded.
+shopt -s promptvars
+
+# Customize prompt. Put $GITSTATUS_PROMPT in it reflect git status.
+#
+# Example:
+#
+#   user@host ~/projects/skynet master ⇡42
+#   $ █
+PS1='\[\033[01;32m\]\u@\h\[\033[00m\] '           # green user@host
+PS1+='\[\033[01;34m\]\w\[\033[00m\]'              # blue current working directory
+PS1+='${GITSTATUS_PROMPT:+ $GITSTATUS_PROMPT}'    # git status (requires promptvars option)
+PS1+='\n\[\033[01;$((31+!$?))m\]\$\[\033[00m\] '  # green/red (success/error) $/# (normal/root)
+PS1+='\[\e]0;\u@\h: \w\a\]'                       # terminal title: user@host: dir
@@ -0,0 +1,111 @@
+# Simple Zsh prompt with Git status.
+
+# Source gitstatus.plugin.zsh from $GITSTATUS_DIR or from the same directory
+# in which the current script resides if the variable isn't set.
+source "${GITSTATUS_DIR:-${${(%):-%x}:h}}/gitstatus.plugin.zsh" || return
+
+# Sets GITSTATUS_PROMPT to reflect the state of the current git repository. Empty if not
+# in a git repository. In addition, sets GITSTATUS_PROMPT_LEN to the number of columns
+# $GITSTATUS_PROMPT will occupy when printed.
+#
+# Example:
+#
+#   GITSTATUS_PROMPT='master ⇣42⇡42 ⇠42⇢42 *42 merge ~42 +42 !42 ?42'
+#   GITSTATUS_PROMPT_LEN=39
+#
+#   master  current branch
+#      ⇣42  local branch is 42 commits behind the remote
+#      ⇡42  local branch is 42 commits ahead of the remote
+#      ⇠42  local branch is 42 commits behind the push remote
+#      ⇢42  local branch is 42 commits ahead of the push remote
+#      *42  42 stashes
+#    merge  merge in progress
+#      ~42  42 merge conflicts
+#      +42  42 staged changes
+#      !42  42 unstaged changes
+#      ?42  42 untracked files
+function gitstatus_prompt_update() {
+  emulate -L zsh
+  typeset -g  GITSTATUS_PROMPT=''
+  typeset -gi GITSTATUS_PROMPT_LEN=0
+
+  # Call gitstatus_query synchronously. Note that gitstatus_query can also be called
+  # asynchronously; see documentation in gitstatus.plugin.zsh.
+  gitstatus_query 'MY'                  || return 1  # error
+  [[ $VCS_STATUS_RESULT == 'ok-sync' ]] || return 0  # not a git repo
+
+  local      clean='%76F'   # green foreground
+  local   modified='%178F'  # yellow foreground
+  local  untracked='%39F'   # blue foreground
+  local conflicted='%196F'  # red foreground
+
+  local p
+
+  local where  # branch name, tag or commit
+  if [[ -n $VCS_STATUS_LOCAL_BRANCH ]]; then
+    where=$VCS_STATUS_LOCAL_BRANCH
+  elif [[ -n $VCS_STATUS_TAG ]]; then
+    p+='%f#'
+    where=$VCS_STATUS_TAG
+  else
+    p+='%f@'
+    where=${VCS_STATUS_COMMIT[1,8]}
+  fi
+
+  (( $#where > 32 )) && where[13,-13]="…"  # truncate long branch names and tags
+  p+="${clean}${where//\%/%%}"             # escape %
+
+  # ⇣42 if behind the remote.
+  (( VCS_STATUS_COMMITS_BEHIND )) && p+=" ${clean}⇣${VCS_STATUS_COMMITS_BEHIND}"
+  # ⇡42 if ahead of the remote; no leading space if also behind the remote: ⇣42⇡42.
+  (( VCS_STATUS_COMMITS_AHEAD && !VCS_STATUS_COMMITS_BEHIND )) && p+=" "
+  (( VCS_STATUS_COMMITS_AHEAD  )) && p+="${clean}⇡${VCS_STATUS_COMMITS_AHEAD}"
+  # ⇠42 if behind the push remote.
+  (( VCS_STATUS_PUSH_COMMITS_BEHIND )) && p+=" ${clean}⇠${VCS_STATUS_PUSH_COMMITS_BEHIND}"
+  (( VCS_STATUS_PUSH_COMMITS_AHEAD && !VCS_STATUS_PUSH_COMMITS_BEHIND )) && p+=" "
+  # ⇢42 if ahead of the push remote; no leading space if also behind: ⇠42⇢42.
+  (( VCS_STATUS_PUSH_COMMITS_AHEAD  )) && p+="${clean}⇢${VCS_STATUS_PUSH_COMMITS_AHEAD}"
+  # *42 if have stashes.
+  (( VCS_STATUS_STASHES        )) && p+=" ${clean}*${VCS_STATUS_STASHES}"
+  # 'merge' if the repo is in an unusual state.
+  [[ -n $VCS_STATUS_ACTION     ]] && p+=" ${conflicted}${VCS_STATUS_ACTION}"
+  # ~42 if have merge conflicts.
+  (( VCS_STATUS_NUM_CONFLICTED )) && p+=" ${conflicted}~${VCS_STATUS_NUM_CONFLICTED}"
+  # +42 if have staged changes.
+  (( VCS_STATUS_NUM_STAGED     )) && p+=" ${modified}+${VCS_STATUS_NUM_STAGED}"
+  # !42 if have unstaged changes.
+  (( VCS_STATUS_NUM_UNSTAGED   )) && p+=" ${modified}!${VCS_STATUS_NUM_UNSTAGED}"
+  # ?42 if have untracked files. It's really a question mark, your font isn't broken.
+  (( VCS_STATUS_NUM_UNTRACKED  )) && p+=" ${untracked}?${VCS_STATUS_NUM_UNTRACKED}"
+
+  GITSTATUS_PROMPT="${p}%f"
+
+  # The length of GITSTATUS_PROMPT after removing %f and %F.
+  GITSTATUS_PROMPT_LEN="${(m)#${${GITSTATUS_PROMPT//\%\%/x}//\%(f|<->F)}}"
+}
+
+# Start gitstatusd instance with name "MY". The same name is passed to
+# gitstatus_query in gitstatus_prompt_update. The flags with -1 as values
+# enable staged, unstaged, conflicted and untracked counters.
+gitstatus_stop 'MY' && gitstatus_start -s -1 -u -1 -c -1 -d -1 'MY'
+
+# On every prompt, fetch git status and set GITSTATUS_PROMPT.
+autoload -Uz add-zsh-hook
+add-zsh-hook precmd gitstatus_prompt_update
+
+# Enable/disable the right prompt options.
+setopt no_prompt_bang prompt_percent prompt_subst
+
+# Customize prompt. Put $GITSTATUS_PROMPT in it to reflect git status.
+#
+# Example:
+#
+#   user@host ~/projects/skynet master ⇡42
+#   % █
+#
+# The current directory gets truncated from the left if the whole prompt doesn't fit on the line.
+PROMPT='%70F%n@%m%f '                                  # green user@host
+PROMPT+='%39F%$((-GITSTATUS_PROMPT_LEN-1))<…<%~%<<%f'  # blue current working directory
+PROMPT+='${GITSTATUS_PROMPT:+ $GITSTATUS_PROMPT}'      # git status
+PROMPT+=$'\n'                                          # new line
+PROMPT+='%F{%(?.76.196)}%#%f '                         # %/# (normal/root); green/red (ok/error)
@@ -0,0 +1,476 @@
+#!/bin/sh
+#
+# This script does not have a stable API.
+
+_gitstatus_install_daemon_found() {
+  local installed="$1"
+  shift
+  [ $# = 0 ] || "$@" "$daemon" "$version" "$installed"
+}
+
+_gitstatus_install_main() {
+  if [ -n "${ZSH_VERSION:-}" ]; then
+    emulate -L sh -o no_unset
+  else
+    set -u
+  fi
+
+  local argv1="$1"
+  shift
+
+  local no_check= no_install= uname_s= uname_m= gitstatus_dir= dl_status= e=
+  local opt= OPTARG= OPTIND=1
+
+  while getopts ':s:m:d:p:e:fnh' opt "$@"; do
+    case "$opt" in
+      h)
+        command cat <<\END
+Usage: install [-s KERNEL] [-m ARCH] [-d DIR] [-p CMD] [-e ERRFD] [-f|-n] [-- CMD [ARG]...]
+
+If positional arguments are specified, call this on success:
+
+  CMD [ARG]... DAEMON VERSION INSTALLED
+
+DAEMON is path to gitstatusd. VERSION is a glob pattern for the
+version this daemon should support; it's supposed to be passed as
+-G to gitstatusd. INSTALLED is 1 if gitstatusd has just been
+downloaded and 0 otherwise.
+
+Options:
+
+  -s KERNEL  use this instead of lowercase `uname -s`
+  -m ARCH    use this instead of lowercase `uname -m`
+  -d DIR     use this instead of `dirname "$0"`
+  -p CMD     eval this every second while downloading gitstatusd
+  -e ERRFD   write error messages to this file descriptor
+  -f         download gitstatusd even if there is one locally
+  -n         do not download gitstatusd (fail instead)
+END
+        return
+      ;;
+      n)
+        if [ -n "$no_install" ]; then
+          >&2 echo "[gitstatus] error: duplicate option: -$opt"
+          return 1
+        fi
+        no_install=1
+      ;;
+      f)
+        if [ -n "$no_check" ]; then
+          >&2 echo "[gitstatus] error: duplicate option: -$opt"
+          return 1
+        fi
+        no_check=1
+      ;;
+      d)
+        if [ -n "$gitstatus_dir" ]; then
+          >&2 echo "[gitstatus] error: duplicate option: -$opt"
+          return 1
+        fi
+        if [ -z "$OPTARG" ]; then
+          >&2 echo "[error] incorrect value of -$opt: $OPTARG"
+          return 1
+        fi
+        gitstatus_dir="$OPTARG"
+      ;;
+      p)
+        if [ -n "$dl_status" ]; then
+          >&2 echo "[gitstatus] error: duplicate option: -$opt"
+          return 1
+        fi
+        if [ -z "$OPTARG" ]; then
+          >&2 echo "[error] incorrect value of -$opt: $OPTARG"
+          return 1
+        fi
+        dl_status="$OPTARG"
+      ;;
+      e)
+        if [ -n "$e" ]; then
+          >&2 echo "[gitstatus] error: duplicate option: -$opt"
+          return 1
+        fi
+        if [ -z "$OPTARG" ]; then
+          >&2 echo "[error] incorrect value of -$opt: $OPTARG"
+          return 1
+        fi
+        e="$OPTARG"
+      ;;
+      m)
+        if [ -n "$uname_m" ]; then
+          >&2 echo "[gitstatus] error: duplicate option: -$opt"
+          return 1
+        fi
+        if [ -z "$OPTARG" ]; then
+          >&2 echo "[error] incorrect value of -$opt: $OPTARG"
+          return 1
+        fi
+        uname_m="$OPTARG"
+      ;;
+      s)
+        if [ -n "$uname_s" ]; then
+          >&2 echo "[gitstatus] error: duplicate option: -$opt"
+          return 1
+        fi
+        if [ -z "$OPTARG" ]; then
+          >&2 echo "[error] incorrect value of -$opt: $OPTARG"
+          return 1
+        fi
+        uname_s="$OPTARG"
+      ;;
+      \?) >&2 echo "[gitstatus] error: invalid option: -$OPTARG"           ; return 1;;
+      :)  >&2 echo "[gitstatus] error: missing required argument: -$OPTARG"; return 1;;
+      *)  >&2 echo "[gitstatus] internal error: unhandled option: -$opt"   ; return 1;;
+    esac
+  done
+
+  shift "$((OPTIND - 1))"
+
+  : "${e:=2}"
+  : "${gitstatus_dir:=$argv1}"
+
+  if [ -n "$no_check" -a -n "$no_install" ]; then
+    >&2 echo "[gitstatus] error: incompatible options: -f, -n"
+    return 1
+  fi
+
+  if [ -z "$uname_s" ]; then
+    uname_s="$(command uname -s)" || return
+    uname_s="$(printf '%s' "$uname_s" | command tr '[A-Z]' '[a-z]')" || return
+  fi
+  if [ -z "$uname_m" ]; then
+    uname_m="$(command uname -m)" || return
+    uname_m="$(printf '%s' "$uname_m" | command tr '[A-Z]' '[a-z]')" || return
+  fi
+
+  local daemon="${GITSTATUS_DAEMON:-}"
+  local cache_dir="${GITSTATUS_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/gitstatus}"
+
+  if [ -z "$no_check" ]; then
+    if [ -n "${daemon##/*}" ]; then
+      >&2 echo "[gitstatus] error: GITSTATUS_DAEMON is not absolute path: $daemon"
+      return 1
+    fi
+    if [ -z "$daemon" -a -e "$gitstatus_dir"/usrbin/gitstatusd ]; then
+      daemon="$gitstatus_dir"/usrbin/gitstatusd
+    fi
+    if [ -n "$daemon" ]; then
+      local gitstatus_version= libgit2_version=
+      if ! . "$gitstatus_dir"/build.info; then
+        >&2 echo "[gitstatus] internal error: failed to source build.info"
+        return 1
+      fi
+      if [ -z "$gitstatus_version" ]; then
+        >&2 echo "[gitstatus] internal error: empty gitstatus_version in build.info"
+        return 1
+      fi
+      local version="$gitstatus_version"
+      _gitstatus_install_daemon_found 0 "$@"
+      return
+    fi
+  fi
+
+  while IFS= read -r line; do
+    line="${line###*}"
+    [ -n "$line" ] || continue
+
+    local uname_s_glob= uname_m_glob= file= version= sha256=
+    eval "$line" || return
+
+    if [ -z "$uname_s_glob" -o \
+         -z "$uname_m_glob" -o \
+         -z "$file"         -o \
+         -z "$version"      -o \
+         -z "$sha256" ]; then
+      >&2 echo "[gitstatus] internal error: invalid install.info line: $line"
+      return 1
+    fi
+
+    case "$uname_s" in
+      $uname_s_glob) ;;
+      *) continue;;
+    esac
+    case "$uname_m" in
+      $uname_m_glob) ;;
+      *) continue;;
+    esac
+
+    # Found a match. The while loop will terminate during this iteration.
+
+    if [ -z "$no_check" ]; then
+      # Check if a suitable gitstatusd already exists.
+      local daemon="$gitstatus_dir"/usrbin/"$file"
+      if [ ! -e "$daemon" ]; then
+        daemon="$cache_dir"/"$file"
+        [ -e "$daemon" ] || daemon=
+      fi
+      if [ -n "$daemon" ]; then
+        _gitstatus_install_daemon_found 0 "$@"
+        return
+      fi
+    fi
+
+    # No suitable gitstatusd exists. Need to download.
+
+    if [ -n "$no_install" ]; then
+      >&2 echo "[gitstatus] error: no gitstatusd found and installation is disabled"
+      return 1
+    fi
+
+    local daemon="$cache_dir"/"$file"
+
+    if [ -n "${cache_dir##/*}" ]; then
+      >&2 echo "[gitstatus] error: GITSTATUS_CACHE_DIR is not absolute: $cache_dir"
+      return 1
+    fi
+    if [ ! -d "$cache_dir" ] && ! mkdir -p -- "$cache_dir" || [ ! -w "$cache_dir" ]; then
+      local dir="$cache_dir"
+      while true; do
+        if [ -e "$dir" ]; then
+          if [ ! -d "$dir" ]; then
+            >&"$e" printf 'Not a directory: \033[4;31m%s\033[0m\n' "$dir"
+            >&"$e" printf '\n'
+            >&"$e" printf 'Delete it, then restart your shell.\n'
+          elif [ ! -w "$dir" ]; then
+            >&"$e" printf 'Directory is not writable: \033[4;31m%s\033[0m\n' "$dir"
+            >&"$e" printf '\n'
+            >&"$e" printf 'Make it writable, then restart your shell.\n'
+          fi
+          break
+        fi
+        if [ "$dir" = / ] || [ "$dir" = . ]; then
+          break
+        fi
+        dir="$(dirname -- "$dir")"
+      done
+      return 1
+    fi
+
+    if [ -n "${TMPDIR-}" -a '(' '(' -d "${TMPDIR-}" -a -w "${TMPDIR-}" ')' -o '!' '(' -d /tmp -a -w /tmp ')' ')' ]; then
+      local tmp="$TMPDIR"
+    else
+      local tmp=/tmp
+    fi
+    if ! command -v mktemp >/dev/null 2>&1 ||
+       ! tmpdir="$(command mktemp -d "$tmp"/gitstatus-install.XXXXXXXXXX)"; then
+      tmpdir="$tmp/gitstatus-install.tmp.$$"
+      if ! mkdir -p -- "$tmpdir"; then
+        if [ "$tmp" = /tmp ]; then
+          local label='directory'
+        else
+          local label='directory (\033[1mTMPDIR\033[m)'
+        fi
+        if [ ! -e "$tmp" ]; then
+          >&"$e" printf 'Temporary '"$label"' does not exist: \033[4;31m%s\033[0m\n' "$tmp"
+          >&"$e" printf '\n'
+          >&"$e" printf 'Create it, then restart your shell.\n'
+        elif [ ! -d "$tmp" ]; then
+          >&"$e" printf 'Not a '"$label"': \033[4;31m%s\033[0m\n' "$tmp"
+          >&"$e" printf '\n'
+          >&"$e" printf 'Make it a directory, then restart your shell.\n'
+        elif [ ! -w "$tmp" ]; then
+          >&"$e" printf 'Temporary '"$label"' is not writable: \033[4;31m%s\033[0m\n' "$tmp"
+          >&"$e" printf '\n'
+          >&"$e" printf 'Make it writable, then restart your shell.\n'
+        fi
+        return 1
+      fi
+    fi
+
+    if ! command -v curl >/dev/null 2>&1 && ! command -v wget >/dev/null 2>&1; then
+      >&"$e" printf 'Please install \033[32mcurl\033[0m or \033[32mwget\033[0m, then restart your shell.\n'
+      return 1
+    fi
+
+    (
+      run_cmd() {
+        command -v "$1" >/dev/null 2>/dev/null || return 127
+        local trapped= pid die ret
+        trap 'trapped=1' $sig
+        # The only reason for suppressing stderr is that `curl -f` cannot be silenced:
+        # `-s` doesn't work despite what the docs say.
+        command "$@" 2>/dev/null &
+        ret="$?"
+        if [ "$ret" = 0 ]; then
+          pid="$!"
+          die="trap - $sig; kill -- $pid 2>/dev/null; wait -- $pid 2>/dev/null; exit 1"
+          trap "$die" $sig
+          [ -z "$trapped" ] || eval "$die"
+          wait -- "$pid" 2>/dev/null
+          ret="$?"
+        fi
+        trap - $sig
+        [ -z "$trapped" ] || exit
+        return "$ret"
+      }
+
+      check_sha256() {
+        local data_file="$tmpdir"/"$1".tar.gz
+        local hash_file="$tmpdir"/"$1".tar.gz.sha256
+        local hash=
+        {
+          command -v shasum >/dev/null 2>/dev/null                            &&
+            run_cmd shasum -b -a 256 -- "$data_file" >"$hash_file" </dev/null &&
+            IFS= read -r hash <"$hash_file"                                   &&
+            hash="${hash%% *}"                                                &&
+            [ ${#hash} -eq 64 ]
+        } || {
+          command -v sha256sum >/dev/null 2>/dev/null                         &&
+            run_cmd sha256sum -b -- "$data_file" >"$hash_file" </dev/null     &&
+            IFS= read -r hash <"$hash_file"                                   &&
+            hash="${hash%% *}"                                                &&
+            [ ${#hash} -eq 64 ]
+        } || {
+          # Note: sha256 can be from hashalot. It's incompatible.
+          # Thankfully, it produces shorter output.
+          command -v sha256 >/dev/null 2>/dev/null &&
+            run_cmd sha256 -- "$data_file" >"$hash_file" </dev/null &&
+            IFS= read -r hash <"$hash_file" &&
+            hash="${hash##* }" &&
+            [ ${#hash} -eq 64 ]
+        } || {
+          hash=
+        }
+        [ "$1" = 1 -a -z "$hash" -o "$hash" = "$sha256" ]
+      }
+
+      local url1="https://github.com/romkatv/gitstatus/releases/download/$version/$file.tar.gz"
+      local url2="https://gitee.com/romkatv/gitstatus/raw/release-$version/release/$file.tar.gz"
+      local sig='INT QUIT TERM ILL PIPE'
+
+      fetch() {
+        if [ "$1" != 1 ] && command -v sleep >/dev/null 2>/dev/null; then
+          if ! run_cmd sleep "$1"; then
+            echo -n >"$tmpdir"/"$1".status
+            return 1
+          fi
+        fi
+        local cmd part url ret
+        for cmd in 'curl -kfsSL' 'wget -qO-' 'curl -q -kfsSL' 'wget --no-config -qO-'; do
+          part=0
+          while true; do
+            if [ "$part" = 2 ]; then
+              ret=1
+              break
+            elif [ "$part" = 0 ]; then
+              url="$2"
+            else
+              url="$2"."$part"
+            fi
+            run_cmd $cmd -- "$url" >>"$tmpdir"/"$1".tar.gz
+            ret="$?"
+            [ "$ret" = 0 ] || break
+            check_sha256 "$1" && break
+            part=$((part+1))
+          done
+          [ "$ret" = 0 ] && break
+          run_cmd rm -f -- "$tmpdir"/"$1".tar.gz && continue
+          ret="$?"
+          break
+        done
+        echo -n >"$tmpdir"/"$1".status
+        return "$ret"
+      }
+
+      local trapped=
+      trap 'trapped=1' $sig
+      fetch 1 "$url1" &
+      local pid1="$!"
+      fetch 2 "$url2" &
+      local pid2="$!"
+
+      local die="trap - $sig; kill -- $pid1 $pid2 2>/dev/null; wait -- $pid1 $pid2 2>/dev/null; exit 1"
+      trap "$die" $sig
+      [ -z "$trapped" ] || eval "$die"
+
+      local n=
+      while true; do
+        [ -z "$dl_status" ] || eval "$dl_status" || eval "$die"
+        if command -v sleep >/dev/null 2>/dev/null; then
+          command sleep 1
+        elif command -v true >/dev/null 2>/dev/null; then
+          command true
+        fi
+        if [ -n "$pid1" -a -e "$tmpdir"/1.status ]; then
+          wait -- "$pid1" 2>/dev/null
+          local ret="$?"
+          pid1=
+          if [ "$ret" = 0 ]; then
+            if [ -n "$pid2" ]; then
+              kill -- "$pid2" 2>/dev/null
+              wait -- "$pid2" 2>/dev/null
+            fi
+            n=1
+            break
+          elif [ -z "$pid2" ]; then
+            break
+          else
+            die="trap - $sig; kill -- $pid2 2>/dev/null; wait -- $pid2 2>/dev/null; exit 1"
+            trap "$die" $sig
+          fi
+        elif [ -n "$pid2" -a -e "$tmpdir"/2.status ]; then
+          wait -- "$pid2" 2>/dev/null
+          local ret="$?"
+          pid2=
+          if [ "$ret" = 0 ]; then
+            if [ -n "$pid1" ]; then
+              kill -- "$pid1" 2>/dev/null
+              wait -- "$pid1" 2>/dev/null
+            fi
+            n=2
+            break
+          elif [ -z "$pid1" ]; then
+            break
+          else
+            die="trap - $sig; kill -- $pid1 2>/dev/null; wait -- $pid1 2>/dev/null; exit 1"
+            trap "$die" $sig
+          fi
+        fi
+      done
+
+      trap - $sig
+
+      if [ -z "$n" ]; then
+        >&"$e" printf 'Failed to download \033[32m%s\033[0m from any mirror:\n' "$file"
+        >&"$e" printf '\n'
+        >&"$e" printf '  1. \033[4m%s\033[0m\n' "$url1"
+        >&"$e" printf '  2. \033[4m%s\033[0m\n' "$url2"
+        >&"$e" printf '\n'
+        >&"$e" printf 'Check your internet connection, then restart your shell.\n'
+        exit 1
+      fi
+
+      command tar -C "$tmpdir" -xzf "$tmpdir"/"$n".tar.gz || exit
+
+      local tmpfile
+      if ! command -v mktemp >/dev/null 2>&1 ||
+         ! tmpfile="$(command mktemp "$cache_dir"/gitstatusd.XXXXXXXXXX)"; then
+        tmpfile="$cache_dir"/gitstatusd.tmp.$$
+      fi
+
+      command mv -f -- "$tmpdir"/"$file" "$tmpfile" || exit
+      command mv -f -- "$tmpfile" "$cache_dir"/"$file" && exit
+      command rm -f -- "$cache_dir"/"$file"
+      command mv -f -- "$tmpfile" "$cache_dir"/"$file" && exit
+      command rm -f -- "$tmpfile"
+      exit 1
+    )
+
+    local ret="$?"
+    command rm -rf -- "$tmpdir"
+    [ "$ret" = 0 ] || return
+
+    _gitstatus_install_daemon_found 1 "$@"
+    return
+  done <"$gitstatus_dir"/install.info
+
+  >&"$e" printf 'There is no prebuilt \033[32mgitstatusd\033[0m for \033[1m%s\033[0m.\n' "$uname_s $uname_m"
+  >&"$e" printf '\n'
+  >&"$e" printf 'See: \033[4mhttps://github.com/romkatv/gitstatus#compiling\033[0m\n'
+  return 1
+}
+
+if [ -z "${0##*/*}" ]; then
+  _gitstatus_install_main "${0%/*}" "$@"
+else
+  _gitstatus_install_main . "$@"
+fi
@@ -0,0 +1,34 @@
+# 3
+#
+# This file is used by ./install and indirectly by shell bindings.
+#
+# The first line is read by powerlevel10k instant prompt. It must
+# be updated whenever the content of this file changes. The actual
+# value doesn't matter as long as it's unique. Consecutive integers
+# work fine.
+
+# Official gitstatusd binaries.
+uname_s_glob="cygwin_nt-10.0"; uname_m_glob="i686";    file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.4"; sha256="5a8a809dcebdb6aa9b47d37e086c0485424a9d9c136770eec3c26cedf5bb75e3";
+uname_s_glob="cygwin_nt-10.0"; uname_m_glob="x86_64";  file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.1"; sha256="c84cade0d6b86e04c27a6055f45851f6b46d6b88ba58772f7ca8ef4d295c800f";
+uname_s_glob="darwin";         uname_m_glob="arm64";   file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.4"; sha256="eae979e990ca37c56ee39fadd0c3f392cbbd0c6bdfb9a603010be60d9e48910a";
+uname_s_glob="darwin";         uname_m_glob="x86_64";  file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.4"; sha256="9fd3913ec1b6b856ab6e08a99a2343f0e8e809eb6b62ca4b0963163656c668e6";
+uname_s_glob="freebsd";        uname_m_glob="amd64";   file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.4"; sha256="8e57ad642251e5acfa430aed82cd4ffe103db0bfadae4a15ccaf462c455d0442";
+uname_s_glob="linux";          uname_m_glob="aarch64"; file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.4"; sha256="32b57eb28bf6d80b280e4020a0045184f8ca897b20b570c12948aa6838673225";
+uname_s_glob="linux";          uname_m_glob="armv6l";  file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.1"; sha256="4bf5a0d0a082f544a48536ad3675930d5d2cc6a8cf906710045e0788f51192b3";
+uname_s_glob="linux";          uname_m_glob="armv7l";  file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.1"; sha256="2b9deb29f86c8209114b71b94fc2e1ed936a1658808a1bee46f4a82fd6a1f8cc";
+uname_s_glob="linux";          uname_m_glob="armv8l";  file="gitstatusd-${uname_s}-aarch64";        version="v1.5.4"; sha256="32b57eb28bf6d80b280e4020a0045184f8ca897b20b570c12948aa6838673225";
+uname_s_glob="linux";          uname_m_glob="i686";    file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.4"; sha256="56d55e2e9a202d3072fa612d8fa1faa61243ffc86418a7fa64c2c9d9a82e0f64";
+uname_s_glob="linux";          uname_m_glob="ppc64le"; file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.4"; sha256="1afd072c8c26ef6ec2d9ac11cef96c84cd6f10e859665a6ffcfb6112c758547e";
+uname_s_glob="linux";          uname_m_glob="x86_64";  file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.4"; sha256="9633816e7832109e530c9e2532b11a1edae08136d63aa7e40246c0339b7db304";
+uname_s_glob="msys_nt-10.0";   uname_m_glob="i686";    file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.1"; sha256="7f9b849fc52e7a95b9b933e25121ad5ae990a1871aad6616922ad7bcf1eebf20";
+uname_s_glob="msys_nt-10.0";   uname_m_glob="x86_64";  file="gitstatusd-${uname_s}-${uname_m}";     version="v1.5.1"; sha256="5d3c626b5ee564dbc13ddba89752dc58b0efe925b26dbd8b2304849d9ba01732";
+
+# Fallbacks to official gitstatusd binaries.
+uname_s_glob="cygwin_nt-*";    uname_m_glob="i686";    file="gitstatusd-cygwin_nt-10.0-${uname_m}"; version="v1.5.2"; sha256="5a8a809dcebdb6aa9b47d37e086c0485424a9d9c136770eec3c26cedf5bb75e3";
+uname_s_glob="cygwin_nt-*";    uname_m_glob="x86_64";  file="gitstatusd-cygwin_nt-10.0-${uname_m}"; version="v1.5.1"; sha256="c84cade0d6b86e04c27a6055f45851f6b46d6b88ba58772f7ca8ef4d295c800f";
+uname_s_glob="mingw32_nt-*";   uname_m_glob="i686";    file="gitstatusd-msys_nt-10.0-${uname_m}";   version="v1.5.1"; sha256="7f9b849fc52e7a95b9b933e25121ad5ae990a1871aad6616922ad7bcf1eebf20";
+uname_s_glob="mingw32_nt-*";   uname_m_glob="x86_64";  file="gitstatusd-msys_nt-10.0-${uname_m}";   version="v1.5.1"; sha256="5d3c626b5ee564dbc13ddba89752dc58b0efe925b26dbd8b2304849d9ba01732";
+uname_s_glob="mingw64_nt-*";   uname_m_glob="i686";    file="gitstatusd-msys_nt-10.0-${uname_m}";   version="v1.5.1"; sha256="7f9b849fc52e7a95b9b933e25121ad5ae990a1871aad6616922ad7bcf1eebf20";
+uname_s_glob="mingw64_nt-*";   uname_m_glob="x86_64";  file="gitstatusd-msys_nt-10.0-${uname_m}";   version="v1.5.1"; sha256="5d3c626b5ee564dbc13ddba89752dc58b0efe925b26dbd8b2304849d9ba01732";
+uname_s_glob="msys_nt-*";      uname_m_glob="i686";    file="gitstatusd-msys_nt-10.0-${uname_m}";   version="v1.5.1"; sha256="7f9b849fc52e7a95b9b933e25121ad5ae990a1871aad6616922ad7bcf1eebf20";
+uname_s_glob="msys_nt-*";      uname_m_glob="x86_64";  file="gitstatusd-msys_nt-10.0-${uname_m}";   version="v1.5.1"; sha256="5d3c626b5ee564dbc13ddba89752dc58b0efe925b26dbd8b2304849d9ba01732";
@@ -0,0 +1,406 @@
+#!/usr/bin/env zsh
+#
+# This script does not have a stable API.
+#
+# Usage: mbuild [-b git-ref] [kernel-arch]...
+#
+# Builds a bunch of gitstatusd-* binaries. Without arguments builds binaries
+# for all platforms. git-ref defaults to master.
+#
+# Before using this script you need to set up build servers and list them
+# in ~/.ssh/config. There should be a Host entry for every value of `assets`
+# association defined below. VMs and cloud instances work as well as physical
+# machines, including localhost. As long as the machine has been set up as
+# described below and you can SSH to it without password, it should work.
+#
+#                    ===[ Build Server Setup ]===
+#
+#                              Linux
+#
+# - Install docker.
+#   $ apt install docker.io     # adjust appropriately if there is no `apt`
+#   $ usermod -aG docker $USER  # not needed if going to build as root
+# - Install git.
+#   $ apt install git           # adjust appropriately if there is no `apt`
+#
+#                              macOS
+#
+# - Install compiler tools:
+#   $ xcode-select --install
+# - Install homebrew: https://brew.sh/.
+#   $ bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
+#
+#                             FreeBSD
+#
+# - Install git.
+#   $ pkg install git
+#
+#                             Windows
+#
+# - Disable Windows Defender (optional).
+#   ps> Set-MpPreference -DisableRealtimeMonitoring $true
+# - Install 64-bit and 32-bit msys2: https://www.msys2.org/wiki/MSYS2-installation/.
+#   - Open each of them after installation, type `pacman -Syu --noconfirm` and close the window.
+#   - Then run in powershell while having no msys2 or cygwin windows open:
+#     ps> C:\msys32\autorebase.bat
+#     ps> C:\msys64\autorebase.bat
+# - Install 64-bit and 32-bit cygwin: https://cygwin.com/install.html.
+#   - Choose to install 32-bit to c:/cygwin32 instead of the default c:/cygwin.
+#   - Select these packages: binutils, cmake, gcc-core, gcc-g++, git, make, perl, wget.
+#
+# IMPORTANT: Install msys2 and cygwin one at a time.
+#
+# IMPORTANT: msys2 builder can reboot the build machine.
+#
+# Option 1: OpenSSH for Windows
+#
+# - Install OpenSSH: https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse.
+#   ps> Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
+#   ps> Start-Service sshd
+#   ps> Set-Service -Name sshd -StartupType 'Automatic'
+# - Enable publickey authentication: https://stackoverflow.com/a/50502015/1095235.
+#   ps> cd $env:USERPROFILE
+#   ps> mkdir .ssh
+#   ps> notepad.exe .ssh/authorized_keys
+#     - Paste your public key, save, close.
+#   ps> icacls .ssh/authorized_keys /inheritance:r
+#   ps> notepad.exe C:\ProgramData\ssh\sshd_config
+#     - Comment out these two lines, save, close:
+#       # Match Group administrators
+#       #   AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys
+#   ps> Restart-Service sshd
+#
+# Option 2: OpenSSH from WSL
+#
+# - Install WSL.
+# - Install Ubuntu.
+# - Install sshd.
+#   $ apt install openssh-server
+#   $ dpkg-reconfigure openssh-server
+#   $ cat >/etc/ssh/sshd_config <<\END
+#     ClientAliveInterval 60
+#     AcceptEnv TERM LANG LC_*
+#     PermitRootLogin no
+#     AllowTcpForwarding no
+#     AllowAgentForwarding no
+#     AllowStreamLocalForwarding no
+#     AuthenticationMethods publickey
+#   END
+#   service ssh --full-restart
+# - Add your public ssh key to ~/.ssh/authorized_keys.
+# - Make `sshd` start when Windows boots.
+
+'emulate' '-L' 'zsh' '-o' 'no_aliases' '-o' 'err_return'
+setopt no_unset extended_glob pipe_fail prompt_percent typeset_silent \
+  no_prompt_subst no_prompt_bang pushd_silent warn_create_global
+
+if [[ $ZSH_VERSION != (5.<1->*|<6->.*) || $ZSH_VERSION == 5.4(|.*) ]]; then
+  print -ru2 -- "[error] unsupported zsh version: $ZSH_VERSION"
+  return 1
+fi
+
+zmodload zsh/system
+
+local -r git_url='https://github.com/romkatv/gitstatus.git'
+
+local -rA assets=(
+  # target kernel-arch   hostname of the build machine
+  cygwin_nt-10.0-i686    build-windows-x86_64
+  cygwin_nt-10.0-x86_64  build-windows-x86_64
+  msys_nt-10.0-i686      build-windows-x86_64
+  msys_nt-10.0-x86_64    build-windows-x86_64
+  darwin-arm64           build-macos-arm64
+  darwin-x86_64          build-macos-x86_64
+  freebsd-amd64          build-freebsd-amd64
+  linux-aarch64          build-linux-aarch64
+  linux-armv6l           build-linux-armv7l
+  linux-armv7l           build-linux-armv7l
+  linux-i686             build-linux-x86_64
+  linux-ppc64le          build-linux-ppc64le
+  linux-x86_64           build-linux-x86_64
+)
+
+local -rA protocol=(
+  'cygwin_nt-10.0-*' windows
+  'msys_nt-10.0-*'   windows
+  'darwin-*'         unix
+  'freebsd-*'        unix
+  'linux-*'          unix
+)
+
+local -r rootdir=${ZSH_SCRIPT:h}
+local -r logs=$rootdir/logs
+local -r locks=$rootdir/locks
+local -r binaries=$rootdir/usrbin
+
+function usage() {
+  print -r -- 'usage: mbuild [-b REF] [KERNEL-ARCH]...'
+}
+
+local OPTARG opt git_ref=master
+local -i OPTIND
+while getopts ":b:h" opt; do
+  case $opt in
+    h) usage; return 0;;
+    b) [[ -n $OPTARG ]]; git_ref=$OPTARG;;
+    \?) print -ru2 -- "mbuild: invalid option: -$OPTARG"           ; return 1;;
+    :)  print -ru2 -- "mbuild: missing required argument: -$OPTARG"; return 1;;
+    *)  print -ru2 -- "mbuild: invalid option: -$opt"              ; return 1;;
+  esac
+done
+
+shift $((OPTIND - 1))
+
+(( $# )) || set -- ${(ko)assets}
+set -- ${(u)@}
+
+local platform
+for platform; do
+  if (( ! $+assets[$platform] )); then
+    print -ru2 -- "mbuild: invalid platform: $platform"
+    return 1
+  fi
+done
+
+local build='
+  rm -rf gitstatus
+  git clone --recursive --shallow-submodules --depth=1 -b '$git_ref' '$git_url'
+  cd gitstatus
+  if command -v zsh >/dev/null 2>&1; then
+    sh=zsh
+  elif command -v dash >/dev/null 2>&1; then
+    sh=dash
+  elif command -v ash >/dev/null 2>&1; then
+    sh=ash
+  else
+    sh=sh
+  fi
+  $sh -x ./build -m '
+
+function build-unix() {
+  local intro flags=(-sw)
+  case $2 in
+    linux-ppc64le) ;;
+    linux-*)       flags+=(-d docker);;
+    darwin-arm64)  intro='PATH="/opt/homebrew/bin:$PATH"';;
+    darwin-*)      intro='PATH="/usr/local/bin:$PATH"';;
+  esac
+  ssh $1 -- /bin/sh -uex <<<"
+    $intro
+    cd /tmp
+    $build ${2##*-} ${(j: :)${(@q)flags}}"
+  scp $1:/tmp/gitstatus/usrbin/gitstatusd $binaries/gitstatusd-$2
+}
+
+function build-windows() {
+  local shell=$(ssh $1 'echo $0')
+  if [[ $shell == '$0'* ]]; then
+    local c='c:'
+  else
+    local c='/mnt/c'
+  fi
+
+  local tmp env bin intro flags=(-w)
+  case $2 in
+    cygwin_nt-10.0-i686)   bin='cygwin32/bin'  ;|
+    cygwin_nt-10.0-x86_64) bin='cygwin64/bin'  ;|
+    msys_nt-10.0-i686)     bin='msys32/usr/bin';|
+    msys_nt-10.0-x86_64)   bin='msys64/usr/bin';|
+    cygwin_nt-10.0-*)
+      tmp='/cygdrive/c/tmp'
+    ;|
+    msys_nt-10.0-*)
+      tmp='/c/tmp'
+      env='MSYSTEM=MSYS'
+      # TODO: fix this (some errors about PGP keys).
+      # flags+=(-s)
+      # intro='pacman -S --needed --noconfirm git; '
+      intro+='PATH="$PATH:/usr/bin/site_perl:/usr/bin/vendor_perl:/usr/bin/core_perl"'
+      while true; do
+        # TODO: run autorebase only when getting an error that can be fixed by autorebasing.
+        break
+        local out
+        out="$(ssh $1 cmd.exe "$c/${bin%%/*}/autorebase.bat" 2>&1)"
+        [[ $out == *"The following DLLs couldn't be rebased"* ]] || break
+        # Reboot to get rid of whatever is using those DLLs.
+        ssh $1 powershell.exe <<<'Restart-Computer -Force' || true
+        sleep 30
+        while ! ssh $1 <<<''; do sleep 5; done
+      done
+      () {
+        while true; do
+          # TODO: fix this (some errors about PGP keys).
+          break
+          local -i fd
+          exec {fd}< <(
+            ssh $1 $c/$bin/env.exe $env c:/$bin/bash.exe -l 2>&1 <<<"
+              pacman -Syu --noconfirm
+              exit")
+          {
+            local line
+            while true; do
+              IFS= read -u $fd -r line || return 0
+              if [[ $line == *"warning: terminate MSYS2"* ]]; then
+                # At this point the machine is hosed. A rogue process with a corrupted name
+                # is eating all CPU. The top SSH connection won't terminate on its own.
+                ssh $1 powershell.exe <<<'Restart-Computer -Force' || true
+                sleep 30
+                while ! ssh $1 <<<''; do sleep 5; done
+                break
+              fi
+            done
+          } always {
+            exec {fd}<&-
+            kill -- -$sysparams[procsubstpid] 2>/dev/null || true
+          }
+        done
+      } "$@"
+    ;|
+  esac
+
+  ssh $1 $c/$bin/env.exe $env c:/$bin/bash.exe -l <<<"
+    set -uex
+    $intro
+    mkdir -p -- $tmp
+    cd -- $tmp
+    $build ${2##*-} ${(j: :)${(@q)flags}}
+    exit"
+  scp $1:$c/tmp/gitstatus/usrbin/gitstatusd $binaries/gitstatusd-$2
+  chmod +x $binaries/gitstatusd-$2
+}
+
+if [[ -r /proc/version && "$(</proc/version)" == *Microsoft* ]]; then
+  () {
+    (( $# )) || return 0
+    print -ru2 -- "WARNING: lock files exist: $@"
+    (( $# )) && rm -- $@
+  } $locks/*(N)
+
+  function flock() {
+    local fd
+    sysopen -ro cloexec -u fd <(
+      exec </dev/null 2>/dev/null
+      (
+        trap '' TERM PIPE
+        local fd
+        while true; do
+          sysopen -wo create,excl -u fd -- $1 && break
+          sleep 1
+        done
+        exec {fd}>&-
+        while true; do
+          print || break
+        done
+        rm -- $1
+      ) &!
+    )
+    local REPLY
+    IFS= read -ru $fd
+  }
+else
+  function flock() {
+    : >>$1
+    zsystem flock $1
+  }
+fi
+
+function build() (
+  setopt xtrace
+  local platform=$1
+  local machine=$assets[$platform]
+  flock $locks/$machine
+  build-${protocol[(k)$platform]} $machine $platform
+  local tmp=gitstatusd-$platform.tmp.$$.tar.gz
+  ( cd -q -- $binaries; tar --owner=0 --group=0 -I 'gzip -9' -cf $tmp gitstatusd-$platform )
+  mv -f -- $binaries/$tmp $binaries/gitstatusd-$platform.tar.gz
+  # Make sure the last command is a built-in (important for flock).
+  :
+)
+
+function mbuild() {
+  local platform pid pids=()
+  for platform; do
+    build $platform &>$logs/$platform &
+    print -r -- "starting build for $platform on $assets[$platform] (pid $!)"
+    pids+=($platform $!)
+  done
+  local failed=()
+  for platform pid in $pids; do
+    print -rn -- "$platform => "
+    if wait $pid; then
+      print -r -- "ok"
+    else
+      print -r -- "error"
+      failed+=$platform
+    fi
+  done
+  (( $#failed )) || return 0
+  print
+  print -r -- "Error logs:"
+  print
+  for platform in $failed; do
+    print -r -- "  $platform => $logs/$platform"
+  done
+  return 1
+}
+
+# Copied from https://github.com/romkatv/run-process-tree.
+function run-process-tree() {
+  zmodload zsh/parameter zsh/param/private || return
+  local -P opt=(${(kv)options[@]})         || return
+  local -P pat=(${patchars[@]})            || return
+  local -P dis_pat=(${dis_patchars[@]})    || return
+  emulate -L zsh -o err_return             || return
+  setopt monitor traps_async pipe_fail no_unset
+  zmodload zsh/system
+
+  if (( $# == 0 )); then
+    print -ru2 -- 'usage: run-process-tree command [arg]...'
+    return 1
+  fi
+
+  local -P stdout REPLY
+  exec {stdout}>&1
+  {
+    {
+      local -Pi pipe
+      local -P gid=$sysparams[pid]
+      local -P sig=(ABRT EXIT HUP ILL INT PIPE QUIT TERM ZERR)
+      local -P trap=(trap "trap - $sig; kill -- -$sysparams[pid]" $sig)
+
+      exec {pipe}>&1 1>&$stdout
+      $trap
+
+      {
+        $trap
+        while sleep 1 && print -u $pipe .; do; done
+      } 2>/dev/null &
+      local -Pi watchdog=$!
+
+      {
+        trap - ZERR
+        exec {pipe}>&-
+        enable -p -- $pat
+        disable -p -- $dis_pat
+        options=($opt zle off monitor off)
+        "$@"
+      } &
+      local -Pi ret
+      wait $! || ret=$?
+
+      trap "exit $ret" TERM
+      kill $watchdog
+      wait $watchdog
+      return ret
+    } | while read; do; done || return
+  } always {
+    exec {stdout}>&-
+  }
+}
+
+mkdir -p -- $logs $locks $binaries
+
+() {
+  run-process-tree mbuild $@
+  exit
+} "$@"
@@ -0,0 +1,37 @@
+// Copyright 2019 Roman Perepelitsa.
+//
+// This file is part of GitStatus.
+//
+// GitStatus is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// GitStatus is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with GitStatus. If not, see <https://www.gnu.org/licenses/>.
+
+#ifndef ROMKATV_GITSTATUS_ALGORITHM_H_
+#define ROMKATV_GITSTATUS_ALGORITHM_H_
+
+#include <algorithm>
+
+namespace gitstatus {
+
+// Requires: Iter is a BidirectionalIterator.
+//
+// Returns iterator pointing to the last value in [begin, end) that compares equal to the value, or
+// begin if none compare equal.
+template <class Iter, class T>
+Iter FindLast(Iter begin, Iter end, const T& val) {
+  while (begin != end && !(*--end == val)) {}
+  return end;
+}
+
+}  // namespace gitstatus
+
+#endif  // ROMKATV_GITSTATUS_ALGORITHM_H_
@@ -0,0 +1,118 @@
+// Copyright 2019 Roman Perepelitsa.
+//
+// This file is part of GitStatus.
+//
+// GitStatus is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// GitStatus is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with GitStatus. If not, see <https://www.gnu.org/licenses/>.
+
+#include "arena.h"
+
+#include <algorithm>
+#include <type_traits>
+
+#include "bits.h"
+#include "check.h"
+
+namespace gitstatus {
+
+namespace {
+
+size_t Clamp(size_t min, size_t val, size_t max) { return std::min(max, std::max(min, val)); }
+
+static const uintptr_t kSingularity = reinterpret_cast<uintptr_t>(&kSingularity);
+
+}  // namespace
+
+// Triple singularity. We are all fucked.
+Arena::Block Arena::g_empty_block = {kSingularity, kSingularity, kSingularity};
+
+Arena::Arena(Arena::Options opt) : opt_(std::move(opt)), top_(&g_empty_block) {
+  CHECK(opt_.min_block_size <= opt_.max_block_size);
+}
+
+Arena::Arena(Arena&& other) : Arena() { *this = std::move(other); }
+
+Arena::~Arena() {
+  // See comments in Makefile for the reason sized deallocation is not used.
+  for (const Block& b : blocks_) ::operator delete(reinterpret_cast<void*>(b.start));
+}
+
+Arena& Arena::operator=(Arena&& other) {
+  if (this != &other) {
+    // In case std::vector ever gets small object optimization.
+    size_t idx = other.reusable_ ? other.top_ - other.blocks_.data() : 0;
+    opt_ = other.opt_;
+    blocks_ = std::move(other.blocks_);
+    reusable_ = other.reusable_;
+    top_ = reusable_ ? blocks_.data() + idx : &g_empty_block;
+    other.blocks_.clear();
+    other.reusable_ = 0;
+    other.top_ = &g_empty_block;
+  }
+  return *this;
+}
+
+void Arena::Reuse(size_t num_blocks) {
+  reusable_ = std::min(reusable_, num_blocks);
+  for (size_t i = reusable_; i != blocks_.size(); ++i) {
+    const Block& b = blocks_[i];
+    // See comments in Makefile for the reason sized deallocation is not used.
+    ::operator delete(reinterpret_cast<void*>(b.start));
+  }
+  blocks_.resize(reusable_);
+  if (reusable_) {
+    top_ = blocks_.data();
+    top_->tip = top_->start;
+  } else {
+    top_ = &g_empty_block;
+  }
+}
+
+void Arena::AddBlock(size_t size, size_t alignment) {
+  if (alignment > alignof(std::max_align_t)) {
+    size += alignment - 1;
+  } else {
+    size = std::max(size, alignment);
+  }
+  if (size <= top_->size() && top_ < blocks_.data() + reusable_ - 1) {
+    assert(blocks_.front().size() == top_->size());
+    ++top_;
+    top_->tip = top_->start;
+    return;
+  }
+  if (size <= opt_.max_alloc_threshold) {
+    size =
+        std::max(size, Clamp(opt_.min_block_size, NextPow2(top_->size() + 1), opt_.max_block_size));
+  }
+
+  auto p = reinterpret_cast<uintptr_t>(::operator new(size));
+  blocks_.push_back(Block{p, p, p + size});
+  if (reusable_) {
+    if (size < blocks_.front().size()) {
+      top_ = &blocks_.back();
+      return;
+    }
+    if (size > blocks_.front().size()) reusable_ = 0;
+  }
+  std::swap(blocks_.back(), blocks_[reusable_]);
+  top_ = &blocks_[reusable_++];
+}
+
+void* Arena::AllocateSlow(size_t size, size_t alignment) {
+  assert(alignment && !(alignment & (alignment - 1)));
+  AddBlock(size, alignment);
+  assert(Align(top_->tip, alignment) + size <= top_->end);
+  return Allocate(size, alignment);
+}
+
+}  // namespace gitstatus
@@ -0,0 +1,273 @@
+// Copyright 2019 Roman Perepelitsa.
+//
+// This file is part of GitStatus.
+//
+// GitStatus is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// GitStatus is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with GitStatus. If not, see <https://www.gnu.org/licenses/>.
+
+#ifndef ROMKATV_GITSTATUS_ARENA_H_
+#define ROMKATV_GITSTATUS_ARENA_H_
+
+#include <cassert>
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <limits>
+#include <new>
+#include <type_traits>
+#include <vector>
+
+#include "string_view.h"
+
+namespace gitstatus {
+
+// Thread-compatible. Very fast and very flexible w.r.t. allocation size and alignment.
+//
+// Natural API extensions:
+//
+//   // Donates a block to the arena. When the time comes, it'll be freed with
+//   // free(p, size, userdata).
+//   void Donate(void* p, size_t size, void* userdata, void(*free)(void*, size_t, void*));
+class Arena {
+ public:
+  struct Options {
+    // The first call to Allocate() will allocate a block of this size. There is one exception when
+    // the first requested allocation size is larger than this limit. Subsequent blocks will be
+    // twice as large as the last until they saturate at max_block_size.
+    size_t min_block_size = 64;
+
+    // Allocate blocks at most this large. There is one exception when the requested allocation
+    // size is larger than this limit.
+    size_t max_block_size = 8 << 10;
+
+    // When the size of the first allocation in a block is larger than this threshold, the block
+    // size will be equal to the allocation size. This is meant to reduce memory waste when making
+    // many allocations with sizes slightly over max_block_size / 2. With max_alloc_threshold equal
+    // to max_block_size / N, the upper bound on wasted memory when making many equally-sized
+    // allocations is 100.0 / (N + 1) percent. When making allocations of different sizes, the upper
+    // bound on wasted memory is 50%.
+    size_t max_alloc_threshold = 1 << 10;
+
+    // Natural extensions:
+    //
+    //   void* userdata;
+    //   void (*alloc)(size_t size, size_t alignment, void* userdata);
+    //   void (*free)(void* p, size_t size, void* userdata);
+  };
+
+  // Requires: opt.min_block_size <= opt.max_block_size.
+  //
+  // Doesn't allocate any memory.
+  Arena(Options opt);
+  Arena() : Arena(Options()) {}
+  Arena(Arena&&);
+  ~Arena();
+
+  Arena& operator=(Arena&& other);
+
+  // Requires: alignment is a power of 2.
+  //
+  // Result is never null and always aligned. If size is zero, the result may be equal to the last.
+  // Alignment above alignof(std::max_align_t) is supported. There is no requirement for alignment
+  // to be less than size or to divide it.
+  inline void* Allocate(size_t size, size_t alignment) {
+    assert(alignment && !(alignment & (alignment - 1)));
+    uintptr_t p = Align(top_->tip, alignment);
+    uintptr_t e = p + size;
+    if (e <= top_->end) {
+      top_->tip = e;
+      return reinterpret_cast<void*>(p);
+    }
+    return AllocateSlow(size, alignment);
+  }
+
+  template <class T>
+  inline T* Allocate(size_t n) {
+    static_assert(!std::is_reference<T>(), "");
+    return static_cast<T*>(Allocate(n * sizeof(T), alignof(T)));
+  }
+
+  template <class T>
+  inline T* Allocate() {
+    return Allocate<T>(1);
+  }
+
+  inline char* MemDup(const char* p, size_t len) {
+    char* res = Allocate<char>(len);
+    std::memcpy(res, p, len);
+    return res;
+  }
+
+  // Copies the null-terminated string (including the trailing null character) to the arena and
+  // returns a pointer to the copy.
+  inline char* StrDup(const char* s) {
+    size_t len = std::strlen(s);
+    return MemDup(s, len + 1);
+  }
+
+  // Guarantees: !StrDup(p, len)[len].
+  inline char* StrDup(const char* p, size_t len) {
+    char* res = Allocate<char>(len + 1);
+    std::memcpy(res, p, len);
+    res[len] = 0;
+    return res;
+  }
+
+  // Guarantees: !StrDup(s)[s.len].
+  inline char* StrDup(StringView s) {
+    return StrDup(s.ptr, s.len);
+  }
+
+  template <class... Ts>
+  inline char* StrCat(const Ts&... ts) {
+    return [&](std::initializer_list<StringView> ss) {
+      size_t len = 0;
+      for (StringView s : ss) len += s.len;
+      char* p = Allocate<char>(len + 1);
+      for (StringView s : ss) {
+        std::memcpy(p, s.ptr, s.len);
+        p += s.len;
+      }
+      *p = 0;
+      return p - len;
+    }({ts...});
+  }
+
+  // Copies/moves `val` to the arena and returns a pointer to it.
+  template <class T>
+  inline std::remove_const_t<std::remove_reference_t<T>>* Dup(T&& val) {
+    return DirectInit<std::remove_const_t<std::remove_reference_t<T>>>(std::forward<T>(val));
+  }
+
+  // The same as `new T{args...}` but on the arena.
+  template <class T, class... Args>
+  inline T* DirectInit(Args&&... args) {
+    T* res = Allocate<T>();
+    ::new (const_cast<void*>(static_cast<const void*>(res))) T(std::forward<Args>(args)...);
+    return res;
+  }
+
+  // The same as `new T(args...)` but on the arena.
+  template <class T, class... Args>
+  inline T* BraceInit(Args&&... args) {
+    T* res = Allocate<T>();
+    ::new (const_cast<void*>(static_cast<const void*>(res))) T{std::forward<Args>(args)...};
+    return res;
+  }
+
+  // Tip() and TipSize() allow you to allocate the remainder of the current block. They can be
+  // useful if you are flexible w.r.t. the allocation size.
+  //
+  // Invariant:
+  //
+  //   const void* tip = Tip();
+  //   void* p = Allocate(TipSize(), 1);  // grab the remainder of the current block
+  //   assert(p == tip);
+  const void* Tip() const { return reinterpret_cast<const void*>(top_->tip); }
+  size_t TipSize() const { return top_->end - top_->tip; }
+
+  // Invalidates all allocations (without running destructors of allocated objects) and frees all
+  // blocks except at most the specified number of blocks. The retained blocks will be used to
+  // fulfil future allocation requests.
+  void Reuse(size_t num_blocks = std::numeric_limits<size_t>::max());
+
+ private:
+  struct Block {
+    size_t size() const { return end - start; }
+    uintptr_t start;
+    uintptr_t tip;
+    uintptr_t end;
+  };
+
+  inline static size_t Align(size_t n, size_t m) { return (n + m - 1) & ~(m - 1); };
+
+  void AddBlock(size_t size, size_t alignment);
+  bool ReuseBlock(size_t size, size_t alignment);
+
+  __attribute__((noinline)) void* AllocateSlow(size_t size, size_t alignment);
+
+  Options opt_;
+  std::vector<Block> blocks_;
+  // Invariant: !blocks_.empty() <= reusable_ && reusable_ <= blocks_.size().
+  size_t reusable_ = 0;
+  // Invariant: (top_ == &g_empty_block) == blocks_.empty().
+  // Invariant: blocks_.empty() || top_ == &blocks_.back() || top_ < blocks_.data() + reusable_.
+  Block* top_;
+
+  static Block g_empty_block;
+};
+
+// Copies of ArenaAllocator use the same thread-compatible Arena without synchronization.
+template <class T>
+class ArenaAllocator {
+ public:
+  using value_type = T;
+  using pointer = T*;
+  using const_pointer = const T*;
+  using reference = T&;
+  using const_reference = const T&;
+  using size_type = size_t;
+  using difference_type = ptrdiff_t;
+  using propagate_on_container_move_assignment = std::true_type;
+  template <class U>
+  struct rebind {
+    using other = ArenaAllocator<U>;
+  };
+  using is_always_equal = std::false_type;
+
+  ArenaAllocator(Arena* arena = nullptr) : arena_(*arena) {}
+
+  Arena& arena() const { return arena_; }
+
+  pointer address(reference x) const { return &x; }
+  const_pointer address(const_reference x) const { return &x; }
+  pointer allocate(size_type n, const void* hint = nullptr) { return arena_.Allocate<T>(n); }
+  void deallocate(T* p, std::size_t n) {}
+  size_type max_size() const { return std::numeric_limits<size_type>::max() / sizeof(value_type); }
+
+  template <class U, class... Args>
+  void construct(U* p, Args&&... args) {
+    ::new (const_cast<void*>(static_cast<const void*>(p))) U(std::forward<Args>(args)...);
+  }
+
+  template <class U>
+  void destroy(U* p) {
+    p->~U();
+  }
+
+  bool operator==(const ArenaAllocator& other) const { return &arena_ == &other.arena_; }
+  bool operator!=(const ArenaAllocator& other) const { return &arena_ != &other.arena_; }
+
+ private:
+  Arena& arena_;
+};
+
+template <class C>
+struct LazyWithArena;
+
+template <template <class, class> class C, class T1, class A>
+struct LazyWithArena<C<T1, A>> {
+  using type = C<T1, ArenaAllocator<typename C<T1, A>::value_type>>;
+};
+
+template <template <class, class, class> class C, class T1, class T2, class A>
+struct LazyWithArena<C<T1, T2, A>> {
+  using type = C<T1, T2, ArenaAllocator<typename C<T1, T2, A>::value_type>>;
+};
+
+template <class C>
+using WithArena = typename LazyWithArena<C>::type;
+
+}  // namespace gitstatus
+
+#endif  // ROMKATV_GITSTATUS_DIR_H_
@@ -0,0 +1,29 @@
+// Copyright 2019 Roman Perepelitsa.
+//
+// This file is part of GitStatus.
+//
+// GitStatus is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// GitStatus is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with GitStatus. If not, see <https://www.gnu.org/licenses/>.
+
+#ifndef ROMKATV_GITSTATUS_BITS_H_
+#define ROMKATV_GITSTATUS_BITS_H_
+
+#include <cstddef>
+
+namespace gitstatus {
+
+inline size_t NextPow2(size_t n) { return n < 2 ? 1 : (~size_t{0} >> __builtin_clzll(n - 1)) + 1; }
+
+}  // namespace gitstatus
+
+#endif  // ROMKATV_GITSTATUS_BITS_H_
@@ -0,0 +1,61 @@
+// Copyright 2019 Roman Perepelitsa.
+//
+// This file is part of GitStatus.
+//
+// GitStatus is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// GitStatus is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with GitStatus. If not, see <https://www.gnu.org/licenses/>.
+
+#ifndef ROMKATV_GITSTATUS_CHECK_H_
+#define ROMKATV_GITSTATUS_CHECK_H_
+
+#include "logging.h"
+
+#include <stdexcept>
+
+// The argument must be an expression convertible to bool.
+// Does nothing if the expression evaluates to true. Otherwise
+// it's equivalent to LOG(FATAL).
+#define CHECK(cond...) \
+  static_cast<void>(0), (!!(cond)) ? static_cast<void>(0) : LOG(FATAL) << #cond << ": "
+
+#define VERIFY(cond...)                                               \
+  static_cast<void>(0), ::gitstatus::internal_check::Thrower(!(cond)) \
+                            ? static_cast<void>(0)                    \
+                            : LOG(ERROR) << #cond << ": "
+
+namespace gitstatus {
+
+struct Exception : std::exception {
+  const char* what() const noexcept override { return "Exception"; }
+};
+
+namespace internal_check {
+
+class Thrower {
+ public:
+  Thrower(bool should_throw) : throw_(should_throw) {}
+  Thrower(Thrower&&) = delete;
+  explicit operator bool() const { return !throw_; }
+  ~Thrower() noexcept(false) {
+    if (throw_) throw Exception();
+  }
+
+ private:
+  bool throw_;
+};
+
+}  // namespace internal_check
+
+}  // namespace gitstatus
+
+#endif  // ROMKATV_GITSTATUS_CHECK_H_
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
jochen	9c84cd9e6c	Phase 3: asus-zephyrus-g14 and memory-pressure, with Go tools and long-running code The laptop model's hardware module and a memory-pressure module for any machine (hq research 027/03, 026/05, to-be 42 phase 3). The predecessor's polling auto-profile and mem-guard user scripts become each module's own Go code launched by the node runtime (ADR 0198): a profile switcher woken by the kernel's power-supply uevents, and a guard that warns on RAM, swap or PSI before systemd-oomd acts, on the desktop over the account's bus and always as an event. supergfxctl and triggerhappy are kept as found (research 027 Q1).	2026-10-04 12:56:23 +02:00
mesh-admin	19a4055bb5	Merge pull request 'The photo clients publish the endpoint they declare (hq issue 227)' (#263 ) from fix/the-photo-admin-client-publishes-the-port-it-declares into main	2026-10-04 10:27:22 +00:00
jschoubben	1bc6daf31b	The photo clients publish the endpoint they declare (hq issue 227) Each declares a web endpoint — 4001, 4012, 4013 — and published a bare 80, which the mesh has nothing to assign for, so 80 reached the machine and collided with the reverse proxy. Written the long way, the software's 80 is published at the port the module declares and the mesh rewrites the outer half to whatever it assigned. photos is the one that failed on the control node; the other two are the same fault waiting for a machine that runs a proxy.	2026-10-04 12:25:28 +02:00
mesh-admin	9208f7409a	Merge pull request 'systemd owns its package; systemd-networkd configures networkd and claims none' (#261 ) from fix/systemd-owns-its-package into main	2026-10-04 10:17:23 +00:00
jochen	a80af7a97f	systemd owns its package; systemd-networkd configures networkd and claims none The service manager's package was declared by the networking module, so the module that is systemd could not own it and had to leave it out. networkd is a component of systemd: its module configures it. Removing the package resource from systemd-networkd uninstalls nothing — the host never removes a package that is not declared absent.	2026-10-04 12:17:08 +02:00
mesh-admin	83a51832d7	Merge pull request 'claude-code writes its managed files from a staged file, not /dev/stdin' (#258 ) from fix/claude-code-writes-managed-from-a-file into main	2026-10-04 10:01:17 +00:00
mesh-admin	9e63a258d0	Merge pull request 'zsh: keep each PATH directory once' (#260 ) from fix/zsh-unique-path into main	2026-10-04 09:34:43 +00:00
jochen	328d90fb88	zsh: keep each PATH directory once Every nested shell, and every sourced file that prepends, added the same directories again; a workstation's PATH carried each of several entries three times. typeset -U in the .zshenv block applies to every zsh.	2026-10-04 11:34:36 +02:00
mesh-admin	ca5ab288f6	Merge pull request 'zsh: save history and initialise completion' (#259 ) from fix/zsh-completion-and-history into main	2026-10-04 09:33:28 +00:00
jochen	5fd0f72221	zsh: save history and initialise completion zsh saves no history by default (SAVEHIST=0) and nothing called compinit, so every machine had 30 lines of unsaved history and only basic completion. Found reviewing the shell on its first machine (hq to-be 41).	2026-10-04 11:33:17 +02:00
jochen	5003dc0377	claude-code writes its managed files from a staged file, not /dev/stdin Node hands a child its input over a socket, which /dev/stdin cannot open (ENXIO): on the first assignment nothing under /etc/claude-code was written.	2026-10-04 11:31:44 +02:00
mesh-admin	0a78d130e5	Merge pull request 'claude-code watches its MCP servers beside the handshake, and retries' (#257 ) from fix/claude-code-watches-without-blocking into main	2026-10-04 09:21:26 +00:00
jochen	4295aad88e	claude-code watches its MCP servers beside the handshake, and asks again until the state answers (novox/hq ADR 0201) Awaited at import, a bucket not yet on the bus — or a grant the bus had not reloaded — answered after the runtime's 10s handshake, and the module was left unserved on its first assignment. Also cites module state as ADR 0201, as hq main numbers it (folds #256).	2026-10-04 11:13:33 +02:00
mesh-admin	9dfd3b1105	Merge pull request 'claude-code: the operator's agent, its managed configuration and the licence consumer side (hq design 36, to-be 40 WP2)' (#244 ) from feat/claude-code-agent into main	2026-10-04 09:01:31 +00:00
mesh-admin	22e8714040	Merge pull request 'The shell and the account's environment as modules: node-env, zsh, powerlevel10k, two plugins, and systemd finished (hq to-be 41 WP3, WP4)' (#255 ) from feat/the-shell-and-its-environment into main	2026-10-04 08:55:11 +00:00
jochen	11e7ede8a4	Merge remote-tracking branch 'origin/main' into feat/the-shell-and-its-environment	2026-10-04 10:31:03 +02:00
jochen	42c80fa9e1	zsh: no doubled blank line in the block when the first slot is empty	2026-10-04 04:05:30 +02:00
jochen	56e0830700	zsh-autosuggestions, zsh-syntax-highlighting: the plugins as packages and one line each The distribution packages both, so they are installed as packages rather than cloned or vendored (novox/hq ADR 0205). Each contributes the line that loads the package's own copy, from the path the Arch package installs, to a slot of the login shell's block (ADR 0204). Syntax highlighting goes in last, as its upstream asks.	2026-10-04 04:04:35 +02:00
jochen	0844b35ebb	powerlevel10k: the prompt as a pinned archive of the module's own, loaded from a slot The distribution does not package the theme, and the predecessor cloned whatever upstream's default branch held the day a hook ran (novox/hq ADR 0205). So upstream's v1.20.0 release is vendored verbatim, with its licence, and shipped as an archive the host unpacks under the account's home and checks by digest. The prompt's configuration is today's ~/.p10k.zsh byte for byte, as a second archive. Inline, its 86 KB would ride in every declaration and be unreviewable JSON. The zsh code that loads both is a contribution to the normal slot (ADR 0204). Instant prompt stays off, as it is today.	2026-10-04 04:04:10 +02:00
jochen	566739e02c	zsh: hold the mesh's login-shell seat, source the environment, and leave the rest to slots The seat is now the mesh's node-login-shell, which a shell module claims rather than declares (novox/hq ADR 0204), and the environment is one module's that every module contributes to (ADR 0203). Per hq to-be 41 WP3: - no seat declaration; the claim is node-login-shell serving execute; - EDITOR, VISUAL, XDG_CONFIG_HOME and the three PATH entries are an environment contribution, not exports in the block; - a ~/.zshenv block sources ~/.config/mesh/environment.sh, so a script, a login and execute all see the environment; - the ~/.zshrc block goes at the start, so the operator's lines run after it, and holds today's shared defaults between the first, normal and last slots. The prompt, the plugins and the operator's own lines are no longer in it; - execute is bounded below the runtime's call limit (20 s default, 25 s at most), kills its whole process group on timeout, cuts each stream at 256 KiB and says so, runs in the account's home without the mesh's words, with the account's session words. The dead runuser branch is gone, because the runtime is the account; - zsh_config shows both files with their block line counts; - the README lists the one-off migration (ADR 0182).	2026-10-04 04:02:54 +02:00
jochen	38b56a7877	node-env: the account's environment as one module's two files Every module contributes variables and PATH entries as facts, and one holder of node-environment places them (novox/hq ADR 0203, to-be 41 WP3). This is that holder: no package, no process, no tools — the directories it owns under the home and two files the controller fills, the POSIX file at the path the seat fixes (~/.config/mesh/environment.sh, sourced by the login shell) and environment.d's 50-mesh.conf for the account's service manager and graphical session.	2026-10-04 03:59:50 +02:00
jochen	0596503db5	systemd: act as the runtime's account can, and never read a failure as an answer The node tools runtime runs as the operator account, not root, and gives its bundles no session words (novox/hq ADR 0175, 0188, 0193). So, per hq to-be 41 WP4: - system-scope start/stop/restart/enable/disable go through sudo -n when not root, as the packet filter and intrusion prevention do, and a refusal is named by how it failed; - user scope is plain --user with XDG_RUNTIME_DIR and the session bus of /run/user/<uid>; the dead --machine branches are gone; - a failed systemctl or journalctl is an error, and an unreachable user manager is said even when systemctl exits 0; systemd_failed reports it beside the other manager's answer instead of claiming nothing failed; - status says whether the mesh declares the unit: its loaded unit file begins with the header the host writes for a module's process. Only such a unit carries the restore note; - the package resource goes: the service manager is always present, and it collided with systemd-networkd's identical declaration; - calls are bounded below the runtime's call limit, a unit name is never an option, and the runner is injected so the tests use a fake one.	2026-10-04 03:58:19 +02:00
jochen	3668b02b94	claude-code keeps its MCP servers in state, not events (novox/hq ADR 0202) One key per registration in the module's servers bucket — all.<server> or <node>.<server> — watched by every node, so a node assigned after a registration takes it at start, which the mcp.registered event could not do. Also narrows apply()'s refusal by hand: the builder compiles without strict, where the discriminated union does not narrow and the build failed.	2026-10-04 03:48:41 +02:00
jochen	a1d7b9ad5a	systemd: the service manager as a module — holds node-service-manager and answers for the units in both scopes The holder of the seat the controller seeds under novox/hq ADR 0177. Eight verbs under the seat's name — units, status, start, stop, restart, enable, disable, journal — each taking an optional scope, "system" by default or "user" for the operator account's own manager, reached as `systemctl --user --machine=<account>@` when the runtime is not that account. One tool of its own, systemd_failed, for every failed unit in both scopes. A package, a claim and a bundle; no container, no process: served by the node tools runtime (ADR 0175) once it exists. `module check` passes against a controller that carries the seat; the tools type-check against the SDK.	2026-10-04 02:32:34 +02:00
jochen	5548b0f4e9	zsh: the shell as a module — package, the mesh's ~/.zshrc block, the login-shell seat and execute The first module of the operator's environment (novox/hq to-be 37 §1, ADR 0173, 0176). A package, the mesh's default configuration as a block inside the account's ~/.zshrc so the operator's own lines around it survive every push (ADR 0174 as the host's `into: block` realises it), a `user` shape that makes zsh the account's login shell, the `login-shell` seat declared with its one verb, and a tools bundle: `execute` under the seat's name, `zsh_config` under the module's. No container, no process: the tools are served by the node tools runtime (ADR 0175), which does not exist yet — the bundle builds and the manifest registers ahead of it. `module check` passes; the tools type-check against the SDK. Two things the manifest cannot yet say, left for the controller: the `user` shape applies wherever the module is assigned, not only where it holds the seat; and the runtime learns the account from MESH_OPERATOR_ACCOUNT, which nothing sets yet.	2026-10-04 02:32:34 +02:00
jochen	295cc59e1e	claude-code: declare using the licence manager's seat when that module exists; until then the mesh refuses a seat no module declares	2026-10-04 02:23:34 +02:00
jochen	6a7e4ebd5e	claude-code over NATS: licence events, a token by request, a login pushed to the manager, MCP servers registered per node or mesh-wide Events carry what happened and no secret; tokens travel on requests (design 32 §10). The manager's licence.rotated/switched events make the module ask anthropic-licence-manager.current; at start it asks once to catch up. A refresh token appearing in the credentials file is a login: it is pushed to the manager's adopt at once, sealed to the manager's key — the one time a refresh token travels. A switch replaces the old licence's grant whole, removes the API key and its helper, and rewrites oauthAccount in ~/.claude.json. New tools register and unregister MCP servers on this node, or with nodes: all / a list via an mcp.registered event every node consumes; called for one node, the answer names the other nodes running claude-code. 26 tests.	2026-10-04 02:23:23 +02:00
jochen	03e729d103	claude-code owns /etc/claude-code and ~/.claude as declared directories So the controller's ownership check refuses a second module owning either. ~/.claude is the operator's at 0700 (it was 0755 on the workstations); of what is inside, the module owns only what it writes, and the host keeps a directory that is not empty when the module goes (hq ADR 0182).	2026-10-03 23:49:16 +02:00
jochen	eab335b755	claude-code: launched over stdio (ADR 0193), the console's five tools in its instructions (ADR 0195) Every bundle is now a child speaking MCP over stdio, so stdout is the channel: the module logs on stderr. The managed CLAUDE.md teaches mesh_search, mesh_describe, mesh_call, mesh_overview and mesh_machine with addresses (<seat>.<verb>, <node>/<module>.<tool>) instead of flat tool names. A hand-over is applied whatever the trailing render says; a failed render is reported beside it. Proven over stdio as the runtime drives it: five tools listed, a key made on first use, a sealed switch writing an access-token-only 0600 credentials file that keeps unknown keys.	2026-10-03 23:41:01 +02:00
jochen	f42b58f789	claude-code: the manifest, the managed directory and the tools (hq design 36, to-be 40 WP2) The module owns /etc/claude-code: managed-mcp.json lists the console as `mesh` over HTTP on loopback plus the servers in its mcp_servers setting (exclusive, by the operator's choice — the https rule of managedMcpServers refuses a loopback console); managed-settings.json carries the attribution convention, keeps claude.ai connectors, and adds the key-helper only for an API-key licence; CLAUDE.md says how a session here works. Rendered whenever the runtime collects the tools, written only on change, through the operator account's sudo. Under the home, only the credentials file, only on a hand-over. Nothing declared under a home or /etc; the console's port comes from node-tools' mcp-endpoint (mesh-tools #34).	2026-10-03 23:40:21 +02:00
jochen	5737752744	claude-code: the sealed hand-over, the credentials write with the lineage rule, the identity read (hq to-be 40 WP2, in progress) The parts of the agent module that hold whichever way the console is registered: X25519 + HKDF + AES-GCM from Node's own library so the bundle carries no dependency; the predecessor's lineage rule (rotation only if newer, a re-issue adopted, a switch regardless) with its incidents as tests; an atomic 0600 write that strips any refresh token and keeps keys it does not know; the account read from the agent's own state file. Manifest and renderer follow.	2026-10-03 23:40:21 +02:00