@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/setup/paseo/paseo-setup.ts

@@ -0,0 +1,253 @@
+/**
+ * Top-level orchestration for `gjc setup paseo`.
+ *
+ * Dispatches to diagnosis, install, or removal, and owns the flag combinations
+ * that must be rejected before any target is touched.
+ */
+import { Settings } from "../../config/settings";
+import { checkPaseoSetup } from "./check";
+import { type CompletedStep, compensate, receiptStep, recoverIntent, runJsonStep, SagaStepError } from "./install-saga";
+import { PaseoPublishError, readTarget } from "./json-publisher";
+import { createOrchestrationSeed, removeSeededRoles } from "./orchestration-preferences";
+import { readProvenance, writeProvenance } from "./paseo-ownership";
+import {
+	buildProviderEntry,
+	createProviderMutation,
+	hasProviderConflict,
+	providerEntryHash,
+	providerKeyFor,
+	resolveGjcCommand,
+} from "./provider-config";
+import { removePaseoSetup } from "./remove";
+import type { PaseoInstallResult, PaseoRemoveResult, SetupCheckResult } from "./result-types";
+import type { PaseoSetupDependencies } from "./setup-deps";
+import {
+	installSkillsBridge,
+	inverseSkillsBridge,
+	preflightSkillsBridge,
+	registerSkillsBridgeDirectory,
+} from "./skills-bridge";
+
+export interface PaseoSetupFlags {
+	readonly check?: boolean;
+	readonly json?: boolean;
+	readonly force?: boolean;
+	readonly remove?: boolean;
+	readonly mpreset?: string;
+}
+
+export class PaseoSetupUsageError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "PaseoSetupUsageError";
+	}
+}
+
+export type PaseoSetupOutcome =
+	| { readonly kind: "check"; readonly result: SetupCheckResult }
+	| { readonly kind: "install"; readonly result: PaseoInstallResult }
+	| { readonly kind: "remove"; readonly result: PaseoRemoveResult };
+
+/**
+ * Reject flag combinations that have no coherent meaning.
+ *
+ * Rejected before any read or write so a misuse can never leave partial state.
+ */
+export function assertUsableFlags(flags: PaseoSetupFlags): void {
+	if (flags.check && flags.remove) {
+		throw new PaseoSetupUsageError(
+			"--check and --remove cannot be combined: --check only reports, --remove mutates.",
+		);
+	}
+	if (flags.mpreset !== undefined && flags.mpreset.trim() === "") {
+		throw new PaseoSetupUsageError("--mpreset requires a preset name.");
+	}
+}
+
+export async function runPaseoSetup(flags: PaseoSetupFlags, deps: PaseoSetupDependencies): Promise<PaseoSetupOutcome> {
+	assertUsableFlags(flags);
+
+	if (flags.check) {
+		const result = await checkPaseoSetup(deps, { mpreset: flags.mpreset, force: flags.force });
+		return { kind: "check", result };
+	}
+
+	if (flags.remove) {
+		const settings = await Settings.init();
+		const result = await removePaseoSetup(deps, {
+			now: deps.now(),
+			unregisterBridgeDirectory: async () => {
+				await unregisterBridgeDirectory(settings, deps.paths.bridgeDir);
+			},
+		});
+		return { kind: "remove", result };
+	}
+
+	return { kind: "install", result: await installPaseoSetup(flags, deps) };
+}
+
+/**
+ * Run the four-step install saga.
+ *
+ * Preflight happens first and is entirely read-only, so the common failure
+ * cases (unparseable config, a conflicting entry, an unresolvable executable, a
+ * foreign file sitting at one of our bridge names) all abort before anything is
+ * written and therefore need no compensation.
+ */
+async function installPaseoSetup(flags: PaseoSetupFlags, deps: PaseoSetupDependencies): Promise<PaseoInstallResult> {
+	const now = deps.now();
+
+	// An interrupted earlier run must be settled before starting a new one. A
+	// discardable intent is cleared here; a `complete-ledger` intent whose ledger
+	// contents are unknown to this run is reported rather than guessed at, and
+	// the steps below re-derive and commit the same provenance anyway.
+	const recovery = await recoverIntent(deps.paths.intentRecord, { repair: true });
+	if (recovery && !recovery.recovered) {
+		return {
+			outcome: "partial-install",
+			compensated: [],
+			uncompensated: [deps.paths.intentRecord],
+			evidence: { failedStep: "intent-recovery", detail: recovery.detail, retained: [deps.paths.intentRecord] },
+		};
+	}
+
+	const resolution = resolveGjcCommand();
+	if (!resolution.ok) {
+		throw new PaseoSetupUsageError(
+			`Cannot register GJC with Paseo: ${resolution.detail}. Paseo needs an absolute command path, so GJC will not write a bare 'gjc' string.`,
+		);
+	}
+
+	const providerKey = providerKeyFor(flags.mpreset);
+	const entry = buildProviderEntry(resolution.command, flags.mpreset);
+
+	const config = await readTarget(deps.paths.configJson);
+	const conflict = hasProviderConflict(config.parsed, providerKey, entry);
+	if (conflict.conflict && !flags.force) {
+		throw new PaseoSetupUsageError(`${conflict.detail} Re-run with --force to overwrite it.`);
+	}
+
+	const preferences = await readTarget(deps.paths.orchestrationPreferences);
+	const seed = createOrchestrationSeed(preferences.parsed);
+	const bridgePreflight = await preflightSkillsBridge(deps);
+
+	const completed: CompletedStep[] = [];
+	const changed: string[] = [];
+	const entryHash = providerEntryHash(entry);
+
+	try {
+		// Step 1: provider entry + provider-key provenance.
+		const step1 = await runJsonStep({
+			label: deps.paths.configJson,
+			step: "provider-config",
+			targetPath: deps.paths.configJson,
+			provenancePath: deps.paths.provenanceLedger,
+			intentPath: deps.paths.intentRecord,
+			ownedKeys: [`agents.providers.${providerKey}`],
+			mutate: createProviderMutation(config, providerKey, entry),
+			nextLedger: ledger => ({ ...ledger, providerKeys: { ...ledger.providerKeys, [providerKey]: entryHash } }),
+			revert: draft => removeProviderKey(draft, providerKey),
+			revertLedger: ledger => {
+				const providerKeys = { ...ledger.providerKeys };
+				delete providerKeys[providerKey];
+				return { ...ledger, providerKeys };
+			},
+			now,
+		});
+		completed.push(step1.completed);
+		if (step1.changed) changed.push(deps.paths.configJson);
+
+		// Step 2: seed empty orchestration roles only.
+		if (seed.seededKeys.length > 0) {
+			const step2 = await runJsonStep({
+				label: deps.paths.orchestrationPreferences,
+				step: "orchestration-preferences",
+				targetPath: deps.paths.orchestrationPreferences,
+				provenancePath: deps.paths.provenanceLedger,
+				intentPath: deps.paths.intentRecord,
+				ownedKeys: [...seed.seededKeys],
+				mutate: seed.mutate,
+				nextLedger: ledger => ({
+					...ledger,
+					seededOrchestrationKeys: { ...ledger.seededOrchestrationKeys, ...seed.seededValues },
+				}),
+				// Compensation must reach the same nested map the forward step wrote.
+				revert: draft => removeSeededRoles(draft, seed.seededKeys, () => true),
+				revertLedger: ledger => {
+					const seededOrchestrationKeys = { ...ledger.seededOrchestrationKeys };
+					for (const key of seed.seededKeys) delete seededOrchestrationKeys[key];
+					return { ...ledger, seededOrchestrationKeys };
+				},
+				now,
+			});
+			completed.push(step2.completed);
+			if (step2.changed) changed.push(deps.paths.orchestrationPreferences);
+		}
+
+		// Step 3: the symlink bridge.
+		const bridge = await installSkillsBridge(bridgePreflight);
+		if (bridge.createdEntries.length > 0 || bridge.bridgeDirCreated) {
+			changed.push(deps.paths.bridgeDir);
+			const ledger = await readProvenance(deps.paths.provenanceLedger);
+			await writeProvenance(deps.paths.provenanceLedger, {
+				...ledger,
+				bridgePath: deps.paths.bridgeDir,
+				bridgeEntries: [...bridge.createdEntries],
+				bridgeDirCreated: bridge.bridgeDirCreated,
+			});
+			completed.push({
+				label: deps.paths.bridgeDir,
+				undo: async () => {
+					try {
+						await inverseSkillsBridge(deps, bridge);
+						return { status: "reverted" as const };
+					} catch (error) {
+						return {
+							status: "conflict" as const,
+							detail: error instanceof Error ? error.message : String(error),
+							retained: [deps.paths.bridgeDir],
+						};
+					}
+				},
+			});
+		}
+
+		// Step 4: register the bridge with GJC skill discovery.
+		const settings = await Settings.init();
+		const receipt = await registerSkillsBridgeDirectory(settings, deps.paths.bridgeDir);
+		completed.push(receiptStep("config.yml skills.customDirectories", receipt));
+		changed.push("config.yml skills.customDirectories");
+	} catch (error) {
+		const failure =
+			error instanceof SagaStepError
+				? error
+				: new SagaStepError(
+						"install",
+						error instanceof PaseoPublishError || error instanceof Error ? error.message : String(error),
+					);
+		const outcome = await compensate(completed, failure);
+		return { outcome: "partial-install", ...outcome };
+	}
+
+	return { outcome: "installed", changed };
+}
+
+function removeProviderKey(draft: Record<string, unknown>, providerKey: string): void {
+	const agents = draft.agents;
+	if (!agents || typeof agents !== "object" || Array.isArray(agents)) return;
+	const providers = (agents as Record<string, unknown>).providers;
+	if (!providers || typeof providers !== "object" || Array.isArray(providers)) return;
+	delete (providers as Record<string, unknown>)[providerKey];
+}
+
+async function unregisterBridgeDirectory(settings: Settings, bridgeDir: string): Promise<void> {
+	await settings.commitAtomicBatchWithCurrent(current => {
+		const skills = current.skills;
+		if (!skills || typeof skills !== "object" || Array.isArray(skills)) return [];
+		const directories = (skills as Record<string, unknown>).customDirectories;
+		if (!Array.isArray(directories)) return [];
+		const next = directories.filter(directory => directory !== bridgeDir);
+		if (next.length === directories.length) return [];
+		return [{ path: "skills.customDirectories", op: "set", value: next }];
+	});
+}

