@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/surfaces/harness-registry.d.ts

@@ -0,0 +1,180 @@
+export declare const HARNESS_REGISTRY: readonly [Readonly<{
+    target: "claudecode";
+    type: 'agent';
+    displayName: "Claude Code";
+    rulesyncTarget: "claudecode";
+    rulesyncFeatures: readonly ["rules", "mcp", "subagents", "skills", "hooks", "permissions"];
+    outputs: Readonly<{
+        instruction: "CLAUDE.md";
+        skills: ".claude/skills";
+        mcp: ".mcp.json";
+        permissions: readonly string[];
+    }>;
+    guard: Readonly<{
+        capability: 'instructed';
+        firing: Readonly<{
+            state: 'enforced';
+            evidence: 'not_applicable';
+            measuredOn: "2026-11-01";
+            measuredVersion: "2.1.316";
+            provenance: "with the exact push pre-allowed by permissions, the hook refused git push to a protected branch and the remote stayed empty while git status ran; the same checkout without the hook pushed";
+        }>;
+    }>;
+    native: Readonly<{
+        state: 'instructed';
+        reason: "a person has not yet reviewed whether the tool loads and triggers them as written";
+    }>;
+    sessionStart: Readonly<{
+        state: 'instructed';
+        evidence: 'not_applicable';
+        measuredOn: "2026-11-03";
+        measuredVersion: "2.1.317";
+        provenance: "a SessionStart hook in .claude/settings.json ran under claude -p and the agent quoted its stdout back, while a hook under a misspelled event name never ran and Claude Code named it as ignored";
+    }>;
+}>, Readonly<{
+    target: "codexcli";
+    type: 'agent';
+    displayName: "Codex";
+    rulesyncTarget: "codexcli";
+    rulesyncFeatures: readonly ["rules", "mcp", "subagents", "skills", "hooks", "permissions"];
+    outputs: Readonly<{
+        instruction: "AGENTS.md";
+        skills: ".agents/skills";
+        mcp: ".codex/config.toml";
+        permissions: readonly string[];
+    }>;
+    guard: Readonly<{
+        capability: 'instructed';
+        firing: Readonly<{
+            state: 'enforced';
+            evidence: 'human_needed';
+            measuredOn: "2026-11-01";
+            measuredVersion: "0.165.0";
+            provenance: "only after a person trusts the hook: untrusted, Codex skipped it and git push ran; trusted (forced with --dangerously-bypass-hook-trust), it refused the push. Trust is per machine and cockpit doctor warns until it is given";
+        }>;
+    }>;
+    native: Readonly<{
+        state: 'instructed';
+        reason: "a person has not yet reviewed whether the tool loads and triggers them as written";
+    }>;
+    sessionStart: Readonly<{
+        state: 'instructed';
+        evidence: 'human_needed';
+        measuredOn: "2026-11-03";
+        measuredVersion: "0.166.0";
+        provenance: "only after a person trusts the hook, as for the guard: a trusted SessionStart hook in .codex/hooks.json ran under codex exec and the agent quoted its stdout back, while a hook under a misspelled event name never ran";
+    }>;
+}>, Readonly<{
+    target: "opencode";
+    type: 'agent';
+    displayName: "OpenCode";
+    rulesyncTarget: "opencodev1";
+    rulesyncFeatures: readonly ["rules", "mcp", "subagents", "skills", "hooks"];
+    outputs: Readonly<{
+        instruction: "AGENTS.md";
+        skills: ".opencode/skills";
+        mcp: "opencode.jsonc";
+        permissions: readonly string[];
+    }>;
+    guard: Readonly<{
+        capability: 'instructed';
+        firing: Readonly<{
+            state: 'enforced';
+            evidence: 'not_applicable';
+            measuredOn: "2026-11-01";
+            measuredVersion: "1.19.4";
+            provenance: "the plugin refused git push and a native read of a secrets file while an unprotected read stayed allowed; before read was routed through the guard, the same read returned the file";
+        }>;
+    }>;
+    native: Readonly<{
+        state: 'instructed';
+        reason: "a person has not yet reviewed whether the tool loads and triggers them as written";
+    }>;
+    sessionStart: {
+        state: 'unavailable';
+        evidence: 'not_applicable';
+        measuredOn: string;
+        measuredVersion: null;
+        provenance: string;
+    };
+}>, Readonly<{
+    target: "cursor";
+    type: 'agent';
+    displayName: "Cursor";
+    rulesyncTarget: "cursor";
+    rulesyncFeatures: readonly ["rules", "mcp", "subagents", "skills", "hooks", "permissions"];
+    outputs: Readonly<{
+        instruction: ".cursor/rules";
+        skills: ".cursor/skills";
+        mcp: ".cursor/mcp.json";
+        permissions: readonly string[];
+    }>;
+    guard: Readonly<{
+        capability: 'unavailable';
+        measuredOn: "2026-10-28";
+        reason: "no guard adapter is checked in, so cockpit generates no guard hook";
+    }>;
+    native: Readonly<{
+        state: 'generated';
+        measuredOn: "2026-10-28";
+        reason: "cockpit writes the files, but no run of the tool beside a broken control has shown that it loads them";
+    }>;
+    sessionStart: {
+        state: 'unavailable';
+        evidence: 'not_applicable';
+        measuredOn: string;
+        measuredVersion: null;
+        provenance: string;
+    };
+}>, Readonly<{
+    target: "grokcli";
+    type: 'agent';
+    displayName: "Grok Build";
+    rulesyncTarget: "grokcli";
+    rulesyncFeatures: readonly ["rules", "mcp", "subagents", "skills", "hooks", "permissions"];
+    outputs: Readonly<{
+        instruction: "AGENTS.md";
+        skills: ".grok/skills";
+        mcp: ".grok/config.toml";
+        permissions: readonly string[];
+    }>;
+    guard: Readonly<{
+        capability: 'unavailable';
+        measuredOn: "2026-10-28";
+        reason: "no guard adapter is checked in, so cockpit generates no guard hook";
+    }>;
+    native: Readonly<{
+        state: 'generated';
+        measuredOn: "2026-10-28";
+        reason: "cockpit writes the files, but no run of the tool beside a broken control has shown that it loads them";
+    }>;
+    sessionStart: {
+        state: 'unavailable';
+        evidence: 'not_applicable';
+        measuredOn: string;
+        measuredVersion: null;
+        provenance: string;
+    };
+}>];
+export type HarnessRegistryRow = typeof HARNESS_REGISTRY[number];
+export type SurfaceTarget = HarnessRegistryRow['target'];
+export type GuardSurfaceTarget = Extract<HarnessRegistryRow, {
+    readonly guard: {
+        readonly capability: 'instructed';
+    };
+}>['target'];
+export declare const SURFACE_TARGETS: readonly SurfaceTarget[];
+export declare const GUARD_SURFACE_TARGETS: readonly GuardSurfaceTarget[];
+export declare const DEFAULT_SURFACE_TOOLS: readonly ("claudecode" | "codexcli" | "opencode")[];
+/** The listed tools in registry order, so rendering and drift do not depend on how the list is spelled. */
+export declare function listedSurfaceTargets(tools: readonly string[]): readonly SurfaceTarget[];
+export declare const SURFACE_EXECUTION_CONTROL_PATHS: readonly string[];
+export declare const SURFACE_PUBLICATION_ANCHORS: readonly string[];
+export declare function isGuardSurfaceTarget(value: unknown): value is GuardSurfaceTarget;
+/**
+ * A date a capability was measured on: a real calendar day, written YYYY-MM-DD, that is not still
+ * to come. Re-measuring a tool changes its date here and in the rows that quote it; the shape is
+ * checked rather than pinned to one literal, so a new run does not mean editing a type and a guard.
+ */
+export declare function isMeasurementDate(value: unknown, today?: Date): value is string;
+export declare function harnessFact(target: SurfaceTarget): HarnessRegistryRow;

