@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/surfaces/projection.js

@@ -0,0 +1,681 @@
+import { createHash } from 'node:crypto';
+import { lstat, open, readlink, realpath } from 'node:fs/promises';
+import { isAbsolute, join, posix, relative, resolve } from 'node:path';
+import { errorCause, snapshotJson, RefusalError, hasErrorCode } from '../environment/contract.js';
+import { SURFACE_TARGETS } from './contract.js';
+import { GUARD_SURFACE_TARGETS as INSTRUCTION_TARGETS, HARNESS_REGISTRY } from './harness-registry.js';
+import { INSTRUCTION_POINTER_MARKERS } from '../environment/instruction-pointer.js';
+import { exactKeys } from '../exact-keys.js';
+const GUIDE_BYTE_LIMIT = 65_536;
+const GUIDE_COUNT_LIMIT = 256;
+const OBSERVATION_CONTENT_BYTE_LIMIT = 786_432;
+const PROJECTION_RESULT_ENTRY_LIMIT = 1_024;
+const SHA256 = /^[a-f0-9]{64}$/;
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+function isObject(value) {
+    return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function capturedValue(value) {
+    const captured = snapshotJson(value);
+    return captured === undefined ? undefined : captured;
+}
+const RESULT_BOUNDS_DIAGNOSTIC = Object.freeze({
+    code: 'PROJECTION_RESULT_BOUNDS',
+    message: 'sibling projection result exceeds the immutable snapshot bound',
+});
+const OBSERVATION_RESULT_BOUNDS = Object.freeze({
+    kind: 'refusal',
+    diagnostic: RESULT_BOUNDS_DIAGNOSTIC,
+});
+const PLANNER_RESULT_BOUNDS = Object.freeze({
+    kind: 'refusal',
+    diagnostic: RESULT_BOUNDS_DIAGNOSTIC,
+});
+function diagnostic(code, message, details = {}) {
+    return capturedValue({ code, message, ...details }) ?? RESULT_BOUNDS_DIAGNOSTIC;
+}
+function refuse(value) {
+    return capturedValue({ kind: 'refusal', diagnostic: value }) ?? PLANNER_RESULT_BOUNDS;
+}
+function observedOutcome(value) {
+    return capturedValue(value) ?? OBSERVATION_RESULT_BOUNDS;
+}
+function safeGuidePath(path) {
+    if (path.length === 0 || path.length > 4096 || path.startsWith('/') || /^[a-z]:[/\\]/i.test(path)
+        || path.includes('\\') || /[\x00-\x1f\x7f]/.test(path))
+        return false;
+    return path.split('/').every(segment => segment.length > 0 && segment !== '.' && segment !== '..');
+}
+function contained(root, path) {
+    const fromRoot = relative(root, path);
+    return fromRoot === '' || !fromRoot.startsWith('..') && !isAbsolute(fromRoot);
+}
+function snapshotRequests(input) {
+    const snapshot = snapshotJson(input);
+    if (!isObject(snapshot) || !exactKeys(snapshot, ['allowedRoots', 'requests']) || !Array.isArray(snapshot.requests)
+        || snapshot.requests.length > GUIDE_COUNT_LIMIT)
+        return undefined;
+    const allowedRoots = stringArray(snapshot.allowedRoots);
+    if (!allowedRoots || allowedRoots.length === 0 || allowedRoots.length > GUIDE_COUNT_LIMIT
+        || new Set(allowedRoots).size !== allowedRoots.length || allowedRoots.some(root => !isAbsolute(root)))
+        return undefined;
+    const result = [];
+    const identities = new Set();
+    for (const request of snapshot.requests) {
+        if (!isObject(request) || !exactKeys(request, ['slug', 'root', 'sourcePath'])
+            || typeof request.slug !== 'string' || !SLUG.test(request.slug)
+            || typeof request.root !== 'string' || !isAbsolute(request.root)
+            || typeof request.sourcePath !== 'string' || !isAbsolute(request.sourcePath))
+            return undefined;
+        const sourcePath = request.sourcePath;
+        if (!allowedRoots.includes(request.root) || !contained(request.root, sourcePath))
+            return undefined;
+        const identity = `${request.slug}\0${sourcePath}`;
+        if (identities.has(identity))
+            return undefined;
+        identities.add(identity);
+        result.push({ slug: request.slug, root: request.root, sourcePath });
+    }
+    return { requests: result, allowedRoots };
+}
+function statIdentity(stat) {
+    return `${stat.dev}:${stat.ino}:${stat.mode}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+}
+function inodeIdentity(stat) {
+    return `${stat.dev}:${stat.ino}`;
+}
+function declaredRootIdentity(entry, linkTarget) {
+    return entry.isSymbolicLink() ? `${statIdentity(entry)}:${linkTarget ?? ''}` : inodeIdentity(entry);
+}
+async function rootEntryIdentity(path) {
+    const entry = await lstat(path, { bigint: true });
+    if (!entry.isDirectory() && !entry.isSymbolicLink())
+        throw new RefusalError('sibling root is not a directory or symlink');
+    const linkTarget = entry.isSymbolicLink() ? await readlink(path) : undefined;
+    return { entry, identity: declaredRootIdentity(entry, linkTarget) };
+}
+async function captureRootAuthority(declared) {
+    let handle;
+    let failure;
+    try {
+        const before = await rootEntryIdentity(declared);
+        handle = await open(declared, 'r');
+        const directory = await handle.stat({ bigint: true });
+        const canonical = await realpath(declared);
+        const direct = await lstat(canonical, { bigint: true });
+        const after = await rootEntryIdentity(declared);
+        if (!directory.isDirectory() || !direct.isDirectory() || before.identity !== after.identity
+            || inodeIdentity(directory) !== inodeIdentity(direct)
+            || !before.entry.isSymbolicLink() && inodeIdentity(before.entry) !== inodeIdentity(directory)) {
+            failure = diagnostic('PROJECTION_GUIDE_CHANGED', `declared sibling root changed while its authority was captured: ${declared}`, { target: declared });
+        }
+        else {
+            return {
+                declared,
+                canonical,
+                declaredIdentity: before.identity,
+                directoryIdentity: inodeIdentity(directory),
+                handle,
+            };
+        }
+    }
+    catch (error) {
+        failure = diagnostic('PROJECTION_GUIDE_UNAVAILABLE', `declared sibling root could not be observed: ${declared}: ${errorCause(error)}`, { target: declared });
+    }
+    try {
+        await handle?.close();
+    }
+    catch (error) {
+        return diagnostic('PROJECTION_GUIDE_CLOSE_FAILED', `sibling root authority descriptor close failed: ${declared}: ${errorCause(error)}`, { target: declared });
+    }
+    return failure ?? diagnostic('PROJECTION_GUIDE_UNAVAILABLE', `declared sibling root observation produced no result: ${declared}`, { target: declared });
+}
+async function rootAuthorityStable(root) {
+    try {
+        const directory = await root.handle.stat({ bigint: true });
+        const declared = await rootEntryIdentity(root.declared);
+        const canonical = await realpath(root.declared);
+        const direct = await lstat(canonical, { bigint: true });
+        return directory.isDirectory() && direct.isDirectory()
+            && root.declaredIdentity === declared.identity && root.canonical === canonical
+            && root.directoryIdentity === inodeIdentity(directory) && root.directoryIdentity === inodeIdentity(direct);
+    }
+    catch {
+        // an unobservable root is no longer stable; the caller reports the change.
+        return false;
+    }
+}
+async function finishRootObservation(roots, outcome) {
+    let closeFailure;
+    for (const root of roots) {
+        try {
+            await root.handle.close();
+        }
+        catch (error) {
+            closeFailure ??= diagnostic('PROJECTION_GUIDE_CLOSE_FAILED', `sibling root authority descriptor close failed: ${root.declared}: ${errorCause(error)}`, { target: root.declared });
+        }
+    }
+    return closeFailure ? observedOutcome({ kind: 'refusal', diagnostic: closeFailure }) : outcome;
+}
+async function pathIdentity(sourcePath) {
+    const entry = await lstat(sourcePath, { bigint: true });
+    if (!entry.isFile() && !entry.isSymbolicLink())
+        throw new RefusalError('guide entry type is unsupported');
+    const entryType = entry.isSymbolicLink() ? 'symlink' : 'file';
+    const linkTarget = entryType === 'symlink' ? await readlink(sourcePath) : undefined;
+    const contentPath = await realpath(sourcePath);
+    const target = await lstat(contentPath, { bigint: true });
+    return { entry, entryType, ...(linkTarget === undefined ? {} : { linkTarget }), contentPath, target };
+}
+async function readGuide(request, requestRoot) {
+    if (!await rootAuthorityStable(requestRoot)) {
+        return diagnostic('PROJECTION_GUIDE_CHANGED', `declared sibling root changed before guide observation: ${request.root}`, { target: request.root });
+    }
+    let pathBefore;
+    try {
+        pathBefore = await pathIdentity(request.sourcePath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return 'missing';
+        return diagnostic('PROJECTION_GUIDE_UNAVAILABLE', `guide entry could not be observed: ${request.sourcePath}`, { target: request.sourcePath });
+    }
+    if (!await rootAuthorityStable(requestRoot)) {
+        return diagnostic('PROJECTION_GUIDE_CHANGED', `declared sibling root changed during guide entry observation: ${request.root}`, { target: request.root });
+    }
+    if (!contained(requestRoot.canonical, pathBefore.contentPath)) {
+        return diagnostic('PROJECTION_GUIDE_ESCAPE', `guide resolves outside its declared sibling root: ${request.sourcePath}`, {
+            target: request.sourcePath, expected: requestRoot.canonical, actual: pathBefore.contentPath,
+        });
+    }
+    let handle;
+    let result;
+    try {
+        handle = await open(request.sourcePath, 'r');
+    }
+    catch (error) {
+        if (!await rootAuthorityStable(requestRoot)) {
+            return diagnostic('PROJECTION_GUIDE_CHANGED', `declared sibling root changed before guide open: ${request.root}`, { target: request.root });
+        }
+        return diagnostic('PROJECTION_GUIDE_UNAVAILABLE', `guide content could not be opened: ${request.sourcePath}: ${errorCause(error)}`, { target: request.sourcePath });
+    }
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!await rootAuthorityStable(requestRoot)) {
+            result = diagnostic('PROJECTION_GUIDE_CHANGED', `declared sibling root changed during guide open: ${request.root}`, { target: request.root });
+        }
+        else if (!before.isFile() || before.size > BigInt(GUIDE_BYTE_LIMIT)
+            || inodeIdentity(before) !== inodeIdentity(pathBefore.target)) {
+            result = diagnostic('PROJECTION_GUIDE_CHANGED', `guide changed before its bounded read: ${request.sourcePath}`, { target: request.sourcePath });
+        }
+        else {
+            const buffer = Buffer.alloc(Number(before.size) + 1);
+            let offset = 0;
+            let rootChanged = false;
+            while (offset < buffer.byteLength) {
+                if (!await rootAuthorityStable(requestRoot)) {
+                    rootChanged = true;
+                    break;
+                }
+                const read = await handle.read(buffer, offset, buffer.byteLength - offset, offset);
+                if (!await rootAuthorityStable(requestRoot)) {
+                    rootChanged = true;
+                    break;
+                }
+                if (read.bytesRead === 0)
+                    break;
+                offset += read.bytesRead;
+            }
+            const after = await handle.stat({ bigint: true });
+            let pathAfter;
+            try {
+                if (!await rootAuthorityStable(requestRoot))
+                    rootChanged = true;
+                pathAfter = await pathIdentity(request.sourcePath);
+                if (!await rootAuthorityStable(requestRoot))
+                    rootChanged = true;
+            }
+            catch {
+                // A pathname that disappears or becomes unreadable during the read is an identity change.
+            }
+            if (rootChanged) {
+                result = diagnostic('PROJECTION_GUIDE_CHANGED', `declared sibling root changed during guide read: ${request.root}`, { target: request.root });
+            }
+            else if (offset > GUIDE_BYTE_LIMIT || statIdentity(before) !== statIdentity(after) || !pathAfter
+                || statIdentity(pathBefore.entry) !== statIdentity(pathAfter.entry)
+                || pathBefore.entryType !== pathAfter.entryType || pathBefore.linkTarget !== pathAfter.linkTarget
+                || pathBefore.contentPath !== pathAfter.contentPath
+                || statIdentity(pathBefore.target) !== statIdentity(pathAfter.target)
+                || inodeIdentity(after) !== inodeIdentity(pathAfter.target)) {
+                result = diagnostic('PROJECTION_GUIDE_CHANGED', `guide changed during its bounded read: ${request.sourcePath}`, { target: request.sourcePath });
+            }
+            else if (!contained(requestRoot.canonical, pathAfter.contentPath)) {
+                result = diagnostic('PROJECTION_GUIDE_ESCAPE', `guide resolves outside its declared sibling root: ${request.sourcePath}`, {
+                    target: request.sourcePath, expected: requestRoot.canonical, actual: pathAfter.contentPath,
+                });
+            }
+            else {
+                let content;
+                try {
+                    content = new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, offset));
+                }
+                catch {
+                    // undecodable bytes are malformed input the caller refuses.
+                    result = diagnostic('PROJECTION_GUIDE_UNAVAILABLE', `guide is not valid UTF-8: ${request.sourcePath}`, { target: request.sourcePath });
+                }
+                if (content !== undefined) {
+                    result = capturedValue({
+                        slug: request.slug,
+                        sourcePath: request.sourcePath,
+                        sourceEntryType: pathAfter.entryType,
+                        ...(pathAfter.linkTarget === undefined ? {} : { sourceLinkTarget: pathAfter.linkTarget }),
+                        contentPath: pathAfter.contentPath,
+                        content,
+                        contentBytes: offset,
+                        contentSha256: createHash('sha256').update(buffer.subarray(0, offset)).digest('hex'),
+                        contentIdentity: statIdentity(after),
+                    }) ?? RESULT_BOUNDS_DIAGNOSTIC;
+                }
+            }
+        }
+    }
+    catch (error) {
+        result = diagnostic('PROJECTION_GUIDE_READ_FAILED', `guide descriptor read failed: ${request.sourcePath}: ${errorCause(error)}`, { target: request.sourcePath });
+    }
+    try {
+        await handle.close();
+    }
+    catch (error) {
+        return diagnostic('PROJECTION_GUIDE_CLOSE_FAILED', `guide descriptor close failed: ${request.sourcePath}: ${errorCause(error)}`, { target: request.sourcePath });
+    }
+    return result ?? diagnostic('PROJECTION_GUIDE_READ_FAILED', `guide descriptor read produced no bounded result: ${request.sourcePath}`, { target: request.sourcePath });
+}
+export async function observeSiblingGuides(input) {
+    const captured = snapshotRequests(input);
+    if (!captured)
+        return observedOutcome({ kind: 'refusal', diagnostic: diagnostic('PROJECTION_INPUT_INVALID', 'guide observation input is invalid') });
+    const allowedRoots = [];
+    for (const declared of captured.allowedRoots) {
+        const root = await captureRootAuthority(declared);
+        if ('code' in root) {
+            const kind = root.code === 'PROJECTION_GUIDE_CHANGED' || root.code === 'PROJECTION_GUIDE_CLOSE_FAILED' ? 'refusal' : 'unavailable';
+            return finishRootObservation(allowedRoots, observedOutcome({ kind, diagnostic: root }));
+        }
+        allowedRoots.push(root);
+    }
+    if (new Set(allowedRoots.map(root => root.canonical)).size !== allowedRoots.length) {
+        return finishRootObservation(allowedRoots, observedOutcome({ kind: 'refusal', diagnostic: diagnostic('PROJECTION_ROOT_AMBIGUOUS', 'declared sibling roots resolve to the same canonical authority') }));
+    }
+    const observations = [];
+    const missing = [];
+    let contentBytes = 0;
+    for (const request of captured.requests) {
+        const mostSpecificRoot = allowedRoots.filter(root => contained(root.declared, request.sourcePath))
+            .sort((left, right) => {
+            const leftDepth = relative(left.declared, request.sourcePath).split(/[\\/]/).length;
+            const rightDepth = relative(right.declared, request.sourcePath).split(/[\\/]/).length;
+            return leftDepth - rightDepth || left.declared.localeCompare(right.declared);
+        })[0];
+        if (!mostSpecificRoot || request.root !== mostSpecificRoot.declared) {
+            return finishRootObservation(allowedRoots, observedOutcome({ kind: 'refusal', diagnostic: diagnostic('PROJECTION_INPUT_INVALID', `guide request is not bound to its most-specific sibling root: ${request.sourcePath}`, { target: request.sourcePath }) }));
+        }
+        const requestRoot = allowedRoots.find(root => root.declared === request.root);
+        const observed = await readGuide(request, requestRoot);
+        if (observed === 'missing')
+            missing.push(request.sourcePath);
+        else if ('code' in observed) {
+            const refusal = ['PROJECTION_GUIDE_CHANGED', 'PROJECTION_GUIDE_ESCAPE', 'PROJECTION_GUIDE_READ_FAILED',
+                'PROJECTION_GUIDE_CLOSE_FAILED', 'PROJECTION_RESULT_BOUNDS'].includes(observed.code);
+            return finishRootObservation(allowedRoots, observedOutcome({ kind: refusal ? 'refusal' : 'unavailable', diagnostic: observed }));
+        }
+        else {
+            contentBytes += observed.contentBytes;
+            if (contentBytes > OBSERVATION_CONTENT_BYTE_LIMIT)
+                return finishRootObservation(allowedRoots, OBSERVATION_RESULT_BOUNDS);
+            observations.push(observed);
+        }
+    }
+    return finishRootObservation(allowedRoots, observedOutcome({ kind: 'complete', observations, missing }));
+}
+function target(value) {
+    return typeof value === 'string' && SURFACE_TARGETS.includes(value);
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every(item => typeof item === 'string') ? value : undefined;
+}
+function capturePlannerInput(input) {
+    const value = snapshotJson(input);
+    if (!isObject(value) || !exactKeys(value, [
+        'canonicalMainCheckout', 'siblingsRoot', 'activeProfiles', 'guideCapLines', 'siblings',
+        'mountedPaths', 'directoryGrants', 'guideObservations', 'standingSources', 'loadCharacterizations',
+    ], ['invocationCwd', 'targets'])
+        || typeof value.canonicalMainCheckout !== 'string' || !isAbsolute(value.canonicalMainCheckout)
+        || typeof value.siblingsRoot !== 'string' || value.siblingsRoot.length === 0
+        || typeof value.guideCapLines !== 'number' || !Number.isSafeInteger(value.guideCapLines) || value.guideCapLines <= 0
+        || !Array.isArray(value.siblings) || value.siblings.length > GUIDE_COUNT_LIMIT
+        || !Array.isArray(value.mountedPaths) || value.mountedPaths.length > GUIDE_COUNT_LIMIT
+        || !Array.isArray(value.directoryGrants) || !Array.isArray(value.guideObservations)
+        || !Array.isArray(value.standingSources) || !isObject(value.loadCharacterizations)
+        || value.directoryGrants.length > GUIDE_COUNT_LIMIT * SURFACE_TARGETS.length
+        || value.guideObservations.length > GUIDE_COUNT_LIMIT || value.standingSources.length > GUIDE_COUNT_LIMIT * SURFACE_TARGETS.length)
+        return undefined;
+    const targets = value.targets === undefined ? SURFACE_TARGETS : stringArray(value.targets);
+    if (!targets || targets.length === 0 || new Set(targets).size !== targets.length || !targets.every(item => target(item)))
+        return undefined;
+    const activeProfiles = stringArray(value.activeProfiles);
+    if (!activeProfiles || new Set(activeProfiles).size !== activeProfiles.length
+        || activeProfiles.some(profile => !/^[a-z0-9][a-z0-9.-]*$/.test(profile)))
+        return undefined;
+    const siblings = [];
+    const siblingSlugs = new Set();
+    for (const row of value.siblings) {
+        if (!isObject(row) || !exactKeys(row, ['slug', 'mount', 'directoryAuthority'], ['declaredOverride', 'guides'])
+            || typeof row.slug !== 'string' || !SLUG.test(row.slug) || siblingSlugs.has(row.slug)
+            || typeof row.mount !== 'string' || !/^(?:always|host|none|profile:[a-z0-9][a-z0-9-]*)$/.test(row.mount)
+            || typeof row.directoryAuthority !== 'string' || row.directoryAuthority.length === 0
+            || row.declaredOverride !== undefined && (typeof row.declaredOverride !== 'string' || !isAbsolute(row.declaredOverride)))
+            return undefined;
+        const guides = row.guides === undefined ? ['CLAUDE.md', 'AGENTS.md'] : stringArray(row.guides);
+        if (!guides || guides.length > GUIDE_COUNT_LIMIT || new Set(guides).size !== guides.length || guides.some(guide => !safeGuidePath(guide)))
+            return undefined;
+        siblingSlugs.add(row.slug);
+        siblings.push({
+            slug: row.slug,
+            mount: row.mount,
+            directoryAuthority: row.directoryAuthority,
+            ...(row.declaredOverride === undefined ? {} : { declaredOverride: row.declaredOverride }),
+            guides: [...guides],
+        });
+    }
+    const mountedPaths = [];
+    const mountIds = new Set();
+    for (const row of value.mountedPaths) {
+        if (!isObject(row) || !exactKeys(row, ['slug', 'path']) || typeof row.slug !== 'string' || !SLUG.test(row.slug)
+            || mountIds.has(row.slug) || typeof row.path !== 'string' || !isAbsolute(row.path))
+            return undefined;
+        mountIds.add(row.slug);
+        mountedPaths.push({ slug: row.slug, path: row.path });
+    }
+    const directoryGrants = [];
+    const grantIds = new Set();
+    for (const row of value.directoryGrants) {
+        if (!isObject(row) || !exactKeys(row, ['slug', 'target', 'path']) || typeof row.slug !== 'string' || !SLUG.test(row.slug)
+            || !target(row.target) || typeof row.path !== 'string' || !isAbsolute(row.path))
+            return undefined;
+        const id = `${row.slug}\0${row.target}`;
+        if (grantIds.has(id))
+            return undefined;
+        grantIds.add(id);
+        directoryGrants.push({ slug: row.slug, target: row.target, path: row.path });
+    }
+    const guideObservations = [];
+    const observationIds = new Set();
+    for (const row of value.guideObservations) {
+        if (!isObject(row) || !exactKeys(row, ['slug', 'sourcePath', 'sourceEntryType', 'contentPath', 'content', 'contentBytes', 'contentSha256', 'contentIdentity'], ['sourceLinkTarget'])
+            || typeof row.slug !== 'string' || !SLUG.test(row.slug) || typeof row.sourcePath !== 'string' || !isAbsolute(row.sourcePath)
+            || typeof row.contentPath !== 'string' || !isAbsolute(row.contentPath)
+            || row.sourceEntryType !== 'file' && row.sourceEntryType !== 'symlink'
+            || row.sourceLinkTarget !== undefined && typeof row.sourceLinkTarget !== 'string'
+            || typeof row.content !== 'string' || typeof row.contentBytes !== 'number' || !Number.isSafeInteger(row.contentBytes)
+            || Buffer.byteLength(row.content) !== row.contentBytes || row.contentBytes > GUIDE_BYTE_LIMIT
+            || typeof row.contentSha256 !== 'string' || !SHA256.test(row.contentSha256)
+            || createHash('sha256').update(row.content).digest('hex') !== row.contentSha256
+            || typeof row.contentIdentity !== 'string' || row.contentIdentity.length === 0
+            || observationIds.has(`${row.slug}\0${row.sourcePath}`))
+            return undefined;
+        observationIds.add(`${row.slug}\0${row.sourcePath}`);
+        guideObservations.push(row);
+    }
+    const standingSources = [];
+    const standingIds = new Set();
+    for (const row of value.standingSources) {
+        if (!isObject(row) || !exactKeys(row, ['target', 'path', 'content', 'scope']) || !target(row.target)
+            || typeof row.path !== 'string' || !safeGuidePath(row.path) || typeof row.content !== 'string'
+            || row.scope !== 'always' && row.scope !== 'scoped' || standingIds.has(`${row.target}\0${row.path}`))
+            return undefined;
+        standingIds.add(`${row.target}\0${row.path}`);
+        standingSources.push(row);
+    }
+    const loadCharacterizations = {};
+    if (Object.keys(value.loadCharacterizations).some(key => !INSTRUCTION_TARGETS.includes(key)))
+        return undefined;
+    for (const harness of INSTRUCTION_TARGETS) {
+        const row = value.loadCharacterizations[harness];
+        if (row === undefined || row === null)
+            continue;
+        if (!isObject(row) || !exactKeys(row, ['measuredOn', 'provenance', 'metric', 'scopeSemantics'])
+            || typeof row.measuredOn !== 'string' || !DATE.test(row.measuredOn)
+            || typeof row.provenance !== 'string' || row.provenance.length === 0
+            || row.metric !== 'lines' || row.scopeSemantics !== 'conditional' && row.scopeSemantics !== 'full')
+            return undefined;
+        loadCharacterizations[harness] = row;
+    }
+    return {
+        canonicalMainCheckout: value.canonicalMainCheckout,
+        siblingsRoot: value.siblingsRoot,
+        activeProfiles,
+        guideCapLines: value.guideCapLines,
+        siblings,
+        mountedPaths,
+        directoryGrants,
+        guideObservations,
+        standingSources,
+        loadCharacterizations,
+        targets: SURFACE_TARGETS.filter(item => targets.includes(item)),
+    };
+}
+function selected(row, profiles) {
+    return row.mount === 'always' || row.mount.startsWith('profile:') && profiles.has(row.mount.slice(8));
+}
+function siblingDirectory(input, row) {
+    if (row.declaredOverride !== undefined)
+        return resolve(row.declaredOverride);
+    if (isAbsolute(row.directoryAuthority))
+        return resolve(row.directoryAuthority);
+    return resolve(input.canonicalMainCheckout, input.siblingsRoot, row.directoryAuthority);
+}
+// The region and owner markers ownership parses in the root AGENTS.md.
+const REGION_MARKER_PREFIXES = ['<!-- cockpit:instructions:', '<!-- cockpit:owner:'];
+const POINTER_BLOCK = new RegExp(`${INSTRUCTION_POINTER_MARKERS.begin}[\\s\\S]*?${INSTRUCTION_POINTER_MARKERS.end}\\n?`, 'g');
+const AGENTS_IMPORT_LINE = /^[ \t]*@(?:\.\/)?AGENTS\.md[ \t]*$/gm;
+/**
+ * The text of a guide as the root AGENTS.md carries it. The pointer setup appends to a sibling guide
+ * points back at this cockpit, so the copy drops it; a CLAUDE.md line importing the sibling's own
+ * AGENTS.md is dropped when that AGENTS.md is copied too, since in the cockpit root the import would
+ * name the cockpit's AGENTS.md instead. Undefined when the guide holds cockpit's own region or owner
+ * markers, which would end or split the generated region.
+ */
+function guideText(content, dropAgentsImport) {
+    if (REGION_MARKER_PREFIXES.some(marker => content.includes(marker)))
+        return undefined;
+    let text = content.replace(POINTER_BLOCK, '');
+    if (dropAgentsImport)
+        text = text.replace(AGENTS_IMPORT_LINE, '');
+    return text.replace(/^\s*\n/, '').trimEnd();
+}
+/** The marker records which guide, at which digest, the block was copied from, so check can name a stale copy. */
+function siblingGuideMarker(sibling, guide, sha256) {
+    return `<!-- cockpit:sibling-guide sibling=${sibling} guide=${guide} sha256=${sha256} -->`;
+}
+export const SIBLING_GUIDE_MARKER = /<!-- cockpit:sibling-guide sibling=([a-z0-9][a-z0-9-]*) guide=(.+?) sha256=([a-f0-9]{64}) -->/g;
+function guideBlock(sibling, guide, sha256, text) {
+    // Shared Markdown contributions are joined by one newline; the leading one separates the heading.
+    return `\n## Instructions for sibling \`${sibling}\` (its ${guide})\n\n${siblingGuideMarker(sibling, guide, sha256)}\n\n${text}`;
+}
+const GENERATED_ONLY_HARNESSES = HARNESS_REGISTRY.filter((row) => row.native.state === 'generated');
+const INSTRUCTION_CAPABILITIES = Object.freeze([
+    // Each probe ran the tool headless in a cockpit beside two siblings. The declared sibling's guide
+    // gave a word the tool could state only if it had loaded the guide; an undeclared sibling's guide
+    // and a decoy file beside the guide gave words it must not state, the broken controls. Copying the
+    // guide into the root AGENTS.md is the one route every tool loaded; each route that left the guide
+    // in its sibling failed in Claude Code or Codex, so sync writes none.
+    Object.freeze({
+        target: 'claudecode', mechanism: 'root-agents-guide', capability: 'instructed', evidence: 'not_applicable',
+        characterizedOn: '2026-11-03', measuredVersion: '2.1.317',
+        provenance: 'in a workspace Claude Code had not trusted, a sibling guide copied into the root AGENTS.md that CLAUDE.md imports loaded, '
+            + 'with or without Claude Code\'s user option for reading AGENTS.md, while the undeclared sibling\'s guide and the decoy did not; '
+            + 'nothing loaded through a committed CLAUDE.md @-import of a link to the guide or of its relative path, through '
+            + 'permissions.additionalDirectories with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD in the settings env (ignored until a person trusts the workspace), '
+            + 'or through --add-dir with that variable set',
+    }),
+    Object.freeze({
+        target: 'codexcli', mechanism: 'root-agents-guide', capability: 'instructed', evidence: 'not_applicable',
+        characterizedOn: '2026-11-03', measuredVersion: '0.166.0',
+        provenance: 'a sibling guide copied into the root AGENTS.md loaded while the undeclared sibling\'s guide and the decoy did not; '
+            + 'nothing loaded through a line in AGENTS.md telling the agent to read a link to the guide, through --add-dir naming the sibling, '
+            + 'or through project_doc_fallback_filenames naming the link, and Codex dropped the end of a project AGENTS.md past 32 KiB',
+    }),
+    Object.freeze({
+        target: 'opencode', mechanism: 'root-agents-guide', capability: 'instructed', evidence: 'not_applicable',
+        characterizedOn: '2026-11-03', measuredVersion: '1.19.5',
+        provenance: 'a sibling guide copied into the root AGENTS.md loaded, as did a guide named through a link in the opencode.jsonc instructions list, '
+            + 'while the undeclared sibling\'s guide and the decoy did not',
+    }),
+    // Sync writes Cursor no rules file of its own for cockpit's instructions: they reach it only
+    // through the root AGENTS.md, and `.cursor/rules/` holds rules overlays alone.
+    ...GENERATED_ONLY_HARNESSES.map(row => ({
+        target: row.target, mechanism: 'rulesync-rules', capability: row.native.state, evidence: 'pending_evidence',
+        characterizedOn: row.native.measuredOn, measuredVersion: null,
+        provenance: row.target === 'cursor'
+            ? 'cockpit\'s instructions and the sibling guides it copies reach Cursor only through the root AGENTS.md, and .cursor/rules holds only rules overlays; no run of the tool beside a broken control has shown that it loads either'
+            : row.native.reason,
+    })),
+]);
+export function shippedInstructionCapabilities() {
+    return INSTRUCTION_CAPABILITIES.map(row => ({ ...row }));
+}
+// `.codex/` sits one level below the cockpit root, so a root-relative path gains one `..`. This is
+// string arithmetic on purpose: `relative('.codex', path)` resolves both against the process's
+// working directory, and a sync run from inside a sibling then wrote a root that named the wrong place.
+export function codexWritableRoot(rootRelativePath) {
+    return posix.join('..', rootRelativePath);
+}
+// The spelling each tool resolves to the sibling: Codex reads a relative root from `.codex/`, and
+// OpenCode, which matches absolute paths only, reads the absolute directory `sync` writes locally.
+function grantSpelling(targetName, path, slug) {
+    if (targetName === 'claudecode')
+        return `permissions.additionalDirectories:${path}`;
+    if (targetName === 'codexcli')
+        return `sandbox_workspace_write.writable_roots:${codexWritableRoot(path)}`;
+    if (targetName === 'opencode')
+        return `permission.external_directory:{file:.cockpit/local/opencode-grant-${slug}}/**=allow`;
+    if (targetName === 'cursor')
+        return `permission.read+write:${path}/**=allow`;
+    return `permission.read+edit:${path}/**=allow`;
+}
+function lines(content) {
+    if (content.length === 0)
+        return 0;
+    const matches = content.match(/\n/g)?.length ?? 0;
+    return matches + (content.endsWith('\n') ? 0 : 1);
+}
+export function planSiblingProjection(input) {
+    const captured = capturePlannerInput(input);
+    if (!captured)
+        return refuse(diagnostic('PROJECTION_INPUT_INVALID', 'sibling projection input is invalid'));
+    const profiles = new Set(captured.activeProfiles);
+    const active = captured.siblings.filter(row => selected(row, profiles));
+    const activeSlugs = new Set(active.map(row => row.slug));
+    if (captured.mountedPaths.length !== active.length || captured.mountedPaths.some(row => !activeSlugs.has(row.slug))
+        || captured.directoryGrants.length !== active.length * captured.targets.length
+        || captured.directoryGrants.some(row => !activeSlugs.has(row.slug))) {
+        return refuse(diagnostic('PROJECTION_INPUT_INVALID', 'mounted paths and grants must exactly cover active sibling rows'));
+    }
+    const guides = [];
+    const grants = [];
+    for (const sibling of active) {
+        const resolvedDirectory = siblingDirectory(captured, sibling);
+        const mounted = captured.mountedPaths.find(row => row.slug === sibling.slug);
+        if (mounted.path !== resolvedDirectory) {
+            return refuse(diagnostic('PROJECTION_MOUNT_MISMATCH', `projection and generated environment mount disagree for ${sibling.slug}`, {
+                target: sibling.slug, expected: resolvedDirectory, actual: mounted.path,
+            }));
+        }
+        for (const harness of captured.targets) {
+            const declared = captured.directoryGrants.find(row => row.slug === sibling.slug && row.target === harness);
+            if (!declared)
+                return refuse(diagnostic('PROJECTION_INPUT_INVALID', `directory grant coverage is incomplete for ${sibling.slug}:${harness}`));
+            if (declared.path !== resolvedDirectory) {
+                return refuse(diagnostic('PROJECTION_GRANT_MISMATCH', `projection and ${harness} directory grant disagree for ${sibling.slug}`, {
+                    target: `${sibling.slug}:${harness}`, expected: resolvedDirectory, actual: declared.path,
+                }));
+            }
+            const portablePath = relative(captured.canonicalMainCheckout, resolvedDirectory) || '.';
+            grants.push({
+                slug: sibling.slug,
+                target: harness,
+                path: portablePath,
+                spelling: grantSpelling(harness, portablePath, sibling.slug),
+                capability: 'instructed',
+                evidence: 'pending_evidence',
+            });
+        }
+        const observed = (guide) => captured.guideObservations.find(row => row.slug === sibling.slug && row.sourcePath === join(resolvedDirectory, guide));
+        const declaredGuides = sibling.guides ?? ['CLAUDE.md', 'AGENTS.md'];
+        const agentsCopied = declaredGuides.includes('AGENTS.md') && observed('AGENTS.md') !== undefined;
+        const seenContent = new Set();
+        for (const guide of declaredGuides) {
+            const observation = observed(guide);
+            if (!observation || seenContent.has(observation.contentSha256))
+                continue;
+            seenContent.add(observation.contentSha256);
+            const text = guideText(observation.content, guide === 'CLAUDE.md' && agentsCopied);
+            if (text === undefined) {
+                return refuse(diagnostic('PROJECTION_INPUT_INVALID', `guide holds cockpit's own instruction region or owner markers: ${observation.sourcePath}`, { target: observation.sourcePath }));
+            }
+            if (text.length === 0)
+                continue;
+            guides.push({
+                sibling: sibling.slug,
+                guide,
+                sourceGuidePath: observation.sourcePath,
+                sourceContentIdentity: observation.contentIdentity,
+                sourceContentSha256: observation.contentSha256,
+                bytes: guideBlock(sibling.slug, guide, observation.contentSha256, text),
+            });
+        }
+    }
+    grants.sort((left, right) => left.slug.localeCompare(right.slug)
+        || SURFACE_TARGETS.indexOf(left.target) - SURFACE_TARGETS.indexOf(right.target));
+    if (guides.length + grants.length > PROJECTION_RESULT_ENTRY_LIMIT)
+        return PLANNER_RESULT_BOUNDS;
+    // Every instruction target loads the root AGENTS.md, so each pays for every copied guide.
+    const guideCost = guides.reduce((sum, guide) => sum + lines(guide.bytes), 0);
+    const costs = [];
+    for (const harness of INSTRUCTION_TARGETS.filter(item => captured.targets.includes(item))) {
+        const characterization = captured.loadCharacterizations[harness];
+        if (!characterization) {
+            costs.push({ target: harness, status: 'unavailable', reason: 'load cost is not characterized' });
+            continue;
+        }
+        let always = guideCost;
+        let scoped = 0;
+        for (const source of captured.standingSources.filter(source => source.target === harness)) {
+            if (source.scope === 'scoped' && characterization.scopeSemantics === 'conditional')
+                scoped += lines(source.content);
+            else
+                always += lines(source.content);
+        }
+        costs.push({
+            target: harness,
+            status: always > captured.guideCapLines ? 'exceeded' : 'within_cap',
+            metric: 'lines',
+            value: always,
+            conditionalValue: scoped,
+            cap: captured.guideCapLines,
+            measuredOn: characterization.measuredOn,
+            provenance: characterization.provenance,
+            scopeSemantics: characterization.scopeSemantics,
+        });
+    }
+    const available = costs.filter((cost) => cost.status !== 'unavailable');
+    const headlineCost = available.reduce((maximum, cost) => !maximum || cost.value > maximum.value ? cost : maximum, undefined);
+    return capturedValue({
+        kind: 'complete',
+        guides,
+        grants,
+        costs,
+        ...(headlineCost ? { headline: { metric: 'lines', value: headlineCost.value, target: headlineCost.target } } : {}),
+    }) ?? PLANNER_RESULT_BOUNDS;
+}