@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/environment/served-checkout-grants.js

@@ -0,0 +1,182 @@
+/**
+ * Grants the agent tools a sibling checkout `use` serves from outside the declared one. The grants
+ * `sync` writes are committed and name the declared checkout, the same in every clone; a worktree
+ * path is one person's disk, so it goes only where a tool reads a machine-local setting.
+ *
+ * Measured on 2026-11-04 beside an ungranted control directory, each run writing into both:
+ * - Claude Code 2.1.318 (`claude -p --permission-mode acceptEdits`): a directory listed in
+ *   `.claude/settings.local.json` `permissions.additionalDirectories` was written and the control
+ *   refused; a twin whose list was a string was named as not loaded and granted nothing. The run
+ *   was in an untrusted workspace, where Claude ignored the committed `.claude/settings.json` list,
+ *   so whether the two lists combine once a person trusts the workspace was not measured.
+ * - OpenCode 1.19.5 (`opencode run`): the `{file:...}` grant file `sync` writes, holding the
+ *   worktree path, allowed the write and the control was denied; a pattern naming a missing grant
+ *   file stopped OpenCode at start, naming the file.
+ * - Codex 0.166.0 (`codex exec`): no project file Codex reads is machine-local. Its project
+ *   `.codex/config.toml` is committed and its only per-project user setting is the trust level;
+ *   `--add-dir <dir>` at start made the worktree writable beside the committed roots, and without
+ *   it the same write was refused.
+ * Cursor and Grok Build were not installed, so nothing is written for them.
+ */
+import { lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, join, sep } from 'node:path';
+import { readBoundedFile } from '../bounded-read.js';
+import { GUARD_LOCAL_PATHS, writeCockpitLocalFiles } from '../guards/local-identity.js';
+import { ENVIRONMENT_CODES, errorCause, isMissing, tryParseJson } from './contract.js';
+import { openCodeGrantFile } from './generated-application/surface-outputs.js';
+const CLAUDE_LOCAL_SETTINGS = '.claude/settings.local.json';
+// What cockpit put in Claude's local settings, so a person's own entries are never taken back.
+const ADDED_NAME = 'claude-local-grants';
+const ADDED_PATH = `${GUARD_LOCAL_PATHS.directory}/${ADDED_NAME}`;
+const ADDED_FORMAT = 'cockpit-claude-local-grants/v1';
+const SETTINGS_MAX_BYTES = 1_048_576;
+export function inside(path, root) {
+    return path === root || path.startsWith(`${root}${sep}`);
+}
+/**
+ * The directory the OpenCode grant file names: the served checkout when it lies outside the
+ * declared one, which the grant would not otherwise reach.
+ */
+export function openCodeGrantDirectory(declared, served) {
+    return served !== undefined && !inside(served, declared) ? served : declared;
+}
+/** Why a directory cannot go into an OpenCode access pattern, or undefined when it can. */
+export function openCodePatternUnsafe(directory) {
+    // The file's bytes become part of an OpenCode pattern: a wildcard would widen the grant and a
+    // quote or backslash would change the JSON around it.
+    return /[*?"\\\x00-\x1f\x7f]/.test(directory)
+        ? `${directory} contains *, ?, a quote, a backslash or a control character, which OpenCode would read as part of its access pattern`
+        : undefined;
+}
+const HARNESS_NAMES = { codexcli: 'Codex', cursor: 'Cursor', grokcli: 'Grok Build' };
+function grantRefusal(message, target, fix) {
+    return { kind: 'refusal', diagnostic: { severity: 'error', code: ENVIRONMENT_CODES.SIBLING_CHECKOUT_RECORD_INVALID, message, target, fix } };
+}
+function plainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** The JSON text of a local file, or undefined when there is none; a link or unreadable file is a reason. */
+function readLocalJson(path) {
+    try {
+        const read = readBoundedFile(path, SETTINGS_MAX_BYTES);
+        if (read.kind === 'too-large')
+            return { reason: `it is larger than ${SETTINGS_MAX_BYTES} bytes` };
+        const bytes = read.bytes.toString('utf8');
+        return { value: tryParseJson(bytes), bytes };
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        return { reason: `it could not be read as a plain file: ${errorCause(error)}` };
+    }
+}
+/**
+ * Plans the machine-local grants for one sibling. `served` is the checkout that serves it, or
+ * undefined when the sibling is no longer declared; `targets` are the listed tools that hold a
+ * committed grant for it. A grant cockpit added earlier for the sibling is taken back when the
+ * served checkout no longer needs it.
+ */
+export async function planAgentGrants(input) {
+    const outside = input.declared !== undefined && input.served !== undefined && !inside(input.served, input.declared) ? input.served : undefined;
+    const addedPath = join(input.root, ADDED_PATH);
+    const recorded = readLocalJson(addedPath);
+    const addedFix = `delete ${addedPath}, remove the additionalDirectories entries cockpit added from ${CLAUDE_LOCAL_SETTINGS}, then run this command again`;
+    if (recorded && 'reason' in recorded)
+        return grantRefusal(`${addedPath} could not be read: ${recorded.reason}`, ADDED_PATH, addedFix);
+    const record = recorded?.value;
+    if (recorded && !(plainObject(record) && record.format === ADDED_FORMAT && plainObject(record.directories)
+        && Object.values(record.directories).every(directory => typeof directory === 'string'))) {
+        return grantRefusal(`${addedPath} is not a record cockpit wrote (it does not carry the ${ADDED_FORMAT} format)`, ADDED_PATH, addedFix);
+    }
+    const added = { ...(plainObject(record) ? record.directories : {}) };
+    const previous = Object.hasOwn(added, input.slug) ? added[input.slug] : undefined;
+    delete added[input.slug];
+    const wantClaude = outside !== undefined && input.targets.includes('claudecode') ? outside : undefined;
+    let settings;
+    if (previous !== undefined || wantClaude !== undefined) {
+        const settingsPath = join(input.root, CLAUDE_LOCAL_SETTINGS);
+        const settingsFix = `make ${settingsPath} a JSON object whose permissions.additionalDirectories is a list of paths, or remove it, then run this command again`;
+        const current = readLocalJson(settingsPath);
+        if (current && 'reason' in current)
+            return grantRefusal(`${settingsPath} could not be read: ${current.reason}`, CLAUDE_LOCAL_SETTINGS, settingsFix);
+        const object = current === undefined ? {} : current.value;
+        const permissions = plainObject(object) ? object.permissions ?? {} : undefined;
+        const listed = plainObject(permissions) ? permissions.additionalDirectories ?? [] : undefined;
+        // Claude Code drops a whole settings file it cannot load, so cockpit never rewrites one it cannot read either.
+        if (!plainObject(object) || !plainObject(permissions) || !Array.isArray(listed) || !listed.every(entry => typeof entry === 'string')) {
+            return grantRefusal(`${settingsPath} is not a Claude Code settings object cockpit can add a directory to`, CLAUDE_LOCAL_SETTINGS, settingsFix);
+        }
+        let directories = listed;
+        if (previous !== undefined && previous !== wantClaude && !Object.values(added).includes(previous)) {
+            directories = directories.filter(directory => directory !== previous);
+        }
+        if (wantClaude !== undefined) {
+            // A directory the person listed themselves stays theirs: cockpit neither records nor removes it.
+            if (previous === wantClaude || !directories.includes(wantClaude))
+                added[input.slug] = wantClaude;
+            if (!directories.includes(wantClaude))
+                directories = [...directories, wantClaude];
+        }
+        if (directories.length !== listed.length || directories.some((directory, index) => directory !== listed[index])) {
+            const { additionalDirectories: _replaced, ...otherPermissions } = permissions;
+            const nextPermissions = directories.length > 0 ? { ...otherPermissions, additionalDirectories: directories } : otherPermissions;
+            const { permissions: _permissions, ...otherSettings } = object;
+            const next = Object.keys(nextPermissions).length > 0 ? { ...otherSettings, permissions: nextPermissions } : otherSettings;
+            settings = { bytes: Object.keys(next).length > 0 ? `${JSON.stringify(next, null, 2)}\n` : null };
+        }
+    }
+    const local = [];
+    if (previous !== added[input.slug])
+        local.push({ name: ADDED_NAME, bytes: `${JSON.stringify({ format: ADDED_FORMAT, directories: added })}\n` });
+    if (input.declared !== undefined && input.targets.includes('opencode')) {
+        const directory = openCodeGrantDirectory(input.declared, input.served);
+        const unsafe = openCodePatternUnsafe(directory);
+        if (unsafe)
+            return grantRefusal(`OpenCode cannot be granted the checkout: ${unsafe}`, directory, 'move the checkout to a plain path, then run this command again');
+        local.push({ name: basename(openCodeGrantFile(input.slug)), bytes: directory });
+    }
+    if (outside === undefined)
+        return { kind: 'complete', plan: { settings, local, lines: [], report: undefined } };
+    const granted = input.targets.filter(target => target === 'claudecode' || target === 'opencode');
+    const ungranted = input.targets.filter(target => target !== 'claudecode' && target !== 'opencode');
+    const lines = [
+        ...granted.map(target => `${target === 'claudecode' ? 'Claude Code' : 'OpenCode'} may edit ${outside} through ${target === 'claudecode' ? CLAUDE_LOCAL_SETTINGS : openCodeGrantFile(input.slug)}, which only this machine reads; restart a session that is already running.`),
+        ...ungranted.map(target => target === 'codexcli'
+            ? `Codex has no machine-local setting for extra writable roots, so its sandbox still reaches only ${input.declared}; start Codex with --add-dir ${outside}.`
+            : `${HARNESS_NAMES[target] ?? target} was not measured for a machine-local grant, so its grant still names only ${input.declared} and it may ask before editing ${outside}.`),
+    ];
+    return { kind: 'complete', plan: { settings, local, lines, report: { granted, ungranted } } };
+}
+/** Writes a plan: cockpit's own record first, so a grant it added is never one it forgets. */
+export async function applyAgentGrants(root, plan) {
+    if (plan.local.length > 0) {
+        const written = await writeCockpitLocalFiles(root, plan.local);
+        if (written.kind !== 'complete')
+            return grantRefusal(`the agent tools' machine-local grants could not be written: ${written.message}`, GUARD_LOCAL_PATHS.directory, 'make .cockpit/local a plain directory you can write, then run this command again');
+    }
+    if (plan.settings === undefined)
+        return { kind: 'complete' };
+    const path = join(root, CLAUDE_LOCAL_SETTINGS);
+    try {
+        if (plan.settings.bytes === null) {
+            await rm(path);
+            return { kind: 'complete' };
+        }
+        const directory = join(root, '.claude');
+        await mkdir(directory, { recursive: true });
+        if ((await lstat(directory)).isSymbolicLink())
+            throw new Error(`${directory} is a symbolic link`);
+        const temporary = join(directory, `.settings.local.json.${process.pid}.tmp`);
+        try {
+            await writeFile(temporary, plan.settings.bytes, { flag: 'wx' });
+            await rename(temporary, path);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+        return { kind: 'complete' };
+    }
+    catch (error) {
+        return grantRefusal(`${path} could not be written: ${errorCause(error)}`, CLAUDE_LOCAL_SETTINGS, 'make .claude a plain directory you can write, then run this command again');
+    }
+}

package/dist/environment/sibling-checkouts.d.ts

@@ -0,0 +1,119 @@
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import type { CockpitConfig, Sibling } from '../schema.js';
+import { type EnvironmentDiagnostic, type ExecutionStep } from './contract.js';
+import { type ResolvedExecutable } from './executable.js';
+export declare const SIBLING_CHECKOUTS_PATH: string;
+/** Each overridden sibling's slug and the canonical absolute directory that serves it. */
+type SiblingCheckoutRecord = Readonly<Record<string, string>>;
+export type SiblingCheckoutRecordRead = Readonly<{
+    kind: 'complete';
+    checkouts: SiblingCheckoutRecord;
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: EnvironmentDiagnostic;
+}>;
+/** The recorded overrides; none when nothing was recorded. A record cockpit did not write is refused, never ignored. */
+export declare function readSiblingCheckouts(cockpitRoot: string): Promise<SiblingCheckoutRecordRead>;
+export declare function writeSiblingCheckouts(cockpitRoot: string, checkouts: SiblingCheckoutRecord): Promise<{
+    readonly kind: 'complete';
+} | {
+    readonly kind: 'refusal';
+    readonly message: string;
+}>;
+export interface ServedSibling {
+    readonly slug: string;
+    /** Where cockpit.toml puts the checkout. */
+    readonly declared: string;
+    /** The checkout the stack, the guard and the health commands use. */
+    readonly served: string;
+    readonly overridden: boolean;
+}
+/** Every declared sibling with the directory that serves it; an override for an undeclared slug serves nothing. */
+export declare function servedSiblings(cockpitRoot: string, config: Readonly<{
+    cockpit: Readonly<{
+        siblings_root: string;
+    }>;
+    sibling: readonly Readonly<{
+        slug: string;
+        dir: string;
+    }>[];
+}>, checkouts: SiblingCheckoutRecord): ReadonlyMap<string, ServedSibling>;
+/** The directory serving a declared sibling; a slug the map lacks is a caller's error, named as one. */
+export declare function servedPath(served: ReadonlyMap<string, ServedSibling>, slug: string): string;
+type ServedSiblingsRead = Readonly<{
+    kind: 'complete';
+    siblings: ReadonlyMap<string, ServedSibling>;
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: EnvironmentDiagnostic;
+}>;
+export declare function loadServedSiblings(cockpitRoot: string, config: Pick<CockpitConfig, 'cockpit' | 'sibling'>): Promise<ServedSiblingsRead>;
+/** The overridden siblings whose recorded directory is gone, such as a removed worktree. */
+export declare function vanishedServedCheckouts(served: ReadonlyMap<string, ServedSibling>): Promise<readonly ServedSibling[]>;
+export declare function vanishedCheckoutFix(slug: string): string;
+/**
+ * A refusal when an override names a directory that is gone. Docker creates a missing bind-mount
+ * source as an empty directory, so the stack would start on nothing. Preflight and doctor report
+ * the same fact as the served-checkouts observation row, so all three agree.
+ */
+export declare function missingServedCheckout(served: ReadonlyMap<string, ServedSibling>): Promise<EnvironmentDiagnostic | undefined>;
+/** The directory variables Compose interpolates: each sibling's `var` and the directory that serves it. */
+export declare function servedSiblingVariables(config: Pick<CockpitConfig, 'sibling'>, served: ReadonlyMap<string, ServedSibling>): Readonly<Record<string, string>>;
+type GitRun = Readonly<{
+    kind: 'complete';
+    stdout: string;
+}> | Readonly<{
+    kind: 'failed';
+    exitCode: number;
+    code: string;
+    detail: string;
+    stderr: string;
+}>;
+/**
+ * `stdoutLimitBytes` replaces the default bound, which keeps only the tail of longer output, with a
+ * hard one: output past it fails with EXECUTION_STDOUT_LIMIT instead of arriving in part.
+ */
+type GitRunOptions = Readonly<{
+    timeoutMs?: number;
+    stdoutLimitBytes?: number;
+}>;
+/** Runs one Git command in a checkout through the authenticated executor and returns its text. */
+export interface GitRunner {
+    readonly executable: ResolvedExecutable;
+    run(cwd: string, id: string, args: readonly string[], options?: GitRunOptions): Promise<GitRun>;
+}
+export declare const GIT_CHILD_CONFIG: readonly ['-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null'];
+export declare function createGitRunner(env: Readonly<Record<string, string | undefined>>, execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>): Promise<GitRunner | Readonly<{
+    unavailable: string;
+}>>;
+type SiblingCheckoutInspection = Readonly<{
+    kind: 'same-repository';
+    directory: string;
+    evidence: 'object-store' | 'remote';
+}> | Readonly<{
+    kind: 'refusal';
+    diagnostic: EnvironmentDiagnostic;
+}>;
+/**
+ * Whether `candidate` is the root of a checkout of the sibling's repository: it shares the declared
+ * checkout's object store (a linked worktree), or its origin names the same repository as the
+ * declared checkout's origin or the declared remote. Anything else is refused: serving an unrelated
+ * repository under a sibling's name would hand its code the sibling's mounts and grants.
+ */
+export declare function inspectSiblingCheckout(input: Readonly<{
+    sibling: Pick<Sibling, 'slug' | 'remote'>;
+    declared: string;
+    candidate: string;
+    git: GitRunner;
+}>): Promise<SiblingCheckoutInspection>;
+/** The declared environment files the served checkout lacks; a fresh worktree has none of the ignored ones. */
+export declare function missingEnvironmentFiles(served: ServedSibling, sibling: Pick<Sibling, 'environment_files'>): Promise<readonly Readonly<{
+    template: string;
+    instance: string;
+}>[]>;
+/** One warning per environment file an overriding checkout lacks, naming who must create it and from what. */
+export declare function missingEnvironmentFileDiagnostics(served: ServedSibling, missing: readonly Readonly<{
+    template: string;
+    instance: string;
+}>[]): readonly EnvironmentDiagnostic[];
+export {};

package/dist/environment/sibling-checkouts.js

@@ -0,0 +1,254 @@
+/**
+ * Owns which checkout serves each sibling: the directory cockpit.toml declares under siblings_root,
+ * or another checkout of the same repository (a linked worktree, usually) that `cockpit use`
+ * recorded for this cockpit checkout alone. Mounts, the guard's allowed roots and the health
+ * commands all read the served directory from here, so they describe the same code.
+ *
+ * The record is machine-local, under `.cockpit/local`, never in cockpit.toml: a worktree path is
+ * one person's disk, and a committed one would point every other clone at a directory it lacks.
+ * Without it, an agent working on a branch in a sibling's worktree had the stack, the checks and
+ * every grade run against the main checkout's branch while reporting green.
+ */
+import { lstatIfPresent } from './presence.js';
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, join, normalize, resolve } from 'node:path';
+import { authenticatedExecutionOutcome } from '../environment-exec/execute.js';
+import { readBoundedFile } from '../bounded-read.js';
+import { cockpitCommand, formatShellCommand } from '../fix-catalogue.js';
+import { GUARD_LOCAL_PATHS, writeCockpitLocalFiles } from '../guards/local-identity.js';
+import { ENVIRONMENT_CODES, errorCause, hasErrorCode, RefusalError, tryParseJson } from './contract.js';
+import { resolveGitExecutable } from './executable.js';
+import { repositoryIdentity } from './repository-identity.js';
+import { redactSensitiveMessage } from './sensitive.js';
+import { gitEnvironment } from './setup.js';
+const FORMAT = 'cockpit-sibling-checkouts/v1';
+const RECORD_NAME = 'sibling-checkouts';
+export const SIBLING_CHECKOUTS_PATH = `${GUARD_LOCAL_PATHS.directory}/${RECORD_NAME}`;
+const RECORD_MAX_BYTES = 65_536;
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+function canonicalDirectory(value) {
+    return typeof value === 'string' && isAbsolute(value) && normalize(value) === value && value !== '/'
+        && !value.endsWith('/') && !/[\x00-\x1f\x7f]/.test(value);
+}
+function recordRefusal(path, reason) {
+    return { kind: 'refusal', diagnostic: {
+            severity: 'error',
+            code: 'SIBLING_CHECKOUT_RECORD_INVALID',
+            message: `${path} is not a sibling checkout record cockpit wrote (${reason}), so cockpit cannot tell which checkout serves each sibling`,
+            target: SIBLING_CHECKOUTS_PATH,
+            fix: `delete ${path}, then run npx --no cockpit use <slug> <checkout> --config <your cockpit.toml> again for each sibling another checkout should serve`,
+        } };
+}
+/** The recorded overrides; none when nothing was recorded. A record cockpit did not write is refused, never ignored. */
+export async function readSiblingCheckouts(cockpitRoot) {
+    const path = join(cockpitRoot, SIBLING_CHECKOUTS_PATH);
+    let bytes;
+    try {
+        const read = readBoundedFile(path, RECORD_MAX_BYTES);
+        if (read.kind === 'too-large')
+            return recordRefusal(path, `it is larger than ${RECORD_MAX_BYTES} bytes`);
+        bytes = read.bytes;
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return { kind: 'complete', checkouts: {} };
+        // ELOOP: a link at the last component; EISDIR: the reader's code for a file that is not regular.
+        if (hasErrorCode(error, 'ELOOP', 'EISDIR'))
+            return recordRefusal(path, 'it is not a plain file');
+        return recordRefusal(path, `it could not be read: ${errorCause(error)}`);
+    }
+    const value = tryParseJson(bytes.toString('utf8'));
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return recordRefusal(path, 'it is not a JSON object');
+    const record = value;
+    if (Object.keys(record).sort().join(',') !== 'checkouts,format' || record.format !== FORMAT) {
+        return recordRefusal(path, `it does not carry the ${FORMAT} format`);
+    }
+    const checkouts = record.checkouts;
+    if (checkouts === null || typeof checkouts !== 'object' || Array.isArray(checkouts)
+        || Object.entries(checkouts).some(([slug, directory]) => !SLUG.test(slug) || !canonicalDirectory(directory))) {
+        return recordRefusal(path, 'a slug or directory in it is malformed');
+    }
+    return { kind: 'complete', checkouts: Object.freeze({ ...checkouts }) };
+}
+export async function writeSiblingCheckouts(cockpitRoot, checkouts) {
+    const ordered = Object.fromEntries(Object.entries(checkouts).sort(([left], [right]) => left < right ? -1 : 1));
+    return writeCockpitLocalFiles(cockpitRoot, [{ name: RECORD_NAME, bytes: `${JSON.stringify({ format: FORMAT, checkouts: ordered })}\n` }]);
+}
+/** Every declared sibling with the directory that serves it; an override for an undeclared slug serves nothing. */
+export function servedSiblings(cockpitRoot, config, checkouts) {
+    const siblingsRoot = resolve(cockpitRoot, config.cockpit.siblings_root);
+    return new Map(config.sibling.map(sibling => {
+        const declared = resolve(siblingsRoot, sibling.dir);
+        const override = Object.hasOwn(checkouts, sibling.slug) ? checkouts[sibling.slug] : undefined;
+        return [sibling.slug, Object.freeze({ slug: sibling.slug, declared, served: override ?? declared, overridden: override !== undefined })];
+    }));
+}
+/** The directory serving a declared sibling; a slug the map lacks is a caller's error, named as one. */
+export function servedPath(served, slug) {
+    const entry = served.get(slug);
+    if (!entry)
+        throw new RefusalError(`sibling ${slug} has no served checkout; it is not declared in cockpit.toml`);
+    return entry.served;
+}
+export async function loadServedSiblings(cockpitRoot, config) {
+    const read = await readSiblingCheckouts(cockpitRoot);
+    return read.kind === 'complete' ? { kind: 'complete', siblings: servedSiblings(cockpitRoot, config, read.checkouts) } : read;
+}
+/** The overridden siblings whose recorded directory is gone, such as a removed worktree. */
+export async function vanishedServedCheckouts(served) {
+    const overridden = [...served.values()].filter(sibling => sibling.overridden);
+    const present = await Promise.all(overridden.map(async (sibling) => (await lstatIfPresent(sibling.served))?.isDirectory() === true));
+    return overridden.filter((_, index) => !present[index]);
+}
+export function vanishedCheckoutFix(slug) {
+    return `serve the declared checkout again with ${cockpitCommand('use', { operand: slug, args: '--clear' })}, or name another checkout of it`;
+}
+/**
+ * A refusal when an override names a directory that is gone. Docker creates a missing bind-mount
+ * source as an empty directory, so the stack would start on nothing. Preflight and doctor report
+ * the same fact as the served-checkouts observation row, so all three agree.
+ */
+export async function missingServedCheckout(served) {
+    const [sibling] = await vanishedServedCheckouts(served);
+    return sibling === undefined ? undefined : {
+        severity: 'error',
+        code: 'SIBLING_CHECKOUT_UNAVAILABLE',
+        message: `sibling ${sibling.slug} is recorded to be served from ${sibling.served}, which is no longer a directory`,
+        target: sibling.served,
+        fix: vanishedCheckoutFix(sibling.slug),
+    };
+}
+/** The directory variables Compose interpolates: each sibling's `var` and the directory that serves it. */
+export function servedSiblingVariables(config, served) {
+    return Object.fromEntries(config.sibling.map(sibling => [sibling.var, servedPath(served, sibling.slug)]));
+}
+// Repository-local `core.fsmonitor` and hooks run code on nearly any Git command. Agents cannot write under
+// `.git`, so this is defence in depth against a checkout whose configuration arrived some other way.
+export const GIT_CHILD_CONFIG = ['-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null'];
+// Global and system configuration can carry aliases, credential helpers and fsmonitor commands that
+// run code; cockpit's Git children read only the repository's own configuration, as setup's clone does.
+export async function createGitRunner(env, execute) {
+    const git = await resolveGitExecutable(env);
+    if (git.state !== 'available')
+        return { unavailable: git.reason };
+    const executable = git.value;
+    const environment = gitEnvironment(env);
+    return {
+        executable,
+        async run(cwd, id, args, { timeoutMs = 30_000, stdoutLimitBytes } = {}) {
+            const step = {
+                id, argv: [executable.canonicalPath, '-C', cwd, ...GIT_CHILD_CONFIG, ...args], argv0: executable.invocationPath,
+                cwd, env: environment, timeoutMs, stdoutLimitBytes: stdoutLimitBytes ?? 65_536, stderrLimitBytes: 65_536,
+                ...stdoutLimitBytes === undefined ? { outputOverflow: 'retain-tail' } : {},
+                paths: [], ports: [], labels: { purpose: id }, expected: [],
+                consumedFiles: [{ path: executable.canonicalPath, sha256: executable.sha256, maxBytes: 536_870_912,
+                        argvIndexes: [0], executable: true, executionMode: executable.executionMode }],
+                filesystemChecks: [], compensation: [],
+            };
+            const outcome = authenticatedExecutionOutcome(await execute(step), step);
+            if (!outcome)
+                return { kind: 'failed', exitCode: -1, code: 'unauthenticated', detail: 'the execution outcome could not be authenticated', stderr: '' };
+            const text = (bytes) => new TextDecoder('utf-8', { fatal: false }).decode(bytes).trim();
+            if (outcome.kind === 'complete')
+                return { kind: 'complete', stdout: text(outcome.stdout) };
+            // Git's last line names the cause (an unreachable host, a file a merge would overwrite); a
+            // remote URL in it may carry credentials, and a line that cannot be redacted is withheld.
+            const line = text(outcome.stderr).replace(/(\w+:\/\/)[^/@\s]+@/g, '$1[redacted]@').split('\n').filter(Boolean).at(-1);
+            const cause = line === undefined ? undefined : redactSensitiveMessage(line.slice(0, 240));
+            return { kind: 'failed', exitCode: outcome.execution.exitCode, code: outcome.code,
+                detail: cause ? `${outcome.code}: ${cause}` : outcome.code, stderr: text(outcome.stderr) };
+        },
+    };
+}
+async function checkoutIdentity(git, directory) {
+    const located = await git.run(directory, 'checkout:identity', ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir']);
+    if (located.kind !== 'complete')
+        return { reason: `it is not a Git checkout (${located.detail})` };
+    const [toplevel, commonDirectory] = located.stdout.split('\n');
+    if (!toplevel || !commonDirectory)
+        return { reason: 'Git did not name its working tree and object store' };
+    const origin = await git.run(directory, 'checkout:origin', ['config', '--get', 'remote.origin.url']);
+    const identity = origin.kind === 'complete' ? repositoryIdentity(origin.stdout) : undefined;
+    try {
+        return {
+            toplevel: await realpath(toplevel), commonDirectory: await realpath(commonDirectory),
+            origin: identity?.kind === 'known' ? identity.identity : undefined,
+        };
+    }
+    catch (error) {
+        return { reason: `the working tree or object store Git named cannot be resolved (${errorCause(error)})` };
+    }
+}
+function sameIdentity(left, right) {
+    return left.host === right.host && left.owner.toLowerCase() === right.owner.toLowerCase()
+        && left.repository.toLowerCase() === right.repository.toLowerCase();
+}
+function spelled(identity) {
+    return identity === undefined ? 'no recognisable origin remote' : `${identity.host}/${identity.owner}/${identity.repository}`;
+}
+/**
+ * Whether `candidate` is the root of a checkout of the sibling's repository: it shares the declared
+ * checkout's object store (a linked worktree), or its origin names the same repository as the
+ * declared checkout's origin or the declared remote. Anything else is refused: serving an unrelated
+ * repository under a sibling's name would hand its code the sibling's mounts and grants.
+ */
+export async function inspectSiblingCheckout(input) {
+    const unavailable = (message, fix) => ({ kind: 'refusal', diagnostic: {
+            severity: 'error', code: 'SIBLING_CHECKOUT_UNAVAILABLE',
+            message, target: input.candidate, fix,
+        } });
+    const listWorktrees = `list the checkouts of ${input.sibling.slug} with git -C ${input.declared} worktree list, and name one of them`;
+    let directory;
+    try {
+        directory = await realpath(input.candidate);
+        if (!(await lstat(directory)).isDirectory())
+            return unavailable(`${input.candidate} is not a directory`, listWorktrees);
+    }
+    catch (error) {
+        return unavailable(`${input.candidate} cannot be resolved (${errorCause(error)})`, listWorktrees);
+    }
+    // The guard admits an agent's `use` by the path as written; a link in it, swapped in after that
+    // check, would record and then grant a directory the agent was never allowed to reach.
+    if (directory !== input.candidate) {
+        return unavailable(`${input.candidate} reaches ${directory} through a symbolic link, so cockpit will not record it`, `name the directory itself: ${cockpitCommand('use', { operand: input.sibling.slug, args: formatShellCommand([directory]) })}`);
+    }
+    const [candidate, declared] = await Promise.all([checkoutIdentity(input.git, directory), checkoutIdentity(input.git, input.declared)]);
+    if ('reason' in candidate)
+        return unavailable(`${directory} cannot serve sibling ${input.sibling.slug}: ${candidate.reason}`, listWorktrees);
+    if (candidate.toplevel !== directory) {
+        return unavailable(`${directory} is inside the checkout at ${candidate.toplevel}, not its root, so the stack would mount part of a checkout`, `name the checkout's root: ${cockpitCommand('use', { operand: input.sibling.slug, args: formatShellCommand([candidate.toplevel]) })}`);
+    }
+    if (!('reason' in declared) && declared.commonDirectory === candidate.commonDirectory) {
+        return { kind: 'same-repository', directory, evidence: 'object-store' };
+    }
+    // The declared checkout may track a fork while cockpit.toml's remote names the upstream; either counts.
+    const declaredRemote = input.sibling.remote === undefined ? undefined : repositoryIdentity(input.sibling.remote);
+    const expected = [...!('reason' in declared) && declared.origin !== undefined ? [declared.origin] : [],
+        ...declaredRemote?.kind === 'known' ? [declaredRemote.identity] : []];
+    if (candidate.origin !== undefined && expected.some(identity => sameIdentity(identity, candidate.origin))) {
+        return { kind: 'same-repository', directory, evidence: 'remote' };
+    }
+    return { kind: 'refusal', diagnostic: {
+            severity: 'error', code: 'SIBLING_CHECKOUT_FOREIGN',
+            message: `${directory} is not a checkout of sibling ${input.sibling.slug}: it shares no object store with ${input.declared}, `
+                + `and its origin (${spelled(candidate.origin)}) is not the sibling's (${expected.length === 0 ? 'none known' : expected.map(spelled).join(' or ')})`,
+            target: input.candidate,
+            fix: `create a worktree of the sibling with git -C ${input.declared} worktree add <path> <branch> and name that path, or ${listWorktrees}`,
+        } };
+}
+/** The declared environment files the served checkout lacks; a fresh worktree has none of the ignored ones. */
+export async function missingEnvironmentFiles(served, sibling) {
+    const present = await Promise.all((sibling.environment_files ?? []).map(async (file) => await lstatIfPresent(join(served.served, file.instance)) !== undefined));
+    return (sibling.environment_files ?? []).filter((_, index) => !present[index]).map(file => ({ template: file.template, instance: file.instance }));
+}
+/** One warning per environment file an overriding checkout lacks, naming who must create it and from what. */
+export function missingEnvironmentFileDiagnostics(served, missing) {
+    return missing.map(file => ({
+        severity: 'warning',
+        code: 'SIBLING_ENVIRONMENT_FILE_MISSING',
+        message: `sibling ${served.slug} is served from ${served.served}, which has no ${file.instance}; the services that read it would start without its settings`,
+        target: join(served.served, file.instance),
+        fix: `a person creates ${join(served.served, file.instance)} from the template ${join(served.served, file.template)}, or copies the one in ${served.declared}; cockpit never copies environment files between checkouts`,
+    }));
+}

package/dist/environment/sibling-observation.d.ts

@@ -0,0 +1,27 @@
+import type { CockpitConfig } from '../schema.js';
+import { type EnvironmentObservation, type StackId } from './contract.js';
+export declare const observationDeclarations: readonly [{
+    readonly id: 'served-checkouts';
+    readonly owner: "sibling-observation";
+    readonly postures: readonly ["environment"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'required';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "SIBLING_CHECKOUT_UNAVAILABLE";
+    readonly isIssued: typeof isSiblingObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}];
+declare function isSiblingObservation(value: unknown): value is EnvironmentObservation;
+declare function observationIssuedAt(value: unknown): number | undefined;
+/** One row: the directories that should serve a sibling and do not exist. Passing means none. */
+export declare function observeServedCheckouts(input: Readonly<{
+    stackId: StackId;
+    observedAt: string;
+    configPath: string;
+    config: Pick<CockpitConfig, 'cockpit' | 'sibling'>;
+}>): Promise<readonly EnvironmentObservation[]>;
+export {};

package/dist/environment/sibling-observation.js

@@ -0,0 +1,45 @@
+// Owns: observing whether each checkout recorded to serve a sibling still exists. It is the one
+// verdict preflight, doctor and `up` share: `up` refuses a vanished served checkout, so a gate that
+// only warned about it would pass a stack `up` cannot start. Must not: decide the health verdict
+// (observations.ts) or inspect whether a checkout belongs to its sibling (sibling-checkouts.ts).
+import { dirname } from 'node:path';
+import { ENVIRONMENT_CODES, RefusalError, snapshotEnvironmentObservation, } from './contract.js';
+import { loadServedSiblings, SIBLING_CHECKOUTS_PATH, vanishedCheckoutFix, vanishedServedCheckouts } from './sibling-checkouts.js';
+const OWNER = 'sibling-observation';
+export const observationDeclarations = Object.freeze([
+    { id: 'served-checkouts', owner: OWNER, postures: ['environment'], stages: [{ stage: 'bootstrap', disposition: 'required' }, { stage: 'steady', disposition: 'required' }], code: ENVIRONMENT_CODES.SIBLING_CHECKOUT_UNAVAILABLE, isIssued: isSiblingObservation, issuedAt: observationIssuedAt },
+]);
+const issuedObservations = new WeakMap();
+function isSiblingObservation(value) {
+    return value !== null && typeof value === 'object' && issuedObservations.has(value);
+}
+function observationIssuedAt(value) {
+    return value !== null && typeof value === 'object' ? issuedObservations.get(value) : undefined;
+}
+/** One row: the directories that should serve a sibling and do not exist. Passing means none. */
+export async function observeServedCheckouts(input) {
+    const served = await loadServedSiblings(dirname(input.configPath), input.config);
+    let missing;
+    let remedy;
+    if (served.kind === 'refusal') {
+        // `up` refuses an unreadable record as well: no one can say which checkout serves a sibling.
+        missing = [SIBLING_CHECKOUTS_PATH];
+        remedy = served.diagnostic.fix ?? `repair ${SIBLING_CHECKOUTS_PATH}`;
+    }
+    else {
+        const vanished = await vanishedServedCheckouts(served.siblings);
+        missing = vanished.map(sibling => sibling.served);
+        remedy = vanished.length === 0 ? 'no action needed' : vanished.map(sibling => `${sibling.slug}: ${vanishedCheckoutFix(sibling.slug)}`).join('; ');
+    }
+    const snapshot = snapshotEnvironmentObservation({
+        code: ENVIRONMENT_CODES.SIBLING_CHECKOUT_UNAVAILABLE, owner: OWNER, stackId: input.stackId, source: 'served-checkouts',
+        observed: { state: 'available', value: missing, observedAt: input.observedAt },
+        expectation: { kind: 'equal', value: [] },
+        applicability: { state: 'required', posture: 'environment' },
+        freshness: { state: 'current' }, remedy,
+    });
+    if (!snapshot)
+        throw new RefusalError('served-checkouts observation is malformed');
+    issuedObservations.set(snapshot, Date.now());
+    return [snapshot];
+}

package/dist/environment/sibling-pull.d.ts

@@ -0,0 +1,23 @@
+import type { GitRunner } from './sibling-checkouts.js';
+export type PullRow = Readonly<{
+    state: 'advanced';
+    path: string;
+    branch: string;
+    upstream: string;
+    from: string;
+    to: string;
+    commits: number;
+}> | Readonly<{
+    state: 'current';
+    path: string;
+    branch: string;
+    upstream: string;
+    ahead: number;
+}> | Readonly<{
+    state: 'skipped';
+    path: string;
+    reason: string;
+    fix: string;
+    blocked: boolean;
+}>;
+export declare function fastForwardCheckout(git: GitRunner, path: string): Promise<PullRow>;