package/dist/surfaces/harness-registry.js

@@ -0,0 +1,117 @@
+// Guard firing and instruction loading for these harnesses are dated runs (the firing records below
+// and the projection's instruction capabilities), so this record claims no pending measurement for
+// them; what stays open is a person's review of the rendered skills.
+const reviewedNative = Object.freeze({
+    state: 'instructed',
+    reason: 'a person has not yet reviewed whether the tool loads and triggers them as written',
+});
+// Cockpit writes rules, skills, MCP and permission files for these harnesses through the
+// generator, so `unavailable` (nothing emitted) would be false; nothing yet shows the tool reads them.
+const generatedNative = Object.freeze({
+    state: 'generated',
+    measuredOn: '2026-10-28',
+    reason: 'cockpit writes the files, but no run of the tool beside a broken control has shown that it loads them',
+});
+const noGuardAdapter = Object.freeze({
+    capability: 'unavailable',
+    measuredOn: '2026-10-28',
+    reason: 'no guard adapter is checked in, so cockpit generates no guard hook',
+});
+// A dated run of the real tool against the generated guard. It replaces the adapter's own record in
+// the capability matrix only while that adapter stays native; the adapter keeps recording the
+// transport shape it was written against.
+const claudeFiring = Object.freeze({
+    state: 'enforced', evidence: 'not_applicable', measuredOn: '2026-11-01', measuredVersion: '2.1.316',
+    provenance: 'with the exact push pre-allowed by permissions, the hook refused git push to a protected branch and the remote stayed empty while git status ran; the same checkout without the hook pushed',
+});
+const codexFiring = Object.freeze({
+    state: 'enforced', evidence: 'human_needed', measuredOn: '2026-11-01', measuredVersion: '0.165.0',
+    provenance: 'only after a person trusts the hook: untrusted, Codex skipped it and git push ran; trusted (forced with --dangerously-bypass-hook-trust), it refused the push. Trust is per machine and cockpit doctor warns until it is given',
+});
+const openCodeFiring = Object.freeze({
+    state: 'enforced', evidence: 'not_applicable', measuredOn: '2026-11-01', measuredVersion: '1.19.4',
+    provenance: 'the plugin refused git push and a native read of a secrets file while an unprotected read stayed allowed; before read was routed through the guard, the same read returned the file',
+});
+// The session-start drift check is guidance: the tool runs `cockpit check` as a session starts and
+// shows its report to the agent, which nothing makes act on it. Each run below put a marker line from
+// the hook into the agent's context, beside a misspelled event that never ran.
+const claudeSessionStart = Object.freeze({
+    state: 'instructed', evidence: 'not_applicable', measuredOn: '2026-11-03', measuredVersion: '2.1.317',
+    provenance: 'a SessionStart hook in .claude/settings.json ran under claude -p and the agent quoted its stdout back, while a hook under a misspelled event name never ran and Claude Code named it as ignored',
+});
+const codexSessionStart = Object.freeze({
+    state: 'instructed', evidence: 'human_needed', measuredOn: '2026-11-03', measuredVersion: '0.166.0',
+    provenance: 'only after a person trusts the hook, as for the guard: a trusted SessionStart hook in .codex/hooks.json ran under codex exec and the agent quoted its stdout back, while a hook under a misspelled event name never ran',
+});
+const noSessionStart = (reason) => ({ state: 'unavailable', evidence: 'not_applicable', measuredOn: '2026-11-03', measuredVersion: null, provenance: reason });
+const completeRulesyncFeatures = Object.freeze(['rules', 'mcp', 'subagents', 'skills', 'hooks', 'permissions']);
+const nonPermissionRulesyncFeatures = Object.freeze(['rules', 'mcp', 'subagents', 'skills', 'hooks']);
+export const HARNESS_REGISTRY = Object.freeze([
+    Object.freeze({
+        target: 'claudecode', type: 'agent', displayName: 'Claude Code', rulesyncTarget: 'claudecode',
+        rulesyncFeatures: completeRulesyncFeatures,
+        outputs: Object.freeze({ instruction: 'CLAUDE.md', skills: '.claude/skills', mcp: '.mcp.json', permissions: Object.freeze(['.claude/settings.json']) }),
+        guard: Object.freeze({ capability: 'instructed', firing: claudeFiring }), native: reviewedNative, sessionStart: claudeSessionStart,
+    }),
+    Object.freeze({
+        target: 'codexcli', type: 'agent', displayName: 'Codex', rulesyncTarget: 'codexcli',
+        rulesyncFeatures: completeRulesyncFeatures,
+        outputs: Object.freeze({ instruction: 'AGENTS.md', skills: '.agents/skills', mcp: '.codex/config.toml', permissions: Object.freeze(['.codex/config.toml']) }),
+        guard: Object.freeze({ capability: 'instructed', firing: codexFiring }), native: reviewedNative, sessionStart: codexSessionStart,
+    }),
+    Object.freeze({
+        target: 'opencode', type: 'agent', displayName: 'OpenCode', rulesyncTarget: 'opencodev1',
+        rulesyncFeatures: nonPermissionRulesyncFeatures,
+        outputs: Object.freeze({ instruction: 'AGENTS.md', skills: '.opencode/skills', mcp: 'opencode.jsonc', permissions: Object.freeze(['opencode.jsonc']) }),
+        guard: Object.freeze({ capability: 'instructed', firing: openCodeFiring }), native: reviewedNative,
+        // OpenCode 1.19.5 delivered session.created to a project plugin beside a misspelled hook that
+        // never ran, but its model call failed, so no plugin hook was shown to put text in the agent's context.
+        sessionStart: noSessionStart('OpenCode 1.19.5 delivers session.created to a plugin, but no run has shown a plugin putting text in the agent\'s context, so cockpit generates no session-start check'),
+    }),
+    Object.freeze({
+        target: 'cursor', type: 'agent', displayName: 'Cursor', rulesyncTarget: 'cursor',
+        rulesyncFeatures: completeRulesyncFeatures,
+        // Rules overlays only: cockpit's own instructions reach Cursor through the root AGENTS.md.
+        outputs: Object.freeze({ instruction: '.cursor/rules', skills: '.cursor/skills', mcp: '.cursor/mcp.json', permissions: Object.freeze(['.cursor/cli.json']) }),
+        guard: noGuardAdapter, native: generatedNative, sessionStart: noSessionStart('cockpit generates no hook for this tool'),
+    }),
+    Object.freeze({
+        target: 'grokcli', type: 'agent', displayName: 'Grok Build', rulesyncTarget: 'grokcli',
+        rulesyncFeatures: completeRulesyncFeatures,
+        outputs: Object.freeze({ instruction: 'AGENTS.md', skills: '.grok/skills', mcp: '.grok/config.toml', permissions: Object.freeze(['.grok/config.toml']) }),
+        guard: noGuardAdapter, native: generatedNative, sessionStart: noSessionStart('cockpit generates no hook for this tool'),
+    }),
+]);
+export const SURFACE_TARGETS = Object.freeze(HARNESS_REGISTRY.map(row => row.target));
+export const GUARD_SURFACE_TARGETS = Object.freeze(HARNESS_REGISTRY
+    .filter((row) => row.guard.capability === 'instructed')
+    .map(row => row.target));
+// The tools a cockpit renders when cockpit.toml lists none: the ones whose guard firing is a dated run
+// of the real tool. A tool the matrix has not measured is rendered only when a team lists it.
+export const DEFAULT_SURFACE_TOOLS = GUARD_SURFACE_TARGETS;
+/** The listed tools in registry order, so rendering and drift do not depend on how the list is spelled. */
+export function listedSurfaceTargets(tools) {
+    return SURFACE_TARGETS.filter(target => tools.includes(target));
+}
+// Native MCP and permission outputs can select executable programs or relax harness authority.
+// The guard derives its protected files from this owner so a new harness cannot omit the boundary.
+export const SURFACE_EXECUTION_CONTROL_PATHS = Object.freeze([...new Set(HARNESS_REGISTRY.flatMap(row => [row.outputs.mcp, ...row.outputs.permissions]))].sort());
+export const SURFACE_PUBLICATION_ANCHORS = Object.freeze([...new Set(HARNESS_REGISTRY.flatMap(row => [row.outputs.instruction, row.outputs.skills, row.outputs.mcp, ...row.outputs.permissions]
+        .filter(path => path.includes('/')).map(path => path.split('/')[0]).filter(path => path.startsWith('.'))))].sort());
+export function isGuardSurfaceTarget(value) {
+    return typeof value === 'string' && GUARD_SURFACE_TARGETS.some(target => target === value);
+}
+/**
+ * A date a capability was measured on: a real calendar day, written YYYY-MM-DD, that is not still
+ * to come. Re-measuring a tool changes its date here and in the rows that quote it; the shape is
+ * checked rather than pinned to one literal, so a new run does not mean editing a type and a guard.
+ */
+export function isMeasurementDate(value, today = new Date()) {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(parsed.valueOf()) && parsed.toISOString().slice(0, 10) === value && value <= today.toISOString().slice(0, 10);
+}
+export function harnessFact(target) {
+    return HARNESS_REGISTRY.find(row => row.target === target);
+}

