@omnitron-dev/omnitron 0.3.0 → 0.3.2

package/dist/infrastructure/container-runtime.js

@@ -7,8 +7,94 @@
  *
  * All Omnitron-managed containers are labeled with `omnitron.managed=true`.
  */
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { CONFIG_ROOT_PREFIX } from './shipped-config.js';
+import { nativeHealthCheck } from './health-recovery.js';
+// Docker RAMInBytes units are binary, case insensitive, with optional b/ib.
+// Normalize once so argv, desired identity and native inspection agree.
+function memoryBytes(value, field) {
+    if (typeof value !== 'string')
+        throw new Error(`${field} must be a Docker memory size`);
+    const match = /^(\d+(?:\.\d*)?|\.\d+) ?(b|[kmgtp](?:i?b)?)?$/i.exec(value);
+    if (!match)
+        throw new Error(`${field} must be a non-negative Docker memory size`);
+    const unit = match[2]?.[0]?.toLowerCase();
+    const power = unit && unit !== 'b' ? 'kmgtp'.indexOf(unit) + 1 : 0;
+    const bytes = Math.trunc(Number(match[1]) * (power > 0 ? 1024 ** power : 1));
+    if (!Number.isSafeInteger(bytes) || bytes < 0)
+        throw new Error(`${field} exceeds exact byte representation`);
+    return bytes;
+}
+/** Pure validation: called before network, volume, image or container mutations. */
+export function containerResources(config) {
+    const limits = config.resources;
+    if (limits !== undefined && (limits === null || typeof limits !== 'object' || Array.isArray(limits)))
+        throw new Error('resources must be an object');
+    const out = {};
+    if (limits?.memory !== undefined)
+        out.memoryBytes = memoryBytes(limits.memory, 'resources.memory');
+    if (limits?.memoryReservation !== undefined)
+        out.memoryReservationBytes = memoryBytes(limits.memoryReservation, 'resources.memoryReservation');
+    if (limits?.cpus !== undefined) {
+        if (typeof limits.cpus !== 'number' || !Number.isFinite(limits.cpus) || limits.cpus < 0)
+            throw new Error('resources.cpus must be finite and non-negative');
+        // Docker parses the decimal spelling as an exact rational, not float * 1e9.
+        const [coefficient, exponent = '0'] = String(limits.cpus).toLowerCase().split('e');
+        const [whole, fraction = ''] = coefficient.split('.');
+        const digits = BigInt(whole + fraction), scale = 9 + Number(exponent) - fraction.length;
+        const divisor = scale < 0 ? 10n ** BigInt(-scale) : 1n;
+        const nano = scale < 0 ? digits / divisor : digits * 10n ** BigInt(scale);
+        if (digits % divisor !== 0n || nano > BigInt(Number.MAX_SAFE_INTEGER))
+            throw new Error('resources.cpus must be exactly representable in nano CPUs');
+        out.nanoCpus = Number(nano);
+    }
+    // Validate both declarations, preserving the existing top-level override.
+    const nested = limits?.shmSize === undefined ? undefined : memoryBytes(limits.shmSize, 'resources.shmSize');
+    const shm = config.shmSize === undefined ? nested : memoryBytes(config.shmSize, 'shmSize');
+    if (shm !== undefined) {
+        out.shmBytes = shm;
+    }
+    for (const value of [out.memoryBytes, out.memoryReservationBytes]) {
+        if (value !== undefined && value > 0 && value < 6 * 1024 ** 2)
+            throw new Error('Positive memory limits require at least 6 MiB');
+    }
+    if (out.memoryBytes && out.memoryReservationBytes !== undefined && out.memoryReservationBytes > out.memoryBytes)
+        throw new Error('resources.memoryReservation cannot exceed resources.memory');
+    return out;
+}
+function resourceArgs(resources) {
+    const args = [];
+    if (resources.memoryBytes !== undefined)
+        args.push('--memory', String(resources.memoryBytes));
+    if (resources.memoryReservationBytes !== undefined)
+        args.push('--memory-reservation', String(resources.memoryReservationBytes));
+    if (resources.nanoCpus !== undefined) {
+        const nano = BigInt(resources.nanoCpus);
+        args.push('--cpus', `${nano / 1000000000n}.${String(nano % 1000000000n).padStart(9, '0')}`);
+    }
+    if (resources.shmBytes !== undefined)
+        args.push('--shm-size', String(resources.shmBytes));
+    return args;
+}
+function observedResources(info) {
+    const h = info.HostConfig;
+    if (!h || ![h['Memory'], h['MemoryReservation'], h['NanoCpus'], h['ShmSize'], h['CpuPeriod']].every(n => typeof n === 'number' && Number.isSafeInteger(n) && n >= 0) ||
+        typeof h['CpuQuota'] !== 'number' || !Number.isSafeInteger(h['CpuQuota']))
+        return undefined;
+    return { memoryBytes: h['Memory'], memoryReservationBytes: h['MemoryReservation'],
+        nanoCpus: h['NanoCpus'], shmBytes: h['ShmSize'], cpuQuota: h['CpuQuota'], cpuPeriod: h['CpuPeriod'] };
+}
+/** Labels record intent; Docker HostConfig records the actual enforced limits. */
+export function containerResourcesMatch(config, actual) {
+    return Object.entries(containerResources(config)).every(([key, value]) => {
+        // Zero shm asks Docker for its daemon-configurable default, not a zero-byte mount.
+        if (key === 'shmBytes' && value === 0)
+            return actual.resources !== undefined;
+        if (key === 'nanoCpus' && (actual.resources?.cpuQuota === undefined || actual.resources.cpuQuota > 0))
+            return false;
+        return actual.resources?.[key] === value;
+    });
+}
 /** Label carrying the desired-spec fingerprint, used for config-drift detection. */
 export const SPEC_HASH_LABEL = 'omnitron.spec-hash';
 /**
@@ -23,6 +109,7 @@ export const SPEC_HASH_LABEL = 'omnitron.spec-hash';
  * being silently ignored because the image is unchanged.
  */
 export function containerSpecHash(config) {
+    const resources = containerResources(config);
     const sortedEnv = Object.keys(config.environment)
         .sort()
         .map((k) => [k, config.environment[k]]);
@@ -57,6 +144,7 @@ export function containerSpecHash(config) {
         // is on the old one, and its name resolves for nobody.
         network: config.network ?? null,
         restart: config.restart,
+        ...(Object.keys(resources).length ? { resources } : {}),
         // What the mounted config files SAY, which the volume paths above cannot:
         // an nginx.conf rewritten in place has the same path. Only when present,
         // so a container with no config files keeps the hash it was created
@@ -132,7 +220,10 @@ export async function countContainersByState(timeoutMs = 10_000) {
         timeout: timeoutMs,
     });
     const counts = { running: 0, paused: 0, stopped: 0 };
-    for (const state of String(stdout).split('\n').map((line) => line.trim()).filter(Boolean)) {
+    for (const state of String(stdout)
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean)) {
         if (state === 'running')
             counts.running++;
         else if (state === 'paused')
@@ -173,7 +264,7 @@ export async function listManagedContainers(options = {}) {
         // all 28 in a single call — so the loop cost roughly 1.2s of process
         // churn per poll when it was working, and under load it stopped returning
         // at all, leaving the containers page in its loading state indefinitely.
-        const inspected = await inspectContainers(names);
+        const inspected = await inspectContainers(names, options.orThrow);
         // Named and then not described: `inspectContainers` swallows its own
         // failure, and an empty answer here is Docker going away mid-question.
         if (options.orThrow && inspected.length === 0) {
@@ -181,17 +272,24 @@ export async function listManagedContainers(options = {}) {
         }
         const managed = [];
         for (const info of inspected) {
-            if (info?.Config?.Labels?.['omnitron.managed'] !== 'true')
+            if (info?.Config?.Labels?.['omnitron.managed'] !== 'true') {
+                if (options.checkNames?.has((info?.Name ?? '').replace(/^\//, '')))
+                    throw new Error('A declared container name is occupied by an unmanaged container');
                 continue;
+            }
             const failure = describeContainerFailure(info.State);
             managed.push({
                 name: (info.Name ?? '').replace(/^\//, ''),
                 image: info.Config?.Image ?? '',
                 status: mapInspectStatus(info.State?.Status),
-                containerId: info.Id?.slice(0, 12),
-                health: mapInspectHealth(info.State?.Health?.Status),
+                containerId: info.Id,
+                specHash: info.Config?.Labels?.[SPEC_HASH_LABEL],
+                labels: info.Config?.Labels,
+                health: mapInspectHealth(info.State?.Health?.Status, info.State?.Status),
+                healthCheck: nativeHealthCheck(info.State?.Health),
                 startedAt: info.State?.StartedAt,
                 ports: publishedPorts(info),
+                resources: observedResources(info),
                 service: info.Config?.Labels?.['omnitron.service'],
                 project: info.Config?.Labels?.['omnitron.project'],
                 stack: info.Config?.Labels?.['omnitron.stack'],
@@ -207,6 +305,21 @@ export async function listManagedContainers(options = {}) {
         return [];
     }
 }
+/** Native IDs are the authority for destructive operations. Never follow a reused name. */
+export async function inspectStackContainers(scope, names = []) {
+    const expected = new Set(names);
+    const actual = await listManagedContainers({ orThrow: true, checkNames: expected });
+    return actual.flatMap(container => {
+        if (container.project !== scope.project || container.stack !== scope.stack) {
+            if (expected.has(container.name))
+                throw new Error(`Container '${container.name}' belongs to another allocation`);
+            return [];
+        }
+        if (!container.containerId || !/^[a-f0-9]{64}$/.test(container.containerId))
+            throw new Error('Container inventory has no immutable identity');
+        return [{ id: container.containerId, name: container.name }];
+    }).sort((a, b) => a.id.localeCompare(b.id));
+}
 /**
  * Published ports, as `"80/tcp" -> 9800`.
  *
@@ -247,7 +360,7 @@ function publishedPorts(info) {
  * array — which is the behaviour wanted here, since a container can be
  * removed between listing and inspecting.
  */
-async function inspectContainers(names) {
+async function inspectContainers(names, strict = false) {
     const { execFile } = await import('node:child_process');
     const { promisify } = await import('node:util');
     const execFileAsync = promisify(execFile);
@@ -260,6 +373,8 @@ async function inspectContainers(names) {
         return Array.isArray(parsed) ? parsed : [];
     }
     catch (err) {
+        if (strict)
+            throw err;
         // A non-zero exit means SOME name was unknown; docker still prints the
         // ones it found, so the output is worth parsing rather than discarding.
         const stdout = err.stdout;
@@ -277,10 +392,16 @@ async function inspectContainers(names) {
 /**
  * Get state of a specific container by name.
  */
-export async function getContainerState(name) {
+export async function getContainerState(name, options = {}) {
     try {
         return await withAdapter(async (adapter) => {
-            const exists = await adapter.containerExists(name);
+            // containerExists deliberately returns false for every inspect failure.
+            // Ownership transfer must distinguish confirmed absence from a daemon
+            // outage: a successful complete listing proves absence; a listed object
+            // that cannot then be inspected is an error, including deletion races.
+            const exists = options.orThrow
+                ? (await adapter.listContainers(true)).includes(name)
+                : await adapter.containerExists(name);
             if (!exists)
                 return null;
             const info = await adapter.inspectContainer(name);
@@ -294,18 +415,27 @@ export async function getContainerState(name) {
                 name: (info.Name ?? name).replace(/^\//, ''),
                 image: info.Config?.Image ?? '',
                 status: mapInspectStatus(info.State?.Status),
-                containerId: info.Id?.slice(0, 12),
-                health: mapInspectHealth(info.State?.Health?.Status),
+                containerId: options.fullId ? info.Id : info.Id?.slice(0, 12),
+                health: mapInspectHealth(info.State?.Health?.Status, info.State?.Status),
+                healthCheck: nativeHealthCheck(info.State?.Health),
                 startedAt: info.State?.StartedAt,
                 ports: publishedPorts(info),
+                resources: observedResources(info),
                 specHash: info.Config?.Labels?.[SPEC_HASH_LABEL],
+                labels: info.Config?.Labels,
+                mounts: (info.Mounts ?? []).map((mount) => ({
+                    source: mount.Source,
+                    target: mount.Destination,
+                })),
                 service: info.Config?.Labels?.['omnitron.service'],
                 networkAttached,
                 ...(failure && { error: failure }),
             };
         });
     }
-    catch {
+    catch (error) {
+        if (options.orThrow)
+            throw error;
         return null;
     }
 }
@@ -327,7 +457,7 @@ export async function getContainerState(name) {
  * default that every resolver must remember is a default that one of them
  * will not: `resolveGateway` was the one return of four that did not call it,
  * and the gateway is the container that faces outward. Measured on the dev
- * stand: `daos-dev-gateway` published on 0.0.0.0:80 while the other ten
+ * stand: `sample-dev-gateway` published on 0.0.0.0:80 while the other ten
  * managed containers were all on 127.0.0.1, and a browser on the LAN could
  * sign in. Defence in depth, because the resolver-side default is the one
  * that can be forgotten and this one cannot.
@@ -385,7 +515,10 @@ export async function containerHoldingPort(hostPort) {
     const { execFile } = await import('node:child_process');
     const { promisify } = await import('node:util');
     try {
-        const { stdout } = await promisify(execFile)('docker', ['ps', '-a', '--format', '{{.Names}}\t{{.Ports}}'], { encoding: 'utf-8', timeout: 20_000 });
+        const { stdout } = await promisify(execFile)('docker', ['ps', '-a', '--format', '{{.Names}}\t{{.Ports}}'], {
+            encoding: 'utf-8',
+            timeout: 20_000,
+        });
         for (const line of String(stdout).split('\n')) {
             const [name, ports] = line.split('\t');
             if (!name || !ports)
@@ -425,9 +558,7 @@ lookup = containerHoldingPort) {
  * Create and start a container from a resolved config.
  */
 export async function createContainer(config) {
-    const { execFile } = await import('node:child_process');
-    const { promisify } = await import('node:util');
-    const execFileAsync = promisify(execFile);
+    const resources = containerResources(config);
     // Ensure the managed network exists before we try to attach to it.
     // Idempotent — `docker network create` errors with "already exists"
     // when present, which we treat as success. Doing this here (rather
@@ -446,7 +577,9 @@ export async function createContainer(config) {
     }
     // Pull image if not present
     await ensureImage(config.image);
-    // Build docker run command directly — xec adapter can hang
+    // Use the local Xec executor with explicit argv. The command can contain
+    // credentials in environment, application flags and nested health checks;
+    // raw execFile errors would print those arguments before any logger sees them.
     const args = ['docker', 'run', '-d', '--name', config.name];
     // Network — explicit network avoids the default bridge, which
     // accumulates phantom endpoints after dockerd restarts on macOS and
@@ -470,7 +603,8 @@ export async function createContainer(config) {
     // Labels — stamp the desired-spec fingerprint so a later reconcile can
     // detect config drift (env/ports/volumes/cmd change under the same image)
     // and recreate instead of silently no-op'ing.
-    const labels = { ...(config.labels ?? {}), [SPEC_HASH_LABEL]: containerSpecHash(config) };
+    const creation = randomUUID();
+    const labels = { ...(config.labels ?? {}), [SPEC_HASH_LABEL]: containerSpecHash(config), 'omnitron.creation': creation };
     for (const [key, value] of Object.entries(labels)) {
         args.push('--label', `${key}=${value}`);
     }
@@ -499,10 +633,7 @@ export async function createContainer(config) {
             args.push('--add-host', entry);
         }
     }
-    // SHM size
-    if (config.shmSize) {
-        args.push('--shm-size', config.shmSize);
-    }
+    args.push(...resourceArgs(resources));
     // Entrypoint override
     if (config.entrypoint) {
         args.push('--entrypoint', config.entrypoint[0]);
@@ -516,7 +647,7 @@ export async function createContainer(config) {
     if (config.command) {
         args.push(...config.command);
     }
-    // Execute docker run — use async execFile to avoid blocking event loop.
+    // Execute docker run asynchronously through Xec's shared error redaction.
     //
     // Self-heal the two stale-state failures that otherwise wedge a managed
     // container into an unstartable state (both seen in production on
@@ -541,7 +672,18 @@ export async function createContainer(config) {
     // Deliberately narrow. A missing image, a bad flag, or a port genuinely
     // held by something else is permanent, and retrying it turns one clear
     // error into several identical ones separated by delays.
-    const runDocker = () => execFileAsync('docker', args.slice(1), { encoding: 'utf-8', timeout: 60_000 });
+    const runDocker = async () => {
+        const { ExecutionEngine } = await import('@xec-sh/core');
+        const engine = new ExecutionEngine({ defaultShell: false, enableEvents: false,
+            adapters: { local: { forceImplementation: 'node' } } });
+        try {
+            return await engine.execute({ command: 'docker', args: args.slice(1), shell: false,
+                adapter: 'local', timeout: 60_000, maxBuffer: 1024 * 1024, throwOnNonZeroExit: true });
+        }
+        finally {
+            await engine.dispose();
+        }
+    };
     let stdout;
     let lastError;
     for (let attempt = 1; attempt <= 3; attempt += 1) {
@@ -554,14 +696,19 @@ export async function createContainer(config) {
             lastError = err;
             const msg = err instanceof Error ? err.message : String(err);
             if (isStaleContainerState(msg)) {
-                await scrubStaleContainerState(config.name, config.network);
+                await cleanFailedCreation(config.name, creation);
+                if (config.network) {
+                    const { PhantomEndpointJanitor } = await import('./phantom-endpoint-janitor.js');
+                    const { createNullLogger } = await import('@omnitron-dev/titan/module/logger');
+                    await new PhantomEndpointJanitor({ networks: [config.network], logger: createNullLogger() }).sweepNetwork(config.network, config.name);
+                }
                 continue;
             }
             if (isPortNotYetReleased(msg)) {
                 // The failed run leaves the container in `Created` holding the name,
                 // so the next attempt would hit the name conflict instead of the
                 // port. Remove it, then wait for the bind to go.
-                await removeContainer(config.name).catch(() => undefined);
+                await cleanFailedCreation(config.name, creation);
                 await new Promise((resolve) => setTimeout(resolve, attempt * 1_000));
                 continue;
             }
@@ -585,40 +732,29 @@ export async function createContainer(config) {
     // rebuild once from clean state so a successful return always means the
     // declared ports are actually reachable.
     if (config.ports.length > 0 && !(await arePortsPublished(config.name, config.ports))) {
-        await scrubStaleContainerState(config.name, config.network);
+        await cleanFailedCreation(config.name, creation);
         ({ stdout } = await runDocker());
     }
+    if (Object.keys(resources).length) {
+        const actual = await getContainerState(config.name, { orThrow: true, fullId: true });
+        if (!actual || actual.labels?.['omnitron.creation'] !== creation || !containerResourcesMatch(config, actual)) {
+            await cleanFailedCreation(config.name, creation);
+            throw new Error(`Container '${config.name}' does not enforce its declared resource limits`);
+        }
+    }
     const output = (stdout ?? '').trim();
     // Return container ID from docker run output (first line is container ID)
     return (output || config.name).slice(0, 12);
 }
-/**
- * Clear stale Docker state that blocks (re)creating a managed container: a
- * leftover container holding the name, and an orphaned libnetwork endpoint
- * holding the name on the managed network. Best-effort — every step may
- * legitimately find nothing to remove.
- */
-async function scrubStaleContainerState(name, network) {
-    const { execFile } = await import('node:child_process');
-    const { promisify } = await import('node:util');
-    const execFileAsync = promisify(execFile);
-    try {
-        await execFileAsync('docker', ['rm', '-f', name], { encoding: 'utf-8', timeout: 15_000 });
-    }
-    catch {
-        // No leftover container.
-    }
-    if (network) {
-        try {
-            await execFileAsync('docker', ['network', 'disconnect', '-f', network, name], {
-                encoding: 'utf-8',
-                timeout: 15_000,
-            });
-        }
-        catch {
-            // No orphaned endpoint for this name.
-        }
+/** A failed docker run may leave its own container in Created. Never follow a reused name. */
+async function cleanFailedCreation(name, creation) {
+    const actual = await getContainerState(name, { orThrow: true, fullId: true });
+    if (!actual)
+        return;
+    if (actual.labels?.['omnitron.creation'] !== creation || !actual.containerId || !/^[a-f0-9]{64}$/.test(actual.containerId)) {
+        throw new Error(`Container '${name}' belongs to another creation; inspect its ownership before retrying`);
     }
+    await removeContainer(actual.containerId);
 }
 /**
  * True if every declared host port shows up in `docker port <name>` (i.e.
@@ -651,26 +787,36 @@ export async function startContainer(nameOrId) {
 /**
  * Stop a running container gracefully.
  */
-export async function stopContainer(nameOrId, _timeout = 10) {
+export async function stopContainer(nameOrId, timeout = 10) {
     const adapter = await getAdapter();
-    await adapter.stopContainer(nameOrId);
+    await adapter.stopContainer(nameOrId, timeout);
 }
 /**
  * Remove a container (force if running).
  */
-export async function removeContainer(nameOrId) {
+export async function removeContainer(nameOrId, options = {}) {
     const adapter = await getAdapter();
-    try {
-        await adapter.removeContainer(nameOrId, true);
-    }
-    catch {
-        // Already removed
-    }
+    await adapter.removeContainer(nameOrId, !options.graceful, options);
 }
 /**
  * Pull an image if not present locally.
  */
 export async function ensureImage(image) {
+    // A local content ID is not a registry reference. Never turn it into a
+    // pull of a repository named "sha256", or accept a missing local object.
+    if (image.startsWith('sha256:')) {
+        if (!/^sha256:[a-f0-9]{64}$/.test(image))
+            throw new Error('Invalid local image ID');
+        const { execFile } = await import('node:child_process');
+        const { promisify } = await import('node:util');
+        const { stdout } = await promisify(execFile)('docker', ['image', 'inspect', image, '--format', '{{.Id}}'], {
+            timeout: 15_000,
+            maxBuffer: 4096,
+        });
+        if (stdout.trim() !== image)
+            throw new Error('Local image identity mismatch');
+        return;
+    }
     const adapter = await getAdapter();
     try {
         // Check if image exists locally via listImages
@@ -713,30 +859,35 @@ export async function waitForHealthy(name, timeoutMs = 60_000) {
         return false;
     }
 }
-/**
- * Create a Docker bridge network if it doesn't exist.
- *
- * Idempotent — `docker network create` exits non-zero with a recognisable
- * "already exists" message when the network is present; we swallow that
- * specific case and propagate everything else. Done via execFile rather
- * than the adapter because the adapter doesn't expose network APIs and
- * the call is rare (once per daemon startup per network).
- */
+/** Reuse existing Docker networks; create only an explicitly absent named bridge. */
 export async function ensureNetwork(name) {
+    // Sharing another container's namespace is a runtime mode, not a network object.
+    if (name.startsWith('container:') && name.length > 'container:'.length)
+        return;
     const { execFile } = await import('node:child_process');
     const { promisify } = await import('node:util');
-    const execFileAsync = promisify(execFile);
+    const run = promisify(execFile);
+    const options = { encoding: 'utf-8', timeout: 15_000 };
+    const inspect = () => run('docker', ['network', 'inspect', name], options);
     try {
-        await execFileAsync('docker', ['network', 'create', name, '--driver', 'bridge'], {
-            encoding: 'utf-8',
-            timeout: 15_000,
-        });
+        await inspect();
+        // In particular, host/none/bridge are Docker-owned and must never be created.
+        return;
     }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (/already exists/i.test(msg))
-            return; // idempotent
-        throw err;
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!/no such network|network .+ not found/i.test(message))
+            throw error;
+    }
+    try {
+        await run('docker', ['network', 'create', name, '--driver', 'bridge'], options);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!/already exists/i.test(message))
+            throw error;
+        // A concurrent creator won. Verify its result rather than trusting error prose.
+        await inspect();
     }
 }
 /**
@@ -849,8 +1000,10 @@ function mapInspectStatus(status) {
         return 'dead';
     return 'not_found';
 }
-function mapInspectHealth(health) {
-    if (!health)
+function mapInspectHealth(health, status) {
+    // Docker retains its last probe after a stop. That historical verdict must
+    // not be presented as a current measurement in CLI, Console or topology.
+    if (status?.toLowerCase() !== 'running' || !health)
         return 'none';
     if (health === 'healthy')
         return 'healthy';
@@ -868,4 +1021,43 @@ function mapInspectHealth(health) {
  * demand — a refused port bind, an OOM kill.
  */
 export const __test__ = { describeContainerFailure, portArg };
+/** Bounded, read-only host inventory, including unmanaged containers that can conflict with a plan. */
+let pendingDockerInventory;
+export async function readDockerInventory() {
+    if (pendingDockerInventory)
+        return pendingDockerInventory;
+    pendingDockerInventory = inspectDockerInventory();
+    try {
+        return await pendingDockerInventory;
+    }
+    finally {
+        pendingDockerInventory = undefined;
+    }
+}
+async function inspectDockerInventory() {
+    const { execFile } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const run = promisify(execFile);
+    const read = async (args) => (await run('docker', args, { encoding: 'utf8', timeout: 15_000, maxBuffer: 16 * 1024 * 1024 })).stdout;
+    const [ids, images, volumes] = await Promise.all([
+        read(['ps', '-aq']), read(['image', 'ls', '--no-trunc', '--digests', '--format', '{{json .}}']),
+        read(['volume', 'ls', '--format', '{{.Name}}']),
+    ]);
+    const names = ids.trim().split('\n').filter(Boolean);
+    const inspected = names.length ? await inspectContainers(names, true) : [];
+    if (inspected.length !== names.length)
+        throw new Error('Incomplete Docker snapshot');
+    return {
+        containers: inspected.map(info => ({
+            name: String(info.Name).replace(/^\//, ''), running: info.State?.Running === true,
+            health: info.State?.Health?.Status, labels: info.Config?.Labels ?? {},
+            ports: Object.values(info.NetworkSettings?.Ports ?? {}).flatMap(bindings => (Array.isArray(bindings) ? bindings : []).map(binding => ({ host: Number(binding.HostPort), bindHost: String(binding.HostIp) }))),
+        })),
+        images: images.trim().split('\n').filter(Boolean).flatMap(line => {
+            const image = JSON.parse(line);
+            return [String(image.ID), `${image.Repository}:${image.Tag}`, `${image.Repository}@${image.Digest}`];
+        }),
+        volumes: volumes.trim().split('\n').filter(Boolean),
+    };
+}
 //# sourceMappingURL=container-runtime.js.map