signalk-container 1.30.0 → 1.32.0

package/AGENTS.md

@@ -42,6 +42,14 @@ Do not add error handling, fallbacks, or validation for scenarios that cannot ha
   - `npm test` — unit only (`dist/test/*.test.js`, no recursion). Safe to run anywhere.
   - `npm run test:integration` — integration only (`dist/test/integration/*.test.js`). Requires podman or docker; tests still self-skip on Windows and when no runtime is found.
   - `npm run test:all` — both. The pre-PR full sweep on a dev box.
+- **Known Windows CI flake.** `node --test` intermittently marks a whole test
+  file failed with a bare `'test failed'` at `:1:1` while every assertion
+  inside it passed — the file's child process exits non-zero after its work
+  completes. It is not tied to any particular file or to the change under
+  test, and `--test-concurrency=1` does not prevent it. Diagnose it by
+  checking whether the reported file's own tests all show ✔; if they do,
+  re-run the job. `npm test` writes `test-results/junit.xml`, which plugin-CI
+  uploads as an artifact — attach that to any upstream report.
 - All new code requires tests. Test behavior at the function boundary, not internal control flow.
 - Inject `client: ContainerClient = getClient()` rather than calling dockerode directly. Tests stub via `makeMockClient(spec)` from `src/test/helpers/mockClient.ts`. See `src/test/getLiveResources.test.ts` for the canonical pattern: a mock whose `getContainer().inspect()` returns the JSON object under test, no real podman/docker invocations.
 - Container-integration tests (those that actually pull `alpine:3.19`) live under `src/test/integration/` and gate on `hasContainerRuntime()` which returns `null` on Windows. Do not add new tests that pull real Linux images without putting them under `src/test/integration/` AND gating on the helper.
@@ -130,6 +138,20 @@ See `src/client.ts`, `src/containers.ts`, `src/log-stream-broker.ts`, and the te
 
 `qualifyImage("foo/bar:tag", podmanRuntime)` prefixes `docker.io/` when needed (podman requires fully qualified names unless `unqualified-search-registries` is set; this holds over the API too). Docker passes through. Use this everywhere we feed an image string to a dockerode call.
 
