@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/environment/compose-topology.js

@@ -162,6 +162,12 @@ function projectServices(stdout) {
         const image = service.image;
         if (image !== undefined && typeof image !== 'string')
             return undefined;
+        const containerName = service.container_name;
+        if (containerName !== undefined && typeof containerName !== 'string')
+            return undefined;
+        const profiles = service.profiles ?? [];
+        if (!Array.isArray(profiles) || profiles.some(profile => typeof profile !== 'string'))
+            return undefined;
         const rawVolumes = service.volumes ?? [];
         if (!Array.isArray(rawVolumes))
             return undefined;
@@ -176,7 +182,8 @@ function projectServices(stdout) {
         }
         projected.push({
             id, ports, healthcheck,
-            image: image ?? null, build: service.build !== undefined, mountSources,
+            image: image ?? null, build: service.build !== undefined, containerName: containerName ?? null, mountSources,
+            ...profiles.length > 0 ? { profiles: profiles } : {},
         });
     }
     return projected;
@@ -300,7 +307,7 @@ async function canonicalPath(path) {
  * Docker follows a symbolic link in the bind source, so `./api/cache -> /` would otherwise hand
  * the host root to a container under a mount = "always" checkout.
  */
-export async function redirectedBindSources(binds, declared) {
+export async function redirectedBindSources(binds, declared, resolve = canonicalPath) {
     const redirected = [];
     for (const bind of new Set(binds)) {
         if (declared.includes(bind))
@@ -310,7 +317,7 @@ export async function redirectedBindSources(binds, declared) {
             continue;
         let inside;
         try {
-            inside = contains(await canonicalPath(owner), await canonicalPath(bind));
+            inside = contains(await resolve(owner), await resolve(bind));
         }
         catch {
             inside = false;
@@ -320,34 +327,35 @@ export async function redirectedBindSources(binds, declared) {
     }
     return redirected.sort((left, right) => left.bind.localeCompare(right.bind));
 }
-/**
- * Judges a cockpit's own Compose topology. A host port that is not drawn from a leased
- * `ports.bases` variable is the same number in every worktree and parallel stack, so the second
- * stack to start fails to bind it; the remaining findings are warnings about what cockpit can
- * then promise, not about whether the stack runs.
- */
-export async function assessComposeTopology(services, declarations) {
-    const leased = new Set(declarations.portVariables);
+function profileOf(sibling) {
+    return sibling.mount.startsWith('profile:') ? sibling.mount.slice('profile:'.length) : undefined;
+}
+// Image references that differ per stack: Compose's own project name, which cockpit derives per
+// checkout, and the leased ports.bases variables.
+function imageVariesPerStack(image, leased) {
+    return [...image.matchAll(/\$\{?([A-Za-z_][A-Za-z0-9_]*)/g)].some(([, name]) => name === 'COMPOSE_PROJECT_NAME' || leased.has(name));
+}
+// The bind findings of the services one profile set runs, judged as `up` judges them under that set.
+async function assessBinds(services, declarations, variables, active, resolve) {
     const diagnostics = [];
-    // `up` admits the topology only when every bind lands inside a mount = "always" checkout or a
-    // generated host path, and every such checkout is mounted; check judges the same binds the same
-    // way, or a configuration check accepts refuses every runtime command.
-    const always = declarations.siblings.filter(sibling => sibling.mount === 'always');
-    const declared = [...always.map(sibling => sibling.path), ...declarations.hostPaths.map(({ path }) => path)];
-    const variables = Object.fromEntries(declarations.siblings.map(sibling => [sibling.var, sibling.path]));
-    const binds = services.flatMap(service => service.mountSources.map(source => ({
+    const running = services.filter(service => !service.profiles?.length || service.profiles.some(profile => active.includes(profile)));
+    const mounted = declarations.siblings.filter(sibling => sibling.mount === 'always'
+        || profileOf(sibling) !== undefined && active.includes(profileOf(sibling)));
+    const declared = [...mounted.map(sibling => sibling.path), ...declarations.hostPaths.map(({ path }) => path)];
+    const binds = running.flatMap(service => service.mountSources.map(source => ({
         service: service.id, source, path: composeBindPath(source, declarations.projectDirectory, variables)
     })))
         .filter(bind => bind.path !== 'volume');
     const resolved = binds.flatMap(bind => bind.path === undefined ? [] : [bind.path]);
     const { missing, unexpected } = compareBindSources(resolved, declared);
-    const redirected = (await redirectedBindSources(resolved, declared)).map(({ bind }) => bind);
-    for (const sibling of always) {
+    const redirected = (await redirectedBindSources(resolved, declared, resolve)).map(({ bind }) => bind);
+    const under = active.length === 0 ? '' : ` with profile ${active.join(', ')} active`;
+    for (const sibling of mounted) {
         if (!missing.includes(sibling.path))
             continue;
         diagnostics.push({
             severity: 'error', code: 'COMPOSE_SIBLING_NOT_MOUNTED', target: `sibling:${sibling.slug}`,
-            message: `sibling ${sibling.slug} is declared mount = "always", but no Compose service bind-mounts ${sibling.path} or a directory inside it; up admits a stack only when every such sibling is mounted, so it would refuse to start`,
+            message: `sibling ${sibling.slug} is declared mount = "${sibling.mount}", but no Compose service${under} bind-mounts ${sibling.path} or a directory inside it; up admits a stack only when every such sibling is mounted, so it would refuse to start`,
             fix: `bind-mount it in a service of the Compose file, whole or a directory inside it (for example "\${${sibling.var}}:/workspace/${sibling.slug}"), or set mount = "none" on sibling ${sibling.slug} in cockpit.toml, then run ${cockpitCommand('sync')}`,
         });
     }
@@ -364,16 +372,73 @@ export async function assessComposeTopology(services, declarations) {
     for (const bind of binds) {
         const why = bind.path === undefined
             ? 'whose host side names a variable cockpit does not supply and gives it no default'
-            : unexpected.includes(bind.path) ? 'which lies inside no mount = "always" sibling and is no environment.generated_host_paths entry'
+            : unexpected.includes(bind.path) ? `which lies inside no mounted sibling${under} and is no environment.generated_host_paths entry`
                 : redirected.includes(bind.path) ? 'which resolves through a symbolic link to a path outside the sibling that holds it' : undefined;
         if (why === undefined)
             continue;
         diagnostics.push({
             severity: 'error', code: 'COMPOSE_BIND_UNDECLARED', target: `compose:${bind.service}:${bind.source}`,
             message: `service ${bind.service} bind-mounts ${bind.path ?? bind.source}, ${why}; up hands a container only the checkouts and host paths cockpit.toml declares, so it would refuse to start`,
-            fix: `bind a directory inside a mount = "always" sibling (its variable, as in "\${VAR}/path", or a path relative to the first Compose file's directory), list the path under environment.generated_host_paths, or remove the bind mount from service ${bind.service}; then run ${cockpitCommand('check')}`,
+            fix: `bind a directory inside a mounted sibling (its variable, as in "\${VAR}/path", or a path relative to the first Compose file's directory), list the path under environment.generated_host_paths, or remove the bind mount from service ${bind.service}; then run ${cockpitCommand('check')}`,
         });
     }
+    return diagnostics;
+}
+/**
+ * Judges a cockpit's own Compose topology. A host port that is not drawn from a leased
+ * `ports.bases` variable is the same number in every worktree and parallel stack, so the second
+ * stack to start fails to bind it; a fixed `container_name` fails the same way, and a fixed tag on a
+ * built image is shared the same way. The remaining findings are warnings about what cockpit can
+ * then promise, not about whether the stack runs.
+ */
+export async function assessComposeTopology(services, declarations) {
+    const leased = new Set(declarations.portVariables);
+    const diagnostics = [];
+    const defined = new Set(services.flatMap(service => service.profiles ?? []));
+    const defaults = declarations.profiles ?? [];
+    for (const [profile, source] of [
+        ...defaults.map(profile => [profile, 'environment.profiles names it']),
+        ...declarations.siblings.flatMap(sibling => profileOf(sibling) === undefined ? []
+            : [[profileOf(sibling), `sibling ${sibling.slug} is mounted under it`]]),
+    ]) {
+        if (defined.has(profile))
+            continue;
+        diagnostics.push({
+            severity: 'error', code: 'COMPOSE_PROFILE_UNDEFINED',
+            target: `profile:${profile}`,
+            message: `profile ${profile} is declared by no service in environment.compose_files, and ${source}; Compose accepts an unknown profile silently, so activating it would start nothing`,
+            fix: `add profiles: [${profile}] to the services it should start, or remove it from cockpit.toml; then run ${cockpitCommand('check')}`,
+        });
+    }
+    // `up` admits the topology only when every bind of an active service lands inside a mounted
+    // checkout or a generated host path, and every such checkout is mounted; check judges the same
+    // binds the same way, or a configuration check accepts refuses every runtime command. A stack
+    // runs the default profile set plus any profiles `up --profile` adds, so the binds are judged
+    // under the default set and under the default set plus each other defined profile: a finding
+    // under several added profiles already shows under one of them.
+    const usable = defaults.filter(profile => defined.has(profile));
+    const sets = [usable, ...[...defined].filter(profile => !usable.includes(profile)).sort().map(profile => [...usable, profile])];
+    const variables = Object.fromEntries(declarations.siblings.map(sibling => [sibling.var, sibling.path]));
+    // The same binds recur in most profile sets, so each real path is resolved once.
+    const resolutions = new Map();
+    const resolve = (path) => {
+        let resolution = resolutions.get(path);
+        if (resolution === undefined) {
+            resolution = canonicalPath(path);
+            resolutions.set(path, resolution);
+        }
+        return resolution;
+    };
+    const seen = new Set();
+    for (const active of sets) {
+        for (const diagnostic of await assessBinds(services, declarations, variables, active, resolve)) {
+            const key = `${diagnostic.code}\0${diagnostic.target}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                diagnostics.push(diagnostic);
+            }
+        }
+    }
     for (const service of services) {
         for (const port of service.ports) {
             // No host interface means Docker binds every one (0.0.0.0 and ::), exposing the service
@@ -396,6 +461,12 @@ export async function assessComposeTopology(services, declarations) {
                 fix: `publish it as "\${${name}}:${port.target}" in the Compose file and declare ${name} under [ports.bases]`,
             });
         }
+        if (service.containerName !== null)
+            diagnostics.push({
+                severity: 'error', code: 'COMPOSE_CONTAINER_NAME_FIXED', target: `compose:${service.id}`,
+                message: `service ${service.id} sets container_name ${JSON.stringify(service.containerName)}, and Docker allows one container of a name, so a second checkout's stack fails to start`,
+                fix: `remove container_name from service ${service.id} and address it by its Compose service name, or with docker compose exec ${service.id}`,
+            });
         if (!service.healthcheck)
             diagnostics.push({
                 severity: 'warning', code: 'COMPOSE_HEALTHCHECK_MISSING', target: `compose:${service.id}`,
@@ -408,6 +479,12 @@ export async function assessComposeTopology(services, declarations) {
                 message: `service ${service.id} runs image ${JSON.stringify(service.image)} by tag, so a later pull can change what runs`,
                 fix: `pin it by digest, for example ${service.image.replace(/:[^/:]*$/, '')}@sha256:<digest> from docker image inspect`,
             });
+        if (service.build && service.image !== null && !imageVariesPerStack(service.image, leased))
+            diagnostics.push({
+                severity: 'error', code: 'COMPOSE_IMAGE_TAG_SHARED', target: `compose:${service.id}`,
+                message: `service ${service.id} builds its image and tags it ${JSON.stringify(service.image)}, which is the same in every worktree and parallel stack, so one checkout's build replaces the image another checkout's stack runs`,
+                fix: `remove image from service ${service.id}, so Compose names the build after this stack's project`,
+            });
     }
     return diagnostics;
 }

package/dist/environment/contract.d.ts

@@ -7,7 +7,7 @@ export interface Diagnostic<Code extends string = string> {
     fix?: string;
 }
 export type JsonSnapshot = null | boolean | number | string | JsonSnapshotArray | JsonSnapshotObject;
-export interface JsonSnapshotArray extends ReadonlyArray<JsonSnapshot> {
+interface JsonSnapshotArray extends ReadonlyArray<JsonSnapshot> {
 }
 export interface JsonSnapshotObject {
     readonly [key: string]: JsonSnapshot;
@@ -113,6 +113,9 @@ export declare const ENVIRONMENT_CODES: Readonly<{
     readonly RECLAIM_LABEL_ESCAPE: 'RECLAIM_LABEL_ESCAPE';
     readonly RECLAIM_ACCOUNTING_MISMATCH: 'RECLAIM_ACCOUNTING_MISMATCH';
     readonly DOWN_RESOURCES_KEPT: 'DOWN_RESOURCES_KEPT';
+    readonly STACKS_ORPHANED: 'STACKS_ORPHANED';
+    readonly STACKS_PRUNE_UNCONFIRMED: 'STACKS_PRUNE_UNCONFIRMED';
+    readonly STACKS_PRUNE_INCOMPLETE: 'STACKS_PRUNE_INCOMPLETE';
     readonly CONFIG_STALE: 'CONFIG_STALE';
     readonly SIBLING_MISSING: 'SIBLING_MISSING';
     readonly GUIDE_CAP_EXCEEDED: 'GUIDE_CAP_EXCEEDED';
@@ -131,6 +134,7 @@ export declare const ENVIRONMENT_CODES: Readonly<{
     readonly GENERATED_ENVIRONMENT_UNAVAILABLE: 'GENERATED_ENVIRONMENT_UNAVAILABLE';
     readonly CLAIM_STATE_UNHEALTHY: 'CLAIM_STATE_UNHEALTHY';
     readonly MOUNT_POSTURE_UNAVAILABLE: 'MOUNT_POSTURE_UNAVAILABLE';
+    readonly COMPOSE_PROFILE_UNDEFINED: 'COMPOSE_PROFILE_UNDEFINED';
     readonly STATE_UNSEEDED: 'STATE_UNSEEDED';
     readonly STACK_NOT_RUNNING: 'STACK_NOT_RUNNING';
     readonly SKILL_BUDGET_UNAVAILABLE: 'SKILL_BUDGET_UNAVAILABLE';
@@ -143,6 +147,8 @@ export declare const ENVIRONMENT_CODES: Readonly<{
     readonly SERVICE_NOT_DECLARED: 'SERVICE_NOT_DECLARED';
     readonly GUARD_HOSTS_UNDECLARED: 'GUARD_HOSTS_UNDECLARED';
     readonly TESTING_GATE_UNDECLARED: 'TESTING_GATE_UNDECLARED';
+    readonly MCP_COMMAND_UNRESOLVED: 'MCP_COMMAND_UNRESOLVED';
+    readonly MCP_ENVIRONMENT_UNSET: 'MCP_ENVIRONMENT_UNSET';
     readonly EVALUATOR_UNAVAILABLE: 'EVALUATOR_UNAVAILABLE';
     readonly EVALUATOR_RUN_FAILED: 'EVALUATOR_RUN_FAILED';
     readonly EVALUATOR_FELL_BACK_TO_RUNNING_TOOL: 'EVALUATOR_FELL_BACK_TO_RUNNING_TOOL';
@@ -150,15 +156,23 @@ export declare const ENVIRONMENT_CODES: Readonly<{
     readonly TEST_GATE_UNSATISFIED: 'TEST_GATE_UNSATISFIED';
     readonly WORK_GRADE_UNSATISFIED: 'WORK_GRADE_UNSATISFIED';
     readonly WORK_CHECK_FAILED: 'WORK_CHECK_FAILED';
+    readonly BROWSER_ROUTE_FINDINGS: 'BROWSER_ROUTE_FINDINGS';
     readonly WORK_VERIFY_FAILED: 'WORK_VERIFY_FAILED';
     readonly WORK_PERSON_REQUIRED: 'WORK_PERSON_REQUIRED';
+    readonly WORK_TEST_WEAKENED: 'WORK_TEST_WEAKENED';
     readonly AUTONOMY_PERSON_REQUIRED: 'AUTONOMY_PERSON_REQUIRED';
     readonly AUTONOMY_CI_ONLY: 'AUTONOMY_CI_ONLY';
     readonly POLICY_WEAKENING_UNCONFIRMED: 'POLICY_WEAKENING_UNCONFIRMED';
+    readonly GUARD_CONFIG_UNSYNCED: 'GUARD_CONFIG_UNSYNCED';
+    readonly GUARD_CONFIG_WIDENED: 'GUARD_CONFIG_WIDENED';
     readonly WORK_ORDER_CLOSED: 'WORK_ORDER_CLOSED';
     readonly CODEX_HOOK_UNTRUSTED: 'CODEX_HOOK_UNTRUSTED';
     readonly SELFTEST_CUSTOM_PROBE_UNSUPPORTED: 'SELFTEST_CUSTOM_PROBE_UNSUPPORTED';
     readonly DECLARATION_UNCONFIRMED: 'DECLARATION_UNCONFIRMED';
+    readonly CONFIRM_PERSON_REQUIRED: 'CONFIRM_PERSON_REQUIRED';
+    readonly CONFIRM_ANSWER_NOT_LISTED: 'CONFIRM_ANSWER_NOT_LISTED';
+    readonly CONFIRM_OBSERVATION_FAILED: 'CONFIRM_OBSERVATION_FAILED';
+    readonly CONFIRM_RECORD_UNWRITABLE: 'CONFIRM_RECORD_UNWRITABLE';
     readonly COCKPIT_NOT_INSTALLED: 'COCKPIT_NOT_INSTALLED';
     readonly COCKPIT_LAUNCHER_UNPROVEN: 'COCKPIT_LAUNCHER_UNPROVEN';
     readonly SIBLING_REMOTE_UNRECORDED: 'SIBLING_REMOTE_UNRECORDED';
@@ -178,6 +192,25 @@ export declare const ENVIRONMENT_CODES: Readonly<{
     readonly UPGRADE_SYNC_FAILED: 'UPGRADE_SYNC_FAILED';
     readonly DATA_SEED_FAILED: 'DATA_SEED_FAILED';
     readonly DATA_SEED_UNAVAILABLE: 'DATA_SEED_UNAVAILABLE';
+    readonly DOCS_NOT_DECLARED: 'DOCS_NOT_DECLARED';
+    readonly DOCS_DECLARATION_UNMATCHED: 'DOCS_DECLARATION_UNMATCHED';
+    readonly DOCS_REFERENCE_REMOVED: 'DOCS_REFERENCE_REMOVED';
+    readonly DOCS_TARGET_REMOVED: 'DOCS_TARGET_REMOVED';
+    readonly DECISION_NUMBER_REUSED: 'DECISION_NUMBER_REUSED';
+    readonly DECISION_UNINDEXED: 'DECISION_UNINDEXED';
+    readonly DECISION_INDEX_ENTRY_MISSING: 'DECISION_INDEX_ENTRY_MISSING';
+    readonly DECISION_STATUS_MISSING: 'DECISION_STATUS_MISSING';
+    readonly DECISION_LINK_UNRESOLVED: 'DECISION_LINK_UNRESOLVED';
+    readonly DECISION_SUPERSEDED_STALE: 'DECISION_SUPERSEDED_STALE';
+    readonly SIBLING_CHECKOUT_RECORD_INVALID: 'SIBLING_CHECKOUT_RECORD_INVALID';
+    readonly SIBLING_CHECKOUT_UNKNOWN: 'SIBLING_CHECKOUT_UNKNOWN';
+    readonly SIBLING_CHECKOUT_UNAVAILABLE: 'SIBLING_CHECKOUT_UNAVAILABLE';
+    readonly SIBLING_CHECKOUT_FOREIGN: 'SIBLING_CHECKOUT_FOREIGN';
+    readonly SIBLING_CHECKOUT_OVERRIDDEN: 'SIBLING_CHECKOUT_OVERRIDDEN';
+    readonly SIBLING_ENVIRONMENT_FILE_MISSING: 'SIBLING_ENVIRONMENT_FILE_MISSING';
+    readonly PULL_SKIPPED: 'PULL_SKIPPED';
+    readonly STACK_INPUTS_CHANGED: 'STACK_INPUTS_CHANGED';
+    readonly STACK_INPUTS_UNRECORDED: 'STACK_INPUTS_UNRECORDED';
 }>;
 export declare const EXECUTION_FAILURE_CODES: readonly ["EXECUTION_SPAWN_FAILED", "EXECUTION_PRECONDITION_CHANGED", "EXECUTION_STAGING_FAILED", "EXECUTION_STAGING_CLEANUP_FAILED", "EXECUTION_TIMEOUT", "EXECUTION_STDOUT_LIMIT", "EXECUTION_STDERR_LIMIT", "EXECUTION_STEP_FAILED", "EXECUTION_ABORTED", "EXECUTION_TERMINATION_UNCONFIRMED"];
 export declare const REFUSAL_CODES: readonly ["CONFIG_NOT_FOUND", "CONFIG_UNREADABLE", "CONFIG_ENCODING_INVALID", "CONFIG_PARSE_INVALID", "CONFIG_SCHEMA_INVALID", "STATE_ROOT_UNAVAILABLE", "STATE_FORMAT_UNSUPPORTED", "STATE_RECORD_MALFORMED", "STATE_LOCKED", "STATE_DURABILITY_INDETERMINATE", "SETUP_CONFIG_REQUIRED", "SETUP_OPTION_DUPLICATE", "SETUP_POSITIONAL_UNSUPPORTED", "SETUP_PATH_OUTSIDE_ROOT", "SETUP_PATH_SYMLINK", "SETUP_PATH_TYPE_INVALID", "SETUP_PARENT_MISSING", "SETUP_REMOTE_MISMATCH", "SETUP_REMOTE_UNRESOLVABLE", "SETUP_MANUAL_MISSING", "SETUP_CLONE_FAILED", "SETUP_POSTCHECK_FAILED", "SETUP_INSTRUCTION_POINTER_INVALID", "SETUP_INSTRUCTION_FILES_INVALID", "CONFIG_CHANGED_DURING_EXECUTION", "EXECUTION_SPAWN_FAILED", "EXECUTION_PRECONDITION_CHANGED", "EXECUTION_STAGING_FAILED", "EXECUTION_STAGING_CLEANUP_FAILED", "EXECUTION_TIMEOUT", "EXECUTION_STDOUT_LIMIT", "EXECUTION_STDERR_LIMIT", "EXECUTION_STEP_FAILED", "EXECUTION_ABORTED", "EXECUTION_TERMINATION_UNCONFIRMED", "EXECUTION_COMPENSATION_TIMEOUT", "EXECUTION_COMPENSATION_STEP_FAILED", "LIFECYCLE_EVIDENCE_INVALID", "LIFECYCLE_PROGRESS_INVALID", "STACK_RECORDED_UNDER_EARLIER_NAME", "PORT_FAMILY_COLLISION", "PORT_LISTENER_EVIDENCE_INVALID", "PORT_FAMILY_OUT_OF_RANGE", "PORT_LEASE_EXHAUSTED", "CLAIM_CO_TENANT", "CLAIM_LIVENESS_UNKNOWN", "DRAIN_ATTEMPT_REPAIR_REQUIRED", "INSTALL_POLICY_OBSERVATION_UNAVAILABLE", "INSTALL_POLICY_OBSERVATION_INVALID", "INSTALL_POLICY_MISSING", "INSTALL_POLICY_AMBIGUOUS", "TEMPLATE_NOT_FOUND", "TEMPLATE_NOT_TRACKED", "TEMPLATE_IGNORED", "TEMPLATE_PATH_OUTSIDE_ROOT", "ENVIRONMENT_FILE_NOT_FOUND", "ENVIRONMENT_FILE_UNREADABLE", "ENVIRONMENT_FILE_TOO_LARGE", "ENVIRONMENT_FILE_MALFORMED", "INSTANCE_NOT_IGNORED", "ENVIRONMENT_SEED_PRECONDITION_CHANGED", "ENVIRONMENT_SEED_FAILED", "RUNTIME_UNAVAILABLE", "RUNTIME_IMAGE_UNAVAILABLE", "RUNTIME_UNMEASURED", "RUNTIME_COMPOSE_REMOTE", "RUNTIME_PROBE_TIMEOUT", "RESET_CONFIRMATION_REQUIRED", "RESET_CONFIRMATION_MISMATCH", "RESET_CO_TENANT", "EVIDENCE_UNAVAILABLE", "RECLAIM_LABEL_ESCAPE", "RECLAIM_ACCOUNTING_MISMATCH", "DOWN_RESOURCES_KEPT", "GIT_COMPARISON_REMOTE_MISMATCH"];
@@ -199,7 +232,7 @@ export declare function tryParseJson(text: string): unknown;
 export declare function hasErrorCode(error: unknown, ...codes: readonly string[]): boolean;
 export declare function isMissing(error: unknown): boolean;
 export declare function isCanonicalTimestamp(value: unknown): value is string;
-export type ExpectedObservation = {
+type ExpectedObservation = {
     kind: 'path';
     target: string;
     state: 'absent' | 'directory' | 'repository';
@@ -314,20 +347,20 @@ export interface ExecutionFence {
 export interface ExecutionPlan {
     steps: readonly ExecutionStep[];
 }
-export type LifecycleResumeBoundary = Readonly<{
+type LifecycleResumeBoundary = Readonly<{
     completedStepIds: readonly string[];
     nextStepId: string | null;
 }>;
 type LifecycleStepBase = Readonly<{
     id: string;
 }>;
-export interface LifecycleEntrypoint {
+interface LifecycleEntrypoint {
     readonly name: string;
     readonly kind: EntrypointKind;
     readonly port: string;
     readonly value: string;
 }
-export interface LifecycleCompletedService {
+interface LifecycleCompletedService {
     readonly service: string;
     readonly containerId: string;
 }
@@ -336,7 +369,7 @@ export interface LifecycleProgress {
     readonly operationGeneration: string;
     readonly completedServices: readonly LifecycleCompletedService[];
 }
-export type LifecycleStep = (LifecycleStepBase & Readonly<{
+type LifecycleStep = (LifecycleStepBase & Readonly<{
     kind: 'preflight';
 }>) | (LifecycleStepBase & Readonly<{
     kind: 'claim';
@@ -411,7 +444,7 @@ export type ObservationExpectation = {
 } | {
     readonly kind: 'present';
 };
-export type ObservationApplicability = {
+type ObservationApplicability = {
     readonly state: 'required';
     readonly posture: string;
 } | {
@@ -419,13 +452,13 @@ export type ObservationApplicability = {
     readonly posture: string;
     readonly reason: string;
 };
-export type ObservationFreshness = {
+type ObservationFreshness = {
     readonly state: 'current';
 } | {
     readonly state: 'stale' | 'missing';
     readonly reason: string;
 };
-export type EnvironmentObservedValue = {
+type EnvironmentObservedValue = {
     readonly state: 'available';
     readonly value: JsonSnapshot;
     readonly observedAt: string;

package/dist/environment/contract.js

@@ -194,6 +194,9 @@ export const ENVIRONMENT_CODES = Object.freeze({
     RECLAIM_LABEL_ESCAPE: 'RECLAIM_LABEL_ESCAPE',
     RECLAIM_ACCOUNTING_MISMATCH: 'RECLAIM_ACCOUNTING_MISMATCH',
     DOWN_RESOURCES_KEPT: 'DOWN_RESOURCES_KEPT',
+    STACKS_ORPHANED: 'STACKS_ORPHANED',
+    STACKS_PRUNE_UNCONFIRMED: 'STACKS_PRUNE_UNCONFIRMED',
+    STACKS_PRUNE_INCOMPLETE: 'STACKS_PRUNE_INCOMPLETE',
     CONFIG_STALE: 'CONFIG_STALE',
     SIBLING_MISSING: 'SIBLING_MISSING',
     GUIDE_CAP_EXCEEDED: 'GUIDE_CAP_EXCEEDED',
@@ -212,6 +215,7 @@ export const ENVIRONMENT_CODES = Object.freeze({
     GENERATED_ENVIRONMENT_UNAVAILABLE: 'GENERATED_ENVIRONMENT_UNAVAILABLE',
     CLAIM_STATE_UNHEALTHY: 'CLAIM_STATE_UNHEALTHY',
     MOUNT_POSTURE_UNAVAILABLE: 'MOUNT_POSTURE_UNAVAILABLE',
+    COMPOSE_PROFILE_UNDEFINED: 'COMPOSE_PROFILE_UNDEFINED',
     STATE_UNSEEDED: 'STATE_UNSEEDED',
     STACK_NOT_RUNNING: 'STACK_NOT_RUNNING',
     SKILL_BUDGET_UNAVAILABLE: 'SKILL_BUDGET_UNAVAILABLE',
@@ -224,6 +228,8 @@ export const ENVIRONMENT_CODES = Object.freeze({
     SERVICE_NOT_DECLARED: 'SERVICE_NOT_DECLARED',
     GUARD_HOSTS_UNDECLARED: 'GUARD_HOSTS_UNDECLARED',
     TESTING_GATE_UNDECLARED: 'TESTING_GATE_UNDECLARED',
+    MCP_COMMAND_UNRESOLVED: 'MCP_COMMAND_UNRESOLVED',
+    MCP_ENVIRONMENT_UNSET: 'MCP_ENVIRONMENT_UNSET',
     EVALUATOR_UNAVAILABLE: 'EVALUATOR_UNAVAILABLE',
     EVALUATOR_RUN_FAILED: 'EVALUATOR_RUN_FAILED',
     EVALUATOR_FELL_BACK_TO_RUNNING_TOOL: 'EVALUATOR_FELL_BACK_TO_RUNNING_TOOL',
@@ -231,15 +237,23 @@ export const ENVIRONMENT_CODES = Object.freeze({
     TEST_GATE_UNSATISFIED: 'TEST_GATE_UNSATISFIED',
     WORK_GRADE_UNSATISFIED: 'WORK_GRADE_UNSATISFIED',
     WORK_CHECK_FAILED: 'WORK_CHECK_FAILED',
+    BROWSER_ROUTE_FINDINGS: 'BROWSER_ROUTE_FINDINGS',
     WORK_VERIFY_FAILED: 'WORK_VERIFY_FAILED',
     WORK_PERSON_REQUIRED: 'WORK_PERSON_REQUIRED',
+    WORK_TEST_WEAKENED: 'WORK_TEST_WEAKENED',
     AUTONOMY_PERSON_REQUIRED: 'AUTONOMY_PERSON_REQUIRED',
     AUTONOMY_CI_ONLY: 'AUTONOMY_CI_ONLY',
     POLICY_WEAKENING_UNCONFIRMED: 'POLICY_WEAKENING_UNCONFIRMED',
+    GUARD_CONFIG_UNSYNCED: 'GUARD_CONFIG_UNSYNCED',
+    GUARD_CONFIG_WIDENED: 'GUARD_CONFIG_WIDENED',
     WORK_ORDER_CLOSED: 'WORK_ORDER_CLOSED',
     CODEX_HOOK_UNTRUSTED: 'CODEX_HOOK_UNTRUSTED',
     SELFTEST_CUSTOM_PROBE_UNSUPPORTED: 'SELFTEST_CUSTOM_PROBE_UNSUPPORTED',
     DECLARATION_UNCONFIRMED: 'DECLARATION_UNCONFIRMED',
+    CONFIRM_PERSON_REQUIRED: 'CONFIRM_PERSON_REQUIRED',
+    CONFIRM_ANSWER_NOT_LISTED: 'CONFIRM_ANSWER_NOT_LISTED',
+    CONFIRM_OBSERVATION_FAILED: 'CONFIRM_OBSERVATION_FAILED',
+    CONFIRM_RECORD_UNWRITABLE: 'CONFIRM_RECORD_UNWRITABLE',
     COCKPIT_NOT_INSTALLED: 'COCKPIT_NOT_INSTALLED',
     COCKPIT_LAUNCHER_UNPROVEN: 'COCKPIT_LAUNCHER_UNPROVEN',
     SIBLING_REMOTE_UNRECORDED: 'SIBLING_REMOTE_UNRECORDED',
@@ -259,6 +273,25 @@ export const ENVIRONMENT_CODES = Object.freeze({
     UPGRADE_SYNC_FAILED: 'UPGRADE_SYNC_FAILED',
     DATA_SEED_FAILED: 'DATA_SEED_FAILED',
     DATA_SEED_UNAVAILABLE: 'DATA_SEED_UNAVAILABLE',
+    DOCS_NOT_DECLARED: 'DOCS_NOT_DECLARED',
+    DOCS_DECLARATION_UNMATCHED: 'DOCS_DECLARATION_UNMATCHED',
+    DOCS_REFERENCE_REMOVED: 'DOCS_REFERENCE_REMOVED',
+    DOCS_TARGET_REMOVED: 'DOCS_TARGET_REMOVED',
+    DECISION_NUMBER_REUSED: 'DECISION_NUMBER_REUSED',
+    DECISION_UNINDEXED: 'DECISION_UNINDEXED',
+    DECISION_INDEX_ENTRY_MISSING: 'DECISION_INDEX_ENTRY_MISSING',
+    DECISION_STATUS_MISSING: 'DECISION_STATUS_MISSING',
+    DECISION_LINK_UNRESOLVED: 'DECISION_LINK_UNRESOLVED',
+    DECISION_SUPERSEDED_STALE: 'DECISION_SUPERSEDED_STALE',
+    SIBLING_CHECKOUT_RECORD_INVALID: 'SIBLING_CHECKOUT_RECORD_INVALID',
+    SIBLING_CHECKOUT_UNKNOWN: 'SIBLING_CHECKOUT_UNKNOWN',
+    SIBLING_CHECKOUT_UNAVAILABLE: 'SIBLING_CHECKOUT_UNAVAILABLE',
+    SIBLING_CHECKOUT_FOREIGN: 'SIBLING_CHECKOUT_FOREIGN',
+    SIBLING_CHECKOUT_OVERRIDDEN: 'SIBLING_CHECKOUT_OVERRIDDEN',
+    SIBLING_ENVIRONMENT_FILE_MISSING: 'SIBLING_ENVIRONMENT_FILE_MISSING',
+    PULL_SKIPPED: 'PULL_SKIPPED',
+    STACK_INPUTS_CHANGED: 'STACK_INPUTS_CHANGED',
+    STACK_INPUTS_UNRECORDED: 'STACK_INPUTS_UNRECORDED',
 });
 export const EXECUTION_FAILURE_CODES = Object.freeze([
     ENVIRONMENT_CODES.EXECUTION_SPAWN_FAILED,

package/dist/environment/executable.d.ts

@@ -20,6 +20,18 @@ export type ExecutableResolution = Readonly<{
 }>;
 export declare function resolveExecutablePath(path: string): Promise<ExecutableResolution>;
 export declare function resolveExecutable(name: string, env: Readonly<Record<string, string | undefined>>): Promise<ExecutableResolution>;
+/**
+ * Whether a command can be started from `cwd`, found the way a wrapper that changes into `cwd` would
+ * find it, without hashing the file: a command with a slash is relative to `cwd`, a bare name is
+ * looked up on PATH. For callers that report presence rather than run the file.
+ */
+export declare function locateExecutable(command: string, env: Readonly<Record<string, string | undefined>>, cwd: string): Promise<Readonly<{
+    state: 'present';
+    path: string;
+}> | Readonly<{
+    state: 'unavailable';
+    reason: string;
+}>>;
 export declare function resolveGitExecutable(env: Readonly<Record<string, string | undefined>>): Promise<ExecutableResolution>;
 export declare function resolveDiskCapacityExecutable(): Promise<ExecutableResolution>;
 export declare function resolveDockerExecutable(env: Readonly<Record<string, string | undefined>>): Promise<ExecutableResolution>;

package/dist/environment/executable.js

@@ -1,7 +1,7 @@
 import { createHash } from 'node:crypto';
 import { constants } from 'node:fs';
 import { lstat, open, realpath } from 'node:fs/promises';
-import { basename, delimiter, isAbsolute, join, normalize } from 'node:path';
+import { basename, delimiter, isAbsolute, join, normalize, resolve } from 'node:path';
 import { errorCause } from './contract.js';
 import { fileFingerprint, recordVerifiedDigest, verifiedDigest } from '../environment-exec/verified-digest.js';
 import { exactKeys } from '../exact-keys.js';
@@ -101,57 +101,80 @@ async function digestRegularFile(path) {
         catch { /* The caller receives unavailable; no descriptor authority survives. */ }
     }
 }
-export async function resolveExecutablePath(path) {
+// The checks that need no file contents: an exact absolute path naming an executable file, or a
+// link that resolves to one.
+async function checkExecutablePath(path) {
     if (typeof path !== 'string' || !isAbsolute(path) || normalize(path) !== path || path.includes('\0')) {
-        return unavailable('Executable path must be an exact absolute path');
+        return { state: 'unavailable', reason: 'Executable path must be an exact absolute path' };
     }
     let invocation;
     try {
         invocation = await lstat(path);
     }
     catch (error) {
-        return unavailable(`Executable is unavailable: ${path}: ${errorCause(error)}`);
+        return { state: 'unavailable', reason: `Executable is unavailable: ${path}: ${errorCause(error)}` };
     }
     if (!(invocation.isFile() || invocation.isSymbolicLink()) || invocation.isFile() && (invocation.mode & 0o111) === 0) {
-        return unavailable(`Executable is unavailable: ${path}`);
+        return { state: 'unavailable', reason: `Executable is unavailable: ${path}` };
     }
-    let canonicalPath;
     try {
-        canonicalPath = await realpath(path);
+        return { state: 'present', path, canonicalPath: await realpath(path) };
     }
     catch (error) {
-        return unavailable(`Executable is unavailable: ${path}: ${errorCause(error)}`);
+        return { state: 'unavailable', reason: `Executable is unavailable: ${path}: ${errorCause(error)}` };
     }
-    const sha256 = await digestRegularFile(canonicalPath);
+}
+export async function resolveExecutablePath(path) {
+    const checked = await checkExecutablePath(path);
+    if (checked.state === 'unavailable')
+        return unavailable(checked.reason);
+    const sha256 = await digestRegularFile(checked.canonicalPath);
     if (sha256 === undefined)
         return unavailable(`Executable identity is unavailable: ${path}`);
-    const value = resolvedExecutable({ canonicalPath, invocationPath: path, sha256, executionMode: 'verified-path' });
+    const value = resolvedExecutable({ canonicalPath: checked.canonicalPath, invocationPath: path, sha256, executionMode: 'verified-path' });
     return value ? { state: 'available', value } : unavailable(`Executable identity is invalid: ${path}`);
 }
-export async function resolveExecutable(name, env) {
-    if (typeof name !== 'string' || name.length === 0 || name.includes('\0'))
-        return unavailable('Executable name is invalid');
-    if (isAbsolute(name))
-        return resolveExecutablePath(name);
-    if (basename(name) !== name)
-        return unavailable('Executable name must be absolute or a PATH entry name');
+const miss = (reason) => ({ state: 'unavailable', reason });
+// Validates the search path once and tries each directory in order; `probe` decides what a hit is.
+async function searchExecutable(name, env, probe, found) {
     const selected = searchPath(env);
     if (selected.kind === 'unreadable')
-        return unavailable('Executable search path is not readable');
+        return miss('Executable search path is not readable');
     const pathValue = selected.path;
     if (typeof pathValue !== 'string' || pathValue.length === 0 || pathValue.includes('\0') || Buffer.byteLength(pathValue) > 65_536) {
-        return unavailable('Executable search path is missing or invalid');
+        return miss('Executable search path is missing or invalid');
     }
     const directories = pathValue.split(delimiter);
     if (directories.length > PATH_ENTRY_LIMIT || directories.some(path => !isAbsolute(path) || normalize(path) !== path)) {
-        return unavailable('Executable search path must contain bounded absolute directories');
+        return miss('Executable search path must contain bounded absolute directories');
     }
     for (const directory of directories) {
-        const result = await resolveExecutablePath(join(directory, name));
-        if (result.state === 'available')
+        const result = await probe(join(directory, name));
+        if (found(result))
             return result;
     }
-    return unavailable(`Executable was not found in the supplied search path: ${name}`);
+    return miss(`Executable was not found in the supplied search path: ${name}`);
+}
+export async function resolveExecutable(name, env) {
+    if (typeof name !== 'string' || name.length === 0 || name.includes('\0'))
+        return unavailable('Executable name is invalid');
+    if (isAbsolute(name))
+        return resolveExecutablePath(name);
+    if (basename(name) !== name)
+        return unavailable('Executable name must be absolute or a PATH entry name');
+    return searchExecutable(name, env, resolveExecutablePath, result => result.state === 'available');
+}
+/**
+ * Whether a command can be started from `cwd`, found the way a wrapper that changes into `cwd` would
+ * find it, without hashing the file: a command with a slash is relative to `cwd`, a bare name is
+ * looked up on PATH. For callers that report presence rather than run the file.
+ */
+export async function locateExecutable(command, env, cwd) {
+    if (typeof command !== 'string' || command.length === 0 || command.includes('\0'))
+        return miss('Executable name is invalid');
+    if (command.includes('/'))
+        return checkExecutablePath(resolve(cwd, command));
+    return searchExecutable(command, env, checkExecutablePath, result => result.state === 'present');
 }
 export async function resolveGitExecutable(env) {
     return resolveExecutable('git', env);

package/dist/environment/generated-application/check.js

@@ -37,6 +37,7 @@ export async function prepareGeneratedEnvironmentCurrentness(input, adapterOverr
             sourceRevision: installedPackageMetadata.cockpitSourceRevision },
         fixContext: { resolvedConfigPath: prepared?.configPath ?? null,
             generatedTargets: prepared ? [...prepared.owned, ...prepared.surfaces].map(row => row.path) : [] },
+        mcpServers: prepared?.mcpServers ?? [],
         ...(authority ? { repairAuthority: authority } : {}),
         ...('status' in publication ? { repairRefusal: publication }
             : 'refusal' in publication ? { repairRefusal: publication.refusal } : {}),
@@ -171,6 +172,7 @@ async function composeTopologyDiagnostics(configPath, sourceSha256, adapters) {
             slug: sibling.slug, var: sibling.var, mount: sibling.mount, path: resolve(siblingsRoot, sibling.dir)
         })),
         hostPaths: config.environment.generated_host_paths.map(declared => ({ declared, path: resolve(root, declared) })),
+        profiles: config.environment.profiles,
     });
 }
 export async function checkGeneratedEnvironment(input, adapterOverrides = {}) {

package/dist/environment/generated-application/prepare.js

@@ -266,6 +266,8 @@ export async function prepare(input, adapters) {
         surfaceAssets: [],
         warnings: [],
         unapprovedMcpServers: [],
+        mcpTransportGaps: [],
+        mcpServers: [],
         registry: derived.result,
         siblingRoots,
         workEnvironment,

package/dist/environment/generated-application/shared.d.ts

@@ -9,7 +9,7 @@ import type { SurfaceFeature, SurfaceSourceFile, SurfaceTarget } from '../../sur
 import type { SurfaceGenerationWarning } from '../../surfaces/generator-adapter.js';
 import type { ActiveSurfaceOverride, SurfaceUpgradeFinding } from '../../surfaces/merge.js';
 import { CORE_EVALUATOR_ASSET as EVALUATOR_ASSET, CORE_SKILL_ASSETS as SKILL_ASSETS } from '../../surfaces/core-declarations.js';
-import type { McpDeclaration } from '../../surfaces/mcp.js';
+import type { McpServer, McpStdioDeclaration } from '../../surfaces/mcp.js';
 import { type GeneratedPathFact, type GeneratedProducer, type SurfaceDesiredEntry } from '../../surfaces/ownership.js';
 import type { DirectoryGrant, GuideObservation, GuideObservationRequest, StandingCost } from '../../surfaces/projection.js';
 import type { NativeFragmentSet, SurfaceInputEvidence } from '../../surfaces/render.js';
@@ -213,6 +213,12 @@ export interface PreparedEnvironment {
         sources: readonly string[];
         sha256: string;
     }>[];
+    readonly mcpTransportGaps: readonly Readonly<{
+        name: string;
+        targets: readonly string[];
+        reason: string;
+    }>[];
+    readonly mcpServers: readonly McpServer[];
     readonly registry: DerivedRegistry;
     readonly siblingRoots: AuthenticatedSiblingRoots;
     readonly workEnvironment: ConsumedWorkEnvironmentConfig;
@@ -317,7 +323,7 @@ export interface ConsumedWorkApplicationAuthorities {
     readonly browser?: Readonly<{
         readonly runtime: BrowserRuntimeProjection;
         readonly namespace: StateNamespace;
-        readonly mcp: McpDeclaration;
+        readonly mcp: McpStdioDeclaration;
         readonly skillTemplate: Readonly<{
             readonly path: string;
             readonly bytes: string;
@@ -481,4 +487,6 @@ export interface GeneratedEnvironmentCurrentness {
     readonly fixContext: FixContext;
     readonly repairAuthority?: GeneratedEnvironmentRepairAuthority;
     readonly repairRefusal?: RefusalOutcome;
+    /** Every declared MCP server as rendered; empty when the environment could not be prepared. */
+    readonly mcpServers: readonly McpServer[];
 }