@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/docs/markdown.d.ts

@@ -0,0 +1,36 @@
+interface ProseLine {
+    readonly line: number;
+    readonly prose: string;
+    readonly comments: readonly string[];
+}
+interface MarkdownLink {
+    readonly line: number;
+    readonly label: string;
+    readonly target: string;
+    readonly index: number;
+    readonly end: number;
+}
+export interface WalkedMarkdown {
+    readonly lines: readonly ProseLine[];
+    readonly fences: readonly Readonly<{
+        line: number;
+        info: string;
+    }>[];
+    /** Each line inside a fenced block, with the info string of its fence. */
+    readonly fencedLines: readonly Readonly<{
+        line: number;
+        info: string;
+        text: string;
+    }>[];
+    readonly links: readonly MarkdownLink[];
+}
+/** The visible prose of a page, line by line: fenced code and front matter removed, HTML comments lifted out. */
+export declare function walkMarkdownProse(body: string): WalkedMarkdown;
+/**
+ * The repository path a link target or cited path names, resolved against `base`, the directory it
+ * is relative to ('' for the repository root): its fragment, query, `:line[:column]` suffix and
+ * trailing slashes dropped, and its percent escapes decoded. Undefined for an empty, absolute or
+ * external (`scheme:`) target. The result may still climb out with `../`; the caller decides.
+ */
+export declare function resolveLinkTarget(base: string, target: string): string | undefined;
+export {};

package/dist/docs/markdown.js

