batch: land #264, #256

.github/workflows/ci.yml

@@ -463,3 +463,23 @@ jobs:
           sudo tar -xzf kubeconform.tar.gz -C /usr/local/bin kubeconform
           sudo apt-get update && sudo apt-get install -y --no-install-recommends python3-yaml
       - run: tests/kserve_test.sh
+
+  # --- Freshness: known issues ---------------------------------------------------
+  # pins/known-issues.toml lists the upstream bugs, behaviour changes and advisories
+  # k3d-gpu depends on, each with the release that fixes it. Offline: fails when an
+  # "ours" pin is inside a fixed issue's affected range, when a workaround marker
+  # outlives its fix, or when markers and entries disagree. `hack/known-issues poll`
+  # (network) finds fixed-in releases; hack/ledger-freshness lists SUPPORTED ledger
+  # rows measured on versions older than today's pins.
+  known-issues:
+    name: Known issues (fixed-in rules, markers), version schemes, ledger re-measure queue
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - run: python3 tests/pinver_test.py
+      - run: python3 tests/known_issues_test.py
+      - run: python3 tests/ledger_freshness_test.py
+      - run: hack/known-issues check

console/audit.py

@@ -84,6 +84,7 @@ def endpoint(address, port):
     return "%s:%s" % (host, port if port is not None else "(port not set)")
 
 
+# known-issue: eat-9 (the rule is general; EAT#9 is the instance that motivated it)
 def check_listener(ls):
     subject = "%s %s" % (endpoint(ls["address"], ls["port"]), ls["name"])
     where = "loopback" if is_loopback(ls["address"]) else "off loopback"

console/model_opt.py

@@ -1104,6 +1104,7 @@ def spec_decide(doc, choose, engine, device, pick, drafters, target, facts, draf
         for d in fit:
             if d["drafter"] == "assistant":
                 if facts and facts["moe"]:
+                    # known-issue: vllm-pr-51493 (the VLLM_USE_V2_MODEL_RUNNER=1 clause goes once a release has the fix)
                     doc["notes"].append("MoE target: Google says the 26B A4B drafter may not speed up at batch 1 without good parallelism (https://ai.google.dev/gemma/docs/mtp/overview); "
                                         "if vLLM's V1 runner fails on it, VLLM_USE_V2_MODEL_RUNNER=1 (https://github.com/vllm-project/vllm/pull/51493); K3D_GPU_AGENT_DRAFT=off turns the drafter off")
                 cfg = {"method": "mtp", "model": d["id"], "num_speculative_tokens": 4}

docs/first-run.md

@@ -72,7 +72,7 @@ What differs on WSL2:
   agent does not request the WSL2 GPU yet. quickstart says so at step 1.
 - The NPU is not available under WSL2
   ([intel/linux-npu-driver#56](https://github.com/intel/linux-npu-driver/issues/56)),
-  so `recipe npu-embeddings` cannot run here.
+  so `recipe npu-embeddings` cannot run here. <!-- known-issue: linux-npu-driver-56 -->
 - WSL2 hides the P/E-core split; no P-core pinning applies.
 - The WSL2 VM gets half the Windows RAM by default. A 32 GB laptop shows about
   15.4 GiB and gets the 4B tier. Raise `memory=` in `%UserProfile%\.wslconfig`

docs/platforms.md

@@ -376,15 +376,20 @@ B70 runs land:
 - Expected collision: a second GPU plugin. `deploy-intel-gpu-plugin.yml` applies
   `deployments/gpu_plugin/base/intel-gpu-plugin.yaml` from intel-device-plugins `main`
   (`intel_gpu_plugin_ref` defaults to `main`, unpinned) beside the baked DaemonSet.
+  `eat-up.sh` therefore stops on `compute_platform=xpu` and points at
+  `K3D_GPU_AGENT_BACKEND=vllm`.
 - Expected collision: a second balloons policy. The reworked `nri_cpu_balloons` role
   renders one NUMA-sized `BalloonsPolicy` per node (`node.<name>`). #21 still installs
   it only on `deploy_nri_balloon_policy == "yes"` (`fresh-install.sh` line 247), so
-  `eat-up.sh`'s `off` keeps it away; a config that turns it on meets k3d-gpu's policy.
+  `eat-up.sh`'s `off` keeps it away, and `eat-up.sh` stops on any other value, an
+  absent key included (`prompt_for_input`, which the stack path and `brownfield.sh model`
+  both call, turns that on).
 - Expected gap: the `hostPath` libraries resolve inside the k3d node container, not
   on the host. The node image would have to carry compatible Level Zero and OpenCL
   user space at those paths, or the pod would mount empty or mismatched libraries.
 - Expected gap: Kata (`kata-fc`, `kata-qemu`) needs `/dev/kvm` and nested
   virtualization inside the k3d node, which k3d-gpu does not pass through today.
+  `eat-up.sh` stops on `deploy_kata_containers=on`.
 
 Gaps for the #20 example instance (`docs/examples/openclaw-instance.yaml`) on k3d-gpu:
 

docs/quickstart.md

@@ -152,7 +152,7 @@ the LLM server does not request it yet.
   ([Docker docs](https://docs.docker.com/desktop/features/gpu/)). The Intel
   path does not use that flag.
 - **The Intel NPU does not work under WSL2.** Intel's Linux NPU driver has no
-  WSL2 support ([intel/linux-npu-driver#56](https://github.com/intel/linux-npu-driver/issues/56)).
+  WSL2 support ([intel/linux-npu-driver#56](https://github.com/intel/linux-npu-driver/issues/56)). <!-- known-issue: linux-npu-driver-56 -->
 
 ## Remove everything
 

examples/kserve/install.sh

@@ -44,7 +44,9 @@ helm upgrade --install kserve-resources oci://ghcr.io/kserve/charts/kserve-resou
     --version "${KSERVE_VERSION}" --namespace kserve \
     --values "${HERE}/kserve-values.yaml" --wait --timeout 10m
 
+# known-issue-begin: kserve-4592
 kubectl apply --server-side -f "${HERE}/openvino-runtime.yaml"
+# known-issue-end: kserve-4592
 
 sed -e "s/supplementalGroups: \[\]/supplementalGroups: [${render_gid}]/" \
     -e "s|gpu.intel.com/i915:|gpu.intel.com/${driver}:|" "${HERE}/qwen3-isvc.yaml" \

examples/kserve/openvino-runtime.yaml

@@ -4,6 +4,7 @@
 # release charts, so it ships here. Changes from upstream: the Helm ownership
 # annotation and label are dropped (Helm does not install it here), and the
 # placeholder image openvino/model_server:replace is pinned to the GPU build.
+# known-issue: kserve-4592 (this file goes once a KServe release's runtimes chart ships kserve-openvino)
 apiVersion: serving.kserve.io/v1alpha1
 kind: ClusterServingRuntime
 metadata: