@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/environment/repository-identity.d.ts

@@ -0,0 +1,13 @@
+export interface RepositoryIdentity {
+    readonly host: string;
+    readonly owner: string;
+    readonly repository: string;
+}
+export type RepositoryIdentityResult = Readonly<{
+    kind: 'known';
+    identity: Readonly<RepositoryIdentity>;
+}> | Readonly<{
+    kind: 'unknown';
+    reason: 'credentialed' | 'malformed' | 'unbounded' | 'unsupported';
+}>;
+export declare function repositoryIdentity(value: unknown): RepositoryIdentityResult;

package/dist/environment/repository-identity.js

@@ -0,0 +1,108 @@
+const INPUT_LIMIT_BYTES = 2_048;
+const PATH_SEGMENT_LIMIT = 32;
+const PATH_SEGMENT_LIMIT_BYTES = 255;
+const SAFE_PATH_SEGMENT = /^[A-Za-z0-9._-]+$/;
+const SAFE_HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+function unknown(reason) {
+    return { kind: 'unknown', reason };
+}
+function normalizedHost(value) {
+    const host = value.toLowerCase().replace(/\.$/, '');
+    if (host.length === 0 || Buffer.byteLength(host) > 253)
+        return undefined;
+    const labels = host.split('.');
+    if (labels.every((label) => /^(?:\d+|0x[0-9a-f]+)$/.test(label))) {
+        if (labels.length !== 4 || labels.some((label) => !/^(?:0|[1-9]\d{0,2})$/.test(label) || Number(label) > 255)) {
+            return undefined;
+        }
+        return host;
+    }
+    if (labels.some((label) => label.length === 0 || label.length > 63 || !SAFE_HOST_LABEL.test(label)))
+        return undefined;
+    return host;
+}
+function known(hostValue, pathValue) {
+    const host = normalizedHost(hostValue);
+    const path = pathValue.startsWith('/') ? pathValue.slice(1) : pathValue;
+    if (!host || path.length === 0 || path.startsWith('/') || path.endsWith('/') || path.includes('//')) {
+        return unknown('malformed');
+    }
+    const segments = path.split('/');
+    if (segments.length > PATH_SEGMENT_LIMIT)
+        return unknown('malformed');
+    if (segments.some((segment) => segment === '.' || segment === '..' || !SAFE_PATH_SEGMENT.test(segment))) {
+        return unknown('malformed');
+    }
+    let repository = segments.pop();
+    if (repository.endsWith('.git'))
+        repository = repository.slice(0, -4);
+    if (repository.length === 0 || repository === '.' || repository === '..')
+        return unknown('malformed');
+    if ([...segments, repository].some((segment) => Buffer.byteLength(segment) > PATH_SEGMENT_LIMIT_BYTES)) {
+        return unknown('unbounded');
+    }
+    const identity = { host, owner: segments.join('/'), repository };
+    return { kind: 'known', identity };
+}
+function urlIdentity(value, scheme) {
+    if (scheme !== 'https' && scheme !== 'ssh')
+        return unknown('unsupported');
+    const authorityStart = scheme.length + 3;
+    if (value.length === authorityStart || value[authorityStart] === '/')
+        return unknown('malformed');
+    const remainder = value.slice(authorityStart);
+    const pathStart = remainder.indexOf('/');
+    if (pathStart < 1)
+        return unknown('malformed');
+    const authority = remainder.slice(0, pathStart);
+    const path = remainder.slice(pathStart);
+    const at = authority.indexOf('@');
+    if (at === 0 || at !== authority.lastIndexOf('@'))
+        return unknown('malformed');
+    let hostAndPort = authority;
+    if (at > 0) {
+        const username = authority.slice(0, at);
+        if (scheme === 'https' || username !== 'git')
+            return unknown('credentialed');
+        hostAndPort = authority.slice(at + 1);
+    }
+    const colon = hostAndPort.indexOf(':');
+    let host = hostAndPort;
+    if (colon >= 0) {
+        if (colon !== hostAndPort.lastIndexOf(':'))
+            return unknown('unsupported');
+        host = hostAndPort.slice(0, colon);
+        const port = hostAndPort.slice(colon + 1);
+        if (host.length === 0 || port.length === 0)
+            return unknown('malformed');
+        if (port !== (scheme === 'https' ? '443' : '22'))
+            return unknown('unsupported');
+    }
+    return known(host, path);
+}
+export function repositoryIdentity(value) {
+    if (typeof value !== 'string')
+        return unknown('malformed');
+    if (Buffer.byteLength(value) > INPUT_LIMIT_BYTES)
+        return unknown('unbounded');
+    if (value.length === 0 || /[\s\x00-\x1f\x7f]/u.test(value) || /[%?#]/.test(value))
+        return unknown('malformed');
+    if (/^[A-Za-z]:/.test(value) || /^[./~\\]/.test(value))
+        return unknown('unsupported');
+    if (value.includes('\\'))
+        return unknown('malformed');
+    if (/(?:^|\/)\.{1,2}(?:\/|$)/.test(value))
+        return unknown('malformed');
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//.exec(value);
+    if (scheme)
+        return urlIdentity(value, scheme[1].toLowerCase());
+    const scp = /^(?:([^@/:]+)@)?([^@/:]+):(.+)$/.exec(value);
+    if (!scp)
+        return unknown('malformed');
+    const [, username, host, path] = scp;
+    if (username !== undefined && username !== 'git')
+        return unknown('credentialed');
+    if (path.startsWith('/'))
+        return unknown('malformed');
+    return known(host, path);
+}

package/dist/environment/runtime-measurement-record.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+declare const Row: z.ZodObject<{
+    runtime: z.ZodString;
+    daemon: z.ZodString;
+    engineVersion: z.ZodString;
+    composeFloor: z.ZodString;
+    measuredOn: z.ZodString;
+}, z.core.$strict>;
+/** One passing measurement: the runtime product, the daemon `docker info` named, its engine version and the Compose floor. */
+export type RuntimeMeasurementRow = Readonly<z.infer<typeof Row>>;
+export type LocalRuntimeMeasurements = Readonly<{
+    kind: 'read';
+    path: string;
+    rows: readonly RuntimeMeasurementRow[];
+}> | Readonly<{
+    kind: 'unreadable';
+    path: string;
+    reason: string;
+}>;
+/** Read the rows; a missing file is an empty record, anything else unreadable names why. */
+export declare function readLocalRuntimeMeasurements(stateRoot: string): Promise<LocalRuntimeMeasurements>;
+export type RecordResult = Readonly<{
+    kind: 'complete';
+    path: string;
+    replaced: RuntimeMeasurementRow | null;
+    discardedUnreadable: string | null;
+}> | Readonly<{
+    kind: 'refusal';
+    path: string;
+    reason: string;
+}>;
+/**
+ * Record one passing measurement, replacing the row for the same runtime and daemon. A record that
+ * cannot be read is replaced too, because every row in it is re-derivable by measuring, and the
+ * result says so; refusing would leave an agent no way forward.
+ */
+export declare function recordLocalRuntimeMeasurement(stateRoot: string, row: RuntimeMeasurementRow): Promise<RecordResult>;
+export {};

package/dist/environment/runtime-measurement-record.js

@@ -0,0 +1,111 @@
+import { errorCause, hasErrorCode } from './contract.js';
+/**
+ * Owns this machine's runtime measurements: `machine/runtime-measurements.json` under the per-user
+ * state root, one row per measured runtime. A row is keyed by the runtime product, the daemon
+ * `docker info` names and the engine version, and says nothing about a checkout, so every checkout
+ * and git worktree of every cockpit on this machine shares it; a different runtime, daemon or
+ * engine matches no row and is refused until it is measured. It is not something the team declares,
+ * so it is not in cockpit.toml: teammates on different runtimes would overwrite each other's rows,
+ * and recording one would change guarded configuration that only a human `sync` accepts.
+ *
+ * It reads and writes the file and nothing else: `runtime-measurement.ts` produces rows and
+ * `runtime.ts` decides whether a row admits the observed runtime.
+ */
+import { randomBytes } from 'node:crypto';
+import { lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { readBoundedInput } from '../config/load.js';
+const MEASUREMENTS_PATH = 'machine/runtime-measurements.json';
+const FORMAT = 'cockpit-runtime-measurements/v1';
+const ROW_LIMIT = 32;
+const Text = z.string().min(1).max(128).regex(/^[^\u0000-\u001f\u007f]+$/);
+const Row = z.object({
+    runtime: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    daemon: Text,
+    engineVersion: Text,
+    composeFloor: z.string().regex(/^\d+\.\d+\.\d+$/),
+    measuredOn: z.string().date(),
+}).strict();
+const MeasurementFile = z.object({ format: z.literal(FORMAT), measurements: z.array(Row).max(ROW_LIMIT) }).strict();
+/** Read the rows; a missing file is an empty record, anything else unreadable names why. */
+export async function readLocalRuntimeMeasurements(stateRoot) {
+    const path = join(stateRoot, MEASUREMENTS_PATH);
+    let bytes;
+    try {
+        const read = await readBoundedInput(path);
+        if (read.kind !== 'complete')
+            return { kind: 'unreadable', path, reason: 'the file is larger than cockpit reads' };
+        bytes = read.bytes;
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return { kind: 'read', path, rows: [] };
+        return { kind: 'unreadable', path, reason: `the file could not be read (${errorCause(error)})` };
+    }
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch { // Parser text would quote the file; the reason names the two ways it fails.
+        return { kind: 'unreadable', path, reason: 'the file is not UTF-8 JSON' };
+    }
+    const parsed = MeasurementFile.safeParse(value);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        return { kind: 'unreadable', path,
+            reason: `the file is not a ${FORMAT} record (${issue ? `${issue.path.join('.') || 'record'}: ${issue.message}` : 'invalid'})` };
+    }
+    return { kind: 'read', path, rows: parsed.data.measurements.map((row) => row) };
+}
+async function plainDirectory(path) {
+    try {
+        const status = await lstat(path);
+        return status.isDirectory() && !status.isSymbolicLink() ? 'present' : `${path} is not a plain directory`;
+    }
+    catch (error) {
+        return hasErrorCode(error, 'ENOENT') ? 'absent' : `${path} is unavailable (${errorCause(error)})`;
+    }
+}
+// Rename replaces a planted symlink at the destination instead of writing through it.
+async function replaceFile(directory, name, bytes) {
+    const temporary = join(directory, `.${name}.${randomBytes(8).toString('hex')}.tmp`);
+    try {
+        await writeFile(temporary, bytes, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, join(directory, name));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/**
+ * Record one passing measurement, replacing the row for the same runtime and daemon. A record that
+ * cannot be read is replaced too, because every row in it is re-derivable by measuring, and the
+ * result says so; refusing would leave an agent no way forward.
+ */
+export async function recordLocalRuntimeMeasurement(stateRoot, row) {
+    const path = join(stateRoot, MEASUREMENTS_PATH);
+    const checked = Row.safeParse(row);
+    if (!checked.success)
+        return { kind: 'refusal', path, reason: `the measurement row is malformed (${checked.error.issues[0]?.message ?? 'invalid'})` };
+    try {
+        const directory = join(stateRoot, 'machine');
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const state = await plainDirectory(directory);
+        if (state !== 'present')
+            return { kind: 'refusal', path, reason: state };
+        const current = await readLocalRuntimeMeasurements(stateRoot);
+        const existing = current.kind === 'read' ? current.rows : [];
+        const replaced = existing.find((candidate) => candidate.runtime === row.runtime && candidate.daemon === row.daemon) ?? null;
+        const kept = existing.filter((candidate) => candidate !== replaced);
+        if (kept.length >= ROW_LIMIT) {
+            return { kind: 'refusal', path, reason: `the record already holds ${ROW_LIMIT} other runtimes; remove the ones this machine no longer runs` };
+        }
+        const record = { format: FORMAT, measurements: [...kept, checked.data] };
+        await replaceFile(directory, 'runtime-measurements.json', `${JSON.stringify(record, null, 2)}\n`);
+        return { kind: 'complete', path, replaced, discardedUnreadable: current.kind === 'unreadable' ? current.reason : null };
+    }
+    catch (error) {
+        return { kind: 'refusal', path, reason: `the record could not be written (${errorCause(error)})` };
+    }
+}

package/dist/environment/runtime-measurement.d.ts

@@ -0,0 +1,27 @@
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import type { Diagnostic } from '../diagnostics.js';
+import { type ExecutionStep } from './contract.js';
+import { type RuntimeProbeRequest, type RuntimeProbeVerdict } from './runtime-probe.js';
+export interface RuntimeMeasureInput {
+    readonly configPath: string;
+    readonly image: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export type RuntimeMeasureProbe = (request: Omit<RuntimeProbeRequest, 'installedModule'>) => Promise<RuntimeProbeVerdict>;
+export interface RuntimeMeasureDependencies {
+    readonly execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+    readonly probe: RuntimeMeasureProbe;
+}
+export interface RuntimeMeasureOutcome {
+    readonly status: number;
+    readonly result: unknown;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly artifact?: string | null;
+    readonly destination?: string | null;
+}
+export declare function runRuntimeMeasure(input: RuntimeMeasureInput, dependencies: RuntimeMeasureDependencies): Promise<RuntimeMeasureOutcome>;
+/**
+ * Production probe binding. The probe only certifies itself when it runs from an installed package,
+ * so a source checkout is told that directly instead of failing deep inside the probe.
+ */
+export declare function probeInstalledRuntime(request: Omit<RuntimeProbeRequest, 'installedModule'>): Promise<RuntimeProbeVerdict>;

package/dist/environment/runtime-measurement.js

@@ -0,0 +1,224 @@
+/**
+ * Owns `cockpit runtime measure`: identifies the local container runtime, clears what an earlier
+ * interrupted measure left behind (`runtime-probe-residue.ts`), hands the runtime to the candidate
+ * and broken-control probe (`runtime-probe.ts`), and records a passing verdict as this machine's
+ * measurement through `runtime-measurement-record.ts`. cockpit.toml is only read: a measurement
+ * describes this machine, so recording one changes no guarded configuration.
+ *
+ * It does not admit runtimes (`runtime.ts` reads the rows) and it never spawns a process itself:
+ * every child process crosses the supplied `execute`, which production binds to
+ * `environment-exec/execute.ts`.
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { selectLocalDockerDaemon } from './docker-daemon.js';
+import { authenticatedExecutionOutcome } from '../environment-exec/execute.js';
+import { loadCockpitConfig } from '../config/load.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+import { ENVIRONMENT_CODES } from './contract.js';
+import { declaresNothingToRun, runtimeNotDeclared } from './declaration.js';
+import { resolveDockerExecutable, resolveGitExecutable } from './executable.js';
+import { observeProcessStart, processHost } from './claims.js';
+import { observeDockerRuntime, observedVersionCore } from './runtime.js';
+import { recordLocalRuntimeMeasurement } from './runtime-measurement-record.js';
+import { MEASURE_DIRECTORY_PREFIX, claimMeasureDirectory, sweepProbeResidue } from './runtime-probe-residue.js';
+import { selectMachineStateRoot } from './state.js';
+import { probeRuntimeSupport } from './runtime-probe.js';
+import { refusalOutcome as refused } from '../refusal.js';
+const IMAGE_ID = /^sha256:[a-f0-9]{64}$/;
+const STEP_TIMEOUT_MS = 10_000;
+const PROBE_STEP_TIMEOUT_MS = 30_000;
+function dockerStep(executable, cwd, env, id, args, stdoutLimitBytes = 1_024) {
+    return {
+        id,
+        argv: [executable.canonicalPath, ...args],
+        argv0: executable.invocationPath,
+        cwd, env, timeoutMs: STEP_TIMEOUT_MS,
+        stdoutLimitBytes, stderrLimitBytes: 4_096,
+        paths: [], ports: [],
+        labels: { purpose: id },
+        expected: [],
+        consumedFiles: [{
+                path: executable.canonicalPath, sha256: executable.sha256,
+                maxBytes: 536_870_912, argvIndexes: [0], executable: true,
+                executionMode: executable.executionMode,
+            }],
+        filesystemChecks: [],
+        compensation: [],
+    };
+}
+async function readDocker(execute, step) {
+    const outcome = authenticatedExecutionOutcome(await execute(step), step);
+    if (!outcome)
+        return { kind: 'failed', detail: 'the execution outcome could not be authenticated' };
+    let stdout = '';
+    let stderr = '';
+    try {
+        // Docker's final line ending is transport framing; trimming would rewrite endpoint identity.
+        stdout = new TextDecoder('utf-8', { fatal: true }).decode(outcome.stdout).replace(/\r?\n$/, '');
+        stderr = new TextDecoder('utf-8', { fatal: true }).decode(outcome.stderr).trim();
+    }
+    catch {
+        return { kind: 'failed', detail: 'docker wrote output that is not UTF-8' };
+    } // Fatal decoding throws only for invalid UTF-8, which the detail names.
+    if (outcome.kind !== 'complete') {
+        return { kind: 'failed', detail: `${outcome.code}${stderr ? `: ${stderr.split('\n', 1)[0].slice(0, 256)}` : ''}` };
+    }
+    return { kind: 'complete', text: stdout };
+}
+export async function runRuntimeMeasure(input, dependencies) {
+    const loaded = await loadCockpitConfig(input.configPath);
+    if (loaded.kind !== 'complete')
+        return { status: 2, result: null, diagnostics: loaded.diagnostics };
+    const configPath = loaded.result.source.path;
+    const config = loaded.result.config;
+    if (declaresNothingToRun(config.environment))
+        return { status: 2, result: null,
+            diagnostics: [runtimeNotDeclared(configPath)] };
+    if (input.image.length === 0 || input.image.length > 256 || input.image.startsWith('-') || /[\s\u0000-\u001f\u007f]/.test(input.image)) {
+        return refused('CLI_USAGE_INVALID', '--image must name one local image reference or ID', '--image');
+    }
+    // Refuse a remote daemon before minutes of probing, and measure exactly the daemon `up` will
+    // reach: a local DOCKER_HOST as given, otherwise the context DOCKER_CONTEXT names or the active
+    // one, pinned by name for every later step so a `docker context use` mid-run cannot move the
+    // measurement to another daemon. cockpit's owners hand Docker no HOME, so a pinned name
+    // resolves through the operator's own context store, as it does for `up`. The context is pinned
+    // by name, not as its endpoint in DOCKER_HOST: that would leave down and reset inside the probe
+    // resolving the "default" context instead.
+    const daemon = await selectLocalDockerDaemon(input.env, STEP_TIMEOUT_MS, dependencies.execute, {
+        command: 'runtime measure', localOnly: 'a measurement describes this machine, which a remote daemon says nothing about'
+    });
+    if (daemon.kind === 'refusal')
+        return { status: 2, result: null, artifact: null, destination: null, diagnostics: [daemon.diagnostic] };
+    // Where the measurement is recorded: the per-user root every checkout of this machine shares.
+    if (process.platform !== 'darwin' && process.platform !== 'linux')
+        return refused(ENVIRONMENT_CODES.STATE_ROOT_UNAVAILABLE, 'runtime measurements are recorded on macOS or Linux only', process.platform);
+    const stateRoot = await selectMachineStateRoot({ platform: process.platform, home: input.env.HOME, xdgStateHome: input.env.XDG_STATE_HOME });
+    if (stateRoot.kind !== 'complete')
+        return refused(stateRoot.kind === 'refusal' ? stateRoot.code : ENVIRONMENT_CODES.STATE_ROOT_UNAVAILABLE, stateRoot.kind === 'refusal' ? stateRoot.message : 'the state root is unavailable', stateRoot.kind === 'refusal' ? stateRoot.target : 'state root');
+    const path = input.env.PATH ?? '';
+    const [docker, git] = await Promise.all([resolveDockerExecutable(input.env), resolveGitExecutable(input.env)]);
+    if (docker.state !== 'available')
+        return refused(ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE, docker.reason, 'docker');
+    if (git.state !== 'available')
+        return refused(ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE, git.reason, 'git');
+    const cwd = dirname(configPath);
+    const runtimeEnv = { PATH: path,
+        ...(input.env.DOCKER_HOST === undefined ? { DOCKER_CONTEXT: daemon.dockerContext } : { DOCKER_HOST: input.env.DOCKER_HOST }) };
+    const observed = await observeDockerRuntime({ executable: docker.value, cwd, env: runtimeEnv, timeoutMs: STEP_TIMEOUT_MS }, dependencies.execute);
+    if (observed.kind !== 'complete')
+        return refused(observed.code, observed.reason, 'docker', observed.fix);
+    const identity = observed.runtimeIdentity;
+    if (identity === null) {
+        return refused(ENVIRONMENT_CODES.RUNTIME_UNMEASURED, `Docker runtime is not a recognised product, so no measurement can apply (docker info: OperatingSystem ${JSON.stringify(observed.operatingSystem)}, `
+            + `Name ${JSON.stringify(observed.name)}, OSType ${JSON.stringify(observed.osType)}; host ${observed.hostPlatform}). `
+            + 'Report these docker info values to the cockpit maintainers so the runtime can be identified', 'docker info');
+    }
+    const image = await readDocker(dependencies.execute, dockerStep(docker.value, cwd, runtimeEnv, 'runtime:measure:image', ['image', 'inspect', input.image, '--format', '{{.Id}}']));
+    if (image.kind !== 'complete' || !IMAGE_ID.test(image.text)) {
+        // The runtime answered, so the remedy is the image, not the runtime.
+        return { status: 2, result: null, artifact: null, destination: null, diagnostics: [{
+                    severity: 'error',
+                    code: ENVIRONMENT_CODES.RUNTIME_IMAGE_UNAVAILABLE,
+                    message: `--image ${JSON.stringify(input.image)} is not a local image (${image.kind === 'complete' ? 'unexpected image ID' : image.detail}); the probe never pulls`,
+                    target: '--image',
+                    fix: 'pull or build it first (docker pull <image>), then run npx --no cockpit runtime measure --config <your cockpit.toml> --image <image> again',
+                }] };
+    }
+    // The floor is the numeric core; a vendor suffix such as `-desktop.1` is evidence, not a floor.
+    // A complete observation has already refused a version without one.
+    const composeFloor = observedVersionCore(observed.composeVersion);
+    const measuredOn = new Date().toISOString().slice(0, 10);
+    // The probe requires an empty canonical directory and creates its isolated HOME beside it, so
+    // both live under one private parent that is removed whatever the verdict.
+    const parent = await realpath(await mkdtemp(join(tmpdir(), MEASURE_DIRECTORY_PREFIX)));
+    let verdict;
+    let swept;
+    try {
+        // The probe's resources and this directory name this process, so a later measure can tell
+        // whether it still runs. Without a readable start only the pid is named, and its resources
+        // are then removed only once that pid is gone.
+        const host = processHost(dependencies.execute);
+        const self = await observeProcessStart(process.pid, host);
+        const owner = self.state === 'present' ? `${process.pid}@${self.start}` : String(process.pid);
+        await claimMeasureDirectory(parent, owner);
+        // A measure killed mid-probe leaves containers, a network, a volume and this directory
+        // behind; clear this cockpit's own before adding another set to a shared daemon.
+        swept = await sweepProbeResidue({
+            observe: (pid) => observeProcessStart(pid, host),
+            projectPrefix: config.cockpit.name.slice(0, 40), temporaryDirectory: dirname(parent), ownDirectory: parent,
+            run: (id, args) => readDocker(dependencies.execute, dockerStep(docker.value, cwd, runtimeEnv, id, args, 65_536)),
+            ...(process.getuid === undefined ? {} : { uid: process.getuid() }),
+        });
+        if (swept.kind === 'refusal')
+            return refused(ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE, `${swept.reason}${swept.removed.length > 0 ? ` (already removed: ${swept.removed.join(', ')})` : ''}; nothing was probed`, 'docker');
+        const probeRoot = join(parent, 'probe');
+        await mkdir(probeRoot, { mode: 0o700 });
+        verdict = await dependencies.probe({
+            executable: docker.value, gitExecutable: git.value, cwd: probeRoot, projectPrefix: config.cockpit.name.slice(0, 40), owner,
+            env: { ...runtimeEnv, ...(input.env.TMPDIR === undefined ? {} : { TMPDIR: input.env.TMPDIR }) },
+            composeFloor, measuredOn, timeoutMs: PROBE_STEP_TIMEOUT_MS,
+            image: { reference: image.text, id: image.text },
+        });
+    }
+    finally {
+        await rm(parent, { recursive: true, force: true });
+    }
+    const evidence = verdict.evidence;
+    const summary = {
+        runtime: identity, dockerInfo: { operatingSystem: observed.operatingSystem, name: observed.name, osType: observed.osType },
+        endpoint: { value: daemon.endpoint, source: daemon.source },
+        image: image.text, candidate: verdict.candidate, brokenControl: verdict.brokenControl,
+        checks: evidence?.candidateChecks ?? null,
+        removedLeftovers: swept.removed, leftUntouched: swept.left,
+    };
+    if (verdict.status !== 'supported' || verdict.candidate !== 'passed' || verdict.brokenControl !== 'rejected') {
+        return { ...refused(verdict.operatorAction?.code ?? ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE, `runtime ${identity} was not measured as supported (candidate ${verdict.candidate}, broken control ${verdict.brokenControl}): `
+                + `${verdict.operatorAction?.reason ?? 'no reason was reported'}; nothing was recorded`, identity), result: summary };
+    }
+    // The probe observes the runtime again; a different daemon or Compose answering it would make
+    // this row describe something other than the identity read above.
+    if (evidence === null || evidence.runtimeVersion !== observed.runtime.version || evidence.composeVersion !== observed.composeVersion
+        || evidence.runtimeExecutableSha256 !== docker.value.sha256) {
+        return { ...refused(ENVIRONMENT_CODES.RUNTIME_UNMEASURED, `the probe measured a different runtime than ${identity} ${observed.runtime.version} with Compose ${observed.composeVersion}; nothing was recorded`, identity), result: summary };
+    }
+    const row = { runtime: identity, daemon: observed.name, engineVersion: observed.runtime.version,
+        composeFloor, measuredOn };
+    const recorded = await recordLocalRuntimeMeasurement(stateRoot.value, row);
+    if (recorded.kind === 'refusal') {
+        return { ...refused(ENVIRONMENT_CODES.RUNTIME_UNMEASURED, `runtime ${identity} passed, but this machine's measurement could not be recorded in ${recorded.path}: ${recorded.reason}`, recorded.path),
+            result: { ...summary, row, recorded: false } };
+    }
+    const notes = [
+        ...(swept.removed.length === 0 ? [] : [`removed what an interrupted measure left behind: ${swept.removed.join('; ')}`]),
+        ...(swept.left.length === 0 ? [] : [`left in place, since a measure may still be running: ${swept.left.join('; ')}`]),
+        `runtime ${identity} on daemon ${JSON.stringify(observed.name)} passed with engine ${row.engineVersion}; recorded with Compose floor ${composeFloor} in ${recorded.path}, shared by every checkout on this machine`,
+        ...(recorded.replaced === null ? [] : [`it replaces the measurement from ${recorded.replaced.measuredOn} (engine ${recorded.replaced.engineVersion})`]),
+        ...(recorded.discardedUnreadable === null ? [] : [`the previous record was unreadable and was replaced: ${recorded.discardedUnreadable}`]),
+        `${basename(configPath)} is unchanged; next: ${cockpitCommand('up', { config: configPath })}`,
+    ];
+    return { status: 0, result: { ...summary, row, recorded: true, path: recorded.path }, destination: null,
+        artifact: `${notes.join('\n')}\n`, diagnostics: [] };
+}
+/**
+ * Production probe binding. The probe only certifies itself when it runs from an installed package,
+ * so a source checkout is told that directly instead of failing deep inside the probe.
+ */
+export async function probeInstalledRuntime(request) {
+    const modulePath = fileURLToPath(new URL('./runtime-probe.js', import.meta.url));
+    const canonicalPath = await realpath(modulePath);
+    const installedSuffix = ['node_modules', '@b00dea', 'cockpit', 'dist', 'environment', 'runtime-probe.js'].join(sep);
+    if (!canonicalPath.endsWith(`${sep}${installedSuffix}`)) {
+        return {
+            status: 'unavailable', runtime: null, composeVersion: null, composeFloor: request.composeFloor, measuredOn: request.measuredOn,
+            candidate: 'failed', brokenControl: 'inconclusive', evidence: null,
+            operatorAction: { required: true, code: ENVIRONMENT_CODES.RUNTIME_UNAVAILABLE,
+                reason: `runtime measurement runs only from an installed @b00dea/cockpit package, and this cockpit runs from ${dirname(canonicalPath)}; install the package and use its cockpit binary` },
+        };
+    }
+    const sha256 = createHash('sha256').update(await readFile(canonicalPath)).digest('hex');
+    return probeRuntimeSupport({ ...request, installedModule: { canonicalPath, sha256 } });
+}

package/dist/environment/runtime-probe-residue.d.ts

@@ -0,0 +1,43 @@
+import { type ProcessStartObservation } from './claims.js';
+export declare const MEASURE_DIRECTORY_PREFIX = "cockpit-runtime-measure-";
+/** Names the measure process that created a probe resource, as `<pid>` or `<pid>@<start identity>`. */
+export declare const PROBE_OWNER_LABEL = "dev.b0dea.cockpit.probe-owner";
+/** Run one Docker read or removal; `failed` carries the first line of Docker's complaint. */
+export type ResidueRunner = (id: string, args: readonly string[]) => Promise<Readonly<{
+    kind: 'complete';
+    text: string;
+}> | Readonly<{
+    kind: 'failed';
+    detail: string;
+}>>;
+/** Observe a process's presence and start identity, as `observeProcessStart` does. */
+export type ProcessObserver = (pid: number) => Promise<ProcessStartObservation>;
+export type ProbeResidueOutcome = Readonly<{
+    kind: 'complete';
+    removed: readonly string[];
+    left: readonly string[];
+}> | Readonly<{
+    kind: 'refusal';
+    reason: string;
+    removed: readonly string[];
+}>;
+/** Mark a freshly created measure directory as owned by `owner` (see `PROBE_OWNER_LABEL`), so a later measure can tell it is alive. */
+export declare function claimMeasureDirectory(directory: string, owner: string): Promise<void>;
+export declare function isProbeOwner(owner: string): boolean;
+/**
+ * Remove this cockpit's probe resources left by a dead measure. A resource is the probe's only if
+ * it carries the probe label and a Compose project named `<projectPrefix>-probe-<batch>` (Compose
+ * appends the stack hash) whose batch matches the label, so a different cockpit's probe, or any other stack, is never touched.
+ * It is dead only when the measure its owner label names is provably gone. Liveness is read from
+ * the label on the shared daemon, not from the temp directory: agent tools give each session its
+ * own TMPDIR, so a concurrent measure's directory is invisible, and judging by it removed that
+ * measure's running probe. Anything not provably dead may be running now and is only reported.
+ */
+export declare function sweepProbeResidue(input: Readonly<{
+    projectPrefix: string;
+    temporaryDirectory: string;
+    ownDirectory: string;
+    run: ResidueRunner;
+    observe: ProcessObserver;
+    uid?: number;
+}>): Promise<ProbeResidueOutcome>;