@@ -0,0 +1,88 @@
+// The Markdown reading shared by the repository's own docs lint and `cockpit docs check`: one walker,
+// so both agree on what counts as prose, code and a link.
+import { posix } from 'node:path';
+/** The visible prose of a page, line by line: fenced code and front matter removed, HTML comments lifted out. */
+export function walkMarkdownProse(body) {
+    const lines = [];
+    const fences = [];
+    const fencedLines = [];
+    const links = [];
+    const rows = body.split(/\r?\n/);
+    let fence;
+    const start = rows[0] === '---' ? rows.indexOf('---', 1) + 1 : 0;
+    let comment;
+    for (let index = start; index < rows.length; index += 1) {
+        const number = index + 1;
+        let text = rows[index];
+        const marker = /^\s*(`{3,}|~{3,})(.*)$/.exec(text);
+        if (fence !== undefined) {
+            if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && marker[2].trim() === '')
+                fence = undefined;
+            else
+                fencedLines.push({ line: number, info: fences.at(-1).info, text });
+            continue;
+        }
+        if (marker && comment === undefined) {
+            fence = marker[1];
+            fences.push({ line: number, info: marker[2].trim() });
+            continue;
+        }
+        const comments = [];
+        let prose = '';
+        while (text !== '') {
+            if (comment) {
+                const close = text.indexOf('-->');
+                comment.text += ` ${close === -1 ? text : text.slice(0, close)}`;
+                if (close === -1) {
+                    text = '';
+                    break;
+                }
+                text = text.slice(close + 3);
+                const owner = lines.find(row => row.line === comment.line);
+                const done = comment.text.trim().replace(/\s+/g, ' ');
+                if (owner)
+                    owner.comments.push(done);
+                else
+                    comments.push(done);
+                comment = undefined;
+                continue;
+            }
+            const open = text.indexOf('<!--');
+            if (open === -1) {
+                prose += text;
+                break;
+            }
+            prose += text.slice(0, open);
+            comment = { line: number, text: '' };
+            text = text.slice(open + 4);
+        }
+        lines.push({ line: number, prose, comments });
+        const visible = prose.replace(/`+[^`]*`+/g, span => ' '.repeat(span.length));
+        for (const match of visible.matchAll(/\[([^\]]*)\]\(([^)\s]*)[^)]*\)/g)) {
+            links.push({ line: number, label: match[1], target: match[2], index: match.index, end: match.index + match[0].length });
+        }
+    }
+    if (comment)
+        throw new Error(`HTML comment opened on line ${comment.line} is not closed`);
+    return { lines, fences, fencedLines, links };
+}
+/**
+ * The repository path a link target or cited path names, resolved against `base`, the directory it
+ * is relative to ('' for the repository root): its fragment, query, `:line[:column]` suffix and
+ * trailing slashes dropped, and its percent escapes decoded. Undefined for an empty, absolute or
+ * external (`scheme:`) target. The result may still climb out with `../`; the caller decides.
+ */
+export function resolveLinkTarget(base, target) {
+    let value = target.split(/[#?]/, 1)[0].replace(/:\d+(?::\d+)?$/, '').replace(/\/+$/, '');
+    // A `%` that starts no valid escape is part of the file name, as CommonMark reads it.
+    try {
+        value = decodeURI(value);
+    }
+    catch (error) {
+        if (!(error instanceof URIError))
+            throw error;
+    }
+    if (value === '' || value.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(value))
+        return undefined;
+    return posix.normalize(posix.join(base, value));
+}

package/dist/docs/references.d.ts

@@ -0,0 +1,32 @@
+import type { Diagnostic } from '../environment/contract.js';
+import { type WalkedMarkdown } from './markdown.js';
+interface RepositoryHistory {
+    /** Each path a commit deleted or renamed away, newest first, mapped to its new name for a rename. */
+    readonly removed: ReadonlyMap<string, string | undefined>;
+    /** Every make target any version of a Makefile defined. */
+    readonly targets: ReadonlySet<string>;
+}
+export interface LivingDocument {
+    readonly path: string;
+    readonly walked: WalkedMarkdown;
+}
+/** `git log --format= --name-status -z -M --diff-filter=DR` output, newest commit first. */
+export declare function parseRemovedPaths(output: string): Map<string, string | undefined>;
+/** The targets the given Makefile lines define, including .PHONY names; special and pattern targets are skipped. */
+export declare function makeTargets(lines: Iterable<string>): Set<string>;
+/** The targets ever defined, from `git log -p` over the Makefiles: every line was added once. */
+export declare function historicalMakeTargets(patch: string): Set<string>;
+/**
+ * The stale references in the given documents. `files` are the repository's files now; a cited
+ * directory counts as present while any file is under it.
+ */
+export declare function staleReferences(input: Readonly<{
+    repository: string;
+    documents: readonly LivingDocument[];
+    files: ReadonlySet<string>;
+    targets: ReadonlySet<string>;
+    history: RepositoryHistory;
+    /** Whether the path is on disk; an ignored file is absent from `files` but not removed. */
+    present: (path: string) => boolean;
+}>): Diagnostic[];
+export {};

package/dist/docs/references.js

@@ -0,0 +1,148 @@
+// Stale references in living documents: a path or `make` target a document cites that the
+// repository once had and has since removed. Keying on history is the whole precision story: a
+// backlog full of proposals ("add `make park`") names things that never existed, and those are
+// left alone, while `make publish` after its target was deleted is exactly the rot to report. No
+// allowlist is needed, and a link that never resolved is a link checker's business.
+import { posix } from 'node:path';
+import { resolveLinkTarget } from './markdown.js';
+/** `git log --format= --name-status -z -M --diff-filter=DR` output, newest commit first. */
+export function parseRemovedPaths(output) {
+    const removed = new Map();
+    const tokens = output.split('\0').filter(token => token !== '');
+    for (let index = 0; index < tokens.length;) {
+        const status = tokens[index++];
+        if (status === 'D') {
+            const path = tokens[index++];
+            if (!removed.has(path))
+                removed.set(path, undefined);
+        }
+        else if (/^R\d*$/.test(status)) {
+            const from = tokens[index++];
+            const to = tokens[index++];
+            if (!removed.has(from))
+                removed.set(from, to);
+        }
+        else
+            throw new Error(`unexpected git name-status record ${JSON.stringify(status)}`);
+    }
+    return removed;
+}
+const RULE = /^([^\s:#=$][^:#=$]*?)\s*::?(?!=)/;
+/** The targets the given Makefile lines define, including .PHONY names; special and pattern targets are skipped. */
+export function makeTargets(lines) {
+    const targets = new Set();
+    for (const line of lines) {
+        const phony = /^\.PHONY\s*:(.*)$/.exec(line);
+        const names = phony ? phony[1] : RULE.exec(line)?.[1];
+        for (const name of names?.trim().split(/\s+/) ?? []) {
+            if (name !== '' && !name.startsWith('.') && !name.includes('%'))
+                targets.add(name);
+        }
+    }
+    return targets;
+}
+/** The targets ever defined, from `git log -p` over the Makefiles: every line was added once. */
+export function historicalMakeTargets(patch) {
+    return makeTargets(patch.split('\n').filter(line => /^[+-]/.test(line) && !/^(?:\+\+\+|---) /.test(line)).map(line => line.slice(1)));
+}
+const SHELL_FENCES = new Set(['', 'sh', 'bash', 'shell', 'zsh', 'console', 'terminal', 'shell-session']);
+const PATH_SPAN = /^[A-Za-z0-9._@+~-][A-Za-z0-9._@+~/-]*$/;
+// `make a b` cites a and b; `make -C dir x` or `make -f other.mk x` cites another Makefile, so not x.
+function citedTargets(text) {
+    const targets = [];
+    for (const match of text.matchAll(/(?:^|[\s;&|(`$])make((?:[ \t]+[^\s;&|)`]+)*)/g)) {
+        const words = match[1].trim().split(/\s+/).filter(Boolean);
+        if (words.some(word => /^-(?:C|f)|^--(?:directory|file|makefile)\b/.test(word)))
+            continue;
+        for (const word of words) {
+            if (word.startsWith('-') || word.includes('='))
+                continue;
+            if (!/^[A-Za-z0-9_][A-Za-z0-9._/-]*$/.test(word))
+                break;
+            targets.push(word);
+        }
+    }
+    return targets;
+}
+function citedPath(document, raw, relativeToDocument) {
+    const value = raw.trim().replace(/^<|>$/g, '');
+    const relative = relativeToDocument || value.startsWith('./') || value.startsWith('../');
+    const resolved = resolveLinkTarget(relative ? posix.dirname(document) : '', value);
+    return resolved === undefined || resolved === '.' || resolved.startsWith('../') ? undefined : resolved;
+}
+// Every directory above the given files: `a/b/c.md` contributes `a` and `a/b`.
+const ancestors = (files) => new Set([...files].flatMap(file => file.split('/').slice(0, -1).map((_, index, parts) => parts.slice(0, index + 1).join('/'))));
+/**
+ * The stale references in the given documents. `files` are the repository's files now; a cited
+ * directory counts as present while any file is under it.
+ */
+export function staleReferences(input) {
+    const findings = [];
+    const directories = ancestors(input.files);
+    const exists = (path) => input.files.has(path) || directories.has(path);
+    const removedDirectories = ancestors(input.history.removed.keys());
+    // Follow renames to where the content lives now; a chain that ends in a deletion is a removal.
+    const successor = (path) => {
+        const seen = new Set();
+        let current = path;
+        while (input.history.removed.has(current) && !seen.has(current)) {
+            seen.add(current);
+            const next = input.history.removed.get(current);
+            if (next === undefined)
+                return undefined;
+            if (exists(next))
+                return next;
+            current = next;
+        }
+        return undefined;
+    };
+    for (const document of input.documents) {
+        const reported = new Set();
+        const start = findings.length;
+        const where = (line) => `${input.repository}${document.path}:${line}`;
+        const cite = (line, path) => {
+            if (path === undefined || exists(path) || !input.history.removed.has(path) && !removedDirectories.has(path) || input.present(path))
+                return;
+            const key = `${line}\0${path}`;
+            if (reported.has(key))
+                return;
+            reported.add(key);
+            const renamed = successor(path);
+            findings.push({ severity: 'error', code: 'DOCS_REFERENCE_REMOVED', target: where(line),
+                message: renamed === undefined
+                    ? `${where(line)} cites ${path}, which the repository history removed`
+                    : `${where(line)} cites ${path}, which the repository history renamed to ${renamed}`,
+                fix: 'cite the path that replaced it (a rename is named in the message), or rewrite or delete the sentence if what it described is gone; then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+        };
+        const citeTargets = (line, text) => {
+            for (const target of citedTargets(text)) {
+                const key = `${line}\0make ${target}`;
+                if (input.targets.has(target) || !input.history.targets.has(target) || reported.has(key))
+                    continue;
+                reported.add(key);
+                findings.push({ severity: 'error', code: 'DOCS_TARGET_REMOVED', target: where(line),
+                    message: `${where(line)} runs make ${target}, a target the Makefiles once defined and no longer do`,
+                    fix: 'cite the target or command that replaced it, or rewrite or delete the sentence if the step is gone; then rerun npx --no cockpit docs check --config <your cockpit.toml>' });
+            }
+        };
+        for (const row of document.walked.lines) {
+            for (const span of row.prose.matchAll(/(`+)([^`]+)\1/g)) {
+                const value = span[2].trim();
+                if (PATH_SPAN.test(value))
+                    cite(row.line, citedPath(document.path, value, false));
+                else
+                    citeTargets(row.line, value);
+            }
+        }
+        for (const link of document.walked.links)
+            cite(link.line, citedPath(document.path, link.target, true));
+        for (const row of document.walked.fencedLines) {
+            if (SHELL_FENCES.has(row.info.split(/\s+/, 1)[0].toLowerCase()))
+                citeTargets(row.line, row.text.replace(/^\s*[$%>#]\s+/, ''));
+        }
+        // Spans, links and fences are read in separate passes; the report follows the document.
+        const line = (finding) => Number(finding.target.slice(finding.target.lastIndexOf(':') + 1));
+        findings.splice(start, findings.length - start, ...findings.slice(start).sort((left, right) => line(left) - line(right)));
+    }
+    return findings;
+}

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

@@ -0,0 +1,35 @@
+import { type UnconfirmedAnswerName } from '../../guards/answer-confirmation.js';
+import { type Diagnostic } from '../contract.js';
+import type { EvaluatedObservation } from '../observations.js';
+export interface ConfirmCommandInput {
+    readonly configPath: string;
+    readonly answer: UnconfirmedAnswerName;
+}
+type Observed = Readonly<{
+    status: number;
+    diagnostics: readonly Diagnostic[];
+}>;
+export interface ConfirmCommandAdapters {
+    /** The preflight command, run against the configuration on disk. */
+    readonly preflight: (input: Readonly<{
+        configPath: string;
+    }>) => Promise<Observed & Readonly<{
+        result: Readonly<{
+            checks: readonly EvaluatedObservation[];
+        }>;
+    }>>;
+    /** The check command, run against the configuration on disk. */
+    readonly check: (input: Readonly<{
+        configPath: string;
+    }>) => Promise<Observed>;
+    readonly now: () => Date;
+}
+export interface ConfirmCommandOutcome {
+    readonly status: 0 | 2;
+    readonly artifact: string | null;
+    readonly destination: null;
+    readonly result: unknown;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function runConfirm(input: ConfirmCommandInput, adapters: ConfirmCommandAdapters): Promise<ConfirmCommandOutcome>;
+export {};

package/dist/environment/application/confirm.js

@@ -0,0 +1,122 @@
+// Sequences `cockpit confirm <answer>`: refuse an answer only a person may confirm, run the existing
+// observation that verifies the rest against this machine and the running product, record what ran,
+// then drop the answer from `unconfirmed` in cockpit.toml. The record goes first, so a failed edit
+// leaves a record nothing uses, never a removed entry the guard cannot account for.
+import { dirname, join } from 'node:path';
+import { canonicalJson } from '../../canonical-json.js';
+import { loadCockpitConfig, readBoundedInput } from '../../config/load.js';
+import { removeUnconfirmedAnswer } from '../../config/unconfirmed-toml.js';
+import { writeVerifiedConfig } from '../../config/verified-write.js';
+import { cockpitCommand } from '../../fix-catalogue.js';
+import { ANSWER_CONFIRMATION_PATH, ANSWER_CONFIRMATIONS, confirmationConfigurationSha256, encodeAnswerConfirmations, parseAnswerConfirmations, personConfirmationFix, } from '../../guards/answer-confirmation.js';
+import { writeCockpitLocalFiles } from '../../guards/local-identity.js';
+import { refusalOutcome } from '../../refusal.js';
+import { sha256Hex } from '../../sha256.js';
+import { ENVIRONMENT_CODES, hasErrorCode } from '../contract.js';
+import { declaredRuntime } from '../declaration.js';
+// The rows of preflight that say the runtime measured on this machine meets the declared floor.
+const RUNTIME_FLOOR_CODES = [ENVIRONMENT_CODES.MACHINE_MEMORY_BELOW_FLOOR, ENVIRONMENT_CODES.MACHINE_CPU_BELOW_FLOOR,
+    ENVIRONMENT_CODES.MACHINE_DISK_BELOW_FLOOR, ENVIRONMENT_CODES.RUNTIME_UNMEASURED];
+// Preflight passes only with the stack up; this row says the port family it holds is leased on the
+// declared bases with current listener evidence.
+const PORT_FAMILY_CODES = [ENVIRONMENT_CODES.PORT_FAMILY_COLLISION];
+const failing = (diagnostics) => diagnostics.filter(row => row.severity === 'error');
+async function observe(observation, configPath, config, adapters) {
+    // A machine floor alone is still measured; the stack and its Compose files need a declared runtime.
+    if (observation !== 'runtime-floor' && declaredRuntime(config.environment) !== 'compose') {
+        return { passed: false, reason: 'cockpit.toml declares no Compose files, so there is no stack or topology to observe', diagnostics: [] };
+    }
+    if (observation === 'check') {
+        const checked = await adapters.check({ configPath });
+        return checked.status === 0 ? { passed: true, evidence: { status: checked.status, diagnostics: checked.diagnostics } }
+            : { passed: false, reason: 'check did not pass', diagnostics: failing(checked.diagnostics) };
+    }
+    const preflight = await adapters.preflight({ configPath });
+    const codes = observation === 'preflight' ? PORT_FAMILY_CODES : RUNTIME_FLOOR_CODES;
+    const rows = preflight.result.checks.filter(check => codes.includes(check.code));
+    const unmet = codes.filter(code => !rows.some(row => row.code === code && row.verdict === 'pass'));
+    const evidence = { checks: rows.map(({ code, verdict, source, measured, observedAt }) => ({ code, verdict, source, measured, observedAt })) };
+    if (observation === 'preflight' && preflight.status !== 0) {
+        return { passed: false, reason: 'preflight did not pass, so the stack is not up and healthy on the declared ports', diagnostics: failing(preflight.diagnostics) };
+    }
+    return unmet.length === 0 ? { passed: true, evidence }
+        : { passed: false, reason: `preflight did not observe ${unmet.join(', ')} passing`, diagnostics: failing(preflight.diagnostics) };
+}
+async function readConfirmations(root) {
+    try {
+        const read = await readBoundedInput(join(root, ANSWER_CONFIRMATION_PATH));
+        return read.kind === 'complete' ? read.bytes : undefined;
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+}
+export async function runConfirm(input, adapters) {
+    const { answer } = input;
+    const confirmation = ANSWER_CONFIRMATIONS[answer];
+    if (confirmation.by === 'person') {
+        return refusalOutcome('CONFIRM_PERSON_REQUIRED', `${answer} is confirmed only by a person: ${confirmation.trustDecision ? `it is a trust decision, because ${confirmation.why}` : confirmation.why}`, answer, personConfirmationFix([answer], input.configPath));
+    }
+    const loaded = await loadCockpitConfig(input.configPath);
+    if (loaded.kind !== 'complete')
+        return { status: 2, artifact: null, destination: null, result: null, diagnostics: loaded.diagnostics };
+    const configPath = loaded.result.source.path;
+    const config = loaded.result.config;
+    if (!config.unconfirmed?.includes(answer)) {
+        return refusalOutcome('CONFIRM_ANSWER_NOT_LISTED', `${answer} is not listed under unconfirmed in ${configPath}, so there is nothing to confirm`, 'unconfirmed', `run ${cockpitCommand('doctor', { config: configPath })}; DECLARATION_UNCONFIRMED names the answers still to confirm`);
+    }
+    const ranAt = adapters.now().toISOString();
+    const verdict = await observe(confirmation.observation, configPath, config, adapters);
+    if (!verdict.passed) {
+        const refused = refusalOutcome('CONFIRM_OBSERVATION_FAILED', `${answer} stays unconfirmed: ${verdict.reason}; confirming it needs ${confirmation.verifies}`, answer, `clear the diagnostics reported beside this one, then run ${cockpitCommand('confirm', { config: configPath, operand: answer })} again; if the value itself is wrong, correct it in cockpit.toml first`);
+        return { ...refused, diagnostics: [...refused.diagnostics, ...verdict.diagnostics] };
+    }
+    // The observation re-reads cockpit.toml itself, so the record binds to what it observed only if the
+    // file is still the one loaded above. An agent edit made meanwhile cannot be reverted before this
+    // read: the guard holds every call but sync and check once the file differs from the synced one.
+    const after = await loadCockpitConfig(configPath);
+    if (after.kind !== 'complete' || after.result.source.sha256 !== loaded.result.source.sha256) {
+        return refusalOutcome(ENVIRONMENT_CODES.CONFIG_CHANGED_DURING_EXECUTION, 'cockpit.toml changed while the observation ran, so it cannot show which configuration passed; nothing was recorded or removed', configPath, `run ${cockpitCommand('confirm', { config: configPath, operand: answer })} again`);
+    }
+    const root = dirname(configPath);
+    const record = { observation: confirmation.observation, ranAt, result: 'passed',
+        evidenceSha256: sha256Hex(canonicalJson(verdict.evidence)), configurationSha256: confirmationConfigurationSha256(config) };
+    const written = await writeCockpitLocalFiles(root, [{ name: 'answer-confirmations',
+            bytes: encodeAnswerConfirmations({ ...parseAnswerConfirmations(await readConfirmations(root)), [answer]: record }) }]);
+    if (written.kind !== 'complete') {
+        return refusalOutcome('CONFIRM_RECORD_UNWRITABLE', `the observation passed, but its record could not be written: ${written.message}; cockpit.toml was not changed`, ANSWER_CONFIRMATION_PATH, `make ${ANSWER_CONFIRMATION_PATH} writable for this user, then run ${cockpitCommand('confirm', { config: configPath, operand: answer })} again`);
+    }
+    const remaining = config.unconfirmed.filter(row => row !== answer);
+    const expected = canonicalJson({ ...config, unconfirmed: remaining.length ? remaining : undefined });
+    const exact = (candidate) => canonicalJson(candidate) === expected;
+    const rerun = `run ${cockpitCommand('confirm', { config: configPath, operand: answer })} again`;
+    const byHand = personConfirmationFix([answer], configPath);
+    const edited = await writeVerifiedConfig({
+        path: configPath, expectedSha256: loaded.result.source.sha256, temporaryTag: 'confirm',
+        edit: text => {
+            const edit = removeUnconfirmedAnswer(text, answer);
+            return edit.kind === 'edited' ? edit.text : text;
+        },
+        isExactChange: exact,
+        messages: {
+            changedBefore: { message: 'cockpit.toml changed while the observation ran; nothing was removed', fix: rerun },
+            changedDuring: { message: 'cockpit.toml changed while the edit was being prepared; nothing was removed', fix: rerun },
+            invalid: reason => ({ message: `removing ${answer} would leave cockpit.toml invalid (${reason}); nothing was removed`, fix: byHand }),
+            notExact: { message: `cockpit.toml does not list ${answer} on one unconfirmed = [...] line this command can edit; nothing was removed`, fix: byHand },
+            writtenMismatch: { message: `${answer} was removed, but re-reading cockpit.toml shows a change beyond it`,
+                fix: `review cockpit.toml for the change you did not make before running ${cockpitCommand('sync', { config: configPath, args: '--dry-run' })}` },
+        },
+    });
+    if (edited.kind !== 'complete')
+        return refusalOutcome(edited.code, edited.message, configPath, edited.fix);
+    const sync = cockpitCommand('sync', { config: configPath });
+    return {
+        status: 0, destination: null, diagnostics: [],
+        artifact: `Confirmed ${answer}: ${confirmation.verifies}. Removed it from unconfirmed in ${configPath} and recorded the observation in ${ANSWER_CONFIRMATION_PATH}.\n`
+            + `Run ${sync} to apply the edit; an agent may where [autonomy] sync = "agent", because the recorded observation makes the removal non-widening.\n`,
+        result: { answer, observation: confirmation.observation, ranAt, outcome: 'passed', evidenceSha256: record.evidenceSha256,
+            record: ANSWER_CONFIRMATION_PATH, unconfirmed: remaining, next: sync },
+    };
+}

package/dist/environment/application/destructive.js

@@ -1,6 +1,6 @@
 import { randomBytes } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { cleanupFencedExecution, repairFencedExecution } from '../../environment-exec/execute.js';
 import { ENVIRONMENT_CODES, forwardedRefusal } from '../contract.js';
 import { readState } from '../state.js';
@@ -13,6 +13,7 @@ import { selectDestructiveInstance } from '../instance.js';
 import { issuedDestructiveRuns, lifecycleContextRefusal, provisionalClaims, withLifecycleRunNotices, } from './lifecycle-context.js';
 import { exactCommandConfigPath, invalidateCompletedLifecycle, lifecycleSuggestion, publishDrainOutcome, publishDrainOutcomeRecord, } from './lifecycle-state.js';
 import { lifecycleRefusal, uniqueDiagnostics } from './shared.js';
+import { forgetStackInputs } from '../stack-inputs.js';
 function destructiveRepairRequired(context) {
     return lifecycleRefusal(ENVIRONMENT_CODES.DRAIN_ATTEMPT_REPAIR_REQUIRED, 'cockpit cannot prove the interrupted destructive executor stopped, so it will not overlap it with another destructive action; preserve the coordination state for explicit repair', context.stackId);
 }
@@ -264,7 +265,10 @@ export async function runDown(input, adapters) {
     const loaded = await loadDestructiveContext(input, adapters);
     if (loaded.kind !== 'complete')
         return loaded;
-    return withLifecycleRunNotices(loaded.result, await settleProvisionalClaim(loaded.result, await downWithContext(loaded.result, adapters)));
+    const outcome = await settleProvisionalClaim(loaded.result, await downWithContext(loaded.result, adapters));
+    // A removed stack runs nothing a later doctor could call stale.
+    const forgotten = outcome.kind === 'complete' && outcome.result.change === 'removed' ? await forgetStackInputs(dirname(loaded.result.source.path)) : [];
+    return withLifecycleRunNotices(loaded.result, forgotten.length === 0 ? outcome : { ...outcome, diagnostics: uniqueDiagnostics([...outcome.diagnostics, ...forgotten]) });
 }
 async function downWithContext(context, adapters) {
     const inspection = await inspectDestructiveRecoveryWithRepair(context, 'down');

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

@@ -2,6 +2,7 @@ import { type EnvironmentDiagnostic } from '../contract.js';
 import type { EvaluatorTool } from '../../schema.js';
 import type { SkippedStateNamespace } from '../state.js';
 import { type GeneratedEnvironmentCurrentness } from '../generated-application/shared.js';
+import type { McpServer } from '../../surfaces/mcp.js';
 import { type ReadinessReport } from '../../readiness.js';
 import type { ReleaseFreshness } from '../../freshness.js';
 import { proposeGeneratedEnvironmentRepair } from '../../repair.js';
@@ -11,17 +12,17 @@ import { type ComparisonRemoteEvaluation, type ObservationCommandAdapters } from
 export interface DoctorCommandInput {
     readonly configPath: string;
 }
-export interface DoctorSurfaceOverrideInspectionComplete {
+interface DoctorSurfaceOverrideInspectionComplete {
     readonly kind: 'complete';
     readonly activeOverrides: readonly ActiveSurfaceOverride[];
     readonly changedOverrideOriginals: readonly SurfaceUpgradeFinding[];
 }
-export interface DoctorSurfaceOverrideInspectionUnavailable {
+interface DoctorSurfaceOverrideInspectionUnavailable {
     readonly kind: 'unavailable';
     readonly code: string;
     readonly reason: string;
 }
-export interface DoctorSurfaceOverrideInspectionRefusal {
+interface DoctorSurfaceOverrideInspectionRefusal {
     readonly kind: 'refusal';
     readonly code: string;
     readonly reason: string;
@@ -34,9 +35,13 @@ export interface DoctorCommandAdapters extends ObservationCommandAdapters {
     readonly inspectHookTrust?: () => Promise<readonly EnvironmentDiagnostic[]>;
     /** A warning when work orders exist but their independent evaluator cannot run on this machine. */
     readonly inspectEvaluator?: (evaluators: readonly EvaluatorTool[]) => Promise<readonly EnvironmentDiagnostic[]>;
+    /** Warnings about what each approved MCP server needs before a tool can start it; never starts one. */
+    readonly inspectMcpStartup?: (servers: readonly McpServer[]) => Promise<readonly EnvironmentDiagnostic[]>;
     /** Warnings about prerequisites the stack checks do not cover: the local install, sibling remotes, committed secrets. */
     readonly inspectReadiness?: () => Promise<readonly EnvironmentDiagnostic[]>;
     /** Other cockpits' state namespaces this version skipped, or why the inventory could not be read; read after load has selected this cockpit's state root. */
+    /** Warnings about stacks on this machine that no checkout can reach, read after load has selected this cockpit's state root. */
+    readonly inspectStacks?: () => Promise<readonly EnvironmentDiagnostic[]>;
     readonly readUnreadableState?: () => Promise<Readonly<{
         kind: 'complete';
         skipped: readonly SkippedStateNamespace[];
@@ -57,13 +62,13 @@ interface DoctorFreshness {
     readonly release: ReleaseFreshness;
     readonly repair?: ReturnType<typeof proposeGeneratedEnvironmentRepair>;
 }
-export interface DoctorDeclaration {
-    readonly subject: 'runtime' | 'reset-volumes' | 'seed';
+interface DoctorDeclaration {
+    readonly subject: 'runtime' | 'reset-volumes' | 'seed' | 'docs';
     readonly state: 'declared' | 'not-declared';
     readonly source: string;
     readonly reason: string;
 }
-export interface ApplicationDoctorEvaluation {
+interface ApplicationDoctorEvaluation {
     readonly verdict: PreflightEvaluation['verdict'];
     readonly checks: readonly DoctorCheck[];
     readonly comparisons: readonly ComparisonRemoteEvaluation[];
@@ -74,7 +79,7 @@ export interface ApplicationDoctorEvaluation {
     /** The reported diagnostics grouped under the prerequisites cockpit depends on; absent when cockpit.toml does not load. */
     readonly readiness?: ReadinessReport;
 }
-export type DoctorCommandResult = Readonly<{
+type DoctorCommandResult = Readonly<{
     kind: 'complete';
     status: 0;
     diagnostics: readonly EnvironmentDiagnostic[];

package/dist/environment/application/doctor.js

@@ -11,6 +11,8 @@ import { loadCockpitConfig, evaluatorTools } from '../../config/load.js';
 import { projectDoctor } from '../observations.js';
 import { applicationDiagnostic, evaluateApplicationHealth, healthDiagnostics, issueHealthObservationSource, prepareHealthObservation, } from './health.js';
 import { ownDataValues } from './shared.js';
+import { cockpitCommand } from '../../fix-catalogue.js';
+import { unconfirmedFix } from '../../guards/answer-confirmation.js';
 import { unreadableStateWarning } from './lifecycle-state.js';
 // What reset and up do to product data rests on these declarations; doctor names an absent one
 // instead of letting it read as a passed check.
@@ -27,6 +29,9 @@ async function doctorDeclarations(loading) {
             : 'environment.compose_files is not declared; runtime commands refuse'),
         row('reset-volumes', environment.resettable_volumes.length > 0, 'environment.resettable_volumes', 'reset may delete and recreate these volumes'),
         row('seed', environment.seed !== undefined, 'environment.seed', 'up runs the seed when a resettable volume is new'),
+        // Docs rot is not environment health, so doctor names the check rather than running it.
+        ...loaded.result.config.docs === undefined ? [] : [{ subject: 'docs', state: 'declared', source: 'docs',
+                reason: `docs check reads the declared living documents and decision records; doctor does not run it: ${cockpitCommand('docs check', { config: loaded.result.source.path })}` }],
     ];
 }
 // The guard denies agent commands that reach these hosts. Two empty lists deny nothing, and that
@@ -72,7 +77,8 @@ async function doctorTestingGateDiagnostics(loading) {
         }];
 }
 // init records answers no person stated under `unconfirmed`. They look exactly like stated values
-// in the file, so doctor keeps naming them until a person confirms each and deletes its entry.
+// in the file, so doctor keeps naming them until each is confirmed: by the observation that verifies
+// it, or by a person where it is a trust decision or no observation settles it.
 async function doctorUnconfirmedDiagnostics(loading) {
     const loaded = await loading;
     if (loaded.kind !== 'complete' || !loaded.result.config.unconfirmed)
@@ -83,7 +89,7 @@ async function doctorUnconfirmedDiagnostics(loading) {
             code: 'DECLARATION_UNCONFIRMED',
             message: `${loaded.result.config.unconfirmed.join(', ')} in cockpit.toml were chosen by the setup agent or by no one named, not stated by a person, so they may not describe this product`,
             target: 'unconfirmed',
-            fix: 'confirm each value with whoever owns the product and correct it in cockpit.toml if it is wrong, delete each confirmed entry from unconfirmed, then run npx --no cockpit sync --config <your cockpit.toml>',
+            fix: unconfirmedFix(loaded.result.config.unconfirmed),
         }];
 }
 // The same weakening `check` fails on: a policy cockpit.toml sets below the one the last sync recorded
@@ -165,16 +171,22 @@ export async function runDoctor(input, adapters) {
         return loaded.kind === 'complete' && loaded.result.config.surfaces.tools.includes('codexcli')
             ? adapters.inspectHookTrust?.() ?? [] : [];
     };
-    const [outcome, guardHosts, unconfirmed, policyWeakened, testingGate, hookTrust, evaluator, readinessWarnings] = await Promise.all([doctorHealth(input, adapters, config),
+    const currentness = prepareGeneratedEnvironmentCurrentness(input);
+    const mcpStartup = async () => adapters.inspectMcpStartup?.((await currentness).mcpServers) ?? [];
+    // The machine-wide state reads are independent of the configuration checks, so they run beside them.
+    const statePending = adapters.readUnreadableState?.();
+    const stacksPending = adapters.inspectStacks?.();
+    const [outcome, guardHosts, unconfirmed, policyWeakened, testingGate, hookTrust, evaluator, readinessWarnings, servedSiblings, mcp] = await Promise.all([doctorHealth(input, adapters, config, currentness),
         doctorGuardHostDiagnostics(config), doctorUnconfirmedDiagnostics(config), doctorPolicyDiagnostics(config), doctorTestingGateDiagnostics(config), hookTrustFindings(),
-        doctorEvaluatorDiagnostics(config, adapters), adapters.inspectReadiness?.() ?? []]);
-    const stateInventory = await adapters.readUnreadableState?.();
+        doctorEvaluatorDiagnostics(config, adapters), adapters.inspectReadiness?.() ?? [], config.then(async (loaded) => adapters.inspectServedSiblings?.(loaded.kind === 'complete' ? loaded : undefined) ?? []), mcpStartup()]);
+    const stateInventory = await statePending;
     const unreadableState = stateInventory?.kind === 'refusal'
         // An inventory that cannot be read, such as one another command holds locked, is no clean one.
         ? stateInventory.diagnostics.map((diagnostic) => ({ ...diagnostic, severity: 'warning',
             message: `doctor could not read this machine's cockpit state, so it did not check for other cockpits' state this version cannot read: ${diagnostic.message}` }))
         : [unreadableStateWarning(stateInventory?.skipped ?? [])].filter((warning) => warning !== undefined);
-    const warnings = [...unconfirmed, ...policyWeakened, ...guardHosts, ...testingGate, ...hookTrust, ...evaluator, ...readinessWarnings, ...unreadableState];
+    const orphanedStacks = await stacksPending ?? [];
+    const warnings = [...unconfirmed, ...policyWeakened, ...guardHosts, ...testingGate, ...hookTrust, ...evaluator, ...readinessWarnings, ...servedSiblings, ...mcp, ...unreadableState, ...orphanedStacks];
     const reported = warnings.length === 0 ? outcome
         : { ...outcome, diagnostics: [...outcome.diagnostics, ...warnings] };
     // Doctor reports on a configuration; without one there is nothing to report on, and a zero
@@ -191,11 +203,11 @@ export async function runDoctor(input, adapters) {
         diagnostics: [...loaded.diagnostics.filter(({ code, target }) => !forwarded.has(`${code}\0${target}`)), ...reported.diagnostics],
     };
 }
-async function doctorHealth(input, adapters, config) {
+async function doctorHealth(input, adapters, config, currentness) {
     const surfaceOverrides = inspectDoctorSurfaceOverrides(input.configPath, adapters);
     const declarations = doctorDeclarations(config);
     const freshness = Promise.all([
-        prepareGeneratedEnvironmentCurrentness(input),
+        currentness,
         adapters.discoverReleaseFreshness?.() ?? Promise.resolve({ kind: 'unknown', reason: 'release discovery is not bound' }),
     ]).then(([currentness, release]) => ({
         local: { kind: currentness.outcome.kind, status: currentness.outcome.status, diagnostics: currentness.outcome.diagnostics },