signalk-container 1.26.0 → 1.28.0

package/AGENTS.md

@@ -72,6 +72,17 @@ Rootless podman below 5.5.0 silently ignores `HostConfig.Ulimits` on the docker-
 - When the host outright REJECTS the ask at container start (crun/runc `setrlimit` — classified `ulimit-rejected` in `src/errors.ts`, checked before the `permission` patterns because the raw text contains "operation not permitted"), the `ensureRunning` create path retries ONCE without the nofile entry — only when the rejection text names nofile (`NOFILE_REJECTION_RE`) — so the container starts on the runtime's default limits, then emits the clamp advisory with `granted` = the observed live hard limit (0 when no source is readable, e.g. podman machine on macOS where the ceiling probe returns null and the ask went through unclamped). Never loop the retry — the nofile ask is dropped at most once. The fallback shares one retry loop with the optimistic-device fallback: a create can trip both, in either order, and every retry rebuilds from the union of ALL concessions so far (dropped device binds + `DEVICES_UNRESOLVED_LABEL` stamp + dropped nofile ask) — a retry rebuilt from the pristine config would re-introduce something the runtime already refused and fail the start that both fallbacks are intended to save.
 - The fallback container carries no nofile entry in its inspect echo, so the regrant reads `asked` from the live limit. Where neither source is readable (macOS) the regrant never fires; elsewhere it may attempt one recreate with the original ask, which fails the same way, re-enters the fallback, and is then bounded by `nofileRegrantAttempts` — do not add a separate attempt map for the fallback, and do not weaken that guard.
 
+### Platform recognition (HaLOS)
+
+`selfDeployment` reports `platform` (`HostPlatform | null`), detected from a platform-specific marker visible to the SK process (`detectPlatform` probe). Recognition only swaps the remediation **text** — it never changes `status`. When a recognised platform has a known, single fix for a failure mode, the doctor renders a platform-specific guide instead of the generic remediation; `remediationHalosDockerSocket` is the first such case (HaLOS + containerized + `permission-denied`), reading the socket's real GID via the `readSocketGid` probe.
+
+The concrete package paths, the compose-edit mechanics, and the exact paste block live in `remediationHalosDockerSocket` / `halosFixScript` in `src/doctor.ts` — that function is the single source of truth, so do not restate them here or in operator docs (they drift when HaLOS packaging changes). The invariants that constrain any such guide:
+
+- **The executable block must be safe to paste verbatim.** It derives the docker-socket GID itself at run time (`stat -c %g`) rather than baking a value in — so it works even when the `readSocketGid` probe returned null, and it never carries a `<placeholder>` that a verbatim paste would write literally into the compose. The probe value is used only for the human-readable prose; the block never depends on it.
+- **It must edit narrowly.** It rewrites `group_add` only when the compose has exactly one `group_add:` block **and that block belongs to the `signalk-server` service** — a sole `group_add` on a different service must be refused, never mis-edited (the `sed` targets the first block, so the guard has to prove that block is the right one). Any other shape (multiple blocks, none, missing file, unreadable socket) no-ops with a note.
+- **It must be idempotent** (operators re-run it after a platform update re-installs the file); the "already present" check is quoting-agnostic (`- 993` / `- "993"` / `- '993'`).
+- **A non-packaged deployment must fall through.** Bare-metal Signal K on a HaLOS host (not containerized) gets the generic remediation, not this guide.
+
 ### Podman SELinux flag
 
 `volumeArg(hostPath, containerPath, runtime)` adds `:Z` for podman bind mounts (Fedora/RHEL SELinux relabel). Named volumes — host strings without a leading `/` or `.` — MUST NOT receive `:Z`; podman rejects them with `"invalid option z for named volume"`. Always go through `volumeArg`, never build `-v host:container[:flags]` strings inline.
@@ -168,6 +179,12 @@ Discoverability — `selfDeployment().containerStorage` reports the filesystem b
 
 The diff has an optional `prior?: ContainerConfig` parameter for detecting "unset" drift (an env key previously set is now absent, a `command` previously set is now `undefined`). The wrapper in `src/index.ts` reads it from `lastConfigs` before overwriting.
 