+### The compat endpoint silently drops what the CLI honours
+
+Everything except `/libpod/info` goes through Podman's **Docker-compat** API via dockerode. That endpoint accepts several fields the CLI supports, returns 201, and then ignores them. Three are known and each cost real debugging time:
+
+| Field                            | CLI                      | Compat endpoint                                                                   |
+| -------------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
+| `HostConfig.Ulimits` (nofile)    | honoured                 | dropped below podman 5.5.0 (containers/podman#25881)                              |
+| `HostConfig.UsernsMode`          | honoured                 | accepted, stored as `private`                                                     |
+| `Mounts[].VolumeOptions.Subpath` | `--mount subpath=` works | accepted, ignored (measured on 5.4.2; Docker Engine honours it — 29.7.2/API 1.55) |
+
+The lesson is procedural: **a runtime's changelog or man page describes its CLI, not this endpoint.** "Podman 5.4 supports volume subpaths" is true and irrelevant — the plugin cannot use it. Before writing a capability claim into a comment, an error message, or the docs, measure it through dockerode against the socket. `src/test/integration/` is where such a probe belongs.
+
+This also means an operator-facing error must name the mechanism precisely. Telling someone "named volumes cannot be subpath-mounted" sends them to the podman docs, which say otherwise, and they conclude the plugin is broken.
+
 ### Inspect-format diff pattern
 
 When we need to read live container state, call `getContainer(name).inspect()` once (through `safeInspect`, which returns `null` on a 404 instead of throwing) and read the JSON fields directly. dockerode returns the same field shapes on podman and docker (verified live: `HostConfig.NanoCpus`, `HostConfig.Memory`, `NetworkSettings.Ports`, `Mounts[].{Type,Source,Destination}`, `Config.{Image,Cmd,Env,Healthcheck}`, etc.), so there's no Go-template parsing and no podman-vs-docker text divergence to guard against. `getLiveResources` and `getLiveContainerConfig` are the canonical examples. `diffContainerConfig` is a pure function over those inspect-derived values — keep new live-state probes reading inspect JSON directly so the diff stays uniform across runtimes.

package/README.md

@@ -18,7 +18,7 @@ Instead of each plugin implementing its own container orchestration, they delega
 - **CPU caps that fit the host** -- a `cpus` limit above the daemon's core count is lowered to it instead of failing the container create (Docker rejects `--cpus 1.5` on a 1-vCPU host outright); the consumer plugin can surface it via the optional `onResourceClamped` callback (otherwise it is a debug-log line). See the [developer guide](doc/plugin-developer-guide.md#resource-limits).
 - **Per-process ulimits** -- `ContainerConfig.ulimits` pins per-process limits (`nofile`, `nproc`, …) on a container. A containerized process inherits these from the runtime, not the host sysctl, so raising the host `fs.file-max` alone does not lift a database's open-files limit; setting `ulimits` does. A `nofile` request over the host ceiling is clamped (not rejected) so the container still starts. See the [developer guide](doc/plugin-developer-guide.md#per-process-ulimits-nofile-) and, for raising the host limit, [Raising the open-files limit](#raising-the-open-files-limit-nofile).
 - **Image management** -- scheduled pruning of dangling images (weekly/monthly), plus optional cleanup of superseded versions of managed-container images
-- **Zero-config data dir sharing** -- `signalkDataMount` mounts the SignalK data directory into any managed container automatically, whether Signal K runs bare-metal, in Docker (named volume), or in Podman (named volume or bind mount). No host paths to configure.
+- **Zero-config persistent storage** -- `signalkDataMount` mounts signalk-container's own data directory into any managed container automatically, whether Signal K runs on bare metal, in Docker (named volume), or in Podman (named volume or bind mount). No host paths to configure; namespace a subdirectory, since every managed container shares it.
 - **Zero-config config root sharing** -- `signalkConfigRootMount` mounts the entire SignalK installation config (`~/.signalk/`) — for backup, audit, or config-sync tools that need the whole tree, not the per-plugin subdirectory.
 - **Zero-config container service connectivity** -- `signalkAccessiblePorts` lets the SignalK process connect back to a service running inside a managed container (e.g. an HTTP or TCP server). signalk-container picks the right networking strategy automatically — port binding on the host loopback for bare-metal deployments, or a shared Docker network with DNS for containerised ones. No host ports are exposed unnecessarily.
 - **Host timezone propagation** -- managed containers and one-shot jobs get `TZ=<host zone>` injected automatically, so time-based logic inside them (cron-style Node-RED flows, Grafana/QuestDB time rendering, log timestamps) agrees with the host clock instead of defaulting to UTC. Consumer plugins that set `env.TZ` themselves keep full control; shell-level tools inside minimal images may additionally need the image's `tzdata` package to interpret the zone name. See the [developer guide](doc/plugin-developer-guide.md#host-timezone).
@@ -644,9 +644,28 @@ The plugin developer guide has a detailed walk-through in [doc/plugin-developer-
 > appears to be ignored, the host's cgroup controller delegation is
 > almost certainly the cause — see [Cgroup controller delegation](#cgroup-controller-delegation) above.
 
-## Mounting the SignalK data directory (`signalkDataMount`)
+## Persistent storage for managed containers (`signalkDataMount`)
 
-When a managed container needs to read or write files that Signal K also accesses (e.g. HLS segments, exports, caches), use `signalkDataMount` instead of computing and hardcoding a host path or volume name.
+When a managed container needs somewhere durable to read and write (e.g. HLS segments, exports, caches), use `signalkDataMount` instead of computing and hardcoding a host path or volume name.
+
+It mounts **signalk-container's own plugin data directory** —
+`<configRoot>/plugin-config-data/signalk-container/`. Signal K rewrites
+`getDataDirPath()` per plugin and this resolves it against signalk-container's
+app, so the source is the same for every managed container whichever plugin
+asked — never the caller's own directory, since a cross-plugin API reached
+through `globalThis` never learns who called it.
+
+The container never sees more than that directory. A bind mount is narrowed
+to the exact host path; a **named volume** is accepted only when it is
+attached to the directory itself, because signalk-container mounts a volume
+whole, and one covering a parent would expose that volume's entire contents —
+sibling plugins' data, or the whole SignalK config tree when the volume sits
+on the config root. That case fails with an error rather than over-sharing —
+see the note below.
+
+**Namespace a subdirectory** (as the example below does) so two consumers
+cannot collide. For the SignalK config root see `signalkConfigRootMount`; to
+mount your own plugin's data dir, translate it with `resolveHostPath`.
 
 ```typescript
 const SK_MOUNT = "/signalk-data";
@@ -654,7 +673,7 @@ const SK_MOUNT = "/signalk-data";
 await containers.ensureRunning("my-worker", {
   image: "myorg/myworker",
   tag: "latest",
-  signalkDataMount: SK_MOUNT, // ← mount the SignalK data dir here
+  signalkDataMount: SK_MOUNT, // ← shared managed-container storage
   command: ["--output", path.join(SK_MOUNT, "my-plugin/output/result.bin")],
 });
 ```
@@ -668,22 +687,30 @@ signalk-container resolves the correct source automatically:
 | Docker, bind-backed data dir   | the exact host path, even when a parent directory is bind-mounted |
 | Podman (rootless or root)      | same logic; named volumes receive no `:Z` flag                    |
 
-The content at `SK_MOUNT` inside the managed container always corresponds to the root of `app.getDataDirPath()`. Build paths using `path.join`:
+On bare metal or a bind mount, `SK_MOUNT` corresponds to the root of the
+resolved directory, so paths compose with `path.join`:
 
 ```typescript
-// Path inside managed container that corresponds to an absolute SignalK path:
-const containerPath = path.join(
-  SK_MOUNT,
-  path.relative(app.getDataDirPath(), absSignalkPath),
-);
+// Path inside the managed container, for a path under the resolved dir:
+const containerPath = path.join(SK_MOUNT, "my-plugin", "output", "result.bin");
 ```
 
+A **named volume** backing the directory works the same way, since it is
+only accepted when attached to that directory. Call
+`containers.resolveSignalkDataMount()` if you need the resolved source (a
+host path or a volume name) at runtime.
+
 > [!note]
-> Docker/Podman do not support subpath mounts on named volumes. If your data directory
-> is backed by a named volume, the entire volume is mounted at `SK_MOUNT`. Avoid writing
-> to paths inside `SK_MOUNT` that are also bind-mounted in the Signal K container (e.g.
-> a plugin's own directory if mounted with `./:/home/node/.signalk/node_modules/my-plugin`)
-> — those paths are not visible from inside the managed container.
+> signalk-container mounts a named volume whole: it sends no subpath, and podman's
+> Docker-compat endpoint ignores one anyway (measured on 5.4.2 — Docker Engine would
+> honour it, so narrowing cannot work uniformly). A volume attached to the
+> resolved directory is mounted whole, which is exactly that directory — fine. A volume
+> attached to a **parent** (the SignalK config root, say) would expose far more than was
+> asked for, so `ensureRunning` rejects it with an error naming the volume and the fix:
+> attach the volume to the data directory, or use `resolveHostPath()` and handle the
+> returned `subPath` deliberately. Also avoid writing to paths inside `SK_MOUNT` that are
+> separately bind-mounted in the Signal K container — those are not visible from inside
+> the managed container.
 
 You can also call `containers.resolveSignalkDataMount()` if you need to inspect the resolved source at runtime (e.g. for logging).
 
@@ -712,7 +739,7 @@ The deployment-mode resolution is identical to `signalkDataMount`: bare-metal re
 `app.config.configPath` is provided by the SignalK server runtime. If the caller's `app` object lacks it (a non-standard host), `ensureRunning()` throws.
 
 > [!note]
-> The same named-volume subpath caveat applies — Docker doesn't support subpath mounts on volumes. If `app.config.configPath` happens to live under a parent-directory bind, signalk-container computes the exact host path so the container sees the right tree.
+> The same named-volume caveat applies — the volume is mounted whole. If `app.config.configPath` happens to live under a parent-directory bind, signalk-container computes the exact host path so the container sees the right tree.
 
 ### When SignalK runs in a container: self-container detection
 
@@ -902,7 +929,7 @@ See [doc/plugin-developer-guide.md](doc/plugin-developer-guide.md) for the full
 | `updateResources(name, limits)`                 | Apply new resource limits live, fall back to recreate                                                                                                                                                                                                                                                                |
 | `getResources(name)`                            | Currently effective limits (plugin defaults ⊕ user override)                                                                                                                                                                                                                                                         |
 | `resolveSignalkDataMount()`                     | Resolve the volume name or host path that backs `app.getDataDirPath()` in the current deployment; returns `null` if the runtime is not yet initialised                                                                                                                                                               |
-| `probeHostDevice(path)`                         | Ask whether a device path exists **on the host** and which groups own its nodes — a plugin cannot `stat()` this itself once SignalK is containerized. Returns `null` for "unknown", which is not the same as `{exists:false}`. 1.30.0+                                                                                |
+| `probeHostDevice(path)`                         | Ask whether a device path exists **on the host** and which groups own its nodes — a plugin cannot `stat()` this itself once SignalK is containerized. Returns `null` for "unknown", which is not the same as `{exists:false}`. 1.30.0+                                                                               |
 | `resolveHostPath(absPath)`                      | Translate an arbitrary absolute path into the `{ source, subPath }` pair the runtime needs to mount it; handles bare-metal, bind, and named-volume topologies                                                                                                                                                        |
 | `resolveContainerAddress(name, port)`           | Return the `host:port` string to reach `port` on a managed container from the SignalK process; call after `ensureRunning()` with `signalkAccessiblePorts` set                                                                                                                                                        |
 | `doctor.imageRunsAsUser(image, user?)`          | Probe whether `image` runs cleanly under the host-UID mapping signalk-container will emit (1.8.0+). Never throws — returns `{ ok, output, error? }`                                                                                                                                                                  |
@@ -955,10 +982,10 @@ All mounted at `/plugins/signalk-container/api/`:
 device you might pass through — from a plugin that cannot see the host:
 
 ```js
-const gpu = await containers.probeHostDevice?.('/dev/dri')
+const gpu = await containers.probeHostDevice?.("/dev/dri");
 if (gpu?.exists) {
-  config.devices = ['/dev/dri']
-  config.groupAdd = gpu.groups   // names, resolved per host
+  config.devices = ["/dev/dri"];
+  config.groupAdd = gpu.groups; // names, resolved per host
 }
 ```
 
@@ -973,10 +1000,10 @@ number loses access on someone else's machine.
 
 Three results, and the difference matters:
 
-| Result                          | Meaning                                                |
-| ------------------------------- | ------------------------------------------------------ |
-| `{exists: true, nodes, groups}` | Device is there; pass `groups` to `groupAdd`            |
-| `{exists: false, …}`            | Definitely absent                                       |
+| Result                          | Meaning                                                                                                                                               |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `{exists: true, nodes, groups}` | Device is there; pass `groups` to `groupAdd`                                                                                                          |
+| `{exists: false, …}`            | Definitely absent                                                                                                                                     |
 | `null`                          | **Unknown** — no runtime, the path could not be read (a permission error, say), or the nodes are there but their owning group could not be determined |
 
 Treat `null` as "assume no device, but do not report it as absent".

package/dist/client.d.ts

@@ -62,15 +62,36 @@ export interface LibpodNetworkBackendInfo {
         path?: string;
     };
 }
+/** One `container_id`/`host_id`/`size` triple from podman's `/info`. */
+export interface LibpodIdMapEntry {
+    container_id?: number;
+    host_id?: number;
+    size?: number;
+}
 /**
  * Podman's native `/libpod/info` — the docker-compat `/info` the rest of the
  * plugin uses does NOT expose `networkBackendInfo`, so host-side network
  * facts (which DNS helper netavark resolved, if any) are only visible here.
- * The version prefix is required (unversioned libpod paths 404); Podman
- * accepts any client version for this endpoint. Returns `null` on Docker,
- * on any request failure, and when the modem can't dial (test mocks).
+ * Returns `null` on Docker, on any request failure, and when the modem
+ * can't dial (test mocks).
  */
 export declare function libpodNetworkBackendInfo(client: ContainerClient): Promise<LibpodNetworkBackendInfo | null>;
+/**
+ * Subordinate ID range podman has for the calling user, from its own
+ * `/info` — the sum of every mapping entry beyond the identity one.
+ *
+ * `--userns=keep-id:uid=N` asks for a 65536-wide subordinate block. Where
+ * the account's `/etc/subuid` allocation is narrower, podman clamps the
+ * length, and at the limit clamps it to zero — which the kernel rejects
+ * with `writing file /proc/<pid>/gid_map: Invalid argument`. Reading the
+ * real width lets the caller bound the request to what exists.
+ *
+ * Asked of podman rather than read from `/etc/subuid` because the plugin
+ * usually runs inside a container, where that file is absent while the
+ * socket still answers. Returns `null` on Docker, on any failure, and when
+ * the modem cannot dial.
+ */
+export declare function libpodSubordinateUidCount(client: Pick<ContainerClient, "modem">): Promise<number | null>;
 /** Runtime the caller prefers when more than one socket is reachable. */
 export type SocketPreference = "auto" | "podman" | "docker";
 export interface ResolvedClient {

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -19,13 +19,18 @@ import Docker from "dockerode";
 import { stat } from "node:fs/promises";
 import { PassThrough } from "node:stream";
 import { categorizeError, messageWithRaw, } from "./errors.js";
+/**
+ * Podman's native info endpoint. The version prefix is required —
+ * unversioned libpod paths 404 — and podman accepts any client version
+ * here. Shared by both probes so the two cannot drift apart.
+ */
+const LIBPOD_INFO_PATH = "/v4.0.0/libpod/info";
 /**
  * Podman's native `/libpod/info` — the docker-compat `/info` the rest of the
  * plugin uses does NOT expose `networkBackendInfo`, so host-side network
  * facts (which DNS helper netavark resolved, if any) are only visible here.
- * The version prefix is required (unversioned libpod paths 404); Podman
- * accepts any client version for this endpoint. Returns `null` on Docker,
- * on any request failure, and when the modem can't dial (test mocks).
+ * Returns `null` on Docker, on any request failure, and when the modem
+ * can't dial (test mocks).
  */
 export function libpodNetworkBackendInfo(client) {
     return new Promise((resolve) => {
@@ -36,7 +41,7 @@ export function libpodNetworkBackendInfo(client) {
         }
         try {
             dial({
-                path: "/v4.0.0/libpod/info",
+                path: LIBPOD_INFO_PATH,
                 method: "GET",
                 statusCodes: { 200: true, 500: "server error" },
             }, (err, data) => {
@@ -55,6 +60,75 @@ export function libpodNetworkBackendInfo(client) {
         }
     });
 }
+/**
+ * Total width of the subordinate entries in one mapping table, or `null`
+ * when the table is absent or contributes nothing usable.
+ *
+ * The identity entry maps the caller's own id and is not part of the
+ * subordinate block. Sizes must be positive safe integers: podman parses
+ * `size` as a uint and rejects `size=1.5` outright, and a negative would
+ * shrink the total below what the account actually has.
+ */
+function subordinateWidth(map) {
+    if (!Array.isArray(map))
+        return null;
+    const total = map
+        .filter((e) => (e?.container_id ?? 0) !== 0)
+        .reduce((n, e) => {
+        const size = e?.size;
+        return typeof size === "number" && Number.isSafeInteger(size) && size > 0
+            ? n + size
+            : n;
+    }, 0);
+    return total > 0 ? total : null;
+}
+/**
+ * Subordinate ID range podman has for the calling user, from its own
+ * `/info` — the sum of every mapping entry beyond the identity one.
+ *
+ * `--userns=keep-id:uid=N` asks for a 65536-wide subordinate block. Where
+ * the account's `/etc/subuid` allocation is narrower, podman clamps the
+ * length, and at the limit clamps it to zero — which the kernel rejects
+ * with `writing file /proc/<pid>/gid_map: Invalid argument`. Reading the
+ * real width lets the caller bound the request to what exists.
+ *
+ * Asked of podman rather than read from `/etc/subuid` because the plugin
+ * usually runs inside a container, where that file is absent while the
+ * socket still answers. Returns `null` on Docker, on any failure, and when
+ * the modem cannot dial.
+ */
+export function libpodSubordinateUidCount(client) {
+    return new Promise((resolve) => {
+        const dial = client.modem.dial?.bind(client.modem);
+        if (!dial) {
+            resolve(null);
+            return;
+        }
+        try {
+            dial({
+                path: LIBPOD_INFO_PATH,
+                method: "GET",
+                statusCodes: { 200: true, 500: "server error" },
+            }, (err, data) => {
+                if (err || typeof data !== "object" || data === null) {
+                    resolve(null);
+                    return;
+                }
+                const maps = data.host?.idMappings;
+                const uid = subordinateWidth(maps?.uidmap);
+                const gid = subordinateWidth(maps?.gidmap);
+                // One `size` governs both the uid and gid mappings, so the usable
+                // width is the smaller of the two — asking for the uid width when
+                // fewer gids exist reproduces the very failure this bounds.
+                // Unknown on either side means no safe bound at all.
+                resolve(uid === null || gid === null ? null : Math.min(uid, gid));
+            });
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
 /**
  * Socket candidates, in priority order, plus whether the operator pinned an
  * explicit endpoint. When `DOCKER_HOST`/`CONTAINER_HOST` is set we honour ONLY

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/containers.d.ts

@@ -1,5 +1,5 @@
 import type Docker from "dockerode";
-import { ContainerConfig, ContainerInfo, ContainerRuntimeInfo, ContainerState, DeviceIssue, EnsureRunningOptions, LocalImageSummary, ManagedImageRef, NofileLimits, PruneResult, ContainerWedged, ResourceClamp, UlimitClamp, VolumeIssue, VolumeSpec } from "./types.js";
+import { ContainerConfig, ContainerInfo, ContainerRuntimeInfo, ContainerState, DeviceIssue, EnsureRunningOptions, LocalImageSummary, ManagedImageRef, NofileLimits, PruneResult, ContainerStateDetail, RequestedConfigProvenance, ContainerWedged, ResourceClamp, UlimitClamp, VolumeIssue, VolumeSpec } from "./types.js";
 import { StreamingProcessHandle } from "./runtime.js";
 import { type ContainerClient } from "./client.js";
 import { type ErrorKind } from "./errors.js";
@@ -84,7 +84,17 @@ export declare function resolveHostTimezone(systemZone?: () => string): string |
  * `defaultHomeForConfigRoot`.
  */
 export declare function defaultTimezoneEnv(env: Record<string, string> | undefined, zone: string | undefined): Record<string, string> | undefined;
-export declare function classifyVolumeSources(volumes: Record<string, string | VolumeSpec> | undefined, probe?: (path: string) => boolean): {
+/**
+ * What a host-source probe could establish about a path.
+ *
+ * `"unknown"` is NOT a synonym for absent. When the manager runs inside a
+ * container its filesystem is not the one the runtime resolves bind sources
+ * against, so `existsSync` on a host path answers a different question than
+ * the one asked. Reporting that as absent drops a volume whose source is
+ * perfectly real — the bug this type exists to prevent.
+ */
+export type VolumeSourceState = boolean | "unknown";
+export declare function classifyVolumeSources(volumes: Record<string, string | VolumeSpec> | undefined, probe?: (path: string) => VolumeSourceState): {
     kept: Record<string, string>;
     skipped: Array<{
         containerPath: string;
@@ -94,6 +104,11 @@ export declare function classifyVolumeSources(volumes: Record<string, string | V
         containerPath: string;
         source: string;
     }>;
+    /** Host paths whose existence could not be established. Kept, not dropped. */
+    unverified: Array<{
+        containerPath: string;
+        source: string;
+    }>;
 };
 /**
  * Given the volume issues from the last `ensureRunning` call (both
@@ -325,6 +340,19 @@ export declare function getLiveContainerDigest(runtime: ContainerRuntimeInfo, co
  */
 export declare function pullImage(runtime: ContainerRuntimeInfo, image: string, onProgress?: (msg: string) => void, client?: ContainerClient): Promise<void>;
 export declare function getContainerState(runtime: ContainerRuntimeInfo, name: string, client?: ContainerClient): Promise<ContainerState>;
+/**
+ * Coarse state plus the detail that explains it — exit code, OOM kill,
+ * restart count and the container's own healthcheck verdict.
+ *
+ * `getContainerState` answers "can I talk to it"; this answers "why is
+ * it like that". Both read the same `State` block from one inspect, and
+ * share `coarseStateFrom` so the two can never disagree about running.
+ *
+ * Returns `state: "missing"` with no detail when the container is gone.
+ * Individual fields stay undefined when the runtime omits them rather
+ * than defaulting to a zero that would read as real data.
+ */
+export declare function getContainerStateDetail(name: string, client?: ContainerClient): Promise<ContainerStateDetail>;
 /**
  * Upper bound on the `.State.Error` text surfaced to callers. Some OCI
  * runtime rejections embed multi-kilobyte detail (spec dumps, nested
@@ -377,6 +405,19 @@ export declare function getLiveResources(runtime: ContainerRuntimeInfo, name: st
  * current-vs-target check minus runtime-injected fields.
  */
 export declare function getRequestedResources(name: string, client?: ContainerClient): Promise<import("./types.js").ContainerResourceLimits | undefined>;
+/**
+ * Parse the requested-config provenance label written at create time.
+ *
+ * Returns `undefined` — meaning "no provenance", so the caller keeps
+ * today's positive-only drift behaviour — when the label is absent,
+ * unparseable, or not an object. It must never return `{}` for a
+ * missing label: an empty provenance reads as "the container was
+ * created with no env at all", which would mask a genuine unset.
+ *
+ * Never throws. A hand-edited or truncated label degrades to
+ * `undefined` rather than breaking `ensureRunning`.
+ */
+export declare function parseRequestedConfigLabel(raw: string | undefined): RequestedConfigProvenance | undefined;
 /**
  * One host-side endpoint for a single container port. Mirror of the
  * `{ HostIp, HostPort }` shape that podman/docker emit under
@@ -503,18 +544,20 @@ export declare function getLiveContainerConfig(runtime: ContainerRuntimeInfo, na
  *     for floating tags (`:latest` digest drift) is the update service's job.
  *   - command: explicit drift when `requested.command` is set and differs
  *     from `live.command`. When `requested.command` is undefined, drift is
- *     reported only if a `prior.command` was set (i.e. the user is now
- *     unsetting it). Without a `prior`, an undefined `requested.command`
- *     can't be told apart from "image's baked CMD" so we skip — the
- *     wrapper's prior-config cache (`lastConfigs`) closes that loop on the
- *     second-and-later calls within a single signalk-container lifetime.
+ *     reported only if a prior `command` was set (i.e. the user is now
+ *     unsetting it). The prior comes from the wrapper's `lastConfigs`
+ *     cache when warm, and otherwise from the create-time provenance
+ *     label; with neither, an undefined `requested.command` can't be
+ *     told apart from "image's baked CMD" so we skip.
  *   - networkMode: runtime defaults (`bridge`, `slirp4netns`, etc.) are
  *     normalized to `""` and compared as equivalent to requested undefined.
  *   - env: requested keys must match live values. Additionally, any key
- *     present in `prior.env` but absent from `requested.env` is treated
- *     as drift (the user is unsetting it). Image-baked env keys not in
- *     either `requested.env` or `prior.env` are ignored — they were never
- *     ours.
+ *     present in the prior env but absent from `requested.env` is treated
+ *     as drift (the user is unsetting it). Image-baked env keys in neither
+ *     `requested.env` nor the prior are ignored — they were never ours.
+ *     The prior is the warm `lastConfigs` entry, falling back to the env
+ *     KEY NAMES recorded in the create-time provenance label; values are
+ *     never recorded there because this check reads only key presence.
  *   - volumes: trailing slashes stripped on both sides; `(host, container)`
  *     tuples compared as a Map keyed by container path. Live binds have
  *     their `:Z`/`:ro` flags already stripped by `getLiveContainerConfig`.
@@ -612,8 +655,10 @@ export declare function ensureRunning(runtime: ContainerRuntimeInfo, name: strin
  * this signalk-container lifetime, if any. Used to detect "unset" drift
  * — env keys removed, `command` previously set and now undefined. The
  * wrapper in `index.ts` reads from its `lastConfigs` cache before
- * overwriting it; on the first call (or after a Signal K restart) this
- * will be undefined and only positive drift is detected.
+ * overwriting it. On the first call (or after a Signal K restart) it
+ * is undefined and the diff falls back to the requested-config
+ * provenance label stamped at create time, so an unset is still
+ * detected across a restart.
  */
 prior?: ContainerConfig, _postRecreate?: boolean, _pull?: PullFn): Promise<void>;
 export declare function startContainer(runtime: ContainerRuntimeInfo, name: string, client?: ContainerClient): Promise<void>;
@@ -877,6 +922,24 @@ export declare function readSelfContainerIdsFromMountinfo(): string[];
  * return null to the caller (depends on the consumer).
  */
 export declare function findSelfContainerId(runtime: ContainerRuntimeInfo, debug?: (msg: string) => void, client?: ContainerClient): Promise<string | null>;
+/**
+ * Refuse a named volume that covers more than the requested directory.
+ *
+ * Neither runtime can subpath-mount a volume, so a volume attached to a
+ * PARENT of the requested directory would hand the managed container
+ * everything in it — for `signalkDataMount`, the whole SignalK config tree
+ * with `security.json` in it, when the container asked only for scratch
+ * space. Throwing gives the caller a clear failure instead of silent access
+ * to files it never requested.
+ *
+ * A volume attached to the requested directory itself is exactly what was
+ * asked for and passes. Callers who genuinely want a parent-backed volume
+ * have `resolveHostPath`, which reports `subPath` so the choice is explicit.
+ *
+ * `field` names the API the consumer actually used, since one resolver
+ * serves both `signalkDataMount` and `signalkConfigRootMount`.
+ */
+export declare function assertVolumeIsNotBroaderThanRequested(volumeName: string, volumeDest: string, requestedDir: string, field: string): void;
 /**
  * Resolve what to mount in a managed container to give it access to
  * the SignalK data directory, regardless of how SignalK itself is deployed.
@@ -890,10 +953,13 @@ export declare function findSelfContainerId(runtime: ContainerRuntimeInfo, debug
  *     fail gracefully at container-create time with a clear Docker error.
  *
  * The result can be used directly as `volumes: { [mountPoint]: source }` in
- * a ContainerConfig.  The content visible at mountPoint inside the managed
- * container will always correspond to the root of dataDir.
+ * a ContainerConfig.  The content visible at mountPoint corresponds to the
+ * root of dataDir: a bind is narrowed to the exact host path, and a named
+ * volume is only accepted when it is mounted on dataDir itself.  A volume
+ * covering a parent throws rather than over-sharing: the plugin sends no
+ * subpath, and podman's compat endpoint would ignore one.
  */
-export declare function resolveSignalkDataSource(dataDir: string, runtime: ContainerRuntimeInfo, debug?: (msg: string) => void, client?: ContainerClient): Promise<string>;
+export declare function resolveSignalkDataSource(dataDir: string, runtime: ContainerRuntimeInfo, debug?: (msg: string) => void, client?: ContainerClient, field?: string): Promise<string>;
 /**
  * Mount entry as parsed from `podman inspect --format '{{range .Mounts}}...'`.
  * Exposed so tests can drive `resolveHostPathFromMounts` directly without
@@ -959,6 +1025,43 @@ export interface ContainerMountResolution {
  *     `resolveSignalkDataSource` does for backwards-compat).
  */
 export declare function resolveHostPath(absPath: string, runtime: ContainerRuntimeInfo, debug?: (msg: string) => void, client?: ContainerClient): Promise<ContainerMountResolution | null>;
+/**
+ * Can `existsSync(hostPath)` be trusted inside this container?
+ *
+ * The caller holds a HOST path and stats that same string locally, so the
+ * mount has to make those two the same thing. Three conditions, and all are
+ * load-bearing:
+ *
+ * - **Bind mounts only.** A named volume's contents are not the host
+ *   filesystem at that path, so a file seen inside one proves nothing.
+ * - **Path-preserving only** (`source === dest`). A bind of `/host/data` to
+ *   `/data` puts the host's `/host/data` at `/data`; the string `/data` inside
+ *   the container names `/host/data` on the host, and the host's own `/data`
+ *   is not visible at all. Verified against a real runtime. Trusting such a
+ *   mount would let `existsSync("/data/certs")` answer about
+ *   `/host/data/certs` and report a nonexistent required source as present --
+ *   exactly the `ifMissing: "abort"` failure this guards.
+ * - **Exact-or-child.** A mount at `/data` covers `/data` and `/data/sub`,
+ *   never `/database`.
+ *
+ * Factored out of `ownBindMountCoverage` so the rule is testable without a
+ * runtime.
+ */
+export declare function isPathUnderBindMount(absPath: string, mounts: readonly InspectedMount[]): boolean;
+/**
+ * Host paths this container can see truthfully, as a predicate.
+ *
+ * A bind mount makes this container's view of a path the HOST's view at a
+ * known offset, so `existsSync` under one is authoritative in both directions.
+ * Anywhere else a containerized process is looking at a different filesystem
+ * entirely, and neither answer means anything about the host.
+ *
+ * Returns a predicate rather than resolving one path so the inspect happens
+ * ONCE per reconcile instead of once per volume. On bare metal, or when the
+ * self-inspect fails, every path is covered / not covered respectively — the
+ * caller decides what that means.
+ */
+export declare function ownBindMountCoverage(runtime: ContainerRuntimeInfo, debug?: (msg: string) => void, client?: ContainerClient): Promise<(absPath: string) => boolean>;
 /**
  * Release a port that was reserved by `findAvailablePort()`.
  * Must be called after the container runtime has successfully bound the port