@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/guards/local-identity.js

@@ -0,0 +1,129 @@
+// Owns the machine-local guard identity file: its path, its bytes and how `sync` writes it.
+// Tracked guard bytes must be identical on every clone, so everything that names this machine
+// (Node, the installed cockpit module, root and configuration device and inode numbers) lives here,
+// in a directory that ignores itself. It decides nothing: the guard application authenticates the
+// file against the running process and the published surfaces before any policy is resolved.
+import { exactKeys } from '../exact-keys.js';
+import { randomBytes } from 'node:crypto';
+import { lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { readBoundedInput } from '../config/load.js';
+import { errorCause, hasErrorCode } from '../environment/contract.js';
+export const GUARD_LOCAL_PATHS = Object.freeze({
+    directory: '.cockpit/local',
+    identity: '.cockpit/local/guard-identity',
+    // The exact configuration the guards were generated from, so a later edit can be compared with it.
+    generatedConfig: '.cockpit/local/guard-config',
+    ignore: '.cockpit/local/.gitignore',
+});
+// The guard script reads this file with `read` one line at a time, so the layout is lines rather
+// than JSON: a format line, the two executables it launches, then the identity the application checks.
+const FORMAT = 'cockpit-guard-local/v1';
+const LOCAL_FILE_MAX_BYTES = 65_536;
+const KEYS = ['root', 'rootDevice', 'rootInode', 'configPath', 'configSha256', 'configDevice', 'configInode',
+    'node', 'nodeSha256', 'nodeFingerprint', 'module', 'moduleSha256'];
+const IGNORE_BYTES = '# cockpit-owned: machine-local files, written by `cockpit sync`, never committed\n*\n';
+export function encodeGuardLocalIdentity(identity) {
+    const ordered = Object.fromEntries(KEYS.map(key => [key, identity[key]]));
+    return `${FORMAT}\n${identity.node}\n${identity.module}\n${JSON.stringify(ordered)}\n`;
+}
+/** The exact identity the bytes carry, or undefined when they are not a complete current-format file. */
+export function parseGuardLocalIdentity(bytes) {
+    const lines = bytes.split('\n');
+    if (lines.length !== 5 || lines[0] !== FORMAT || lines[4] !== '')
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(lines[3]);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return undefined; // not the current format
+        throw error;
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (!exactKeys(record, KEYS) || !KEYS.every(key => typeof record[key] === 'string'))
+        return undefined;
+    const identity = record;
+    return identity.node === lines[1] && identity.module === lines[2] && encodeGuardLocalIdentity(identity) === bytes ? identity : undefined;
+}
+async function observeLocalFile(path) {
+    try {
+        const before = await lstat(path);
+        if (!before.isFile() || before.isSymbolicLink() || before.size > LOCAL_FILE_MAX_BYTES)
+            return { kind: 'invalid' };
+        const read = await readBoundedInput(path);
+        if (read.kind !== 'complete' || read.bytes.length > LOCAL_FILE_MAX_BYTES)
+            return { kind: 'invalid' };
+        const after = await lstat(path);
+        if (!after.isFile() || after.isSymbolicLink() || after.dev !== before.dev || after.ino !== before.ino
+            || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)
+            return { kind: 'invalid' };
+        return { kind: 'complete', status: after, bytes: read.bytes };
+    }
+    catch (error) {
+        return hasErrorCode(error, 'ENOENT') ? { kind: 'absent' } : { kind: 'invalid' };
+    }
+}
+async function directoryAt(path, create) {
+    try {
+        const status = await lstat(path);
+        return status.isDirectory() && !status.isSymbolicLink() ? undefined : `${path} is not a plain directory`;
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'ENOENT') || !create)
+            return `${path} is unavailable (${error.code ?? 'unknown error'})`;
+    }
+    await mkdir(path, { mode: 0o700 });
+    return directoryAt(path, false);
+}
+// Rename replaces a planted symlink at the destination instead of writing through it.
+async function replaceFile(directory, name, bytes) {
+    const temporary = join(directory, `.${name}.${randomBytes(8).toString('hex')}.tmp`);
+    try {
+        await writeFile(temporary, bytes, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, join(directory, name));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/**
+ * Publish the identity after the tracked surfaces it authenticates, with the configuration text it
+ * names written first; the reason names what failed.
+ */
+export async function writeGuardLocalIdentity(root, identity, configText) {
+    return writeCockpitLocalFiles(root, [{ name: basename(GUARD_LOCAL_PATHS.generatedConfig), bytes: configText },
+        { name: basename(GUARD_LOCAL_PATHS.identity), bytes: encodeGuardLocalIdentity(identity) }]);
+}
+/** Replace machine-local files under `.cockpit/local`, a directory that ignores itself; the reason names what failed. */
+export async function writeCockpitLocalFiles(root, files) {
+    let current = GUARD_LOCAL_PATHS.directory;
+    try {
+        const parent = await directoryAt(join(root, '.cockpit'), false);
+        if (parent)
+            return { kind: 'refusal', message: parent };
+        const directory = join(root, GUARD_LOCAL_PATHS.directory);
+        const local = await directoryAt(directory, true);
+        if (local)
+            return { kind: 'refusal', message: local };
+        current = GUARD_LOCAL_PATHS.ignore;
+        const ignore = join(root, GUARD_LOCAL_PATHS.ignore);
+        const currentIgnore = await observeLocalFile(ignore);
+        if (currentIgnore.kind !== 'complete' || currentIgnore.bytes.toString('utf8') !== IGNORE_BYTES) {
+            await replaceFile(directory, '.gitignore', IGNORE_BYTES);
+        }
+        for (const file of files) {
+            current = `${GUARD_LOCAL_PATHS.directory}/${file.name}`;
+            if (!/^[a-z0-9][a-z0-9-]*$/.test(file.name))
+                return { kind: 'refusal', message: `${current} is not a plain local file name` };
+            await replaceFile(directory, file.name, file.bytes);
+        }
+        return { kind: 'complete' };
+    }
+    catch (error) {
+        return { kind: 'refusal', message: `${current} could not be written (${errorCause(error)})` };
+    }
+}

package/dist/guards/policy-change.d.ts

@@ -0,0 +1,43 @@
+import type { EnvironmentDiagnostic } from '../environment/contract.js';
+import type { CockpitConfig } from '../schema.js';
+type PolicyChange = Readonly<{
+    kind: 'non-widening';
+}> | Readonly<{
+    kind: 'widening';
+    fields: readonly string[];
+}>;
+/**
+ * Every schema path a rule names, so a test can hold each to a field the schema still has: a rule
+ * whose path was renamed away never matches, and its field silently falls back to the default.
+ * Paths under `sibling[].` name a field of a sibling row.
+ */
+export declare const POLICY_CHANGE_RULE_PATHS: readonly string[];
+/**
+ * Whether `after` lets agents do anything `before` did not, over the loaded configurations. Only a
+ * difference a rule above proves safe is non-widening; every other difference widens. `confirmed`
+ * names the answers whose recorded observation matches `after`; only those may leave `unconfirmed`.
+ */
+export declare function policyChange(before: CockpitConfig, after: CockpitConfig, confirmed?: ReadonlySet<string>): PolicyChange;
+type GuardConfigChange = Readonly<{
+    kind: 'unchanged' | 'unrecorded';
+}> | PolicyChange;
+/**
+ * How the current configuration differs from the one the guards were generated from. `recorded` is
+ * the copy sync kept of that configuration; one missing, or not the configuration `generatedSha256`
+ * names, cannot show the edit is safe. `confirmations` is the machine-local record `cockpit confirm`
+ * keeps of the observations that confirmed answers.
+ */
+export declare function guardConfigChange(generatedSha256: string, recorded: Uint8Array | undefined, current: Readonly<{
+    sha256: string;
+    config: CockpitConfig;
+}>, confirmations?: Uint8Array): GuardConfigChange;
+/** Why a changed configuration needs a person before the guard applies it, for a hold or a check. */
+export declare function guardConfigHeldReason(change: Exclude<GuardConfigChange, Readonly<{
+    kind: 'unchanged' | 'non-widening';
+}>>): string;
+/** What `check` reports about an edit the guards were not regenerated for, or nothing. */
+export declare function inspectGuardConfigChange(root: string, configPath: string, current: Readonly<{
+    sha256: string;
+    config: CockpitConfig;
+}>): Promise<readonly EnvironmentDiagnostic[]>;
+export {};

package/dist/guards/policy-change.js

@@ -0,0 +1,159 @@
+// Owns whether an edit of cockpit.toml widens what agents may do. The guard holds every agent call
+// once the configuration differs from the one it was generated from; this classification decides
+// whether that hold needs a person (the edit widens) or only a sync an agent may run (it does not).
+// It fails closed: a field with no rule here widens whenever it changes, so a field added to the
+// schema later is a person's decision until someone writes down why it is not. A rule exists only
+// for a field that cannot widen the guard's trust inputs (the commands agents run unprompted, the
+// roots they write, the secrets they are kept from, who passes a gate) in the direction it admits.
+// [guards], [work], [autonomy], [mcp], [testing], [browser] and every command field have none, so
+// any change to them is a person's.
+// The rules read the configuration rather than compare the guard policy each side would build: most
+// of what they judge (Compose files and profiles, resettable volumes, the tools guarded, a sibling's
+// operator gate) never reaches that policy, and building it observes the checkouts on disk.
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { UNSYNCED_ADMITTED_PROSE } from '../command-table.js';
+import { parseCockpitConfigBytes, readBoundedInput } from '../config/load.js';
+import { hasErrorCode } from '../environment/contract.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+import { sha256Hex } from '../sha256.js';
+import { ANSWER_CONFIRMATION_PATH, confirmedAnswers } from './answer-confirmation.js';
+import { GUARD_LOCAL_PATHS, parseGuardLocalIdentity } from './local-identity.js';
+const safe = () => [];
+const gains = (from, to) => to.some(row => !from.some(was => isDeepStrictEqual(was, row)));
+/** A list that may lose rows but not gain one. */
+const onlyRemoves = (before = [], after = [], at) => gains(before, after) ? [at] : [];
+/** A list that may gain rows but not lose one. */
+const onlyAdds = (before = [], after = [], at) => gains(after, before) ? [at] : [];
+function plainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** The paths under `at` that differ in a way no rule admits; a rule is looked up by its path from the walk's root. */
+function walk(before, after, rules, at, key = '') {
+    const rule = rules[key];
+    if (rule)
+        return [...rule(before, after, at)];
+    if (plainObject(before) && plainObject(after)) {
+        return [...new Set([...Object.keys(before), ...Object.keys(after)])].flatMap(name => walk(before[name], after[name], rules, at ? `${at}.${name}` : name, key ? `${key}.${name}` : name));
+    }
+    return isDeepStrictEqual(before, after) ? [] : [at];
+}
+// The fields of an existing sibling that say what it is for. Everything else about a sibling decides
+// what the agent may write or read: its directory is a writable root, its environment files are the
+// instances the guard protects, its guides are copied into every agent's instructions, and its derived
+// MCP sources start processes outside the guard.
+const SIBLING_RULES = {
+    purpose: safe,
+    host_reason: safe,
+    // Only the stale-stack warning reads these.
+    rebuild_inputs: safe,
+    // An operator gate keeps a sibling out of default runs; adding one narrows, removing one widens.
+    gate: (before, after, at) => before !== undefined && after === undefined ? [at] : [],
+};
+// A new sibling is a new root the agent may write, wherever its directory is, so only a removed or
+// described one is compared field by field.
+const siblings = (before, after, at) => [
+    ...before.flatMap(row => {
+        const now = after.find(candidate => candidate.slug === row.slug);
+        // A removed sibling takes its instance protection with it, and its directory leaves the guard's view.
+        return now ? walk(row, now, SIBLING_RULES, `${at}.${row.slug}`) : [`${at}.${row.slug}`];
+    }),
+    ...after.filter(row => !before.some(candidate => candidate.slug === row.slug)).map(row => `${at}.${row.slug}`),
+];
+// A policy row admits its build and test commands in every sibling of its toolchain.
+const installPolicies = (before, after, at) => after.flatMap(row => {
+    const was = before.find(candidate => candidate.toolchain === row.toolchain && candidate.lockfile === row.lockfile);
+    return ['build', 'test'].filter(kind => row[kind] !== undefined && !isDeepStrictEqual(row[kind], was?.[kind]))
+        .map(kind => `${at}.${row.toolchain}:${row.lockfile}.${kind}`);
+});
+// Keyed by schema path from the configuration's root.
+const CHANGE_RULES = {
+    // Removing an entry would claim a person stated an answer nobody stated; policyChange admits the
+    // removal of one an observation recorded as confirmed for exactly the new configuration.
+    unconfirmed: onlyAdds,
+    'cockpit.guide_cap': safe,
+    sibling: siblings,
+    ports: safe,
+    'environment.compose_files': onlyRemoves,
+    // A profile starts more of the Compose files' services, as a new Compose file does.
+    'environment.profiles': onlyRemoves,
+    'environment.install_policies': installPolicies,
+    // Reset deletes exactly these volumes.
+    'environment.resettable_volumes': onlyRemoves,
+    // Addresses derived from leased ports, and the floor the host is held to: neither reaches the guard.
+    'environment.entrypoint_derivatives': safe,
+    'environment.machine': safe,
+    // Removing a tool deletes its guard registration.
+    'surfaces.tools': onlyAdds,
+    // Only docs check reads living documents. The decision paths stay a person's: work orders
+    // never count changes under them as out of scope.
+    'docs.living': safe,
+};
+/**
+ * Every schema path a rule names, so a test can hold each to a field the schema still has: a rule
+ * whose path was renamed away never matches, and its field silently falls back to the default.
+ * Paths under `sibling[].` name a field of a sibling row.
+ */
+export const POLICY_CHANGE_RULE_PATHS = Object.freeze([...Object.keys(CHANGE_RULES),
+    ...Object.keys(SIBLING_RULES).map(field => `sibling[].${field}`)]);
+/**
+ * Whether `after` lets agents do anything `before` did not, over the loaded configurations. Only a
+ * difference a rule above proves safe is non-widening; every other difference widens. `confirmed`
+ * names the answers whose recorded observation matches `after`; only those may leave `unconfirmed`.
+ */
+export function policyChange(before, after, confirmed = new Set()) {
+    const unconfirmed = (from = [], to = [], at) => gains(to, from.filter(answer => !confirmed.has(answer))) ? [at] : [];
+    const fields = walk(before, after, { ...CHANGE_RULES, unconfirmed }, '');
+    return fields.length ? { kind: 'widening', fields: [...new Set(fields)] } : { kind: 'non-widening' };
+}
+/**
+ * How the current configuration differs from the one the guards were generated from. `recorded` is
+ * the copy sync kept of that configuration; one missing, or not the configuration `generatedSha256`
+ * names, cannot show the edit is safe. `confirmations` is the machine-local record `cockpit confirm`
+ * keeps of the observations that confirmed answers.
+ */
+export function guardConfigChange(generatedSha256, recorded, current, confirmations) {
+    if (current.sha256 === generatedSha256)
+        return { kind: 'unchanged' };
+    const before = recorded && sha256Hex(recorded) === generatedSha256 ? parseCockpitConfigBytes(recorded) : undefined;
+    return before ? policyChange(before, current.config, confirmedAnswers(confirmations, current.config)) : { kind: 'unrecorded' };
+}
+/** Why a changed configuration needs a person before the guard applies it, for a hold or a check. */
+export function guardConfigHeldReason(change) {
+    return change.kind === 'widening'
+        ? `it widens what agents may do (${change.fields.join(', ')})`
+        : `the configuration they were generated from is not recorded in ${GUARD_LOCAL_PATHS.generatedConfig}, so the edit cannot be shown not to widen what agents may do`;
+}
+/** What `check` reports about an edit the guards were not regenerated for, or nothing. */
+export async function inspectGuardConfigChange(root, configPath, current) {
+    const local = async (path) => {
+        try {
+            const read = await readBoundedInput(join(root, path));
+            return read.kind === 'complete' ? read.bytes : undefined;
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT'))
+                return undefined;
+            throw error;
+        }
+    };
+    const identityBytes = await local(GUARD_LOCAL_PATHS.identity);
+    // No guard was generated on this machine, so nothing holds the agent.
+    if (!identityBytes)
+        return [];
+    const identity = parseGuardLocalIdentity(identityBytes.toString('utf8'));
+    if (!identity)
+        return [];
+    const change = guardConfigChange(identity.configSha256, await local(GUARD_LOCAL_PATHS.generatedConfig), current, await local(ANSWER_CONFIRMATION_PATH));
+    if (change.kind === 'unchanged')
+        return [];
+    if (change.kind === 'non-widening')
+        return [{ severity: 'warning', target: 'guard',
+                code: 'GUARD_CONFIG_UNSYNCED',
+                message: `cockpit.toml changed since the guards were generated without widening what agents may do; the guard holds every agent tool call except ${UNSYNCED_ADMITTED_PROSE} until it is synced`,
+                fix: `run ${cockpitCommand('sync', { config: configPath })}; an agent may run it where [autonomy] sync = "agent"` }];
+    return [{ severity: 'error', target: 'guard',
+            code: 'GUARD_CONFIG_WIDENED',
+            message: `cockpit.toml changed since the guards were generated and ${guardConfigHeldReason(change)}; the guard holds every agent tool call until a person syncs`,
+            fix: `a person reads the change and runs ${cockpitCommand('sync', { config: configPath })} in a terminal outside the agent, or the change is reverted` }];
+}

package/dist/guards/policy-pin.d.ts

@@ -0,0 +1,13 @@
+import { type GuardDecision } from './evaluator.js';
+import type { GuardFileContent, ParsedInvocation } from './invocation-parser.js';
+/**
+ * The denial for a tool call that would change the pinned policy tables, or undefined. `isConfig`
+ * says whether a lexically resolved path is the configuration, by spelling or by file identity.
+ */
+export declare function pinnedPolicyDenial(input: Readonly<{
+    tool: string;
+    cwd: string;
+    content?: GuardFileContent;
+    paths: readonly string[];
+    invocations: readonly ParsedInvocation[];
+}>, current: string, isConfig: (path: string) => boolean): GuardDecision | undefined;

package/dist/guards/policy-pin.js

@@ -0,0 +1,177 @@
+// Owns the guard's pin on the autonomy policy: an agent tool call that would change cockpit.toml's
+// [work] (with [work.gates]) or [autonomy] table, or [mcp] while a person approves MCP servers, is a
+// hard denial. An edit, write or patch is applied to the current text and the tables compared; a
+// shell command that names the file and is not a proven read, a Git record or cockpit's --config
+// operand cannot be applied, so it is denied too.
+// The decision is pure: the guard application supplies the current text and which targets are the
+// configuration under another name.
+import { posix } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { pinnedPolicyTables } from '../autonomy.js';
+import { innerCommand } from './evaluator.js';
+import { classifyReadOnlyInvocation, cockpitLauncherPrefix } from './read-only.js';
+const denial = (reason) => ({ decision: 'deny', reason });
+const PINNED = '[work], [work.gates] and [autonomy] (and [mcp] while [autonomy] mcp_approve is not agent)';
+/** Applies one `*** Update File` section of a patch to `text`, or undefined when a hunk does not match exactly once. */
+function applyPatchSection(text, lines) {
+    let result = text;
+    const hunks = [];
+    for (const line of lines) {
+        if (line.startsWith('@@'))
+            hunks.push([]);
+        else if (line !== '*** End of File')
+            (hunks.at(-1) ?? (hunks.push([]), hunks.at(-1))).push(line);
+    }
+    for (const hunk of hunks) {
+        const before = hunk.filter(line => !line.startsWith('+')).map(line => line.slice(1)).join('\n');
+        const after = hunk.filter(line => !line.startsWith('-')).map(line => line.slice(1)).join('\n');
+        const first = result.indexOf(before);
+        if (first < 0 || result.indexOf(before, first + 1) >= 0)
+            return undefined;
+        result = result.slice(0, first) + after + result.slice(first + before.length);
+    }
+    return result;
+}
+function proposedText(content, isConfig, current) {
+    if (content.kind === 'write')
+        return isConfig(content.path) ? content.content : 'untouched';
+    if (content.kind === 'replace') {
+        if (!isConfig(content.path))
+            return 'untouched';
+        if (!content.old)
+            return undefined;
+        const first = current.indexOf(content.old);
+        if (first < 0 || !content.all && current.indexOf(content.old, first + 1) >= 0)
+            return undefined;
+        return content.all ? current.split(content.old).join(content.new) : current.slice(0, first) + content.new + current.slice(first + content.old.length);
+    }
+    const lines = content.text.trimEnd().split('\n').slice(1, -1);
+    let section;
+    let target;
+    let touched = false;
+    let next = current;
+    const flush = () => {
+        if (!section || !target)
+            return true;
+        if (target === 'add') {
+            next = section.map(line => line.slice(1)).join('\n') + '\n';
+            return true;
+        }
+        const applied = applyPatchSection(next, section);
+        if (applied === undefined)
+            return false;
+        next = applied;
+        return true;
+    };
+    for (const line of lines) {
+        const header = /^\*\*\* (Add File|Update File|Delete File|Move to): (.+)$/.exec(line);
+        if (!header) {
+            section?.push(line);
+            continue;
+        }
+        if (!flush())
+            return undefined;
+        section = undefined;
+        target = undefined;
+        if (!isConfig(header[2]))
+            continue;
+        touched = true;
+        // Deleting or moving the configuration is the structural denial's; either way its tables would change.
+        if (header[1] === 'Delete File' || header[1] === 'Move to')
+            return undefined;
+        section = [];
+        target = header[1] === 'Add File' ? 'add' : 'update';
+    }
+    if (!flush())
+        return undefined;
+    return touched ? next : 'untouched';
+}
+const GIT_RECORDING = new Set(['add', 'commit', 'diff', 'log', 'show', 'status', 'blame']);
+// Only the `git` the command search path finds: a path spelled `git` may be any program.
+function recordsWithoutWriting(invocation) {
+    if (invocation.executable !== 'git')
+        return false;
+    const words = invocation.argv;
+    for (let index = 0; index < words.length; index++) {
+        const word = words[index];
+        if (word === '-C' || word === '-c') {
+            index++;
+            continue;
+        }
+        if (word.startsWith('-'))
+            return false;
+        return GIT_RECORDING.has(word);
+    }
+    return false;
+}
+/**
+ * The invocations the pin judges. A cockpit session or exec runs the words after its `--` as a
+ * command of its own, so that command is judged as one more invocation and the wrapper by the words
+ * before it. Exec's command runs in a product container, where neither a read-only spelling nor a
+ * cockpit launcher proves what the program is, so naming the configuration there is never excused.
+ */
+function judgedInvocations(invocations) {
+    const judged = [];
+    const pending = invocations.map(invocation => ({ ...invocation, contained: false }));
+    for (let invocation = pending.shift(); invocation; invocation = pending.shift()) {
+        const prefix = invocation.executable === null ? undefined : cockpitLauncherPrefix(invocation.executable, invocation.argv);
+        const inner = prefix === undefined ? undefined : innerCommand(invocation.argv.slice(prefix));
+        if (!inner) {
+            judged.push(invocation);
+            continue;
+        }
+        judged.push({ ...invocation, argv: invocation.argv.slice(0, invocation.argv.length - inner.words.length - 1) });
+        pending.push({ executable: inner.words[0], argv: inner.words.slice(1), cwd: invocation.cwd, wrapped: false, redirects: [],
+            words: inner.words.map((value, index) => ({ role: index ? 'argument' : 'executable', value })),
+            contained: invocation.contained || inner.runs === 'container' });
+    }
+    return judged;
+}
+/**
+ * The denial for a tool call that would change the pinned policy tables, or undefined. `isConfig`
+ * says whether a lexically resolved path is the configuration, by spelling or by file identity.
+ */
+export function pinnedPolicyDenial(input, current, isConfig) {
+    const resolved = (cwd) => (path) => isConfig(posix.resolve(cwd, path));
+    if (input.tool === 'Bash') {
+        for (const invocation of judgedInvocations(input.invocations)) {
+            const names = resolved(invocation.cwd);
+            // `--out=cockpit.toml` names the file as surely as a bare operand does.
+            const naming = invocation.argv.flatMap((word, index) => names(word) || word.includes('=') && names(word.slice(word.indexOf('=') + 1)) ? [index] : []);
+            const writes = invocation.redirects.some(redirect => redirect.write);
+            if (!naming.length && !invocation.redirects.some(redirect => redirect.write && names(redirect.target)))
+                continue;
+            // A proven read leaves the file as it is, and staging or committing it records the text the
+            // guard already checked.
+            if (!writes && !invocation.contained && (classifyReadOnlyInvocation(invocation) || recordsWithoutWriting(invocation)))
+                continue;
+            // Installed cockpit reads the file it is given with --config, but a path or `node <script>`
+            // spells any program as well as cockpit. Whether it starts cockpit is the evaluator's
+            // launcher proof, so only the --config operand is left to it; naming the file anywhere
+            // else is denied whatever the spelling starts.
+            const prefix = invocation.executable === null || invocation.contained ? undefined : cockpitLauncherPrefix(invocation.executable, invocation.argv);
+            const configOperand = (index) => prefix !== undefined && index >= prefix
+                && (invocation.argv[index].startsWith('--config=') || index > prefix && invocation.argv[index - 1] === '--config');
+            if (!writes && naming.every(configOperand))
+                continue;
+            return denial(`Refusing a shell command that names the cockpit configuration: the guard cannot tell whether it changes ${PINNED}, which only a person changes. Edit other tables with your editing tool, which the guard can check.`);
+        }
+        return undefined;
+    }
+    if (!input.paths.some(resolved(input.cwd)))
+        return undefined;
+    if (!input.content)
+        return denial(`Refusing an edit of the cockpit configuration whose new text the guard was not given, so it cannot show ${PINNED} unchanged.`);
+    const proposed = proposedText(input.content, resolved(input.cwd), current);
+    if (proposed === 'untouched')
+        return undefined;
+    if (proposed === undefined)
+        return denial(`Refusing an edit of the cockpit configuration that does not apply exactly once to its current text, so the guard cannot show ${PINNED} unchanged.`);
+    const before = pinnedPolicyTables(current);
+    const after = pinnedPolicyTables(proposed);
+    if (!before || !after)
+        return denial(`Refusing an edit that leaves the cockpit configuration unparseable, so the guard cannot show ${PINNED} unchanged.`);
+    if (!isDeepStrictEqual(before, after))
+        return denial(`Refusing to change ${PINNED} in the cockpit configuration: who may pass a gate is a person's decision, made outside the agent. Ask a person to edit it and run sync.`);
+    return undefined;
+}

package/dist/guards/protected-locations.d.ts

@@ -0,0 +1,62 @@
+import { type ExecutionStep } from '../environment/contract.js';
+import type { ResolvedExecutable } from '../environment/executable.js';
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+/**
+ * The running cockpit package and every package it loads, each under the spelling it was found by
+ * and its real path, plus the consumer's `node_modules` spelling of the package when that is a link
+ * to it. The guard authenticates only its entry point, so all of these are controls.
+ */
+export declare function guardInstalledDirectories(packageRoot: string, consumerRoot: string): readonly string[];
+/**
+ * The file whose identity proves that `executable` with the launcher `words` after it, run in `cwd`,
+ * starts `launcher`, the installed cockpit the guard runs from, or undefined when it may start
+ * something else. A path, or the script `node` is given, qualifies when it resolves to the launcher;
+ * the bare name when the first `cockpit` on the command search path does. `npx` qualifies only in
+ * `root`, where npm runs a `bin` the root package.json declares before any installed one and applies
+ * the root `.npmrc`, whose `script-shell` and `node-options` run other code first; with neither
+ * present it runs the root's `node_modules/.bin/cockpit`, which must resolve to the launcher.
+ */
+export declare function guardLauncherEvidence(executable: string, words: readonly string[], cwd: string, root: string, launcher: string, searchPath: string): string | undefined;
+/**
+ * Absolute search path entries, and their real paths, that lie inside an allowed root. A relative
+ * entry resolves against whatever directory a command runs in, so it names no fixed location.
+ */
+export declare function guardSearchDirectories(searchPath: string, allowedRoots: readonly string[]): readonly string[];
+/** The first entry of `searchPath` that is not absolute, an empty one included, or null when there is none. */
+export declare function guardSearchPathRelativeEntry(searchPath: string): string | null;
+/**
+ * Every path at or below `path` whose case-folded name starts with `.env` or is `.secrets`, of any
+ * type, without following links, as a recursive search would reach it; null once the walk passes
+ * `entryLimit` entries or finds more than the sensitive path bound. A missing path has none.
+ */
+export declare function guardSensitivePathsBelow(path: string, entryLimit?: number): readonly string[] | null;
+export type GuardExecute = (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+/**
+ * The paths a default ripgrep search of `path` reads that are named `.env*`, lie below a `.secrets`
+ * directory or are one of `watched`, each reported at its first such name, as Git lists what the
+ * enclosing repository does not ignore; null past the sensitive path bound. Undefined when Git
+ * did not answer or its list cannot stand for ripgrep's: outside a repository, through a
+ * nested repository or submodule, below an `.ignore` or `.rgignore` file, which ripgrep reads and Git
+ * does not, or when the search names an ignored directory, whose children ripgrep may still read.
+ *
+ * Only `.gitignore` files are applied: ripgrep reads those, the repository's exclude file and the
+ * global excludes file, but finds the global one by other rules than Git, so Git applying fewer
+ * lists more. Hidden paths are kept: a type such as `rg -t sh`, which matches `.env`, reads them.
+ * Undefined as well when a `.gitignore` Git reads holds a line the two may match differently.
+ */
+export declare function guardUnignoredSensitivePaths(path: string, watched: readonly string[], git: ResolvedExecutable, execute: GuardExecute): Promise<readonly string[] | null | undefined>;
+/**
+ * Every path `repository`'s index holds that is named `.env*`, lies below a `.secrets` or `.env*`
+ * directory or is one of `watched`, or null past the sensitive path bound or when Git did not
+ * answer. Only the index is asked: a file removed from it stays in history, which this does not walk.
+ */
+export declare function guardTrackedSensitivePaths(repository: string, watched: readonly string[], git: ResolvedExecutable, execute: GuardExecute): Promise<readonly string[] | null>;
+/**
+ * Identities of every file in each case-folded spelling of `env/.secrets` below `root`, and whether
+ * any has a second hard link; `identities` is null once more than the bound of entries was seen,
+ * which leaves every read unproven rather than silently uncovered.
+ */
+export declare function guardSecretFiles(root: string): {
+    readonly identities: readonly string[] | null;
+    readonly linked: boolean;
+};