package/src/setup/paseo/provider-config.ts

@@ -0,0 +1,139 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { $which } from "@gajae-code/utils";
+import { type BuildChannel, resolveBuildMetadata } from "../../build-metadata";
+import { hashBytes, type ReadTargetResult } from "./json-publisher";
+import { PROVIDER_EXTENDS, PROVIDER_KEY } from "./setup-deps";
+
+const PROVIDER_LABEL = "Gajae Code";
+
+export interface PaseoProviderEntry {
+	extends: string;
+	label: string;
+	command: string[];
+	env: Record<string, string>;
+	enabled: boolean;
+}
+
+export type GjcCommandResolution =
+	| { readonly ok: true; readonly command: string[]; readonly channel: BuildChannel }
+	| { readonly ok: false; readonly channel: BuildChannel; readonly detail: string };
+
+export type ProviderConflict =
+	| { readonly conflict: false }
+	| { readonly conflict: true; readonly subject: string; readonly detail: string };
+
+/** Resolve an executable from PATH without ever returning its bare command name. */
+function resolveViaPath(name: string): string | undefined {
+	return $which(name) ?? undefined;
+}
+
+export function resolveGjcCommand(): GjcCommandResolution {
+	const metadata = resolveBuildMetadata();
+	switch (metadata.channel) {
+		case "release":
+		case "dev":
+		case "compiled":
+			return { ok: true, command: [process.execPath, "acp"], channel: metadata.channel };
+		case "local-source": {
+			const launcher = process.argv[1];
+			if (!launcher) {
+				return {
+					ok: false,
+					channel: metadata.channel,
+					detail: "local-source launcher process.argv[1] is missing; cannot write an absolute command path",
+				};
+			}
+			const resolvedLauncher = path.resolve(launcher);
+			if (!isReadableFile(resolvedLauncher)) {
+				return {
+					ok: false,
+					channel: metadata.channel,
+					detail: `local-source launcher '${resolvedLauncher}' is not a readable file; cannot write an absolute command path`,
+				};
+			}
+			return { ok: true, command: [process.execPath, resolvedLauncher, "acp"], channel: metadata.channel };
+		}
+		case "package-install": {
+			const executable = resolveViaPath("gjc");
+			if (!executable || !path.isAbsolute(executable)) {
+				return {
+					ok: false,
+					channel: metadata.channel,
+					detail: "gjc was not found on PATH; cannot write an absolute command path",
+				};
+			}
+			return { ok: true, command: [executable, "acp"], channel: metadata.channel };
+		}
+		case "unknown":
+			return { ok: false, channel: metadata.channel, detail: "build channel is unknown; cannot resolve gjc" };
+		default: {
+			const _exhaustive: never = metadata.channel;
+			throw new Error(`Unhandled build channel '${_exhaustive}'`);
+		}
+	}
+}
+
+export function providerKeyFor(mpreset?: string): string {
+	return mpreset === undefined ? PROVIDER_KEY : `${PROVIDER_KEY}-${mpreset}`;
+}
+
+export function buildProviderEntry(command: string[], mpreset?: string): PaseoProviderEntry {
+	return {
+		extends: PROVIDER_EXTENDS,
+		label: mpreset === undefined ? PROVIDER_LABEL : `${PROVIDER_LABEL} (${mpreset})`,
+		command: mpreset === undefined ? [...command] : [...command, "--mpreset", mpreset],
+		env: { GJC_ACP_PERMISSION_MODE: "prompt" },
+		enabled: true,
+	};
+}
+
+/**
+ * Produces the narrowly scoped mutation passed to {@link planPublish}. The
+ * read result is accepted so callers retain an explicit preflight-to-plan flow.
+ */
+export function createProviderMutation(
+	_current: ReadTargetResult,
+	key: string,
+	entry: PaseoProviderEntry,
+): (draft: Record<string, unknown>) => void {
+	return draft => {
+		const agents = asRecord(draft.agents);
+		if (!agents) draft.agents = {};
+		const targetAgents = draft.agents as Record<string, unknown>;
+		const providers = asRecord(targetAgents.providers);
+		if (!providers) targetAgents.providers = {};
+		(targetAgents.providers as Record<string, unknown>)[key] = entry;
+	};
+}
+
+export function hasProviderConflict(
+	config: Record<string, unknown>,
+	key: string,
+	entry: PaseoProviderEntry,
+): ProviderConflict {
+	const existing = asRecord(asRecord(config.agents)?.providers)?.[key];
+	if (existing === undefined || JSON.stringify(existing) === JSON.stringify(entry)) return { conflict: false };
+	return {
+		conflict: true,
+		subject: `agents.providers.${key}`,
+		detail: `Existing provider entry at agents.providers.${key} differs from the GJC-managed entry.`,
+	};
+}
+
+export function providerEntryHash(entry: PaseoProviderEntry): string {
+	return hashBytes(JSON.stringify(entry));
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+function isReadableFile(filePath: string): boolean {
+	try {
+		fs.accessSync(filePath, fs.constants.R_OK);
+		return fs.statSync(filePath).isFile();
+	} catch {
+		return false;
+	}
+}

package/src/setup/paseo/remove.ts

@@ -0,0 +1,183 @@
+/**
+ * Provenance-gated rollback for `gjc setup paseo --remove`.
+ *
+ * Removal never deletes on value-equality alone. A key is removed only when
+ * GJC's own ledger recorded creating it AND the current value still hashes to
+ * what GJC wrote. A user who hand-authored the same value, or who edited ours
+ * afterwards, keeps their content.
+ *
+ * Steps are undone in reverse of the install order (4 to 1). The first step
+ * that cannot be undone safely halts the rest, so the result is an
+ * interpretable prefix rather than a scattered mix.
+ */
+import { planPublish, publishPlan, readTarget } from "./json-publisher";
+import { removeSeededRoles } from "./orchestration-preferences";
+import {
+	EMPTY_LEDGER,
+	isProvenancedOrchestrationKey,
+	isProvenancedProvider,
+	provenancedProviderKeys,
+	readProvenance,
+	writeProvenance,
+} from "./paseo-ownership";
+import { type PaseoProviderEntry, providerEntryHash } from "./provider-config";
+import type { PartialRemovalEvidence, PaseoRemoveResult } from "./result-types";
+import { INSTALL_SKILL_NAMES, type InstallSkillName, type PaseoSetupDependencies } from "./setup-deps";
+import { inverseSkillsBridge, SkillsBridgeError } from "./skills-bridge";
+
+export interface RemoveOptions {
+	readonly now: Date;
+	/** Undo the config.yml `skills.customDirectories` append. Supplied by the orchestrator. */
+	readonly unregisterBridgeDirectory?: () => Promise<void>;
+}
+
+/**
+ * Remove every target GJC can prove it owns.
+ *
+ * Returns `nothing-to-remove` when the ledger holds no ownership at all, which
+ * is distinct from removing zero keys because the user edited all of them.
+ */
+export async function removePaseoSetup(
+	deps: PaseoSetupDependencies,
+	options: RemoveOptions,
+): Promise<PaseoRemoveResult> {
+	const ledger = await readProvenance(deps.paths.provenanceLedger);
+	const ownsAnything =
+		provenancedProviderKeys(ledger).length > 0 ||
+		Object.keys(ledger.seededOrchestrationKeys).length > 0 ||
+		(ledger.bridgeEntries?.length ?? 0) > 0;
+	if (!ownsAnything) return { outcome: "nothing-to-remove" };
+
+	const removed: string[] = [];
+	const remaining: string[] = [];
+	let nextLedger = ledger;
+
+	// Step 4 inverse: config.yml registration.
+	if (options.unregisterBridgeDirectory) {
+		try {
+			await options.unregisterBridgeDirectory();
+			removed.push("config.yml skills.customDirectories");
+		} catch (error) {
+			return partial(removed, ["config.yml skills.customDirectories"], {
+				failedStep: "config.yml skills.customDirectories",
+				detail: error instanceof Error ? error.message : String(error),
+				retained: [deps.paths.provenanceLedger],
+			});
+		}
+	}
+
+	// Step 3 inverse: the symlink bridge.
+	if (ledger.bridgeEntries && ledger.bridgeEntries.length > 0) {
+		try {
+			// Only names the locked allowlist knows are undone; a ledger carrying an
+			// unknown name is ignored rather than trusted into a filesystem removal.
+			const createdEntries = ledger.bridgeEntries.filter((name): name is InstallSkillName =>
+				(INSTALL_SKILL_NAMES as readonly string[]).includes(name),
+			);
+			await inverseSkillsBridge(deps, {
+				createdEntries,
+				bridgeDirCreated: ledger.bridgeDirCreated ?? false,
+			});
+			removed.push(deps.paths.bridgeDir);
+			nextLedger = { ...nextLedger, bridgeEntries: [], bridgeDirCreated: false };
+		} catch (error) {
+			const detail = error instanceof SkillsBridgeError ? error.message : String(error);
+			remaining.push(deps.paths.bridgeDir);
+			await writeProvenance(deps.paths.provenanceLedger, nextLedger);
+			return partial(removed, remaining, {
+				failedStep: deps.paths.bridgeDir,
+				detail,
+				retained: [deps.paths.provenanceLedger],
+			});
+		}
+	}
+
+	// Step 2 inverse: seeded orchestration roles.
+	const seededKeys = Object.keys(nextLedger.seededOrchestrationKeys);
+	if (seededKeys.length > 0) {
+		// Roles live under `providers`, so removal must reach into that map. Deleting
+		// a top-level key would clear our provenance while leaving the role pointing
+		// at the provider entry we are about to delete.
+		const outcome = await revertJson(deps.paths.orchestrationPreferences, options.now, draft =>
+			removeSeededRoles(draft, seededKeys, (key, currentValue) =>
+				isProvenancedOrchestrationKey(nextLedger, key, currentValue ?? ""),
+			),
+		);
+		if (!outcome.ok) {
+			remaining.push(deps.paths.orchestrationPreferences);
+			await writeProvenance(deps.paths.provenanceLedger, nextLedger);
+			return partial(removed, remaining, {
+				failedStep: deps.paths.orchestrationPreferences,
+				detail: outcome.detail,
+				retained: [deps.paths.provenanceLedger],
+			});
+		}
+		removed.push(deps.paths.orchestrationPreferences);
+		nextLedger = { ...nextLedger, seededOrchestrationKeys: {} };
+	}
+
+	// Step 1 inverse: provider entries, including every earlier `--mpreset` run.
+	const providerKeys = provenancedProviderKeys(nextLedger);
+	if (providerKeys.length > 0) {
+		const survivors: Record<string, string> = {};
+		const outcome = await revertJson(deps.paths.configJson, options.now, draft => {
+			const providers = providersOf(draft);
+			if (!providers) return;
+			for (const key of providerKeys) {
+				const entry = providers[key];
+				if (entry === undefined) continue;
+				const hash = providerEntryHash(entry as PaseoProviderEntry);
+				if (isProvenancedProvider(nextLedger, key, hash)) delete providers[key];
+				else survivors[key] = nextLedger.providerKeys[key] ?? hash;
+			}
+		});
+		if (!outcome.ok) {
+			remaining.push(deps.paths.configJson);
+			await writeProvenance(deps.paths.provenanceLedger, nextLedger);
+			return partial(removed, remaining, {
+				failedStep: deps.paths.configJson,
+				detail: outcome.detail,
+				retained: [deps.paths.provenanceLedger],
+			});
+		}
+		removed.push(deps.paths.configJson);
+		nextLedger = { ...nextLedger, providerKeys: survivors };
+	}
+
+	const stillOwns =
+		Object.keys(nextLedger.providerKeys).length > 0 || Object.keys(nextLedger.seededOrchestrationKeys).length > 0;
+	await writeProvenance(deps.paths.provenanceLedger, stillOwns ? nextLedger : EMPTY_LEDGER);
+	return { outcome: "removed", removed };
+}
+
+function providersOf(draft: Record<string, unknown>): Record<string, unknown> | undefined {
+	const agents = draft.agents;
+	if (!agents || typeof agents !== "object" || Array.isArray(agents)) return undefined;
+	const providers = (agents as Record<string, unknown>).providers;
+	if (!providers || typeof providers !== "object" || Array.isArray(providers)) return undefined;
+	return providers as Record<string, unknown>;
+}
+
+async function revertJson(
+	targetPath: string,
+	now: Date,
+	mutate: (draft: Record<string, unknown>) => void,
+): Promise<{ ok: true } | { ok: false; detail: string }> {
+	try {
+		const current = await readTarget(targetPath);
+		if (!current.exists) return { ok: true };
+		const plan = planPublish(current, mutate);
+		await publishPlan(targetPath, plan, { expectedIdentity: current.identity, backup: true, now });
+		return { ok: true };
+	} catch (error) {
+		return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+function partial(
+	removed: readonly string[],
+	remaining: readonly string[],
+	evidence: PartialRemovalEvidence,
+): PaseoRemoveResult {
+	return { outcome: "partial-removal", removed, remaining, evidence };
+}

package/src/setup/paseo/result-types.ts

@@ -0,0 +1,79 @@
+/**
+ * Result unions for `gjc setup paseo`.
+ *
+ * `SetupCheckResult` is deliberately four-valued. Parse failures, conflicts,
+ * missing executables, and partial-operation evidence are all `drift` carrying
+ * a structured reason -- they are NOT extra top-level statuses. Install and
+ * remove outcomes live in their own unions so command outcomes never leak into
+ * the diagnosis DTO.
+ */
+
+/** The four locked check states. Adding a fifth is a spec change, not an implementation detail. */
+export type SetupCheckStatus = "pass" | "drift" | "stale" | "skipped";
+
+/** Structured detail carried inside a `drift` result. */
+export type DriftReasonCode =
+	| "parse-refusal"
+	| "format-drift"
+	| "owned-key-conflict"
+	| "missing-executable"
+	| "partial-install"
+	| "partial-removal"
+	| "orphan-skill"
+	| "unlinked-skill"
+	| "missing-provider-entry"
+	| "missing-bridge-link"
+	| "missing-skills-directory"
+	| "unseeded-orchestration-role";
+
+export interface DriftReason {
+	readonly code: DriftReasonCode;
+	/** Which owned path or key the reason concerns. Never a secret value. */
+	readonly subject: string;
+	readonly detail: string;
+}
+
+export interface SetupCheckResult {
+	readonly component: "paseo";
+	readonly status: SetupCheckStatus;
+	readonly reasons: readonly DriftReason[];
+	/** Human-facing next step, present for `stale` so the user knows a restart is theirs to make. */
+	readonly guidance?: string;
+}
+
+export interface PartialInstallEvidence {
+	readonly failedStep: string;
+	readonly detail: string;
+	/** Paths whose state was preserved for recovery. Never file contents. */
+	readonly retained: readonly string[];
+}
+
+export type PaseoInstallResult =
+	| { readonly outcome: "installed"; readonly changed: readonly string[] }
+	| {
+			readonly outcome: "partial-install";
+			readonly compensated: readonly string[];
+			readonly uncompensated: readonly string[];
+			readonly evidence: PartialInstallEvidence;
+	  };
+
+export interface PartialRemovalEvidence {
+	readonly failedStep: string;
+	readonly detail: string;
+	readonly retained: readonly string[];
+}
+
+export type PaseoRemoveResult =
+	| { readonly outcome: "removed"; readonly removed: readonly string[] }
+	| { readonly outcome: "nothing-to-remove" }
+	| {
+			readonly outcome: "partial-removal";
+			readonly removed: readonly string[];
+			readonly remaining: readonly string[];
+			readonly evidence: PartialRemovalEvidence;
+	  };
+
+/** Exit code for a check result. `stale` and `skipped` are not failures. */
+export function checkExitCode(result: SetupCheckResult): number {
+	return result.status === "drift" ? 1 : 0;
+}