+### Resource-limit precedence and CPU priority tiers
+
+The effective limits of a managed container are `tier ⊕ consumer resources ⊕ user override`, merged field-by-field with `null` = unset. `pluginDefaults` in `src/index.ts` is the single capture point of the bottom two layers (the plugin-wide `containerCpuPriority` tier with the consumer's `resources` on top) — `minimizeOverride`, `updateResources` and "Reset to plugin defaults" all read that map, so a new default-shaped input must be folded in there, not merged separately. Jobs get `jobCpuPriority ⊕ caller resources` in the API `runJob` wrapper.
+
+Tiers are `--cpu-shares` values from `CPU_PRIORITY_SHARES` (`src/configNormalize.ts`, browser-safe so the panel shares the table). `normal` is deliberately no request: unset is `cpu.weight` 100 on every runtime, whereas the shares → weight translation is the OCI runtime's and differs (crun and runc < 1.3.2: 1024 → 39; runc ≥ 1.3.2: 1024 → 100 — measured, see the README table), and `podman update --cpu-shares 0` is a no-op — hence `cpuShares` is in `FIELDS_THAT_CANNOT_LIVE_UNSET`, `getLiveResources` reports 1024 as a real value, and neither the panel nor the tests assume one formula (the integration test accepts either).
+
 ### Recursion guard in ensureRunning
 
 After auto-recreate, `ensureRunning` recursively re-enters itself with `_postRecreate=true`. The underscore prefix marks this as an internal-use-only parameter — do not document it for consumer plugins, do not move it earlier in the signature. The guard breaks the loop if state somehow stays `running` or `stopped` after the `remove`.

package/README.md

@@ -464,6 +464,7 @@ The plugin embeds a React config panel in the Signal K Admin UI (via Module Fede
 - **Keep N prior managed-image versions** -- on the prune schedule above, also remove superseded versions of images belonging to managed containers, keeping this many prior versions in addition to the running one (default `1`; `0` keeps only the running image). Only touches images of containers this plugin manages — never your other images (e.g. a hand-pulled questdb/grafana), the running image, or any image in use by a container. See [Image version cleanup](#image-version-cleanup).
 - **Update check interval** -- how often to check consumer plugins for new container images (1h to 1 week, default 24h)
 - **Background update checks** -- toggle for metered connections; manual checks still work when off
+- **CPU priority: containers / jobs** -- soft CPU weight every managed container (default `normal`) and every one-shot job (default `lowest`) gets when they compete for CPU. See [CPU priority](#cpu-priority).
 - **Disable user-namespace remap (ZFS escape hatch)** -- off by default. Secondary fix for ZFS / id-map-less hosts; prefer the host-side `fuse-overlayfs` storage driver first ([ZFS host notes](#zfs-and-other-idmap-incompatible-filesystems)). Enable only if container creation fails with `crun: writing file /proc/<pid>/gid_map: Invalid argument` and you cannot switch storage drivers. With the flag on, signalk-container stops emitting `--userns=keep-id` for rootless Podman; bind-mount file ownership still lands on the host caller for root-by-default images (questdb, grafana, mayara), but non-root images lose host-caller ownership in exchange for being able to start at all.
 
 ### Managed Containers (one card per running or stopped container)
@@ -480,9 +481,9 @@ The plugin embeds a React config panel in the Signal K Admin UI (via Module Fede
 
 ### Resource Limits Editor (expands inline when you click "Edit Limits" on a running container)
 
-- Four primary fields visible by default: CPU cores, Memory, Memory+swap, Max processes
-- **Advanced** section (collapsed) for CPU shares, CPU pinning, memory reservation, OOM score adjust
-- **× button** next to each field to explicitly unset (send `null`, removing a plugin-default limit)
+- Five primary fields visible by default: CPU cores, CPU priority (a tier, or a raw shares value), Memory, Memory+swap, Max processes
+- **Advanced** section (collapsed) for CPU pinning, memory reservation, OOM score adjust
+- **× button** next to each field to explicitly unset (send `null`, removing a plugin-default limit); the CPU priority select has none — Normal is the unset
 - **Apply** -- live update where possible, recreate where needed, with a clear result box showing which method was used and any warnings (e.g. "dropped cpusetCpus — not delegated by cgroups")
 - **Revert** -- discard unsaved form edits, re-seed from current effective state
 - **Reset to default** -- clear the user override entirely and restore the consumer plugin's pristine default limits (confirmation dialog warns about possible recreate)
@@ -505,7 +506,7 @@ Each consumer plugin (signalk-questdb, signalk-grafana, mayara, etc.) declares d
 1. Open the Signal K admin UI → Plugin Config → **Container Manager**
 2. Find the container you want to tune in the "Managed Containers" list
 3. Click **Edit Limits ▸** on the row
-4. Edit the CPU cores, Memory, Memory+swap, or Max processes fields. Use the × button next to a field to explicitly unset a limit the plugin set. Click **Advanced** to access cpuShares, cpusetCpus, memoryReservation, and oomScoreAdj.
+4. Edit the CPU cores, CPU priority, Memory, Memory+swap, or Max processes fields. Use the × button next to a field to explicitly unset a limit the plugin set. Click **Advanced** to access cpusetCpus, memoryReservation, and oomScoreAdj.
 5. Click **Apply** — live updated where possible (no downtime), recreated where needed. The result box shows which method was used plus any warnings.
 6. To restore the plugin's default: click **Reset to default** (amber button). This clears your override and applies the pristine default to the running container.
 
@@ -516,7 +517,7 @@ The form re-seeds from the server's fresh state after every Apply or Reset, so t
 | Field               | Example          | What it does                                                                                                                                                             |
 | ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `cpus`              | `1.5`            | Hard CPU cap. `1.5` = max 1.5 cores. The most important field for stability.                                                                                             |
-| `cpuShares`         | `512`            | Soft CPU weight under contention (default 1024). Lower = lower priority.                                                                                                 |
+| `cpuShares`         | `512`            | Soft CPU weight under contention (`--cpu-shares`). Unset = the runtime default (`cpu.weight` 100); the panel offers named tiers. See [CPU priority](#cpu-priority).      |
 | `cpusetCpus`        | `"1,2"`          | Pin to specific cores. Useful to keep heavy containers off core 0 where Signal K runs. May force a recreate on hosts where the cpuset cgroup controller isn't delegated. |
 | `memory`            | `"512m"`, `"2g"` | Hard memory cap. Container is OOM-killed if exceeded.                                                                                                                    |
 | `memorySwap`        | `"512m"`         | Memory + swap total. **Set equal to `memory` to disable swap entirely** — recommended on Pi/eMMC where swap is slow.                                                     |
@@ -600,6 +601,33 @@ curl http://localhost:3000/plugins/signalk-container/api/containers/mayara-serve
 
 Note that `override` contains only the fields that differ from the consumer plugin's default — this minimization is automatic and lets future plugin default bumps flow through without you having to re-edit your override.
 
+### CPU priority
+
+`cpus` is a hard cap; `cpuShares` is a _soft_ weight that only matters when containers actually compete for CPU. On an idle host it changes nothing; when a chart import saturates every core, it decides who gets the CPU. The plugin exposes it as named tiers:
+
+| Tier     | `cpuShares` | `cpu.weight` on crun, runc < 1.3.2 | `cpu.weight` on runc ≥ 1.3.2 | Default for        |
+| -------- | ----------- | ---------------------------------- | ---------------------------- | ------------------ |
+| `high`   | `5120`      | 196                                | 363                          |                    |
+| `normal` | _unset_     | 100                                | 100                          | managed containers |
+| `low`    | `512`       | 20                                 | 59                           |                    |
+| `lowest` | `128`       | 5                                  | 21                           | jobs (`runJob`)    |
+
+Two plugin-wide settings pick the default tier for managed containers and for jobs. A consumer plugin's own `resources.cpuShares` beats the tier, and a per-container override (panel or `containerOverrides`) beats both — the tier is simply the bottom layer of the same merge. To return one container to `normal`, pick Normal in the panel's limits editor (or `POST …/resources` with `{"cpuShares": null}`): that recreates the container, because neither runtime can un-set shares in place. A `cpuShares: null` written straight into `containerOverrides` is only picked up as far as a live update can go — the next consumer restart logs "cannot live-unset" and the container keeps its old weight until it is recreated.
+
+Two things worth knowing:
+
+- **`normal` means no request, not 1024.** The kernel schedules by cgroup v2 `cpu.weight`; the OCI runtime translates `--cpu-shares` into it, and the translation is the runtime's, not the kernel's: crun (Podman's default) and runc before 1.3.2 use a linear formula under which an explicit `1024` lands at weight 39 — _below_ an untouched container at 100 — while runc 1.3.2 and later use a quadratic one that maps 1024 to 100 (measured above on crun 1.21 and runc 1.4.3). Unset is 100 on every runtime and the tier order holds on every runtime; only the absolute numbers differ. Don't "reset" a container by typing 1024; use `normal` (the panel) or `null` (JSON).
+- **Weights rank cgroup siblings only.** Managed containers and jobs are siblings of each other, so the tiers rank them against one another. Signal K itself usually lives in a different cgroup branch, so ranking it _above_ the plugin containers is a systemd `CPUWeight=` at the right level, not a tier here:
+  - Universal installer (rootless Podman, Signal K as a Quadlet unit in `app.slice`, managed containers in `user.slice`): the installer writes `~/.config/systemd/user/app.slice.d/50-signalk-cpu-priority.conf` with `[Slice] CPUWeight=300`. A hand-rolled rootless setup with Signal K as a user service takes the same drop-in.
+  - Bare-metal Signal K as a system service with rootful Podman/Docker: `signalk.service` and the `docker-*.scope` / `libpod-*.scope` containers are siblings under `system.slice`, so `systemctl edit signalk.service` → `[Service] CPUWeight=300` does it.
+  - Signal K itself in Docker (compose): its container is a sibling of the managed ones under `system.slice`, so the tiers already rank against it; give the Signal K service `cpu_shares: 5120` to put it on top.
+
+  The host's own services in `system.slice` are untouched by any of this.
+
+Changing a tier _down_ (or between `high`/`low`/`lowest`) is applied live (`podman update` / `docker update`) to running containers on the next consumer-plugin restart. Moving a container _up_ to `normal` needs a recreate: neither runtime can un-set shares in place, so the restart only logs the mismatch — use the panel (Normal → Apply, or Reset to default) to recreate.
+
+If the host has not delegated the `cpu` cgroup controller, the tiers are stored but silently have no effect — the panel says so next to the selects, and the [doctor](#quick-check-apidoctordeployment) reports `cgroup-controllers-incomplete`.
+
 ### Picking the right values
 
 1. Run the container without overrides for a typical workload
@@ -709,7 +737,7 @@ services:
 
 You'll see "could not detect self container id" in the SignalK log when the cascade has failed; the override resolves it without code changes.
 
-For a full walkthrough of the in-container deployment (socket bind-mount, self-container-id override, reference quadlet, troubleshooting table) see **[doc/run-in-container.md](doc/run-in-container.md)**.
+For a full walkthrough of the in-container deployment (socket bind-mount, self-container-id override, reference quadlet, troubleshooting table) see **[doc/run-in-container.md](doc/run-in-container.md)**. On [HaLOS](https://github.com/halos-org/halos) the Doctor recognises the platform and renders a paste-once fix for the docker-socket permission it ships with — see [doc/run-in-container.md#halos](doc/run-in-container.md#halos).
 
 ## Connecting back to a container service (`signalkAccessiblePorts`)
 
@@ -912,6 +940,8 @@ All mounted at `/plugins/signalk-container/api/`:
 | Keep N prior managed-image versions | `1`      | On the prune schedule, also remove superseded versions of managed-container images, keeping this many prior versions besides the running one (`0` = running only). Never touches unregistered images, the running image, or in-use images. See [Image version cleanup](#image-version-cleanup). |
 | Max concurrent jobs                 | `2`      | Limit parallel one-shot job executions                                                                                                                                                                                                                                                          |
 | Update check interval               | `24h`    | How often to check for container image updates (e.g. `24h`, `12h`, `1h`). Min 1h.                                                                                                                                                                                                               |
+| CPU priority: containers            | `normal` | Soft CPU weight tier for every managed container unless the owning plugin or a per-container override sets `cpuShares`. See [CPU priority](#cpu-priority).                                                                                                                                      |
+| CPU priority: jobs                  | `lowest` | Soft CPU weight tier for one-shot job containers unless the caller sets `cpuShares`. See [CPU priority](#cpu-priority).                                                                                                                                                                         |
 | Background update checks            | `true`   | Periodically check for updates in the background. Disable on metered connections — manual checks via the UI button still work.                                                                                                                                                                  |
 | Disable user-namespace remap        | `false`  | Suppress rootless-Podman `--userns=keep-id` on filesystems that cannot be id-mapped (ZFS, some encrypted FS). Secondary escape hatch only — the recommended primary fix is host-side `fuse-overlayfs` storage (see [ZFS host notes](#zfs-and-other-idmap-incompatible-filesystems)).            |
 | Container overrides                 | `{}`     | Per-container resource limits (CPU, memory, PIDs). Field-level merged on top of consumer plugin defaults. See dev guide.                                                                                                                                                                        |

package/dist/configNormalize.d.ts

@@ -3,6 +3,7 @@
  * backend (`index.ts`) and the React config panel. Kept free of any
  * node-only imports so it can be bundled into the configpanel.
  */
+import type { ContainerResourceLimits, CpuPriority } from "./types.js";
 /**
  * Prior managed-image versions the reaper keeps by default, in addition
  * to the running one. Shared between the config schema's `default`, the
@@ -31,4 +32,42 @@ export declare function keepImageVersionsSelectValue(value: unknown): string;
  * string can never persist a worse policy than the contract allows.
  */
 export declare function keepImageVersionsFromSelectValue(selectValue: string): number;
+/**
+ * CPU priority tiers, expressed as the `--cpu-shares` value each one
+ * maps to. Shares are the wire format the runtime takes; the kernel
+ * ranks cgroup siblings by cgroup v2 `cpu.weight`, and the OCI runtime
+ * translates shares into a weight. That translation is the runtime's:
+ * crun and runc before 1.3.2 use a linear formula (1024 → 39), runc
+ * 1.3.2+ a quadratic one (1024 → 100). Unset is weight 100 everywhere,
+ * so `normal` is deliberately *no request* — the only value that means
+ * the same on every runtime — and the tiers are ordered by shares,
+ * which both formulas preserve.
+ *
+ * Weights only arbitrate among cgroup siblings under contention; hard
+ * caps are `cpus`.
+ */
+export declare const CPU_PRIORITY_SHARES: Readonly<Record<CpuPriority, number | null>>;
+/** Tier keys in descending priority order, for select widgets. */
+export declare const CPU_PRIORITIES: readonly CpuPriority[];
+export declare const DEFAULT_CONTAINER_CPU_PRIORITY: CpuPriority;
+/**
+ * One-shot helpers (chart imports, GDAL, wipe jobs) are the workloads
+ * that saturate every core on a small host; they yield to the
+ * long-running services by default.
+ */
+export declare const DEFAULT_JOB_CPU_PRIORITY: CpuPriority;
+/**
+ * Coerce a stored config value to a tier name. Anything that is not
+ * a known tier (hand-edited config, older panel) falls back to the
+ * given default so a typo can never select a priority nobody asked for.
+ */
+export declare function normalizeCpuPriority(value: unknown, fallback: CpuPriority): CpuPriority;
+/**
+ * The resource-limits fragment a tier contributes. `normal` contributes
+ * nothing, so it never shows up as a limit and cannot mask a
+ * consumer's or user's own `cpuShares`.
+ */
+export declare function cpuPriorityLimits(tier: CpuPriority): Pick<ContainerResourceLimits, "cpuShares">;
+/** Reverse lookup for display: the tier a shares value stands for, if any. */
+export declare function cpuPriorityForShares(shares: number | null | undefined): CpuPriority | null;
 //# sourceMappingURL=configNormalize.d.ts.map

package/dist/configNormalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configNormalize.d.ts","sourceRoot":"","sources":["../src/configNormalize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKjE;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK5E"}
+{"version":3,"file":"configNormalize.d.ts","sourceRoot":"","sources":["../src/configNormalize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKjE;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK5E;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC,CAM1E,CAAC;AAEJ,kEAAkE;AAClE,eAAO,MAAM,cAAc,EAAE,SAAS,WAAW,EAKhD,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,WAAsB,CAAC;AACpE;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAsB,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,WAAW,GACpB,WAAW,CAKb;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,GAChB,IAAI,CAAC,uBAAuB,EAAE,WAAW,CAAC,CAG5C;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAChC,WAAW,GAAG,IAAI,CAMpB"}

package/dist/configNormalize.js

@@ -44,4 +44,68 @@ export function keepImageVersionsFromSelectValue(selectValue) {
         return DEFAULT_KEEP_IMAGE_VERSIONS;
     return normalizeKeepImageVersions(Number(selectValue));
 }
+/**
+ * CPU priority tiers, expressed as the `--cpu-shares` value each one
+ * maps to. Shares are the wire format the runtime takes; the kernel
+ * ranks cgroup siblings by cgroup v2 `cpu.weight`, and the OCI runtime
+ * translates shares into a weight. That translation is the runtime's:
+ * crun and runc before 1.3.2 use a linear formula (1024 → 39), runc
+ * 1.3.2+ a quadratic one (1024 → 100). Unset is weight 100 everywhere,
+ * so `normal` is deliberately *no request* — the only value that means
+ * the same on every runtime — and the tiers are ordered by shares,
+ * which both formulas preserve.
+ *
+ * Weights only arbitrate among cgroup siblings under contention; hard
+ * caps are `cpus`.
+ */
+export const CPU_PRIORITY_SHARES = {
+    high: 5120,
+    normal: null,
+    low: 512,
+    lowest: 128,
+};
+/** Tier keys in descending priority order, for select widgets. */
+export const CPU_PRIORITIES = [
+    "high",
+    "normal",
+    "low",
+    "lowest",
+];
+export const DEFAULT_CONTAINER_CPU_PRIORITY = "normal";
+/**
+ * One-shot helpers (chart imports, GDAL, wipe jobs) are the workloads
+ * that saturate every core on a small host; they yield to the
+ * long-running services by default.
+ */
+export const DEFAULT_JOB_CPU_PRIORITY = "lowest";
+/**
+ * Coerce a stored config value to a tier name. Anything that is not
+ * a known tier (hand-edited config, older panel) falls back to the
+ * given default so a typo can never select a priority nobody asked for.
+ */
+export function normalizeCpuPriority(value, fallback) {
+    return typeof value === "string" &&
+        CPU_PRIORITIES.includes(value)
+        ? value
+        : fallback;
+}
+/**
+ * The resource-limits fragment a tier contributes. `normal` contributes
+ * nothing, so it never shows up as a limit and cannot mask a
+ * consumer's or user's own `cpuShares`.
+ */
+export function cpuPriorityLimits(tier) {
+    const shares = CPU_PRIORITY_SHARES[tier];
+    return shares === null ? {} : { cpuShares: shares };
+}
+/** Reverse lookup for display: the tier a shares value stands for, if any. */
+export function cpuPriorityForShares(shares) {
+    if (shares === undefined || shares === null)
+        return "normal";
+    for (const tier of CPU_PRIORITIES) {
+        if (CPU_PRIORITY_SHARES[tier] === shares)
+            return tier;
+    }
+    return null;
+}
 //# sourceMappingURL=configNormalize.js.map

package/dist/configNormalize.js.map

@@ -1 +1 @@
-{"version":3,"file":"configNormalize.js","sourceRoot":"","sources":["../src/configNormalize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,2BAA2B,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,OAAO,MAAM,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gCAAgC,CAAC,WAAmB;IAClE,wEAAwE;IACxE,qEAAqE;IACrE,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,2BAA2B,CAAC;IAClE,OAAO,0BAA0B,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"configNormalize.js","sourceRoot":"","sources":["../src/configNormalize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,2BAA2B,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,OAAO,MAAM,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gCAAgC,CAAC,WAAmB;IAClE,wEAAwE;IACxE,qEAAqE;IACrE,IAAI,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,2BAA2B,CAAC;IAClE,OAAO,0BAA0B,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B;IACE,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,GAAG;IACR,MAAM,EAAE,GAAG;CACZ,CAAC;AAEJ,kEAAkE;AAClE,MAAM,CAAC,MAAM,cAAc,GAA2B;IACpD,MAAM;IACN,QAAQ;IACR,KAAK;IACL,QAAQ;CACT,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAAgB,QAAQ,CAAC;AACpE;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAgB,QAAQ,CAAC;AAE9D;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAc,EACd,QAAqB;IAErB,OAAO,OAAO,KAAK,KAAK,QAAQ;QAC7B,cAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC;QACrD,CAAC,CAAE,KAAqB;QACxB,CAAC,CAAC,QAAQ,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAiB;IAEjB,MAAM,MAAM,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AACtD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,oBAAoB,CAClC,MAAiC;IAEjC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC7D,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,mBAAmB,CAAC,IAAI,CAAC,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;IACxD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/containers.js

@@ -782,10 +782,10 @@ export async function getLiveResources(runtime, name, client = getClient()) {
         out.cpus = Math.round((nano / 1_000_000_000) * 1000) / 1000;
     }
     const shares = Number(cpuShares);
-    // 0 and 1024 are both "default" — only emit if explicitly set to
-    // something else, since 1024 is the kernel default and we'd add
-    // noise to comparisons.
-    if (Number.isFinite(shares) && shares > 0 && shares !== 1024) {
+    // Both runtimes report 0 when no shares were requested. 1024 is a real
+    // request, not a default: on crun it maps to cpu.weight 39 where unset
+    // means 100 (see CPU_PRIORITY_SHARES in configNormalize.ts).
+    if (Number.isFinite(shares) && shares > 0) {
         out.cpuShares = shares;
     }
     if (cpusetCpus && cpusetCpus.trim() !== "") {