@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/environment/reclaim.js

@@ -265,39 +265,43 @@ function selectionRow(bytes) {
 // Ownership is label-based: a resource without this stack's label is never removed, so listing the
 // rest of a shared daemon only cost time. Listing and inspecting every container, image and volume
 // on a daemon with a hundred unrelated containers made each `down` observation take seconds, and
-// `container ls --size` alone ran past the step timeout. Volumes stay unfiltered because a reset
-// refuses when a declared volume name belongs to something this stack does not own, and an
+// `container ls --size` alone ran past the step timeout. A stack's volumes stay unfiltered because a
+// reset refuses when a declared volume name belongs to something this stack does not own, and an
 // unlabelled volume of that name would otherwise be invisible; their inspection is still scoped.
-function runtimeCommand(kind, selection, stackId) {
+// The machine-wide listing has no such name to check, so it lists cockpit-labelled volumes alone.
+function runtimeCommand(kind, selection, owner) {
     if (kind === 'build-cache')
         return ['--host', selection.endpoint, 'builder', 'du', '--format', 'json'];
-    const prefix = ['--host', selection.endpoint];
-    const owned = ['--filter', `label=${REQUIRED_LABELS.stack}=${stackId}`];
+    const owned = ['--filter', owner === null ? `label=${REQUIRED_LABELS.stack}` : `label=${REQUIRED_LABELS.stack}=${owner.stackId}`];
     const command = kind === 'container' ? ['container', 'ls', '--all', '--no-trunc', ...owned]
-        : kind === 'volume' ? ['volume', 'ls'] : kind === 'image' ? ['image', 'ls', '--all', '--no-trunc', ...owned] : [kind, 'ls', '--no-trunc', ...owned];
-    return [...prefix, ...command, '--format', discoveryFormat(kind)];
+        : kind === 'volume' ? ['volume', 'ls', ...owner === null ? owned : []]
+            : kind === 'image' ? ['image', 'ls', '--all', '--no-trunc', ...owned] : [kind, 'ls', '--no-trunc', ...owned];
+    return ['--host', selection.endpoint, ...command, '--format', discoveryFormat(kind, owner)];
 }
-function discoveryFormat(kind) {
+function discoveryFormat(kind, owner) {
     const id = kind === 'volume' ? '{{json .Name}}' : '{{json .ID}}';
     const name = kind === 'container' ? '{{json .Names}}' : kind === 'image' ? '{{json .Repository}}' : '{{json .Name}}';
     const label = (key) => `{{json (.Label "${key}")}}`;
+    const labels = kind === 'image' ? '{}' : `{${(owner === null ? MACHINE_LABELS : listedLabels(kind)).map((key) => `"${key}":${label(key)}`).join(',')}}`;
+    // The machine-wide listing attributes each resource by its labels alone and reports whether a container runs.
+    if (owner === null)
+        return `{"id":${id},"name":${name},"state":${kind === 'container' ? '{{json .State}}' : '""'},"labels":${labels}}`;
     // Without `--size` a container prints a misleading "0B (virtual ...)", so its size is unmeasured.
     const bytes = kind === 'network' || kind === 'container' ? 'null' : '{{json .Size}}';
-    const labels = kind === 'image' ? '{}' : `{${listedLabels(kind).map((key) => `"${key}":${label(key)}`).join(',')}}`;
     return `{"id":${id},"name":${name},"labels":${labels},"referenced":false,"bytes":${bytes}}`;
 }
 function listedLabels(kind) {
     return [...Object.values(REQUIRED_LABELS), ...kind === 'volume' ? Object.values(COMPOSE_LABELS) : []];
 }
-function dockerLabels(value, kind) {
+/** The labels Docker printed, refused when any is not `allowed` or its value is too long or holds a NUL; empty values are dropped. */
+function dockerLabels(value, allowed, maxLength = 512) {
     if (value === null || typeof value !== 'object' || Array.isArray(value))
         return undefined;
     const labels = {};
-    const allowed = new Set(listedLabels(kind));
-    if (Object.keys(value).some((key) => !allowed.has(key)))
+    if (Object.keys(value).some((key) => !allowed.includes(key)))
         return undefined;
     for (const [key, labelValue] of Object.entries(value)) {
-        if (typeof labelValue !== 'string' || labelValue.length > 512 || labelValue.includes('\0'))
+        if (typeof labelValue !== 'string' || labelValue.length > maxLength || labelValue.includes('\0'))
             return undefined;
         if (labelValue !== '')
             labels[key] = labelValue;
@@ -345,7 +349,7 @@ function dockerResource(value, kind) {
     const name = row.name;
     const labels = kind === 'image'
         ? row.labels !== null && typeof row.labels === 'object' && !Array.isArray(row.labels) && exactKeys(row.labels, []) ? {} : undefined
-        : dockerLabels(row.labels, kind);
+        : dockerLabels(row.labels, listedLabels(kind));
     const bytes = dockerBytes(row.bytes, kind === 'container');
     const referenced = kind === 'image' ? typeof row.referenced === 'boolean' ? row.referenced : undefined : row.referenced;
     return typeof id === 'string' && typeof name === 'string' && labels !== undefined && bytes !== undefined && typeof referenced === 'boolean'
@@ -500,17 +504,8 @@ async function selectDocker(input, executable, env, execute) {
         return undefined;
     return { value: { context: input.context, endpoint: row.endpoint }, startedAt: outcome.receipt.startedAt, finishedAt: outcome.receipt.finishedAt };
 }
-async function listResources(runtime, kind, execute) {
-    const step = exactStep(`runtime:discover:${kind}`, [runtime.executable.canonicalPath, ...runtimeCommand(kind, runtime.selection, runtime.stackId)], runtime.executable, runtime.cwd, runtime.env, runtime.timeoutMs, [], {
-        stackId: runtime.stackId, cockpitId: runtime.cockpitId, resourceKind: kind,
-        dockerContext: runtime.selection.context, dockerEndpoint: runtime.selection.endpoint,
-    }, [], OUTPUT_LIMIT);
-    if (step === undefined)
-        return undefined;
-    const outcome = cleanOutput(await execute(step));
-    const text = outcome === undefined ? undefined : utf8(outcome.stdout);
-    if (outcome === undefined || text === undefined)
-        return undefined;
+/** One stack's listed resources of one kind, or nothing when any row cannot be read. */
+function stackRows(text, kind) {
     const resources = [];
     for (const line of text.split('\n')) {
         if (line.length === 0)
@@ -538,7 +533,37 @@ async function listResources(runtime, kind, execute) {
     }
     if (resources.length > MAX_RESOURCES || new Set(resources.map(({ id }) => id)).size !== resources.length)
         return undefined;
-    return { value: resources.sort((a, b) => lexical(a.id, b.id)), startedAt: outcome.receipt.startedAt, finishedAt: outcome.receipt.finishedAt };
+    return resources.sort((a, b) => lexical(a.id, b.id));
+}
+/**
+ * Lists every kind at once on the context's daemon, reading the selection before and after so the
+ * listings describe one daemon. A step that fails, writes to stderr or prints a row `parse` rejects
+ * fails the whole listing closed.
+ */
+async function listOnSelectedDaemon(input, executable, env, execute, owner, kinds, parse) {
+    const planned = await selectDocker(input, executable, env, execute);
+    if (planned === undefined)
+        return undefined;
+    const selection = planned.value;
+    const listed = await Promise.all(kinds.map(async (kind) => {
+        const step = exactStep(`${owner === null ? 'stacks' : 'runtime'}:discover:${kind}`, [executable.canonicalPath, ...runtimeCommand(kind, selection, owner)], executable, input.cwd, env, input.timeoutMs, [], {
+            ...owner === null ? {} : { stackId: owner.stackId, cockpitId: owner.cockpitId },
+            resourceKind: kind, dockerContext: selection.context, dockerEndpoint: selection.endpoint,
+        }, [], OUTPUT_LIMIT);
+        const outcome = step === undefined ? undefined : cleanOutput(await execute(step));
+        const text = outcome === undefined ? undefined : utf8(outcome.stdout);
+        const rows = text === undefined ? undefined : parse(text, kind);
+        return rows === undefined ? undefined : { value: rows, startedAt: outcome.receipt.startedAt, finishedAt: outcome.receipt.finishedAt };
+    }));
+    if (listed.some((value) => value === undefined))
+        return undefined;
+    const lists = listed;
+    const listedAt = lists.map(({ finishedAt }) => finishedAt).sort(lexical).at(-1);
+    const reselected = await selectDocker(input, executable, env, execute);
+    if (reselected === undefined || !sameSelection(reselected.value, selection)
+        || Date.parse(reselected.startedAt) < Date.parse(listedAt))
+        return undefined;
+    return { selection, lists, listedAt, reselected };
 }
 /** Runs one kind's inspection steps; an oversized object names its chunk instead of failing anonymously. */
 async function runInspections(steps, kind, execute) {
@@ -569,7 +594,7 @@ async function inspectImages(runtime, images, execute) {
             return undefined;
         for (const [position, record] of rows.entries()) {
             const resourceId = ids[position];
-            const observedLabels = exactKeys(record, ['id', 'labels']) ? dockerLabels(record.labels) : undefined;
+            const observedLabels = exactKeys(record, ['id', 'labels']) ? dockerLabels(record.labels, listedLabels()) : undefined;
             if (record.id !== resourceId || observedLabels === undefined || labels.has(resourceId))
                 return undefined;
             labels.set(resourceId, observedLabels);
@@ -678,23 +703,14 @@ function sameSelection(left, right) {
 async function discoverReclaimRound(input, executable, env, execute) {
     // The selection is read before and after the listings, and again after the inspections, so the
     // context's endpoint cannot have moved to another daemon while this stack was being read.
-    const planned = await selectDocker(input, executable, env, execute);
-    if (planned === undefined)
+    const listed = await listOnSelectedDaemon(input, executable, env, execute, { stackId: input.stackId, cockpitId: input.cockpitId }, DISCOVERY_KINDS, stackRows);
+    if (listed === undefined || Date.parse(listed.reselected.finishedAt) - Date.parse(listed.listedAt) > 30_000)
         return undefined;
+    const { lists, listedAt, selection } = listed;
     const runtime = {
         executable, cwd: input.cwd, env, timeoutMs: input.timeoutMs,
-        stackId: input.stackId, cockpitId: input.cockpitId, selection: planned.value,
+        stackId: input.stackId, cockpitId: input.cockpitId, selection,
     };
-    const listed = await Promise.all(DISCOVERY_KINDS.map((kind) => listResources(runtime, kind, execute)));
-    if (listed.some((value) => value === undefined))
-        return undefined;
-    const lists = listed;
-    const listedAt = lists.map(({ finishedAt }) => finishedAt).sort(lexical).at(-1);
-    const current = await selectDocker(input, executable, env, execute);
-    if (current === undefined || !sameSelection(current.value, planned.value)
-        || Date.parse(current.startedAt) < Date.parse(listedAt)
-        || Date.parse(current.finishedAt) - Date.parse(listedAt) > 30_000)
-        return undefined;
     const [containers, networks, volumes, images, buildCache] = lists.map(({ value }) => value);
     const inspect = boundedExecutor(execute, MAX_CONCURRENT_INSPECTIONS);
     const inspected = await Promise.all([
@@ -718,10 +734,10 @@ async function discoverReclaimRound(input, executable, env, execute) {
     if (Date.parse(finishedAt) - Date.parse(startedAt) > 30_000)
         return undefined;
     const confirmed = await selectDocker(input, executable, env, execute);
-    if (confirmed === undefined || !sameSelection(confirmed.value, planned.value)
+    if (confirmed === undefined || !sameSelection(confirmed.value, selection)
         || Date.parse(confirmed.startedAt) < Date.parse(finishedAt))
         return undefined;
-    return { observedAt: finishedAt, producer: 'runtime-resource-discovery', resources, startedAt, stackId: input.stackId, selection: planned.value };
+    return { observedAt: finishedAt, producer: 'runtime-resource-discovery', resources, startedAt, stackId: input.stackId, selection };
 }
 /**
  * Lists and inspects this stack's runtime resources on the selected Docker context. Discovery
@@ -741,6 +757,95 @@ export async function discoverReclaim(input, execute) {
     return await discoverReclaimRound(input, executable, env, execute)
         ?? await discoverReclaimRound(input, executable, env, execute);
 }
+const MACHINE_KINDS = ['container', 'network', 'volume'];
+const COMPOSE_WORKING_DIR = 'com.docker.compose.project.working_dir';
+const MACHINE_LABELS = [...Object.values(REQUIRED_LABELS), COMPOSE_LABELS.project, COMPOSE_WORKING_DIR];
+const RUNNING_STATES = new Set(['running', 'restarting', 'paused']);
+// Each removal names its resources in argv, which a step bounds; a chunk also keeps the ids Docker
+// echoes on stdout within the step's default output cap.
+const REMOVAL_CHUNK = 128;
+function machineRows(text, kind) {
+    const resources = [];
+    let unattributed = 0;
+    for (const line of text.split('\n')) {
+        if (line.length === 0)
+            continue;
+        // Unparseable docker output is unproven; the discovery fails closed.
+        const row = tryParseJson(line);
+        if (row === null || typeof row !== 'object' || Array.isArray(row) || !exactKeys(row, ['id', 'name', 'state', 'labels']))
+            return undefined;
+        const { id, name, state, labels: listed } = row;
+        // A working directory is a path, so its label may run far past a stack's own label bound.
+        const labels = listed !== null && typeof listed === 'object' && exactKeys(listed, MACHINE_LABELS) ? dockerLabels(listed, MACHINE_LABELS, 4_096) : undefined;
+        if (typeof id !== 'string' || !RESOURCE_ID.test(id) || typeof name !== 'string' || name.length === 0 || name.length > 512
+            || typeof state !== 'string' || state.length > 64 || labels === undefined)
+            return undefined;
+        const stack = labels[REQUIRED_LABELS.stack] ?? '';
+        const owner = labels[REQUIRED_LABELS.owner] ?? '';
+        if (!STACK_ID.test(stack) || !COCKPIT_ID.test(owner) || !SHA256.test(labels[REQUIRED_LABELS.config] ?? '')) {
+            unattributed += 1;
+            continue;
+        }
+        const workingDir = labels[COMPOSE_WORKING_DIR];
+        resources.push({
+            kind, id, name, cockpitId: owner, stackId: stack,
+            running: kind === 'container' && RUNNING_STATES.has(state),
+            composeProject: labels[COMPOSE_LABELS.project] ?? null,
+            workingDir: kind === 'container' && workingDir !== undefined && isAbsolute(workingDir) ? normalize(workingDir) : null,
+        });
+    }
+    return { resources, unattributed };
+}
+/**
+ * Lists every container, network and volume on the selected daemon that carries cockpit's stack
+ * label, whichever cockpit or checkout started it, for the machine-wide stack inventory. Ownership
+ * comes from the labels alone; nothing is attributed by its name. The selection is read before and
+ * after the listings, as `discoverReclaim` does, so the listings describe one daemon.
+ */
+export async function discoverMachineStacks(input, execute) {
+    const executable = resolvedDockerExecutable(input.executable);
+    const env = safeEnvironment(input.env);
+    if (executable === undefined || env === undefined || !DOCKER_SELECTOR.test(input.context)
+        || input.host !== undefined && (admitLocalDockerEndpoint(input.host) === undefined || input.context !== 'default')
+        || !validExecutionInput(executable, input.cwd, input.env, input.timeoutMs))
+        return undefined;
+    const listed = await listOnSelectedDaemon(input, executable, env, execute, null, MACHINE_KINDS, machineRows);
+    if (listed === undefined)
+        return undefined;
+    const resources = listed.lists.flatMap(({ value }) => value.resources);
+    if (resources.length > MAX_RESOURCES)
+        return undefined;
+    return {
+        selection: listed.selection, observedAt: listed.listedAt,
+        resources: resources.sort((left, right) => lexical(`${left.kind}:${left.id}`, `${right.kind}:${right.id}`)),
+        unattributed: listed.lists.reduce((sum, { value }) => sum + value.unattributed, 0),
+    };
+}
+/**
+ * The Docker removals prune runs for one kind of one orphaned stack's resources, as the machine
+ * discovery attributed them: one client per chunk rather than one per resource. Undefined when the
+ * resources are not all of one kind and one stack, or a step cannot be built.
+ */
+export function machineStackRemovalSteps(input, selection, resources) {
+    const executable = resolvedDockerExecutable(input.executable);
+    const env = safeEnvironment(input.env);
+    const [first] = resources;
+    if (first === undefined || executable === undefined || env === undefined || admitLocalDockerEndpoint(selection.endpoint) === undefined
+        || resources.some(({ kind, stackId, cockpitId, id }) => kind !== first.kind || stackId !== first.stackId || cockpitId !== first.cockpitId || !RESOURCE_ID.test(id))
+        || !validExecutionInput(executable, input.cwd, input.env, input.timeoutMs))
+        return undefined;
+    const command = first.kind === 'container' ? ['container', 'rm', '--force'] : [first.kind, 'rm'];
+    const removals = [];
+    for (let start = 0; start < resources.length; start += REMOVAL_CHUNK) {
+        const chunk = resources.slice(start, start + REMOVAL_CHUNK);
+        const ids = chunk.map(({ id }) => id);
+        const step = exactStep(`stacks:prune:${first.kind}:${digestValue(ids).slice(0, 16)}`, [executable.canonicalPath, '--host', selection.endpoint, ...command, '--', ...ids], executable, input.cwd, env, input.timeoutMs, [], { stackId: first.stackId, cockpitId: first.cockpitId, resourceKind: first.kind, resourceCount: String(ids.length) });
+        if (step === undefined)
+            return undefined;
+        removals.push({ step, resources: chunk });
+    }
+    return removals;
+}
 function refusal(code, message, target, fix) {
     return { kind: 'refusal', diagnostics: [diagnostic(code, message, target, fix)] };
 }

package/dist/environment/runtime.d.ts

@@ -86,8 +86,8 @@ export declare function observeRuntimeExecution(input: {
     readonly plan: ExecutionPlan;
     readonly outcome: ExecuteProbeOutcome;
 }): readonly EnvironmentObservation[];
-export type RuntimeOperation = 'validate' | 'up' | 'down';
-export interface RuntimeAdapterInput {
+type RuntimeOperation = 'validate' | 'up' | 'down';
+interface RuntimeAdapterInput {
     runtime: {
         name: 'docker';
         version: string;
@@ -108,7 +108,7 @@ export interface RuntimeAdapterInput {
     coldStartLimitMillis?: number;
     expectedMountSources?: readonly string[];
 }
-export interface RuntimePlanResult {
+interface RuntimePlanResult {
     runtime: 'docker';
     operation: RuntimeOperation;
     projectName: string;
@@ -120,7 +120,7 @@ export interface ComposeArtifact {
     sha256: string;
 }
 /** Each `[[sibling]] var` and the absolute sibling directory it names. */
-export type SiblingDirectoryVariables = Readonly<Record<string, string>>;
+type SiblingDirectoryVariables = Readonly<Record<string, string>>;
 export type RuntimeAdapterAuthority = 
 /** A stack's own Compose files, which interpolate the lease, the sibling directories and their own defaults. */
 Readonly<{
@@ -133,7 +133,7 @@ Readonly<{
 /** The numeric core of a version Docker or Compose printed, or undefined when it has none. */
 export declare function observedVersionCore(value: string): string | undefined;
 export declare function classifyResolvedRuntimeLiterals(values: readonly string[]): 'resolved' | 'unresolved' | 'unsafe';
-export type MachineFloorPlanInput = {
+type MachineFloorPlanInput = {
     readonly runtimeExecutable: ResolvedExecutable;
     readonly diskExecutable: ResolvedExecutable;
     readonly cwd: string;
@@ -146,7 +146,7 @@ export type MachineFloorPlanInput = {
     readonly timeoutMs: number;
     readonly authority?: MachineFloorAuthority;
 };
-export interface MachineFloorThresholds {
+interface MachineFloorThresholds {
     readonly memoryBytes: number;
     readonly cpuMillis: number;
     readonly freeDiskBytes: number;
@@ -172,14 +172,14 @@ export declare function issueMachineFloorAuthority(input: {
     checkout: ConsumedSetupCheckoutObservation;
 }> | undefined;
 export declare function isMachineFloorEvidence(value: unknown): value is MachineFloorEvidence;
-export interface DockerRuntimeObservationInput {
+interface DockerRuntimeObservationInput {
     readonly executable: ResolvedExecutable;
     readonly cwd: string;
     readonly env: Readonly<Record<string, string>>;
     readonly timeoutMs: number;
 }
-export type RuntimeIdentity = 'docker-desktop' | 'orbstack' | 'colima' | 'rancher-desktop' | 'docker-engine';
-export interface DockerInfoIdentityInput {
+type RuntimeIdentity = 'docker-desktop' | 'orbstack' | 'colima' | 'rancher-desktop' | 'docker-engine';
+interface DockerInfoIdentityInput {
     readonly operatingSystem: string;
     readonly name: string;
     readonly osType: string;
@@ -196,7 +196,7 @@ export interface DockerInfoIdentityInput {
  * been probed on a host here.
  */
 export declare function runtimeIdentity(input: DockerInfoIdentityInput): RuntimeIdentity | null;
-export type DockerRuntimeObservation = Readonly<{
+type DockerRuntimeObservation = Readonly<{
     kind: 'complete';
     runtime: {
         readonly name: 'docker';
@@ -223,7 +223,7 @@ export declare function issueRuntimeMeasurementProbeAuthority(observation: Docke
 export declare function runtimeMeasurementProbeObservation(authority: RuntimeMeasurementProbeAuthority, executableSha256: string): Extract<DockerRuntimeObservation, {
     readonly kind: 'complete';
 }> | undefined;
-export type RuntimeMeasurementAdmission = Readonly<{
+type RuntimeMeasurementAdmission = Readonly<{
     kind: 'admitted';
     runtimeIdentity: string;
     measurement: string;
@@ -239,7 +239,7 @@ export declare function versionAtLeast(actual: string, floor: string): boolean;
 export declare function admitRuntimeMeasurement(observation: DockerRuntimeObservation, measurements: LocalRuntimeMeasurements): RuntimeMeasurementAdmission;
 export declare function observeRuntimeMeasurement(admission: RuntimeMeasurementAdmission, stackId: StackId): EnvironmentObservation;
 export declare function observeDockerRuntime(rawInput: DockerRuntimeObservationInput, execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>): Promise<DockerRuntimeObservation>;
-export type MachineFloorMeasurement = {
+type MachineFloorMeasurement = {
     readonly kind: 'complete';
     readonly evidence: MachineFloorEvidence;
 } | MachineFloorRefusal | {
@@ -255,7 +255,7 @@ export interface RuntimeObservationWindow {
     readonly startedAt: string;
     readonly expiresAt: string;
 }
-export interface RuntimeTopologyService {
+interface RuntimeTopologyService {
     readonly id: string;
     readonly dependsOn: readonly string[];
     readonly bindMountSources: readonly string[];
@@ -278,7 +278,7 @@ export interface RuntimeTopologyEvidence {
     readonly observationWindow: RuntimeObservationWindow;
     readonly services: readonly RuntimeTopologyService[];
 }
-export type RuntimeTopologyObservation = {
+type RuntimeTopologyObservation = {
     readonly kind: 'complete';
     readonly step: ExecutionStep;
     readonly topology: RuntimeTopologyEvidence;
@@ -287,6 +287,7 @@ export type RuntimeTopologyObservation = {
     readonly kind: 'unavailable';
     readonly reason: string;
     readonly mounts?: RuntimeMountMismatch;
+    readonly undefinedProfiles?: readonly string[];
 };
 export declare const OBSERVATION_WINDOW_HEADROOM_MS = 300000;
 /**
@@ -309,7 +310,7 @@ export type RuntimeMountMismatch = Readonly<{
 export declare function isRuntimeTopologyEvidence(value: unknown): value is RuntimeTopologyEvidence;
 export declare function resolveRuntimeServiceOrder(topology: RuntimeTopologyEvidence): readonly string[];
 export declare function projectRuntimeExecutionEnvironment(topology: RuntimeTopologyEvidence, namespace?: StateNamespace): Readonly<Record<string, string>> | undefined;
-export type RuntimeContainerIdSlot = Readonly<{
+type RuntimeContainerIdSlot = Readonly<{
     kind: 'runtime-container-id';
     service: string;
 }>;
@@ -328,7 +329,7 @@ export interface RuntimeLifecycleExecutionSemantics {
     readonly filesystemChecks: ExecutionStep['filesystemChecks'];
     readonly compensation: readonly RuntimeLifecycleExecutionSemantics[];
 }
-export interface RuntimeLifecycleServiceSemantics {
+interface RuntimeLifecycleServiceSemantics {
     readonly id: string;
     readonly start: RuntimeLifecycleExecutionSemantics;
     readonly status: RuntimeLifecycleExecutionSemantics;
@@ -416,6 +417,8 @@ export declare function startRuntimeService(input: {
     readonly topology: RuntimeTopologyEvidence;
     readonly service: string;
     readonly execute: Execute;
+    /** Build the service's image and replace its container, as `rebuild` does after its code changed. */
+    readonly rebuild?: true;
 }): Promise<RuntimeServiceOutcome>;
 /**
  * Re-reads a service an earlier run started: stale when Compose no longer has the recorded
@@ -427,6 +430,49 @@ export declare function revalidateRuntimeService(input: {
     readonly expectedContainerId: string;
     readonly execute: Execute;
 }): Promise<RuntimeServiceOutcome>;
+/**
+ * Restarts one service's container in place with `compose restart`, then waits for it as `up` does
+ * and inspects it, so the outcome is the same healthy-or-failed evidence a start gives.
+ */
+export declare function restartRuntimeService(input: {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly service: string;
+    readonly execute: Execute;
+}): Promise<RuntimeServiceOutcome>;
+/** One service of the stack as Compose reports it; `state` is `absent` when it has no container. */
+export interface RuntimeServiceState {
+    readonly service: string;
+    readonly state: string;
+    readonly health: string | null;
+    readonly status: string | null;
+    readonly exitCode: number | null;
+}
+/** Lists every service of the stack with its container's state and health through `compose ps`. */
+export declare function observeRuntimeServiceStates(input: {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly execute: Execute;
+}): Promise<Readonly<{
+    kind: 'complete';
+    services: readonly RuntimeServiceState[];
+}> | Readonly<{
+    kind: 'unavailable';
+    reason: string;
+}>>;
+/**
+ * The foreground command that runs `argv` inside one service's container, under the stack's own
+ * project, files and profiles, so the caller never names the derived project.
+ */
+export declare function planRuntimeServiceExec(input: {
+    readonly topology: RuntimeTopologyEvidence;
+    readonly service: string;
+    readonly argv: readonly [string, ...string[]];
+    readonly tty: boolean;
+}): Readonly<{
+    executable: ResolvedExecutable;
+    argv: readonly string[];
+    cwd: string;
+    env: Readonly<Record<string, string>>;
+}> | undefined;
 /** The observation as healthy-service evidence, or undefined when the service is not running healthy. */
 export declare function admitRuntimeServiceHealth(observation: RuntimeServiceObservation): RuntimeServiceEvidence | undefined;
 export declare function isRuntimeServiceEvidence(value: unknown): value is RuntimeServiceEvidence;
@@ -467,14 +513,14 @@ export interface RuntimeServiceFailureLogContext {
     readonly filesystemChecks: ExecutionStep['filesystemChecks'];
 }
 export declare function consumeRuntimeServiceFailureForLogs(evidence: RuntimeServiceFailureEvidence): RuntimeServiceFailureLogContext | undefined;
-export interface RuntimeServiceFailureContext {
+interface RuntimeServiceFailureContext {
     readonly observation: RuntimeServiceObservation;
     readonly executable: ResolvedExecutable;
     readonly cwd: string;
     readonly env: Readonly<Record<string, string>>;
 }
 export declare function consumeRuntimeServiceObservationForFailureLogs(value: RuntimeServiceObservation): RuntimeServiceFailureContext | undefined;
-export type RuntimeStopOutcome = 
+type RuntimeStopOutcome = 
 /** Compose stopped the stack and a fresh `ps` found nothing running. */
 {
     readonly kind: 'stopped';

package/dist/environment/runtime.js

@@ -1278,6 +1278,12 @@ function parseTopology(stdout, stackId, configSha256, activeProfiles) {
             profiles.set(name, selected);
         }
         const active = new Set(activeProfiles);
+        // Compose reports only the services of active profiles, so an active profile no reported
+        // service carries is one no service declares; Compose itself accepts it silently.
+        const declaredProfiles = new Set([...profiles.values()].flat());
+        const undefinedProfiles = activeProfiles.filter((profile) => !declaredProfiles.has(profile));
+        if (undefinedProfiles.length > 0)
+            return { undefinedProfiles };
         const names = declaredNames.filter((name) => {
             const serviceProfiles = profiles.get(name) ?? [];
             return serviceProfiles.length === 0 || serviceProfiles.some((profile) => active.has(profile));
@@ -1371,6 +1377,12 @@ function admitRuntimeTopology(contract, step, outcome) {
     const projected = parseTopology(outcome.stdout, contract.stackId, contract.configSha256, contract.runtime.activeProfiles);
     if (!projected)
         return unavailable();
+    if ('undefinedProfiles' in projected)
+        return {
+            kind: 'unavailable',
+            reason: `no Compose service declares profile ${projected.undefinedProfiles.join(', ')}`,
+            undefinedProfiles: projected.undefinedProfiles,
+        };
     const mounts = compareBindSources(projected.services.flatMap(({ bindMountSources }) => bindMountSources), contract.runtime.expectedMountSources);
     // The caller can name the sibling or host path behind each difference; a bare refusal here
     // left `up` reporting only that readiness authority was unavailable.
@@ -1486,7 +1498,7 @@ function runtimeServiceLookupSteps(topologyContract, service, issuanceId) {
     const identity = derivedComposeStep(topologyContract.step, `runtime:docker-compose:identity:${service.id}`, 'ps', ['ps', '--quiet', '--all', service.id], 128, issuanceId, MAX_OBSERVATION_WINDOW_MS, undefined, topologyContract.runtime.interpolatedNames);
     return status && identity ? { status, identity } : undefined;
 }
-function runtimeServiceInitialSteps(topologyContract, service, issuanceId) {
+function runtimeServiceInitialSteps(topologyContract, service, issuanceId, rebuild = false) {
     // `up --wait` returns only once the service runs and its healthcheck passes, after Compose has
     // built or pulled its image, and the declared cold_start_seconds bounds exactly that. The
     // ordinary command budget does not: a first `up` was killed and reported "did not become
@@ -1495,7 +1507,7 @@ function runtimeServiceInitialSteps(topologyContract, service, issuanceId) {
     // grace; a start without that grace was killed mid-recreate, leaving the replacement container
     // created but never started.
     const start = derivedComposeStep({ ...topologyContract.step, timeoutMs: COMPOSE_STOP_GRACE_MS
-            + Math.max(topologyContract.step.timeoutMs, topologyContract.runtime.coldStartLimitMillis) }, `runtime:docker-compose:start:${service.id}`, 'up', ['--progress', 'quiet', 'up', '--detach', '--wait', '--no-deps', service.id], OUTPUT_LIMIT_BYTES, issuanceId, MAX_OBSERVATION_WINDOW_MS, undefined, topologyContract.runtime.interpolatedNames);
+            + Math.max(topologyContract.step.timeoutMs, topologyContract.runtime.coldStartLimitMillis) }, `runtime:docker-compose:start:${service.id}`, 'up', ['--progress', 'quiet', 'up', '--detach', '--wait', '--no-deps', ...rebuild ? ['--build', '--force-recreate'] : [], service.id], OUTPUT_LIMIT_BYTES, issuanceId, MAX_OBSERVATION_WINDOW_MS, undefined, topologyContract.runtime.interpolatedNames);
     // A service that failed its start under a restart policy restarts forever until `down`. The
     // failed `up` stops it and keeps the container, so its logs stay readable and the next `up`
     // starts it again.
@@ -1817,7 +1829,7 @@ function runtimeServiceFailure(contract, stage, outcome, previousFinishedAt, con
  */
 export async function startRuntimeService(input) {
     const contract = runtimeServiceContract(input.topology, input.service);
-    const steps = contract && runtimeServiceInitialSteps(contract.topologyContract, contract.service, randomBytes(32).toString('hex'));
+    const steps = contract && runtimeServiceInitialSteps(contract.topologyContract, contract.service, randomBytes(32).toString('hex'), input.rebuild === true);
     if (!contract || !steps)
         return { kind: 'failure' };
     const { projectName } = contract.topologyContract.runtime;
@@ -1881,6 +1893,64 @@ export async function revalidateRuntimeService(input) {
         return { kind: 'stale' };
     return inspectRuntimeService({ ...contract, containerId: observed.containerId, identityFinishedAt: identity.receipt.finishedAt }, input.execute);
 }
+/**
+ * Restarts one service's container in place with `compose restart`, then waits for it as `up` does
+ * and inspects it, so the outcome is the same healthy-or-failed evidence a start gives.
+ */
+export async function restartRuntimeService(input) {
+    const contract = runtimeServiceContract(input.topology, input.service);
+    const step = contract && derivedComposeStep({ ...contract.topologyContract.step, timeoutMs: COMPOSE_STOP_GRACE_MS + contract.topologyContract.step.timeoutMs }, `runtime:docker-compose:restart:${contract.service.id}`, 'restart', ['--progress', 'quiet', 'restart', '--no-deps', contract.service.id], OUTPUT_LIMIT_BYTES, randomBytes(32).toString('hex'), MAX_OBSERVATION_WINDOW_MS, undefined, contract.topologyContract.runtime.interpolatedNames);
+    if (!contract || !step)
+        return { kind: 'failure' };
+    const restarted = await input.execute(step);
+    if (restarted.kind !== 'complete' || restarted.stderr.byteLength !== 0) {
+        return runtimeServiceFailure(contract, 'start', restarted, undefined, null);
+    }
+    return startRuntimeService(input);
+}
+/** Lists every service of the stack with its container's state and health through `compose ps`. */
+export async function observeRuntimeServiceStates(input) {
+    const contract = issuedTopologyEvidence.get(input.topology);
+    const step = contract && derivedComposeStep(contract.step, `runtime:docker-compose:ps:${contract.runtime.projectName}`, 'ps', ['ps', '--format', 'json', '--all'], OUTPUT_LIMIT_BYTES, randomBytes(32).toString('hex'), MAX_OBSERVATION_WINDOW_MS, undefined, contract.runtime.interpolatedNames);
+    if (!contract || !step)
+        return { kind: 'unavailable', reason: 'the stack topology is no longer current' };
+    const outcome = await input.execute(step);
+    if (outcome.kind !== 'complete')
+        return { kind: 'unavailable', reason: `docker compose ps failed (${outcome.code})` };
+    const reported = new Map();
+    try {
+        for (const line of new TextDecoder('utf-8', { fatal: true }).decode(outcome.stdout).split('\n')) {
+            if (line.trim() === '')
+                continue;
+            const row = JSON.parse(line);
+            if (row.Project !== contract.runtime.projectName || typeof row.Service !== 'string' || typeof row.State !== 'string') {
+                return { kind: 'unavailable', reason: 'docker compose ps reported a container outside this stack or without a state' };
+            }
+            reported.set(row.Service, {
+                service: row.Service, state: row.State,
+                health: typeof row.Health === 'string' && row.Health !== '' ? row.Health : null,
+                status: typeof row.Status === 'string' ? row.Status : null,
+                exitCode: typeof row.ExitCode === 'number' ? row.ExitCode : null,
+            });
+        }
+    }
+    catch (error) {
+        return { kind: 'unavailable', reason: unavailableReason('docker compose ps output is not JSON lines', error) };
+    }
+    return { kind: 'complete', services: [...contract.services.keys()].sort().map(service => reported.get(service)
+            ?? { service, state: 'absent', health: null, status: null, exitCode: null }) };
+}
+/**
+ * The foreground command that runs `argv` inside one service's container, under the stack's own
+ * project, files and profiles, so the caller never names the derived project.
+ */
+export function planRuntimeServiceExec(input) {
+    const contract = runtimeServiceContract(input.topology, input.service);
+    const step = contract && derivedComposeStep(contract.topologyContract.step, `runtime:docker-compose:exec:${contract.service.id}`, 'exec', ['exec', ...input.tty ? [] : ['--no-tty'], contract.service.id, ...input.argv], OUTPUT_LIMIT_BYTES, randomBytes(32).toString('hex'), MAX_OBSERVATION_WINDOW_MS, undefined, contract.topologyContract.runtime.interpolatedNames);
+    if (!contract || !step)
+        return undefined;
+    return { executable: contract.topologyContract.runtime.runtimeExecutable, argv: step.argv.slice(1), cwd: step.cwd, env: step.env };
+}
 /** The observation as healthy-service evidence, or undefined when the service is not running healthy. */
 export function admitRuntimeServiceHealth(observation) {
     const contract = issuedRuntimeServiceObservations.get(observation);

package/dist/environment/served-checkout-grants.d.ts

@@ -0,0 +1,53 @@
+import type { SurfaceTarget } from '../surfaces/contract.js';
+import { type EnvironmentDiagnostic } from './contract.js';
+export declare function inside(path: string, root: string): boolean;
+/**
+ * The directory the OpenCode grant file names: the served checkout when it lies outside the
+ * declared one, which the grant would not otherwise reach.
+ */
+export declare function openCodeGrantDirectory(declared: string, served: string | undefined): string;
+/** Why a directory cannot go into an OpenCode access pattern, or undefined when it can. */
+export declare function openCodePatternUnsafe(directory: string): string | undefined;
+export interface AgentGrantPlan {
+    readonly settings: Readonly<{
+        bytes: string | null;
+    }> | undefined;
+    readonly local: readonly Readonly<{
+        name: string;
+        bytes: string;
+    }>[];
+    /** What the tools can reach, for a served checkout outside the declared one. */
+    readonly lines: readonly string[];
+    readonly report: Readonly<{
+        granted: readonly SurfaceTarget[];
+        ungranted: readonly SurfaceTarget[];
+    }> | undefined;
+}
+type Planned = Readonly<{
+    kind: 'complete';
+    plan: AgentGrantPlan;
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: EnvironmentDiagnostic;
+}>;
+/**
+ * Plans the machine-local grants for one sibling. `served` is the checkout that serves it, or
+ * undefined when the sibling is no longer declared; `targets` are the listed tools that hold a
+ * committed grant for it. A grant cockpit added earlier for the sibling is taken back when the
+ * served checkout no longer needs it.
+ */
+export declare function planAgentGrants(input: Readonly<{
+    root: string;
+    slug: string;
+    declared: string | undefined;
+    served: string | undefined;
+    targets: readonly SurfaceTarget[];
+}>): Promise<Planned>;
+/** Writes a plan: cockpit's own record first, so a grant it added is never one it forgets. */
+export declare function applyAgentGrants(root: string, plan: AgentGrantPlan): Promise<Readonly<{
+    kind: 'complete';
+} | {
+    kind: 'refusal';
+    diagnostic: EnvironmentDiagnostic;
+}>>;
+export {};