package/dist/surfaces/mcp.d.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import { type SurfaceSourceFile, type SurfaceTarget } from './contract.js';
+declare const Source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"core">;
+    path: z.ZodString;
+    sha256: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"overlay">;
+    path: z.ZodString;
+    sha256: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"sibling">;
+    path: z.ZodString;
+    sha256: z.ZodString;
+    slug: z.ZodString;
+}, z.core.$strict>], "kind">;
+declare const Declaration: z.ZodObject<{
+    name: z.ZodString;
+    command: z.ZodString;
+    args: z.ZodArray<z.ZodString>;
+    cwd: z.ZodString;
+    envNames: z.ZodArray<z.ZodString>;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"core">;
+        path: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"overlay">;
+        path: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"sibling">;
+        path: z.ZodString;
+        sha256: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export type McpSource = z.infer<typeof Source>;
+export type McpDeclaration = z.infer<typeof Declaration>;
+export interface McpDiagnostic {
+    readonly code: 'MCP_INPUT_INVALID' | 'MCP_DECLARATION_INVALID' | 'MCP_COMMAND_CONFLICT' | 'MCP_NOT_APPROVED' | 'MCP_APPROVAL_UNKNOWN';
+    readonly message: string;
+    readonly server?: string;
+    readonly sources?: readonly McpSource[];
+    /** The approval digest of the server's current declaration, on MCP_NOT_APPROVED. */
+    readonly sha256?: string;
+}
+interface McpServer {
+    readonly name: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly envNames: readonly string[];
+    readonly enabled: boolean;
+    readonly sources: readonly McpSource[];
+}
+export interface McpCollection {
+    readonly servers: readonly McpServer[];
+    readonly wrappers: readonly {
+        readonly path: string;
+        readonly bytes: string;
+        readonly sha256: string;
+    }[];
+    readonly harnesses: readonly {
+        readonly target: SurfaceTarget;
+        readonly servers: readonly {
+            readonly name: string;
+            readonly command: string;
+            readonly args: readonly string[];
+            readonly enabled: boolean;
+        }[];
+    }[];
+}
+export type McpCollectionOutcome = Readonly<{
+    kind: 'complete';
+    result: McpCollection;
+    diagnostics: readonly McpDiagnostic[];
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: McpDiagnostic;
+}>;
+export type McpParseOutcome = Readonly<{
+    kind: 'complete';
+    declarations: readonly McpDeclaration[];
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: McpDiagnostic;
+}>;
+type McpIdentity = Pick<McpDeclaration, 'command' | 'args' | 'cwd' | 'envNames'>;
+/** The digest `[mcp.approved]` records for a server, so a changed declaration is no longer approved. */
+export declare function mcpApprovalDigest(declaration: McpIdentity, cockpitDirectory: string): string;
+export declare function collectMcpDeclarations(input: unknown): McpCollectionOutcome;
+export declare function hasTargetMcpServers(sources: readonly SurfaceSourceFile[], target: SurfaceTarget): boolean;
+export declare function parseMcpDeclarationFile(input: unknown): McpParseOutcome;
+export {};

package/dist/surfaces/mcp.js

@@ -0,0 +1,186 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { z } from 'zod';
+import { parseDocument } from 'yaml';
+import { INHERITED_TOOL_ENVIRONMENT, snapshotJson, tryParseJson } from '../environment/contract.js';
+import { reservedPathSegment, SURFACE_TARGETS } from './contract.js';
+import { harnessFact } from './harness-registry.js';
+const EnvironmentName = z.string().regex(/^[A-Z][A-Z0-9_]*$/).max(128);
+const ServerName = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/).max(128);
+const RelativePath = z.string().min(1).max(4096).refine(path => !isAbsolute(path)
+    && !/[\\\x00-\x1f\x7f]/.test(path) && !/^[a-z]:/i.test(path)
+    && path.split('/').every(part => part !== '' && part !== '.' && part !== '..' && !reservedPathSegment(part)));
+const ShellToken = z.string().min(1).max(4096).refine(value => !/[\x00-\x1f\x7f]|\$\(|\$\{|`/.test(value));
+const WorkingDirectory = ShellToken.refine(isAbsolute);
+const Sha256 = z.string().regex(/^[a-f0-9]{64}$/);
+const Source = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('core'), path: RelativePath, sha256: Sha256 }).strict(),
+    z.object({ kind: z.literal('overlay'), path: RelativePath, sha256: Sha256 }).strict(),
+    z.object({ kind: z.literal('sibling'), path: RelativePath, sha256: Sha256, slug: z.string().regex(/^[a-z0-9][a-z0-9-]*$/) }).strict(),
+]);
+const Argument = ShellToken.refine(value => !/^--?(?:api[-_]?key|token|password|secret|authorization|credential)(?:=|$)/i.test(value)
+    && !/^[a-z][a-z0-9+.-]*:\/\/[^/]*@/i.test(value));
+const Declaration = z.object({
+    name: ServerName,
+    command: ShellToken.refine(value => !value.startsWith('-')),
+    args: z.array(Argument).max(256),
+    cwd: WorkingDirectory,
+    envNames: z.array(EnvironmentName).max(128).refine(names => new Set(names).size === names.length),
+    source: Source,
+}).strict();
+const Input = z.object({
+    cockpitDirectory: WorkingDirectory,
+    declarations: z.array(Declaration).max(256),
+    approved: z.record(ServerName, Sha256).refine(approved => Object.keys(approved).length <= 256),
+    targets: z.array(z.enum(SURFACE_TARGETS)).min(1).max(SURFACE_TARGETS.length).refine(targets => new Set(targets).size === targets.length),
+}).strict();
+function refuse(code, message) {
+    return { kind: 'refusal', diagnostic: { code, message } };
+}
+function quote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+// Each harness starts the wrapper as `.cockpit/mcp/<id>.sh` from the directory the agent was
+// launched in, so it runs only from the cockpit root (the guard hooks require the same) and the
+// server's directory is relative to it: the committed bytes are the same in every clone. The `./`
+// keeps CDPATH from choosing another directory and printing it into the JSON-RPC stream, and `-P`
+// resolves `..` from the real root, against which the relative path was computed.
+function wrapper(server, cockpitDirectory) {
+    const inherited = ['PATH', ...INHERITED_TOOL_ENVIRONMENT].filter(name => !server.envNames.includes(name));
+    return [
+        '#!/bin/sh',
+        'set -eu',
+        `cd -P -- ${quote(`./${relative(cockpitDirectory, server.cwd) || '.'}`)}`,
+        `executable=$(command -v ${quote(server.command)}) || { printf '%s\\n' 'MCP_EXECUTABLE_UNAVAILABLE' >&2; exit 2; }`,
+        '[ -f "$executable" ] && [ -x "$executable" ] || { printf \'%s\\n\' \'MCP_EXECUTABLE_UNAVAILABLE\' >&2; exit 2; }',
+        // `npx`, `uvx` and most npm servers are `#!/usr/bin/env node` scripts: without PATH they
+        // cannot start. The rest of the inherited set carries caches and locale, never a credential.
+        `exec /usr/bin/env -i ${inherited.map(name => `\${${name}+"${name}=$${name}"}`).join(' ')}`
+            + `${server.envNames.map(name => ` ${name}="\${${name}?required environment name ${name} is unset}"`).join('')} "$executable"${server.args.map(arg => ` ${quote(arg)}`).join('')}`,
+        '',
+    ].join('\n');
+}
+// What a human reviews before approving a server: everything the wrapper runs. The working
+// directory is taken relative to the cockpit so the digest is the same in every clone.
+function identity(declaration, cockpitDirectory) {
+    return JSON.stringify({ command: declaration.command, args: declaration.args, cwd: relative(cockpitDirectory, declaration.cwd) || '.', envNames: [...declaration.envNames].sort() });
+}
+/** The digest `[mcp.approved]` records for a server, so a changed declaration is no longer approved. */
+export function mcpApprovalDigest(declaration, cockpitDirectory) {
+    return createHash('sha256').update(identity(declaration, cockpitDirectory)).digest('hex');
+}
+export function collectMcpDeclarations(input) {
+    const captured = snapshotJson(input);
+    const parsed = Input.safeParse(captured);
+    if (!parsed.success)
+        return refuse('MCP_INPUT_INVALID', 'MCP declarations, approvals and targets must be bounded canonical data');
+    const { approved, cockpitDirectory } = parsed.data;
+    const collected = new Map();
+    for (const declaration of parsed.data.declarations) {
+        const prior = collected.get(declaration.name);
+        if (prior && identity(prior.declaration, cockpitDirectory) !== identity(declaration, cockpitDirectory)) {
+            const conflict = snapshotJson({ kind: 'refusal', diagnostic: {
+                    code: 'MCP_COMMAND_CONFLICT', server: declaration.name,
+                    message: 'MCP server identity has divergent command, arguments, working directory or environment names',
+                    sources: [...prior.sources, declaration.source],
+                } });
+            return conflict ? conflict
+                : refuse('MCP_INPUT_INVALID', 'MCP conflict exceeds the bounded data budget');
+        }
+        if (prior) {
+            if (!prior.sources.some(source => JSON.stringify(source) === JSON.stringify(declaration.source)))
+                prior.sources.push(declaration.source);
+        }
+        else
+            collected.set(declaration.name, { declaration, sources: [declaration.source] });
+    }
+    const digests = new Map([...collected].map(([name, { declaration }]) => [name, mcpApprovalDigest(declaration, cockpitDirectory)]));
+    const servers = [...collected.values()].map(({ declaration, sources }) => ({
+        name: declaration.name, command: declaration.command, args: declaration.args, cwd: declaration.cwd,
+        envNames: [...declaration.envNames].sort(), enabled: Object.hasOwn(approved, declaration.name) && approved[declaration.name] === digests.get(declaration.name),
+        sources: sources.sort((left, right) => JSON.stringify(left) < JSON.stringify(right) ? -1 : JSON.stringify(left) > JSON.stringify(right) ? 1 : 0),
+    })).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    const diagnostics = servers.filter(server => !server.enabled).map(server => ({
+        code: 'MCP_NOT_APPROVED', server: server.name, sources: server.sources, sha256: digests.get(server.name),
+        message: 'MCP server has no shared approval for its current declaration and remains disabled',
+    }));
+    for (const name of Object.keys(approved).sort())
+        if (!collected.has(name))
+            diagnostics.push({
+                code: 'MCP_APPROVAL_UNKNOWN', server: name, message: 'The shared approval list names an undeclared MCP server',
+            });
+    const wrappers = servers.map(server => {
+        const bytes = wrapper(server, cockpitDirectory);
+        return { path: `.cockpit/mcp/${createHash('sha256').update(server.name).digest('hex')}.sh`, bytes, sha256: createHash('sha256').update(bytes).digest('hex') };
+    });
+    const result = {
+        servers, wrappers,
+        harnesses: parsed.data.targets.map(target => ({ target, servers: servers.map((server, index) => ({
+                name: server.name, command: '/bin/sh', args: [wrappers[index].path], enabled: server.enabled,
+            })) })),
+    };
+    const outcome = snapshotJson({ kind: 'complete', result, diagnostics });
+    return outcome ? outcome : refuse('MCP_INPUT_INVALID', 'Canonical MCP output exceeds the bounded data budget');
+}
+const NativeServer = z.object({
+    type: z.literal('stdio').optional(), command: Declaration.shape.command,
+    args: z.array(Argument).max(256).default([]), cwd: RelativePath.or(z.literal('.')).optional(),
+    env: z.record(EnvironmentName, z.string().max(128)).default({}),
+}).strict();
+// Absence is inferred only from cockpit's neutral shape; other source forms retain generator validation.
+const GeneratedServer = NativeServer.extend({ cwd: WorkingDirectory.optional(), disabled: z.boolean().optional() });
+const GeneratedServers = z.record(ServerName, GeneratedServer);
+const TargetServers = z.object({ mcpServers: z.record(ServerName, GeneratedServer.nullable()).optional() }).strict();
+export function hasTargetMcpServers(sources, target) {
+    const source = sources.find(candidate => candidate.path === 'mcp.jsonc');
+    if (!source)
+        return false;
+    try {
+        const document = parseDocument(source.bytes, { uniqueKeys: true });
+        const root = z.record(z.string(), z.unknown()).safeParse(JSON.parse(source.bytes));
+        if (document.errors.length > 0 || document.warnings.length > 0 || !root.success)
+            return true;
+        const shared = GeneratedServers.safeParse(root.data.mcpServers);
+        const targetNames = SURFACE_TARGETS.map(candidate => harnessFact(candidate).rulesyncTarget);
+        if (!shared.success || Object.entries(root.data).some(([name, value]) => name !== 'mcpServers'
+            && (!targetNames.some(candidate => candidate === name) || !TargetServers.safeParse(value).success)))
+            return true;
+        const override = TargetServers.safeParse(root.data[harnessFact(target).rulesyncTarget] ?? {});
+        if (!override.success)
+            return true;
+        return Object.values({ ...shared.data, ...override.data.mcpServers }).some(server => server !== null);
+    }
+    catch {
+        // Unknown syntax and malformed declarations still reach Rulesync's authenticated parser.
+        return true;
+    }
+}
+const NativeFile = z.object({ mcpServers: z.record(ServerName, NativeServer).refine(servers => Object.keys(servers).length <= 256) }).strict();
+const ParseInput = z.object({ bytes: z.string(), source: Source, workingDirectory: WorkingDirectory }).strict();
+export function parseMcpDeclarationFile(input) {
+    const parsed = ParseInput.safeParse(snapshotJson(input));
+    if (!parsed.success)
+        return refuse('MCP_DECLARATION_INVALID', 'MCP source must be bounded authenticated declaration bytes');
+    const { bytes, source, workingDirectory } = parsed.data;
+    if (createHash('sha256').update(bytes).digest('hex') !== source.sha256)
+        return refuse('MCP_DECLARATION_INVALID', 'MCP source digest does not match declaration bytes');
+    const value = tryParseJson(bytes);
+    if (value === undefined)
+        return refuse('MCP_DECLARATION_INVALID', 'MCP declaration is not valid JSON');
+    const file = NativeFile.safeParse(value);
+    if (!file.success)
+        return refuse('MCP_DECLARATION_INVALID', 'MCP declaration contains unsupported command, environment or transport fields');
+    const declarations = [];
+    for (const [name, server] of Object.entries(file.data.mcpServers)) {
+        if (Object.entries(server.env).some(([key, reference]) => reference !== `\${${key}}`)) {
+            return refuse('MCP_DECLARATION_INVALID', 'MCP environment entries must reference their same declared environment name');
+        }
+        const cwd = resolve(workingDirectory, server.cwd ?? '.');
+        const offset = relative(workingDirectory, cwd);
+        if (offset === '..' || offset.startsWith('../') || isAbsolute(offset))
+            return refuse('MCP_DECLARATION_INVALID', 'MCP working directory escapes its declared sibling');
+        declarations.push({ name, command: server.command, args: server.args, cwd, envNames: Object.keys(server.env).sort(), source });
+    }
+    const captured = snapshotJson({ kind: 'complete', declarations });
+    return captured ? captured : refuse('MCP_DECLARATION_INVALID', 'MCP declarations exceed the bounded data budget');
+}

package/dist/surfaces/merge.d.ts

@@ -0,0 +1,30 @@
+import { type SurfaceDeclaration as SurfaceDeclarationValue } from '../schema.js';
+import type { SurfaceFeature } from './contract.js';
+export interface ActiveSurfaceOverride {
+    readonly name: string;
+    readonly feature: SurfaceFeature;
+    readonly originalSha256: string;
+    readonly recordedSha256: string;
+    readonly overlaySource: string;
+}
+export interface SurfaceUpgradeFinding {
+    readonly code: 'OVERRIDDEN_CORE_CHANGED';
+    readonly name: string;
+    readonly recordedSha256: string;
+    readonly currentSha256: string;
+    readonly overlaySource: string;
+}
+export interface SurfaceMergeComplete {
+    readonly kind: 'complete';
+    readonly surfaces: readonly SurfaceDeclarationValue[];
+    readonly overrides: readonly ActiveSurfaceOverride[];
+    readonly findings: readonly SurfaceUpgradeFinding[];
+}
+export interface SurfaceMergeRefusal {
+    readonly kind: 'refusal';
+    readonly code: 'SURFACE_INPUT_INVALID' | 'SURFACE_NAME_DUPLICATE' | 'SURFACE_KIND_AMBIGUOUS' | 'SURFACE_OVERRIDE_INVALID' | 'SURFACE_PATH_CONFLICT';
+    readonly message: string;
+}
+export type SurfaceMergeResult = SurfaceMergeComplete | SurfaceMergeRefusal;
+export declare function surfaceDeclarationSha256(declaration: SurfaceDeclarationValue): string;
+export declare function mergeSurfaceDeclarations(coreInput: unknown, overlayInput: unknown): SurfaceMergeResult;