@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/read-composition.js

@@ -0,0 +1,397 @@
+import { createHash } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { loadCockpitConfig, consumeLoadedConfigProjection } from '../config/load.js';
+import {} from './application/health.js';
+import { decodeLifecycleRecord } from './application/lifecycle.js';
+import {} from './application/lifecycle-context.js';
+import {} from './application/logs.js';
+import { publishLifecycleRecord } from './application/lifecycle-state.js';
+import {} from './application/services.js';
+import { createLifecycleCommandAdapters } from './lifecycle-composition.js';
+import { deriveEntrypoints, observeRetainedPortFamily, projectRetainedPortFamilyResult } from './ports.js';
+import { DOCKER_CLIENT_ENVIRONMENT, ENVIRONMENT_CODES, RefusalError } from './contract.js';
+import { loadServedSiblings, servedSiblingVariables } from './sibling-checkouts.js';
+import { DeclarationRefusalError, runtimeNotDeclared, serviceNotDeclared } from './declaration.js';
+import { admitRuntimeServiceHealth, revalidateRuntimeService, } from './runtime.js';
+import { resolveDockerExecutable } from './executable.js';
+import { STABILITY_CAPTURE_OUTPUT_LIMIT_BYTES, authenticateStabilityCapture, captureRuntimeEvidence, createEnvironmentSnapshot, createStabilityCapturePlan, } from './evidence.js';
+import { readState } from './state.js';
+import { readBoundedFile } from '../bounded-read.js';
+const COMPOSE_BYTE_LIMIT = 1_048_576;
+const DEFAULT_OUTPUT_LIMIT = 1_048_576;
+function freezeJson(value) {
+    if (Array.isArray(value))
+        return value.map(freezeJson);
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, freezeJson(child)]));
+    }
+    return value;
+}
+function captureInput(value) {
+    try {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        const required = ['configPath', 'env', 'sessionId', 'timeoutMs'];
+        const optional = ['outputLimitBytes', 'signal', 'runtimeMeasurementProbeAuthority'];
+        const keys = Reflect.ownKeys(descriptors);
+        if (keys.some((key) => typeof key !== 'string' || !required.includes(key) && !optional.includes(key))
+            || required.some((key) => !descriptors[key] || !('value' in descriptors[key]))
+            || keys.some((key) => typeof key === 'string' && !('value' in descriptors[key])))
+            return undefined;
+        const configPath = descriptors.configPath.value;
+        const rawEnvironment = descriptors.env.value;
+        const sessionId = descriptors.sessionId.value;
+        const timeoutMs = descriptors.timeoutMs.value;
+        const outputLimitBytes = descriptors.outputLimitBytes?.value ?? DEFAULT_OUTPUT_LIMIT;
+        const signal = descriptors.signal?.value;
+        const runtimeMeasurementProbeAuthority = descriptors.runtimeMeasurementProbeAuthority?.value;
+        if (typeof configPath !== 'string' || configPath.length === 0 || configPath.includes('\0')
+            || typeof sessionId !== 'string' || sessionId.length === 0 || sessionId.includes('\0')
+            || typeof timeoutMs !== 'number' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000
+            || typeof outputLimitBytes !== 'number' || !Number.isSafeInteger(outputLimitBytes) || outputLimitBytes < 1 || outputLimitBytes > 16_777_216
+            || signal !== undefined && !(signal instanceof AbortSignal)
+            || !rawEnvironment || typeof rawEnvironment !== 'object' || Array.isArray(rawEnvironment))
+            return undefined;
+        const env = {};
+        for (const [name, entry] of Object.entries(rawEnvironment)) {
+            if (name.length === 0 || name.includes('\0') || name.includes('=')
+                || entry !== undefined && (typeof entry !== 'string' || entry.includes('\0')))
+                return undefined;
+            env[name] = entry;
+        }
+        return {
+            configPath: resolve(configPath),
+            env,
+            sessionId,
+            timeoutMs,
+            outputLimitBytes,
+            ...(signal ? { signal } : {}),
+            ...(runtimeMeasurementProbeAuthority === undefined ? {} : { runtimeMeasurementProbeAuthority }),
+        };
+    }
+    catch { // A throwing accessor or proxy trap makes the input malformed; the caller refuses it.
+        return undefined;
+    }
+}
+function runtimeEnvironment(env) {
+    return Object.fromEntries(Object.entries(env)
+        .filter((entry) => DOCKER_CLIENT_ENVIRONMENT.has(entry[0]) && typeof entry[1] === 'string'));
+}
+function confined(root, path) {
+    const relation = relative(root, path);
+    return relation === '' || relation !== '..' && !relation.startsWith(`..${sep}`) && !isAbsolute(relation);
+}
+async function composeArtifact(root, reference) {
+    if (typeof reference !== 'string' || reference.length === 0 || reference.includes('\0'))
+        return undefined;
+    const expected = resolve(root, reference);
+    if (!confined(root, expected))
+        return undefined;
+    try {
+        const canonicalPath = await realpath(expected);
+        if (canonicalPath !== expected)
+            return undefined;
+        const read = readBoundedFile(canonicalPath, COMPOSE_BYTE_LIMIT);
+        if (read.kind !== 'complete')
+            return undefined;
+        const bytes = read.bytes;
+        const source = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        return {
+            reference,
+            canonicalPath,
+            source,
+            sha256: createHash('sha256').update(bytes).digest('hex'),
+        };
+    }
+    catch {
+        // An artifact that cannot be read carries no authority; callers refuse it as unavailable compose artifacts.
+        return undefined;
+    }
+}
+async function composeArtifacts(root, references) {
+    const artifacts = [];
+    for (const reference of references) {
+        const artifact = await composeArtifact(root, reference);
+        if (!artifact)
+            return undefined;
+        artifacts.push(artifact);
+    }
+    return artifacts.length > 0 ? artifacts : undefined;
+}
+function sameSource(left, right) {
+    return left.path === right.path && left.byteLength === right.byteLength && left.sha256 === right.sha256;
+}
+async function authenticateService(topology, service, containerId, execute, signal) {
+    const revalidated = await revalidateRuntimeService({
+        topology, service, expectedContainerId: containerId,
+        execute: (step) => execute(step, signal ? { signal } : undefined),
+    });
+    return revalidated.kind === 'observed' ? admitRuntimeServiceHealth(revalidated.observation) : undefined;
+}
+function exactCompletedTopology(context) {
+    const topologyServices = context.topology.services.map(({ id }) => id).sort();
+    const completedServices = context.lifecycle.completedServices.map(({ service }) => service).sort();
+    return topologyServices.length === completedServices.length
+        && topologyServices.every((service, index) => service === completedServices[index]);
+}
+export function createReadCommandAdapters(rawInput, execute, executeForeground) {
+    const input = captureInput(rawInput);
+    // `refuse` receives the lifecycle's own refusal, such as an unmeasured runtime, so a caller can
+    // report it instead of a generic unavailable context.
+    // A service verb may act on a stack whose start stopped part-way: rebuilding the service that
+    // failed is how its fixed code gets running. Every other reader needs a started service.
+    const prepare = async (signal, refuse, partial = false) => {
+        if (!input || typeof execute !== 'function')
+            throw new RefusalError('read command composition is unavailable');
+        const lifecycle = createLifecycleCommandAdapters({
+            configPath: input.configPath,
+            env: input.env,
+            sessionId: input.sessionId,
+            timeoutMs: input.timeoutMs,
+            ...(input.runtimeMeasurementProbeAuthority === undefined ? {} : {
+                runtimeMeasurementProbeAuthority: input.runtimeMeasurementProbeAuthority,
+            }),
+        }, (step) => execute(step, signal ? { signal } : undefined));
+        const loaded = await lifecycle.load({ configPath: input.configPath });
+        if (loaded.kind === 'refusal' && loaded.diagnostics.some(({ code }) => code === ENVIRONMENT_CODES.ENVIRONMENT_NOT_DECLARED)) {
+            throw new DeclarationRefusalError(runtimeNotDeclared(input.configPath));
+        }
+        if (loaded.kind !== 'complete') {
+            if (refuse && loaded.diagnostics.length > 0)
+                refuse(loaded.diagnostics);
+            throw new RefusalError('authenticated lifecycle context is unavailable');
+        }
+        const context = loaded.result;
+        const configurationResult = await loadCockpitConfig(input.configPath);
+        if (configurationResult.kind !== 'complete')
+            throw new RefusalError('configuration projection is unavailable');
+        const configuration = consumeLoadedConfigProjection(configurationResult.result);
+        if (!configuration || !sameSource(context.source, configuration.source)) {
+            throw new RefusalError('configuration authority does not match');
+        }
+        const checkoutRoot = dirname(configuration.source.path);
+        const references = configuration.config.environment.compose_files;
+        const composeFiles = await composeArtifacts(checkoutRoot, references);
+        if (!composeFiles)
+            throw new RefusalError('compose artifacts are unavailable');
+        const retained = await observeRetainedPortFamily({ namespace: context.namespace, stackId: context.stackId,
+            holderId: context.holderId, checkoutId: context.checkoutId, config: context.ports });
+        if (retained.kind !== 'complete')
+            throw new RefusalError('retained port authority is unavailable');
+        const entrypoints = deriveEntrypoints({ lease: retained.lease, declarations: context.entrypointDerivatives });
+        const ports = await projectRetainedPortFamilyResult({ retainedResult: retained, entrypointResult: entrypoints });
+        if (!ports)
+            throw new RefusalError('retained port projection is unavailable');
+        const readiness = await lifecycle.withRuntimeReadiness(context, async (value) => value, ports, refuse);
+        if (!readiness)
+            throw new RefusalError('authenticated runtime topology is unavailable');
+        if (readiness.topology.cwd !== checkoutRoot
+            || readiness.topology.stackId !== context.stackId
+            || readiness.topology.configSha256 !== context.runtimeSha256) {
+            throw new RefusalError('configuration and runtime authority do not match');
+        }
+        const lifecycleRead = await readState(context.namespace.paths.lifecycle(context.stackId));
+        if (lifecycleRead.kind !== 'complete')
+            throw new RefusalError('lifecycle state is unavailable');
+        const lifecycleValue = decodeLifecycleRecord(lifecycleRead.value, context)?.value;
+        if (!lifecycleValue)
+            throw new RefusalError('lifecycle state is malformed');
+        if (lifecycleValue.teardownComplete)
+            throw new RefusalError('down removed the stack');
+        if (lifecycleValue.completedServices.length === 0 && !partial)
+            throw new RefusalError('lifecycle state is malformed');
+        if (lifecycleValue.holderId !== context.holderId)
+            throw new RefusalError('lifecycle holder authority changed');
+        const env = runtimeEnvironment(input.env);
+        const executable = await resolveDockerExecutable(input.env);
+        if (executable.state !== 'available') {
+            throw new RefusalError(`runtime executable authority changed: ${executable.reason}`);
+        }
+        if (executable.value.sha256 !== readiness.topology.executableSha256) {
+            throw new RefusalError('runtime executable authority changed');
+        }
+        const confirmedComposeFiles = await composeArtifacts(checkoutRoot, references);
+        if (!confirmedComposeFiles || JSON.stringify(confirmedComposeFiles) !== JSON.stringify(composeFiles)) {
+            throw new RefusalError('compose artifacts changed during runtime observation');
+        }
+        // The stack interpolates the checkout `use` recorded, so reading it must name the same one.
+        const served = await loadServedSiblings(checkoutRoot, configuration.config);
+        if (served.kind === 'refusal')
+            throw new RefusalError(served.diagnostic.message);
+        const ownComposeAuthority = {
+            ownComposeFiles: true,
+            cockpitId: context.cockpitId,
+            stackId: context.stackId,
+            portLeaseProjection: ports,
+            siblingDirectories: servedSiblingVariables(configuration.config, served.siblings),
+        };
+        return {
+            run: context,
+            ownComposeAuthority,
+            configuration,
+            namespace: context.namespace,
+            cockpitId: context.cockpitId,
+            stackId: context.stackId,
+            holderId: context.holderId,
+            topology: readiness.topology,
+            lifecycleRecord: lifecycleRead.value,
+            lifecycle: lifecycleValue,
+            executable,
+            composeFiles,
+            env,
+        };
+    };
+    const observeLogs = async (request) => {
+        if (!input || resolve(request.configPath) !== input.configPath)
+            throw new RefusalError('log configuration path does not match');
+        const context = await prepare(input.signal, (diagnostics) => { throw new DeclarationRefusalError(diagnostics[0]); });
+        const declared = context.topology.services.map(({ id }) => id);
+        if (!declared.includes(request.service))
+            throw new DeclarationRefusalError(serviceNotDeclared(request.service, declared));
+        const completed = context.lifecycle.completedServices.find(({ service }) => service === request.service);
+        if (!completed) {
+            throw new RefusalError('requested service is not in the selected running stack');
+        }
+        const evidence = await authenticateService(context.topology, completed.service, completed.containerId, execute, input.signal);
+        if (!evidence)
+            throw new RefusalError('requested service identity is unavailable');
+        const after = await readState(context.namespace.paths.lifecycle(context.stackId));
+        if (after.kind !== 'complete' || JSON.stringify(after.value) !== JSON.stringify(context.lifecycleRecord)) {
+            throw new RefusalError('lifecycle state changed during log observation');
+        }
+        return {
+            ownComposeAuthority: context.ownComposeAuthority,
+            request: {
+                runtime: 'docker-compose',
+                executable: context.executable.value,
+                cwd: context.topology.cwd,
+                stackId: context.stackId,
+                configSha256: context.configuration.runtimeSha256,
+                batchId: context.topology.batchId,
+                containerId: evidence.containerId,
+                runtimeVersion: context.topology.runtimeVersion,
+                composeVersion: context.topology.composeVersion,
+                projectName: context.topology.projectName,
+                composeFiles: context.composeFiles,
+                services: context.topology.services.map(({ id }) => id),
+                service: request.service,
+                timeoutMs: input.timeoutMs,
+                outputLimitBytes: input.outputLimitBytes,
+                env: context.env,
+            },
+        };
+    };
+    const observeEnvironment = async (request) => {
+        if (!input || resolve(request.configPath) !== input.configPath)
+            throw new RefusalError('environment configuration path does not match');
+        const context = await prepare();
+        if (!exactCompletedTopology(context)) {
+            throw new RefusalError('a complete stable runtime cohort is unavailable');
+        }
+        let evidenceSubject;
+        for (const completed of context.lifecycle.completedServices) {
+            const service = await authenticateService(context.topology, completed.service, completed.containerId, execute);
+            if (!service)
+                throw new RefusalError('runtime service cohort changed');
+            evidenceSubject = service;
+        }
+        if (!evidenceSubject)
+            throw new RefusalError('runtime evidence subject is unavailable');
+        const createdAt = new Date().toISOString();
+        const capturePlan = createStabilityCapturePlan({
+            stackId: context.stackId,
+            configSha256: context.configuration.runtimeSha256,
+            runtimeExecutable: context.executable.value,
+            cwd: context.topology.cwd,
+            env: Object.fromEntries(Object.entries(context.env).filter(([name]) => name === 'PATH')),
+            containerId: evidenceSubject.containerId,
+            batchId: context.topology.batchId,
+            runtime: { name: 'docker', version: context.topology.runtimeVersion },
+            contentPaths: ['/proc/1/exe'],
+            timeoutMs: input.timeoutMs,
+            outputLimitBytes: STABILITY_CAPTURE_OUTPUT_LIMIT_BYTES,
+        });
+        if (capturePlan.kind !== 'preview' || capturePlan.plan.steps.length !== 2) {
+            const reason = capturePlan.diagnostics.map(({ message }) => message).join('; ');
+            throw new RefusalError(`runtime evidence capture plan is unavailable: ${reason || 'the plan does not hold two capture steps'}`);
+        }
+        const results = [];
+        for (const step of capturePlan.plan.steps)
+            results.push(await execute(step));
+        const authenticated = authenticateStabilityCapture({
+            plan: capturePlan,
+            results: results,
+        });
+        if ('state' in authenticated) {
+            throw new RefusalError(`runtime evidence capture is unavailable: ${authenticated.reason} (${authenticated.code})`);
+        }
+        const evidence = captureRuntimeEvidence({ capture: authenticated });
+        if (evidence.state !== 'available')
+            throw new RefusalError(`runtime evidence is unavailable: ${evidence.reason}`);
+        const after = await readState(context.namespace.paths.lifecycle(context.stackId));
+        if (after.kind !== 'complete' || JSON.stringify(after.value) !== JSON.stringify(context.lifecycleRecord)) {
+            throw new RefusalError('lifecycle state changed during environment observation');
+        }
+        const snapshot = createEnvironmentSnapshot({
+            stackId: context.stackId,
+            configSha256: context.configuration.runtimeSha256,
+            createdAt,
+            creationSource: 'resolved-config',
+            intendedState: context.configuration.config,
+        });
+        const ownedSnapshot = { ...snapshot, intendedState: freezeJson(snapshot.intendedState) };
+        const ownedEvidence = {
+            ...evidence,
+            runtime: { ...evidence.runtime },
+            command: {
+                ...evidence.command,
+                stepIds: [...evidence.command.stepIds],
+            },
+            observedBytes: { ...evidence.observedBytes },
+            stability: { ...evidence.stability },
+        };
+        return { snapshot: ownedSnapshot, evidence: ownedEvidence };
+    };
+    const observeServices = async (request) => {
+        if (!input || resolve(request.configPath) !== input.configPath)
+            throw new RefusalError('service configuration path does not match');
+        const context = await prepare(input.signal, (diagnostics) => { throw new DeclarationRefusalError(diagnostics[0]); }, true);
+        return {
+            topology: context.topology,
+            completedServices: context.lifecycle.completedServices,
+            // The recorded container is what `up`, `preflight` and `logs` revalidate, so a rebuild that
+            // replaced it updates the record rather than leaving the stack looking broken.
+            recordContainer: async (service, containerId) => {
+                const value = { ...context.lifecycle, completedServices: context.lifecycle.completedServices
+                        .map((row) => row.service === service ? { service, containerId } : row) };
+                const published = await publishLifecycleRecord(context.run, context.lifecycleRecord, value);
+                if ('status' in published)
+                    return published.diagnostics;
+                if (published.kind === 'complete')
+                    return [];
+                return [{ severity: 'error',
+                        code: published.kind === 'missing' ? ENVIRONMENT_CODES.STATE_RECORD_MALFORMED : published.code,
+                        target: context.namespace.paths.lifecycle(context.stackId).path,
+                        message: `the rebuilt container of service ${service} runs, and the stack record could not be updated to it${published.kind === 'missing' ? '' : `: ${published.message}`}`,
+                        fix: 'run npx --no cockpit up --config <your cockpit.toml> to record the running containers again' }];
+            },
+        };
+    };
+    const services = {
+        observe: observeServices,
+        execute: (step) => execute(step, input?.signal ? { signal: input.signal } : undefined),
+        executeForeground: async (planned) => {
+            if (!executeForeground)
+                throw new RefusalError('foreground execution is not bound');
+            return executeForeground(planned, input?.signal ? { signal: input.signal } : {});
+        },
+    };
+    const logs = {
+        observe: observeLogs,
+        execute: (step, options) => execute(step, options),
+        ...(input?.signal ? { signal: input.signal } : {}),
+    };
+    return { logs, services, environment: { observe: observeEnvironment } };
+}

