@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/sibling-instructions.js

@@ -0,0 +1,224 @@
+// Which root instruction files each agent tool loads in a repository, measured 2026-11-03 by asking
+// each tool for words only a file it had loaded could tell it, beside a decoy file it must not load:
+// Codex 0.166.0 and OpenCode 1.19.5 loaded AGENTS.md; Claude Code 2.1.317 loaded only CLAUDE.md (its
+// built-in AGENTS.md reader is an option user settings can turn on and project settings cannot). With
+// no AGENTS.md, OpenCode fell back to CLAUDE.md and Codex loaded nothing. None of the three loaded
+// .cursorrules, .cursor/rules, GEMINI.md, .github/copilot-instructions.md or .windsurfrules. So a
+// repository's instructions reach every tool alike only when AGENTS.md holds them and CLAUDE.md
+// imports it; anything else leaves some tool without them.
+import { randomBytes } from 'node:crypto';
+import { sha256Hex } from '../sha256.js';
+import { constants } from 'node:fs';
+import { lstat, open, realpath, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readBoundedInput } from '../config/load.js';
+import { ENVIRONMENT_CODES, errorCause, isMissing, RefusalError } from './contract.js';
+const CLAUDE_IMPORT = '@AGENTS.md\n';
+const TOOL_ONLY_FILES = ['.cursorrules', '.cursor/rules', 'GEMINI.md', '.github/copilot-instructions.md', '.windsurfrules'];
+async function readInstructionFile(path) {
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return { kind: 'absent' };
+        throw error;
+    }
+    // A link is read where it resolves, so CLAUDE.md linked to AGENTS.md counts as one file.
+    const real = await realpath(path);
+    const read = await readBoundedInput(real);
+    if (read.kind !== 'complete')
+        throw new RefusalError(`${path} is larger than cockpit reads`);
+    return { kind: 'present', real, bytes: read.bytes, text: new TextDecoder('utf-8', { fatal: true }).decode(read.bytes) };
+}
+async function classify(root) {
+    const agents = await readInstructionFile(join(root, 'AGENTS.md'));
+    const claude = await readInstructionFile(join(root, 'CLAUDE.md'));
+    // Claude Code resolves `@path` at the start of a line or after whitespace; an email address has neither.
+    const claudeImports = claude.kind === 'present' && /(^|\s)@\S/.test(claude.text);
+    if (agents.kind === 'absent')
+        return { state: claude.kind === 'absent' ? 'neither' : 'claude-only', claudeImports, agents, claude };
+    if (claude.kind === 'absent')
+        return { state: 'agents-only', claudeImports, agents, claude };
+    const linked = claude.real === agents.real || /^[ \t]*@(\.\/)?AGENTS\.md[ \t]*$/m.test(claude.text);
+    return { state: linked ? 'linked' : 'unlinked', claudeImports, agents, claude };
+}
+/**
+ * One warning for each way a repository's root instruction files leave a listed agent tool without
+ * them. A team that uses only Claude Code loses nothing when a repository keeps CLAUDE.md alone.
+ */
+export async function inspectSiblingInstructions(repository, tools) {
+    const claude = tools.includes('claudecode');
+    // OpenCode falls back to CLAUDE.md when AGENTS.md is absent; Codex does not.
+    const agentsReaders = tools.includes('codexcli') || tools.includes('opencode');
+    const target = `sibling:${repository.slug}`;
+    const findings = [];
+    let classified;
+    const toolOnly = [];
+    try {
+        classified = await classify(repository.root);
+        for (const name of TOOL_ONLY_FILES) {
+            try {
+                await lstat(join(repository.root, name));
+                toolOnly.push(name);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+    }
+    catch (error) {
+        return [{
+                severity: 'warning',
+                code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+                message: `which agent tools load the instructions of sibling ${repository.slug} could not be checked: ${errorCause(error)}`,
+                target,
+                fix: `make the instruction files at the root of ${repository.root} readable UTF-8 files, then rerun this command`,
+            }];
+    }
+    if (classified.state === 'agents-only' && claude)
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_INSTRUCTIONS_AGENTS_ONLY',
+            message: `sibling ${repository.slug} has AGENTS.md but no CLAUDE.md, so Claude Code started there loads none of its instructions`,
+            target,
+            fix: 'run npx --no cockpit setup --config <your cockpit.toml> to see the CLAUDE.md it proposes (one line, @AGENTS.md); once a person approves it, run npx --no cockpit setup --config <your cockpit.toml> --write-instruction-files',
+        });
+    if (classified.state === 'claude-only' && tools.includes('codexcli'))
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_INSTRUCTIONS_CLAUDE_ONLY',
+            message: `sibling ${repository.slug} has CLAUDE.md but no AGENTS.md, so Codex started there loads none of its instructions`
+                + (classified.claudeImports ? '; CLAUDE.md imports other files with @, which only Claude Code follows, so setup proposes no move' : ''),
+            target,
+            fix: 'run npx --no cockpit setup --config <your cockpit.toml> to see the move it proposes (CLAUDE.md copied byte for byte to AGENTS.md, CLAUDE.md replaced by @AGENTS.md) and, once a person approves it, rerun it with --write-instruction-files; when CLAUDE.md imports other files with @, setup proposes nothing and a person moves the shared instructions into AGENTS.md by hand',
+        });
+    if (classified.state === 'unlinked' && claude && agentsReaders)
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_INSTRUCTIONS_UNLINKED',
+            message: `sibling ${repository.slug} has both AGENTS.md and CLAUDE.md, but CLAUDE.md does not import AGENTS.md, so Claude Code loads only CLAUDE.md and Codex only AGENTS.md`,
+            target,
+            fix: 'a person merges the instructions every tool needs into AGENTS.md, then makes CLAUDE.md a line reading @AGENTS.md followed only by instructions that apply to Claude Code alone',
+        });
+    if (classified.state === 'neither')
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_INSTRUCTIONS_MISSING',
+            message: `sibling ${repository.slug} has neither AGENTS.md nor CLAUDE.md, so no agent tool started there loads instructions for it`,
+            target,
+            fix: 'a person writes AGENTS.md with what an agent must know to work in the repository, then runs npx --no cockpit setup --config <your cockpit.toml> --write-instruction-files to add the CLAUDE.md that imports it',
+        });
+    if (toolOnly.length > 0)
+        findings.push({
+            severity: 'warning',
+            // A literal, so the diagnostic inventory captures the fix beside the code.
+            code: 'SIBLING_INSTRUCTIONS_TOOL_ONLY',
+            message: `sibling ${repository.slug} keeps instructions in ${toolOnly.join(', ')}, which Claude Code, Codex and OpenCode do not load`,
+            target,
+            fix: 'a person moves the instructions every tool needs from those files into AGENTS.md, and keeps only settings specific to one tool where they are',
+        });
+    return findings;
+}
+async function createExclusive(path, bytes, mode) {
+    const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, mode);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function syncDirectory(path) {
+    const directory = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+async function holds(path, expected) {
+    const read = await readBoundedInput(path);
+    return read.kind === 'complete' && Buffer.from(read.bytes).equals(Buffer.from(expected));
+}
+/**
+ * Makes AGENTS.md the file every tool loads and CLAUDE.md the import Claude Code needs, in the two
+ * cases that need no judgement: AGENTS.md alone gains a CLAUDE.md reading `@AGENTS.md`, and CLAUDE.md
+ * alone, when it imports nothing of its own, moves byte for byte to AGENTS.md and becomes that import.
+ * Without `write` it only reports the change. It writes only ordinary files directly in a canonical
+ * root, never through a link, and refuses when a file changed after it was read.
+ */
+export async function synchronizeSiblingInstructionFiles(input) {
+    const root = input.siblingRoot;
+    const agentsPath = join(root, 'AGENTS.md');
+    const claudePath = join(root, 'CLAUDE.md');
+    let created;
+    try {
+        if (await realpath(root) !== root)
+            return { kind: 'refusal', root, reason: 'the sibling root must be a canonical directory without symlink redirects' };
+        const classified = await classify(root);
+        const change = classified.state === 'agents-only' ? 'claude-import'
+            : classified.state === 'claude-only' && !classified.claudeImports ? 'move-to-agents' : undefined;
+        if (!change)
+            return { kind: 'none', root };
+        const before = await lstat(change === 'claude-import' ? agentsPath : claudePath);
+        if (!before.isFile())
+            return { kind: 'refusal', root, reason: `${change === 'claude-import' ? 'AGENTS.md' : 'CLAUDE.md'} is not an ordinary file` };
+        if (!input.write)
+            return { kind: 'offered', root, change };
+        if (change === 'claude-import') {
+            await createExclusive(claudePath, CLAUDE_IMPORT, 0o644);
+            created = claudePath;
+        }
+        else {
+            const original = classified.claude.kind === 'present' ? classified.claude.bytes : new Uint8Array();
+            await createExclusive(agentsPath, original, Number(before.mode) & 0o777);
+            created = agentsPath;
+            const temporary = join(root, `.CLAUDE.md.cockpit-instructions-${randomBytes(8).toString('hex')}`);
+            try {
+                await createExclusive(temporary, CLAUDE_IMPORT, Number(before.mode) & 0o777);
+                const current = await lstat(claudePath);
+                const reread = await readBoundedInput(claudePath);
+                if (!current.isFile() || current.dev !== before.dev || current.ino !== before.ino || current.size !== before.size
+                    || current.mtimeMs !== before.mtimeMs || reread.kind !== 'complete' || sha256Hex(reread.bytes) !== sha256Hex(original)) {
+                    throw new RefusalError('CLAUDE.md changed before it could be replaced');
+                }
+                await rename(temporary, claudePath);
+            }
+            finally {
+                await unlink(temporary).catch((cleanup) => { if (!isMissing(cleanup))
+                    throw cleanup; });
+            }
+        }
+        // From here the instructions live only in what was written; nothing is undone any more.
+        created = undefined;
+        await syncDirectory(root);
+        if (!await holds(claudePath, CLAUDE_IMPORT))
+            return { kind: 'refusal', root, reason: 'CLAUDE.md does not hold the import after writing' };
+        if (change === 'move-to-agents' && !await holds(agentsPath, classified.claude.kind === 'present' ? classified.claude.bytes : '')) {
+            return { kind: 'refusal', root, reason: 'AGENTS.md does not hold the moved instructions after writing' };
+        }
+        return { kind: 'written', root, change };
+    }
+    catch (error) {
+        // A file this run created is removed when the change could not complete, so a half-made move
+        // never leaves two copies of the instructions that can drift apart.
+        if (created) {
+            try {
+                await unlink(created);
+            }
+            catch (cleanup) {
+                if (!isMissing(cleanup))
+                    return { kind: 'refusal', root, reason: `${errorCause(error)}; ${created} could not be removed: ${errorCause(cleanup)}` };
+            }
+        }
+        return { kind: 'refusal', root, reason: errorCause(error) };
+    }
+}

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>;

package/dist/environment/sibling-pull.js

@@ -0,0 +1,95 @@
+/**
+ * Owns bringing one checkout up to its upstream, the way a careful person would: fetch, then
+ * fast-forward the branch that is checked out, and nothing else. It never merges, rebases,
+ * stashes, switches branch or touches a modified file; a checkout it cannot fast-forward cleanly
+ * is left exactly as it was and reported with the reason. That is what makes it safe to run
+ * unprompted: the only change it can make is one `git merge --ff-only` would make.
+ */
+import { formatShellCommand } from '../fix-catalogue.js';
+import { parseGitBranchStatus } from './git-observation.js';
+// Keys that make fetch or merge spawn a command the repository's own configuration names. Agents cannot
+// write under `.git`, so this is defence in depth. Git lower-cases section and variable names in its output.
+const COMMAND_KEYS = /^(?:core\.(?:sshcommand|askpass|gitproxy)|credential\.(?:.+\.)?helper|remote\..+\.(?:uploadpack|receivepack))$/;
+async function commandBearingKey(git, path) {
+    const listed = await git.run(path, 'pull:config', ['config', '--list', '--name-only']);
+    if (listed.kind !== 'complete')
+        return { reason: `its Git configuration could not be read (${listed.detail})` };
+    return listed.stdout.split('\n').find(key => COMMAND_KEYS.test(key));
+}
+async function branchStatus(git, path) {
+    const status = await git.run(path, 'pull:status', ['status', '--porcelain=v2', '--branch', '--untracked-files=no']);
+    if (status.kind !== 'complete')
+        return { reason: `git status failed (${status.detail})` };
+    const parsed = parseGitBranchStatus(status.stdout);
+    return parsed.kind === 'complete' ? parsed : { reason: parsed.reason };
+}
+/**
+ * The filter drivers the upstream's attributes name that the repository's own configuration does
+ * not define. cockpit's Git reads no global configuration, where `git lfs install` puts its driver,
+ * and a checkout through an undefined filter writes the stored pointer silently, with no error.
+ */
+async function unconfiguredFilters(git, path) {
+    const named = await git.run(path, 'pull:filters', ['grep', '-h', '-o', '-I', '-E', 'filter=[^[:space:]]+', '@{upstream}', '--', ':(glob)**/.gitattributes']);
+    // grep exits 1 when nothing matches.
+    if (named.kind !== 'complete')
+        return named.exitCode === 1 ? [] : { reason: `its attributes could not be read (${named.detail})` };
+    const drivers = [...new Set(named.stdout.split('\n').map(line => line.trim().slice('filter='.length)).filter(Boolean))];
+    // One call lists every filter variable; git exits 1 when there are none. Section and variable
+    // names are lower-cased in the output, the driver (subsection) keeps its case.
+    const configured = await git.run(path, 'pull:filter-drivers', ['config', '--get-regexp', '^filter\\.']);
+    if (configured.kind !== 'complete' && configured.exitCode !== 1)
+        return { reason: `its Git configuration could not be read (${configured.detail})` };
+    const defined = new Set();
+    for (const line of configured.kind === 'complete' ? configured.stdout.split('\n') : []) {
+        const match = /^filter\.(.+)\.(smudge|process)(?:\s|$)/.exec(line);
+        if (match)
+            defined.add(match[1]);
+    }
+    return drivers.filter(driver => !defined.has(driver));
+}
+export async function fastForwardCheckout(git, path) {
+    const shell = (...args) => formatShellCommand(['git', '-C', path, ...args]);
+    const skipped = (reason, fix, blocked = true) => ({ state: 'skipped', path, reason, fix, blocked });
+    const before = await branchStatus(git, path);
+    if ('reason' in before)
+        return skipped(`it is not a readable Git checkout: ${before.reason}`, `inspect it with ${shell('status')}`);
+    if (before.revision === '(initial)')
+        return skipped('it has no commits yet', `commit in it, or ignore it until it has a history`);
+    if (before.branch === '(detached)')
+        return skipped('HEAD is detached, so there is no branch to move', `check out a branch with ${shell('switch', '<branch>')} if it should follow one`, false);
+    if (before.upstream === null)
+        return skipped(`branch ${before.branch} tracks no upstream`, `set one with ${shell('branch', '--set-upstream-to', '<remote>/<branch>')} if it should follow one`, false);
+    const command = await commandBearingKey(git, path);
+    if (typeof command === 'object')
+        return skipped(command.reason, `inspect it with ${shell('config', '--list')}`);
+    if (command !== undefined)
+        return skipped(`its Git configuration sets ${command}, which would run a command during the fetch`, `review ${shell('config', '--list', '--show-origin')}; if you trust the setting, run ${shell('pull', '--ff-only')} yourself`);
+    const fetched = await git.run(path, 'pull:fetch', ['fetch', '--quiet', '--prune'], { timeoutMs: 120_000 });
+    if (fetched.kind !== 'complete') {
+        return skipped(`fetching ${before.upstream} failed (${fetched.detail})`, `run ${shell('fetch')} yourself to see why; cockpit fetches without the global Git configuration, so a credential helper set only there is not used`);
+    }
+    const after = await branchStatus(git, path);
+    if ('reason' in after)
+        return skipped(`it could not be read after fetching: ${after.reason}`, `inspect it with ${shell('status')}`);
+    const upstream = after.upstream ?? before.upstream;
+    if (!after.adjacencyReported)
+        return skipped(`${upstream}, which ${after.branch} tracks, no longer exists`, `push the branch to recreate it, or stop tracking it with ${shell('branch', '--unset-upstream')}`);
+    if (after.behind === 0)
+        return { state: 'current', path, branch: after.branch, upstream, ahead: after.ahead };
+    if (after.ahead > 0)
+        return skipped(`${after.branch} has diverged from ${upstream} (${after.behind} behind, ${after.ahead} ahead)`, `reconcile it by hand, for example with ${shell('rebase', upstream)}; cockpit only fast-forwards`);
+    if (after.trackedDirtyCount > 0)
+        return skipped(`${after.branch} is ${after.behind} behind ${upstream}, but ${after.trackedDirtyCount} tracked file(s) are modified`, `commit or stash the changes (see ${shell('status', '--short')}), then run pull again; cockpit never moves a checkout with work in it`);
+    const filters = await unconfiguredFilters(git, path);
+    if ('reason' in filters)
+        return skipped(filters.reason, `inspect it with ${shell('check-attr', '-a', '--', '<path>')}`);
+    if (filters.length > 0)
+        return skipped(`it uses the Git filter ${filters.join(', ')} (Git LFS, for one), which is configured only outside the repository, `
+            + 'so a fast-forward here would check out its placeholder files instead of their content', `run ${shell('pull', '--ff-only')} yourself`);
+    const merged = await git.run(path, 'pull:fast-forward', ['merge', '--ff-only', '--quiet', '@{upstream}'], { timeoutMs: 120_000 });
+    if (merged.kind !== 'complete')
+        return skipped(`fast-forwarding ${after.branch} to ${upstream} failed (${merged.detail})`, `run ${shell('merge', '--ff-only', '@{upstream}')} yourself to see what is in the way`);
+    const head = await git.run(path, 'pull:head', ['rev-parse', 'HEAD']);
+    return { state: 'advanced', path, branch: after.branch, upstream, from: after.revision,
+        to: head.kind === 'complete' ? head.stdout : 'unknown', commits: after.behind };
+}

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

@@ -0,0 +1,45 @@
+import { type ExecuteProbeOutcome } from '../environment-exec/execute.js';
+import type { Diagnostic } from '../diagnostics.js';
+import { type ExecutionStep } from './contract.js';
+export interface SiblingAddInput {
+    readonly configPath: string;
+    readonly slug: string;
+    readonly create: boolean;
+    readonly from?: string;
+    readonly remote?: string;
+    readonly dir?: string;
+    readonly purpose?: string;
+    readonly varName?: string;
+    /** How the stack uses the checkout; defaulted from the declared runtime when absent. */
+    readonly mount?: string;
+    readonly instructionPointer?: boolean;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export interface SiblingRemoveInput {
+    readonly configPath: string;
+    readonly slug: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export interface SiblingDependencies {
+    readonly execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+}
+export interface SiblingOutcome {
+    readonly status: number;
+    readonly result: unknown;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly artifact?: string | null;
+    readonly destination?: string | null;
+}
+export type GitRepositoryInitializationOutcome = Readonly<{
+    kind: 'complete';
+}> | Readonly<{
+    kind: 'refusal';
+    reason: string;
+}>;
+/** Initialises one local repository through the authenticated process seam used by sibling creation. */
+export declare function initializeLocalGitRepository(input: Readonly<{
+    path: string;
+    env: Readonly<Record<string, string | undefined>>;
+}>, dependencies: SiblingDependencies): Promise<GitRepositoryInitializationOutcome>;
+export declare function runSiblingAdd(input: SiblingAddInput, dependencies: SiblingDependencies): Promise<SiblingOutcome>;
+export declare function runSiblingRemove(input: SiblingRemoveInput): Promise<SiblingOutcome>;