From e8764b802a2e826eae560de9fea7d848a665ab82 Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sat, 3 Oct 2026 12:49:36 +0800 Subject: [PATCH 1/6] fix(overlays): backport smartctl_exporter Describe fix (upstream #329) smartctl_exporter 0.14.0 derives Describe() from the devices it can read at startup. A device that only becomes readable later (an NVMe whose ACL arrives late, or an HDD waking from standby) then makes Collect() emit metrics with unregistered descriptors, so /metrics returns HTTP 500 and the whole scrape fails, hiding even the healthy disks. Backport upstream PR #329, which makes Describe() send the full explicit descriptor set. Carry it as an overlay until smartctl_exporter 0.15.0 is released and packaged in nixpkgs. Refs: https://github.com/prometheus-community/smartctl_exporter/pull/329 --- overlays/README.md | 6 +++ .../329-explicit-descriptors.patch | 50 +++++++++++++++++++ overlays/smartctl-exporter/default.nix | 15 ++++++ 3 files changed, 71 insertions(+) create mode 100644 overlays/smartctl-exporter/329-explicit-descriptors.patch create mode 100644 overlays/smartctl-exporter/default.nix diff --git a/overlays/README.md b/overlays/README.md index f410f62c..1b87f9d3 100644 --- a/overlays/README.md +++ b/overlays/README.md @@ -13,6 +13,9 @@ overlays/ ├── default.nix # Entrypoint for all overlays ├── computer-use-linux.nix # trycua/computer-use-linux package ├── cua-driver.nix # trycua/cua driver (cua-driver) package +├── smartctl-exporter/ # smartctl_exporter backport (upstream PR #329) +│ ├── default.nix +│ └── 329-explicit-descriptors.patch └── fcitx5/ # Chinese input method configuration ├── README.md ├── default.nix # fcitx5 overlay definition @@ -55,3 +58,6 @@ This overlay provides: - `computer-use-linux.nix`: packages `pkgs/computer-use-linux`. - `cua-driver.nix`: packages `pkgs/cua-driver` (used by the computer-use VMs). +- `smartctl-exporter/`: patches `prometheus-smartctl-exporter` with upstream PR + [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) until smartctl_exporter + 0.15.0 is released; see `overlays/smartctl-exporter/default.nix`. diff --git a/overlays/smartctl-exporter/329-explicit-descriptors.patch b/overlays/smartctl-exporter/329-explicit-descriptors.patch new file mode 100644 index 00000000..6fdeb6c8 --- /dev/null +++ b/overlays/smartctl-exporter/329-explicit-descriptors.patch @@ -0,0 +1,50 @@ +diff --git a/main.go b/main.go +index c5b138a..05a222e 100644 +--- a/main.go ++++ b/main.go +@@ -57,7 +57,44 @@ type SMARTctlManagerCollector struct { + + // Describe sends the super-set of all possible descriptors of metrics + func (i *SMARTctlManagerCollector) Describe(ch chan<- *prometheus.Desc) { +- prometheus.DescribeByCollect(i, ch) ++ ch <- metricSmartctlVersion ++ ch <- metricDeviceModel ++ ch <- metricDeviceCount ++ ch <- metricDeviceCapacityBlocks ++ ch <- metricDeviceCapacityBytes ++ ch <- metricDeviceTotalCapacityBytes ++ ch <- metricDeviceBlockSize ++ ch <- metricDeviceInterfaceSpeed ++ ch <- metricDeviceAttribute ++ ch <- metricDevicePowerOnSeconds ++ ch <- metricDeviceRotationRate ++ ch <- metricDeviceTemperature ++ ch <- metricDevicePowerCycleCount ++ ch <- metricDevicePercentageUsed ++ ch <- metricDeviceAvailableSpare ++ ch <- metricDeviceAvailableSpareThreshold ++ ch <- metricDeviceCriticalWarning ++ ch <- metricDeviceMediaErrors ++ ch <- metricDeviceNumErrLogEntries ++ ch <- metricDeviceBytesRead ++ ch <- metricDeviceBytesWritten ++ ch <- metricDeviceSmartStatus ++ ch <- metricDeviceExitStatus ++ ch <- metricDeviceState ++ ch <- metricDeviceStatistics ++ ch <- metricDeviceErrorLogCount ++ ch <- metricDeviceSelfTestLogCount ++ ch <- metricDeviceSelfTestLogErrorCount ++ ch <- metricDeviceERCSeconds ++ ch <- metricSCSIGrownDefectList ++ ch <- metricReadErrorsCorrectedByRereadsRewrites ++ ch <- metricReadErrorsCorrectedByEccFast ++ ch <- metricReadErrorsCorrectedByEccDelayed ++ ch <- metricReadTotalUncorrectedErrors ++ ch <- metricWriteErrorsCorrectedByRereadsRewrites ++ ch <- metricWriteErrorsCorrectedByEccFast ++ ch <- metricWriteErrorsCorrectedByEccDelayed ++ ch <- metricWriteTotalUncorrectedErrors + } + + // Collect is called by the Prometheus registry when collecting metrics. diff --git a/overlays/smartctl-exporter/default.nix b/overlays/smartctl-exporter/default.nix new file mode 100644 index 00000000..3eb42568 --- /dev/null +++ b/overlays/smartctl-exporter/default.nix @@ -0,0 +1,15 @@ +# smartctl_exporter 0.14.0 derives `Describe()` from the devices it can read at +# startup, so when a device only becomes readable later (an NVMe whose ACL +# arrives late, or an HDD waking from standby) `Collect()` emits metrics whose +# descriptors were never registered and `/metrics` starts returning HTTP 500, +# which fails the whole scrape and hides even the healthy disks. +# +# Backport of upstream PR #329: `Describe()` now sends the full, explicit +# descriptor set. Drop this overlay once smartctl_exporter 0.15.0 is released +# and packaged in nixpkgs: +# https://github.com/prometheus-community/smartctl_exporter/pull/329 +_: _final: prev: { + prometheus-smartctl-exporter = prev.prometheus-smartctl-exporter.overrideAttrs (prevAttrs: { + patches = (prevAttrs.patches or [ ]) ++ [ ./329-explicit-descriptors.patch ]; + }); +} From 0a847c1f5576338c34de0bdc04fbcfd85ddf6a55 Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sat, 3 Oct 2026 12:53:30 +0800 Subject: [PATCH 2/6] refactor(overlays): pin smartctl_exporter to the upstream #329 commit Replace the backported patch with a src/version/vendorHash override that pins prometheus-smartctl-exporter to upstream 6274decc (2026-09-28), which already carries the Describe() fix from PR #329. Simpler to maintain than a patch file and it tracks the upstream change directly; drop the overlay once smartctl_exporter 0.15.0 is packaged in nixpkgs. --- overlays/README.md | 7 ++- .../329-explicit-descriptors.patch | 50 ------------------- overlays/smartctl-exporter/default.nix | 22 +++++--- 3 files changed, 18 insertions(+), 61 deletions(-) delete mode 100644 overlays/smartctl-exporter/329-explicit-descriptors.patch diff --git a/overlays/README.md b/overlays/README.md index 1b87f9d3..bd784dae 100644 --- a/overlays/README.md +++ b/overlays/README.md @@ -13,9 +13,8 @@ overlays/ ├── default.nix # Entrypoint for all overlays ├── computer-use-linux.nix # trycua/computer-use-linux package ├── cua-driver.nix # trycua/cua driver (cua-driver) package -├── smartctl-exporter/ # smartctl_exporter backport (upstream PR #329) -│ ├── default.nix -│ └── 329-explicit-descriptors.patch +├── smartctl-exporter/ # smartctl_exporter pinned to the #329 fix +│ └── default.nix └── fcitx5/ # Chinese input method configuration ├── README.md ├── default.nix # fcitx5 overlay definition @@ -58,6 +57,6 @@ This overlay provides: - `computer-use-linux.nix`: packages `pkgs/computer-use-linux`. - `cua-driver.nix`: packages `pkgs/cua-driver` (used by the computer-use VMs). -- `smartctl-exporter/`: patches `prometheus-smartctl-exporter` with upstream PR +- `smartctl-exporter/`: pins `prometheus-smartctl-exporter` to the upstream commit carrying PR [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) until smartctl_exporter 0.15.0 is released; see `overlays/smartctl-exporter/default.nix`. diff --git a/overlays/smartctl-exporter/329-explicit-descriptors.patch b/overlays/smartctl-exporter/329-explicit-descriptors.patch deleted file mode 100644 index 6fdeb6c8..00000000 --- a/overlays/smartctl-exporter/329-explicit-descriptors.patch +++ /dev/null @@ -1,50 +0,0 @@ -diff --git a/main.go b/main.go -index c5b138a..05a222e 100644 ---- a/main.go -+++ b/main.go -@@ -57,7 +57,44 @@ type SMARTctlManagerCollector struct { - - // Describe sends the super-set of all possible descriptors of metrics - func (i *SMARTctlManagerCollector) Describe(ch chan<- *prometheus.Desc) { -- prometheus.DescribeByCollect(i, ch) -+ ch <- metricSmartctlVersion -+ ch <- metricDeviceModel -+ ch <- metricDeviceCount -+ ch <- metricDeviceCapacityBlocks -+ ch <- metricDeviceCapacityBytes -+ ch <- metricDeviceTotalCapacityBytes -+ ch <- metricDeviceBlockSize -+ ch <- metricDeviceInterfaceSpeed -+ ch <- metricDeviceAttribute -+ ch <- metricDevicePowerOnSeconds -+ ch <- metricDeviceRotationRate -+ ch <- metricDeviceTemperature -+ ch <- metricDevicePowerCycleCount -+ ch <- metricDevicePercentageUsed -+ ch <- metricDeviceAvailableSpare -+ ch <- metricDeviceAvailableSpareThreshold -+ ch <- metricDeviceCriticalWarning -+ ch <- metricDeviceMediaErrors -+ ch <- metricDeviceNumErrLogEntries -+ ch <- metricDeviceBytesRead -+ ch <- metricDeviceBytesWritten -+ ch <- metricDeviceSmartStatus -+ ch <- metricDeviceExitStatus -+ ch <- metricDeviceState -+ ch <- metricDeviceStatistics -+ ch <- metricDeviceErrorLogCount -+ ch <- metricDeviceSelfTestLogCount -+ ch <- metricDeviceSelfTestLogErrorCount -+ ch <- metricDeviceERCSeconds -+ ch <- metricSCSIGrownDefectList -+ ch <- metricReadErrorsCorrectedByRereadsRewrites -+ ch <- metricReadErrorsCorrectedByEccFast -+ ch <- metricReadErrorsCorrectedByEccDelayed -+ ch <- metricReadTotalUncorrectedErrors -+ ch <- metricWriteErrorsCorrectedByRereadsRewrites -+ ch <- metricWriteErrorsCorrectedByEccFast -+ ch <- metricWriteErrorsCorrectedByEccDelayed -+ ch <- metricWriteTotalUncorrectedErrors - } - - // Collect is called by the Prometheus registry when collecting metrics. diff --git a/overlays/smartctl-exporter/default.nix b/overlays/smartctl-exporter/default.nix index 3eb42568..c9143520 100644 --- a/overlays/smartctl-exporter/default.nix +++ b/overlays/smartctl-exporter/default.nix @@ -1,15 +1,23 @@ # smartctl_exporter 0.14.0 derives `Describe()` from the devices it can read at # startup, so when a device only becomes readable later (an NVMe whose ACL # arrives late, or an HDD waking from standby) `Collect()` emits metrics whose -# descriptors were never registered and `/metrics` starts returning HTTP 500, -# which fails the whole scrape and hides even the healthy disks. +# descriptors were never registered and `/metrics` returns HTTP 500, failing the +# whole scrape and hiding even the healthy disks. # -# Backport of upstream PR #329: `Describe()` now sends the full, explicit -# descriptor set. Drop this overlay once smartctl_exporter 0.15.0 is released -# and packaged in nixpkgs: +# Pin the package to the upstream commit that carries the fix (PR #329, merged +# 2026-09-28, then included in the "Update Go (#391)" commit below) instead of +# backporting it as a patch. Drop this overlay once smartctl_exporter 0.15.0 is +# released and packaged in nixpkgs: # https://github.com/prometheus-community/smartctl_exporter/pull/329 _: _final: prev: { - prometheus-smartctl-exporter = prev.prometheus-smartctl-exporter.overrideAttrs (prevAttrs: { - patches = (prevAttrs.patches or [ ]) ++ [ ./329-explicit-descriptors.patch ]; + prometheus-smartctl-exporter = prev.prometheus-smartctl-exporter.overrideAttrs (_prev: { + version = "0.14.0-unstable-2026-09-28"; + src = prev.fetchFromGitHub { + owner = "prometheus-community"; + repo = "smartctl_exporter"; + rev = "6274decc61212cc61e58796cc3b8cf5cfa035809"; + hash = "sha256-KR+j4uLqxVtRpQ7L8UxOypOHZG9CxUGw0ELIO7e6tXc="; + }; + vendorHash = "sha256-PJiMYWdoQ3Zk7sYHveG9uIgOjllgPuu6RjAPVdKUi6Y="; }); } From e975f69383b44acfa1f06e660e77ffcad85535f3 Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sat, 3 Oct 2026 12:53:30 +0800 Subject: [PATCH 3/6] docs: add a workaround registry with removal conditions WORKAROUNDS.md collects temporary workarounds, version pins, carried patches, and known gaps, each with a removal condition, so they can be re-evaluated and rolled back on a schedule. AGENTS.md points to it and states the convention: a change that adds a workaround adds a row in the same PR. --- AGENTS.md | 7 +++++++ WORKAROUNDS.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 WORKAROUNDS.md diff --git a/AGENTS.md b/AGENTS.md index f27f310d..65022aa6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,6 +59,12 @@ deployments. Keep repository guidance here; reusable global rules live in `agent - Use `lib.mkDefault` for defaults and `lib.mkForce` only when necessary. - Give module options a `description` and preserve platform-specific conditions. +## Workarounds + +Temporary workarounds, version pins, carried patches, and known gaps are recorded in +[WORKAROUNDS.md](./WORKAROUNDS.md), each with a removal condition. Add a row in the same change that +introduces one, and re-evaluate entries when their `Revisit` trigger comes up. + ## Command Hazards - `just eval-host `, `just build-host `, `just build-microvm `, and `just test` @@ -120,6 +126,7 @@ repository, and cross-link them — no need to be told. ## Further Context - [Repository overview](./README.md) +- [Workarounds & known gaps](./WORKAROUNDS.md) - [Outputs and tests](./outputs/README.md) - [Hosts](./hosts/README.md), [system modules](./modules/README.md), and [Home Manager](./home/README.md) diff --git a/WORKAROUNDS.md b/WORKAROUNDS.md new file mode 100644 index 00000000..c93a84c8 --- /dev/null +++ b/WORKAROUNDS.md @@ -0,0 +1,49 @@ +# Workarounds & known gaps + +Temporary workarounds, version pins, carried patches, and known gaps are collected here, each with +the condition under which it can be removed. Review the list periodically so obsolete workarounds +get rolled back instead of lingering. + +## How to use + +- **Adding** — a change that introduces a workaround, pin, carried patch, or known gap adds a row + here in the same PR, with a concrete **removal condition**. +- **Removing** — once the removal condition is met, delete the change and set `Status` to `removed` + (mention the ID in the commit), or delete the row. +- **Reviewing** — re-evaluate rows whose `Revisit` trigger is due and refresh `Status`. + +## Types + +| Type | Meaning | +| ------------- | --------------------------------------------------------------------------- | +| `patch` | Upstream code carried locally (an overlay, a patch file, or a fork branch). | +| `pin` | A version or revision pinned for a reason that can go away. | +| `workaround` | A setting that works around a bug or a hardware quirk. | +| `known-issue` | A known limitation with no fix yet. | +| `wip` | An unfinished feature or gap. | + +## Registry + +| ID | Type | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------- | ------ | +| WA-001 | `pin` | smartctl_exporter pinned to upstream `6274decc`, which carries PR [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) — `overlays/smartctl-exporter/` | `/metrics` returns HTTP 500 once a device becomes readable after startup ([#305](https://github.com/prometheus-community/smartctl_exporter/issues/305), [#326](https://github.com/prometheus-community/smartctl_exporter/issues/326)) | Drop once smartctl_exporter **0.15.0** is released and packaged in nixpkgs | 2026-10-03 | next nixpkgs bump | active | +| WA-002 | `pin` | `nixpkgs-2505` — `flake.nix`, consumer `home/base/tui/container.nix` | `kubernetes-helm` regressed in newer nixpkgs | Drop the input and its consumer once helm works again in current nixpkgs | 2025-12-03 | when helm is revisited | active | +| WA-003 | `pin` | `rust-overlay` follow — `flake.nix` | lanzaboote v1.1.0's pinned rust-overlay uses the deprecated `stdenv.isLinux`/`stdenv.isDarwin` | Drop the follow once lanzaboote updates its pin (or we drop the lanzaboote pin) | 2026-09-25 | on lanzaboote bump | active | +| WA-004 | `pin` | `catppuccin` on `main` — `flake.nix` | `main` carries the nodejs→nodejs-slim deprecation fix, which is not in a release | Switch to a release tag once it includes the fix | 2026-09-25 | on catppuccin release | active | +| WA-005 | `pin` | `tuios` input — `flake.nix`, `home/base/tui/tuios/` | nixpkgs lags behind upstream | Use nixpkgs' `tuios` once it is recent enough | 2026-10-03 | on nixpkgs bump | active | +| WA-006 | `pin` | `nixpkgs-blender` — `flake.nix` | Blender 5.2 LTS + CUDA/OptiX pin; keeps `just up` from triggering a full source rebuild | Bump deliberately when needed; drop the pin if the current nixpkgs build is acceptable | 2026-07-24 | deliberate | active | +| WA-007 | `pin` | WeChat from `nixpkgs-master` — `hardening/bwraps/default.nix` | newest builds; the pinned channel lags | Fall back to the stable channel once it has a good build | 2026-10-03 | on nixpkgs bump | active | +| WA-008 | `workaround` | Relaxed NVMe APST (`nvme_core.default_ps_max_latency_us=100000`) — `hosts/idols-ai/hardware-configuration.nix` | the KINGBANK KP260 (DRAM-less QLC) froze on slow APST wake-ups | Keep relaxed while kernel logs stay clean; restore `nvme_core.default_ps_max_latency_us=0 nvme_core.io_timeout=4294967295 pcie_aspm=off` if freezes return | 2026-10-03 | watch NVMe timeout/reset/AER in the journal | active | +| WA-009 | `workaround` | USB-SATA bridge mitigations (`usbcore.autosuspend=-1`, `usb-storage.delay_use=10`) — `hosts/12kingdoms-youko/default.nix` | flaky JMicron JMS567 resets with UDMA-CRC and I/O errors | Drop once the bridge/controller is replaced; the signal is smartctl CRC/media errors | 2026-09-21 | on hardware change or CRC errors | active | +| WA-010 | `workaround` | Insta360 Link USB reset on S3 resume — `hosts/idols-ai/default.nix` | the camera stays enumerated with a stalled UVC endpoint after resume | Drop after the Insta360 firmware or the kernel `uvcvideo` fixes it | 2026-08-01 | on kernel or firmware change | active | +| WA-011 | `workaround` | Kernel module blacklist (`esp4`, `esp6`, `rxrpc`) — `modules/nixos/base/kernel-hardening.nix` | attack surface for the Dirty Frag LPE (CVE-2026-43284 / CVE-2026-43500) | Kept as defence in depth; drop only if something needs those modules | 2026-10-03 | rarely | active | +| WA-012 | `known-issue` | Apple Silicon 16k page size — `hosts/12kingdoms-shoukei/apple-silicon.nix` | some x86_64 apps and games need `muvm`, which is currently disabled | Hardware limitation; revisit when Asahi or muvm support changes | — | on Asahi changes | active | +| WA-013 | `wip` | NixOS tests — `outputs/README.md` | tests rebuild custom packages (no private cache) and hosts need their own ssh host key to decrypt agenix | Resolve when a private cache exists and tests can run per-service | 2024-03-13 | quarterly | active | + +## Related + +- Unmerged **nixpkgs** PRs are carried via the `nixpkgs-patched` input and the + [`.agents/skills/nixpkgs-patched`](./.agents/skills/nixpkgs-patched/SKILL.md) workflow (that input + currently carries nothing; the `patch` rows above are per-package overlays instead). +- Routine version pins (colmena, agenix, disko, lanzaboote, haumea, home-manager, `nixpkgs-stable`, + `nixpkgs-darwin`, …) are the versions in use, not workarounds, so they are not listed here. From 39d351ade2e074951f7d371a59a244f05220e009 Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sat, 3 Oct 2026 12:56:31 +0800 Subject: [PATCH 4/6] docs: group the workaround registry by type Split the single table into Pins / Workarounds / Known issues / WIP sections so the registry is readable by section instead of scanning a Type column. --- WORKAROUNDS.md | 71 +++++++++++++++++++++++++++++--------------------- 1 file changed, 42 insertions(+), 29 deletions(-) diff --git a/WORKAROUNDS.md b/WORKAROUNDS.md index c93a84c8..7c8a6931 100644 --- a/WORKAROUNDS.md +++ b/WORKAROUNDS.md @@ -1,49 +1,62 @@ # Workarounds & known gaps -Temporary workarounds, version pins, carried patches, and known gaps are collected here, each with -the condition under which it can be removed. Review the list periodically so obsolete workarounds -get rolled back instead of lingering. +Temporary workarounds, version pins, carried patches, and known gaps are collected here, grouped by +type, each with the condition under which it can be removed. Review the list periodically so +obsolete workarounds get rolled back instead of lingering. ## How to use - **Adding** — a change that introduces a workaround, pin, carried patch, or known gap adds a row - here in the same PR, with a concrete **removal condition**. + under the matching section below in the same PR, with a concrete **removal condition**. - **Removing** — once the removal condition is met, delete the change and set `Status` to `removed` (mention the ID in the commit), or delete the row. - **Reviewing** — re-evaluate rows whose `Revisit` trigger is due and refresh `Status`. -## Types +## Pins -| Type | Meaning | -| ------------- | --------------------------------------------------------------------------- | -| `patch` | Upstream code carried locally (an overlay, a patch file, or a fork branch). | -| `pin` | A version or revision pinned for a reason that can go away. | -| `workaround` | A setting that works around a bug or a hardware quirk. | -| `known-issue` | A known limitation with no fix yet. | -| `wip` | An unfinished feature or gap. | +A version or revision pinned for a reason that can go away. -## Registry +| ID | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------- | ---------------------- | ------ | +| WA-001 | smartctl_exporter pinned to upstream `6274decc`, which carries PR [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) — `overlays/smartctl-exporter/` | `/metrics` returns HTTP 500 once a device becomes readable after startup ([#305](https://github.com/prometheus-community/smartctl_exporter/issues/305), [#326](https://github.com/prometheus-community/smartctl_exporter/issues/326)) | Drop once smartctl_exporter **0.15.0** is released and packaged in nixpkgs | 2026-10-03 | next nixpkgs bump | active | +| WA-002 | `nixpkgs-2505` — `flake.nix`; consumer `home/base/tui/container.nix` | `kubernetes-helm` regressed in newer nixpkgs | Drop the input and its consumer once helm works again in current nixpkgs | 2025-12-03 | when helm is revisited | active | +| WA-003 | `rust-overlay` follow — `flake.nix` | lanzaboote v1.1.0's pinned rust-overlay uses the deprecated `stdenv.isLinux`/`stdenv.isDarwin` | Drop the follow once lanzaboote updates its pin (or we drop the lanzaboote pin) | 2026-09-25 | on lanzaboote bump | active | +| WA-004 | `catppuccin` on `main` — `flake.nix` | `main` carries the nodejs→nodejs-slim deprecation fix, which is not in a release | Switch to a release tag once it includes the fix | 2026-09-25 | on catppuccin release | active | +| WA-005 | `tuios` input — `flake.nix`; `home/base/tui/tuios/` | nixpkgs lags behind upstream | Use nixpkgs' `tuios` once it is recent enough | 2026-10-03 | on nixpkgs bump | active | +| WA-006 | `nixpkgs-blender` — `flake.nix` | Blender 5.2 LTS + CUDA/OptiX pin; keeps `just up` from triggering a full source rebuild | Bump deliberately when needed; drop the pin if the current nixpkgs build is acceptable | 2026-07-24 | deliberate | active | +| WA-007 | WeChat from `nixpkgs-master` — `hardening/bwraps/default.nix` | newest builds; the pinned channel lags | Fall back to the stable channel once it has a good build | 2026-10-03 | on nixpkgs bump | active | -| ID | Type | What & where | Why | Removal condition | Added | Revisit | Status | -| ------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------- | ------ | -| WA-001 | `pin` | smartctl_exporter pinned to upstream `6274decc`, which carries PR [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) — `overlays/smartctl-exporter/` | `/metrics` returns HTTP 500 once a device becomes readable after startup ([#305](https://github.com/prometheus-community/smartctl_exporter/issues/305), [#326](https://github.com/prometheus-community/smartctl_exporter/issues/326)) | Drop once smartctl_exporter **0.15.0** is released and packaged in nixpkgs | 2026-10-03 | next nixpkgs bump | active | -| WA-002 | `pin` | `nixpkgs-2505` — `flake.nix`, consumer `home/base/tui/container.nix` | `kubernetes-helm` regressed in newer nixpkgs | Drop the input and its consumer once helm works again in current nixpkgs | 2025-12-03 | when helm is revisited | active | -| WA-003 | `pin` | `rust-overlay` follow — `flake.nix` | lanzaboote v1.1.0's pinned rust-overlay uses the deprecated `stdenv.isLinux`/`stdenv.isDarwin` | Drop the follow once lanzaboote updates its pin (or we drop the lanzaboote pin) | 2026-09-25 | on lanzaboote bump | active | -| WA-004 | `pin` | `catppuccin` on `main` — `flake.nix` | `main` carries the nodejs→nodejs-slim deprecation fix, which is not in a release | Switch to a release tag once it includes the fix | 2026-09-25 | on catppuccin release | active | -| WA-005 | `pin` | `tuios` input — `flake.nix`, `home/base/tui/tuios/` | nixpkgs lags behind upstream | Use nixpkgs' `tuios` once it is recent enough | 2026-10-03 | on nixpkgs bump | active | -| WA-006 | `pin` | `nixpkgs-blender` — `flake.nix` | Blender 5.2 LTS + CUDA/OptiX pin; keeps `just up` from triggering a full source rebuild | Bump deliberately when needed; drop the pin if the current nixpkgs build is acceptable | 2026-07-24 | deliberate | active | -| WA-007 | `pin` | WeChat from `nixpkgs-master` — `hardening/bwraps/default.nix` | newest builds; the pinned channel lags | Fall back to the stable channel once it has a good build | 2026-10-03 | on nixpkgs bump | active | -| WA-008 | `workaround` | Relaxed NVMe APST (`nvme_core.default_ps_max_latency_us=100000`) — `hosts/idols-ai/hardware-configuration.nix` | the KINGBANK KP260 (DRAM-less QLC) froze on slow APST wake-ups | Keep relaxed while kernel logs stay clean; restore `nvme_core.default_ps_max_latency_us=0 nvme_core.io_timeout=4294967295 pcie_aspm=off` if freezes return | 2026-10-03 | watch NVMe timeout/reset/AER in the journal | active | -| WA-009 | `workaround` | USB-SATA bridge mitigations (`usbcore.autosuspend=-1`, `usb-storage.delay_use=10`) — `hosts/12kingdoms-youko/default.nix` | flaky JMicron JMS567 resets with UDMA-CRC and I/O errors | Drop once the bridge/controller is replaced; the signal is smartctl CRC/media errors | 2026-09-21 | on hardware change or CRC errors | active | -| WA-010 | `workaround` | Insta360 Link USB reset on S3 resume — `hosts/idols-ai/default.nix` | the camera stays enumerated with a stalled UVC endpoint after resume | Drop after the Insta360 firmware or the kernel `uvcvideo` fixes it | 2026-08-01 | on kernel or firmware change | active | -| WA-011 | `workaround` | Kernel module blacklist (`esp4`, `esp6`, `rxrpc`) — `modules/nixos/base/kernel-hardening.nix` | attack surface for the Dirty Frag LPE (CVE-2026-43284 / CVE-2026-43500) | Kept as defence in depth; drop only if something needs those modules | 2026-10-03 | rarely | active | -| WA-012 | `known-issue` | Apple Silicon 16k page size — `hosts/12kingdoms-shoukei/apple-silicon.nix` | some x86_64 apps and games need `muvm`, which is currently disabled | Hardware limitation; revisit when Asahi or muvm support changes | — | on Asahi changes | active | -| WA-013 | `wip` | NixOS tests — `outputs/README.md` | tests rebuild custom packages (no private cache) and hosts need their own ssh host key to decrypt agenix | Resolve when a private cache exists and tests can run per-service | 2024-03-13 | quarterly | active | +## Workarounds + +A setting that works around a bug or a hardware quirk. + +| ID | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------- | ------ | +| WA-008 | Relaxed NVMe APST (`nvme_core.default_ps_max_latency_us=100000`) — `hosts/idols-ai/hardware-configuration.nix` | the KINGBANK KP260 (DRAM-less QLC) froze on slow APST wake-ups | Keep relaxed while kernel logs stay clean; restore `nvme_core.default_ps_max_latency_us=0 nvme_core.io_timeout=4294967295 pcie_aspm=off` if freezes return | 2026-10-03 | watch NVMe timeout/reset/AER in the journal | active | +| WA-009 | USB-SATA bridge mitigations (`usbcore.autosuspend=-1`, `usb-storage.delay_use=10`) — `hosts/12kingdoms-youko/default.nix` | flaky JMicron JMS567 resets with UDMA-CRC and I/O errors | Drop once the bridge/controller is replaced; the signal is smartctl CRC/media errors | 2026-09-21 | on hardware change or CRC errors | active | +| WA-010 | Insta360 Link USB reset on S3 resume — `hosts/idols-ai/default.nix` | the camera stays enumerated with a stalled UVC endpoint after resume | Drop after the Insta360 firmware or the kernel `uvcvideo` fixes it | 2026-08-01 | on kernel or firmware change | active | +| WA-011 | Kernel module blacklist (`esp4`, `esp6`, `rxrpc`) — `modules/nixos/base/kernel-hardening.nix` | attack surface for the Dirty Frag LPE (CVE-2026-43284 / CVE-2026-43500) | Kept as defence in depth; drop only if something needs those modules | 2026-10-03 | rarely | active | + +## Known issues + +A known limitation with no fix yet. + +| ID | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- | ----- | ---------------- | ------ | +| WA-012 | Apple Silicon 16k page size — `hosts/12kingdoms-shoukei/apple-silicon.nix` | some x86_64 apps and games need `muvm`, which is currently disabled | Hardware limitation; revisit when Asahi or muvm support changes | — | on Asahi changes | active | + +## WIP + +An unfinished feature or gap. + +| ID | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------- | --------- | ------ | +| WA-013 | NixOS tests — `outputs/README.md` | tests rebuild custom packages (no private cache) and hosts need their own ssh host key to decrypt agenix | Resolve when a private cache exists and tests can run per-service | 2024-03-13 | quarterly | active | ## Related - Unmerged **nixpkgs** PRs are carried via the `nixpkgs-patched` input and the [`.agents/skills/nixpkgs-patched`](./.agents/skills/nixpkgs-patched/SKILL.md) workflow (that input - currently carries nothing; the `patch` rows above are per-package overlays instead). + currently carries nothing; package-level carries are recorded under `Pins`). - Routine version pins (colmena, agenix, disko, lanzaboote, haumea, home-manager, `nixpkgs-stable`, `nixpkgs-darwin`, …) are the versions in use, not workarounds, so they are not listed here. From 7fe63a47198bdfc3eb255b6afa30b670d2827c91 Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sat, 3 Oct 2026 12:59:45 +0800 Subject: [PATCH 5/6] docs: fix the muvm workaround entry reasoning muvm is disabled because it does not build/run on nixos-apple-silicon yet, not because of a permanent hardware limitation; the 16k page size is the reason it is wanted, and the removal condition is muvm building and working. --- WORKAROUNDS.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/WORKAROUNDS.md b/WORKAROUNDS.md index 7c8a6931..939783e9 100644 --- a/WORKAROUNDS.md +++ b/WORKAROUNDS.md @@ -41,9 +41,9 @@ A setting that works around a bug or a hardware quirk. A known limitation with no fix yet. -| ID | What & where | Why | Removal condition | Added | Revisit | Status | -| ------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------- | ----- | ---------------- | ------ | -| WA-012 | Apple Silicon 16k page size — `hosts/12kingdoms-shoukei/apple-silicon.nix` | some x86_64 apps and games need `muvm`, which is currently disabled | Hardware limitation; revisit when Asahi or muvm support changes | — | on Asahi changes | active | +| ID | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----- | -------------------------------------- | ------ | +| WA-012 | `muvm` (x86_64 apps/games via microVM) disabled — `hosts/12kingdoms-shoukei/apple-silicon.nix` | Apple Silicon's 16k page size means x86_64 apps need `muvm`; it is off because it does not build/run on nixos-apple-silicon yet ([nixos-apple-silicon#237](https://github.com/nix-community/nixos-apple-silicon/issues/237)) | Re-enable once `muvm` builds and works | — | on nixos-apple-silicon or muvm updates | active | ## WIP From 0a8fb5cf01112b5744e0b99d5f570f4219cff77e Mon Sep 17 00:00:00 2001 From: Ryan Yin Date: Sat, 3 Oct 2026 13:12:31 +0800 Subject: [PATCH 6/6] docs(workarounds): clarify removal and recovery conditions --- WORKAROUNDS.md | 18 +++++++++++------- overlays/README.md | 4 ++-- overlays/smartctl-exporter/default.nix | 4 ++-- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/WORKAROUNDS.md b/WORKAROUNDS.md index 939783e9..00fbe6dd 100644 --- a/WORKAROUNDS.md +++ b/WORKAROUNDS.md @@ -18,7 +18,7 @@ A version or revision pinned for a reason that can go away. | ID | What & where | Why | Removal condition | Added | Revisit | Status | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------- | ---------------------- | ------ | -| WA-001 | smartctl_exporter pinned to upstream `6274decc`, which carries PR [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) — `overlays/smartctl-exporter/` | `/metrics` returns HTTP 500 once a device becomes readable after startup ([#305](https://github.com/prometheus-community/smartctl_exporter/issues/305), [#326](https://github.com/prometheus-community/smartctl_exporter/issues/326)) | Drop once smartctl_exporter **0.15.0** is released and packaged in nixpkgs | 2026-10-03 | next nixpkgs bump | active | +| WA-001 | smartctl_exporter pinned to upstream `6274decc`, which carries PR [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) — `overlays/smartctl-exporter/` | `/metrics` returns HTTP 500 once a device becomes readable after startup ([#305](https://github.com/prometheus-community/smartctl_exporter/issues/305), [#326](https://github.com/prometheus-community/smartctl_exporter/issues/326)) | Drop once nixpkgs provides a version containing the #329 fix | 2026-10-03 | next nixpkgs bump | active | | WA-002 | `nixpkgs-2505` — `flake.nix`; consumer `home/base/tui/container.nix` | `kubernetes-helm` regressed in newer nixpkgs | Drop the input and its consumer once helm works again in current nixpkgs | 2025-12-03 | when helm is revisited | active | | WA-003 | `rust-overlay` follow — `flake.nix` | lanzaboote v1.1.0's pinned rust-overlay uses the deprecated `stdenv.isLinux`/`stdenv.isDarwin` | Drop the follow once lanzaboote updates its pin (or we drop the lanzaboote pin) | 2026-09-25 | on lanzaboote bump | active | | WA-004 | `catppuccin` on `main` — `flake.nix` | `main` carries the nodejs→nodejs-slim deprecation fix, which is not in a release | Switch to a release tag once it includes the fix | 2026-09-25 | on catppuccin release | active | @@ -30,12 +30,16 @@ A version or revision pinned for a reason that can go away. A setting that works around a bug or a hardware quirk. -| ID | What & where | Why | Removal condition | Added | Revisit | Status | -| ------ | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------- | ------ | -| WA-008 | Relaxed NVMe APST (`nvme_core.default_ps_max_latency_us=100000`) — `hosts/idols-ai/hardware-configuration.nix` | the KINGBANK KP260 (DRAM-less QLC) froze on slow APST wake-ups | Keep relaxed while kernel logs stay clean; restore `nvme_core.default_ps_max_latency_us=0 nvme_core.io_timeout=4294967295 pcie_aspm=off` if freezes return | 2026-10-03 | watch NVMe timeout/reset/AER in the journal | active | -| WA-009 | USB-SATA bridge mitigations (`usbcore.autosuspend=-1`, `usb-storage.delay_use=10`) — `hosts/12kingdoms-youko/default.nix` | flaky JMicron JMS567 resets with UDMA-CRC and I/O errors | Drop once the bridge/controller is replaced; the signal is smartctl CRC/media errors | 2026-09-21 | on hardware change or CRC errors | active | -| WA-010 | Insta360 Link USB reset on S3 resume — `hosts/idols-ai/default.nix` | the camera stays enumerated with a stalled UVC endpoint after resume | Drop after the Insta360 firmware or the kernel `uvcvideo` fixes it | 2026-08-01 | on kernel or firmware change | active | -| WA-011 | Kernel module blacklist (`esp4`, `esp6`, `rxrpc`) — `modules/nixos/base/kernel-hardening.nix` | attack surface for the Dirty Frag LPE (CVE-2026-43284 / CVE-2026-43500) | Kept as defence in depth; drop only if something needs those modules | 2026-10-03 | rarely | active | +| ID | What & where | Why | Removal condition | Added | Revisit | Status | +| ------ | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------- | ------ | +| WA-008 | Relaxed NVMe APST (`nvme_core.default_ps_max_latency_us=100000`) — `hosts/idols-ai/hardware-configuration.nix` | the KINGBANK KP260 (DRAM-less QLC) froze on slow APST wake-ups | Drop the override once kernel/firmware fixes or replacement hardware make default APST reliable | 2026-10-03 | watch NVMe timeout/reset/AER in the journal | active | +| WA-009 | USB-SATA bridge mitigations (`usbcore.autosuspend=-1`, `usb-storage.delay_use=10`) — `hosts/12kingdoms-youko/default.nix` | flaky JMicron JMS567 resets with UDMA-CRC and I/O errors | Drop once the bridge/controller is replaced; the signal is smartctl CRC/media errors | 2026-09-21 | on hardware change or CRC errors | active | +| WA-010 | Insta360 Link USB reset on S3 resume — `hosts/idols-ai/default.nix` | the camera stays enumerated with a stalled UVC endpoint after resume | Drop after the Insta360 firmware or the kernel `uvcvideo` fixes it | 2026-08-01 | on kernel or firmware change | active | +| WA-011 | Kernel module blacklist (`esp4`, `esp6`, `rxrpc`) — `modules/nixos/base/kernel-hardening.nix` | attack surface for the Dirty Frag LPE (CVE-2026-43284 / CVE-2026-43500) | Kept as defence in depth; drop only if something needs those modules | 2026-10-03 | rarely | active | + +If WA-008 freezes recur, the fallback is to restore +`nvme_core.default_ps_max_latency_us=0 nvme_core.io_timeout=4294967295 pcie_aspm=off`; this is a +recovery procedure, not its removal condition. ## Known issues diff --git a/overlays/README.md b/overlays/README.md index bd784dae..9e377807 100644 --- a/overlays/README.md +++ b/overlays/README.md @@ -58,5 +58,5 @@ This overlay provides: - `computer-use-linux.nix`: packages `pkgs/computer-use-linux`. - `cua-driver.nix`: packages `pkgs/cua-driver` (used by the computer-use VMs). - `smartctl-exporter/`: pins `prometheus-smartctl-exporter` to the upstream commit carrying PR - [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) until smartctl_exporter - 0.15.0 is released; see `overlays/smartctl-exporter/default.nix`. + [#329](https://github.com/prometheus-community/smartctl_exporter/pull/329) until nixpkgs provides + a version containing the fix; see `overlays/smartctl-exporter/default.nix`. diff --git a/overlays/smartctl-exporter/default.nix b/overlays/smartctl-exporter/default.nix index c9143520..697a9e65 100644 --- a/overlays/smartctl-exporter/default.nix +++ b/overlays/smartctl-exporter/default.nix @@ -6,8 +6,8 @@ # # Pin the package to the upstream commit that carries the fix (PR #329, merged # 2026-09-28, then included in the "Update Go (#391)" commit below) instead of -# backporting it as a patch. Drop this overlay once smartctl_exporter 0.15.0 is -# released and packaged in nixpkgs: +# backporting it as a patch. Drop this overlay once nixpkgs provides a version +# containing the #329 fix: # https://github.com/prometheus-community/smartctl_exporter/pull/329 _: _final: prev: { prometheus-smartctl-exporter = prev.prometheus-smartctl-exporter.overrideAttrs (_prev: {