@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/generated-application/shared.js

@@ -0,0 +1,354 @@
+import { cockpitCommand } from '../../fix-catalogue.js';
+import { proposeGeneratedEnvironmentRepair } from '../../repair.js';
+import { createHash } from 'node:crypto';
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isProxy } from 'node:util/types';
+import { parseDocument } from 'yaml';
+import { observeConfigSource } from '../../config/load.js';
+import { executeProbe } from '../../environment-exec/execute.js';
+import { CORE_EVALUATOR_ASSET as EVALUATOR_ASSET, CORE_SKILL_ASSETS as SKILL_ASSETS } from '../../surfaces/core-declarations.js';
+import { encodeOwnershipManifest, projectGeneratedPathFacts, } from '../../surfaces/ownership.js';
+import { ENVIRONMENT_CODES, errorCause, hasErrorCode } from '../contract.js';
+import { cockpitId, stackId } from '../identity.js';
+import { refusalOutcome as refuse } from '../../refusal.js';
+export const OWNER = 'generated-environment-application';
+export const surfaceObservationDeclarations = Object.freeze([
+    { id: 'harness-surfaces', owner: OWNER, postures: ['environment'], stages: [{ stage: 'bootstrap', disposition: 'required' }, { stage: 'steady', disposition: 'required' }], code: ENVIRONMENT_CODES.HARNESS_SURFACE_UNAVAILABLE, isIssued: isGeneratedApplicationSurfaceObservation, issuedAt: generatedApplicationSurfaceObservationIssuedAt },
+    { id: 'directory-grants', owner: OWNER, postures: ['directory-grants'], stages: [{ stage: 'bootstrap', disposition: 'required' }, { stage: 'steady', disposition: 'required' }], code: ENVIRONMENT_CODES.DIRECTORY_GRANTS_UNAVAILABLE, isIssued: isGeneratedApplicationSurfaceObservation, issuedAt: generatedApplicationSurfaceObservationIssuedAt },
+    { id: 'guide-budget', owner: OWNER, postures: ['environment'], stages: [{ stage: 'bootstrap', disposition: 'required' }, { stage: 'steady', disposition: 'required' }], code: ENVIRONMENT_CODES.GUIDE_CAP_EXCEEDED, isIssued: isGeneratedApplicationSurfaceObservation, issuedAt: generatedApplicationSurfaceObservationIssuedAt },
+    { id: 'skill-budget', owner: OWNER, postures: ['environment'], stages: [{ stage: 'bootstrap', disposition: 'required' }, { stage: 'steady', disposition: 'required' }], code: ENVIRONMENT_CODES.SKILL_BUDGET_UNAVAILABLE, isIssued: isGeneratedApplicationSurfaceObservation, issuedAt: generatedApplicationSurfaceObservationIssuedAt },
+]);
+export const issuedSurfaceObservations = new WeakMap();
+function containedPath(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot === '' || fromRoot !== '..' && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);
+}
+export function activeClaudeImports(bytes) {
+    const imports = [];
+    let fence;
+    let inComment = false;
+    for (const [index, line] of bytes.split(/\r?\n/u).entries()) {
+        const trimmed = line.trimStart();
+        const marker = /^ {0,3}(?<fence>`{3,}|~{3,})(?<suffix>.*)$/u.exec(line)?.groups;
+        if (fence) {
+            if (marker?.fence?.[0] === fence.marker && marker.fence.length >= fence.length
+                && marker.suffix?.trim() === '')
+                fence = undefined;
+            continue;
+        }
+        if (inComment) {
+            if (trimmed.includes('-->'))
+                inComment = false;
+            continue;
+        }
+        if (trimmed.startsWith('<!--')) {
+            if (!trimmed.includes('-->'))
+                inComment = true;
+            continue;
+        }
+        if (marker?.fence && (marker.fence[0] !== '`' || !marker.suffix?.includes('`'))) {
+            fence = { marker: marker.fence[0], length: marker.fence.length };
+            continue;
+        }
+        if (line === '@AGENTS.md')
+            imports.push(index);
+    }
+    return imports;
+}
+export async function siblingRootsCurrent(authority) {
+    try {
+        if (await realpath(authority.declaredRoot) !== authority.canonicalRoot)
+            return false;
+        const root = await lstat(authority.canonicalRoot);
+        if (!root.isDirectory() || root.isSymbolicLink()
+            || root.dev !== authority.rootIdentity.dev || root.ino !== authority.rootIdentity.ino)
+            return false;
+        for (const sibling of authority.siblings.values()) {
+            const canonical = await realpath(sibling.root);
+            const status = await lstat(canonical);
+            if (canonical !== sibling.root || !containedPath(authority.canonicalRoot, canonical)
+                || !status.isDirectory() || status.isSymbolicLink()
+                || status.dev !== sibling.identity.dev || status.ino !== sibling.identity.ino)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        // a failed re-observation means the root is no longer authenticated; the caller refuses.
+        return false;
+    }
+}
+// A teammate's clone of a cockpit has none of its siblings until setup clones them; a sibling
+// setup cannot clone was reported as a bare realpath ENOENT with nothing to do about it.
+function absentSibling(sibling, path, configPath) {
+    const setup = cockpitCommand('setup', { config: configPath });
+    const fix = sibling.acquire === 'auto' ? `run ${setup}, which clones ${sibling.remote} there, then rerun this command`
+        : sibling.acquire === 'manual' ? `clone ${sibling.remote} into ${path}, then rerun this command`
+            : `clone or create the repository at ${path}, then rerun this command; cockpit.toml records no remote for it (acquire = "none"), so setup cannot clone it: whoever has the checkout records one with ${cockpitCommand('sibling add', { operand: sibling.slug, config: configPath, args: '--remote <url>' })} and commits cockpit.toml, and every later ${setup} clones it`;
+    return {
+        kind: 'refusal',
+        // A literal, so the diagnostic inventory captures the fix beside the code.
+        code: 'SIBLING_MISSING',
+        reason: `sibling ${sibling.slug} is declared at ${path}, and nothing is there`,
+        target: `sibling:${sibling.slug}`,
+        fix,
+    };
+}
+export async function authenticateSiblingRoots(root, config, configPath) {
+    try {
+        const declaredRoot = resolve(root, config.cockpit.siblings_root);
+        const canonicalRoot = await realpath(declaredRoot);
+        const rootStatus = await lstat(canonicalRoot);
+        if (!rootStatus.isDirectory() || rootStatus.isSymbolicLink()) {
+            return { kind: 'refusal', reason: 'the declared sibling root is not an ordinary directory' };
+        }
+        const siblings = new Map();
+        for (const sibling of config.sibling) {
+            const declared = resolve(declaredRoot, sibling.dir);
+            if (!containedPath(declaredRoot, declared)) {
+                return { kind: 'refusal', reason: `sibling ${sibling.slug} escapes the declared sibling root` };
+            }
+            const present = await lstat(declared).then(() => true, (error) => {
+                if (hasErrorCode(error, 'ENOENT'))
+                    return false;
+                throw error;
+            });
+            if (!present)
+                return absentSibling(sibling, declared, configPath);
+            const canonical = await realpath(declared);
+            const status = await lstat(canonical);
+            if (!containedPath(canonicalRoot, canonical)) {
+                return { kind: 'refusal', reason: `sibling ${sibling.slug} resolves outside the declared sibling root` };
+            }
+            if (!status.isDirectory() || status.isSymbolicLink()) {
+                return { kind: 'refusal', reason: `sibling ${sibling.slug} is not an ordinary directory` };
+            }
+            siblings.set(sibling.slug, { root: canonical, identity: { dev: status.dev, ino: status.ino } });
+        }
+        return { kind: 'complete', roots: {
+                declaredRoot, canonicalRoot, rootIdentity: { dev: rootStatus.dev, ino: rootStatus.ino }, siblings,
+            } };
+    }
+    catch (error) {
+        const reason = errorCause(error);
+        return { kind: 'refusal', reason: `could not verify the sibling root (${reason})` };
+    }
+}
+export const defaultAdapters = { observeSource: observeConfigSource, execute: executeProbe };
+export const OWNERSHIP_PATH = '.cockpit/generated-environment-ownership.json';
+export const SHA256 = /^[a-f0-9]{64}$/;
+export const MAX_OWNERSHIP_BYTES = 1_048_576;
+export const COMPOSE_SOURCE_BYTES = 1_048_576;
+export const MAX_OWNED_FILES = 256;
+export const MAX_EXECUTABLE_BYTES = 536_870_912;
+export const MAX_GENERATED_BYTES = 16_777_216;
+export const MAX_SURFACE_FILE_BYTES = 65_536;
+const MAX_SURFACE_BYTES = 4_194_304;
+export const MAX_HELPER_FRAME_BYTES = 65_536;
+export const HELPER_TIMEOUT_MS = 10_000;
+// The native hook cost workload spawns Git once per ref update, 128 times. On a loaded host that
+// takes seconds (7 s at a load average of 24), so under the helper bound an over-budget hook timed
+// out and was reported as a failed execution instead of being sent to CI.
+export const NATIVE_HOOK_COST_TIMEOUT_MS = 60_000;
+export const SURFACE_ROOT = fileURLToPath(new URL('../../../surfaces', import.meta.url));
+export const RESTRICTION_ASSETS = Object.freeze([
+    'guards/bash-guard.sh',
+    'guards/claude.adapter.json',
+    'guards/codex.adapter.json',
+    'guards/opencode.adapter.json',
+]);
+// Shipped beside the setup skill, outside the skill contract: the skill set admits only entry points and the
+// shared procedure, and these are pulled on demand like the browser reference.
+export const REFERENCE_ASSETS = Object.freeze([
+    'references/test-data-and-personas.md',
+]);
+export const WORK_ASSETS = Object.freeze([
+    'skills/cockpit-browser.skill.md',
+    'references/browser.md',
+    'references/testing-tiers.md',
+]);
+export const issuedApplicationProjections = new WeakMap();
+export const projectedWorkApplicationAuthorities = new WeakSet();
+export const issuedWorkApplicationAuthorities = new WeakMap();
+export const issuedSelectedBootstrapAuthorities = new WeakMap();
+export const consumedBootstrapStatePublications = new WeakSet();
+export function skillDescription(bytes) {
+    const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(bytes)?.[1];
+    if (front === undefined)
+        return undefined;
+    const description = parseDocument(front).toJS({ maxAliasCount: 0 })?.description;
+    return typeof description === 'string' ? description : undefined;
+}
+export const compareCodeUnits = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+export function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function ownRecord(value) {
+    try {
+        if (value === null || typeof value !== 'object' || Array.isArray(value) || isProxy(value)
+            || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+            return undefined;
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (Object.getOwnPropertySymbols(value).length > 0
+            || Object.values(descriptors).some((descriptor) => descriptor.get || descriptor.set || !descriptor.enumerable))
+            return undefined;
+        return Object.fromEntries(Object.entries(descriptors).map(([key, descriptor]) => [key, descriptor.value]));
+    }
+    catch {
+        // a guard over caller-supplied values; a throwing accessor or proxy trap is malformed input the caller refuses.
+        return undefined;
+    }
+}
+export function guideLines(bytes) {
+    return bytes.trimEnd().split('\n').length;
+}
+// An overlay pins the digest of the built-in it replaces, so a cockpit upgrade that changes that
+// built-in is reviewed before the override keeps shadowing it.
+function overrideChanged(finding, severity) {
+    return {
+        severity, code: 'OVERRIDDEN_CORE_CHANGED', target: finding.overlaySource,
+        message: `overlay ${finding.name} replaces the built-in ${finding.name} recorded as sha256 ${finding.recordedSha256}, but this cockpit version's built-in is sha256 ${finding.currentSha256}`,
+        fix: 'review the new built-in against your override, set the overlay\'s replaces.sha256 to the current digest this message names, then run npx --no cockpit sync --config <your cockpit.toml>',
+    };
+}
+// Copied sibling guides count toward the cap, so a sibling's own edit can push it over.
+export function guideCapExceeded(cost) {
+    return { kind: 'refusal', artifact: null, destination: null, result: null, status: 2,
+        diagnostics: [{
+                severity: 'error', code: ENVIRONMENT_CODES.GUIDE_CAP_EXCEEDED, target: 'cockpit.guide_cap',
+                message: `the instructions ${cost.target} loads at start are ${cost.value} lines, over cockpit.guide_cap ${cost.cap}; the count includes each sibling guide copied into the root AGENTS.md`,
+                fix: 'shorten the root or sibling guides, or move conditional guidance into a skill, or raise cockpit.guide_cap in cockpit.toml, then run npx --no cockpit sync --config <your cockpit.toml>',
+            }] };
+}
+// Codex 0.166.0 dropped the end of a project AGENTS.md past 32 KiB without saying so (measured
+// 2026-11-03), and the copied sibling guides sit at the end of cockpit's region. The team's own text
+// outside the region counts too, so this is the least the file holds.
+export const CODEX_PROJECT_DOC_BYTES = 32_768;
+export function guideBytesExceeded(bytes) {
+    return { kind: 'refusal', artifact: null, destination: null, result: null, status: 2,
+        diagnostics: [{
+                severity: 'error',
+                // A literal, so the diagnostic inventory captures the fix beside the code.
+                code: 'GUIDE_CAP_EXCEEDED',
+                target: 'AGENTS.md',
+                message: `cockpit's part of the root AGENTS.md, with the sibling guides it copies, is ${bytes} bytes; Codex drops whatever follows the first 32768 bytes of a project AGENTS.md without saying so`,
+                fix: 'shorten the root or sibling guides, or name fewer guides in sibling.guides, then run npx --no cockpit sync --config <your cockpit.toml>',
+            }] };
+}
+// The projection skips an absent guide, so a misspelled name otherwise copies nothing and says nothing.
+export function siblingGuideMissing(slug, guide, sourcePath) {
+    return { kind: 'refusal', artifact: null, destination: null, result: null, status: 2,
+        diagnostics: [{
+                severity: 'error',
+                code: 'SIBLING_GUIDE_MISSING',
+                target: `sibling.${slug}.guides`,
+                message: `sibling ${slug} declares the guide ${guide}, but ${sourcePath} does not exist, so no harness would load it`,
+                fix: 'correct or remove the guide name in that sibling\'s guides list in cockpit.toml, then run npx --no cockpit sync --config <your cockpit.toml>',
+            }] };
+}
+export function overrideChangedRefusal(finding) {
+    return { kind: 'refusal', artifact: null, destination: null, result: null, status: 2,
+        diagnostics: [overrideChanged(finding, 'error')] };
+}
+export function complete(action, prepared, dryRun = false, changes = [], staleRemoval) {
+    if (!prepared.surfaceSelftest || !prepared.surfaceHealth)
+        return refuse('SURFACE_INPUT_INVALID', 'authenticated surface health inputs are missing', 'surfaces');
+    const generatedPaths = generatedPathFacts(prepared, dryRun ? 'declared-before-sync' : 'required-after-sync');
+    if (generatedPaths.kind !== 'complete')
+        return refuse(generatedPaths.diagnostic.code, generatedPaths.diagnostic.message, generatedPaths.diagnostic.target);
+    const application = {
+        generatedPaths: generatedPaths.facts,
+        sourceSha256: prepared.sourceSha256,
+        runtimeSha256: prepared.runtimeSha256,
+        generation: prepared.generation,
+        surfaceSelftest: prepared.surfaceSelftest,
+        activeSurfaceOverrides: prepared.activeSurfaceOverrides,
+        changedOverrideOriginals: prepared.changedOverrideOriginals,
+        inspection: {
+            kind: 'passed',
+            files: prepared.owned.map(({ path, sha256: digest }) => ({ path, sha256: digest, ownership: 'whole-file' })),
+        },
+    };
+    issuedApplicationProjections.set(application, Object.freeze({
+        root: prepared.root, stackId: prepared.stackId, currentPublication: !dryRun,
+        siblingRoots: prepared.siblingRoots,
+        node: prepared.node, surfaceSelftest: prepared.surfaceSelftest, surfaceHealth: prepared.surfaceHealth,
+        ...(!dryRun && prepared.workApplication ? { workApplication: prepared.workApplication } : {}),
+    }));
+    return {
+        kind: 'complete', artifact: null, destination: null,
+        diagnostics: [
+            // A trust warning is a review prompt for settings being written; repeating it for an
+            // unchanged file on every sync and check trained people to ignore it.
+            ...prepared.warnings.filter(warning => changes.some(change => change.operation === 'write' && change.path === warning.path))
+                .map(({ severity, code, target, path, message }) => ({
+                severity, code, target: `${target}:${path}`, message,
+            })),
+            ...prepared.unapprovedMcpServers.map(server => ({
+                severity: 'warning', code: 'MCP_NOT_APPROVED', target: server.name,
+                message: `MCP server ${server.name}, declared in ${server.sources.join(', ')}, has no approval in [mcp.approved] for its current declaration (command, arguments, working directory and environment names for a local server; URL, header references and headers helper for a remote one) (sha256 ${server.sha256}), so every harness keeps it disabled`,
+                fix: 'a person reviews its declaration, sets its name to the sha256 in this message under [mcp.approved] in cockpit.toml and runs npx --no cockpit sync --config <your cockpit.toml>; while [autonomy] mcp_approve is person, the default, the guard refuses an agent\'s edit of [mcp]. To keep it off, nothing is needed',
+            })),
+            ...prepared.mcpTransportGaps.map(gap => ({
+                severity: 'warning', code: 'MCP_TRANSPORT_UNAVAILABLE', target: gap.name,
+                message: `${gap.reason}, so sync writes nothing for it there and the server is unavailable in those tools`,
+                fix: 'nothing is needed if the server is not wanted in those tools; otherwise declare it with credentials the tool can carry (an environment reference in headers rather than a headersHelper for OpenCode), or remove those tools from [surfaces] tools, then run npx --no cockpit sync --config <your cockpit.toml>',
+            })),
+            // Real sync and check refuse a changed original; a preview reports it so it can be reviewed.
+            ...prepared.changedOverrideOriginals.map(finding => overrideChanged(finding, 'warning')),
+        ],
+        status: 0,
+        result: {
+            action,
+            dryRun,
+            changes,
+            generation: prepared.generation,
+            sourceSha256: prepared.sourceSha256,
+            paths: [...prepared.owned.map(({ path }) => path), ...prepared.surfaces.map(({ path }) => path)].sort(compareCodeUnits),
+            application,
+            ...(staleRemoval ? { staleRemoval } : {}),
+        },
+    };
+}
+export function generatedPathFacts(prepared, applicability) {
+    const manifest = encodeOwnershipManifest(prepared).manifest;
+    const declarations = [
+        ...prepared.generated.map(file => ({ producer: 'generated-environment', applicability,
+            entry: manifest.entries.find(entry => entry.path === file.path) })),
+        ...prepared.surfaces.map(file => ({ producer: 'surface-render', applicability,
+            entry: manifest.entries.find(entry => entry.path === file.path) })),
+    ];
+    return projectGeneratedPathFacts(manifest, { root: prepared.root, cockpitId: prepared.cockpitId, configPath: prepared.configPath }, declarations);
+}
+function isGeneratedApplicationSurfaceObservation(value) {
+    return value !== null && typeof value === 'object' && issuedSurfaceObservations.has(value);
+}
+function generatedApplicationSurfaceObservationIssuedAt(value) {
+    return value !== null && typeof value === 'object' ? issuedSurfaceObservations.get(value) : undefined;
+}
+export function confined(root, path) {
+    if (typeof path !== 'string' || path.length === 0 || path.includes('\0') || isAbsolute(path))
+        return undefined;
+    const target = resolve(root, path);
+    const offset = relative(root, target);
+    return offset !== '' && offset !== '..' && !offset.startsWith(`..${sep}`) && !isAbsolute(offset) ? target : undefined;
+}
+export function sourceIdentity(identity) {
+    return JSON.stringify({ root: identity.root, chain: identity.chain, file: identity.file });
+}
+export function readSurfaceAsset(path, read) {
+    if (read.kind !== 'complete')
+        return undefined;
+    try {
+        return { path, bytes: new TextDecoder('utf-8', { fatal: true }).decode(read.bytes),
+            sha256: read.sha256, identity: read.identity };
+    }
+    catch { /* undecodable bytes are malformed input the caller refuses. */
+        return undefined;
+    }
+}
+export function mergedAdapters(overrides) {
+    return { ...defaultAdapters, ...overrides };
+}

package/dist/environment/generated-application/surface-observation.d.ts

@@ -0,0 +1,4 @@
+import { type EnvironmentObservation } from '../contract.js';
+import { type GeneratedApplicationProjection } from './shared.js';
+export declare const SURFACE_OBSERVATION_CODES: readonly string[];
+export declare function observeGeneratedApplicationSurfaces(application: GeneratedApplicationProjection): readonly EnvironmentObservation[] | undefined;

package/dist/environment/generated-application/surface-observation.js

@@ -0,0 +1,69 @@
+import { surfaceModelSha256 } from '../../surfaces/render.js';
+import { ENVIRONMENT_CODES, snapshotEnvironmentObservation } from '../contract.js';
+import { stackId } from '../identity.js';
+import { OWNER, issuedApplicationProjections, issuedSurfaceObservations } from './shared.js';
+// The rows only this observation answers; when it cannot be made they report missing evidence.
+export const SURFACE_OBSERVATION_CODES = [ENVIRONMENT_CODES.HARNESS_SURFACE_UNAVAILABLE,
+    ENVIRONMENT_CODES.DIRECTORY_GRANTS_UNAVAILABLE, ENVIRONMENT_CODES.GUIDE_CAP_EXCEEDED, ENVIRONMENT_CODES.SKILL_BUDGET_UNAVAILABLE];
+export function observeGeneratedApplicationSurfaces(application) {
+    const record = application !== null && typeof application === 'object'
+        ? issuedApplicationProjections.get(application)
+        : undefined;
+    if (!record?.currentPublication || record.surfaceSelftest !== application.surfaceSelftest)
+        return undefined;
+    const grantsSha256 = surfaceModelSha256(record.surfaceHealth.grants);
+    const availableGuideCosts = record.surfaceHealth.guideCosts.filter((cost) => cost.status !== 'unavailable');
+    if (!grantsSha256 || grantsSha256 !== record.surfaceHealth.nativeGrants.modelSha256
+        || availableGuideCosts.length !== record.surfaceHealth.guideCosts.length
+        || availableGuideCosts.some(cost => cost.status !== 'within_cap'))
+        return undefined;
+    const guideValue = availableGuideCosts.reduce((maximum, cost) => Math.max(maximum, cost.value), 0);
+    const guideCap = availableGuideCosts[0]?.cap;
+    if (guideCap === undefined || availableGuideCosts.some(cost => cost.cap !== guideCap))
+        return undefined;
+    const observedAt = record.surfaceHealth.observedAt;
+    const required = (posture) => ({ state: 'required', posture });
+    const observations = [
+        snapshotEnvironmentObservation({
+            code: ENVIRONMENT_CODES.HARNESS_SURFACE_UNAVAILABLE, owner: OWNER, stackId: record.stackId,
+            source: `surface-manifest:${record.surfaceSelftest.manifestSha256}`,
+            observed: { state: 'available', value: { manifestSha256: record.surfaceSelftest.manifestSha256,
+                    harnesses: record.surfaceSelftest.configuredHarnesses, entries: record.surfaceSelftest.entries.length }, observedAt },
+            expectation: { kind: 'present' }, applicability: required('environment'), freshness: { state: 'current' },
+            remedy: 'run npx --no cockpit sync --config <your cockpit.toml>, then rerun npx --no cockpit preflight --config <your cockpit.toml>',
+        }),
+        snapshotEnvironmentObservation({
+            code: ENVIRONMENT_CODES.DIRECTORY_GRANTS_UNAVAILABLE, owner: OWNER, stackId: record.stackId,
+            source: `directory-grants:${grantsSha256}`,
+            observed: { state: 'available', value: { grants: record.surfaceHealth.grants.length,
+                    generatedFragments: record.surfaceHealth.nativeGrants.fragments.length, modelSha256: grantsSha256 }, observedAt },
+            expectation: { kind: 'present' }, applicability: record.surfaceHealth.grants.length > 0
+                ? required('directory-grants')
+                : { state: 'not-applicable', posture: 'directory-grants', reason: 'the active sibling projection declares no directory grants' },
+            freshness: { state: 'current' },
+            remedy: 'run npx --no cockpit sync --config <your cockpit.toml>, then rerun npx --no cockpit preflight --config <your cockpit.toml>',
+        }),
+        snapshotEnvironmentObservation({
+            code: ENVIRONMENT_CODES.GUIDE_CAP_EXCEEDED, owner: OWNER, stackId: record.stackId,
+            source: `surface-guide-costs:${record.surfaceSelftest.manifestSha256}`,
+            observed: { state: 'available', value: guideValue, observedAt }, expectation: { kind: 'maximum', value: guideCap },
+            applicability: required('environment'), freshness: { state: 'current' },
+            remedy: 'move conditional guidance behind its scoped or pull-loaded surface, then run npx --no cockpit sync --config <your cockpit.toml>',
+        }),
+        snapshotEnvironmentObservation({
+            code: ENVIRONMENT_CODES.SKILL_BUDGET_UNAVAILABLE, owner: OWNER, stackId: record.stackId,
+            source: `installed-skill-inventory:${record.surfaceHealth.skillInventorySha256}`,
+            observed: { state: 'available', value: { coreCollectionSha256: record.surfaceHealth.skillCollectionSha256,
+                    inventorySha256: record.surfaceHealth.skillInventorySha256, inventory: record.surfaceHealth.skillInventory, skills: record.surfaceHealth.skills,
+                    costs: record.surfaceHealth.skillCosts.map(({ target, metric, value, cap }) => ({ target, metric, value, cap })) }, observedAt },
+            expectation: { kind: 'present' }, applicability: required('environment'), freshness: { state: 'current' },
+            remedy: 'move skill procedure text out of always-loaded entry points, then run npx --no cockpit sync --config <your cockpit.toml>',
+        }),
+    ];
+    if (!observations.every((observation) => observation !== undefined))
+        return undefined;
+    const issuedAt = Date.now();
+    for (const observation of observations)
+        issuedSurfaceObservations.set(observation, issuedAt);
+    return observations;
+}

package/dist/environment/generated-application/surface-outputs.d.ts

@@ -0,0 +1,71 @@
+import { type SurfaceFeature, type SurfaceSourceFile, type SurfaceTarget } from '../../surfaces/contract.js';
+import { type SurfaceGenerationOutcome } from '../../surfaces/generator-adapter.js';
+import { type McpCollectionOutcome } from '../../surfaces/mcp.js';
+import { type NativeFragmentSet } from '../../surfaces/render.js';
+export declare function expectedSurfaceOutputs(tools: readonly SurfaceTarget[], features: readonly SurfaceFeature[], sources: readonly SurfaceSourceFile[]): Readonly<Partial<Record<SurfaceTarget, readonly string[]>>>;
+export declare function expectedClaudePluginOutputs(features: readonly SurfaceFeature[], sources: readonly SurfaceSourceFile[]): readonly string[];
+export declare function claudePluginManifest(): Readonly<{
+    bytes: string;
+    sha256: string;
+}>;
+export declare function alwaysLoadedRule(bytes: string): Readonly<{
+    kind: 'complete';
+    bytes: string;
+}> | Readonly<{
+    kind: 'refusal';
+    reason: string;
+}>;
+export declare function emptyGeneration(): Extract<SurfaceGenerationOutcome, {
+    kind: 'complete';
+}>;
+/**
+ * OpenCode's native read tool asks its `read` permission with the file path relative to the Git
+ * worktree, and its `*` matches across `/`, so each protected path is denied both as written and
+ * below any prefix: that covers a cockpit root nested in a larger repository and siblings reached
+ * through `../`. Only `*` and `?` are pattern characters there; either one in a path becomes `?`,
+ * which over-matches a deny and so stays safe. The plugin's guard routing refuses the same reads,
+ * case-folded; these rules still deny the declared spellings when the plugin cannot load.
+ */
+export declare function openCodeReadDenials(siblings: readonly {
+    slug: string;
+    path: string;
+}[], instances: readonly {
+    slug: string;
+    path: string;
+}[]): readonly string[];
+/** The machine-local file `sync` writes with a sibling's absolute directory, for OpenCode to read. */
+export declare function openCodeGrantFile(slug: string): string;
+export declare const GUIDE_LOAD_CHARACTERIZATIONS: Readonly<{
+    [k: string]: {
+        measuredOn: string;
+        metric: 'lines';
+        scopeSemantics: "conditional" | "full";
+        provenance: string;
+    };
+}>;
+export declare function nativeSources(mcp: Extract<McpCollectionOutcome, {
+    kind: 'complete';
+}>, grants: readonly {
+    slug: string;
+    target: SurfaceTarget;
+    path: string;
+}[], siblings: readonly {
+    slug: string;
+    path: string;
+}[], instances: readonly {
+    slug: string;
+    path: string;
+}[]): readonly SurfaceSourceFile[];
+export declare function nativeFragmentSet(generated: Extract<SurfaceGenerationOutcome, {
+    kind: 'complete';
+}>, model: unknown, paths: Readonly<Partial<Record<SurfaceTarget, string>>>): NativeFragmentSet | undefined;
+export declare function nativeGrantFragmentSet(generated: Extract<SurfaceGenerationOutcome, {
+    kind: 'complete';
+}>, grants: readonly Readonly<{
+    slug: string;
+    target: SurfaceTarget;
+    path: string;
+}>[], paths: Readonly<Partial<Record<SurfaceTarget, string>>>, openCodeReads: readonly string[]): NativeFragmentSet | undefined;
+export declare function bindNativeGrantsToMcp(mcp: NativeFragmentSet, grants: NativeFragmentSet): NativeFragmentSet | undefined;
+export declare function nativeMcpPaths(targets: readonly SurfaceTarget[]): Readonly<Partial<Record<SurfaceTarget, string>>>;
+export declare function nativeGrantPaths(targets: readonly SurfaceTarget[]): Readonly<Partial<Record<SurfaceTarget, string>>>;