package/dist/environment/readiness-composition.d.ts

@@ -0,0 +1,57 @@
+import { loadCockpitConfig } from '../config/load.js';
+import type { ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import { type EnvironmentDiagnostic, type ExecutionStep } from './contract.js';
+import type { ReadinessReport } from '../readiness.js';
+interface ProjectReadinessInput {
+    /** The cockpit root, where cockpit.toml is or will be written. */
+    readonly root: string;
+    /** Present once cockpit.toml exists; its siblings are the repositories asked. */
+    readonly configPath?: string;
+    /** Repositories observed before cockpit.toml exists. */
+    readonly repositories?: readonly Readonly<{
+        slug: string;
+        root: string;
+    }>[];
+    /** Doctor already names a cockpit root outside Git through its checkout observation. */
+    readonly checkRoot: boolean;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly timeoutMs: number;
+    /** The agent tools init was asked to set up, before cockpit.toml records them. */
+    readonly tools?: readonly string[];
+}
+type LoadedConfigResult = Awaited<ReturnType<typeof loadCockpitConfig>>;
+export declare function inspectProjectReadiness(input: ProjectReadinessInput, execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>, preloaded?: LoadedConfigResult): Promise<readonly EnvironmentDiagnostic[]>;
+/**
+ * init's readiness probes. Before cockpit.toml exists, whether a runtime will be declared is read
+ * from the estate classification: an estate with no runnable product gets a surfaces-only cockpit.
+ */
+export declare function inspectInitReadiness(input: Omit<ProjectReadinessInput, 'env' | 'timeoutMs'> & Readonly<{
+    classification?: string;
+}>, binding: Readonly<{
+    env: ProjectReadinessInput['env'];
+    timeoutMs: number;
+    execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+}>): Promise<Readonly<{
+    state: ReadinessReport['state'];
+    findings: readonly EnvironmentDiagnostic[];
+}>>;
+/**
+ * What the container runtime on this machine offers, measured by the same collector preflight
+ * compares the machine floor with, so init can propose a floor where no Compose limit records one.
+ */
+export declare function measureInitMachine(input: Readonly<{
+    root: string;
+}>, binding: Readonly<{
+    env: ProjectReadinessInput['env'];
+    timeoutMs: number;
+    execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+}>): Promise<Readonly<{
+    kind: 'complete';
+    memoryMb: number;
+    cpus: number;
+    observedAt: string;
+}> | Readonly<{
+    kind: 'unavailable';
+    reason: string;
+}>>;
+export {};

package/dist/environment/readiness-composition.js

@@ -0,0 +1,151 @@
+// Binds the readiness probes no health row covers to the production executor, for doctor and for
+// init: whether the cockpit root is a Git working tree before any cockpit.toml exists, the cockpit's
+// own install and recorded sibling remotes, secret files a repository commits, and root instruction
+// files that leave some agent tool without a repository's instructions. Each finding
+// comes from its owner; this module only chooses which repositories to ask.
+import { lstat } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { loadCockpitConfig } from '../config/load.js';
+import { authenticatedExecutionOutcome } from '../environment-exec/execute.js';
+import { inspectTeamReadiness } from '../team-metadata.js';
+import { guardSearchPathRelativeEntry } from '../guards/protected-locations.js';
+import { DOCKER_CLIENT_ENVIRONMENT, ENVIRONMENT_CODES, snapshotExecutionStep, RefusalError, isMissing } from './contract.js';
+import { resolveDiskCapacityExecutable, resolveDockerExecutable, resolveGitExecutable } from './executable.js';
+import { measureMachineFloor } from './runtime.js';
+import { gitRepositoryRefusal, inspectTrackedSecretFiles } from './git-observation.js';
+import { declaresNothingToRun } from './declaration.js';
+import { inspectSiblingInstructions } from './sibling-instructions.js';
+import { DEFAULT_SURFACE_TOOLS } from '../surfaces/harness-registry.js';
+async function isDirectory(path) {
+    try {
+        return (await lstat(path)).isDirectory();
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+}
+export async function inspectProjectReadiness(input, execute, 
+// A caller that already loaded cockpit.toml hands the result over rather than reading it again.
+preloaded) {
+    // A cockpit.toml that does not load is the finding; its own refusal says what to fix first.
+    const loaded = preloaded ?? (input.configPath === undefined ? undefined : await loadCockpitConfig(input.configPath));
+    if (loaded && loaded.kind !== 'complete')
+        return [];
+    const findings = input.configPath === undefined ? [] : [...await inspectTeamReadiness(input.configPath)];
+    const tools = loaded?.kind === 'complete' ? loaded.result.config.surfaces.tools : input.tools ?? DEFAULT_SURFACE_TOOLS;
+    const refusers = ['codexcli', 'opencode'].filter(tool => tools.includes(tool)).map(tool => tool === 'codexcli' ? 'Codex' : 'OpenCode');
+    // The guard reads the PATH its hook inherits from the harness, which is started from a shell like
+    // this one; while that PATH holds a relative entry it asks before every command.
+    const relativeEntry = guardSearchPathRelativeEntry(input.env.PATH ?? '');
+    if (input.configPath !== undefined && relativeEntry !== null)
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'GUARD_SEARCH_PATH_RELATIVE',
+            message: `PATH holds the relative entry ${JSON.stringify(relativeEntry)}${relativeEntry === '' ? ' (an empty entry is the working directory)' : ''}; an agent harness started with this PATH gets a guard that asks before every command, because a file the agent wrote could run in place of the command${refusers.length > 0 ? `, and ${refusers.join(' and ')} refuse${refusers.length === 1 ? 's' : ''} what it asks about` : ''}`,
+            target: 'PATH',
+            fix: 'remove every relative or empty entry from PATH where the shell profile or launcher that starts the agent harness sets it, then restart the harness',
+        });
+    let repositories = input.repositories ?? [];
+    if (loaded?.kind === 'complete') {
+        const siblingRoot = resolve(dirname(loaded.result.source.path), loaded.result.config.cockpit.siblings_root);
+        repositories = loaded.result.config.sibling.map((sibling) => ({ slug: sibling.slug, root: resolve(siblingRoot, sibling.dir) }));
+    }
+    // Only an existing directory has files to ask about; an absent one is reported as missing elsewhere.
+    const present = [];
+    for (const repository of repositories)
+        if (await isDirectory(repository.root))
+            present.push(repository);
+    // The cockpit root's own AGENTS.md and CLAUDE.md are generated by sync.
+    for (const repository of present)
+        if (resolve(repository.root) !== resolve(input.root))
+            findings.push(...await inspectSiblingInstructions(repository, tools));
+    const git = await resolveGitExecutable(input.env);
+    if (git.state !== 'available') {
+        // Without Git, the root and secret checks did not run; their absence from the report is no finding.
+        findings.push({
+            severity: 'warning',
+            code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+            message: `the readiness checks that ask Git (the cockpit root's working tree, committed secret files) did not run: ${git.reason}`,
+            target: 'git',
+            fix: 'install Git and put it on PATH, then rerun this command',
+        });
+        return findings;
+    }
+    // A greenfield root init writes into in place stays outside Git until someone runs git init, and
+    // setup refuses it only later; init reached environment-verified without saying so.
+    if (input.checkRoot && await isDirectory(input.root)) {
+        const step = snapshotExecutionStep({
+            id: 'git:readiness-working-tree', argv: [git.value.canonicalPath, '-C', input.root, 'rev-parse', '--show-toplevel'],
+            argv0: git.value.invocationPath, cwd: input.root, env: {}, timeoutMs: input.timeoutMs,
+            stdoutLimitBytes: 4_096, stderrLimitBytes: 4_096, paths: [input.root], ports: [], labels: { source: input.root },
+            expected: [], consumedFiles: [{ path: git.value.canonicalPath, sha256: git.value.sha256, maxBytes: 536_870_912,
+                    argvIndexes: [0], executable: true, executionMode: git.value.executionMode }],
+            filesystemChecks: [], compensation: [],
+        });
+        if (!step)
+            throw new RefusalError('the cockpit root Git probe could not be planned');
+        const outcome = authenticatedExecutionOutcome(await execute(step), step);
+        if (!outcome)
+            throw new RefusalError('the cockpit root Git probe returned unauthenticated evidence');
+        // Git exits non-zero outside a working tree and in one it refuses to read; any other refusal is a
+        // probe that did not run.
+        if (outcome.kind === 'refusal' && outcome.code !== ENVIRONMENT_CODES.EXECUTION_STEP_FAILED) {
+            throw new RefusalError(`the cockpit root Git probe did not run (${outcome.code})`);
+        }
+        const refused = outcome.kind === 'refusal' ? gitRepositoryRefusal(outcome.stderr) : undefined;
+        if (refused?.kind === 'not-a-repository')
+            findings.push({
+                severity: 'warning',
+                code: ENVIRONMENT_CODES.SETUP_PATH_TYPE_INVALID,
+                message: `${input.root} is not inside a Git working tree, so setup will refuse to run there and no teammate can clone this cockpit`,
+                target: input.root,
+                fix: `run git -C ${input.root} init, then commit the cockpit files once a person has reviewed them`,
+            });
+        if (refused?.kind === 'refused')
+            findings.push({
+                severity: 'warning',
+                code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+                message: `whether ${input.root} is inside a Git working tree could not be checked: ${refused.reason}`,
+                target: input.root,
+                fix: refused.fix,
+            });
+    }
+    findings.push(...await inspectTrackedSecretFiles({ executable: git.value, repositories: present, timeoutMs: input.timeoutMs }, execute));
+    return findings;
+}
+/**
+ * init's readiness probes. Before cockpit.toml exists, whether a runtime will be declared is read
+ * from the estate classification: an estate with no runnable product gets a surfaces-only cockpit.
+ */
+export async function inspectInitReadiness(input, binding) {
+    const { classification, ...probe } = input;
+    const loaded = input.configPath === undefined ? undefined : await loadCockpitConfig(input.configPath);
+    const findings = await inspectProjectReadiness({ ...probe, env: binding.env, timeoutMs: binding.timeoutMs }, binding.execute, loaded);
+    const state = loaded?.kind === 'complete'
+        ? declaresNothingToRun(loaded.result.config.environment) ? 'surfaces-only' : 'runtime'
+        : classification === undefined ? 'undetermined' : classification === 'no-runnable-product' ? 'surfaces-only' : 'runtime';
+    return { state, findings };
+}
+/**
+ * What the container runtime on this machine offers, measured by the same collector preflight
+ * compares the machine floor with, so init can propose a floor where no Compose limit records one.
+ */
+export async function measureInitMachine(input, binding) {
+    const [docker, disk] = await Promise.all([resolveDockerExecutable(binding.env), resolveDiskCapacityExecutable()]);
+    if (docker.state !== 'available')
+        return { kind: 'unavailable', reason: docker.reason };
+    if (disk.state !== 'available')
+        return { kind: 'unavailable', reason: disk.reason };
+    const env = Object.fromEntries(Object.entries(binding.env)
+        .filter((entry) => DOCKER_CLIENT_ENVIRONMENT.has(entry[0]) && typeof entry[1] === 'string'));
+    const measured = await measureMachineFloor({ runtimeExecutable: docker.value, diskExecutable: disk.value, cwd: input.root,
+        env, timeoutMs: binding.timeoutMs }, binding.execute);
+    if (measured.kind !== 'complete')
+        return { kind: 'unavailable', reason: measured.kind === 'refusal'
+                ? measured.diagnostics.map(row => row.message).join('; ') : 'docker info did not report the runtime\'s memory and CPUs' };
+    return { kind: 'complete', memoryMb: Math.floor(measured.evidence.memoryBytes / 1024 ** 2),
+        cpus: measured.evidence.cpuMillis / 1_000, observedAt: measured.evidence.observedAt };
+}