@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/environment/application/guard.d.ts

@@ -5,6 +5,7 @@ import { type GuardSurfaceTarget } from '../../surfaces/harness-registry.js';
 import { type FixContext } from '../../fix-catalogue.js';
 import { observeSetupCheckout, type SetupCheckoutObservation } from '../setup-observation.js';
 import { loadCockpitConfig, type LoadedConfigProjection } from '../../config/load.js';
+import { type SiblingCheckoutRecordRead } from '../sibling-checkouts.js';
 export interface GuardEvaluationApplicationInput {
     readonly identity: unknown;
     /** The checkout the invoked guard script resolved from its own location. */
@@ -17,7 +18,7 @@ export interface GuardEvaluationApplicationInput {
     /** The harness's command search path, whose directories inside the allowed roots the guard protects. */
     readonly searchPath?: string;
 }
-export interface GuardEvaluationApplicationAdapters {
+interface GuardEvaluationApplicationAdapters {
     readonly loadConfig: typeof loadCockpitConfig;
     readonly observeCheckout: typeof observeSetupCheckout;
     readonly resolveGit: () => Promise<import('../executable.js').ExecutableResolution>;
@@ -25,19 +26,24 @@ export interface GuardEvaluationApplicationAdapters {
     readonly resolveDocker?: () => Promise<import('../executable.js').ExecutableResolution>;
     readonly execute?: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
 }
-export interface GuardEvaluationApplicationResult {
+interface GuardEvaluationApplicationResult {
     readonly decision: GuardDecision;
     readonly diagnostics: readonly import('../contract.js').Diagnostic[];
     readonly fixContext?: FixContext;
 }
 /** Installed bytes are authority only while their source, roots and publication still match. */
 export declare function runGuardEvaluationApplication(input: GuardEvaluationApplicationInput, adapters: GuardEvaluationApplicationAdapters): Promise<GuardEvaluationApplicationResult>;
-export interface PreparedGuardEvaluationPolicy {
+interface PreparedGuardEvaluationPolicy {
     readonly policy: GuardEvaluationPolicy;
 }
-export interface GuardEvaluationPolicyInput {
+interface GuardEvaluationPolicyInput {
     readonly configuration: LoadedConfigProjection;
     readonly checkout: SetupCheckoutObservation;
 }
-/** Source projections share authenticated authority; installed consumption is admitted separately. */
-export declare function prepareGuardEvaluationPolicy(input: GuardEvaluationPolicyInput): Promise<EnvironmentCommandOutcome<PreparedGuardEvaluationPolicy>>;
+/**
+ * Source projections share authenticated authority; installed consumption is admitted separately.
+ * `siblingCheckouts` is the configuration directory's sibling checkout record, when the caller
+ * started reading it already; it is read here otherwise.
+ */
+export declare function prepareGuardEvaluationPolicy(input: GuardEvaluationPolicyInput, siblingCheckouts?: Promise<SiblingCheckoutRecordRead>): Promise<EnvironmentCommandOutcome<PreparedGuardEvaluationPolicy>>;
+export {};

package/dist/environment/application/guard.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { lstatIfPresentSync } from '../presence.js';
 import { lstatSync, realpathSync } from 'node:fs';
 import { isDeepStrictEqual } from 'node:util';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
@@ -8,13 +9,15 @@ import { hasErrorCode, RefusalError, ENVIRONMENT_CODES, errorCause, snapshotJson
 import { GUARD_EXECUTABLE_SEARCH_PATH } from '../executable.js';
 import { CockpitConfig } from '../../schema.js';
 import { pinnedPolicyDenial } from '../../guards/policy-pin.js';
+import { guardConfigChange, guardConfigHeldReason } from '../../guards/policy-change.js';
 import { evaluateGuard, foldGuardSpelling, GUARD_LOCATION_LIMITS, GUARD_ROOT_PROTECTIONS, guardIdentity, } from '../../guards/evaluator.js';
-import { ordinarySessionCommand, resolveOrdinaryInvocation } from '../../command-table.js';
+import { commandSpelling, ordinarySessionCommand, resolveOrdinaryInvocation, UNSYNCED_ADMITTED_COMMANDS, UNSYNCED_ADMITTED_PROSE } from '../../command-table.js';
 import { effectivePolicy } from '../../autonomy.js';
 import { GUARD_INPUT_LIMITS, parseGuardInput } from '../../guards/invocation-parser.js';
 import { readAnchoredFile, readAnchoredBatches, nodeAuthority } from '../../generated-environment/transaction.js';
 import { parseOwnershipManifest } from '../../surfaces/ownership.js';
 import { installedPackageMetadata } from '../../package-metadata.js';
+import { ANSWER_CONFIRMATION_PATH } from '../../guards/answer-confirmation.js';
 import { GUARD_LOCAL_PATHS, parseGuardLocalIdentity } from '../../guards/local-identity.js';
 import { guardInstalledDirectories, guardLauncherEvidence, guardSearchDirectories, guardSearchPathRelativeEntry, guardSecretFiles, guardSensitivePathsBelow, guardTrackedSensitivePaths, guardUnignoredSensitivePaths, } from '../../guards/protected-locations.js';
 import { classifyReadOnlyInvocation, cockpitLauncherPrefix } from '../../guards/read-only.js';
@@ -27,9 +30,10 @@ import { observeInstallPolicyLockfiles, withInstallPolicyProjection } from '../i
 import { resolveInstallPolicies, renderGuardProjectCommand } from '../install-policy.js';
 import { checkoutId as deriveCheckoutId, publicationCockpitId } from '../identity.js';
 import { consumeSetupCheckoutProjection, observeSetupCheckout, withSetupCheckoutProjection, } from '../setup-observation.js';
-import { loadCockpitConfig, consumeLoadedConfigProjection } from '../../config/load.js';
+import { browserPreapprovalRequested, loadCockpitConfig, consumeLoadedConfigProjection, STRUCTURED_INPUT_BYTE_LIMIT } from '../../config/load.js';
 import { deriveRegistry } from '../../registry-derivation.js';
 import { confinedPath, lifecycleRefusal, ownDataValues, sameSource } from './shared.js';
+import { readSiblingCheckouts, servedSiblings } from '../sibling-checkouts.js';
 // `npx --no cockpit logs --service <id>` is an ordinary invocation only for a declared service. A
 // cockpit's services are whatever its own Compose files resolve to, so they are read from Compose
 // rather than guessed, and an unreadable topology refuses.
@@ -50,6 +54,15 @@ function guardHeld(identity, what, why, fix) {
         : `a human must restore it with \`${formatShellCommand(['git', '-C', identity.root, 'restore', '--', fix.path])}\` (it is committed), or run ${sync}`;
     return `${what}; ${why}, so every tool call is held, including a sync run through this agent. Fix: ${action}.`;
 }
+// An edit that does not widen what agents may do needs only a sync, which the agent may run itself;
+// every other call waits for it, so no call is judged under a policy sync has not published.
+function unsyncedHold(identity, detail) {
+    const sync = cockpitCommand('sync', { config: identity.configPath });
+    const reason = `${identity.configPath} changed since the guards were generated without widening what agents may do${detail}; every tool call except ${UNSYNCED_ADMITTED_PROSE} is held until it is synced. Fix: run \`${sync}\` (this agent may run it where [autonomy] sync = "agent"), then commit any regenerated files.`;
+    return { decision: { decision: 'unavailable', reason }, diagnostics: [{ severity: 'error', target: 'guard', message: reason,
+                code: 'GUARD_CONFIG_UNSYNCED',
+                fix: `run ${sync}; an agent may run it where [autonomy] sync = "agent"` }] };
+}
 const GUARD_RESTORABLE = new Set(['.cockpit/generated-environment-ownership.json', '.cockpit/guards/bash-guard.sh',
     '.claude/settings.json', '.codex/hooks.json', '.opencode/plugin/cockpit-guards.js']);
 /** Installed bytes are authority only while their source, roots and publication still match. */
@@ -148,13 +161,25 @@ export async function runGuardEvaluationApplication(input, adapters) {
         const modulePending = settle(read(dirname(identity.module), basename(identity.module), 16_777_216));
         const configPending = settle(adapters.loadConfig(identity.configPath));
         const publicationPending = settle(readPublication());
+        const checkoutsPending = settle(readSiblingCheckouts(identity.root));
         const module = unwrap(await modulePending);
         if (module.sha256 !== identity.moduleSha256)
             return changed('the installed cockpit version changed (its handler bytes differ)');
         const loaded = unwrap(await configPending);
-        if (loaded.kind !== 'complete' || loaded.result.source.path !== identity.configPath || loaded.result.source.sha256 !== identity.configSha256) {
+        if (loaded.kind !== 'complete' || loaded.result.source.path !== identity.configPath) {
             return unavailable(guardHeld(identity, `${identity.configPath} changed since the guards were generated`, 'guard policy comes from it and an edit takes effect only once a human approves it', { kind: 'sync' }));
         }
+        // Every check below runs against the configuration on disk; an edit since sync is admitted
+        // only when it does not widen the one the guards were generated from, and then only for sync.
+        const configSha256 = loaded.result.source.sha256;
+        const unsynced = configSha256 !== identity.configSha256;
+        if (unsynced) {
+            const local = (path) => readAnchoredFile(identity.root, path, STRUCTURED_INPUT_BYTE_LIMIT, node, { execute: adapters.execute ?? executeProbe });
+            const [recorded, confirmations] = await Promise.all([local(GUARD_LOCAL_PATHS.generatedConfig), local(ANSWER_CONFIRMATION_PATH)]);
+            const change = guardConfigChange(identity.configSha256, recorded.kind === 'complete' ? recorded.bytes : undefined, { sha256: configSha256, config: loaded.result.config }, confirmations.kind === 'complete' ? confirmations.bytes : undefined);
+            if (change.kind === 'widening' || change.kind === 'unrecorded')
+                return unavailable(guardHeld(identity, `${identity.configPath} changed since the guards were generated and ${guardConfigHeldReason(change)}`, 'guard policy comes from it and an edit that may widen it takes effect only once a human approves it', { kind: 'sync' }));
+        }
         const config = loaded.result.config;
         let publication;
         try {
@@ -200,9 +225,11 @@ export async function runGuardEvaluationApplication(input, adapters) {
             return unavailable(parsed.reason);
         if (parsed.cwd !== data.cwd)
             return unavailable('Guard request cwd does not match its invocation authority.');
-        const prepared = await prepareGuardEvaluationPolicy({ configuration: loaded.result, checkout });
+        const prepared = await prepareGuardEvaluationPolicy({ configuration: loaded.result, checkout }, checkoutsPending.then(unwrap));
         if (prepared.kind !== 'complete')
-            return unavailable('Guard policy authority could not be authenticated.');
+            return unsynced
+                ? unsyncedHold(identity, `, but the guard cannot build its policy from it (${prepared.diagnostics[0]?.message ?? 'no reason given'})`)
+                : unavailable('Guard policy authority could not be authenticated.');
         // The inspector answers synchronously, so what only Git can say is asked first: which protected
         // paths a default ripgrep search reads, and which a repository's index holds for a Git command
         // that prints committed content. A request not asked here gets the walk, or no answer.
@@ -333,7 +360,7 @@ export async function runGuardEvaluationApplication(input, adapters) {
             launched.push(proven);
             return proven;
         };
-        const configured = { canonicalRoot: identity.root, configPath: identity.configPath };
+        const configured = { canonicalRoot: identity.root, configPath: identity.configPath, profiles: agentProfiles(config) };
         for (const { executable, cwd, argv } of parsed.invocations) {
             const proven = prove(executable, cwd, argv, true);
             // The evaluator judges a session's command as one more invocation, so its spelling needs proof too.
@@ -341,6 +368,9 @@ export async function runGuardEvaluationApplication(input, adapters) {
             if (inner)
                 prove(inner[0], cwd, inner.slice(1), false);
         }
+        if (unsynced && !(parsed.tool === 'Bash' && parsed.invocations.length > 0 && parsed.invocations.every(invocation => launched.some(entry => entry.session && entry.executable === invocation.executable && entry.cwd === invocation.cwd
+            && isDeepStrictEqual(entry.argv, invocation.argv) && UNSYNCED_ADMITTED_COMMANDS.some(name => name === commandSpelling(entry.argv.slice(entry.prefix)).name)))))
+            return unsyncedHold(identity, '');
         let launcherSha256;
         if (launched.length) {
             const status = lstatSync(launcher);
@@ -370,24 +400,17 @@ export async function runGuardEvaluationApplication(input, adapters) {
         }
         if (cockpitInvocations.length + prepared.result.policy.projectCommands.length > GUARD_INPUT_LIMITS.invocations)
             return unavailable('Guard candidates exceed the invocation bound.');
-        // The policy pin needs the text an edit applies to, which must be the text the guard was generated for.
+        // The policy pin needs the text an edit applies to, which must be the text the policy was built from.
         const configRead = publication.get(configName);
-        if (configRead.sha256 !== identity.configSha256)
+        if (configRead.sha256 !== configSha256)
             return unavailable('Guard configuration changed during evaluation.');
         const configStatus = lstatSync(identity.configPath);
         // A hard link or another spelling of the configuration is the configuration.
         const isConfig = (path) => {
             if (foldGuardSpelling(path) === foldGuardSpelling(identity.configPath))
                 return true;
-            try {
-                const status = lstatSync(path);
-                return status.dev === configStatus.dev && status.ino === configStatus.ino;
-            }
-            catch (error) {
-                if (hasErrorCode(error, 'ENOENT', 'ENOTDIR'))
-                    return false;
-                throw error;
-            }
+            const status = lstatIfPresentSync(path);
+            return status !== undefined && status.dev === configStatus.dev && status.ino === configStatus.ino;
         };
         const pinned = pinnedPolicyDenial(parsed, configRead.bytes.toString('utf8'), isConfig);
         if (pinned)
@@ -398,7 +421,7 @@ export async function runGuardEvaluationApplication(input, adapters) {
             searchPathRelativeEntry: guardSearchPathRelativeEntry(searchPath),
             ripgrepConfigActive: data.ripgrepConfigActive === true }, inspect);
         const current = await adapters.loadConfig(identity.configPath);
-        if (current.kind !== 'complete' || current.result.source.sha256 !== identity.configSha256)
+        if (current.kind !== 'complete' || current.result.source.sha256 !== configSha256)
             return unavailable('Guard configuration changed during evaluation.');
         for (const [path, before] of [...roots, ...inspected]) {
             const after = lstatSync(path);
@@ -422,13 +445,41 @@ export async function runGuardEvaluationApplication(input, adapters) {
         return unavailable(`Guard authority could not be read or revalidated: ${errorCause(error)}`);
     }
 }
-// The guard runs only against the configuration sync generated it from, so the policy read here is the
-// one the last sync accepted.
+// The guard runs against the configuration sync generated it from, or one that does not widen it and
+// admits only sync and check, so the policy read here grants nothing the last sync did not.
 function ordinaryGrants(config) {
     const policy = effectivePolicy(config);
-    return [...config.browser?.request_preapproval === true ? ['browser-preapproval'] : [],
+    return [...config.browser && browserPreapprovalRequested(config.browser) ? ['browser-preapproval'] : [],
         ...policy.autonomy.sync === 'agent' ? ['autonomy-sync'] : [], ...policy.autonomy.reset === 'agent' ? ['autonomy-reset'] : []];
 }
+// `up --profile` and `session --profile` start that profile's services for one run. Only the default
+// set a person declared is theirs to name, and a profile that mounts an operator-gated sibling, which
+// touches live data or local hardware, never starts without a person.
+function agentProfiles(config) {
+    return config.environment.profiles.filter(profile => !config.sibling.some(row => row.gate === 'operator' && row.mount === `profile:${profile}`));
+}
+/**
+ * Every checkout the guard grants for a sibling: each declared directory, then each checkout `use`
+ * recorded, which is where the agent works on that sibling. A recorded checkout that is gone grants
+ * nothing. Allowed roots, instance protection and project commands all come from this one list.
+ */
+function siblingRoots(config, siblingsRoot, served) {
+    const declared = config.sibling.map((sibling, index) => {
+        const root = resolve(siblingsRoot, sibling.dir);
+        if (!confinedPath(siblingsRoot, root))
+            throw new RefusalError('guard policy sibling escapes its declared root');
+        return { sibling, index, root };
+    });
+    const recorded = declared.flatMap(({ sibling, index }) => {
+        const entry = served.get(sibling.slug);
+        if (!entry?.overridden)
+            return [];
+        if (!lstatIfPresentSync(entry.served)?.isDirectory())
+            return [];
+        return [{ sibling, index, root: entry.served }];
+    });
+    return [...declared, ...recorded];
+}
 class GuardFileMissing extends RefusalError {
     path;
     constructor(path) {
@@ -439,8 +490,12 @@ class GuardFileMissing extends RefusalError {
 function guardPolicyRefusal(message) {
     return lifecycleRefusal(ENVIRONMENT_CODES.LIFECYCLE_EVIDENCE_INVALID, message, 'guard-policy');
 }
-/** Source projections share authenticated authority; installed consumption is admitted separately. */
-export async function prepareGuardEvaluationPolicy(input) {
+/**
+ * Source projections share authenticated authority; installed consumption is admitted separately.
+ * `siblingCheckouts` is the configuration directory's sibling checkout record, when the caller
+ * started reading it already; it is read here otherwise.
+ */
+export async function prepareGuardEvaluationPolicy(input, siblingCheckouts) {
     const inputData = ownDataValues(input, ['configuration', 'checkout']);
     const data = inputData && Object.hasOwn(inputData, 'configuration') && Object.hasOwn(inputData, 'checkout') ? inputData : undefined;
     if (!data)
@@ -455,12 +510,16 @@ export async function prepareGuardEvaluationPolicy(input) {
     if (derived.kind !== 'complete')
         return guardPolicyRefusal(`guard policy registry refused (${derived.code}): ${derived.message}`);
     const guardConfig = CockpitConfig.parse(derived.result.config);
+    const recorded = await (siblingCheckouts ?? readSiblingCheckouts(dirname(loaded.source.path)));
+    if (recorded.kind === 'refusal')
+        return guardPolicyRefusal(recorded.diagnostic.message);
+    const served = servedSiblings(dirname(loaded.source.path), guardConfig, recorded.checkouts);
     const observed = snapshotJson(data.checkout);
     if (observed?.state !== 'available')
         return guardPolicyRefusal('guard policy checkout observation is unavailable');
     try {
         const identities = new Map();
-        let siblingsRoot;
+        let checkoutRoots;
         const result = await withSetupCheckoutProjection(data.checkout, {
             source: loaded.source, cockpitName: loaded.config.cockpit.name, evaluatedAt: Date.parse(observed.observedAt),
         }, (projection) => {
@@ -509,14 +568,11 @@ export async function prepareGuardEvaluationPolicy(input) {
                 return path;
             };
             const canonicalRoot = directory(dirname(loaded.source.path));
-            siblingsRoot = directory(resolve(canonicalRoot, config.cockpit.siblings_root));
+            checkoutRoots = siblingRoots(config, directory(resolve(canonicalRoot, config.cockpit.siblings_root)), served);
             const allowedRoots = new Set([canonicalRoot]);
             const instances = [];
             const templates = [];
-            for (const sibling of config.sibling) {
-                const root = resolve(siblingsRoot, sibling.dir);
-                if (!confinedPath(siblingsRoot, root))
-                    throw new RefusalError('guard policy sibling escapes its declared root');
+            for (const { sibling, root } of checkoutRoots) {
                 allowedRoots.add(directory(root));
                 for (const file of derived.result.secretPaths.filter(row => row.slug === sibling.slug)) {
                     const path = resolve(root, file.path);
@@ -571,16 +627,15 @@ export async function prepareGuardEvaluationPolicy(input) {
             return { kind: 'complete', status: 0, diagnostics: [],
                 result: { policy } };
         });
-        if (!result || result.kind !== 'complete' || !siblingsRoot) {
+        if (!result || result.kind !== 'complete' || !checkoutRoots) {
             return result ?? guardPolicyRefusal('guard policy checkout authority is copied, changed, expired or already consumed');
         }
         const boundaries = result.result.policy;
         const projectCommands = [];
-        for (const [siblingIndex, sibling] of guardConfig.sibling.entries()) {
+        for (const { index: siblingIndex, sibling, root: checkoutRoot } of checkoutRoots) {
             const policies = guardConfig.environment.install_policies;
             if (!policies.some(policy => policy.toolchain === sibling.toolchain && (policy.build || policy.test)))
                 continue;
-            const checkoutRoot = resolve(siblingsRoot, sibling.dir);
             const checkoutId = deriveCheckoutId({ checkoutPath: checkoutRoot });
             const evaluatedAt = Date.now();
             const observation = await observeInstallPolicyLockfiles({ source: loaded.source, siblingIndex, siblingSlug: sibling.slug,

package/dist/environment/application/health.d.ts

@@ -2,12 +2,12 @@ import type { ExecuteProbeOutcome } from '../../environment-exec/execute.js';
 import { RefusalError, type CheckoutId, type EnvironmentDiagnostic, type EnvironmentObservation, type ExecutionStep, type StackId } from '../contract.js';
 import { type ResolvedExecutable } from '../executable.js';
 import { type SetupCheckoutProjection } from '../setup-observation.js';
-import type { LoadedConfigProjection } from '../../config/load.js';
+import { loadCockpitConfig, type LoadedConfigProjection } from '../../config/load.js';
 import { type EvaluatedObservation, type PreflightContext, type PreflightEvaluation } from '../observations.js';
 import { type ComparisonRemoteResult } from '../git-observation.js';
 import type { CapturedRuntimeEvidence, EnvironmentSnapshot } from '../evidence.js';
 import { type ReadinessRefusal } from './lifecycle-context.js';
-export interface ComparisonRemoteInput {
+interface ComparisonRemoteInput {
     readonly executable: ResolvedExecutable;
     readonly checkoutRoot: string;
     readonly env: Readonly<Record<string, string>>;
@@ -29,8 +29,12 @@ export interface HealthObservationProducers {
     readonly ports: () => Promise<readonly EnvironmentObservation[]>;
     readonly runtime: () => Promise<readonly EnvironmentObservation[]>;
     readonly state: () => Promise<readonly EnvironmentObservation[]>;
+    readonly siblings: () => Promise<readonly EnvironmentObservation[]>;
     readonly templates: () => Promise<readonly EnvironmentObservation[]>;
 }
+export type LoadedCockpitConfigResult = Extract<Awaited<ReturnType<typeof loadCockpitConfig>>, {
+    readonly kind: 'complete';
+}>;
 export interface HealthObservationSourceInput {
     readonly checkout: SetupCheckoutProjection;
     readonly configuration: LoadedConfigProjection;
@@ -55,6 +59,11 @@ export interface ObservationCommandAdapters {
     readonly execute: (step: ExecutionStep, options: {
         readonly signal?: AbortSignal;
     }) => Promise<ExecuteProbeOutcome>;
+    /**
+     * Which checkout serves each sibling, what a worktree lacks, and whether the running stack is stale.
+     * Reads cockpit.toml again unless handed the loaded configuration or called after `load`.
+     */
+    readonly inspectServedSiblings?: (loaded?: LoadedCockpitConfigResult) => Promise<readonly EnvironmentDiagnostic[]>;
 }
 export interface PreflightCommandInput {
     readonly configPath: string;
@@ -65,13 +74,13 @@ export interface ComparisonRemoteEvaluation {
     readonly sibling: string;
     readonly result: ComparisonRemoteResult;
 }
-export interface ApplicationPreflightEvaluation {
+interface ApplicationPreflightEvaluation {
     readonly verdict: PreflightEvaluation['verdict'];
     readonly revision: string;
     readonly checks: readonly EvaluatedObservation[];
     readonly comparisons: readonly ComparisonRemoteEvaluation[];
 }
-export type PreflightCommandResult = Readonly<{
+type PreflightCommandResult = Readonly<{
     kind: 'complete';
     status: 0;
     diagnostics: readonly EnvironmentDiagnostic[];
@@ -122,7 +131,7 @@ interface PreparedHealthObservation {
     readonly notices: () => readonly EnvironmentDiagnostic[];
     readonly unobservable: ReadonlyMap<string, string>;
 }
-declare const healthProducerNames: readonly ["claims", "git", "host", "lifecycle", "ports", "runtime", "state", "templates", "envSchema", "surfaces"];
+declare const healthProducerNames: readonly ["claims", "git", "host", "lifecycle", "ports", "runtime", "state", "templates", "envSchema", "siblings", "surfaces"];
 export declare function applicationDiagnostic(code: EnvironmentDiagnostic['code'], message: string, target: string, fix?: string): EnvironmentDiagnostic;
 export declare function issueHealthObservationSource(rawSource: HealthObservationSourceInput): HealthObservationSource | undefined;
 export declare function prepareHealthObservation(input: {

package/dist/environment/application/health.js

@@ -5,6 +5,7 @@ import { resolvedGitExecutable } from '../executable.js';
 import { declaresNothingToRun } from '../declaration.js';
 import { checkoutId as deriveCheckoutId, stackId as deriveStackId } from '../identity.js';
 import { consumeSetupCheckoutProjection } from '../setup-observation.js';
+import { loadCockpitConfig } from '../../config/load.js';
 import { aggregateObservations, stoppedStackApplicability, } from '../observations.js';
 import { envSchemaToolMissing, VARLOCK_INSTALL_URL } from '../env-schema-observation.js';
 import { SURFACE_OBSERVATION_CODES } from '../generated-application/surface-observation.js';
@@ -25,7 +26,7 @@ export class ObservationProducerRefusal extends RefusalError {
 }
 const issuedHealthObservationSources = new WeakMap();
 const healthProducerNames = Object.freeze([
-    'claims', 'git', 'host', 'lifecycle', 'ports', 'runtime', 'state', 'templates', 'envSchema', 'surfaces',
+    'claims', 'git', 'host', 'lifecycle', 'ports', 'runtime', 'state', 'templates', 'envSchema', 'siblings', 'surfaces',
 ]);
 export function applicationDiagnostic(code, message, target, fix) {
     return { severity: 'error', code, message, target, ...(fix === undefined ? {} : { fix }) };
@@ -348,6 +349,7 @@ function unavailablePreflight(message, forwarded) {
 export async function runPreflight(input, adapters) {
     let health;
     let refused;
+    let servedFindings = Promise.resolve([]);
     try {
         const source = await adapters.load(input, issueHealthObservationSource, (diagnostics) => { refused = diagnostics; return undefined; }, 'preflight');
         if (!source)
@@ -355,6 +357,8 @@ export async function runPreflight(input, adapters) {
         const observed = prepareHealthObservation(input, source);
         if (!observed)
             return unavailablePreflight('preflight requires authenticated steady lifecycle evidence');
+        // Reports only and catches its own errors, so it runs beside the health evaluation.
+        servedFindings = adapters.inspectServedSiblings?.() ?? Promise.resolve([]);
         health = await evaluateApplicationHealth(observed, adapters);
     }
     catch (error) {
@@ -370,10 +374,12 @@ export async function runPreflight(input, adapters) {
     };
     // A stopped stack never passes the gate, whatever the rows observable without it say.
     const passed = health.verdict === 'pass' && health.stopped === null;
+    // Warnings only: a stale stack still answers, and whether a changed lockfile matters is the product's call.
+    const served = await servedFindings;
     return {
         kind: passed ? 'complete' : 'blocked',
         status: passed ? 0 : 2,
-        diagnostics: healthDiagnostics(health),
+        diagnostics: [...healthDiagnostics(health), ...served],
         result,
     };
 }

package/dist/environment/application/lifecycle-context.d.ts

@@ -52,6 +52,8 @@ export interface RuntimeReadiness {
     readonly runtimeObservations: readonly EnvironmentObservation[];
     /** The digest of each file this runtime is started from, by the name a person edits. */
     readonly inputs: RuntimeInputs;
+    /** The Compose profiles this runtime activates, sorted. */
+    readonly activeProfiles: readonly string[];
 }
 export interface AcquiredPorts {
     readonly leaseResult: LeasePortFamilyResult;
@@ -65,7 +67,7 @@ interface LifecycleCommandAdapters {
     execute(step: ExecutionStep): Promise<ExecuteProbeOutcome>;
     withRuntimeReadiness<T>(context: LifecycleRunContext, use: (runtime: RuntimeReadiness) => Promise<T>, ports?: PortLeaseProjection, refuse?: ReadinessRefusal<T>, purpose?: RuntimeReadinessPurpose): Promise<T | undefined>;
 }
-export type SeedOutcome = Readonly<{
+type SeedOutcome = Readonly<{
     kind: 'none' | 'current' | 'ran';
 }> | Readonly<{
     kind: 'refusal';
@@ -76,6 +78,11 @@ export interface UpCommandAdapters extends LifecycleCommandAdapters {
     seed?(context: LifecycleRunContext, up: Extract<UpCommandResult, {
         kind: 'complete';
     }>['result']): Promise<SeedOutcome>;
+    /**
+     * Records the siblings' lockfiles and rebuild inputs the stack runs on; warnings when it cannot.
+     * A resumed stack keeps the record of its start, because resuming restarts nothing.
+     */
+    recordStackInputs?(context: LifecycleRunContext, change: 'started' | 'resumed' | 'unchanged'): Promise<readonly EnvironmentDiagnostic[]>;
     withLifecycleStage<T>(context: LifecycleRunContext, use: (stage: LifecycleStageProjection) => Promise<T>, refuse?: ReadinessRefusal<T>): Promise<T | undefined>;
     withAcquiredPorts<T>(context: LifecycleRunContext, use: (ports: AcquiredPorts) => Promise<T>, refuse?: ReadinessRefusal<T>): Promise<T | undefined>;
 }
@@ -126,7 +133,7 @@ export type DownCommandResult = EnvironmentCommandOutcome<Readonly<{
     stackId: StackId;
     change: 'removed' | 'unchanged';
 }>>;
-export interface ResetPreviewResult {
+interface ResetPreviewResult {
     readonly stackId: StackId;
     readonly planDigest: string;
     readonly targets: readonly ResetTargetInput[];
@@ -155,7 +162,7 @@ export interface OperatorResetSession {
     }>;
     decide(decision: 'approve' | 'decline'): Promise<OperatorResetResult>;
 }
-export interface DestructiveRunContextInput {
+interface DestructiveRunContextInput {
     readonly lifecycle: LifecycleRunContext;
     readonly instance: SelectDestructiveInstanceInput;
     /** The holder claim the load took on a stack no session held, so this run could read it. */

package/dist/environment/application/lifecycle-state.js

@@ -6,7 +6,7 @@ import { abortStateTransaction, readState, transactState } from '../state.js';
 import { decodeLifecycleRecord, resolveLifecycleStage } from '../lifecycle-stage.js';
 import { inspectPortLeaseTransfer, revalidatePortLeaseProjection } from '../ports.js';
 import { commitDrainOutcome, decodeCoordinationRecord } from '../claims.js';
-import { lifecycleRefusal, ownerDiagnostic, shellQuote } from './shared.js';
+import { lifecycleRefusal, ownerDiagnostic } from './shared.js';
 import { withLifecycleConfiguration } from './lifecycle-context.js';
 export function lifecycleSuggestion(context, command) {
     return cockpitCommand(command, { config: context.source.path });
@@ -82,7 +82,7 @@ export async function publishLifecycleRecord(context, expected, value, transfer,
 // Port leases are machine-wide, so up reads every cockpit's state. Another cockpit's namespace this
 // version cannot read is skipped there rather than refused; this cockpit's own unreadable state still
 // refuses in the command itself. The skipped ones are named in a single warning with one cleanup
-// command, and only by doctor: the folders belong to other cockpits, usually ones an earlier version
+// command (`stacks prune`), and only by doctor: the folders belong to other cockpits, usually ones an earlier version
 // left behind, and repeating them on every up (and so every session) buried each result under lines
 // about cockpits the person was not working on. A port they still hold fails up on its own.
 export function unreadableStateWarning(skipped) {
@@ -96,7 +96,7 @@ export function unreadableStateWarning(skipped) {
         code: ENVIRONMENT_CODES.STATE_RECORD_MALFORMED,
         message: `${count} under ${directory} cannot be read by this cockpit version (${reasons}), so their claims and port leases were ignored`,
         target: directory,
-        fix: `ask the person who owns this machine whether any cockpit still uses them; if none does, stop any stack they started (docker compose ls lists them), then delete them: rm -rf ${skipped.map(({ path }) => shellQuote(path)).join(' ')}`,
+        fix: `preview their removal with ${cockpitCommand('stacks prune')}, which removes those an earlier cockpit build left once none of their stacks is kept, then apply it with --apply`,
     };
 }
 // `up` keeps a holder whenever containers may exist, so a stack no session holds has nothing running.
@@ -147,6 +147,7 @@ export async function invalidateCompletedLifecycle(context, workBasisSha256, ope
         completedServices: [],
         ...(purpose === 'down' ? { teardownComplete: true } : {
             ...(stored.value.runtimeInputs ? { runtimeInputs: stored.value.runtimeInputs } : {}),
+            ...(stored.value.activeProfiles ? { activeProfiles: stored.value.activeProfiles } : {}),
         }),
     };
     const publication = await publishLifecycleRecord(context, stored.record, value);

package/dist/environment/application/lifecycle.d.ts

@@ -1,4 +1,4 @@
-import { type LifecycleProgress } from '../contract.js';
+import { type EnvironmentDiagnostic, type LifecycleProgress } from '../contract.js';
 import { type RuntimeServiceEvidence, type RuntimeServiceFailureEvidence, type RuntimeServiceObservation, type RuntimeTopologyEvidence } from '../runtime.js';
 import { type SessionCommandAdapters, type SessionCommandInput, type SessionCommandResult, type SleepCommandAdapters, type SleepCommandInput, type SleepCommandResult, type UpCommandAdapters, type UpCommandInput, type UpCommandResult } from './lifecycle-context.js';
 export { decodeLifecycleRecord } from '../lifecycle-stage.js';
@@ -12,6 +12,7 @@ type ServiceAdmission = {
     readonly logs?: RuntimeServiceFailureEvidence | RuntimeServiceObservation;
 };
 export declare function revalidateService(topology: RuntimeTopologyEvidence, completed: LifecycleProgress['completedServices'][number], adapters: Pick<UpCommandAdapters, 'execute'>): Promise<ServiceAdmission>;
+export declare function collectFailureLogs(evidence: RuntimeServiceFailureEvidence | RuntimeServiceObservation | undefined, service: string, adapters: Pick<UpCommandAdapters, 'execute'>): Promise<readonly EnvironmentDiagnostic[]>;
 export declare function runUp(input: UpCommandInput, adapters: UpCommandAdapters): Promise<UpCommandResult>;
 export declare function runSession(input: SessionCommandInput, adapters: SessionCommandAdapters): Promise<SessionCommandResult>;
 export declare function runSleep(input: SleepCommandInput, adapters: SleepCommandAdapters): Promise<SleepCommandResult>;

package/dist/environment/application/lifecycle.js

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { constants as osConstants } from 'node:os';
 import { isDeepStrictEqual } from 'node:util';
-import { basename, isAbsolute, join, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { cleanupFencedExecution, repairFencedExecution } from '../../environment-exec/execute.js';
 import { ENVIRONMENT_CODES, forwardedRefusal, } from '../contract.js';
 import { cockpitCommand } from '../../fix-catalogue.js';
@@ -15,6 +15,7 @@ import { observationSatisfiesExpectation } from '../observations.js';
 import { issuedLifecycleRuns, lifecycleContextRefusal, withLifecycleConfiguration, withLifecycleRunNotices, } from './lifecycle-context.js';
 import { exactCommandConfigPath, invalidateCompletedLifecycle, lifecycleSuggestion, publishDrainOutcome, publishLifecycleRecord, readLifecycleRecord, repairRequired, unheldStack, } from './lifecycle-state.js';
 import { lifecycleRefusal, ownerDiagnostic, uniqueDiagnostics } from './shared.js';
+import { forgetStackInputs } from '../stack-inputs.js';
 function seconds(millis) {
     return String(millis / 1_000);
 }
@@ -89,7 +90,7 @@ async function reportFailedService(evidence, service, context, adapters, stop) {
         ...(stopped === false ? [ownerDiagnostic(ENVIRONMENT_CODES.EXECUTION_COMPENSATION_STEP_FAILED, `the failed service ${service} could not be stopped, so it may keep restarting; run \`${lifecycleSuggestion(context, 'down')}\` to remove it`, service)] : []),
     ];
 }
-async function collectFailureLogs(evidence, service, adapters) {
+export async function collectFailureLogs(evidence, service, adapters) {
     if (!evidence)
         return [ownerDiagnostic(ENVIRONMENT_CODES.LIFECYCLE_EVIDENCE_INVALID, 'bounded failure logs are unavailable', service)];
     const plan = planFailureLogs({ evidence, tail: 200, timeoutMs: 10_000, outputLimitBytes: 1_048_576 });
@@ -282,6 +283,7 @@ async function executeUpRound(context, adapters, forceReset, rememberAcquisition
             holderId: context.holderId,
             ...planned.plan.progress,
             runtimeInputs: runtime.inputs,
+            ...(runtime.activeProfiles.length > 0 ? { activeProfiles: runtime.activeProfiles } : {}),
         };
         if (!stored || resetProgress || stored.value.holderId !== context.holderId && !completedCoTenant) {
             // The first lifecycle data starts its durable history, as `setup` does (an existing
@@ -458,6 +460,9 @@ async function upWithContext(context, adapters) {
                     diagnostics: uniqueDiagnostics([...result.diagnostics, ...data.diagnostics]) };
             if (data?.kind === 'ran' || data?.kind === 'current')
                 result = { ...result, result: { ...result.result, seed: data.kind } };
+            const unrecorded = await adapters.recordStackInputs?.(context, result.result.change) ?? [];
+            if (unrecorded.length > 0)
+                result = { ...result, diagnostics: uniqueDiagnostics([...result.diagnostics, ...unrecorded]) };
         }
         if (result.kind === 'refusal' && releasable()) {
             const compensation = await compensateAcquiredPortHolder({
@@ -596,7 +601,10 @@ export async function runSleep(input, adapters) {
         return lifecycleRefusal(ENVIRONMENT_CODES.LIFECYCLE_EVIDENCE_INVALID, 'lifecycle run authority is unavailable', configPath);
     }
     const context = loaded.result;
-    return withLifecycleRunNotices(context, await sleepWithContext(context, adapters));
+    const outcome = await sleepWithContext(context, adapters);
+    // A stopped stack runs nothing a later doctor could call stale.
+    const forgotten = outcome.kind === 'complete' && outcome.result.change === 'stopped' ? await forgetStackInputs(dirname(context.source.path)) : [];
+    return withLifecycleRunNotices(context, forgotten.length === 0 ? outcome : { ...outcome, diagnostics: uniqueDiagnostics([...outcome.diagnostics, ...forgotten]) });
 }
 async function sleepWithContext(context, adapters) {
     let recovery = await inspectSleepDrainRecovery({

package/dist/environment/application/services.d.ts

@@ -0,0 +1,60 @@
+import type { ExecuteProbeOutcome, ForegroundProcessInput, ForegroundProcessOutcome } from '../../environment-exec/execute.js';
+import { type EnvironmentCommandOutcome, type EnvironmentDiagnostic, type ExecutionStep, type LifecycleProgress } from '../contract.js';
+import { type RuntimeServiceState, type RuntimeTopologyEvidence } from '../runtime.js';
+export interface ServiceObservation {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly completedServices: LifecycleProgress['completedServices'];
+    /** Records the container a rebuild put in place of the one the stack was started with. */
+    readonly recordContainer: (service: string, containerId: string) => Promise<readonly EnvironmentDiagnostic[]>;
+}
+export interface ServiceCommandAdapters {
+    readonly observe: (input: {
+        readonly configPath: string;
+    }) => Promise<ServiceObservation>;
+    readonly execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+    readonly executeForeground: (input: ForegroundProcessInput) => Promise<ForegroundProcessOutcome>;
+}
+export declare function runServicePs(input: Readonly<{
+    configPath: string;
+}>, adapters: ServiceCommandAdapters): Promise<EnvironmentCommandOutcome<Readonly<{
+    services: readonly RuntimeServiceState[];
+}>>>;
+/**
+ * `restart` restarts the container in place; `rebuild` builds the service's image and replaces its
+ * container, for a change baked into the image. Both then wait for the service as `up` does and
+ * report its logs when it does not become healthy.
+ */
+export declare function runServiceRestart(input: Readonly<{
+    configPath: string;
+    service: string;
+    verb: 'restart' | 'rebuild';
+}>, adapters: ServiceCommandAdapters): Promise<EnvironmentCommandOutcome<Readonly<{
+    service: string;
+    containerId: string;
+    change: 'restarted' | 'rebuilt';
+}>>>;
+type ServiceExecResult = Readonly<{
+    kind: 'complete';
+    status: number;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: Readonly<{
+        exitCode: number;
+        signal: NodeJS.Signals | null;
+    }>;
+}> | Readonly<{
+    kind: 'refusal';
+    status: number;
+    diagnostics: readonly EnvironmentDiagnostic[];
+    result: null;
+}>;
+/**
+ * Runs a command inside one service's container in the foreground. A command that exits nonzero
+ * is the command's answer, not a cockpit failure, so its status passes through as `session` does.
+ */
+export declare function runServiceExec(input: Readonly<{
+    configPath: string;
+    service: string;
+    argv: readonly [string, ...string[]];
+    tty: boolean;
+}>, adapters: ServiceCommandAdapters): Promise<ServiceExecResult>;
+export {};